1 /* EINA - EFL data type library 2 * Copyright (C) 2002-2012 Carsten Haitzler, Jorge Luis Zapata Muga, Cedric Bail 3 * 4 * This library is free software; you can redistribute it and/or 5 * modify it under the terms of the GNU Lesser General Public 6 * License as published by the Free Software Foundation; either 7 * version 2.1 of the License, or (at your option) any later version. 8 * 9 * This library is distributed in the hope that it will be useful, 10 * but WITHOUT ANY WARRANTY; without even the implied warranty of 11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 12 * Lesser General Public License for more details. 13 * 14 * You should have received a copy of the GNU Lesser General Public 15 * License along with this library; 16 * if not, see <http://www.gnu.org/licenses/>. 17 * 18 * This file incorporates work covered by the following copyright and 19 * permission notice: 20 * 21 * Copyright (C) 2008 Peter Wehrfritz 22 * 23 * Permission is hereby granted, free of charge, to any person obtaining a copy 24 * of this software and associated documentation files (the "Software"), to 25 * deal in the Software without restriction, including without limitation the 26 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or 27 * sell copies of the Software, and to permit persons to whom the Software is 28 * furnished to do so, subject to the following conditions: 29 * 30 * The above copyright notice and this permission notice shall be included in 31 * all copies of the Software and its Copyright notices. In addition publicly 32 * documented acknowledgment must be given that this software has been used if no 33 * source code of this software is made available publicly. This includes 34 * acknowledgments in either Copyright notices, Manuals, Publicity and Marketing 35 * documents or any documentation provided with any product containing this 36 * software. This License does not apply to any software that links to the 37 * libraries provided by this software (statically or dynamically), but only to 38 * the software provided. 39 * 40 * Please see the OLD-COPYING.PLAIN for a plain-english explanation of this notice 41 * and it's intent. 42 * 43 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 44 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 45 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL 46 * THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER 47 * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 48 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 49 */ 50 51 #ifndef EINA_TMPSTR_H_ 52 #define EINA_TMPSTR_H_ 53 54 #include "eina_types.h" 55 56 /** 57 * @page eina_tmpstr_ppage 58 * 59 * Eina tmpstr is intended for being able to conveniently pass strings back 60 * to a calling parent without having to use single static buffers (which 61 * don't work with multiple threads or when returning multiple times as 62 * parameters to a single function. 63 * 64 * The traditional way to "return" a string in C is either to provide a buffer 65 * as a parameter to return it in, return a pointer to a single static buffer, 66 * which has issues, or return a duplicated string. All cases are inconvenient 67 * and return special handling. This is intended to make this easier. Now you 68 * can do something like this: 69 * 70 * @code 71 * Eina_Tmpstr *my_homedir(void) { 72 * return eina_tmpstr_add(eina_environment_home_get()); 73 * } 74 * 75 * Eina_Tmpstr *my_tmpdir(void) { 76 * return eina_tmpstr_add(getenv("TMP")); 77 * } 78 * 79 * void my_movefile(Eina_Tmpstr *src, Eina_Tmpstr *dst) { 80 * rename(src, dst); 81 * eina_tmpstr_del(src); 82 * eina_tmpstr_del(dst); 83 * } 84 * 85 * char buf[500]; 86 * my_movefile(my_homedir(), my_tmpdir()); 87 * my_movefile("/tmp/file", "/tmp/newname"); 88 * my_movefile(my_homedir(), "/var/tmp"); 89 * snprintf(buf, sizeof(buf), "/tmp/%i.file", rand()); 90 * my_movefile("/tmp.file", buf); 91 * @endcode 92 * 93 * Notice that you can interchange standard C strings (static ones or even 94 * generated buffers) with tmpstrings. The Eina_Tmpstr type is merely a 95 * type marker letting you know that the function will clean up those 96 * strings after use, and it is totally interchangeable with const char. 97 */ 98 99 /** 100 * @addtogroup Eina_Data_Types_Group Data Types 101 * 102 * @{ 103 */ 104 105 /** 106 * @defgroup Eina_Stringshare_Group Stringshare 107 * 108 * @{ 109 */ 110 111 /** 112 * @typedef Eina_Tmpstr 113 * 114 * Interchangeable with "const char *" but still a good visual hint for the 115 * purpose. This indicates the string is temporary and should be freed after 116 * use. 117 * 118 * @since 1.8.0 119 */ 120 121 typedef const char Eina_Tmpstr; 122 123 /** 124 * @brief Adds a new temporary string based on the input string. 125 * 126 * @param[in] str This is the input string that is copied into the temp string. 127 * @return A pointer to the tmp string that is a standard C string. 128 * 129 * When you add a temporary string (tmpstr) it is expected to have a very 130 * short lifespan, and at any one time only a few of these are intended to 131 * exist. This is not intended for longer term storage of strings. The 132 * intended use is the ability to safely pass strings as return values from 133 * functions directly into parameters of new functions and then have the 134 * string be cleaned up automatically by the caller. 135 * 136 * If @p str is NULL, or no memory space exists to store the tmpstr, then 137 * NULL will be returned, otherwise a valid string pointer will be returned 138 * that you can treat as any other C string (e.g. strdup(tmpstr) or 139 * printf("%s\n", tmpstr) etc.). This string should be considered read-only 140 * and immutable, and when you are done with the string you should delete it 141 * with eina_tmpstr_del(). 142 * 143 * Example usage: 144 * 145 * @code 146 * Eina_Tmpstr *my_homedir(void) { 147 * return eina_tmpstr_add(eina_environment_home_get()); 148 * } 149 * 150 * void my_rmfile(Eina_Tmpstr *str) { 151 * if (!str) return; 152 * unlink(str); 153 * eina_tmpstr_del(str); 154 * } 155 * 156 * my_rmfile(my_homedir()); 157 * my_rmfile("/tmp/file"); 158 * @endcode 159 * 160 * @see eina_tmpstr_del() 161 * @see eina_tmpstr_add_length() 162 * 163 * @since 1.8.0 164 */ 165 EAPI Eina_Tmpstr *eina_tmpstr_add(const char *str) EINA_WARN_UNUSED_RESULT; 166 167 /** 168 * @brief Adds a new temporary string based on the input string and length. 169 * 170 * @param[in] str This is the input string that is copied into the temp string. 171 * @param[in] length This is the maximum length and the allocated length of the temp string. 172 * @return A pointer to the tmp string that is a standard C string. 173 * 174 * When you add a temporary string (tmpstr) it is expected to have a very 175 * short lifespan, and at any one time only a few of these are intended to 176 * exist. This is not intended for longer term storage of strings. The 177 * intended use is the ability to safely pass strings as return values from 178 * functions directly into parameters of new functions and then have the 179 * string be cleaned up automatically by the caller. 180 * 181 * If @p str is NULL, or no memory space exists to store the tmpstr, then 182 * NULL will be returned, otherwise a valid string pointer will be returned 183 * that you can treat as any other C string (e.g. strdup(tmpstr) or 184 * printf("%s\n", tmpstr) etc.). This string should be considered read-only 185 * and immutable, and when you are done with the string you should delete it 186 * with eina_tmpstr_del(). 187 * 188 * @note If the length is greater than the actual string, but still '\0' 189 * terminated, there won't be any crash and the string will be correct, 190 * but eina_tmpstr_len will return an erroneous length. So if you 191 * want to have the correct length always call eina_tmpstr_add_length 192 * with length == strlen(str). 193 * @see eina_tmpstr_del() 194 * @see eina_tmpstr_add() 195 * 196 * @since 1.8.0 197 */ 198 EAPI Eina_Tmpstr *eina_tmpstr_add_length(const char *str, size_t length); 199 200 /** 201 * @brief **Deprecated** Return the length of a temporary string including the '\0'. 202 * 203 * @param tmpstr This is any C string pointer, but if it is a tmp string 204 * it will return the length faster. 205 * @return The length of the string including the '\0' 206 * 207 * @deprecated 208 * @see eina_tmpstr_len() 209 * @since 1.8.0 210 */ 211 EINA_DEPRECATED EAPI size_t eina_tmpstr_strlen(Eina_Tmpstr *tmpstr); 212 213 /** 214 * @brief Returns the length of a temporary string. 215 * 216 * @param[in] tmpstr This is any C string pointer, but if it is a tmp string 217 * it will return the length faster. 218 * @return The length of the string. 219 * 220 * @since 1.14.0 221 */ 222 EAPI size_t eina_tmpstr_len(Eina_Tmpstr *tmpstr); 223 224 /** 225 * @brief Deletes the temporary string if it is one, or ignore it if it is not. 226 * 227 * @param[in] tmpstr This is any C string pointer, but if it is a tmp string 228 * it is freed. 229 * 230 * This will delete the given temporary string @p tmpstr if it is a valid 231 * temporary string, or otherwise it will ignore it and do nothing so this 232 * can be used safely with non-temporary strings. 233 * 234 * @see eina_tmpstr_add() 235 * 236 * @since 1.8.0 237 */ 238 EAPI void eina_tmpstr_del(Eina_Tmpstr *tmpstr) EINA_ARG_NONNULL(1); 239 240 /** 241 * @brief Adds a new temporary string using the passed string. The passed 242 * string is used directly as the buffer. The passed string must be malloced. 243 * 244 * @param[in] str The input string to manage. 245 * @return A pointer to the tmp string that is a standard C string. 246 * 247 * This function creates a new temporary string. On error, @c NULL is 248 * returned. To free the resources, use eina_tmpstr_del(). 249 * 250 * @see eina_tmpstr_del() 251 * @since 1.17.0 252 */ 253 EAPI Eina_Tmpstr *eina_tmpstr_manage_new(char *str) EINA_WARN_UNUSED_RESULT; 254 255 /** 256 * @brief Adds a new temporary string using the passed string. The passed 257 * string is used directly as the buffer. The passed string must be malloced. 258 * 259 * @param[in] str The input string to manage. 260 * @param[in] length The length of the string. 261 * @return A pointer to the tmp string that is a standard C string. 262 * 263 * This function creates a new temporary string. On error, @c NULL is 264 * returned. To free the resources, use eina_tmpstr_del(). 265 * 266 * @see eina_tmpstr_manage_new() 267 * @see eina_tmpstr_del() 268 * @since 1.17.0 269 */ 270 EAPI Eina_Tmpstr *eina_tmpstr_manage_new_length(char *str, size_t length); 271 272 /** 273 * @} 274 */ 275 276 /** 277 * @} 278 */ 279 280 #endif 281