1
0

string 5.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275
  1. .TH STRING 2
  2. .SH NAME
  3. s_alloc, s_append, s_array, s_copy, s_error, s_free, s_incref, s_memappend, s_nappend, s_new, s_newalloc, s_parse, s_reset, s_restart, s_terminate, s_tolower, s_putc, s_unique, s_grow, s_read, s_read_line, s_getline, s_allocinstack, s_freeinstack, s_rdinstack \- extensible strings
  4. .SH SYNOPSIS
  5. .B #include <u.h>
  6. .br
  7. .B #include <libc.h>
  8. .br
  9. .B #include <String.h>
  10. .PP
  11. .B
  12. String* s_new(void)
  13. .br
  14. .B
  15. void s_free(String *s)
  16. .br
  17. .B
  18. String* s_newalloc(int n)
  19. .br
  20. .B
  21. String* s_array(char *p, int n)
  22. .br
  23. .B
  24. String* s_grow(String *s, int n)
  25. .PP
  26. .B
  27. void s_putc(String *s, int c)
  28. .br
  29. .B
  30. void s_terminate(String *s)
  31. .br
  32. .B
  33. String* s_reset(String *s)
  34. .br
  35. .B
  36. String* s_restart(String *s)
  37. .br
  38. .B
  39. String* s_append(String *s, char *p)
  40. .br
  41. .B
  42. String* s_nappend(String *s, char *p, int n)
  43. .br
  44. .B
  45. String* s_memappend(String *s, char *p, int n)
  46. .br
  47. .B
  48. String* s_copy(char *p)
  49. .br
  50. .B
  51. String* s_parse(String *s1, String *s2)
  52. .br
  53. .PP
  54. .B
  55. void s_tolower(String *s)
  56. .PP
  57. .B
  58. String* s_incref(String *s)
  59. .br
  60. .B
  61. String* s_unique(String *s)
  62. .PP
  63. .B
  64. #include <bio.h>
  65. .PP
  66. .B
  67. int s_read(Biobuf *b, String *s, int n)
  68. .br
  69. .B
  70. char* s_read_line(Biobuf *b, String *s)
  71. .br
  72. .B
  73. char* s_getline(Biobuf *b, String *s)
  74. .br
  75. .B
  76. Sinstack* s_allocinstack(char *file)
  77. .br
  78. .B
  79. void s_freeinstack(Sinstack *stack)
  80. .br
  81. .B
  82. char* s_rdinstack(Sinstack *stack, String *to)
  83. .SH DESCRIPTION
  84. .PP
  85. These routines manipulate extensible strings.
  86. The basic type is
  87. .BR String ,
  88. which points to an array of characters. The string
  89. maintains pointers to the beginning and end of the allocated
  90. array. In addition a finger pointer keeps track of where
  91. parsing will start (for
  92. .IR s_parse )
  93. or new characters will be added (for
  94. .IR s_putc ,
  95. .IR s_append ,
  96. and
  97. .IR s_nappend ).
  98. The structure, and a few useful macros are:
  99. .sp
  100. .EX
  101. typedef struct String {
  102. Lock;
  103. char *base; /* base of String */
  104. char *end; /* end of allocated space+1 */
  105. char *ptr; /* ptr into String */
  106. ...
  107. } String;
  108. #define s_to_c(s) ((s)->base)
  109. #define s_len(s) ((s)->ptr-(s)->base)
  110. #define s_clone(s) s_copy((s)->base)
  111. .EE
  112. .PP
  113. .I S_to_c
  114. is used when code needs a reference to the character array.
  115. Using
  116. .B s->base
  117. directly is frowned upon since it exposes too much of the implementation.
  118. .SS "allocation and freeing
  119. .PP
  120. A string must be allocated before it can be used.
  121. One normally does this using
  122. .IR s_new ,
  123. giving the string an initial allocation of
  124. 128 bytes.
  125. If you know that the string will need to grow much
  126. longer, you can use
  127. .I s_newalloc
  128. instead, specifying the number of bytes in the
  129. initial allocation.
  130. .PP
  131. .I S_free
  132. causes both the string and its character array to be freed.
  133. .PP
  134. .I S_grow
  135. grows a string's allocation by a fixed amount. It is useful if
  136. you are reading directly into a string's character array but should
  137. be avoided if possible.
  138. .PP
  139. .I S_array
  140. is used to create a constant array, that is, one whose contents
  141. won't change. It points directly to the character array
  142. given as an argument. Tread lightly when using this call.
  143. .SS "Filling the string
  144. After its initial allocation, the string points to the beginning
  145. of an allocated array of characters starting with
  146. .SM NUL.
  147. .PP
  148. .I S_putc
  149. writes a character into the string at the
  150. pointer and advances the pointer to point after it.
  151. .PP
  152. .I S_terminate
  153. writes a
  154. .SM NUL
  155. at the pointer but doesn't advance it.
  156. .PP
  157. .I S_restart
  158. resets the pointer to the begining of the string but doesn't change the contents.
  159. .PP
  160. .I S_reset
  161. is equivalent to
  162. .I s_restart
  163. followed by
  164. .IR s_terminate .
  165. .PP
  166. .I S_append
  167. and
  168. .I s_nappend
  169. copy characters into the string at the pointer and
  170. advance the pointer. They also write a
  171. .SM NUL
  172. at
  173. the pointer without advancing the pointer beyond it.
  174. Both routines stop copying on encountering a
  175. .SM NUL.
  176. .I S_memappend
  177. is like
  178. .I s_nappend
  179. but doesn't stop at a
  180. .SM NUL.
  181. .PP
  182. If you know the initial character array to be copied into a string,
  183. you can allocate a string and copy in the bytes using
  184. .IR s_copy .
  185. This is the equivalent of a
  186. .I s_new
  187. followed by an
  188. .IR s_append .
  189. .PP
  190. .I S_parse
  191. copies the next white space terminated token from
  192. .I s1
  193. to
  194. the end of
  195. .IR s2 .
  196. White space is defined as space, tab,
  197. and newline. Both single and double quoted strings are treated as
  198. a single token. The bounding quotes are not copied.
  199. There is no escape mechanism.
  200. .PP
  201. .I S_tolower
  202. converts all
  203. .SM ASCII
  204. characters in the string to lower case.
  205. .SS Multithreading
  206. .PP
  207. .I S_incref
  208. is used by multithreaded programs to avoid having the string memory
  209. released until the last user of the string performs an
  210. .IR s_free .
  211. .I S_unique
  212. returns a unique copy of the string: if the reference count it
  213. 1 it returns the string, otherwise it returns an
  214. .I s_clone
  215. of the string.
  216. .SS "Bio interaction
  217. .PP
  218. .I S_read
  219. reads the requested number of characters through a
  220. .I Biobuf
  221. into a string. The string is grown as necessary.
  222. An eof or error terminates the read.
  223. The number of bytes read is returned.
  224. The string is
  225. .SM ASCII
  226. .SM NUL
  227. terminated.
  228. .PP
  229. .I S_read_line
  230. reads up to and including the next newline and returns
  231. a pointer to the beginning of the bytes read.
  232. An eof or error terminates the read and returns 0.
  233. The string is
  234. .SM NUL
  235. terminated.
  236. .PP
  237. .I S_getline
  238. reads up to the next newline and returns
  239. a pointer to the beginning of the bytes read
  240. (0 on eof or error).
  241. Leading
  242. spaces and tabs and the trailing newline are all discarded.
  243. .I S_getline
  244. will discard all lines beginning with
  245. .LR # .
  246. .PP
  247. .I S_rdinstack
  248. will recursively read through files included with
  249. .L #include
  250. and discard all other lines beginning with
  251. .LR # .
  252. The next line read from a
  253. .I stack
  254. of include files is appended to
  255. .IR to .
  256. .I S_rdinstack
  257. returns a pointer to the beginning of the bytes read.
  258. An eof or error terminates the read and returns 0.
  259. The string is
  260. .SM NUL
  261. terminated.
  262. .I S_allocinstack
  263. opens
  264. .I file
  265. for reading and returns a pointer to a new stack of include files, or
  266. .B nil
  267. on failure.
  268. .I S_freeinstack
  269. frees such a
  270. .IR stack .
  271. .SH SOURCE
  272. .B /sys/src/libString
  273. .SH SEE ALSO
  274. .IR bio (2)