Unicode String
Eina » Data Types

These functions provide basic unicode string handling More...

## Typedefs

typedef uint32_t | Eina_Unicode
| A type that holds Unicode codepoints.

## Functions

EINA_API size_t | eina_unicode_strlen (const Eina_Unicode *ustr)
EINA_API size_t | eina_unicode_strnlen (const Eina_Unicode *ustr, int n)
| Returns the length of a Eina_Unicode string, up to a limit.
EINA_API Eina_Unicode * | eina_unicode_strdup (const Eina_Unicode *text)
| Same as the standard strdup just with Eina_Unicode instead of char.
EINA_API Eina_Unicode * | eina_unicode_strndup (const Eina_Unicode *text, size_t n)
| Same as strdup but cuts on the given size.
EINA_API int | eina_unicode_strcmp (const Eina_Unicode *a, const Eina_Unicode *b)
| Same as the standard strcmp just with Eina_Unicode instead of char.
EINA_API Eina_Unicode * | eina_unicode_strcpy (Eina_Unicode *dest, const Eina_Unicode *source)
| Same as the standard strcpy just with Eina_Unicode instead of char.
EINA_API Eina_Unicode * | eina_unicode_strstr (const Eina_Unicode *haystack, const Eina_Unicode *needle)
| Same as the standard strstr just with Eina_Unicode instead of char.
EINA_API Eina_Unicode * | eina_unicode_strncpy (Eina_Unicode *dest, const Eina_Unicode *source, size_t n)
| Same as the standard strncpy just with Eina_Unicode instead of char.
EINA_API Eina_Unicode * | eina_unicode_escape (const Eina_Unicode *str)
static Eina_Unicode | eina_unicode_utf8_next_get (const char *buf, int *iindex)
| Reads UTF8 bytes from `buf`, starting at `iindex` and returns the decoded code point at `iindex` offset, and advances `iindex` to the next code point after this.
EINA_API Eina_Unicode | eina_unicode_utf8_get_next (const char *buf, int *iindex) EINA_DEPRECATED
EINA_API Eina_Unicode | eina_unicode_utf8_get_prev (const char *buf, int *iindex)
| Reads UTF8 bytes from `buf`, starting at `iindex` and returns the decoded code point at `iindex` offset, and moves `iindex` to the previous code point.
EINA_API int | eina_unicode_utf8_get_len (const char *buf)
| Returns the number of unicode characters in the string.
EINA_API Eina_Unicode * | eina_unicode_utf8_to_unicode (const char *utf, int *_len)
| Converts a utf-8 string to a newly allocated Eina_Unicode string.
EINA_API char * | eina_unicode_unicode_to_utf8_range (const Eina_Unicode *uni, int ulen, int *_len)
| Converts an Eina_Unicode string to a newly allocated utf-8 substring at given length.
EINA_API char * | eina_unicode_unicode_to_utf8 (const Eina_Unicode *uni, int *_len)
| Converts an Eina_Unicode string to a newly allocated utf-8 string.

## Variables

EINA_API const Eina_Unicode * | EINA_UNICODE_EMPTY_STRING
| Same as the standard strlen just with Eina_Unicode instead of char.

## Detailed Description

These functions provide basic unicode string handling

Eina_Unicode is a type that holds unicode codepoints.

## Function Documentation

## eina_unicode_strnlen()

EINA_API size_t eina_unicode_strnlen | ( | const Eina_Unicode * | ustr,
|  | int | n )

Returns the length of a Eina_Unicode string, up to a limit.

This function returns the number of characters in string, up to a maximum of n. If the terminating character is not found in the string, it returns n.

Parameters

  [in] | ustr | String to search
  [in] | n | Max length to search

Returns
  Number of characters or n.

References EINA_SAFETY_ON_NULL_RETURN_VAL.

## eina_unicode_strdup()

EINA_API Eina_Unicode * eina_unicode_strdup | ( | const Eina_Unicode * | text | ) |

Same as the standard strdup just with Eina_Unicode instead of char.

Parameters

  [in] | text | The text to duplicate.

Returns
  The duplicated string.

References EINA_SAFETY_ON_NULL_RETURN_VAL, and eina_unicode_strndup().

## eina_unicode_strndup()

EINA_API Eina_Unicode * eina_unicode_strndup | ( | const Eina_Unicode * | text,
|  | size_t | n )

Same as strdup but cuts on the given size.

Assumes n < len

Parameters

  [in] | text | The text to duplicate.
  [in] | n | The maximum size of the text to duplicate.

Returns
  The duplicated string.

This function duplicates `text`. The resulting string is cut on `n`. `n` is assumed to be lesser (<) than the length of `text`. When not needed anymore, the returned string must be freed.

Since
  1.1.0

References EINA_SAFETY_ON_NULL_RETURN_VAL.

Referenced by eina_unicode_strdup().

## eina_unicode_strcmp()

EINA_API int eina_unicode_strcmp | ( | const Eina_Unicode * | a,
|  | const Eina_Unicode * | b )

Same as the standard strcmp just with Eina_Unicode instead of char.

Parameters

  [in] | a | The text to be compared.
  [in] | b | The text to be compared.

Returns
  An integer value indicating the ordinal relation of `a` to `b`.

References EINA_SAFETY_ON_NULL_RETURN_VAL.

## eina_unicode_strcpy()

EINA_API Eina_Unicode * eina_unicode_strcpy | ( | Eina_Unicode * | dest,
|  | const Eina_Unicode * | source )

Same as the standard strcpy just with Eina_Unicode instead of char.

Parameters

  [out] | dest | The text which `source` is to be copied.
  [in] | source | The text to copy from.

Returns
  `dest` is returned.

References EINA_SAFETY_ON_NULL_RETURN_VAL.

## eina_unicode_strstr()

EINA_API Eina_Unicode * eina_unicode_strstr | ( | const Eina_Unicode * | haystack,
|  | const Eina_Unicode * | needle )

Same as the standard strstr just with Eina_Unicode instead of char.

Parameters

  [in] | haystack | The text to be searched.
  [in] | needle | The text to search for

Returns
  The substring of `haystack` which starts with `needle` when `needle` is founded in `haystack`, or NULL is returned.

References EINA_SAFETY_ON_NULL_RETURN_VAL.

## eina_unicode_strncpy()

EINA_API Eina_Unicode * eina_unicode_strncpy | ( | Eina_Unicode * | dest,
|  | const Eina_Unicode * | source,
|  | size_t | n )

Same as the standard strncpy just with Eina_Unicode instead of char.

Parameters

  [out] | dest | The text which `source` is to be copied.
  [in] | source | The text to copy from.
  [in] | n | Maximum number of characters to be copied from `source`.

Returns
  `dest` is returned.

References EINA_SAFETY_ON_NULL_RETURN_VAL.

## eina_unicode_escape()

EINA_API Eina_Unicode * eina_unicode_escape | ( | const Eina_Unicode * | str | ) |

See also
  eina_str_escape()

Parameters

  [in] | str | The string to escape.

Returns
  The escaped string.

References EINA_SAFETY_ON_NULL_RETURN_VAL.

## eina_unicode_utf8_next_get()

Eina_Unicode eina_unicode_utf8_next_get | ( | const char * | buf,
|  | int * | iindex )

inline static

Reads UTF8 bytes from `buf`, starting at `iindex` and returns the decoded code point at `iindex` offset, and advances `iindex` to the next code point after this.

`iindex` is always advanced, unless if the advancement is after the `NULL`.

On error: return a codepoint between DC80 to DCFF where the low 8 bits are the byte's value.

Parameters

  [in] | buf | the string
  [in,out] | iindex | the index to look at and return by.

Returns
  the codepoint found, 0 if `buf` or `iindex` are NULL

Since
  1.8.0

References EINA_API, EINA_ARG_NONNULL, EINA_DEPRECATED, EINA_MALLOC, eina_unicode_unicode_to_utf8(), eina_unicode_unicode_to_utf8_range(), eina_unicode_utf8_get_len(), eina_unicode_utf8_get_next(), eina_unicode_utf8_get_prev(), eina_unicode_utf8_to_unicode(), and EINA_WARN_UNUSED_RESULT.

## eina_unicode_utf8_get_next()

EINA_API Eina_Unicode eina_unicode_utf8_get_next | ( | const char * | buf,
|  | int * | iindex )

Deprecated
  use eina_unicode_utf8_next_get Reads UTF8 bytes from `buf`, starting at `iindex` and returns the decoded code point at `iindex` offset, and advances `iindex` to the next code point after this. `iindex` is always advanced, unless if the advancement is after the `NULL`.

On error: return a codepoint between DC80 to DCFF where the low 8 bits are the byte's value.

Parameters

  [in] | buf | the string
  [in,out] | iindex | the index to look at and return by.

Returns
  the codepoint found, 0 if `buf` or `iindex` are NULL

Since
  1.1.0

References EINA_API.

Referenced by eina_unicode_utf8_next_get().

## eina_unicode_utf8_get_prev()

EINA_API Eina_Unicode eina_unicode_utf8_get_prev | ( | const char * | buf,
|  | int * | iindex )

Reads UTF8 bytes from `buf`, starting at `iindex` and returns the decoded code point at `iindex` offset, and moves `iindex` to the previous code point.

`iindex` is always moved, as long as it's not past the start of the string.

On error: return a codepoint between DC80 to DCFF where the low 8 bits are the byte's value.

Parameters

  [in] | buf | the string
  [in,out] | iindex | the index to look at and return by.

Returns
  the codepoint found.

Since
  1.1.0

References EINA_SAFETY_ON_NULL_RETURN_VAL.

Referenced by eina_unicode_utf8_next_get(), and evas_string_char_prev_get().

## eina_unicode_utf8_get_len()

EINA_API int eina_unicode_utf8_get_len | ( | const char * | buf | ) |

Returns the number of unicode characters in the string.

That is, the number of Eina_Unicodes it'll take to store this string in an Eina_Unicode string.

Parameters

  [in] | buf | the string

Returns
  the number of unicode characters (not bytes) in the string

Since
  1.1.0

References EINA_SAFETY_ON_NULL_RETURN_VAL.

Referenced by eina_unicode_utf8_next_get(), eina_unicode_utf8_to_unicode(), and evas_string_char_len_get().

## eina_unicode_utf8_to_unicode()

EINA_API Eina_Unicode * eina_unicode_utf8_to_unicode | ( | const char * | utf,
|  | int * | _len )

Converts a utf-8 string to a newly allocated Eina_Unicode string.

Parameters

  [in] | utf | the string in utf-8
  [out] | _len | the length of the returned Eina_Unicode string.

Returns
  the newly allocated Eina_Unicode string.

Since
  1.1.0

References EINA_SAFETY_ON_NULL_RETURN_VAL, and eina_unicode_utf8_get_len().

Referenced by eina_unicode_utf8_next_get().

## eina_unicode_unicode_to_utf8_range()

EINA_API char * eina_unicode_unicode_to_utf8_range | ( | const Eina_Unicode * | uni,
|  | int | ulen,
|  | int * | _len )

Converts an Eina_Unicode string to a newly allocated utf-8 substring at given length.

Parameters

  [in] | uni | the Eina_Unicode string
  [in] | ulen | the length in the unicode string to convert.
  [out] | _len | the length byte length of the return utf8 substring.

Returns
  the newly allocated utf-8 substring.

Since
  1.17

References EINA_SAFETY_ON_NULL_RETURN_VAL.

Referenced by eina_unicode_unicode_to_utf8(), and eina_unicode_utf8_next_get().

## eina_unicode_unicode_to_utf8()

EINA_API char * eina_unicode_unicode_to_utf8 | ( | const Eina_Unicode * | uni,
|  | int * | _len )

Converts an Eina_Unicode string to a newly allocated utf-8 string.

Parameters

  [in] | uni | the Eina_Unicode string
  [out] | _len | the length byte length of the return utf8 string.

Returns
  the newly allocated utf-8 string.

Since
  1.1.0

References eina_unicode_unicode_to_utf8_range().

Referenced by eina_unicode_utf8_next_get(), and evas_textblock_cursor_content_get().