## Strings

Strings — text buffers which grow automatically as text is added

## Functions

lt_string_t * | lt_string_new ()
lt_string_t * | lt_string_ref ()
void | lt_string_unref ()
char * | lt_string_free ()
size_t | lt_string_length ()
const char * | lt_string_value ()
lt_string_t * | lt_string_truncate ()
void | lt_string_clear ()
lt_string_t * | lt_string_append_c ()
lt_string_t * | lt_string_append ()
lt_string_t * | lt_string_append_filename ()
lt_string_t * | lt_string_replace_c ()
char | lt_string_at ()

## Types and Values

| lt_string_t

## Description

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

## Functions

### lt_string_new ()

    lt_string_t *
    lt_string_new (const char *string);

Creates an instance of lt_string_t with `string` .

#### Parameters

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` .

#### Parameters

string | a lt_string_t |

#### 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).

#### Parameters

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()`.

#### Parameters

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` .

#### Parameters

string | a lt_string_t |

#### Returns

the number of characters

### lt_string_value ()

    const char *
    lt_string_value (const lt_string_t *string);

Returns the buffer in `string` .

#### Parameters

string | a lt_string_t |

#### Returns

a string which `string` has.

### 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.

#### Parameters

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_clear ()

    void
    lt_string_clear (lt_string_t *string);

Clean up the buffer in `string` .

#### Parameters

string | a lt_string_t |

### 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.

#### Parameters

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 ()

    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.

#### Parameters

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_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.

#### Parameters

string | a lt_string_t |
path | the string to append onto the end of `string` as a file path |
... | a `NULL`-terminated list of strings to append onto the end of `string` as a file path |

#### 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` .

#### Parameters

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_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.

#### Parameters

string | a lt_string_t |
pos | position in `string` where to obtain the byte |

#### Returns

the byte in `string` at `pos`

## Types and Values

### 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.