DocWire SDK
DocWire SDK: Award-winning modern data processing in C++20. SourceForge Community Choice & Microsoft support. AI-driven processing. Supports nearly 100 data formats, including email boxes and OCR. Boost efficiency in text extraction, web data extraction, data mining, document analysis. Offline processing possible for security and confidentiality
Public Member Functions | List of all members
docwire::ensure< T > Class Template Reference

A utility for creating expressive, exception-throwing assertions in a fluent style. More...

#include <ensure.h>

Public Member Functions

 ensure (const T &value, const source_location &loc=source_location::current())
 Constructs an ensure object, capturing a value and the source location of the call. More...
 
template<typename U >
void operator== (const U &other) const
 Performs an equality check (==). Throws if m_value != other. More...
 
template<typename U >
void operator!= (const U &other) const
 Performs an inequality check (!=). Throws if m_value == other. More...
 
template<typename U >
void operator> (const U &other) const
 Performs a greater-than check (>). Throws if m_value <= other. More...
 
template<typename U >
void operator>= (const U &other) const
 Performs a greater-than-or-equal-to check (>=). Throws if m_value < other. More...
 
template<typename U >
void operator< (const U &other) const
 Performs a less-than check (<). Throws if m_value >= other. More...
 
template<typename U >
void operator<= (const U &other) const
 Performs a less-than-or-equal-to check (<=). Throws if m_value > other. More...
 
template<typename U >
requires string_like< T > &&string_like< U > void contains (const U &substring) const
 Checks if the held string-like value contains a substring. Throws if it does not. More...
 
void is_one_of (std::initializer_list< T > expected_values) const
 Checks if the held value is present in a given set of values. Throws if it is not. More...
 

Detailed Description

template<typename T>
class docwire::ensure< T >

A utility for creating expressive, exception-throwing assertions in a fluent style.

This class is the core of a fluent validation API. It is designed to be constructed with a value to be tested, and then used with a comparison operator to check a condition. If the condition fails, it throws a docwire::error with rich diagnostic information, including the source location of the check and the values involved.

The intended usage is natural and expressive:

docwire::ensure(actual_value) == expected_value;
docwire::ensure(similarity_score) > 0.9;
docwire::ensure(my_string).contains("substring");
docwire::ensure
ensure(const T &, const docwire::source_location &) -> ensure< T >
Deduction guide for the ensure class template.

To prevent accidental misuse where a check is written but no comparison is performed (e.g., docwire::ensure(a == b);), the class is marked [[nodiscard]] to encourage compiler warnings. More importantly, in debug builds, its destructor will assert if no comparison operator was called, immediately flagging the bug at runtime. This runtime check is compiled out in release builds for zero performance overhead.

Performance
In release builds (when NDEBUG is defined), this class is a true zero-cost abstraction. Compilers like GCC, Clang, and MSVC with standard optimizations (e.g., -O2 or /O2) will inline the constructor and operators, completely optimizing away the temporary ensure object. The resulting machine code for a check like ensure(a) == b; is identical to a handwritten if (!(a == b)) throw ...;, imposing no overhead on the success path.
Template Parameters
TThe type of the value being held for comparison.

Definition at line 55 of file ensure.h.

Constructor & Destructor Documentation

◆ ensure()

template<typename T >
docwire::ensure< T >::ensure ( const T &  value,
const source_location &  loc = source_location::current() 
)
inlineexplicit

Constructs an ensure object, capturing a value and the source location of the call.

Parameters
valueThe value to be tested (the left-hand side of a future comparison).
locThe source location, captured automatically by the compiler.

Definition at line 63 of file ensure.h.

Member Function Documentation

◆ contains()

template<typename T >
template<typename U >
requires string_like<T>&& string_like<U> void docwire::ensure< T >::contains ( const U &  substring) const
inline

Checks if the held string-like value contains a substring. Throws if it does not.

This method is only available if both the held type T and the argument type U are string-like (e.g., std::string, std::string_view, const char*).

Parameters
substringThe substring to search for.

Definition at line 153 of file ensure.h.

◆ is_one_of()

template<typename T >
void docwire::ensure< T >::is_one_of ( std::initializer_list< T >  expected_values) const
inline

Checks if the held value is present in a given set of values. Throws if it is not.

This provides a convenient way to check against a list of acceptable outcomes.

ensure(status_code).is_one_of({200, 201, 204});
docwire::ensure::ensure
ensure(const T &value, const source_location &loc=source_location::current())
Constructs an ensure object, capturing a value and the source location of the call.
Definition: ensure.h:63
Parameters
expected_valuesAn initializer list of values to check against.

Definition at line 167 of file ensure.h.

◆ operator!=()

template<typename T >
template<typename U >
void docwire::ensure< T >::operator!= ( const U &  other) const
inline

Performs an inequality check (!=). Throws if m_value == other.

Parameters
otherThe value to compare against.

Definition at line 95 of file ensure.h.

◆ operator<()

template<typename T >
template<typename U >
void docwire::ensure< T >::operator< ( const U &  other) const
inline

Performs a less-than check (<). Throws if m_value >= other.

Parameters
otherThe value to compare against.

Definition at line 128 of file ensure.h.

◆ operator<=()

template<typename T >
template<typename U >
void docwire::ensure< T >::operator<= ( const U &  other) const
inline

Performs a less-than-or-equal-to check (<=). Throws if m_value > other.

Parameters
otherThe value to compare against.

Definition at line 139 of file ensure.h.

◆ operator==()

template<typename T >
template<typename U >
void docwire::ensure< T >::operator== ( const U &  other) const
inline

Performs an equality check (==). Throws if m_value != other.

Parameters
otherThe value to compare against (the right-hand side).

Definition at line 84 of file ensure.h.

◆ operator>()

template<typename T >
template<typename U >
void docwire::ensure< T >::operator> ( const U &  other) const
inline

Performs a greater-than check (>). Throws if m_value <= other.

Parameters
otherThe value to compare against.

Definition at line 106 of file ensure.h.

◆ operator>=()

template<typename T >
template<typename U >
void docwire::ensure< T >::operator>= ( const U &  other) const
inline

Performs a greater-than-or-equal-to check (>=). Throws if m_value < other.

Parameters
otherThe value to compare against.

Definition at line 117 of file ensure.h.

The documentation for this class was generated from the following file: