Formattable

---

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