param.c File Reference

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <ctype.h>
#include <float.h>
#include <limits.h>
#include "parameter/param_internal.h"
#include "utils_common.h"
#include "yac_assert.h"
#include "geometry.h"

Include dependency graph for param.c:

Go to the source code of this file.

Data Structures
struct	yac_param

Enumerations
enum	{ DEG_RAD_LOOKUP_COUNT = sizeof(deg_rad_lookup) / sizeof(deg_rad_lookup[0]) }

Functions
enum yac_param_type	yac_param_get_type (const struct yac_param *param)
	Get the type of a parameter.
int	yac_param_is_default (const struct yac_param *param)
	Check whether a parameter is at its default value.
const char *	yac_param_get_name (const struct yac_param *param)
	Get the name of the current parameter.
int	yac_param_get_sub_count (const struct yac_param *param, size_t *count)
	Get the number of subparameters.
int	yac_param_get_sub_by_name (struct yac_param *param, const char *name, struct yac_param **sub_param)
	Get a handle to a subparameter by name.
int	yac_param_get_sub_by_index (struct yac_param *param, size_t idx, struct yac_param **sub_param)
	Get a handle to a subparameter by index.
int	yac_param_append (struct yac_param *param, struct yac_param **sub_param)
	Append a new default subparameter to a list parameter and return a handle to it.
int	yac_param_set_scalar (struct yac_param *param, const char *value_str)
	Set the value of a scalar parameter from a string.
int	yac_param_get_scalar (const struct yac_param *param, char *buf, size_t buflen)
	Get the value of a scalar parameter as a string.
int	yac_param_set_scalar_int (struct yac_param *param, int value)
	Set the value of a scalar parameter as an int.
int	yac_param_set_scalar_dble (struct yac_param *param, double value)
	Set the value of a scalar parameter as a double.
int	yac_param_get_scalar_int (const struct yac_param *param, int *value)
	Get the value of a scalar parameter as an int.
int	yac_param_get_scalar_dble (const struct yac_param *param, double *value)
	Get the value of a scalar parameter as a double.
void	yac_param_get_error_buffer (char **buffer, size_t *buffer_size)
int	yac_param_parse_dble (const char *value_str, const char *param_name, double *value)
int	yac_param_parse_dble_with_unit (const char *value_str, const char *param_name, double *value, enum yac_param_angle_unit *unit)
int	yac_param_format_scalar_dble (char *buf, size_t buflen, double value, const char *value_desc, const char *param_name)
const char *	yac_param_get_last_error (void)
	Retrieve the last error message for the calling thread.
void	yac_param_delete (struct yac_param *param)
double	yac_wrap_rad (double value, char const *param_name)
double	yac_wrap_deg (double value, char const *param_name)
double	yac_deg_to_rad (double deg, char const *param_name)
double	yac_rad_to_deg (double rad, char const *param_name)

Variables
static char	error_buf [ERROR_BUF_SIZE] = {'\0'}
struct {
double   deg
double   rad
}	deg_rad_lookup []

Enumeration Type Documentation

anonymous enum

anonymous enum

Enumerator
DEG_RAD_LOOKUP_COUNT

Definition at line 387 of file param.c.

Function Documentation

yac_deg_to_rad()

double yac_deg_to_rad	(	double	deg,
		char const *	param_name )

Convert degrees to radians

Will try to use a precise value from math.h if available, otherwise falls back to the standard formula. All angles are automatically warped to the range [-180, 180) degrees or [-pi, pi) radians by the caller, so no special handling for values outside that range is needed here.

Parameters

deg	angle in degrees
param_name	parameter name for error messages (can be NULL)

Returns

angle in radians

Definition at line 390 of file param.c.

Here is the call graph for this function:

Here is the caller graph for this function:

yac_param_append()

int yac_param_append	(	struct yac_param *	param,
		struct yac_param **	sub_param )

Append a new default subparameter to a list parameter and return a handle to it.

For list parameters, appends a new subparameter generated by the default_factory function provided at list construction. Returns a handle to the new subparameter via the output pointer.

Parameters

	param	Parameter handle (must be a list)
[out]	sub_param	Pointer to output handle for the new subparameter

Returns

0 on success, nonzero on error

Definition at line 107 of file param.c.

Here is the call graph for this function:

Here is the caller graph for this function:

yac_param_delete()

void yac_param_delete

(

struct yac_param *

param

)

Definition at line 307 of file param.c.

Here is the call graph for this function:

Here is the caller graph for this function:

yac_param_format_scalar_dble()

int yac_param_format_scalar_dble	(	char *	buf,
		size_t	buflen,
		double	value,
		const char *	value_desc,
		const char *	param_name )

Format a double scalar value into buf

Parameters

buf	target output buffer
buflen	size of buf in bytes
value	value to be formatted
value_desc	description of the value for error messages
param_name	parameter name for error messages (can be NULL)

Returns

0 on success, 1 on failure (error message is set)

Remarks

The formatting tries to use the highest significant-digit precision that still fits into the buffer, but will fail if the buffer is too small to hold the shortest possible representation of the value.

Definition at line 259 of file param.c.

Here is the caller graph for this function:

yac_param_get_error_buffer()

void yac_param_get_error_buffer	(	char **	buffer,
		size_t *	buffer_size )

Definition at line 177 of file param.c.

Here is the caller graph for this function:

yac_param_get_last_error()

const char * yac_param_get_last_error

(

void

)

Retrieve the last error message for the calling thread.

If a parameter API function returns an error, this function returns a pointer to a thread-local buffer containing a human-readable error message. The pointer is valid until the next API call in the same thread.

Returns

Pointer to the last error message string (never NULL).

Definition at line 301 of file param.c.

Here is the call graph for this function:

Here is the caller graph for this function:

yac_param_get_name()

const char * yac_param_get_name

(

const struct yac_param *

param

)

Get the name of the current parameter.

Returns the name of the parameter referenced by the handle. For root or unnamed parameters, returns NULL. The returned pointer is valid until the next API call in the same thread.

Parameters

param

Parameter handle

Returns

Name of the parameter, or NULL if unnamed/root

Definition at line 50 of file param.c.

Here is the caller graph for this function:

yac_param_get_scalar()

int yac_param_get_scalar	(	const struct yac_param *	param,
		char *	buf,
		size_t	buflen )

Get the value of a scalar parameter as a string.

The value is converted to a string representation and written to the output buffer. The output buffer must be large enough to hold the value and a null terminator. On error, returns nonzero and sets an error message.

Parameters

	param	Parameter handle
[out]	buf	Output buffer for string value
	buflen	Size of output buffer

Returns

0 on success, nonzero on error

Definition at line 128 of file param.c.

Here is the caller graph for this function:

yac_param_get_scalar_dble()

int yac_param_get_scalar_dble	(	const struct yac_param *	param,
		double *	value )

Get the value of a scalar parameter as a double.

Only works if the parameter supports double retrieval. On error or if not supported, returns nonzero and sets an error message.

Parameters

	param	Parameter handle
[out]	value	Pointer to output double value

Returns

0 on success, nonzero on error

Definition at line 166 of file param.c.

Here is the caller graph for this function:

yac_param_get_scalar_int()

int yac_param_get_scalar_int	(	const struct yac_param *	param,
		int *	value )

Get the value of a scalar parameter as an int.

Only works if the parameter supports integer retrieval. On error or if not supported, returns nonzero and sets an error message.

Parameters

	param	Parameter handle
[out]	value	Pointer to output integer value

Returns

0 on success, nonzero on error

Definition at line 157 of file param.c.

Here is the caller graph for this function:

yac_param_get_sub_by_index()

int yac_param_get_sub_by_index	(	struct yac_param *	param,
		size_t	idx,
		struct yac_param **	sub_param )

Get a handle to a subparameter by index.

For struct and list parameters, returns a handle to the i'th subparameter (0 <= idx < sub_count) via the output pointer. For oneof parameters, returns a handle to the active subparameter, if idx=0.

Note: The returned sub_param handle is managed internally and must NOT be freed or deleted by the caller.

Parameters

	param	Parameter handle
	idx	Subparameter index
[out]	sub_param	Pointer to output handle

Returns

0 on success, nonzero on error

Definition at line 92 of file param.c.

Here is the call graph for this function:

Here is the caller graph for this function:

yac_param_get_sub_by_name()

int yac_param_get_sub_by_name	(	struct yac_param *	param,
		const char *	name,
		struct yac_param **	sub_param )

Get a handle to a subparameter by name.

For struct parameters, returns a handle to the subparameter with the given name via the output pointer. For list parameters, returns a handle to the subparameter with the given name. For oneof parameters, returns a handle to the subparameter with the given name, if it is the active one; otherwise returns an error.

Note: The returned sub_param handle is managed internally and must NOT be freed or deleted by the caller.

Parameters

	param	Parameter handle
	name	Subparameter name
[out]	sub_param	Pointer to output handle

Returns

0 on success, nonzero on error

Definition at line 75 of file param.c.

Here is the call graph for this function:

Here is the caller graph for this function:

yac_param_get_sub_count()

int yac_param_get_sub_count	(	const struct yac_param *	param,
		size_t *	count )

Get the number of subparameters.

For struct parameters, sets count to the number of named subparameters. For list parameters, sets count to the current number of elements in the list. For oneof parameters, sets count to one. For scalar or empty parameters, sets count to 0 and sets an error message.

Parameters

	param	Parameter handle
[out]	count	Pointer to output count

Returns

0 on success, nonzero on error

Definition at line 60 of file param.c.

Here is the call graph for this function:

Here is the caller graph for this function:

yac_param_get_type()

enum yac_param_type yac_param_get_type

(

const struct yac_param *

param

)

Get the type of a parameter.

Returns the type of the parameter referenced by the handle. This can be used to determine if the parameter is a scalar, struct, list, or empty.

Parameters

param

Parameter handle

Returns

Parameter type (see yac_param_type)

Definition at line 24 of file param.c.

Here is the call graph for this function:

Here is the caller graph for this function:

yac_param_is_default()

int yac_param_is_default

(

const struct yac_param *

param

)

Check whether a parameter is at its default value.

Returns 1 if the parameter is currently set to its default value, 0 if not. On error (e.g., invalid handle), returns -1 and sets an error message.

Parameters

param

Parameter handle

Returns

1 if at default, 0 if not, -1 on error

Definition at line 37 of file param.c.

Here is the call graph for this function:

Here is the caller graph for this function:

yac_param_parse_dble()

int yac_param_parse_dble	(	const char *	value_str,
		const char *	param_name,
		double *	value )

Parse a double from value_str.

Parameters

value_str	string to parse; if NULL the call fails with an error
param_name	name of the parameter, used in error messages
value	receives the parsed double on success

Returns

0 on success, 1 on parse error (error message is set)

Definition at line 182 of file param.c.

Here is the caller graph for this function:

yac_param_parse_dble_with_unit()

int yac_param_parse_dble_with_unit	(	const char *	value_str,
		const char *	param_name,
		double *	value,
		enum yac_param_angle_unit *	unit )

Parse a double and optional angle unit suffix from value_str.

Accepted forms: "<double>", "<double> <unit>", "<double><unit>" with unit in {deg, rad, d, r} (case-insensitive).

Parameters

[in]	value_str	string to parse; if NULL the call fails with an error
[in]	param_name	name of the parameter, used in error messages
[out]	value	receives the parsed double on success
[out]	unit	receives parsed/default unit on success

Returns

0 on success, 1 on parse error (error message is set)

Definition at line 196 of file param.c.

Here is the call graph for this function:

Here is the caller graph for this function:

yac_param_set_scalar()

int yac_param_set_scalar	(	struct yac_param *	param,
		const char *	value_str )

Set the value of a scalar parameter from a string.

The value string is parsed and converted to the parameter's type internally. For example, "42" for an integer, "3.14" for a double, or "foo" for a string. On error (e.g., invalid format), returns nonzero and sets an error message.

Parameters

param	Parameter handle
value_str	String representation of the value

Returns

0 on success, nonzero on error

Definition at line 118 of file param.c.

Here is the caller graph for this function:

yac_param_set_scalar_dble()

int yac_param_set_scalar_dble	(	struct yac_param *	param,
		double	value )

Set the value of a scalar parameter as a double.

Only works if the parameter supports double assignment. On error or if not supported, returns nonzero and sets an error message.

Parameters

param	Parameter handle
value	Double value to set

Returns

0 on success, nonzero on error

Definition at line 148 of file param.c.

Here is the caller graph for this function:

yac_param_set_scalar_int()

int yac_param_set_scalar_int	(	struct yac_param *	param,
		int	value )

Set the value of a scalar parameter as an int.

Only works if the parameter supports integer assignment. On error or if not supported, returns nonzero and sets an error message.

Parameters

param	Parameter handle
value	Integer value to set

Returns

0 on success, nonzero on error

Definition at line 139 of file param.c.

Here is the caller graph for this function:

yac_rad_to_deg()

double yac_rad_to_deg	(	double	rad,
		char const *	param_name )

Convert radians to degrees

Will try to use a precise value from math.h if available, otherwise falls back to the standard formula. All angles are automatically warped to the range [-180, 180) degrees or [-pi, pi) radians by the caller, so no special handling for values outside that range is needed here.

Parameters

rad	angle in radians
param_name	parameter name for error messages (can be NULL)

Returns

angle in degrees

Definition at line 404 of file param.c.

Here is the call graph for this function:

Here is the caller graph for this function:

yac_wrap_deg()

double yac_wrap_deg	(	double	value,
		char const *	param_name )

Utility functions for warpping angle values to the standard range [-180, 180) degrees.

Parameters

value	angle value to be wrapped
param_name	parameter name for error messages (can be NULL)

Returns

wrapped angle value

Definition at line 336 of file param.c.

Here is the caller graph for this function:

yac_wrap_rad()

double yac_wrap_rad	(	double	value,
		char const *	param_name )

Utility functions for warpping angle values to the standard range [-pi, pi) radians.

Parameters

value	angle value to be wrapped
param_name	parameter name for error messages (can be NULL)

Returns

wrapped angle value

Definition at line 322 of file param.c.

Here is the caller graph for this function:

Variable Documentation

deg

double deg

Definition at line 350 of file param.c.

[struct]

struct { ... } deg_rad_lookup[]

error_buf

char error_buf[ERROR_BUF_SIZE] = {'\0'}

static

Definition at line 17 of file param.c.

rad

double rad

Definition at line 351 of file param.c.