Properties


Typedefs

typedef _cpl_property_ cpl_property
 The opaque property data type.

Functions

void cpl_property_delete (cpl_property *self)
 Destroy a property.
cpl_propertycpl_property_duplicate (const cpl_property *other)
 Create a copy of a property.
int cpl_property_get_bool (const cpl_property *self)
 Get the value of a boolean property.
char cpl_property_get_char (const cpl_property *self)
 Get the value of a character property.
const char * cpl_property_get_comment (const cpl_property *self)
 Get the property comment.
double cpl_property_get_double (const cpl_property *self)
 Get the value of a double property.
float cpl_property_get_float (const cpl_property *self)
 Get the value of a float property.
int cpl_property_get_int (const cpl_property *self)
 Get the value of an integer property.
long cpl_property_get_long (const cpl_property *self)
 Get the value of a long property.
const char * cpl_property_get_name (const cpl_property *self)
 Get the property name.
long cpl_property_get_size (const cpl_property *self)
 Get the current number of elements a property contains.
const char * cpl_property_get_string (const cpl_property *self)
 Get the value of a string property.
cpl_type cpl_property_get_type (const cpl_property *self)
 Get the type of a property.
cpl_propertycpl_property_new (const char *name, cpl_type type)
 Create an empty property of a given type.
cpl_propertycpl_property_new_array (const char *name, cpl_type type, int size)
 Create an empty property of a given type and size.
cpl_error_code cpl_property_set_bool (cpl_property *self, int value)
 Set the value of a boolean property.
cpl_error_code cpl_property_set_char (cpl_property *self, char value)
 Set the value of a character property.
cpl_error_code cpl_property_set_comment (cpl_property *self, const char *comment)
 Modify a property's comment.
cpl_error_code cpl_property_set_double (cpl_property *self, double value)
 Set the value of a double property.
cpl_error_code cpl_property_set_float (cpl_property *self, float value)
 Set the value of a float property.
cpl_error_code cpl_property_set_int (cpl_property *self, int value)
 Set the value of an integer property.
cpl_error_code cpl_property_set_long (cpl_property *self, long value)
 Set the value of a long property.
cpl_error_code cpl_property_set_name (cpl_property *self, const char *name)
 Modify the name of a property.
cpl_error_code cpl_property_set_string (cpl_property *self, const char *value)
 Set the value of a string property.

Detailed Description

This module implements the property type. The type cpl_property is basically a variable container which consists of a name, a type identifier and a specific value of that type. The type identifier always determines the type of the associated value. A property is similar to an ordinary variable and its current value can be set or retrieved through its name. In addition a property may have a descriptive comment associated. A property can be created for the basic types char, bool (int), int, long, float and double. Also C strings are supported. Support for arrays in general is currently not available.

Synopsis:
   #include <cpl_property.h>

Typedef Documentation

typedef struct _cpl_property_ cpl_property

The opaque property data type.


Function Documentation

void cpl_property_delete ( cpl_property self  ) 

Destroy a property.

Parameters:
self The property.
Returns:
Nothing.
The function destroys a property of any kind. All property members including their values are properly deallocated. If the property self is NULL, nothing is done and no error is set.

cpl_property* cpl_property_duplicate ( const cpl_property other  ) 

Create a copy of a property.

Parameters:
other The property to copy.
Returns:
The copy of the given property, or NULL in case of an error. In the latter case an appropriate error code is set.
Errors:
CPL_ERROR_NULL_INPUT The parameter self is a NULL pointer.

The function returns a copy of the property self. The copy is a deep copy, i.e. all property members are copied.

int cpl_property_get_bool ( const cpl_property self  ) 

Get the value of a boolean property.

Parameters:
self The property.
Returns:
The current property value. If an error occurs the function returns 0 and an appropriate error code is set.
Errors:
CPL_ERROR_NULL_INPUT The parameter self is a NULL pointer.
CPL_ERROR_TYPE_MISMATCH The property self is not of type CPL_TYPE_BOOL.

The function retrieves the boolean value currently stored in the property self.

char cpl_property_get_char ( const cpl_property self  ) 

Get the value of a character property.

Parameters:
self The property.
Returns:
The current property value. If an error occurs the function returns '\0' and an appropriate error code is set.
Errors:
CPL_ERROR_NULL_INPUT The parameter self is a NULL pointer.
CPL_ERROR_TYPE_MISMATCH The property self is not of type CPL_TYPE_CHAR.

The function retrieves the character value currently stored in the property self.

const char* cpl_property_get_comment ( const cpl_property self  ) 

Get the property comment.

Parameters:
self The property.
Returns:
The comment of the property if it is present or NULL. If an error occurrs the function returns NULL and sets an appropriate error code.
Errors:
CPL_ERROR_NULL_INPUT The parameter self is a NULL pointer.

The function returns a handle for the read-only comment string of self.

double cpl_property_get_double ( const cpl_property self  ) 

Get the value of a double property.

Parameters:
self The property.
Returns:
The current property value. If an error occurs the function returns 0.0 and an appropriate error code is set.
Errors:
CPL_ERROR_NULL_INPUT The parameter self is a NULL pointer.
CPL_ERROR_TYPE_MISMATCH The property self is not of type CPL_TYPE_DOUBLE.

The function retrieves the double value currently stored in the property self.

float cpl_property_get_float ( const cpl_property self  ) 

Get the value of a float property.

Parameters:
self The property.
Returns:
The current property value. If an error occurs the function returns 0.0 and an appropriate error code is set.
Errors:
CPL_ERROR_NULL_INPUT The parameter self is a NULL pointer.
CPL_ERROR_TYPE_MISMATCH The property self is not of type CPL_TYPE_FLOAT.

The function retrieves the float value currently stored in the property self.

int cpl_property_get_int ( const cpl_property self  ) 

Get the value of an integer property.

Parameters:
self The property.
Returns:
The current property value. If an error occurs the function returns 0 and an appropriate error code is set.
Errors:
CPL_ERROR_NULL_INPUT The parameter self is a NULL pointer.
CPL_ERROR_TYPE_MISMATCH The property self is not of type CPL_TYPE_INT.

The function retrieves the integer value currently stored in the property self.

long cpl_property_get_long ( const cpl_property self  ) 

Get the value of a long property.

Parameters:
self The property.
Returns:
The current property value. If an error occurs the function returns 0 and an appropriate error code is set.
Errors:
CPL_ERROR_NULL_INPUT The parameter self is a NULL pointer.
CPL_ERROR_TYPE_MISMATCH The property self is not of type CPL_TYPE_LONG.

The function retrieves the long value currently stored in the property self.

const char* cpl_property_get_name ( const cpl_property self  ) 

Get the property name.

Parameters:
self The property.
Returns:
The name of the property or NULL if an error occurred. In the latter case an appropriate error code is set.
Errors:
CPL_ERROR_NULL_INPUT The parameter self is a NULL pointer.

The function returns a handle for the read-only identifier string of self.

long cpl_property_get_size ( const cpl_property self  ) 

Get the current number of elements a property contains.

Parameters:
self The property.
Returns:
The current number of elements or -1 in case of an error. If an error occurred an appropriate error code is set.
Errors:
CPL_ERROR_NULL_INPUT The parameter self is a NULL pointer.

The function returns the current number of elements the property self contains. This is the array size of the property's value and in particular, for a property of the type CPL_TYPE_STRING, it is the length of the string as given by the strlen() function plus 1.

const char* cpl_property_get_string ( const cpl_property self  ) 

Get the value of a string property.

Parameters:
self The property.
Returns:
The current property value. If an error occurs the function returns NULL and an appropriate error code is set.
Errors:
CPL_ERROR_NULL_INPUT The parameter self is a NULL pointer.
CPL_ERROR_TYPE_MISMATCH The property self is not of type CPL_TYPE_STRING.

The function retrieves the string value currently stored in the property self.

cpl_type cpl_property_get_type ( const cpl_property self  ) 

Get the type of a property.

Parameters:
self The property.
Returns:
The type code of this property. In case of an error the returned type code is CPL_TYPE_INVALID and an appropriate error code is set.
Errors:
CPL_ERROR_NULL_INPUT The parameter self is a NULL pointer.

This function returns the type of the data value stored in the property self.

cpl_property* cpl_property_new ( const char *  name,
cpl_type  type 
)

Create an empty property of a given type.

Parameters:
name Property name.
type Property type flag.
Returns:
The newly created property, or NULL if it could not be created. In the latter case an appropriate error code is set.
Errors:
CPL_ERROR_NULL_INPUT The parameter name is a NULL pointer.
CPL_ERROR_INVALID_TYPE The requested property type type is not supported.

The function allocates memory for a property of type type and assigns the identifier string name to the newly created property.

The returned property must be destroyed using the property destructor cpl_property_delete().

See also:
cpl_property_delete()

cpl_property* cpl_property_new_array ( const char *  name,
cpl_type  type,
int  size 
)

Create an empty property of a given type and size.

Parameters:
name Property name.
type Property type flag.
size Size of the property value.
Returns:
The newly created property, or NULL if it could not be created. in the latter case an appropriate error code is set.
Errors:
CPL_ERROR_NULL_INPUT The parameter name is a NULL pointer.

The function allocates memory for a property of type type and assigns the identifier string name to the newly created property. The property value is created such that size elements of type type can be stored.

The returned property must be destroyed using the property destructor cpl_property_delete().

See also:
cpl_property_delete()

cpl_error_code cpl_property_set_bool ( cpl_property self,
int  value 
)

Set the value of a boolean property.

Parameters:
self The property.
value New value.
Returns:
The function returns CPL_ERROR_NONE on success and an appropriate error code if an error occurred. In the latter case the error code is also set in the error handling system.
Errors:
CPL_ERROR_NULL_INPUT The parameter self is a NULL pointer.
CPL_ERROR_TYPE_MISMATCH The property self is not of type CPL_TYPE_BOOL.

The function replaces the current boolean value of self with a a 0, if value is equal to 0. If value is different from 0 any previous value of self is replaced by a 1.

cpl_error_code cpl_property_set_char ( cpl_property self,
char  value 
)

Set the value of a character property.

Parameters:
self The property.
value New value.
Returns:
The function returns CPL_ERROR_NONE on success and an appropriate error code if an error occurred. In the latter case the error code is also set in the error handling system.
Errors:
CPL_ERROR_NULL_INPUT The parameter self is a NULL pointer.
CPL_ERROR_TYPE_MISMATCH The property self is not of type CPL_TYPE_CHAR.

The function replaces the current character value of self with a copy of the value value.

cpl_error_code cpl_property_set_comment ( cpl_property self,
const char *  comment 
)

Modify a property's comment.

Parameters:
self The property.
comment New comment.
Returns:
The function returns CPL_ERROR_NONE on success and an appropriate error code if an error occurred. In the latter case the error code is also set in the error handling system.
Errors:
CPL_ERROR_NULL_INPUT The parameter self or comment is a NULL pointer.

The function replaces the current comment field of self with a copy of the string comment. The new comment may be NULL. In this case the function effectively deletes the current comment.

cpl_error_code cpl_property_set_double ( cpl_property self,
double  value 
)

Set the value of a double property.

Parameters:
self The property.
value New value.
Returns:
The function returns CPL_ERROR_NONE on success and an appropriate error code if an error occurred. In the latter case the error code is also set in the error handling system.
Errors:
CPL_ERROR_NULL_INPUT The parameter self is a NULL pointer.
CPL_ERROR_TYPE_MISMATCH The property self is not of type CPL_TYPE_DOUBLE.

The function replaces the current double value of self with a copy of the value value.

cpl_error_code cpl_property_set_float ( cpl_property self,
float  value 
)

Set the value of a float property.

Parameters:
self The property.
value New value.
Returns:
The function returns CPL_ERROR_NONE on success and an appropriate error code if an error occurred. In the latter case the error code is also set in the error handling system.
Errors:
CPL_ERROR_NULL_INPUT The parameter self is a NULL pointer.
CPL_ERROR_TYPE_MISMATCH The property self is not of type CPL_TYPE_FLOAT.

The function replaces the current float value of self with a copy of the value value.

cpl_error_code cpl_property_set_int ( cpl_property self,
int  value 
)

Set the value of an integer property.

Parameters:
self The property.
value New value.
Returns:
The function returns CPL_ERROR_NONE on success and an appropriate error code if an error occurred. In the latter case the error code is also set in the error handling system.
Errors:
CPL_ERROR_NULL_INPUT The parameter self is a NULL pointer.
CPL_ERROR_TYPE_MISMATCH The property self is not of type CPL_TYPE_INT.

The function replaces the current integer value of self with a copy of the value value.

cpl_error_code cpl_property_set_long ( cpl_property self,
long  value 
)

Set the value of a long property.

Parameters:
self The property.
value New value.
Returns:
The function returns CPL_ERROR_NONE on success and an appropriate error code if an error occurred. In the latter case the error code is also set in the error handling system.
Errors:
CPL_ERROR_NULL_INPUT The parameter self is a NULL pointer.
CPL_ERROR_TYPE_MISMATCH The property self is not of type CPL_TYPE_LONG.

The function replaces the current long value of self with a copy of the value value.

cpl_error_code cpl_property_set_name ( cpl_property self,
const char *  name 
)

Modify the name of a property.

Parameters:
self The property.
name New name.
Returns:
The function returns CPL_ERROR_NONE on success and an appropriate error code if an error occurred. In the latter case the error code is also set in the error handling system.
Errors:
CPL_ERROR_NULL_INPUT The parameter self or name is a NULL pointer.

The function replaces the current name of self with a copy of the string name. The function returns an error if name is NULL.

cpl_error_code cpl_property_set_string ( cpl_property self,
const char *  value 
)

Set the value of a string property.

Parameters:
self The property.
value New value.
Returns:
The function returns CPL_ERROR_NONE on success and an appropriate error code if an error occurred. In the latter case the error code is also set in the error handling system.
Errors:
CPL_ERROR_NULL_INPUT The parameter self or value is a NULL pointer.
CPL_ERROR_TYPE_MISMATCH The property self is not of type CPL_TYPE_STRING.

The function replaces the current string value of self with a copy of the value value.


Generated on Wed Mar 18 09:40:12 2009 for Common Pipeline Library Reference Manual by  doxygen 1.4.7