## buf

buf — a string you can append to

## Stability Level

Stable, unless otherwise indicated

## Synopsis

    #include <vips/vips.h>

                        VipsBuf;
    #define             VIPS_BUF_STATIC                     (TEXT)
    void                vips_buf_rewind                     (VipsBuf *buf);
    void                vips_buf_destroy                    (VipsBuf *buf);
    void                vips_buf_init                       (VipsBuf *buf);
    void                vips_buf_set_static                 (VipsBuf *buf,
                                                             char *base,
                                                             int mx);
    void                vips_buf_set_dynamic                (VipsBuf *buf,
                                                             int mx);
    void                vips_buf_init_static                (VipsBuf *buf,
                                                             char *base,
                                                             int mx);
    void                vips_buf_init_dynamic               (VipsBuf *buf,
                                                             int mx);
    gboolean            vips_buf_appendns                   (VipsBuf *buf,
                                                             const char *str,
                                                             int sz);
    gboolean            vips_buf_appends                    (VipsBuf *buf,
                                                             const char *str);
    gboolean            vips_buf_appendf                    (VipsBuf *buf,
                                                             const char *fmt,
                                                             ...);
    gboolean            vips_buf_vappendf                   (VipsBuf *buf,
                                                             const char *fmt,
                                                             va_list ap);
    gboolean            vips_buf_appendc                    (VipsBuf *buf,
                                                             char ch);
    gboolean            vips_buf_appendsc                   (VipsBuf *buf,
                                                             gboolean quote,
                                                             const char *str);
    gboolean            vips_buf_appendgv                   (VipsBuf *buf,
                                                             GValue *value);
    gboolean            vips_buf_append_size                (VipsBuf *buf,
                                                             size_t n);
    gboolean            vips_buf_removec                    (VipsBuf *buf,
                                                             char ch);
    gboolean            vips_buf_change                     (VipsBuf *buf,
                                                             const char *o,
                                                             const char *n);
    gboolean            vips_buf_is_empty                   (VipsBuf *buf);
    gboolean            vips_buf_is_full                    (VipsBuf *buf);
    const char *        vips_buf_all                        (VipsBuf *buf);
    const char *        vips_buf_firstline                  (VipsBuf *buf);
    gboolean            vips_buf_appendg                    (VipsBuf *buf,
                                                             double g);
    gboolean            vips_buf_appendd                    (VipsBuf *buf,
                                                             int d);
    int                 vips_buf_len                        (VipsBuf *buf);

## Description

A message buffer you can append stuff to safely and quickly. If the message gets too long, you get "..." and truncation. Message buffers can be on the stack or heap.

For example:

    char txt[256];
    VipsBuf buf = VIPS_BUF_STATIC (txt);
    int i;

    vips_buf_appends (&buf, "Numbers are: ");
    for (i = 0; i < array_length; i++) {
      if (i > 0)
        vips_buf_appends (&buf, ", ");
      vips_buf_appendg (&buf, array[i]);
    }
    printf ("%s", vips_buf_all (&buf));

## Details

### VipsBuf

    typedef struct {
    	/* All fields are private.
    	 */
    } VipsBuf;

### VIPS_BUF_STATIC()

    #define             VIPS_BUF_STATIC( TEXT )

Initialize a heap buffer. For example:

    char txt[256];
    VipsBuf buf = VIPS_BUF_STATIC (txt);

`TEXT` : | the storage area to use

### vips_buf_rewind ()

    void                vips_buf_rewind                     (VipsBuf *buf);

Reset the buffer to the empty string.

`buf` : | the buffer

### vips_buf_destroy ()

    void                vips_buf_destroy                    (VipsBuf *buf);

Destroy a buffer. Only needed for heap buffers. Leaves the buffer in the _init state.

`buf` : | the buffer

### vips_buf_init ()

    void                vips_buf_init                       (VipsBuf *buf);

Initialize a buffer.

`buf` : | the buffer

### vips_buf_set_static ()

    void                vips_buf_set_static                 (VipsBuf *buf,
                                                             char *base,
                                                             int mx);

Attach the buffer to a static memory area. The buffer needs to have been initialised. The memory area needs to be at least 4 bytes long.

`buf` : | the buffer
`base` : | the start of the memory area to use for storage
`mx` : | the size of the storage area

### vips_buf_set_dynamic ()

    void                vips_buf_set_dynamic                (VipsBuf *buf,
                                                             int mx);

Attach the buffer to a heap memory area. The buffer needs to have been initialised. The memory area needs to be at least 4 bytes long.

`buf` : | the buffer
`mx` : | the size of the storage area

### vips_buf_init_static ()

    void                vips_buf_init_static                (VipsBuf *buf,
                                                             char *base,
                                                             int mx);

Initialise and attach to a static memory area. `VIPS_BUF_STATIC()` is usually more convenient.

For example:

    char txt[256];
    VipsBuf buf;

    vips_buf_init_static (&buf, txt, 256);

Static buffers don't need to be freed when they go out of scope, but their size must be set at compile-time.

`buf` : | the buffer
`base` : | the start of the memory area to use for storage
`mx` : | the size of the storage area

### vips_buf_init_dynamic ()

    void                vips_buf_init_dynamic               (VipsBuf *buf,
                                                             int mx);

Initialise and attach to a heap memory area. The memory area needs to be at least 4 bytes long.

    VipsBuf buf;

    vips_buf_init_synamic (&buf, 256);

Dynamic buffers must be freed with `vips_buf_destroy()`, but their size can be set at runtime.

`buf` : | the buffer
`mx` : | the size of the storage area

### vips_buf_appendns ()

    gboolean            vips_buf_appendns                   (VipsBuf *buf,
                                                             const char *str,
                                                             int sz);

Append at most `sz` chars from `str` to `buf`. `sz` < 0 means unlimited. This is the low-level append operation: functions like `vips_buf_appendf()` build on top of this.

`buf` : | the buffer
`str` : | the string to append to the buffer
`sz` : | the size of the string to append
Returns : | `FALSE` on overflow, `TRUE` otherwise.

### vips_buf_appends ()

    gboolean            vips_buf_appends                    (VipsBuf *buf,
                                                             const char *str);

Append the whole of `str` to `buf`.

`buf` : | the buffer
`str` : | the string to append to the buffer
Returns : | `FALSE` on overflow, `TRUE` otherwise.

### vips_buf_appendf ()

    gboolean            vips_buf_appendf                    (VipsBuf *buf,
                                                             const char *fmt,
                                                             ...);

Format the string and append to `buf`.

`buf` : | the buffer
`fmt` : | ``printf()``-style format string
Returns : | `FALSE` on overflow, `TRUE` otherwise.

### vips_buf_vappendf ()

    gboolean            vips_buf_vappendf                   (VipsBuf *buf,
                                                             const char *fmt,
                                                             va_list ap);

Append to `buf`, args as ``vprintf()``.

`buf` : | the buffer
`fmt` : | ``printf()``-style format string
`ap` : | arguments to format string
Returns : | `FALSE` on overflow, `TRUE` otherwise.

### vips_buf_appendc ()

    gboolean            vips_buf_appendc                    (VipsBuf *buf,
                                                             char ch);

Append a single character `ch` to `buf`.

`buf` : | the buffer
`ch` : | the character to append to the buffer
Returns : | `FALSE` on overflow, `TRUE` otherwise.

### vips_buf_appendsc ()

    gboolean            vips_buf_appendsc                   (VipsBuf *buf,
                                                             gboolean quote,
                                                             const char *str);

### vips_buf_appendgv ()

    gboolean            vips_buf_appendgv                   (VipsBuf *buf,
                                                             GValue *value);

Format and append a GValue with `g_strdup_value_contents()`.

`buf` : | the buffer
`value` : | GValue to format and append
Returns : | `FALSE` on overflow, `TRUE` otherwise.

### vips_buf_append_size ()

    gboolean            vips_buf_append_size                (VipsBuf *buf,
                                                             size_t n);

Turn a number of bytes into a sensible string ... eg "12", "12KB", "12MB", "12GB" etc.

`buf` : | the buffer
`n` : | the number of bytes
Returns : | `FALSE` on overflow, `TRUE` otherwise.

### vips_buf_removec ()

    gboolean            vips_buf_removec                    (VipsBuf *buf,
                                                             char ch);

Remove the last character, if it's `ch`.

`buf` : | the buffer
`ch` : | the character to remove
Returns : | `FALSE` on failure, `TRUE` otherwise.

### vips_buf_change ()

    gboolean            vips_buf_change                     (VipsBuf *buf,
                                                             const char *o,
                                                             const char *n);

Swap the rightmost occurence of `o` for `n`.

`buf` : | the buffer
`o` : | the string to search for
`n` : | the string to substitute
Returns : | `FALSE` on overflow, `TRUE` otherwise.

### vips_buf_is_empty ()

    gboolean            vips_buf_is_empty                   (VipsBuf *buf);

`buf` : | the buffer
Returns : | `TRUE` if the buffer is empty.

### vips_buf_is_full ()

    gboolean            vips_buf_is_full                    (VipsBuf *buf);

`buf` : | the buffer
Returns : | `TRUE` if the buffer is full.

### vips_buf_all ()

    const char *        vips_buf_all                        (VipsBuf *buf);

Return the contents of the buffer as a C string.

`buf` : | the buffer
Returns : | the `NULL`-terminated contents of the buffer. This is a pointer to the memory managed by the buffer and must not be freed.

### vips_buf_firstline ()

    const char *        vips_buf_firstline                  (VipsBuf *buf);

Trim to just the first line (excluding "\n").

`buf` : | the buffer
Returns : | the `NULL`-terminated contents of the buffer. This is a pointer to the memory managed by the buffer and must not be freed.

### vips_buf_appendg ()

    gboolean            vips_buf_appendg                    (VipsBuf *buf,
                                                             double g);

Append a double, non-localised. Useful for config files etc.

`buf` : | the buffer
`g` : | value to format and append
Returns : | `FALSE` on overflow, `TRUE` otherwise.

### vips_buf_appendd ()

    gboolean            vips_buf_appendd                    (VipsBuf *buf,
                                                             int d);

Append a number. If the number is -ve, add brackets. Needed for building function arguments.

`buf` : | the buffer
`d` : | value to format and append
Returns : | `FALSE` on overflow, `TRUE` otherwise.

### vips_buf_len ()

    int                 vips_buf_len                        (VipsBuf *buf);

`buf` : | the buffer
Returns : | the number of characters currently in the buffer.

## See Also

vips