Trait sophia_api::term::Term

pub trait Term: Debug {
    type BorrowTerm<'x>: Term + Copy
       where Self: 'x;

    // Required methods
    fn kind(&self) -> TermKind;
    fn borrow_term(&self) -> Self::BorrowTerm<'_>;

    // Provided methods
    fn is_iri(&self) -> bool { ... }
    fn is_blank_node(&self) -> bool { ... }
    fn is_literal(&self) -> bool { ... }
    fn is_variable(&self) -> bool { ... }
    fn is_atom(&self) -> bool { ... }
    fn is_triple(&self) -> bool { ... }
    fn iri(&self) -> Option<IriRef<MownStr<'_>>> { ... }
    fn bnode_id(&self) -> Option<BnodeId<MownStr<'_>>> { ... }
    fn lexical_form(&self) -> Option<MownStr<'_>> { ... }
    fn datatype(&self) -> Option<IriRef<MownStr<'_>>> { ... }
    fn language_tag(&self) -> Option<LanguageTag<MownStr<'_>>> { ... }
    fn variable(&self) -> Option<VarName<MownStr<'_>>> { ... }
    fn triple(&self) -> Option<[Self::BorrowTerm<'_>; 3]> { ... }
    fn to_triple(self) -> Option<[Self; 3]>
       where Self: Sized { ... }
    fn constituents<'s>(
        &'s self
    ) -> Box<dyn Iterator<Item = Self::BorrowTerm<'s>> + 's> { ... }
    fn to_constituents<'a>(self) -> Box<dyn Iterator<Item = Self> + 'a>
       where Self: Clone + 'a { ... }
    fn atoms<'s>(
        &'s self
    ) -> Box<dyn Iterator<Item = Self::BorrowTerm<'s>> + 's> { ... }
    fn to_atoms<'a>(self) -> Box<dyn Iterator<Item = Self> + 'a>
       where Self: Sized + 'a { ... }
    fn eq<T: Term>(&self, other: T) -> bool { ... }
    fn cmp<T>(&self, other: T) -> Ordering
       where T: Term { ... }
    fn hash<H: Hasher>(&self, state: &mut H) { ... }
    fn into_term<T: FromTerm>(self) -> T
       where Self: Sized { ... }
    fn try_into_term<T: TryFromTerm>(self) -> Result<T, T::Error>
       where Self: Sized { ... }
    fn as_simple(&self) -> SimpleTerm<'_> { ... }
}

A generalized RDF term.

Implementation

The only method without a default implementation is kind, which indicates what kind of RDF term a given Term represents.

However, while all other methods have a default implementtation (returning None), those corresponding to the supported kinds MUST be overridden accordingly, otherwise they will panic. See below for an explaination of this design choice.

In order to test that all the methods are implemented consistently, consider using the macro assert_consistent_term_impl. The macro should be invoked on various instances of the type, at least one for each kind that the type supports.

Design rationale

The methods defined by this trait are not independant: depending on the value returned by kind, other methods are expected to return Some(...) or None accordingly.

An alternative solution would have been for the variants of TermKind to contain the corresponding values. This would arguably have been more idiomatic for users, and less error-prone for implementors of this trait.

However, this would have caused performance issues in some cases, because the MownStr returned by, e.g., iri or lexical_form, can be allocated on demand by some implementations.

Required Associated Types

type BorrowTerm<'x>: Term + Copy where Self: 'x

A type of Term that can be borrowed from this type (i.e. that can be obtained from a simple reference to this type). It is used in particular for accessing constituents of quoted tripes (Term::triple) or for sharing this term with a function that expects T: Term (rather than &T) using Term::borrow_term.

In “standard” cases, this type is either &Self or Self (for types implementing Copy).

Note to implementors

• When in doubt, set BorrowTerm<'x> to &'x Self.
• If your type implements Copy, consider setting it to Self.
• If your type is a wrapper W(T) where T: Term, consider setting it to W(T::BorrowTerm<'x>).
• If none of the options above are possible, your type is probably not a good fit for implementing Term.

Required Methods

fn kind(&self) -> TermKind

Return the kind of RDF term that this Term represents.

fn borrow_term(&self) -> Self::BorrowTerm<'_>

Get something implementing Term from a simple reference to self, representing the same RDF term as self.

Wny do functions in Sophia expect T: Term and never &T: Term?

To understand the rationale of this design choice, consider an imaginary type Foo. A function f(x: Foo) requires users to waive the ownership of the Foo value they want to pass to the function. This is not always suited to the users needs. On the other hand, a function g(x: &Foo) not only allows, but forces its users to maintain ownership of the Foo value they want to pass to the function. Again, there are situations where this is not suitable. The standard solution to this problem is to use the Borrow trait: a function h<T>(x: T) where T: Borrow<Foo> allows x to be passed either by value (transferring ownership) or by reference (simply borrowing the caller’s Foo).

While this design pattern is usable with a single type (Foo in our example above), it is not usable with a trait, such as Term: the following trait bound is not valid in Rust: T: Borrow<Term>. Yet, we would like any function expecting a terms to be able to either take its ownership or simply borrow it, depending on the caller’s needs and preferences.

The borrow_term methods offer a solution to this problem, and therefore the trait bound T: Term must be thought of as equivalent to T: Borrow<Term>: the caller can chose to either waive ownership of its term (by passing it directly) or keep it (by passing the result of borrow_term() instead).

Provided Methods

fn is_iri(&self) -> bool

Return true if this Term is an IRI, i.e. if kind retuns TermKind::Iri.

fn is_blank_node(&self) -> bool

Return true if this Term is a blank node, i.e. if kind retuns TermKind::BlankNode.

fn is_literal(&self) -> bool

Return true if this Term is a literal, i.e. if kind retuns TermKind::Literal.

fn is_variable(&self) -> bool

Return true if this Term is a variable, i.e. if kind retuns TermKind::Variable.

fn is_atom(&self) -> bool

Return true if this Term is an atomic term, i.e. an IRI, a blank node, a literal or a variable.

fn is_triple(&self) -> bool

Return true if this Term is an RDF-star quoted triple, i.e. if kind retuns TermKind::Triple.

fn iri(&self) -> Option<IriRef<MownStr<'_>>>

If kind returns TermKind::Iri, return this IRI. Otherwise return None.

Note to implementors

The default implementation assumes that Term::is_iri always return false. If that is not the case, this method must be explicit implemented.

fn bnode_id(&self) -> Option<BnodeId<MownStr<'_>>>

If kind returns TermKind::BlankNode, return the locally unique label of this blank node. Otherwise return None.

Note to implementors

The default implementation assumes that Term::is_blank_node always return false. If that is not the case, this method must be explicit implemented.

fn lexical_form(&self) -> Option<MownStr<'_>>

If kind returns TermKind::Literal, return the lexical form of this literal. Otherwise return None.

Note to implementors

The default implementation assumes that Term::is_literal always return false. If that is not the case, this method must be explicit implemented.

fn datatype(&self) -> Option<IriRef<MownStr<'_>>>

If kind returns TermKind::Literal, return the datatype IRI of this literal. Otherwise return None.

NB: if this literal is a language-tagged string, then this method MUST return http://www.w3.org/1999/02/22-rdf-syntax-ns#langString.

Note to implementors

The default implementation assumes that Term::is_literal always return false. If that is not the case, this method must be explicit implemented.

fn language_tag(&self) -> Option<LanguageTag<MownStr<'_>>>

If kind returns TermKind::Literal, and if this literal is a language-tagged string, return its language tag. Otherwise return None.

Note to implementors

The default implementation assumes that Term::is_literal always return false. If that is not the case, this method must be explicit implemented.

fn variable(&self) -> Option<VarName<MownStr<'_>>>

If kind returns TermKind::Variable, return the name of this variable. Otherwise return None.

Note to implementors

The default implementation assumes that Term::is_variable always return false. If that is not the case, this method must be explicit implemented.

fn triple(&self) -> Option<[Self::BorrowTerm<'_>; 3]>

If kind returns TermKind::Triple, return this triple. Otherwise return None.

Note to implementors

The default implementation assumes that Term::is_triple always return false. If that is not the case, this method must be explicit implemented.

fn to_triple(self) -> Option<[Self; 3]>

where Self: Sized,

If kind returns TermKind::Triple, return this triple, consuming this term. Otherwise return None.

Note to implementors

The default implementation assumes that Term::is_triple always return false. If that is not the case, this method must be explicit implemented.

fn constituents<'s>( &'s self ) -> Box<dyn Iterator<Item = Self::BorrowTerm<'s>> + 's>

Iter over all the constituents of this term.

If this term is atomic, the iterator yields only the term itself. If it is a quoted triple, the iterator yields the quoted triple itself, and the constituents of its subject, predicate and object.

fn to_constituents<'a>(self) -> Box<dyn Iterator<Item = Self> + 'a>

where Self: Clone + 'a,

Iter over all the constiutents of this term, consuming it.

See Term::constituents.

fn atoms<'s>(&'s self) -> Box<dyn Iterator<Item = Self::BorrowTerm<'s>> + 's>

Iter over all the atomic constituents of this term.

If this term is atomic, the iterator yields only the term itself. If it is a quoted triple, the iterator yields the atoms of its subject, predicate and object.

fn to_atoms<'a>(self) -> Box<dyn Iterator<Item = Self> + 'a>

where Self: Sized + 'a,

Iter over all the atomic constituents of this term, consuming it.

See Term::atoms.

fn eq<T: Term>(&self, other: T) -> bool

Check whether self and other represent the same RDF term.

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

where T: Term,

Compare two terms:

• IRIs < literals < blank nodes < quoted triples < variables
• IRIs, blank nodes and variables are ordered by their value
• Literals are ordered by their datatype, then their language (if any), then their lexical form
• Quoted triples are ordered in lexicographical order

NB: literals are ordered by their lexical value, so for example, "10"^^xsd:integer comes before "2"^^xsd:integer.

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

Compute an implementation-independant hash of this RDF term.

fn into_term<T: FromTerm>(self) -> T

where Self: Sized,

Convert this term in another type.

This method is to FromTerm what Into::into is to From.

NB: if you want to make a copy of this term without consuming it, you can use this_term.borrow_term().into_term::<T>().

fn try_into_term<T: TryFromTerm>(self) -> Result<T, T::Error>

where Self: Sized,

Try to convert this term into another type.

This method is to TryFromTerm what TryInto::try_into is to TryFrom.

NB: if you want to make a copy of this term without consuming it, you can use this_term.borrow_term().try_into_term::<T>().

fn as_simple(&self) -> SimpleTerm<'_>

Copies this term into a SimpleTerm, borrowing as much as possible from self (calling SimpleTerm::from_term_ref).

Object Safety

This trait is not object safe.

Implementations on Foreign Types

impl Term for f64

f64 implements Term so that Rust literals can be used as RDF literals in code.

E.g.:

graph.insert(&subject, &rdf::value, 3.14)?;

type BorrowTerm<'x> = f64

fn kind(&self) -> TermKind

fn lexical_form(&self) -> Option<MownStr<'_>>

fn datatype(&self) -> Option<IriRef<MownStr<'_>>>

fn language_tag(&self) -> Option<LanguageTag<MownStr<'_>>>

fn borrow_term(&self) -> Self::BorrowTerm<'_>

impl Term for i32

i32 implements Term so that Rust literals can be used as RDF literals in code.

E.g.:

graph.insert(&subject, &rdf::value, 42)?;

type BorrowTerm<'x> = i32

fn kind(&self) -> TermKind

fn lexical_form(&self) -> Option<MownStr<'_>>

fn datatype(&self) -> Option<IriRef<MownStr<'_>>>

fn language_tag(&self) -> Option<LanguageTag<MownStr<'_>>>

fn borrow_term(&self) -> Self::BorrowTerm<'_>

impl Term for isize

isize implements Term so that Rust values can be used as RDF literals in code.

E.g.:

let answer: isize = 42;
graph.insert(&subject, &rdf::value, answer)?;

type BorrowTerm<'x> = isize

fn kind(&self) -> TermKind

fn lexical_form(&self) -> Option<MownStr<'_>>

fn datatype(&self) -> Option<IriRef<MownStr<'_>>>

fn language_tag(&self) -> Option<LanguageTag<MownStr<'_>>>

fn borrow_term(&self) -> Self::BorrowTerm<'_>

impl Term for str

str implements Term so that Rust literals can be used as RDF literals in code.

E.g.:

graph.insert(&subject, &rdfs::label, "hello world")?;

type BorrowTerm<'x> = &'x str where Self: 'x

fn kind(&self) -> TermKind

fn lexical_form(&self) -> Option<MownStr<'_>>

fn datatype(&self) -> Option<IriRef<MownStr<'_>>>

fn language_tag(&self) -> Option<LanguageTag<MownStr<'_>>>

fn borrow_term(&self) -> Self::BorrowTerm<'_>

impl Term for usize

usize implements Term so that Rust values can be used as RDF literals in code.

E.g.:

let answer: usize = 42;
graph.insert(&subject, &rdf::value, answer)?;

type BorrowTerm<'x> = usize

fn kind(&self) -> TermKind

fn lexical_form(&self) -> Option<MownStr<'_>>

fn datatype(&self) -> Option<IriRef<MownStr<'_>>>

fn language_tag(&self) -> Option<LanguageTag<MownStr<'_>>>

fn borrow_term(&self) -> Self::BorrowTerm<'_>

impl<'a, T> Term for &'a T

where T: Term<BorrowTerm<'a> = &'a T> + ?Sized,

type BorrowTerm<'x> = &'a T where 'a: 'x

fn kind(&self) -> TermKind

fn is_iri(&self) -> bool

fn is_blank_node(&self) -> bool

fn is_literal(&self) -> bool

fn is_variable(&self) -> bool

fn is_triple(&self) -> bool

fn iri(&self) -> Option<IriRef<MownStr<'_>>>

fn bnode_id(&self) -> Option<BnodeId<MownStr<'_>>>

fn lexical_form(&self) -> Option<MownStr<'_>>

fn datatype(&self) -> Option<IriRef<MownStr<'_>>>

fn language_tag(&self) -> Option<LanguageTag<MownStr<'_>>>

fn variable(&self) -> Option<VarName<MownStr<'_>>>

fn triple(&self) -> Option<[Self::BorrowTerm<'_>; 3]>

fn to_triple(self) -> Option<[Self; 3]>

fn borrow_term(&self) -> Self::BorrowTerm<'_>

fn eq<U: Term>(&self, other: U) -> bool

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

Implementors

impl<'a> Term for SimpleTerm<'a>

type BorrowTerm<'x> = &'x SimpleTerm<'a> where 'a: 'x

impl<'a> Term for NsTerm<'a>

type BorrowTerm<'x> = &'x NsTerm<'a> where 'a: 'x

impl<T> Term for Iri<T>

where T: Borrow<str> + Debug,

type BorrowTerm<'x> = &'x Iri<T> where T: 'x

impl<T> Term for IriRef<T>

where T: Borrow<str> + Debug,

type BorrowTerm<'x> = &'x IriRef<T> where T: 'x

impl<T> Term for BnodeId<T>

where T: Borrow<str> + Debug,

type BorrowTerm<'x> = &'x BnodeId<T> where T: 'x

impl<T> Term for VarName<T>

where T: Borrow<str> + Debug,

type BorrowTerm<'x> = &'x VarName<T> where T: 'x

impl<T: Term> Term for CmpTerm<T>

type BorrowTerm<'x> = CmpTerm<<T as Term>::BorrowTerm<'x>> where T: 'x