StrBuffer

Data Structures
struct	CrocStrBuffer

Functions
void	croc_ex_buffer_init (CrocThread *t, CrocStrBuffer *b)
void	croc_ex_buffer_addChar (CrocStrBuffer *b, crocchar_t c)
void	croc_ex_buffer_addString (CrocStrBuffer *b, const char *s)
void	croc_ex_buffer_addStringn (CrocStrBuffer *b, const char *s, uword_t len)
void	croc_ex_buffer_addTop (CrocStrBuffer *b)
word_t	croc_ex_buffer_finish (CrocStrBuffer *b)
void	croc_ex_buffer_start (CrocStrBuffer *b)
char *	croc_ex_buffer_prepare (CrocStrBuffer *b, uword_t size)
void	croc_ex_buffer_addPrepared (CrocStrBuffer *b)

Detailed Description

A way of building up strings piecewise.

---

Data Structure Documentation

struct CrocStrBuffer

A structure used for building strings up piecewise.

Although the members are defined so you can allocate this structure on the stack, treat it as if it were an opaque type! Only pass it to the buffer functions.

Function Documentation

void croc_ex_buffer_init	(	CrocThread *	t,
		CrocStrBuffer *	b
	)

Initializes a CrocStrBuffer.

Using a CrocStrBuffer goes something like this:

1. Declare a CrocStrBuffer variable.
2. Initialize it with this function.
3. Add pieces to it with the various other functions.
4. When you're done building your string, call croc_ex_buffer_finish on it, which will leave the resulting string on top of the stack.

So for example:

CrocStrBuffer b;

// Start!
croc_ex_buffer_init(t, &b);
croc_ex_buffer_addString(&b, "Hello");
croc_ex_buffer_addChar(&b, ',');
croc_pushString(t, " world!");
croc_ex_buffer_addTop(&b);
croc_ex_buffer_finish(&b);
// Now there is only one more stack slot than what we started with, and it contains the string "Hello, world!".

Note that croc_ex_buffer_init pushes a stack slot for use by the buffer which is used until croc_ex_buffer_finish is called. You shouldn't remove or modify this slot, and you shouldn't remove stack slots below it either (or else things will get messed up). You can, however, push and pop stack slots above this slot freely.

void croc_ex_buffer_addChar	(	CrocStrBuffer *	b,
		crocchar_t	c
	)

Adds a single Unicode codepoint to b.

void croc_ex_buffer_addString	(	CrocStrBuffer *	b,
		const char *	s
	)

Adds a zero-terminated string to b.

void croc_ex_buffer_addStringn	(	CrocStrBuffer *	b,
		const char *	s,
		uword_t	len
	)

Adds a string of length len to b.

void croc_ex_buffer_addTop

(

CrocStrBuffer *

b

)

Expects a single string on top of the stack, pops it, and adds it to b.

word_t croc_ex_buffer_finish

(

CrocStrBuffer *

b

)

Finishes building the string.

The stack should be in the same configuration as it was right after the corresponding croc_ex_buffer_init call. The bookkeeping slot is removed and the result string is pushed in its place.

After this is called, the buffer can be reused to build a new string by calling croc_ex_buffer_start on it.

Returns

the stack index of the result string.

void croc_ex_buffer_start

(

CrocStrBuffer *

b

)

After building up a string and calling croc_ex_buffer_finish on a buffer b, you can start building a new string with the same buffer object by calling this.

char* croc_ex_buffer_prepare	(	CrocStrBuffer *	b,
		uword_t	size
	)

Prepares a memory area of size bytes for you to write raw string data into.

When you call this function on a buffer, you cannot call any of the other functions on it until you call croc_ex_buffer_addPrepared. It places the buffer into a special mode, and in addition, may push a value onto the stack. Just like with the buffer's bookkeeping slot, do not modify, remove, or change the position of this slot.

Returns

a pointer to a memory area of size bytes which you are expected to fill with string data.

The pointer returned from this may point into Croc's memory. Do not store the pointer! Just keep it long enough to fill the area with data and call croc_ex_buffer_addPrepared.

void croc_ex_buffer_addPrepared

(

CrocStrBuffer *

b

)

Adds the memory area that was returned by croc_ex_buffer_prepare to the buffer.

After calling this, the buffer will be back into its normal mode, and the stack slot that croc_ex_buffer_prepare may have allocated will be gone. The stack must be in the same configuration as it was after croc_ex_buffer_prepare was called.