Documented example for eina_value.

SVN revision: 68071

legacy/eina/src/examples/Makefile.am

@@ -40,7 +40,8 @@ SRCS = \
 	eina_tiler_01.c \
 	eina_model_01.c \
 	eina_model_02.c \
-	eina_model_03.c
+	eina_model_03.c \
+	eina_value_01.c
 
 examples_PROGRAMS =
 
@@ -80,7 +81,8 @@ examples_PROGRAMS += \
 	eina_model_01 \
 	eina_model_02 \
 	eina_model_03 \
-	eina_model_04
+	eina_model_04 \
+	eina_value_01
 
 eina_model_04_SOURCES = \
 	eina_model_04_animal.c \

legacy/eina/src/examples/eina_value_01.c

@@ -0,0 +1,50 @@
+#include <Eina.h>
+
+int main(int argc, char **argv)
+{
+   Eina_Value v;
+   int i;
+   char *newstr;
+
+   eina_init();
+
+   eina_value_setup(&v, EINA_VALUE_TYPE_INT);
+   eina_value_set(&v, 123);
+   eina_value_get(&v, &i);
+   printf("v=%d\n", i);
+
+   newstr = eina_value_to_string(&v);
+   printf("v as string: %s\n", newstr);
+   free(newstr); // it was allocated by eina_value_to_string()
+   eina_value_flush(&v); // destroy v contents, will not use anymore
+
+   const char *s;
+   eina_value_setup(&v, EINA_VALUE_TYPE_STRING);
+   eina_value_set(&v, "My string");
+   eina_value_get(&v, &s);
+   printf("v=%s (pointer: %p)\n", s, s);
+
+   newstr = eina_value_to_string(&v);
+   printf("v as string: %s (pointer: %p)\n", newstr, newstr);
+   free(newstr); // it was allocated by eina_value_to_string()
+   eina_value_flush(&v); // destroy v contents, string 's' is not valid anymore!
+
+   Eina_Value otherv;
+   eina_value_setup(&otherv, EINA_VALUE_TYPE_STRING);
+   eina_value_setup(&v, EINA_VALUE_TYPE_INT);
+
+   // convert from int to string:
+   eina_value_set(&v, 123);
+   eina_value_convert(&v, &otherv);
+   eina_value_get(&otherv, &s);
+   printf("otherv=%s\n", s);
+
+   // and the other way around!
+   eina_value_set(&otherv, "33");
+   eina_value_convert(&otherv, &v);
+   eina_value_get(&v, &i);
+   printf("v=%d\n", i);
+
+   eina_value_flush(&otherv);
+   eina_value_flush(&v);
+}

legacy/eina/src/include/eina_value.h

@@ -26,6 +26,72 @@
 #include "eina_hash.h"
 #include <stdarg.h>
 
+/**
+ * @page eina_value_example_01_page Eina_Value usage
+ * @dontinclude eina_value_01.c
+ *
+ * This very simple example shows how to use some of the basic features of eina
+ * value: setting and getting values, converting between types and printing a
+ * value as a string.
+ *
+ * Our main function starts out with the basic, declaring some variables and
+ * initializing eina:
+ * @until eina_init
+ *
+ * Now we can jump into using eina value. We set a value, get this value and
+ * then print it:
+ * @until printf
+ *
+ * In the above snippet of code we printed an @c int value, we can however print
+ * the value as a string:
+ * @until free
+ *
+ * And once done with a value it's good practice to destroy it:
+ * @until eina_value_flush
+ *
+ * We now reuse @c v to store a string, get its value and print it:
+ * @until printf
+ * @note Since @c s is the value and not returned by @c eina_value_to_string()
+ * we don't need to free it.
+ *
+ * Just because we stored a string doesn't mean we can't use the @c
+ * eina_value_to_string() function, we can and it's important to note that it
+ * will return not the stored string but rather a copy of it(one we have to
+ * free):
+ * @until eina_value_flush
+ *
+ * And now to explore conversions between two type we'll create another value:
+ * @until eina_value_setup
+ *
+ * And make sure @c v and @c otherv have different types:
+ * @until eina_value_setup
+ *
+ * We then set a value to @c v and have it converted, to do this we don't need
+ * to tell to which type we want to convert, we just say were we want to store
+ * the converted value and eina value will figure out what to convert to, and
+ * how:
+ * @until eina_value_convert
+ *
+ * And now let's check the conversion worked:
+ * @until printf
+ *
+ * But converting to strings is not particularly exciting, @c
+ * eina_value_to_string() already did that, so now let's make the conversion the
+ * other way around, from string to @c int:
+ * @until printf
+ *
+ * And once done, destroy the values:
+ * @until }
+ *
+ * Full source code: @ref eina_value_01_c
+ */
+
+/**
+ * @page eina_value_01_c eina_value_01.c
+ * @include eina_value_01.c
+ * @example eina_value_01.c
+ */
+
 /**
  * @addtogroup Eina_Data_Types_Group Data Types
  *
@@ -56,6 +122,9 @@
  * children, reference counting, inheritance and interfaces, see @ref
  * Eina_Model_Group.
  *
+ * Examples of usage of the Eina_Value API:
+ * @li @ref eina_value_example_01_page
+ *
  * @{
  */