Detailed Description

See also: Barracuda Introduction

Classes
struct	BufPrint
	The BufPrint class, which implements a compact printf-style formatter, is a base class used by several other classes. More...

Macros
#define	BufPrint_getUserData(o) (o)->userData

#define	BufPrint_erase(o) (o)->cursor=0
	Discard pending bytes without flushing or releasing storage. More...

#define	BufPrint_getBuf(o) (o)->buf

#define	BufPrint_setBuf(o, b, size) (o)->buf=b,(o)->bufSize=size,(o)->cursor=0
	Replace borrowed storage and discard pending bytes. More...

#define	BufPrint_getBufSize(o) (o)->cursor

#define	BufPrint_destructor(o)
	No operation: BufPrint does not own its storage or context. More...

#define	BufPrint_write2(o, data) BufPrint_write(o, data, -1)
	Append a NUL-terminated string without copying its terminator. More...

Typedefs
typedef int(*	BufPrint_Flush) (struct BufPrint *o, int sizeRequired)
	BufPrint flush callback function. More...

typedef struct BufPrint	BufPrint
	The BufPrint class, which implements a compact printf-style formatter, is a base class used by several other classes. More...

Functions
BA_API void	BufPrint_constructor (BufPrint o, void userData, BufPrint_Flush flush)
	Initialize a writer without storage; install a buffer before writing. More...

BA_API void	BufPrint_constructor2 (BufPrint o, char buf, int size, void *userData, BufPrint_Flush flush)
	Initialize a writer with borrowed storage. More...

BA_API int	BufPrint_vprintf (BufPrint o, const char fmt, va_list argList)
	Format arguments into this writer. More...

BA_API int	BufPrint_printf (BufPrint o, const char fmt,...)
	Format values using the compact BAS formatter. More...

BA_API int	BufPrint_write (BufPrint o, const void data, int len)
	Append bytes, flushing or expanding through the callback as needed. More...

BA_API int	BufPrint_putc (BufPrint *o, int c)
	Append one byte (C function: BufPrint_putc). More...

BA_API int	BufPrint_flush (BufPrint *o)
	Deliver pending bytes to the callback with sizeRequired zero. More...

BA_API int	BufPrint_b64Encode (BufPrint o, const void source, S32 slen)
	Append padded standard Base64; see BufPrint::b64Encode. More...

BA_API int	BufPrint_b64urlEncode (BufPrint o, const void source, S32 slen, BaBool padding)
	Append Base64url using - and _, without a NUL terminator. More...

BA_API int	BufPrint_jsonString (BufPrint o, const char str, size_t len)
	Append a complete quoted JSON string. More...

void *	BufPrint::getUserData ()

	BufPrint::BufPrint (void *userData=0, BufPrint_Flush flush=0)
	BufPrint constructor. More...

	BufPrint::BufPrint (char buf, int size, void userData=0, BufPrint_Flush flush=0)
	Initialize a writer using caller-owned storage. More...

int	BufPrint::vprintf (const char *fmt, va_list argList)
	Format arguments into this writer. More...

int	BufPrint::printf (const char *fmt,...)
	Format values using the compact BAS formatter. More...

char *	BufPrint::getBuf ()
	Returns a pointer to the internal buffer. More...

void	BufPrint::setBuf (char *buf, int size)
	Replace borrowed storage and reset the cursor, discarding pending data. More...

U32	BufPrint::getBufSize ()

void	BufPrint::erase ()
	resets the cursor, thus erasing the data in the buffer More...

int	BufPrint::baputc (int c)
	Append one byte (C function: BufPrint_putc). More...

int	BufPrint::write (const void *data, int len)
	Append bytes, flushing or expanding through the callback as needed. More...

int	BufPrint::write (const char *buf)
	Append a NUL-terminated string (C macro: BufPrint_write2). More...

int	BufPrint::flush ()
	Deliver pending bytes to the callback with sizeRequired zero. More...

int	BufPrint::b64Encode (const void *data, S32 slen)
	Append standard Base64 with = padding, without a NUL terminator. More...

int	BufPrint::b64urlEncode (const void *source, S32 slen, bool padding)
	Append Base64url using - and _, without a NUL terminator. More...

int	BufPrint::jsonString (const char *str, size_t len)
	Append a complete quoted JSON string. More...

Macro Definition Documentation

◆ BufPrint_destructor

#define BufPrint_destructor ( o )

No operation: BufPrint does not own its storage or context.

Parameters

[in] o Writer being destroyed; release owned resources separately.

◆ BufPrint_erase

#define BufPrint_erase ( o ) (o)->cursor=0

Discard pending bytes without flushing or releasing storage.

Parameters

[in,out] o Initialized writer.

◆ BufPrint_getBuf

#define BufPrint_getBuf ( o ) (o)->buf

Parameters

[in] o Initialized writer.

Returns: Borrowed buffer, possibly NULL; not automatically NUL-terminated. Replacing or expanding storage invalidates this pointer.

◆ BufPrint_getBufSize

#define BufPrint_getBufSize ( o ) (o)->cursor

Parameters

[in] o Initialized writer.

Returns: Pending byte count, not capacity or previously sent bytes.

◆ BufPrint_getUserData

#define BufPrint_getUserData ( o ) (o)->userData

Parameters

[in] o Initialized writer.

Returns: Borrowed callback context, possibly NULL.

◆ BufPrint_setBuf

#define BufPrint_setBuf	(	o,
		b,
		size
	)	(o)->buf=b,(o)->bufSize=size,(o)->cursor=0

Replace borrowed storage and discard pending bytes.

Parameters

[in,out]	o	Initialized writer.
[in]	b	Writable buffer, valid while installed; not freed by BufPrint.
[in]	size	Nonnegative capacity in bytes.

◆ BufPrint_write2

#define BufPrint_write2	(	o,
		data
	)	BufPrint_write(o, data, -1)

Append a NUL-terminated string without copying its terminator.

Parameters

[in,out]	o	Initialized writer.
[in]	data	Required string, length fitting int, not overlapping storage.

Returns: Zero on success, negative callback error on failure; partial output may have been produced. See BufPrint::write(const char*).

Typedef Documentation

◆ BufPrint

typedef struct BufPrint BufPrint

The BufPrint class, which implements a compact printf-style formatter, is a base class used by several other classes.

This class does not allocate memory for the buffer. Thus, any class using BufPrint must provide a buffer BufPrint can use. The output from printf is formatted in the buffer passed into the constructor. BufPrint calls the callback function BufPrint_Flush when the buffer is full. See BufPrint_Flush for additional details.

◆ BufPrint_Flush

typedef int(* BufPrint_Flush) (struct BufPrint *o, int sizeRequired)

BufPrint flush callback function.

A BufPrint instance calls the flush callback function when the buffer is full or when BufPrint::flush is called. The callback can either extend the buffer or flush and reset the buffer.

The following default callback is set if no callback is installed when calling the BufPrint constructor:

static int BufPrint_defaultFlush(struct BufPrint* bp, int sizeRequired)
{
   bp->cursor=0; // Reset
   baAssert(sizeRequired == 0); // Program error in code calling BufPrint_xxx
   return sizeRequired ? -1 : 0;
}

Parameters

o	Borrowed writer. Update its buffer, capacity and cursor when providing more space or consuming pending bytes.
sizeRequired	Additional space requested in bytes. Zero denotes an explicit flush, or initial buffer creation by printf/vprintf. A callback that grows storage must preserve pending bytes. A callback that sends data must reset the cursor and leave usable storage for continued output.

Returns: Zero on success; a negative status on failure. Use negative errors consistently: some operations propagate the status, others return -1. Earlier bytes may already have been sent when a later operation fails.

Function Documentation

◆ b64Encode()

int BufPrint::b64Encode	(	const void *	data,
		S32	slen
	)

Append standard Base64 with = padding, without a NUL terminator.

Parameters

[in]	data	Borrowed source containing at least slen readable bytes.
[in]	slen	Nonnegative source length in bytes; zero produces no output.

Returns: Zero on success, -1 on output failure. Partial output is possible.

See also: baB64Decode

◆ b64urlEncode()

int BufPrint::b64urlEncode	(	const void *	source,
		S32	slen,
		bool	padding
	)

Append Base64url using - and _, without a NUL terminator.

Parameters

[in]	source	Borrowed source containing at least slen readable bytes.
[in]	slen	Nonnegative source length in bytes; zero produces no output.
[in]	padding	True appends = padding, false omits it.

Returns: Zero on success, -1 on output failure. Partial output is possible.

See also: baB64Decode

◆ baputc()

int BufPrint::baputc ( int c )

Append one byte (C function: BufPrint_putc).

Parameters

[in] c Character value converted to char.

Returns: Zero on success, -1 if obtaining buffer space fails.

◆ BufPrint() [1/2]

BufPrint::BufPrint	(	char *	buf,
		int	size,
		void *	userData = `0`,
		BufPrint_Flush	flush = `0`
	)

Initialize a writer using caller-owned storage.

C constructor name: BufPrint_constructor2

Parameters

buf	Borrowed writable storage; must remain valid while installed.
size	Nonnegative capacity in bytes. Supply usable storage before writing.
userData	Optional borrowed pointer (default NULL) stored in the BufPrint object and accessible in the flush callback.
flush	Optional callback; NULL selects the fixed-buffer callback. See BufPrint_Flush for details.

See also: setBuf(), getUserData()

◆ BufPrint() [2/2]

BufPrint::BufPrint	(	void *	userData = `0`,
		BufPrint_Flush	flush = `0`
	)

BufPrint constructor.

When using this constructor, make sure to also call setBuf(). C constructor name: BufPrint_constructor

Parameters

userData	Optional borrowed pointer (default NULL) stored in the BufPrint object and accessible in the flush callback.
flush	Optional callback; NULL selects the fixed-buffer callback. See BufPrint_Flush for details.

See also: setBuf(), getUserData()

◆ BufPrint_b64Encode()

BA_API int BufPrint_b64Encode	(	BufPrint *	o,
		const void *	source,
		S32	slen
	)

Append padded standard Base64; see BufPrint::b64Encode.

Parameters

[in,out]	o	Initialized writer.
[in]	source	Borrowed readable bytes.
[in]	slen	Nonnegative source length in bytes.

Returns: Zero on success, -1 on output failure. Partial output is possible.

◆ BufPrint_b64urlEncode()

BA_API int BufPrint_b64urlEncode	(	BufPrint *	o,
		const void *	source,
		S32	slen,
		BaBool	padding
	)

Append Base64url using - and _, without a NUL terminator.

Parameters

[in]	source	Borrowed source containing at least slen readable bytes.
[in]	slen	Nonnegative source length in bytes; zero produces no output.
[in]	padding	True appends = padding, false omits it.

Returns: Zero on success, -1 on output failure. Partial output is possible.

See also: baB64Decode

Parameters

[in,out] o Initialized writer.

◆ BufPrint_constructor()

BA_API void BufPrint_constructor	(	BufPrint *	o,
		void *	userData,
		BufPrint_Flush	flush
	)

Initialize a writer without storage; install a buffer before writing.

Parameters

[out]	o	Caller-owned writer.
[in]	userData	Optional borrowed callback context, or NULL.
[in]	flush	Callback or NULL for the default fixed-buffer callback.

See also: BufPrint_Flush

◆ BufPrint_constructor2()

BA_API void BufPrint_constructor2	(	BufPrint *	o,
		char *	buf,
		int	size,
		void *	userData,
		BufPrint_Flush	flush
	)

Initialize a writer with borrowed storage.

Parameters

[out]	o	Caller-owned writer.
[in]	buf	Writable buffer, valid while installed.
[in]	size	Nonnegative buffer capacity in bytes.
[in]	userData	Optional borrowed callback context, or NULL.
[in]	flush	Callback or NULL for the default fixed-buffer callback.

See also: BufPrint_Flush

◆ BufPrint_flush()

BA_API int BufPrint_flush ( BufPrint * o )

Deliver pending bytes to the callback with sizeRequired zero.

Returns: Zero if empty; otherwise the callback status (zero success, negative failure). The cursor is reset even if the callback fails.

Parameters

[in,out] o Initialized writer.

◆ BufPrint_jsonString()

BA_API int BufPrint_jsonString	(	BufPrint *	o,
		const char *	str,
		size_t	len
	)

Append a complete quoted JSON string.

Escapes ASCII control characters, quotes, slash and backslash. UTF-8 is validated and encoded as \uxxxx sequences, using surrogate pairs for characters outside the Basic Multilingual Plane. Does not append NUL.

Parameters

[in]	str	Borrowed ASCII or UTF-8 bytes. Embedded NUL bytes are escaped.
[in]	len	Exact readable byte count; no NUL terminator is required.

Returns: Zero on success; negative status on invalid UTF-8 or output failure. Failure can leave a partial quoted string in the buffer or output stream.

See also: printf

Parameters

[in,out] o Initialized writer.

◆ BufPrint_printf()

BA_API int BufPrint_printf	(	BufPrint *	o,
		const char *	fmt,
			...
	)

Format values using the compact BAS formatter.

Supports integer conversions %d, %i, %u, %o, %x, %X; %p, %c, %s and %%; flags -, +, space, # and 0; width and precision (including *); and the h, l and ll integer length modifiers. %lld and %llu format S64 and U64. %f, %e, %E, %g and %G require floating-point support in the build. This is not a complete implementation of the C library printf.

%j takes a NUL-terminated UTF-8 string and emits a quoted JSON string using jsonString. Precision limits input bytes and must not split a UTF-8 sequence. %s and %j require complete NUL-terminated input even with precision. NULL string pointers become "(null)" (%j also adds JSON quotes). Avoid %n: this implementation does not maintain an output byte count.

Parameters

[in] fmt Required NUL-terminated format. Following arguments must match the conversions and promoted C types. Keep widths and precisions within signed-short range; literal fields are limited by the parser.

Returns: Zero on success, negative status on failure, not a byte count. Partial output can remain on failure. Does not append NUL or flush.

See also: vprintf jsonString

Parameters

[in,out] o Initialized writer.

◆ BufPrint_putc()

BA_API int BufPrint_putc	(	BufPrint *	o,
		int	c
	)

Append one byte (C function: BufPrint_putc).

Parameters

[in] c Character value converted to char.

Returns: Zero on success, -1 if obtaining buffer space fails.

Parameters

[in,out] o Initialized writer.

◆ BufPrint_vprintf()

BA_API int BufPrint_vprintf	(	BufPrint *	o,
		const char *	fmt,
		va_list	argList
	)

Format arguments into this writer.

Parameters

[in]	fmt	NUL-terminated format using printf's supported conversions.
[in]	argList	Initialized argument list matching fmt. Its state after this call is platform dependent; use va_copy if it is needed again.

Returns: Zero on success, negative status on failure; not a byte count. Output is not automatically NUL-terminated or flushed. Partial output may remain buffered or already have been sent on failure.

See also: printf

Parameters

[in,out] o Initialized writer.

◆ BufPrint_write()

BA_API int BufPrint_write	(	BufPrint *	o,
		const void *	data,
		int	len
	)

Append bytes, flushing or expanding through the callback as needed.

Parameters

[in]	data	Borrowed readable source; must not overlap destination storage. With negative len, supply a NUL-terminated string.
[in]	len	Byte count, or a negative value to use strlen(data). Length and cursor arithmetic must fit int.

Returns: Zero on success, negative callback status on failure. Earlier bytes may already have been buffered or sent. Does not append NUL.

Parameters

[in,out] o Initialized writer.

◆ erase()

void BufPrint::erase ( )

resets the cursor, thus erasing the data in the buffer

◆ flush()

int BufPrint::flush ( )

Deliver pending bytes to the callback with sizeRequired zero.

Returns: Zero if empty; otherwise the callback status (zero success, negative failure). The cursor is reset even if the callback fails.

◆ getBuf()

char * BufPrint::getBuf ( )

Returns a pointer to the internal buffer.

Please note that the buffer returned by this method is not zero terminated.

Returns: Borrowed buffer pointer, possibly NULL before setup. The pointer can change when the callback replaces or reallocates storage.

See also: BufPrint::getBufSize

◆ getBufSize()

U32 BufPrint::getBufSize ( )

Returns: Pending byte count, not capacity or total bytes previously sent.

◆ getUserData()

void * BufPrint::getUserData ( )

Returns: Borrowed user data pointer set in the constructor, possibly NULL.

◆ jsonString()

int BufPrint::jsonString	(	const char *	str,
		size_t	len
	)

Append a complete quoted JSON string.

Escapes ASCII control characters, quotes, slash and backslash. UTF-8 is validated and encoded as \uxxxx sequences, using surrogate pairs for characters outside the Basic Multilingual Plane. Does not append NUL.

Parameters

[in]	str	Borrowed ASCII or UTF-8 bytes. Embedded NUL bytes are escaped.
[in]	len	Exact readable byte count; no NUL terminator is required.

Returns: Zero on success; negative status on invalid UTF-8 or output failure. Failure can leave a partial quoted string in the buffer or output stream.

See also: printf

◆ printf()

int BufPrint::printf	(	const char *	fmt,
			...
	)

Format values using the compact BAS formatter.

Supports integer conversions %d, %i, %u, %o, %x, %X; %p, %c, %s and %%; flags -, +, space, # and 0; width and precision (including *); and the h, l and ll integer length modifiers. %lld and %llu format S64 and U64. %f, %e, %E, %g and %G require floating-point support in the build. This is not a complete implementation of the C library printf.

%j takes a NUL-terminated UTF-8 string and emits a quoted JSON string using jsonString. Precision limits input bytes and must not split a UTF-8 sequence. %s and %j require complete NUL-terminated input even with precision. NULL string pointers become "(null)" (%j also adds JSON quotes). Avoid %n: this implementation does not maintain an output byte count.

Parameters

[in] fmt Required NUL-terminated format. Following arguments must match the conversions and promoted C types. Keep widths and precisions within signed-short range; literal fields are limited by the parser.

Returns: Zero on success, negative status on failure, not a byte count. Partial output can remain on failure. Does not append NUL or flush.

See also: vprintf jsonString

◆ setBuf()

void BufPrint::setBuf	(	char *	buf,
		int	size
	)

Replace borrowed storage and reset the cursor, discarding pending data.

Neither the old nor new storage is freed by BufPrint.

Parameters

buf	Borrowed writable storage; must remain valid while installed.
size	Nonnegative capacity in bytes. Supply usable storage before writing.

◆ vprintf()

int BufPrint::vprintf	(	const char *	fmt,
		va_list	argList
	)

Format arguments into this writer.

Parameters

[in]	fmt	NUL-terminated format using printf's supported conversions.
[in]	argList	Initialized argument list matching fmt. Its state after this call is platform dependent; use va_copy if it is needed again.

Returns: Zero on success, negative status on failure; not a byte count. Output is not automatically NUL-terminated or flushed. Partial output may remain buffered or already have been sent on failure.

See also: printf

◆ write() [1/2]

int BufPrint::write ( const char * buf )

Append a NUL-terminated string (C macro: BufPrint_write2).

Parameters

[in] buf Required readable string, not overlapping writer storage. Its length must fit int; the terminating NUL is not copied.

Returns: Zero on success, negative callback status on failure. Partial output may already have been produced.

◆ write() [2/2]

int BufPrint::write	(	const void *	data,
		int	len
	)

Append bytes, flushing or expanding through the callback as needed.

Parameters

[in]	data	Borrowed readable source; must not overlap destination storage. With negative len, supply a NUL-terminated string.
[in]	len	Byte count, or a negative value to use strlen(data). Length and cursor arithmetic must fit int.

Returns: Zero on success, negative callback status on failure. Earlier bytes may already have been buffered or sent. Does not append NUL.

Detailed Description

Classes

Macros

Typedefs

Functions

Macro Definition Documentation

◆ BufPrint_destructor

◆ BufPrint_erase

◆ BufPrint_getBuf

◆ BufPrint_getBufSize

◆ BufPrint_getUserData

◆ BufPrint_setBuf

◆ BufPrint_write2

Typedef Documentation

◆ BufPrint

◆ BufPrint_Flush

Function Documentation

◆ b64Encode()

◆ b64urlEncode()

◆ baputc()

◆ BufPrint() [1/2]

◆ BufPrint() [2/2]

◆ BufPrint_b64Encode()

◆ BufPrint_b64urlEncode()

◆ BufPrint_constructor()

◆ BufPrint_constructor2()

◆ BufPrint_flush()

◆ BufPrint_jsonString()

◆ BufPrint_printf()

◆ BufPrint_putc()

◆ BufPrint_vprintf()

◆ BufPrint_write()

◆ erase()

◆ flush()

◆ getBuf()

◆ getBufSize()

◆ getUserData()

◆ jsonString()

◆ printf()

◆ setBuf()

◆ vprintf()

◆ write() [1/2]

◆ write() [2/2]