Module source 

A Source yields items, and may also fail in the process. This module also provides two specialized kinds of source: TripleSource and QuadSource.

The Source trait provides an API similar to (a subset of) the Iterator API, with methods such as for_each_item and try_for_each_item. TripleSource and QuadSource provides specialized alternative (e.g. for_each_triple and for_each_quad, respectively).

Rationale (or Why not simply use Iterator?)

The Iterator trait is designed in such a way that items must live at least as long as the iterator itself. This assumption may be too strong in some situations.

For example, consider a parser using 3 buffers to store the subject, predicate, and object of the triples it parses. Each time it extracts a triple from the data, it yields it (as 3 references to its internal buffers) to the closure passed to for_each_triple. Then, it reuses the buffers to store the data for the next triple, and yields the new triple, as 3 references to the same buffers.

Such a parser can not implement Iterator, because, once yielded by the iterator’s next method, an item is free to live during further iterations. In particular, it can be stored in a collection, and still be alive when the next method is called again (consider for example the Iterator::collect method).

Because many parsers (as well as other triple/quad sources) will be implemented in a manner similar to that described above, we have to provide a trait with weaker assumptions on the lifetime of the yielded triples.

The alternative would be to wrap such parsers with a layer that would copy the data from internal buffers to fresh buffers for each triples, but we do not want to impose that cost on all implementations — especially when many consumers will be happy with short-lived references.

About the design of TripleSource and QuadSource

The design of TripleSource (resp. QuadSource) may seem overcomplicated, but it aims to have the following properties.

• When a concrete type implements Source and its items implement Triple, then it is automatically recognized as a TripleSource.
• When a TripleSource is required, it can be used as a simple trait bound, without requiring the user to add a higher ranked trait bound (HRTB) like for <'x> S:Item<'x>: Triple.

Re-exports

pub use StreamError::*;

Modules

convert

I define ToQuads and ToQuads, the result type of TripleSource::to_quads and QuadSource::to_triples respectively.

filter

I define FilterSource, the result type of Source::filter_items. I also define FilterTripleSource and FilterQuadSource, which are required to ensure that the output of TripleSource::filter_triples and QuadSource::filter_quads are recognized as a TripleSource and a QuadSource, respectively.

filter_map

I define FilterMapSource the result type of Source::filter_map_items.

map

I define MapSource, the result type of Source::map_items.

Enums

StreamError

A error that is raised by functions that move fallible Sources into fallible Sinks.

Traits

IntoSource

An extension trait for iterators, converting them to an Infallible Source.

QuadSource

A quad source is a Source producing quads.

Source

A source produces items, and may also fail in the process.

StreamResultExt

Additional methods for StreamResult

TripleSource

A triple source is a Source producing triples.

Type Aliases

QSQuad

Type alias to denote the type of quads yielded by a QuadSource.

StreamResult

Convenient type alias for Result whose error is StreamError.

TSTriple

Type alias to denote the type of triples yielded by a TripleSource.