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.