XCLE



List Object structure and methods

Instructions manual


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_List object type


Function XCLE_ListAlloc

XCLE_List XCLE_ListAlloc(void) ;
Allocates a new, empty, list.

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


Errors:
_ ENOMEM: if no memory was available



Function XCLE_ListAllocBlock

XCLE_List XCLE_ListAllocBlock(unsigned long numb) ;
Allocates a new, empty, list, with space reserved.

Args:
_ numb: size of space to reservate


Returns:
_ NULL: if no memory was available
else a new list, with space already allocated for 'numb' objects.


Errors:
_ ENOMEM: if no memory was available



Function XCLE_ListCopy

XCLE_List XCLE_ListCopy(XCLE_List lst) ;
Copies a List object and its contents.

Args:
_ lst: List object to copy


Returns:
_ NULL: if no memory was available
else a complete (recursive) copy of the List.


Errors:
_ EINVAL: if a NULL List was passed as argument
_ ENOMEM: if no memory was available

Note:
This method copies the List given, and fills it with copies of the original's
contents. Thus, this is a complete reallocation, and no memory buffer from the
original List is reused. The new objects' reference counts are set to zero,
while the originals' are unchanged.




Function XCLE_ListClone

XCLE_List XCLE_ListClone(XCLE_List lst) ;
Clones a List object.

Args:
_ lst


Returns:
_ NULL: if no memory was available
else a clone of the List object.


Errors:
_ EINVAL: if a NULL List was passed as argument
_ ENOMEM: if no memory was available

Note:
This method does only a "flat" copy of the List object, filling the copy with
direct references to the original's objects. The new List reference count is
set to zero, while the contained objects' reference counts are unchanged.




Function XCLE_ListDup

XCLE_List XCLE_ListUpRef(XCLE_List lst) ;
Increases the reference count of a List, and of all the objects it contains.

Args:
_ lst: the List to reference


Returns:
_ NULL: if a NULL List was passed as argument
else the original List object.


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



Function XCLE_ListDrop

XCLE_List XCLE_ListDrop(XCLE_List lst) ;
Decreases the reference count of a List, and of all the objects it contains.

Args:
_ lst: the List to dereference


Returns:
_ NULL: if a NULL List was passed as argument
else the original List object.


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



Function XCLE_ListFree

void XCLE_ListFree(XCLE_List lst) ;
Frees a List object, if its reference count is zero.

Args:
_ lst: List object to free




Function XCLE_ListLen

unsigned long XCLE_ListLen(XCLE_List lst) ;
Returns the length of a List.

Args:
_ lst: List to query


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


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



Function XCLE_ListGet

XCLE_Object XCLE_ListGet(XCLE_List lst, unsigned long pos) ;
Gets an object by its position in a List.

Args:
_ lst: List to query
_ pos: position of the object to retrieve


Returns:
_ -1: if a NULL List was passed as argument, or the index was out of range
else the retrieved object.


Errors:
_ EINVAL: if a NULL List was passed as argument, or the index was out of range



Function XCLE_ListPut

XCLE_Object XCLE_ListPut(XCLE_List lst, unsigned long pos, XCLE_Object obj) ;
Puts an object by its position in a List.

Args:
_ lst: List to update
_ pos: position of the object to put
_ obj: object to put into the List


Returns:
_ NULL: if a NULL List was passed as argument, or the index was out of range
else the original object that was at this position


Errors:
_ EINVAL: if a NULL List was passed as argument, or the index was out of range



Function XCLE_ListDel

XCLE_List XCLE_ListDel(XCLE_List lst, unsigned long beg, unsigned long end) ;
Deletes the objects in positions [beg,end[ in an List.

Args:
_ lst: List to update
_ beg: beginning of the section to cut, starting at 0
_ end: end of this section


Returns:
_ NULL: if a NULL List was passed, indexes were out of range, or a reallocation failed
else the original List.


Errors:
_ EINVAL: if a NULL List was passed as argument, or indexes were out of range
_ ENOMEM: if no memory was available



Function XCLE_ListIns

XCLE_List XCLE_ListIns(XCLE_List lst, unsigned long pos, XCLE_List lsi) ;
Inserts the objects of the second List in the first, between the pos-th and the pos+1-th objects.

Args:
_ lst: List to insert into
_ pos: position of insertion point, starting at 0
_ lsi: inserted List


Returns:
_ NULL: if a NULL List was passed, indexes were out of range, or a reallocation failed
else the first List, with the second's objects inserted.


Errors:
_ EINVAL: if a NULL List was passed as argument, or indexes were out of range
_ ENOMEM: if no memory was available

Note:
To prevent internal structures and memory corruption, 'lsi' is emptied after successfull
insertion. Using a null 'pos' means the second list is inserted at the very beginning
of 'lst', while a 'pos' equal to the first List length means to insert at the very end.




Function XCLE_ListPush

XCLE_List XCLE_ListPush(XCLE_List lst, XCLE_Object obj) ;
Adds an object at the end of a List.

Args:
_ lst: List to update
_ obj: object to append


Returns:
_ NULL: if a NULL List or object was passed as argument, or a reallocation failed
else the updated List, with the object appended.


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



Function XCLE_ListPop

XCLE_Object XCLE_ListPop(XCLE_List lst) ;
Deletes an object from the end of a List.

Args:
_ lst: List to update


Returns:
_ NULL: if a NULL List was passed as argument, the List was empty, or a reallocation failed
else the object deleted from the ned of the List.


Errors:
_ EINVAL: if a NULL List was passed as argument or the List was empty
_ ENOMEM: if no memory was available



Function XCLE_ListUnshift

XCLE_List XCLE_ListUnshift(XCLE_List lst, XCLE_Object obj) ;
Adds an object at the beginning of a List.

Args:
_ lst: List to update
_ obj: object to prepend


Returns:
_ NULL: if a NULL List was passed as argument or a reallocation failed
else the updated list, with the object prepended.


Errors:
_ EINVAL: if a NULL List was passed as argument
_ ENOMEM: if no memory was available



Function XCLE_ListShift

XCLE_Object XCLE_ListShift(XCLE_List lst) ;
Deletes an object from the beginning of a List.

Args:
_ lst: List to update


Returns:
_ NULL: if a NULL List was passed as argument, the List was empty, or a reallocation failed
else the object deleted from the beginning of the List.


Errors:
_ EINVAL: if a NULL List was passed as argument or the List was empty
_ ENOMEM: if no memory was available



Function XCLE_ListMap

unsigned long XCLE_ListMap(XCLE_List lst, , void * data) ;
Executes a function on all objects of a List, totalizing the return values.

OOPS:
Something was wrong here




Function XCLE_ListSort

XCLE_List XCLE_ListSort(XCLE_List lst, ) ;
Sorts a List, using the provided object comparison function.

OOPS:
Something was wrong here




Function XCLE_ListEqual

unsigned char XCLE_ListEqual(XCLE_List lst, XCLE_List lstw) ;
Compares two Lists.

Args:
_ lst: List object to compare
_ lstw: reference List


Returns:
_ -1: if a NULL List was passed as argument
_ 0: if the two Lists were distinct
_ +1: if the two Lists were identical (i.e., same length, and equal objects)


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



Generated by textdoc2html - 2006-02-22