ajwillia-ms pushed a commit to branch master. http://git.enlightenment.org/tools/examples.git/commit/?id=13fb2b4b1b4e514fbf2a4d78d1f8ac4dd2b564da
commit 13fb2b4b1b4e514fbf2a4d78d1f8ac4dd2b564da Author: Andy Williams <[email protected]> Date: Thu Nov 16 15:13:01 2017 +0000 eina: Add a little more documentation for our examples --- reference/c/eina/src/eina_array.c | 15 ++++++++++++++- reference/c/eina/src/eina_hash.c | 16 ++++++++++++++++ reference/c/eina/src/eina_iterator.c | 9 +++++++++ reference/c/eina/src/eina_list.c | 9 +++++++++ reference/c/eina/src/eina_string.c | 29 +++++++++++++++++++++++++++-- reference/c/eina/src/eina_value.c | 17 +++++++++++++++++ reference/c/eina/src/eina_value_custom.c | 11 +++++++++++ 7 files changed, 103 insertions(+), 3 deletions(-) diff --git a/reference/c/eina/src/eina_array.c b/reference/c/eina/src/eina_array.c index 79b60cf..9086c02 100644 --- a/reference/c/eina/src/eina_array.c +++ b/reference/c/eina/src/eina_array.c @@ -6,9 +6,18 @@ #include <Eina.h> #include <Efl_Core.h> +/* + * Eina Array examples. + * + * These examples demonstrate how to work with eina_array data and methods. + * We use a simple array of strings to initialise our eina_array before + * performing various mutations and printing the results. + */ + static Eina_Array * _array_create() { + // some content to populate our array const char *names[] = { "helo", "hera", "starbuck", "kat", "boomer", @@ -20,7 +29,8 @@ _array_create() Eina_Array *array; unsigned int i; - array = eina_array_new(20); + // set up an array with a growth step to give a little headroom + array = eina_array_new(25); for (i = 0; i < 20; i++) eina_array_push(array, strdup(names[i])); @@ -33,6 +43,7 @@ static void _array_free(Eina_Array *array) char *item; unsigned int i; + // free each item in our array and then free the array itself EINA_ARRAY_ITER_NEXT(array, i, item, iterator) free(item); eina_array_free(array); @@ -41,6 +52,7 @@ static void _array_free(Eina_Array *array) static Eina_Bool _item_print(const void *container EINA_UNUSED, void *data, void *fdata EINA_UNUSED) { + // we know our content is just strings so we can simply printf the data printf(" %s\n", (char *)data); return EINA_TRUE; } @@ -51,6 +63,7 @@ _item_keep(void *data, void *gdata EINA_UNUSED) const char *name; name = (const char *)data; + // let's keep any strings that are no more than 7 characters long if (strlen(name) <= 7) return EINA_TRUE; diff --git a/reference/c/eina/src/eina_hash.c b/reference/c/eina/src/eina_hash.c index 007ccc6..986f54e 100644 --- a/reference/c/eina/src/eina_hash.c +++ b/reference/c/eina/src/eina_hash.c @@ -6,6 +6,17 @@ #include <Eina.h> #include <Efl_Core.h> +/* + * Eina Hash examples. + * + * These examples demonstrate how to work with eina_hash data and methods. + * + * We have two main hash objects here, firstly an int keyed hash with some + * dummy content. + * The second example is that of a simple telephone book. The names are the + * string keys to the hash with phone numbers in the data field. + */ + static void _entry_free_cb(void *data) { @@ -38,11 +49,13 @@ _hash_demo() hash = _hash_create(); + // get an iterator of the keys so we can print a line per entry iter = eina_hash_iterator_key_new(hash); printf("Print contents of int hash\n"); EINA_ITERATOR_FOREACH(iter, key) { + // look up the value for the key so we can print both value = eina_hash_find(hash, key); printf(" Item found with id %d has value %s\n", *key, value); } @@ -52,6 +65,8 @@ _hash_demo() eina_hash_free(hash); } +// here we begin the phone book example + static void _phonebook_entry_print(const void *key, void *data) { @@ -68,6 +83,7 @@ _phonebook_print(Eina_Hash *book) count = eina_hash_population(book); printf("Complete phone book (%d):\n", count); + // this iterator returns the key and value for each entry iter = eina_hash_iterator_tuple_new(book); EINA_ITERATOR_FOREACH(iter, t) _phonebook_entry_print(t->key, t->data); diff --git a/reference/c/eina/src/eina_iterator.c b/reference/c/eina/src/eina_iterator.c index c286a6e..257e9ed 100644 --- a/reference/c/eina/src/eina_iterator.c +++ b/reference/c/eina/src/eina_iterator.c @@ -6,6 +6,15 @@ #include <Eina.h> #include <Efl_Core.h> +/* + * Eina Iterator examples. + * + * These examples demonstrate how to work with eina_iterator methods. + * Both an eina_list and an eina_array are created and an iterator obtained + * for both. You can see how we can use iterators irrespective of the source + * and also that there are different ways to work with iterating content. + */ + static Eina_Bool _print_item(const void *container EINA_UNUSED, void *data, void *fdata EINA_UNUSED) { diff --git a/reference/c/eina/src/eina_list.c b/reference/c/eina/src/eina_list.c index ac4f6e6..69cad22 100644 --- a/reference/c/eina/src/eina_list.c +++ b/reference/c/eina/src/eina_list.c @@ -6,11 +6,20 @@ #include <Eina.h> #include <Efl_Core.h> +/* + * Eina List examples. + * + * These examples demonstrate how to work with eina_list data and methods. + * We create a simple list of names by appending strings to an empty list + * and then run various mutations and print each result. + */ + static Eina_List * _list_create() { Eina_List *list = NULL; + // passing NULL as the list parameter will create a new list list = eina_list_append(list, "Adama"); list = eina_list_append(list, "Baltar"); list = eina_list_append(list, "Roslin"); diff --git a/reference/c/eina/src/eina_string.c b/reference/c/eina/src/eina_string.c index f4c306a..4e2e95d 100644 --- a/reference/c/eina/src/eina_string.c +++ b/reference/c/eina/src/eina_string.c @@ -6,6 +6,17 @@ #include <Eina.h> #include <Efl_Core.h> +/* + * Eina String examples. + * + * These examples demonstrate how to work with eina_str, eina_strbuf and + * eina_stringshare. The eina_str_* methods are helper functions for managing + * strings, eina_stringshare provides methods for more easily managing the + * memory needed by strings, saving space and speeding up operations. + * Lastly eina_strbuf is an API for mutating strings optimally which can then + * provide stanard string exports to work with stanard string functions. + */ + static void _string_splitjoin() { @@ -14,11 +25,13 @@ _string_splitjoin() char *joined; int i; + // split the string into an array on each occurrence of ";" printf("Name list split\n"); arr = eina_str_split(names, ";", 0); for (i = 0; arr[i]; i++) printf(" %s\n", arr[i]); + // Here we re-join two of the strings with a different separator - "&" joined = malloc(sizeof(char) * 11); eina_str_join_len(joined, 11, '&', arr[0], strlen(arr[0]), arr[1], strlen(arr[1])); @@ -40,9 +53,10 @@ _string_case() eina_str_toupper(&str); printf(" Upper: %s\n", str); + free(str); + eina_str_tolower(&str); printf(" Lower: %s\n", str); - free(str); } @@ -55,8 +69,11 @@ _string_startend() printf("File named %s:\n", file); printf(" starts with \"lib\"? %d\n", eina_str_has_prefix(file, "lib")); printf(" ends with \"efl.SO\"? %d\n", eina_str_has_suffix(file, "efl.SO")); + + // The has_extension method is like has_suffix but case insensitive printf(" has extension \".SO\"? %d\n", eina_str_has_extension(file, ".SO")); + // we can also copy segments of a string start = malloc(sizeof(char) * 7); eina_strlcpy(start, file, 7); printf(" first 6 chars \"%s\"\n", start); @@ -70,6 +87,8 @@ _string_escape() char *tmp; str = "Here's some \"example\" text."; + + // backslash escaping a string for use on the command line, for example tmp = eina_str_escape(str); printf("String: %s\n", str); printf("Escaped: %s\n", tmp); @@ -100,11 +119,14 @@ _string_share() "%s will be revealed."; const char *line3 = "There are many copies. And they have a plan."; + // Creating a new stringshare which is deleted when we are done + // If other methods had referenced the string it would not delete immediately printf("Line1: %s\n", line1); str = eina_stringshare_add_length(line1, 31); printf(" limited to %d: %s\n", eina_stringshare_strlen(str), str); eina_stringshare_del(str); + // There are many helpful printf functions for formatting shared strings str = eina_stringshare_printf(line2, 12, 3, 4, "four"); printf("Line2: %s\n", str); eina_stringshare_del(str); @@ -112,6 +134,7 @@ _string_share() printf(" format limit (len %d): %s...\n", eina_stringshare_strlen(str), str); eina_stringshare_del(str); + // By replacing a stringshare it applies anywhere that references this share printf("Line3: %s\n", line3); str = eina_stringshare_add(line3); printf(" shared: %s\n", str); @@ -125,12 +148,13 @@ _string_buf() { Eina_Strbuf *buf, *substr; + // populate a new bugger buf = eina_strbuf_new(); - eina_strbuf_append_length(buf, "BUFFE", 5); eina_strbuf_append_char(buf, 'R'); printf("buffer: %s\n", eina_strbuf_string_get(buf)); + // Demonstrating standard string functions using a strbuf eina_strbuf_tolower(buf); printf("lower: %s\n", eina_strbuf_string_get(buf)); @@ -143,6 +167,7 @@ _string_buf() eina_strbuf_reset(buf); printf("\n"); + // we can even insert or remove content within the string buffer eina_strbuf_append_printf(buf, "%s%c", "buffe", 'r'); eina_strbuf_insert_printf(buf, " %s: %d", 6, "length", (int)eina_strbuf_length_get(buf)); printf("printf: %s\n", eina_strbuf_string_get(buf)); diff --git a/reference/c/eina/src/eina_value.c b/reference/c/eina/src/eina_value.c index 0fe7a79..5980117 100644 --- a/reference/c/eina/src/eina_value.c +++ b/reference/c/eina/src/eina_value.c @@ -6,6 +6,15 @@ #include <Eina.h> #include <Efl_Core.h> +/* + * Eina Value examples. + * + * These examples demonstrate how to work with eina_value data and methods. + * Eina_Value is a way to represent and pass data of varying types and to + * convert efficiently between them.. + * Eina_Value can even define structs for managing more complex requirements. + */ + static void _value_int() { @@ -13,11 +22,13 @@ _value_int() char *str; int i; + // Setting up an integer value type eina_value_setup(&int_val, EINA_VALUE_TYPE_INT); eina_value_set(&int_val, 123); eina_value_get(&int_val, &i); printf("int_val value is %d\n", i); + // It can easily be converted it to a string str = eina_value_to_string(&int_val); printf("int_val to string is \"%s\"\n", str); free(str); // it was allocated by eina_value_to_string() @@ -31,11 +42,14 @@ _value_string() const char *str; char *newstr; + // Setting up an integer value type eina_value_setup(&str_val, EINA_VALUE_TYPE_STRING); eina_value_set(&str_val, "My string"); eina_value_get(&str_val, &str); printf("str_val value is \"%s\" (pointer: %p)\n", str, str); + // To string here will copy the data, so we still need to free it + // Notice that the pointer is different on the returned string newstr = eina_value_to_string(&str_val); printf("str_val to string is \"%s\" (pointer: %p)\n", newstr, newstr); free(newstr); // it was allocated by eina_value_to_string() @@ -49,6 +63,7 @@ _value_convert() int i; char *str; + // set up string and int types to convert between eina_value_setup(&str_val, EINA_VALUE_TYPE_STRING); eina_value_setup(&int_val, EINA_VALUE_TYPE_INT); @@ -86,6 +101,7 @@ _value_struct_define() EINA_VALUE_STRUCT_MEMBER(NULL, Struct, chr) }; + // set up the members and describe the struct parameters members[0].type = EINA_VALUE_TYPE_INT; members[1].type = EINA_VALUE_TYPE_CHAR; static Eina_Value_Struct_Desc desc = { @@ -121,6 +137,7 @@ _value_struct_print(Eina_Value *struct_val) printf(" num: %d\n", num); printf(" chr: %c\n", chr); + // we can check if a struct contains a field before working with it if (eina_value_struct_get(struct_val, "missing", &num)) printf( "missing: %d\n", num); } diff --git a/reference/c/eina/src/eina_value_custom.c b/reference/c/eina/src/eina_value_custom.c index 6b309e5..a80f177 100644 --- a/reference/c/eina/src/eina_value_custom.c +++ b/reference/c/eina/src/eina_value_custom.c @@ -2,10 +2,21 @@ #define EFL_BETA_API_SUPPORT 1 #include <stdio.h> +#include <sys/time.h> #include <Eina.h> #include <Efl_Core.h> +/* + * Eina Value custom examples. + * + * Eina_Value allows the definition of custom types which can be passed like + * any other Eina_Value. This example defines a custom timezone type and all + * the methods that must be implemented for a custom type. + * As this encapsulates the system timezone struct we initialise it from + * the gettimeofday method.. + */ + static Eina_Bool _tz_setup(const Eina_Value_Type *type, void *mem) { --
