Skip to main content

Module value

Module value 

Source
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 nodeF32 (the bit pattern)
float from a double nodeF64 (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 primitivePrims (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 ValueBuilder made, 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 the Parsed (ValueBuilder::finish), each of which takes the charge along, and dropped anywhere the two go together.
Map
A dict in insertion order with PyDict_SetItem semantics. Built whole (ValueBuilder::map, or Map::from_entries for 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).
ValueBuilder
Builds one object’s value on its input’s meter: the reader’s only way to make a Parsed (plan section 3.10).

Enums§

PrimArray
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_typetree picks UnityPyBoost’s for an object of byte_size > 0 and the pure-Python one for byte_size == 0 (helpers/TypeTreeHelper.py:146-153). Each reads some trees its own way (CANONICAL_DUMP.md section 7), and crate::walk::WriteRules::MirrorReader writes 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::NodeList in Parsed::lists: the root tree’s list, then one per distinct ref-type tree a ReferencedObject read through (deduplicated by Arc pointer, so the count is bounded by the file’s ref types, which the input’s meter bounds, and which can pass u16). A u32 costs nothing: Map stays 32 bytes.