string 5.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236
  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 \- 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. .SH DESCRIPTION
  75. .PP
  76. These routines manipulate extensible strings.
  77. The basic type is
  78. .BR String ,
  79. which points to an array of characters. The string
  80. maintains pointers to the beginning and end of the allocated
  81. array. In addition a finger pointer keeps track of where
  82. parsing will start (for
  83. .IR s_parse )
  84. or new characters will be added (for
  85. .IR s_putc ,
  86. .IR s_append ,
  87. and
  88. .IR s_nappend ).
  89. The structure, and a few useful macros are:
  90. .sp
  91. .EX
  92. typedef struct String {
  93. Lock;
  94. char *base; /* base of String */
  95. char *end; /* end of allocated space+1 */
  96. char *ptr; /* ptr into String */
  97. ...
  98. } String;
  99. #define s_to_c(s) ((s)->base)
  100. #define s_len(s) ((s)->ptr-(s)->base)
  101. #define s_clone(s) s_copy((s)->base)
  102. .EE
  103. .PP
  104. .I S_to_c
  105. is used when code needs a reference to the character array.
  106. Using
  107. .B s->base
  108. directly is frowned upon since it exposes too much of the implementation.
  109. .SS "allocation and freeing
  110. .PP
  111. A string must be allocated before it can be used.
  112. One normally does this using
  113. .IR s_new ,
  114. giving the string an initial allocation of
  115. 128 bytes.
  116. If you know that the string will need to grow much
  117. longer, you can use
  118. .I s_newalloc
  119. instead, specifying the number of bytes in the
  120. initial allocation.
  121. .PP
  122. .I S_free
  123. causes both the string and its character array to be freed.
  124. .PP
  125. .I S_grow
  126. grows a string's allocation by a fixed amount. It is useful if
  127. you are reading directly into a string's character array but should
  128. be avoided if possible.
  129. .PP
  130. .I S_array
  131. is used to create a constant array, that is, one whose contents
  132. won't change. It points directly to the character array
  133. given as an argument. Tread lightly when using this call.
  134. .SS "Filling the string
  135. After its initial allocation, the string points to the beginning
  136. of an allocated array of characters starting with
  137. .SM NUL.
  138. .PP
  139. .I S_putc
  140. writes a character into the string at the
  141. pointer and advances the pointer to point after it.
  142. .PP
  143. .I S_terminate
  144. writes a
  145. .SM NUL
  146. at the pointer but doesn't advance it.
  147. .PP
  148. .I S_restart
  149. resets the pointer to the begining of the string but doesn't change the contents.
  150. .PP
  151. .I S_reset
  152. is equivalent to
  153. .I s_restart
  154. followed by
  155. .IR s_terminate .
  156. .PP
  157. .I S_append
  158. and
  159. .I s_nappend
  160. copy characters into the string at the pointer and
  161. advance the pointer. They also write a
  162. .SM NUL
  163. at
  164. the pointer without advancing the pointer beyond it.
  165. Both routines stop copying on encountering a
  166. .SM NUL.
  167. .I S_memappend
  168. is like
  169. .I s_nappend
  170. but doesn't stop at a
  171. .SM NUL.
  172. .PP
  173. If you know the initial character array to be copied into a string,
  174. you can allocate a string and copy in the bytes using
  175. .IR s_copy .
  176. This is the equivalent of a
  177. .I s_new
  178. followed by an
  179. .IR s_append .
  180. .PP
  181. .I S_parse
  182. copies the next white space terminated token from
  183. .I s1
  184. to
  185. the end of
  186. .IR s2 .
  187. White space is defined as space, tab,
  188. and newline. Both single and double quoted strings are treated as
  189. a single token. The bounding quotes are not copied.
  190. There is no escape mechanism.
  191. .PP
  192. .I S_tolower
  193. converts all
  194. .SM ASCII
  195. characters in the string to lower case.
  196. .SS Multithreading
  197. .PP
  198. .I S_incref
  199. is used by multithreaded programs to avoid having the string memory
  200. released until the last user of the string performs an
  201. .IR s_free .
  202. .I S_unique
  203. returns a unique copy of the string: if the reference count it
  204. 1 it returns the string, otherwise it returns an
  205. .I s_clone
  206. of the string.
  207. .SS "Bio interaction
  208. .PP
  209. .I S_read
  210. reads the requested number of characters through a
  211. .I Biobuf
  212. into a string. The string is grown as necessary.
  213. An eof or error terminates the read.
  214. The number of bytes read is returned.
  215. The string is null terminated.
  216. .PP
  217. .I S_read_line
  218. reads up to and including the next newline and returns
  219. a pointer to the beginning of the bytes read.
  220. An eof or error terminates the read.
  221. The string is null terminated.
  222. .PP
  223. .I S_getline
  224. reads up to the next newline and returns
  225. a pointer to the beginning of the bytes read. Leading
  226. spaces and tabs and the trailing newline are all discarded.
  227. .I S_getline
  228. will recursively read through files included with
  229. .B #include
  230. and discard all other lines beginning with
  231. .BR # .
  232. .SH SOURCE
  233. .B /sys/src/libString
  234. .SH SEE ALSO
  235. .IR bio (2)