value

func (Duration) ISO8601 ¶

func (d Duration) ISO8601() string

ISO8601 returns the duration formatted as an ISO-8601 string.

func (Duration) Parts ¶

func (d Duration) Parts() map[string]int64

Parts decomposes the duration into days, hours, minutes, and seconds.

func (Duration) Seconds ¶

func (d Duration) Seconds() int64

Seconds returns the duration as a whole number of seconds.

func (Duration) String ¶

func (d Duration) String() string

String returns the duration formatted as "<n>s".

func (*EqualityContext) Equal ¶ added in v0.60.0

func (c *EqualityContext) Equal(v, other Value) bool

Equal reports whether v and other hold the same kind and value.

func (HashLookupKey) ExtraPayloadBytes ¶

func (k HashLookupKey) ExtraPayloadBytes() int

ExtraPayloadBytes returns heap bytes stored only by this lookup key, excluding the fixed HashLookupKey struct itself. Scalar lookup keys either keep their payload in numeric fields or alias the original key value's string payload; array keys and big-integer keys retain a canonical lookup string that is not reachable otherwise. It is intended for the interpreter's internal use; hosts should not call it, and it carries no compatibility promise (see docs/embedding-api-stability.md).

func (Money) Add ¶

func (m Money) Add(other Money) (Money, error)

Add returns the sum of m and other, or an error if their currencies differ or the result would overflow the int64 cents range.

func (Money) Cents ¶

func (m Money) Cents() int64

Cents returns the amount in the smallest currency unit.

func (Money) Currency ¶

func (m Money) Currency() string

Currency returns the ISO-4217 currency code.

func (Money) DivInt ¶

func (m Money) DivInt(divisor int64) (Money, error)

DivInt divides m by the given integer divisor, returning an error on division by zero or on the one signed-division overflow case (MinInt64 / -1, whose true result is not representable in int64).

func (Money) MulInt ¶

func (m Money) MulInt(factor int64) (Money, error)

MulInt multiplies m by the given integer factor, preserving the currency, or returns an error if the result would overflow the int64 cents range.

func (Money) String ¶

func (m Money) String() string

String returns the amount formatted as "X.XX CUR".

func (Money) Sub ¶

func (m Money) Sub(other Money) (Money, error)

Sub returns m minus other, or an error if their currencies differ or the result would overflow the int64 cents range.

func (Range) String ¶ added in v0.60.0

func (r Range) String() string

String renders the range the way it is written in source, including the open-ended forms: 1..5, 1..., ..5, 1.., and so on.

func (Regex) String ¶ added in v0.60.0

func (r Regex) String() string

String renders the regex the way it is written in source: /pattern/flags. The source is escaped so wrapping it in delimiters yields a valid, round-trippable literal. Without this, a source built from a string (Regexp.new("a/b"), Regexp.new("\n")) would render /a/b/ or embed a raw newline, neither of which the lexer can re-parse.

func (Value) Array ¶

func (v Value) Array() []Value

Array returns the array content of v, or nil if v is not an array. The returned slice is the array's live backing: element writes through it are visible to every alias of the array, but callers must not assume its length stays current across Ruby-style in-place mutators (push, pop, ...), which swap the wrapper's element slice.

func (Value) BigInt ¶ added in v0.60.0

func (v Value) BigInt() *big.Int

BigInt returns the integer content of v as a *big.Int for every KindInt value, compact or big. The result is a fresh copy the caller owns; mutating it never affects v. It returns nil when v is not an integer.

func (Value) Block ¶

func (v Value) Block() BlockPayload

Block returns the underlying block payload of v, or nil if v is not a block. The concrete type is private to the runtime; callers operate through the BlockPayload marker.

func (Value) Bool ¶

func (v Value) Bool() bool

Bool returns the boolean content of v, or false if v is not a bool.

func (Value) Builtin ¶

func (v Value) Builtin() BuiltinPayload

Builtin returns the underlying builtin payload of v, or nil if v is not a builtin. The concrete type is private to the runtime; callers operate through the BuiltinPayload marker.

func (Value) Class ¶

func (v Value) Class() ClassPayload

Class returns the underlying class payload of v, or nil if v is not a class. The concrete type is private to the runtime; callers operate through the ClassPayload marker.

func (Value) CompactInt ¶ added in v0.60.0

func (v Value) CompactInt() (int64, bool)

CompactInt returns v's integer content and true when v is an integer that fits in int64 (the compact representation). It returns (0, false) for big integers and non-integers, letting callers that require an int64 distinguish a genuine zero from an out-of-range value, which Int alone cannot. It is intended for the interpreter's internal use; hosts should combine IsBigInt with Int, and it carries no compatibility promise (see docs/embedding-api-stability.md).

func (Value) Data ¶

func (v Value) Data() any

Data returns the underlying payload stored in v. Callers are expected to type-assert against the payload type associated with v.Kind(). Prefer the typed accessors (Int, Array, Hash, ...): they cover every kind, and for the runtime-only kinds (functions, blocks, classes, instances, enums) the concrete payload type behind Data is internal to the interpreter and carries no compatibility promise.

An integer outside the int64 range exposes its live *big.Int payload, like arrays and hashes expose their live backing. Mutating it corrupts the value (big payloads are immutable by contract); callers that need an owned copy use BigInt instead.

func (Value) Duration ¶

func (v Value) Duration() Duration

Duration returns the duration content of v, or a zero Duration if v is not a duration.

func (Value) Enum ¶

func (v Value) Enum() EnumPayload

Enum returns the underlying enum definition payload of v, or nil if v is not an enum. The concrete type is private to the runtime; callers operate through the EnumPayload marker.

func (Value) EnumValue ¶

func (v Value) EnumValue() EnumValuePayload

EnumValue returns the underlying enum value payload of v, or nil if v is not an enum value. The concrete type is private to the runtime; callers operate through the EnumValuePayload marker.

func (Value) Eql ¶ added in v0.60.0

func (v Value) Eql(other Value) bool

Eql reports whether v and other are equal under hash-key semantics: they must share the same kind and compare equal, so an Int never eql-matches a Float even when their numeric values coincide. It backs the Ruby-style `eql?` predicate. Because Equal already requires matching kinds (Vibescript `==` performs no cross-kind numeric coercion), Eql currently coincides with Equal; it exists as a distinct, documented contract aligned with hash-key equality rather than with broad value equivalence.

func (Value) Equal ¶

func (v Value) Equal(other Value) bool

Equal reports whether v and other hold the same kind and value.

package main

import (
	"fmt"

	"github.com/mgomes/vibescript/vibes/value"
)

func main() {
	a := value.NewInt(1)
	b := value.NewInt(1)
	c := value.NewString("1")
	fmt.Println(a.Equal(b))
	fmt.Println(a.Equal(c))
}

Output:
true
false

func (Value) Float ¶

func (v Value) Float() float64

Float returns the float content of v, coercing from int if needed. An integer outside the int64 range converts best-effort to the nearest float64; magnitudes beyond the float64 range yield +/-Infinity, matching Ruby's Integer#to_f.

func (Value) Function ¶

func (v Value) Function() FunctionPayload

Function returns the underlying script-function payload of v, or nil if v is not a function. The concrete type is private to the runtime; callers operate through the FunctionPayload marker.

func (Value) Hash ¶

func (v Value) Hash() map[string]Value

Hash returns the hash content of v, or nil if v is not a hash or object. A KindHash payload wraps its entries in a hashData struct (to carry optional default metadata); a KindObject payload is a bare map.

func (Value) HashClearEntries ¶ added in v0.60.0

func (v Value) HashClearEntries()

HashClearEntries removes every entry from a hash or object in place, preserving a hash's Ruby-style default metadata (Ruby's Hash#clear keeps the default). The typed-entry map, insertion order, and any materialized legacy map are replaced with fresh empty storage so the old backings are released.

func (Value) HashDeleteKey ¶ added in v0.60.0

func (v Value) HashDeleteKey(key Value) (Value, bool, error)

HashDeleteKey removes the entry for key from a hash or object in place, returning the removed value and whether the key was present. On a typed hash it removes the key's slot from the recorded insertion order (keeping the order/entries invariant HashSet maintains) and mirrors the removal into the materialized legacy map when one exists. A missing key leaves the hash untouched. An error is returned only for an unsupported key.

func (Value) HashEntries ¶ added in v0.60.0

func (v Value) HashEntries() []HashEntry

HashEntries returns hash entries with original keys preserved. Objects are exposed as string-keyed entries.

func (Value) HashEntriesInto ¶ added in v0.60.0

func (v Value) HashEntriesInto(buf []HashEntry) []HashEntry

HashEntriesInto appends hash entries with original keys preserved into buf when it has enough capacity. Typed entries appear in Ruby-style insertion order; legacy string-map entries appear in Go map order (callers that need determinism for legacy hashes sort by key themselves). It is intended for the interpreter's internal use; hosts should not call it, and it carries no compatibility promise (see docs/embedding-api-stability.md).

func (Value) HashGet ¶ added in v0.60.0

func (v Value) HashGet(key Value) (Value, bool, error)

HashGet returns the value for key from a hash or object.

func (Value) HashHasTypedEntries ¶

func (v Value) HashHasTypedEntries() bool

HashHasTypedEntries reports whether a hash carries canonical typed-key entries in addition to the legacy string-key map exposed by Hash(). It is intended for the interpreter's internal use; hosts should not call it, and it carries no compatibility promise (see docs/embedding-api-stability.md).

func (Value) HashLen ¶ added in v0.60.0

func (v Value) HashLen() int

HashLen returns the number of entries in a hash or object.

func (Value) HashSet ¶ added in v0.60.0

func (v Value) HashSet(key, val Value) error

HashSet stores key/value in a hash or object. On a hash it preserves Ruby-style insertion order: a new key is appended to the recorded order and an existing key keeps its original position while taking the new value.

func (Value) HashStringMapIfMaterialized ¶

func (v Value) HashStringMapIfMaterialized() (map[string]Value, bool)

HashStringMapIfMaterialized returns the legacy string-key map when one already exists, without forcing typed hashes to allocate that lossy compatibility view. It is intended for the interpreter's internal use; hosts should not call it, and it carries no compatibility promise (see docs/embedding-api-stability.md).

func (Value) Identical ¶ added in v0.60.0

func (v Value) Identical(other Value) bool

Identical reports whether v and other refer to the same object, backing the Ruby-style `equal?` predicate. Immutable value kinds (nil, bool, int, float, string, symbol, money, duration, time, range) are identical when they share the same kind and value, since the language exposes no distinct identities for equal immutables. Integers outside the int64 range are the exception: they are heap objects and compare by payload identity, matching Ruby, where bignums are separate objects. Mutable composites (array, hash, object) and runtime-only kinds (function, builtin, block, class, instance, enum, enum value) are identical only when they share the same backing storage, so two independently constructed composites with equal contents are not identical.

NaN floats are the one immutable case where value equality is not enough: IEEE NaN != NaN, so deferring to Equal would make x.equal?(x) false for a NaN receiver and break reflexivity. Identity treats any two NaN floats as identical, keeping equal? reflexive while matching the value-identity model floats already follow.

Empty arrays are the one principled exception: any two empty arrays report identical regardless of their backing storage. This is harmless because an empty array has no element storage to alias — appending to one never affects another — so they behave as a single value-like empty rather than as distinct mutable objects. Backing pointers alone cannot establish this, because an empty result preallocated with spare capacity (for example array.select starting from make([]Value, 0, len(arr))) carries its own non-zerobase pointer and a different capacity than a literal []; only a length check captures the contract. Empty hashes and objects stay distinct because every hash carries its own hashData wrapper (NewHash allocates a fresh one per call) and NewObject allocates a fresh backing map for nil input, so each empty composite has a distinct identity rather than collapsing onto a shared zero pointer.

func (Value) Inspect ¶ added in v0.60.0

func (v Value) Inspect() string

Inspect returns a debug representation of v, mirroring Ruby's Object#inspect. Unlike String (which is the to_s form), Inspect preserves quoting and escaping for strings, renders symbols with their leading colon, and recurses into arrays and hashes so the result is a stable, parseable debug rendering. Hash entries use Vibescript's colon-label key form (`{ name: "Ada" }`) rather than Ruby's hash-rocket syntax, which Vibescript does not support, so the output round-trips as a Vibescript literal. Cycles are collapsed to <cycle> exactly like String.

func (Value) InspectBounded ¶ added in v0.60.0

func (v Value) InspectBounded(limit int) (string, error)

InspectBounded renders v like Inspect but stops once the formatted output would exceed limit bytes, returning the partial output and ErrStringRenderTruncated. A non-positive limit means unbounded and behaves exactly like Inspect. Like StringBounded, it writes into a single growing buffer and checks the budget after each piece, so a hostile composite cannot allocate an output much larger than limit before the budget trips. Cycle handling is identical to Inspect.

func (Value) InspectByteLenBounded ¶ added in v0.60.0

func (v Value) InspectByteLenBounded(step func() error) (int, error)

InspectByteLenBounded reports the number of bytes Inspect would produce for v without materializing the rendering, so callers can bound an allocation before it happens. It walks composites with the same cycle detection Inspect uses and invokes step once per node visited, so a caller can charge a sandbox step budget against the traversal and abort it when step returns an error. The first error step reports stops the walk and is returned alongside the partial count. See StringByteLenBounded for why driving step from inside the walk matters for shared-but-acyclic graphs. It is intended for the interpreter's internal use; hosts should not call it, and it carries no compatibility promise (see docs/embedding-api-stability.md).

func (Value) Instance ¶

func (v Value) Instance() InstancePayload

Instance returns the underlying instance payload of v, or nil if v is not an instance. The concrete type is private to the runtime; callers operate through the InstancePayload marker.

func (Value) Int ¶

func (v Value) Int() int64

Int returns the integer content of v, coercing from float if needed. An integer outside the int64 range (IsBigInt) returns 0, the same fallback a wrong-kind value gets — never a truncated or wrapped result. Callers that must handle big integers use BigInt (or IsBigInt to detect them first).

func (Value) IsBigInt ¶ added in v0.60.0

func (v Value) IsBigInt() bool

IsBigInt reports whether v is an integer whose value lies outside the int64 range (and therefore carries a big-integer payload). Int64-range integers always use the compact representation, so IsBigInt is equivalent to "this integer does not fit in an int64".

func (Value) IsNil ¶

func (v Value) IsNil() bool

IsNil reports whether v is a nil value.

func (Value) Kind ¶

func (v Value) Kind() ValueKind

Kind returns the ValueKind of v.

func (Value) Money ¶

func (v Value) Money() Money

Money returns the money content of v, or a zero Money if v is not money.

func (Value) Range ¶

func (v Value) Range() Range

Range returns the range content of v, or a zero Range if v is not a range.

func (Value) RangeTypedHashEntries ¶

func (v Value) RangeTypedHashEntries(visit func(lookupKey HashLookupKey, entry HashEntry))

RangeTypedHashEntries calls visit for each typed entry of v in place, without materializing an intermediate slice. It is a no-op for non-hash values and for hashes still using the legacy string-key map. Callers that only need a read-only pass over entries (memory estimation) use it to avoid the per-call slice TypedHashEntriesInto allocates for a hash larger than the caller's buffer. Because it holds no shared state it is safe to nest, which a buffer-reusing variant would not be. It is intended for the interpreter's internal use; hosts should not call it, and it carries no compatibility promise (see docs/embedding-api-stability.md).

func (Value) Regex ¶ added in v0.60.0

func (v Value) Regex() Regex

Regex returns the regex payload of v. It panics when v is not a regex, like the other kind accessors.

func (Value) ReserveHashOrder ¶ added in v0.60.0

func (v Value) ReserveHashOrder(n int)

ReserveHashOrder pre-sizes the insertion-order backing to capacity n so a builder that knows its final entry count avoids the append growth overshoot, where a hash of 3 entries would otherwise retain 4 order slots. This keeps the backing's capacity equal to the entry count the memory-quota projection charges. It does not initialize typed-entry storage, so hash literals can reserve order capacity without allocating typed buckets before their per-entry accounting runs. It is a no-op when v is not a hash, n is non-positive, or the backing already has at least n slots. It is intended for the interpreter's internal use; hosts should not call it, and it carries no compatibility promise (see docs/embedding-api-stability.md).

func (Value) ReserveTypedHashOrder ¶

func (v Value) ReserveTypedHashOrder(n int)

ReserveTypedHashOrder prepares an empty hash builder for typed-key writes and reserves its insertion-order backing. It preserves a materialized legacy map when one already exists, which keeps Hash() callers synchronized as HashSet populates typed entries. It is a no-op for non-hashes, negative capacities, or legacy hashes that already contain entries. It is intended for the interpreter's internal use; hosts should not call it, and it carries no compatibility promise (see docs/embedding-api-stability.md).

func (Value) SetArrayElems ¶ added in v0.60.0

func (v Value) SetArrayElems(elems []Value)

SetArrayElems replaces the element slice of an existing array wrapper in place. It is the primitive behind the runtime's Ruby-style mutators: because the wrapper is shared by every Value that aliases the array, the new elements are visible through all of them. It is a no-op when v is not an array. It is intended for the interpreter's internal use; hosts should not call it, and it carries no compatibility promise (see docs/embedding-api-stability.md).

func (Value) SetHashDefaults ¶

func (v Value) SetHashDefaults(defaultValue, defaultProc Value)

SetHashDefaults overwrites the Ruby-style default metadata of an existing hash wrapper in place. It exists so a deep clone can register the destination wrapper in its seen-set before it walks the default value/proc: a default that reaches the hash itself (e.g. Hash.new { |_, _| h }) then dedups against the already-registered wrapper instead of cloning a second one whose defaults would close over the wrong object. v must be a hash whose wrapper is not yet shared; mutating a hash that other Values observe would change their defaults. It is intended for the interpreter's internal use; hosts should not call it, and it carries no compatibility promise (see docs/embedding-api-stability.md).

func (Value) String ¶

func (v Value) String() string

String returns the string representation of v.

package main

import (
	"fmt"

	"github.com/mgomes/vibescript/vibes/value"
)

func main() {
	v := value.NewString("hello")
	fmt.Println(v.String())
}

Output:
hello

func (Value) StringBounded ¶ added in v0.60.0

func (v Value) StringBounded(limit int) (string, error)

StringBounded renders v like String but stops once the formatted output would exceed limit bytes, returning the partial output and ErrStringRenderTruncated. A non-positive limit means unbounded and behaves exactly like String. Rendering writes directly into a single growing buffer and checks the budget after each element, so a hostile composite cannot allocate intermediate per-element strings or a final joined buffer larger than roughly limit plus one element before the limit trips. Cycle handling is identical to String.

func (Value) StringByteLen ¶ added in v0.60.0

func (v Value) StringByteLen() int

StringByteLen returns the number of bytes String would produce for v without materializing the rendered representation. Callers that must bound an allocation before it happens (such as the sandbox's interpolation memory guard) use it to reject an oversized rendering instead of building the string first and only then observing that it exceeded a quota. The byte count walks arrays and hashes with the same cycle detection String uses, so the projection matches the eventual output exactly. It is intended for the interpreter's internal use; hosts should not call it, and it carries no compatibility promise (see docs/embedding-api-stability.md).

func (Value) StringByteLenBounded ¶ added in v0.60.0

func (v Value) StringByteLenBounded(step func() error) (int, error)

StringByteLenBounded reports the same byte count as StringByteLen but invokes step once per node visited during the projection walk, so a caller can charge a sandbox step budget against the traversal and abort it when step returns an error. The first error step reports stops the walk and is returned unchanged alongside the partial count.

StringByteLen's cycle detection only collapses references that are currently on the recursion stack: a shared but acyclic graph (for example the result of repeatedly evaluating a = [a, a], where each level holds two references to the same child slice) is fully re-walked at every occurrence, so the traversal is exponential in the nesting depth even though the value's memory and its eventual rendering both stay bounded by the cycle marker. The memory quota alone cannot bound that work because it is checked only after the walk completes. Driving step from inside the walk lets the step quota trip during the traversal instead of letting it run unbounded. It is intended for the interpreter's internal use; hosts should not call it, and it carries no compatibility promise (see docs/embedding-api-stability.md).

func (Value) StringByteLenBoundedUpTo ¶ added in v0.60.0

func (v Value) StringByteLenBoundedUpTo(limit int, step func() error) (count int, truncated bool, err error)

StringByteLenBoundedUpTo reports String's byte length up to limit bytes. It stops as soon as it can prove the rendering would exceed limit, returning truncated as true and limit+1 as the count. Like StringByteLenBounded, it invokes step during aggregate walks so callers can charge sandbox work before materializing any rendering. It is intended for the interpreter's internal use; hosts should not call it, and it carries no compatibility promise (see docs/embedding-api-stability.md).

func (Value) StringRuneLen ¶ added in v0.60.0

func (v Value) StringRuneLen() int

StringRuneLen returns the number of runes String would produce for v without materializing the rendered representation. It mirrors StringByteLen but counts display width in the unit fmt uses for string precision and padding. It is intended for the interpreter's internal use; hosts should not call it, and it carries no compatibility promise (see docs/embedding-api-stability.md).

func (Value) StringRuneLenBounded ¶ added in v0.60.0

func (v Value) StringRuneLenBounded(step func() error) (int, error)

StringRuneLenBounded reports the same rune count as StringRuneLen but invokes step once per node visited during the projection walk, matching StringByteLenBounded's sandbox accounting. It is intended for the interpreter's internal use; hosts should not call it, and it carries no compatibility promise (see docs/embedding-api-stability.md).

func (Value) Time ¶

func (v Value) Time() time.Time

Time returns the time content of v, or a zero time if v is not a time.

func (Value) Truthy ¶

func (v Value) Truthy() bool

Truthy reports whether v is considered true in a boolean context.

func (Value) TypedHashEntriesInto ¶

func (v Value) TypedHashEntriesInto(buf []TypedHashEntry) []TypedHashEntry

TypedHashEntriesInto appends typed hash entries and their stored lookup keys into buf. It returns nil for non-hash values and hashes that still use only the legacy string-key map. It is intended for the interpreter's internal use; hosts should not call it, and it carries no compatibility promise (see docs/embedding-api-stability.md).

func (Value) WriteInspectTo ¶ added in v0.60.0

func (v Value) WriteInspectTo(buf *strings.Builder)

WriteInspectTo streams the same bytes Inspect would return for v directly into buf, without first materializing the rendered representation as a separate string. It mirrors WriteStringTo: callers that have already bounded the rendering against a quota (such as the sandbox's inspect memory guard, which reserves the projected length before calling) use it to render straight into a builder they grew to the projected size, so the peak allocation stays the single backing array the quota already charged rather than the doubling growth a fresh zero-capacity builder would take. It delegates to the unbounded inspect renderer, so writing into a strings.Builder never fails. It is intended for the interpreter's internal use; hosts should not call it, and it carries no compatibility promise (see docs/embedding-api-stability.md).

func (Value) WriteStringTo ¶ added in v0.60.0

func (v Value) WriteStringTo(buf *strings.Builder)

WriteStringTo streams the same bytes String would return for v directly into buf, without first materializing the rendered representation as a separate string. Callers that have already bounded the rendering against a quota (such as the sandbox's interpolation memory guard, which reserves the projected length before calling) use it to stream an aggregate straight into their builder instead of allocating the full rendering and then copying it, which would transiently hold both the temporary and the destination copy and could exceed a memory limit the projected length already passed. It delegates to the unified unbounded renderer, so writing into a strings.Builder never fails. It is intended for the interpreter's internal use; hosts should not call it, and it carries no compatibility promise (see docs/embedding-api-stability.md).

func (ValueKind) String ¶

func (k ValueKind) String() string

String returns the human-readable name of the ValueKind.