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

Object Dictionaries


Detailed Description

Mutable dictionaries of simple objects.

This module is provided as a convenience package for the C API, since the C standard libraries lack a generic dictionary type. The dictionaries provided by this package are mutable and synchronized. In a singe threaded environment (or if a dictionary is used only by a singe thread), unsynchronized method equivalents of the synchronized methods can be used. These unsynchronized methods are marked with the suffix _unlocked.

The dictionaries are represented by instances of the structure struct sobj_dict. The structure and the dictionary methods are declared in the include file <sobject/#dict.h>


Files

file  dict.h
 Public include file for simple object dictionaries.

Data Structures

struct  sobj_dict
 Simple object dictionary. More...

Functions

sobj_dictnew_sobj_dict (void)
 Create a new (empty) dictionary object.
sobj_dictnew_sobj_dict_from_array (struct sobj *sobj)
 Create a new dictionary object from an array object.
sobj_dictnew_sobj_dict_from_vec (unsigned n, const char **key, struct sobj **value)
 Create a new dictionary object from a vector of key/value pairs.
sobj_dictnew_sobj_dict_from_dict (struct sobj_dict *sobj_dict)
 Create a new dictionary object from a dictionary.
sobj_dictsobj_dict_clone (struct sobj_dict *sobj_dict)
 Create a flat copy of a dictionary object.
bool sobj_dict_put (struct sobj_dict *sobj_dict, const char *key, struct sobj *value)
 Insert an object into a dictionary.
bool sobj_dict_put_unlocked (struct sobj_dict *sobj_dict, const char *key, struct sobj *value)
 Insert an object into a dictionary.
sobjsobj_dict_get (struct sobj_dict *sobj_dict, const char *key)
 Get an object from the dictionary.
sobjsobj_dict_get_unlocked (struct sobj_dict *sobj_dict, const char *key)
 Get an object from the dictionary.
bool sobj_dict_remove (struct sobj_dict *sobj_dict, const char *key)
 Remove an object from a dictionary.
bool sobj_dict_remove_unlocked (struct sobj_dict *sobj_dict, const char *key)
 Remove an object from a dictionary.
void sobj_dict_clear (struct sobj_dict *sobj_dict)
 Remove all objects from the dictionary.
void sobj_dict_clear_unlocked (struct sobj_dict *sobj_dict)
 Remove all objects from the dictionary.
int sobj_dict_count (const struct sobj_dict *sobj_dict)
 Return the number object objects bound by the dictionary.
int sobj_dict_elements (struct sobj_dict *sobj_dict, char ***key_vec, struct sobj ***value_vec)
 Get the elements bound in the dictionary.
int sobj_dict_elements_unlocked (const struct sobj_dict *sobj_dict, const char **key_vec, struct sobj **value_vec)
 Get the elements bound in the dictionary.
void sobj_dict_prealloc (struct sobj_dict *sobj_dict, int count)
 Preallocate storage.
void sobj_dict_prealloc_unlocked (struct sobj_dict *sobj_dict, int count)
 Preallocate storage.
sobjsobj_dict_as_array (struct sobj_dict *sobj_dict, const char *cn)
 Create an array object representing the dictionary data.
sobjsobj_dict_as_array_unlocked (struct sobj_dict *sobj_dict, const char *cn)
 Create an array object representing the dictionary data.
void sobj_dict_dump (const struct sobj_dict *sobj_dict)
 Dump a text representation of the object dictionary to the standard error stream.


Function Documentation

struct sobj_dict* new_sobj_dict void   ) 
 

Create a new (empty) dictionary object.

A new dictionary object with a refcount of 0 is created.

Returns:
The new dictionary object.

struct sobj_dict* new_sobj_dict_from_array struct sobj sobj  ) 
 

Create a new dictionary object from an array object.

A new dictionary object with a refcount of 0 is created. The dictionary is initialized using an array object. All array elements with classless keys of type string are inserted into the dictionary (if multiple elements share the same keys, the last element with a specific key is used). Array elements with keys that are not of type string are ignored.

Parameters:
sobj The array object. If the object is NIL, an empty dictionary object is created. It is a fatal runtime error if the object is not of type nil or type array.
Returns:
The new dictionary object.
Note:
Keys of type string and associated with a class are ignored.

struct sobj_dict* new_sobj_dict_from_dict struct sobj_dict sobj_dict  ) 
 

Create a new dictionary object from a dictionary.

This function is an alias for sobj_dict_clone().

Parameters:
sobj_dict The dictionary object.
Returns:
The cloned dictionary object.
See also:
sobj_dict_clone().

struct sobj_dict* new_sobj_dict_from_vec unsigned  n,
const char **  key,
struct sobj **  value
 

Create a new dictionary object from a vector of key/value pairs.

A new dictionary object with a refcount of 0 is created. The dictionary is initialized using a key vector and a value vector. If a key appear more than once in the key vector, then the last key/value pairs matching that key is used.

Parameters:
n The number of elements in the key/value vectors.
key Vector of dictionary keys.
value Vector of dictionary values.
Returns:
The new dictionary object.

struct sobj* sobj_dict_as_array struct sobj_dict sobj_dict,
const char *  cn
 

Create an array object representing the dictionary data.

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

struct sobj* sobj_dict_as_array_unlocked struct sobj_dict sobj_dict,
const char *  cn
 

Create an array object representing the dictionary data.

Parameters:
sobj_dict The dictionary object.
cn The class name of the resulting object. This may be a null-pointer.
Returns:
An array object representing the dictionary data.
Note:
The dictionary is not locked while the operation is performed.

void sobj_dict_clear struct sobj_dict sobj_dict  ) 
 

Remove all objects from the dictionary.

Parameters:
sobj_dict The dictionary object.

void sobj_dict_clear_unlocked struct sobj_dict sobj_dict  ) 
 

Remove all objects from the dictionary.

Parameters:
sobj_dict The dictionary object.
Note:
The dictionary is not locked while the operation is performed.

struct sobj_dict* sobj_dict_clone struct sobj_dict sobj_dict  ) 
 

Create a flat copy of a dictionary object.

A flat copy of a dictionary object is created. The cloned dictionary holds (counted) references to the objects bound in the specified dictionary.

Parameters:
sobj_dict The dictionary object.
Returns:
The cloned dictionary object.

int sobj_dict_count const struct sobj_dict sobj_dict  ) 
 

Return the number object objects bound by the dictionary.

Parameters:
sobj_dict The dictionary object.
Returns:
The number of objects bound by the dictionary.

void sobj_dict_dump const struct sobj_dict sobj_dict  ) 
 

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

The function is intended as a debugging aid. It should not be used in a production environment.

Parameters:
sobj_dict The dictionary object.

int sobj_dict_elements struct sobj_dict sobj_dict,
char ***  key_vec,
struct sobj ***  value_vec
 

Get the elements bound in the dictionary.

Parameters:
sobj_dict The dictionary object.
key_vec If key_vec is not a null-pointer, a vector of dictionary keys is allocated from the heap and assigned to *key_vec. The strings stored to (*key_vec)[] are heap-allocated copies of the dictionary keys.
value_vec If value_vec is not a null-pointer, a vector of new references to the dictionary values is allocated from the heap (i.e. the reference counters are increased) and assigned to *value_vec.
Returns:
The function returns the number of key/value pairs bound in the dictionary.
Note:
Be careful to release all storage allocated by the function. You may use the following code fragment as a template:
          char **key_vec = 0;
          struct sobj **value_vec = 0;
          int i, n;
          n = sobj_dict_elements(sobj_dict, &key_vec, &value_vec);
          // Code
          for (i = 0; i < n; ++i) {
            if (key_vec[i]) sobj_free(key_vec[i]);
            if (value_vec[i]) SOBJ_RELEASE(value_vec[i]);
          }
          sobj_free(key_vec);
          sobj_free(value_vec);
See also:
sobj_dict_elements_unlocked().

int sobj_dict_elements_unlocked const struct sobj_dict sobj_dict,
const char **  key_vec,
struct sobj **  value_vec
 

Get the elements bound in the dictionary.

Parameters:
sobj_dict The dictionary object.
key_vec Vector receiving the dictionary keys. This may be a null-pointer.
value_vec Vector receiving the bound values. The references copied to the value_vec[] vector are borrowed from the dictionary (i.e. the reference counter is not increased). This may be a null-pointer.
Returns:
The function returns the number of key/value pairs bound in the dictionary.
Note:
Call sobj_dict_count() to get the sizes required for the key_vec and value_vec arrays.
See also:
sobj_dict_elements().

struct sobj* sobj_dict_get struct sobj_dict sobj_dict,
const char *  key
 

Get an object from the dictionary.

The function returns an object from the dictionary bound to the specified key.

Parameters:
sobj_dict The dictionary object.
key The dictionary key.
Returns:
The function returns a new reference the object bound to the specified key. If no object is bound to the specified key, a null-pointer is returned.
Note:
The dictionary is locked while the operation is performed.
See also:
sobj_dict_get_unlocked().

struct sobj* sobj_dict_get_unlocked struct sobj_dict sobj_dict,
const char *  key
 

Get an object from the dictionary.

The function returns an object from the dictionary bound to the specified key.

Parameters:
sobj_dict The dictionary object.
key The dictionary key.
Returns:
The function returns a borrowed reference the object bound to the specified key. If no object is bound to the specified key, a null-pointer is returned.
Note:
  • The dictionary is not locked while the lookup operation is performed.
  • The function returns a borrowed reference.
See also:
sobj_dict_get().

void sobj_dict_prealloc struct sobj_dict sobj_dict,
int  count
 

Preallocate storage.

This function provides a hint to the allocator of the dictionary about elements being added. If an application is able to estimate an upper bound for a number of objects being added to the dictionary and that estimate is likely to be precise, the application may call this function to provide that information to the dictionary. The allocator will reserve space in advance, possibly eliminating the need for several costly realloc() calls.

Parameters:
sobj_dict The dictionary object.
count The estimated number of objects being added to the dictionary.
See also:
sobj_dict_prealloc_unlocked().

void sobj_dict_prealloc_unlocked struct sobj_dict sobj_dict,
int  count
 

Preallocate storage.

This function provides a hint to the allocator of the dictionary about elements being added. If an application is able to estimate an upper bound for a number of objects being added to the dictionary and that estimate is likely to be precise, the application may call this function to provide that information to the dictionary. The allocator will reserve space in advance, possibly eliminating the need for several costly realloc() calls.

Parameters:
sobj_dict The dictionary object.
count The estimated number of objects being added to the dictionary.
Note:
The dictionary is not locked by the function.
See also:
sobj_dict_prealloc().

bool sobj_dict_put struct sobj_dict sobj_dict,
const char *  key,
struct sobj value
 

Insert an object into a dictionary.

Insert an object into the specified dictionary. If an object is already bound to the specified key, the bound object is replaced by the specified object.

Parameters:
sobj_dict The dictionary object.
key The dictionary key.
value The value to be bound to the specified key.
Return values:
false The object was inserted into the dictionary. No object was replaced.
true An already bound object was replaced by the specified object.
Note:
The dictionary is locked while the operation is performed.
See also:
sobj_dict_put_unlocked().

bool sobj_dict_put_unlocked struct sobj_dict sobj_dict,
const char *  key,
struct sobj value
 

Insert an object into a dictionary.

Insert an object into the specified dictionary. If an object is already bound to the specified key, the bound object is replaced by the specified object.

Parameters:
sobj_dict The dictionary object.
key The dictionary key.
value The value to be bound to the specified key.
Return values:
false The object was inserted into the dictionary. No object was replaced.
true An already bound object was replaced by the specified object.
Note:
The dictionary is not locked while the operation is performed.
See also:
sobj_dict_put().

bool sobj_dict_remove struct sobj_dict sobj_dict,
const char *  key
 

Remove an object from a dictionary.

The function removes the object from the dictionary that is bound to the specified key.

Parameters:
sobj_dict The dictionary object.
key The key to be unbound by the operation.
Return values:
true The key was found in the dictionary. The bound object was removed.
false The key was not found. The dictionary object is unchanged.

bool sobj_dict_remove_unlocked struct sobj_dict sobj_dict,
const char *  key
 

Remove an object from a dictionary.

The function removes the object from the dictionary that is bound to the specified key.

The dictionary is not locked while the operation is performed.

Parameters:
sobj_dict The dictionary object.
key The key to be unbound by the operation.
Return values:
true The key was found in the dictionary. The bound object was removed.
false The key was not found. The dictionary object is unchanged.


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