Filtering

Overview

Some operations allow a filter to be specified. A filter distinguishes objects that are to be operated on from those that are not.

Filters implement a boolean function that takes an object as a parameter and returns true if that object passes the filter. There are several filter class hierarchies, corresponding to the type of object they filter. There are a large number of predefined filters. The user is free to implement others.

Filter Users

Operations that use filters include:

• Selection
  • Collections returned by selection operations contain only those items that pass a specified filter.
• Messaging
  • A message is delivered only to receivers that pass a filter specified by the sender.
  • A message is delivered to a potential receiver only if its class passes all message_handler_filter child nodes of a receiver.

Filter Usage

To determine if a specific filter instance passes a specific item instance, use passes_filter().

Filter Types

Types of filter hierarchies include the following:

• property filters
• property link filters.
• node filters.
• node link filters
• message filters

A function that takes a filter argument specifies one of these types as its filter parameter.

Each filter hierarchy includes, at a minimum, implementations of the following filter types:

• any_<xxx>_filter
  • Selects every object
• none_<xxx>_filter
  • Selects no objects.
• not_<xxx>_filter
  • Inverts the result of a child filter.
• or_<xxx>_filter
  • Selects an object if any child filter does.
• and_<xxx>_filter
  • Selects an object if no child filter fails to select it.

Filter Shortcuts

Shortcut free functions are provided to construct filters that implement some of the more complex, but commonly-used patterns,

Filters are Nodes

Filter classes are derived from node. Therefore, node capabilities apply to instances of them.

Motivation

The filtering feature is motivated by:

• Decoupling
  • The user and creator of a filter need not be the same.
• Code re-use
  • Code that implements common filters and filter patterns resides in one place.
• Dynamism
  • Filtering is specified at runtime.

Note

Any operation that has a filter parameter, defaults it to nullptr. A filter with this value is treated as an any_<xxx>_filter, passing all objects.