1Buffer(3)                        OCaml library                       Buffer(3)
2
3
4

NAME

6       Buffer - Extensible string buffers.
7

Module

9       Module   Buffer
10

Documentation

12       Module Buffer
13        : sig end
14
15
16       Extensible string buffers.
17
18       This module implements string buffers that automatically expand as nec‐
19       essary.   It  provides  accumulative  concatenation   of   strings   in
20       quasi-linear  time (instead of quadratic time when strings are concate‐
21       nated pairwise).
22
23
24
25
26
27
28       type t
29
30
31       The abstract type of buffers.
32
33
34
35
36       val create : int -> t
37
38
39       create n returns a fresh buffer, initially empty.  The n  parameter  is
40       the initial size of the internal string that holds the buffer contents.
41       That string is automatically reallocated when more  than  n  characters
42       are  stored  in the buffer, but shrinks back to n characters when reset
43       is called.  For best performance, n should be of the same order of mag‐
44       nitude  as  the  number of characters that are expected to be stored in
45       the buffer (for instance, 80 for a buffer that holds one output  line).
46       Nothing bad will happen if the buffer grows beyond that limit, however.
47       In doubt, take n = 16  for  instance.   If  n  is  not  between  1  and
48       Sys.max_string_length , it will be clipped to that interval.
49
50
51
52
53       val contents : t -> string
54
55       Return a copy of the current contents of the buffer.  The buffer itself
56       is unchanged.
57
58
59
60
61       val sub : t -> int -> int -> string
62
63
64       Buffer.sub b off len returns (a copy of) the substring of  the  current
65       contents  of  the  buffer b starting at offset off of length len bytes.
66       May raise Invalid_argument if out of bounds request. The buffer  itself
67       is unaffected.
68
69
70
71
72       val blit : t -> int -> string -> int -> int -> unit
73
74
75       Buffer.blit  src  srcoff  dst dstoff len copies len characters from the
76       current contents of the buffer src  ,  starting  at  offset  srcoff  to
77       string dst , starting at character dstoff .
78
79       Raise  Invalid_argument if srcoff and len do not designate a valid sub‐
80       string of src , or if dstoff and len do not designate a valid substring
81       of dst .
82
83
84
85
86       val nth : t -> int -> char
87
88       get  the  n-th character of the buffer. Raise Invalid_argument if index
89       out of bounds
90
91
92
93
94       val length : t -> int
95
96       Return the number of characters currently contained in the buffer.
97
98
99
100
101       val clear : t -> unit
102
103       Empty the buffer.
104
105
106
107
108       val reset : t -> unit
109
110       Empty the buffer and deallocate the internal string holding the  buffer
111       contents,  replacing  it  with  the initial internal string of length n
112       that was allocated by Buffer.create n .  For  long-lived  buffers  that
113       may have grown a lot, reset allows faster reclamation of the space used
114       by the buffer.
115
116
117
118
119       val add_char : t -> char -> unit
120
121
122       add_char b c appends the character c at the end of the buffer b .
123
124
125
126
127       val add_string : t -> string -> unit
128
129
130       add_string b s appends the string s at the end of the buffer b .
131
132
133
134
135       val add_substring : t -> string -> int -> int -> unit
136
137
138       add_substring b s ofs len takes  len  characters  from  offset  ofs  in
139       string s and appends them at the end of the buffer b .
140
141
142
143
144       val add_substitute : t -> (string -> string) -> string -> unit
145
146
147       add_substitute  b  f  s  appends the string pattern s at the end of the
148       buffer b with substitution.  The substitution process looks  for  vari‐
149       ables into the pattern and substitutes each variable name by its value,
150       as obtained by applying the mapping f to the variable name. Inside  the
151       string  pattern,  a  variable  name immediately follows a non-escaped $
152       character and is one of the following:
153
154       -a non empty sequence of alphanumeric or _ characters,
155
156       -an arbitrary sequence of characters enclosed by  a  pair  of  matching
157       parentheses  or  curly  brackets.   An  escaped $ character is a $ that
158       immediately follows a backslash character; it then stands for a plain $
159       .  Raise Not_found if the closing character of a parenthesized variable
160       cannot be found.
161
162
163
164
165
166       val add_buffer : t -> t -> unit
167
168
169       add_buffer b1 b2 appends the current contents of buffer b2 at  the  end
170       of buffer b1 .  b2 is not modified.
171
172
173
174
175       val add_channel : t -> Pervasives.in_channel -> int -> unit
176
177
178       add_channel  b ic n reads exactly n character from the input channel ic
179       and stores them at the end of buffer b  .   Raise  End_of_file  if  the
180       channel contains fewer than n characters.
181
182
183
184
185       val output_buffer : Pervasives.out_channel -> t -> unit
186
187
188       output_buffer  oc b writes the current contents of buffer b on the out‐
189       put channel oc .
190
191
192
193
194
195
196OCamldoc                          2010-01-29                         Buffer(3)