Parameter List Handling API

Handling of multiple sections or subsections and the elements in parameter sets. More...

Collaboration diagram for Parameter List Handling API:

Functions
int	GfParmGetEltNb (void *handle, const char *path)
	Count the number of subsections in a section in the parameter set handle.
int	GfParmListSeekFirst (void *handle, const char *path)
	Select the first immediate subsection of a section.
int	GfParmListSeekNext (void *handle, const char *path)
	Advance to the next immediate subsection.
int	GfParmListClean (void *handle, const char *path)
	Remove all the subsections in a section in the parameter set handle.
char *	GfParmListGetCurEltName (void *handle, const char *path)
	Get current subsection name of the parameter set handle during subsection iteration.
const char *	GfParmGetCurStr (void *handle, const char *path, const char *key, const char *deflt)
	Get a string parameter from the parameter set handle based on subsection iteration.
tdble	GfParmGetCurNum (void *handle, const char *path, const char *key, const char *unit, tdble deflt)
	Get a numerical parameter from the parameter set handle based on subsection iteration.
int	GfParmSetCurStr (void *handle, const char *path, const char *key, const char *val)
	Set a string parameter in the parameter set handle based on subsection iteration.
int	GfParmSetCurNum (void *handle, const char *path, const char *key, const char *unit, tdble val)
	Set a numerical parameter in the parameter set handle based on subsection iteration.

Detailed Description

Handling of multiple sections or subsections and the elements in parameter sets.

Iterating safely over an empty or nonempty list

const char *path = "Gearbox/gears";
if (GfParmListSeekFirst(settings, path) == 0) {
    while (GfParmListGetCurEltName(settings, path) != NULL) {
        tdble ratio = GfParmGetCurNum(settings, path, PRM_RATIO, NULL, 0.0f);
        // Use ratio for this gear. Do not mutate the list while iterating.
        if (GfParmListSeekNext(settings, path) != 0) {
            break;
        }
    }
}

settings must be a valid handle. Nested iteration of different sections is possible, but another iterator over the same section replaces its cursor.

Function Documentation

GfParmGetCurNum()

tdble GfParmGetCurNum	(	void *	handle,
		const char *	path,
		const char *	key,
		const char *	unit,
		tdble	deflt )

Get a numerical parameter from the parameter set handle based on subsection iteration.

The internal state of the parameter set handle must point to a current subsection, this is done using GfParmListSeekFirst or GfParmListSeekNext. If the parameter does not exist the given default value is returned without unit conversion.

A subsection can have any name and structure, any section element enclosed by the section given in the path is a subsection.

Parameters

[in]	handle	parameter set handle
[in]	path	path of the section used to iterate subsections
[in]	key	parameter key name
[in]	unit	unit to convert the result to (NULL if SI is desired)
[in]	deflt	Fallback value already expressed in the requested unit.

Returns

Converted numeric value, or deflt unchanged if there is no current element or the attribute is missing or not numeric.

See also

GfParmListSeekFirst

GfParmListSeekNext

Definition at line 2578 of file params.cpp.

Here is the call graph for this function:

GfParmGetCurStr()

const char * GfParmGetCurStr	(	void *	handle,
		const char *	path,
		const char *	key,
		const char *	deflt )

Get a string parameter from the parameter set handle based on subsection iteration.

The internal state of the parameter set handle must point to a current subsection, this is done using GfParmListSeekFirst or GfParmListSeekNext. If the parameter does not yet exist the given default is returned.

A subsection can have any name and structure, any section element enclosed by the section given in the path is a subsection.

Parameters

[in]	handle	parameter set handle
[in]	path	path of the section used to iterate subsections
[in]	key	parameter key name
[in]	deflt	Borrowed fallback string, possibly NULL.

Returns

Borrowed parameter value, or deflt if there is no current element or the attribute is missing, empty or not a string. Do not free the result.

Note

The pointer returned is for immediate use, if you plan to keep the value for a long time, it is necessary to copy the string, because removing the attribute will produce an incoherent pointer.

See also

GfParmListSeekFirst

GfParmListSeekNext

Definition at line 2496 of file params.cpp.

Here is the call graph for this function:

GfParmGetEltNb()

int GfParmGetEltNb	(	void *	handle,
		const char *	path )

Count the number of subsections in a section in the parameter set handle.

A subsection can have any name and structure, any section element enclosed by the section given in the path is a subsection.

Parameters

[in]	handle	parameter set handle
[in]	path	path of the section containing the subsections to count

Returns

Number of immediate child sections, or 0 if the section is missing or empty. Attributes and deeper descendants are not counted.

Definition at line 2243 of file params.cpp.

Here is the call graph for this function:

GfParmListClean()

int GfParmListClean	(	void *	handle,
		const char *	path )

Remove all the subsections in a section in the parameter set handle.

A subsection can have any name and structure, any section element enclosed by the section given in the path is a subsection.

Parameters

[in,out]	handle	parameter set handle
[in]	path	path of the section containing the subsections to remove

Note

The parent section and its own attributes remain. Restart iteration with GfParmListSeekFirst before using current-element functions again.

Returns

0 Ok
-1 Error

Definition at line 2362 of file params.cpp.

Here is the call graph for this function:

GfParmListGetCurEltName()

char * GfParmListGetCurEltName	(	void *	handle,
		const char *	path )

Get current subsection name of the parameter set handle during subsection iteration.

The internal state of the parameter set handle must point to a current subsection, this is done using GfParmListSeekFirst or GfParmListSeekNext. This call returns the name of the current subsection.

A subsection can have any name and structure, any section element enclosed by the section given in the path is a subsection.

Parameters

[in]	handle	parameter set handle
[in]	path	path of the section used to iterate subsections

Returns

Borrowed short name of the current subsection (not its full path). Do not modify or free it, despite the char* return type.
NULL if failed

Note

The pointer returned is for immediate use, if you plan to keep the value for a long time, it is necessary to copy the string, because removing the section will produce an incoherent pointer.

See also

GfParmListSeekFirst

GfParmListSeekNext

Definition at line 2410 of file params.cpp.

Here is the call graph for this function:

GfParmListSeekFirst()

int GfParmListSeekFirst	(	void *	handle,
		const char *	path )

Select the first immediate subsection of a section.

A subsection can have any name and structure, any section element enclosed by the section given in the path is a subsection.

Parameters

[in,out]	handle	Parameter set handle; the cursor is stored in the shared section, not privately in this handle.
[in]	path	path of the section containing the subsections to iterate through

Returns

0 if the parent section exists, even when empty; -1 if missing. Use GfParmListGetCurEltName to check whether a current element exists.

See also

GfParmListSeekNext

GfParmListGetCurEltName

Definition at line 2286 of file params.cpp.

Here is the call graph for this function:

GfParmListSeekNext()

int GfParmListSeekNext	(	void *	handle,
		const char *	path )

Advance to the next immediate subsection.

A subsection can have any name and structure, any section element enclosed by the section given in the path is a subsection.

Parameters

[in,out]	handle	Parameter set handle; changes the shared section cursor.
[in]	path	path of the section containing the subsections to iterate through

Returns

0 Ok
1 End of list reached
-1 if the section is missing or there is no current element (including a call after the end was already reached).

See also

GfParmListSeekFirst

GfParmListGetCurEltName

Definition at line 2323 of file params.cpp.

Here is the call graph for this function:

GfParmSetCurNum()

int GfParmSetCurNum	(	void *	handle,
		const char *	path,
		const char *	key,
		const char *	unit,
		tdble	val )

Set a numerical parameter in the parameter set handle based on subsection iteration.

The internal state of the parameter set handle must point to a current subsection, this is done using GfParmListSeekFirst or GfParmListSeekNext. If the parameter does not yet exist it is created. The value is assigned to the value, min and max.

A subsection can have any name and structure, any section element enclosed by the section given in the path is a subsection.

Parameters

[in,out]	handle	parameter set handle
[in]	path	path of the section used to iterate subsections
[in]	key	parameter key name
[in]	unit	Unit of val (NULL or empty for SI); converted to SI for storage and copied for later serialization.
[in]	val	value to set

Returns

0 ok
-1 error

See also

GfParmListSeekFirst

GfParmListSeekNext

Definition at line 2834 of file params.cpp.

Here is the call graph for this function:

GfParmSetCurStr()

int GfParmSetCurStr	(	void *	handle,
		const char *	path,
		const char *	key,
		const char *	val )

Set a string parameter in the parameter set handle based on subsection iteration.

The internal state of the parameter set handle must point to a current subsection, this is done using GfParmListSeekFirst or GfParmListSeekNext. If the parameter does not yet exist it is created. The within constraint is not checked.

A subsection can have any name and structure, any section element enclosed by the section given in the path is a subsection.

Parameters

[in,out]	handle	parameter set handle
[in]	path	path of the section used to iterate subsections
[in]	key	parameter key name
[in]	val	value (NULL or empty string to remove the parameter)

Note

Copies val and replaces the attribute's type. As with GfParmSetStr, do not pass a borrowed pointer to the same attribute's current value. Removing the last attribute can delete the current section and invalidate the list cursor; restart iteration before using current-element functions.

Returns

0 ok
-1 error

See also

GfParmListSeekFirst

GfParmListSeekNext

Definition at line 2682 of file params.cpp.

Here is the call graph for this function: