string.h 6.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259
  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 *
  47. lub_string_dup(
  48. /**
  49. * The string to duplicate
  50. */
  51. const char *string
  52. );
  53. /**
  54. * This operation concatinates the specified text onto an existing string.
  55. *
  56. * \pre
  57. * - 'string_ptr' must contain reference to NULL or to a dynamically
  58. * allocated string.
  59. *
  60. * \post
  61. * - The old string referenced by 'string_ptr' will be automatically released
  62. * - 'string_ptr' will be updated to point to a dynamically allocated string
  63. * containing the concatinated text.
  64. * - If there is insufficient resource to extend the string then it will not
  65. * be extended.
  66. * - The client maintains responsibility for releasing the string reference
  67. * by string_ptr when they are finished using it.
  68. */
  69. void
  70. lub_string_cat(
  71. /**
  72. * A pointer to the string to concatinate
  73. */
  74. char **string_ptr,
  75. /**
  76. * The text to be appended
  77. */
  78. const char *text
  79. );
  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
  101. 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. /**
  116. * This operation dupicates a specified length of some text into a
  117. * new string.
  118. *
  119. * \pre
  120. * - none
  121. *
  122. * \return
  123. * A dynamically allocated string containing the same content as that specified.
  124. *
  125. * \post
  126. * - The client is responsible for calling lub_string_free() with the
  127. * returned string when they are finished using it.
  128. */
  129. char *
  130. lub_string_dupn(
  131. /**
  132. * The string containing the text to duplicate
  133. */
  134. const char *string,
  135. /**
  136. * The length of text to be duplicated
  137. */
  138. unsigned length
  139. );
  140. /**
  141. * This operation returns a pointer to the last (space separated) word in the
  142. * specified string.
  143. *
  144. * \pre
  145. * - none
  146. *
  147. * \return
  148. * A pointer to the last word in the string.
  149. *
  150. * \post
  151. * - none
  152. */
  153. const char *
  154. lub_string_suffix(
  155. /**
  156. * The string from which to extract a suffix
  157. */
  158. const char *string
  159. );
  160. /**
  161. * This operation compares string cs to string ct in a case insensitive manner.
  162. *
  163. * \pre
  164. * - none
  165. *
  166. * \return
  167. * - < 0 if cs < ct
  168. * - 0 if cs == ct
  169. * - > 0 if cs > ct
  170. *
  171. * \post
  172. * - none
  173. */
  174. int
  175. lub_string_nocasecmp(
  176. /**
  177. * The first string for the comparison
  178. */
  179. const char *cs,
  180. /**
  181. * The second string for the comparison
  182. */
  183. const char *ct
  184. );
  185. /**
  186. * This operation performs a case insensitive search for a substring within
  187. * another string.
  188. *
  189. * \pre
  190. * - none
  191. *
  192. * \return
  193. * pointer to first occurance of a case insensitive version of the string ct,
  194. * or NULL if not present.
  195. *
  196. * \post
  197. * - none
  198. */
  199. const char *
  200. lub_string_nocasestr(
  201. /**
  202. * The string within which to find a substring
  203. */
  204. const char *cs,
  205. /**
  206. * The substring for which to search
  207. */
  208. const char *ct
  209. );
  210. /**
  211. * This operation releases the resources associated with a dynamically allocated
  212. * string.
  213. *
  214. * \pre
  215. * - The calling client must have responsibility for the passed string.
  216. *
  217. * \return
  218. * none
  219. *
  220. * \post
  221. * - The string is no longer usable, any references to it must be discarded.
  222. */
  223. void
  224. lub_string_free(
  225. /**
  226. * The string to be released
  227. */
  228. char *string
  229. );
  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 *
  243. lub_string_decode(const char *string);
  244. _END_C_DECL
  245. #endif /* _lub_string_h */
  246. /** @} */