string.h 7.1 KB

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