GskBuffer

typedef struct {
  guint			size;

  GskBufferFragment    *first_frag;
  GskBufferFragment    *last_frag;
} GskBuffer;

A buffer is just a list of fragments and a size counter.

GskBufferFragment

typedef struct {
  GskBufferFragment    *next;
  char                 *buf;
  guint                 buf_max_size;	/* allocation size of buf */
  guint                 buf_start;	/* offset in buf of valid data */
  guint                 buf_length;	/* length of valid data in buf */
  
  gboolean              is_foreign;
  GDestroyNotify        destroy;
  gpointer              destroy_data;
} GskBufferFragment;

This structure should rarely be accessed directly, instead you should use the GskBuffer methods. They are exposed for optimization and debugging convenience.

A single contiguous chunk of memory in the buffer. Each GskBufferFragment is managed by a single buffer, but internally fragments are sometimes transferred whole between buffers.

A foreign fragment is one which created with gsk_buffer_append_foreign(). It means that gsk will use the destroy method rather than the normal buffer pool, where data and the GskBufferFragment are allocated continguously. The headers of foreign fragments are pooled in a separate pool.

gsk_buffer_construct ()

void        gsk_buffer_construct            (GskBuffer *buffer);

Construct an empty buffer out of raw memory. (This is equivalent to filling the buffer with 0s)

gsk_buffer_read ()

guint       gsk_buffer_read                 (GskBuffer *buffer,
                                             gpointer data,
                                             guint max_length);

Removes up to max_length data from the beginning of the buffer, and writes it to data. The number of bytes actually read is returned.

gsk_buffer_peek ()

guint       gsk_buffer_peek                 (const GskBuffer *buffer,
                                             gpointer data,
                                             guint max_length);

Copies up to max_length data from the beginning of the buffer, and writes it to data. The number of bytes actually copied is returned.

This function is just like gsk_buffer_read() except that the data is not removed from the buffer.

gsk_buffer_discard ()

int         gsk_buffer_discard              (GskBuffer *buffer,
                                             guint max_discard);

Removes up to max_discard data from the beginning of the buffer, and returns the number of bytes actually discarded.

gsk_buffer_read_line ()

char*       gsk_buffer_read_line            (GskBuffer *buffer);

Parse a newline (\n) terminated line from buffer and return it as a newly allocated string. The newline is changed to a NUL character.

If the buffer does not contain a newline, then NULL is returned.

gsk_buffer_parse_string0 ()

char*       gsk_buffer_parse_string0        (GskBuffer *buffer);

Parse a NUL-terminated line from buffer and return it as a newly allocated string.

If the buffer does not contain a newline, then NULL is returned.

gsk_buffer_peek_char ()

int         gsk_buffer_peek_char            (const GskBuffer *buffer);

Get the first byte in the buffer as a positive or 0 number. If the buffer is empty, -1 is returned. The buffer is unchanged.

gsk_buffer_read_char ()

int         gsk_buffer_read_char            (GskBuffer *buffer);

Get the first byte in the buffer as a positive or 0 number, and remove the character from the buffer. If the buffer is empty, -1 is returned.

gsk_buffer_append ()

void        gsk_buffer_append               (GskBuffer *buffer,
                                             gconstpointer data,
                                             guint length);

Append data into the buffer.

gsk_buffer_append_string ()

void        gsk_buffer_append_string        (GskBuffer *buffer,
                                             const char *string);

Append a string to the buffer.

gsk_buffer_append_char ()

void        gsk_buffer_append_char          (GskBuffer *buffer,
                                             char character);

Append a byte to a buffer.

gsk_buffer_append_string0 ()

void        gsk_buffer_append_string0       (GskBuffer *buffer,
                                             const char *string);

Append a NUL-terminated string to the buffer. The NUL is appended.

gsk_buffer_append_foreign ()

void        gsk_buffer_append_foreign       (GskBuffer *buffer,
                                             gconstpointer data,
                                             int length,
                                             GDestroyNotify destroy,
                                             gpointer destroy_data);

This function allows data to be placed in a buffer without copying. It is the callers' responsibility to ensure that data will remain valid until the destroy method is called. destroy may be omitted if data is permanent, for example, if appended a static string into a buffer.

gsk_buffer_printf ()

void        gsk_buffer_printf               (GskBuffer *buffer,
                                             const char *format,
                                             ...);

Append printf-style content to a buffer.

gsk_buffer_vprintf ()

void        gsk_buffer_vprintf              (GskBuffer *buffer,
                                             const char *format,
                                             va_list args);

Append printf-style content to a buffer, given a va_list.

gsk_buffer_drain ()

guint       gsk_buffer_drain                (GskBuffer *dst,
                                             GskBuffer *src);

Transfer all data from src to dst, leaving src empty.

gsk_buffer_transfer ()

guint       gsk_buffer_transfer             (GskBuffer *dst,
                                             GskBuffer *src,
                                             guint max_transfer);

Transfer data out of src and into dst. Data is removed from src. The number of bytes transferred is returned.

gsk_buffer_writev ()

int         gsk_buffer_writev               (GskBuffer *read_from,
                                             int fd);

Writes as much data as possible to the given file-descriptor using the writev(2) function to deal with multiple fragments efficiently, where available.

gsk_buffer_read_in_fd ()

int         gsk_buffer_read_in_fd           (GskBuffer *write_to,
                                             int read_from);

Append data into the buffer directly from the given file-descriptor.

gsk_buffer_index_of ()

int         gsk_buffer_index_of             (GskBuffer *buffer,
                                             char char_to_find);

Scans for the first instance of the given character.

gsk_buffer_polystr_index_of ()

int         gsk_buffer_polystr_index_of     (GskBuffer *buffer,
                                             char **strings);

Scans for the first instance of any of the strings in the buffer.

gsk_buffer_destruct ()

void        gsk_buffer_destruct             (GskBuffer *to_destroy);

Remove all fragments from a buffer, leaving it empty. The buffer is guaranteed to not to be consuming any resources, but it also is allowed to start using it again.

gsk_buffer_cleanup_recycling_bin ()

void        gsk_buffer_cleanup_recycling_bin
                                            ();

Free unused buffer fragments. (Normally some are kept around to reduce strain on the global allocator.)

GskBufferIterator

typedef struct {
  GskBufferFragment *fragment;
  guint in_cur;
  guint cur_length;
  const guint8 *cur_data;
  guint offset;
} GskBufferIterator;

An iterator which can be used to walk through a buffer.

You MUST not modify the buffer that you are editing in any way.

TODO: exceptions to the above may be feasible, but we have to see what the demands are...

gsk_buffer_iterator_offset()

#define gsk_buffer_iterator_offset(iterator)	((iterator)->offset)

Get the offset in bytes into GskBuffer that we are into the whole buffer.

gsk_buffer_iterator_construct ()

void        gsk_buffer_iterator_construct   (GskBufferIterator *iterator,
                                             GskBuffer *to_iterate);

Initialize a new GskBufferIterator.

gsk_buffer_iterator_peek ()

guint       gsk_buffer_iterator_peek        (GskBufferIterator *iterator,
                                             gpointer out,
                                             guint max_length);

Peek data from the current position of an iterator. The iterator's position is not changed.

gsk_buffer_iterator_read ()

guint       gsk_buffer_iterator_read        (GskBufferIterator *iterator,
                                             gpointer out,
                                             guint max_length);

Peek data from the current position of an iterator. The iterator's position is updated to be at the end of the data read.

gsk_buffer_iterator_skip ()

guint       gsk_buffer_iterator_skip        (GskBufferIterator *iterator,
                                             guint max_length);

Advance an iterator forward in the buffer, returning the number of bytes skipped.

gsk_buffer_iterator_find_char ()

gboolean    gsk_buffer_iterator_find_char   (GskBufferIterator *iterator,
                                             char c);

If it exists, skip forward to the next instance of c and return TRUE. Otherwise, do nothing and return FALSE.

GSK_BUFFER_STATIC_INIT

#define GSK_BUFFER_STATIC_INIT		{ 0, NULL, NULL }

Macro which can be used to initialize an empty buffer. One can write: GskBuffer buf = GSK_BUFFER_STATIC_INIT;