This API component allows the creation, assignment, and cloning of instances of types. More...

#include <ifactory.h>

Inheritance diagram for mi::neuraylib::IFactory:

Public Types
enum	Assign_result { NULL_POINTER = 1 , STRUCTURAL_MISMATCH = 2 , NO_CONVERSION = 4 , TARGET_KEY_MISSING = 8 , SOURCE_KEY_MISSING = 16 , DIFFERENT_COLLECTIONS = 32 , NON_IDATA_VALUES = 64 , INCOMPATIBLE_POINTER_TYPES = 128 , DEEP_ASSIGNMENT_TO_CONST_POINTER = 256 , INCOMPATIBLE_PRIVACY_LEVELS = 1024 , INCOMPATIBLE_ENUM_TYPES = 2048 , INCOMPATIBLE_OPTIONS = 4096 , FORCE_32_BIT_RESULT = 0xffffffffU }
	This enum represents possible events that can happen during assignment of types. More...

enum	Assign_clone_options { DEEP_ASSIGNMENT_OR_CLONE = 1 , FIX_SET_OF_TARGET_KEYS = 4 , FORCE_32_BIT_OPTIONS = 0xffffffffU }
	This enum represents various options for the assignment or cloning of types. More...

Public Types inherited from mi::base::Interface_declare< 0x8afad838, ... >
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...

Public Member Functions
virtual base::IInterface *	create (const char type_name, Uint32 argc=0, const base::IInterface argv[]=0)=0
	Creates an object of the type `type_name`. More...

template<class T>
T *	create (const char type_name, Uint32 argc=0, const base::IInterface argv[]=0)
	Creates an object of the type `type_name`. More...

template<class T>
T *	create ()
	Creates an object of the type `T`. More...

virtual Uint32	assign_from_to (const IData source, IData target, Uint32 options=0)=0
	Assigns the value(s) of `source` to `target`. More...

virtual IData *	clone (const IData *source, Uint32 options=0)=0
	Creates a clone of a type. More...

template<class T>
T *	clone (const IData *source, Uint32 options=0)
	Creates a clone of a type. More...

virtual Sint32	compare (const IData lhs, const IData rhs)=0
	Compares two instances of mi::IData. More...

virtual const IString *	dump (const IData data, const char name=0, Size depth=0)=0
	Returns a textual representation of a type. More...

virtual const IString *	dump (neuraylib::ITransaction transaction, const IData data, const char *name=0, Size depth=0)=0
	Returns a textual representation of a type. More...

virtual const IStructure_decl *	get_structure_decl (const char *structure_name) const =0
	Returns a registered structure declaration. More...

virtual const IEnum_decl *	get_enum_decl (const char *enum_name) const =0
	Returns a registered enum declaration. 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...

Additional Inherited Members
Static Public Member Functions inherited from mi::base::Interface_declare< 0x8afad838, ... >
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

This API component allows the creation, assignment, and cloning of instances of types.

It also provides a comparison function for types.

Types are interfaces derived from mi::IData. See Types for an explanation of the type system.

Member Enumeration Documentation

^◆ Assign_clone_options

enum mi::neuraylib::IFactory::Assign_clone_options

This enum represents various options for the assignment or cloning of types.

The enum values are powers of two such that they can be combined in a bitmask. Such a bitmask van be is passed to assign_from_to() and clone().

Enumerator

DEEP_ASSIGNMENT_OR_CLONE

By default, assignment or cloning of instances of mi::IPointer and mi::IConst_pointer is shallow, i.e., the pointer represented by these interfaces is assigned or cloned as a plain value and both pointers point to the same interface afterwards.

If this option is given the assignment or cloning is deep, i.e., the operations happens on the wrapped pointers themselves.

FIX_SET_OF_TARGET_KEYS

By default, assignment might change the set of keys if the for target is a dynamic array or map.

If this option is given the set of keys in the target remains fixed.

^◆ Assign_result

enum mi::neuraylib::IFactory::Assign_result

This enum represents possible events that can happen during assignment of types.

The enum values are powers of two such that they can be combined in a bitmask. Such a bitmask is returned by assign_from_to().

Enumerator
NULL_POINTER	One of the arguments `source` or `target` is `NULL`. Alternatively, a deep assignment to an instance of mi::IPointer failed due to a `NULL` value.
STRUCTURAL_MISMATCH	There is a structural mismatch between `source` and `target`. One of the two arguments is of type mi::IData_simple and the other one is of mi::IData_collection, or alternatively, both arguments are of type mi::IData_collection and there is at least one key which is of type mi::IData_simple in one argument, and of type mi::IData_collection in the other argument.
NO_CONVERSION	Both arguments (or at least one key thereof) are of different interfaces derived from mi::IData_simple and there is no conversion between them. This happens for example if an instance of mi::ISint32 is assigned to an instance of mi::IString).
TARGET_KEY_MISSING	There is at least one key in `source` which does not exist in `target`.
SOURCE_KEY_MISSING	There is at least one key in `target` which does not exist in `source`.
DIFFERENT_COLLECTIONS	Both arguments `source` and `target` (or the types of at least one key thereof) are collections, but of different type. For example, this flag is set when assigning from static to dynamic arrays, from arrays to maps, or from arrays or maps to compounds, or vice versa.
NON_IDATA_VALUES	The argument `source` is a collection and contains at least one key which is not of type mi::IData, e.g., in untyped arrays or maps. Or `source` is a pointer or contains a key that is a pointer that wraps an instance not derived from mi::IData. Such types cannot get assigned with this method.
INCOMPATIBLE_POINTER_TYPES	Shallow assignment (the default) was requested and the assignment failed due to incompatible pointer types, e.g., assigning from mi::IConst_pointer to mi::IPointer, or between different typed pointers (mi::IPointer::set_pointer() or mi::IConst_pointer::set_pointer() failed).
DEEP_ASSIGNMENT_TO_CONST_POINTER	Deep assignment was requested and `target` is an instance of mi::IConst_pointer (or a key of `target` is an instance of mi::IConst_pointer).
INCOMPATIBLE_PRIVACY_LEVELS	The assignment failed due to incompatible privacy levels, i.e., mi::IRef::set_reference() returned error code -4.
INCOMPATIBLE_ENUM_TYPES	The assignment failed due to incompatible enum types.
INCOMPATIBLE_OPTIONS	The assignment failed due to incompatible options.

Member Function Documentation

^◆ assign_from_to()

virtual Uint32 mi::neuraylib::IFactory::assign_from_to	(	const IData *	source,
		IData *	target,
		Uint32	options = `0`
	)

pure virtual

Assigns the value(s) of source to target.

Assignment succeeds if both source and target are of the same type. If not, the method tries to perform an assignment on a best effort basis. For example, an assignment between interfaces derived from mi::INumber might require a conversion as defined in the C/C++ standard. If both arguments are of type mi::IData_collection, assignment happens for all keys existing in both parameters.

Parameters

source	The instance to assign from.
target	The instance to assign to.
options	See Assign_clone_options for possible options.

Returns: The return value is a bit field that indicates which events occurred during assignment. See Assign_result for possible events.

: The value 0 indicates that the assignment took place without any problems. Note that a non-zero value is not necessarily an error, it is up to the caller to interpret the result according to the context. For example, assigning from an instance of mi::IFloat32_3 to an instance of mi::IFloat32_2 will result in TARGET_KEY_MISSING because there is no key named "z" in mi::IFloat32_2. It is up to the caller to decide whether this is the intended behavior or not.

^◆ clone() [1/2]

template<class T>

T * mi::neuraylib::IFactory::clone	(	const IData *	source,
		Uint32	options = `0`
	)

inline

Creates a clone of a type.

It is not possible to clone untyped pointers and collections that wrap/contain interface pointers that are not of type mi::IData.

This templated member function is a wrapper of the non-template variant for the user's convenience. It eliminates the need to call mi::base::IInterface::get_interface(const Uuid&) on the returned pointer, since the return type already is a pointer to the type T specified as template parameter.

Parameters

source	The instance to clone.
options	See Assign_clone_options for possible options.

Template Parameters

T	The interface type of the class to create

^◆ clone() [2/2]

virtual IData * mi::neuraylib::IFactory::clone	(	const IData *	source,
		Uint32	options = `0`
	)

pure virtual

Creates a clone of a type.

It is not possible to clone untyped pointers and collections that wrap/contain interface pointers that are not of type mi::IData.

Parameters

source	The instance to clone.
options	See Assign_clone_options for possible options.

^◆ compare()

virtual Sint32 mi::neuraylib::IFactory::compare	(	const IData *	lhs,
		const IData *	rhs
	)

pure virtual

Compares two instances of mi::IData.

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

If lhs or rhs is NULL, the result is the lexicographic comparison of the pointer addresses themselves.
Otherwise, the type names of lhs and rhs are considered. If they are different, the result is determined by strcmp() on the type names. For example, this method never returns 0 if you compare a dynamic array and a static array, even if they have the same element type, length, and equal element values.
Finally, the values of the elements are compared lexicographically, as defined by operator< or strcmp() with the following special cases for selected interfaces:
- mi::IRef: If mi::IRef::get_reference_name() returns NULL for at least one operand, the result is the lexicographic comparison of the pointer addresses. Otherwise, the result is determined by strcmp() on the names of the referenced DB elements.
- mi::IPointer and mi::IConst_pointer: If mi::IPointer::get_pointer() or mi::IConst_pointer::get_pointer() returns NULL for at least one operand, the result is the lexicographic comparison of the pointer addresses. Otherwise, if at least one pointer is not of the type mi::IData, the result is the lexicographic comparison of the pointer addresses. Finally (both pointers are of type mi::IData), the result is determined by the recursive invocation of this method on these pointers.
- mi::IData_collection: First, if the collections have different length, this decides the comparison. Next, the elements are compared pairwise in lexicographic order of the element index. If the element keys are different, strcmp() on the element keys determines the result. Otherwise, the element values are compared by recursive invocation of this method (or lexicographic comparison of the pointer addresses if one element is not of type mi::IData). If they are different, this decides the result, otherwise the comparison continues with the next element. If all elements are equal, the result is 0.

Parameters

lhs	The left-hand side operand for the comparison.
rhs	The right-hand side operand for the comparison.

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

^◆ create() [1/3]

template<class T>

T * mi::neuraylib::IFactory::create ( )

inline

Creates an object of the type T.

This factory allows the creation of instances of mi::IData and derived interfaces. It is not possible to create instances of mi::IRef or collections of references. Use mi::neuraylib::IDice_transaction instead.

The created object will be initialized in a manner dependent upon the passed type name. Each class has its own policy on initialization. So, one should not make any assumptions on the values of the various class members.

Note that there are two versions of this templated member function, one that takes no arguments, and another one that takes one or three arguments (the type name, and two optional arguments passed to the factory class). The version with no arguments can only be used to create a subset of supported types: it supports only those types where the type name can be deduced from the template parameter, i.e., it does not support arrays, structures, maps, and pointers. The version with one or three arguments can be used to create any type (but requires the type name as parameter, which is redundant for many types). Attempts to use the version with no arguments with a template parameter where the type name can not be deduced results in compiler errors.

This templated member function is a wrapper of the non-template variant for the user's convenience. It eliminates the need to call mi::base::IInterface::get_interface(const Uuid&) on the returned pointer, since the return type already is a pointer to the type T specified as template parameter.

Template Parameters

T	The interface type of the class to create

Returns: A pointer to the created object on success, or NULL on failure (e.g., invalid type name).

^◆ create() [2/3]

template<class T>

T * mi::neuraylib::IFactory::create	(	const char *	type_name,
		Uint32	argc = `0`,
		const base::IInterface *	argv[] = `0`
	)

inline

Creates an object of the type type_name.

The arguments passed to this method are passed to the constructor of the created object.

This factory allows the creation of instances of mi::IData and derived interfaces. It is not possible to create instances of mi::IRef or collections of references. Use mi::neuraylib::IDice_transaction instead.

The created object will be initialized in a manner dependent upon the passed type name. Each class has its own policy on initialization. So, one should not make any assumptions on the values of the various class members.

Note that there are two versions of this templated member function, one that takes no arguments, and another one that takes one or three arguments (the type name, and two optional arguments passed to the factory class). The version with no arguments can only be used to create a subset of supported types: it supports only those types where the type name can be deduced from the template parameter, i.e., it does not support arrays, structures, maps, and pointers. The version with one or three arguments can be used to create any type (but requires the type name as parameter, which is redundant for many types). Attempts to use the version with no arguments with a template parameter where the type name can not be deduced results in compiler errors.

This templated member function is a wrapper of the non-template variant for the user's convenience. It eliminates the need to call mi::base::IInterface::get_interface(const Uuid&) on the returned pointer, since the return type already is a pointer to the type T specified as template parameter.

Parameters

type_name	The type name of the object to create
argc	The number of elements in `argv`
argv	The array of arguments passed to the constructor

Template Parameters

T	The interface type of the class to create

Returns: A pointer to the created object on success, or NULL on failure (e.g., invalid type name).

^◆ create() [3/3]

virtual base::IInterface * mi::neuraylib::IFactory::create	(	const char *	type_name,
		Uint32	argc = `0`,
		const base::IInterface *	argv[] = `0`
	)

pure virtual

Creates an object of the type type_name.

The arguments passed to this method are passed to the constructor of the created object.

This factory allows the creation of instances of mi::IData and derived interfaces. It is not possible to create instances of mi::IRef or collections of references. Use mi::neuraylib::IDice_transaction instead.

The created object will be initialized in a manner dependent upon the passed type name. Each class has its own policy on initialization. So, one should not make any assumptions on the values of the various class members.

Parameters

type_name	The type name of the object to create. See Types for possible type names.
argc	The number of elements in `argv`.
argv	The array of arguments passed to the constructor.

Returns: A pointer to the created object on success, or NULL on failure (e.g., invalid type name).

^◆ dump() [1/2]

virtual const IString * mi::neuraylib::IFactory::dump	(	const IData *	data,
		const char *	name = `0`,
		Size	depth = `0`
	)

pure virtual

Returns a textual representation of a type.

The textual representation is of the form "type name = value" if name is not NULL, and of the form "value" if name is NULL. The representation of the value might contain line breaks, for example for structures and arrays. Subsequent lines have a suitable indentation. The assumed indentation level of the first line is specified by depth.

^◆ dump() [2/2]

virtual const IString * mi::neuraylib::IFactory::dump	(	neuraylib::ITransaction *	transaction,
		const IData *	data,
		const char *	name = `0`,
		Size	depth = `0`
	)

pure virtual

Returns a textual representation of a type.

This overload of mi::neuraylib::IFactory::dump(const IData*,const char*,Size) requires an additional transaction pointer. This is necessary to support the dumping of possibly nested non-mi::IData types.

^◆ get_enum_decl()

virtual const IEnum_decl * mi::neuraylib::IFactory::get_enum_decl ( const char * enum_name ) const

pure virtual

Returns a registered enum declaration.

Parameters

enum_name The name of the enum declaration to return.

Returns: The enum declaration for name, or NULL if there is no enum declaration for that name.

^◆ get_structure_decl()

virtual const IStructure_decl * mi::neuraylib::IFactory::get_structure_decl ( const char * structure_name ) const

pure virtual

Returns a registered structure declaration.

Parameters

structure_name The name of the structure declaration to return.

Returns: The structure declaration for name, or NULL if there is no structure declaration for that name.

Public Types

Public Member Functions

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ Assign_clone_options

◆ Assign_result

Member Function Documentation

◆ assign_from_to()

◆ clone() [1/2]

◆ clone() [2/2]

◆ compare()

◆ create() [1/3]

◆ create() [2/3]

◆ create() [3/3]

◆ dump() [1/2]

◆ dump() [2/2]

◆ get_enum_decl()

◆ get_structure_decl()

^◆ Assign_clone_options

^◆ Assign_result

^◆ assign_from_to()

^◆ clone() [1/2]

^◆ clone() [2/2]

^◆ compare()

^◆ create() [1/3]

^◆ create() [2/3]

^◆ create() [3/3]

^◆ dump() [1/2]

^◆ dump() [2/2]

^◆ get_enum_decl()

^◆ get_structure_decl()