prelude-string: libprelude Reference Manual

## prelude-string prelude-string |

## Functions

int | prelude_string_new ()
int | prelude_string_new_nodup ()
int | prelude_string_new_ref ()
int | prelude_string_new_dup ()
int | prelude_string_new_dup_fast ()
void | prelude_string_destroy ()
void | prelude_string_destroy_internal ()
int | prelude_string_new_nodup_fast ()
int | prelude_string_new_ref_fast ()
int | prelude_string_set_dup_fast ()
int | prelude_string_set_dup ()
int | prelude_string_set_nodup_fast ()
int | prelude_string_set_nodup ()
int | prelude_string_set_ref_fast ()
int | prelude_string_set_ref ()
int | prelude_string_copy_ref ()
int | prelude_string_copy_dup ()
prelude_string_t * | prelude_string_ref ()
int | prelude_string_clone ()
size_t | prelude_string_get_len ()
const char * | prelude_string_get_string_or_default ()
const char * | prelude_string_get_string ()
int | prelude_string_get_string_released ()
prelude_bool_t | prelude_string_is_empty ()
void | prelude_string_clear ()
int | prelude_string_cat ()
int | prelude_string_ncat ()
int | prelude_string_sprintf ()
int | prelude_string_vprintf ()
#define | prelude_string_set_constant()
#define | prelude_string_new_constant()
int | prelude_string_compare ()

## Types and Values

typedef | prelude_string_t

## Description

## Functions

### prelude_string_new ()

    int
    prelude_string_new (prelude_string_t **string);

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

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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.

#### Parameters

string | Pointer to a prelude_string_t object. |

### prelude_string_destroy_internal ()

    void
    prelude_string_destroy_internal (prelude_string_t *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()`.

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

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

#### Parameters

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

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.

#### Parameters

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)

### prelude_string_new_constant()

    #define             prelude_string_new_constant(string, str)

### prelude_string_compare ()

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

Compare `str1` and `str2` .

#### Parameters

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.

## Types and Values

### prelude_string_t

    typedef struct prelude_string prelude_string_t;