pub trait Term: Debug {
type BorrowTerm<'x>: Term + Copy
where Self: 'x;
Show 26 methods
// 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<'_> { ... }
}
Expand description
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§
Sourcetype BorrowTerm<'x>: Term + Copy
where
Self: 'x
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
Required Methods§
Sourcefn borrow_term(&self) -> Self::BorrowTerm<'_>
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§
Sourcefn is_iri(&self) -> bool
fn is_iri(&self) -> bool
Return true if this Term
is an IRI,
i.e. if kind
retuns TermKind::Iri
.
Sourcefn is_blank_node(&self) -> bool
fn is_blank_node(&self) -> bool
Return true if this Term
is a blank node,
i.e. if kind
retuns TermKind::BlankNode
.
Sourcefn is_literal(&self) -> bool
fn is_literal(&self) -> bool
Return true if this Term
is a literal,
i.e. if kind
retuns TermKind::Literal
.
Sourcefn is_variable(&self) -> bool
fn is_variable(&self) -> bool
Return true if this Term
is a variable,
i.e. if kind
retuns TermKind::Variable
.
Sourcefn is_atom(&self) -> bool
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.
Sourcefn is_triple(&self) -> bool
fn is_triple(&self) -> bool
Return true if this Term
is an RDF-star quoted triple,
i.e. if kind
retuns TermKind::Triple
.
Sourcefn iri(&self) -> Option<IriRef<MownStr<'_>>>
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.
Sourcefn bnode_id(&self) -> Option<BnodeId<MownStr<'_>>>
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.
Sourcefn lexical_form(&self) -> Option<MownStr<'_>>
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.
Sourcefn datatype(&self) -> Option<IriRef<MownStr<'_>>>
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.
Sourcefn language_tag(&self) -> Option<LanguageTag<MownStr<'_>>>
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.
Sourcefn variable(&self) -> Option<VarName<MownStr<'_>>>
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.
Sourcefn triple(&self) -> Option<[Self::BorrowTerm<'_>; 3]>
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.
Sourcefn to_triple(self) -> Option<[Self; 3]>where
Self: Sized,
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.
Sourcefn constituents<'s>(
&'s self,
) -> Box<dyn Iterator<Item = Self::BorrowTerm<'s>> + 's>
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.
Sourcefn to_constituents<'a>(self) -> Box<dyn Iterator<Item = Self> + 'a>where
Self: Clone + 'a,
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.
Sourcefn atoms<'s>(&'s self) -> Box<dyn Iterator<Item = Self::BorrowTerm<'s>> + 's>
fn atoms<'s>(&'s self) -> Box<dyn Iterator<Item = Self::BorrowTerm<'s>> + 's>
Sourcefn to_atoms<'a>(self) -> Box<dyn Iterator<Item = Self> + 'a>where
Self: Sized + 'a,
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.
Sourcefn eq<T: Term>(&self, other: T) -> bool
fn eq<T: Term>(&self, other: T) -> bool
Check whether self
and other
represent the same RDF term.
Sourcefn cmp<T>(&self, other: T) -> Orderingwhere
T: Term,
fn cmp<T>(&self, other: T) -> Orderingwhere
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
.
Sourcefn hash<H: Hasher>(&self, state: &mut H)
fn hash<H: Hasher>(&self, state: &mut H)
Compute an implementation-independant hash of this RDF term.
Sourcefn into_term<T: FromTerm>(self) -> Twhere
Self: Sized,
fn into_term<T: FromTerm>(self) -> Twhere
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>()
.
Sourcefn try_into_term<T: TryFromTerm>(self) -> Result<T, T::Error>where
Self: Sized,
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>()
.
Sourcefn as_simple(&self) -> SimpleTerm<'_>
fn as_simple(&self) -> SimpleTerm<'_>
Copies this term into a SimpleTerm
,
borrowing as much as possible from self
(calling SimpleTerm::from_term_ref
).
Dyn Compatibility§
This trait is not dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.
Implementations on Foreign Types§
Source§impl Term for f64
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<'_>
Source§impl Term for i32
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<'_>
Source§impl Term for isize
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<'_>
Source§impl Term for str
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<'_>
Source§impl Term for usize
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)?;