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

Object Modification Functions
[Simple Objects C API]


Detailed Description

Create modified instances of simple objects.

Instances of simple objects are immutable, so they can't be modified directly. The functions in this module perform so called modifications by creating and returning a new, ``modified'' object. The original object is -- of course -- kept unchanged.


Functions

sobjsobj_set_classname (struct sobj *sobj, const char *cn)
 Change the class name of the called object.
sobjsobj_insert (struct sobj *sobj, int position, struct sobj *key, struct sobj *value)
 Insert an element (key/value pair) into an array object.
sobjsobj_insert_with_string (struct sobj *sobj, int position, const char *key_string, struct sobj *value)
 Insert an element (key/value pair) into an array object.
sobjsobj_insert_many (struct sobj *sobj, int position, int key_n, struct sobj **key, int value_n, struct sobj **value)
 Insert a sequence of elements (key/value pairs) into an array object.
sobjsobj_append (struct sobj *sobj, struct sobj *key, struct sobj *value)
 Append an element (key/value pair) to an array object.
sobjsobj_append_with_string (struct sobj *sobj, const char *key_string, struct sobj *value)
 Append an element (key/value pair) to an array object.
sobjsobj_append_many (struct sobj *sobj, int key_n, struct sobj **key, int value_n, struct sobj **value)
 Append a sequence of elements (key/value pairs) to an array object.
sobjsobj_remove (struct sobj *sobj, int position, int count)
 Remove a number of elements from an array object.
sobjsobj_remove_key (struct sobj *sobj, struct sobj *key, struct sobj_env *env)
 Remove the last element whose key matches the specified key.
sobjsobj_remove_key_with_string (struct sobj *sobj, const char *key_string, struct sobj_env *env)
 Remove the last element whose key matches the specified key.
sobjsobj_replace (struct sobj *sobj, int position, struct sobj *key, struct sobj *value)
 Replace an element in an array object.
sobjsobj_replace_with_string (struct sobj *sobj, int position, const char *key_string, struct sobj *value)
 Replace an element in an array object.
sobjsobj_put (struct sobj *sobj, struct sobj *key, struct sobj *value, struct sobj_env *env)
 Alter or add an element in/to an array object.
sobjsobj_put_with_string (struct sobj *sobj, const char *key_string, struct sobj *value, struct sobj_env *env)
 Alter or add an element in/to an array object.
sobjsobj_concat (struct sobj *sobj, struct sobj *operand)
 Append an array object to an array object or a string object to a string object.
sobjsobj_set (struct sobj *sobj, const char *address, struct sobj *value, bool slice, struct sobj_env *env)
 Substitute a subobject at the specified address.
sobjsobj_set2 (struct sobj *sobj, struct sobj *address, struct sobj *value, bool slice, struct sobj_env *env)
 Substitute a subobject at the specified address.
sobjsobj_string_insert (struct sobj *sobj, int position, const char *string)
 Insert a string into a string object.
sobjsobj_string_append (struct sobj *sobj, const char *string)
 Append a string to the end of a string object.
sobjsobj_string_replace (struct sobj *sobj, int position, int length, const char *string)
 Replace a substring of the specified string object.
sobjsobj_string_replace_ucx (struct sobj *sobj, int position, int length, const char *string_ucx)
 Replace a substring of the specified string object.


Function Documentation

struct sobj* sobj_append struct sobj sobj,
struct sobj key,
struct sobj value
 

Append an element (key/value pair) to an array object.

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

Parameters:
sobj The called object.
key The key of the key/value pair. The value null is equivalent to a NIL object.
value The value of the key/value pair. The value null is equivalent to a NIL object.
Returns:
The function returns an array object with the specified element appended.
See also:
sobj_append_with_string().

struct sobj* sobj_append_many struct sobj sobj,
int  key_n,
struct sobj **  key,
int  value_n,
struct sobj **  value
 

Append a sequence of elements (key/value pairs) to an array object.

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

Parameters:
sobj The called object.
key_n The number of keys specified.
key Pointer to a vector of keys. This may be a null-pointer if key_n is 0. If the vector contains null-pointers, these are interpreted as NIL objects.
value_n The number of values specified.
value Pointer to a vector of values. This may be a null-pointer if value_n is null.
The parameter value_n indicates the number of elements being appended. If the value array is longer than the key array (key_n), the unspecified keys are set to NIL. If the value array is shorter than the key array, the extra key values in key are ignored.

If the specified element sequence is empty or if the value parameter is a null-pointer, the called object remains unchanged.

Returns:
The function returns an array object with the specified elements appended.

struct sobj* sobj_append_with_string struct sobj sobj,
const char *  key_string,
struct sobj value
 

Append an element (key/value pair) to an array object.

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

Parameters:
sobj The called object.
key_string The key of the key/value pair, represented as a raw UTF-8 encoded UNICODE string.
value The value of the key/value pair. The value null is equivalent to a NIL object.
Returns:
The function returns an array object with the specified element appended.
See also:
sobj_append().

struct sobj* sobj_concat struct sobj sobj,
struct sobj operand
 

Append an array object to an array object or a string object to a string object.

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

Parameters:
sobj The called object.
operand The array object being appended. It is a fatal runtime error if the parameter operand is not of the same type as the called object sobj (either array or string).
Returns:
The function returns the concatenation of the called object and the operand.

struct sobj* sobj_insert struct sobj sobj,
int  position,
struct sobj key,
struct sobj value
 

Insert an element (key/value pair) into an array object.

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

Parameters:
sobj The called object.
position The index position for inserting the element. Negative values are counted from the end of the array. If index is equal to the length of the array, the element is appended to the array. It is a fatal runtime error if the index is out of bounds.
key The key of the key/value pair. The value null is equivalent to a NIL object.
value The value of the key/value pair. The value null is equivalent to a NIL object.
Note:
The number of valid positions in an insert operation is the length of the array plus one, so specifying a position -1 causes the element to be appended to the array.
Returns:
The function returns an array object with the specified element inserted.
See also:
sobj_insert_with_string().

struct sobj* sobj_insert_many struct sobj sobj,
int  position,
int  key_n,
struct sobj **  key,
int  value_n,
struct sobj **  value
 

Insert a sequence of elements (key/value pairs) into an array object.

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

Parameters:
sobj The called object.
position The index position for inserting the sequence of elements. Negative values are counted from the end of the array. If position is equal to the length of the array, the elements are appended to the array. It is a fatal runtime error if the index is out of bounds.
key_n The number of keys specified.
key Pointer to a vector of keys. This may be a null-pointer if key_n is 0. If the vector contains null-pointers, these are interpreted as NIL objects.
value_n The number of values specified.
value Pointer to a vector of values. This may be a null-pointer if value_n is null.
The parameter value_n indicates the number of elements being inserted. If the value array is longer than the key array (key_n), the unspecified keys are set to NIL. If the value array is shorter than the key array, the extra key values in key are ignored.

If the specified element sequence is empty or if the value parameter is a null-pointer, the called object remains unchanged.

Note:
The number of valid positions in an insert operation is the length of the array plus one, so specifying a position -1 causes the elements to be appended to the array.
Returns:
The function returns an array object with the specified elements inserted.

struct sobj* sobj_insert_with_string struct sobj sobj,
int  position,
const char *  key_string,
struct sobj value
 

Insert an element (key/value pair) into an array object.

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

Parameters:
sobj The called object.
position The index position for inserting the element. Negative values are counted from the end of the array. If index is equal to the length of the array, the element is appended to the array. It is a fatal runtime error if the index is out of bounds.
key_string String representing the key of the key/value pair. This is a raw UTF-8 encoded string.
value The value of the key/value pair. The value null is equivalent to a NIL object.
Note:
The number of valid positions in an insert operation is the length of the array plus one, so specifying a position -1 causes the element to be appended to the array.
Returns:
The function returns an array object with the specified element inserted.
See also:
sobj_insert().

struct sobj* sobj_put struct sobj sobj,
struct sobj key,
struct sobj value,
struct sobj_env env
 

Alter or add an element in/to an array object.

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

Parameters:
sobj The called object.
key The key of the array element that should be altered. The last element in the array with a matching key is altered. If the specified key is not found in the array, the specified key/value pair is appended to the array.
value The value of the specified element. A null-pointer indicates a NIL value.
env The environment used for resolving variable references in the address and in element keys of type string. This may be a null-pointer.
Returns:
The function returns an array object with the specified element altered or added.
See also:
sobj_put_with_string().

struct sobj* sobj_put_with_string struct sobj sobj,
const char *  key_string,
struct sobj value,
struct sobj_env env
 

Alter or add an element in/to an array object.

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

Parameters:
sobj The called object.
key_string A string representing the key for the put operation. The key is interpreted as a raw UTF-8 encoded UNICODE string.
value The value of the specified element. A null-pointer indicates a NIL value.
env The environment used for resolving variable references in the address and in element keys of type string. This may be a null-pointer.
Returns:
The function returns an array object with the specified element altered or added.
See also:
sobj_put().

struct sobj* sobj_remove struct sobj sobj,
int  position,
int  count
 

Remove a number of elements from an array object.

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

Parameters:
sobj The called object.
position The inserted position of the first element being removed. Negative values are counted from the end of the array. It is a fatal runtime error if the index is out of bounds.
count The number of elements being removed. This value must be positive, zero, or -1. If count is zero, the array object remains unchanged. If count is -1, all elements up to the end of the array are removed.
Returns:
The function returns an array object with the specified elements removed.

struct sobj* sobj_remove_key struct sobj sobj,
struct sobj key,
struct sobj_env env
 

Remove the last element whose key matches the specified key.

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

Parameters:
sobj The called object.
key The specified element key.
env The environment used for resolving variable references in the element keys of type string. This may be a null-pointer.
The array object remains unchanged if the specified key is not found.

Returns:
The function returns an array object with the specified element removed.
Note:
Only the last element with a matching key is removed. The array might contain multiple elements with a matching key.
See also:
sobj_remove_key_with_string().

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

Remove the last element whose key matches the specified key.

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

Parameters:
sobj The called object.
key_string The specified element key, represented as a raw UTF-8 encoded UNICODE string.
env The environment used for resolving variable references in the element keys of type string. This may be a null-pointer.
The array object remains unchanged if the specified key is not found.

Returns:
The function returns an array object with the specified element removed.
Note:
Only the last element with a matching key is removed. The array might contain multiple elements with a matching key.
See also:
sobj_remove_key().

struct sobj* sobj_replace struct sobj sobj,
int  position,
struct sobj key,
struct sobj value
 

Replace an element in an array object.

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

Parameters:
sobj The called object.
position The index position of the element being replaced. Negative values are counted from the end of the array. It is a fatal runtime error if the index is out of bounds.
key The replacement key of the specified element. A null-pointer indicates that the key should remain unchanged.
value The replacement value of the specified element. A null-pointer indicates that the value should remain unchanged.
Returns:
The function returns an array object with the specified element altered.
Note:
A null-pointer does not represent a NIL value.
See also:
sobj_replace_with_string().

struct sobj* sobj_replace_with_string struct sobj sobj,
int  position,
const char *  key_string,
struct sobj value
 

Replace an element in an array object.

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

Parameters:
sobj The called object.
position The index position of the element being replaced. Negative values are counted from the end of the array. It is a fatal runtime error if the index is out of bounds.
key_string The replacement key of the specified element, represented as a raw UTF-8 encoded UNICODE string. A null-pointer indicates that the key should remain unchanged.
value The replacement value of the specified element. A null-pointer indicates that the value should remain unchanged.
Returns:
The function returns an array object with the specified element altered.
Note:
A null-pointer does not represent a NIL value.
See also:
sobj_replace().

struct sobj* sobj_set struct sobj sobj,
const char *  address,
struct sobj value,
bool  slice,
struct sobj_env env
 

Substitute a subobject at the specified address.

Parameters:
sobj The called object.
address The parameter string is encoded as an UTF-8 UNICODE string and interpreted as a text serialization of a simple object. If the first non-whitespace character in string is a dot (.) or an opening bracket ([), the string "NIL" (without the quotes) is prepended to the parameter. The represented simple object is interpreted as an address selecting the object to be substituted. If the address starts with a star (*), the star character is skipped. (This is for compatibility with sobj_get() only, the star prefix is not really useful for sobj_set()).
value The value to be substituted in place of the selected subobject.
slice Flag indicating if an element or slice addressed by an index or slice selection should be replaced by a single value or a sequence of elements.
env The environment used for resolving variable references in the address and in element keys of type string. This may be a null-pointer.
Returns:
If the address can not be resolved, the function returns a null-pointer. On succeeds, an object with the specified subobject replaced is returned.

struct sobj* sobj_set2 struct sobj sobj,
struct sobj address,
struct sobj value,
bool  slice,
struct sobj_env env
 

Substitute a subobject at the specified address.

Parameters:
sobj The called object.
address The address selecting the simple object to be substituted.
value The value to be substituted in place of the selected subobject.
slice Flag indicating if an element or slice addressed by an index or slice selection should be replaced by a single value or a sequence of elements.
env The environment used for resolving variable references in the address and in element keys of type string. This may be a null-pointer.
Returns:
If the address can't be resolved, the function returns a null-pointer. On succeeds, an object with the specified subobject replaced is returned.

struct sobj* sobj_set_classname struct sobj sobj,
const char *  cn
 

Change the class name of the called object.

Parameters:
sobj The called object.
cn The new class name.
Returns:
A new object with the class name changed to cn.

struct sobj* sobj_string_append struct sobj sobj,
const char *  string
 

Append a string to the end of a string object.

It is a fatal runtime error if the specified object is not of type string.

Parameters:
sobj The called object.
string The string to be appended.
Returns:
The function returns a string object with the specified string appended.

struct sobj* sobj_string_insert struct sobj sobj,
int  position,
const char *  string
 

Insert a string into a string object.

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

Parameters:
sobj The called object.
position The character position for inserting the specified string. If the position is -1 or points beyond the end of the string, the specified string str is appended to the called object.
string The string to be inserted.
Returns:
The function returns a string object with the specified string inserted.

struct sobj* sobj_string_replace struct sobj sobj,
int  position,
int  length,
const char *  string
 

Replace a substring of the specified string object.

It is a fatal runtime error of the specified object is not of type string.

Parameters:
sobj The called object.
position The character position for replacing the specified string. If the position is -1 or points beyond the end of the string, the specified string str is appended to the called object.
length The length of the substring to be replaced. For length == 0 this is equivalent to the string_insert() function. If length is larger than the rest of the string or -1, the entire rest of the string is replaced. It is a fatal runtime error to pass a negative value smaller than -1.
string The replacement string.
Returns:
The function returns a string object with the specified substring replaced.

struct sobj* sobj_string_replace_ucx struct sobj sobj,
int  position,
int  length,
const char *  string_ucx
 

Replace a substring of the specified string object.

It is a fatal runtime error of the specified object is not of type string.

Parameters:
sobj The called object.
position The character position for replacing the specified string. If the position is -1 or points beyond the end of the string, the specified string str is appended to the called object.
length The length of the substring to be replaced. For length == 0 this is equivalent to the string_insert() function. If length is larger than the rest of the string or -1, the entire rest of the string is replaced. It is a fatal runtime error to pass a negative value smaller than -1.
string_ucx The replacement string. This is an extended UNICODE string, possibly containing references.
Returns:
The function returns a string object with the specified substring replaced.


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