Data Structures
struct	UBindTarget
	Holds information for binding functions. More...

struct	USeriesIter
	Iterator for const series of any type. More...

struct	UBlockIt
	Iterator for const UCell array. More...

union	UCell
	A cell holds a single value of a simple type or a reference (often to a UBuffer) for a complex type. More...

struct	UBuffer
	The UBuffer struct holds information about a resource, usually a chunk of memory. More...

struct	UThread
	The UThread struct stores the data specific to a thread of execution. More...

struct	UEnvParameters
	The UEnvParameters struct allows the user to override default buffer and structure sizes. More...

Macros
#define	ur_type(c)
	Return UrlanDataType of cell.

#define	ur_setId(c, t)
	Set type and initialize the other 24 bits of UCellId to zero.

#define	ur_isShared(n)
	True if buffer number refers to a buffer in the shared environment.

#define	ur_isSliced(c)
	True if the end member of a series cell is set.

#define	ur_foreach(bi)
	Loop over all members of an iterator struct.

#define	ur_hold(n)
	Convenience macro for ur_holdBuffer().

#define	ur_release(h)
	Convenience macro for ur_releaseBuffer().

#define	ur_pop(ut)
	Decrement stack.used.

#define	ur_buffer(n)
	Macro to get buffer known to be in thread dataStore.

#define	ur_bufferE(n)
	Convenience macro for ur_bufferEnv().

#define	ur_bufferSer(c)
	Convenience macro for ur_bufferSeries().

#define	ur_bufferSerM(c)
	Convenience macro for ur_bufferSeriesM().

Functions
const char *	ur_atomCStr (UThread *ut, UAtom atom)
	Get name of atom.

UThread *	ur_makeThread (const UThread *ut, uint32_t flags)
	Create a new thread.

int	ur_destroyThread (UThread *ut)
	Free memory used by UThread.

UEnvParameters *	ur_envParam (UEnvParameters *par)
	Initialize UEnvParameters structure to default values.

UThread *	ur_makeEnv (const UEnvParameters *par)
	Allocate UEnv and initial UThread.

void	ur_freeEnv (UThread *ut)
	Free environment and the initial thread.

void	ur_freezeEnv (UThread *ut)
	Move the startup thread dataStore to the shared environment.

int	ur_datatypeCount (UThread *ut)
	Get number of datatypes installed in the environment.

UAtom	ur_intern (UThread ut, const char name, int len)
	Add a single atom to the shared environment.

UAtom	ur_internAtom (UThread ut, const char it, const char *end)
	Add a single atom to the shared environment.

UAtom *	ur_internAtoms (UThread ut, const char words, UAtom *atoms)
	Add atoms to the shared environment.

UBuffer *	ur_genBuffers (UThread ut, int count, UIndex index)
	Generate new buffers in dataStore.

UBuffer *	ur_generate (UThread ut, int count, UIndex index, const uint8_t *types)
	Generate and initialize buffers of given types.

void	ur_destroyBuffer (UThread ut, UBuffer buf)
	Destroy buffer in dataStore.

UIndex	ur_holdBuffer (UThread *ut, UIndex bufN)
	Keeps buffer in thread dataStore from being garbage collected by ur_recycle().

void	ur_releaseBuffer (UThread *ut, UIndex hold)
	Enables garbage collection of dataStore buffer which was held by ur_holdBuffer().

UCell *	ur_push (UThread *ut, int type)
	Set id of cell on top of stack and increment stack.used.

UCell *	ur_pushCell (UThread ut, const UCell src)
	Copy cell to top of stack and increment stack.used.

UBuffer *	ur_threadContext (UThread *ut)
	Get thread global context.

UBuffer *	ur_envContext (UThread *ut)
	Get shared global context.

UStatus	ur_error (UThread ut, int errorType, const char fmt,...)
	Create error! exception.

void	ur_appendTrace (UThread *ut, UIndex blkN, UIndex it)
	Append block position to the current exception error! trace.

int	ur_true (const UCell *cell)
	Check if a value is "true".

int	ur_same (UThread ut, const UCell a, const UCell *b)

int	ur_equal (UThread ut, const UCell a, const UCell *b)

int	ur_equalCase (UThread ut, const UCell a, const UCell *b)
	Case-sensitive equality test.

int	ur_compare (UThread ut, const UCell a, const UCell *b)

int	ur_compareCase (UThread ut, const UCell a, const UCell *b)
	Case-sensitive ordering comparison.

void	ur_toStr (UThread ut, const UCell cell, UBuffer *str, int depth)
	Append data representation of cell to a string.

void	ur_toText (UThread ut, const UCell cell, UBuffer *str)
	Append textual representation of cell to a string.

const UCell *	ur_wordCell (UThread ut, const UCell cell)
	Get word value for read-only operations.

UCell *	ur_wordCellM (UThread ut, const UCell cell)
	Get modifiable word value.

UStatus	ur_setWord (UThread ut, const UCell word, const UCell *src)
	Set word.

const UBuffer *	ur_bufferEnv (UThread *ut, UIndex n)
	Get buffer from either the thread dataStore or environment sharedStore.

const UBuffer *	ur_bufferSeries (const UThread ut, const UCell cell)
	Get series buffer.

UBuffer *	ur_bufferSeriesM (UThread ut, const UCell cell)
	Get modifiable series buffer.

void	ur_seriesSlice (const UThread ut, USeriesIter si, const UCell *cell)
	Set USeriesIter to series slice.

UStatus	ur_seriesSliceM (UThread ut, USeriesIterM si, const UCell *cell)
	Set USeriesIterM to modifiable series slice.

const UBuffer *	ur_blockIt (const UThread ut, UBlockIt bi, const UCell *blkCell)
	Set UBlockIt to the start and end of a block slice.

UStatus	ur_tokenizeB (UThread ut, UIndex blkN, int inputEncoding, const uint8_t start, const uint8_t *end)
	Parse UTF-8 or Latin1 data into block.

UIndex	ur_tokenize (UThread ut, const char it, const char end, UCell res)
	Convert a UTF-8 data string into a block.

Variables
const UBuffer *	USeriesIter::buf
	Buffer pointer.

UIndex	USeriesIter::it
	Start position.

UIndex	USeriesIter::end
	End position.

const UCell *	UBlockIt::it
	Start position.

const UCell *	UBlockIt::end
	End position.

Detailed Description

Macro Definition Documentation

◆ ur_foreach

#define ur_foreach ( bi )

Value:

for(; bi.it != bi.end; ++bi.it)

Loop over all members of an iterator struct.

These include UBlockIt, UBlockIter, USeriesIter.

Examples: calculator.c.

◆ ur_pop

#define ur_pop ( ut )

Value:

--(ut)->stack.used

Decrement stack.used.

Must not be called if stack.used is zero.

Function Documentation

◆ ur_appendTrace()

void ur_appendTrace	(	UThread *	ut,
		UIndex	blkN,
		UIndex	it )

Append block position to the current exception error! trace.

Parameters

blkN	Block id.
it	Position in block blkN.

◆ ur_atomCStr()

const char * ur_atomCStr	(	UThread *	ut,
		UAtom	atom )

Get name of atom.

Parameters

atom	Valid atom.

Returns: Null terminated string.

◆ ur_blockIt()

const UBuffer * ur_blockIt	(	const UThread *	ut,
		UBlockIt *	bi,
		const UCell *	blkCell )

Set UBlockIt to the start and end of a block slice.

Parameters

bi	Iterator struct to fill.
blkCell	Pointer to a valid block cell.

Returns: Pointer to buffer referenced by blkCell.

◆ ur_bufferEnv()

const UBuffer * ur_bufferEnv	(	UThread *	ut,
		UIndex	n )

Get buffer from either the thread dataStore or environment sharedStore.

The macro ur_bufferE() should normally be used to call this function.

Parameters

n	Buffer identifier.

Returns: Pointer to buffer n.

◆ ur_bufferSeries()

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

Get series buffer.

The macro ur_bufferSer() should normally be used to call this function.

Parameters

cell	Pointer to valid series or bound word cell.

Returns: Pointer to buffer referenced by cell->series.buf.

◆ ur_bufferSeriesM()

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

Get modifiable series buffer.

The macro ur_bufferSerM() should normally be used to call this function.

Parameters

cell	Pointer to valid series or bound word cell.

Returns: Pointer to buffer referenced by cell->series.buf. If the buffer is in shared storage then an error is generated and zero is returned.

◆ ur_compare()

int ur_compare	(	UThread *	ut,
		const UCell *	a,
		const UCell *	b )

Returns: 1, 0, or -1, if cell a is greater than, equal to, or less than cell b.

◆ ur_compareCase()

int ur_compareCase	(	UThread *	ut,
		const UCell *	a,
		const UCell *	b )

Case-sensitive ordering comparison.

Returns: 1, 0, or -1, if cell a is greater than, equal to, or less than cell b.

◆ ur_datatypeCount()

int ur_datatypeCount ( UThread * ut )

Get number of datatypes installed in the environment.

Returns: Number of datatypes.

◆ ur_destroyBuffer()

void ur_destroyBuffer	(	UThread *	ut,
		UBuffer *	buf )

Destroy buffer in dataStore.

The buffer must be valid. This function must not be called with a buffer which has not been generated with ur_genBuffers(), has not been initialized, or has already been destroyed.

Parameters

buf	Pointer to valid buffer.

◆ ur_destroyThread()

int ur_destroyThread ( UThread * ut )

Free memory used by UThread.

To destroy a thread created with ur_makeEnv(), use ur_freeEnv().

Parameters

ut	Thread created with ur_makeThread()

Returns: Non-zero if thread is not NULL and not an initial thread.

◆ ur_envContext()

UBuffer * ur_envContext ( UThread * ut )

Get shared global context.

Returns: Pointer to context, or zero if ur_freezeEnv() has not been called.

◆ ur_equal()

int ur_equal	(	UThread *	ut,
		const UCell *	a,
		const UCell *	b )

Returns: Non-zero if values are equivalent.

◆ ur_equalCase()

int ur_equalCase	(	UThread *	ut,
		const UCell *	a,
		const UCell *	b )

Case-sensitive equality test.

Returns: Non-zero if values are equivalent.

◆ ur_error()

UStatus ur_error	(	UThread *	ut,
		int	errorType,
		const char *	fmt,
			... )

Create error! exception.

The errorType is only descriptive, it has no real function.

Parameters

errorType	UrlanErrorType (UR_ERR_TYPE, UR_ERR_SCRIPT, etc.).
fmt	Error message with printf() style formatting.

Returns: UR_THROW

◆ ur_freeEnv()

void ur_freeEnv ( UThread * ut )

Free environment and the initial thread.

The caller must make sure no other threads created with ur_makeThread() are running.

Parameters

ut	UThread created with ur_makeEnv(). It is safe to pass zero.

◆ ur_freezeEnv()

void ur_freezeEnv ( UThread * ut )

Move the startup thread dataStore to the shared environment.

This may only be called once after ur_makeEnv(), and must be done before a second thread is created.

The thread method UR_THREAD_FREEZE is called before any adjustments are made. After the store has been converted, all buffer holds are removed and a fresh thread dataStore is created.

Parameters

ut	UThread created with ur_makeEnv().

◆ ur_genBuffers()

UBuffer * ur_genBuffers	(	UThread *	ut,
		int	count,
		UIndex *	index )

Generate new buffers in dataStore.

This may trigger the garbage collector.

The new buffers are completely unintialized, so the caller must make them valid before the next garbage recycle.

Parameters

count	Number of buffers to obtain.
index	Return array of buffer ids. This must large enough to to hold count indices.

Returns: Pointer to first buffer. The buffer indicies are stored in index.

◆ ur_generate()

UBuffer * ur_generate	(	UThread *	ut,
		int	count,
		UIndex *	index,
		const uint8_t *	types )

Generate and initialize buffers of given types.

Strings will have an UR_ENC_LATIN1 form. Vectors will have an UR_VEC_I32 form.

Parameters

count	Number of buffers to obtain.
index	Return array of buffer ids. This must large enough to to hold count indices.
types	Array of UrlanDataType.

Returns: Pointer to first buffer. The buffer indicies are stored in index.

◆ ur_holdBuffer()

UIndex ur_holdBuffer	(	UThread *	ut,
		UIndex	bufN )

Keeps buffer in thread dataStore from being garbage collected by ur_recycle().

Returns: Hold id to be used with ur_releaseBuffer().

◆ ur_intern()

UAtom ur_intern	(	UThread *	ut,
		const char *	name,
		int	len )

Add a single atom to the shared environment.

Parameters

name	Pointer to atom name.
len	Length of name.

Returns: Atom of word or UR_INVALID_ATOM if an error was generated.

See also: ur_internAtom, ur_internAtoms

◆ ur_internAtom()

UAtom ur_internAtom	(	UThread *	ut,
		const char *	it,
		const char *	end )

Add a single atom to the shared environment.

Parameters

it	Start of word.
end	End of word.

Returns: Atom of word or UR_INVALID_ATOM if an error was generated.

See also: ur_intern, ur_internAtoms

◆ ur_internAtoms()

UAtom * ur_internAtoms	(	UThread *	ut,
		const char *	words,
		UAtom *	atoms )

Add atoms to the shared environment.

Parameters

words	C string containing words separated by whitespace.
atoms	Return area for atoms of the words.

Returns: Pointer marking the end of the entries set in atoms.

◆ ur_makeEnv()

UThread * ur_makeEnv ( const UEnvParameters * par )

Allocate UEnv and initial UThread.

Parameters

atomLimit	Maximum number of atoms. Memory usage is ((12 + 12) * atomLimit) bytes.
dtTable	Array of pointers to user defined datatypes. Pass zero if dtCount is zero.
dtCount	Number of datatypes in dtTable.
thrSize	Byte size of each thread in the environment. Pass zero if no extra memory is needed.
thrMethod	Callback function to initialize and cleanup threads. This may be zero.
par	Environment parameters.

Returns: Pointer to initial thread.

◆ ur_makeThread()

UThread * ur_makeThread	(	const UThread *	ut,
		uint32_t	flags )

Create a new thread.

Parameters

ut	Existing thread.
flags	Zero or UR_TFLAG_FIBRE.

Returns: Pointer to new thread in the same environment as ut, or NULL if memory could not be allocated.

◆ ur_push()

UCell * ur_push	(	UThread *	ut,
		int	type )

Set id of cell on top of stack and increment stack.used.

Returns: Pointer to initilized cell on stack.

◆ ur_pushCell()

UCell * ur_pushCell	(	UThread *	ut,
		const UCell *	src )

Copy cell to top of stack and increment stack.used.

Returns: Pointer to copy on stack.

◆ ur_same()

int ur_same	(	UThread *	ut,
		const UCell *	a,
		const UCell *	b )

Returns: Non-zero if values are the same.

◆ ur_seriesSlice()

void ur_seriesSlice	(	const UThread *	ut,
		USeriesIter *	si,
		const UCell *	cell )

Set USeriesIter to series slice.

Parameters

si	Iterator struct to fill.
cell	Pointer to a valid series cell.

◆ ur_seriesSliceM()

UStatus ur_seriesSliceM	(	UThread *	ut,
		USeriesIterM *	si,
		const UCell *	cell )

Set USeriesIterM to modifiable series slice.

Parameters

si	Iterator struct to fill.
cell	Pointer to a valid series cell.

Returns: UR_OK/UR_THROW

◆ ur_setWord()

UStatus ur_setWord	(	UThread *	ut,
		const UCell *	word,
		const UCell *	src )

Set word.

This copies src into the cell which the word is bound to.

If the word is unbound or bound to the shared environment then an error is generated and UR_THROW is returned.

Parameters

word	Word to set.
src	Source value to copy.

Returns: UR_OK/UR_THROW

◆ ur_threadContext()

UBuffer * ur_threadContext ( UThread * ut )

Get thread global context.

Returns: Pointer to thread global context.

◆ ur_tokenize()

UIndex ur_tokenize	(	UThread *	ut,
		const char *	it,
		const char *	end,
		UCell *	res )

Convert a UTF-8 data string into a block.

Note: Currently, non-ASCII characters are only allowed inside string!/file! types and comments.

Parameters

it	Start of string.
end	End of string.
res	Cell to initialize as UT_BLOCK if non-zero is returned.

Returns: Block buffer id. If a syntax error is found, then an error is generated with ur_error() and zero is returned.

◆ ur_tokenizeB()

UStatus ur_tokenizeB	(	UThread *	ut,
		UIndex	blkN,
		int	inputEncoding,
		const uint8_t *	start,
		const uint8_t *	end )

Parse UTF-8 or Latin1 data into block.

Parameters

blkN	Index of initialized block buffer.
inputEncoding	UR_ENC_UTF8 or UR_ENC_LATIN1
start	Pointer to start of input data.
end	Pointer to end of input data.

Returns: UR_OK if all input successfully parsed, or UR_THROW on syntax error.

◆ ur_toStr()

void ur_toStr	(	UThread *	ut,
		const UCell *	cell,
		UBuffer *	str,
		int	depth )

Append data representation of cell to a string.

Parameters

str	String to add to.

◆ ur_toText()

void ur_toText	(	UThread *	ut,
		const UCell *	cell,
		UBuffer *	str )

Append textual representation of cell to a string.

Parameters

str	String to add to.

◆ ur_true()

int ur_true ( const UCell * cell )

Check if a value is "true".

Note that a word bound to 'none is true.

Returns: Non-zero if cell is not none! or a false logic! value.

◆ ur_wordCell()

const UCell * ur_wordCell	(	UThread *	ut,
		const UCell *	cell )

Get word value for read-only operations.

Parameters

cell	Pointer to word cell.

Returns: Pointer to value cell. If the word does not have a valid binding then an error is generated and zero is returned.

◆ ur_wordCellM()

UCell * ur_wordCellM	(	UThread *	ut,
		const UCell *	cell )

Get modifiable word value.

Parameters

cell	Pointer to word cell.

Returns: Pointer to value cell. If the word does not have a valid binding then an error is generated and zero is returned.

Data Structures

Macros

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ ur_foreach

◆ ur_pop

Function Documentation

◆ ur_appendTrace()

◆ ur_atomCStr()

◆ ur_blockIt()

◆ ur_bufferEnv()

◆ ur_bufferSeries()

◆ ur_bufferSeriesM()

◆ ur_compare()

◆ ur_compareCase()

◆ ur_datatypeCount()

◆ ur_destroyBuffer()

◆ ur_destroyThread()

◆ ur_envContext()

◆ ur_equal()

◆ ur_equalCase()

◆ ur_error()

◆ ur_freeEnv()

◆ ur_freezeEnv()

◆ ur_genBuffers()

◆ ur_generate()

◆ ur_holdBuffer()

◆ ur_intern()

◆ ur_internAtom()

◆ ur_internAtoms()

◆ ur_makeEnv()

◆ ur_makeThread()

◆ ur_push()

◆ ur_pushCell()

◆ ur_same()

◆ ur_seriesSlice()

◆ ur_seriesSliceM()

◆ ur_setWord()

◆ ur_threadContext()

◆ ur_tokenize()

◆ ur_tokenizeB()

◆ ur_toStr()

◆ ur_toText()

◆ ur_true()

◆ ur_wordCell()

◆ ur_wordCellM()