Docs / Standard library

Buffers

Build and edit line-oriented text with mutable Buffer values.

Browse documentation
On this page

A Buffer is a growable sequence of String lines. It is useful when a program needs to build or edit text one line at a time.

let lines = buffer.new()
buffer.add-line(lines, "first")
buffer.add-line(lines, "second")
buffer.set-line(lines, 1, "updated") try
print(buffer.to-text(lines))

This prints:

first
updated

Operations

Signature Result and behavior
buffer.new() -> Buffer Create an empty buffer.
buffer.add-line(Buffer, String) -> Buffer Append one line and return the same buffer.
buffer.line-count(Buffer) -> Int Return the number of lines.
buffer.line(Buffer, Int) -> Result<String, BufferError> On success, return the line at a zero-based index.
buffer.set-line(Buffer, Int, String) -> Result<Buffer, BufferError> On success, replace the line at a zero-based index and return the buffer.
buffer.to-text(Buffer) -> String Join the lines with \n.

Mutation words return their receiver, so chained calls and flow steps thread one buffer through successive mutations. buffer.line and buffer.set-line fail when the index is negative or is at least the line count. Add try to either call to propagate that failure, or use catch to supply a fallback. A user word that lets the failure escape through try receives an inferred Result signature; explicit Result<T, E> signatures remain supported. See results and error handling.

Names refer to the same buffer value; binding it with let does not make a copy. A second name observes changes made through the first. Buffers cannot be compared with == or !=, and print does not accept a Buffer; convert it with buffer.to-text first.

For whole-file input as text, see file operations. For line and word counts, see text operations.