diff options
author | Xavier Leroy <xavier.leroy@inria.fr> | 1999-02-25 10:26:38 +0000 |
---|---|---|
committer | Xavier Leroy <xavier.leroy@inria.fr> | 1999-02-25 10:26:38 +0000 |
commit | a5eb7789fdeb76f8339dbca0ed96ad173d53c947 (patch) | |
tree | 492b423b1f1c3c671ad301ecdb5c2f69690fbfba /stdlib/buffer.mli | |
parent | d654e2fa88b97315e3d51142ccfc636edc590c74 (diff) | |
download | ocaml-a5eb7789fdeb76f8339dbca0ed96ad173d53c947.tar.gz |
Revu le module Buffer.
Utilise Buffer dans Printf.sprintf; ajout Printf.bprintf.
Ajout Map.mem.
git-svn-id: http://caml.inria.fr/svn/ocaml/trunk@2309 f963ae5c-01c2-4b8c-9fe0-0dff7051ff02
Diffstat (limited to 'stdlib/buffer.mli')
-rw-r--r-- | stdlib/buffer.mli | 118 |
1 files changed, 47 insertions, 71 deletions
diff --git a/stdlib/buffer.mli b/stdlib/buffer.mli index 4004df6266..13900de279 100644 --- a/stdlib/buffer.mli +++ b/stdlib/buffer.mli @@ -2,88 +2,64 @@ (* *) (* Objective Caml *) (* *) -(* Pierre Weis, projet Cristal, INRIA Rocquencourt *) +(* Pierre Weis and Xavier Leroy, projet Cristal, INRIA Rocquencourt *) (* *) (* Copyright 1999 Institut National de Recherche en Informatique et *) (* en Automatique. Distributed only by permission. *) (* *) (***********************************************************************) -(* Module [Buffer]: string buffers, automatically expanded as necessary. - Provide accumulative concatenation of strings in linear time, - instead of quadratic time. - Also a convenient abstraction of strings and channels - for input output. *) +(* Module [Buffer]: extensible string buffers *) -type t;; +(* This module implements string 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). *) + +type t (* The abstract type of buffers. *) -(* Basic operations on buffers. *) val create : int -> t - (* [create n] returns a fresh buffer of length [n]. - The length of the buffer is the maximum number of characters - that can be written in the buffer without extending the - buffer, and further calls to [reset] will shrink the buffer to - this initial length. - The initial contents of the buffer is not specified. *) + (* [create n] returns a fresh buffer, initially empty. + The [n] parameter is the initial size of the internal string + that holds the buffer contents. That string is automatically + reallocated when more than [n] characters are stored in the buffer, + but shrinks back to [n] characters when [reset] is called. + For best performance, [n] 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 [n = 16] for instance. *) val contents : t -> string - (* Returns a copy of the actual contents of the buffer. - The writing position of the buffer is left unchanged. *) + (* Return a copy of the current contents of the buffer. + The buffer itself is unchanged. *) val length : t -> int - (* [length b n] returns the actual length of buffer [b]. *) -val position : t -> int - (* Returns the actual writing position of the buffer. *) + (* Return the number of characters currently contained in the buffer. *) val clear : t -> unit - (* Reset to zero the writing position of the buffer. *) + (* Empty the buffer. *) val reset : t -> unit - (* [reset b] resets the buffer to its initial length and resets - to zero the writing position of the buffer. The underlying - storage character string of the buffer is restored to its - initial value. *) - -(* The [printf] facility for buffers. *) -val bprintf : t -> ('a, t, unit) format -> 'a - (* [bprintf] has the same functionality as [fprintf] but material - is output on buffers. See the module [printf] for details. *) - -(* Output function for buffers. *) -val output_string : t -> string -> unit -val output_char : t -> char -> unit -val output : t -> string -> int -> int -> unit - (* Similar to the usual functions from module [Pervasives], - but output is done on the buffer argument. *) -val output_buffer : t -> t -> unit - (* [output_buffer b1 b2] copies the contents of buffer [b2] into - the buffer [b1]. - The writing position of buffer [b2] is left unchanged. *) - -(* Connection between buffers and out channels. *) -val open_out : t -> out_channel -> unit - (* Connects the buffer to the given out channel. - Overflows or explicit flushes now cause the buffer to be - output on the given out channel. *) -val close_out : t -> unit - (* Flushes the buffer to its out channel, resets the buffer, then - suppresses the connection between the buffer and its out channel. - The out channel is not closed. - Nothing happens if the buffer is not connected to any out channel. *) -val flush : t -> unit - (* Outputs the contents of the buffer to its out channel, and resets - to zero the writing position of the buffer. - The out channel is not flushed. - Nothing happens if the buffer is not connected to any out channel. *) - -(* Reading characters from input channels. *) -val input : in_channel -> t -> int -> int - (* [input ic b len] attempts to read [len] characters from input - channel [ic] and stores them in buffer [b]. - It returns the actual number of characters read. *) -val really_input : in_channel -> t -> int -> unit - (* Same as the [input] function above, but using the input function - [Pervasives.really_input] instead of [Pervasives.input]. - Raise [End_of_file] if the end of file is reached before [len] - characters have been read. *) -val read_in_channel : in_channel -> t -> unit - (* [Buffer.read_in_channel ic b] copies the entire contents of - input channel [ic] in buffer [b]. *) - + (* Empty the buffer and deallocate the internal string holding the + buffer contents, replacing it with the initial internal string + of length [n] that was allocated by [create n]. + For long-lived buffers that may have grown a lot, [reset] allows + faster reclaimation of the space used by the buffer. *) +val add_char : t -> char -> unit + (* [add_char b c] appends the character [c] at the end of + the buffer [b]. *) +val add_string : t -> string -> unit + (* [add_string b s] appends the string [s] at the end of + the buffer [b]. *) +val add_substring : t -> string -> int -> int -> unit + (* [add_substring b s ofs len] takes [len] characters from offset + [ofs] in string [s] and appends them at the end of the buffer [b]. *) +val add_buffer : t -> t -> unit + (* [add_buffer b1 b2] appends the current contents of buffer [b2] + at the end of buffer [b1]. [b2] is not modified. *) +val add_channel : t -> in_channel -> int -> unit + (* [add_channel b ic n] reads exactly [n] character from the + input channel [ic] and stores them at the end of buffer [b]. + Raise [End_of_file] if the channel contains fewer than [n] + characters. *) +val output_buffer : out_channel -> t -> unit + (* [output_buffer oc b] writes the current contents of buffer [b] + on the output channel [oc]. *) |