Provides the C-style interface for ioda::Variable objects. More...

Collaboration diagram for Variables:

Modules
	ioda_variable_isa
	Checks a variable's type.

	ioda_variable_write_full
	Write an entire variable.

	ioda_variable_read_full
	Read an entire variable.

Files
file	Variable_c.h
	C bindings for ioda::Variable

file	Variable_c.cpp
	C bindings for ioda::Variable

Classes
struct	c_variable
	Class-like encapsulation of C variable functions. More...

Macros
#define	IODA_VARIABLE_ISA_IMPL(funcnamestr, Type)

#define	IODA_VARIABLE_WRITE_FULL(funcnamestr, Type)

#define	IODA_VARIABLE_READ_FULL(funcnamestr, Type)

Functions
IODA_DL void	ioda_variable_destruct (struct ioda_variable *var)
	Deallocates an variable. More...

IODA_DL struct ioda_has_attributes *	ioda_variable_atts (const struct ioda_variable *var)
	Access a variable's attributes. More...

IODA_DL struct ioda_dimensions *	ioda_variable_get_dimensions (const struct ioda_variable *)
	Gets an variable's dimensions. More...

IODA_DL bool	ioda_variable_resize (struct ioda_variable var, size_t N, const long newDims)
	Resize a variable. More...

IODA_DL bool	ioda_variable_attachDimensionScale (struct ioda_variable var, unsigned int DimensionNumber, const struct ioda_variable scale)
	Attach a dimension scale to a variable. More...

IODA_DL bool	ioda_variable_detachDimensionScale (struct ioda_variable var, unsigned int DimensionNumber, const struct ioda_variable scale)
	Detach a dimension scale from a variable. More...

IODA_DL bool	ioda_variable_setDimScale (struct ioda_variable var, size_t n_dims, const struct ioda_variable const *dims)
	Convenience function to set a sequence of scales on a variable. More...

IODA_DL int	ioda_variable_isDimensionScale (const struct ioda_variable *var)
	Check if a variable acts as a dimension scale. More...

IODA_DL bool	ioda_variable_setIsDimensionScale (struct ioda_variable var, size_t sz_name, const char dimensionScaleName)
	Convert a variable into a dimension scale. More...

IODA_DL size_t	ioda_variable_getDimensionScaleName (const struct ioda_variable var, size_t len_out, char out)
	Get the name of the dimension scale. More...

IODA_DL int	ioda_variable_isDimensionScaleAttached (const struct ioda_variable var, unsigned int DimensionNumber, const struct ioda_variable scale)
	Is the variable "scale" attached as dimension "DimensionNumber" to variable "var"? More...

ioda_has_attributes *	ioda_variable_atts (const ioda_variable *var)

ioda_dimensions *	ioda_variable_get_dimensions (const ioda_variable *var)

	C_TEMPLATE_FUNCTION_DEFINITION (ioda_variable_isa, IODA_VARIABLE_ISA_IMPL)

	C_TEMPLATE_FUNCTION_DEFINITION_NOSTR (ioda_variable_write_full, IODA_VARIABLE_WRITE_FULL)

IODA_DL bool	ioda_variable_write_full_str (ioda_variable var, size_t sz, const char const *vals)
	Write a sequence of strings to a variable. More...

	C_TEMPLATE_FUNCTION_DEFINITION_NOSTR (ioda_variable_read_full, IODA_VARIABLE_READ_FULL)

IODA_DL ioda_string_ret_t *	ioda_variable_read_full_str (const ioda_variable *var)

Detailed Description

Provides the C-style interface for ioda::Variable objects.

Macro Definition Documentation

◆ IODA_VARIABLE_ISA_IMPL

#define IODA_VARIABLE_ISA_IMPL	(	funcnamestr,
		Type
	)

Value:

  IODA_DL int funcnamestr(const ioda_variable* var) {                                              \
    C_TRY;                                                                                         \
    Expects(var != nullptr);                                                                       \
    bool ret = var->var.isA<Type>();                                                               \
    C_CATCH_AND_RETURN((ret) ? 1 : 0, -1);                                                         \
  }

Definition at line 134 of file Variable_c.cpp.

◆ IODA_VARIABLE_READ_FULL

#define IODA_VARIABLE_READ_FULL	(	funcnamestr,
		Type
	)

Value:

  IODA_DL bool funcnamestr(const ioda_variable* var, size_t sz, Type* vals) {                      \
    C_TRY;                                                                                         \
    Expects(var != nullptr);                                                                       \
    Expects(vals != nullptr);                                                                      \
    var->var.read<Type>(gsl::span<Type>(vals, sz));                                                \
    C_CATCH_AND_RETURN(true, false);                                                               \
  }

Definition at line 169 of file Variable_c.cpp.

◆ IODA_VARIABLE_WRITE_FULL

#define IODA_VARIABLE_WRITE_FULL	(	funcnamestr,
		Type
	)

Value:

  IODA_DL bool funcnamestr(ioda_variable* var, size_t sz, const Type* vals) {                      \
    C_TRY;                                                                                         \
    Expects(var != nullptr);                                                                       \
    Expects(vals != nullptr);                                                                      \
    var->var.write<Type>(gsl::span<const Type>(vals, sz));                                         \
    C_CATCH_AND_RETURN(true, false);                                                               \
  }

Definition at line 146 of file Variable_c.cpp.

Function Documentation

◆ C_TEMPLATE_FUNCTION_DEFINITION()

C_TEMPLATE_FUNCTION_DEFINITION	(	ioda_variable_isa	,
		IODA_VARIABLE_ISA_IMPL
	)

◆ C_TEMPLATE_FUNCTION_DEFINITION_NOSTR() [1/2]

C_TEMPLATE_FUNCTION_DEFINITION_NOSTR	(	ioda_variable_read_full	,
		IODA_VARIABLE_READ_FULL
	)

◆ C_TEMPLATE_FUNCTION_DEFINITION_NOSTR() [2/2]

C_TEMPLATE_FUNCTION_DEFINITION_NOSTR	(	ioda_variable_write_full	,
		IODA_VARIABLE_WRITE_FULL
	)

◆ ioda_variable_attachDimensionScale()

bool ioda_variable_attachDimensionScale	(	struct ioda_variable *	var,
		unsigned int	DimensionNumber,
		const struct ioda_variable *	scale
	)

Attach a dimension scale to a variable.

Parameters

[in]	var	is the variable.
	DimensionNumber	denotes the dimension which you are adding a scale to. Counts start at zero.
[in]	scale	is the dimension scale that will be attached.

Returns: true on success.; false on failure.

Precondition: var and scale must both be valid.; DimensionNumber must be within the variable's dimensionality.; scale must not already be attached at the same dimension number.; var and scale must share the same backend instance.

Definition at line 60 of file Variable_c.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ioda_variable_atts() [1/2]

ioda_has_attributes* ioda_variable_atts ( const ioda_variable * var )

Definition at line 31 of file Variable_c.cpp.

◆ ioda_variable_atts() [2/2]

IODA_DL struct ioda_has_attributes* ioda_variable_atts ( const struct ioda_variable * var )

Access a variable's attributes.

See also: ioda::Group::atts.

Parameters

[in] var is the variable whose attributes are being accessed.

Returns: A handle to the Has_Attributes container on success (you must free after use).; NULL on failure.

Here is the caller graph for this function:

◆ ioda_variable_destruct()

void ioda_variable_destruct ( struct ioda_variable * var )

Deallocates an variable.

Parameters

var	is the variable to be destructed.

Definition at line 24 of file Variable_c.cpp.

Here is the caller graph for this function:

◆ ioda_variable_detachDimensionScale()

bool ioda_variable_detachDimensionScale	(	struct ioda_variable *	var,
		unsigned int	DimensionNumber,
		const struct ioda_variable *	scale
	)

Detach a dimension scale from a variable.

Parameters

[in]	var	is the variable.
	DimensionNumber	denotes the dimension of var which contains the scale that will be detached.
[in]	scale	is the dimension scale that will be attached.

Returns: true on success.; false on failure.

Precondition: var and scale must both be valid.; DimensionNumber must be within the variable's dimensionality.; scale must already be attached at the specified dimension number.; var and scale must share the same backend instance.

Definition at line 69 of file Variable_c.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ioda_variable_get_dimensions() [1/2]

ioda_dimensions* ioda_variable_get_dimensions ( const ioda_variable * var )

Definition at line 40 of file Variable_c.cpp.

Here is the call graph for this function:

◆ ioda_variable_get_dimensions() [2/2]

IODA_DL struct ioda_dimensions* ioda_variable_get_dimensions ( const struct ioda_variable * )

Gets an variable's dimensions.

Parameters

[in] var is the variable.

Returns: A dimension object that contains the variable's dimensions. Must be freed when no longer used.

Here is the caller graph for this function:

◆ ioda_variable_getDimensionScaleName()

size_t ioda_variable_getDimensionScaleName	(	const struct ioda_variable *	var,
		size_t	len_out,
		char *	out
	)

Get the name of the dimension scale.

Parameters

[in]	var	is the dimension scale.
[out]	out	is the output buffer that will hold the name of the dimension scale. This will always be a null-terminated string. If len_out is smaller than the length of the dimension scale's name, then out will be truncated to fit.
	len_out	is the length (size) of the output buffer, in bytes.

Returns: The minimum size of an output buffer needed to fully read the scale name. Callers should check that the return value is less than len_out. If it is not, then the output buffer is too small and should be expanded. The output buffer is always at least one byte in size (the null byte).; 0 if an error has occurred.

Precondition: var must be valid.; out must be valid (not null!)

Definition at line 109 of file Variable_c.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ioda_variable_isDimensionScale()

int ioda_variable_isDimensionScale ( const struct ioda_variable * var )

Check if a variable acts as a dimension scale.

Parameters

[in] var is the variable.

Returns: 1 if yes.; 0 if no.; -1 on error.

Precondition: var must be valid.

Definition at line 93 of file Variable_c.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ioda_variable_isDimensionScaleAttached()

int ioda_variable_isDimensionScaleAttached	(	const struct ioda_variable *	var,
		unsigned int	DimensionNumber,
		const struct ioda_variable *	scale
	)

Is the variable "scale" attached as dimension "DimensionNumber" to variable "var"?

Parameters

[in]	var	is the variable.
	DimensionNumber	is the dimension number. Numbering starts at zero.
[in]	scale	is the candidate dimension scale.

Returns: 1 if attached.; 0 if not attached.; -1 on error.

Precondition: var and scale must both be valid and from the same backend engine instance.; DimensionNumber must be less than the variable's dimensionality.

Definition at line 123 of file Variable_c.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ioda_variable_read_full_str()

IODA_DL ioda_string_ret_t* ioda_variable_read_full_str ( const ioda_variable * var )

Definition at line 180 of file Variable_c.cpp.

Here is the call graph for this function:

◆ ioda_variable_resize()

bool ioda_variable_resize	(	struct ioda_variable *	var,
		size_t	N,
		const long *	newDims
	)

Resize a variable.

Parameters

[in]	var	is the variable.
	N	is the dimensionality of newDims. Must match current dimensionality.
[in]	newDims	is a sequence of dimension sizes.

Returns: true on success.; false on failure.

Precondition: var must be valid.; N and newDims must match the variable's current dimensionality. There is no way to add more dimensions to an existing variable.

Definition at line 50 of file Variable_c.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ioda_variable_setDimScale()

bool ioda_variable_setDimScale	(	struct ioda_variable *	var,
		size_t	n_dims,
		const struct ioda_variable const	dims
	)

Convenience function to set a sequence of scales on a variable.

Parameters

[in]	var	is the variable.
	n_dims	is the size of the dims array.
[in]	dims	is a sequence of dimension scales that will be attached to var. dims[0] will be attached to var along dimension 0, dims[1] will be attached to var along dimension 1, and so on.

Returns: true on success.; false on failure.

Precondition: var must be valid.; dims must be non-null, and each scale in dims must be valid and share the same backend instance as var.; The scales in dims should not already be attached to var at their expected places.; n_dims must be less than or equal to the dimensionality of var.

Definition at line 78 of file Variable_c.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ioda_variable_setIsDimensionScale()

bool ioda_variable_setIsDimensionScale	(	struct ioda_variable *	var,
		size_t	sz_name,
		const char *	dimensionScaleName
	)

Convert a variable into a dimension scale.

Parameters

[in]	var	is the variable that will become a scale.
	sz_name	is strlen(dimensionScaleName). Fortran compatability.
[in]	dimensionScaleName	is the "name" of the dimension scale. This name does not need to correspond to the variable's name, and acts as a convenience label when reading data.

Returns: true on success.; false on failure.

Precondition: var must be valid.; dimensionScaleName must be valid. If unused, it should be set to an empty string and not NULL.

Definition at line 100 of file Variable_c.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ioda_variable_write_full_str()

IODA_DL bool ioda_variable_write_full_str	(	struct ioda_variable *	var,
		size_t	sz,
		const char const	vals
	)

Write a sequence of strings to a variable.

Parameters

[in]	var	is the variable.
	sz	is the number of strings to write. For ioda_variable_write_full_str, this must match var's current number of elements.
[in]	vals	is a sequence of sz NULL-terminated strings.

Returns: true on success.; false on failure.

Precondition: var must be a valid string-typed variable.; sz must equal the variable's current number of elements.; vals must be valid and have at least length sz.; Each val in vals must be a NULL-terminated string. Each val must not be NULL itself.

Definition at line 157 of file Variable_c.cpp.

Here is the call graph for this function:

Modules

Files

Classes

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ IODA_VARIABLE_ISA_IMPL

◆ IODA_VARIABLE_READ_FULL

◆ IODA_VARIABLE_WRITE_FULL

Function Documentation

◆ C_TEMPLATE_FUNCTION_DEFINITION()

◆ C_TEMPLATE_FUNCTION_DEFINITION_NOSTR() [1/2]

◆ C_TEMPLATE_FUNCTION_DEFINITION_NOSTR() [2/2]

◆ ioda_variable_attachDimensionScale()

◆ ioda_variable_atts() [1/2]

◆ ioda_variable_atts() [2/2]

◆ ioda_variable_destruct()

◆ ioda_variable_detachDimensionScale()

◆ ioda_variable_get_dimensions() [1/2]

◆ ioda_variable_get_dimensions() [2/2]

◆ ioda_variable_getDimensionScaleName()

◆ ioda_variable_isDimensionScale()

◆ ioda_variable_isDimensionScaleAttached()

◆ ioda_variable_read_full_str()

◆ ioda_variable_resize()

◆ ioda_variable_setDimScale()

◆ ioda_variable_setIsDimensionScale()

◆ ioda_variable_write_full_str()