string.h 6.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276
  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. #include "lub/types.h"
  33. #define UTF8_MASK 0xC0
  34. #define UTF8_11 0xC0 /* First UTF8 byte */
  35. #define UTF8_10 0x80 /* Next UTF8 bytes */
  36. _BEGIN_C_DECL
  37. /**
  38. * This operation duplicates the specified string.
  39. *
  40. * \pre
  41. * - none
  42. *
  43. * \return
  44. * A dynamically allocated string containing the same content as that specified.
  45. *
  46. * \post
  47. * - The client is responsible for calling lub_string_free() with the
  48. * returned string when they are finished using it.
  49. */
  50. char *lub_string_dup(
  51. /**
  52. * The string to duplicate
  53. */
  54. const char *string);
  55. /**
  56. * This operation concatinates the specified text onto an existing string.
  57. *
  58. * \pre
  59. * - 'string_ptr' must contain reference to NULL or to a dynamically
  60. * allocated string.
  61. *
  62. * \post
  63. * - The old string referenced by 'string_ptr' will be automatically released
  64. * - 'string_ptr' will be updated to point to a dynamically allocated string
  65. * containing the concatinated text.
  66. * - If there is insufficient resource to extend the string then it will not
  67. * be extended.
  68. * - The client maintains responsibility for releasing the string reference
  69. * by string_ptr when they are finished using it.
  70. */
  71. void lub_string_cat(
  72. /**
  73. * A pointer to the string to concatinate
  74. */
  75. char **string_ptr,
  76. /**
  77. * The text to be appended
  78. */
  79. const char *text);
  80. /**
  81. * This operation concatinates a specified length of some text onto an
  82. * existing string.
  83. *
  84. * \pre
  85. * - 'string_ptr' must contain reference to NULL or to a dynamically allocated
  86. * string.
  87. *
  88. * \post
  89. * - The old string referenced by 'string_ptr' will be automatically
  90. * released.
  91. * - 'string_ptr' will be updated to point to a dynamically allocated
  92. * string containing the concatinated text.
  93. * - If there is insufficient resource to extend the string then it will not
  94. * be extended.
  95. * - If there length passed in is greater than that of the specified 'text'
  96. * then the length of the 'text' will be assumed.
  97. * - The client maintains responsibility for releasing the string reference
  98. * by string_ptr when they are finished using it.
  99. */
  100. void lub_string_catn(
  101. /**
  102. * A pointer to the string to concatinate
  103. */
  104. char **string_ptr,
  105. /**
  106. * The text to be appended
  107. */
  108. const char *text,
  109. /**
  110. * The length of text to be appended
  111. */
  112. size_t length);
  113. /**
  114. * This operation dupicates a specified length of some text into a
  115. * new string.
  116. *
  117. * \pre
  118. * - none
  119. *
  120. * \return
  121. * A dynamically allocated string containing the same content as that specified.
  122. *
  123. * \post
  124. * - The client is responsible for calling lub_string_free() with the
  125. * returned string when they are finished using it.
  126. */
  127. char *lub_string_dupn(
  128. /**
  129. * The string containing the text to duplicate
  130. */
  131. const char *string,
  132. /**
  133. * The length of text to be duplicated
  134. */
  135. unsigned length);
  136. /**
  137. * This operation returns a pointer to the last (space separated) word in the
  138. * specified string.
  139. *
  140. * \pre
  141. * - none
  142. *
  143. * \return
  144. * A pointer to the last word in the string.
  145. *
  146. * \post
  147. * - none
  148. */
  149. const char *lub_string_suffix(
  150. /**
  151. * The string from which to extract a suffix
  152. */
  153. const char *string);
  154. /**
  155. * This operation compares string cs to string ct in a case insensitive manner.
  156. *
  157. * \pre
  158. * - none
  159. *
  160. * \return
  161. * - < 0 if cs < ct
  162. * - 0 if cs == ct
  163. * - > 0 if cs > ct
  164. *
  165. * \post
  166. * - none
  167. */
  168. int lub_string_nocasecmp(
  169. /**
  170. * The first string for the comparison
  171. */
  172. const char *cs,
  173. /**
  174. * The second string for the comparison
  175. */
  176. const char *ct);
  177. /**
  178. * This operation performs a case insensitive search for a substring within
  179. * another string.
  180. *
  181. * \pre
  182. * - none
  183. *
  184. * \return
  185. * pointer to first occurance of a case insensitive version of the string ct,
  186. * or NULL if not present.
  187. *
  188. * \post
  189. * - none
  190. */
  191. const char *lub_string_nocasestr(
  192. /**
  193. * The string within which to find a substring
  194. */
  195. const char *cs,
  196. /**
  197. * The substring for which to search
  198. */
  199. const char *ct);
  200. /**
  201. * This operation releases the resources associated with a dynamically allocated
  202. * string.
  203. *
  204. * \pre
  205. * - The calling client must have responsibility for the passed string.
  206. *
  207. * \return
  208. * none
  209. *
  210. * \post
  211. * - The string is no longer usable, any references to it must be discarded.
  212. */
  213. void lub_string_free(
  214. /**
  215. * The string to be released
  216. */
  217. char *string);
  218. /*
  219. * These are the escape characters which are used by default when
  220. * expanding variables. These characters will be backslash escaped
  221. * to prevent them from being interpreted in a script.
  222. *
  223. * This is a security feature to prevent users from arbitarily setting
  224. * parameters to contain special sequences.
  225. */
  226. extern const char *lub_string_esc_default;
  227. extern const char *lub_string_esc_regex;
  228. extern const char *lub_string_esc_quoted;
  229. /**
  230. * This operation decode the escaped string.
  231. *
  232. * \pre
  233. * - none
  234. *
  235. * \return
  236. * - The allocated string without escapes.
  237. *
  238. * \post
  239. * - The result string must be freed after using.
  240. */
  241. char *lub_string_decode(const char *string);
  242. char *lub_string_ndecode(const char *string, unsigned int len);
  243. /**
  244. * This operation encode the string using escape.
  245. *
  246. * \pre
  247. * - none
  248. *
  249. * \return
  250. * - The allocated string with escapes.
  251. *
  252. * \post
  253. * - The result string must be freed after using.
  254. */
  255. char *lub_string_encode(const char *string, const char *escape_chars);
  256. char *lub_string_tolower(const char *str);
  257. unsigned int lub_string_equal_part(const char *str1, const char *str2,
  258. bool_t utf8);
  259. _END_C_DECL
  260. #endif /* _lub_string_h */
  261. /** @} */