buf: libvips Reference Manual

## buf buf — a string you can append to |

## Stability Level

Stable, unless otherwise indicated

## Functions

#define | VIPS_BUF_STATIC()
void | vips_buf_rewind ()
void | vips_buf_destroy ()
void | vips_buf_init ()
void | vips_buf_set_static ()
void | vips_buf_set_dynamic ()
void | vips_buf_init_static ()
void | vips_buf_init_dynamic ()
gboolean | vips_buf_appendns ()
gboolean | vips_buf_appends ()
gboolean | vips_buf_appendf ()
gboolean | vips_buf_vappendf ()
gboolean | vips_buf_appendc ()
gboolean | vips_buf_appendsc ()
gboolean | vips_buf_appendgv ()
gboolean | vips_buf_append_size ()
gboolean | vips_buf_removec ()
gboolean | vips_buf_change ()
gboolean | vips_buf_is_empty ()
gboolean | vips_buf_is_full ()
const char * | vips_buf_all ()
const char * | vips_buf_firstline ()
gboolean | vips_buf_appendg ()
gboolean | vips_buf_appendd ()
int | vips_buf_len ()

## Types and Values

| VipsBuf

## Includes

    #include <vips/vips.h>

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

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    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));

## Functions

### VIPS_BUF_STATIC()

    #define             VIPS_BUF_STATIC(TEXT)

Initialize a heap buffer. For example:

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

#### Parameters

TEXT | the storage area to use |

### vips_buf_rewind ()

    void
    vips_buf_rewind (VipsBuf *buf);

Reset the buffer to the empty string.

#### Parameters

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.

#### Parameters

buf | the buffer |

### vips_buf_init ()

    void
    vips_buf_init (VipsBuf *buf);

Initialize a buffer.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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:

    1
    2
    3
    4
    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.

#### Parameters

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.

    1
    2
    3
    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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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

#### Parameters

buf | the buffer |
fmt | <function>`printf()`</function>-style format string |
... | arguments to 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 <function>`vprintf()`</function>.

#### Parameters

buf | the buffer |
fmt | <function>`printf()`</function>-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` .

#### Parameters

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 as a printable thing. We display text line "3144 bytes of binary data" for BLOBs like icc-profile-data.

Use `vips_image_get_as_string()` to make a text representation of a field. That will base64-encode blobs, for example.

#### Parameters

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.

#### Parameters

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

#### Parameters

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 occurrence of `o` for `n` .

#### Parameters

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

#### Parameters

buf | the buffer |

#### Returns

`TRUE` if the buffer is empty.

### vips_buf_is_full ()

    gboolean
    vips_buf_is_full (VipsBuf *buf);

#### Parameters

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.

#### Parameters

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").

#### Parameters

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.

#### Parameters

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.

#### Parameters

buf | the buffer |
d | value to format and append |

#### Returns

`FALSE` on overflow, `TRUE` otherwise.

### vips_buf_len ()

    int
    vips_buf_len (VipsBuf *buf);

#### Parameters

buf | the buffer |

#### Returns

the number of characters currently in the buffer.

## Types and Values

### VipsBuf

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

## See Also

vips