libs/histogram/doc/concepts/Transform.qbk

   1 [/
   2             Copyright Hans Dembinski 2018 - 2019.
   3    Distributed under the Boost Software License, Version 1.0.
   4       (See accompanying file LICENSE_1_0.txt or copy at
   5             https://www.boost.org/LICENSE_1_0.txt)
   6 ]
   7
   8 [section:Transform Transform]
   9
  10 A [*Transform] implements a monotonic mapping between two real-valued domains, external and internal. It is used to extend the [classref boost::histogram::axis::regular regular axis]. The bins in the internal domain are of equal width, while the bins in the external domain are non-equal width. Must be [@https://en.cppreference.com/w/cpp/named_req/DefaultConstructible DefaultConstructible], [@https://en.cppreference.com/w/cpp/named_req/CopyConstructible CopyConstructible], and [@https://en.cppreference.com/w/cpp/named_req/CopyAssignable CopyAssignable].
  11
  12 [heading Required features]
  13
  14 * `T` is a type meeting the requirements of [*Transform]
  15 * `t` is a value of type `T`
  16 * `X` is a type with the semantics of a floating-point type
  17 * `x` is a value of type `X`
  18 * `Y` is a floating-point type
  19 * `y` is a value of type `Y`
  20
  21 [table Valid expressions
  22 [[Expression] [Returns] [Semantics, Pre/Post-conditions]]
  23 [
  24   [`t.forward(x)`]
  25   [`Y`]
  26   [
  27     Const or static member function which maps the external value to the corresponding internal value. The return type `Y` may differ from `X`.
  28   ]
  29 ]
  30 [
  31   [`t.inverse(y)`]
  32   [`X`]
  33   [
  34     Const or static member function which maps the internal value to the corresponding external value. The result of `t.inverse(t.forward(x))` must be approximately equal to `x` within floating-point precision.
  35   ]
  36 ]
  37 [
  38   [`t == u`]
  39   [`bool`]
  40   [
  41     `u` is another value of type `T`. Returns `true` if both values have the same state. Otherwise returns `false`. May be omitted if `T` is stateless. If this binary operator is not implemented, the library considers the arguments equal, if and only if their types are the same.
  42   ]
  43 ]
  44 ]
  45
  46 [heading Optional features]
  47
  48 * `T` is a type meeting the requirements of [*Transform]
  49 * `t` is a value of type `T`
  50 * `ar` is a value of an archive with Boost.Serialization semantics
  51
  52 [table Valid expressions
  53 [[Expression] [Returns] [Semantics, Pre/Post-conditions]]
  54 [
  55   [`t.serialize(ar, n)`]
  56   []
  57   [
  58     `ar` is a value of an archive with Boost.Serialization semantics and `n` is an unsigned integral value. Saves to the archive or loads serialized state from the archive. The version number `n` is the stored version when the object is loaded or the current version when the object is saved.
  59   ]
  60 ]
  61 ]
  62
  63 [heading Models]
  64
  65 * [classref boost::histogram::axis::transform::id]
  66 * [classref boost::histogram::axis::transform::log]
  67 * [classref boost::histogram::axis::transform::sqrt]
  68 * [classref boost::histogram::axis::transform::pow]
  69
  70 [endsect]