Tizen Native API  5.0
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

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]formattableA handle to the formattable object
[out]cloneA 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_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_OUT_OF_MEMORYOut of memory

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]formattableA pointer to a handle to the newly created formattable object
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_OUT_OF_MEMORYOut 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_copyThe char string
[out]formattableA pointer to a handle to the newly created formattable object
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_OUT_OF_MEMORYOut 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]valueThe double value to be used
[out]formattableA pointer to a handle to the newly created formattable object
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_OUT_OF_MEMORYOut 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_copyAn array with the i18n_formattable_h handles
[in]countThe number of the elements in the array
[out]formattableA pointer to a handle to the newly created formattable object
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_OUT_OF_MEMORYOut 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]valueThe int64_t value to be used
[out]formattableA pointer to a handle to the newly created formattable object
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_OUT_OF_MEMORYOut 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]valueThe long value to be used
[out]formattableA pointer to a handle to the newly created formattable object
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_OUT_OF_MEMORYOut of memory

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]dateThe i18n_udate instance
[out]formattableA pointer to a handle to the newly created formattable object
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_OUT_OF_MEMORYOut of memory

Releases the given i18n_formattable_h handle.

Since :
2.3.2 and 3.0
Parameters:
[in]formattableA handle to the formattable object to be released
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid 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]formattableA handle to the formattable object
[in]indexA number representing the position in the array from which the element should be obtained
[out]elementA 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_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_INDEX_OUTOFBOUNDSIndex value out of range
I18N_ERROR_INVALID_FORMATThe 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]formattableA handle to the formattable object
[in]otherA handle to the other formattable object
[out]equalA 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_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid 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]formattableA handle to the formattable object
[out]arrayA pointer to an array of i18n_formattable_h handles
[out]countA 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_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_OUT_OF_MEMORYOut 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]formattableA handle to the formattable object
[out]dateA 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_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid 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]formattableA handle to the formattable object
[out]valueA 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_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid 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]formattableA handle to the formattable object
[out]valueA 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_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid 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]formattableA handle to the formattable object
[out]valueA 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_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid 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]formattableA handle to the formattable object
[out]valueA 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_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_INVALID_FORMATThe given formattable type is not a string
I18N_ERROR_OUT_OF_MEMORYOut of memory
I18N_ERROR_UNKNOWNUnknown error

Gets the data type of the given formattable object.

Since :
2.3.2 and 3.0
Parameters:
[in]formattableA handle to the formattable object
[out]typeA 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_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid 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]formattableA handle to the formattable object
[out]is_numericA 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_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid 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]formattableA handle to the formattable object
[in]otherA handle to the other formattable object
[out]not_equalA 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_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid 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]formattableA handle to the formattable object
[in]arrayAn array of handles to the formattable objects
[in]countThe number of array elements to be copied
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid 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]formattableA handle to the formattable object
[in]dateThe new i18n_udate value to be set
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid 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]formattableA handle to the formattable object
[in]valueThe new double value to be set
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid 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]formattableA handle to the formattable object
[in]valueThe new int64_t value to be set
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid 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]formattableA handle to the formattable object
[in]valueThe new int32_t value to be set
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid 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]formattableA handle to the formattable object
[in]string_to_copyThe new string value to be set
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter