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

Simple Objects C API


Files

file  sobject.h
 Public include file for the simple object library.
file  version.h
 Public include file providing the library version number through the macro SOBJ_VERSION.

Modules

group  Memory Management
 Functions and macros dealing with memory managenent.
group  Constructor Functions
 Constructor functions for creating simple object instances.
group  Byte Buffers
 Buffers for exchanging binary data with the simple objects API.
group  Object Building Functions
 Functions for building simple object instances from a format specification and a variable argument list.
group  Environments
 Functions dealing with simple object environments and class environments.
group  Find and Substitute
 This module provides methods for finding and substiting sub-objects of simple objects.
group  Object Modification Functions
 Create modified instances of simple objects.
group  Object Scanning Functions
 Functions for scanning values from structured objects.
group  Serialization
 Functions for simple objects serialization and de-serialization.
group  Type Testing
 Functions for testing the type and class of objects.

Data Structures

struct  sobj
 Simple object instance structure. More...

Defines

#define SOBJ_VERSION   "0.5.0"
 The library version number.

Enumerations

enum  sobj_msg_type { SOBJ_MSG_ERROR = 1, SOBJ_MSG_WARNING = 2, SOBJ_MSG_INFO = 3, SOBJ_MSG_DEBUG = 4 }
 Enumeration of message types. More...
enum  sobj_expr_type {
  SOBJ_EXPR_POS = 1, SOBJ_EXPR_NEG, SOBJ_EXPR_NOT, SOBJ_EXPR_PLUS,
  SOBJ_EXPR_MINUS, SOBJ_EXPR_MUL, SOBJ_EXPR_DIV, SOBJ_EXPR_MOD,
  SOBJ_EXPR_LS, SOBJ_EXPR_LS_APPROX, SOBJ_EXPR_LE, SOBJ_EXPR_LE_APPROX,
  SOBJ_EXPR_GT, SOBJ_EXPR_GT_APPROX, SOBJ_EXPR_GE, SOBJ_EXPR_GE_APPROX,
  SOBJ_EXPR_EQ, SOBJ_EXPR_EQ_APPROX, SOBJ_EXPR_NE, SOBJ_EXPR_NE_APPROX,
  SOBJ_EXPR_AND, SOBJ_EXPR_OR, SOBJ_EXPR_COND, SOBJ_EXPR_SEQ,
  SOBJ_EXPR_SEL, SOBJ_EXPR_INDEX, SOBJ_EXPR_CALL, SOBJ_EXPR_CAT
}
 Expression type enumeration for simple objects of type expr. More...
enum  sobj_type {
  SOBJ_TYPE_NIL = 0, SOBJ_TYPE_BOOL = 1, SOBJ_TYPE_INT = 2, SOBJ_TYPE_FLOAT = 3,
  SOBJ_TYPE_STRING = 4, SOBJ_TYPE_BINARY = 5, SOBJ_TYPE_ARRAY = 6, SOBJ_TYPE_EXPR = 7,
  SOBJ_TYPE_VREF = 8
}
 Object type enumeration. More...

Functions

sobjsobj_index (struct sobj *sobj, int index)
 Perform an index operation.
sobjsobj_slice (struct sobj *sobj, int lower_bound, int upper_bound)
 Perform a slice operation.
sobjsobj_select (struct sobj *sobj, struct sobj *key, struct sobj_env *env)
 Perform a selection operation.
sobjsobj_select_with_string (struct sobj *sobj, const char *key_string, struct sobj_env *env)
 Perform a selection operation using a string as the key.
sobjsobj_lookup (struct sobj *sobj, struct sobj *key, struct sobj_env *env)
 Perform a dictionary lookup operation.
sobjsobj_lookup_with_string (struct sobj *sobj, const char *key_string, struct sobj_env *env)
 Perform a dictionary lookup operation using a key string.
sobjsobj_call (struct sobj *sobj, const char *selector, struct sobj *args, struct sobj_env *env)
 Perform a method call on a simple object.
int sobj_index_of (struct sobj *sobj, struct sobj *key, struct sobj_env *env)
 Return the index of the element associated with the specified key.
int sobj_index_of_with_string (struct sobj *sobj, const char *key_string, struct sobj_env *env)
 Return the index of the element associated with the specified key.
sobjsobj_get (struct sobj *sobj, const char *address, bool pure, struct sobj_env *env)
 Get a subobject of the called object.
sobjsobj_get2 (struct sobj *sobj, struct sobj *address, bool pure, struct sobj_env *env)
 Get a subobject of the called object.
sobjsobj_getf (struct sobj *sobj, bool pure, struct sobj_env *env, const char *address_fmt,...)
 Get a subobject of the called object.
sobjsobj_vgetf (struct sobj *sobj, bool pure, struct sobj_env *env, const char *address_fmt, va_list ap)
 Get a subobject of the called object.
char * sobj_substring (struct sobj *sobj, int position, int count, struct sobj_env *env)
 Get a substring from the called object.
size_t sobj_string_length (struct sobj *sobj)
 Return the length of a string (number of UNICODE characters).
enum sobj_type sobj_type (struct sobj *sobj)
 Return the object type.
const char * sobj_typename (enum sobj_type type, bool upper)
 Return a type name string for the specified type.
const char * sobj_classname (struct sobj *sobj)
 Return the object class name.
unsigned long sobj_length (struct sobj *sobj)
 Return the length of the object.
size_t sobj_string_ucx (struct sobj *sobj, char *buffer, ptrdiff_t buffer_size)
 Get the extended UNICODE string from a string object.
sobjsobj_binary_type_id (struct sobj *sobj)
 Get the type id of a simple object of type binary.
const unsigned char * sobj_binary_data (struct sobj *sobj, size_t *length_ref)
 Get the data field of a simple object of type binary.
size_t sobj_binary_copy_data (struct sobj *sobj, unsigned char *buffer, ptrdiff_t buffer_size)
 Get the data field of a simple object of type binary.
int sobj_array_count (struct sobj *sobj)
 Get the number of elements stored in an array object.
void sobj_array_values (struct sobj *sobj, struct sobj **value)
 Get the values stored in an array object.
void sobj_array_keys (struct sobj *sobj, struct sobj **key)
 Get the keys stored in an array object.
sobjsobj_array_key (struct sobj *sobj, int index)
 Get an array key at a specified index.
sobjsobj_array_value (struct sobj *sobj, int index)
 Get an array value at a specified index.
const char * sobj_vref_ref (struct sobj *sobj)
 Get the reference string from a vref object.
enum sobj_expr_type sobj_expr_type (struct sobj *sobj)
 Get the expression type from an expression object.
int sobj_expr_op_count (struct sobj *sobj)
 Get the number of operands from an expression object.
int sobj_expr_op (struct sobj *sobj, struct sobj **op)
 Get the operands from an expression object.
sobjsobj_eval (struct sobj *sobj, struct sobj_env *env)
 Perform an object evaluation.
sobjsobj_resolve (struct sobj *sobj, bool recursive, struct sobj_env *env)
 Resolve variable references.
sobjsobj_copy (struct sobj *sobj)
 Create a (flat) copy of a simple object.
int sobj_compare (struct sobj *sobj, struct sobj *operand, struct sobj_env *env)
 Perform an ordered comparison of the called object with the specified object operand.
const char * sobj_version (const char *version)
 Get the library version number.
void sobj_cleanup (void)
 Final cleanup function.
void sobj_threads (void)
 Indicator function for POSIX threads support.
void sobj_mm_hooks (void)
 Indicator function for memory manager hooks support.
sobjsobj_address (const char *address, struct sobj_env *env)
 Convert an address string to an address object.
void sobj_address_string (struct sobj *address, struct sobj_buffer *buffer, struct sobj_env *env)
 Convert an address object to an address string.
bool sobj_to_bool (struct sobj *sobj, bool *error)
 Convert a simple object to bool.
int sobj_to_int (struct sobj *sobj, bool *error)
 Convert a simple object to int.
long sobj_to_long (struct sobj *sobj, bool *error)
 Convert a simple object to long.
long long sobj_to_long_long (struct sobj *sobj, bool *error)
 Convert a simple object to long long.
unsigned sobj_to_unsigned (struct sobj *sobj, bool *error)
 Convert a simple object to unsigned.
unsigned long sobj_to_unsigned_long (struct sobj *sobj, bool *error)
 Convert a simple object to unsigned long.
unsigned long long sobj_to_unsigned_long_long (struct sobj *sobj, bool *error)
 Convert a simple object to unsigned long long.
int8_t sobj_to_int8_t (struct sobj *sobj, bool *error)
 Convert a simple object to int8_t.
int16_t sobj_to_int16_t (struct sobj *sobj, bool *error)
 Convert a simple object to int16_t.
int32_t sobj_to_int32_t (struct sobj *sobj, bool *error)
 Convert a simple object to int32_t.
int64_t sobj_to_int64_t (struct sobj *sobj, bool *error)
 Convert a simple object to int64_t.
intmax_t sobj_to_intmax_t (struct sobj *sobj, bool *error)
 Convert a simple object to intmax_t.
uint8_t sobj_to_uint8_t (struct sobj *sobj, bool *error)
 Convert a simple object to uint8_t.
uint16_t sobj_to_uint16_t (struct sobj *sobj, bool *error)
 Convert a simple object to uint16_t.
uint32_t sobj_to_uint32_t (struct sobj *sobj, bool *error)
 Convert a simple object to uint32_t.
uint64_t sobj_to_uint64_t (struct sobj *sobj, bool *error)
 Convert a simple object to uint64_t.
uintmax_t sobj_to_uintmax_t (struct sobj *sobj, bool *error)
 Convert a simple object to uintmax_t.
size_t sobj_to_size_t (struct sobj *sobj, bool *error)
 Convert a simple object to size_t.
ptrdiff_t sobj_to_ptrdiff_t (struct sobj *sobj, bool *error)
 Convert a simple object to ptrdiff_t.
float sobj_to_float (struct sobj *sobj, bool *error)
 Convert a simple object to float.
double sobj_to_double (struct sobj *sobj, bool *error)
 Convert a simple object to double.
size_t sobj_to_string (struct sobj *sobj, char *buffer, ptrdiff_t buffer_size)
 Convert a simple object to a string.
char * sobj_str (struct sobj *sobj, struct sobj_env *env)
 Create a string representation of a simple object.


Define Documentation

#define SOBJ_VERSION   "0.5.0"
 

The library version number.

The version number is always encoded as a string of the form x.x.x or x.x.x-extra (where x is a decimal number and extra is an arbitrary string).


Enumeration Type Documentation

enum sobj_expr_type
 

Expression type enumeration for simple objects of type expr.

Enumeration values:
SOBJ_EXPR_POS  Unary positive expression.
SOBJ_EXPR_NEG  Unary arithmetic negation expression.
SOBJ_EXPR_NOT  Unary locical NOT expression.
SOBJ_EXPR_PLUS  Binary PLUS expression.
SOBJ_EXPR_MINUS  Binary MINUS expression.
SOBJ_EXPR_MUL  Binary multiplication expression.

SOBJ_EXPR_DIV  Binary divide expression.
SOBJ_EXPR_MOD  Binary modulo expression.
SOBJ_EXPR_LS  Less-than comparison expression.

SOBJ_EXPR_LS_APPROX  Approximate less-than comparison expression.
SOBJ_EXPR_LE  Less-or-equal comparison expression.
SOBJ_EXPR_LE_APPROX  Approximate less-or-equal comparison expression.
SOBJ_EXPR_GT  Greater-than comparison expression.
SOBJ_EXPR_GT_APPROX  Approximate greater-than comparison expression.
SOBJ_EXPR_GE  Greater-or-equal comparison expression.
SOBJ_EXPR_GE_APPROX  Approximate greater-or-equal comparison expression.
SOBJ_EXPR_EQ  Equality comparison expression.

SOBJ_EXPR_EQ_APPROX  Approximate equality comparison expression.
SOBJ_EXPR_NE  Non-equality comparison expression.
SOBJ_EXPR_NE_APPROX  Approximate non-equality comparison expression.
SOBJ_EXPR_AND  Binary logical AND expression.
SOBJ_EXPR_OR  Binary logical OR expression.
SOBJ_EXPR_COND  Conditional expression.
SOBJ_EXPR_SEQ  Sequential expression.
SOBJ_EXPR_SEL  Selection expression.
SOBJ_EXPR_INDEX  Index expression.
SOBJ_EXPR_CALL  Method call expression.
SOBJ_EXPR_CAT  Concatenation expression.

enum sobj_msg_type
 

Enumeration of message types.

Enumeration values:
SOBJ_MSG_ERROR  Error message.
SOBJ_MSG_WARNING  Waring message.
SOBJ_MSG_INFO  Info message.

The message should be logged but does not indicate a problem.

SOBJ_MSG_DEBUG  Debugging message.

These message may be discarded in a production environment.

enum sobj_type
 

Object type enumeration.

Enumeration values:
SOBJ_TYPE_NIL  Object type nil.
SOBJ_TYPE_BOOL  Object type bool.
SOBJ_TYPE_INT  Object type int.
SOBJ_TYPE_FLOAT  Object type float.
SOBJ_TYPE_STRING  Object type string.
SOBJ_TYPE_BINARY  Object type binary.
SOBJ_TYPE_ARRAY  Object type array.
SOBJ_TYPE_EXPR  Object type expr.
SOBJ_TYPE_VREF  Object type vref.


Function Documentation

struct sobj* sobj_address const char *  address,
struct sobj_env env
 

Convert an address string to an address object.

The function converts an address string compatible with sobj_get() or sobj_set() to an address object.

If the specified address string is empty or starts with an bracket or dot, the string "NIL" is prepended. If the address string starts with a star ('*'), the star character is skipped and the address string is converted as is.

Parameters:
address The address string.
env The environment to be used for decoding (unpacking) the address string. This may be a null-pointer.
Returns:
If the address string could be converted, the corresponding address object is returned. In case of a conversion error, a null-pointer is returned.

void sobj_address_string struct sobj address,
struct sobj_buffer buffer,
struct sobj_env env
 

Convert an address object to an address string.

The function creates a serialization of the specified address object. If the serialization starts with the string prefix "(nil." or "(nil[", then the initial "(nil" and the trailing ")" is removed from the address string.

Parameters:
address The address object.
env The environment to be used. This may be a null-pointer.
buffer Buffer receiving the address string. The buffer is cleared before the address string is written to the buffer.

int sobj_array_count struct sobj sobj  ) 
 

Get the number of elements stored in an array object.

It is a fatal runtime error if the called object is not of type array.

Parameters:
sobj The called object.
Returns:
The number of elements in the array object.

struct sobj* sobj_array_key struct sobj sobj,
int  index
 

Get an array key at a specified index.

It is a fatal runtime error if the called object is not of type array.

Parameters:
sobj The called object.
index The index of the element. Negative values count from the end of the array (-1 addresses the last array element). It is a fatal runtime error if the specified index is out of bounds.
Returns:
The key of the specified element.

void sobj_array_keys struct sobj sobj,
struct sobj **  key
 

Get the keys stored in an array object.

It is a fatal runtime error if the called object is not of type array.

Parameters:
sobj The called object.
key Vector receiving pointers to the keys stored in the array. The reference counter of the keys stored to key[] is not increased. Note that classless NIL objects are represented by null-pointers.
The caller must make sure that the vector value is large enough to hold all values. The function sobj_array_count() can be used to determine the number of elements stored in an array.

struct sobj* sobj_array_value struct sobj sobj,
int  index
 

Get an array value at a specified index.

It is a fatal runtime error if the called object is not of type array.

Parameters:
sobj The called object.
index The index of the element. Negative values count from the end of the array (-1 addresses the last array element). It is a fatal runtime error if the specified index is out of bounds.
Returns:
The value of the specified element.

void sobj_array_values struct sobj sobj,
struct sobj **  value
 

Get the values stored in an array object.

It is a fatal runtime error if the called object is not of type array.

Parameters:
sobj The called object.
value Vector receiving pointers to the values stored in the array. The reference counter of the values stored to value[] is not increased.
The caller must make sure that the vector value is large enough to hold all values. The function sobj_array_count() can be used to determine the number of elements stored in an array.

size_t sobj_binary_copy_data struct sobj sobj,
unsigned char *  buffer,
ptrdiff_t  buffer_size
 

Get the data field of a simple object of type binary.

It is a fatal runtime error if the called object is not of type binary. The function creats a copy of the data field.

Parameters:
sobj The called object.
buffer Pointer to the buffer receiving the copy of the data field. If this is a null-pointer, the data field will not be copied.
buffer_size The size of the buffer receiving the copy of the data field. No more than buffer_size bytes are written to buffer.
Returns:
The function returns the number of bytes in the data field of the simple object.

const unsigned char* sobj_binary_data struct sobj sobj,
size_t *  length_ref
 

Get the data field of a simple object of type binary.

It is a fatal runtime error if the called object is not of type binary.

Parameters:
sobj The called object.
length_ref If length_ref is not a null-pointer, the length (i.e. the number of bytes) of the data field is copied to *length_ref.
Returns:
A pointer to the data buffer of the object. The data in the buffer may not be modified by the caller. Use sobj_binary_copy_data() if you need to modify the data.

struct sobj* sobj_binary_type_id struct sobj sobj  ) 
 

Get the type id of a simple object of type binary.

It is a fatal runtime error if the called object is not of type binary.

Parameters:
sobj The called object.
Returns:
The type id of the object.

struct sobj* sobj_call struct sobj sobj,
const char *  selector,
struct sobj args,
struct sobj_env env
 

Perform a method call on a simple object.

The function performs a method call on a simple object. A call operation is performed on a selection expression, where the left operand is the called object and the right operand is the method selector.

If the called object sobj is a classless selection expression, the class name for the environment class is taken from the left operand of the expression, else the class name is taken from the called object sobj itself.

Instead of specifying a selection expression, the convenience parameter selector can be used to create a selection expression on the fly.

Parameters:
sobj The called object.
selector Convenience parameter. If this is not a null-pointer, a classless selection expression is created and used as the called object. The left operand if the selection expression is the parameter sobj and the right operand is a string object created from the UTF-8 encoded UNICODE string selector (note that selector is not an extended UNICODE string).
args The argument array passed to the called method. A null-pointer or a NIL object represents an empty argument array. It is a runtime error if args is not null, NIL, or of type array.
env The environment for resolving the call operation. This may be a null-pointer.
Returns:
The function returns the object returned by the appropriate callback function from the environment. In case of an error, null is returned and the error flag of the environment object is set.
Note:
If no environment is specified (i.e. env is null), then a null-pointer is returned.

const char* sobj_classname struct sobj sobj  ) 
 

Return the object class name.

Parameters:
sobj The called object.
Returns:
The object class name. If no class name is associated with the object, a null-pointer is returned.

void sobj_cleanup void   ) 
 

Final cleanup function.

The function release all heap stored allocated by the simple object library. Calling a simple object function after sobj_cleanup() has been called yields undefined results.

int sobj_compare struct sobj sobj,
struct sobj operand,
struct sobj_env env
 

Perform an ordered comparison of the called object with the specified object operand.

Variable references in strings are resolved before the objects are compared. Objects of type vref are not resolved.

Parameters:
sobj The called object.
operand The operand compared with the called object.
env The environment. This may be a null-pointer.
The function implements the following order.
  1. Class name. Objects are compared by class name first. The class names are compared using the strcmp() function. Since the class names are encoded as UTF-8, the resulting order is the UNICODE codepoint order. Classless objects are sorted first.
  2. Object type. Object types are ordered using the enumeration order of enum sobj_type.
  3. Object value.
    • Numerical and boolean values are compared canonically.
    • Strings are compared using the strcmp() function. If a string contains variable references, these are resolved before the string values are compared.
    • Binary objects are compared by ID first. If the IDs are equal, the binary data buffers are compared lexically.
    • Arrays are compared lexically, array elements are compared lexically as (key, value) tuples.
    • Expressions are compared by expression type (using the enumeration order of enum sobj_expr_type). Expressions of the same type are compared lexically.
    • Variable references are compared by comparing the reference strings using the strcmp() function.

Note:
This comparison function implies a total order on simple object values. This order depends on the variable resolution method so_vref() or so_vref_str() of the environment object env.
Return values:
-1 The called object sobj is smaller than the operand.
0 The called object sobj and the operand are equal after resolving variable references in strings.
1 The called object sobj is greater than the operand.

struct sobj* sobj_copy struct sobj sobj  ) 
 

Create a (flat) copy of a simple object.

The function creates a flat copy of a simple object. A flat copy is a copy where only the top-level object is replacated. The copied object will reference the same nested objects as the original object.

See the Copying Objects page for a discussion of copying objects.

Parameters:
sobj The object to be copied.
Returns:
The copied object.

struct sobj* sobj_eval struct sobj sobj,
struct sobj_env env
 

Perform an object evaluation.

The semantics of an evaluation operation depends on the object type:

  • string. If the string object contains variable references, these variable references are resolved.
  • vref. The variable reference is resolved. If the resulting object is of type string or expression, the sobj_eval() function is called again on the result, respecting the class ID of the result.
  • expr. If a class environment is associated with the object, the eval() method of that environment is called to perform the evaluation. The first operand is evaluated recursively before the class environment lookup is performed, so the class ID of the evaluated first operand determines the class environment.
  • For all other types the called object is returned.

Note:
The sobj_eval() function calles itself recursively only if an object of type vref resolves to an object of type string or expr. As a consequence, at most one extra recursion per level is performed.

If the evaluation fails, the error flag of the environment is set.

Parameters:
sobj The called object.
env The environment used for evaluation. This may be a null-pointer.
Returns:
The function returns the result of the evaluation or a null-pointer if the evaluation failed.

int sobj_expr_op struct sobj sobj,
struct sobj **  op
 

Get the operands from an expression object.

It is a fatal runtime error if the called object is not of type expr.

Parameters:
sobj The called object.
op Vector receiving pointers to the operand objects. The reference counter is not increased for the operand objects stored to op[]. op may be a null-pointer.
Returns:
The number of operands.

int sobj_expr_op_count struct sobj sobj  ) 
 

Get the number of operands from an expression object.

It is a fatal runtime error if the called object is not of type expr.

Parameters:
sobj The called object.
Returns:
The number of operands.

enum sobj_expr_type sobj_expr_type struct sobj sobj  ) 
 

Get the expression type from an expression object.

It is a fatal runtime error if the called object is not of type expr.

Parameters:
sobj The called object.
Returns:
The expression type.

struct sobj* sobj_get struct sobj sobj,
const char *  address,
bool  pure,
struct sobj_env env
 

Get a subobject of the called object.

Parameters:
sobj The called object.
address The address of the subobject. The string address is interpreted as a text serialization of a binary object. If the first non-whitespace character of address is a dot (.) or opening bracket ([), the string "NIL" is prepended to the address. If the address starts with a star (*), the star character is skipped. Use the star-prefix to supress the NIL-prefix.
pure Flag indicating that pure address resolution should be used.
env The environment. This may be a null-pointer.
Returns:
The function returns the specified subobject. The function returns a null-pointer if the pure flag was selected an the address does not resolve to a subobject of the called object.

struct sobj* sobj_get2 struct sobj sobj,
struct sobj address,
bool  pure,
struct sobj_env env
 

Get a subobject of the called object.

Parameters:
sobj The called object.
address The address of the subobject.
pure Flag indicating that pure address resolution should be used.
env The environment. This may be a null-pointer.
Returns:
The function returns the specified subobject. The function returns a null-pointer if the pure flag was selected an the address does not resolve to a subobject of the called object.

struct sobj* sobj_getf struct sobj sobj,
bool  pure,
struct sobj_env env,
const char *  address_fmt,
  ...
 

Get a subobject of the called object.

This function is a variant of the sobj_get() function, where the address is specified using a printf-style format string an variable format arguments.

Parameters:
sobj The called object.
pure Flag indicating that pure address resolution should be used.
env The environment. This may be a null-pointer.
address_fmt The format string for the address of the subobject.
... Variable arguments specified in the format string address_fmt.
Returns:
The function returns the specified subobject. The function returns a null-pointer if the pure flag was selected an the address does not resolve to a subobject of the called object.

struct sobj* sobj_index struct sobj sobj,
int  index
 

Perform an index operation.

The called object has to be a valid sequence object for the operation. For an index operation, this is one of array, string, expr. If the called object is not a valid sequence, a classless index expression is created where the first operand is the called object sobj and the second operand (the index array) holds a single integer object (type int) representing the value of the parameter index.

Parameters:
sobj The called object.
index The index in the index operation.
Returns:
The function returns the result of the index operation.

int sobj_index_of struct sobj sobj,
struct sobj key,
struct sobj_env env
 

Return the index of the element associated with the specified key.

It is a fatal runtime error if the called object is not of type array.

Parameters:
sobj The called object.
key The key to look for.
env The environment used for comparing the keys. This may be a null-pointer.
Returns:
The function returns the index of the last element in the array matching the specified key or -1 if the specified key was not found.
See also:
sobj_index_of_with_string().

int sobj_index_of_with_string struct sobj sobj,
const char *  key_string,
struct sobj_env env
 

Return the index of the element associated with the specified key.

It is a fatal runtime error if the called object is not of type array. This is a variant of the sobj_index_of() function.

Parameters:
sobj The called object.
key_string The key to look for, represented as a raw UTF-8 encoded UNICODE string.
env The environment used for comparing the keys. This may be a null-pointer.
Returns:
The function returns the index of the last element in the array matching the specified key or -1 if the specified key was not found.
See also:
sobj_index_of().

unsigned long sobj_length struct sobj sobj  ) 
 

Return the length of the object.

The length of an object is defined as follows:

  • Objects of type nil have the length 0.
  • Objects of type bool have the length 1.
  • The length of objects of type int or float is undefined, but may be defined in a later version of the library. The current implementation will return the length 1 for these objects, but applications should not rely on this behavior.
  • The length of string objects is defined as the number of UNICODE characters in the string. Variable references are counted as single characters. This is compatible with the sobj_string_length() function.
  • The length of a binary object is the number of bytes stored in the body of the binary object (as returned by sobj_binary_data()).
  • For objects of type array, the length is the number of elements stored in the array. This is compatible with sobj_array_count().
  • The length of an expr object is the number of operands of the top-level expression (either 1, 2, or 3). This is compatible with sobj_expr_op_count().
  • The length of a vref object is 1.

Parameters:
sobj The called object. If this is a null-pointer, then the function will return 0.
Returns:
The length of the object.

struct sobj* sobj_lookup struct sobj sobj,
struct sobj key,
struct sobj_env env
 

Perform a dictionary lookup operation.

It is a fatal runtime error of the called object is not of type array.

Parameters:
sobj The called object.
key The key of the desired element.
env The environment used for comparison of the keys with the specified selector. This may be a null-pointer.
Returns:
The function returns the value bound to the specified key or a null-pointer if the specified key is not bound.
See also:
sobj_lookup_with_string().

struct sobj* sobj_lookup_with_string struct sobj sobj,
const char *  key_string,
struct sobj_env env
 

Perform a dictionary lookup operation using a key string.

This is a convenience function calling sobj_lookup().

Parameters:
sobj The called object.
key_string The key of the desired element, represented as a raw UTF-8 encoded UNICODE string.
env The environment used for comparison of the keys with the specified selector. This may be a null-pointer.
Returns:
The function returns the value bound to the specified key or a null-pointer if the specified key is not bound.
See also:
sobj_lookup().

void sobj_mm_hooks void   ) 
 

Indicator function for memory manager hooks support.

This function is present only if the SObject library was compiled with memory manager hooks support. The function does nothing. The function can be used to check for memory manager hooks support through an Autoconf configure script.

struct sobj* sobj_resolve struct sobj sobj,
bool  recursive,
struct sobj_env env
 

Resolve variable references.

The function may operate recursively on all contained objects. An object of type string is replaced by a string with all variable references resolved. An object of type vref is resolved. All other objects are kept unchanged.

Parameters:
sobj The called object.
recursive Flag indicating if the function should operate recursively. If this flag is set, the function operates on all objects contained in the called object. If the flag is clear, the function operates only on the called object itself.
env The environment used for variable resolution. This may be a null-pointer.
Returns:
The function returns the resolved object.

struct sobj* sobj_select struct sobj sobj,
struct sobj key,
struct sobj_env env
 

Perform a selection operation.

The called object is the dictionary of the operation and has to be of type array. If the dictionary is not of type array or the dictionary does not contain the specified key, the object returned is a (classless) selection expression where the first operand is the called object sobj and the second operand is the selector (key).

Parameters:
sobj The called object.
key The selector of the selection operation.
env The environment used for comparison of the keys with the specified selector. This may be a null-pointer.
Returns:
The function returns the result of the selection operation.
See also:
sobj_select_with_string().

struct sobj* sobj_select_with_string struct sobj sobj,
const char *  key_string,
struct sobj_env env
 

Perform a selection operation using a string as the key.

This is a convenience function calling sobj_select().

Parameters:
sobj The called object.
key_string The selector of the selection operation, represented as a raw UTF-8 encoded UNICODE string.
env The environment used for comparison of the keys with the specified selector. This may be a null-pointer.
Returns:
The function returns the result of the selection operation.
See also:
sobj_select().

struct sobj* sobj_slice struct sobj sobj,
int  lower_bound,
int  upper_bound
 

Perform a slice operation.

The called object has to be a valid sequence object for the operation. For a slice operation, this is either array or string. If the called object is not a valid sequence, a classless index expression is created where the first operand is the called object sobj and the second operand (the index array) holds two integer objects (type int) representing the value of the parameters lower_bound and upper_bound.

Parameters:
sobj The called object.
lower_bound The (inclusive) lower bound of the slice operation.
upper_bound The (exclusive) upper bound of the slice operation.
Returns:
The function returns the result of the slice operation.

char* sobj_str struct sobj sobj,
struct sobj_env env
 

Create a string representation of a simple object.

The function creats a string representation of a simple object. The so_str() method of the environment object is used to create the string representation. If the so_str() method returns a null-pointer, the function sobj_to_string() is used to create the string representation.

Parameters:
sobj The called object.
env The environment used for string conversion. This may be a null-pointer.
Returns:
The function returns a heap allocated, null-terminated string representation of the called object.

size_t sobj_string_length struct sobj sobj  ) 
 

Return the length of a string (number of UNICODE characters).

The function returns the number of UNICODE characters and variable references in a string object. A variable reference counts as a single character.

Parameters:
sobj The called object. It is a fatal runtime error if the called object is not of type string.
Returns:
The number of UNICODE character and variable references in the specified string object.

size_t sobj_string_ucx struct sobj sobj,
char *  buffer,
ptrdiff_t  buffer_size
 

Get the extended UNICODE string from a string object.

It is a fatal runtime error if the called object is not of type string (i.e. SOBJ_TYPE_STRING or SOBJ_TYPE_ISTRING).

Parameters:
sobj The called object.
buffer Pointer to a buffer receiving a copy of the extended UNICODE string. If this is null, no copy is made.
buffer_size Size of the buffer referenced by buffer.
Returns:
The function returns the size of the extended UNICODE string as the number of bytes required to storage the characters, not including the terminating null-character.
Note:
Do not use the sobj_string_length() function to determine the size of the buffer, since sobj_string_length() returns the number of UNICODE characters and top-level variable references, not the number of bytes required to store the extended UNICODE string. Call sobj_string_ucx() with buffer == null instead.

char* sobj_substring struct sobj sobj,
int  position,
int  count,
struct sobj_env env
 

Get a substring from the called object.

The called object has to be of type string. It is a fatal runtime error if the called object in not of type string

Parameters:
sobj The called object.
position The position of the first character of the substring. Negative values are counted from the end of the string (e.g. the value -1 selects the last character of the string). If the position is out of bounds, it is silently clipped to valid values.
count The length of the selected substring (number of UNICODE characters). If the value is -1 or larger that the number of UNICODE characters following the specified position, the entire rest of the string is selected. Values smaller than -1 cause a fatal runtime error.
env The environment used for resolving variable references in the string. This may be a null-pointer.
Returns:
The function returns the selected substring. The storage for the returned string is allocated from the heap. The caller is responsible for releasing the storage.

void sobj_threads void   ) 
 

Indicator function for POSIX threads support.

This function is present only if the SObject library was compiled with threads support. The function does nothing. The function can be used to check for SObject threads support through an Autoconf configure script.

bool sobj_to_bool struct sobj sobj,
bool *  error
 

Convert a simple object to bool.

Parameters:
sobj The object.
error In case of a conversion error and if error is not a null-pointer, *error is set to true.
Returns:
The function returns the result of the conversion. In case of an error, false is returned.

double sobj_to_double struct sobj sobj,
bool *  error
 

Convert a simple object to double.

Parameters:
sobj The object.
error In case of a conversion error and if error is not a null-pointer, *error is set to true.
Returns:
The function returns the result of the conversion. In case of an error, 0.0 is returned.

float sobj_to_float struct sobj sobj,
bool *  error
 

Convert a simple object to float.

Parameters:
sobj The object.
error In case of a conversion error and if error is not a null-pointer, *error is set to true.
Returns:
The function returns the result of the conversion. In case of an error, 0.0 is returned.

int sobj_to_int struct sobj sobj,
bool *  error
 

Convert a simple object to int.

Parameters:
sobj The object.
error In case of a conversion error and if error is not a null-pointer, *error is set to true.
Returns:
The function returns the result of the conversion. In case of an error, 0 is returned.

int16_t sobj_to_int16_t struct sobj sobj,
bool *  error
 

Convert a simple object to int16_t.

Parameters:
sobj The object.
error In case of a conversion error and if error is not a null-pointer, *error is set to true.
Returns:
The function returns the result of the conversion. In case of an error, 0 is returned.

int32_t sobj_to_int32_t struct sobj sobj,
bool *  error
 

Convert a simple object to int32_t.

Parameters:
sobj The object.
error In case of a conversion error and if error is not a null-pointer, *error is set to true.
Returns:
The function returns the result of the conversion. In case of an error, 0 is returned.

int64_t sobj_to_int64_t struct sobj sobj,
bool *  error
 

Convert a simple object to int64_t.

Parameters:
sobj The object.
error In case of a conversion error and if error is not a null-pointer, *error is set to true.
Returns:
The function returns the result of the conversion. In case of an error, 0 is returned.

int8_t sobj_to_int8_t struct sobj sobj,
bool *  error
 

Convert a simple object to int8_t.

Parameters:
sobj The object.
error In case of a conversion error and if error is not a null-pointer, *error is set to true.
Returns:
The function returns the result of the conversion. In case of an error, 0 is returned.

intmax_t sobj_to_intmax_t struct sobj sobj,
bool *  error
 

Convert a simple object to intmax_t.

Parameters:
sobj The object.
error In case of a conversion error and if error is not a null-pointer, *error is set to true.
Returns:
The function returns the result of the conversion. In case of an error, 0 is returned.

long sobj_to_long struct sobj sobj,
bool *  error
 

Convert a simple object to long.

Parameters:
sobj The object.
error In case of a conversion error and if error is not a null-pointer, *error is set to true.
Returns:
The function returns the result of the conversion. In case of an error, 0 is returned.

long long sobj_to_long_long struct sobj sobj,
bool *  error
 

Convert a simple object to long long.

Parameters:
sobj The object.
error In case of a conversion error and if error is not a null-pointer, *error is set to true.
Returns:
The function returns the result of the conversion. In case of an error, 0 is returned.

ptrdiff_t sobj_to_ptrdiff_t struct sobj sobj,
bool *  error
 

Convert a simple object to ptrdiff_t.

Parameters:
sobj The object.
error In case of a conversion error and if error is not a null-pointer, *error is set to true.
Returns:
The function returns the result of the conversion. In case of an error, 0 is returned.

size_t sobj_to_size_t struct sobj sobj,
bool *  error
 

Convert a simple object to size_t.

Parameters:
sobj The object.
error In case of a conversion error and if error is not a null-pointer, *error is set to true.
Returns:
The function returns the result of the conversion. In case of an error, 0 is returned.

size_t sobj_to_string struct sobj sobj,
char *  buffer,
ptrdiff_t  buffer_size
 

Convert a simple object to a string.

The function creats a string representation of a simple object. If an object is not of type string, it is converted to string type using the documented ruleset. The resulting string will be null-terminated UNICODE string.

If the simple object is a string containing variable references, the variable references are ignored.

Parameters:
sobj The simple object instance to be converted to a string.
buffer The buffer receiving the converted string. If this is a null-pointer, no conversion is done.
buffer_size The size of the buffer receiving the converted string. At most buffer_size bytes are written to buffer. If the converted string does not fit into the buffer, it will be truncated. Note that the truncated string will not be null-terminated. The special value -1 indicates that the buffer is large enough.
Returns:
The number of bytes required to strore the converted string, not including the terminating null-character.
Note:
Veriable references embedded in strings are not resolved.

uint16_t sobj_to_uint16_t struct sobj sobj,
bool *  error
 

Convert a simple object to uint16_t.

Parameters:
sobj The object.
error In case of a conversion error and if error is not a null-pointer, *error is set to true.
Returns:
The function returns the result of the conversion. In case of an error, 0 is returned.

uint32_t sobj_to_uint32_t struct sobj sobj,
bool *  error
 

Convert a simple object to uint32_t.

Parameters:
sobj The object.
error In case of a conversion error and if error is not a null-pointer, *error is set to true.
Returns:
The function returns the result of the conversion. In case of an error, 0 is returned.

uint64_t sobj_to_uint64_t struct sobj sobj,
bool *  error
 

Convert a simple object to uint64_t.

Parameters:
sobj The object.
error In case of a conversion error and if error is not a null-pointer, *error is set to true.
Returns:
The function returns the result of the conversion. In case of an error, 0 is returned.

uint8_t sobj_to_uint8_t struct sobj sobj,
bool *  error
 

Convert a simple object to uint8_t.

Parameters:
sobj The object.
error In case of a conversion error and if error is not a null-pointer, *error is set to true.
Returns:
The function returns the result of the conversion. In case of an error, 0 is returned.

uintmax_t sobj_to_uintmax_t struct sobj sobj,
bool *  error
 

Convert a simple object to uintmax_t.

Parameters:
sobj The object.
error In case of a conversion error and if error is not a null-pointer, *error is set to true.
Returns:
The function returns the result of the conversion. In case of an error, 0 is returned.

unsigned sobj_to_unsigned struct sobj sobj,
bool *  error
 

Convert a simple object to unsigned.

Parameters:
sobj The object.
error In case of a conversion error and if error is not a null-pointer, *error is set to true.
Returns:
The function returns the result of the conversion. In case of an error, 0 is returned.

unsigned long sobj_to_unsigned_long struct sobj sobj,
bool *  error
 

Convert a simple object to unsigned long.

Parameters:
sobj The object.
error In case of a conversion error and if error is not a null-pointer, *error is set to true.
Returns:
The function returns the result of the conversion. In case of an error, 0 is returned.

unsigned long long sobj_to_unsigned_long_long struct sobj sobj,
bool *  error
 

Convert a simple object to unsigned long long.

Parameters:
sobj The object.
error In case of a conversion error and if error is not a null-pointer, *error is set to true.
Returns:
The function returns the result of the conversion. In case of an error, 0 is returned.

enum sobj_type sobj_type struct sobj sobj  ) 
 

Return the object type.

Parameters:
sobj The called object.
Returns:
The object type.

const char* sobj_typename enum sobj_type  type,
bool  upper
 

Return a type name string for the specified type.

Parameters:
type A simple object type.
upper Flag indicating that the type name should be returned as an uppercase string.
Returns:
The type name.

const char* sobj_version const char *  version  ) 
 

Get the library version number.

Parameters:
version The version string of the installer header files. This should be either a null-pointer or the value of the version macro SOBJ_VERSION (as defined in <sobject/version.h>).
Note:
If a header version string is specified (i.e. version is not null) and it does not match the version number of the library, then an error message is written to stderr and the program is terminated through abort(). If this is not what you want to do in case of a version mismatch, you can specify version as a null-pointer and compare the returned string to SOBJ_VERSION yourself.
Returns:
A version string of the library. This is a pointer to constant static storage.

struct sobj* sobj_vgetf struct sobj sobj,
bool  pure,
struct sobj_env env,
const char *  address_fmt,
va_list  ap
 

Get a subobject of the called object.

This function is a variant of the sobj_get() function, where the address is specified using a printf-style format string an variable argument pointer.

Parameters:
sobj The called object.
pure Flag indicating that pure address resolution should be used.
env The environment. This may be a null-pointer.
address_fmt The format string for the address of the subobject.
ap Variable argument pointer for the variable arguments specified in the format string address_fmt.
Returns:
The function returns the specified subobject. The function returns a null-pointer if the pure flag was selected an the address does not resolve to a subobject of the called object.

const char* sobj_vref_ref struct sobj sobj  ) 
 

Get the reference string from a vref object.

It is a fatal runtime error if the called object is not of type vref.

Parameters:
sobj The called object.
Returns:
The function returns a pointer to the reference string stored in the object. The caller may not modify the reference string.


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