Skip to content

Commit 469d80a

Browse files
committed
docs: document always-on precondition checks and FCPP_NO_PRECONDITION_CHECKS (#29)
1 parent bfcd227 commit 469d80a

1 file changed

Lines changed: 12 additions & 0 deletions

File tree

README.md

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ The primary focus of this library is
1919
* [macOS (Makefiles/g++)](#macos-makefilesg)
2020
* [Linux (Makefiles)](#linux-makefiles)
2121
* [Windows (Visual Studio)](#windows-visual-studio)
22+
* [Error handling](#error-handling)
2223
* [Functional vector usage (fcpp::vector)](#functional-vector-usage-fcppvector)
2324
* [extract unique (distinct) elements in a set](#extract-unique-distinct-elements-in-a-set)
2425
* [zip, map, filter, sort, reduce](#zip-map-filter-sort-reduce)
@@ -91,6 +92,17 @@ cmake -S . -B build
9192
```
9293
Then open the generated ```functional_cpp.sln``` in the ```build``` folder.
9394

95+
## Error handling
96+
Operations with a precondition (for example subscripting with ```operator[]```, ```replace_range_at```, or ```zip``` on containers of unequal size) validate that precondition at runtime. If it is violated, the program is terminated immediately via ```std::abort()```.
97+
98+
Unlike the standard library's ```assert```, these checks are **always active and behave identically in debug and release builds** (they are not disabled by ```NDEBUG```), so an out-of-bounds access fails fast in production instead of becoming silent undefined behavior.
99+
100+
If you have a performance-critical section whose inputs are already known to be valid, you can compile the checks out by defining ```FCPP_NO_PRECONDITION_CHECKS```:
101+
```console
102+
cmake -S . -B build -DCMAKE_CXX_FLAGS="-DFCPP_NO_PRECONDITION_CHECKS"
103+
```
104+
With the checks disabled, violating a precondition is undefined behavior, exactly like the underlying ```std::vector```/```std::set```/```std::map```.
105+
94106
## Functional vector usage (fcpp::vector)
95107
### extract unique (distinct) elements in a set
96108
```c++

0 commit comments

Comments
 (0)