aboutsummaryrefslogtreecommitdiffstats
path: root/reference
diff options
context:
space:
mode:
authorAndy Williams <andy@andywilliams.me>2017-11-16 15:13:01 +0000
committerAndy Williams <andy@andywilliams.me>2017-11-16 15:13:01 +0000
commit13fb2b4b1b4e514fbf2a4d78d1f8ac4dd2b564da (patch)
treef2aad79fea099a9bdc952d70021ab3c501ef6d1f /reference
parenteina: Add str/strbuf/stringshare reference examples (diff)
downloadexamples-13fb2b4b1b4e514fbf2a4d78d1f8ac4dd2b564da.tar.gz
eina: Add a little more documentation for our examples
Diffstat (limited to 'reference')
-rw-r--r--reference/c/eina/src/eina_array.c15
-rw-r--r--reference/c/eina/src/eina_hash.c16
-rw-r--r--reference/c/eina/src/eina_iterator.c9
-rw-r--r--reference/c/eina/src/eina_list.c9
-rw-r--r--reference/c/eina/src/eina_string.c29
-rw-r--r--reference/c/eina/src/eina_value.c17
-rw-r--r--reference/c/eina/src/eina_value_custom.c11
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 79b60cfe..9086c02d 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 007ccc67..986f54ea 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 c286a6e7..257e9ed2 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 ac4f6e68..69cad22f 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 f4c306ab..4e2e95dc 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 0fe7a79d..59801172 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 6b309e56..a80f177c 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)
{