2015 004 Addition of Buffer module

Proposal 2015-004

Addition of Buffer module

Author: Ken Friis Larsen
Last revised: August 11, 2015
Status: proposed
Discussion: issue #4

---

Synopsis

signature BUFFER =
sig
    type buf
    val new      : int -> buf
    val contents : buf -> string
    val size     : buf -> int
    val clear    : buf -> unit
    val reset    : buf -> unit

    val addChar      : buf -> char -> unit
    val addString    : buf -> string -> unit
    val addSubString : buf -> substring -> unit
end

structure Buffer :> BUFFER

Description

• type buf

  A type of mutable string buffers that allows efficient concatenation at the end and automatically expand as necessary. It provides accumulative concatenation of strings in quasi-linear time (instead of quadratic time when strings are concatenated pairwise).

• new hint creates a new empty buffer. Raises Size if hint <= 0 or hint > String.maxSize. The argument hint is used as the initial size of the internal string that holds the buffer contents. The internal string is automatically reallocated as contents is stored in the buffer. For best performance, hint 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 hint = 16 for instance.

• contents buf returns the contents of buf.

• size buf returns the size of the contents of buf.

• clear buf emptys buf.

• reset buf emptys buf and shrink the internal string to the initial hint.

• addChar buf c appends c at the end of buf.

• addString buf s appends s at the end of buf.

• addSubString buf ss appends ss at the end of buf.

Discussion

Generating strings efficiently is needed for many programming tasks. It is possible to implement this module with other parts of the Basis Library, however to get top performance you need to use the internal representation of strings (for some systems at least).

This module is shipped as part of Moscow ML's library, since version 2.10.

Impact

Adopting this proposal should not affect existing programs.

Rationale

This module is a natural candidate for inclusion in the Basis Library. Similar structures have been found to be useful in other programming languages, for instance StringBuilder in Java and the Buffer module in O'Caml (the original inspiration for this module).

---

History

• [2015-08-11] Proposed

---