GLib.StringChunk¶

record (struct)

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 StringChunk.insert_const it is also possible to remove duplicates.

To create a new GStringChunk use StringChunk.new.

To add strings to a GStringChunk use StringChunk.insert.

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

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

Methods¶

clear¶

def clear(self) -> None

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

free¶

def free(self) -> None

Frees all memory allocated by the StringChunk. After calling StringChunk.free it is not safe to access any of the strings which were contained within it.

insert¶

def insert(self, string: str) -> str

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 StringChunk.insert_const, this function does not check for duplicates. Also strings added with StringChunk.insert will not be searched by StringChunk.insert_const when looking for duplicates.

Parameters:

string — the string to add

insert_const¶

def insert_const(self, string: str) -> str

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

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 StringChunk.insert_const will not return a pointer to a string added with StringChunk.insert, even if they do match.

Parameters:

string — the string to add

insert_len¶

def insert_len(self, string: str, len: int) -> str

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.

Parameters:

string — bytes to insert
len — number of bytes of string to insert, or -1 to insert a nul-terminated string