Tizen Native API  5.0

Provides useful functions for C string manipulation.

This group of functions allow you to more easily manipulate strings, they provide functionality not available through string.h.

Warning:
Since these functions modify the strings they can't be used with shared strings(eina_stringshare).

See an example here.

Functions

size_t eina_strlcpy (char *dst, const char *src, size_t siz)
 Copies a c-string to another.
size_t eina_strlcat (char *dst, const char *src, size_t siz)
 Appends a c-string.
Eina_Bool eina_str_has_prefix (const char *str, const char *prefix)
 Checks if the given string has the given prefix.
Eina_Bool eina_str_has_suffix (const char *str, const char *suffix)
 Checks if the given string has the given suffix.
Eina_Bool eina_str_has_extension (const char *str, const char *ext)
 Checks if the given string has the given extension.
char ** eina_str_split (const char *string, const char *delimiter, int max_tokens)
 Splits a string using a delimiter.
char ** eina_str_split_full (const char *string, const char *delimiter, int max_tokens, unsigned int *elements)
 Splits a string using a delimiter and returns number of elements.
size_t eina_str_join_len (char *dst, size_t size, char sep, const char *a, size_t a_len, const char *b, size_t b_len)
 Joins two strings of known length.
char * eina_str_convert (const char *enc_from, const char *enc_to, const char *text)
 Uses Iconv to convert a text string from one encoding to another.
char * eina_str_convert_len (const char *enc_from, const char *enc_to, const char *text, size_t len, size_t *retlen)
 Uses Iconv to convert a text string from one encoding to another.
char * eina_str_escape (const char *str)
 Escapes slashes, spaces and apostrophes in strings.
void eina_str_tolower (char **str)
 Lowercases all the characters in range [A-Z] in the given string.
void eina_str_toupper (char **str)
 Uppercases all the characters in range [a-z] in the given string.
unsigned char * eina_memdup (unsigned char *mem, size_t size, Eina_Bool terminate)
 Memory duplication function with optional termination for strings.

Defines

#define eina_str_join_static(dst, sep, a, b)   eina_str_join_len(dst, sizeof(dst), sep, a, (sizeof(a) > 0) ? sizeof(a) - 1 : 0, b, (sizeof(b) > 0) ? sizeof(b) - 1 : 0)
 Joins two static strings and store the result in a static buffer.

Define Documentation

#define eina_str_join_static (   dst,
  sep,
  a,
 
)    eina_str_join_len(dst, sizeof(dst), sep, a, (sizeof(a) > 0) ? sizeof(a) - 1 : 0, b, (sizeof(b) > 0) ? sizeof(b) - 1 : 0)

Joins two static strings and store the result in a static buffer.

Parameters:
[out]dstThe buffer to store the result.
[in]sepThe separator character to use.
[in]aFirst string to use, before sep.
[in]bSecond string to use, after sep.
Returns:
The number of characters printed.

This function is similar to eina_str_join_len(), but will assume string sizes are know using sizeof(X).

See also:
eina_str_join()
eina_str_join_static()

Function Documentation

unsigned char* eina_memdup ( unsigned char *  mem,
size_t  size,
Eina_Bool  terminate 
)

Memory duplication function with optional termination for strings.

Parameters:
[in]memThe memory to copy
[in]sizeThe size of mem
[in]terminateIf true, the returned memory will be nul terminated with '\0'
Returns:
The copied memory, must be freed
Since (EFL) :
1.13
Since :
3.0
char* eina_str_convert ( const char *  enc_from,
const char *  enc_to,
const char *  text 
)

Uses Iconv to convert a text string from one encoding to another.

Parameters:
[in]enc_fromEncoding to convert from.
[in]enc_toEncoding to convert to.
[in]textThe text to convert.
Returns:
The converted text.

This function converts text, encoded in enc_from. On success, the converted text is returned and is encoded in enc_to. On failure, NULL is returned. Iconv is used to convert text. If Iconv is not available, NULL is returned. When not used anymore, the returned value must be freed.

Warning:
This function is guaranteed to break when '\0' characters are in text. DO NOT USE THIS FUNCTION IF YOUR TEXT CONTAINS NON-TERMINATING '\0' CHARACTERS.
Since :
2.3.1
char* eina_str_convert_len ( const char *  enc_from,
const char *  enc_to,
const char *  text,
size_t  len,
size_t *  retlen 
)

Uses Iconv to convert a text string from one encoding to another.

Parameters:
[in]enc_fromEncoding to convert from.
[in]enc_toEncoding to convert to.
[in]textThe text to convert.
[in]lenThe size in bytes of the text to convert.
[in]retlenThe size in bytes of the converted text.
Returns:
The converted text.

This function converts text, encoded in enc_from. On success, the converted text is returned and is encoded in enc_to. On failure, NULL is returned. Iconv is used to convert text. If Iconv is not available, NULL is returned. When not used anymore, the returned value must be freed.

Since (EFL) :
1.8
Since :
3.0
char* eina_str_escape ( const char *  str)

Escapes slashes, spaces and apostrophes in strings.

Parameters:
[in]strThe string to escape.
Returns:
The escaped string.

Escaping is done by adding a slash "\" before any occurrence of slashes "\" include "\n" and "\t", spaces " ", apostrophes "'" or quotes """. This function returns a newly allocated escaped string on success, NULL on failure. When not used anymore, the returned value must be freed.

Since :
2.3.1
Examples:
eina_str_01.c.
Eina_Bool eina_str_has_extension ( const char *  str,
const char *  ext 
)

Checks if the given string has the given extension.

Parameters:
[in]strThe string to work with.
[in]extThe extension to check for.
Returns:
EINA_TRUE if the string has the given extension, EINA_FALSE otherwise.

This function does the same as eina_str_has_suffix(), except it's case insensitive.

Since :
2.3.1
Examples:
eina_str_01.c.
Eina_Bool eina_str_has_prefix ( const char *  str,
const char *  prefix 
)

Checks if the given string has the given prefix.

Parameters:
[in]strThe string to work with.
[in]prefixThe prefix to check for.
Returns:
EINA_TRUE if the string has the given prefix, EINA_FALSE otherwise.

This function returns EINA_TRUE if str has the prefix prefix, EINA_FALSE otherwise. If the length of prefix is greater than str, EINA_FALSE is returned.

Since :
2.3.1
Examples:
eina_str_01.c.
Eina_Bool eina_str_has_suffix ( const char *  str,
const char *  suffix 
)

Checks if the given string has the given suffix.

Parameters:
[in]strThe string to work with.
[in]suffixThe suffix to check for.
Returns:
EINA_TRUE if the string has the given suffix, EINA_FALSE otherwise.

This function returns EINA_TRUE if str has the suffix suffix, EINA_FALSE otherwise. If the length of suffix is greater than str, EINA_FALSE is returned.

Since :
2.3.1
Examples:
eina_str_01.c.
size_t eina_str_join_len ( char *  dst,
size_t  size,
char  sep,
const char *  a,
size_t  a_len,
const char *  b,
size_t  b_len 
)

Joins two strings of known length.

Parameters:
[out]dstThe buffer to store the result.
[in]sizeSize (in byte) of the buffer.
[in]sepThe separator character to use.
[in]aFirst string to use, before sep.
[in]a_lenLength of a.
[in]bSecond string to use, after sep.
[in]b_lenLength of b.
Returns:
The number of characters printed.

This function joins the strings a and b (in that order) and separate them with sep. The result is stored in the buffer dst and at most size - 1 characters will be written and the string is NULL-terminated. a_len is the length of a (not including '\0') and b_len is the length of b (not including '\0'). This function returns the number of characters printed (not including the trailing '\0' used to end output to strings). Just like snprintf(), it will not write more than size bytes, thus a returned value of size or more means that the output was truncated.

See also:
eina_str_join()
eina_str_join_static()
Since :
2.3.1
Examples:
eina_str_01.c.
char** eina_str_split ( const char *  string,
const char *  delimiter,
int  max_tokens 
)

Splits a string using a delimiter.

Parameters:
[in]stringThe string to split.
[in]delimiterThe string which specifies the places at which to split the string.
[in]max_tokensThe maximum number of strings to split string into, or a number less than 1 to split as many times as possible. This parameter IGNORES the added NULL terminator.
Returns:
A newly-allocated NULL-terminated array of strings or NULL if it fails to allocate the array.

This function splits string into a maximum of max_tokens pieces, using the given delimiter delimiter. delimiter is not included in any of the resulting strings, unless max_tokens is reached. If max_tokens is less than 1, the string is split as many times as possible. If max_tokens is reached, the last string in the returned string array contains the remainder of string. The returned value is a newly allocated NULL-terminated array of strings or NULL if it fails to allocate the array. To free it, free the first element of the array and the array itself.

Note:
If you need the number of elements in the returned array see eina_str_split_full().
Since :
2.3.1
Examples:
eina_str_01.c.
char** eina_str_split_full ( const char *  string,
const char *  delimiter,
int  max_tokens,
unsigned int *  elements 
)

Splits a string using a delimiter and returns number of elements.

Parameters:
[in]stringThe string to split.
[in]delimiterThe string which specifies the places at which to split the string.
[in]max_tokensThe maximum number of strings to split string into, or a number less than 1 to split as many times as possible. This parameter IGNORES the added NULL terminator.
[out]elementsWhere to return the number of elements in returned array. This array is guaranteed to be no greater than max_tokens, and it will NOT count the NULL terminator element.
Returns:
A newly-allocated NULL-terminated array of strings or NULL if it fails to allocate the array.

This function splits string into a maximum of max_tokens pieces, using the given delimiter delimiter. delimiter is not included in any of the resulting strings, unless max_tokens is reached. If max_tokens is less than 1, the string is split as many times as possible. If max_tokens is reached, the last string in the returned string array contains the remainder of string. The returned value is a newly allocated NULL-terminated array of strings or NULL if it fails to allocate the array. To free it, free the first element of the array and the array itself.

Note:
The actual size of the returned array, when elements returns greater than zero, will always be elements + 1. This is due to the NULL terminator element that is added to the array for safety. If it returns 6, the number of split strings returned will be 6, but the size of the array (including the NULL element) will actually be 7.
See also:
eina_str_split()
Since :
2.3.1
void eina_str_tolower ( char **  str)

Lowercases all the characters in range [A-Z] in the given string.

Parameters:
[in,out]strThe string to lowercase.

This function modifies the original string, changing all characters in [A-Z] to lowercase. If str is NULL or is an empty string, this function does nothing.

Since :
2.3.1
Examples:
eina_str_01.c.
void eina_str_toupper ( char **  str)

Uppercases all the characters in range [a-z] in the given string.

Parameters:
[in,out]strThe string to uppercase.

This function modifies the original string, changing all characters in [a-z] to uppercase. If str is NULL or is an empty string, this function does nothing.

Since :
2.3.1
Examples:
eina_str_01.c.
size_t eina_strlcat ( char *  dst,
const char *  src,
size_t  siz 
)

Appends a c-string.

Parameters:
[out]dstThe destination string.
[in]srcThe source string.
[in]sizThe size of the destination string.
Returns:
The length of the source string plus MIN(siz, strlen(initial dst))

This function appends src to dst of size siz (unlike strncat, siz is the full size of dst, not space left). At most siz - 1 characters will be copied. Always NULL-terminates (unless siz <= strlen(dst)). This function returns strlen(src) + MIN(siz, strlen(initial dst)). If the returned value is greater or equal than siz, truncation occurred.

Since :
2.3.1
Examples:
eina_simple_xml_parser_01.c, and eina_str_01.c.
size_t eina_strlcpy ( char *  dst,
const char *  src,
size_t  siz 
)

Copies a c-string to another.

Parameters:
[out]dstThe destination string.
[in]srcThe source string.
[in]sizThe size of the destination string.
Returns:
The length of the source string.

This function copies up to siz - 1 characters from the NULL-terminated string src to dst, NULL-terminating the result (unless siz is equal to 0). The returned value is the length of src. If the returned value is greater than siz, truncation occurred.

Note:
The main difference between eina_strlcpy and strncpy is that this ensures dst is NULL-terminated even if no NULL byte is found in the first siz bytes of src.
Since :
2.3.1
Examples:
eina_simple_xml_parser_01.c, and eina_str_01.c.