anil.recoil.org
My working unpac repository
1(**************************************************************************)
2(* *)
3(* OCaml *)
4(* *)
5(* Pierre Weis and Xavier Leroy, projet Cristal, INRIA Rocquencourt *)
6(* *)
7(* Copyright 1999 Institut National de Recherche en Informatique et *)
8(* en Automatique. *)
9(* *)
10(* All rights reserved. This file is distributed under the terms of *)
11(* the GNU Lesser General Public License version 2.1, with the *)
12(* special exception on linking described in the file LICENSE. *)
13(* *)
14(**************************************************************************)
15
16(** Extensible buffers.
17
18 This module implements buffers that automatically expand
19 as necessary. It provides accumulative concatenation of strings
20 in linear time (instead of quadratic time when strings are
21 concatenated pairwise). For example:
22
23{[
24 let concat_strings ss =
25 let b = Buffer.create 16 in
26 List.iter (Buffer.add_string b) ss;
27 Buffer.contents b
28
29]}
30
31*)
32
33(** {b Unsynchronized accesses} *)
34
35[@@@alert unsynchronized_access
36 "Unsynchronized accesses to buffers are a programming error."
37]
38
39 (**
40 Unsynchronized accesses to a buffer may lead to an invalid buffer state.
41 Thus, concurrent accesses to a buffer must be synchronized (for instance
42 with a {!Mutex.t}).
43*)
44
45type t
46(** The abstract type of buffers. *)
47
48val create : int -> t
49(** [create n] returns a fresh buffer, initially empty.
50 The [n] parameter is the initial size of the internal byte sequence
51 that holds the buffer contents. That byte sequence is automatically
52 reallocated when more than [n] characters are stored in the buffer,
53 but shrinks back to [n] characters when [reset] is called.
54 For best performance, [n] should be of the same order of magnitude
55 as the number of characters that are expected to be stored in
56 the buffer (for instance, 80 for a buffer that holds one output
57 line). Nothing bad will happen if the buffer grows beyond that
58 limit, however. In doubt, take [n = 16] for instance.
59 If [n] is not between 1 and {!Sys.max_string_length}, it will
60 be clipped to that interval. *)
61
62val contents : t -> string
63(** Return a copy of the current contents of the buffer.
64 The buffer itself is unchanged. *)
65
66val to_bytes : t -> bytes
67(** Return a copy of the current contents of the buffer.
68 The buffer itself is unchanged.
69 @since 4.02 *)
70
71val sub : t -> int -> int -> string
72(** [Buffer.sub b off len] returns a copy of [len] bytes from the
73 current contents of the buffer [b], starting at offset [off].
74 @raise Invalid_argument if [off] and [len] do not designate a valid
75 range of [b]. *)
76
77val blit : t -> int -> bytes -> int -> int -> unit
78(** [Buffer.blit src srcoff dst dstoff len] copies [len] characters from
79 the current contents of the buffer [src], starting at offset [srcoff]
80 to [dst], starting at character [dstoff].
81 @raise Invalid_argument if [srcoff] and [len] do not designate a valid
82 range of [src], or if [dstoff] and [len] do not designate a valid
83 range of [dst].
84 @since 3.11.2
85*)
86
87val nth : t -> int -> char
88(** Get the n-th character of the buffer.
89 @raise Invalid_argument if
90 index out of bounds *)
91
92val length : t -> int
93(** Return the number of characters currently contained in the buffer. *)
94
95val clear : t -> unit
96(** Empty the buffer. *)
97
98val reset : t -> unit
99(** Empty the buffer and deallocate the internal byte sequence holding the
100 buffer contents, replacing it with the initial internal byte sequence
101 of length [n] that was allocated by {!Buffer.create} [n].
102 For long-lived buffers that may have grown a lot, [reset] allows
103 faster reclamation of the space used by the buffer. *)
104
105val output_buffer : out_channel -> t -> unit
106(** [output_buffer oc b] writes the current contents of buffer [b]
107 on the output channel [oc]. *)
108
109val truncate : t -> int -> unit
110(** [truncate b len] truncates the length of [b] to [len]
111 Note: the internal byte sequence is not shortened.
112 @raise Invalid_argument if [len < 0] or [len > length b].
113 @since 4.05 *)
114
115(** {1 Appending} *)
116
117(** Note: all [add_*] operations can raise [Failure] if the internal byte
118 sequence of the buffer would need to grow beyond {!Sys.max_string_length}.
119*)
120
121val add_char : t -> char -> unit
122(** [add_char b c] appends the character [c] at the end of buffer [b]. *)
123
124val add_utf_8_uchar : t -> Uchar.t -> unit
125(** [add_utf_8_uchar b u] appends the {{:https://tools.ietf.org/html/rfc3629}
126 UTF-8} encoding of [u] at the end of buffer [b].
127
128 @since 4.06 *)
129
130val add_utf_16le_uchar : t -> Uchar.t -> unit
131(** [add_utf_16le_uchar b u] appends the
132 {{:https://tools.ietf.org/html/rfc2781}UTF-16LE} encoding of [u]
133 at the end of buffer [b].
134
135 @since 4.06 *)
136
137val add_utf_16be_uchar : t -> Uchar.t -> unit
138(** [add_utf_16be_uchar b u] appends the
139 {{:https://tools.ietf.org/html/rfc2781}UTF-16BE} encoding of [u]
140 at the end of buffer [b].
141
142 @since 4.06 *)
143
144val add_string : t -> string -> unit
145(** [add_string b s] appends the string [s] at the end of buffer [b]. *)
146
147val add_bytes : t -> bytes -> unit
148(** [add_bytes b s] appends the byte sequence [s] at the end of buffer [b].
149 @since 4.02 *)
150
151val add_substring : t -> string -> int -> int -> unit
152(** [add_substring b s ofs len] takes [len] characters from offset
153 [ofs] in string [s] and appends them at the end of buffer [b].
154
155 @raise Invalid_argument if [ofs] and [len] do not designate a valid
156 range of [s]. *)
157
158val add_subbytes : t -> bytes -> int -> int -> unit
159(** [add_subbytes b s ofs len] takes [len] characters from offset
160 [ofs] in byte sequence [s] and appends them at the end of buffer [b].
161
162 @raise Invalid_argument if [ofs] and [len] do not designate a valid
163 range of [s].
164
165 @since 4.02 *)
166
167val add_substitute : t -> (string -> string) -> string -> unit
168(** [add_substitute b f s] appends the string pattern [s] at the end
169 of buffer [b] with substitution.
170 The substitution process looks for variable references in
171 the pattern and substitutes each variable reference with its value, as
172 obtained by applying the mapping [f] to the variable name. Inside the
173 string pattern, a variable reference is a non-escaped [$] immediately
174 followed by a variable name, which is one of the following:
175 - a non empty sequence of alphanumeric or [_] characters,
176 - an arbitrary sequence of characters enclosed by a pair of
177 matching parentheses or curly brackets.
178 An escaped [$] character is a [$] that immediately follows a backslash
179 character; the two characters together stand for a plain [$]. *)
180
181val add_buffer : t -> t -> unit
182(** [add_buffer b1 b2] appends the current contents of buffer [b2]
183 at the end of buffer [b1]. [b2] is not modified. *)
184
185val add_channel : t -> in_channel -> int -> unit
186(** [add_channel b ic n] reads at most [n] characters from the
187 input channel [ic] and stores them at the end of buffer [b].
188 @raise End_of_file if the channel contains fewer than [n]
189 characters. In this case, the characters are still added to
190 the buffer, so as to avoid loss of data.
191
192 @raise Invalid_argument if [len < 0] or [len > Sys.max_string_length].
193 *)
194
195(** {1 Buffers and Sequences} *)
196
197val to_seq : t -> char Seq.t
198(** Iterate on the buffer, in increasing order.
199
200 The behavior is not specified if the buffer is modified during iteration.
201 @since 4.07 *)
202
203val to_seqi : t -> (int * char) Seq.t
204(** Iterate on the buffer, in increasing order, yielding indices along chars.
205
206 The behavior is not specified if the buffer is modified during iteration.
207 @since 4.07 *)
208
209val add_seq : t -> char Seq.t -> unit
210(** Add chars to the buffer
211 @since 4.07 *)
212
213val of_seq : char Seq.t -> t
214(** Create a buffer from the generator
215 @since 4.07 *)
216
217(** {1 Binary encoding of integers} *)
218
219(** The functions in this section append binary encodings of integers
220 to buffers.
221
222 Little-endian (resp. big-endian) encoding means that least
223 (resp. most) significant bytes are stored first. Big-endian is
224 also known as network byte order. Native-endian encoding is
225 either little-endian or big-endian depending on {!Sys.big_endian}.
226
227 32-bit and 64-bit integers are represented by the [int32] and
228 [int64] types, which can be interpreted either as signed or
229 unsigned numbers.
230
231 8-bit and 16-bit integers are represented by the [int] type,
232 which has more bits than the binary encoding. Functions that
233 encode these values truncate their inputs to their least
234 significant bytes.
235*)
236
237val add_uint8 : t -> int -> unit
238(** [add_uint8 b i] appends a binary unsigned 8-bit integer [i] to
239 [b].
240 @since 4.08
241*)
242
243val add_int8 : t -> int -> unit
244(** [add_int8 b i] appends a binary signed 8-bit integer [i] to
245 [b].
246 @since 4.08
247*)
248
249val add_uint16_ne : t -> int -> unit
250(** [add_uint16_ne b i] appends a binary native-endian unsigned 16-bit
251 integer [i] to [b].
252 @since 4.08
253*)
254
255val add_uint16_be : t -> int -> unit
256(** [add_uint16_be b i] appends a binary big-endian unsigned 16-bit
257 integer [i] to [b].
258 @since 4.08
259*)
260
261val add_uint16_le : t -> int -> unit
262(** [add_uint16_le b i] appends a binary little-endian unsigned 16-bit
263 integer [i] to [b].
264 @since 4.08
265*)
266
267val add_int16_ne : t -> int -> unit
268(** [add_int16_ne b i] appends a binary native-endian signed 16-bit
269 integer [i] to [b].
270 @since 4.08
271*)
272
273val add_int16_be : t -> int -> unit
274(** [add_int16_be b i] appends a binary big-endian signed 16-bit
275 integer [i] to [b].
276 @since 4.08
277*)
278
279val add_int16_le : t -> int -> unit
280(** [add_int16_le b i] appends a binary little-endian signed 16-bit
281 integer [i] to [b].
282 @since 4.08
283*)
284
285val add_int32_ne : t -> int32 -> unit
286(** [add_int32_ne b i] appends a binary native-endian 32-bit integer
287 [i] to [b].
288 @since 4.08
289*)
290
291val add_int32_be : t -> int32 -> unit
292(** [add_int32_be b i] appends a binary big-endian 32-bit integer
293 [i] to [b].
294 @since 4.08
295*)
296
297val add_int32_le : t -> int32 -> unit
298(** [add_int32_le b i] appends a binary little-endian 32-bit integer
299 [i] to [b].
300 @since 4.08
301*)
302
303val add_int64_ne : t -> int64 -> unit
304(** [add_int64_ne b i] appends a binary native-endian 64-bit integer
305 [i] to [b].
306 @since 4.08
307*)
308
309val add_int64_be : t -> int64 -> unit
310(** [add_int64_be b i] appends a binary big-endian 64-bit integer
311 [i] to [b].
312 @since 4.08
313*)
314
315val add_int64_le : t -> int64 -> unit
316(** [add_int64_ne b i] appends a binary little-endian 64-bit integer
317 [i] to [b].
318 @since 4.08
319*)