Skip to content

Update examples and cross-references #120

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mborland merged 3 commits into from
Feb 26, 2026
Merged

Update examples and cross-references #120

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
d74ec63
Update expected output
mborland Feb 26, 2026
c1503d3
Add xref to example so the reader can run this themself
mborland Feb 26, 2026
b49d048
Add missing example to examples page
mborland Feb 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions doc/modules/ROOT/pages/design.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -176,6 +176,8 @@ Stacktrace:
7# 0x0000000000003925 in bin.v2/libs/safe_numbers/test/basic_usage_stacktrace.test/gcc-11/debug/x86_64/cxxstd-20-iso/threading-multi/visibility-hidden/basic_usage_stacktrace
----

To see these yourself see the xref:examples.adoc#examples_basic_usage_stacktrace[Basic Usage with Diagnostic Information Example].

== Runtime Overflow Policies

Different domains require different responses to overflow:
Expand Down
59 changes: 58 additions & 1 deletion doc/modules/ROOT/pages/examples.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,14 +36,71 @@ Error Detected: Overflow detected in unsigned addition
include::example$basic_usage_stacktrace.cpp[]
----

Output:
Output on Linux x64:
----
./boost/safe_numbers/detail/unsigned_integer_basis.hpp(278): Throw in function boost::safe_numbers::detail::add_helper<boost::safe_numbers::overflow_policy::throw_exception, unsigned char>::apply(boost::safe_numbers::detail::unsigned_integer_basis<unsigned char>, boost::safe_numbers::detail::unsigned_integer_basis<unsigned char>)::<lambda()>
Dynamic exception type: boost::wrapexcept<std::overflow_error>
std::exception::what: Overflow detected in u8 addition

Stacktrace:
0# 0x000000000000B19C in bin.v2/libs/safe_numbers/test/basic_usage_stacktrace.test/gcc-11/debug/x86_64/cxxstd-20-iso/threading-multi/visibility-hidden/basic_usage_stacktrace
1# 0x00000000000099D0 in bin.v2/libs/safe_numbers/test/basic_usage_stacktrace.test/gcc-11/debug/x86_64/cxxstd-20-iso/threading-multi/visibility-hidden/basic_usage_stacktrace
2# 0x0000000000009AE0 in bin.v2/libs/safe_numbers/test/basic_usage_stacktrace.test/gcc-11/debug/x86_64/cxxstd-20-iso/threading-multi/visibility-hidden/basic_usage_stacktrace
3# 0x000000000000820A in bin.v2/libs/safe_numbers/test/basic_usage_stacktrace.test/gcc-11/debug/x86_64/cxxstd-20-iso/threading-multi/visibility-hidden/basic_usage_stacktrace
4# 0x0000000000003A1E in bin.v2/libs/safe_numbers/test/basic_usage_stacktrace.test/gcc-11/debug/x86_64/cxxstd-20-iso/threading-multi/visibility-hidden/basic_usage_stacktrace
5# 0x0000000000029D90 in /lib/x86_64-linux-gnu/libc.so.6
6# __libc_start_main in /lib/x86_64-linux-gnu/libc.so.6
7# 0x0000000000003925 in bin.v2/libs/safe_numbers/test/basic_usage_stacktrace.test/gcc-11/debug/x86_64/cxxstd-20-iso/threading-multi/visibility-hidden/basic_usage_stacktrace
----

Output on MSVC x64
----
D:\a\safe_numbers\boost-root\boost/safe_numbers/detail/unsigned_integer_basis.hpp(278): Throw in function void __cdecl boost::safe_numbers::detail::add_helper<0,unsigned char>::apply::<lambda_1>::operator ()(void) const
Dynamic exception type: struct boost::wrapexcept<class std::overflow_error>
std::exception::what: Overflow detected in u8 addition

Stacktrace:
0# RtlDispatchException in C:\Windows\SYSTEM32\ntdll.dll
1# KiUserExceptionDispatch in C:\Windows\SYSTEM32\ntdll.dll
2# RaiseException in C:\Windows\System32\KERNELBASE.dll
3# _CxxThrowException at D:\a\_work\1\s\src\vctools\crt\vcruntime\src\eh\throw.cpp:79
4# boost::throw_exception<std::overflow_error> at D:\a\safe_numbers\boost-root\boost\throw_exception.hpp:171
5# `boost::safe_numbers::detail::add_helper<0,unsigned char>::apply'::`2'::<lambda_1>::operator() at D:\a\safe_numbers\boost-root\boost\safe_numbers\detail\unsigned_integer_basis.hpp:278
6# boost::safe_numbers::detail::add_helper<0,unsigned char>::apply at D:\a\safe_numbers\boost-root\boost\safe_numbers\detail\unsigned_integer_basis.hpp:318
7# boost::safe_numbers::detail::operator+<unsigned char> at D:\a\safe_numbers\boost-root\boost\safe_numbers\detail\unsigned_integer_basis.hpp:486
8# main at D:\a\safe_numbers\boost-root\libs\safe_numbers\examples\basic_usage_stacktrace.cpp:24
9# invoke_main at D:\a\_work\1\s\src\vctools\crt\vcstartup\src\startup\exe_common.inl:79
10# __scrt_common_main_seh at D:\a\_work\1\s\src\vctools\crt\vcstartup\src\startup\exe_common.inl:288
11# __scrt_common_main at D:\a\_work\1\s\src\vctools\crt\vcstartup\src\startup\exe_common.inl:331
12# mainCRTStartup at D:\a\_work\1\s\src\vctools\crt\vcstartup\src\startup\exe_main.cpp:17
13# BaseThreadInitThunk in C:\Windows\System32\KERNEL32.DLL
14# RtlUserThreadStart in C:\Windows\SYSTEM32\ntdll.dll
----

Output on Other Platforms:
----
./boost/safe_numbers/detail/unsigned_integer_basis.hpp(278): Throw in function ...
Dynamic exception type: boost::wrapexcept<std::overflow_error>
std::exception::what: Overflow detected in u8 addition
----
====

[#examples_basic_bounded_usage]
== Basic Bounded Usage

.This https://github.com/boostorg/safe_numbers/blob/develop/examples/basic_bounded_usage.cpp[example] demonstrates the default behavior where bounded arithmetic that exceeds the declared range throws an exception.
====
[source, c++]
----
include::example$basic_bounded_usage.cpp[]
----

Output:
----
Error Detected: bounded_uint<0, 100> addition result out of range
----
====

[#examples_construction]
== Construction and Conversion

Expand Down
Loading