libcm is a C development framework with an emphasis on audio signal processing applications.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

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