Struct NixAttrs 

pub struct NixAttrs(/* private fields */);

A Nix attribute set with lazy overlay support.

Internally uses either a concrete compact AttrsMap or a lazy overlay chain. The // operator creates O(1) overlay nodes instead of O(m log n) merges. Attribute access walks the chain right-to-left in O(depth). Full iteration (attrNames, attrValues) flattens on demand.

The second tuple field is an OPTIONAL source-position table (None for the vast majority of attrsets — merges, overlays, builtin-built, dynamic keys). eval_attrset attaches it for a literal with static keys so builtins.unsafeGetAttrPos can report a key’s file/line/column (the attrTag declarations — options.json dock root). It is behind Rc, so a clone is a refcount bump; None costs one pointer-sized word.

Implementations

impl NixAttrs

pub fn new() -> Self

pub fn with_capacity(_capacity: usize) -> Self

pub fn set_positions(&mut self, pos: Rc<AttrPositions>)

Attach a source-position table (the static keys’ byte offsets of the literal that built this attrset). Called by eval_attrset; consumed by builtins.unsafeGetAttrPos. Never affects any observed value.

pub fn positions(&self) -> Option<&Rc<AttrPositions>>

The source-position table, if this attrset carries one (a literal with static keys). None for merges/overlays/builtin-built/dynamic-key attrsets.

pub fn pos_for(&self, key: &str) -> Option<ResolvedPos>

Resolve the source position of key in this attrset — the file/line/ column builtins.unsafeGetAttrPos returns. None when the attrset has no position table, the key is absent from it, or the source has no file (a <string>-eval’d literal).

pub fn inner(&self) -> AttrsMap<Symbol, Value>

Borrow the underlying map. Flattens if overlay.

pub fn get(&self, key: &str) -> Option<&Value>

Look up an attribute by name. Walks overlay chain right-to-left.

pub fn get_sym(&self, sym: &Symbol) -> Option<&Value>

Look up by pre-interned Symbol.

Fast path: if the overlay’s flat cache has been populated (by any prior full iteration — attrNames, attrValues, // merge that needed key enumeration, etc.), read directly from it in O(1). This matters in real Nix workloads where an attrset is first iterated (module eval, with desugaring) and then hit many times by dotted access — CppNix has no such structure and pays O(1) always; we want to match that whenever the cache is warm.

Slow path: walk the overlay chain right-to-left in O(depth). Not populating the cache on cold lookups is deliberate — the cache costs O(n) to build and the chain is usually short (1–3 overlays).

pub fn insert(&mut self, key: String, value: Value)

Insert or overwrite an attribute. Flattens overlay if needed.

pub fn contains_key(&self, key: &str) -> bool

pub fn contains_key_sym(&self, sym: &Symbol) -> bool

pub fn keys(&self) -> impl Iterator<Item = String>

pub fn iter(&self) -> impl Iterator<Item = (String, &Value)>

pub fn iter_unsorted(&self) -> impl Iterator<Item = (String, &Value)>

pub fn iter_syms(&self) -> impl Iterator<Item = (Symbol, &Value)>

Sym-keyed unsorted iteration — ZERO interner traffic, zero allocation.

This exists because live-sampling the cid marquee eval (2026-07-21, release-profiling binary) showed the interner round-trip as the #1 CPU sink — 27–39% of the eval thread, sustained: iter_unsorted above materializes a fresh heap String per key via resolve AND collects the whole map into a Vec on every call, and callers like intersectAttrs then re-intern each of those Strings straight back to the Symbol they started as (contains_key(&str) → intern), with a third intern inside insert. Sym→String→hash+memcmp→Sym, three times per key per call, at nixpkgs scale.

Symbol is Copy(u32) and as_flat() hands back a real borrow (the Overlay case populates its cache), so this iterator borrows instead of collecting. Byte-neutral by the same argument already sealed for the unsorted-iteration change: the observable order of any result attrset is re-derived at observation time via sorted_entries.

pub fn insert_sym(&mut self, sym: Symbol, value: Value)

Sym-keyed insert — the zero-intern sibling of insert, for callers that already hold the Symbol (every iter_syms consumer).

pub fn values(&self) -> impl Iterator<Item = &Value>

pub fn remove(&mut self, key: &str) -> Option<Value>

pub fn len(&self) -> usize

pub fn is_empty(&self) -> bool

pub fn overlay(self, other: NixAttrs) -> NixAttrs

O(1) lazy overlay: self // other. Does NOT merge eagerly.

pub fn update(&self, other: &NixAttrs) -> NixAttrs

Eager merge (legacy API — prefer overlay for //).

Trait Implementations

impl Clone for NixAttrs

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for NixAttrs

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for NixAttrs

fn default() -> Self

Returns the “default value” for a type.

impl Drop for NixAttrs

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl From<NixAttrs> for Value

fn from(attrs: NixAttrs) -> Self

Converts to this type from the input type.

impl FromIterator<(String, Value)> for NixAttrs

fn from_iter<I: IntoIterator<Item = (String, Value)>>(iter: I) -> Self

Creates a value from an iterator.

impl IntoIterator for NixAttrs

type Item = (String, Value)

The type of the elements being iterated over.

type IntoIter = Box<dyn Iterator<Item = (String, Value)>>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.