/vendor/gc/include/cord.h

http://github.com/feyeleanor/RubyGoLightly · C++ Header · 327 lines · 56 code · 50 blank · 221 comment · 2 complexity · 49d0db4f59bb4874db24c5942ed8c2ee MD5 · raw file

  1. /*
  2. * Copyright (c) 1993-1994 by Xerox Corporation. All rights reserved.
  3. *
  4. * THIS MATERIAL IS PROVIDED AS IS, WITH ABSOLUTELY NO WARRANTY EXPRESSED
  5. * OR IMPLIED. ANY USE IS AT YOUR OWN RISK.
  6. *
  7. * Permission is hereby granted to use or copy this program
  8. * for any purpose, provided the above notices are retained on all copies.
  9. * Permission to modify the code and to distribute modified code is granted,
  10. * provided the above notices are retained, and a notice that the code was
  11. * modified is included with the above copyright notice.
  12. *
  13. * Author: Hans-J. Boehm (boehm@parc.xerox.com)
  14. */
  15. /* Boehm, October 5, 1995 4:20 pm PDT */
  16. /*
  17. * Cords are immutable character strings. A number of operations
  18. * on long cords are much more efficient than their strings.h counterpart.
  19. * In particular, concatenation takes constant time independent of the length
  20. * of the arguments. (Cords are represented as trees, with internal
  21. * nodes representing concatenation and leaves consisting of either C
  22. * strings or a functional description of the string.)
  23. *
  24. * The following are reasonable applications of cords. They would perform
  25. * unacceptably if C strings were used:
  26. * - A compiler that produces assembly language output by repeatedly
  27. * concatenating instructions onto a cord representing the output file.
  28. * - A text editor that converts the input file to a cord, and then
  29. * performs editing operations by producing a new cord representing
  30. * the file after echa character change (and keeping the old ones in an
  31. * edit history)
  32. *
  33. * For optimal performance, cords should be built by
  34. * concatenating short sections.
  35. * This interface is designed for maximum compatibility with C strings.
  36. * ASCII NUL characters may be embedded in cords using CORD_from_fn.
  37. * This is handled correctly, but CORD_to_char_star will produce a string
  38. * with embedded NULs when given such a cord.
  39. *
  40. * This interface is fairly big, largely for performance reasons.
  41. * The most basic constants and functions:
  42. *
  43. * CORD - the type of a cord;
  44. * CORD_EMPTY - empty cord;
  45. * CORD_len(cord) - length of a cord;
  46. * CORD_cat(cord1,cord2) - concatenation of two cords;
  47. * CORD_substr(cord, start, len) - substring (or subcord);
  48. * CORD_pos i; CORD_FOR(i, cord) { ... CORD_pos_fetch(i) ... } -
  49. * examine each character in a cord. CORD_pos_fetch(i) is the char.
  50. * CORD_fetch(int i) - Retrieve i'th character (slowly).
  51. * CORD_cmp(cord1, cord2) - compare two cords.
  52. * CORD_from_file(FILE * f) - turn a read-only file into a cord.
  53. * CORD_to_char_star(cord) - convert to C string.
  54. * (Non-NULL C constant strings are cords.)
  55. * CORD_printf (etc.) - cord version of printf. Use %r for cords.
  56. */
  57. # ifndef CORD_H
  58. # define CORD_H
  59. # include <stddef.h>
  60. # include <stdio.h>
  61. /* Cords have type const char *. This is cheating quite a bit, and not */
  62. /* 100% portable. But it means that nonempty character string */
  63. /* constants may be used as cords directly, provided the string is */
  64. /* never modified in place. The empty cord is represented by, and */
  65. /* can be written as, 0. */
  66. typedef const char * CORD;
  67. /* An empty cord is always represented as nil */
  68. # define CORD_EMPTY 0
  69. /* Is a nonempty cord represented as a C string? */
  70. #define CORD_IS_STRING(s) (*(s) != '\0')
  71. /* Concatenate two cords. If the arguments are C strings, they may */
  72. /* not be subsequently altered. */
  73. CORD CORD_cat(CORD x, CORD y);
  74. /* Concatenate a cord and a C string with known length. Except for the */
  75. /* empty string case, this is a special case of CORD_cat. Since the */
  76. /* length is known, it can be faster. */
  77. /* The string y is shared with the resulting CORD. Hence it should */
  78. /* not be altered by the caller. */
  79. CORD CORD_cat_char_star(CORD x, const char * y, size_t leny);
  80. /* Compute the length of a cord */
  81. size_t CORD_len(CORD x);
  82. /* Cords may be represented by functions defining the ith character */
  83. typedef char (* CORD_fn)(size_t i, void * client_data);
  84. /* Turn a functional description into a cord. */
  85. CORD CORD_from_fn(CORD_fn fn, void * client_data, size_t len);
  86. /* Return the substring (subcord really) of x with length at most n, */
  87. /* starting at position i. (The initial character has position 0.) */
  88. CORD CORD_substr(CORD x, size_t i, size_t n);
  89. /* Return the argument, but rebalanced to allow more efficient */
  90. /* character retrieval, substring operations, and comparisons. */
  91. /* This is useful only for cords that were built using repeated */
  92. /* concatenation. Guarantees log time access to the result, unless */
  93. /* x was obtained through a large number of repeated substring ops */
  94. /* or the embedded functional descriptions take longer to evaluate. */
  95. /* May reallocate significant parts of the cord. The argument is not */
  96. /* modified; only the result is balanced. */
  97. CORD CORD_balance(CORD x);
  98. /* The following traverse a cord by applying a function to each */
  99. /* character. This is occasionally appropriate, especially where */
  100. /* speed is crucial. But, since C doesn't have nested functions, */
  101. /* clients of this sort of traversal are clumsy to write. Consider */
  102. /* the functions that operate on cord positions instead. */
  103. /* Function to iteratively apply to individual characters in cord. */
  104. typedef int (* CORD_iter_fn)(char c, void * client_data);
  105. /* Function to apply to substrings of a cord. Each substring is a */
  106. /* a C character string, not a general cord. */
  107. typedef int (* CORD_batched_iter_fn)(const char * s, void * client_data);
  108. # define CORD_NO_FN ((CORD_batched_iter_fn)0)
  109. /* Apply f1 to each character in the cord, in ascending order, */
  110. /* starting at position i. If */
  111. /* f2 is not CORD_NO_FN, then multiple calls to f1 may be replaced by */
  112. /* a single call to f2. The parameter f2 is provided only to allow */
  113. /* some optimization by the client. This terminates when the right */
  114. /* end of this string is reached, or when f1 or f2 return != 0. In the */
  115. /* latter case CORD_iter returns != 0. Otherwise it returns 0. */
  116. /* The specified value of i must be < CORD_len(x). */
  117. int CORD_iter5(CORD x, size_t i, CORD_iter_fn f1,
  118. CORD_batched_iter_fn f2, void * client_data);
  119. /* A simpler version that starts at 0, and without f2: */
  120. int CORD_iter(CORD x, CORD_iter_fn f1, void * client_data);
  121. # define CORD_iter(x, f1, cd) CORD_iter5(x, 0, f1, CORD_NO_FN, cd)
  122. /* Similar to CORD_iter5, but end-to-beginning. No provisions for */
  123. /* CORD_batched_iter_fn. */
  124. int CORD_riter4(CORD x, size_t i, CORD_iter_fn f1, void * client_data);
  125. /* A simpler version that starts at the end: */
  126. int CORD_riter(CORD x, CORD_iter_fn f1, void * client_data);
  127. /* Functions that operate on cord positions. The easy way to traverse */
  128. /* cords. A cord position is logically a pair consisting of a cord */
  129. /* and an index into that cord. But it is much faster to retrieve a */
  130. /* charcter based on a position than on an index. Unfortunately, */
  131. /* positions are big (order of a few 100 bytes), so allocate them with */
  132. /* caution. */
  133. /* Things in cord_pos.h should be treated as opaque, except as */
  134. /* described below. Also note that */
  135. /* CORD_pos_fetch, CORD_next and CORD_prev have both macro and function */
  136. /* definitions. The former may evaluate their argument more than once. */
  137. # include "private/cord_pos.h"
  138. /*
  139. Visible definitions from above:
  140. typedef <OPAQUE but fairly big> CORD_pos[1];
  141. * Extract the cord from a position:
  142. CORD CORD_pos_to_cord(CORD_pos p);
  143. * Extract the current index from a position:
  144. size_t CORD_pos_to_index(CORD_pos p);
  145. * Fetch the character located at the given position:
  146. char CORD_pos_fetch(CORD_pos p);
  147. * Initialize the position to refer to the given cord and index.
  148. * Note that this is the most expensive function on positions:
  149. void CORD_set_pos(CORD_pos p, CORD x, size_t i);
  150. * Advance the position to the next character.
  151. * P must be initialized and valid.
  152. * Invalidates p if past end:
  153. void CORD_next(CORD_pos p);
  154. * Move the position to the preceding character.
  155. * P must be initialized and valid.
  156. * Invalidates p if past beginning:
  157. void CORD_prev(CORD_pos p);
  158. * Is the position valid, i.e. inside the cord?
  159. int CORD_pos_valid(CORD_pos p);
  160. */
  161. # define CORD_FOR(pos, cord) \
  162. for (CORD_set_pos(pos, cord, 0); CORD_pos_valid(pos); CORD_next(pos))
  163. /* An out of memory handler to call. May be supplied by client. */
  164. /* Must not return. */
  165. extern void (* CORD_oom_fn)(void);
  166. /* Dump the representation of x to stdout in an implementation defined */
  167. /* manner. Intended for debugging only. */
  168. void CORD_dump(CORD x);
  169. /* The following could easily be implemented by the client. They are */
  170. /* provided in cordxtra.c for convenience. */
  171. /* Concatenate a character to the end of a cord. */
  172. CORD CORD_cat_char(CORD x, char c);
  173. /* Concatenate n cords. */
  174. CORD CORD_catn(int n, /* CORD */ ...);
  175. /* Return the character in CORD_substr(x, i, 1) */
  176. char CORD_fetch(CORD x, size_t i);
  177. /* Return < 0, 0, or > 0, depending on whether x < y, x = y, x > y */
  178. int CORD_cmp(CORD x, CORD y);
  179. /* A generalization that takes both starting positions for the */
  180. /* comparison, and a limit on the number of characters to be compared. */
  181. int CORD_ncmp(CORD x, size_t x_start, CORD y, size_t y_start, size_t len);
  182. /* Find the first occurrence of s in x at position start or later. */
  183. /* Return the position of the first character of s in x, or */
  184. /* CORD_NOT_FOUND if there is none. */
  185. size_t CORD_str(CORD x, size_t start, CORD s);
  186. /* Return a cord consisting of i copies of (possibly NUL) c. Dangerous */
  187. /* in conjunction with CORD_to_char_star. */
  188. /* The resulting representation takes constant space, independent of i. */
  189. CORD CORD_chars(char c, size_t i);
  190. # define CORD_nul(i) CORD_chars('\0', (i))
  191. /* Turn a file into cord. The file must be seekable. Its contents */
  192. /* must remain constant. The file may be accessed as an immediate */
  193. /* result of this call and/or as a result of subsequent accesses to */
  194. /* the cord. Short files are likely to be immediately read, but */
  195. /* long files are likely to be read on demand, possibly relying on */
  196. /* stdio for buffering. */
  197. /* We must have exclusive access to the descriptor f, i.e. we may */
  198. /* read it at any time, and expect the file pointer to be */
  199. /* where we left it. Normally this should be invoked as */
  200. /* CORD_from_file(fopen(...)) */
  201. /* CORD_from_file arranges to close the file descriptor when it is no */
  202. /* longer needed (e.g. when the result becomes inaccessible). */
  203. /* The file f must be such that ftell reflects the actual character */
  204. /* position in the file, i.e. the number of characters that can be */
  205. /* or were read with fread. On UNIX systems this is always true. On */
  206. /* MS Windows systems, f must be opened in binary mode. */
  207. CORD CORD_from_file(FILE * f);
  208. /* Equivalent to the above, except that the entire file will be read */
  209. /* and the file pointer will be closed immediately. */
  210. /* The binary mode restriction from above does not apply. */
  211. CORD CORD_from_file_eager(FILE * f);
  212. /* Equivalent to the above, except that the file will be read on demand.*/
  213. /* The binary mode restriction applies. */
  214. CORD CORD_from_file_lazy(FILE * f);
  215. /* Turn a cord into a C string. The result shares no structure with */
  216. /* x, and is thus modifiable. */
  217. char * CORD_to_char_star(CORD x);
  218. /* Turn a C string into a CORD. The C string is copied, and so may */
  219. /* subsequently be modified. */
  220. CORD CORD_from_char_star(const char *s);
  221. /* Identical to the above, but the result may share structure with */
  222. /* the argument and is thus not modifiable. */
  223. const char * CORD_to_const_char_star(CORD x);
  224. /* Write a cord to a file, starting at the current position. No */
  225. /* trailing NULs are newlines are added. */
  226. /* Returns EOF if a write error occurs, 1 otherwise. */
  227. int CORD_put(CORD x, FILE * f);
  228. /* "Not found" result for the following two functions. */
  229. # define CORD_NOT_FOUND ((size_t)(-1))
  230. /* A vague analog of strchr. Returns the position (an integer, not */
  231. /* a pointer) of the first occurrence of (char) c inside x at position */
  232. /* i or later. The value i must be < CORD_len(x). */
  233. size_t CORD_chr(CORD x, size_t i, int c);
  234. /* A vague analog of strrchr. Returns index of the last occurrence */
  235. /* of (char) c inside x at position i or earlier. The value i */
  236. /* must be < CORD_len(x). */
  237. size_t CORD_rchr(CORD x, size_t i, int c);
  238. /* The following are also not primitive, but are implemented in */
  239. /* cordprnt.c. They provide functionality similar to the ANSI C */
  240. /* functions with corresponding names, but with the following */
  241. /* additions and changes: */
  242. /* 1. A %r conversion specification specifies a CORD argument. Field */
  243. /* width, precision, etc. have the same semantics as for %s. */
  244. /* (Note that %c,%C, and %S were already taken.) */
  245. /* 2. The format string is represented as a CORD. */
  246. /* 3. CORD_sprintf and CORD_vsprintf assign the result through the 1st */ /* argument. Unlike their ANSI C versions, there is no need to guess */
  247. /* the correct buffer size. */
  248. /* 4. Most of the conversions are implement through the native */
  249. /* vsprintf. Hence they are usually no faster, and */
  250. /* idiosyncracies of the native printf are preserved. However, */
  251. /* CORD arguments to CORD_sprintf and CORD_vsprintf are NOT copied; */
  252. /* the result shares the original structure. This may make them */
  253. /* very efficient in some unusual applications. */
  254. /* The format string is copied. */
  255. /* All functions return the number of characters generated or -1 on */
  256. /* error. This complies with the ANSI standard, but is inconsistent */
  257. /* with some older implementations of sprintf. */
  258. /* The implementation of these is probably less portable than the rest */
  259. /* of this package. */
  260. #ifndef CORD_NO_IO
  261. #include <stdarg.h>
  262. int CORD_sprintf(CORD * out, CORD format, ...);
  263. int CORD_vsprintf(CORD * out, CORD format, va_list args);
  264. int CORD_fprintf(FILE * f, CORD format, ...);
  265. int CORD_vfprintf(FILE * f, CORD format, va_list args);
  266. int CORD_printf(CORD format, ...);
  267. int CORD_vprintf(CORD format, va_list args);
  268. #endif /* CORD_NO_IO */
  269. # endif /* CORD_H */