Getting Started

Boost.Decimal is header-only and has no dependencies, so in most cases it is enough to add the library’s include directory to your compiler’s search path and include the umbrella header:

#include <boost/decimal.hpp>

The umbrella header pulls in the six decimal types and every feature that has no external dependency. The optional {fmt} support in fmt_format.hpp is not included by the umbrella and must be included explicitly. See Directory Structure for the full header list.

B2

Run the following commands to clone the latest version of Boost, prepare the Boost.Build system, and build with C++14 as the default standard:

git clone https://github.com/boostorg/boost
cd boost
git submodule update --init
./bootstrap
./b2 cxxstd=14

To install the headers system-wide, run:

sudo ./b2 install cxxstd=14

The value of cxxstd must be at least 14. See the b2 documentation under cxxstd for all valid values.

CMake

Boost.Decimal ships a CMake package and the Boost::decimal target. When building against a Boost tree that contains this library, request it and link the interface target:

cmake .. -DBOOST_INCLUDE_LIBRARIES="decimal"

target_link_libraries(my_target PRIVATE Boost::decimal)

The library can also be built and installed on its own, which installs the headers, the CMake package files, and a pkg-config file:

git clone https://github.com/boostorg/decimal
cd decimal
mkdir build && cd build
cmake ..
cmake --build . --target install

To install somewhere other than the default system location, pass CMAKE_INSTALL_PREFIX at the configure step:

cmake .. -DCMAKE_INSTALL_PREFIX=/your/custom/path
cmake --build . --target install

The installed package is then consumed with find_package, which provides the same Boost::decimal target:

find_package(boost_decimal REQUIRED)

target_link_libraries(my_target PRIVATE Boost::decimal)

If a custom CMAKE_INSTALL_PREFIX was used, the consuming project has to be told where to look, for example by configuring it with cmake -DCMAKE_PREFIX_PATH=/your/custom/path.

The library can also be consumed without installing it at all, using FetchContent:

include(FetchContent)
FetchContent_Declare(
    decimal
    GIT_REPOSITORY https://github.com/boostorg/decimal
    GIT_TAG        develop
)
FetchContent_MakeAvailable(decimal)

target_link_libraries(my_target PRIVATE Boost::decimal)

vcpkg

Available in the official vcpkg sources.

Conan

Available in the official conan sources as part of the Boost distribution.

C++20 Module

When compiling with C++20 or newer, the library can be consumed as a named module instead of via header inclusion:

import boost.decimal;

The module interface unit is module/decimal.cppm, and consumers of the module compile with BOOST_DECIMAL_USE_MODULE defined. It is built either by b2 from module/Jamfile, or by CMake with BOOST_DECIMAL_BUILD_MODULE set, in which case the toolchain must also provide the standard library module (import std). Both in-tree module builds use C++23.

CUDA Support

The types and many of the functions can run on both host and device under CUDA. Compile with a CUDA-aware toolchain and define BOOST_DECIMAL_ENABLE_CUDA. Functions carrying BOOST_DECIMAL_HOST_DEVICE or BOOST_DECIMAL_CUDA_CONSTEXPR in their signature run on both host and device; all others run on host only. See Use of the library in a CUDA kernel for a complete example.

Dependencies

The library has no required dependencies and needs only a conforming C++14 compiler. Two headers depend on facilities that may not be present, and each detects its own availability:

<boost/decimal/format.hpp> provides the <format> support. It requires C++20 and a standard library that supplies <format> (GCC >= 13, Clang >= 18, MSVC >= 19.40). It is included by the umbrella header, and defines BOOST_DECIMAL_HAS_FORMAT_SUPPORT when the support is active.
<boost/decimal/fmt_format.hpp> provides the {fmt} support with any language standard. It must be included explicitly, and defines BOOST_DECIMAL_HAS_FMTLIB_SUPPORT when {fmt} is found.

Compiling a Program

Because the library is header-only, a single command compiles and runs a program that uses it. Substitute the path to your Boost installation for /path/to/boost:

Linux

g++ -std=c++14 -I /path/to/boost first_example.cpp -o first_example && ./first_example

macOS

clang++ -std=c++14 -I /path/to/boost first_example.cpp -o first_example && ./first_example

Windows

cl /EHsc /std:c++14 /I C:\path\to\boost first_example.cpp && first_example.exe

The program itself, along with its expected output, is shown in Basic Usage.

Edit this Page