You are here: Start » Programming Tips » Understanding OrNil Filter Variants

Understanding OrNil Filter Variants

What are OrNil filter variants

Filter variants distinguish various approaches to a single task and are packed into a single task related group. Most of the time filter variants will use a distinct algorithm or a different set of input data to achieve the same result at the end. In case of OrNil filter variants the difference lies in the error handling output data type. OrNil filter variants are available when a filter expects a non-empty data collection on input and make it possible to skip the execution instead of stopping it with a Domain Error in the Unsafe variant. When this happens all affected outputs are set to the Nil value.

Why were OrNil filter variants introduced

Filters like RegionMassCenter, GetArrayElement or PathBoundingRectangle expect a non-empty data collection on input in order to extract certain attributes based on the values. When the collection is empty and the Unsafe variant is used, the execution is stopped with a Domain Error. If it is beneficial to simply skip such operation instead of stopping the program, SkipEmpty(Collection) filters can be used to convert execution to conditional processing and skip it entirely when the collection is empty. OrNil filter variants are a natural progression as they require less work and provide the same capability.

When should OrNil filter variants be used

Use OrNil filter variants when there's a need to skip the execution after invalid input data was fed to a filter instead of stopping it.

When do OrNil filter variants skip the execution

The conditions vary depending on the filter. Most of the time the main condition is an empty data collection on input. Some OrNil filter variants may have additional conditions described on their help pages. Do note though that OrNil filter variants will still throw Domain Error exceptions if the values provided are outside of the domain, e.g. negative array index.

RegionMassCenter throwing a Domain Error on empty input region. The program execution is stopped.

RegionMassCenter not being executed due to conditional processing introduced with SkipEmptyRegion. Program execution continues.

RegionMassCenter in the OrNil variant safely executed and introduces conditional processing on its output. Program execution continues.

Previous: Optimizing Image Analysis for Speed

Next: Working with XML Trees