bit_assertion -> bit_verify

CMakeLists.txt

@@ -30,8 +30,8 @@ if (PROJECT_IS_TOP_LEVEL)
     include(compiler_init)
     compiler_init(bit)
 
-    # Debug builds get the BIT_DEBUG flag set otherwise we set the BIT_NDEBUG flag
-    target_compile_definitions(bit INTERFACE $<IF:$<CONFIG:Debug>, BIT_DEBUG=1, BIT_NDEBUG=1>)
+    # Debug builds get the BIT_VERIFY flag set.
+    target_compile_definitions(bit INTERFACE $<$<CONFIG:Debug>: -DBIT_VERIFY>)
 
     # For neatness, we put the example executables in build/bin/.
     include(GNUInstallDirs)

docs/_quarto.yml

@@ -157,12 +157,12 @@ website:
             - text: "---"
             - section: "Debugging"
               contents:
-                  - text: "Assertions"
-                    href: content/bit_assertion/index.qmd
+                  - text: "Verifications"
+                    href: content/verify/index.qmd
                   - text: "Compiler Flags"
-                    href: content/bit_assertion/index.qmd#compiler-flags
+                    href: content/verify/index.qmd#compiler-flags
                   - text: "Design Rationale"
-                    href: content/bit_assertion/index.qmd#design-rationale
+                    href: content/verify/index.qmd#design-rationale
             - text: "---"
             - section: "Technical Notes"
               contents:

docs/content/_common.qmd

@@ -8,11 +8,9 @@ $$
 $$
 :::
 
-<!-- Our assertion macros and compiler flags that control them -->
-[`BIT_DEBUG`]:                          /content/bit_assertion/index.qmd
-[`NDEBUG`]:                             /content/bit_assertion/index.qmd
-[`bit_assertion`]:                      /content/bit_assertion/index.qmd
-[`bit_debug_assertion`]:                /content/bit_assertion/index.qmd
+<!-- Our verify macro and compiler flag that controls it -->
+[`BIT_VERIFY`]:                         /content/verify/index.qmd
+[`bit_verify`]:                         /content/verify/index.qmd
 
 <!-- Formatted links to the pages for the bit::vector class -->
 [`bit::vector`]:                        /content/vector/index.qmd

docs/content/matrix/access.qmd

@@ -41,7 +41,7 @@ col(std::size_t j) const;                   // <6>
 ::: {.callout-warning}
 # Range checks
 In general, these methods do *not* check whether an index is in bounds, and if it isn't, the behavior is undefined (but bound to be wrong!)
-Set the `BIT_DEBUG` flag at compile time to check this condition --- any violation will cause the program to abort with a helpful message.
+Set the `BIT_VERIFY` flag at compile time to check this condition --- any violation will cause the program to abort with a helpful message.
 :::
 
 [Example]{.bt}
@@ -82,4 +82,4 @@ Col 2: [1 0 1 0]
 
 ### See Also
 [`vector::reference`] \
-[`bit_assertion`]
+[`bit_verify`]

docs/content/matrix/all.qmd

@@ -17,8 +17,8 @@ constexpr bool none() const;    // <3>
 
 ::: {.callout-caution}
 # Empty bit-matrices
-Calling these methods for an empty bit-matrix is likely an error --- if you set the `BIT_DEBUG` flag at compile time, we throw an exception with a helpful message.
-If the `BIT_DEBUG` flag is not set, `all()` and `none()` _both_ return `true` while `any()` will return `false`.
+Calling these methods for an empty bit-matrix is likely an error --- if you set the `BIT_VERIFY` flag at compile time, we throw an exception with a helpful message.
+If the `BIT_VERIFY` flag is not set, `all()` and `none()` _both_ return `true` while `any()` will return `false`.
 :::
 
 [Example]{.bt}

docs/content/matrix/characteristic_polynomial.qmd

@@ -62,7 +62,7 @@ Therefore, we expect to get the $\FF$ coefficients as `11111111`, which agrees w
 #include <bit/bit.h>
 int main()
 {
-    // For this example - turn off BIT_DEBUG and enable optimization here!
+    // For this example - turn off BIT_VERIFY and enable optimization here!
     auto M = bit::matrix<>::random(512);        // <1>
     auto p = bit::characteristic_polynomial(M);
     std::cout << "Characteristic polynomial:\n" << p << "\n\n";

docs/content/matrix/dot.qmd

@@ -44,7 +44,7 @@ The dot product is a critical operation in linear algebra, so it is fortunate th
 ::: {.callout-warning}
 # Range checking
 The function arguments must have compatible sizes. \
-Set the `BIT_DEBUG` flag at compile time to check this condition --- any violation will cause the program to abort with a helpful message.
+Set the `BIT_VERIFY` flag at compile time to check this condition --- any violation will cause the program to abort with a helpful message.
 :::
 
 [Example]{.bt}

docs/content/matrix/index.qmd

@@ -206,9 +206,8 @@ Method | Description
 ### Debugging
 Macro | Description
 ----- | -----------
-[`BIT_DEBUG`]                       | This compile-time flag enables extra safety checks.
-[`bit_debug_assertion`]                | These assertions are only checked if the `BIT_DEBUG` flag is set at compile time.
-[`bit_assertion`]               | Use this form for checks that must always be performed.
+[`BIT_VERIFY`]                      | This compile-time flag enables extra safety checks.
+[`bit_verify`]                      | These checks are only performed if the `BIT_VERIFY` flag is set at compile time.
 : {.bordered .striped .hover .responsive tbl-colwidths="[35,65]"}
 
 ## Non-member Functions

docs/content/matrix/invert.qmd

@@ -24,7 +24,7 @@ Contrast that to matrices over the reals where, mathematically at least, matrice
 
 ::: {.callout-warning}
 # The bit-matrix argument must be square
-The input matrix must be square, and the [`bit_assertion`] macro checks that pre-condition.
+The input matrix must be square, and, if the `BIT_VERIFY` flag is set at compile time, the [`bit_verify`] macro checks that pre-condition.
 :::
 
 [Example]{.bt}

docs/content/matrix/logical-op-eq.qmd

@@ -29,7 +29,7 @@ These methods all return a reference to `*this` so they can be chained with othe
 ::: {.callout-warning}
 # Dimensions must match
 The two bit-matrices in question must have the same dimensions.
-Set the `BIT_DEBUG` flag at compile time to check this condition --- any violation will cause the program to abort with a helpful message.
+Set the `BIT_VERIFY` flag at compile time to check this condition --- any violation will cause the program to abort with a helpful message.
 :::
 
 There is one other bit-twiddling method:

docs/content/matrix/logical-op.qmd

@@ -35,7 +35,7 @@ operator*(const bit::matrix<Block, Alloc> &lhs,
 ::: {.callout-warning}
 # Dimensions must match
 The two bit-matrices in question must have the same dimensions.
-Set the `BIT_DEBUG` flag at compile time to check this condition --- any violation will cause the program to abort with a helpful message.
+Set the `BIT_VERIFY` flag at compile time to check this condition --- any violation will cause the program to abort with a helpful message.
 :::
 
 [Example]{.bt}

docs/content/matrix/pow.qmd

@@ -25,7 +25,7 @@ It is also worth noting that all arithmetic in $\FF$ is mod 2, so there are no o
 
 ::: {.callout-warning}
 # The bit-matrix argument must be square
-The input matrix must be square, and the [`bit_assertion`] macro checks that pre-condition.
+The input matrix must be square, and, if the `BIT_VERIFY` flag is set at compile time, the [`bit_verify`] macro checks that pre-condition.
 :::
 
 [Example]{.bt}

docs/content/matrix/replace.qmd

@@ -23,7 +23,7 @@ replace(const bit::matrix &with);                                   // <3>
 ::: {.callout-warning}
 # Sizes must be compatible
 The sub-matrix `with` we are copying from must fit inside the existing bit-matrix!
-Set the `BIT_DEBUG` flag at compile time to check this condition --- any violation will cause the program to abort with a helpful message.
+Set the `BIT_VERIFY` flag at compile time to check this condition --- any violation will cause the program to abort with a helpful message.
 :::
 
 These methods return a reference to `*this` so they can be chained with other calls.

docs/content/matrix/sub.qmd

@@ -23,7 +23,7 @@ sub(std::size_t n) const const;                                             // <
 ::: {.callout-warning}
 # Bounds checking
 `(i0, j0)` has to be a valid index pair, and the requested dimensions must fit as a valid sub-matrix.
-Set the `BIT_DEBUG` flag at compile time to check these conditions --- any violation will cause the program to abort with a helpful message.
+Set the `BIT_VERIFY` flag at compile time to check these conditions --- any violation will cause the program to abort with a helpful message.
 :::
 
 [Example]{.bt}

docs/content/matrix/swap.qmd

@@ -19,8 +19,8 @@ These methods return a reference to `*this`, so can be chained with other calls.
 # Bounds checking
 Generally, these methods do *not* check whether the indices are in bounds.
 If they aren't, the behavior is undefined (but bound to be wrong!)
-All of them will perform range checking if you set the `BIT_DEBUG` at compile time.
-See [`bit_assertion`].
+All of them will perform range checking if you set the `BIT_VERIFY` at compile time.
+See [`bit_verify`].
 :::
 
 [Example]{.bt}

docs/content/notes/design.qmd

@@ -203,23 +203,12 @@ Arbitrary $m \times n$ bit-matrices are supported, but some methods only make se
 
 Apart from using column-major versus row-major mode, the other potentially sensible idea would be to base the whole library on bit-matrices where bit-vectors are either $n \times 1$ or $1 \times n$ bit-matrices.
 
-## Assertions
+## Bounds checking
 
 In the development cycle, it can be helpful to confirm that indices are in bounds and perform other range checks.
 However, those checks are expensive and can slow down numerical code by orders of magnitude.
 We don't want those verifications accidentally left "on" in our production code.
 
-For this reason, we include our versions of the standard [`std::assert`] macro.
-
-::: {.callout-tip}
-# Assertions have messages
-Our assertions come with the ability to print an explanation of what caused any failure.
-:::
-
-The most commonly used form in the library is `bit_debug_assertion(...)`.
-This form expands to nothing *unless* the programmer sets the `BIT_DEBUG` flag at compile time.
+For this reason, we include the [`bit_verify`] macro.
+The macro expands to nothing *unless* the programmer sets the `BIT_VERIFY` flag at compile time.
 That is typically done automatically *only* for debug software builds and is *never* done for release/optimized builds.
-
-There is also a version `bit_assertion(...)` that is very similar to the  [`std::assert`] macro with the addition of a message.
-Typically these are for assertions where the cost of the check is cheap compared to the cost of the work done in the method.
-This form expands to nothing *only if* the `NDEBUG` flag is set a compile time.

docs/content/polynomial/access.qmd

@@ -35,7 +35,7 @@ constexpr polynomial& set_coefficients(vector_type&& c);    // <10>
 # Bounds checking
 Generally, the methods do *not* check whether the index `i` is in bounds.
 The behavior is undefined if it is out of bounds, but it will surely not be good!
-Set the `BIT_DEBUG` flag at compile time to check this condition --- any violation will cause the program to abort with a helpful message.
+Set the `BIT_VERIFY` flag at compile time to check this condition --- any violation will cause the program to abort with a helpful message.
 :::
 
 The `vector_type` is simply a [`bit::vector`] with the appropriate `Block` and `Allocator` template parameters.
@@ -86,4 +86,4 @@ After call v = []
 ### See Also
 [`polynomial::reference`] \
 [`polynomial::size`]      \
-[`bit_assertion`]
+[`bit_verify`]

docs/content/polynomial/evaluation.qmd

@@ -57,7 +57,7 @@ The sum uses [Horner's method](https://en.wikipedia.org/wiki/Horner%27s_method).
 
 ::: {.callout-warning}
 # The bit-matrix argument must be square
-The input matrix must be square, and the [`bit_assertion`] macro checks that pre-condition.
+The input matrix must be square, and, if the `BIT_VERIFY` flag is set at compile time, the [`bit_verify`] macro checks that pre-condition.
 :::
 
 [Example]{.bt}

docs/content/polynomial/index.qmd

@@ -168,9 +168,8 @@ These checks can have a severe performance penalty so typically are only turned
 
 Macro | Description
 ----- | -----------
-[`BIT_DEBUG`]               | This compile-time flag enables extra safety checks.
-[`bit_debug_assertion`]        | These assertions are **only** checked if you set the `BIT_DEBUG` flag at compile time.
-[`bit_assertion`]       | These assertions are always checked.
+[`BIT_VERIFY`]          | This compile-time flag enables extra safety checks.
+[`bit_verify`]          | These checks are **only** done if you set the `BIT_VERIFY` flag at compile time.
 : {.bordered .striped .hover .responsive tbl-colwidths="[35,65]"}
 
 ## Non-member Functions

docs/content/vector/access.qmd

@@ -34,7 +34,7 @@ constexpr reference back()
 # Bounds checking
 Generally, these methods do *not* check whether the index `i` is in bounds.
 The behavior is undefined if it is out of bounds, but it will surely not be good!
-Set the `BIT_DEBUG` flag at compile time to check this condition --- any violation will cause the program to abort with a helpful message.
+Set the `BIT_VERIFY` flag at compile time to check this condition --- any violation will cause the program to abort with a helpful message.
 :::
 
 [Example]{.bt}
@@ -83,4 +83,4 @@ v.back():  0
 ### See Also
 [`vector::reference`] \
 [`vector::size`] \
-[`bit_assertion`]
+[`bit_verify`]