add tmpstr to efl eina tree... this is for the future so not going

into eina tree.



SVN revision: 78112

ChangeLog

@@ -43,3 +43,4 @@
 2012-10-17  Carsten Haitzler (The Rasterman)
 
         * Add eina_barrier API to cover pthread_barrier functionality
+        * Add eina_tmpstr_add() and eina_tmpstr_del().

NEWS

@@ -8,6 +8,7 @@ Changes since 1.7.0:
 Additions:
     * Add DOCTYPE children parsing in eina_simple_xml
     * Add eina_barrier thread API
+    * Add eina_tmpstr_add() and eina_tmpstr_del()
     
 Improvements:
     * Single EFL tree now covring all EFL library components.

src/lib/eina/Makefile.am

@@ -82,7 +82,8 @@ eina_mmap.h \
 eina_xattr.h \
 eina_value.h \
 eina_inline_value.x \
-eina_inline_lock_barrier.x
+eina_inline_lock_barrier.x \
+eina_tmpstr.h
 
 # Will be back for developper after 1.2.
 # eina_model.h
@@ -151,7 +152,8 @@ eina_value.c \
 eina_xattr.c \
 eina_share_common.h \
 eina_private.h \
-eina_strbuf_common.h
+eina_strbuf_common.h \
+eina_tmpstr.c
 
 # Will be back for developper after 1.2
 # eina_model.c \

src/lib/eina/eina_main.c

@@ -156,6 +156,7 @@ EAPI Eina_Inlist *_eina_tracking = NULL;
    S(file);
    S(prefix);
    S(value);
+   S(tmpstr);
 /* no model for now
    S(model);
  */
@@ -196,6 +197,7 @@ static const struct eina_desc_setup _eina_desc_setup[] = {
    S(file),
    S(prefix),
    S(value),
+   S(tmpstr),
 /* no model for now
    S(model)
  */

src/lib/eina/eina_tmpstr.c

@@ -0,0 +1,106 @@
+/* EINA - EFL data type library
+ * Copyright (C) 2002,2003,2004,2005,2006,2007,2008,2010
+ *                         Carsten Haitzler,
+ *                         Jorge Luis Zapata Muga,
+ *                         Cedric Bail,
+ *                         Gustavo Sverzut Barbieri
+ *                         Tom Hacohen
+ *                         Brett Nash
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library;
+ * if not, see <http://www.gnu.org/licenses/>.
+ */
+
+#include <stdlib.h>
+#include <stdio.h>
+#include <string.h>
+
+#ifdef HAVE_EVIL
+# include <Evil.h>
+#endif
+
+#include "eina_config.h"
+#include "eina_private.h"
+#include "eina_error.h"
+#include "eina_log.h"
+#include "eina_lock.h"
+#include "eina_share_common.h"
+
+/* undefs EINA_ARG_NONULL() so NULL checks are not compiled out! */
+#include "eina_safety_checks.h"
+#include "eina_tmpstr.h"
+
+typedef struct _Str Str;
+
+struct _Str
+{
+   Str *next;
+   char *str;
+};
+
+static Eina_Lock _mutex;
+static Str *strs = NULL;
+
+Eina_Bool
+eina_tmpstr_init(void)
+{
+   if (!eina_lock_new(&_mutex)) return EINA_FALSE;
+   return EINA_TRUE;
+}
+
+Eina_Bool
+eina_tmpstr_shutdown(void)
+{
+   eina_lock_free(&_mutex);
+   return EINA_TRUE;
+}
+
+EAPI Eina_Tmpstr *
+eina_tmpstr_add(const char *str)
+{
+   Str *s;
+   int len;
+   
+   if (!str) return NULL;
+   len = strlen(str);
+   s = malloc(sizeof(Str) + len + 1);
+   if (!s) return NULL;
+   s->str = ((char *)s) + sizeof(Str);
+   strcpy(s->str, str);
+   eina_lock_take(&_mutex);
+   s->next = strs;
+   strs = s;
+   eina_lock_release(&_mutex);
+   return s->str;
+}
+
+EAPI void
+eina_tmpstr_del(Eina_Tmpstr *tmpstr)
+{
+   Str *s, *sp;
+   
+   if ((!strs) || (!tmpstr)) return;
+   eina_lock_take(&_mutex);
+   for (sp = NULL, s = strs; s; sp = s, s = s->next)
+     {
+        if (s->str == tmpstr)
+          {
+             if (sp) sp->next = s->next;
+             else strs = s->next;
+             free(s);
+             break;
+          }
+     }
+   eina_lock_release(&_mutex);
+}

src/lib/eina/eina_tmpstr.h

@@ -0,0 +1,190 @@
+/* EINA - EFL data type library
+ * Copyright (C) 2002-2012 Carsten Haitzler, Jorge Luis Zapata Muga, Cedric Bail
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library;
+ * if not, see <http://www.gnu.org/licenses/>.
+ *
+ * This file incorporates work covered by the following copyright and
+ * permission notice:
+ *
+ * Copyright (C) 2008 Peter Wehrfritz
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to
+ *  deal in the Software without restriction, including without limitation the
+ *  rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ *  sell copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in
+ *  all copies of the Software and its Copyright notices. In addition publicly
+ *  documented acknowledgment must be given that this software has been used if no
+ *  source code of this software is made available publicly. This includes
+ *  acknowledgments in either Copyright notices, Manuals, Publicity and Marketing
+ *  documents or any documentation provided with any product containing this
+ *  software. This License does not apply to any software that links to the
+ *  libraries provided by this software (statically or dynamically), but only to
+ *  the software provided.
+ *
+ *  Please see the OLD-COPYING.PLAIN for a plain-english explanation of this notice
+ *  and it's intent.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+ *  THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+ *  IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ *  CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+#ifndef EINA_TMPSTR_H_
+#define EINA_TMPSTR_H_
+
+#include "eina_types.h"
+
+/**
+ * @page eina_tmpstr_ppage
+ * 
+ * Eina tmpstr is intended for being able to conveniently pass strings back
+ * to a calling parent without having to use single static buffers (which
+ * don't work with multiple threads or when returning multilpe times as
+ * parameters to a single function.
+ * 
+ * The traditional way to "return" a string in C is either to provide a buffer
+ * as a paramater to return it in, return a pointer to a single static buffer,
+ * which has issues, or return a duplicated string. All cases are inconvenient
+ * and return special handling. This is intended to make this easier. Now you
+ * can do something like this:
+ * 
+ * @code
+ * Eina_Tmpstr *my_homedir(void) {
+ *   return eina_tmpstr_add(getenv("HOME"));
+ * }
+ * 
+ * Eina_Tmpstr *my_tmpdir(void) {
+ *   return eina_tmpstr_add(getenv("TMP"));
+ * }
+ * 
+ * void my_movefile(Eina_Tmpstr *src, Eina_Tmpstr *dst) {
+ *   rename(src, dst);
+ *   eina_tmpstr_del(src);
+ *   eina_tmpstr_del(dst);
+ * }
+ * 
+ * char buf[500];
+ * my_movefile(my_homedir(), my_tmpdir());
+ * my_movefile("/tmp/file", "/tmp/newname");
+ * my_movefile(my_homedir(), "/var/tmp");
+ * snprintf(buf, sizeof(buf), "/tmp/%i.file", rand());
+ * my_movefile("/tmp.file", buf);
+ * @endcode
+ * 
+ * Notice that you can interchange standard C strings (static ones or even
+ * generated buffers) with tmpstrings. The Eina_Tmpstr type is merely a
+ * type marker letting you know that the function will clean up those
+ * strings after use, and it is totally interchangeable with const char.
+ */
+
+/**
+ * @addtogroup Eina_Data_Types_Group Data Types
+ *
+ * @{
+ */
+
+/**
+ * @defgroup Eina_Stringshare_Group Stringshare
+ *
+ * @{
+ */
+
+/**
+ * @typedef Eina_Tmpstr
+ *
+ * Interchangeable with "const char *" but still a good visual hint for the
+ * purpose. This indicates the string is temporary and should be freed after
+ * use.
+ *
+ * @since 1.8.0
+ */
+
+typedef const char Eina_Tmpstr;
+
+/**
+ * @brief Add a new temporary string based on the input string.
+ * 
+ * @param str This is the input stringthat is copied into the temp string.
+ * @return A pointer to the tmp string that is a standard C string.
+ * 
+ * When you add a temporary string (tmpstr) it is expected to have a very
+ * short lifespan, and at any one time only a few of these are intended to
+ * exist. This is not intended for longer term storage of strings. The
+ * intended use is the ability to safely pass strings as return values from
+ * functions directly into parameters of new functions and then have the
+ * string be cleaned up automatically by the caller.
+ * 
+ * If @p str is NULL, or no memory space exists to store the tmpstr, then
+ * NULL will be returned, otherwise a valid string pointer will be returned
+ * that you can treat as any other C string (eg strdup(tmpstr) or
+ * printf("%s\n", tmpstr) etc.). This string should be considered read-only
+ * and immutable, and when youa re done with the string yo should delete it
+ * with eina_tmpstr_del().
+ * 
+ * Example usage:
+ * 
+ * @code
+ * Eina_Tmpstr *my_homedir(void) {
+ *   return eina_tmpstr_add(getenv("HOME"));
+ * }
+ * 
+ * void my_rmfile(Eina_Tmpstr *str) {
+ *   if (!str) return;
+ *   unlink(str);
+ *   eina_tmpstr_del(str);
+ * }
+ * 
+ * my_rmfile(my_homedir());
+ * my_rmfile("/tmp/file");
+ * @endcode
+ * 
+ * @see eina_tmpstr_del()
+ * 
+ * @since 1.8.0
+ */
+EAPI Eina_Tmpstr *eina_tmpstr_add(const char *str) EINA_WARN_UNUSED_RESULT;
+
+/**
+ * @brief Delete the temporary string if it is one, or ignore it if it is not.
+ * 
+ * @param tmpstr This is any C string pointer, but if it is a tmp string
+ * it is freed.
+ * 
+ * This will delete the given temporary string @p tmpstr if it is a valid
+ * temporary string, or otherwise it will ignore it and do nothing so this
+ * can be used safely with non-temporary strings.
+ * 
+ * @see eina_tmpstr_add()
+ * 
+ * @since 1.8.0
+ */
+EAPI void eina_tmpstr_del(Eina_Tmpstr *tmpstr) EINA_ARG_NONNULL(1);
+
+/**
+ * @}
+ */
+
+/**
+ * @}
+ */
+
+#endif