Datatype Context

Contexts are a table of word/value pairs. More...

Macros
#define	ur_ctxCell(c, n)
	Get pointer of UCell in context by index.

Functions
UIndex	ur_makeContext (UThread *ut, int size)
	Generate and initialize a single context.
UBuffer *	ur_makeContextCell (UThread *ut, int size, UCell *cell)
	Generate a single context and set cell to reference it.
void	ur_ctxReserve (UBuffer *buf, int size)
	Allocates enough memory to hold size words.
UBuffer *	ur_ctxClone (UThread *ut, const UBuffer *src, UCell *cell)
	Clone a new context and set cell to reference it.
UBuffer *	ur_ctxMirror (UThread *ut, const UBuffer *src, UCell *cell)
	Create a shallow copy of a context and set cell to reference the new context.
void	ur_ctxSetWords (UBuffer *ctx, const UCell *it, const UCell *end)
	Add the set-word! values in a series of cells to the words in a context.
void	ur_ctxInit (UBuffer *buf, int size)
	Initialize context buffer.
void	ur_ctxFree (UBuffer *buf)
	Free context data.
void	ur_ctxWordAtoms (const UBuffer *ctx, UAtom *atoms)
	Get word atoms in order.
int	ur_atomsSearch (const UAtomEntry *entries, int count, UAtom atom)
	Find an atom in a UAtomEntry table using a binary search.
int	ur_ctxAppendWord (UBuffer *ctx, UAtom atom)
	Append word to context.
int	ur_ctxAddWordI (UBuffer *ctx, UAtom atom)
	Add word to context if it does not already exist.
UCell *	ur_ctxAddWord (UBuffer *ctx, UAtom atom)
	Similar to ur_ctxAddWordI(), but safely returns the cell pointer.
void	ur_atomsSort (UAtomEntry *entries, int low, int high)
	Sort UAtomEntry table in ascending atom value order.
UBuffer *	ur_ctxSort (UBuffer *ctx)
	Sort the internal context search table so ur_ctxLookup() is faster.
const UBuffer *	ur_sortedContext (UThread *ut, const UCell *cell)
	Get context and make sure it is fully sorted for minimal ur_ctxLookup() time.
int	ur_ctxLookup (const UBuffer *ctx, UAtom atom)
	Find word in context by atom.
void	ur_bindCells (UThread *ut, UCell *it, UCell *end, const UBindTarget *bt)
	Bind an array of cells to a target.
void	ur_bind (UThread *ut, UBuffer *blk, const UBuffer *ctx, int bindType)
	Bind block to context.
void	ur_bindCopy (UThread *ut, const UBuffer *ctx, UCell *it, UCell *end)
	Recursively bind blocks to the bindings found in a context.
void	ur_unbindCells (UThread *ut, UCell *it, UCell *end, int deep)
	Unbind all words in an array of cells.
void	ur_infuse (UThread *ut, UCell *it, UCell *end, const UBuffer *ctx)
	Replace words in cells with their values from a context.

Detailed Description

Contexts are a table of word/value pairs.

Function Documentation

ur_atomsSearch()

int ur_atomsSearch	(	const UAtomEntry *	entries,
		int	count,
		UAtom	atom )

Find an atom in a UAtomEntry table using a binary search.

The table must have been previously sorted with ur_atomsSort().

Returns

Index of atom in table or -1 if not found.

ur_atomsSort()

void ur_atomsSort	(	UAtomEntry *	entries,
		int	low,
		int	high )

Sort UAtomEntry table in ascending atom value order.

Pass low of 0 and high of (count - 1) to sort the entire table.

Parameters

entries	Array of initialized UAtomEntry structs.
low	First entry in sort partition.
high	Last entry in sort partition.

ur_bind()

void ur_bind	(	UThread *	ut,
		UBuffer *	blk,
		const UBuffer *	ctx,
		int	bindType )

Bind block to context.

This recursively binds all sub-blocks.

Parameters

blk	Block to bind.
ctx	Context. This may be a stand-alone context outside of any dataStore.
bindType	UR_BIND_THREAD, UR_BIND_ENV, etc.

ur_bindCells()

void ur_bindCells	(	UThread *	ut,
		UCell *	it,
		UCell *	end,
		const UBindTarget *	bt )

Bind an array of cells to a target.

This recursively binds all blocks in the range of cells.

Parameters

it	First cell.
end	End of cell array.
bt	Bind target.

ur_bindCopy()

void ur_bindCopy	(	UThread *	ut,
		const UBuffer *	ctx,
		UCell *	it,
		UCell *	end )

Recursively bind blocks to the bindings found in a context.

Parameters

ctx	Context of bind target words.
it	First cell.
end	End of cell array.

ur_ctxAddWord()

UCell * ur_ctxAddWord	(	UBuffer *	ctx,
		UAtom	atom )

Similar to ur_ctxAddWordI(), but safely returns the cell pointer.

Returns

Pointer to value cell of word.

ur_ctxAddWordI()

int ur_ctxAddWordI	(	UBuffer *	ctx,
		UAtom	atom )

Add word to context if it does not already exist.

If added, the word value is initialized as UT_UNSET.

Note that the ctx->ptr may be changed by this function.

Returns

Index of word in context.

See also

ur_ctxAppendWord

ur_ctxAppendWord()

int ur_ctxAppendWord	(	UBuffer *	ctx,
		UAtom	atom )

Append word to context.

This should only be called if the word is known to not already exist in the context.

The new word value is initialized as UT_UNSET.

Returns

Index of word in context.

See also

ur_ctxAddWordI, ur_ctxAddWord

ur_ctxClone()

UBuffer * ur_ctxClone	(	UThread *	ut,
		const UBuffer *	src,
		UCell *	cell )

Clone a new context and set cell to reference it.

Parameters

src	Context to copy.
cell	Cell to initialize.

Returns

Pointer to context buffer.

ur_ctxFree()

void ur_ctxFree

(

UBuffer *

buf

)

Free context data.

buf->ptr and buf->used are set to zero.

ur_ctxInit()

void ur_ctxInit	(	UBuffer *	buf,
		int	size )

Initialize context buffer.

Parameters

size	Number of words to reserve.

ur_ctxLookup()

int ur_ctxLookup	(	const UBuffer *	ctx,
		UAtom	atom )

Find word in context by atom.

Parameters

cxt	Initialized context buffer.
atom	Atom of word to find.

Returns

Word index or -1 if not found.

ur_ctxMirror()

UBuffer * ur_ctxMirror	(	UThread *	ut,
		const UBuffer *	src,
		UCell *	cell )

Create a shallow copy of a context and set cell to reference the new context.

No binding is done, so any blocks remain bound to the source context.

Parameters

src	Context to copy.
cell	Cell to initialize.

Returns

Pointer to context buffer.

ur_ctxReserve()

void ur_ctxReserve	(	UBuffer *	buf,
		int	size )

Allocates enough memory to hold size words.

buf->used is not changed.

Parameters

buf	Initialized context buffer.
size	Number of words to reserve.

ur_ctxSetWords()

void ur_ctxSetWords	(	UBuffer *	ctx,
		const UCell *	it,
		const UCell *	end )

Add the set-word! values in a series of cells to the words in a context.

Parameters

ctx	Destination context.
it	Start of cells.
end	End of cells.

ur_ctxSort()

UBuffer * ur_ctxSort

(

UBuffer *

ctx

)

Sort the internal context search table so ur_ctxLookup() is faster.

If the context is already sorted then nothing is done.

Words appended to a context after it has been sorted will still be found by ur_ctxLookup(), but a slower, linear search will be used for them until ur_ctxSort() is called again.

Parameters

ctx	Initialized context buffer.

Returns

The ctx argument.

ur_ctxWordAtoms()

void ur_ctxWordAtoms	(	const UBuffer *	ctx,
		UAtom *	atoms )

Get word atoms in order.

Parameters

ctx	Valid context buffer
atoms	Array large enough to hold ctx->used atoms.

ur_infuse()

void ur_infuse	(	UThread *	ut,
		UCell *	it,
		UCell *	end,
		const UBuffer *	ctx )

Replace words in cells with their values from a context.

This recursively infuses all sub-blocks.

Unlike bind, this only modifies UT_WORD cells in UT_BLOCK or UT_PAREN slices.

Parameters

bi	Cells to infuse.
ctx	Context.

ur_makeContext()

UIndex ur_makeContext	(	UThread *	ut,
		int	size )

Generate and initialize a single context.

If you need multiple buffers then ur_genBuffers() should be used.

Parameters

size	Number of words to reserve.

Returns

Buffer id of context.

ur_makeContextCell()

UBuffer * ur_makeContextCell	(	UThread *	ut,
		int	size,
		UCell *	cell )

Generate a single context and set cell to reference it.

If you need multiple buffers then ur_genBuffers() should be used.

Parameters

size	Number of words to reserve.
cell	Cell to initialize.

Returns

Pointer to context buffer.

ur_sortedContext()

const UBuffer * ur_sortedContext	(	UThread *	ut,
		const UCell *	cell )

Get context and make sure it is fully sorted for minimal ur_ctxLookup() time.

If the context is shared and has not been sorted, then an error is generated with ur_error() and zero is returned.

Parameters

cell	Valid context cell.

Returns

Pointer to context buffer or zero.

ur_unbindCells()

void ur_unbindCells	(	UThread *	ut,
		UCell *	it,
		UCell *	end,
		int	deep )

Unbind all words in an array of cells.

Parameters

it	First cell.
end	End of cell array.
deep	Recursively unbinds all blocks if non-zero.