## prelude-string

prelude-string

## Synopsis

    typedef             prelude_string_t;
    int                 prelude_string_new                  (prelude_string_t **string);
    int                 prelude_string_new_nodup            (prelude_string_t **string,
                                                             char *str);
    int                 prelude_string_new_ref              (prelude_string_t **string,
                                                             const char *str);
    int                 prelude_string_new_dup              (prelude_string_t **string,
                                                             const char *str);
    int                 prelude_string_new_dup_fast         (prelude_string_t **string,
                                                             const char *str,
                                                             size_t len);
    void                prelude_string_destroy              (prelude_string_t *string);
    void                prelude_string_destroy_internal     (prelude_string_t *string);
    int                 prelude_string_new_nodup_fast       (prelude_string_t **string,
                                                             char *str,
                                                             size_t len);
    int                 prelude_string_new_ref_fast         (prelude_string_t **string,
                                                             const char *str,
                                                             size_t len);
    int                 prelude_string_set_dup_fast         (prelude_string_t *string,
                                                             const char *buf,
                                                             size_t len);
    int                 prelude_string_set_dup              (prelude_string_t *string,
                                                             const char *buf);
    int                 prelude_string_set_nodup_fast       (prelude_string_t *string,
                                                             char *buf,
                                                             size_t len);
    int                 prelude_string_set_nodup            (prelude_string_t *string,
                                                             char *buf);
    int                 prelude_string_set_ref_fast         (prelude_string_t *string,
                                                             const char *buf,
                                                             size_t len);
    int                 prelude_string_set_ref              (prelude_string_t *string,
                                                             const char *buf);
    int                 prelude_string_copy_ref             (const prelude_string_t *src,
                                                             prelude_string_t *dst);
    int                 prelude_string_copy_dup             (const prelude_string_t *src,
                                                             prelude_string_t *dst);
    prelude_string_t *  prelude_string_ref                  (prelude_string_t *string);
    int                 prelude_string_clone                (const prelude_string_t *src,
                                                             prelude_string_t **dst);
    size_t              prelude_string_get_len              (const prelude_string_t *string);
    const char *        prelude_string_get_string_or_default
                                                            (const prelude_string_t *string,
                                                             const char *def);
    const char *        prelude_string_get_string           (const prelude_string_t *string);
    int                 prelude_string_get_string_released  (prelude_string_t *string,
                                                             char **outptr);
    prelude_bool_t      prelude_string_is_empty             (const prelude_string_t *string);
    void                prelude_string_clear                (prelude_string_t *string);
    int                 prelude_string_cat                  (prelude_string_t *dst,
                                                             const char *str);
    int                 prelude_string_ncat                 (prelude_string_t *dst,
                                                             const char *str,
                                                             size_t len);
    int                 prelude_string_sprintf              (prelude_string_t *string,
                                                             const char *fmt,
                                                             ...);
    int                 prelude_string_vprintf              (prelude_string_t *string,
                                                             const char *fmt,
                                                             va_list ap);
    #define             prelude_string_set_constant         (string, str)
    #define             prelude_string_new_constant         (string, str)
    int                 prelude_string_compare              (const prelude_string_t *str1,
                                                             const prelude_string_t *str2);

## Description

## Details

### prelude_string_t

    typedef struct prelude_string prelude_string_t;

### prelude_string_new ()

    int                 prelude_string_new                  (prelude_string_t **string);

Create a new prelude_string_t object, and store in in `string`.

`string` : | Pointer where to store the created prelude_string_t.
Returns : | 0 on success, or a negative value if an error occured.

### prelude_string_new_nodup ()

    int                 prelude_string_new_nodup            (prelude_string_t **string,
                                                             char *str);

Create a new prelude_string_t object with a reference to `str` as initial value. `str` is owned by `string` and will be freed upon `prelude_string_destroy()`.

`string` : | Pointer where to store the created prelude_string_t object.
`str` : | Initial string value.
Returns : | 0 on success, a negative value if an error occured.

### prelude_string_new_ref ()

    int                 prelude_string_new_ref              (prelude_string_t **string,
                                                             const char *str);

Create a new prelude_string_t object with a reference to `str` as initial value. `str` won't be freed upon `prelude_string_destroy()`.

`string` : | Pointer where to store the created prelude_string_t object.
`str` : | Initial string value.
Returns : | 0 on success, a negative value if an error occured.

### prelude_string_new_dup ()

    int                 prelude_string_new_dup              (prelude_string_t **string,
                                                             const char *str);

Create a new prelude_string_t object with a copy of `str` as it's initial value. The copy is owned by the `string` and will be freed upon `prelude_string_destroy()`.

`string` : | Pointer where to store the created prelude_string_t object.
`str` : | Initial string value.
Returns : | 0 on success, a negative value if an error occured.

### prelude_string_new_dup_fast ()

    int                 prelude_string_new_dup_fast         (prelude_string_t **string,
                                                             const char *str,
                                                             size_t len);

Create a new prelude_string_t object with a copy of `str` as it's initial value. The copy is owned by the `string` and will be freed upon `prelude_string_destroy()`.

`string` : | Pointer where to store the created prelude_string_t object.
`str` : | Initial string value.
`len` : | Lenght of `str`.
Returns : | 0 on success, a negative value if an error occured.

### prelude_string_destroy ()

    void                prelude_string_destroy              (prelude_string_t *string);

Decrease refcount and destroy `string`. `string` content content is destroyed if applicable (dup and nodup, or a referenced string that have been modified.

`string` : | Pointer to a prelude_string_t object.

### prelude_string_destroy_internal ()

    void                prelude_string_destroy_internal     (prelude_string_t *string);

`string` : |

### prelude_string_new_nodup_fast ()

    int                 prelude_string_new_nodup_fast       (prelude_string_t **string,
                                                             char *str,
                                                             size_t len);

Create a new prelude_string_t object with a reference to `str` as initial value. `str` is owned by `string` and will be freed upon `prelude_string_destroy()`.

`string` : | Pointer where to store the created prelude_string_t object.
`str` : | Initial string value.
`len` : | Lenght of `str`.
Returns : | 0 on success, a negative value if an error occured.

### prelude_string_new_ref_fast ()

    int                 prelude_string_new_ref_fast         (prelude_string_t **string,
                                                             const char *str,
                                                             size_t len);

Create a new prelude_string_t object with a reference to `str` as initial value. `str` won't be freed upon `prelude_string_destroy()`.

`string` : | Pointer where to store the created prelude_string_t object.
`str` : | Initial string value.
`len` : | Length of `str`.
Returns : | 0 on success, a negative value if an error occured.

### prelude_string_set_dup_fast ()

    int                 prelude_string_set_dup_fast         (prelude_string_t *string,
                                                             const char *buf,
                                                             size_t len);

Store a copy of the string pointed by `buf` in `string`. The `buf` copy will be freed upon `prelude_string_destroy()`.

`string` : | Pointer to a prelude_string_t object.
`buf` : | String to store in `string`.
`len` : | Lenght of `buf`.
Returns : | 0 on success, or a negative value if an error occured.

### prelude_string_set_dup ()

    int                 prelude_string_set_dup              (prelude_string_t *string,
                                                             const char *buf);

Store a copy of the string pointed by `buf` in `string`. The `buf` copy will be freed upon `prelude_string_destroy()`.

`string` : | Pointer to a prelude_string_t object.
`buf` : | String to store in `string`.
Returns : | 0 on success, or a negative value if an error occured.

### prelude_string_set_nodup_fast ()

    int                 prelude_string_set_nodup_fast       (prelude_string_t *string,
                                                             char *buf,
                                                             size_t len);

Store a reference to the string pointed by `buf` in `string`. The referenced `buf` will be freed upon `prelude_string_destroy()`.

`string` : | Pointer to a prelude_string_t object.
`buf` : | String to store in `string`.
`len` : | Lenght of `buf`.
Returns : | 0 on success, or a negative value if an error occured.

### prelude_string_set_nodup ()

    int                 prelude_string_set_nodup            (prelude_string_t *string,
                                                             char *buf);

Store a reference to the string pointed by `buf` in `string`. The referenced `buf` will be freed upon `prelude_string_destroy()`.

`string` : | Pointer to a prelude_string_t object.
`buf` : | String to store in `string`.
Returns : | 0 on success, or a negative value if an error occured.

### prelude_string_set_ref_fast ()

    int                 prelude_string_set_ref_fast         (prelude_string_t *string,
                                                             const char *buf,
                                                             size_t len);

Store a reference to the string pointed by `buf` in `string`. The referenced `buf` value won't be modified or freed.

`string` : | Pointer to a prelude_string_t object.
`buf` : | String to store in `string`.
`len` : | Lenght of `buf`.
Returns : | 0 on success, or a negative value if an error occured.

### prelude_string_set_ref ()

    int                 prelude_string_set_ref              (prelude_string_t *string,
                                                             const char *buf);

Store a reference to the string pointed by `buf` in `string`. The referenced `buf` value won't be modified or freed.

`string` : | Pointer to a prelude_string_t object.
`buf` : | String to store in `string`.
Returns : | 0 on success, or a negative value if an error occured.

### prelude_string_copy_ref ()

    int                 prelude_string_copy_ref             (const prelude_string_t *src,
                                                             prelude_string_t *dst);

Reference `src` content within `dst`. The referenced content won't be modified or freed.

`src` : | Pointer to a prelude_string_t object to copy data from.
`dst` : | Pointer to a prelude_string_t object to copy data to.
Returns : | 0 on success, or a negative value if an error occured.

### prelude_string_copy_dup ()

    int                 prelude_string_copy_dup             (const prelude_string_t *src,
                                                             prelude_string_t *dst);

Copy `src` content within `dst`. The content is owned by `src` and independent of `dst`.

`src` : | Pointer to a prelude_string_t object to copy data from.
`dst` : | Pointer to a prelude_string_t object to copy data to.
Returns : | 0 on success, or a negative value if an error occured.

### prelude_string_ref ()

    prelude_string_t *  prelude_string_ref                  (prelude_string_t *string);

Increase `string` reference count.

`string` : | Pointer to a prelude_string_t object to reference.
Returns : | `string`.

### prelude_string_clone ()

    int                 prelude_string_clone                (const prelude_string_t *src,
                                                             prelude_string_t **dst);

Clone `src` within a new prelude_string_t object stored into `dst`. Data carried by `dst` and `src` are independant.

`src` : | Pointer to an existing prelude_string_t object.
`dst` : | Pointer to an address where to store the created prelude_string_t object.
Returns : | 0 on success, or a negative value if an error occured.

### prelude_string_get_len ()

    size_t              prelude_string_get_len              (const prelude_string_t *string);

Return the length of the string carried by `string` object.

`string` : | Pointer to a prelude_string_t object.
Returns : | The length of the string owned by `string`.

### prelude_string_get_string_or_default ()

    const char *        prelude_string_get_string_or_default
                                                            (const prelude_string_t *string,
                                                             const char *def);

Return the string carried on by `string` object, or `def` if it is empty. There should be no operation done on the returned string since it is still owned by `string`.

`string` : | Pointer to a prelude_string_t object.
`def` : | Default value to a return in case `string` is empty.
Returns : | The string owned by `string` or `def`.

### prelude_string_get_string ()

    const char *        prelude_string_get_string           (const prelude_string_t *string);

Return the string carried on by `string` object. There should be no operation done on the returned string since it is still owned by `string`.

`string` : | Pointer to a prelude_string_t object.
Returns : | The string owned by `string` if any.

### prelude_string_get_string_released ()

    int                 prelude_string_get_string_released  (prelude_string_t *string,
                                                             char **outptr);

Get `string` content, and release it so that further operation on `string` won't modify the returned content.

`string` : | Pointer to a prelude_string_t object.
`outptr` : | Pointer to an address where to store the released string.
Returns : | 0 on success, or a negative value if an error occured.

### prelude_string_is_empty ()

    prelude_bool_t      prelude_string_is_empty             (const prelude_string_t *string);

Check whether `string` is empty.

`string` : | Pointer to a prelude_string_t object.
Returns : | TRUE if `string` is empty, FALSE otherwise.

### prelude_string_clear ()

    void                prelude_string_clear                (prelude_string_t *string);

Reset `string` content to zero.

`string` : | Pointer to a prelude_string_t object.

### prelude_string_cat ()

    int                 prelude_string_cat                  (prelude_string_t *dst,
                                                             const char *str);

The `prelude_string_cat()` function appends the `str` string to the `dst` prelude_string_t object over-writing the `\0' character at the end of `dst`, and then adds a termi-nating `\0' character.

`dst` : | Pointer to a prelude_string_t object.
`str` : | Pointer to a string.
Returns : | `len`, or a negative value if an error occured.

### prelude_string_ncat ()

    int                 prelude_string_ncat                 (prelude_string_t *dst,
                                                             const char *str,
                                                             size_t len);

`dst` : |
`str` : |
`len` : |
Returns : |

### prelude_string_sprintf ()

    int                 prelude_string_sprintf              (prelude_string_t *string,
                                                             const char *fmt,
                                                             ...);

Produce output according to `fmt`, and write output to the given `string`. See snprintf(3) to learn more about `fmt` format.

`string` : | Pointer to a prelude_string_t object.
`fmt` : | Format string to use.
`...` : | Variable argument list.
Returns : | The number of characters written, or a negative value if an error occured.

### prelude_string_vprintf ()

    int                 prelude_string_vprintf              (prelude_string_t *string,
                                                             const char *fmt,
                                                             va_list ap);

Produce output according to `fmt`, storing argument provided in `ap` variable argument list, and write the output to the given `string`. See sprintf(3) for more information on `fmt` format.

`string` : | Pointer to a prelude_string_t object.
`fmt` : | Format string to use.
`ap` : | Variable argument list.
Returns : | The number of characters written, or a negative value if an error occured.

### prelude_string_set_constant()

    #define             prelude_string_set_constant(string, str)

`string` : |
`str` : |

### prelude_string_new_constant()

    #define             prelude_string_new_constant(string, str)

`string` : |
`str` : |

### prelude_string_compare ()

    int                 prelude_string_compare              (const prelude_string_t *str1,
                                                             const prelude_string_t *str2);

`str1` : | Pointer to a prelude_string_t object to compare with `str2`.
`str2` : | Pointer to a prelude_string_t object to compare with `str1`.
Returns : | 0 if `str1` and `str2` value are equal, a negative value otherwise.