<!--
SPDX-FileCopyrightText: 2025 Slatian

SPDX-License-Identifier: LGPL-3.0-only
-->

# Criterium Concepts

## Criterium

A Criterium is a datastructure that describes a condition that matches against one or more values, the comparison either results in a <i>match</i> or in a <i>not-match</i>.

The comparison can either be one directly by the Criterium itself using the [DirectMatch] trait its `criterium_match()` method or by compiling the Criterium to SQL and using it to query a database.

The Criterium crate provides pre-made Implementations of for numbers, strings and boolean values, you can use these to compose more complex Criteria for your datastructures. The supported features depend on which interfaces you implement for those.

[DirectMatch]: https://docs.rs/criterium/latest/criterium/trait.DirectMatch.html

## Null/None Values

Criterium uses `null`, `undefined` and `None` and "unset" interchangably, all of them mean that the value is not defined and therefore not equals to any set value. Other Comparisons that imply a presence of a value on the other side of the operator must fail. (Similar to how SQL works)

The primitives have an `IsNone` matcher to detect the absence or undefinedness of a value.

A null equals null situaion should be avaided. Converting options of values to criteria converts them to an `Equals` for `Some(…)` and an `IsNone` for `None` inputs.

Whenever possible (without breaking semantics of course) criterium tries to convert `None` and `Unknown` results into boolean ones, i.e. when `… and true` and `… or false` situations arise. Information not being present is different from an error.

## Chain

A [CriteriumChain] is a way to connect multiple criteria with each other using boolean operators.

Usually complex queries take in a CriteriumChain with the containing type set to a custom enum that represents all the possible Criteria that are available.

While chains **can** be complex, they **don't have to** be. They could be as simple as being a container for a single citerium.

Chains follow an intentionally open data-structure, this means one can add custom functionality by implementing own traits.

[CriteriumChain]: https://docs.rs/criterium/latest/criterium/chain/enum.CriteriumChain.html

## Inverting

Inverting is used throughout Criterium to describe the process of negating the match-result, either by adding or removing a `Not` statement.

(in most progamming languages the boolean operator for this is `not` or `!`.)

Types that support inverting directly have `invert()` and `invert_if(bool)` methods.

Please note that inverting a comparison against a nullable value result in a <i>match</i> (as in `true`) when comparing against null.

