## prelude-string

prelude-string —

## Synopsis

    struct      prelude_string;
    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)

## Description

## Details

### struct prelude_string

    struct prelude_string {
    	prelude_list_t list;

            int flags;
            int refcount;

            union {
                    char *rwbuf;
                    const char *robuf;
    };

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