Struct rerun::dataframe::EntityPathFilter

pub struct EntityPathFilter {
    rules: BTreeMap<EntityPathRule, RuleEffect>,
}

A way to filter a set of EntityPaths.

This implements as simple set of include/exclude rules:

+ /world/**           # add everything…
- /world/roads/**     # …but remove all roads…
+ /world/roads/main   # …but show main road

If there is multiple matching rules, the most specific rule wins. If there are multiple rules of the same specificity, the last one wins. If no rules match, the path is excluded.

The /** suffix matches the whole subtree, i.e. self and any child, recursively (/world/** matches both /world and /world/car/driver). Other uses of * are not (yet) supported.

EntityPathFilter sorts the rule by entity path, with recursive coming before non-recursive. This means the last matching rule is also the most specific one. For instance:

+ /world/**
- /world
- /world/car/**
+ /world/car/driver

The last rule matching /world/car/driver is + /world/car/driver, so it is included. The last rule matching /world/car/hood is - /world/car/**, so it is excluded. The last rule matching /world is - /world, so it is excluded. The last rule matching /world/house is + /world/**, so it is included.

Fields

rules: BTreeMap<EntityPathRule, RuleEffect>

Implementations

impl EntityPathFilter

pub fn parse_forgiving( rules: &str, subst_env: &EntityPathSubs ) -> EntityPathFilter

Parse an entity path filter from a string while ignore syntax errors.

Example of rules:

+ /world/**
- /world/roads/**
+ /world/roads/main

Each line is a rule.

The first character should be + or -. If missing, + is assumed. The rest of the line is trimmed and treated as an entity path.

Conflicting rules are resolved by the last rule.

pub fn from_query_expressions_forgiving<'a>( rules: impl IntoIterator<Item = &'a str>, subst_env: &EntityPathSubs ) -> EntityPathFilter

Build a filter from a list of query expressions.

Each item in the iterator should be a query expression.

The first character should be + or -. If missing, + is assumed. The rest of the expression is trimmed and treated as an entity path.

Conflicting rules are resolved by the last rule.

pub fn parse_strict( rules: &str, subst_env: &EntityPathSubs ) -> Result<EntityPathFilter, EntityPathFilterParseError>

Parse an entity path filter from a string, returning an error if the syntax is invalid.

Example of rules:

+ /world/**
- /world/roads/**
+ /world/roads/main

Each line is a rule.

The first character should be + or -. If missing, + is assumed. The rest of the line is trimmed and treated as an entity path.

Conflicting rules are resolved by the last rule.

pub fn from_query_expressions_strict<'a>( rules: impl IntoIterator<Item = &'a str>, subst_env: &EntityPathSubs ) -> Result<EntityPathFilter, EntityPathFilterParseError>

Build a filter from a list of query expressions.

Each item in the iterator should be a query expression.

The first character should be + or -. If missing, + is assumed. The rest of the expression is trimmed and treated as an entity path.

Conflicting rules are resolved by the last rule.

pub fn all() -> EntityPathFilter

Creates a filter that accepts everything.

pub fn single_entity_filter(entity_path: &EntityPath) -> EntityPathFilter

Creates a new entity path filter that includes only a single entity.

pub fn subtree_entity_filter(entity_path: &EntityPath) -> EntityPathFilter

Creates a new entity path filter that includes a single subtree.

pub fn add_rule(&mut self, effect: RuleEffect, rule: EntityPathRule)

pub fn iter_expressions(&self) -> impl Iterator<Item = String>

pub fn formatted(&self) -> String

pub fn most_specific_match(&self, path: &EntityPath) -> Option<RuleEffect>

Find the most specific matching rule and return its effect. If no rule matches, return None.

pub fn matches(&self, path: &EntityPath) -> bool

Does this filter include the given entity path?

pub fn matches_exactly(&self, entity_path: &EntityPath) -> bool

Is there a rule for this exact entity path (ignoring subtree)?

pub fn add_exact(&mut self, clone: EntityPath)

Include this entity, but not the subtree.

pub fn add_subtree(&mut self, clone: EntityPath)

Include this entity with subtree.

pub fn remove_subtree_and_matching_rules(&mut self, clone: EntityPath)

Remove a subtree and any existing rules that it would match.

Because most-specific matches win, if we only add a subtree exclusion it can still be overridden by existing inclusions. This method ensures that not only do we add a subtree exclusion, but clear out any existing inclusions or (now redundant) exclusions that would match the subtree.

pub fn remove_rule_for(&mut self, entity_path: &EntityPath)

Remove any rule for the given entity path (ignoring whether or not that rule includes the subtree).

pub fn contains_rule_for_exactly(&self, entity_path: &EntityPath) -> bool

Is there any rule for this entity path?

Whether or not the subtree is included is NOT important.

pub fn is_explicitly_included(&self, entity_path: &EntityPath) -> bool

Is this entity path explicitly included?

Whether or not the subtree is included is NOT important.

pub fn is_explicitly_excluded(&self, entity_path: &EntityPath) -> bool

Is this entity path explicitly excluded?

Whether or not the subtree is included is NOT important.

pub fn is_anything_in_subtree_included(&self, path: &EntityPath) -> bool

Is anything under this path included (including self)?

pub fn is_superset_of(&self, other: &EntityPathFilter) -> bool

Checks whether this results of this filter “fully contain” the results of another filter.

If this returns true there should not exist any EntityPath for which Self::matches would return true and the other filter would return false for this filter.

This check operates purely on the rule expressions and not the actual entity tree, and will thus not reason about entities included in an actual recording: different queries that are not a superset of each other may still query the same entities in given recording.

This is a conservative estimate, and may return false in situations where the query does in fact cover the other query. However, it should never return true in a case where the other query would not be fully covered.

Trait Implementations

impl AddAssign for EntityPathFilter

fn add_assign(&mut self, rhs: EntityPathFilter)

The union of all rules

impl Clone for EntityPathFilter

fn clone(&self) -> EntityPathFilter

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for EntityPathFilter

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for EntityPathFilter

fn default() -> EntityPathFilter

Returns the “default value” for a type.

impl Hash for EntityPathFilter

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

where H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for EntityPathFilter

fn eq(&self, other: &EntityPathFilter) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Sum for EntityPathFilter

fn sum<I>(iter: I) -> EntityPathFilter

where I: Iterator<Item = EntityPathFilter>,

The union of all rules

impl TryFrom<&str> for EntityPathFilter

type Error = EntityPathFilterParseError

The type returned in the event of a conversion error.

fn try_from( value: &str ) -> Result<EntityPathFilter, <EntityPathFilter as TryFrom<&str>>::Error>

Performs the conversion.

impl Eq for EntityPathFilter

impl StructuralPartialEq for EntityPathFilter