Value
Table of Contents
Interfaces
- DXNValueInterface
- Implemented by every `DXN*` wrapper class -- the PHP analog of the
`dxnType` string tag used for kind dispatch in the JS port, and of
`Dextrin.Value`'s closed type union in the Elixir original. Native
PHP values (`null`, `bool`, `int`, `float`, `string`, and `array`
for `map`/`array`) never implement this; {@see Equality::kindOf()}
handles those directly.
Classes
- DXNBytes
- DXN `bytes` (`@bytes "..."`, base64 in text) -- raw binary data.
- DXNChar
- DXN `char` (`?a`) -- a single Unicode codepoint, distinct from a
1-codepoint `string`.
- DXNCustomTag
- DXN `custom-tag` (`@tag value`) -- the open extension point, no
decoder registered for `name`.
- DXNDate
- DXN `date` (`~D[YYYY-MM-DD]`) -- a bare calendar date, ISO 8601.
- DXNDateTime
- DXN `datetime` (`@datetime "..."`) -- an offset-aware instant,
non-UTC. Mirrors `.dxnb`'s wire shape directly: an instant plus an
informational offset. Same exact (not lossy) microsecond-precision
conversion as {@see DXNTimestamp}.
- DXNDecimal
- DXN `decimal` (`19.99M`) -- an exact fixed-point number, `sign *
unscaledValue * 10^exponent`. `unscaledValue` is always a numeric
string (bcmath-formatted), independent of the top-level integer
hybrid rule ({@see DXNInteger}) -- exact decimal arithmetic needs
bcmath regardless of magnitude, so there's no native-`int` fast
path to preserve here the way there is for a bare `integer`.
- DXNDuration
- DXN `duration` (`@duration "P1Y2M"`) -- 7 independent, individually
optional fields, not reducible to one scalar. No conversion helper:
PHP's `DateInterval` exists, but normalizes `P1W` into `days = 7`
internally, losing the weeks/days distinction DXN keeps
independent -- not a clean conversion target.
- DXNInteger
- An arbitrary-precision integer, backed by `bcmath` (no `ext-gmp`
assumed available) -- only ever constructed for a magnitude outside
`PHP_INT_MIN..PHP_INT_MAX`. {@see DXNInteger::represent()} is the
canonical entry point embodying the project's hybrid integer rule:
a value that fits stays a native `int` everywhere (ordinary `+`,
`-`, comparisons just work); only genuine overflow reaches this
class, whose own arithmetic is method calls, not operators -- PHP
has no operator overloading for arithmetic.
- DXNKeyword
- DXN `keyword` (`:foo` / `foo:` in key position) -- always wraps in
this port, with no `trusted:`-driven alternate representation the
way the Elixir (real atom) and JS (`Symbol.for`) ports have. PHP
has nothing analogous to a BEAM atom table or `Symbol.for`'s global
registry: every `DXNKeyword` is an ordinary heap-allocated, GC'd
object, so there's no exhaustible interning table decoding
untrusted input could ever threaten in the first place -- this is
a deliberate omission, not a missing feature.
- DXNList
- DXN `list` (`[1 2 3]`) -- wrapped so it stays distinct from `array`
(`@array[...]`), which claims the bare sequential-PHP-array shape
instead (see the project's collections decision: PHP's `array`
only offers one structural fork, sequential-vs-associative, so it
can't safely host two DXN types).
- DXNOrderedMap
- DXN `ordered-map` (`@ordered %{...}`) -- order is part of value
identity. Wrapped rather than a bare associative PHP array (which
already claims `map`, the no-ordering-guarantee sibling) so the two
stay distinguishable on encode; also because a DXN map/ordered-map
key can be any DXN value, not just an `int|string` the way a native
PHP array key must be.
- DXNRational
- DXN `rational` (`22/7`) -- an exact ratio, never auto-reduced (`4/2`
and `2/1` are structurally distinct values, same as the Elixir and
JS ports). `numerator`/`denominator` are numeric strings, same
"always bcmath, regardless of magnitude" rule as {@see DXNDecimal}.
- DXNRegex
- DXN `regex` (`~r/pattern/flags`) -- PCRE-style semantics (matching
Erlang `:re`/Elixir `Regex`, per `dxn/DXN.md` ยง2.3), which happens
to make PHP's own PCRE-backed `preg_*` a *better* native fit than
JS's `RegExp` had: DXN's `x` (extended) and `r` (ungreedy) flags
both have real PHP modifier equivalents (`r` maps to PHP's
uppercase `U`, distinct from lowercase `u`/unicode) where JS had
neither. Only `f` (firstline) has no PHP preg modifier to reach
for, so {@see self::toPcrePattern()} is guarded on that alone, not
on `x`/`f`/`r` wholesale.
- DXNSet
- DXN `set` (`@{...}`) -- deduplicated at construction, structural
equality, order-independent.
- DXNSortedSet
- DXN `sorted-set` (`@sorted-set @{...}`) -- sorted and deduplicated
at every construction site, same invariant enforced in the Elixir
and JS ports. Cross-type ordering is implementation-defined per
DXN.md; this port's fixed rank order is {@see Equality}'s own.
- DXNStruct
- DXN `struct` (`%Name{...}` / `%Name[...]`), opaque without a
schema. Keeps the keyed/positional shapes distinct rather than
normalizing to one, same as the Elixir and JS ports -- `.dxnb` is
always positional and can't recover field names without a schema.
- DXNSymbol
- DXN `symbol` (a bare identifier, e.g. `foo`) -- an unevaluated
reference, e.g. a type name. Always wraps: PHP has no "evaluated
later" bare-identifier native type, and no interning table whose
exhaustion decoding untrusted input would need to guard against
either way.
- DXNTime
- DXN `time` (`~T[HH:MM:SS(.ffffff)?]`) -- a bare time of day, ISO
8601. No conversion helper: PHP has no native "time of day" type to
convert to/from without a synthetic, misleading date component.
- DXNTimestamp
- DXN `timestamp` (`~U[YYYY-MM-DD HH:MM:SSZ]`) -- a UTC instant.
- DXNTuple
- DXN `tuple` (`{1 2 3}`) -- list-backed, arbitrary length.
- DXNUri
- DXN `uri` (`@uri "..."`) -- a raw string, not parsed, same
round-trip-safety rationale as the Elixir and JS ports.
- DXNUuid
- DXN `uuid` (`@uuid "..."`) -- 16 raw bytes, RFC 4122. PHP strings
are binary-safe natively, so the raw-bytes field itself needs no
`Uint8Array`-style wrapper the way JS needed one.
- Equality
- Shared structural equality/ordering kernel backing every DXN value,
native and wrapped alike -- the PHP analog of the JS port's
`src/values/equality.cjs`. `kindOf()` dispatches on
{@see DXNValueInterface::dxnType()} for wrapped classes, PHP's own
native types for scalars, `array_is_list()` to split `array`/`map`,
and "any other object" (a plain object with public properties,
`stdClass` or otherwise) as `struct` -- the encode-side convenience
described in the project's own value-model mapping.