Struct NodeRef

Source

pub struct NodeRef<'doc> { /* private fields */ }

Expand description

A borrowed reference to a YAML node.

NodeRef<'doc> provides zero-copy access to node data. The lifetime 'doc ties the reference to its parent Document, ensuring the node cannot outlive the document.

§Zero-Copy Scalar Access

Scalar data is accessed directly from libfyaml’s internal buffers:

use fyaml::Document;

let doc = Document::parse_str("key: value").unwrap();
let root = doc.root().unwrap();
let value = root.at_path("/key").unwrap();

// This returns &'doc str - zero allocation!
let s: &str = value.scalar_str().unwrap();
assert_eq!(s, "value");

Navigate the tree using paths or iteration:

use fyaml::Document;

let doc = Document::parse_str("users:\n  - name: Alice\n  - name: Bob").unwrap();
let root = doc.root().unwrap();

// Path navigation
let first_user = root.at_path("/users/0/name").unwrap();
assert_eq!(first_user.scalar_str().unwrap(), "Alice");

// Iteration
let users = root.at_path("/users").unwrap();
for user in users.seq_iter() {
    println!("{}", user.at_path("/name").unwrap().scalar_str().unwrap());
}

§Thread Safety

NodeRef is !Send and !Sync because the underlying document is not thread-safe.

Implementations§

Source §

impl<'doc> NodeRef<'doc>

Source

pub fn document(&self) -> &'doc Document

Returns a reference to the parent document.

Source

pub fn kind(&self) -> NodeType

Returns the type of this node.

Source

pub fn is_scalar(&self) -> bool

Returns true if this node is a scalar value.

Source

pub fn is_mapping(&self) -> bool

Returns true if this node is a mapping (dictionary).

Source

pub fn is_sequence(&self) -> bool

Returns true if this node is a sequence (list).

Source

pub fn style(&self) -> NodeStyle

Returns the style of this node.

For scalar nodes, this indicates quoting style (plain, single-quoted, etc.). For sequences/mappings, this indicates flow vs block style.

Source

pub fn is_quoted(&self) -> bool

Returns true if this scalar was quoted (single or double quotes).

Source

pub fn is_non_plain(&self) -> bool

Returns true if this scalar has a non-plain style.

Non-plain styles include single-quoted, double-quoted, literal (|), and folded (>). These styles should prevent type inference (the value should be treated as a string, not inferred as bool/int/null).

Source

pub fn scalar_bytes(&self) -> Result<&'doc [u8]>

Returns the scalar value as a byte slice (zero-copy).

The returned slice points directly into libfyaml’s internal buffer. It is valid for the lifetime 'doc of the document.

§Errors

Returns an error if this is not a scalar node.

§Example

use fyaml::Document;

let doc = Document::parse_str("data: hello").unwrap();
let node = doc.at_path("/data").unwrap();
assert_eq!(node.scalar_bytes().unwrap(), b"hello");

Source

pub fn scalar_str(&self) -> Result<&'doc str>

Returns the scalar value as a string slice (zero-copy).

The returned string points directly into libfyaml’s internal buffer. It is valid for the lifetime 'doc of the document.

§Errors

Returns an error if this is not a scalar node or if the content is not valid UTF-8.

§Example

use fyaml::Document;

let doc = Document::parse_str("name: Alice").unwrap();
let name = doc.at_path("/name").unwrap().scalar_str().unwrap();
assert_eq!(name, "Alice");

Source

pub fn tag_bytes(&self) -> Result<Option<&'doc [u8]>>

Returns the YAML tag as a byte slice (zero-copy).

Returns Ok(None) if the node has no explicit tag.

Source

pub fn tag_str(&self) -> Result<Option<&'doc str>>

Returns the YAML tag as a string slice (zero-copy).

Returns Ok(None) if the node has no explicit tag.

Source

pub fn at_path(&self, path: &str) -> Option<NodeRef<'doc>>

Navigates to a child node by path.

Path format uses / as separator:

/foo - access key “foo” in a mapping
/0 - access index 0 in a sequence
/foo/bar/0 - nested access
`` (empty) - returns self

Returns None if the path doesn’t exist.

§Example

use fyaml::Document;

let doc = Document::parse_str("a:\n  b:\n    c: deep").unwrap();
let deep = doc.root().unwrap().at_path("/a/b/c").unwrap();
assert_eq!(deep.scalar_str().unwrap(), "deep");

Source

pub fn seq_len(&self) -> Result<usize>

Returns the number of items in a sequence node.

§Errors

Returns an error if this is not a sequence.

Source

pub fn map_len(&self) -> Result<usize>

Returns the number of key-value pairs in a mapping node.

§Errors

Returns an error if this is not a mapping.

Source

pub fn seq_get(&self, index: i32) -> Option<NodeRef<'doc>>

Gets a sequence item by index.

Returns None if the index is out of bounds or this is not a sequence. Negative indices count from the end (-1 is the last element).

Source

pub fn seq_iter(&self) -> SeqIter<'doc> ⓘ

Returns an iterator over items in a sequence node.

If this is not a sequence, the iterator will be empty.

§Example

use fyaml::Document;

let doc = Document::parse_str("- a\n- b\n- c").unwrap();
let root = doc.root().unwrap();

let items: Vec<&str> = root.seq_iter()
    .map(|n| n.scalar_str().unwrap())
    .collect();
assert_eq!(items, vec!["a", "b", "c"]);

Source

pub fn map_get(&self, key: &str) -> Option<NodeRef<'doc>>

Looks up a value in this mapping by string key.

Returns None if the key is not found or this is not a mapping.

Source

pub fn map_iter(&self) -> MapIter<'doc> ⓘ

Returns an iterator over key-value pairs in a mapping node.

If this is not a mapping, the iterator will be empty.

§Example

use fyaml::Document;

let doc = Document::parse_str("a: 1\nb: 2").unwrap();
let root = doc.root().unwrap();

for (key, value) in root.map_iter() {
    println!("{}: {}", key.scalar_str().unwrap(), value.scalar_str().unwrap());
}

Source