aboutsummaryrefslogtreecommitdiffstats
path: root/src/lib/eina/eina_tmpstr.h
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/eina/eina_tmpstr.h')
-rw-r--r--src/lib/eina/eina_tmpstr.h197
1 files changed, 102 insertions, 95 deletions
diff --git a/src/lib/eina/eina_tmpstr.h b/src/lib/eina/eina_tmpstr.h
index 7460356930..6f0d5587bb 100644
--- a/src/lib/eina/eina_tmpstr.h
+++ b/src/lib/eina/eina_tmpstr.h
@@ -1,14 +1,14 @@
/* 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
+ * This library is a 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
+ * 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
@@ -28,23 +28,23 @@
* 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
+ * all copies of the Software and its Copyright notices. In addition, publicly
+ * documented acknowledgement 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
+ * acknowledgements 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
+ * Please see 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
+ * 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
+ * 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.
*/
@@ -54,34 +54,34 @@
#include "eina_types.h"
/**
- * @page eina_tmpstr_ppage
- *
+ * @page eina_tmpstr_page
+ *
* 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
+ * don't work with multiple threads or when returning multiple 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,
+ * as a parameter 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");
@@ -89,21 +89,23 @@
* 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
+ * type marker letting you know that the function cleans up those
* strings after use, and it is totally interchangeable with const char.
*/
/**
- * @addtogroup Eina_Data_Types_Group Data Types
+ * @defgroup Eina_Tmpstr_Group Tmpstr
+ * @ingroup Eina_Data_Types_Group
*
- * @{
- */
-
-/**
- * @defgroup Eina_Stringshare_Group Stringshare
+ * @brief 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 multiple times as
+ * parameters to a single function.
+ *
+ * @ref eina_tmpstr_page
*
* @{
*/
@@ -111,9 +113,9 @@
/**
* @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.
+ * @brief Interchangeable with "const char *", but still a good visual hint for the
+ * purpose. This indicates that the string is temporary and should be freed after
+ * use.
*
* @since 1.8.0
*/
@@ -121,106 +123,115 @@
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().
- *
+ * @brief Adds a new temporary string based on the input string.
+ *
+ * @since 1.8.0
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks 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 long 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 cleaned up automatically by the caller.
+ *
+ * @remarks If @a str is @c NULL, or no memory space exists to store the tmpstr, then
+ * @c NULL is returned, otherwise a valid string pointer is 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 you are done with the string you should delete it
+ * using 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
- *
+ *
+ * @param[in] str The input string that is copied into the temp string
+ * @return A pointer to the tmp string that is a standard C string
+ *
* @see eina_tmpstr_del()
* @see eina_tmpstr_add_length()
- *
- * @since 1.8.0
*/
EAPI Eina_Tmpstr *eina_tmpstr_add(const char *str) EINA_WARN_UNUSED_RESULT;
/**
- * @brief Add a new temporary string based on the input string and length.
- *
- * @param str This is the input stringthat is copied into the temp string.
- * @param length This is the maximum length and the allocated length of 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().
+ * @brief Adds a new temporary string based on the input string and length.
+ *
+ * @since 1.8.0
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks 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 long 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 cleaned up automatically by the caller.
+ *
+ * @remarks If @a str is @c NULL, or no memory space exists to store the tmpstr, then
+ * @c NULL is returned, otherwise a valid string pointer is 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 you are done with the string you should delete it
+ * using eina_tmpstr_del().
*
* @note If the length is greater than the actual string, but still '\0'
* terminateed. Their won't be any crash and the string will be correct,
* but eina_tmpstr_strlen will return an erroneous length. So if you
* want to have the correct length always call eina_tmpstr_add_length
* with length == strlen(str).
+ *
+ * @param[in] str The input string that is copied into the temp string
+ * @param[in] length The maximum length and the allocated length of the temp string
+ * @return A pointer to the tmp string that is a standard C string
+ *
* @see eina_tmpstr_del()
* @see eina_tmpstr_add()
- *
- * @since 1.8.0
*/
EAPI Eina_Tmpstr *eina_tmpstr_add_length(const char *str, size_t length);
/**
- * @brief Return the length of a temporary string including the '\0'.
- *
- * @param tmpstr This is any C string pointer, but if it is a tmp string
- * it will return the length faster.
- * @return The length of the string including the '\0';
+ * @brief Returns the length of a temporary string including the '\0'.
*
* @since 1.8.0
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] tmpstr A C string pointer, but if it is a tmp string
+ * it returns the length faster
+ * @return The length of the string including the '\0'
*/
EAPI size_t eina_tmpstr_strlen(Eina_Tmpstr *tmpstr);
/**
- * @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()
- *
+ * @brief Deletes the temporary string if it is one, or ignores it if it is not.
+ *
+ * @details This deletes the given temporary string @a tmpstr if it is a valid
+ * temporary string, otherwise it ignores it and does nothing, so this
+ * can be used safely with non-temporary strings.
+ *
* @since 1.8.0
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] tmpstr A C string pointer, but if it is a tmp string
+ * it is freed
+ *
+ * @see eina_tmpstr_add()
*/
EAPI void eina_tmpstr_del(Eina_Tmpstr *tmpstr) EINA_ARG_NONNULL(1);
@@ -228,8 +239,4 @@ EAPI void eina_tmpstr_del(Eina_Tmpstr *tmpstr) EINA_ARG_NONNULL(1);
* @}
*/
-/**
- * @}
- */
-
#endif