Struct Item

pub struct Item { /* private fields */ }

The reference to an ItemBuf.

Implementations

impl Item

pub const fn new() -> &'static Item

Construct an Item corresponding to the root item.

Examples

use rune::{Item, ItemBuf};

assert_eq!(Item::new(), &*ItemBuf::new());

pub const unsafe fn from_bytes(content: &[u8]) -> &Item

Construct an Item from an ItemBuf.

Safety

Caller must ensure that content has a valid ItemBuf representation. The easiest way to accomplish this is to use the rune::item! macro.

Examples

use rune::{Item, ItemBuf};

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

// SAFETY: item is constructed from a valid buffer.
let item = unsafe { Item::from_bytes(item.as_bytes()) };

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 AsRef<Item> for &Item

fn as_ref(&self) -> &Item

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

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 Debug for Item

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

Formats the value using the given formatter.

impl Default for &Item

fn default() -> &Item

Returns the “default value” for a type.

impl Display for Item

Format implementation for an ItemBuf.

An empty item is formatted as {root}, because it refers to the topmost root module.

Examples

use rune::alloc::prelude::*;
use rune::ItemBuf;
use rune::item::ComponentRef;

let root = ItemBuf::new().try_to_string()?;
assert_eq!("{root}", root);

let hello = ItemBuf::with_item(&[ComponentRef::Str("hello"), ComponentRef::Id(0)])?;
assert_eq!("hello::$0", hello.try_to_string()?);

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

Formats the value using the given formatter.

impl Hash for Item

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

where __H: Hasher,

Feeds this value into the given Hasher.

impl<'a> IntoIterator for &'a Item

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 Item as IntoIterator>::IntoIter

Creates an iterator from a value.

impl Ord for Item

fn cmp(&self, other: &Item) -> Ordering

This method returns an Ordering between self and other.

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 PartialEq<Iter<'_>> for &Item

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 PartialEq<Iter<'_>> for Item

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 PartialEq for Item

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 PartialOrd for Item

fn partial_cmp(&self, other: &Item) -> 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 Serialize for Item

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 TryToOwned for Item

type Owned = ItemBuf

The resulting type after obtaining ownership.

fn try_to_owned(&self) -> Result<<Item as TryToOwned>::Owned, Error>

Creates owned data from borrowed data, usually by cloning.

impl Eq for Item

impl StructuralPartialEq for Item