Docs for param, add several noexcept, small doc tweaks.

doc/expression.rst

@@ -14,3 +14,4 @@ Mention reference semantics for non-trivial expressions.
 
    variable.rst
    number.rst
+   param.rst

doc/number.rst

@@ -11,7 +11,9 @@ The :cpp:class:`~heyoka::number` class
 .. cpp:class:: number
 
    This class is used to represent numerical constants in heyoka's expression
-   system. It consists of a union of several floating-point types.
+   system.
+
+   It consists of a union of several floating-point types.
 
    .. cpp:type:: value_type = std::variant<float, double, long double, mppp::real128, mppp::real>
 

doc/param.rst

@@ -0,0 +1,103 @@
+Runtime parameters
+==================
+
+*#include <heyoka/param.hpp>*
+
+The :cpp:class:`~heyoka::param` class
+-------------------------------------
+
+.. cpp:namespace-push:: heyoka
+
+.. cpp:class:: param
+
+   This class is used to represent numerical parameters in heyoka's expression
+   system.
+
+   A parameter is a constant whose value, unlike :cpp:class:`~heyoka::number`,
+   is *not* fixed at the time of the creation of a symbolic expressions. Instead,
+   the value of a parameter is loaded at a later stage (e.g., during the numerical
+   integration of a system of ODEs) from a user-supplied array of parameter values.
+   Parameters are uniquely identified by a zero-based index representing
+   the position in the array of parameter values from which the value of the parameter
+   will be loaded.
+
+   A :ref:`tutorial <tut_param>` illustrating the use of this class is available.
+
+   .. cpp:function:: param() noexcept
+
+      Default constructor.
+
+      The default constructor initialises a parameter with index 0.
+
+   .. cpp:function:: explicit param(std::uint32_t idx) noexcept
+
+      Constructor from index.
+
+      :param idx: the index value for the parameter.
+
+   .. cpp:function:: param(const param &) noexcept
+   .. cpp:function:: param(param &&) noexcept
+   .. cpp:function:: param &operator=(const param &) noexcept
+   .. cpp:function:: param &operator=(param &&) noexcept
+   .. cpp:function:: ~param()
+
+      Parameters are copy/move constructible, copy/move assignable and destructible.
+
+   .. cpp:function:: [[nodiscard]] std::uint32_t idx() const noexcept
+
+      Index getter.
+
+      :return: the index value of the parameter.
+
+Functions
+---------
+
+.. cpp:function:: void swap(param &a, param &b) noexcept
+
+   Swap primitive.
+
+   This function will efficiently swap *a* and *b*.
+
+   :param a: the first parameter.
+   :param b: the second parameter.
+
+.. cpp:function:: std::ostream &operator<<(std::ostream &os, const param &p)
+
+   Stream operator.
+
+   :param os: the output stream.
+   :param p: the input parameter.
+
+   :return: a reference to *os*.
+
+   :exception: any exception thrown by the stream operator of ``std::uint32_t``.
+
+Operators
+---------
+
+.. cpp:function:: bool operator==(const param &a, const param &b) noexcept
+.. cpp:function:: bool operator!=(const param &a, const param &b) noexcept
+
+   Equality comparison operators.
+
+   Two parameters are considered equal if they have the same index value.
+
+   :param a: the first parameter.
+   :param b: the second parameter.
+
+   :return: the result of the comparison.
+
+.. cpp:namespace-pop::
+
+Standard library specialisations
+--------------------------------
+
+.. cpp:struct:: template <> std::hash<heyoka::param>
+
+   Specialisation of ``std::hash`` for :cpp:class:`heyoka::param`.
+
+   .. cpp:function:: std::size_t operator()(const heyoka::param &p) const noexcept
+
+      :param p: the input :cpp:class:`heyoka::param`.
+
+      :return: a hash value for *p*.

doc/tut_param.rst

@@ -20,7 +20,7 @@ for large ODE systems.
 
 In order to avoid having to re-create a new integrator if the value of a constant
 in an expression changes, heyoka's expression system provides a node type,
-called ``param`` (or *runtime parameter*), which
+called :cpp:class:`~heyoka::param` (or *runtime parameter*), which
 represents mathematical constants whose value is not known at the time of
 construction of the expression.
 
@@ -47,7 +47,7 @@ With respect to the previous examples, where :math:`g/l` had been
 hard-coded to ``9.8``, now :math:`g/l` is represented as ``par[0] / par[1]``.
 The syntax ``par[i]`` indicates a runtime parameter that is stored
 at the index ``i`` in an array of parameter values. The array of
-parameter values is optionally passed to the constructor as the keyword argument
+parameter values is optionally passed to the constructor as the :ref:`keyword argument <kwargs>`
 ``kw::pars`` (which, in this case, contains the values ``9.8`` for :math:`g` and ``1.``
 for :math:`l`).
 If an array of parameter values is not passed to the constructor,

doc/variable.rst

@@ -1,5 +1,3 @@
-.. _variable:
-
 Variables
 =========
 
@@ -13,7 +11,9 @@ The :cpp:class:`~heyoka::variable` class
 .. cpp:class:: variable
 
    This class is used to represent symbolic variables in heyoka's expression
-   system. Variables are uniquely identified by their name.
+   system.
+
+   Variables are uniquely identified by their name.
 
    .. note::
 
@@ -88,7 +88,6 @@ Operators
 
    :return: the result of the comparison.
 
-
 .. cpp:namespace-pop::
 
 Standard library specialisations

include/heyoka/param.hpp

@@ -49,19 +49,19 @@ class HEYOKA_DLL_PUBLIC param
     }
 
 public:
-    param();
+    param() noexcept;
 
-    explicit param(std::uint32_t);
+    explicit param(std::uint32_t) noexcept;
 
-    param(const param &);
+    param(const param &) noexcept;
     param(param &&) noexcept;
 
-    param &operator=(const param &);
+    param &operator=(const param &) noexcept;
     param &operator=(param &&) noexcept;
 
     ~param();
 
-    [[nodiscard]] const std::uint32_t &idx() const;
+    [[nodiscard]] std::uint32_t idx() const noexcept;
 };
 
 namespace detail
@@ -73,8 +73,8 @@ HEYOKA_DLL_PUBLIC std::size_t hash(const param &) noexcept;
 
 HEYOKA_DLL_PUBLIC std::ostream &operator<<(std::ostream &, const param &);
 
-HEYOKA_DLL_PUBLIC bool operator==(const param &, const param &);
-HEYOKA_DLL_PUBLIC bool operator!=(const param &, const param &);
+HEYOKA_DLL_PUBLIC bool operator==(const param &, const param &) noexcept;
+HEYOKA_DLL_PUBLIC bool operator!=(const param &, const param &) noexcept;
 
 HEYOKA_DLL_PUBLIC double eval_dbl(const param &, const std::unordered_map<std::string, double> &,
                                   const std::vector<double> &);

src/param.cpp

@@ -27,22 +27,22 @@
 
 HEYOKA_BEGIN_NAMESPACE
 
-param::param() : param(0) {}
+param::param() noexcept : param(0) {}
 
-param::param(std::uint32_t idx) : m_index(idx) {}
+param::param(std::uint32_t idx) noexcept : m_index(idx) {}
 
-param::param(const param &) = default;
+param::param(const param &) noexcept = default;
 
 param::param(param &&) noexcept = default;
 
-param &param::operator=(const param &) = default;
+param &param::operator=(const param &) noexcept = default;
 
 param &param::operator=(param &&) noexcept = default;
 
 // NOLINTNEXTLINE(performance-trivially-destructible)
 param::~param() = default;
 
-const std::uint32_t &param::idx() const
+std::uint32_t param::idx() const noexcept
 {
     return m_index;
 }
@@ -67,12 +67,12 @@ std::ostream &operator<<(std::ostream &os, const param &p)
     return os << fmt::format("p{}", p.idx());
 }
 
-bool operator==(const param &p0, const param &p1)
+bool operator==(const param &p0, const param &p1) noexcept
 {
     return p0.idx() == p1.idx();
 }
 
-bool operator!=(const param &p0, const param &p1)
+bool operator!=(const param &p0, const param &p1) noexcept
 {
     return !(p0 == p1);
 }