## memory-based streams

memory-based streams — streams whose data is "memory", inside pointer-accessed data.

## Synopsis

    GskStream *         gsk_memory_buffer_source_new        (GskBuffer *buffer);
    GskStream *         gsk_memory_slab_source_new          (gconstpointer data,
                                                             guint data_len,
                                                             GDestroyNotify destroy,
                                                             gpointer destroy_data);
    GskStream *         gsk_memory_source_new_printf        (const char *format,
                                                             ...);
    GskStream *         gsk_memory_source_new_vprintf       (const char *format,
                                                             va_list args);
    GskStream *         gsk_memory_source_static_string     (const char *str);
    GskStream *         gsk_memory_source_static_string_n   (const char *str,
                                                             guint length);
    void                (*GskMemoryBufferCallback)          (GskBuffer *buffer,
                                                             gpointer data);
    GskStream *         gsk_memory_buffer_sink_new          (GskMemoryBufferCallback callback,
                                                             gpointer data,
                                                             GDestroyNotify destroy);

## Description

These are sources and sinks which use memory to store output and input. Because of system-architectures, memory never blocks.

## Details

### gsk_memory_buffer_source_new ()

    GskStream *         gsk_memory_buffer_source_new        (GskBuffer *buffer);

Create a read-only GskStream that will drain the data from `buffer` and may it available for reading on the stream.

`buffer` : | buffer whose contents should be readable from the new stream. It will be immediately (before the function returns) drained of all data, and will not be used any more by the stream.
Returns : | the new read-only stream.

### gsk_memory_slab_source_new ()

    GskStream *         gsk_memory_slab_source_new          (gconstpointer data,
                                                             guint data_len,
                                                             GDestroyNotify destroy,
                                                             gpointer destroy_data);

Create a read-only stream which has certain, given data available for reading.

For efficiency, this code does not copy the data, but rather calls a user-supplied destroy method when we are done.

One possibility if you need the data copied, is to call g_memdup on data, then pass in g_free for `destroy` and the copy of the data as `destroy_data`.

`data` : | binary data which will be readable from the returned stream.
`data_len` : | length of the returned stream.
`destroy` : | method called by the stream once `data` is completely used (ie, the user has read all the data or shutdown the stream)
`destroy_data` : | data passed to `destroy`.
Returns : | the new read-only stream.

### gsk_memory_source_new_printf ()

    GskStream *         gsk_memory_source_new_printf        (const char *format,
                                                             ...);

Create a read-only stream which has the result of doing the sprintf available for reading.

`format` : | a printf(3) format string.
`...` : | arguments, as used by printf(3).
Returns : | the new read-only stream.

### gsk_memory_source_new_vprintf ()

    GskStream *         gsk_memory_source_new_vprintf       (const char *format,
                                                             va_list args);

Create a read-only stream which has the result of doing the vsprintf available for reading. This is useful for chaining from other printf-like functions.

`format` : | a printf(3) format string.
`args` : | arguments, as used by vprintf(3).
Returns : | the new read-only stream.

### gsk_memory_source_static_string ()

    GskStream *         gsk_memory_source_static_string     (const char *str);

Create a read-only stream which has `str` available for reading.

Note that the NUL will not be read from the stream.

`str` : | the static string which is the content of the stream.
Returns : | the new read-only stream.

### gsk_memory_source_static_string_n ()

    GskStream *         gsk_memory_source_static_string_n   (const char *str,
                                                             guint length);

Create a read-only stream which has `length` bytes starting at `str` available for reading.

`str` : | the static string or binary-data which is the content of the stream.
`length` : | length of the stream in bytes.
Returns : | the new read-only stream.

### GskMemoryBufferCallback ()

    void                (*GskMemoryBufferCallback)          (GskBuffer *buffer,
                                                             gpointer data);

Function to call when a memory-buffer-sink (as created with `gsk_memory_buffer_sink_new()`) is finished. This takes the buffer, which is full of data, and the data argument to `gsk_memory_buffer_sink_new()` as well.

The buffer will be destroyed immediately after this call, so it does not matter if you read or peek from this buffer.

`buffer` : | the buffer which has been filled.
`data` : | user-data to pass through to this function.

### gsk_memory_buffer_sink_new ()

    GskStream *         gsk_memory_buffer_sink_new          (GskMemoryBufferCallback callback,
                                                             gpointer data,
                                                             GDestroyNotify destroy);

Create a sink for binary data which just fills a binary buffer. When the stream is done, the `callback` will be run with the full buffer.

`callback` : | function to call when the buffer has been filled.
`data` : | user-data to pass to the `callback`.
`destroy` : | function to call when we are done with the data.
Returns : | the writable stream whose destination is a GskBuffer.