Mobile native Wearable native

Eina Tools

Eina provides a number of tools, such as string manipulation, that make your life easier when coding applications:

  • Convert fast: conversion from, for example, strings to integers and double
  • Counter: measures the number of calls and their time
  • Error: error identifiers
  • File: file list and path split
  • Lazy allocator: lazy allocator
  • Log: full-featured logging system
  • Magic: provides runtime type checking
  • Memory Pool: abstraction for various memory allocators
  • Module lists: loads and shares modules using the Eina_Module standard
  • Rectangle: rectangle structure and standard manipulation methods
  • Safety Checks: extra checks that report unexpected conditions and can be disabled during compilation
  • String: set of functions that manage C strings

String

When creating applications, you always need to manipulate strings. Eina provides a very useful API for manipulating C strings:

  • The most common string manipulation is the "split". If you have a string, such as "Rasterman:Bluebugs:Tasn:Illogict:billiob:Puppet_Master", and you want to print it in an easily readable format, you can use the eina_str_split() function to split the string using 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 to split the string into. If you set a number less than 1, it splits 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. 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
free(arr[0]);
free(arr);

  • To change the string to lowercase or uppercase, use the eina_str_tolower() and eina_str_toupper() functions. They change the case for all characters of the given string. 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
eina_str_tolower(&str);
printf("%s\n", str);
// Free the allocated memory
free(str);

  • If you need to "join" 2 strings of known length, use the eina_str_join() function. 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 2 strings, and the 2 final parameters are the stings to be joined.

    char *part1 = "Tizen 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
free(res):

  • To check whether a string starts or ends with another string, use the eina_str_has_prefix() or eina_str_has_suffix() function. 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'")
else
   printf("String does not have extension "philippe)

Memory Pool

The Eina_Mempool tool provides memory pool functionality. With a memory pool, you can preallocate fixed-size memory spaces for easy memory management.

The following mempools are available:

  • buddy
  • chained_pool
  • ememoa_fixed and ememoa_unknown
  • fixed_bitmap
  • pass_through
  • one_big

Safety Checks

Eina safety checks are a set of macros that can be used to check for parameters or values that must never occur. The concept is similar to the assert() function, but safety checks log the parameter or value and return instead of aborting your program.

The following safety checks are available:

  • EINA_SAFETY_ON_NULL_RETURN(exp)
  • EINA_SAFETY_ON_NULL_RETURN_VAL(exp, val)
  • EINA_SAFETY_ON_NULL_GOTO(exp, label)
  • EINA_SAFETY_ON_TRUE_RETURN(exp)
  • EINA_SAFETY_ON_TRUE_RETURN_VAL(exp, val)
  • EINA_SAFETY_ON_TRUE_GOTO(exp, label)
  • EINA_SAFETY_ON_FALSE_RETURN(exp)
  • EINA_SAFETY_ON_FALSE_RETURN_VAL(exp, val)
  • EINA_SAFETY_ON_FALSE_GOTO(exp, label)
  • EINA_ARG_NONNULL(...)

To return if a variable is NULL, use the EINA_SAFETY_ON_NULL_RETURN() function. This macro calls return if the given parameter is NULL.

Eina_Bool myfunction(char *param) 
{
   // If my param is NULL, EINA_SAFETY_ON_NULL_RETURN calls "return"
   EINA_SAFETY_ON_NULL_RETURN(param);

   printf("My pram is : %s\n", param);

   return EINA_TRUE;
}

To return a specific value, use the EINA_SAFETY_ON_NULL_RETURN_VAL() function instead of the EINA_SAFETY_ON_NULL_RETURN() function. This macro returns the given value.

Eina_Bool void myfunction(char *param)
{
   // If the parameter is NULL, return EINA_FALSE;
   EINA_SAFETY_ON_NULL_RETURN_VAL(param, EINA_FALSE);
   printf("My pram is : %s\n", param);

   return EINA_TRUE;
}

To call another function if a parameter is NULL, use the EINA_SAFETY_ON_NULL_GOTO() function. This macro works similarly to the EINA_SAFETY_ON_NULL_RETURN() function except that it calls goto with the given function instead of return.

static void isnullcb()
{
   printf("The parameter is NULL\n");
}
Eina_Bool void myfunction(char *param)
{
   // If the parameter is NULL we return EINA_FALSE;
   EINA_SAFETY_ON_NULL_GOTO(param, isnullcb);
   printf("My pram is : %s\n", param);

   return EINA_TRUE;
}

Eina also provides macros that check whether a given value is TRUE or FALSE. For example, to call return if a given value is TRUE, use the EINA_SAFETY_ON_TRUE_RETURN() function. To call "goto" in a given function if a given value is TRUE, use the EINA_SAFETY_ON_NULL_GOTO() function.

Go to top