gi-glib-2.0.30: GLib bindings

Copyright | Will Thompson and Iñaki García Etxebarria
License | LGPL-2.1
Maintainer | Iñaki García Etxebarria
Safe Haskell | None
Language | Haskell2010

GI.GLib.Structs.StringChunk

Contents

- Exported types
- Methods
  - clear
  - insert
  - insertConst
  - insertLen

Description

`GStringChunk` provides efficient storage of groups of strings

String chunks are used to store groups of strings. Memory is allocated in blocks, and as strings are added to the `GStringChunk` they are copied into the next free position in a block. When a block is full a new block is allocated.

When storing a large number of strings, string chunks are more efficient than using `strdup` since fewer calls to `malloc()` are needed, and less memory is wasted in memory allocation overheads.

By adding strings with `stringChunkInsertConst` it is also possible to remove duplicates.

To create a new `GStringChunk` use `StringChunk`.`new`().

To add strings to a `GStringChunk` use `stringChunkInsert`.

To add strings to a `GStringChunk`, but without duplicating strings which are already in the `GStringChunk`, use `stringChunkInsertConst`.

To free the entire `GStringChunk` use `stringChunkFree`. It is not possible to free individual strings.

Synopsis

- newtype StringChunk = StringChunk (ManagedPtr StringChunk)
- stringChunkClear :: (HasCallStack, MonadIO m) => StringChunk -> m ()
- stringChunkInsert :: (HasCallStack, MonadIO m) => StringChunk -> Text -> m Text
- stringChunkInsertConst :: (HasCallStack, MonadIO m) => StringChunk -> Text -> m Text
- stringChunkInsertLen :: (HasCallStack, MonadIO m) => StringChunk -> Text -> Int64 -> m Text

# Exported types

newtype StringChunk Source #

Memory-managed wrapper type.

Constructors

StringChunk (ManagedPtr StringChunk) |

#### Instances

Instances details

Eq StringChunk Source # |
Instance details Defined in GI.GLib.Structs.StringChunk Methods (==) :: StringChunk -> StringChunk -> Bool Source # (/=) :: StringChunk -> StringChunk -> Bool Source #
BoxedPtr StringChunk Source # |
Instance details Defined in GI.GLib.Structs.StringChunk Methods boxedPtrCopy :: StringChunk -> IO StringChunk Source # boxedPtrFree :: StringChunk -> IO () Source #
ManagedPtrNewtype StringChunk Source # |
Instance details Defined in GI.GLib.Structs.StringChunk Methods toManagedPtr :: StringChunk -> ManagedPtr StringChunk Source #

# Methods

### Click to display all available methods, including inherited ones

Expand

#### Methods

clear, insert, insertConst, insertLen.

#### Getters

None.

#### Setters

None.

## clear

stringChunkClear Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> StringChunk | `chunk`: a `StringChunk`
-> m () |

Frees all strings contained within the `StringChunk`. After calling `stringChunkClear` it is not safe to access any of the strings which were contained within it.

Since: 2.14

## insert

stringChunkInsert Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> StringChunk | `chunk`: a `StringChunk`
-> Text | `string`: the string to add
-> m Text | Returns: a pointer to the copy of `string` within the `StringChunk`

Adds a copy of `string` to the `StringChunk`. It returns a pointer to the new copy of the string in the `StringChunk`. The characters in the string can be changed, if necessary, though you should not change anything after the end of the string.

Unlike `stringChunkInsertConst`, this function does not check for duplicates. Also strings added with `stringChunkInsert` will not be searched by `stringChunkInsertConst` when looking for duplicates.

## insertConst

stringChunkInsertConst Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> StringChunk | `chunk`: a `StringChunk`
-> Text | `string`: the string to add
-> m Text | Returns: a pointer to the new or existing copy of `string` within the `StringChunk`

Adds a copy of `string` to the `StringChunk`, unless the same string has already been added to the `StringChunk` with `stringChunkInsertConst`.

This function is useful if you need to copy a large number of strings but do not want to waste space storing duplicates. But you must remember that there may be several pointers to the same string, and so any changes made to the strings should be done very carefully.

Note that `stringChunkInsertConst` will not return a pointer to a string added with `stringChunkInsert`, even if they do match.

## insertLen

stringChunkInsertLen Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> StringChunk | `chunk`: a `StringChunk`
-> Text | `string`: bytes to insert
-> Int64 | `len`: number of bytes of `string` to insert, or -1 to insert a nul-terminated string
-> m Text | Returns: a pointer to the copy of `string` within the `StringChunk`

Adds a copy of the first `len` bytes of `string` to the `StringChunk`. The copy is nul-terminated.

Since this function does not stop at nul bytes, it is the caller's responsibility to ensure that `string` has at least `len` addressable bytes.

The characters in the returned string can be changed, if necessary, though you should not change anything after the end of the string.

Since: 2.4