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

Find and Substitute
[Simple Objects C API]


Detailed Description

This module provides methods for finding and substiting sub-objects of simple objects.


Find Flag Constants

Flag constants for the sobj_find() and sobj_substitute() functions.

#define SOBJ_FIND_CN   (1)
 Flag indicating that the relevant sub-object's class names must match the specified class name.
#define SOBJ_FIND_TYPE   (2)
 Flag indicating that the relevant sub-object's types must match the specified type.
#define SOBJ_FIND_RECURSIVE   (4)
 Flag indicating that the find/substitute operation should be performed recursively on the found/substituted objects.

Typedefs

typedef int sobj_find_fn (struct sobj *sobj, void *so_sender)
 Function type for sobj_find() callback functions.
typedef sobjsobj_substitute_fn (struct sobj *sobj, void *so_sender)
 Function type for sobj_substitute() callback functions.

Functions

int sobj_find (struct sobj *sobj, const char *cn, enum sobj_type type, sobj_find_fn *fn, void *sender, int flags)
 Find sub-objects of the specified object matching the specified criteria.
int sobj_find_cn (struct sobj *sobj, const char *cn, sobj_find_fn *fn, void *sender)
 Find sub-objects of the specified object matching the specified class name.
int sobj_find_type (struct sobj *sobj, enum sobj_type type, sobj_find_fn *fn, void *sender)
 Find sub-objects of the specified object matching the specified type.
int sobj_find_list (struct sobj *sobj, const char *cn, enum sobj_type type, struct sobj **vec, int vec_size, int flags)
 Create a list of all sub-objects matching the specified criteria.
int sobj_find_cn_list (struct sobj *sobj, const char *cn, struct sobj **vec, int vec_size)
 Create a list of all sub-objects matching the specified class name.
int sobj_find_type_list (struct sobj *sobj, enum sobj_type type, struct sobj **vec, int vec_size)
 Create a list of all sub-objects matching the specified class name.
sobjsobj_substitute (struct sobj *sobj, const char *cn, enum sobj_type type, sobj_substitute_fn *fn, void *sender, int flags)
 In the specified objects substitute sub-objects matching the specified criteria.
sobjsobj_substitute_cn (struct sobj *sobj, const char *cn, sobj_substitute_fn *fn, void *sender)
 In the specified objects substitute sub-objects matching the specified class name.
sobjsobj_substitute_type (struct sobj *sobj, enum sobj_type type, sobj_substitute_fn *fn, void *sender)
 In the specified objects substitute sub-objects matching the specified class name.


Define Documentation

#define SOBJ_FIND_CN   (1)
 

Flag indicating that the relevant sub-object's class names must match the specified class name.

#define SOBJ_FIND_RECURSIVE   (4)
 

Flag indicating that the find/substitute operation should be performed recursively on the found/substituted objects.

#define SOBJ_FIND_TYPE   (2)
 

Flag indicating that the relevant sub-object's types must match the specified type.


Typedef Documentation

typedef int sobj_find_fn(struct sobj *sobj, void *so_sender)
 

Function type for sobj_find() callback functions.

Parameters:
sobj The object found.
so_sender The sender parameter passed to the sobj_find() function (or variant).
Returns:
If the function returns 0, then the find function continues scanning for matching sub-objects. A non-zero return value causes the find operation to be terminated. The value returned is the passed on to the caller of the find function.

typedef struct sobj* sobj_substitute_fn(struct sobj *sobj, void *so_sender)
 

Function type for sobj_substitute() callback functions.

Parameters:
sobj The object to be substituted.
so_sender The sender parameter passed to the sobj_substitute() function (or variant).
Returns:
The function should return the object that is to be substituted in place of the specified object. The function may indicate an error condition by returning a null-pointer.


Function Documentation

int sobj_find struct sobj sobj,
const char *  cn,
enum sobj_type  type,
sobj_find_fn fn,
void *  sender,
int  flags
 

Find sub-objects of the specified object matching the specified criteria.

Parameters:
sobj The object to be scanned.
cn The class name to look for. A null-pointer is equivalent to an empty/missing class name. See flags parameter.
type The object type to look for. See flags parameter.
fn The function to be called for every matching sub-object.
sender The sender object passed to the callback function through the so_sender parameter.
flags A combination of the following flags:
  • SOBJ_FIND_CN
    Find only sub-objects matching the specified class name.
  • SOBJ_FIND_TYPE
    Find only sub-objects matching the specified type.
  • SOBJ_FIND_RECURSIVE
    Scan recursively through sub-objects matching the specified criteria. (Sub-objects not matching the specified criteria are always scanned.)
Returns:
The function returns either 0 or the first non-zero return value received from the callback function.

int sobj_find_cn struct sobj sobj,
const char *  cn,
sobj_find_fn fn,
void *  sender
 

Find sub-objects of the specified object matching the specified class name.

Parameters:
sobj The object to be scanned.
cn The class name to look for. A null-pointer is equivalent to an empty/missing class name.
fn The function to be called for every matching sub-object.
sender The sender object passed to the callback function through the so_sender parameter.
Returns:
The function returns either 0 or the first non-zero return value received from the callback function.
Note:
Sub-objects matching the specified class name are not scanned recursively (i.e. the SOBJ_FIND_RECURSIVE flag is not used).

int sobj_find_cn_list struct sobj sobj,
const char *  cn,
struct sobj **  vec,
int  vec_size
 

Create a list of all sub-objects matching the specified class name.

Parameters:
sobj The object to be scanned.
cn The class name to look for. A null-pointer is equivalent to an empty/missing class name.
vec Pointer to a vector receiving borrowed references to the sub-objects found. If this is a null-pointer, then the function only counts the matching sub-objects without creating a listing.
vec_size The size of the specified vector. No more than vec_size object references are written to the specified vector. This parameter is ignored if vec is a null-pointer.
Returns:
The function returns the number of sub-objects found.
Note:
Sub-objects matching the specified class name are not scanned recursively (i.e. the SOBJ_FIND_RECURSIVE flag is not used).

int sobj_find_list struct sobj sobj,
const char *  cn,
enum sobj_type  type,
struct sobj **  vec,
int  vec_size,
int  flags
 

Create a list of all sub-objects matching the specified criteria.

Parameters:
sobj The object to be scanned.
cn The class name to look for. A null-pointer is equivalent to an empty/missing class name. See flags parameter.
type The object type to look for. See flags parameter.
vec Pointer to a vector receiving borrowed references to the sub-objects found. If this is a null-pointer, then the function only counts the matching sub-objects without creating a listing.
vec_size The size of the specified vector. No more than vec_size object references are written to the specified vector. This parameter is ignored if vec is a null-pointer.
flags A combination of the following flags:
  • SOBJ_FIND_CN
    Find only sub-objects matching the specified class name.
  • SOBJ_FIND_TYPE
    Find only sub-objects matching the specified type.
  • SOBJ_FIND_RECURSIVE
    Scan recursively through sub-objects matching the specified criteria. (Sub-objects not matching the specified criteria are always scanned.)
Returns:
The function returns the number of sub-objects found.

int sobj_find_type struct sobj sobj,
enum sobj_type  type,
sobj_find_fn fn,
void *  sender
 

Find sub-objects of the specified object matching the specified type.

Parameters:
sobj The object to be scanned.
type The object type to look for.
fn The function to be called for every matching sub-object.
sender The sender object passed to the callback function through the so_sender parameter.
Returns:
The function returns either 0 or the first non-zero return value received from the callback function.
Note:
Sub-objects matching the specified type are not scanned recursively (i.e. the SOBJ_FIND_RECURSIVE flag is not used).

int sobj_find_type_list struct sobj sobj,
enum sobj_type  type,
struct sobj **  vec,
int  vec_size
 

Create a list of all sub-objects matching the specified class name.

Parameters:
sobj The object to be scanned.
type The object type to look for.
vec Pointer to a vector receiving borrowed references to the sub-objects found. If this is a null-pointer, then the function only counts the matching sub-objects without creating a listing.
vec_size The size of the specified vector. No more than vec_size object references are written to the specified vector. This parameter is ignored if vec is a null-pointer.
Returns:
The function returns the number of sub-objects found.
Note:
Sub-objects matching the specified type are not scanned recursively (i.e. the SOBJ_FIND_RECURSIVE flag is not used).

struct sobj* sobj_substitute struct sobj sobj,
const char *  cn,
enum sobj_type  type,
sobj_substitute_fn fn,
void *  sender,
int  flags
 

In the specified objects substitute sub-objects matching the specified criteria.

Parameters:
sobj The original object.
cn The class name to look for. A null-pointer is equivalent to an empty/missing class name. See flags parameter.
type The object type to look for. See flags parameter.
fn The function to be called for every matching sub-object to produce the sub-object that should be substituted for the matching sub-object.
sender The sender object passed to the callback function through the so_sender parameter.
flags A combination of the following flags:
  • SOBJ_FIND_CN
    Find only sub-objects matching the specified class name.
  • SOBJ_FIND_TYPE
    Find only sub-objects matching the specified type.
  • SOBJ_FIND_RECURSIVE
    Scan recursively through the replacement sub-objects returned by the callback function. Note that if the replacement object itself is not processed, only its sub-objects.
Returns:
The function returns a new object with the matching sub-objects replaced. If one invocation of the callback function indicated an error (i.e. the callback function returned a null-pointer), then a null-pointer is returned.

struct sobj* sobj_substitute_cn struct sobj sobj,
const char *  cn,
sobj_substitute_fn fn,
void *  sender
 

In the specified objects substitute sub-objects matching the specified class name.

Parameters:
sobj The original object.
cn The class name to look for. A null-pointer is equivalent to an empty/missing class name.
fn The function to be called for every matching sub-object to produce the sub-object that should be substituted for the matching sub-object.
sender The sender object passed to the callback function through the so_sender parameter.
Returns:
The function returns a new object with the matching sub-objects replaced. If one invocation of the callback function indicated an error (i.e. the callback function returned a null-pointer), then a null-pointer is returned.
Note:
The replacement sub-objects are not scanned recursively (i.e. the SOBJ_FIND_RECURSIVE flag is not used).

struct sobj* sobj_substitute_type struct sobj sobj,
enum sobj_type  type,
sobj_substitute_fn fn,
void *  sender
 

In the specified objects substitute sub-objects matching the specified class name.

Parameters:
sobj The original object.
type The object type to look for.
fn The function to be called for every matching sub-object to produce the sub-object that should be substituted for the matching sub-object.
sender The sender object passed to the callback function through the so_sender parameter.
Returns:
The function returns a new object with the matching sub-objects replaced. If one invocation of the callback function indicated an error (i.e. the callback function returned a null-pointer), then a null-pointer is returned.
Note:
The replacement sub-objects are not scanned recursively (i.e. the SOBJ_FIND_RECURSIVE flag is not used).


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