String buffer
3
RAPTOR Library

# String buffer

Append-only strings.

## Synopsis

    typedef             raptor_stringbuffer;
    raptor_stringbuffer* raptor_new_stringbuffer            (void);
    void                raptor_free_stringbuffer            (raptor_stringbuffer *stringbuffer);
    int                 raptor_stringbuffer_append_counted_string
                                                            (raptor_stringbuffer *stringbuffer,
                                                             unsigned char *string,
                                                             size_t length,
                                                             int do_copy);
    int                 raptor_stringbuffer_append_string   (raptor_stringbuffer *stringbuffer,
                                                             unsigned char *string,
                                                             int do_copy);
    int                 raptor_stringbuffer_append_decimal  (raptor_stringbuffer *stringbuffer,
                                                             int integer);
    int                 raptor_stringbuffer_append_stringbuffer
                                                            (raptor_stringbuffer *stringbuffer,
                                                             raptor_stringbuffer *append);
    int                 raptor_stringbuffer_prepend_counted_string
                                                            (raptor_stringbuffer *stringbuffer,
                                                             unsigned char *string,
                                                             size_t length,
                                                             int do_copy);
    int                 raptor_stringbuffer_prepend_string  (raptor_stringbuffer *stringbuffer,
                                                             unsigned char *string,
                                                             int do_copy);
    unsigned char*      raptor_stringbuffer_as_string       (raptor_stringbuffer *stringbuffer);
    size_t              raptor_stringbuffer_length          (raptor_stringbuffer *stringbuffer);
    int                 raptor_stringbuffer_copy_to_string  (raptor_stringbuffer *stringbuffer,
                                                             unsigned char *string,
                                                             size_t length);

## Description

A utility class that allows easy construction of strings that grow at the end by appending new strings. Primarily used for constructing/serializing syntaxes into strings by the raptor_iostream and raptor_serializer classes.

## Details

### raptor_stringbuffer

    raptor_stringbuffer* raptor_stringbuffer;

Raptor string buffer class

### raptor_new_stringbuffer ()

    raptor_stringbuffer* raptor_new_stringbuffer            (void);

Create a new stringbuffer.

Returns :

  pointer to a raptor_stringbuffer object or NULL on failure

### raptor_free_stringbuffer ()

    void                raptor_free_stringbuffer            (raptor_stringbuffer *stringbuffer);

Destroy a stringbuffer.

`stringbuffer` :

  stringbuffer object to destroy.

### raptor_stringbuffer_append_counted_string ()

    int                 raptor_stringbuffer_append_counted_string
                                                            (raptor_stringbuffer *stringbuffer,
                                                             unsigned char *string,
                                                             size_t length,
                                                             int do_copy);

If `string` is NULL or `length` is 0, no work is performed.

If `do_copy` is non-0, the passed-in string is copied into new memory otherwise the stringbuffer becomes the owner of the string pointer and will free it when the stringbuffer is destroyed.

Add a string to the stringbuffer.

`stringbuffer` :

  raptor stringbuffer

`string` :

  string

`length` :

  length of string

`do_copy` :

  non-0 to copy the string

Returns :

  non-0 on failure

### raptor_stringbuffer_append_string ()

    int                 raptor_stringbuffer_append_string   (raptor_stringbuffer *stringbuffer,
                                                             unsigned char *string,
                                                             int do_copy);

Add a string to the stringbuffer.

If `string` is NULL, no work is performed.

If `do_copy` is non-0, the passed-in string is copied into new memory otherwise the stringbuffer becomes the owner of the string pointer and will free it when the stringbuffer is destroyed.

`stringbuffer` :

  raptor stringbuffer

`string` :

  string

`do_copy` :

  non-0 to copy the string

Returns :

  non-0 on failure

### raptor_stringbuffer_append_decimal ()

    int                 raptor_stringbuffer_append_decimal  (raptor_stringbuffer *stringbuffer,
                                                             int integer);

Add an integer in decimal to the stringbuffer.

`stringbuffer` :

  raptor stringbuffer

`integer` :

  integer to format as decimal and add

Returns :

  non-0 on failure

### raptor_stringbuffer_append_stringbuffer ()

    int                 raptor_stringbuffer_append_stringbuffer
                                                            (raptor_stringbuffer *stringbuffer,
                                                             raptor_stringbuffer *append);

Add a stringbuffer to the stringbuffer.

This function removes the content from the appending stringbuffer, making it empty and appends it to the supplied stringbuffer.

`stringbuffer` :

  raptor_stringbuffer

`append` :

  raptor_stringbuffer to append

Returns :

  non-0 on failure

### raptor_stringbuffer_prepend_counted_string ()

    int                 raptor_stringbuffer_prepend_counted_string
                                                            (raptor_stringbuffer *stringbuffer,
                                                             unsigned char *string,
                                                             size_t length,
                                                             int do_copy);

If do_copy is non-0, the passed-in string is copied into new memory otherwise the stringbuffer becomes the owner of the string pointer and will free it when the stringbuffer is destroyed.

Add a string to the start of the stringbuffer.

`stringbuffer` :

  raptor stringbuffer

`string` :

  string

`length` :

  length of string

`do_copy` :

  non-0 to copy the string

Returns :

  non-0 on failure

### raptor_stringbuffer_prepend_string ()

    int                 raptor_stringbuffer_prepend_string  (raptor_stringbuffer *stringbuffer,
                                                             unsigned char *string,
                                                             int do_copy);

Add a string to the start of the stringbuffer.

If do_copy is non-0, the passed-in string is copied into new memory otherwise the stringbuffer becomes the owner of the string pointer and will free it when the stringbuffer is destroyed.

`stringbuffer` :

  raptor stringbuffer

`string` :

  string

`do_copy` :

  non-0 to copy the string

Returns :

  non-0 on failure

### raptor_stringbuffer_as_string ()

    unsigned char*      raptor_stringbuffer_as_string       (raptor_stringbuffer *stringbuffer);

Return the stringbuffer as a C string.

Note: the return value is a to a shared string that the stringbuffer allocates and manages.

`stringbuffer` :

  raptor stringbuffer

Returns :

  NULL on failure or stringbuffer is empty, otherwise a pointer to a shared copy of the string.

### raptor_stringbuffer_length ()

    size_t              raptor_stringbuffer_length          (raptor_stringbuffer *stringbuffer);

Return the stringbuffer length.

`stringbuffer` :

  raptor stringbuffer

Returns :

  size of stringbuffer

### raptor_stringbuffer_copy_to_string ()

    int                 raptor_stringbuffer_copy_to_string  (raptor_stringbuffer *stringbuffer,
                                                             unsigned char *string,
                                                             size_t length);

Copy the stringbuffer into a string.

Copies the underlying string to a pre-allocated buffer. The output string is always '\0' terminated.

`stringbuffer` :

  raptor stringbuffer

`string` :

  output string

`length` :

  size of output string

Returns :

  non-0 on failure such as stringbuffer is empty, buffer is too small