Struct ItemBuf

pub struct ItemBuf<A = Global>
where
    A: Allocator,
{ /* private fields */ }

The name of an item in the Rune Language.

This is made up of a collection of strings, like ["foo", "bar"]. This is indicated in rune as foo::bar.

An item can also belongs to a crate, which in rune could be indicated as ::crate::foo::bar. These items must be constructed using ItemBuf::with_crate.

Items are inlined if they are smaller than 32 bytes.

Panics

The max length of a string component is is 2**14 = 16384. Attempting to add a string larger than that will panic. This also constitutes the maximum number of nested sibling components that can exist in a single source file since they all use anonymous identifiers.

Component encoding

The following details internal implementation details of an Item, and is not exposed through its API. It is provided here in case you need to work with the internal of an item.

A single component is encoded as:

• A two byte tag as a u16 in native endianess, indicating its type (least significant 2 bits) and data (most significant 14 bits).
• If the type is a STRING, the data is treated as the length of the string. Any other type this the data is treated as the numeric id of the component.
• If the type is a STRING, the tag is repeated at the end of it to allow for seeking backwards. This is not the case for other types. Since they are fixed size its not necessary.

So all in all, a string is encoded as this where the d part indicates the length of the string:

dddddddd ddddddtt *string content* dddddddd ddddddtt

And any other component is just the two bytes where the d part makes up a numerical component:

dddddddd ddddddtt

Implementations

impl<A> ItemBuf<A>

where A: Allocator,

pub fn push<C>(&mut self, c: C) -> Result<(), Error>

where C: IntoComponent,

Push the given component to the current item.

pub fn pop(&mut self) -> bool

Pop a the tail component, returning true if there was something to pop.

pub fn extend<I>(&mut self, i: I) -> Result<(), Error>

where I: IntoIterator, <I as IntoIterator>::Item: IntoComponent,

Extend the current item with an iterator.

pub fn clear(&mut self)

Clear the current item.

impl ItemBuf

pub const fn new() -> ItemBuf

Construct a new empty item.

Examples

use rune::ItemBuf;

let item = ItemBuf::new();
let mut it = item.iter();

assert_eq!(it.next(), None);

pub fn with_item( iter: impl IntoIterator, ) -> Result<ItemBuf, Error>

where <impl IntoIterator as IntoIterator>::Item: IntoComponent,

Construct a new item with the given path.

Examples

use rune::ItemBuf;
use rune::item::ComponentRef;

let item = ItemBuf::with_item(["foo", "bar"])?;
let mut it = item.iter();

assert_eq!(it.next(), Some(ComponentRef::Str("foo")));
assert_eq!(it.next(), Some(ComponentRef::Str("bar")));
assert_eq!(it.next(), None);

pub fn with_crate(name: &str) -> Result<ItemBuf, Error>

Construct item for a crate.

Examples

use rune::ItemBuf;
use rune::item::ComponentRef;

let mut item = ItemBuf::with_crate("std")?;
item.push("foo");
assert_eq!(item.as_crate(), Some("std"));

let mut it = item.iter();
assert_eq!(it.next(), Some(ComponentRef::Crate("std")));
assert_eq!(it.next(), Some(ComponentRef::Str("foo")));
assert_eq!(it.next(), None);

pub fn with_crate_item<I>(name: &str, iter: I) -> Result<ItemBuf, Error>

where I: IntoIterator, <I as IntoIterator>::Item: IntoComponent,

Create a crated item with the given name.

Examples

use rune::ItemBuf;
use rune::item::ComponentRef;

let item = ItemBuf::with_crate_item("std", ["option"])?;
assert_eq!(item.as_crate(), Some("std"));

let mut it = item.iter();
assert_eq!(it.next(), Some(ComponentRef::Crate("std")));
assert_eq!(it.next(), Some(ComponentRef::Str("option")));
assert_eq!(it.next(), None);

Methods from Deref<Target = Item>

pub fn as_bytes(&self) -> &[u8]

Return the underlying byte representation of the Item.

Examples

use rune::{Item, ItemBuf};

assert_eq!(Item::new().as_bytes(), b"");

let item = ItemBuf::with_item(["foo", "bar"])?;
assert_eq!(item.as_bytes(), b"\x0d\0foo\x0d\0\x0d\0bar\x0d\0");

pub fn as_crate(&self) -> Option<&str>

Get the crate corresponding to the item.

Examples

use rune::ItemBuf;

let item = ItemBuf::with_crate("std")?;
assert_eq!(item.as_crate(), Some("std"));

let item = ItemBuf::with_item(["local"])?;
assert_eq!(item.as_crate(), None);

pub fn first(&self) -> Option<ComponentRef<'_>>

Access the first component of this item.

Examples

use rune::ItemBuf;
use rune::item::ComponentRef;

let item = ItemBuf::with_item(["foo", "bar"])?;
assert_eq!(item.first(), Some(ComponentRef::Str("foo")));

pub fn is_empty(&self) -> bool

Check if the item is empty.

Examples

use rune::ItemBuf;

let item = ItemBuf::new();
assert!(item.is_empty());

let item = ItemBuf::with_crate("std")?;
assert!(!item.is_empty());

pub fn as_vec(&self) -> Result<Vec<Component>, Error>

Construct a new vector from the current item.

pub fn as_local(&self) -> Option<&str>

If the item only contains one element, return that element.

pub fn join( &self, other: impl IntoIterator, ) -> Result<ItemBuf, Error>

where <impl IntoIterator as IntoIterator>::Item: IntoComponent,

Return an owned and joined variant of this item.

Examples

use rune::Item;
use rune::item::ComponentRef;

let item = Item::new();
assert!(item.is_empty());

let item2 = item.join(["hello", "world"])?;
assert_eq!(item2.first(), Some(ComponentRef::Str("hello")));
assert_eq!(item2.last(), Some(ComponentRef::Str("world")));

pub fn extended<C>(&self, part: C) -> Result<ItemBuf, Error>

where C: IntoComponent,

Return an owned and extended variant of this item.

Examples

use rune::Item;
use rune::item::ComponentRef;

let item = Item::new();
assert!(item.is_empty());

let item2 = item.extended("hello")?;
assert_eq!(item2.first(), Some(ComponentRef::Str("hello")));

pub fn last(&self) -> Option<ComponentRef<'_>>

Access the last component in the path.

pub fn base_name(&self) -> Option<&str>

Access the base name of the item if available.

The base name is the last string component of the item.

pub fn iter(&self) -> Iter<'_>

An iterator over the Components that constitute this item.

Examples

use rune::ItemBuf;
use rune::item::{ComponentRef, IntoComponent};

let mut item = ItemBuf::new();

item.push("start")?;
item.push(ComponentRef::Id(1))?;
item.push(ComponentRef::Id(2))?;
item.push("middle")?;
item.push(ComponentRef::Id(3))?;
item.push("end")?;

let mut it = item.iter();

assert_eq!(it.next(), Some("start".as_component_ref()));
assert_eq!(it.next(), Some(ComponentRef::Id(1)));
assert_eq!(it.next(), Some(ComponentRef::Id(2)));
assert_eq!(it.next(), Some("middle".as_component_ref()));
assert_eq!(it.next(), Some(ComponentRef::Id(3)));
assert_eq!(it.next(), Some("end".as_component_ref()));
assert_eq!(it.next(), None);

assert!(!item.is_empty());

pub fn starts_with<U>(&self, other: U) -> bool

where U: AsRef<Item>,

Test if current item starts with another.

pub fn is_super_of<U>(&self, other: U, n: usize) -> bool

where U: AsRef<Item>,

Test if current is immediate super of other.

Examples

use rune::{Item, ItemBuf};

assert!(Item::new().is_super_of(Item::new(), 1));
assert!(!ItemBuf::with_item(["a"])?.is_super_of(Item::new(), 1));

assert!(!ItemBuf::with_item(["a", "b"])?.is_super_of(ItemBuf::with_item(["a"])?, 1));
assert!(ItemBuf::with_item(["a", "b"])?.is_super_of(ItemBuf::with_item(["a", "b"])?, 1));
assert!(!ItemBuf::with_item(["a"])?.is_super_of(ItemBuf::with_item(["a", "b", "c"])?, 1));

pub fn ancestry<U>(&self, other: U) -> Result<(ItemBuf, ItemBuf), Error>

where U: AsRef<Item>,

Get the ancestry of one module to another.

This returns three things:

• The shared prefix between the current and the other path.
• The suffix to get to the other path from the shared prefix.

Examples

use rune::{Item, ItemBuf};

assert_eq!(
    (ItemBuf::new(), ItemBuf::new()),
    Item::new().ancestry(Item::new())?
);

assert_eq!(
    (ItemBuf::new(), ItemBuf::with_item(["a"])?),
    Item::new().ancestry(ItemBuf::with_item(["a"])?)?
);

assert_eq!(
    (ItemBuf::new(), ItemBuf::with_item(["a", "b"])?),
    Item::new().ancestry(ItemBuf::with_item(["a", "b"])?)?
);

assert_eq!(
    (ItemBuf::with_item(["a"])?, ItemBuf::with_item(["b"])?),
    ItemBuf::with_item(["a", "c"])?.ancestry(ItemBuf::with_item(["a", "b"])?)?
);

assert_eq!(
    (ItemBuf::with_item(["a", "b"])?, ItemBuf::with_item(["d", "e"])?),
    ItemBuf::with_item(["a", "b", "c"])?.ancestry(ItemBuf::with_item(["a", "b", "d", "e"])?)?
);

pub fn parent(&self) -> Option<&Item>

Get the parent item for the current item.

Examples

use rune::ItemBuf;

let item = ItemBuf::with_item(["foo", "bar", "baz"])?;
let item2 = ItemBuf::with_item(["foo", "bar"])?;

assert_eq!(item.parent(), Some(&*item2));

pub fn unqalified(&self) -> Unqalified<'_>

Display an unqalified variant of the item which does not include :: if a crate is present.

Trait Implementations

impl<A> AsRef<Item> for ItemBuf<A>

where A: Allocator,

fn as_ref(&self) -> &Item

Converts this type into a shared reference of the (usually inferred) input type.

impl<A> Borrow<Item> for ItemBuf<A>

where A: Allocator,

fn borrow(&self) -> &Item

Immutably borrows from an owned value.

impl<A> Debug for ItemBuf<A>

where A: Allocator,

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

Formats the value using the given formatter.

impl<A> Default for ItemBuf<A>

where A: Allocator + Default,

fn default() -> ItemBuf<A>

Returns the “default value” for a type.

impl<A> Deref for ItemBuf<A>

where A: Allocator,

type Target = Item

The resulting type after dereferencing.

fn deref(&self) -> &<ItemBuf<A> as Deref>::Target

Dereferences the value.

impl<'de, A> Deserialize<'de> for ItemBuf<A>

where A: Allocator + Default,

fn deserialize<D>( deserializer: D, ) -> Result<ItemBuf<A>, <D as Deserializer<'de>>::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<A> Display for ItemBuf<A>

where A: Allocator,

Format implementation for an ItemBuf, defers to Item.

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

Formats the value using the given formatter.

impl<A> FromStr for ItemBuf<A>

where A: Allocator + Default,

type Err = FromStrError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<ItemBuf<A>, <ItemBuf<A> as FromStr>::Err>

Parses a string s to return a value of this type.

impl<A> Hash for ItemBuf<A>

where A: Allocator,

fn hash<H>(&self, state: &mut H)

where H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<'a, A> IntoIterator for &'a ItemBuf<A>

where A: Allocator,

type IntoIter = Iter<'a>

Which kind of iterator are we turning this into?

type Item = ComponentRef<'a>

The type of the elements being iterated over.

fn into_iter(self) -> <&'a ItemBuf<A> as IntoIterator>::IntoIter

Creates an iterator from a value.

impl<A> Ord for ItemBuf<A>

where A: Allocator,

fn cmp(&self, other: &ItemBuf<A>) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl<A> PartialEq<&Item> for ItemBuf<A>

where A: Allocator,

fn eq(&self, other: &&Item) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<A> PartialEq<Item> for &ItemBuf<A>

where A: Allocator,

fn eq(&self, other: &Item) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<A> PartialEq<Item> for ItemBuf<A>

where A: Allocator,

fn eq(&self, other: &Item) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<ItemBuf> for &Item

fn eq(&self, other: &ItemBuf) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<ItemBuf> for Item

fn eq(&self, other: &ItemBuf) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<A> PartialEq<Iter<'_>> for &ItemBuf<A>

where A: Allocator,

fn eq(&self, other: &Iter<'_>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<A> PartialEq<Iter<'_>> for ItemBuf<A>

where A: Allocator,

fn eq(&self, other: &Iter<'_>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<A> PartialEq for ItemBuf<A>

where A: Allocator,

fn eq(&self, other: &ItemBuf<A>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<A> PartialOrd for ItemBuf<A>

where A: Allocator,

fn partial_cmp(&self, other: &ItemBuf<A>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<A> Serialize for ItemBuf<A>

where A: Allocator,

fn serialize<S>( &self, serializer: S, ) -> Result<<S as Serializer>::Ok, <S as Serializer>::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl<A> TryClone for ItemBuf<A>

where A: Allocator + Clone,

fn try_clone(&self) -> Result<ItemBuf<A>, Error>

Try to clone the current value, raising an allocation error if it’s unsuccessful.

fn try_clone_from(&mut self, source: &Self) -> Result<(), Error>

Performs copy-assignment from source.

impl<C, A> TryFromIteratorIn<C, A> for ItemBuf<A>

where A: Allocator, C: IntoComponent,

fn try_from_iter_in<T>(iter: T, alloc: A) -> Result<ItemBuf<A>, Error>

where T: IntoIterator<Item = C>,

Creates a value from an iterator within an allocator.

impl<A> Eq for ItemBuf<A>

where A: Allocator,