gi-glib-2.0.17: GLib bindings

Copyright | Will Thompson Iñaki García Etxebarria and Jonas Platte
License | LGPL-2.1
Maintainer | Iñaki García Etxebarria (garetxe@gmail.com)
Safe Haskell | None
Language | Haskell2010

GI.GLib.Structs.String

Contents

- Exported types
- Methods
  - append
  - appendC
  - appendLen
  - appendUnichar
  - appendUriEscaped
  - asciiDown
  - asciiUp
  - assign
  - down
  - equal
  - erase
  - free
  - freeToBytes
  - hash
  - insert
  - insertC
  - insertLen
  - insertUnichar
  - overwrite
  - overwriteLen
  - prepend
  - prependC
  - prependLen
  - prependUnichar
  - setSize
  - truncate
  - up
- Properties
  - allocatedLen
  - len
  - str

Description

The GString struct contains the public fields of a GString.

Synopsis

- newtype String = String (ManagedPtr String)
- newZeroString :: MonadIO m => m String
- noString :: Maybe String
- stringAppend :: (HasCallStack, MonadIO m) => String -> Text -> m String
- stringAppendC :: (HasCallStack, MonadIO m) => String -> Int8 -> m String
- stringAppendLen :: (HasCallStack, MonadIO m) => String -> Text -> Int64 -> m String
- stringAppendUnichar :: (HasCallStack, MonadIO m) => String -> Char -> m String
- stringAppendUriEscaped :: (HasCallStack, MonadIO m) => String -> Text -> Text -> Bool -> m String
- stringAsciiDown :: (HasCallStack, MonadIO m) => String -> m String
- stringAsciiUp :: (HasCallStack, MonadIO m) => String -> m String
- stringAssign :: (HasCallStack, MonadIO m) => String -> Text -> m String
- stringDown :: (HasCallStack, MonadIO m) => String -> m String
- stringEqual :: (HasCallStack, MonadIO m) => String -> String -> m Bool
- stringErase :: (HasCallStack, MonadIO m) => String -> Int64 -> Int64 -> m String
- stringFree :: (HasCallStack, MonadIO m) => String -> Bool -> m (Maybe Text)
- stringFreeToBytes :: (HasCallStack, MonadIO m) => String -> m Bytes
- stringHash :: (HasCallStack, MonadIO m) => String -> m Word32
- stringInsert :: (HasCallStack, MonadIO m) => String -> Int64 -> Text -> m String
- stringInsertC :: (HasCallStack, MonadIO m) => String -> Int64 -> Int8 -> m String
- stringInsertLen :: (HasCallStack, MonadIO m) => String -> Int64 -> Text -> Int64 -> m String
- stringInsertUnichar :: (HasCallStack, MonadIO m) => String -> Int64 -> Char -> m String
- stringOverwrite :: (HasCallStack, MonadIO m) => String -> Word64 -> Text -> m String
- stringOverwriteLen :: (HasCallStack, MonadIO m) => String -> Word64 -> Text -> Int64 -> m String
- stringPrepend :: (HasCallStack, MonadIO m) => String -> Text -> m String
- stringPrependC :: (HasCallStack, MonadIO m) => String -> Int8 -> m String
- stringPrependLen :: (HasCallStack, MonadIO m) => String -> Text -> Int64 -> m String
- stringPrependUnichar :: (HasCallStack, MonadIO m) => String -> Char -> m String
- stringSetSize :: (HasCallStack, MonadIO m) => String -> Word64 -> m String
- stringTruncate :: (HasCallStack, MonadIO m) => String -> Word64 -> m String
- stringUp :: (HasCallStack, MonadIO m) => String -> m String
- getStringAllocatedLen :: MonadIO m => String -> m Word64
- setStringAllocatedLen :: MonadIO m => String -> Word64 -> m ()
- getStringLen :: MonadIO m => String -> m Word64
- setStringLen :: MonadIO m => String -> Word64 -> m ()
- clearStringStr :: MonadIO m => String -> m ()
- getStringStr :: MonadIO m => String -> m (Maybe Text)
- setStringStr :: MonadIO m => String -> CString -> m ()

# Exported types

newtype String Source #

Memory-managed wrapper type.

Constructors

String (ManagedPtr String) |

Instances

BoxedObject String Source # |
Instance details Defined in GI.GLib.Structs.String Methods boxedType :: String -> IO GType Source #
tag ~ AttrSet => Constructible String tag Source # |
Instance details Defined in GI.GLib.Structs.String Methods new :: MonadIO m => (ManagedPtr String -> String) -> [AttrOp String tag] -> m String Source #

newZeroString :: MonadIO m => m String Source #

Construct a `String` struct initialized to zero.

noString :: Maybe String Source #

A convenience alias for `Nothing` :: `Maybe` `String`.

# Methods

## append

stringAppend Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> String | `string`: a `String`
-> Text | `val`: the string to append onto the end of `string`
-> m String | Returns: `string`

Adds a string onto the end of a `String`, expanding it if necessary.

## appendC

stringAppendC Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> String | `string`: a `String`
-> Int8 | `c`: the byte to append onto the end of `string`
-> m String | Returns: `string`

Adds a byte onto the end of a `String`, expanding it if necessary.

## appendLen

stringAppendLen Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> String | `string`: a `String`
-> Text | `val`: bytes to append
-> Int64 | `len`: number of bytes of `val` to use, or -1 for all of `val`
-> m String | Returns: `string`

Appends `len` bytes of `val` to `string`.

If `len` is positive, `val` may contain embedded nuls and need not be nul-terminated. It is the caller's responsibility to ensure that `val` has at least `len` addressable bytes.

If `len` is negative, `val` must be nul-terminated and `len` is considered to request the entire string length. This makes `stringAppendLen` equivalent to `stringAppend`.

## appendUnichar

stringAppendUnichar Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> String | `string`: a `String`
-> Char | `wc`: a Unicode character
-> m String | Returns: `string`

Converts a Unicode character into UTF-8, and appends it to the string.

## appendUriEscaped

stringAppendUriEscaped Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> String | `string`: a `String`
-> Text | `unescaped`: a string
-> Text | `reservedCharsAllowed`: a string of reserved characters allowed to be used, or `Nothing`
-> Bool | `allowUtf8`: set `True` if the escaped string may include UTF8 characters
-> m String | Returns: `string`

Appends `unescaped` to `string`, escaped any characters that are reserved in URIs using URI-style escape sequences.

Since: 2.16

## asciiDown

stringAsciiDown Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> String | `string`: a GString
-> m String | Returns: passed-in `string` pointer, with all the uppercase characters converted to lowercase in place, with semantics that exactly match `asciiTolower`.

Converts all uppercase ASCII letters to lowercase ASCII letters.

## asciiUp

stringAsciiUp Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> String | `string`: a GString
-> m String | Returns: passed-in `string` pointer, with all the lowercase characters converted to uppercase in place, with semantics that exactly match `asciiToupper`.

Converts all lowercase ASCII letters to uppercase ASCII letters.

## assign

stringAssign Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> String | `string`: the destination `String`. Its current contents are destroyed.
-> Text | `rval`: the string to copy into `string`
-> m String | Returns: `string`

Copies the bytes from a string into a `String`, destroying any previous contents. It is rather like the standard `strcpy()` function, except that you do not have to worry about having enough space to copy the string.

## down

stringDown Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> String | `string`: a `String`
-> m String | Returns: the `String`

Deprecated: (Since version 2.2)This function uses the locale-specific `tolower()` function, which is almost never the right thing. Use `stringAsciiDown` or `utf8Strdown` instead.

Converts a `String` to lowercase.

## equal

stringEqual Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> String | `v`: a `String`
-> String | `v2`: another `String`
-> m Bool | Returns: `True` if the strings are the same length and contain the same bytes

Compares two strings for equality, returning `True` if they are equal. For use with `HashTable`.

## erase

stringErase Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> String | `string`: a `String`
-> Int64 | `pos`: the position of the content to remove
-> Int64 | `len`: the number of bytes to remove, or -1 to remove all following bytes
-> m String | Returns: `string`

Removes `len` bytes from a `String`, starting at position `pos`. The rest of the `String` is shifted down to fill the gap.

## free

stringFree Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> String | `string`: a `String`
-> Bool | `freeSegment`: if `True`, the actual character data is freed as well
-> m (Maybe Text) | Returns: the character data of `string` (i.e. `Nothing` if `freeSegment` is `True`)

Frees the memory allocated for the `String`. If `freeSegment` is `True` it also frees the character data. If it's `False`, the caller gains ownership of the buffer and must free it after use with `free`.

## freeToBytes

stringFreeToBytes Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> String | `string`: a `String`
-> m Bytes | Returns: A newly allocated `Bytes` containing contents of `string`; `string` itself is freed

Transfers ownership of the contents of `string` to a newly allocated `Bytes`. The `String` structure itself is deallocated, and it is therefore invalid to use `string` after invoking this function.

Note that while `String` ensures that its buffer always has a trailing nul character (not reflected in its "len"), the returned `Bytes` does not include this extra nul; i.e. it has length exactly equal to the "len" member.

Since: 2.34

## hash

stringHash Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> String | `str`: a string to hash
-> m Word32 | Returns: hash code for `str`

Creates a hash code for `str`; for use with `HashTable`.

## insert

stringInsert Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> String | `string`: a `String`
-> Int64 | `pos`: the position to insert the copy of the string
-> Text | `val`: the string to insert
-> m String | Returns: `string`

Inserts a copy of a string into a `String`, expanding it if necessary.

## insertC

stringInsertC Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> String | `string`: a `String`
-> Int64 | `pos`: the position to insert the byte
-> Int8 | `c`: the byte to insert
-> m String | Returns: `string`

Inserts a byte into a `String`, expanding it if necessary.

## insertLen

stringInsertLen Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> String | `string`: a `String`
-> Int64 | `pos`: position in `string` where insertion should happen, or -1 for at the end
-> Text | `val`: bytes to insert
-> Int64 | `len`: number of bytes of `val` to insert, or -1 for all of `val`
-> m String | Returns: `string`

Inserts `len` bytes of `val` into `string` at `pos`.

If `len` is positive, `val` may contain embedded nuls and need not be nul-terminated. It is the caller's responsibility to ensure that `val` has at least `len` addressable bytes.

If `len` is negative, `val` must be nul-terminated and `len` is considered to request the entire string length.

If `pos` is -1, bytes are inserted at the end of the string.

## insertUnichar

stringInsertUnichar Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> String | `string`: a `String`
-> Int64 | `pos`: the position at which to insert character, or -1 to append at the end of the string
-> Char | `wc`: a Unicode character
-> m String | Returns: `string`

Converts a Unicode character into UTF-8, and insert it into the string at the given position.

## overwrite

stringOverwrite Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> String | `string`: a `String`
-> Word64 | `pos`: the position at which to start overwriting
-> Text | `val`: the string that will overwrite the `string` starting at `pos`
-> m String | Returns: `string`

Overwrites part of a string, lengthening it if necessary.

Since: 2.14

## overwriteLen

stringOverwriteLen Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> String | `string`: a `String`
-> Word64 | `pos`: the position at which to start overwriting
-> Text | `val`: the string that will overwrite the `string` starting at `pos`
-> Int64 | `len`: the number of bytes to write from `val`
-> m String | Returns: `string`

Overwrites part of a string, lengthening it if necessary. This function will work with embedded nuls.

Since: 2.14

## prepend

stringPrepend Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> String | `string`: a `String`
-> Text | `val`: the string to prepend on the start of `string`
-> m String | Returns: `string`

Adds a string on to the start of a `String`, expanding it if necessary.

## prependC

stringPrependC Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> String | `string`: a `String`
-> Int8 | `c`: the byte to prepend on the start of the `String`
-> m String | Returns: `string`

Adds a byte onto the start of a `String`, expanding it if necessary.

## prependLen

stringPrependLen Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> String | `string`: a `String`
-> Text | `val`: bytes to prepend
-> Int64 | `len`: number of bytes in `val` to prepend, or -1 for all of `val`
-> m String | Returns: `string`

Prepends `len` bytes of `val` to `string`.

If `len` is positive, `val` may contain embedded nuls and need not be nul-terminated. It is the caller's responsibility to ensure that `val` has at least `len` addressable bytes.

If `len` is negative, `val` must be nul-terminated and `len` is considered to request the entire string length. This makes `stringPrependLen` equivalent to `stringPrepend`.

## prependUnichar

stringPrependUnichar Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> String | `string`: a `String`
-> Char | `wc`: a Unicode character
-> m String | Returns: `string`

Converts a Unicode character into UTF-8, and prepends it to the string.

## setSize

stringSetSize Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> String | `string`: a `String`
-> Word64 | `len`: the new length
-> m String | Returns: `string`

Sets the length of a `String`. If the length is less than the current length, the string will be truncated. If the length is greater than the current length, the contents of the newly added area are undefined. (However, as always, string->str[string->len] will be a nul byte.)

## truncate

stringTruncate Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> String | `string`: a `String`
-> Word64 | `len`: the new size of `string`
-> m String | Returns: `string`

Cuts off the end of the GString, leaving the first `len` bytes.

## up

stringUp Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> String | `string`: a `String`
-> m String | Returns: `string`

Deprecated: (Since version 2.2)This function uses the locale-specific `toupper()` function, which is almost never the right thing. Use `stringAsciiUp` or `utf8Strup` instead.

Converts a `String` to uppercase.

# Properties

## allocatedLen

the number of bytes that can be stored in the string before it needs to be reallocated. May be larger than `len`.

getStringAllocatedLen :: MonadIO m => String -> m Word64 Source #

Get the value of the “`allocated_len`” field. When overloading is enabled, this is equivalent to

    get string #allocatedLen

setStringAllocatedLen :: MonadIO m => String -> Word64 -> m () Source #

Set the value of the “`allocated_len`” field. When overloading is enabled, this is equivalent to

    set string [ #allocatedLen := value ]

## len

contains the length of the string, not including the terminating nul byte.

getStringLen :: MonadIO m => String -> m Word64 Source #

Get the value of the “`len`” field. When overloading is enabled, this is equivalent to

    get string #len

setStringLen :: MonadIO m => String -> Word64 -> m () Source #

Set the value of the “`len`” field. When overloading is enabled, this is equivalent to

    set string [ #len := value ]

## str

points to the character data. It may move as text is added. The `str` field is null-terminated and so can be used as an ordinary C string.

clearStringStr :: MonadIO m => String -> m () Source #

Set the value of the “`str`” field to `Nothing`. When overloading is enabled, this is equivalent to

    clear #str

getStringStr :: MonadIO m => String -> m (Maybe Text) Source #

Get the value of the “`str`” field. When overloading is enabled, this is equivalent to

    get string #str

setStringStr :: MonadIO m => String -> CString -> m () Source #

Set the value of the “`str`” field. When overloading is enabled, this is equivalent to

    set string [ #str := value ]