1[/ 2 Copyright 2011 - 2020 John Maddock. 3 Copyright 2013 - 2019 Paul A. Bristow. 4 Copyright 2013 Christopher Kormanyos. 5 6 Distributed under the Boost Software License, Version 1.0. 7 (See accompanying file LICENSE_1_0.txt or copy at 8 http://www.boost.org/LICENSE_1_0.txt). 9] 10 11[section:backendconc Backend Requirements] 12 13The requirements on the `Backend` template argument to `number` are split up into 14sections: compulsory and optional. 15 16Compulsory requirements have no default implementation in the library, therefore if the feature 17they implement is to be supported at all, then they must be implemented by the backend. 18 19Optional requirements have default implementations that are called if the backend doesn't provide 20its own. Typically the backend will implement these to improve performance. 21 22In the following tables, type B is the `Backend` template argument to `number`, `b` and `b2` are 23a variables of type B, `pb` is a variable of type B*, `cb`, `cb2` and `cb3` are constant variables of type `const B`, 24`rb` is a variable of type `B&&`, `a` and `a2` are variables of Arithmetic type, 25`s` is a variable of type `const char*`, `ui` is a variable of type `unsigned`, `bb` is a variable of type `bool`, 26`pa` is a variable of type pointer-to-arithmetic-type, `exp` is a variable of type `B::exp_type`, 27`pexp` is a variable of type `B::exp_type*`, `i` is a variable of type `int`, `pi` pointer to a variable of type `int`, 28B2 is another type that meets these requirements, b2 is a variable of type B2, `ss` is variable of type `std::streamsize` 29and `ff` is a variable of type `std::ios_base::fmtflags`. 30 31[table Compulsory Requirements on the Backend type. 32[[Expression][Return Type][Comments][Throws]] 33[[`B::signed_types`][`mpl::list<type-list>`][A list of signed integral types that can be assigned to type B. The types shall be 34 listed in order of size, smallest first, and shall terminate in the type that is `std::intmax_t`.][[space]]] 35[[`B::unsigned_types`][`mpl::list<type-list>`][A list of unsigned integral types that can be assigned to type B. The types shall be 36 listed in order of size, smallest first, and shall terminate in the type that is `std::uintmax_t`.][[space]]] 37[[`B::float_types`][`mpl::list<type-list>`][A list of floating-point types that can be assigned to type B.The types shall be 38 listed in order of size, smallest first, and shall terminate in type `long double`.][[space]]] 39[[`B::exponent_type`][A signed integral type.][The type of the exponent of type B. This type is required only for floating-point types.][[space]]] 40[[`B()`][ ][Default constructor.][[space]]] 41[[`B(cb)`][ ][Copy Constructor.][[space]]] 42[[`b = b`][`B&`][Assignment operator.][[space]]] 43[[`b = a`][`B&`][Assignment from an Arithmetic type. The type of `a` shall be listed in one of the type lists 44 `B::signed_types`, `B::unsigned_types` or `B::float_types`.][[space]]] 45[[`b = s`][`B&`][Assignment from a string.][Throws a `std::runtime_error` if the string could not be interpreted as a valid number.]] 46[[`b.swap(b)`][`void`][Swaps the contents of its arguments.][`noexcept`]] 47[[`cb.str(ss, ff)`][`std::string`][Returns the string representation of `b` with `ss` digits and formatted according to the flags set in `ff`. 48 If `ss` is zero, then returns as many digits as are required to reconstruct the original value.][[space]]] 49[[`b.negate()`][`void`][Negates `b`.][[space]]] 50[[`cb.compare(cb2)`][`int`][Compares `cb` and `cb2`, returns a value less than zero if `cb < cb2`, a value greater than zero if `cb > cb2` and zero 51 if `cb == cb2`.][`noexcept`]] 52[[`cb.compare(a)`][`int`][Compares `cb` and `a`, returns a value less than zero if `cb < a`, a value greater than zero if `cb > a` and zero 53 if `cb == a`. The type of `a` shall be listed in one of the type lists 54 `B::signed_types`, `B::unsigned_types` or `B::float_types`.][[space]]] 55[[`eval_add(b, cb)`][`void`][Adds `cb` to `b`.][[space]]] 56[[`eval_subtract(b, cb)`][`void`][Subtracts `cb` from `b`.][[space]]] 57[[`eval_multiply(b, cb)`][`void`][Multiplies `b` by `cb`.][[space]]] 58[[`eval_divide(b, cb)`][`void`][Divides `b` by `cb`.] 59 [`std::overflow_error` if cb has the value zero, and `std::numeric_limits<number<B> >::has_infinity == false`]] 60[[`eval_modulus(b, cb)`][`void`][Computes `b %= cb`, only required when `B` is an integer type.] 61 [`std::overflow_error` if cb has the value zero.]] 62[[`eval_bitwise_and(b, cb)`][`void`][Computes `b &= cb`, only required when `B` is an integer type.][[space]]] 63[[`eval_bitwise_or(b, cb)`][`void`][Computes `b |= cb`, only required when `B` is an integer type.][[space]]] 64[[`eval_bitwise_xor(b, cb)`][`void`][Computes `b ^= cb`, only required when `B` is an integer type.][[space]]] 65[[`eval_complement(b, cb)`][`void`][Computes the ones-complement of `cb` and stores the result in `b`, only required when `B` is an integer type.][[space]]] 66[[`eval_left_shift(b, ui)`][`void`][Computes `b <<= ui`, only required when `B` is an integer type.][[space]]] 67[[`eval_right_shift(b, ui)`][`void`][Computes `b >>= ui`, only required when `B` is an integer type.][[space]]] 68[[`eval_convert_to(pa, cb)`][`void`][Converts `cb` to the type of `*pa` and store the result in `*pa`. Type `B` shall support 69 conversion to at least types `std::intmax_t`, `std::uintmax_t` and `long long`. 70 Conversion to other arithmetic types can then be synthesised using other operations. 71 Conversions to other types are entirely optional.][[space]]] 72[[`eval_frexp(b, cb, pexp)`][`void`][Stores values in `b` and `*pexp` such that the value of `cb` is b * 2[super *pexp], only required when `B` is a floating-point type.][[space]]] 73[[`eval_ldexp(b, cb, exp)`][`void`][Stores a value in `b` that is cb * 2[super exp], only required when `B` is a floating-point type.][[space]]] 74[[`eval_frexp(b, cb, pi)`][`void`][Stores values in `b` and `*pi` such that the value of `cb` is b * 2[super *pi], only required when `B` is a floating-point type.] 75 [`std::runtime_error` if the exponent of cb is too large to be stored in an `int`.]] 76[[`eval_ldexp(b, cb, i)`][`void`][Stores a value in `b` that is cb * 2[super i], only required when `B` is a floating-point type.][[space]]] 77[[`eval_floor(b, cb)`][`void`][Stores the floor of `cb` in `b`, only required when `B` is a floating-point type.][[space]]] 78[[`eval_ceil(b, cb)`][`void`][Stores the ceiling of `cb` in `b`, only required when `B` is a floating-point type.][[space]]] 79[[`eval_sqrt(b, cb)`][`void`][Stores the square root of `cb` in `b`, only required when `B` is a floating-point type.][[space]]] 80[[`boost::multiprecision::number_category<B>::type`][`mpl::int_<N>`][`N` is one of the values `number_kind_integer`, `number_kind_floating_point`, `number_kind_complex`, `number_kind_rational` or `number_kind_fixed_point`. 81 Defaults to `number_kind_floating_point`.][[space]]] 82[[`eval_conj(b, cb)`][`void`][Sets `b` to the complex conjugate of `cb`. Required for complex types only - other types have a sensible default.][[space]]] 83[[`eval_proj(b, cb)`][`void`][Sets `b` to the Riemann projection of `cb`. Required for complex types only - other types have a sensible default.][[space]]] 84[[`eval_real(b, cb)`][`void`][Sets `b` to the real part of `cb`. Required for complex types only - other types have a sensible default.][[space]]] 85[[`eval_imag(b, cb)`][`void`][Sets `b` to the imaginary of `cb`. Required for complex types only - other types have a sensible default.][[space]]] 86[[`eval_set_real(b, a)`][`void`][Sets the real part of `b` to `cb`. Required for complex types only - other types have a sensible default.][[space]]] 87[[`eval_set_imag(b, a)`][`void`][Sets the imaginary part of `b` to `cb`. Required for complex types only - other types have a sensible default.][[space]]] 88] 89 90[table Optional Requirements on the Backend Type 91[[Expression][Returns][Comments][Throws]] 92 93[[['Construct and assign:]]] 94[[`B(rb)`][`B`][Move constructor. Afterwards variable `rb` shall be in sane state, albeit with unspecified value. 95 Only destruction and assignment to the moved-from variable `rb` need be supported after the operation.][`noexcept`]] 96[[`b = rb`][`B&`][Move-assign. Afterwards variable `rb` shall be in sane state, albeit with unspecified value. 97 Only destruction and assignment to the moved-from variable `rb` need be supported after the operation.][`noexcept`]] 98[[`B(a)`][`B`][Direct construction from an arithmetic type. The type of `a` shall be listed in one of the type lists 99 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 100 When not provided, this operation is simulated using default-construction followed by assignment.][[space]]] 101[[`B(b2)`][`B`][Copy constructor from a different back-end type. When not provided, a generic interconversion routine is used. 102 This constructor may be `explicit` if the corresponding frontend constructor should also be `explicit`.][[space]]] 103[[`b = b2`][`b&`][Assignment operator from a different back-end type. When not provided, a generic interconversion routine is used.][[space]]] 104[[`assign_components(b, a, a)`][`void`][Assigns to `b` the two components in the following arguments. 105 Only applies to rational and complex number types. 106 When not provided, arithmetic operations are used to synthesise the result from the two values.][[space]]] 107[[`assign_components(b, b2, b2)`][`void`][Assigns to `b` the two components in the following arguments. 108 Only applies to rational and complex number types. 109 When not provided, arithmetic operations are used to synthesise the result from the two values.][[space]]] 110 111[[['Comparisons:]]] 112[[`eval_eq(cb, cb2)`][`bool`][Returns `true` if `cb` and `cb2` are equal in value. 113 When not provided, the default implementation returns `cb.compare(cb2) == 0`.][`noexcept`]] 114[[`eval_eq(cb, a)`][`bool`][Returns `true` if `cb` and `a` are equal in value. 115 The type of `a` shall be listed in one of the type lists 116 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 117 When not provided, return the equivalent of `eval_eq(cb, B(a))`.][[space]]] 118[[`eval_eq(a, cb)`][`bool`][Returns `true` if `cb` and `a` are equal in value. 119 The type of `a` shall be listed in one of the type lists 120 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 121 When not provided, the default version returns `eval_eq(cb, a)`.][[space]]] 122[[`eval_lt(cb, cb2)`][`bool`][Returns `true` if `cb` is less than `cb2` in value. 123 When not provided, the default implementation returns `cb.compare(cb2) < 0`.][`noexcept`]] 124[[`eval_lt(cb, a)`][`bool`][Returns `true` if `cb` is less than `a` in value. 125 The type of `a` shall be listed in one of the type lists 126 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 127 When not provided, the default implementation returns `eval_lt(cb, B(a))`.][[space]]] 128[[`eval_lt(a, cb)`][`bool`][Returns `true` if `a` is less than `cb` in value. 129 The type of `a` shall be listed in one of the type lists 130 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 131 When not provided, the default implementation returns `eval_gt(cb, a)`.][[space]]] 132[[`eval_gt(cb, cb2)`][`bool`][Returns `true` if `cb` is greater than `cb2` in value. 133 When not provided, the default implementation returns `cb.compare(cb2) > 0`.][`noexcept`]] 134[[`eval_gt(cb, a)`][`bool`][Returns `true` if `cb` is greater than `a` in value. 135 The type of `a` shall be listed in one of the type lists 136 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 137 When not provided, the default implementation returns `eval_gt(cb, B(a))`.][[space]]] 138[[`eval_gt(a, cb)`][`bool`][Returns `true` if `a` is greater than `cb` in value. 139 The type of `a` shall be listed in one of the type lists 140 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 141 When not provided, the default implementation returns `eval_lt(cb, a)`.][[space]]] 142[[`eval_is_zero(cb)`][`bool`][Returns `true` if `cb` is zero, otherwise `false`. The default version of this function 143 returns `cb.compare(ui_type(0)) == 0`, where `ui_type` is `ui_type` is 144 `typename mpl::front<typename B::unsigned_types>::type`.][[space]]] 145[[`eval_get_sign(cb)`][`int`][Returns a value < zero if `cb` is negative, a value > zero if `cb` is positive, and zero if `cb` is zero. 146 The default version of this function 147 returns `cb.compare(ui_type(0))`, where `ui_type` is `ui_type` is 148 `typename mpl::front<typename B::unsigned_types>::type`.][[space]]] 149 150[[['Basic arithmetic:]]] 151[[`eval_add(b, a)`][`void`][Adds `a` to `b`. The type of `a` shall be listed in one of the type lists 152 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 153 When not provided, the default version calls `eval_add(b, B(a))`][[space]]] 154[[`eval_add(b, cb, cb2)`][`void`][Add `cb` to `cb2` and stores the result in `b`. 155 When not provided, does the equivalent of `b = cb; eval_add(b, cb2)`.][[space]]] 156[[`eval_add(b, cb, a)`][`void`][Add `cb` to `a` and stores the result in `b`. The type of `a` shall be listed in one of the type lists 157 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 158 When not provided, does the equivalent of `eval_add(b, cb, B(a))`.][[space]]] 159[[`eval_add(b, a, cb)`][`void`][Add `a` to `cb` and stores the result in `b`. The type of `a` shall be listed in one of the type lists 160 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 161 When not provided, does the equivalent of `eval_add(b, cb, a)`.][[space]]] 162[[`eval_subtract(b, a)`][`void`][Subtracts `a` from `b`. The type of `a` shall be listed in one of the type lists 163 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 164 When not provided, the default version calls `eval_subtract(b, B(a))`][[space]]] 165[[`eval_subtract(b, cb, cb2)`][`void`][Subtracts `cb2` from `cb` and stores the result in `b`. 166 When not provided, does the equivalent of `b = cb; eval_subtract(b, cb2)`.][[space]]] 167[[`eval_subtract(b, cb, a)`][`void`][Subtracts `a` from `cb` and stores the result in `b`. The type of `a` shall be listed in one of the type lists 168 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 169 When not provided, does the equivalent of `eval_subtract(b, cb, B(a))`.][[space]]] 170[[`eval_subtract(b, a, cb)`][`void`][Subtracts `cb` from `a` and stores the result in `b`. The type of `a` shall be listed in one of the type lists 171 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 172 When not provided, does the equivalent of `eval_subtract(b, cb, a); b.negate();`.][[space]]] 173[[`eval_multiply(b, a)`][`void`][Multiplies `b` by `a`. The type of `a` shall be listed in one of the type lists 174 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 175 When not provided, the default version calls `eval_multiply(b, B(a))`][[space]]] 176[[`eval_multiply(b, cb, cb2)`][`void`][Multiplies `cb` by `cb2` and stores the result in `b`. 177 When not provided, does the equivalent of `b = cb; eval_multiply(b, cb2)`.][[space]]] 178[[`eval_multiply(b, cb, a)`][`void`][Multiplies `cb` by `a` and stores the result in `b`. The type of `a` shall be listed in one of the type lists 179 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 180 When not provided, does the equivalent of `eval_multiply(b, cb, B(a))`.][[space]]] 181[[`eval_multiply(b, a, cb)`][`void`][Multiplies `a` by `cb` and stores the result in `b`. The type of `a` shall be listed in one of the type lists 182 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 183 When not provided, does the equivalent of `eval_multiply(b, cb, a)`.][[space]]] 184[[`eval_multiply_add(b, cb, cb2)`][`void`][Multiplies `cb` by `cb2` and adds the result to `b`. 185 When not provided does the equivalent of creating a temporary `B t` and `eval_multiply(t, cb, cb2)` followed by 186 `eval_add(b, t)`.][[space]]] 187[[`eval_multiply_add(b, cb, a)`][`void`][Multiplies `a` by `cb` and adds the result to `b`. 188 The type of `a` shall be listed in one of the type lists 189 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 190 When not provided does the equivalent of creating a temporary `B t` and `eval_multiply(t, cb, a)` followed by 191 `eval_add(b, t)`.][[space]]] 192[[`eval_multiply_add(b, a, cb)`][`void`][Multiplies `a` by `cb` and adds the result to `b`. 193 The type of `a` shall be listed in one of the type lists 194 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 195 When not provided does the equivalent of `eval_multiply_add(b, cb, a)`.][[space]]] 196[[`eval_multiply_subtract(b, cb, cb2)`][`void`][Multiplies `cb` by `cb2` and subtracts the result from `b`. 197 When not provided does the equivalent of creating a temporary `B t` and `eval_multiply(t, cb, cb2)` followed by 198 `eval_subtract(b, t)`.][[space]]] 199[[`eval_multiply_subtract(b, cb, a)`][`void`][Multiplies `a` by `cb` and subtracts the result from `b`. 200 The type of `a` shall be listed in one of the type lists 201 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 202 When not provided does the equivalent of creating a temporary `B t` and `eval_multiply(t, cb, a)` followed by 203 `eval_subtract(b, t)`.][[space]]] 204[[`eval_multiply_subtract(b, a, cb)`][`void`][Multiplies `a` by `cb` and subtracts the result from `b`. 205 The type of `a` shall be listed in one of the type lists 206 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 207 When not provided does the equivalent of `eval_multiply_subtract(b, cb, a)`.][[space]]] 208[[`eval_multiply_add(b, cb, cb2, cb3)`][`void`][Multiplies `cb` by `cb2` and adds the result to `cb3` storing the result in `b`. 209 When not provided does the equivalent of `eval_multiply(b, cb, cb2)` followed by 210 `eval_add(b, cb3)`. 211 For brevity, only a version showing all arguments of type `B` is shown here, but you can replace up to any 2 of 212 `cb`, `cb2` and `cb3` with any type listed in one of the type lists 213 `B::signed_types`, `B::unsigned_types` or `B::float_types`.][[space]]] 214[[`eval_multiply_subtract(b, cb, cb2, cb3)`][`void`][Multiplies `cb` by `cb2` and subtracts from the result `cb3` storing the result in `b`. 215 When not provided does the equivalent of `eval_multiply(b, cb, cb2)` followed by 216 `eval_subtract(b, cb3)`. 217 For brevity, only a version showing all arguments of type `B` is shown here, but you can replace up to any 2 of 218 `cb`, `cb2` and `cb3` with any type listed in one of the type lists 219 `B::signed_types`, `B::unsigned_types` or `B::float_types`.][[space]]] 220[[`eval_divide(b, a)`][`void`][Divides `b` by `a`. The type of `a` shall be listed in one of the type lists 221 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 222 When not provided, the default version calls `eval_divide(b, B(a))`] 223 [`std::overflow_error` if `a` has the value zero, and `std::numeric_limits<number<B> >::has_infinity == false`]] 224[[`eval_divide(b, cb, cb2)`][`void`][Divides `cb` by `cb2` and stores the result in `b`. 225 When not provided, does the equivalent of `b = cb; eval_divide(b, cb2)`.] 226 [`std::overflow_error` if `cb2` has the value zero, and `std::numeric_limits<number<B> >::has_infinity == false`]] 227[[`eval_divide(b, cb, a)`][`void`][Divides `cb` by `a` and stores the result in `b`. The type of `a` shall be listed in one of the type lists 228 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 229 When not provided, does the equivalent of `eval_divide(b, cb, B(a))`.] 230 [`std::overflow_error` if `a` has the value zero, and `std::numeric_limits<number<B> >::has_infinity == false`]] 231[[`eval_divide(b, a, cb)`][`void`][Divides `a` by `cb` and stores the result in `b`. The type of `a` shall be listed in one of the type lists 232 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 233 When not provided, does the equivalent of `eval_divide(b, B(a), cb)`.] 234 [`std::overflow_error` if cb has the value zero, and `std::numeric_limits<number<B> >::has_infinity == false`]] 235[[`eval_increment(b)`][void][Increments the value of `b` by one. 236 When not provided, does the equivalent of `eval_add(b, static_cast<ui_type>(1u))`. 237 Where `ui_type` is `typename mpl::front<typename B::unsigned_types>::type`.][[space]]] 238[[`eval_decrement(b)`][void][Decrements the value of `b` by one. 239 When not provided, does the equivalent of `eval_subtract(b, static_cast<ui_type>(1u))`. 240 Where `ui_type` is `typename mpl::front<typename B::unsigned_types>::type`.][[space]]] 241 242[[['Integer specific operations:]]] 243[[`eval_modulus(b, a)`][`void`][Computes `b %= cb`, only required when `B` is an integer type. The type of `a` shall be listed in one of the type lists 244 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 245 When not provided, the default version calls `eval_modulus(b, B(a))`] 246 [`std::overflow_error` if `a` has the value zero.]] 247[[`eval_modulus(b, cb, cb2)`][`void`][Computes `cb % cb2` and stores the result in `b`, only required when `B` is an integer type. 248 When not provided, does the equivalent of `b = cb; eval_modulus(b, cb2)`.] 249 [`std::overflow_error` if `a` has the value zero.]] 250[[`eval_modulus(b, cb, a)`][`void`][Computes `cb % a` and stores the result in `b`, only required when `B` is an integer type. The type of `a` shall be listed in one of the type lists 251 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 252 When not provided, does the equivalent of `eval_modulus(b, cb, B(a))`.] 253 [`std::overflow_error` if `a` has the value zero.]] 254[[`eval_modulus(b, a, cb)`][`void`][Computes `cb % a` and stores the result in `b`, only required when `B` is an integer type. The type of `a` shall be listed in one of the type lists 255 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 256 When not provided, does the equivalent of `eval_modulus(b, B(a), cb)`.] 257 [`std::overflow_error` if `a` has the value zero.]] 258[[`eval_bitwise_and(b, a)`][`void`][Computes `b &= cb`, only required when `B` is an integer type. The type of `a` shall be listed in one of the type lists 259 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 260 When not provided, the default version calls `eval_bitwise_and(b, B(a))`][[space]]] 261[[`eval_bitwise_and(b, cb, cb2)`][`void`][Computes `cb & cb2` and stores the result in `b`, only required when `B` is an integer type. 262 When not provided, does the equivalent of `b = cb; eval_bitwise_and(b, cb2)`.][[space]]] 263[[`eval_bitwise_and(b, cb, a)`][`void`][Computes `cb & a` and stores the result in `b`, only required when `B` is an integer type. The type of `a` shall be listed in one of the type lists 264 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 265 When not provided, does the equivalent of `eval_bitwise_and(b, cb, B(a))`.][[space]]] 266[[`eval_bitwise_and(b, a, cb)`][`void`][Computes `cb & a` and stores the result in `b`, only required when `B` is an integer type. The type of `a` shall be listed in one of the type lists 267 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 268 When not provided, does the equivalent of `eval_bitwise_and(b, cb, a)`.][[space]]] 269[[`eval_bitwise_or(b, a)`][`void`][Computes `b |= cb`, only required when `B` is an integer type. The type of `a` shall be listed in one of the type lists 270 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 271 When not provided, the default version calls `eval_bitwise_or(b, B(a))`][[space]]] 272[[`eval_bitwise_or(b, cb, cb2)`][`void`][Computes `cb | cb2` and stores the result in `b`, only required when `B` is an integer type. 273 When not provided, does the equivalent of `b = cb; eval_bitwise_or(b, cb2)`.][[space]]] 274[[`eval_bitwise_or(b, cb, a)`][`void`][Computes `cb | a` and stores the result in `b`, only required when `B` is an integer type. The type of `a` shall be listed in one of the type lists 275 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 276 When not provided, does the equivalent of `eval_bitwise_or(b, cb, B(a))`.][[space]]] 277[[`eval_bitwise_or(b, a, cb)`][`void`][Computes `cb | a` and stores the result in `b`, only required when `B` is an integer type. The type of `a` shall be listed in one of the type lists 278 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 279 When not provided, does the equivalent of `eval_bitwise_or(b, cb, a)`.][[space]]] 280[[`eval_bitwise_xor(b, a)`][`void`][Computes `b ^= cb`, only required when `B` is an integer type. The type of `a` shall be listed in one of the type lists 281 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 282 When not provided, the default version calls `eval_bitwise_xor(b, B(a))`][[space]]] 283[[`eval_bitwise_xor(b, cb, cb2)`][`void`][Computes `cb ^ cb2` and stores the result in `b`, only required when `B` is an integer type. 284 When not provided, does the equivalent of `b = cb; eval_bitwise_xor(b, cb2)`.][[space]]] 285[[`eval_bitwise_xor(b, cb, a)`][`void`][Computes `cb ^ a` and stores the result in `b`, only required when `B` is an integer type. The type of `a` shall be listed in one of the type lists 286 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 287 When not provided, does the equivalent of `eval_bitwise_xor(b, cb, B(a))`.][[space]]] 288[[`eval_bitwise_xor(b, a, cb)`][`void`][Computes `a ^ cb` and stores the result in `b`, only required when `B` is an integer type. The type of `a` shall be listed in one of the type lists 289 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 290 When not provided, does the equivalent of `eval_bitwise_xor(b, cb, a)`.][[space]]] 291[[`eval_left_shift(b, cb, ui)`][`void`][Computes `cb << ui` and stores the result in `b`, only required when `B` is an integer type. 292 When not provided, does the equivalent of `b = cb; eval_left_shift(b, a);`.][[space]]] 293[[`eval_right_shift(b, cb, ui)`][`void`][Computes `cb >> ui` and stores the result in `b`, only required when `B` is an integer type. 294 When not provided, does the equivalent of `b = cb; eval_right_shift(b, a);`.][[space]]] 295[[`eval_qr(cb, cb2, b, b2)`][`void`][Sets `b` to the result of `cb / cb2` and `b2` to the result of `cb % cb2`. Only required when `B` is an integer type. 296 The default version of this function is synthesised from other operations above.] 297 [`std::overflow_error` if `a` has the value zero.]] 298[[`eval_integer_modulus(cb, ui)`][`unsigned`][Returns the result of `cb % ui`. Only required when `B` is an integer type. 299 The default version of this function is synthesised from other operations above.] 300 [`std::overflow_error` if `a` has the value zero.]] 301[[`eval_lsb(cb)`][`unsigned`][Returns the index of the least significant bit that is set. Only required when `B` is an integer type. 302 The default version of this function is synthesised from other operations above.][[space]]] 303[[`eval_msb(cb)`][`unsigned`][Returns the index of the most significant bit that is set. Only required when `B` is an integer type. 304 The default version of this function is synthesised from other operations above.][[space]]] 305[[`eval_bit_test(cb, ui)`][`bool`][Returns true if `cb` has bit `ui` set. Only required when `B` is an integer type. 306 The default version of this function is synthesised from other operations above.][[space]]] 307[[`eval_bit_set(b, ui)`][`void`][Sets the bit at index `ui` in `b`. Only required when `B` is an integer type. 308 The default version of this function is synthesised from other operations above.][[space]]] 309[[`eval_bit_unset(b, ui)`][`void`][Unsets the bit at index `ui` in `b`. Only required when `B` is an integer type. 310 The default version of this function is synthesised from other operations above.][[space]]] 311[[`eval_bit_flip(b, ui)`][`void`][Flips the bit at index `ui` in `b`. Only required when `B` is an integer type. 312 The default version of this function is synthesised from other operations above.][[space]]] 313[[`eval_gcd(b, cb, cb2)`][`void`][Sets `b` to the greatest common divisor of `cb` and `cb2`. Only required when `B` is an integer type. 314 The default version of this function is synthesised from other operations above.][[space]]] 315[[`eval_lcm(b, cb, cb2)`][`void`][Sets `b` to the least common multiple of `cb` and `cb2`. Only required when `B` is an integer type. 316 The default version of this function is synthesised from other operations above.][[space]]] 317[[`eval_gcd(b, cb, a)`][`void`][Sets `b` to the greatest common divisor of `cb` and `cb2`. Only required when `B` is an integer type. 318 The type of `a` shall be listed in one of the type lists 319 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 320 The default version of this function calls `eval_gcd(b, cb, B(a))`.][[space]]] 321[[`eval_lcm(b, cb, a)`][`void`][Sets `b` to the least common multiple of `cb` and `cb2`. Only required when `B` is an integer type. 322 The type of `a` shall be listed in one of the type lists 323 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 324 The default version of this function calls `eval_lcm(b, cb, B(a))`.][[space]]] 325[[`eval_gcd(b, a, cb)`][`void`][Sets `b` to the greatest common divisor of `cb` and `a`. Only required when `B` is an integer type. 326 The type of `a` shall be listed in one of the type lists 327 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 328 The default version of this function calls `eval_gcd(b, cb, a)`.][[space]]] 329[[`eval_lcm(b, a, cb)`][`void`][Sets `b` to the least common multiple of `cb` and `a`. Only required when `B` is an integer type. 330 The type of `a` shall be listed in one of the type lists 331 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 332 The default version of this function calls `eval_lcm(b, cb, a)`.][[space]]] 333[[`eval_powm(b, cb, cb2, cb3)`][`void`][Sets `b` to the result of ['(cb^cb2)%cb3]. 334 The default version of this function is synthesised from other operations above.][[space]]] 335[[`eval_powm(b, cb, cb2, a)`][`void`][Sets `b` to the result of ['(cb^cb2)%a]. 336 The type of `a` shall be listed in one of the type lists 337 `B::signed_types`, `B::unsigned_types`. 338 The default version of this function is synthesised from other operations above.][[space]]] 339[[`eval_powm(b, cb, a, cb2)`][`void`][Sets `b` to the result of ['(cb^a)%cb2]. 340 The type of `a` shall be listed in one of the type lists 341 `B::signed_types`, `B::unsigned_types`. 342 The default version of this function is synthesised from other operations above.][[space]]] 343[[`eval_powm(b, cb, a, a2)`][`void`][Sets `b` to the result of ['(cb^a)%a2]. 344 The type of `a` shall be listed in one of the type lists 345 `B::signed_types`, `B::unsigned_types`. 346 The default version of this function is synthesised from other operations above.][[space]]] 347[[`eval_integer_sqrt(b, cb, b2)`][`void`][Sets `b` to the largest integer which when squared is less than `cb`, also 348 sets `b2` to the remainder, ie to ['cb - b[super 2]]. 349 The default version of this function is synthesised from other operations above.][[space]]] 350 351[[['Sign manipulation:]]] 352[[`eval_abs(b, cb)`][`void`][Set `b` to the absolute value of `cb`. 353 The default version of this functions assigns `cb` to `b`, and then calls `b.negate()` if 354 `eval_get_sign(cb) < 0`.][[space]]] 355[[`eval_fabs(b, cb)`][`void`][Set `b` to the absolute value of `cb`. 356 The default version of this functions assigns `cb` to `b`, and then calls `b.negate()` if 357 `eval_get_sign(cb) < 0`.][[space]]] 358 359[[['floating-point functions:]]] 360[[`eval_fpclassify(cb)`][`int`][Returns one of the same values returned by `std::fpclassify`. Only required when `B` is an floating-point type. 361 The default version of this function will only test for zero `cb`.][[space]]] 362[[`eval_trunc(b, cb)`][`void`][Performs the equivalent operation to `std::trunc` on argument `cb` and stores the result in `b`. Only required when `B` is an floating-point type. 363 The default version of this function is synthesised from other operations above.][[space]]] 364[[`eval_round(b, cb)`][`void`][Performs the equivalent operation to `std::round` on argument `cb` and stores the result in `b`. Only required when `B` is an floating-point type. 365 The default version of this function is synthesised from other operations above.][[space]]] 366[[`eval_exp(b, cb)`][`void`][Performs the equivalent operation to `std::exp` on argument `cb` and stores the result in `b`. Only required when `B` is an floating-point type. 367 The default version of this function is synthesised from other operations above.][[space]]] 368[[`eval_exp2(b, cb)`][`void`][Performs the equivalent operation to `std::exp2` on argument `cb` and stores the result in `b`. Only required when `B` is an floating-point type. 369 The default version of this function is implemented in terms of `eval_pow`.][[space]]] 370[[`eval_log(b, cb)`][`void`][Performs the equivalent operation to `std::log` on argument `cb` and stores the result in `b`. Only required when `B` is an floating-point type. 371 The default version of this function is synthesised from other operations above.][[space]]] 372[[`eval_log10(b, cb)`][`void`][Performs the equivalent operation to `std::log10` on argument `cb` and stores the result in `b`. Only required when `B` is an floating-point type. 373 The default version of this function is synthesised from other operations above.][[space]]] 374[[`eval_sin(b, cb)`][`void`][Performs the equivalent operation to `std::sin` on argument `cb` and stores the result in `b`. Only required when `B` is an floating-point type. 375 The default version of this function is synthesised from other operations above.][[space]]] 376[[`eval_cos(b, cb)`][`void`][Performs the equivalent operation to `std::cos` on argument `cb` and stores the result in `b`. Only required when `B` is an floating-point type. 377 The default version of this function is synthesised from other operations above.][[space]]] 378[[`eval_tan(b, cb)`][`void`][Performs the equivalent operation to `std::exp` on argument `cb` and stores the result in `b`. Only required when `B` is an floating-point type. 379 The default version of this function is synthesised from other operations above.][[space]]] 380[[`eval_asin(b, cb)`][`void`][Performs the equivalent operation to `std::asin` on argument `cb` and stores the result in `b`. Only required when `B` is an floating-point type. 381 The default version of this function is synthesised from other operations above.][[space]]] 382[[`eval_acos(b, cb)`][`void`][Performs the equivalent operation to `std::acos` on argument `cb` and stores the result in `b`. Only required when `B` is an floating-point type. 383 The default version of this function is synthesised from other operations above.][[space]]] 384[[`eval_atan(b, cb)`][`void`][Performs the equivalent operation to `std::atan` on argument `cb` and stores the result in `b`. Only required when `B` is an floating-point type. 385 The default version of this function is synthesised from other operations above.][[space]]] 386[[`eval_sinh(b, cb)`][`void`][Performs the equivalent operation to `std::sinh` on argument `cb` and stores the result in `b`. Only required when `B` is an floating-point type. 387 The default version of this function is synthesised from other operations above.][[space]]] 388[[`eval_cosh(b, cb)`][`void`][Performs the equivalent operation to `std::cosh` on argument `cb` and stores the result in `b`. Only required when `B` is an floating-point type. 389 The default version of this function is synthesised from other operations above.][[space]]] 390[[`eval_tanh(b, cb)`][`void`][Performs the equivalent operation to `std::tanh` on argument `cb` and stores the result in `b`. Only required when `B` is an floating-point type. 391 The default version of this function is synthesised from other operations above.][[space]]] 392[[`eval_fmod(b, cb, cb2)`][`void`][Performs the equivalent operation to `std::fmod` on arguments `cb` and `cb2`, and store the result in `b`. Only required when `B` is an floating-point type. 393 The default version of this function is synthesised from other operations above.][[space]]] 394[[`eval_modf(b, cb, pb)`][`void`][Performs the equivalent operation to `std::modf` on argument `cb`, and store the integer result in `*pb` and the fractional part in `b`. 395 Only required when `B` is an floating-point type. 396 The default version of this function is synthesised from other operations above.][[space]]] 397[[`eval_pow(b, cb, cb2)`][`void`][Performs the equivalent operation to `std::pow` on arguments `cb` and `cb2`, and store the result in `b`. Only required when `B` is an floating-point type. 398 The default version of this function is synthesised from other operations above.][[space]]] 399[[`eval_atan2(b, cb, cb2)`][`void`][Performs the equivalent operation to `std::atan` on arguments `cb` and `cb2`, and store the result in `b`. Only required when `B` is an floating-point type. 400 The default version of this function is synthesised from other operations above.][[space]]] 401[[`eval_scalbn(b, cb, e)`][`void`][Scales value `cb` by ['r[super e]], where ['r] is the radix of the type. The default version of this function 402 is implemented in terms of eval_ldexp, consequently this function must be provided for types with a radix other than 2.]] 403[[`eval_scalbln(b, cb, e)`][`void`][Calls `eval_scalbn(b, cb, e)`.]] 404[[`eval_ilogb(cb)`][`B::exponent_type`][Returns the exponent ['e] of value `cb` such that ['1 <= cb*r[super -e] < r], where ['r] is the radix of type B. 405 The default version of this function is implemented in terms of eval_frexp, consequently this function must be provided for types with a radix other than 2.]] 406[[`eval_remquo(b, cb, cb2, pi)`][`void`][Sets `b = cb - n * cb2` and stores `n` in `*pi`.]] 407[[`eval_remquo(b, cb, a, pi)`][`void`][Default version converts a to type B and calls the overload above.]] 408[[`eval_remquo(b, a, cb, pi)`][`void`][Default version converts a to type B and calls the overload above.]] 409[[`eval_remainder(b, cb, cb2)`][`void`][Default version calls eval_remquo with a dummy final argument.]] 410[[`eval_remainder(b, cb, a)`][`void`][Default version calls eval_remquo with a dummy final argument.]] 411[[`eval_remainder(b, a, cb)`][`void`][Default version calls eval_remquo with a dummy final argument.]] 412 413[[`eval_fdim(b, cb, cb2)`][`void`][Default version sets `b = cb - cb2` if `cb > cb2` and zero otherwise. Special cases are handled as in the C99 annex.]] 414[[`eval_fdim(b, cb, a)`][`void`][Default version sets `b = cb - cb2` if `cb > cb2` and zero otherwise. Special cases are handled as in the C99 annex.]] 415[[`eval_fdim(b, a, cb)`][`void`][Default version sets `b = cb - cb2` if `cb > cb2` and zero otherwise. Special cases are handled as in the C99 annex.]] 416 417[[`eval_fmax(b, cb, cb2)`][`void`][Sets `b` to the larger of `cb` and `cb2`.]] 418[[`eval_fmax(b, cb, a)`][`void`][Sets `b` to the larger of `cb` and `a`.]] 419[[`eval_fmax(b, a, cb)`][`void`][Sets `b` to the larger of `cb` and `a`.]] 420[[`eval_fmin(b, cb, cb2)`][`void`][Sets `b` to the smaller of `cb` and `cb2`.]] 421[[`eval_fmin(b, cb, a)`][`void`][Sets `b` to the smaller of `cb` and `a`.]] 422[[`eval_fmin(b, a, cb)`][`void`][Sets `b` to the smaller of `cb` and `a`.]] 423 424[[`eval_hypot(b, cb, cb2)`][`void`][Sets `b` to the square root of the sum of the squares of `cb` and `cb2` without undue over or under flow.]] 425[[`eval_hypot(b, cb, a)`][`void`][As above.]] 426[[`eval_hypot(b, a, cb)`][`void`][As above.]] 427 428[[`eval_logb(b, cb)`][`B::exponent_type`][Sets `b` to the exponent ['e] of value `cb` such that ['1 <= cb*r[super -b] < r], where ['r] is the radix of type B. 429 The default version of this function is implemented in terms of `eval_ilogb`.]] 430[[`eval_nearbyint(b, cb)`][`void`][Calls `eval_round(b, cb)`.]] 431[[`eval_rint(b, cb)`][`void`][Calls `eval_nearbyint(b, cb)`.]] 432[[`eval_log2(b, cb)`][`void`][Sets `b` to the logarithm base 2 of `cb`.]] 433 434[[['hashing:]]] 435[[`hash_value(cb)`][`std::size_t`] 436 [Returns a hash value for the argument that is suitable for use with `std::hash` etc. If not provided then no automatic hashing support will be available for the number type.]] 437] 438 439When the tables above place no ['throws] requirements on an operation, then it is up to each type modelling this concept to 440decide when or whether throwing an exception is desirable. However, thrown exceptions should always either be the type, or 441inherit from the type `std::runtime_error`. For example, a floating-point type might choose to throw `std::overflow_error` 442whenever the result of an operation would be infinite, and `std::underflow_error` whenever it would round to zero. 443 444[note 445The non-member functions are all named with an "eval_" prefix to avoid conflicts with template classes of the same name - 446in point of fact this naming convention shouldn't be necessary, but rather works around some compiler bugs.] 447 448[h4 Overloadable Functions] 449 450Some of the C99 math functions do not have `eval_` functions but must be overloaded directly: these functions 451are either trivial or are forwarded to the Boost.Math implementations by default. 452The full list of these functions is: 453 454 int sign (const ``['number-or-expression-template-type]``&); 455 int signbit (const ``['number-or-expression-template-type]``&); 456 ``['number]`` changesign (const ``['number-or-expression-template-type]``&); 457 ``['number]`` copysign (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&); 458 ``['number]`` asinh (const ``['number-or-expression-template-type]``&); 459 ``['number]`` acosh (const ``['number-or-expression-template-type]``&); 460 ``['number]`` atanh (const ``['number-or-expression-template-type]``&); 461 ``['number]`` cbrt (const ``['number-or-expression-template-type]``&); 462 ``['number]`` erf (const ``['number-or-expression-template-type]``&); 463 ``['number]`` erfc (const ``['number-or-expression-template-type]``&); 464 ``['number]`` expm1 (const ``['number-or-expression-template-type]``&); 465 ``['number]`` log1p (const ``['number-or-expression-template-type]``&); 466 ``['number]`` tgamma (const ``['number-or-expression-template-type]``&); 467 ``['number]`` lgamma (const ``['number-or-expression-template-type]``&); 468 long lrint (const ``['number-or-expression-template-type]``&); 469 long long llrint (const ``['number-or-expression-template-type]``&); 470 ``['number]`` nextafter (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&); 471 ``['number]`` nexttoward (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&); 472 473[endsect] 474