Expand description
The dynamic value: UnityPy’s parse_as_dict() model, made self-describing.
Each variant is one Python type with the distinctions the canonical dump
keeps (docs/CANONICAL_DUMP.md section 3), so the encoder and the Python
conversion need no typetree, only the names:
| UnityPy (Boost path) | Value |
|---|---|
int (any width, bool apart) | Int, or UInt above i64::MAX |
float from a float node | F32 (the bit pattern) |
float from a double node | F64 (the bit pattern) |
str (surrogate-escaped) | Str (the raw bytes) |
bytes (TypelessData) | Bytes (a zero-copy slice of the file) |
list read as one run of a primitive | Prims (vector<UInt8>/char as zero-copy bytes) |
any other list (classes, strings, pairs, vectors) | List |
tuple (pair; the pure-Python path’s aligned primitive arrays) | Tuple |
dict (insertion order, PyDict_SetItem) | Dict |
Dict keys are NodeIds of the crate::typetree::NodeList the map was read with, so a
field costs no allocation and no reference count. A Parsed holds those
lists: the root tree’s first, then each ref-type tree a ReferencedObject
read through. Map::list says which list a map’s keys belong to.
Memory. A Parsed carries the Charge for every allocation its
value holds (each list, map, tuple and primitive run, at
crate::limits::heap_cost of its capacity, and the table of its node
lists), charged to the input’s meter by the reader before it allocated
them. Dropping the Parsed returns them, so values a caller keeps count
against the input’s bound for as long as they are kept. So the value
cannot leave its charge: Parsed is not Clone, its value is reached
by reference only (Parsed::value), and Value is not Clone either
(a deep copy would be an uncharged allocation the size of the input’s
value). The reader builds every list, map, tuple and run through a
ValueBuilder, the one metered path; Map has no growth method.
A built value travels with its charge. The builder hands each list,
map, tuple and run back as a Built: the value and the charge for its
heap, which no public method separates. A Built goes into its parent’s
metered vector (MeteredVec::push_built, MeteredVec::push_entry,
MeteredVec::set_entry), which takes its charge along, or into the
Parsed (ValueBuilder::finish); dropped anywhere, its value and its
charge go together. So no value the builder made can outlive its charge,
whenever the builder itself is dropped (round 5: the builder kept every
charge until finish, and a value taken before a builder was dropped
lived on uncharged).
What the types pin, and what a test pins. A Parsed has no public
constructor: ValueBuilder::finish is the only way to one, so every
Parsed holds the charges of what it holds. A caller’s own value (one to
write, a test’s) goes through a builder too, on Meter::unlimited when
it is not an input’s; ValueBuilder::scalar wraps a value that owns no
heap, and refuses a list, map, tuple or run that owns an allocation. It
cannot refuse a Str or Bytes that owns a plain Vec, since a
bytes::Bytes does not say whether it is a slice of a charged buffer
(the file’s, crate::RawStr::charged, a decoded block’s) or owns
memory no meter saw, so a string or bytes passed to it must be such a
slice (round 6). Value’s variants are public data,
though, so the types cannot prove that a value pushed into a vector as a
plain Value owns no uncharged heap (a List made from a plain Vec).
That the reader never does that is its discipline, checked by package
B’s counting-allocator test (plan section 7.3), as tests/memory_model.rs
checks the builder itself.
The snippets below must not compile. Stable rustdoc does not check a
compile_fail test’s error code, so each is written to fail one way
only: the item it names is missing, private or not Clone.
// The value cannot be moved out of its `Parsed` (round 3: the charge
// dropped with the rest of the `Parsed` while the value lived on).
fn take(p: unityrs_core::Parsed) -> unityrs_core::Value {
p.value
}// Nor copied without a charge: `Value` is not `Clone`.
fn clone<T: Clone>() {}
clone::<unityrs_core::Value>();fn clone<T: Clone>() {}
clone::<unityrs_core::Parsed>();fn clone<T: Clone>() {}
clone::<unityrs_core::Map>();fn clone<T: Clone>() {}
clone::<unityrs_core::PrimArray>();// A map does not grow outside the reader's metered builder.
let _ = unityrs_core::Map::push_unique;// Not by insertion either (a test-only helper inside the crate).
let _ = unityrs_core::Map::insert;// Nor is one allocated at an unmetered capacity.
let _ = unityrs_core::Map::with_capacity;// A `Parsed` is not assembled from charges the caller picked, with any
// arguments: the reader finishes a `ValueBuilder`.
let _ = unityrs_core::Parsed::new;// Nor without a charge (round 4): a caller's value goes through a
// builder on `Meter::unlimited()`.
let _ = unityrs_core::Parsed::unmetered;// A built value does not leave its charge (round 5): its fields are
// private, and no method moves the value out.
fn take(b: unityrs_core::value::Built) -> unityrs_core::Value {
b.value
}let _ = unityrs_core::value::Built::into_value;// What the snippets above refuse, a caller does this way.
use unityrs_core::limits::Meter;
use unityrs_core::typetree::{NodeList, NodeRow};
use unityrs_core::{Value, ValueBuilder};
let root = NodeList::trusted(vec![NodeRow::new(0, "int", "v")]).unwrap().into_shared().unwrap();
let b = ValueBuilder::new(&Meter::unlimited(), root).unwrap();
let mut items = b.vec();
items.push(Value::Int(1)).unwrap();
let list = b.list(items);
let p = b.finish(list, 4);
assert_eq!(p.value(), &Value::List(vec![Value::Int(1)]));Owner: the scaffold (implemented types and helpers); package B may add methods and fast paths but not change these signatures.
Structs§
- Built
- A list, map, tuple or primitive run a
ValueBuildermade, with the charge for its heap (module docs). No public method separates the two: the value goes on only into a parent’s metered vector (MeteredVec::push_built,MeteredVec::push_entry,MeteredVec::set_entry) or into theParsed(ValueBuilder::finish), each of which takes the charge along, and dropped anywhere the two go together. - Map
- A dict in insertion order with
PyDict_SetItemsemantics. Built whole (ValueBuilder::map, orMap::from_entriesfor a value a caller makes), never grown in place. - Parsed
- One object’s value, the node lists that name its keys, the reader that built it, and the charge for the value’s memory and the lists’ table (module docs).
- Value
Builder - Builds one object’s value on its input’s meter: the reader’s only way to
make a
Parsed(plan section 3.10).
Enums§
- Prim
Array - A run of primitives, decoded to native values (floats as bit patterns).
- PrimRun
- A primitive run, as the reader collects it, for
ValueBuilder::prims. - ReadBy
- Which of UnityPy’s two readers built a value:
read_typetreepicks UnityPyBoost’s for an object ofbyte_size > 0and the pure-Python one forbyte_size == 0(helpers/TypeTreeHelper.py:146-153). Each reads some trees its own way (CANONICAL_DUMP.mdsection 7), andcrate::walk::WriteRules::MirrorReaderwrites a value as the reader that built it reads. - Value
- A value read through a typetree. Not
Clone(module docs).
Type Aliases§
- ListIx
- Index of a
crate::typetree::NodeListinParsed::lists: the root tree’s list, then one per distinct ref-type tree aReferencedObjectread through (deduplicated byArcpointer, so the count is bounded by the file’s ref types, which the input’s meter bounds, and which can passu16). Au32costs nothing:Mapstays 32 bytes.