libcm is a C development framework with an emphasis on audio signal processing applications.
您最多选择25个主题 主题必须以字母或数字开头,可以包含连字符 (-),并且长度不得超过35个字符

cmText.h 12KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305
  1. #ifndef cmText_h
  2. #define cmText_h
  3. #ifdef __cplusplus
  4. extern "C" {
  5. #endif
  6. //( { file_desc:"Text processing functions." kw:[text]}
  7. //
  8. // The cmText API supports two basic tasks: the generation of
  9. // formatted text into dynamic arrays and text to number parsing.
  10. //
  11. //)
  12. //(
  13. enum
  14. {
  15. kOkTxRC = 0,
  16. kNullTxRC,
  17. kCvtErrTxRC,
  18. kLHeapFailTxRC,
  19. kBufTooSmallTxRC
  20. };
  21. typedef unsigned cmTxRC_t;
  22. typedef cmHandle_t cmTextSysH_t;
  23. extern cmTextSysH_t cmTextSysNullHandle;
  24. cmTxRC_t cmTextSysInitialize( cmCtx_t* ctx, cmTextSysH_t* hp );
  25. cmTxRC_t cmTextSysFinalize( cmTextSysH_t* hp );
  26. bool cmTextSysIsValid( cmTextSysH_t h );
  27. // Print the string into a static, global, but resizable, buffer.
  28. // This string is only valid until the next call to cmTextSysPrintS().
  29. // This function is not currently thread safe - calls from different
  30. // threads can therefore overwrite one anothers buffered strings
  31. // unexpectedly.
  32. cmChar_t* cmTextSysVPrintfS( cmTextSysH_t h, const cmChar_t* fmt, va_list vl );
  33. cmChar_t* cmTextSysPrintfS( cmTextSysH_t h, const cmChar_t* fmt, ... );
  34. // Print the string into memory supplied by a linked heap.
  35. // Strings returned from this function may be deallocated with a call to
  36. // cmLhFree().
  37. cmChar_t* cmTextSysVPrintfH( cmLHeapH_t h, const cmChar_t* fmt, va_list vl );
  38. cmChar_t* cmTextSysPrintfH( cmLHeapH_t h, const cmChar_t* fmt, ... );
  39. // Print a string and store it in the internal text system heap.
  40. // The memory used by these strings will be automatically released
  41. // whent he text system is destroyed. The caller may optionally release
  42. // a string via cmTextSysFreeStr().
  43. cmChar_t* cmTextSysVPrintf( cmTextSysH_t h, const cmChar_t* fmt, va_list vl );
  44. cmChar_t* cmTextSysPrintf( cmTextSysH_t h, const cmChar_t* fmt, ... );
  45. void cmTextSysFreeStr( cmTextSysH_t h, const cmChar_t* s );
  46. // Return true if 's' is stored in the text systems internal heap,
  47. bool cmTextSysIsStored(cmTextSysH_t h, const cmChar_t* s );
  48. //
  49. // Global interface:
  50. //
  51. // These functions are equivalent to the same-named functions above
  52. // but use a globally allocated cmTextSysH_t handle.
  53. cmTxRC_t cmTsInitialize( cmCtx_t* ctx );
  54. cmTxRC_t cmTsFinalize();
  55. bool cmTsIsValid();
  56. cmChar_t* cmTsVPrintfS( const cmChar_t* fmt, va_list vl );
  57. cmChar_t* cmTsPrintfS( const cmChar_t* fmt, ... );
  58. cmChar_t* cmTsVPrintfH( cmLHeapH_t h, const cmChar_t* fmt, va_list vl );
  59. cmChar_t* cmTsPrintfH( cmLHeapH_t h, const cmChar_t* fmt, ... );
  60. cmChar_t* cmTsVPrintf( const cmChar_t* fmt, va_list vl );
  61. cmChar_t* cmTsPrintf( const cmChar_t* fmt, ... );
  62. void cmTsFreeStr( const cmChar_t* s );
  63. bool cmTsIsStored(const cmChar_t* s );
  64. // Print a formatted string into s[]. s[] is reallocated as necessary to
  65. // hold the string. s must be freed by the caller via cmMemFree().
  66. cmChar_t* cmTsVPrintfP( cmChar_t* s, const cmChar_t* fmt, va_list vl );
  67. cmChar_t* cmTsPrintfP( cmChar_t* s, const cmChar_t* fmt, ... );
  68. // Set err to NULL to ignore errors.
  69. //
  70. cmTxRC_t cmTextToInt( const char* text, int* ip, cmErr_t* err );
  71. cmTxRC_t cmTextToUInt( const char* text, unsigned* up, cmErr_t* err );
  72. cmTxRC_t cmTextToFloat( const char* text, float* fp, cmErr_t* err );
  73. cmTxRC_t cmTextToDouble( const char* text, double* dp, cmErr_t* err );
  74. cmTxRC_t cmTextToBool( const char* text, bool* bp, cmErr_t* err );
  75. // In all cases s, s0 and s1 are expected to be non-NULL.
  76. // If any of the arguments were allowed to be NULL, then the natural
  77. // return value would be NULL and this would lead to ambiguities
  78. // with the meaning of a NULL return value.
  79. // Return ptr to next non-white or terminating 0 if EOS is encountered.
  80. cmChar_t* cmTextNextNonWhiteOrEos( cmChar_t* s );
  81. const cmChar_t* cmTextNextNonWhiteOrEosC( const cmChar_t* s );
  82. // Return ptr to next non-white char. or NULL if EOS is encountered.
  83. cmChar_t* cmTextNextNonWhite( cmChar_t* s );
  84. const cmChar_t* cmTextNextNonWhiteC( const cmChar_t* s );
  85. // Return ptr to prev non-white or s if BOS is encountered.
  86. // If returned ptr == s0 then BOS was encountered.
  87. cmChar_t* cmTextPrevNonWhiteOrBos( cmChar_t* s0, const cmChar_t* s1 );
  88. const cmChar_t* cmTextPrevNonWhiteOrBosC( const cmChar_t* s0, const cmChar_t* s1 );
  89. // Return ptr to prev non-white char. or NULL if BOS is encountered.
  90. cmChar_t* cmTextPrevNonWhite( cmChar_t* s0, const cmChar_t* s1 );
  91. const cmChar_t* cmTextPrevNonWhiteC( const cmChar_t* s0, const cmChar_t* s1 );
  92. // Return ptr to next white or terminating 0 if EOS is encountered.
  93. // ( *(return_ptr)==0 if EOS is encountered )
  94. cmChar_t* cmTextNextWhiteOrEos( cmChar_t* s );
  95. const cmChar_t* cmTextNextWhiteOrEosC( const cmChar_t* s );
  96. // Return ptr to next white char. or NULL if EOS is encountered.
  97. cmChar_t* cmTextNextWhite( cmChar_t* s );
  98. const cmChar_t* cmTextNextWhiteC( const cmChar_t* s );
  99. // Return ptr to prev white or s if BOS is encountered.
  100. // If returned ptr != s then *(returned_ptr-1) == '\n'
  101. cmChar_t* cmTextPrevWhiteOrBos( cmChar_t* s0, const cmChar_t* s1 );
  102. const cmChar_t* cmTextPrevWhiteOrBosC( const cmChar_t* s0, const cmChar_t* s1 );
  103. // Return ptr to prev white char. or NULL if BOS is encountered.
  104. cmChar_t* cmTextPrevWhite( cmChar_t* s0, const cmChar_t* s1 );
  105. const cmChar_t* cmTextPrevWhiteC( const cmChar_t* s0, const cmChar_t* s1 );
  106. // Backup to first char on line.
  107. // Return ptr to first char on line or first char in buffer.
  108. // If return_ptr!=s0 then *(return_ptr-1) == '\n'.
  109. cmChar_t* cmTextBegOfLine( cmChar_t* s0, const cmChar_t* s1 );
  110. const cmChar_t* cmTextBegOfLineC( const cmChar_t* s0, const cmChar_t* s1 );
  111. // Move forward to last char on line.
  112. // Return ptr to last char on line.
  113. // If *return_ptr == 0 then the end of buffer was encountered prior
  114. // to the next '\n' otherwise *(return_ptr) == '\n'.
  115. cmChar_t* cmTextEndOfLine( cmChar_t* s );
  116. const cmChar_t* cmTextEndOfLineC( const cmChar_t* s );
  117. // Return a pointer to the last non-white character in the string
  118. // or NULL if s is NULL or empty.
  119. cmChar_t* cmTextLastNonWhiteChar( const cmChar_t* s );
  120. const cmChar_t* cmTextLastNonWhiteCharC( const cmChar_t* s );
  121. // Return a pointer to the last white character in the string
  122. // or NULL if s is NULL or empty.
  123. cmChar_t* cmTextLastWhiteChar( const cmChar_t* s );
  124. const cmChar_t* cmTextLastWhiteCharC( const cmChar_t* s );
  125. // Shrink the text by copying all char's beginning with t+tn to t.
  126. // ex: 'abcd' s=a, t=b, tn=1 -> acd
  127. // 'abcd' s=a, t=b, tn=2 -> ad
  128. void cmTextShrinkS( cmChar_t* s, const cmChar_t* t, unsigned tn );
  129. void cmTextShrinkSN(cmChar_t* s, unsigned sn, const cmChar_t* t, unsigned tn );
  130. // Remove the last n characters from s by inserting a '\0' at s[ strlen(s)-n ].
  131. void cmTextClip( cmChar_t* s, unsigned n );
  132. // Trim white space from the begining/end/both of a string
  133. cmChar_t* cmTextTrimBegin( cmChar_t* s );
  134. cmChar_t* cmTextTrimEnd( cmChar_t* s );
  135. cmChar_t* cmTextTrim( cmChar_t* );
  136. // Expand s by copying all bytes past t to t+tn.
  137. cmChar_t* cmTextExpandS( cmChar_t* s, const cmChar_t* t, unsigned tn );
  138. // Replace t[tn] with u[un] in s[].
  139. cmChar_t* cmTextReplaceSN( cmChar_t* s, const cmChar_t* t, unsigned tn, const cmChar_t* u, unsigned un );
  140. // Replace t[tn] with u in s[].
  141. cmChar_t* cmTextReplaceS( cmChar_t* s, const cmChar_t* t, unsigned tn, const cmChar_t* u );
  142. // Replace all occurrences of t[] with u[] in s[].
  143. cmChar_t* cmTextReplaceAll( cmChar_t* s, const cmChar_t* t, const cmChar_t* u );
  144. // Replace the first occurence of t[] in s[] with u[].
  145. cmChar_t* cmTextReplaceFirst( cmChar_t* s, const cmChar_t* t, const cmChar_t* u );
  146. // Insert u[un] at before t in s[].
  147. cmChar_t* cmTextInsertSN( cmChar_t* s, const cmChar_t* t, const cmChar_t* u, unsigned un );
  148. // Insert u[] at before t in s[].
  149. cmChar_t* cmTextInsertS( cmChar_t* s, const cmChar_t* t, const cmChar_t* u );
  150. cmChar_t* cmTextAppend( cmChar_t* s, unsigned* sn, const cmChar_t* u, unsigned un );
  151. cmChar_t* cmTextAppendSN( cmChar_t* s, const cmChar_t* u, unsigned un );
  152. // append u[un] to s[] and append terminating zero.
  153. cmChar_t* cmTextAppendSNZ( cmChar_t* s, const cmChar_t* u, unsigned un );
  154. // both s[] and u[] are strz's
  155. cmChar_t* cmTextAppendSS( cmChar_t* s, const cmChar_t* u );
  156. // Same as multiple calls to cmTextAppendSS().
  157. // Terminate the var-args list with NULL.
  158. cmChar_t* cmTextVAppendSS( cmChar_t* s, ... );
  159. // Append 'n' copies of 'c' to the end of s[].
  160. cmChar_t* cmTextAppendChar( cmChar_t* s, cmChar_t c, unsigned n );
  161. // Returns true if the string is NULL or all spaces.
  162. bool cmTextIsEmpty( const cmChar_t* s );
  163. bool cmTextIsNotEmpty( const cmChar_t* s );
  164. // Same as strlen() but handles case where s0 == NULL as length==0.
  165. unsigned cmTextLength( const cmChar_t* s0 );
  166. // Same as strcmp() but handles NULL. Note that if both s0 and s1 are NULL
  167. // then return is 0.
  168. int cmTextCmp( const cmChar_t* s0, const cmChar_t* s1 );
  169. // Same as cmTextCmp() but only compare the first 'n' characters.
  170. int cmTextCmpN( const cmChar_t* s0, const cmChar_t* s1, unsigned n );
  171. // Convert text in s0[] to upper/lower case in s1[].
  172. // Note that s0[] and s1[] may point to the same string
  173. void cmTextToLower( const cmChar_t* s0, cmChar_t* s1 );
  174. void cmTextToUpper( const cmChar_t* s0, cmChar_t* s1 );
  175. // Returns NULL if string contains fewer than lineIdx lines.
  176. // Note: first line == 1.
  177. cmChar_t* cmTextLine( cmChar_t* s, unsigned line );
  178. const cmChar_t* cmTextLineC( const cmChar_t* s, unsigned line );
  179. // Reduce all consecutive white spaces to a single space.
  180. cmChar_t* cmTextRemoveConsecutiveSpaces( cmChar_t* s );
  181. // Columnize s[] by inserting EOL's at the first available
  182. // space prior 'colCnt' columns. If no space exists then
  183. // the words will be broken. If length s[] is less than
  184. // 'colCnt' then s[] is returned with no changes.
  185. cmChar_t* cmTextColumize( cmChar_t* s, unsigned colCnt );
  186. // Indent the rows of s[] by inserting 'indent' spaces
  187. // just after each '\n'. If s[] contains no '\n' then
  188. // s[] is returned with no changes.
  189. cmChar_t* cmTextIndentRows( cmChar_t* s, unsigned indent );
  190. // Prefix all rows of s[] with p[].
  191. cmChar_t* cmTextPrefixRows( cmChar_t* s, const cmChar_t* t );
  192. // Remove leading white space from all rows of s.
  193. cmChar_t* cmTextTrimRows( cmChar_t* s );
  194. // Remove all white space prior to the first non-white space
  195. // character.
  196. cmChar_t* cmTextEatLeadingSpace( cmChar_t* s );
  197. // Return a pointer to the beginning of the next row
  198. // or NULL if there is no next row.
  199. cmChar_t* cmTextNextRow( cmChar_t* s );
  200. const cmChar_t* cmTextNextRowC( const cmChar_t* s );
  201. // Return the minimum indent of all rows in s[].
  202. unsigned cmTextMinIndent( const cmChar_t* s );
  203. // Outdent s[] by 'n'.
  204. // If a row is indented by less than 'n' then it is
  205. // then all leading white space is removed.
  206. cmChar_t* cmTextOutdent( cmChar_t* s, unsigned n );
  207. // Given a string containing binary data encoded as base64
  208. // return the size of the buffer required to hold the
  209. // decoded binary data. Note that if xV[] is a legal base64
  210. // string then xN must be a multiple of 4. If xN is not
  211. // a mulitple of 4 then the function returns kInvalidCnt.
  212. unsigned cmTextDecodeBase64BufferByteCount( const char* xV, unsigned xN );
  213. // Decode the base64 data in xV[xN] into yV[yN]. Note that the
  214. // minimum value of yN can be determined via
  215. // cmTextDecodeBase64BufferByteCount().
  216. // Return the actual count of bytes decoded into yV[].
  217. unsigned cmTextDecodeBase64( const char* xV, unsigned xN, void* yV, unsigned yN );
  218. // Given the count of bytes in a binary array, return
  219. // the count of bytes required to store the array in base64.
  220. unsigned cmTextEncodeBase64BufferByteCount( unsigned xN );
  221. // Encode the binary array xV[xN] into yV[yN]. Note that the value
  222. // of yN can be determined via cmTextEncodeBase64BufferByteCount().
  223. cmTxRC_t cmTextEncodeBase64( const void* xV, unsigned xN, char* yV, unsigned yN );
  224. //)
  225. #ifdef __cplusplus
  226. }
  227. #endif
  228. #endif