XCLE_Containers

XCLE: eXtensible Concatenative Language Engine
Copyright (C) 2000-2006 Yann LANDRIN-SCHWEITZER a.k.a. Varkhan

This library is free software; you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published
by the Free Software Foundation; either version 2.1 of the License, or
(at your option) any later version.

This library is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser
General Public License for more details.

You should have received a copy of the GNU Lesser General Public License
along with this library; if not, write to the Free Software Foundation,
Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

Author: Yann LANDRIN-SCHWEITZER
Contact: varkhan@varkhan.net
Homepage: http://www.varkhan.net/

XCLE_Stack definition

Function XCLE_StackAlloc

XCLE_Stack XCLE_StackAlloc(unsigned long chksz) ;
Allocates a new, empty Stack.

	Args:
		_ chksz	: buffer size increment

Returns:
	_ NULL	: if no memory was available
	else the newly allocated Stack.

	Errors:
		_ ENOMEM	: if no memory was available

Function XCLE_StackFree

void XCLE_StackFree(XCLE_Stack stk) ;
Frees a Stack, dereferences and frees its contents.

	Args:
		_ stk	: Stack to free

Function XCLE_StackDepth

unsigned long XCLE_StackDepth(XCLE_Stack stk) ;
Returns the depth (number of elements) of a Stack.

	Args:
		_ stk	: Stack we want to get information about

Returns:
	_ -1	: if a NULL Stack was passed as argument
	else the Stack's depth.

	Errors:
		_ EINVAL	: if a NULL Stack was passed as argument

Function XCLE_StackPush

unsigned long XCLE_StackPush(XCLE_Stack stk, XCLE_Object obj) ;
Pushes and references an object onto a Stack.

Args:
	_ stk	: Stack to push on
	_ obj	: object to push

Returns:
	_ -1	: if some error occurred
	else the new depth of the Stack.

Errors:
	_ EINVAL	: if a NULL Stack or object was passed as argument
	_ EACCES	: if the Stack was freezed and consequently cannot receive objects
	_ ENOMEM	: if no memory was available

Function XCLE_StackPop

XCLE_Object XCLE_StackPop(XCLE_Stack stk) ;
Pops and dereferences an object from a Stack.

	Args:
		_ stk	: non-empty Stack

Returns:
	_ NULL	: if the Stack was NULL, empty or freezed
	else the object popped from the stack.

Errors:
	_ EINVAL	: if a NULL Stack was passed as argument
	_ EACCES	: if the Stack was freezed and consequently cannot yield objects
	_ ENOMEM	: if a memory disallocation failed (non-fatal error)

Function XCLE_StackGet

XCLE_Object XCLE_StackGet(XCLE_Stack stk, unsigned long num) ;
Gets an object at a specified level of a Stack.

Args:
	_ stk	: non-empty Stack
	_ num	: level at which to look for an object

Returns:
	_ NULL	: if the XCLE_Stack was NULL, or the level invalid
	else the object at level 'num' of the Stack (first level is 1).

	Errors:
		_ EINVAL	: if a NULL or empty Stack was passed as argument, or the level was invalid

Function XCLE_StackPut

XCLE_Object XCLE_StackPut(XCLE_Stack stk, XCLE_Object obj, unsigned long num) ;
Puts an XCLE_Object at a specified level of a Stack.

Args:
	_ stk	: Stack to put in
	_ obj	: object to put
	_ num	: level at which to put an object

Returns:
	_ NULL	: if the Stack was NULL, or the level invalid
	else the old object at the specified level of the Stack (first level is 1).

	Errors:
		_ EINVAL	: if a NULL Stack or object was passed as argument, or the level was invalid

Function XCLE_StackMap

unsigned long XCLE_StackMap(XCLE_Stack stk, , void * dat) ;
Executes a map handler function on all objects of a Stack.

Args:
	_ stk	: Stack to map
	_ obj	: object to put
	_ map	: map handler
	_ dat	: user data pointer

Returns:
	_ -1	: if the Stack or the map handler were NULL
	_ -1	: if the map handler retuned -1 at some time
	else the sum of all the values returned by the map handler

Errors:
	_ EINVAL	: if a NULL Stack or object was passed as argument, or the level was invalid
	and any error generated by the map handler.

Note:
	The map handler takes several arguments:
	_ lvl	: the Stack level being currently mapped
	_ obj	: the Object at this level
	_ dat	: the user data pointer passed to XCLE_StackMap
	The mapping stops when all the non-empty levels have been mapped, or the map handler
	returns a value of ~0 (i.e. -1).

Function XCLE_StackChkType

unsigned long XCLE_StackChkType(XCLE_Stack stk, unsigned long argc, XCLE_Type * argt) ;
Checks the number and types of objects on an Stack.

Args:
	_ stk	: Stack to type-check
	_ argc	: number of objects to check
	_ argt	: types of objects to check (or-ed types of admissible objects, level by level)

Returns:
	_ -1	: if the Stack was NULL or there were not enough objects on Stack
	else an error flag (0 if all arguments were OK, every bit standing as an individual
	error flag for each level).

	Errors:
		_ EINVAL	: if a NULL Stack was passed as argument

Variables domain definition

Function XCLE_HashAlloc

XCLE_Hash XCLE_HashAlloc(unsigned long chksz) ;
Allocates an empty Hash.

	Args:
		_ chksz	: buffer size increment

Returns:
	_ NULL	: if no memory was available
	else a new empty Hash.

	Errors:
		_ ENOMEM	: if no memory was available

Function XCLE_HashFree

void XCLE_HashFree(XCLE_Hash hsh) ;
Frees a Hash, dereferences and frees its contents.

	Args:
		_ hsh	: XCLE_Hash to free

Function XCLE_HashGet

XCLE_Object XCLE_HashGet(XCLE_Hash hsh, char * name) ;
Gets an elements by its key in a Hash.

Args:
	_ hsh	: Hash to query
	_ name	: key, or "Object name"

Returns:
	_ NULL	: if a NULL Hash or name was passed as argument, or no object was indexed by this key
	else the Object under this 'name'.

Errors:
	_ EINVAL	: if a NULL Hash or name was passed as argument
	_ ENOMEM	: if no memory was available

Function XCLE_HashSet

XCLE_Object XCLE_HashSet(XCLE_Hash hsh, char * name, XCLE_Object obj) ;
Indexes an object under a key in a Hash, and reference it.

Args:
	_ hsh	: Hash to query
	_ name	: key, or "Object name"
	_ obj	: object to set under its "name"

Returns:
	_ NULL	: if some error occurred
	else the old object under this key, if it existed (and it is then dereferenced)
	or the object passed as argument.

Errors:
	_ EINVAL	: if a NULL Hash, name or object was passed as argument
	_ EACCES	: if the Hash was freezed and consequently cannot receive objects
	_ ENOMEM	: if no memory was available

Function XCLE_HashDel

XCLE_Object XCLE_HashDel(XCLE_Hash hsh, char * name) ;
Deletes a key and dereferences its contents in a Hash.

Args:
	_ hsh	: Hash to query
	_ name	: key, or "Object name"

Returns:
	_ NULL	: if a NULL Hash or name was passed as argument, or the key was not found
	else the object under name 'name'.

Errors:
	_ EINVAL	: if a NULL Hash or name was passed as argument
	_ EACCES	: if the Hash was freezed and consequently cannot yield objects
	_ ENOMEM	: if a disallocation failed (non-fatal error)

Function XCLE_HashMap

unsigned long XCLE_HashMap(XCLE_Hash hsh, , void * dat) ;
Executes a map handler function on all objects of a Hash.

Args:
	_ hsh	: Hash to map
	_ obj	: object to put
	_ map	: map handler
	_ dat	: user data pointer

Returns:
	_ -1	: if the Hash or the map handler were NULL
	_ -1	: if the map handler retuned -1 at some time
	else the sum of all the values returned by the map handler

Errors:
	_ EINVAL	: if a NULL Hash or object was passed as argument, or the level was invalid
	and any error generated by the map handler.

Note:
	The map handler takes several arguments:
	_ name	: the Hash key being currently mapped
	_ obj	: the Object at this level
	_ dat	: the user data pointer passed to XCLE_HashMap
	The mapping stops when all the keys have been mapped, or the map handler returns a
	value of ~0 (i.e. -1).

Generated by textdoc2html - 2006-02-22