Add section on literals with note on how they construct

Author: mborland

doc/decimal.adoc

@@ -20,6 +20,7 @@ include::decimal/generic_decimal.adoc[]
 include::decimal/decimal32.adoc[]
 include::decimal/decimal64.adoc[]
 include::decimal/decimal128.adoc[]
+include::decimal/literals.adoc[]
 include::decimal/numbers.adoc[]
 include::decimal/cmath.adoc[]
 include::decimal/cstdlib.adoc[]

doc/decimal/decimal128.adoc

@@ -83,14 +83,6 @@ explicit constexpr operator std::bfloat16_t() const noexcept;
 explicit constexpr operator decimal32() const noexcept;
 explicit constexpr operator decimal64() const noexcept;
 
-// Literals
-constexpr auto operator  "" _DL(const char* str) -> decimal128
-constexpr auto operator  "" _dl(const char* str) -> decimal128
-constexpr auto operator  "" _DL(unsigned long long v) -> decimal128
-constexpr auto operator  "" _dl(unsigned long long v) -> decimal128
-BOOST_DECIMAL_CXX20_CONSTEXPR auto operator  "" _DL(long double v) -> decimal128
-BOOST_DECIMAL_CXX20_CONSTEXPR auto operator  "" _dl(long double v) -> decimal128
-
 } //namespace decimal
 } //namespace boost
 

doc/decimal/decimal32.adoc

@@ -83,16 +83,6 @@ explicit constexpr operator std::bfloat16_t() const noexcept;
 explicit constexpr operator decimal64() const noexcept;
 explicit constexpr operator decimal128() const noexcept;
 
-// Literals
-constexpr auto operator  "" _DF(const char* str) -> decimal32
-constexpr auto operator  "" _df(const char* str) -> decimal32
-
-constexpr auto operator  "" _DF(unsigned long long v) -> decimal32
-constexpr auto operator  "" _dF(unsigned long long v) -> decimal32
-
-BOOST_DECIMAL_CXX20_CONSTEXPR auto operator  "" _DF(long double v) -> decimal32
-BOOST_DECIMAL_CXX20_CONSTEXPR auto operator  "" _dF(long double v) -> decimal32
-
 } //namespace decimal
 } //namespace boost
 

doc/decimal/decimal64.adoc

@@ -83,14 +83,6 @@ explicit constexpr operator std::bfloat16_t() const noexcept;
 explicit constexpr operator decimal32() const noexcept;
 explicit constexpr operator decimal128() const noexcept;
 
-// Literals
-constexpr auto operator  "" _DD(const char* str) -> decimal64
-constexpr auto operator  "" _dd(const char* str) -> decimal64
-constexpr auto operator  "" _DD(unsigned long long v) -> decimal64
-constexpr auto operator  "" _dd(unsigned long long v) -> decimal64
-BOOST_DECIMAL_CXX20_CONSTEXPR auto operator  "" _DD(long double v) -> decimal64
-BOOST_DECIMAL_CXX20_CONSTEXPR auto operator  "" _dd(long double v) -> decimal64
-
 } //namespace decimal
 } //namespace boost
 

doc/decimal/literals.adoc

@@ -0,0 +1,41 @@
+////
+Copyright 2023 Matt Borland
+Distributed under the Boost Software License, Version 1.0.
+https://www.boost.org/LICENSE_1_0.txt
+////
+
+[#literals]
+= Literals Support
+:idprefix: literals_
+
+The following literals are offered to construct each of the types:
+
+[source, c++]
+----
+namespace boost {
+namespace decimal {
+
+constexpr auto operator  "" _DF(const char* str) -> decimal32
+constexpr auto operator  "" _df(const char* str) -> decimal32
+
+constexpr auto operator  "" _DF(unsigned long long v) -> decimal32
+constexpr auto operator  "" _dF(unsigned long long v) -> decimal32
+
+constexpr auto operator  "" _DD(const char* str) -> decimal64
+constexpr auto operator  "" _dd(const char* str) -> decimal64
+
+constexpr auto operator  "" _DD(unsigned long long v) -> decimal64
+constexpr auto operator  "" _dd(unsigned long long v) -> decimal64
+
+constexpr auto operator  "" _DL(const char* str) -> decimal128
+constexpr auto operator  "" _dl(const char* str) -> decimal128
+
+constexpr auto operator  "" _DL(unsigned long long v) -> decimal128
+constexpr auto operator  "" _dl(unsigned long long v) -> decimal128
+
+} //namespace decimal
+} //namespace boost
+----
+
+IMPORTANT: `0.2_DF` is equivalent to calling `decimal32{2, -1}`.
+These are different from calling `decimal32{0.2}` which converts from a floating-point value which may or may not be exactly represented.