VipsSbuf: VIPS Reference Manual

## VipsSbuf VipsSbuf — buffered read from a source |

## Stability Level

Stable, unless otherwise indicated

## Functions

VipsSbuf * | vips_sbuf_new_from_source ()
void | vips_sbuf_unbuffer ()
int | vips_sbuf_getc ()
#define | VIPS_SBUF_GETC()
void | vips_sbuf_ungetc ()
#define | VIPS_SBUF_UNGETC()
int | vips_sbuf_require ()
#define | VIPS_SBUF_REQUIRE()
#define | VIPS_SBUF_PEEK()
#define | VIPS_SBUF_FETCH()
const char * | vips_sbuf_get_line ()
char * | vips_sbuf_get_line_copy ()
const char * | vips_sbuf_get_non_whitespace ()
int | vips_sbuf_skip_whitespace ()

## Properties

VipsSource * | input | Read / Write

## Types and Values

#define | VIPS_SBUF_BUFFER_SIZE

## Object Hierarchy

        GObject
        ╰── VipsObject
            ╰── VipsSbuf

## Includes

    #include <vips/vips.h>

## Description

VipsSbuf wraps up a VipsSource and provides a set of calls for text-oriented buffered reading. You can fetch lines of text, skip whitespace, and so on.

It is useful for implementing things like CSV readers, for example.

## Functions

### vips_sbuf_new_from_source ()

    VipsSbuf *
    vips_sbuf_new_from_source (VipsSource *source);

Create a VipsSbuf wrapping a source.

#### Parameters

source | source to operate on |

#### Returns

a new VipsSbuf

### vips_sbuf_unbuffer ()

    void
    vips_sbuf_unbuffer (VipsSbuf *sbuf);

Discard the input buffer and reset the read point. You must call this before using read or seek on the underlying VipsSource class.

#### Parameters

sbuf | source to operate on |

### vips_sbuf_getc ()

    int
    vips_sbuf_getc (VipsSbuf *sbuf);

Fetch the next character from the source.

If you can, use the macro `VIPS_SBUF_GETC()` instead for speed.

#### Parameters

sbuf | source to operate on |

#### Returns

the next char from `sbuf` , -1 on read error or EOF.

### VIPS_SBUF_GETC()

    #define             VIPS_SBUF_GETC( S )

Fetch the next character from the source.

#### Parameters

sbuf | source to operate on |

#### Returns

the next char from `sbuf` , -1 on read error or EOF.

### vips_sbuf_ungetc ()

    void
    vips_sbuf_ungetc (VipsSbuf *sbuf);

The opposite of `vips_sbuf_getc()`: undo the previous getc.

unget more than one character is undefined. Unget at the start of the file does nothing.

If you can, use the macro `VIPS_SBUF_UNGETC()` instead for speed.

#### Parameters

sbuf | source to operate on |

### VIPS_SBUF_UNGETC()

    #define             VIPS_SBUF_UNGETC( S )

The opposite of `vips_sbuf_getc()`: undo the previous getc.

unget more than one character is undefined. Unget at the start of the file does nothing.

#### Parameters

sbuf | source to operate on |

### vips_sbuf_require ()

    int
    vips_sbuf_require (VipsSbuf *sbuf,
                       int require);

Make sure there are at least `require` bytes of readahead available.

#### Parameters

sbuf | source to operate on |
require | make sure we have at least this many chars available |

#### Returns

0 on success, -1 on error or EOF.

### VIPS_SBUF_REQUIRE()

    #define             VIPS_SBUF_REQUIRE( S, R )

Make sure at least `require` characters are available for `VIPS_SBUF_PEEK()` and `VIPS_SBUF_FETCH()`.

#### Parameters

sbuf | source to operate on |
require | need this many characters |

#### Returns

0 on success, -1 on read error or EOF.

### VIPS_SBUF_PEEK()

    #define VIPS_SBUF_PEEK( S ) ((S)->input_buffer + (S)->read_point)

After a successful `VIPS_SBUF_REQUIRE()`, you can index this to get require characters of input.

#### Parameters

sbuf | source to operate on |

#### Returns

a pointer to the next requre characters of input.

### VIPS_SBUF_FETCH()

    #define VIPS_SBUF_FETCH( S ) ((S)->input_buffer[(S)->read_point++])

After a successful `VIPS_SBUF_REQUIRE()`, you can use this require times to fetch characters of input.

#### Parameters

sbuf | source to operate on |

#### Returns

the next input character.

### vips_sbuf_get_line ()

    const char *
    vips_sbuf_get_line (VipsSbuf *sbuf);

Fetch the next line of text from `sbuf` and return it. The end of line character (or characters, for DOS files) are removed, and the string is terminated with a null (`\0` character).

Returns NULL on end of file or read error.

If the line is longer than some arbitrary (but large) limit, it is truncated. If you need to be able to read very long lines, use the slower `vips_sbuf_get_line_copy()`.

The return value is owned by `sbuf` and must not be freed. It is valid until the next get call to `sbuf` .

#### Parameters

sbuf | source to operate on |

#### Returns

the next line of text, or NULL on EOF or read error.

### vips_sbuf_get_line_copy ()

    char *
    vips_sbuf_get_line_copy (VipsSbuf *sbuf);

Fetch the next line of text from `sbuf` and return it. The end of line character (or characters, for DOS files) are removed, and the string is terminated with a null (`\0` character).

The return result must be freed with `g_free()`.

This is slower than `vips_sbuf_get_line()`, but can work with lines of any length.

#### Parameters

sbuf | source to operate on |

#### Returns

the next line of text, or NULL on EOF or read error.

### vips_sbuf_get_non_whitespace ()

    const char *
    vips_sbuf_get_non_whitespace (VipsSbuf *sbuf);

Fetch the next chunk of non-whitespace text from the source, and null-terminate it.

After this, the next getc will be the first char of the next block of whitespace (or EOF).

If the first getc is whitespace, stop instantly and return the empty string.

If the item is longer than some arbitrary (but large) limit, it is truncated.

The return value is owned by `sbuf` and must not be freed. It is valid until the next get call to `sbuf` .

#### Parameters

sbuf | source to operate on |

#### Returns

the next block of non-whitespace, or NULL on EOF or read error.

### vips_sbuf_skip_whitespace ()

    int
    vips_sbuf_skip_whitespace (VipsSbuf *sbuf);

After this, the next getc will be the first char of the next block of non-whitespace (or EOF).

Also skip comments, ie. from any '#' character to the end of the line.

#### Parameters

sbuf | source to operate on |

#### Returns

0 on success, or -1 on EOF.

## Types and Values

### VIPS_SBUF_BUFFER_SIZE

    #define VIPS_SBUF_BUFFER_SIZE (4096)

## Property Details

### The `“input”` property

      “input”                    VipsSource *

Source to load from.

Owner: VipsSbuf

Flags: Read / Write

## See Also

foreign