string.h 6.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268
  1. /*
  2. * string.h
  3. */
  4. /**
  5. \ingroup lub
  6. \defgroup lub_string string
  7. @{
  8. \brief This utility provides some simple string manipulation functions which
  9. augment those found in the standard ANSI-C library.
  10. As a rule of thumb if a function returns "char *" then the calling client becomes responsible for invoking
  11. lub_string_free() to release the dynamically allocated memory.
  12. If a "const char *" is returned then the client has no responsiblity for releasing memory.
  13. */
  14. /*---------------------------------------------------------------
  15. * HISTORY
  16. * 7-Dec-2004 Graeme McKerrell
  17. * Updated to use the "lub" prefix
  18. * 6-Feb-2004 Graeme McKerrell
  19. * removed init_fn type definition and parameter, the client had
  20. * more flexiblity in defining their own initialisation operation with
  21. * arguments rather than use a "one-size-fits-all" approach.
  22. * Modified blockpool structure to support FIFO block allocation.
  23. * 23-Jan-2004 Graeme McKerrell
  24. * Initial version
  25. *---------------------------------------------------------------
  26. * Copyright (C) 2004 3Com Corporation. All Rights Reserved.
  27. *--------------------------------------------------------------- */
  28. #ifndef _lub_string_h
  29. #define _lub_string_h
  30. #include <stddef.h>
  31. #include "lub/c_decl.h"
  32. _BEGIN_C_DECL
  33. /**
  34. * This operation duplicates the specified string.
  35. *
  36. * \pre
  37. * - none
  38. *
  39. * \return
  40. * A dynamically allocated string containing the same content as that specified.
  41. *
  42. * \post
  43. * - The client is responsible for calling lub_string_free() with the
  44. * returned string when they are finished using it.
  45. */
  46. char *lub_string_dup(
  47. /**
  48. * The string to duplicate
  49. */
  50. const char *string);
  51. /**
  52. * This operation concatinates the specified text onto an existing string.
  53. *
  54. * \pre
  55. * - 'string_ptr' must contain reference to NULL or to a dynamically
  56. * allocated string.
  57. *
  58. * \post
  59. * - The old string referenced by 'string_ptr' will be automatically released
  60. * - 'string_ptr' will be updated to point to a dynamically allocated string
  61. * containing the concatinated text.
  62. * - If there is insufficient resource to extend the string then it will not
  63. * be extended.
  64. * - The client maintains responsibility for releasing the string reference
  65. * by string_ptr when they are finished using it.
  66. */
  67. void lub_string_cat(
  68. /**
  69. * A pointer to the string to concatinate
  70. */
  71. char **string_ptr,
  72. /**
  73. * The text to be appended
  74. */
  75. const char *text);
  76. /**
  77. * This operation concatinates a specified length of some text onto an
  78. * existing string.
  79. *
  80. * \pre
  81. * - 'string_ptr' must contain reference to NULL or to a dynamically allocated
  82. * string.
  83. *
  84. * \post
  85. * - The old string referenced by 'string_ptr' will be automatically
  86. * released.
  87. * - 'string_ptr' will be updated to point to a dynamically allocated
  88. * string containing the concatinated text.
  89. * - If there is insufficient resource to extend the string then it will not
  90. * be extended.
  91. * - If there length passed in is greater than that of the specified 'text'
  92. * then the length of the 'text' will be assumed.
  93. * - The client maintains responsibility for releasing the string reference
  94. * by string_ptr when they are finished using it.
  95. */
  96. void lub_string_catn(
  97. /**
  98. * A pointer to the string to concatinate
  99. */
  100. char **string_ptr,
  101. /**
  102. * The text to be appended
  103. */
  104. const char *text,
  105. /**
  106. * The length of text to be appended
  107. */
  108. size_t length);
  109. /**
  110. * This operation dupicates a specified length of some text into a
  111. * new string.
  112. *
  113. * \pre
  114. * - none
  115. *
  116. * \return
  117. * A dynamically allocated string containing the same content as that specified.
  118. *
  119. * \post
  120. * - The client is responsible for calling lub_string_free() with the
  121. * returned string when they are finished using it.
  122. */
  123. char *lub_string_dupn(
  124. /**
  125. * The string containing the text to duplicate
  126. */
  127. const char *string,
  128. /**
  129. * The length of text to be duplicated
  130. */
  131. unsigned length);
  132. /**
  133. * This operation returns a pointer to the last (space separated) word in the
  134. * specified string.
  135. *
  136. * \pre
  137. * - none
  138. *
  139. * \return
  140. * A pointer to the last word in the string.
  141. *
  142. * \post
  143. * - none
  144. */
  145. const char *lub_string_suffix(
  146. /**
  147. * The string from which to extract a suffix
  148. */
  149. const char *string);
  150. /**
  151. * This operation compares string cs to string ct in a case insensitive manner.
  152. *
  153. * \pre
  154. * - none
  155. *
  156. * \return
  157. * - < 0 if cs < ct
  158. * - 0 if cs == ct
  159. * - > 0 if cs > ct
  160. *
  161. * \post
  162. * - none
  163. */
  164. int lub_string_nocasecmp(
  165. /**
  166. * The first string for the comparison
  167. */
  168. const char *cs,
  169. /**
  170. * The second string for the comparison
  171. */
  172. const char *ct);
  173. /**
  174. * This operation performs a case insensitive search for a substring within
  175. * another string.
  176. *
  177. * \pre
  178. * - none
  179. *
  180. * \return
  181. * pointer to first occurance of a case insensitive version of the string ct,
  182. * or NULL if not present.
  183. *
  184. * \post
  185. * - none
  186. */
  187. const char *lub_string_nocasestr(
  188. /**
  189. * The string within which to find a substring
  190. */
  191. const char *cs,
  192. /**
  193. * The substring for which to search
  194. */
  195. const char *ct);
  196. /**
  197. * This operation releases the resources associated with a dynamically allocated
  198. * string.
  199. *
  200. * \pre
  201. * - The calling client must have responsibility for the passed string.
  202. *
  203. * \return
  204. * none
  205. *
  206. * \post
  207. * - The string is no longer usable, any references to it must be discarded.
  208. */
  209. void lub_string_free(
  210. /**
  211. * The string to be released
  212. */
  213. char *string);
  214. /*
  215. * These are the escape characters which are used by default when
  216. * expanding variables. These characters will be backslash escaped
  217. * to prevent them from being interpreted in a script.
  218. *
  219. * This is a security feature to prevent users from arbitarily setting
  220. * parameters to contain special sequences.
  221. */
  222. extern const char *lub_string_esc_default;
  223. extern const char *lub_string_esc_regex;
  224. extern const char *lub_string_esc_quoted;
  225. /**
  226. * This operation decode the escaped string.
  227. *
  228. * \pre
  229. * - none
  230. *
  231. * \return
  232. * - The allocated string without escapes.
  233. *
  234. * \post
  235. * - The result string must be freed after using.
  236. */
  237. char *lub_string_decode(const char *string);
  238. char *lub_string_ndecode(const char *string, unsigned int len);
  239. /**
  240. * This operation encode the string using escape.
  241. *
  242. * \pre
  243. * - none
  244. *
  245. * \return
  246. * - The allocated string with escapes.
  247. *
  248. * \post
  249. * - The result string must be freed after using.
  250. */
  251. char *lub_string_encode(const char *string, const char *escape_chars);
  252. char *lub_string_tolower(const char *str);
  253. _END_C_DECL
  254. #endif /* _lub_string_h */
  255. /** @} */