String

- Main Page
- Related Pages
- Modules
- Namespaces
- Data Structures
- Files
- Examples

Macros | Functions | Variables
String
Eina » Tools

Provide useful functions for C string manipulation. More...

## Macros
#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)
| Join two static strings and store the result in a static buffer. More...

## Functions
EAPI size_t | eina_strlcpy (char *dst, const char *src, size_t siz) EINA_ARG_NONNULL(1
| Copy a c-string to another. More...
EAPI size_t EAPI size_t | eina_strlcat (char *dst, const char *src, size_t siz) EINA_ARG_NONNULL(1
| Append a c-string. More...
EAPI size_t EAPI size_t EAPI Eina_Bool | eina_str_has_prefix (const char *str, const char *prefix) EINA_PURE EINA_ARG_NONNULL(1
| Check if the given string has the given prefix. More...
EAPI Eina_Bool | eina_str_has_suffix (const char *str, const char *suffix) EINA_PURE EINA_ARG_NONNULL(1
| Check if the given string has the given suffix. More...
EAPI Eina_Bool | eina_str_has_extension (const char *str, const char *ext) EINA_PURE EINA_ARG_NONNULL(1
| Check if the given string has the given extension. More...
EAPI char ** | eina_str_split (const char *string, const char *delimiter, int max_tokens) EINA_ARG_NONNULL(1
| Split a string using a delimiter. More...
EAPI char ** | eina_str_split_full (const char *string, const char *delimiter, int max_tokens, unsigned int *elements) EINA_ARG_NONNULL(1
| Split a string using a delimiter and returns number of elements. More...
EAPI 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) EINA_ARG_NONNULL(1
| Join two strings of known length. More...
EAPI size_t EAPI char * | eina_str_convert (const char *enc_from, const char *enc_to, const char *text) EINA_WARN_UNUSED_RESULT EINA_MALLOC EINA_ARG_NONNULL(1
| Use Iconv to convert a text string from one encoding to another. More...
EAPI size_t EAPI char EAPI char * | eina_str_convert_len (const char *enc_from, const char *enc_to, const char *text, size_t len, size_t *retlen) EINA_WARN_UNUSED_RESULT EINA_MALLOC EINA_ARG_NONNULL(1
| Use Iconv to convert a text string from one encoding to another. More...
EAPI size_t EAPI char EAPI char EAPI char * | eina_str_escape (const char *str) EINA_WARN_UNUSED_RESULT EINA_MALLOC EINA_ARG_NONNULL(1)
| Escape slashes, spaces and apostrophes in strings. More...
EAPI void | eina_str_tolower (char **str)
| Lowercase all the characters in range [A-Z] in the given string. More...
EAPI void | eina_str_toupper (char **str)
| Uppercase all the characters in range [a-z] in the given string. More...
static size_t | eina_str_join (char *dst, size_t size, char sep, const char *a, const char *b) EINA_ARG_NONNULL(1
static size_t | eina_strlen_bounded (const char *str, size_t maxlen) EINA_PURE EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1)
EAPI unsigned char * | eina_memdup (unsigned char *mem, size_t size, Eina_Bool terminate)
| memory duplication function with optional termination for strings More...
EAPI char * | eina_strftime (const char *format, const struct tm *tm)
| Create and update the buffer based on strftime output. More...

## Variables
EAPI size_t EAPI size_t EAPI Eina_Bool | EINA_WARN_UNUSED_RESULT

## Detailed Description

Provide 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.

## Macro Definition Documentation

#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)

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

Parameters

  dst | The buffer to store the result.
  sep | The separator character to use.
  a | First string to use, before `sep`.
  b | Second 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

EAPI size_t eina_strlcpy | ( | char * | dst,
|  | const char * | src,
|  | size_t | siz
| ) |  |

Copy a c-string to another.

Parameters

  dst | The destination string.
  src | The source string.
  siz | The 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.

Examples:
  eet-data-file_descriptor_01.c, eet-data-file_descriptor_02.c, eet-data-nested.c, eet-data-simple.c, and eina_str_01.c.

Referenced by ecore_file_mksubdirs(), efreet_desktop_command_progress_get(), efreet_lang_reset(), and eina_file_mkstemp().

EAPI size_t EAPI size_t eina_strlcat | ( | char * | dst,
|  | const char * | src,
|  | size_t | siz
| ) |  |

Append a c-string.

Parameters

  dst | The destination string.
  src | The source string.
  siz | The 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.

Examples:
  eina_str_01.c.

EAPI size_t EAPI size_t EAPI Eina_Bool eina_str_has_prefix | ( | const char * | str,
|  | const char * | prefix
| ) |  |

Check if the given string has the given prefix.

Parameters

  str | The string to work with.
  prefix | The 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.

Examples:
  eina_str_01.c.

Referenced by eina_strftime().

EAPI Eina_Bool eina_str_has_suffix | ( | const char * | str,
|  | const char * | suffix
| ) |  |

Check if the given string has the given suffix.

Parameters

  str | The string to work with.
  suffix | The 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.

Examples:
  eina_str_01.c.

Referenced by eina_strftime().

EAPI Eina_Bool eina_str_has_extension | ( | const char * | str,
|  | const char * | ext
| ) |  |

Check if the given string has the given extension.

Parameters

  str | The string to work with.
  ext | The 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.

Examples:
  eina_str_01.c.

Referenced by eina_strftime().

EAPI char** eina_str_split | ( | const char * | string,
|  | const char * | delimiter,
|  | int | max_tokens
| ) |  |

Split a string using a delimiter.

Parameters

  string | The string to split.
  delimiter | The string which specifies the places at which to split the string.
  max_tokens | The 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 splitted 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().

Examples:
  eina_str_01.c.

Referenced by edje_edit_group_copy(), edje_evas_global_perspective_get(), efreet_hostname_get(), and eina_strftime().

EAPI char** eina_str_split_full | ( | const char * | string,
|  | const char * | delimiter,
|  | int | max_tokens,
|  | unsigned int * | elements
| ) |  |

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

Parameters

  string | The string to split.
  delimiter | The string which specifies the places at which to split the string.
  max_tokens | The 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.
  elements | Where 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 splitted 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()

Referenced by eina_strftime().

EAPI 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
| ) |  |

Join two strings of known length.

Parameters

  dst | The buffer to store the result.
  size | Size (in byte) of the buffer.
  sep | The separator character to use.
  a | First string to use, before `sep`.
  a_len | length of `a`.
  b | Second string to use, after `sep`.
  b_len | length 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()

Examples:
  eina_str_01.c.

Referenced by eina_strftime().

EAPI size_t EAPI char* eina_str_convert | ( | const char * | enc_from,
|  | const char * | enc_to,
|  | const char * | text
| ) |  |

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

Parameters

  enc_from | Encoding to convert from.
  enc_to | Encoding to convert to.
  text | The 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.

Referenced by eina_strftime().

EAPI size_t EAPI char EAPI char* eina_str_convert_len | ( | const char * | enc_from,
|  | const char * | enc_to,
|  | const char * | text,
|  | size_t | len,
|  | size_t * | retlen
| ) |  |

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

Parameters

  enc_from | Encoding to convert from.
  enc_to | Encoding to convert to.
  text | The text to convert.
  len | The size in bytes of the text to convert.
  retlen | The 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
  1.8

Referenced by ecore_x_selection_owner_get(), and eina_strftime().

EAPI size_t EAPI char EAPI char EAPI char* eina_str_escape | ( | const char * | str | ) |

Escape slashes, spaces and apostrophes in strings.

Parameters

  str | The string to escape.

Returns
  The escaped string.

Escaping is done by adding a slash "\" before any occurrence of slashes "\" include '
' and '', 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.

Referenced by edje_edit_source_generate().

EAPI void eina_str_tolower | ( | char ** | str | ) |

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

Parameters

  str | The 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.

Referenced by eina_strbuf_tolower().

EAPI void eina_str_toupper | ( | char ** | str | ) |

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

Parameters

  str | The 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.

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

memory duplication function with optional termination for strings

Parameters

  mem | The memory to copy
  size | The size of `mem`
  terminate | If true, the returned memory will be nul terminated with '\0'

Returns
  the copied memory, must be freed

Since
  1.13

EAPI char* eina_strftime | ( | const char * | format,
|  | const struct tm * | tm
| ) |  |

Create and update the buffer based on strftime output.

Parameters

  tm | Pointer to a tm structure needed by strftime.
  format | String containing format specifiers needed by strftime.

Returns
  Updated buffer based on strftime output

This will create a buffer of exact required size based on strftime output once use is complete the buffer has to be freed using free.

Example usage:

1 time_t curr_time;
2 struct tm *info;
3 char *buf;
4 curr_time = time(NULL);
5 info = localtime(&curr_time);
6 buf = eina_strftime("%I:%M%p", info);
7 //after use
8 free(buf);

Since
  1.17.0

References EINA_FALSE, eina_str_convert(), eina_str_convert_len(), eina_str_has_extension(), eina_str_has_prefix(), eina_str_has_suffix(), eina_str_join_len(), eina_str_split(), eina_str_split_full(), and EINA_UNUSED.