6.29 Byte Strings

8.12

6.29 Byte Strings🔗ℹ

A byte string is a sequence of bytes (i.e., integers between 0 and 255 inclusive). A byte string works with map-referencing […] to access a byte via #%index. A byte string also works with the ++ operator to append bytes strings. A byte string can be used as sequence, in which case it supplies its bytes in order.

A byte string is normally mutable, but byte-string literals are immutable. The Bytes annotation is satisfied by both mutable and immutable byte strings, while MutableBytes and ImmutableBytes require one or the other.

The . operator can be used on a byte string expression as equivalent to calling Bytes functions:

bstr.length()
is
Bytes.length(bstr)
bstr.get(n)
is
Bytes.get(bstr, n)
bstr.set(n, byte)
is
Bytes.set(bstr, n, byte)
bstr.append(bstr2, ...)
is
Bytes.append(bstr, bstr2, ...)
bstr.subbytes(arg, ...)
is
Bytes.subbytes(bstr, arg, ...)
bstr.copy()
is
Bytes.copy(bstr)
bstr.copy_from(arg, ...)
is
Bytes.copy_from(bstr, arg, ...)
bstr.utf8_string(arg, ...)
is
Bytes.utf8_string(bstr, arg, ...)
bstr.latin1_string(arg, ...)
is
Bytes.latin1_string(bstr, arg, ...)
bstr.locale_string(arg, ...)
is
Bytes.locale_string(bstr, arg, ...)

Byte strings are comparable, which means that generic operations like < and > work on byte strings.

annotation

Bytes

annotation

MutableBytes

annotation

ImmutableBytes

Matches byte strings, where MutableBytes matches only mutable byte strings, and and ImmutableBytes matches only immutable byte strings.

function

fun Bytes.make(length :: NonnegInt, byte :: Byte = 0)

:: MutableBytes

Creates a fresh byte string with length bytes, where each byte is initialized to byte.

> Bytes.make(5, 33)
Bytes.copy(#"!!!!!")

function

fun Bytes.length(bstr :: Bytes) :: NonnegInt

Returns the number of bytes in bstr.

> Bytes.length(#"hello")
5
> #"hello".length()
5

function

fun Bytes.get(bstr :: Bytes, n :: NonnegInt) :: Byte

Equivalent to bstr[n] (with the default implicit #%index form). Returns the nth byte of bstr (starting from 0).

> #"abc"[0]
97
> #"abc".get(0)
97

function

fun Bytes.set(bstr :: MutableBytes,

n :: NonnegInt, byte :: Byte)

:: Void

Equivalent to bstr[n] := byte (with the default implicit #%index form). Updates the nth position of bstr to byte.

> def b = #"abc".copy()
> b[0] := 104
> b
Bytes.copy(#"hbc")
> b.set(1, 104)
> b
Bytes.copy(#"hhc")

function

fun Bytes.append(bstr :: Bytes, ...) :: MutableBytes

Appends bstrs by creating a new mutable byte string with all bytes.

> #"abc".append(#"def", #"ghi")
Bytes.copy(#"abcdefghi")

function

fun Bytes.subbytes(bstr :: Bytes,

start :: NonnegInt,

end :: NonnegInt = Bytes.length(bstr))

:: MutableBytes

Returns the substring of bstr from start (inclusive) to end (exclusive).

> Bytes.subbytes(#"hello", 2, 4)
Bytes.copy(#"ll")
> Bytes.subbytes(#"hello", 2)
Bytes.copy(#"llo")

function

fun Bytes.copy(bstr :: Bytes) :: MutableBytes

Returns a frash mutable byte string with the same initial content as bstr.

function

fun Bytes.copy_from(dest_bstr :: MutableBytes,

dest_start :: NonnegInt,

src_bstr :: Bytes,

src_start :: NonnegInt = 0,

src_end :: NonnegInt = Bytes.length(src_bstr))

:: Void

Copies bytes from src_bstr at src_start (inclusive) to src_end (exclusive) into dest_bstr starting at dest_start. The length of dest_bstr must be at least dest_start + (src_end - src_start).

function

fun Bytes.utf8_string(bstr :: Bytes,

err_char :: maybe(Char) = #false,

start :: NonnegInt = 0,

end :: NonnegInt = Bytes.length(bstr))

:: String

function

fun Bytes.latin1_string(bstr :: Bytes,

err_char :: maybe(Char) = #false,

start :: NonnegInt = 0,

end :: NonnegInt = Bytes.length(bstr))

:: String

function

fun Bytes.locale_string(bstr :: Bytes,

err_char :: maybe(Char) = #false,

start :: NonnegInt = 0,

end :: NonnegInt = Bytes.length(bstr))

:: String

Converts a byte string to a string, decoding as UTF-8, Latin-1, or the current locale’s encoding. The err_char argument provides a character to use in place of an encoding error, where #false means that an exception is thrown.

> #"hello".utf8_string()
"hello"

1	Rhombus Essentials
2	Collections and Iteration
3	Syntax Objects and Macros
4	Classes and Interfaces
5	Static Information and Binding
6	Core Reference
7	Meta and Macros Reference
8	Rhombus Static by Default
9	Libraries
10	Naming Conventions

6.1	General Forms
6.2	Definitions
6.3	Namespaces
6.4	Import
6.5	Export
6.6	Functions
6.7	Operators
6.8	Classes and Interfaces
6.9	Veneers
6.10	Mutable Variables and Assignment
6.11	Repetitions
6.12	Block
6.13	Conditionals
6.14	Matching
6.15	Iteration
6.16	Recursion
6.17	Context Parameters
6.18	Exceptions
6.19	Continuations
6.20	Implicit Forms
6.21	Static and Dynamic Lookup
6.22	Modules and Submodules
6.23	Booleans
6.24	Numbers
6.25	Characters
6.26	Strings
6.27	Keywords
6.28	Symbols
6.29	Byte Strings
6.30	Lists
6.31	Pairs and Pair Lists
6.32	Mutable Lists
6.33	Arrays
6.34	Maps
6.35	Sets
6.36	Boxes
6.37	Indexables
6.38	Listables
6.39	Sequences
6.40	Appendables
6.41	Comparables
6.42	Paths
6.43	Source Locations
6.44	Void
6.45	Equality
6.46	Dot
6.47	Multiple Values
6.48	Annotations
6.49	Enumerations
6.50	Input and Output
6.51	Eval
6.52	Syntax Objects
6.53	Syntax Classes
6.54	Simple Expression Macros
6.55	Unit Testing

bstr.length()	is	Bytes.length(bstr)
bstr.get(n)	is	Bytes.get(bstr, n)
bstr.set(n, byte)	is	Bytes.set(bstr, n, byte)
bstr.append(bstr2, ...)	is	Bytes.append(bstr, bstr2, ...)
bstr.subbytes(arg, ...)	is	Bytes.subbytes(bstr, arg, ...)
bstr.copy()	is	Bytes.copy(bstr)
bstr.copy_from(arg, ...)	is	Bytes.copy_from(bstr, arg, ...)
bstr.utf8_string(arg, ...)	is	Bytes.utf8_string(bstr, arg, ...)
bstr.latin1_string(arg, ...)	is	Bytes.latin1_string(bstr, arg, ...)
bstr.locale_string(arg, ...)	is	Bytes.locale_string(bstr, arg, ...)