String Tool

String manipulation is one of the most common tasks in any application. Eina provides an application programming interface (API) for the manipulation of C strings: eina_str. This API provides several functions described in this document: splitting strings, joining strings, converting strings to upper or lower case and checking to see whether a string begins or ends with another string.

Splitting Strings

The eina_str_split() allows you to function to split a string at a delimiter. The first parameter is the string to split, the second determines where to split the string and the final parameter is the maximum number of strings into which the original string should be split. If the maximum number of returned strings is less than one, the function will split the string as many times as possible.

The function returns a newly-allocated NULL-terminated array of strings, or NULL if it fails to allocate the array.

NOTE: Always remember to free the memory allocated by the eina_str_split() function.

char *nicks = "Rasterman:Bluebugs:Tasn:Illogict:billiob:Puppet_Master";
char **result_arr;
int i;
// Splitting the string with ':' delimiter
result_arr = eina_str_split(names, ":", 0);
// Printing the result
for (i = 0; result_arr[i]; i++)
   printf("Nick : %s\n", result_arr[i]);
// Remember to free memory

Converting Strings to Upper/Lower Case

The eina_str_tolower() and eina_str_toupper() functions allow strings to be converted to lower or upper case respectively. They change the case for all characters of the given string, regardless of their original case. These functions modify the original strings.

char *str;
// Initialize the string
str = malloc(sizeof(char) * 4);
strcpy(str, "bsd");
// Change the string to uppercase
eina_str_toupper((char **)&str);
printf("%s\n", str);
// Change the string to lowercase
printf("%s\n", str);
// Free the allocated memory

Joining Strings

The eina_str_join() function allows two strings of a known length to be joined together. The fist parameter is the buffer to store the result, the second is the size of the buffer, the third is the separator between the two strings and the two final parameters are the stings to be joined.

char *part1 = "Elementary powered by";
char *part2 = "Enlightenment Foundation Libraries";
char *res;
size_t size;
// Calculate the string size + 1 for the delimiter
size = strlen(part1) + strlen(part2) + 1
// Allocate memory for the result
res = malloc(sizeof(char) * size);
// Join the strings
eina_str_join(res, size, ' ', part1, part2);
printf("%s\n", res);
// Free the allocated memory

Matching the Start/End of a String

The eina_str_has_prefix() and eina_str_has_suffix() function allow for strings to be matched against the beginning or end of another string respectively. You can also check whether a string has a particular extension with the eina_str_has_extension() function.

These functions return EINA_TRUE if the given string contains the specified prefix, suffix, or extension and EINA_FALSE if it does not.

char *names = "Carsten;Cedric;Tom;Chidambar;Boris;Philippe"
if (eina_str_has_prefix(names, "Carsten"))
   printf("String starts with 'Carsten'")
if (eina_str_has_suffix(names, "Philippe"))
   printf("String ends with 'Philippe'")
if (eina_str_has_extension(names, "philippe"))
   printf("String has extension 'philippe'")
   printf("String does not have extension "philippe)

Further Reading

The String Tools API
An auto-generated reference to the String Tools API and its functions.
The eina_string Tutorial
A tutorial demonstrating the use of the String Tools API.