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  quasi-
20       linear  time  (instead  of quadratic time when strings are concatenated
21       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 nth : t -> int -> char
73
74       get  the  n-th character of the buffer. Raise Invalid_argument if index
75       out of bounds
76
77
78
79
80       val length : t -> int
81
82       Return the number of characters currently contained in the buffer.
83
84
85
86
87       val clear : t -> unit
88
89       Empty the buffer.
90
91
92
93
94       val reset : t -> unit
95
96       Empty the buffer and deallocate the internal string holding the  buffer
97       contents,  replacing  it  with  the initial internal string of length n
98       that was allocated by Buffer.create n .  For  long-lived  buffers  that
99       may have grown a lot, reset allows faster reclamation of the space used
100       by the buffer.
101
102
103
104
105       val add_char : t -> char -> unit
106
107
108       add_char b c appends the character c at the end of the buffer b .
109
110
111
112
113       val add_string : t -> string -> unit
114
115
116       add_string b s appends the string s at the end of the buffer b .
117
118
119
120
121       val add_substring : t -> string -> int -> int -> unit
122
123
124       add_substring b s ofs len takes  len  characters  from  offset  ofs  in
125       string s and appends them at the end of the buffer b .
126
127
128
129
130       val add_substitute : t -> (string -> string) -> string -> unit
131
132
133       add_substitute  b  f  s  appends the string pattern s at the end of the
134       buffer b with substitution.  The substitution process looks  for  vari‐
135       ables into the pattern and substitutes each variable name by its value,
136       as obtained by applying the mapping f to the variable name. Inside  the
137       string  pattern,  a  variable  name immediately follows a non-escaped $
138       character and is one of the following:
139
140       -a non empty sequence of alphanumeric or _ characters,
141
142       -an arbitrary sequence of characters enclosed by  a  pair  of  matching
143       parentheses  or  curly  brackets.   An  escaped $ character is a $ that
144       immediately follows a backslash character; it then stands for a plain $
145       .  Raise Not_found if the closing character of a parenthesized variable
146       cannot be found.
147
148
149
150
151
152       val add_buffer : t -> t -> unit
153
154
155       add_buffer b1 b2 appends the current contents of buffer b2 at  the  end
156       of buffer b1 .  b2 is not modified.
157
158
159
160
161       val add_channel : t -> Pervasives.in_channel -> int -> unit
162
163
164       add_channel  b ic n reads exactly n character from the input channel ic
165       and stores them at the end of buffer b  .   Raise  End_of_file  if  the
166       channel contains fewer than n characters.
167
168
169
170
171       val output_buffer : Pervasives.out_channel -> t -> unit
172
173
174       output_buffer  oc b writes the current contents of buffer b on the out‐
175       put channel oc .
176
177
178
179
180
181
182OCamldoc                          2007-05-24                         Buffer(3)