Binary
Binary — byte-level data and serialization.
Binary is a Collection of bytes. Each element is an Integer (0-255). String is a subclass of Binary that adds grapheme-aware text operations.
BEAM Mapping
Beamtalk binaries map directly to Erlang binaries (binary()).
Examples
bin := Binary serialize: 42
Binary deserialize: bin // => 42
Binary fromIolist: #("hello", " ", "world")
// => _
Methods
Class Methods
Serialize any value to a binary (class method).
Converts a Beamtalk value to its binary representation using Erlang's external term format.
Examples
(Binary serialize: 42) class name // => "Binary"
Deserialize a binary back to the original value (class method).
Uses safe mode to prevent atom table exhaustion from untrusted input. Atoms not already in the atom table will cause an error.
Examples
Binary deserialize: (Binary serialize: #(1, 2, 3))
// => _
Convert an iolist to a flat binary (class method).
An iolist is a (possibly nested) list of binaries and integers (0-255). This flattens it into a single binary.
Examples
Binary fromIolist: #("hello", " ", "world")
// => _
Create a binary from a list of byte integers (0-255).
Examples
Binary fromBytes: #(104, 101, 108, 108, 111) // => _
Deserialize a binary and return both the value and bytes consumed.
Returns a tuple of (value, bytesConsumed). Useful for parsing concatenated ETF values from a binary stream.
Examples
bin := Binary serialize: 42
result := Binary deserializeWithUsed: bin
result first // => 42
result second // => bytes consumed
Instance Methods
Return the byte count of this binary.
Examples
(Binary serialize: 42) size // => _
Iterate over each byte (Integer 0-255), evaluating block with each one.
Examples
(Binary fromBytes: #(104, 101)) do: [:b | Transcript show: b]
Return a developer-readable string representation.
Displays hex representation for non-UTF-8 binaries, or quoted string for valid UTF-8 binaries.
Examples
(Binary fromBytes: #(104, 101)) printString // => _
Return the byte value (0-255) at the given 1-based index.
Raises index_out_of_bounds if the index is out of range.
Examples
(Binary fromBytes: #(104, 101, 108)) at: 1 // => 104
Return the byte value (0-255) at the given 0-based offset.
Uses 0-based indexing to match Erlang's binary:at/2.
Raises index_out_of_bounds if the offset is out of range.
Examples
(Binary fromBytes: #(104, 101, 108)) byteAt: 0 // => 104
Return the byte count of this binary.
Alias for size on Binary. On String, provides unambiguous byte count
(since String overrides size with grapheme count).
Examples
(Binary fromBytes: #(104, 101, 108)) byteSize // => 3
Return a zero-copy slice of this binary.
Takes a 0-based offset and length. Raises index_out_of_bounds
if the range is invalid.
Examples
(Binary fromBytes: #(1, 2, 3, 4, 5)) part: 1 size: 3 // => _
Concatenate this binary with another binary.
Examples
(Binary fromBytes: #(1, 2)) concat: (Binary fromBytes: #(3, 4)) // => _
Convert this binary to a list of byte integers (0-255).
Examples
(Binary fromBytes: #(104, 101)) toBytes // => #(104, 101)
Validate UTF-8 and return the binary as a String.
Returns a Result: success gives a String, failure gives an error with the byte offset of the invalid sequence.
Examples
(Binary fromBytes: #(104, 101, 108, 108, 111)) asString // => _
Return this binary as a String without UTF-8 validation.
Use when you trust the source data is valid UTF-8.
Examples
(Binary fromBytes: #(104, 101, 108, 108, 111)) asStringUnchecked // => "hello"
Inherited Methods
From Collection
Return the number of elements.
Iterate over each element, evaluating block with each one.
Return a developer-readable string representation.
Return the class used to build results from collection operations.
Used by collect:, select:, and reject: to return the same
collection type as the receiver. Sealed subclasses override this.
Examples
#(1, 2) species // => List
#[1, 2] species // => Array
Test if the collection has no elements.
Examples
#() isEmpty // => true
#(1) isEmpty // => false
Test if the collection has at least one element.
Examples
#(1) isNotEmpty // => true
#() isNotEmpty // => false
Test if the collection contains the given element.
Default implementation iterates with do: and returns early on match.
Subclasses may override with more efficient lookup.
Examples
#(1, 2, 3) includes: 2 // => true
#(1, 2, 3) includes: 9 // => false
Reduce the collection with an accumulator.
Evaluates block with (accumulator, element) for each element.
Returns the final accumulator value.
Kept as @primitive because the pure-BT implementation using do: with
local-variable mutation does not work for abstract-class methods: the
compiler generates lists:foreach (no state threading) instead of
lists:foldl. The Erlang helper calls the block as Block(Acc, Elem)
(accumulator first) to match the Beamtalk block value: acc value: each
convention expected by collect:, select:, and reject:.
Examples
#(1, 2, 3) inject: 0 into: [:sum :x | sum + x] // => 6
Collect results of evaluating block on each element.
Returns a collection of the same type as the receiver (species pattern).
Builds the result in reverse using addFirst: then converts via species withAll:.
Examples
#(1, 2, 3) collect: [:x | x * 2] // => #(2, 4, 6)
Select elements for which block returns true.
Returns a collection of the same type as the receiver (species pattern).
Builds the result in reverse using addFirst: then converts via species withAll:.
Examples
#(1, 2, 3, 4) select: [:x | x > 2] // => #(3, 4)
Reject elements for which block returns true.
Examples
#(1, 2, 3, 4) reject: [:x | x > 2] // => #(1, 2)
Find the first element for which block returns true.
Returns nil if no element matches. Uses ^ (non-local return) for
early exit — this compiles to throw/catch on BEAM.
Examples
#(1, 2, 3) detect: [:x | x > 1] // => 2
Find the first element matching block, or evaluate noneBlock if none.
Uses ^ (non-local return) for early exit — compiles to throw/catch on BEAM.
Examples
#(1, 2) detect: [:x | x > 5] ifNone: [0] // => 0
Test if any element satisfies block.
Uses ^ (non-local return) for early exit — compiles to throw/catch on BEAM.
Examples
#(1, 2, 3) anySatisfy: [:x | x > 2] // => true
Test if all elements satisfy block.
Uses ^ (non-local return) for early exit — compiles to throw/catch on BEAM.
Examples
#(2, 4, 6) allSatisfy: [:x | x isEven] // => true
Return a string representation.
From Value
Return a developer-readable string representation showing fields.
Produces ClassName(field: value, ...). Field values are recursively
inspected — strings are quoted, nested objects show their own inspect.
A class with no fields produces ClassName().
Examples
ValuePoint x: 3 y: 4 inspect // => "ValuePoint(x: 3, y: 4)"
ValuePoint new inspect // => "ValuePoint(x: 0, y: 0)"
From Object
Return the class of the receiver.
Examples
42 class // => Integer
"hello" class // => String
Test if the receiver is nil. Returns false for all objects except nil.
Examples
42 isNil // => false
nil isNil // => true
Test if the receiver is not nil. Returns true for all objects except nil.
Examples
42 notNil // => true
nil notNil // => false
If the receiver is nil, evaluate nilBlock. Otherwise return self.
Examples
42 ifNil: [0] // => 42
nil ifNil: [0] // => 0
If the receiver is not nil, evaluate notNilBlock with self.
Examples
42 ifNotNil: [:v | v + 1] // => 43
nil ifNotNil: [:v | v + 1] // => nil
If nil, evaluate nilBlock; otherwise evaluate notNilBlock with self.
Examples
42 ifNil: [0] ifNotNil: [:v | v + 1] // => 43
nil ifNil: [0] ifNotNil: [:v | v + 1] // => 0
If not nil, evaluate notNilBlock with self; otherwise evaluate nilBlock.
Examples
42 ifNotNil: [:v | v + 1] ifNil: [0] // => 43
nil ifNotNil: [:v | v + 1] ifNil: [0] // => 0
Return a developer-readable string representation.
Default implementation returns "a ClassName". Subclasses such as
Integer, String, and List override this to return richer output.
Examples
42 printString // => "42"
Return a user-facing string representation for display purposes.
Default implementation delegates to printString. Subclasses such as
String and Symbol override this to return a more readable form without
developer annotations (e.g. no surrounding quotes or # prefix).
Examples
42 displayString // => "42"
Inspect the receiver.
Examples
42 inspect // => "42"
Return the receiver itself. Useful for cascading side effects.
Examples
42 yourself // => 42
Return a hash value for the receiver.
Examples
42 hash
Test if the receiver responds to the given selector.
Examples
42 respondsTo: #abs // => true
Return the names of fields.
Examples
42 fieldNames // => #()
Return the value of the named field.
Examples
object fieldAt: #name
Set the value of the named field (returns new state).
Examples
object fieldAt: #name put: "Alice"
Send a unary message dynamically.
Examples
42 perform: #abs // => 42
Send a message dynamically with arguments.
Examples
3 perform: #max: withArguments: #(5) // => 5
Raise an error indicating this method must be overridden by a subclass.
Examples
self subclassResponsibility
Raise an error indicating this method has not yet been implemented.
Use this for work-in-progress stubs. Distinct from subclassResponsibility,
which signals an interface contract violation.
Examples
self notImplemented
Send aValue to the current transcript without a trailing newline.
Nil-safe: does nothing when no transcript is set (batch compile, tests).
Examples
42 show: "value: "
Send aValue to the current transcript followed by a newline.
Nil-safe: does nothing when no transcript is set (batch compile, tests).
Examples
42 showCr: "hello world"
Test if the receiver is an instance of aClass or any of its subclasses.
Examples
42 isKindOf: Integer // => true
42 isKindOf: Object // => true
#foo isKindOf: Symbol // => true
#foo isKindOf: String // => false
Raise an error with the given message.
Examples
self error: "something went wrong"
From ProtoObject
Test value equality (Erlang ==).
Examples
42 == 42 // => true
"abc" == "abc" // => true
Test value inequality (negation of ==).
Examples
1 /= 2 // => true
42 /= 42 // => false
Return the class of the receiver.
Examples
42 class // => Integer
"hello" class // => String
Handle messages the receiver does not understand. Override for custom dispatch.
Examples
42 unknownMessage // => ERROR: does_not_understand
Send a message dynamically with an arguments list.
Examples
42 perform: #abs withArguments: #() // => 42
Execute a class method in the caller's process, bypassing gen_server dispatch.
The caller takes responsibility for knowing the method does not mutate class state. Useful for long-running class methods that would otherwise block the class object's gen_server.
Limitations: only resolves methods defined directly on the target class
module (does not walk the superclass chain). Class variables and self
are not available to the method (nil and #{} are passed).
Examples
MyClass performLocally: #run:ctx: withArguments: #(input, ctx)
Send a message dynamically with an arguments list and explicit timeout.
The timeout (in milliseconds or #infinity) applies to the gen_server:call
when the receiver is an actor. For value types, timeout is ignored.
Examples
actor perform: #query withArguments: #(sql) timeout: 30000