Introduction
Try to avoid awkward punctuation in the introduction (parentheses, i.e., etc.) - these are reading obstacles, an introduction should be fluid. Consider changing:
Boost.Int128 is a portable implementation of a signed, and an unsigned 128-bit integer and related functionality (i.e. , , etc). Importantly, on all platforms, the sizeof the types provided in this library are exactly 128-bits.
to something like:
Boost.Int128 is a fully portable implementation of signed and unsigned 128-bit integers. The library supports a robust range of related functionality such as , , , and . On all platforms, the size of the 128 bit types provided are exactly 128-bits.
Perhaps add a paragraph to get some more numbers in the mix:
For comparison, a 64-bit unsigned integer maximum value is 18,446,744,073,709,551,615. The maximum value for a 128-bit unsigned integer is 340,282,366,920,938,463,463,374,607,431,768,211,455. For signed integers, the maxima are half of these. These enormous numbers are used in scientific and financial computing, though perhaps more often as 128-bit values holding identifiers, addresses and bit masks.
This paragraph is a little awkward, haven't you already said the library is header-only - no need to say "The library is also available as a single header here."
Consider changing:
The library is header-only, has no dependencies, and requires only C++14. The library is also available as a single header here. When using C++20 or newer, the library can be consumed as a module import boost.int128.
to two short paragraphs:
The library is header-only, has no dependencies, and requires C++14 or later. When using C++20 or later, the library can optionally be imported as a module: import boost.int128.
Boost.Int128 is available here[LINK].
Getting Started
Would have liked the "Getting Started" section to end with a "hello world" example - possibly 3 super short examples (one each for Windows, Linux, Macos), perhaps even just adding two numbers together and printing the result.
Pretty Printers
Would prefer to see the pretty printers section follow the examples. and not precede it. Seemed jarring to go from getting started straight into printing, without any working code in between.
Examples
Good to see the Examples well commented and with Expected Output - would have liked to see an introductory sentence/para to each example highlighting anything special or of note about the code, and/or the use case to which it applies.
Directory Structure
- some Headers entries are not links; can they be made links?
Formatting Support
The order of fmt, format reversed in the left-hand TOC compared to the text.
Boost.Random Support
Comparison to Boost.Multiprecision
These sections should include links to the named library - does boost:random[] work as an auto link?
Configuration Macros
Is the use of these macros trivial, or would the more complex one's benefit from a short example?
Benchmarks
Bit of a nit but the long numbers are awkward to compare quickly. For example,
9932867 10242720
They are easier to compare (no counting of digits) as:
9,832,867 10,242,720
Introduction
Try to avoid awkward punctuation in the introduction (parentheses, i.e., etc.) - these are reading obstacles, an introduction should be fluid. Consider changing:
Boost.Int128 is a portable implementation of a signed, and an unsigned 128-bit integer and related functionality (i.e. , , etc). Importantly, on all platforms, the sizeof the types provided in this library are exactly 128-bits.
to something like:
Boost.Int128 is a fully portable implementation of signed and unsigned 128-bit integers. The library supports a robust range of related functionality such as , , , and . On all platforms, the size of the 128 bit types provided are exactly 128-bits.
Perhaps add a paragraph to get some more numbers in the mix:
For comparison, a 64-bit unsigned integer maximum value is 18,446,744,073,709,551,615. The maximum value for a 128-bit unsigned integer is 340,282,366,920,938,463,463,374,607,431,768,211,455. For signed integers, the maxima are half of these. These enormous numbers are used in scientific and financial computing, though perhaps more often as 128-bit values holding identifiers, addresses and bit masks.
This paragraph is a little awkward, haven't you already said the library is header-only - no need to say "The library is also available as a single header here."
Consider changing:
The library is header-only, has no dependencies, and requires only C++14. The library is also available as a single header here. When using C++20 or newer, the library can be consumed as a module import boost.int128.
to two short paragraphs:
The library is header-only, has no dependencies, and requires C++14 or later. When using C++20 or later, the library can optionally be imported as a module: import boost.int128.
Boost.Int128 is available here[LINK].
Getting Started
Would have liked the "Getting Started" section to end with a "hello world" example - possibly 3 super short examples (one each for Windows, Linux, Macos), perhaps even just adding two numbers together and printing the result.
Pretty Printers
Would prefer to see the pretty printers section follow the examples. and not precede it. Seemed jarring to go from getting started straight into printing, without any working code in between.
Examples
Good to see the Examples well commented and with Expected Output - would have liked to see an introductory sentence/para to each example highlighting anything special or of note about the code, and/or the use case to which it applies.
Directory Structure
Formatting Support
The order of fmt, format reversed in the left-hand TOC compared to the text.
Boost.Random Support
Comparison to Boost.Multiprecision
These sections should include links to the named library - does boost:random[] work as an auto link?
Configuration Macros
Is the use of these macros trivial, or would the more complex one's benefit from a short example?
Benchmarks
Bit of a nit but the long numbers are awkward to compare quickly. For example,
9932867 10242720
They are easier to compare (no counting of digits) as:
9,832,867 10,242,720