CODA Expression

Typedefs
typedef struct coda_expression_struct	coda_expression
typedef enum coda_expression_type_enum	coda_expression_type

Functions
int	coda_expression_print (const coda_expression *expr, int(*print)(const char *,...))
const char *	coda_expression_get_type_name (coda_expression_type type)
void	coda_expression_delete (coda_expression *expr)
int	coda_expression_is_constant (const coda_expression *expr)
int	coda_expression_is_equal (const coda_expression *expr1, const coda_expression *expr2)
int	coda_expression_get_type (const coda_expression *expr, coda_expression_type *type)
int	coda_expression_eval_bool (const coda_expression *expr, const coda_cursor *cursor, int *value)
int	coda_expression_eval_integer (const coda_expression *expr, const coda_cursor *cursor, int64_t *value)
int	coda_expression_eval_float (const coda_expression *expr, const coda_cursor *cursor, double *value)
int	coda_expression_eval_string (const coda_expression *expr, const coda_cursor *cursor, char **value, long *length)
int	coda_expression_eval_node (const coda_expression *expr, coda_cursor *cursor)
int	coda_expression_from_string (const char *exprstring, coda_expression **expr)

Detailed Description

CODA comes with a powerful expression language that can be used to perform calculations based on product data. This expression system is used internally with the product format definition (codadef) files that CODA uses to interpret products, but it can also be used by you as a user for your own purposes. More information on the CODA expression language and its ascii syntax can be found in the CODA documentation.

The example below shows how to evaluate a simple integer expression that does not make use of any product data:

const char *equation = "1+2";
coda_expression *expr;
long result;
 
coda_expression_from_string(equation, &expr);
coda_expression_eval_integer(expr, NULL, &result);
coda_expression_delete(expr);
printf("%d\n", result);

However, in most cases you will want to run an expression on actual product data. In the example below the expression expects a cursor that points to a record which has two fields, 'numerator' and 'denominator', and it will return a floating point value with the division of those two field values.

const char *equation = "float(./numerator)/float(./denominator)";
coda_cursor cursor;
coda_expression *expr;
double result;
 
coda_expression_from_string(equation, &expr);
 
... loop over all cursors for which you want to calculate the division ....
coda_expression_eval_integer(expr, &cursor, &result);
printf("%f\n", result);
... end of loop ...
 
coda_expression_delete(expr);

Note that, unlike most other CODA functions, the coda_expression_from_string() and coda_expression_delete() functions do not require that CODA is initialised with coda_init(). This also holds for the coda_expression_eval functions if no cursor is provided as parameter (i.e. when a static evaluation of the expression is performed).

Typedef Documentation

coda_expression

coda_expression

CODA Expression

coda_expression_type

coda_expression_type

Result types of CODA expressions.

Function Documentation

coda_expression_delete()

void coda_expression_delete

(

coda_expression *

expr

)

Delete the CODA expression object.

Parameters

expr	A CODA expression object

coda_expression_eval_bool()

int coda_expression_eval_bool	(	const coda_expression *	expr,
		const coda_cursor *	cursor,
		int *	value
	)

Evaluate a boolean expression. The expression object should be a coda_expression_bool expression. The function will evaluate the expression at the given cursor position and return the resulting boolean value (which will be 0 for False and 1 for True).

Parameters

expr	A boolean expression object
cursor	Cursor pointing to a location in the product where the boolean expression should be evaluated (can be NULL for constant expressions).
value	Pointer to the variable where the resulting boolean value will be stored.

Returns

• 0, Success.
• -1, Error occurred (check coda_errno).

coda_expression_eval_float()

int coda_expression_eval_float	(	const coda_expression *	expr,
		const coda_cursor *	cursor,
		double *	value
	)

Evaluate a floating point expression. The function will evaluate the expression at the given cursor position and return the resulting floating point value. The expression object should be a coda_expression_float expression.

Parameters

expr	A floating point expression object
cursor	Cursor pointing to a location in the product where the floating point expression should be evaluated (can be NULL for constant expressions).
value	Pointer to the variable where the resulting floating point value will be stored.

Returns

• 0, Success.
• -1, Error occurred (check coda_errno).

coda_expression_eval_integer()

int coda_expression_eval_integer	(	const coda_expression *	expr,
		const coda_cursor *	cursor,
		int64_t *	value
	)

Evaluate an integer expression. The expression object should be a coda_expression_integer expression. The function will evaluate the expression at the given cursor position and return the resulting integer value.

Parameters

expr	An integer expression object
cursor	Cursor pointing to a location in the product where the integer expression should be evaluated (can be NULL for constant expressions).
value	Pointer to the variable where the resulting integer value will be stored.

Returns

• 0, Success.
• -1, Error occurred (check coda_errno).

coda_expression_eval_node()

int coda_expression_eval_node	(	const coda_expression *	expr,
		coda_cursor *	cursor
	)

Evaluate a node expression. The function will moves the cursor to a different position in a product based on the node expression. The expression object should be a coda_expression_node expression.

Parameters

expr	A node expression object
cursor	Cursor pointing to a location in the product where the node expression should be evaluated.

Returns

• 0, Success.
• -1, Error occurred (check coda_errno).

coda_expression_eval_string()

int coda_expression_eval_string	(	const coda_expression *	expr,
		const coda_cursor *	cursor,
		char **	value,
		long *	length
	)

Evaluate a string expression. The function will evaluate the expression at the given cursor position (if provided) and return the resulting string and length. If length is 0 then no string will be returned and value will be set to NULL. If a string is returned then it will be zero terminated. However, in the case where the string itself also contains zero characters, strlen() can not be used and the length parameter will give the actual string length of value. The expression object should be a coda_expression_string expression.

Note

The caller of this function is responsible for freeing the memory of the result that is stored in value. It is recommended to do this with coda_free().

Parameters

expr	A string expression object
cursor	Cursor pointing to a location in the product where the string expression should be evaluated (can be NULL for constant expressions).
value	Pointer to the variable where the result string will be stored (will be NULL if length == 0).
length	Pointer to the variable where the length of the result string will be stored.

Returns

• 0, Success.
• -1, Error occurred (check coda_errno).

coda_expression_from_string()

int coda_expression_from_string	(	const char *	exprstring,
		coda_expression **	expr
	)

Create a new CODA expression object by parsing a string containing a CODA expression. The string should contain a valid CODA expression. The returned expression object should be cleaned up using coda_expression_delete() after it has been used.

Parameters

exprstring	A string containing the string representation of the CODA expression
expr	Pointer to the variable where the expression object will be stored.

Returns

• 0, Success.
• -1, Error occurred (check coda_errno).

coda_expression_get_type()

int coda_expression_get_type	(	const coda_expression *	expr,
		coda_expression_type *	type
	)

Retrieve the result type of a CODA expression.

Parameters

expr	A CODA expression object
type	Pointer to the variable where the result type of the CODA expression will be stored.

Returns

• 0, Success.
• -1, Error occurred (check coda_errno).

coda_expression_get_type_name()

const char * coda_expression_get_type_name

(

coda_expression_type

type

)

Returns the name of an expression type.

Parameters

type	CODA expression type

Returns

if the type is known a string containing the name of the type, otherwise the string "unknown".

coda_expression_is_constant()

int coda_expression_is_constant

(

const coda_expression *

expr

)

Return whether an expression is constant or not. An expression is constant if it does not depend on the contents of a product and if the expression evaluation function can be called with cursor=NULL.

Parameters

expr	A CODA expression object

Returns

• 0, Expression will depend on the contents of a product.
• 1, Expression is constant.
• -1, Error occurred (check coda_errno).

coda_expression_is_equal()

int coda_expression_is_equal	(	const coda_expression *	expr1,
		const coda_expression *	expr2
	)

Determines whether two expressions are equal or not This function will return 1 if both expressions are equal, and 0 if they are not.

The comparison will not be on the evaluated result of the expressions but on the operators and operands of the expressions themselves. For two expressions to be equal, all operands to an operation need to be equal and operands need to be provided in the same order. So the expression '1!=2' will not be considered equal to the expression '2!=1'.

Providing two NULL pointers will be considered as a case of equal expressions.

Parameters

expr1	A CODA expression object
expr2	A CODA expression object

Returns

• 0, expr1 and expr2 consist of the exact same sequence of operators and operands.
• 1, expr1 and expr2 differ in terms of operators and operands.

coda_expression_print()

int coda_expression_print	(	const coda_expression *	expr,
		int(*)(const char *,...)	print
	)

Write the full expression using a printf compatible function. This function will produce a string representation of the expression itself (it won't evaluate the expression, nor write its result). The print function parameter should be a function that resembles printf(). The printed string representation is something that can be passed to coda_expression_from_string() again to reproduce the expression object.

Parameters

expr	Pointer to the expression object.
print	Reference to a printf compatible function.

Returns

• 0, Succes.
• -1, Error occurred (check coda_errno).