Main Page | Modules | Alphabetical List | Data Structures | File List | Data Fields | Globals | Related Pages

Object Lists


Detailed Description

Mutable lists of simple objects.

This module is provided as a convenience package for the C API, since the C standard libraries lack a generic mutable list type. The lists provided by this package are mutable and synchronized. In a single threaded environment or if a list is used only be a single thread, the unsynchronized variants of the list API functions may be used instead. The unsynchronized variants are marked with the suffix _unlocked.

Simple object lists are represented by instances of the structure struct sobj_list. The incomplete structure type and the list API methods are declared in the include file <sobject/#list.h>.


Files

file  list.h
 Public include file for simple object lists.

Data Structures

struct  sobj_list
 Simple object list. More...

Functions

void sobj_list_dump (const struct sobj_list *sobj_list)
 Dump a text representation of the object list to the standard error stream.
sobj_listsobj_list::new_sobj_list (void)
 Create a new (empty) instance of a simple object list.
sobj_listsobj_list::new_sobj_list_from_array (struct sobj *sobj)
 Create a new instance of a simple object list from an array object.
sobj_listsobj_list::new_sobj_list_from_dict (struct sobj_dict *dict)
 Create a new instance of a simple object list from a simple object dictionary.
sobj_listsobj_list::new_sobj_list_from_vec (struct sobj **vec, int n)
 Create a new instance of a simple object list from a vector of element values.
sobj_listsobj_list::sobj_list_copy (struct sobj_list *list)
 Create a copy of a simple object list.
sobj_listsobj_list::sobj_list_copy_unlocked (struct sobj_list *list)
 Create a copy of a simple object list.
void sobj_list::sobj_list_append (struct sobj_list *list, struct sobj *value)
 Append an element to a simple objects list.
void sobj_list::sobj_list_append_unlocked (struct sobj_list *list, struct sobj *value)
 Append an element to a simple objects list.
int sobj_list::sobj_list_insert (struct sobj_list *list, int index, struct sobj *value)
 Insert an element into a simple objects list.
int sobj_list::sobj_list_insert_unlocked (struct sobj_list *list, int index, struct sobj *value)
 Insert an element into a simple objects list.
sobjsobj_list::sobj_list_remove (struct sobj_list *list, int index)
 Remove an indexed element from a simple objects list.
sobjsobj_list::sobj_list_remove_unlocked (struct sobj_list *list, int index)
 Remove an indexed element from a simple objects list.
int sobj_list::sobj_list_remove_object (struct sobj_list *list, struct sobj *value)
 Remove a value from a simple objects list.
int sobj_list::sobj_list_remove_object_unlocked (struct sobj_list *list, struct sobj *value)
 Remove a value from a simple objects list.
int sobj_list::sobj_list_remove_equal (struct sobj_list *list, struct sobj *value, struct sobj_env *env)
 Remove a value from a simple objects list.
int sobj_list::sobj_list_remove_equal_unlocked (struct sobj_list *list, struct sobj *value, struct sobj_env *env)
 Remove a value from a simple objects list.
int sobj_list::sobj_list_find (struct sobj_list *list, struct sobj *value)
 Find a value in a simple objects list.
int sobj_list::sobj_list_find_unlocked (struct sobj_list *list, struct sobj *value)
 Find a value in a simple objects list.
int sobj_list::sobj_list_find_equal (struct sobj_list *list, struct sobj *value, struct sobj_env *env)
 Find a value in a simple objects list.
int sobj_list::sobj_list_find_equal_unlocked (struct sobj_list *list, struct sobj *value, struct sobj_env *env)
 Find a value in a simple objects list.
void sobj_list::sobj_list_clear (struct sobj_list *list)
 Clear a simple objects list (remove all elements).
void sobj_list::sobj_list_clear_unlocked (struct sobj_list *list)
 Clear a simple objects list (remove all elements).
int sobj_list::sobj_list_count (struct sobj_list *list)
 Get the number of elements stored in a simple objects list.
bool sobj_list::sobj_list_is_empty (struct sobj_list *list)
 Check if the list is empty.
int sobj_list::sobj_list_get_elements (struct sobj_list *list, struct sobj ***vec)
 Get all elements stored in a simple objects list.
int sobj_list::sobj_list_get_elements_unlocked (struct sobj_list *list, struct sobj **vec)
 Get all elements stored in a simple objects list.
sobjsobj_list::sobj_list_as_array (struct sobj_list *list, const char *cn)
 Convert a list to a keyless simple object array representing the list.
sobjsobj_list::sobj_list_as_array_unlocked (struct sobj_list *list, const char *cn)
 Convert a list to a keyless simple object array representing the list.
sobjsobj_list::sobj_list_as_mapping (struct sobj_list *list, const char *cn)
 Convert a list to a simple object array representing a mapping.
sobjsobj_list::sobj_list_as_mapping_unlocked (struct sobj_list *list, const char *cn)
 Convert a list to a simple object array representing a mapping.


Function Documentation

struct sobj_list * new_sobj_list void   )  [related, inherited]
 

Create a new (empty) instance of a simple object list.

Returns:
The new instance.

struct sobj_list * new_sobj_list_from_array struct sobj sobj  )  [related, inherited]
 

Create a new instance of a simple object list from an array object.

The list will contain all values from the array object. The keys of the array object are ignored.

Parameters:
sobj The array object. It is a fatal runtime error if the specified object is not an array.
Returns:
The new instance.

struct sobj_list * new_sobj_list_from_dict struct sobj_dict dict  )  [related, inherited]
 

Create a new instance of a simple object list from a simple object dictionary.

The list will contain all values from the dictionary. The keys of the dictionary object are ignored.

Returns:
The new instance.

struct sobj_list * new_sobj_list_from_vec struct sobj **  vec,
int  n
[related, inherited]
 

Create a new instance of a simple object list from a vector of element values.

Parameters:
vec The vector of element values.
n The number of elements.
Returns:
The new instance.

void sobj_list_append struct sobj_list list,
struct sobj value
[related, inherited]
 

Append an element to a simple objects list.

Parameters:
list The list object.
value The element to be appended.

void sobj_list_append_unlocked struct sobj_list list,
struct sobj value
[related, inherited]
 

Append an element to a simple objects list.

This is the unsynchronized variant of sobj_list_append().

Parameters:
list The list object.
value The element to be appended.

struct sobj * sobj_list_as_array struct sobj_list list,
const char *  cn
[related, inherited]
 

Convert a list to a keyless simple object array representing the list.

Parameters:
list The list object.
cn The class name of the resulting object. This may be a null-pointer.
Returns:
An array object representing the list.

struct sobj * sobj_list_as_array_unlocked struct sobj_list list,
const char *  cn
[related, inherited]
 

Convert a list to a keyless simple object array representing the list.

This is the unsynchronized variant of sobj_list_as_array().

Parameters:
list The list object.
cn The class name of the resulting object. This may be a null-pointer.
Returns:
An array object representing the list.

struct sobj * sobj_list_as_mapping struct sobj_list list,
const char *  cn
[related, inherited]
 

Convert a list to a simple object array representing a mapping.

The list is converted to a mapping using the following rules (matched in the specified order):

  1. If a list element is a classless and keyless array (all keys are classless NIL objects) with exactly two elements, then the first element is interpreted as the key and the second element is interpreted as the value.
  2. If a list element is a classless array, then the array is appended to the resulting mapping array.
  3. If none of the above rules match, then the element is appended to the array, associated with a NIL key.

Parameters:
list The list object.
cn The class name of the resulting object. This may be a null-pointer.
Returns:
An array object representing the resulting mapping.

struct sobj * sobj_list_as_mapping_unlocked struct sobj_list list,
const char *  cn
[related, inherited]
 

Convert a list to a simple object array representing a mapping.

This is the unsynchronized variant of sobj_list_as_mapping().

Parameters:
list The list object.
cn The class name of the resulting object. This may be a null-pointer.
Returns:
An array object representing the resulting mapping.

void sobj_list_clear struct sobj_list list  )  [related, inherited]
 

Clear a simple objects list (remove all elements).

Parameters:
list The list object.

void sobj_list_clear_unlocked struct sobj_list list  )  [related, inherited]
 

Clear a simple objects list (remove all elements).

This is the unsynchronized variant of sobj_list_clear().

Parameters:
list The list object.

struct sobj_list * sobj_list_copy struct sobj_list list  )  [related, inherited]
 

Create a copy of a simple object list.

Returns:
The copied list.

struct sobj_list * sobj_list_copy_unlocked struct sobj_list list  )  [related, inherited]
 

Create a copy of a simple object list.

This is the unsynchronized variant of sobj_list_copy().

Returns:
The copied list.

int sobj_list_count struct sobj_list list  )  [related, inherited]
 

Get the number of elements stored in a simple objects list.

Parameters:
list The list object.
Returns:
The number of elements in the list.

void sobj_list_dump const struct sobj_list sobj_list  ) 
 

Dump a text representation of the object list to the standard error stream.

This function is intended for debugging only and should not be used by production code.

Parameters:
sobj_list The object list.

int sobj_list_find struct sobj_list list,
struct sobj value
[related, inherited]
 

Find a value in a simple objects list.

Parameters:
list The list object.
value The value to search for. This must be the same object as the object to be found in the list.
Returns:
The index of the first matching object or -1 of no matching object was found.

int sobj_list_find_equal struct sobj_list list,
struct sobj value,
struct sobj_env env
[related, inherited]
 

Find a value in a simple objects list.

Parameters:
list The list object.
value The value to search for. This must be an object equal to the object to be found in the list.
env The environment to be used for comparing objects. A null-pointer indicates that no environment should be used.
Returns:
The index of the first matching object or -1 of no matching object was found.

int sobj_list_find_equal_unlocked struct sobj_list list,
struct sobj value,
struct sobj_env env
[related, inherited]
 

Find a value in a simple objects list.

This is the unsynchronized variant of sobj_list_find_equal().

Parameters:
list The list object.
value The value to search for.
env The environment to be used for comparing objects. A null-pointer indicates that no environment should be used.
Returns:
The index of the first matching object or -1 of no matching object was found.

int sobj_list_find_unlocked struct sobj_list list,
struct sobj value
[related, inherited]
 

Find a value in a simple objects list.

This is the unsynchronized variant of sobj_list_find().

Parameters:
list The list object.
value The value to search for.
Returns:
The index of the first matching object or -1 of no matching object was found.

int sobj_list_get_elements struct sobj_list list,
struct sobj ***  vec
[related, inherited]
 

Get all elements stored in a simple objects list.

The function allocates a vector of pointers to new refereces to the element values stored in the list. The resulting vector is assigned to *vec and must be freed by the called (through sobj_free()).

Parameters:
list The list object.
vec Pointer to the variable receiving the vector of pointers. If the list is empty, then a null-pointer is assigned to *vec.
Returns:
The number of elements in the list.

int sobj_list_get_elements_unlocked struct sobj_list list,
struct sobj **  vec
[related, inherited]
 

Get all elements stored in a simple objects list.

Parameters:
list The list object.
vec Pointer to a vector receiving borrowed refereces to the element values stored in the list.
Returns:
The number of elements in the list.

int sobj_list_insert struct sobj_list list,
int  index,
struct sobj value
[related, inherited]
 

Insert an element into a simple objects list.

Parameters:
list The list object.
index The index position of the new element. Negative values are counted from the end of the list, -1 causes the element to be appended to the end of the list.
value The element to be inserted.
Returns:
The index of the inserted element. If the specified index was not valid (i.e. too small negative or too large positive), then the special error value -1 is returned.

int sobj_list_insert_unlocked struct sobj_list list,
int  index,
struct sobj value
[related, inherited]
 

Insert an element into a simple objects list.

This is the unsynchronized variant of sobj_list_insert().

Parameters:
list The list object.
index The index position of the new element.
value The element to be inserted.
Returns:
The index of the inserted element or -1.

bool sobj_list_is_empty struct sobj_list list  )  [related, inherited]
 

Check if the list is empty.

Parameters:
list The list object.
Return values:
true The list is empty.
false The list is not empty.

struct sobj * sobj_list_remove struct sobj_list list,
int  index
[related, inherited]
 

Remove an indexed element from a simple objects list.

Parameters:
list The list object.
index The index position of the element to be removed. Negative values are counted from the end of the list, where -1 causes the last element to be removed.
Returns:
A new referece to the element removed from the list. If the specified index was not valid, then a null-pointer is returned.

int sobj_list_remove_equal struct sobj_list list,
struct sobj value,
struct sobj_env env
[related, inherited]
 

Remove a value from a simple objects list.

If the specified value is contained in the list more than once, then only the first occurrence is removed.

Parameters:
list The list object.
value The value to be removed. The first value in the list that is equal to the specified value will be removed.
env The environment to be used for comparing objects. A null-pointer indicates that no environment should be used.
Returns:
The index of the object removed from the list. If the specified value was not found in the list, then the special value -1 is returned.

int sobj_list_remove_equal_unlocked struct sobj_list list,
struct sobj value,
struct sobj_env env
[related, inherited]
 

Remove a value from a simple objects list.

This is the unsynchronized variant of sobj_list_remove_equal().

Parameters:
list The list object.
value The value to be removed.
env The environment to be used for comparing objects. A null-pointer indicates that no environment should be used.
Returns:
The index of the object removed from the list or -1.

int sobj_list_remove_object struct sobj_list list,
struct sobj value
[related, inherited]
 

Remove a value from a simple objects list.

If the specified value is contained in the list more than once, then only the first occurrence is removed.

Parameters:
list The list object.
value The value to be removed. This must be the same object as the object to be removed from the list.
Returns:
The index of the object removed from the list. If the specified value was not found in the list, then the special value -1 is returned.

int sobj_list_remove_object_unlocked struct sobj_list list,
struct sobj value
[related, inherited]
 

Remove a value from a simple objects list.

This is the unsynchronized variant of sobj_list_remove_object().

Parameters:
list The list object.
value The value to be removed.
Returns:
The index of the object removed from the list or -1.

struct sobj * sobj_list_remove_unlocked struct sobj_list list,
int  index
[related, inherited]
 

Remove an indexed element from a simple objects list.

This is the unsynchronized variant of sobj_list_remove().

Parameters:
list The list object.
index The index position of the element to be removed.
Returns:
A new referece to the element removed from the list or a null-pointer.


Generated on Sat Jul 23 16:07:33 2005 for sobject by  doxygen 1.3.9.1