man-pages/man3/Buffer.3o.html
2021-03-31 01:06:50 +01:00

1105 lines
12 KiB
HTML

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML><HEAD><TITLE>Man page of Buffer</TITLE>
</HEAD><BODY>
<H1>Buffer</H1>
Section: OCaml library (3o)<BR>Updated: 2020-01-30<BR><A HREF="#index">Index</A>
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
<A NAME="lbAB">&nbsp;</A>
<H2>NAME</H2>
Buffer - Extensible buffers.
<A NAME="lbAC">&nbsp;</A>
<H2>Module</H2>
Module Buffer
<A NAME="lbAD">&nbsp;</A>
<H2>Documentation</H2>
<P>
Module
<B>Buffer</B>
<BR>&nbsp;:&nbsp;
<B>sig end</B>
<P>
<P>
Extensible buffers.
<P>
This module implements buffers that automatically expand
as necessary. It provides accumulative concatenation of strings
in quasi-linear time (instead of quadratic time when strings are
concatenated pairwise).
<P>
<P>
<P>
<P>
<P>
<I>type t </I>
<P>
<P>
The abstract type of buffers.
<P>
<P>
<P>
<I>val create </I>
:
<B>int -&gt; t</B>
<P>
<P>
<B>create n</B>
returns a fresh buffer, initially empty.
The
<B>n</B>
parameter is the initial size of the internal byte sequence
that holds the buffer contents. That byte sequence is automatically
reallocated when more than
<B>n</B>
characters are stored in the buffer,
but shrinks back to
<B>n</B>
characters when
<B>reset</B>
is called.
For best performance,
<B>n</B>
should be of the same order of magnitude
as the number of characters that are expected to be stored in
the buffer (for instance, 80 for a buffer that holds one output
line). Nothing bad will happen if the buffer grows beyond that
limit, however. In doubt, take
<B>n = 16</B>
for instance.
If
<B>n</B>
is not between 1 and
<B>Sys.max_string_length</B>
, it will
be clipped to that interval.
<P>
<P>
<P>
<I>val contents </I>
:
<B>t -&gt; string</B>
<P>
Return a copy of the current contents of the buffer.
The buffer itself is unchanged.
<P>
<P>
<P>
<I>val to_bytes </I>
:
<B>t -&gt; bytes</B>
<P>
Return a copy of the current contents of the buffer.
The buffer itself is unchanged.
<P>
<P>
<B>Since</B>
4.02
<P>
<P>
<P>
<I>val sub </I>
:
<B>t -&gt; int -&gt; int -&gt; string</B>
<P>
<P>
<B>Buffer.sub b off len</B>
returns a copy of
<B>len</B>
bytes from the
current contents of the buffer
<B>b</B>
, starting at offset
<B>off</B>
.
<P>
Raise
<B>Invalid_argument</B>
if
<B>srcoff</B>
and
<B>len</B>
do not designate a valid
range of
<B>b</B>
.
<P>
<P>
<P>
<I>val blit </I>
:
<B>t -&gt; int -&gt; bytes -&gt; int -&gt; int -&gt; unit</B>
<P>
<P>
<B>Buffer.blit src srcoff dst dstoff len</B>
copies
<B>len</B>
characters from
the current contents of the buffer
<B>src</B>
, starting at offset
<B>srcoff</B>
to
<B>dst</B>
, starting at character
<B>dstoff</B>
.
<P>
Raise
<B>Invalid_argument</B>
if
<B>srcoff</B>
and
<B>len</B>
do not designate a valid
range of
<B>src</B>
, or if
<B>dstoff</B>
and
<B>len</B>
do not designate a valid
range of
<B>dst</B>
.
<P>
<P>
<B>Since</B>
3.11.2
<P>
<P>
<P>
<I>val nth </I>
:
<B>t -&gt; int -&gt; char</B>
<P>
Get the n-th character of the buffer. Raise
<B>Invalid_argument</B>
if
index out of bounds
<P>
<P>
<P>
<I>val length </I>
:
<B>t -&gt; int</B>
<P>
Return the number of characters currently contained in the buffer.
<P>
<P>
<P>
<I>val clear </I>
:
<B>t -&gt; unit</B>
<P>
Empty the buffer.
<P>
<P>
<P>
<I>val reset </I>
:
<B>t -&gt; unit</B>
<P>
Empty the buffer and deallocate the internal byte sequence holding the
buffer contents, replacing it with the initial internal byte sequence
of length
<B>n</B>
that was allocated by
<B>Buffer.create</B>
<B>n</B>
.
For long-lived buffers that may have grown a lot,
<B>reset</B>
allows
faster reclamation of the space used by the buffer.
<P>
<P>
<P>
<I>val add_char </I>
:
<B>t -&gt; char -&gt; unit</B>
<P>
<P>
<B>add_char b c</B>
appends the character
<B>c</B>
at the end of buffer
<B>b</B>
.
<P>
<P>
<P>
<I>val add_utf_8_uchar </I>
:
<B>t -&gt; Uchar.t -&gt; unit</B>
<P>
<P>
<B>add_utf_8_uchar b u</B>
appends the
UTF-8 encoding of
<B>u</B>
at the end of buffer
<B>b</B>
.
<P>
<P>
<B>Since</B>
4.06.0
<P>
<P>
<P>
<I>val add_utf_16le_uchar </I>
:
<B>t -&gt; Uchar.t -&gt; unit</B>
<P>
<P>
<B>add_utf_16le_uchar b u</B>
appends the
UTF-16LE encoding of
<B>u</B>
at the end of buffer
<B>b</B>
.
<P>
<P>
<B>Since</B>
4.06.0
<P>
<P>
<P>
<I>val add_utf_16be_uchar </I>
:
<B>t -&gt; Uchar.t -&gt; unit</B>
<P>
<P>
<B>add_utf_16be_uchar b u</B>
appends the
UTF-16BE encoding of
<B>u</B>
at the end of buffer
<B>b</B>
.
<P>
<P>
<B>Since</B>
4.06.0
<P>
<P>
<P>
<I>val add_string </I>
:
<B>t -&gt; string -&gt; unit</B>
<P>
<P>
<B>add_string b s</B>
appends the string
<B>s</B>
at the end of buffer
<B>b</B>
.
<P>
<P>
<P>
<I>val add_bytes </I>
:
<B>t -&gt; bytes -&gt; unit</B>
<P>
<P>
<B>add_bytes b s</B>
appends the byte sequence
<B>s</B>
at the end of buffer
<B>b</B>
.
<P>
<P>
<B>Since</B>
4.02
<P>
<P>
<P>
<I>val add_substring </I>
:
<B>t -&gt; string -&gt; int -&gt; int -&gt; unit</B>
<P>
<P>
<B>add_substring b s ofs len</B>
takes
<B>len</B>
characters from offset
<B>ofs</B>
in string
<B>s</B>
and appends them at the end of buffer
<B>b</B>
.
<P>
<P>
<P>
<I>val add_subbytes </I>
:
<B>t -&gt; bytes -&gt; int -&gt; int -&gt; unit</B>
<P>
<P>
<B>add_subbytes b s ofs len</B>
takes
<B>len</B>
characters from offset
<B>ofs</B>
in byte sequence
<B>s</B>
and appends them at the end of buffer
<B>b</B>
.
<P>
<P>
<B>Since</B>
4.02
<P>
<P>
<P>
<I>val add_substitute </I>
:
<B>t -&gt; (string -&gt; string) -&gt; string -&gt; unit</B>
<P>
<P>
<B>add_substitute b f s</B>
appends the string pattern
<B>s</B>
at the end
of buffer
<B>b</B>
with substitution.
The substitution process looks for variables into
the pattern and substitutes each variable name by its value, as
obtained by applying the mapping
<B>f</B>
to the variable name. Inside the
string pattern, a variable name immediately follows a non-escaped
<B>$</B>
character and is one of the following:
<P>
-a non empty sequence of alphanumeric or
<B>_</B>
characters,
<P>
-an arbitrary sequence of characters enclosed by a pair of
matching parentheses or curly brackets.
An escaped
<B>$</B>
character is a
<B>$</B>
that immediately follows a backslash
character; it then stands for a plain
<B>$</B>
.
Raise
<B>Not_found</B>
if the closing character of a parenthesized variable
cannot be found.
<P>
<P>
<P>
<P>
<I>val add_buffer </I>
:
<B>t -&gt; t -&gt; unit</B>
<P>
<P>
<B>add_buffer b1 b2</B>
appends the current contents of buffer
<B>b2</B>
at the end of buffer
<B>b1</B>
.
<B>b2</B>
is not modified.
<P>
<P>
<P>
<I>val add_channel </I>
:
<B>t -&gt; in_channel -&gt; int -&gt; unit</B>
<P>
<P>
<B>add_channel b ic n</B>
reads at most
<B>n</B>
characters from the
input channel
<B>ic</B>
and stores them at the end of buffer
<B>b</B>
.
Raise
<B>End_of_file</B>
if the channel contains fewer than
<B>n</B>
characters. In this case, the characters are still added to
the buffer, so as to avoid loss of data.
<P>
<P>
<P>
<I>val output_buffer </I>
:
<B>out_channel -&gt; t -&gt; unit</B>
<P>
<P>
<B>output_buffer oc b</B>
writes the current contents of buffer
<B>b</B>
on the output channel
<B>oc</B>
.
<P>
<P>
<P>
<I>val truncate </I>
:
<B>t -&gt; int -&gt; unit</B>
<P>
<P>
<B>truncate b len</B>
truncates the length of
<B>b</B>
to
<B>len</B>
Note: the internal byte sequence is not shortened.
Raise
<B>Invalid_argument</B>
if
<B>len &lt; 0</B>
or
<B>len &gt; length b</B>
.
<P>
<P>
<B>Since</B>
4.05.0
<P>
<P>
<P>
<P>
<A NAME="lbAE">&nbsp;</A>
<H3>Iterators</H3>
<P>
<P>
<P>
<I>val to_seq </I>
:
<B>t -&gt; char Seq.t</B>
<P>
Iterate on the buffer, in increasing order.
Modification of the buffer during iteration is undefined behavior.
<P>
<P>
<B>Since</B>
4.07
<P>
<P>
<P>
<I>val to_seqi </I>
:
<B>t -&gt; (int * char) Seq.t</B>
<P>
Iterate on the buffer, in increasing order, yielding indices along chars.
Modification of the buffer during iteration is undefined behavior.
<P>
<P>
<B>Since</B>
4.07
<P>
<P>
<P>
<I>val add_seq </I>
:
<B>t -&gt; char Seq.t -&gt; unit</B>
<P>
Add chars to the buffer
<P>
<P>
<B>Since</B>
4.07
<P>
<P>
<P>
<I>val of_seq </I>
:
<B>char Seq.t -&gt; t</B>
<P>
Create a buffer from the generator
<P>
<P>
<B>Since</B>
4.07
<P>
<P>
<P>
<P>
<A NAME="lbAF">&nbsp;</A>
<H3>Binary encoding of integers</H3>
<P>
<P>
<P>
<P>
The functions in this section append binary encodings of integers
to buffers.
<P>
Little-endian (resp. big-endian) encoding means that least
(resp. most) significant bytes are stored first. Big-endian is
also known as network byte order. Native-endian encoding is
either little-endian or big-endian depending on
<B>Sys.big_endian</B>
.
<P>
32-bit and 64-bit integers are represented by the
<B>int32</B>
and
<B>int64</B>
types, which can be interpreted either as signed or
unsigned numbers.
<P>
8-bit and 16-bit integers are represented by the
<B>int</B>
type,
which has more bits than the binary encoding. Functions that
encode these values truncate their inputs to their least
significant bytes.
<P>
<P>
<I>val add_uint8 </I>
:
<B>t -&gt; int -&gt; unit</B>
<P>
<P>
<B>add_uint8 b i</B>
appends a binary unsigned 8-bit integer
<B>i</B>
to
<B>b</B>
.
<P>
<P>
<B>Since</B>
4.08
<P>
<P>
<P>
<I>val add_int8 </I>
:
<B>t -&gt; int -&gt; unit</B>
<P>
<P>
<B>add_int8 b i</B>
appends a binary signed 8-bit integer
<B>i</B>
to
<B>b</B>
.
<P>
<P>
<B>Since</B>
4.08
<P>
<P>
<P>
<I>val add_uint16_ne </I>
:
<B>t -&gt; int -&gt; unit</B>
<P>
<P>
<B>add_uint16_ne b i</B>
appends a binary native-endian unsigned 16-bit
integer
<B>i</B>
to
<B>b</B>
.
<P>
<P>
<B>Since</B>
4.08
<P>
<P>
<P>
<I>val add_uint16_be </I>
:
<B>t -&gt; int -&gt; unit</B>
<P>
<P>
<B>add_uint16_be b i</B>
appends a binary big-endian unsigned 16-bit
integer
<B>i</B>
to
<B>b</B>
.
<P>
<P>
<B>Since</B>
4.08
<P>
<P>
<P>
<I>val add_uint16_le </I>
:
<B>t -&gt; int -&gt; unit</B>
<P>
<P>
<B>add_uint16_le b i</B>
appends a binary little-endian unsigned 16-bit
integer
<B>i</B>
to
<B>b</B>
.
<P>
<P>
<B>Since</B>
4.08
<P>
<P>
<P>
<I>val add_int16_ne </I>
:
<B>t -&gt; int -&gt; unit</B>
<P>
<P>
<B>add_int16_ne b i</B>
appends a binary native-endian signed 16-bit
integer
<B>i</B>
to
<B>b</B>
.
<P>
<P>
<B>Since</B>
4.08
<P>
<P>
<P>
<I>val add_int16_be </I>
:
<B>t -&gt; int -&gt; unit</B>
<P>
<P>
<B>add_int16_be b i</B>
appends a binary big-endian signed 16-bit
integer
<B>i</B>
to
<B>b</B>
.
<P>
<P>
<B>Since</B>
4.08
<P>
<P>
<P>
<I>val add_int16_le </I>
:
<B>t -&gt; int -&gt; unit</B>
<P>
<P>
<B>add_int16_le b i</B>
appends a binary little-endian signed 16-bit
integer
<B>i</B>
to
<B>b</B>
.
<P>
<P>
<B>Since</B>
4.08
<P>
<P>
<P>
<I>val add_int32_ne </I>
:
<B>t -&gt; int32 -&gt; unit</B>
<P>
<P>
<B>add_int32_ne b i</B>
appends a binary native-endian 32-bit integer
<B>i</B>
to
<B>b</B>
.
<P>
<P>
<B>Since</B>
4.08
<P>
<P>
<P>
<I>val add_int32_be </I>
:
<B>t -&gt; int32 -&gt; unit</B>
<P>
<P>
<B>add_int32_be b i</B>
appends a binary big-endian 32-bit integer
<B>i</B>
to
<B>b</B>
.
<P>
<P>
<B>Since</B>
4.08
<P>
<P>
<P>
<I>val add_int32_le </I>
:
<B>t -&gt; int32 -&gt; unit</B>
<P>
<P>
<B>add_int32_le b i</B>
appends a binary little-endian 32-bit integer
<B>i</B>
to
<B>b</B>
.
<P>
<P>
<B>Since</B>
4.08
<P>
<P>
<P>
<I>val add_int64_ne </I>
:
<B>t -&gt; int64 -&gt; unit</B>
<P>
<P>
<B>add_int64_ne b i</B>
appends a binary native-endian 64-bit integer
<B>i</B>
to
<B>b</B>
.
<P>
<P>
<B>Since</B>
4.08
<P>
<P>
<P>
<I>val add_int64_be </I>
:
<B>t -&gt; int64 -&gt; unit</B>
<P>
<P>
<B>add_int64_be b i</B>
appends a binary big-endian 64-bit integer
<B>i</B>
to
<B>b</B>
.
<P>
<P>
<B>Since</B>
4.08
<P>
<P>
<P>
<I>val add_int64_le </I>
:
<B>t -&gt; int64 -&gt; unit</B>
<P>
<P>
<B>add_int64_ne b i</B>
appends a binary little-endian 64-bit integer
<B>i</B>
to
<B>b</B>
.
<P>
<P>
<B>Since</B>
4.08
<P>
<P>
<P>
<HR>
<A NAME="index">&nbsp;</A><H2>Index</H2>
<DL>
<DT id="1"><A HREF="#lbAB">NAME</A><DD>
<DT id="2"><A HREF="#lbAC">Module</A><DD>
<DT id="3"><A HREF="#lbAD">Documentation</A><DD>
<DL>
<DT id="4"><A HREF="#lbAE">Iterators</A><DD>
<DT id="5"><A HREF="#lbAF">Binary encoding of integers</A><DD>
</DL>
</DL>
<HR>
This document was created by
<A HREF="/cgi-bin/man/man2html">man2html</A>,
using the manual pages.<BR>
Time: 00:05:36 GMT, March 31, 2021
</BODY>
</HTML>