nupp.text

Working with text a byte at a time.

newBuffer hands back a FIFO byte buffer: append to one end, read from the other, and the string is built once instead of once per concatenation.

local text = require("nupp.text")

const out = text.newBuffer()
out:put("hello", ", ", "world")
print(out:get())

A buffer comes from the host. On LuaJIT it is string.buffer; everywhere else it is a portable one written in Nupp. Both answer to the same Buffer, so a program that only ever writes and reads bytes does not notice which it has.

nupp.text.utf8 is the other half of this namespace: codepoints rather than bytes.

Submodules

ModuleDescription
nupp.text.spiImplementation interfaces consumed during ordinary module initialization.
nupp.text.utf8nupp.text.utf8 reads Unicode scalars out of strings and nupp.io.ByteView values.

Module contents

Types

TypeKindDescription
BufferrecordA mutable FIFO byte sequence.

Functions

FunctionKindDescription
newBufferfunctionCreates an empty FIFO byte buffer.

Types#

Bufferrecord#

record Buffer ...

A mutable FIFO byte sequence.

Members

NameKindDescription
__lenmetamethodReturns the unread byte count without consuming data.
__concatmetamethodConcatenates the buffer's unread text with another value.
__tostringmetamethodReturns unread bytes without consuming them.
putmethodAppends each value and returns a borrow of this same buffer for chaining.
putfmethodFormats and appends text, returning the same borrowed buffer.
getmethodConsumes successive requested byte counts and returns one string per count.
tostringmethodCopies unread bytes into a string without advancing the FIFO.
resetmethodDiscards buffered bytes and returns the same reusable buffer.
freemethodReleases retained storage and returns the same reusable buffer.
skipmethodDiscards a prefix of unread bytes and returns the same borrowed buffer.
setmethodReplaces unread contents with bytes and returns the same borrowed buffer.

__lenmetamethod#

__len: function(self): integer

Returns the unread byte count without consuming data.

Arguments
NameTypeDescription
?self
Returns
TypeDescription
integer

__concatmetamethod#

__concat: function(self, other: any): string

Concatenates the buffer's unread text with another value.

Arguments
NameTypeDescription
?self
otherany
Returns
TypeDescription
string

__tostringmetamethod#

__tostring: function(self): string

Returns unread bytes without consuming them.

Arguments
NameTypeDescription
?self
Returns
TypeDescription
string

putmethod#

put: function(exclusive b: Buffer, ...: any): Buffer borrows (b)

Appends each value and returns a borrow of this same buffer for chaining.

Arguments
NameTypeDescription
exclusive bBuffer
...any
Returns
TypeDescription
Buffer borrows (b)

putfmethod#

putf: function(exclusive b: Buffer, fmt: string, ...: any): Buffer borrows (b)

Formats and appends text, returning the same borrowed buffer.

Arguments
NameTypeDescription
exclusive bBuffer
fmtstring
...any
Returns
TypeDescription
Buffer borrows (b)

getmethod#

get: function(exclusive b: Buffer, ...: integer?): (string,...string)

Consumes successive requested byte counts and returns one string per count. With no count, consumes all unread bytes. Counts are taken in order, so when one is negative or fractional and raises, the reads before it have already consumed their bytes.

Arguments
NameTypeDescription
exclusive bBuffer
...integer?
Returns
TypeDescription
string

tostringmethod#

tostring: function(b: Buffer): string

Copies unread bytes into a string without advancing the FIFO.

Arguments
NameTypeDescription
bBuffer
Returns
TypeDescription
string

resetmethod#

reset: function(exclusive b: Buffer): Buffer borrows (b)

Discards buffered bytes and returns the same reusable buffer.

Arguments
NameTypeDescription
exclusive bBuffer
Returns
TypeDescription
Buffer borrows (b)

freemethod#

free: function(exclusive b: Buffer): Buffer borrows (b)

Releases retained storage and returns the same reusable buffer.

Arguments
NameTypeDescription
exclusive bBuffer
Returns
TypeDescription
Buffer borrows (b)

skipmethod#

skip: function(exclusive b: Buffer, count: integer): Buffer borrows (b)

Discards a prefix of unread bytes and returns the same borrowed buffer.

Arguments
NameTypeDescription
exclusive bBuffer
countinteger
Returns
TypeDescription
Buffer borrows (b)

setmethod#

set: function(exclusive b: Buffer, bytes: string): Buffer borrows (b)

Replaces unread contents with bytes and returns the same borrowed buffer.

Arguments
NameTypeDescription
exclusive bBuffer
bytesstring
Returns
TypeDescription
Buffer borrows (b)

Functions#

newBufferfunction#

const newBuffer: function(size: (integer | table)?, options: table?): Buffer

Creates an empty FIFO byte buffer.

Arguments

NameTypeDescription
size(integer | table)?

a capacity hint, or the options table when it is the only argument

optionstable?

the host buffer library's options, where it has any

Returns

TypeDescription
Buffer

the buffer, holding nothing