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