From cd70fc8007c6e2e5e210826b532cbe7ea93af798 Mon Sep 17 00:00:00 2001
From: gastal <gastal@7cbeb6ba-43b4-40fd-8cce-4c39aea84d33>
Date: Mon, 27 Jun 2011 20:26:43 +0000
Subject: [PATCH] Eina: eina_str example and accompanying documentation.

git-svn-id: svn+ssh://svn.enlightenment.org/var/svn/e/trunk/eina@60742 7cbeb6ba-43b4-40fd-8cce-4c39aea84d33
---
 src/examples/Makefile.am   |  6 +++--
 src/examples/eina_str_01.c | 58 ++++++++++++++++++++++++++++++++++++++++++++++
 src/include/eina_str.h     | 48 ++++++++++++++++++++++++++++++++++++++
 3 files changed, 110 insertions(+), 2 deletions(-)
 create mode 100644 src/examples/eina_str_01.c

diff --git a/src/examples/Makefile.am b/src/examples/Makefile.am
index 64e4193..f3e474c 100644
--- a/src/examples/Makefile.am
+++ b/src/examples/Makefile.am
@@ -28,7 +28,8 @@ SRCS = \
 	eina_log_03.c \
 	eina_inlist_01.c \
 	eina_inlist_02.c \
-	eina_inlist_03.c
+	eina_inlist_03.c \
+	eina_str_01.c
 
 pkglib_PROGRAMS =
 
@@ -56,6 +57,7 @@ pkglib_PROGRAMS += \
 	eina_log_03 \
 	eina_inlist_01 \
 	eina_inlist_02 \
-	eina_inlist_03
+	eina_inlist_03 \
+	eina_str_01
 endif
 
diff --git a/src/examples/eina_str_01.c b/src/examples/eina_str_01.c
new file mode 100644
index 0000000..8de1f43
--- /dev/null
+++ b/src/examples/eina_str_01.c
@@ -0,0 +1,58 @@
+//Compile with:
+//gcc -Wall -o eina_str_01 eina_str_01.c `pkg-config --cflags --libs eina`
+
+#include <stdio.h>
+#include <Eina.h>
+
+int main(int argc, char **argv)
+{
+   char *names = "Calvin;Leoben;D'anna;Simon;Doral;Six;Daniel;Sharon";
+   char *str;
+   char *prologue;
+   char *part1 = "The Cylons were created by man. They evolved. They rebelled.";
+   char *part2 = "There are many copies. And they have a plan.";
+   char **arr;
+   int i;
+
+   eina_init();
+
+   arr = eina_str_split(names, ";", 0);
+   for (i = 0; arr[i]; i++)
+     printf("%s\n", arr[i]);
+
+   str = malloc(sizeof(char) * 4);
+   sprintf(str, "%s", "bsg");
+
+   eina_str_toupper((char **)&str);
+   printf("%s\n", str);
+   eina_str_tolower(&str);
+   printf("%s\n", str);
+
+   if (eina_str_has_prefix(names, "Calvin"))
+      printf("Starts with 'Calvin'\n");
+   if (eina_str_has_suffix(names, "sharon"))
+      printf("Ends with 'sharon'\n");
+   if (eina_str_has_extension(names, "sharon"))
+      printf("Has extension 'sharon'\n");
+
+   printf("%s\n", eina_str_escape("They'll start going ripe on us pretty soon."));
+
+   prologue = malloc(sizeof(char) * 106);
+   eina_str_join_len(prologue, 106, ' ', part1, strlen(part1), part2, strlen(part2));
+   printf("%s\n", prologue);
+
+   eina_strlcpy(str, prologue, 4);
+   printf("%s\n", str);
+
+   free(prologue);
+   free(str);
+
+   str = malloc(sizeof(char) * 14);
+   sprintf(str, "%s", "cylons+");
+   eina_strlcat(str, "humans", 14);
+   printf("%s\n", str);
+
+   eina_shutdown();
+
+   return 0;
+}
diff --git a/src/include/eina_str.h b/src/include/eina_str.h
index 477e024..b4854d6 100644
--- a/src/include/eina_str.h
+++ b/src/include/eina_str.h
@@ -7,6 +7,52 @@
 #include "eina_types.h"
 
 /**
+ * @page tutorial_eina_string Eina String example
+ * @dontinclude eina_str_01.c
+ *
+ * Whenever using eina we need to include it:
+ * @skipline #include
+ * @line #include
+ *
+ * In our main function we declare(and initialize) some variables and initialize
+ * eina:
+ * @until eina_init
+ *
+ * It's frequentely nescessary to split a string into it's constituent parts,
+ * eina_str_split() make's it easy to do so:
+ * @until printf
+ *
+ * Another common need is to make a string uppercase or lowercase, so let's
+ * create a string and make it uppercase and then make it lowercase again:
+ * @until printf
+ * @until printf
+ *
+ * Next we use eina to check if our @p names string starts or ends with some
+ * values:
+ * @until Has
+ *
+ * When strings will be used in a terminal(or a number of other places) it
+ * nescessary to escape certain characters that appear in them:
+ * @until printf
+ *
+ * Much as we previously split a string we will now join two strings:
+ * @until printf
+ *
+ * With strlcpy() we can copy what portion of the @p prologue fits in @p str and
+ * be sure that it's still NULL terminated:
+ * @until printf
+ *
+ * Since we are done with @p prologue and @p str we should free them:
+ * @until free(str
+ *
+ * Finally we see strlcat in action:
+ * @until printf("
+ *
+ * And then shut eina down and exit:
+ * @until }
+ * @example eina_str_01.c
+ */
+/**
  * @addtogroup Eina_String_Group String
  *
  * @brief These functions provide useful C string management.
@@ -17,6 +63,8 @@
 /**
  * @addtogroup Eina_Tools_Group Tools
  *
+ * For more information refer to the @ref tutorial_eina_string "string example".
+ *
  * @{
  */
 
-- 
2.7.4