strb.h File Reference

#include <inttypes.h>
#include <stdarg.h>
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

Include dependency graph for strb.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	strbstate_t
	String buffer state. More...

Macros
#define	STRB_EXT_STATE   1
#define	STRB_UNPUTC   1
#define	STRB_RESTORE   1
#define	STRB_REUSE_CONST   1
#define	STRB_SIZE_HINT(X)   static restrict X
#define	STRB_MAX   SIZE_MAX
#define	PRIstrbsize   PRIu16
#define	STRB_MAX_SIZE   UINT16_MAX
#define	STRB_DFL_SIZE   (256)
#define	STRB_MAX_INTERNAL_SIZE   (256)
#define	STRB_GROW_FACTOR   (2)
#define	_Optional
#define	strb_wrote(sb)   strb_restore(sb)

Typedefs
typedef uint16_t	strbsize_t
typedef struct strb_t	strb_t
	String buffer object.

Enumerations
enum	{ strb_insert , strb_overwrite }
	Editing mode. More...

Functions
strb_t *	strb_use (strbstate_t *restrict sbs, size_t size, char buf[STRB_SIZE_HINT(size)])
	Create a string buffer object for managing an external character array.
_Optional strb_t *	strb_reuse (strbstate_t *restrict sbs, size_t size, char buf[STRB_SIZE_HINT(size)])
	Create a string buffer object by reusing an external character array.
_Optional const strb_t *	strb_reuse_const (strbstate_t *restrict sbs, const char buf[STRB_SIZE_HINT(1)])
	Create a string buffer object that wraps a constant string.
_Optional strb_t *	strb_alloc (size_t n)
	Create a string buffer object with internal storage.
_Optional strb_t *	strb_dup (const char *str)
	Create a string buffer object with internal storage by duplicating a string.
_Optional strb_t *	strb_ndup (const char *str, size_t n)
	Create a string buffer object with internal storage by duplicating a sequence of characters.
_Optional strb_t *	strb_aprintf (const char *restrict format,...)
	Create a string buffer object with internal storage by parsing a format string.
_Optional strb_t *	strb_vaprintf (const char *restrict format, va_list args)
	Create a string buffer object with internal storage by parsing a format string.
void	strb_free (_Optional strb_t *sb)
	Destroy a string buffer object.
char *	strb_ptr (strb_t *sb)
	Get a pointer to the character array underlying a string buffer.
const char *	strb_cptr (strb_t const *sb)
size_t	strb_len (strb_t const *sb)
	Get the number of characters stored in a string buffer.
int	strb_setmode (strb_t *sb, int mode)
	Set the editing mode of a string buffer.
int	strb_getmode (const strb_t *sb)
	Get the editing mode of a string buffer.
int	strb_seek (strb_t *sb, size_t pos)
	Set the editing position of a string buffer.
size_t	strb_tell (strb_t const *sb)
	Get the editing position of a string buffer.
int	strb_putc (strb_t *sb, int c)
	Put a character into a string buffer.
int	strb_nputc (strb_t *sb, int c, size_t n)
	Put a character into a string buffer multiple times.
int	strb_unputc (strb_t *sb)
	Undo the last put character operation.
int	strb_puts (strb_t *restrict sb, const char *restrict str)
	Put a string into a string buffer.
int	strb_nputs (strb_t *restrict sb, const char *restrict str, size_t n)
	Put a sequence of characters into a string buffer.
int	strb_vputf (strb_t *restrict sb, const char *restrict format, va_list args)
	Put a generated string into a string buffer.
int	strb_putf (strb_t *restrict sb, const char *restrict format,...)
	Put a generated string into a string buffer.
_Optional char *	strb_write (strb_t *sb, size_t n)
	Prepare to write characters directly into a string buffer.
void	strb_split (strb_t *sb)
	Split a string at the current position.
void	strb_restore (strb_t *sb)
	Restore a character that may have been overwritten by a preceding write.
void	strb_delto (strb_t *sb, size_t pos)
	Delete characters to a specified position in a string buffer.
int	strb_cpy (strb_t *restrict sb, const char *restrict str)
	Copy a string into a string buffer.
int	strb_ncpy (strb_t *restrict sb, const char *restrict str, size_t n)
	Copy a sequence of characters into a string buffer.
int	strb_vprintf (strb_t *restrict sb, const char *restrict format, va_list args)
	Print a generated string into a string buffer.
int	strb_printf (strb_t *restrict sb, const char *restrict format,...)
	Print a generated string into a string buffer.
bool	strb_error (strb_t const *sb)
	Get the error indicator of a string buffer.
void	strb_clearerr (strb_t *sb)
	Clear the error indicator of a string buffer.

Detailed Description

Author

Christopher Bazley (chris.nosp@m..baz.nosp@m.ley@a.nosp@m.rm.c.nosp@m.om)

Version

0.4

Date

2026-02-18

Copyright

Copyright (c) 2024

Definition in file strb.h.

Macro Definition Documentation

_Optional

#define _Optional

Definition at line 194 of file strb.h.

PRIstrbsize

#define PRIstrbsize   PRIu16

Macro to be used to print values of type strbsize_t

Definition at line 120 of file strb.h.

STRB_DFL_SIZE

#define STRB_DFL_SIZE   (256)

Buffer size, in characters, substituted by strb_alloc when the requested size is too small.

Definition at line 131 of file strb.h.

STRB_EXT_STATE

#define STRB_EXT_STATE   1

Whether the interface has user-allocated string buffer state objects.

Definition at line 26 of file strb.h.

STRB_GROW_FACTOR

#define STRB_GROW_FACTOR   (2)

Factor by which to grow the string buffer size when space is exhausted.

Definition at line 142 of file strb.h.

STRB_MAX

#define STRB_MAX   SIZE_MAX

Maximum number of allocated string buffer objects.

Definition at line 109 of file strb.h.

STRB_MAX_INTERNAL_SIZE

#define STRB_MAX_INTERNAL_SIZE   (256)

Maximum buffer size, in characters, allocated as part of a strb_t object rather than separately.

Definition at line 137 of file strb.h.

STRB_MAX_SIZE

#define STRB_MAX_SIZE   UINT16_MAX

Maximum string size, in characters (including null terminator).

Definition at line 125 of file strb.h.

STRB_RESTORE

#define STRB_RESTORE   1

Whether the interface provides the strb_restore function.

Definition at line 40 of file strb.h.

STRB_REUSE_CONST

#define STRB_REUSE_CONST   1

Whether the interface provides the strb_reuse_const function.

Definition at line 47 of file strb.h.

STRB_SIZE_HINT

#define STRB_SIZE_HINT

(

X

)

static restrict X

Macro used to suppress variably modified types in parameter lists.

Definition at line 57 of file strb.h.

STRB_UNPUTC

#define STRB_UNPUTC   1

Whether the interface provides the strb_unputc function.

Definition at line 33 of file strb.h.

strb_wrote

#define strb_wrote

(

sb

)

strb_restore(sb)

Deprecated:

Original name of strb_restore.

Definition at line 1054 of file strb.h.

Typedef Documentation

strb_t

typedef struct strb_t strb_t

String buffer object.

An object type to be used in place of strbstate_t for all operations on a string buffer. It need not be a complete type. Consequently, it may be impossible to wrongly declare an object of type strb_t and its internal state should only be accessed by the provided functions.

Definition at line 205 of file strb.h.

strbsize_t

typedef uint16_t strbsize_t

Type capable of representing all supported character positions and buffer sizes.

Definition at line 115 of file strb.h.

Enumeration Type Documentation

anonymous enum

anonymous enum

Editing mode.

Enumerator
strb_insert	Insertion moves characters upward and lengthens the string. Deletion in insertion mode moves characters downward and shortens the string.
strb_overwrite	Overwrite characters at the current position and lengthen the string only as necessary (at the end). Deletion in overwrite mode merely repositions the next operation.

Definition at line 657 of file strb.h.

Function Documentation

strb_alloc()

_Optional strb_t * strb_alloc

(

size_t

n

)

Create a string buffer object with internal storage.

Allocates storage for a string buffer object, initialises it, and returns its address. If storage allocation fails, a null pointer is returned.

The initial string length is 0. This function does not necessarily allocate storage for a string immediately, providing that all other functions operate as if it had been allocated. Subsequent operations on the string buffer may allocate or free extra storage, if supported by the implementation.

Parameters

n	A hint about how much storage to allocate for an internal buffer (where 0 means default size). Measured in characters not bytes, excluding the terminating null character.

Returns

Address of the created string buffer object, or a null pointer on failure.

Postcondition

The user is responsible for calling strb_free to free the string buffer object.

If successful, strb_tell and strb_len return 0.

If successful, a call to strb_restore will have no effect until strb_write has been called.

If successful, a call to strb_error will return false until an error occurs.

Definition at line 269 of file strb.c.

strb_aprintf()

_Optional strb_t * strb_aprintf	(	const char *restrict	format,
			...
	)

Create a string buffer object with internal storage by parsing a format string.

Allocates storage for a string buffer object, initialises it, and returns its address. If storage allocation fails, a null pointer is returned.

The format parameter specifies how to convert subsequent arguments to generate a string, which forms the initial content of the buffer. Subsequent operations on the buffer may automatically allocate or free extra storage, if supported by the implementation.

Parameters

[in]	format	Specifies how to convert subsequent arguments to generate a string.
	...	Arguments to be substituted into the generated string.

Returns

Address of the created string buffer object, or a null pointer on failure.

Postcondition

The user is responsible for calling strb_free to free the string buffer object.

If successful, strb_tell and strb_len return the number of characters generated.

If successful, the last character generated (if any) can be removed by strb_unputc.

If successful, a call to strb_restore will have no effect until strb_write has been called.

If successful, a call to strb_error will return false until an error occurs.

Definition at line 373 of file strb.c.

strb_clearerr()

void strb_clearerr

(

strb_t *

sb

)

Clear the error indicator of a string buffer.

Parameters

[in,out]

sb

String buffer.

Precondition

The given sb address was returned by strb_use, strb_reuse, strb_alloc, strb_dup, strb_ndup, strb_aprintf or strb_vaprintf.

Postcondition

A call to strb_error will return false until an error occurs.

Definition at line 830 of file strb.c.

strb_cptr()

const char * strb_cptr

(

strb_t const *

sb

)

See also

strb_ptr

Definition at line 409 of file strb.c.

strb_cpy()

int strb_cpy	(	strb_t *restrict	sb,
		const char *restrict	str
	)

Copy a string into a string buffer.

Replaces the string in a buffer by copying a string.

Parameters

[in,out]	sb	String buffer.
[in]	str	A string to be copied as the new content of the buffer.

Returns

Zero if successful, otherwise EOF.

Precondition

The given sb address was returned by strb_use, strb_reuse, strb_alloc, strb_dup, strb_ndup, strb_aprintf or strb_vaprintf.

Postcondition

If successful, strb_tell and strb_len return the number of characters copied.

If successful, the last character copied (if any) can be removed by strb_unputc.

If successful, a call to strb_restore will have no effect until strb_write has been called.

On failure, a call to strb_error will return true until strb_clearerr has been called.

Definition at line 798 of file strb.c.

strb_delto()

void strb_delto	(	strb_t *	sb,
		size_t	pos
	)

Delete characters to a specified position in a string buffer.

Deletes characters between the current position and a position specified by the caller. If the mode is strb_insert, then the character at the higher of the two positions is moved to the lower position, and any following characters are moved the same distance; otherwise, no characters are moved. Afterwards, the value of the position indicator is the lower of the two positions. This function may substitute a smaller buffer at the implementer's discretion.

Passing a position greater than the string length is allowed: SIZE_MAX or (size_t)-1 can be used as a shorthand to delete all characters between the current position and the end of the string.

Parameters

[in,out]	sb	String buffer.
	pos	New position, in characters.

Precondition

The given sb address was returned by strb_use, strb_reuse, strb_alloc, strb_dup, strb_ndup, strb_aprintf or strb_vaprintf.

Postcondition

The position indicator is at the lower of pos and the previous position and the string length has decreased by not more than the difference between the two.

A call to strb_restore will have no effect until strb_write has been called.

Definition at line 746 of file strb.c.

strb_dup()

_Optional strb_t * strb_dup

(

const char *

str

)

Create a string buffer object with internal storage by duplicating a string.

Allocates storage for a string buffer object, initialises it, and returns its address. If storage allocation fails, a null pointer is returned.

Copies the given string into internal storage, including its null terminator. Subsequent operations on the string buffer may automatically allocate or free extra storage, if supported by the implementation.

Parameters

[in]

str

A string to be copied as the initial content of the buffer.

Returns

Address of the created string buffer object, or a null pointer on failure.

Postcondition

The user is responsible for calling strb_free to free the string buffer object.

If successful, strb_tell and strb_len return the number of characters copied.

If successful, the last character copied (if any) can be removed by strb_unputc.

If successful, a call to strb_restore will have no effect until strb_write has been called.

If successful, a call to strb_error will return false until an error occurs.

Definition at line 368 of file strb.c.

strb_error()

bool strb_error

(

strb_t const *

sb

)

Get the error indicator of a string buffer.

Additional storage for the underlying character array may be allocated automatically as the string grows, for example because of calls to strb_puts. When using a character array passed to strb_use or strb_reuse, or an internal buffer of fixed size, any attempt to allocate more storage fails. If any attempt at storage allocation fails, the state of the buffer, mode, and position indicator are as if the failed operation had never been attempted. This allows use in interactive software running on machines with limited physical memory and no swap file.

An error indicator is stored to allow deferred error handling. Its value can be read at any time by calling strb_error. An error can only be cleared explicitly (by calling strb_clearerr). The error indicator is set as a side-effect of any function that returns an error value, including because of attempts to reposition to an unsupported index or select an unsupported editing mode. Consequently, it is a reliable indication of whether the current string is valid.

Parameters

[in]

sb

String buffer.

Returns

True if an error occurred since the most recent call to strb_clearerr, otherwise false.

Precondition

The given sb address was returned by strb_use, strb_reuse, strb_alloc, strb_dup, strb_ndup, strb_aprintf or strb_vaprintf.

Definition at line 824 of file strb.c.

strb_free()

void strb_free

(

_Optional strb_t *

sb

)

Destroy a string buffer object.

The associated buffer is also automatically freed, except in the case where its address was passed as a parameter to strb_use or strb_reuse. This must be enforced because storage allocation is abstracted. To pass an internally allocated string to code that needs to take ownership of it, it must first be copied (e.g., using strdup).

May be called with a null pointer, in which case this function has no effect.

Parameters

[in]

sb

String buffer to destroy, or a null pointer.

Precondition

The given sb address is null or was returned by strb_use, strb_reuse, strb_alloc, strb_dup, strb_ndup, strb_aprintf or strb_vaprintf.

Postcondition

sb is invalid for use with any function.

Definition at line 384 of file strb.c.

strb_getmode()

int strb_getmode

(

const strb_t *

sb

)

Get the editing mode of a string buffer.

Parameters

[in]

sb

String buffer.

Returns

Current editing mode.

Precondition

The given sb address was returned by strb_use, strb_reuse, strb_alloc, strb_dup, strb_ndup, strb_aprintf or strb_vaprintf.

Postcondition

The returned value may be passed to strb_setmode.

Definition at line 443 of file strb.c.

strb_len()

size_t strb_len

(

strb_t const *

sb

)

Get the number of characters stored in a string buffer.

A null character may appear anywhere in string buffer, since it is easy to insert one by calling strb_putf(sb, "%c", 0). It would be hard to prevent such misuse. Consequently, strb_len(sb) and strlen(strb_ptr(sb)) can return different results. The returned length is never less than, but may be greater than, the true string length.

Parameters

[in]

sb

String buffer.

Returns

Number of characters stored in the string buffer.

Precondition

The given sb address was returned by strb_use, strb_reuse, strb_alloc, strb_dup, strb_ndup, strb_aprintf or strb_vaprintf.

Definition at line 415 of file strb.c.

strb_ncpy()

int strb_ncpy	(	strb_t *restrict	sb,
		const char *restrict	str,
		size_t	n
	)

Copy a sequence of characters into a string buffer.

Replaces the string in a buffer by copying up to n characters from the array designated by str, then appends a null terminator. A null character and any characters following it are not copied.

Parameters

[in,out]	sb	String buffer.
[in]	str	An array of characters to be copied as the new content of the buffer.
	n	Maximum number of characters to copy from str.

Returns

Zero if successful, otherwise EOF.

Precondition

The given sb address was returned by strb_use, strb_reuse, strb_alloc, strb_dup, strb_ndup, strb_aprintf or strb_vaprintf.

Postcondition

If successful, strb_tell and strb_len return the number of characters copied.

If successful, the last character copied (if any) can be removed by strb_unputc.

If successful, a call to strb_restore will have no effect until strb_write has been called.

On failure, a call to strb_error will return true until strb_clearerr has been called.

Definition at line 792 of file strb.c.

strb_ndup()

_Optional strb_t * strb_ndup	(	const char *	str,
		size_t	n
	)

Create a string buffer object with internal storage by duplicating a sequence of characters.

Allocates storage for a string buffer object, initialises it, and returns its address. If storage allocation fails, a null pointer is returned.

Copies up to n characters from the array designated by str into internal storage, then appends a null terminator. A null character and any characters following it are not copied. Subsequent operations on the string buffer may automatically allocate or free extra storage, if supported by the implementation.

Parameters

[in]	str	An array of characters to be copied as the initial content of the buffer.
	n	Maximum number of characters to copy from str.

Returns

Address of the created string buffer object, or a null pointer on failure.

Postcondition

The user is responsible for calling strb_free to free the string buffer object.

If successful, strb_tell and strb_len return the number of characters copied.

If successful, the last character copied (if any) can be removed by strb_unputc.

If successful, a call to strb_restore will have no effect until strb_write has been called.

If successful, a call to strb_error will return false until an error occurs.

Definition at line 315 of file strb.c.

strb_nputc()

int strb_nputc	(	strb_t *	sb,
		int	c,
		size_t	n
	)

Put a character into a string buffer multiple times.

Equivalent to calling strb_putc n times with the given value of c.

Parameters

[in,out]	sb	String buffer.
	c	Character to put.
	n	The number of times to copy the specified character into the buffer.

Returns

If successful, the character written, otherwise EOF.

Precondition

The given sb address was returned by strb_use, strb_reuse, strb_alloc, strb_dup, strb_ndup, strb_aprintf or strb_vaprintf.

Postcondition

If successful, the position indicator has advanced by n characters and the string length has increased by not more than n (depending on editing position and mode).

If successful, the last character written can be removed by strb_unputc.

If successful, a call to strb_restore will have no effect until strb_write has been called.

On failure, a call to strb_error will return true until strb_clearerr has been called.

Definition at line 489 of file strb.c.

strb_nputs()

int strb_nputs	(	strb_t *restrict	sb,
		const char *restrict	str,
		size_t	n
	)

Put a sequence of characters into a string buffer.

Copies up to n characters from the array designated by str into the buffer at the current position as if by calling strb_putc for each character. A null character and any characters following it are not copied.

Parameters

[in,out]	sb	String buffer.
[in]	str	A string to be copied into the buffer.
	n	Maximum number of characters to copy from str.

Returns

Zero if successful, otherwise EOF. (This is stricter than fputs, which returns only 'a nonnegative value' if successful.)

Precondition

The given sb address was returned by strb_use, strb_reuse, strb_alloc, strb_dup, strb_ndup, strb_aprintf or strb_vaprintf.

Postcondition

If successful, the position indicator has advanced by the number of characters copied and the string length has increased by not more than the number of characters copied.

If successful, the last character copied can be removed by strb_unputc.

If successful, a call to strb_restore will have no effect until strb_write has been called.

On failure, a call to strb_error will return true until strb_clearerr has been called.

Definition at line 532 of file strb.c.

strb_printf()

int strb_printf	(	strb_t *restrict	sb,
		const char *restrict	format,
			...
	)

Print a generated string into a string buffer.

Replaces the string in a buffer by generating characters under control of a format string.

Parameters

[in,out]	sb	String buffer.
[in]	format	Specifies how to convert subsequent arguments to generate a string.
	...	Arguments to be substituted into the generated string.

Returns

Zero if successful, otherwise EOF. (This differs from sprintf, which returns 'the number of characters written in the array, not counting the terminating null character, or a negative value'.)

Precondition

The given sb address was returned by strb_use, strb_reuse, strb_alloc, strb_dup, strb_ndup, strb_aprintf or strb_vaprintf.

Postcondition

If successful, strb_tell and strb_len return the number of characters generated.

If successful, the last character written can be removed by strb_unputc.

If successful, a call to strb_restore will have no effect until strb_write has been called.

On failure, a call to strb_error will return true until strb_clearerr has been called.

Definition at line 811 of file strb.c.

strb_ptr()

char * strb_ptr

(

strb_t *

sb

)

Get a pointer to the character array underlying a string buffer.

The returned pointer is guaranteed to be usable as a string (i.e. null terminated).

Parameters

[in]

sb

String buffer.

Returns

Address of the character stored at position 0 in the string buffer.

Precondition

The given sb address was returned by strb_use, strb_reuse, strb_alloc, strb_dup, strb_ndup, strb_aprintf or strb_vaprintf.

Postcondition

The returned pointer is valid until the next call to a strb_... function.

Definition at line 402 of file strb.c.

strb_putc()

int strb_putc	(	strb_t *	sb,
		int	c
	)

Put a character into a string buffer.

Copies one character into the buffer at the current position and increments the position indicator. If the mode is strb_insert, then characters at the current position are first moved upward to make space; otherwise, no characters are moved. Additional storage is allocated if permitted and necessary.

Parameters

[in,out]	sb	String buffer.
	c	Character to put.

Precondition

The given sb address was returned by strb_use, strb_reuse, strb_alloc, strb_dup, strb_ndup, strb_aprintf or strb_vaprintf.

Returns

If successful, the character written, otherwise EOF.

Postcondition

If successful, the position indicator was incremented and the string length may have increased by one (depending on editing position and mode).

If successful, the character written can be removed by strb_unputc.

If successful, a call to strb_restore will have no effect until strb_write has been called.

On failure, a call to strb_error will return true until strb_clearerr has been called.

Definition at line 484 of file strb.c.

strb_putf()

int strb_putf	(	strb_t *restrict	sb,
		const char *restrict	format,
			...
	)

Put a generated string into a string buffer.

Generates characters under control of a format string, which are written into the buffer at the current position as if by calling strb_putc for each character.

Parameters

[in,out]	sb	String buffer.
[in]	format	Specifies how to convert subsequent arguments to generate a string.
	...	Arguments to be substituted into the generated string.

Returns

Zero if successful, otherwise EOF. (This differs from fprintf, which returns 'the number of characters transmitted, or a negative value'.)

Precondition

The given sb address was returned by strb_use, strb_reuse, strb_alloc, strb_dup, strb_ndup, strb_aprintf or strb_vaprintf.

Postcondition

If successful, the position indicator has advanced by the number of characters generated and the string length has increased by not more than the number of characters generated.

If successful, the last character written can be removed by strb_unputc.

If successful, a call to strb_restore will have no effect until strb_write has been called.

On failure, a call to strb_error will return true until strb_clearerr has been called.

Definition at line 575 of file strb.c.

strb_puts()

int strb_puts	(	strb_t *restrict	sb,
		const char *restrict	str
	)

Put a string into a string buffer.

Copies a string into the buffer at the current position as if by calling strb_putc for each character except for the terminating null, which is not copied.

Parameters

[in,out]	sb	String buffer.
[in]	str	A string to be copied into the buffer.

Returns

Zero if successful, otherwise EOF. (This is stricter than fputs, which returns only 'a nonnegative value' if successful.)

Precondition

The given sb address was returned by strb_use, strb_reuse, strb_alloc, strb_dup, strb_ndup, strb_aprintf or strb_vaprintf.

Postcondition

If successful, the position indicator has advanced by the length of the given str and the string length has increased by not more than the length of the given str.

If successful, the last character copied can be removed by strb_unputc.

If successful, a call to strb_restore will have no effect until strb_write has been called.

On failure, a call to strb_error will return true until strb_clearerr has been called.

Definition at line 545 of file strb.c.

strb_restore()

void strb_restore

(

strb_t *

sb

)

Restore a character that may have been overwritten by a preceding write.

Restores the character previously at the current position before the most recent call to strb_write or strb_split.

This function exists primarily to make it efficient and simple to write strings (as opposed to unterminated character sequences) directly into a string buffer. Since strings are terminated by a null character, any character overwritten by this terminator must be restored to prevent unintentional truncation.

For example, prepending "fish" to "cat" should not result in the string "fish\0at". A call to strb_restore would restore the overwritten character 'c' in-place, regardless of the current editing mode.

This is likely to be more efficient than reserving space for one extra character when calling strb_write (to produce "fish\0cat") and then deleting the excess null character by calling strb_unputc (which might need to move characters).

Parameters

[in,out]

sb

String buffer.

Precondition

The given sb address was returned by strb_use, strb_reuse, strb_alloc, strb_dup, strb_ndup, strb_aprintf or strb_vaprintf.

Postcondition

If there was no intervening call that put, deleted, or restored characters, or that set the position, then the character at the current position is restored the value that it had prior to the most recent call to strb_write or strb_split.

Definition at line 733 of file strb.c.

strb_reuse()

_Optional strb_t * strb_reuse	(	strbstate_t *restrict	sbs,
		size_t	size,
		char	buf[STRB_SIZE_HINT(size)]
	)

Create a string buffer object by reusing an external character array.

Initialises a string buffer object and returns its address. The caller must pass a string buffer state object to be used to store information about the buffer.

The buf array should contain at least one null character within the first size characters, whose position is the initial string length. Any following characters are ignored. If no null character is found within the first size characters (or the maximum supported length, if less), a null pointer is returned.

The effects of strb_... functions on an external array are always immediately visible and the string therein is always null terminated. Operations on the string buffer can use the whole of the external array but never allocate any extra storage.

Parameters

[out]	sbs	String buffer state.
	size	Size of the array to be used instead of an internal buffer, measured in characters not bytes, including space for the terminating null character. Must not be 0.
[in,out]	buf	The array to be used instead of an internal buffer.

Returns

Address of the created string buffer object, or a null pointer on failure.

Postcondition

The user may call strb_free to free the string buffer object, but it is not required and has no effect.

The created string buffer object becomes invalid if the storage for sbs or buf is deallocated.

The created string buffer object becomes invalid if the sbs object is modified (other than as a side-effect of calling a strb_... function which is not strb_reuse or strb_use).

If successful, strb_tell and strb_len return the reused string length.

If successful, a call to strb_restore will have no effect until strb_write has been called.

If successful, the last character of the reused string (if any) can be removed by strb_unputc.

If successful, a call to strb_error will return false until an error occurs.

Definition at line 154 of file strb.c.

strb_reuse_const()

_Optional const strb_t * strb_reuse_const	(	strbstate_t *restrict	sbs,
		const char	buf[STRB_SIZE_HINT(1)]
	)

Create a string buffer object that wraps a constant string.

Initialises a string buffer object and returns its address. The caller must pass a string buffer state object to be used to store information about the buffer.

The buf array must contain at least one null character, whose position is the string length. Any following characters are ignored. If no null character is found within the maximum supported length, a null pointer is returned.

If successful, the created string buffer object is immutable (as indicated by its qualified type). Functions that require a mutable string buffer object have undefined behaviour when invoked with an object created by this function.

Parameters

[out]	sbs	String buffer state.
[in]	buf	The array to be used instead of an internal buffer.

Returns

Address of the created string buffer object, or a null pointer on failure.

Postcondition

The created string buffer object becomes invalid if the storage for sbs or buf is deallocated.

The created string buffer object becomes invalid if the sbs object is modified.

If successful, strb_tell and strb_len return the constant string's length.

If successful, strb_ptr returns the constant string's address.

If successful, a call to strb_error will return false.

Definition at line 179 of file strb.c.

strb_seek()

int strb_seek	(	strb_t *	sb,
		size_t	pos
	)

Set the editing position of a string buffer.

Instead of passing a position parameter to every function, an internal position indicator is stored in the string buffer object. The initial position is the end of the string. It is updated by operations on the string.

Repositioning can fail if the requested position is not supported by the library, in which case the current position is unchanged. Any value returned by strb_tell is accepted by strb_seek.

Passing a position greater than the string buffer length is allowed and does not change the length. If characters are later written beyond the end of the string, then the length will be updated. The initial value of any intervening characters will be 0.

Parameters

[in,out]	sb	String buffer.
	pos	New position, in characters.

Returns

Zero if successful, otherwise EOF.

Precondition

The given sb address was returned by strb_use, strb_reuse, strb_alloc, strb_dup, strb_ndup, strb_aprintf or strb_vaprintf.

Postcondition

Alters the behaviour of strb_putc, strb_unputc, strb_puts, strb_nputs, strb_vputf, strb_putf, strb_write and strb_delto.

A call to strb_unputc will fail until a character has been put into the buffer.

If successful, a call to strb_restore will have no effect until strb_write has been called.

On failure, a call to strb_error will return true until strb_clearerr has been called.

Definition at line 453 of file strb.c.

strb_setmode()

int strb_setmode	(	strb_t *	sb,
		int	mode
	)

Set the editing mode of a string buffer.

Instead of providing variants of every function to insert or overwrite characters, this behaviour is controlled by a mode stored in the string buffer object. The initial mode is strb_insert.

Changing the mode can fail if the requested mode is not supported by the library, in which case the current mode is unchanged. Any value returned by strb_getmode is accepted by strb_setmode.

Parameters

[in,out]	sb	String buffer.
	mode	New mode.

Returns

Zero if successful, otherwise EOF.

Precondition

The given sb address was returned by strb_use, strb_reuse, strb_alloc, strb_dup, strb_ndup, strb_aprintf or strb_vaprintf.

Postcondition

Alters the behaviour of strb_putc, strb_unputc, strb_puts, strb_nputs, strb_vputf, strb_putf, strb_write and strb_delto.

If successful, a call to strb_unputc will fail until a character has been put into the buffer.

On failure, a call to strb_error will return true until strb_clearerr has been called.

Definition at line 428 of file strb.c.

strb_split()

void strb_split

(

strb_t *

sb

)

Split a string at the current position.

Writes a null character into the buffer at the current position but does not increment the position indicator.

This function exists to make it efficient and simple to split or truncate the string in a buffer (as strtok does) without moving characters. It is equivalent to calling strb_write with 0 and storing a null character at the returned address.

Parameters

[in,out]

sb

String buffer.

Precondition

The given sb address was returned by strb_use, strb_reuse, strb_alloc, strb_dup, strb_ndup, strb_aprintf or strb_vaprintf.

Postcondition

The character at the current position is null.

The position indicator and string length are unmodified.

The user may call strb_restore to restore the character that was at the current position before the call to strb_split.

Definition at line 725 of file strb.c.

strb_tell()

size_t strb_tell

(

strb_t const *

sb

)

Get the editing position of a string buffer.

Parameters

[in]

sb

String buffer.

Returns

Current editing position.

Precondition

The given sb address was returned by strb_use, strb_reuse, strb_alloc, strb_dup, strb_ndup, strb_aprintf or strb_vaprintf.

Postcondition

The returned value may be passed to strb_seek.

Definition at line 471 of file strb.c.

strb_unputc()

int strb_unputc

(

strb_t *

sb

)

Undo the last put character operation.

Restores one character behind the current position and decrements the position indicator. If the mode is strb_insert, then any characters in the buffer at the former position are moved downward to the new position; otherwise, no characters are moved. This function may substitute a smaller buffer at the implementer's discretion.

A call to a function that deletes characters or sets the position/mode will discard any restorable characters in the string buffer object. Only one character is guaranteed to be restorable, regardless of mode. If this function is called too many times without an intervening write, then it may fail.

Parameters

[in,out]

sb

String buffer.

Returns

If successful, the character removed, otherwise EOF.

Precondition

The given sb address was returned by strb_use, strb_reuse, strb_alloc, strb_dup, strb_ndup, strb_aprintf or strb_vaprintf.

Postcondition

If successful, the restored character cannot be restored again.

If successful, the position indicator was decremented.

If successful in strb_insert mode, the string length was decremented.

If successful, a call to strb_restore will have no effect until strb_write has been called.

On failure, a call to strb_error will return true until strb_clearerr has been called.

Definition at line 502 of file strb.c.

strb_use()

strb_t * strb_use	(	strbstate_t *restrict	sbs,
		size_t	size,
		char	buf[STRB_SIZE_HINT(size)]
	)

Create a string buffer object for managing an external character array.

Initialises a string buffer object and returns its address. The caller must pass a string buffer state object to be used to store information about the buffer.

A null character is written as the first character of buf. The initial string length is 0. This function cannot fail.

The effects of strb_... functions on an external array are always immediately visible and the string therein is always null terminated. Operations on the string buffer can use the whole of the external array but never allocate any extra storage.

Parameters

[out]	sbs	String buffer state.
	size	Size of the array to be used instead of an internal buffer, measured in characters not bytes, including space for the terminating null character. Must not be 0.
[out]	buf	The array to be used instead of an internal buffer.

Returns

Address of the created string buffer object.

Postcondition

The user may call strb_free to free the string buffer object, but it is not required and has no effect.

The created string buffer object becomes invalid if the storage for sbs or buf is deallocated.

The created string buffer object becomes invalid if the sbs object is modified (other than as a side-effect of calling a strb_... function which is not strb_reuse or strb_use).

strb_tell and strb_len return 0.

A call to strb_restore will have no effect until strb_write has been called.

A call to strb_unputc will fail until a character has been put into the buffer.

A call to strb_error will return false until an error occurs.

Definition at line 139 of file strb.c.

strb_vaprintf()

_Optional strb_t * strb_vaprintf	(	const char *restrict	format,
		va_list	args
	)

Create a string buffer object with internal storage by parsing a format string.

Allocates storage for a string buffer object, initialises it, and returns its address. If storage allocation fails, a null pointer is returned.

The format parameter specifies how to convert subsequent arguments to generate a string, which forms the initial content of the buffer. Subsequent operations on the buffer may automatically allocate or free extra storage, if supported by the implementation.

Parameters

[in]	format	Specifies how to convert subsequent arguments to generate a string.
	args	Variable argument list to be substituted into the generated string.

Returns

Address of the created string buffer object, or a null pointer on failure.

Postcondition

The user is responsible for calling strb_free to free the string buffer object.

If successful, strb_tell and strb_len return the number of characters generated.

If successful, the last character generated (if any) can be removed by strb_unputc.

If successful, a call to strb_restore will have no effect until strb_write has been called.

If successful, a call to strb_error will return false until an error occurs.

Definition at line 338 of file strb.c.

strb_vprintf()

int strb_vprintf	(	strb_t *restrict	sb,
		const char *restrict	format,
		va_list	args
	)

Print a generated string into a string buffer.

Replaces the string in a buffer by generating characters under control of a format string.

Parameters

[in,out]	sb	String buffer.
[in]	format	Specifies how to convert subsequent arguments to generate a string.
	args	Variable argument list to be substituted into the generated string.

Returns

Zero if successful, otherwise EOF. (This differs from vsprintf, which returns 'the number of characters written in the array, not counting the terminating null character, or a negative value'.)

Precondition

The given sb address was returned by strb_use, strb_reuse, strb_alloc, strb_dup, strb_ndup, strb_aprintf or strb_vaprintf.

Postcondition

If successful, strb_tell and strb_len return the number of characters generated.

If successful, the last character written can be removed by strb_unputc.

If successful, a call to strb_restore will have no effect until strb_write has been called.

On failure, a call to strb_error will return true until strb_clearerr has been called.

Definition at line 805 of file strb.c.

strb_vputf()

int strb_vputf	(	strb_t *restrict	sb,
		const char *restrict	format,
		va_list	args
	)

Put a generated string into a string buffer.

Generates characters under control of a format string, which are written into the buffer at the current position as if by calling strb_putc for each character.

Parameters

[in,out]	sb	String buffer.
[in]	format	Specifies how to convert subsequent arguments to generate a string.
	args	Variable argument list to be substituted into the generated string.

Returns

Zero if successful, otherwise EOF. (This differs from fprintf, which returns 'the number of characters transmitted, or a negative value'.)

Precondition

The given sb address was returned by strb_use, strb_reuse, strb_alloc, strb_dup, strb_ndup, strb_aprintf or strb_vaprintf.

Postcondition

If successful, the position indicator has advanced by the number of characters generated and the string length has increased by not more than the number of characters generated.

If successful, the last character written can be removed by strb_unputc.

If successful, a call to strb_restore will have no effect until strb_write has been called.

On failure, a call to strb_error will return true until strb_clearerr has been called.

Definition at line 552 of file strb.c.

strb_write()

_Optional char * strb_write	(	strb_t *	sb,
		size_t	n
	)

Prepare to write characters directly into a string buffer.

Allows direct insertion of strings into the buffer, particularly by third-party functions which cannot be modified to operate on a string buffer object. Because it returns an unqualified pointer, this function also provides a mechanism for avoiding casts when calling functions that do not accept the address of a const char.

The n parameter indicates the number of characters expected to be written into the buffer (not including any null terminator). If the mode is strb_insert, then strb_write will move characters at the current position upward to make space; otherwise, no characters are moved. Additional storage is allocated if necessary to allow n + 1 characters to be written.

Parameters

[in,out]	sb	String buffer.
	n	The number of characters expected to be written into the buffer.

Returns

A pointer to the position where the first character should be written, or a null pointer on failure.

Precondition

The given sb address was returned by strb_use, strb_reuse, strb_alloc, strb_dup, strb_ndup, strb_aprintf or strb_vaprintf.

Postcondition

The existing contents of the buffer are unmodified. Any space allocated beyond the previous end of the buffer is filled with null characters.

If successful, the position indicator has advanced by n characters and the string length has increased by not more than n characters.

After copying up to n + 1 characters (including any null terminator) into the buffer at the returned address, the user may call strb_restore to restore the character that was at offset n from the current position before the call to strb_write.

On failure, a call to strb_error will return true until strb_clearerr has been called.

Definition at line 645 of file strb.c.