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

Functions
static size_t	eina_strlen_bounded (const char *str, size_t maxlen)
	Count up to a given amount of bytes of the given string. More...

static size_t	eina_str_join (char dst, size_t size, char sep, const char a, const char *b)
	Join two strings of known length. More...

static char *	eina_strdup (const char *str)
	strdup function which takes `NULL` without crashing More...

static char *	eina_strndup (const char *str, size_t n)
	strndup function which takes `NULL` without crashing More...

static Eina_Bool	eina_streq (const char a, const char b)
	streq function which takes `NULL` without crashing More...

EAPI size_t	eina_strlcpy (char dst, const char src, size_t siz) EINA_ARG_NONNULL(1
	Copies 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
	Appends 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
	Checks 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
	Checks 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
	Checks 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
	Splits 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
	Splits 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
	Joins 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
	Uses 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
	Uses 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)
	Escapes slashes, spaces and apostrophes in strings. More...

EAPI void	eina_str_tolower (char **str)
	Lowercases all the characters in range [A-Z] in the given string. More...

EAPI void	eina_str_toupper (char **str)
	Uppercases all the characters in range [a-z] in the given string. More...

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

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.

Macro Definition Documentation

◆ eina_str_join_static

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

Parameters

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

◆ eina_strlen_bounded()

static size_t eina_strlen_bounded	(	const char *	str,
		size_t	maxlen
	)

inlinestatic

Count up to a given amount of bytes of the given string.

Parameters

str	The string pointer.
maxlen	The maximum length to allow.

Returns: the string size or (size_t)-1 if greater than maxlen.

This function returns the size of str, up to maxlen characters. It avoid needless iterations after that size. str must be a valid pointer and MUST not be NULL, otherwise this function will crash. This function returns the string size, or (size_t)-1 if the size is greater than maxlen.

◆ eina_str_join()

static size_t eina_str_join	(	char *	dst,
		size_t	size,
		char	sep,
		const char *	a,
		const char *	b
	)

inlinestatic

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`.
b	Second string to use, after `sep`.

Returns: The number of characters printed.

This function is similar to eina_str_join_len(), but will compute the length of a and b using strlen().

See also: eina_str_join_len(); eina_str_join_static()

References eina_str_join_len().

◆ eina_strdup()

static char* eina_strdup ( const char * str )

inlinestatic

strdup function which takes NULL without crashing

Parameters

str	The string to copy

Returns: the copied string, must be freed

Since: 1.12

◆ eina_strndup()

static char* eina_strndup	(	const char *	str,
		size_t	n
	)

inlinestatic

strndup function which takes NULL without crashing

Parameters

str	The string to copy
n	The maximum number of char to copy

Returns: the copied string, must be freed

Note: this also implements strndup() on Windows

Since: 1.23

◆ eina_streq()

static Eina_Bool eina_streq	(	const char *	a,
		const char *	b
	)

inlinestatic

streq function which takes NULL without crashing

Parameters

a	string a
b	string b

Returns: true if strings are equal

Since: 1.12

Examples: inwin_example.c.

References EINA_FALSE, and EINA_TRUE.

Referenced by ecore_wl2_display_input_find_by_name(), edje_edit_color_class_description_get(), edje_edit_color_class_description_set(), elput_input_pointer_xy_get(), and evas_output_method_set().

◆ eina_strlcpy()

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

Copies a c-string to another.

Parameters

[out]	dst	The destination string.
[in]	src	The source string.
[in]	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, eina_simple_xml_parser_01.c, and eina_str_01.c.

Referenced by eina_error_msg_get().

◆ eina_strlcat()

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

Appends a c-string.

Parameters

[out]	dst	The destination string.
[in]	src	The source string.
[in]	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_simple_xml_parser_01.c, and eina_str_01.c.

◆ eina_str_has_prefix()

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

Checks if the given string has the given prefix.

Parameters

[in]	str	The string to work with.
[in]	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 ecore_win32_clipboard_get(), and ecore_win32_clipboard_set().

◆ eina_str_has_suffix()

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

Checks if the given string has the given suffix.

Parameters

[in]	str	The string to work with.
[in]	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.

◆ eina_str_has_extension()

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

Checks if the given string has the given extension.

Parameters

[in]	str	The string to work with.
[in]	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 ecore_file_can_exec().

◆ eina_str_split()

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

Splits a string using a delimiter.

Parameters

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

Examples: eina_str_01.c.

Referenced by edje_edit_group_copy().

◆ eina_str_split_full()

EAPI 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]	string	The string to split.
[in]	delimiter	The string which specifies the places at which to split the string.
[in]	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.
[out]	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 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()

◆ eina_str_join_len()

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
	)

Joins two strings of known length.

Parameters

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

◆ eina_str_convert()

EAPI size_t EAPI 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_from	Encoding to convert from.
[in]	enc_to	Encoding to convert to.
[in]	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.

◆ eina_str_convert_len()

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
	)

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

Parameters

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

◆ eina_str_escape()

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

Escapes slashes, spaces and apostrophes in strings.

Parameters

[in] str The 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.

Referenced by edje_edit_data_source_generate(), and edje_fontset_append_set().

◆ eina_str_tolower()

EAPI void eina_str_tolower ( char ** str )

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

Parameters

[in,out] 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().

◆ eina_str_toupper()

EAPI void eina_str_toupper ( char ** str )

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

Parameters

[in,out] 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.

◆ eina_memdup()

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

Memory duplication function with optional termination for strings.

Parameters

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

Returns: The copied memory, must be freed

Since: 1.13

Referenced by elm_cnp_selection_set().

◆ eina_strftime()

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

Creates and update the buffer based on strftime output.

Parameters

[in]	tm	Pointer to a tm structure needed by strftime.
[in]	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:

time_t curr_time;
struct tm *info;
char *buf;
curr_time = time(NULL);
info = localtime(&curr_time);
buf = eina_strftime("%I:%M%p", info);
//after use
free(buf);

Since: 1.17.0

Referenced by eina_strbuf_append_strftime(), and eina_strbuf_insert_strftime().

Macros

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ eina_str_join_static

Function Documentation

◆ eina_strlen_bounded()

◆ eina_str_join()

◆ eina_strdup()

◆ eina_strndup()

◆ eina_streq()

◆ eina_strlcpy()

◆ eina_strlcat()

◆ eina_str_has_prefix()

◆ eina_str_has_suffix()

◆ eina_str_has_extension()

◆ eina_str_split()

◆ eina_str_split_full()

◆ eina_str_join_len()

◆ eina_str_convert()

◆ eina_str_convert_len()

◆ eina_str_escape()

◆ eina_str_tolower()

◆ eina_str_toupper()

◆ eina_memdup()

◆ eina_strftime()