pub struct LocationFilter {
filter_type: u64,
fields: Vec<u64>,
}Expand description
A draft-23 LOCATION_FILTER (Parameter Type 0x21), Section 9.19.9.
LOCATION_FILTER Parameter {
Parameter Type (vi64) = 0x21,
Location Filter Type (vi64),
[StartGroup (vi64),]
[StartObject (vi64),]
[EndGroupDelta (vi64),]
[EndObject (vi64),]
}§The shape is the type
Section 9.19.9: “The Location Filter Type dictates which optional variable-length integer fields follow, and how they are interpreted.” Each constructor here is one of the six types Table 6 lists, and the type is written first, so a caller cannot build a type the draft does not define, cannot build a three-field filter by leaving a field out of a four-field one, and cannot confuse the two types that carry no fields at all — None and Next Object, which mean opposite things.
There is no length. The type is the only thing that says where the value ends, so a receiver that reads the type wrong reads every parameter after it wrong too; this is why the value is built here and handed back through the codec’s own decoder before it is returned.
Fields§
§filter_type: u64§fields: Vec<u64>Implementations§
Source§impl LocationFilter
impl LocationFilter
Sourcepub fn none() -> Self
pub fn none() -> Self
Type 0x00: no filter at all, and no fields.
Section 9.19.9: “If Location Filter Type is 0x00, no fields follow and
there is no Location Filter.” In a REQUEST_UPDATE this is how a filter
already in force is taken away: Section 9.5 has “no generic mechanism to
remove a parameter from a request”, and omitting LOCATION_FILTER from
a REQUEST_UPDATE leaves the value unchanged rather than clearing it.
Sourcepub fn relative(start_group: u64) -> Self
pub fn relative(start_group: u64) -> Self
Type 0x01: a start relative to the live edge, open-ended.
Section 9.19.9: the start Location is {Largest Object.Group + 1 - StartGroup, 0}, so 0 is the next group, 1 the current group, and
N is N - 1 groups before the current one. Clamped at both ends of
the number space by the publisher rather than here, because resolving it
needs Largest Object.
Sourcepub fn absolute_start(start_group: u64, start_object: u64) -> Self
pub fn absolute_start(start_group: u64, start_object: u64) -> Self
Type 0x02: an absolute start, open-ended.
Every start is absolute here, {0, 0} included: it is the first
Location of the track. The live edge is a type of its own,
LocationFilter::next_object.
Sourcepub fn next_object() -> Self
pub fn next_object() -> Self
Type 0x05: start at the Next Object, open-ended, with no fields.
Section 9.19.9: “If Location Filter Type is 0x05, no fields follow and it specifies the Next Object.” Section 3.4 names this filter as half of the recipe for exactly-once delivery on a subscription with a fill: a Next Object subscription filter paired with an open-ended fill range, which the publisher ends at Largest Object.
Sourcepub fn range(
start_group: u64,
start_object: u64,
end_group_delta: u64,
) -> Result<Self, FillError>
pub fn range( start_group: u64, start_object: u64, end_group_delta: u64, ) -> Result<Self, FillError>
Type 0x03: an absolute start and an end group, covering all objects in the end group.
Section 9.19.9: “EndGroupDelta is delta encoded from StartGroup, but both
the start and end groups are absolute, not relative to Largest Object.”
So the end group is start_group + end_group_delta, and a delta of 0
ends in the group it started in.
§Errors
FillError::EndGroupOverflow when the sum leaves the number space,
which Section 9.19.9 makes a DELTA_ENCODING_OVERFLOW at the receiver.
Sourcepub fn range_to(
start_group: u64,
start_object: u64,
end_group_delta: u64,
end_object: u64,
) -> Result<Self, FillError>
pub fn range_to( start_group: u64, start_object: u64, end_group_delta: u64, end_object: u64, ) -> Result<Self, FillError>
Type 0x04: a fully specified inclusive range,
{start_group, start_object} through
{start_group + end_group_delta, end_object}.
end_object is the Object ID of the last object the range covers. It is
not that Object ID plus one, and an end_object of 0 means object 0
rather than the whole group.
§Errors
Sourcepub fn filter_type(&self) -> u64
pub fn filter_type(&self) -> u64
The Location Filter Type, one of
location_filter_types.
Sourcepub fn fields(&self) -> &[u64]
pub fn fields(&self) -> &[u64]
The vi64 fields that follow the type, in wire order. Empty for both
None and Next Object, which only LocationFilter::filter_type tells
apart.
Sourcepub fn encode_value(&self) -> Vec<u8> ⓘ
pub fn encode_value(&self) -> Vec<u8> ⓘ
The encoded value, without the parameter type ahead of it: the
Location Filter Type, then the fields it names.
Sourcepub fn parameter(&self) -> Result<KeyValuePair, FillError>
pub fn parameter(&self) -> Result<KeyValuePair, FillError>
This filter as the Message Parameter that carries it.
§Errors
FillError::NotRoundTrippable if the codec’s own
decode_location_filter does not read back the type and fields that
went in.