Enhance opstream by allowing output to a specified ostream. (#1106)

* Enhance opstream by allowing output to a specified buffer.

+ Extend the capabilities of `opstream` by allowing output to be directed to any `std::ostream`
  instead of forcing output to `std::cout`. If the output stream is not specified, it will default
  to the previous behavior of `std::cout`.
+ Provide `const` attribute for some arguments of functions provided in `dbc.hh`.
+ This PR also serves as a sanity check for the new git pre-commit-copyright hook, #1105.

* Fix doxygen error.

* rename variable to avoid shadowing.

* Fix mismatched const in hh and i.hh file.

src/c4/opstream.cc

@@ -4,7 +4,7 @@
  * \author Kent G. Budge
  * \date   Mon Jun 25 12:12:31 MDT 2018
  * \brief  Define methods of class opstream
- * \note   Copyright (C) 2018-2020 Triad National Security, LLC., All rights reserved. */
+ * \note   Copyright (C) 2018-2021 Triad National Security, LLC., All rights reserved. */
 //------------------------------------------------------------------------------------------------//
 
 #include "opstream.hh"
@@ -17,12 +17,14 @@ namespace rtt_c4 {
  *
  * Causes all buffered data to be written to console in MPI rank order; that is, all data from rank
  * 0 is written first, then all data from rank 1, and so on.
+ *
+ * /param[in,out] out ostream buffer to write data into. defaults to std::cout.
  */
-void opstream::mpibuf::send() {
+void opstream::mpibuf::send(std::ostream &myout) {
   unsigned const pid = rtt_c4::node();
   if (pid == 0) {
     buffer_.push_back('\0'); // guarantees that buffer_.size() > 0
-    std::cout << &buffer_[0];
+    myout << &buffer_[0];
     buffer_.clear();
 
     unsigned const pids = rtt_c4::nodes();
@@ -34,7 +36,7 @@ void opstream::mpibuf::send() {
         rtt_c4::receive(&buffer_[0], N, i);
       }
       buffer_.push_back('\0');
-      std::cout << &buffer_[0]; // guarantees that buffer_.size() > 0
+      myout << &buffer_[0]; // guarantees that buffer_.size() > 0
     }
   } else {
 

src/c4/opstream.hh

@@ -3,7 +3,7 @@
  * \file   c4/opstream.hh
  * \author Kent G. Budge
  * \brief  Define class opstream
- * \note   Copyright (C) 2018-2020 Triad National Security, LLC., All rights reserved. */
+ * \note   Copyright (C) 2018-2021 Triad National Security, LLC., All rights reserved. */
 //------------------------------------------------------------------------------------------------//
 
 #ifndef c4_opstream_hh
@@ -58,15 +58,15 @@ public:
   }
 
   //! Send all buffered data synchronously to the console.
-  void send() { sb_.send(); }
+  void send(std::ostream &myout = std::cout) { sb_.send(myout); }
 
   //! Shrink the internal buffer to fit the current buffered data.
   void shrink_to_fit() { sb_.shrink_to_fit(); }
 
 private:
   struct mpibuf : public std::streambuf {
 
-    void send();
+    void send(std::ostream &myout);
     void shrink_to_fit();
 
     int_type overflow(int_type c) override;

src/ds++/dbc.hh

@@ -19,15 +19,15 @@ namespace rtt_dsxx {
 
 //! Check whether a sequence is monotonically increasing.
 template <typename Forward_Iterator>
-bool is_monotonic_increasing(Forward_Iterator first, Forward_Iterator last);
+bool is_monotonic_increasing(Forward_Iterator first, Forward_Iterator const last);
 
 //! Check whether a sequence is strictly monotonically increasing.
 template <typename Forward_Iterator>
-bool is_strict_monotonic_increasing(Forward_Iterator first, Forward_Iterator last);
+bool is_strict_monotonic_increasing(Forward_Iterator first, Forward_Iterator const last);
 
 //! Check whether a sequence is strictly monotonically decreasing.
 template <typename Forward_Iterator>
-bool is_strict_monotonic_decreasing(Forward_Iterator first, Forward_Iterator last);
+bool is_strict_monotonic_decreasing(Forward_Iterator first, Forward_Iterator const last);
 
 //! Check whether a matrix is symmetric.
 template <typename Random_Access_Container>

src/ds++/dbc.i.hh

@@ -4,7 +4,7 @@
  * \author Kent G. Budge
  * \date   Wed Jan 22 15:18:23 MST 2003
  * \brief  Template implementation for dbc
- * \note   Copyright (C) 2016-2020 Triad National Security, LLC., All rights reserved.
+ * \note   Copyright (C) 2016-2021 Triad National Security, LLC., All rights reserved.
  *
  * This header defines several function templates that perform common numerical operations not
  * standardized in the STL algorithm header. It also defines some useful STL-style predicates. These
@@ -21,28 +21,23 @@
 
 namespace rtt_dsxx {
 
-//-------------------------------------------------------------------------//
+//------------------------------------------------------------------------------------------------//
 /*!
  * \brief Check whether a sequence is monotonically increasing.
  *
  * Checks whether every element in a sequence is less than or equal to the next element of the
  * sequence.  This is particularly useful for Design by Contract assertions that check that a
  * sequence is sorted.
  *
- * \arg \a Forward_Iterator
- * A forward iterator whose value type supports \c operator<.
- *
- * \param first
- * Points to the first element of the sequence.
- *
- * \param last
- * Points one element past the end of the sequence.
+ * \tparam Forward_Iterator A forward iterator whose value type supports \c operator<.
+ * \param[in,out] first Points to the first element of the sequence.
+ * \param[in]     last Points one element past the end of the sequence.
  *
  * \return \c true if \f$a_i<=a_{i+1}\f$ for all \f$a_i\f$ in the sequence;
  * \c false otherwise.
  */
 template <typename Forward_Iterator>
-bool is_monotonic_increasing(Forward_Iterator first, Forward_Iterator last) {
+bool is_monotonic_increasing(Forward_Iterator first, Forward_Iterator const last) {
   Forward_Iterator prev = first;
   while (++first != last) {
     if (*first < *prev)
@@ -53,28 +48,22 @@ bool is_monotonic_increasing(Forward_Iterator first, Forward_Iterator last) {
   return true;
 }
 
-//-------------------------------------------------------------------------//
+//------------------------------------------------------------------------------------------------//
 /*!
  * \brief Check whether a sequence is strictly monotonically increasing.
  *
  * Checks whether every element in a sequence is less than the next element of the sequence.  This
  * is particularly useful for Design by Contract assertions that check the validity of a table of
  * data.
  *
- * \arg \a Forward_Iterator
- * A forward iterator whose value type supports \c operator<.
+ * \tparam Forward_Iterator A forward iterator whose value type supports \c operator<.
+ * \param[in,out] first Points to the first element of the sequence.
+ * \param[in]     last Points one element past the end of the sequence.
  *
- * \param first
- * Points to the first element of the sequence.
- *
- * \param last
- * Points one element past the end of the sequence.
- *
- * \return \c true if \f$a_i<a_{i+1}\f$ for all \f$a_i\f$ in the sequence;
- * \c false otherwise.
+ * \return \c true if \f$a_i<a_{i+1}\f$ for all \f$a_i\f$ in the sequence; \c false otherwise.
  */
 template <typename Forward_Iterator>
-bool is_strict_monotonic_increasing(Forward_Iterator first, Forward_Iterator last) {
+bool is_strict_monotonic_increasing(Forward_Iterator first, Forward_Iterator const last) {
   Forward_Iterator prev = first;
   while (++first != last) {
     if (!(*prev < *first))
@@ -84,28 +73,23 @@ bool is_strict_monotonic_increasing(Forward_Iterator first, Forward_Iterator las
   return true;
 }
 
-//-------------------------------------------------------------------------//
+//------------------------------------------------------------------------------------------------//
 /*!
  * \brief Check whether a sequence is strictly monotonically decreasing.
  *
  * Checks whether every element in a sequence is greater than the next element of the sequence.
  *
- * \arg \a Forward_Iterator
- * A forward iterator whose value type supports \c operator<.
- *
- * \param first
- * Points to the first element of the sequence.
- *
- * \param last
- * Points one element past the end of the sequence.
+ * \tparam Forward_Iterator A forward iterator whose value type supports \c operator<.
+ * \param[in,out] first Points to the first element of the sequence.
+ * \param[in]     last Points one element past the end of the sequence.
  *
  * \pre \c last>first
  *
  * \return \c true if \f$a_{i+1}<a_i\f$ for all \f$a_i\f$ in the sequence;
  * \c false otherwise.
  */
 template <typename Forward_Iterator>
-bool is_strict_monotonic_decreasing(Forward_Iterator first, Forward_Iterator last) {
+bool is_strict_monotonic_decreasing(Forward_Iterator first, Forward_Iterator const last) {
   Require(first < last);
   Forward_Iterator prev = first;
   while (++first != last) {
@@ -116,24 +100,19 @@ bool is_strict_monotonic_decreasing(Forward_Iterator first, Forward_Iterator las
   return true;
 }
 
-//-------------------------------------------------------------------------//
+//------------------------------------------------------------------------------------------------//
 /*!
  * \brief Check whether a matrix is symmetric.
  *
- * \arg \a Random_Access_Container
- * A random access container type.
- *
- * \param A Matrix that is supposed to be symmetric.
- *
- * \param n Rank of the matrix.
- *
- * \param tolerance Tolerance for comparing matrix elements.
+ * \tparam Random_Access_Container A random access container type.
+ * \param[in] A Matrix that is supposed to be symmetric.
+ * \param[in] n Rank of the matrix.
+ * \param[in] tolerance Tolerance for comparing matrix elements.
  *
  * \pre \c A.size()==n*n
  * \pre \c tolerance>=0.0
  *
- * \return \c true if <code>A[i+n*j]==A[j+n*i]</code> for all \c i and \c j; \c false
- * otherwise.
+ * \return \c true if <code>A[i+n*j]==A[j+n*i]</code> for all \c i and \c j; \c false otherwise.
  */
 template <typename Random_Access_Container>
 bool is_symmetric_matrix(Random_Access_Container const &A, unsigned const n,