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_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

... :

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 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_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