Strings

Strings — text buffers which grow automatically as text is added

Synopsis

lt_string_t *       lt_string_append                    (lt_string_t *string,
                                                         const char *str);
lt_string_t *       lt_string_append_c                  (lt_string_t *string,
                                                         char c);
lt_string_t *       lt_string_append_filename           (lt_string_t *string,
                                                         const char *path);
char                lt_string_at                        (lt_string_t *string,
                                                         ssize_t pos);
void                lt_string_clear                     (lt_string_t *string);
char *              lt_string_free                      (lt_string_t *string,
                                                         lt_bool_t free_segment);
size_t              lt_string_length                    (const lt_string_t *string);
lt_string_t *       lt_string_new                       (const char *string);
lt_string_t *       lt_string_ref                       (lt_string_t *string);
lt_string_t *       lt_string_replace_c                 (lt_string_t *string,
                                                         size_t pos,
                                                         char c);
                    lt_string_t;
lt_string_t *       lt_string_truncate                  (lt_string_t *string,
                                                         ssize_t len);
void                lt_string_unref                     (lt_string_t *string);
const char *        lt_string_value                     (const lt_string_t *string);

Description

A lt_string_t is an object that handles the memory management of a C string.

Details

lt_string_append ()

lt_string_t *       lt_string_append                    (lt_string_t *string,
                                                         const char *str);

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

string :

a lt_string_t

str :

the string to append onto the end of string

Returns :

the same string object. [transfer none]

lt_string_append_c ()

lt_string_t *       lt_string_append_c                  (lt_string_t *string,
                                                         char c);

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

string :

a lt_string_t

c :

the byte to append onto the end of string

Returns :

the same string object. [transfer none]

lt_string_append_filename ()

lt_string_t *       lt_string_append_filename           (lt_string_t *string,
                                                         const char *path);

Adds a string onto the end of a lt_string_t as a file path.

string :

a lt_string_t

path :

the string to append onto the end of string as a file path

Returns :

the same string object. [transfer none]

lt_string_at ()

char                lt_string_at                        (lt_string_t *string,
                                                         ssize_t pos);

Obtain a byte in a lt_string_t at pos. If pos is a negative, the position is calculated from current size. i.e. if the buffer contains "abc", and pos is -1, this will returns 'c' then.

string :

a lt_string_t

pos :

position in string where to obtain the byte

Returns :

the byte in string at pos

lt_string_clear ()

void                lt_string_clear                     (lt_string_t *string);

Clean up the buffer in string.

string :

a lt_string_t

lt_string_free ()

char *              lt_string_free                      (lt_string_t *string,
                                                         lt_bool_t free_segment);

Frees the memory allocated for the lt_string_t. If free_segment 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().

string :

a lt_string_t

free_segment :

if TRUE, the actual character data is freed as well

Returns :

the character data of string (i.e. NULL if free_segment is TRUE)

lt_string_length ()

size_t              lt_string_length                    (const lt_string_t *string);

Returns the number of characters in buffer for string.

string :

a lt_string_t

Returns :

the number of characters

lt_string_new ()

lt_string_t *       lt_string_new                       (const char *string);

Creates an instance of lt_string_t with string.

string :

an initial string to set

Returns :

a new instance of lt_string_t.

lt_string_ref ()

lt_string_t *       lt_string_ref                       (lt_string_t *string);

Increases the reference count of string.

string :

a lt_string_t

Returns :

the same string object. [transfer none]

lt_string_replace_c ()

lt_string_t *       lt_string_replace_c                 (lt_string_t *string,
                                                         size_t pos,
                                                         char c);

Replaces a character in string at pos.

string :

a lt_string_t

pos :

position in string where replacement should happen

c :

the byte to replace

Returns :

the same string object. [transfer none]

lt_string_t

typedef struct _lt_string_t lt_string_t;

All the fields in the lt_string_t structure are private to the lt_string_t implementation.


lt_string_truncate ()

lt_string_t *       lt_string_truncate                  (lt_string_t *string,
                                                         ssize_t len);

Truncates the characters in the buffer according to len. if len is a negative, how many characters is truncated will be calculated from current size. i.e. if the buffer contains "abc", and len is -1, the buffer will be "ab" after this call.

string :

a lt_string_t

len :

the number of characters to be truncated from the buffer.

Returns :

the same string object. [transfer none]

lt_string_unref ()

void                lt_string_unref                     (lt_string_t *string);

Decreases the reference count of string. when its reference count drops to 0, the object is finalized (i.e. its memory is freed).

string :

a lt_string_t

lt_string_value ()

const char *        lt_string_value                     (const lt_string_t *string);

Returns the buffer in string.

string :

a lt_string_t

Returns :

a string which string has.