Formattable interconverts between the primitive numeric types (double, long, etc.) as well as i18n_udate and char string.

Required Header

#include <utils_i18n.h>

Overview

Internally, an i18n_formattable_h handle holds an object that is a union of primitive types. As such, it can only store one flavor of data at a time. To determine what flavor of data it contains, use the i18n_formattable_get_type function.

Functions
int	i18n_formattable_create_default (i18n_formattable_h *formattable)
	Creates a new default i18n_formattable_h.
int	i18n_formattable_create_with_udate (i18n_udate date, i18n_formattable_h *formattable)
	Creates a new i18n_formattable_h handle with an i18n_udate instance.
int	i18n_formattable_create_with_double (double value, i18n_formattable_h *formattable)
	Creates a new i18n_formattable_h handle with a double value.
int	i18n_formattable_create_with_long (int32_t value, i18n_formattable_h *formattable)
	Creates a new i18n_formattable_h handle with a long value.
int	i18n_formattable_create_with_int64 (int64_t value, i18n_formattable_h *formattable)
	Creates a new i18n_formattable_h handle with an int64_t value.
int	i18n_formattable_create_with_char_string (const char str_to_copy, i18n_formattable_h formattable)
	Creates a new i18n_formattable_h handle with a char string pointer.
int	i18n_formattable_create_with_formattable_array (const i18n_formattable_h array_to_copy, int32_t count, i18n_formattable_h formattable)
	Creates a new i18n_formattable_h handle with an array of i18n_formattable_h handles.
int	i18n_formattable_destroy (i18n_formattable_h formattable)
	Releases the given i18n_formattable_h handle.
int	i18n_formattable_clone (i18n_formattable_h formattable, i18n_formattable_h *clone)
	Clones the given formattable handle with the related object to the clone handle.
int	i18n_formattable_get_array (i18n_formattable_h formattable, i18n_formattable_h *array, int32_t count)
	Gets the array value and count of the given formattable object.
int	i18n_formattable_get_date (i18n_formattable_h formattable, i18n_udate *date)
	Gets the date value of the given formattable object.
int	i18n_formattable_get_double (i18n_formattable_h formattable, double *value)
	Gets the double value of the given formattable object.
int	i18n_formattable_get_int64 (i18n_formattable_h formattable, int64_t *value)
	Gets the int64 value of the given formattable object.
int	i18n_formattable_get_long (i18n_formattable_h formattable, int32_t *value)
	Gets the long value of the given formattable object.
int	i18n_formattable_get_string (i18n_formattable_h formattable, char **value)
	Gets the string value of the given formattable object.
int	i18n_formattable_get_type (i18n_formattable_h formattable, i18n_formattable_type_e *type)
	Gets the data type of the given formattable object.
int	i18n_formattable_is_numeric (i18n_formattable_h formattable, bool *is_numeric)
	Sets the variable pointed by the is_numeric pointer to `true` if the data type of the given formattable object is I18N_FORMATTABLE_TYPE_DOUBLE, I18N_FORMATTABLE_TYPE_LONG or I18N_FORMATTABLE_TYPE_INT64.
int	i18n_formattable_not_equal (i18n_formattable_h formattable, i18n_formattable_h other, bool *not_equal)
	Sets the variable pointed by the not_equal pointer to `true` if the given formattable object is not equal to the given other formattable object.
int	i18n_formattable_equal (i18n_formattable_h formattable, i18n_formattable_h other, bool *equal)
	Sets the variable pointed by the equal pointer to `true` if the given formattable object is equal to the given other formattable object.
int	i18n_formattable_element_at (i18n_formattable_h formattable, int32_t index, i18n_formattable_h *element)
	Sets the object pointed by the element pointer to the element at the index position in the array stored by the given formattable object (if its type is I18N_FORMATTABLE_TYPE_ARRAY).
int	i18n_formattable_set_array (i18n_formattable_h formattable, const i18n_formattable_h *array, int32_t count)
	Sets the array value and count of the given formattable object and changes the type to I18N_FORMATTABLE_TYPE_ARRAY.
int	i18n_formattable_set_date (i18n_formattable_h formattable, i18n_udate date)
	Sets the date value of the given formattable object and changes the type to the I18N_FORMATTABLE_TYPE_DATE.
int	i18n_formattable_set_double (i18n_formattable_h formattable, double value)
	Sets the double value of the given formattable object and changes the type to the I18N_FORMATTABLE_TYPE_DOUBLE.
int	i18n_formattable_set_int64 (i18n_formattable_h formattable, int64_t value)
	Sets the int64 value of the given formattable object and changes the type to the I18N_FORMATTABLE_TYPE_INT64.
int	i18n_formattable_set_long (i18n_formattable_h formattable, int32_t value)
	Sets the long value of the given formattable object and changes the type to the I18N_FORMATTABLE_TYPE_LONG.
int	i18n_formattable_set_string (i18n_formattable_h formattable, const char *string_to_copy)
	Sets the string value of the given formattable object and changes the type to the I18N_FORMATTABLE_TYPE_STRING.
Typedefs
typedef void *	i18n_formattable_h
	Handle to the object of class used for formatting i18n_format_h and its subclasses.

Typedef Documentation

typedef void* i18n_formattable_h

Handle to the object of class used for formatting i18n_format_h and its subclasses.

Since :: 3.0

Enumeration Type Documentation

enum i18n_formattable_type_e

Enumeration for the flavor of data type contained within an i18n_formattable_h object.

Since :: 3.0

Enumerator:

I18N_FORMATTABLE_TYPE_DATE	Selector indicating an i18n_udate value
I18N_FORMATTABLE_TYPE_DOUBLE	Selector indicating a double value
I18N_FORMATTABLE_TYPE_LONG	Selector indicating a 32-bit integer value
I18N_FORMATTABLE_TYPE_STRING	Selector indicating a string value
I18N_FORMATTABLE_TYPE_ARRAY	Selector indicating an array of i18n_formattable_h
I18N_FORMATTABLE_TYPE_INT64	Selector indicating a 64-bit integer value
I18N_FORMATTABLE_TYPE_OBJECT	Selector indicating a generic object value. In the current version of the API, such objects are not supported and cannot be used. This value was added for completeness and possible future extensions.

Function Documentation

int i18n_formattable_clone	(	i18n_formattable_h	formattable,
		i18n_formattable_h *	clone
	)

Clones the given formattable handle with the related object to the clone handle.

Since :: 2.3.2 and 3.0

Clones can be used concurrently in multiple threads.

Remarks:: The cloned object should be released by the caller with the i18n_formattable_destroy() function.

Parameters:

[in]	formattable	A handle to the formattable object
[out]	clone	A pointer to a handle to the formattable object which will be filled with a copy of the formattable handle.

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_OUT_OF_MEMORY	Out of memory

int i18n_formattable_create_default ( i18n_formattable_h * formattable )

Creates a new default i18n_formattable_h.

Since :: 2.3.2 and 3.0

Remarks:: The created object should be released by the caller with the i18n_formattable_destroy() function.

Parameters:

[out] formattable A pointer to a handle to the newly created formattable object

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_OUT_OF_MEMORY	Out of memory

int i18n_formattable_create_with_char_string	(	const char *	str_to_copy,
		i18n_formattable_h *	formattable
	)

Creates a new i18n_formattable_h handle with a char string pointer.

Assumes that the char string is null terminated.

Since :: 2.3.2 and 3.0

Remarks:: The created object should be released by the caller with the i18n_formattable_destroy() function.

Parameters:

[in]	str_to_copy	The char string
[out]	formattable	A pointer to a handle to the newly created formattable object

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_OUT_OF_MEMORY	Out of memory

int i18n_formattable_create_with_double	(	double	value,
		i18n_formattable_h *	formattable
	)

Creates a new i18n_formattable_h handle with a double value.

Since :: 2.3.2 and 3.0

Remarks:: The created object should be released by the caller with the i18n_formattable_destroy() function.

Parameters:

[in]	value	The double value to be used
[out]	formattable	A pointer to a handle to the newly created formattable object

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_OUT_OF_MEMORY	Out of memory

int i18n_formattable_create_with_formattable_array	(	const i18n_formattable_h *	array_to_copy,
		int32_t	count,
		i18n_formattable_h *	formattable
	)

Creates a new i18n_formattable_h handle with an array of i18n_formattable_h handles.

Since :: 2.3.2 and 3.0

Remarks:: The created object should be released by the caller with the i18n_formattable_destroy() function.

Parameters:

[in]	array_to_copy	An array with the i18n_formattable_h handles
[in]	count	The number of the elements in the array
[out]	formattable	A pointer to a handle to the newly created formattable object

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_OUT_OF_MEMORY	Out of memory

int i18n_formattable_create_with_int64	(	int64_t	value,
		i18n_formattable_h *	formattable
	)

Creates a new i18n_formattable_h handle with an int64_t value.

Since :: 2.3.2 and 3.0

Remarks:: The created object should be released by the caller with the i18n_formattable_destroy() function.

Parameters:

[in]	value	The int64_t value to be used
[out]	formattable	A pointer to a handle to the newly created formattable object

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_OUT_OF_MEMORY	Out of memory

int i18n_formattable_create_with_long	(	int32_t	value,
		i18n_formattable_h *	formattable
	)

Creates a new i18n_formattable_h handle with a long value.

Since :: 2.3.2 and 3.0

Remarks:: The created object should be released by the caller with the i18n_formattable_destroy() function.

Parameters:

[in]	value	The long value to be used
[out]	formattable	A pointer to a handle to the newly created formattable object

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_OUT_OF_MEMORY	Out of memory

int i18n_formattable_create_with_udate	(	i18n_udate	date,
		i18n_formattable_h *	formattable
	)

Creates a new i18n_formattable_h handle with an i18n_udate instance.

Since :: 2.3.2 and 3.0

Remarks:: The created object should be released by the caller with the i18n_formattable_destroy() function.

Parameters:

[in]	date	The i18n_udate instance
[out]	formattable	A pointer to a handle to the newly created formattable object

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_OUT_OF_MEMORY	Out of memory

int i18n_formattable_destroy ( i18n_formattable_h formattable )

Releases the given i18n_formattable_h handle.

Since :: 2.3.2 and 3.0

Parameters:

[in] formattable A handle to the formattable object to be released

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_formattable_element_at	(	i18n_formattable_h	formattable,
		int32_t	index,
		i18n_formattable_h *	element
	)

Sets the object pointed by the element pointer to the element at the index position in the array stored by the given formattable object (if its type is I18N_FORMATTABLE_TYPE_ARRAY).

Since :: 2.3.2 and 3.0

Remarks:: If this object is not of type I18N_FORMATTABLE_TYPE_ARRAY then the result is undefined.

The obtained formattable element should not be released by the caller as it belongs to the given formattable object of type I18N_FORMATTABLE_TYPE_ARRAY.

Parameters:

[in]	formattable	A handle to the formattable object
[in]	index	A number representing the position in the array from which the element should be obtained
[out]	element	A pointer to a handle to the formattable object which will be filled by the function

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_INDEX_OUTOFBOUNDS	Index value out of range
I18N_ERROR_INVALID_FORMAT	The given formattable type is not an array

int i18n_formattable_equal	(	i18n_formattable_h	formattable,
		i18n_formattable_h	other,
		bool *	equal
	)

Sets the variable pointed by the equal pointer to true if the given formattable object is equal to the given other formattable object.

Since :: 2.3.2 and 3.0

Parameters:

[in]	formattable	A handle to the formattable object
[in]	other	A handle to the other formattable object
[out]	equal	A pointer to a boolean variable which will be filled by the function

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_formattable_get_array	(	i18n_formattable_h	formattable,
		i18n_formattable_h **	array,
		int32_t *	count
	)

Gets the array value and count of the given formattable object.

Since :: 2.3.2 and 3.0

Remarks:: If this object is not of type I18N_FORMATTABLE_TYPE_ARRAY then the result is undefined. The obtained array should be released by the caller with the free() function.

Parameters:

[in]	formattable	A handle to the formattable object
[out]	array	A pointer to an array of i18n_formattable_h handles
[out]	count	A pointer to an int32_t variable which will be filled with the number of array's elements

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_OUT_OF_MEMORY	Out of memory

int i18n_formattable_get_date	(	i18n_formattable_h	formattable,
		i18n_udate *	date
	)

Gets the date value of the given formattable object.

Since :: 2.3.2 and 3.0

Remarks:: If this object is not of type I18N_FORMATTABLE_TYPE_DATE then the result is undefined.

Parameters:

[in]	formattable	A handle to the formattable object
[out]	date	A pointer to an i18n_udate object which will be filled with the date obtained from the given formattable object

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_formattable_get_double	(	i18n_formattable_h	formattable,
		double *	value
	)

Gets the double value of the given formattable object.

Since :: 2.3.2 and 3.0

Remarks:: If this object is not of type I18N_FORMATTABLE_TYPE_DOUBLE then the result is undefined.

Parameters:

[in]	formattable	A handle to the formattable object
[out]	value	A pointer to a double variable which will be filled with the value obtained from the given formattable object

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_formattable_get_int64	(	i18n_formattable_h	formattable,
		int64_t *	value
	)

Gets the int64 value of the given formattable object.

Since :: 2.3.2 and 3.0

Remarks:: If this object is not of type I18N_FORMATTABLE_TYPE_INT64 then the result is undefined.

Parameters:

[in]	formattable	A handle to the formattable object
[out]	value	A pointer to an int64_t variable which will be filled with the value obtained from the given formattable object

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_formattable_get_long	(	i18n_formattable_h	formattable,
		int32_t *	value
	)

Gets the long value of the given formattable object.

If the magnitude is too large to fit in a long, then the maximum or minimum long value, as appropriate, is set to value and the I18N_ERROR_INVALID_FORMAT error code is returned by the function.

Since :: 2.3.2 and 3.0

Parameters:

[in]	formattable	A handle to the formattable object
[out]	value	A pointer to a int32_t variable which will be filled with the value obtained from the given formattable object

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_formattable_get_string	(	i18n_formattable_h	formattable,
		char **	value
	)

Gets the string value of the given formattable object.

Since :: 2.3.2 and 3.0

Remarks:: If the type is not a string, the function returns the I18N_ERROR_INVALID_FORMAT error code and the value is set to NULL. The value should be released by the caller with the free() function.

Parameters:

[in]	formattable	A handle to the formattable object
[out]	value	A pointer to a char string variable which will be filled with the value obtained from the given formattable object

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_INVALID_FORMAT	The given formattable type is not a string
I18N_ERROR_OUT_OF_MEMORY	Out of memory
I18N_ERROR_UNKNOWN	Unknown error

int i18n_formattable_get_type	(	i18n_formattable_h	formattable,
		i18n_formattable_type_e *	type
	)

Gets the data type of the given formattable object.

Since :: 2.3.2 and 3.0

Parameters:

[in]	formattable	A handle to the formattable object
[out]	type	A pointer to an i18n_formattable_type_e variable which will be filled with the type obtained from the given formattable object

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_formattable_is_numeric	(	i18n_formattable_h	formattable,
		bool *	is_numeric
	)

Sets the variable pointed by the is_numeric pointer to true if the data type of the given formattable object is I18N_FORMATTABLE_TYPE_DOUBLE, I18N_FORMATTABLE_TYPE_LONG or I18N_FORMATTABLE_TYPE_INT64.

Since :: 2.3.2 and 3.0

Parameters:

[in]	formattable	A handle to the formattable object
[out]	is_numeric	A pointer to a boolean variable which will be filled by the function

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_formattable_not_equal	(	i18n_formattable_h	formattable,
		i18n_formattable_h	other,
		bool *	not_equal
	)

Sets the variable pointed by the not_equal pointer to true if the given formattable object is not equal to the given other formattable object.

Since :: 2.3.2 and 3.0

Parameters:

[in]	formattable	A handle to the formattable object
[in]	other	A handle to the other formattable object
[out]	not_equal	A pointer to a boolean variable which will be filled by the function

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_formattable_set_array	(	i18n_formattable_h	formattable,
		const i18n_formattable_h *	array,
		int32_t	count
	)

Sets the array value and count of the given formattable object and changes the type to I18N_FORMATTABLE_TYPE_ARRAY.

Since :: 2.3.2 and 3.0

Parameters:

[in]	formattable	A handle to the formattable object
[in]	array	An array of handles to the formattable objects
[in]	count	The number of array elements to be copied

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_formattable_set_date	(	i18n_formattable_h	formattable,
		i18n_udate	date
	)

Sets the date value of the given formattable object and changes the type to the I18N_FORMATTABLE_TYPE_DATE.

Since :: 2.3.2 and 3.0

Parameters:

[in]	formattable	A handle to the formattable object
[in]	date	The new i18n_udate value to be set

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_formattable_set_double	(	i18n_formattable_h	formattable,
		double	value
	)

Sets the double value of the given formattable object and changes the type to the I18N_FORMATTABLE_TYPE_DOUBLE.

Since :: 2.3.2 and 3.0

Parameters:

[in]	formattable	A handle to the formattable object
[in]	value	The new double value to be set

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_formattable_set_int64	(	i18n_formattable_h	formattable,
		int64_t	value
	)

Sets the int64 value of the given formattable object and changes the type to the I18N_FORMATTABLE_TYPE_INT64.

Since :: 2.3.2 and 3.0

Parameters:

[in]	formattable	A handle to the formattable object
[in]	value	The new int64_t value to be set

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_formattable_set_long	(	i18n_formattable_h	formattable,
		int32_t	value
	)

Sets the long value of the given formattable object and changes the type to the I18N_FORMATTABLE_TYPE_LONG.

Since :: 2.3.2 and 3.0

Parameters:

[in]	formattable	A handle to the formattable object
[in]	value	The new int32_t value to be set

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_formattable_set_string	(	i18n_formattable_h	formattable,
		const char *	string_to_copy
	)

Sets the string value of the given formattable object and changes the type to the I18N_FORMATTABLE_TYPE_STRING.

Since :: 2.3.2 and 3.0

Parameters:

[in]	formattable	A handle to the formattable object
[in]	string_to_copy	The new string value to be set

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

Required Header

Overview

Functions

Typedefs

Typedef Documentation

Enumeration Type Documentation

Function Documentation