The interface for creating expressions. More...

#include <iexpression.h>

Inheritance diagram for mi::neuraylib::IExpression_factory:

Public Member Functions
Access to related factories.
virtual IValue_factory *	get_value_factory () const =0
	Returns the value factory associated with this expression factory. More...

Creation of expressions and expression lists
virtual IExpression_constant *	create_constant (IValue *value) const =0
	Creates a constant (mutable). More...

virtual const IExpression_constant *	create_constant (const IValue *value) const =0
	Creates a constant (const). More...

virtual IExpression_call *	create_call (const char *name) const =0
	Creates a call. More...

virtual IExpression_parameter *	create_parameter (const IType *type, Size index) const =0
	Creates a parameter reference. More...

virtual IExpression_direct_call *	create_direct_call (const char name, IExpression_list arguments, Sint32 *errors=0) const =0
	Creates a direct call. More...

virtual IExpression_temporary *	create_temporary (const IType *type, Size index) const =0
	Creates a temporary reference. More...

virtual IExpression_list *	create_expression_list () const =0
	Creates a new expression list. More...

Creation of annotations, annotation blocks, and annotations lists
virtual IAnnotation *	create_annotation (const char name, const IExpression_list arguments) const =0
	Creates a new annotation. More...

virtual IAnnotation_block *	create_annotation_block () const =0
	Creates a new annotation block. More...

virtual IAnnotation_list *	create_annotation_list () const =0
	Creates a new annotation list. More...

Cloning of expressions and expression lists
virtual IExpression *	clone (const IExpression *expr) const =0
	Clones the given expression. More...

template<class T>
T *	clone (const T *expr) const
	Clones the given expression. More...

virtual IExpression_list *	clone (const IExpression_list *expression_list) const =0
	Clones the given expression list. More...

Dumping of expression and expression lists
virtual const IString *	dump (const IExpression expr, const char name, Size depth=0) const =0
	Returns a textual representation of an expression. More...

virtual const IString *	dump (const IExpression_list list, const char name, Size depth=0) const =0
	Returns a textual representation of an expression list. More...

Dumping of annotations, annotation blocks, and annotation lists
virtual const IString *	dump (const IAnnotation annotation, const char name, Size depth=0) const =0
	Returns a textual representation of an annotation. More...

virtual const IString *	dump (const IAnnotation_block block, const char name, Size depth=0) const =0
	Returns a textual representation of an annotation block. More...

virtual const IString *	dump (const IAnnotation_list list, const char name, Size depth=0) const =0
	Returns a textual representation of an annotation list. More...

Miscellaneous methods
virtual IExpression *	create_cast (IExpression src_expr, const IType target_type, const char cast_db_name, bool force_cast, bool direct_call, Sint32 errors=0) const =0
	Returns an expression which casts the source expression to a target type. More...

virtual IExpression *	create_decl_cast (IExpression src_expr, const IType_struct target_type, const char cast_db_name, bool force_cast, bool direct_call, Sint32 errors=0) const =0
	Returns an expression which casts the source expression to a target type. More...

Public Member Functions inherited from mi::base::IInterface
virtual Uint32	retain () const =0
	Increments the reference count. More...

virtual Uint32	release () const =0
	Decrements the reference count. More...

virtual const IInterface *	get_interface (const Uuid &interface_id) const =0
	Acquires a const interface from another. More...

template<class T>
const T *	get_interface () const
	Acquires a const interface from another. More...

virtual IInterface *	get_interface (const Uuid &interface_id)=0
	Acquires a mutable interface from another. More...

template<class T>
T *	get_interface ()
	Acquires a mutable interface from another. More...

virtual Uuid	get_iid () const =0
	Returns the interface ID of the most derived interface. More...

Comparison of expression and expression lists
enum	Comparison_options { DEFAULT_OPTIONS = 0 , DEEP_CALL_COMPARISONS = 1 , SKIP_TYPE_ALIASES = 2 , COMPARISON_OPTIONS_FORCE_32_BIT = 0xffffffffU }
	Various options for the comparison of expressions or expression lists. More...

virtual Sint32	compare (const IExpression lhs, const IExpression rhs, Uint32 flags=0, Float64 epsilon=0.0) const =0
	Compares two instances of mi::neuraylib::IExpression. More...

virtual Sint32	compare (const IExpression_list lhs, const IExpression_list rhs, Uint32 flags=0, Float64 epsilon=0.0) const =0
	Compares two instances of mi::neuraylib::IExpression_list. More...

Additional Inherited Members
Public Types inherited from mi::base::Interface_declare< 0x9fd3b2d4, ... >
typedef Interface_declare< id1, ... >	Self
	Own type. More...

typedef Uuid_t< id1, ... >	IID
	Declares the interface ID (IID) of this interface. More...

Public Types inherited from mi::base::IInterface
typedef Uuid_t<0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0>	IID
	Declares the interface ID (IID) of this interface. More...

Static Public Member Functions inherited from mi::base::Interface_declare< 0x9fd3b2d4, ... >
static bool	compare_iid (const Uuid &iid)
	Compares the interface ID `iid` against the interface ID of this interface and of its ancestors. More...

Static Public Member Functions inherited from mi::base::IInterface
static bool	compare_iid (const Uuid &iid)
	Compares the interface ID `iid` against the interface ID of this interface. More...

Detailed Description

The interface for creating expressions.

An expression factory can be obtained from mi::neuraylib::IMdl_factory::create_expression_factory().

See also: mi::neuraylib::IType_factory, mi::neuraylib::IValue_factory

Member Enumeration Documentation

^◆ Comparison_options

enum mi::neuraylib::IExpression_factory::Comparison_options

Various options for the comparison of expressions or expression lists.

See also: The flags parameter of compare()

Enumerator

DEFAULT_OPTIONS

Default comparison options.

DEEP_CALL_COMPARISONS

This option indicates that call expressions should be compared for equality, not for identity.

That is, the comparison is not done via mi::neuraylib::IExpression::get_value(), but by traversing into the referenced function call, i.e., comparing the function definition reference and the arguments. This option is useful if you want to decide whether an argument is semantically equal to the corresponding default parameter.

SKIP_TYPE_ALIASES

This option indicates that all type aliases should be skipped before types of expression are compared.

Defaults and argument might sometimes differ in explicit type modifiers, therefore this option is useful if you want to decide whether an argument is semantically equal to the corresponding default parameter.

Member Function Documentation

^◆ clone() [1/3]

virtual IExpression * mi::neuraylib::IExpression_factory::clone ( const IExpression * expr ) const

pure virtual

Clones the given expression.

Note that referenced DB elements, e.g., resources in constant expressions, or function calls and material instances in call expressions, are not copied, but shared. Function calls and material instances that serve as default arguments, are copied, though.

^◆ clone() [2/3]

virtual IExpression_list * mi::neuraylib::IExpression_factory::clone ( const IExpression_list * expression_list ) const

pure virtual

Clones the given expression list.

Note that referenced DB elements, e.g., resources in constant expressions, or function calls and material instances in call expressions, are not copied, but shared.

^◆ clone() [3/3]

template<class T>

T * mi::neuraylib::IExpression_factory::clone ( const T * expr ) const

inline

Clones the given expression.

Note that referenced DB elements, e.g., resources in constant expressions, or function calls and material instances in call expressions, are not copied, but shared. Function calls and material instances that serve as default arguments, are copied, though.

^◆ compare() [1/2]

virtual Sint32 mi::neuraylib::IExpression_factory::compare	(	const IExpression *	lhs,
		const IExpression *	rhs,
		Uint32	flags = `0`,
		Float64	epsilon = `0.0`
	)		const

pure virtual

Compares two instances of mi::neuraylib::IExpression.

The comparison operator for instances of mi::neuraylib::IExpression is defined as follows:

If lhs or rhs is NULL, the result is the lexicographic comparison of the pointer addresses themselves.
Otherwise, the types of lhs and rhs are compared. If they are different, the result is determined by that comparison.
Next, the kind of the expressions are compared. If they are different, the result is determined by operator< on the mi::neuraylib::IExpression::Kind values. Note that setting SKIP_TYPE_ALIASES in flags modifies this behavior.
Finally, the expressions are compared as follows:
- For constants the results is defined by comparing their values.
- For calls, the result is defined by comparison of the call reference (unless DEEP_CALL_COMPARISONS is set in flags). Note that the representation of this call reference is an internal implementation detail, and the comparison result might have the opposite sign as strcmp() on the strings returned by mi::neuraylib::IExpression_call::get_call().
- For parameter and temporary references, the results is defined by operator<() on the indices.
- For indirect calls, first the definition reference is compared. Note that the representation of this definition reference is an internal implementation detail, and the comparison result might have the opposite sign as strcmp() on the strings returned by mi::neuraylib::IExpression_direct_call::get_definition(). If both indirect call reference the same definition, then the result is defined by comparison of the arguments.

Parameters

lhs	The left-hand side operand for the comparison.
rhs	The right-hand side operand for the comparison.
flags	A bitmask of flags of type Comparison_options.
epsilon	Maximum difference for floating point values to consider them as equal.

Returns: -1 if lhs < rhs, 0 if lhs == rhs, and +1 if lhs > rhs.

^◆ compare() [2/2]

virtual Sint32 mi::neuraylib::IExpression_factory::compare	(	const IExpression_list *	lhs,
		const IExpression_list *	rhs,
		Uint32	flags = `0`,
		Float64	epsilon = `0.0`
	)		const

pure virtual

Compares two instances of mi::neuraylib::IExpression_list.

The comparison operator for instances of mi::neuraylib::IExpression_list is defined as follows:

If lhs or rhs is NULL, the result is the lexicographic comparison of the pointer addresses themselves.
Next, the list sizes are compared using operator<().
Next, the lists are traversed by increasing index and the names are compared using strcmp().
Finally, the list elements are enumerated by increasing index and the expressions are compared.

Parameters

lhs	The left-hand side operand for the comparison.
rhs	The right-hand side operand for the comparison.
flags	A bitmask of flags of type Comparison_options.
epsilon	Maximum difference for floating point values to consider them as equal.

Returns: -1 if lhs < rhs, 0 if lhs == rhs, and +1 if lhs > rhs.

^◆ create_annotation()

virtual IAnnotation * mi::neuraylib::IExpression_factory::create_annotation	(	const char *	name,
		const IExpression_list *	arguments
	)		const

pure virtual

Creates a new annotation.

Returns NULL if one of the arguments is not a constant expression.

^◆ create_annotation_block()

virtual IAnnotation_block * mi::neuraylib::IExpression_factory::create_annotation_block ( ) const

pure virtual

Creates a new annotation block.

^◆ create_annotation_list()

virtual IAnnotation_list * mi::neuraylib::IExpression_factory::create_annotation_list ( ) const

pure virtual

Creates a new annotation list.

^◆ create_call()

virtual IExpression_call * mi::neuraylib::IExpression_factory::create_call ( const char * name ) const

pure virtual

Creates a call.

Parameters

name	The DB name of the referenced function call or material instance.

Returns: The created call, or NULL in case of errors.

^◆ create_cast()

virtual IExpression * mi::neuraylib::IExpression_factory::create_cast	(	IExpression *	src_expr,
		const IType *	target_type,
		const char *	cast_db_name,
		bool	force_cast,
		bool	direct_call,
		Sint32 *	errors = `0`
	)		const

pure virtual

Returns an expression which casts the source expression to a target type.

This is a convenience function that creates an instance of the cast operator with the necessary arguments, stores it in the database, and returns a call expressions for the just created function. Note that the cast operator requires that the type of the source expression and the target type are compatible (see mi::neuraylib::IType_factory::is_compatible()).

See also: Cast operator

Parameters

src_expr	The expression whose type is supposed to be cast.
target_type	The result type of the cast. Note that the inserted cast operator acts on types without qualifiers, i.e., modifiers on `target_type` are ignored.
cast_db_name	This name is used when storing the instance of the cast operator in the database. If the name is already taken by another DB element, this string will be used as the base for generating a unique name. If `NULL`, a unique name is generated.
force_cast	This flag has only an effect if the type of the source expression is identical to the target type. If `true`, then the cast expression will still be created. If `false`, then `src_expr` itself will be returned.
direct_call	Indicates whether to create a direct call expression or an (indirect) call expression.
errors	An optional pointer to an mi::Sint32 to which an error code will be written. The error codes have the following meaning: 0: Success. -1: Invalid parameters (`NULL` pointer). -2: The type of `src_expr` cannot be cast to `target_type`.

Returns: The resulting expression or NULL in case of failure.

^◆ create_constant() [1/2]

virtual const IExpression_constant * mi::neuraylib::IExpression_factory::create_constant ( const IValue * value ) const

pure virtual

Creates a constant (const).

Parameters

value The value of the constant.

Returns: The created constant.

^◆ create_constant() [2/2]

virtual IExpression_constant * mi::neuraylib::IExpression_factory::create_constant ( IValue * value ) const

pure virtual

Creates a constant (mutable).

Parameters

value The value of the constant.

Returns: The created constant, or NULL in case of errors.

^◆ create_decl_cast()

virtual IExpression * mi::neuraylib::IExpression_factory::create_decl_cast	(	IExpression *	src_expr,
		const IType_struct *	target_type,
		const char *	cast_db_name,
		bool	force_cast,
		bool	direct_call,
		Sint32 *	errors = `0`
	)		const

pure virtual

Returns an expression which casts the source expression to a target type.

This is a convenience function that creates an instance of the decl_cast operator with the necessary arguments, stores it in the database, and returns a call expressions for the just created function. Note that the decl_cast operator requires that the type of the source expression and the target type are struct types from the same struct category (see mi::neuraylib::IType_factory::from_same_struct_category()).

See also: Decl_cast operator

Parameters

src_expr	The expression whose type is supposed to be cast.
target_type	The result type of the cast. Note that the inserted decl_cast operator acts on types without qualifiers, i.e., modifiers on `target_type` are ignored.
cast_db_name	This name is used when storing the instance of the decl_cast operator in the database. If the name is already taken by another DB element, this string will be used as the base for generating a unique name. If `NULL`, a unique name is generated.
force_cast	This flag has only an effect if the type of the source expression is identical to the target type. If `true`, then the decl_cast expression will still be created. If `false`, then `src_expr` itself will be returned.
direct_call	Indicates whether to create a direct call expression or an (indirect) call expression.
errors	An optional pointer to an mi::Sint32 to which an error code will be written. The error codes have the following meaning: 0: Success. -1: Invalid parameters (`NULL` pointer). -2: The type of `src_expr` cannot be cast to `target_type`.

Returns: The resulting expression or NULL in case of failure.

^◆ create_direct_call()

virtual IExpression_direct_call * mi::neuraylib::IExpression_factory::create_direct_call	(	const char *	name,
		IExpression_list *	arguments,
		Sint32 *	errors = `0`
	)		const

pure virtual

Creates a direct call.

Parameters

	name	The DB name of the referenced function or material definition.
	arguments	The arguments of the created direct call. Arguments for parameters without default are mandatory, otherwise optional. The type of an argument must match the corresponding parameter type. Any argument missing in `arguments` will be set to the default of the corresponding parameter. Note that the expressions in `arguments` are copied. Valid subexpressions are constants, direct calls, and parameter references. operation is a deep copy, e.g., DB elements referenced in call expressions are also copied. `NULL` is a valid argument which is handled like an empty expression list.
[out]	errors	An optional pointer to an mi::Sint32 to which an error code will be written. The error codes have the following meaning: 0: Success. -1: An argument for a non-existing parameter was provided in `arguments`. -2: The type of an argument in `arguments` does not have the correct type. -3: A parameter that has no default was not provided with an argument value. -5: A parameter type is uniform, but the corresponding argument has a varying return type. -6: An argument expression is not a constant, a direct call, nor a parameter. -7: Invalid parameters (`NULL` pointer) or `name` is not a valid DB name of a function or material definition. -8: One of the parameter types is uniform, but the corresponding argument or default is a call expression and the return type of the called function or material definition is effectively varying since the function or material definition itself is varying. -9: The function or material definition is invalid due to a module reload.

Returns: The created call, or NULL in case of errors.

^◆ create_expression_list()

virtual IExpression_list * mi::neuraylib::IExpression_factory::create_expression_list ( ) const

pure virtual

Creates a new expression list.

^◆ create_parameter()

virtual IExpression_parameter * mi::neuraylib::IExpression_factory::create_parameter	(	const IType *	type,
		Size	index
	)		const

pure virtual

Creates a parameter reference.

Parameters

type	The type of the parameter.
index	The index of the parameter.

Returns: The created parameter reference, or NULL in case of errors.

^◆ create_temporary()

virtual IExpression_temporary * mi::neuraylib::IExpression_factory::create_temporary	(	const IType *	type,
		Size	index
	)		const

pure virtual

Creates a temporary reference.

Parameters

type	The type of the temporary.
index	The index of the temporary.

Returns: The created temporary reference, or NULL in case of errors.

^◆ dump() [1/5]

virtual const IString * mi::neuraylib::IExpression_factory::dump	(	const IAnnotation *	annotation,
		const char *	name,
		Size	depth = `0`
	)		const

pure virtual

Returns a textual representation of an annotation.

The representation of the annotation will contain line breaks. Subsequent lines have a suitable indentation. The assumed indentation level of the first line is specified by depth.

Note: The exact format of the textual representation is unspecified and might change in future releases. The textual representation is primarily meant as a debugging aid. Do not base application logic on it.

^◆ dump() [2/5]

virtual const IString * mi::neuraylib::IExpression_factory::dump	(	const IAnnotation_block *	block,
		const char *	name,
		Size	depth = `0`
	)		const

pure virtual

Returns a textual representation of an annotation block.

The representation of the annotation block will contain line breaks. Subsequent lines have a suitable indentation. The assumed indentation level of the first line is specified by depth.

Note: The exact format of the textual representation is unspecified and might change in future releases. The textual representation is primarily meant as a debugging aid. Do not base application logic on it.

^◆ dump() [3/5]

virtual const IString * mi::neuraylib::IExpression_factory::dump	(	const IAnnotation_list *	list,
		const char *	name,
		Size	depth = `0`
	)		const

pure virtual

Returns a textual representation of an annotation list.

The representation of the annotation list will contain line breaks. Subsequent lines have a suitable indentation. The assumed indentation level of the first line is specified by depth.

Note: The exact format of the textual representation is unspecified and might change in future releases. The textual representation is primarily meant as a debugging aid. Do not base application logic on it.

^◆ dump() [4/5]

virtual const IString * mi::neuraylib::IExpression_factory::dump	(	const IExpression *	expr,
		const char *	name,
		Size	depth = `0`
	)		const

pure virtual

Returns a textual representation of an expression.

The parameter depth is only relevant for constants, where the argument is passed to mi::neuraylib::IValue_factory::dump().

Note: The exact format of the textual representation is unspecified and might change in future releases. The textual representation is primarily meant as a debugging aid. Do not base application logic on it.

^◆ dump() [5/5]

virtual const IString * mi::neuraylib::IExpression_factory::dump	(	const IExpression_list *	list,
		const char *	name,
		Size	depth = `0`
	)		const

pure virtual

Returns a textual representation of an expression list.

The representation of the expression list will contain line breaks. Subsequent lines have a suitable indentation. The assumed indentation level of the first line is specified by depth.

Note: The exact format of the textual representation is unspecified and might change in future releases. The textual representation is primarily meant as a debugging aid. Do not base application logic on it.

^◆ get_value_factory()

virtual IValue_factory * mi::neuraylib::IExpression_factory::get_value_factory ( ) const

pure virtual

Returns the value factory associated with this expression factory.

Public Member Functions

Comparison of expression and expression lists

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ Comparison_options

Member Function Documentation

◆ clone() [1/3]

◆ clone() [2/3]

◆ clone() [3/3]

◆ compare() [1/2]

◆ compare() [2/2]

◆ create_annotation()

◆ create_annotation_block()

◆ create_annotation_list()

◆ create_call()

◆ create_cast()

◆ create_constant() [1/2]

◆ create_constant() [2/2]

◆ create_decl_cast()

◆ create_direct_call()

◆ create_expression_list()

◆ create_parameter()

◆ create_temporary()

◆ dump() [1/5]

◆ dump() [2/5]

◆ dump() [3/5]

◆ dump() [4/5]

◆ dump() [5/5]

◆ get_value_factory()

^◆ Comparison_options

^◆ clone() [1/3]

^◆ clone() [2/3]

^◆ clone() [3/3]

^◆ compare() [1/2]

^◆ compare() [2/2]

^◆ create_annotation()

^◆ create_annotation_block()

^◆ create_annotation_list()

^◆ create_call()

^◆ create_cast()

^◆ create_constant() [1/2]

^◆ create_constant() [2/2]

^◆ create_decl_cast()

^◆ create_direct_call()

^◆ create_expression_list()

^◆ create_parameter()

^◆ create_temporary()

^◆ dump() [1/5]

^◆ dump() [2/5]

^◆ dump() [3/5]

^◆ dump() [4/5]

^◆ dump() [5/5]

^◆ get_value_factory()