pub struct QueryItem { /* private fields */ }Expand description
One clause of a Query.
An event matches an item when both hold:
- its type is one of
types— OR semantics, and an emptytypesmatches any type; - its tags contain all of
tags— AND semantics, and an emptytagsmatches any tags.
At least one of the two must be non-empty; an item constraining neither would
match everything, which is Query::all’s job.
§Examples
use happenstance_core::{QueryItem, Tags};
// "Any StudentSubscribed or StudentUnsubscribed event for course c1."
let item = QueryItem::new(
["StudentSubscribed", "StudentUnsubscribed"],
Tags::from_pairs([("course", "c1")])?,
)?;
assert_eq!(item.types().len(), 2);Implementations§
Source§impl QueryItem
impl QueryItem
Sourcepub fn new<T>(
types: impl IntoIterator<Item = T>,
tags: Tags,
) -> Result<Self, InvalidQuery>
pub fn new<T>( types: impl IntoIterator<Item = T>, tags: Tags, ) -> Result<Self, InvalidQuery>
Creates a query item.
Types are deduplicated and sorted so that two items expressing the same constraint compare equal.
§Errors
Returns InvalidQuery::UnconstrainedItem if both types and tags
are empty, or InvalidQuery::EventType if a type string is invalid.
The InvalidQuery: From<T::Error> bound is what lets this accept both
&str (fallible conversion) and an already-built EventType
(infallible), rather than forcing callers into one or the other.
Sourcepub fn of(
first: EventType,
rest: impl IntoIterator<Item = EventType>,
tags: Tags,
) -> Self
pub fn of( first: EventType, rest: impl IntoIterator<Item = EventType>, tags: Tags, ) -> Self
Creates an item from at least one type the caller already holds.
Total: it returns QueryItem, not a Result. new has
two ways to fail, and neither can reach this signature. A built
EventType has already been validated, and a separate first
parameter means the item always constrains at least one type, so it can
never be the unconstrained item new refuses. Equal inputs produce ==
items through either constructor, because both share one sort and dedup.
Reach for new instead when the types are strings, or
arrive as a sequence whose length you do not know, and for
of_types when there are also no tags. Both validate
and can refuse, which is why they return a Result. Splitting off the
head is how “at least one” becomes a fact of the signature here: a slice
or iterator parameter says nothing about its length, so a total
constructor over one would have to panic or accept the empty item (ADR-0069).
§Examples
use happenstance_core::{EventType, QueryItem, Tags};
const COURSE_DEFINED: EventType = EventType::from_static("CourseDefined");
let tags = Tags::from_pairs([("course", "c1")])?;
// No further types, and no `?` on the item.
let item = QueryItem::of(COURSE_DEFINED, [], tags);
assert_eq!(item.types(), [COURSE_DEFINED]);Sourcepub fn of_types<T>(
types: impl IntoIterator<Item = T>,
) -> Result<Self, InvalidQuery>
pub fn of_types<T>( types: impl IntoIterator<Item = T>, ) -> Result<Self, InvalidQuery>
Creates an item constrained only by type.
§Errors
Returns InvalidQuery::UnconstrainedItem if types is empty, or
InvalidQuery::EventType if a type string is invalid.
Sourcepub fn tagged(tags: Tags) -> Result<Self, InvalidQuery>
pub fn tagged(tags: Tags) -> Result<Self, InvalidQuery>
Creates an item constrained only by tags.
§Errors
Returns InvalidQuery::UnconstrainedItem if tags is empty.
Sourcepub fn types(&self) -> &[EventType]
pub fn types(&self) -> &[EventType]
The types this item accepts, sorted. Empty means “any type”.
Examples found in repository?
879fn print_boundary<B: Boundary>(boundary: &B) -> Result<()> {
880 let query = boundary.query()?;
881
882 match query.items() {
883 Some(items) => {
884 for item in items {
885 let types: Vec<&str> = item.types().iter().map(EventType::as_str).collect();
886 println!(" {} where {:?}", types.join(" | "), item.tags());
887 }
888 }
889 // Unreachable for a well-formed model, and spelled rather than
890 // `unwrap`ped: `Query::All` is what a boundary constraining neither
891 // types nor tags would produce, and an empty `EVENT_TYPES` is already
892 // a compile error.
893 None => println!(" the whole log"),
894 }
895
896 Ok(())
897}The tags an event must carry. Empty means “any tags”.
Examples found in repository?
879fn print_boundary<B: Boundary>(boundary: &B) -> Result<()> {
880 let query = boundary.query()?;
881
882 match query.items() {
883 Some(items) => {
884 for item in items {
885 let types: Vec<&str> = item.types().iter().map(EventType::as_str).collect();
886 println!(" {} where {:?}", types.join(" | "), item.tags());
887 }
888 }
889 // Unreachable for a well-formed model, and spelled rather than
890 // `unwrap`ped: `Query::All` is what a boundary constraining neither
891 // types nor tags would produce, and an empty `EVENT_TYPES` is already
892 // a compile error.
893 None => println!(" the whole log"),
894 }
895
896 Ok(())
897}Trait Implementations§
Source§impl<'de> Deserialize<'de> for QueryItem
Available on crate feature serde only.
impl<'de> Deserialize<'de> for QueryItem
serde only.