Struct SymbolId 

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

The canonical identity of a symbol. See the module docs for the grammar.

An id holds its canonical text (shared, so cloning is cheap). Because printing is injective and only canonical text parses, two ids are equal exactly when their texts are, and ids order by their text. A parent’s text is a prefix of its children’s, so a parent always sorts before them. Structural accessors (descriptors, package, …) read the text on demand.

Implementations

impl SymbolId

pub fn global(package: Package, descriptors: Vec<Descriptor>) -> Self

A global id: package followed by descriptors (empty for the package root).

pub fn package_root(package: Package) -> Self

The package root (a crate’s root module).

pub fn path<I, S>(segments: I) -> Result<Self, IdError>

where I: IntoIterator<Item = S>, S: Into<String>,

A path as written, for references whose kinds are unknown.

pub fn unresolved(name: impl Into<String>) -> Self

A method called on a receiver of unknown type.

pub fn parse(text: &str) -> Result<Self, IdError>

Parse the canonical form. The exact inverse of Display: only canonical text is accepted (a simple name in backticks, for instance, is rejected), so parse(s) succeeding implies parse(s)?.to_string() == s.

pub fn as_str(&self) -> &str

The canonical text, sym: prefix included.

pub fn is_global(&self) -> bool

true for global (kind-explicit) ids.

pub fn is_unresolved(&self) -> bool

true for SymbolId::unresolved ids.

pub fn package(&self) -> Option<Package>

The package of a global id.

pub fn descriptors(&self) -> Vec<Descriptor>

The descriptors of a global id (empty for the other forms).

pub fn segments(&self) -> Option<Vec<String>>

The segments of a path id.

pub fn last(&self) -> Option<Descriptor>

The last descriptor of a global id.

pub fn name(&self) -> Cow<'_, str>

The short name: the last descriptor’s name, the package name of a package root, the last path segment, or the unresolved method name.

assert_eq!(SymbolId::parse("sym:cargo a . b/C#go().").unwrap().name(), "go");
assert_eq!(SymbolId::parse("sym:cargo a .").unwrap().name(), "a");

pub fn root(&self) -> Option<Cow<'_, str>>

The first name: the package name, or the first path segment. None for unresolved ids.

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

The enclosing definition. For a global id, the last descriptor is dropped, then any trailing type-parameter descriptors, so a method in a trait-impl block has its type as parent. For a path id, the last segment is dropped. A package root, a one-segment path and an unresolved id have no parent.

let m = SymbolId::parse("sym:cargo a . T#[Tr]f().").unwrap();
assert_eq!(m.parent().unwrap().to_string(), "sym:cargo a . T#");
assert_eq!(SymbolId::parse("sym:cargo a . T#").unwrap().parent().unwrap().to_string(), "sym:cargo a .");
assert!(SymbolId::parse("sym:cargo a .").unwrap().parent().is_none());

pub fn child(&self, descriptor: Descriptor) -> Option<SymbolId>

Append a descriptor to a global id. None for the other forms, which have no kinds to extend.

pub fn names(&self) -> Vec<Cow<'_, str>>

Every name in order: package and descriptor names for a global id, the segments of a path id, the name of an unresolved id.

pub fn extend_path(&self, segment: &str) -> SymbolId

Continue an id with a segment of unknown kind: the result is a path id made of names plus segment. This is how a reference that leaves known territory (krate::known::unknown) is recorded.

let m = SymbolId::parse("sym:cargo a . net/").unwrap();
assert_eq!(m.extend_path("dial").to_string(), "sym:extern a::net::dial");

pub fn view(&self) -> IdView<'_>

A borrowed view of the id’s parts. Unlike package and descriptors it allocates nothing but the descriptor list (and a name only when it needs unescaping), so it suits hot paths such as deriving a diagram id per call site.

use sealmap_model::{DescriptorKind, IdView, SymbolId};

let id = SymbolId::parse("sym:cargo shop . db/Db#[Store]put().").unwrap();
let IdView::Global(g) = id.view() else { unreachable!() };
assert_eq!((g.manager, &*g.package, g.version.is_none()), ("cargo", "shop", true));
let kinds: Vec<_> = g.descriptors.iter().map(|d| (d.kind, &*d.name)).collect();
assert_eq!(kinds, [
    (DescriptorKind::Namespace, "db"),
    (DescriptorKind::Type, "Db"),
    (DescriptorKind::TypeParameter, "Store"),
    (DescriptorKind::Method, "put"),
]);

pub fn display_path(&self) -> String

The names joined by ::, for human-facing labels. Not injective: never use it as a key.

Trait Implementations

impl Clone for SymbolId

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 SymbolId

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for SymbolId

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

Deserialize this value from the given Serde deserializer.

impl Display for SymbolId

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

Formats the value using the given formatter.

impl Eq for SymbolId

impl FromStr for SymbolId

type Err = IdError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

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

impl Hash for SymbolId

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

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 Ord for SymbolId

fn cmp(&self, other: &Self) -> 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.

fn clamp_to<R>(self, range: R) -> Self

where Self: Sized, R: ClampBounds<Self>,

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

Restrict a value to a certain range.

impl PartialEq for SymbolId

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

Equality operator ==.

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

Inequality operator !=.

impl PartialOrd for SymbolId

fn partial_cmp(&self, other: &Self) -> 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 SymbolId

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

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for SymbolId