<commit_before># cauldron

[![Travis CI](https://travis-ci.org/lycantropos/cauldron.svg?branch=master)](https://travis-ci.org/lycantropos/cauldron)
[![Codecov](https://codecov.io/gh/lycantropos/cauldron/branch/master/graph/badge.svg)](https://codecov.io/gh/lycantropos/cauldron)
[![ReadTheDocs](https://readthedocs.org/projects/cauldron-cpp/badge/?version=latest)](https://cauldron-cpp.readthedocs.io/en/latest)
[![Licence](https://img.shields.io/github/license/lycantropos/cauldron.svg)](https://github.com/lycantropos/cauldron/blob/master/LICENSE)

`cauldron` helps to write property-based test cases
and abstract from specific examples.

The core definition is *strategy*
(which is related to [strategy pattern](https://en.wikipedia.org/wiki/Strategy_pattern),
but not the same):
an object which encapsulates an algorithm for generating specific type of values.

Strategies can be modified

- by filtering out values which do not satisfy custom predicates,
- by transforming values with custom operators

and combined

- united into one,
- passed as an argument to another strategy).

## Usage

### Simple example

Let's build strategy which always generates `true` value

```c++
#include <iostream>
#include <cauldron/just.h>


int main() {
  cauldron::Just<bool> true_values(true);
  bool true_value = true_values();
  if (true_value) {
    std::cout << "Hello, World!" << std::endl;
    return 0;
  } else {
    std::cout << "Something went wrong!" << std::endl;
    return 1;
  };
}
```

### Complex example

Let's assume we're writing a program
that works with vectors of numbers
and we need to calculate *Euclidean norm* (aka *magnitude*) of a vector.
Formula is

![magnitude](https://latex.codecogs.com/gif.latex?%5Cforall%20x%20%5Cin%20%5Cmathbb%7BR%7D%5En%20%3A%20%5Cleft%5C%7Cx%5Cright%5C%7C_2%20%3D%20%5Csqrt%7B%20%5Cleft%7C%20x_1%20%5Cright%7C%5E2%20+%20%5Cldots%20+%20%5Cleft%7C%20x_n%20%5Cright%7C%5E2%20%7D)

where `n` is the vector space dimension.

Magnitude satisfies next ratios

1. Magnitude of zero vector equals to zero 

![zero vector](https://latex.codecogs.com/gif.latex?%5Cleft%5C%7C%5Cvec%7B0%7D%5Cright%5C%7C_2%20%3D%200)

2. Magnitude of non-zero vector is always positive

![non-zero vector](https://latex.codecogs.com/gif.latex?%5Cforall%20x%20%5Cin%20%5Cmathbb%7BR%7D%5En%20%3A%20x%20%5Cneq%20%5Cvec%7B0%7D%20%5CRightarrow%20%5Cleft%5C%7Cx%5Cright%5C%7C_2%20%3E%200)

3. [Triangle inequality](https://en.wikipedia.org/wiki/Triangle_inequality)<commit_msg>Using 'LaTeX' formula for space dimension<commit_after># cauldron

[![Travis CI](https://travis-ci.org/lycantropos/cauldron.svg?branch=master)](https://travis-ci.org/lycantropos/cauldron)
[![Codecov](https://codecov.io/gh/lycantropos/cauldron/branch/master/graph/badge.svg)](https://codecov.io/gh/lycantropos/cauldron)
[![ReadTheDocs](https://readthedocs.org/projects/cauldron-cpp/badge/?version=latest)](https://cauldron-cpp.readthedocs.io/en/latest)
[![Licence](https://img.shields.io/github/license/lycantropos/cauldron.svg)](https://github.com/lycantropos/cauldron/blob/master/LICENSE)

`cauldron` helps to write property-based test cases
and abstract from specific examples.

The core definition is *strategy*
(which is related to [strategy pattern](https://en.wikipedia.org/wiki/Strategy_pattern),
but not the same):
an object which encapsulates an algorithm for generating specific type of values.

Strategies can be modified

- by filtering out values which do not satisfy custom predicates,
- by transforming values with custom operators

and combined

- united into one,
- passed as an argument to another strategy).

## Usage

### Simple example

Let's build strategy which always generates `true` value

```c++
#include <iostream>
#include <cauldron/just.h>


int main() {
  cauldron::Just<bool> true_values(true);
  bool true_value = true_values();
  if (true_value) {
    std::cout << "Hello, World!" << std::endl;
    return 0;
  } else {
    std::cout << "Something went wrong!" << std::endl;
    return 1;
  };
}
```

### Complex example

Let's assume we're writing a program
that works with vectors of numbers
and we need to calculate *Euclidean norm* (aka *magnitude*) of a vector.
Formula is

![magnitude](https://latex.codecogs.com/gif.latex?%5Cforall%20x%20%5Cin%20%5Cmathbb%7BR%7D%5En%20%3A%20%5Cleft%5C%7Cx%5Cright%5C%7C_2%20%3D%20%5Csqrt%7B%20%5Cleft%7C%20x_1%20%5Cright%7C%5E2%20+%20%5Cldots%20+%20%5Cleft%7C%20x_n%20%5Cright%7C%5E2%20%7D)

where ![n](https://latex.codecogs.com/gif.latex?n) is the vector space dimension.

Magnitude satisfies next ratios

1. Magnitude of zero vector equals to zero 

![zero vector](https://latex.codecogs.com/gif.latex?%5Cleft%5C%7C%5Cvec%7B0%7D%5Cright%5C%7C_2%20%3D%200)

2. Magnitude of non-zero vector is always positive

![non-zero vector](https://latex.codecogs.com/gif.latex?%5Cforall%20x%20%5Cin%20%5Cmathbb%7BR%7D%5En%20%3A%20x%20%5Cneq%20%5Cvec%7B0%7D%20%5CRightarrow%20%5Cleft%5C%7Cx%5Cright%5C%7C_2%20%3E%200)

3. [Triangle inequality](https://en.wikipedia.org/wiki/Triangle_inequality)
{'fraction_non_alphanumeric': 0.15151515151515152, 'fraction_numerical': 0.05228758169934641, 'mean_word_length': 5.9559228650137745, 'pattern_counts': {'":': 0, '<': 25, '<?xml version=': 0, '>': 9, 'https://': 27, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6658738', 'n_tokens_mistral': 2070, 'n_tokens_neox': 1940, 'n_words': 364}