laeUtils.h

Go to the documentation of this file.

////////////////////////////////////////////////////////////////////////////////
//
// Package:   Laelaps
//
// Library:   liblaelaps
//
// File:      leaUtils.h
//
//
/*! \file
 *
 * $LastChangedDate: 2016-01-21 16:50:25 -0700 (Thu, 21 Jan 2016) $
 * $Rev: 4268 $
 *
 * \brief Laelaps common utilities.
 *
 * \author Robin Knight   (robin.knight@roadnarrows.com)
 *
 * \par Copyright
 *   \h_copy 2015-2017. RoadNarrows LLC.\n
 *   http://www.roadnarrows.com\n
 *   All Rights Reserved
 */
/*
 * @EulaBegin@
 * 
 * Unless otherwise stated explicitly, all materials contained are copyrighted
 * and may not be used without RoadNarrows LLC's written consent,
 * except as provided in these terms and conditions or in the copyright
 * notice (documents and software) or other proprietary notice provided with
 * the relevant materials.
 * 
 * IN NO EVENT SHALL THE AUTHOR, ROADNARROWS LLC, OR ANY 
 * MEMBERS/EMPLOYEES/CONTRACTORS OF ROADNARROWS OR DISTRIBUTORS OF THIS SOFTWARE
 * BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR
 * CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS
 * DOCUMENTATION, EVEN IF THE AUTHORS OR ANY OF THE ABOVE PARTIES HAVE BEEN
 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 * 
 * THE AUTHORS AND  ROADNARROWS LLC SPECIFICALLY DISCLAIM ANY WARRANTIES,
 * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
 * FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS ON AN
 * "AS IS" BASIS, AND THE AUTHORS AND DISTRIBUTORS HAVE NO OBLIGATION TO
 * PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
 * 
 * @EulaEnd@
 */
////////////////////////////////////////////////////////////////////////////////

#ifndef _LAE_UTILS_H
#define _LAE_UTILS_H

#include <sys/types.h>
#include <sys/time.h>
#include <time.h>
#include <math.h>

#include <string>
#include <vector>

#include "rnr/rnrconfig.h"
#include "rnr/log.h"

#include "Laelaps/laelaps.h"

#define M_TAU (2.0 * M_PI)    ///< tau = 2 * pi

namespace laelaps
{
  const long      MILLION = 1000000;
  const long long BILLION = 1000000000;


  // . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  // String functions.
  // . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

  /*!
   * \brief Convert version dotted string to integer equivalent.
   *
   * \param str   Dotted version string "M[.m[.R]]".
   *
   * \return Version number.
   */
  extern uint_t strToVersion(const std::string &str);

  /*!
   * \brief Get the error string describing the \h_laelaps error code.
   *
   * The absolute value of the error code is taken prior retrieving the string.
   * An unknown or out-of-range error code will be mapped to
   * \ref LAE_ECODE_BADEC.
   *
   * \param  ecode  Instance of \ref lae_ecodes.
   *
   * \return Returns the appropriate error code string.
   */
  extern const char *getStrError(const int ecode);

  /*!
   * \brief Boolean to string.
   *
   * \param b   Boolean value.
   *
   * \return Pointer to null-terminated constant character string.
   */
  inline const char *boolstr(bool b)
  {
    return b? "true": "false";
  }


  // . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  // Math functions.
  // . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

  /*!
   * \brief Convert degrees to radians
   *
   * \param d   Degrees.
   *
   * \return Radians.
   */
  inline double degToRad(double d)
  {
    return d / 360.0 * M_TAU;
  }

  /*!
   * \brief Convert radians to degrees
   *
   * \param r   Radians.
   *
   * \return Degrees.
   */
  inline double radToDeg(double r)
  {
    return r / M_TAU * 360.0;
  }

  /*!
   * \brief Integer absolute value.
   *
   * \param a   Integer value.
   *
   * \return |a|
   */
  inline int iabs(int a)
  {
    return a>=0? a: -a;
  }

  /*!
   * \brief Cap value within limits [min, max].
   *
   * \param a     Value.
   * \param min   Minimum.
   * \param max   Maximum.
   *
   * \return a: min \h_le a \h_le max
   */
  inline double fcap(double a, double min, double max)
  {
    return a<min? min: a>max? max: a;
  }

  /*!
   * \brief Cap value within limits [min, max].
   *
   * \param a     Value.
   * \param min   Minimum.
   * \param max   Maximum.
   *
   * \return a: min \h_le a \h_le max
   */
  inline int cap(int a, int min, int max)
  {
    return a<min? min: a>max? max: a;
  }

  /*!
   * \brief Cap value within limits [min, max].
   *
   * \param a     Value.
   * \param min   Minimum.
   * \param max   Maximum.
   *
   * \return a: min \h_le a \h_le max
   */
  inline uint_t cap(uint_t a, uint_t min, uint_t max)
  {
    return a<min? min: a>max? max: a;
  }

  /*!
   * \brief Sign of a.
   *
   * \return Return 1.0 or -1.0.
   */
  inline double signof(double a)
  {
    return a<0? -1.0: 1.0;
  }

  /*!
   * \brief Sign of a.
   *
   * \return Return 1 or -1.
   */
  inline int signof(int a)
  {
    return a<0? -1: 1;
  }


  // . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  // timeval functions.
  // . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

  typedef struct timeval timeval_t;     ///< typedef'ed timeval structure
  typedef struct timespec timespec_t;   ///< typedef'ed timespec structure

  /*!
   * \brief Less than compare operator.
   *
   * Compare if the left hand side time is earlier than the right hand side
   * time.
   *
   * lhs \h_lt rhs
   *
   * \param lhs   Left hand side time.
   * \param rhs   Right hand side time.
   *
   * \return Returns true or false.
   */
  bool operator<(const struct timeval& lhs, const struct timeval& rhs);

  /*!
   * \brief Equality compare operator.
   *
   * Compare if the two times are equal.
   *
   * lhs == rhs
   *
   * \param lhs   Left hand side time.
   * \param rhs   Right hand side time.
   *
   * \return Returns true or false.
   */
  bool operator==(const struct timeval& lhs, const struct timeval& rhs);

  /*!
   * \brief Greater than compare operator.
   *
   * Compare if the left hand side time is later than the right hand side
   * time.
   *
   * lhs \h_gt rhs
   *
   * \param lhs   Left hand side time.
   * \param rhs   Right hand side time.
   *
   * \return Returns true or false.
   */
  bool operator>(const struct timeval& lhs, const struct timeval& rhs);

  /*!
   * \brief Less than or equal to compare operator.
   *
   * Compare if the left hand side time is equal or earlier than the right hand
   * side time.
   *
   * lhs \h_le rhs
   *
   * \param lhs   Left hand side time.
   * \param rhs   Right hand side time.
   *
   * \return Returns true or false.
   */
  bool operator<=(const struct timeval& lhs, const struct timeval& rhs);

  /*!
   * \brief Greater than or equal to compare operator.
   *
   * Compare if the left hand side time is equal or later than the right hand
   * side time.
   *
   * lhs \h_ge rhs
   *
   * \param lhs   Left hand side time.
   * \param rhs   Right hand side time.
   *
   * \return Returns true or false.
   */
  bool operator>=(const struct timeval& lhs, const struct timeval& rhs);

  /*!
   * \brief Addition operator.
   *
   * op1 + op2
   *
   * \param op1   Left hand side time.
   * \param op2   Right hand side time.
   *
   * \return Sum of times.
   */
  struct timeval operator+(const struct timeval& op1,
                           const struct timeval& op2);

  /*!
   * \brief Subtraction operator.
   *
   * op1 - op2, op1 \h_ge op2.
   *
   * \param op1   Left hand side time.
   * \param op2   Right hand side time.
   *
   * \return Difference of times.
   */
  struct timeval operator-(const struct timeval& op1,
                           const struct timeval& op2);

  /*!
   * \brief Calculate delta time in microseconds.
   *
   * t1 - t0, t1 \h_ge t0
   *
   * \param t1  Later time.
   * \param t0  Earlier time.
   *
   * \return Returns dt in microseconds.
   */
  long dt_usec(struct timeval& t1, struct timeval& t0);

  /*!
   * \brief Calculate delta time.
   *
   * t1 - t0
   *
   * \param t1  Time 1.
   * \param t0  Time 0.
   *
   * \return Returns dt as a double. May be negative.
   */
  double dt(struct timeval& t1, struct timeval& t0);


  // . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  // timespec functions.
  // . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

  /*!
   * \brief Less than compare operator.
   *
   * Compare if the left hand side time is earlier than the right hand side
   * time.
   *
   *
   * lhs \h_lt rhs
   *
   * \param lhs   Left hand side time.
   * \param rhs   Right hand side time.
   *
   * \return Returns true or false.
   */
  bool operator<(const struct timespec& lhs, const struct timespec& rhs);

  /*!
   * \brief Equality compare operator.
   *
   * Compare if the two times are equal.
   *
   * lhs == rhs
   *
   * \param lhs   Left hand side time.
   * \param rhs   Right hand side time.
   *
   * \return Returns true or false.
   */
  bool operator==(const struct timespec& lhs, const struct timespec& rhs);

  /*!
   * \brief Greater than compare operator.
   *
   * Compare if the left hand side time is later than the right hand side
   * time.
   *
   * lhs \h_gt rhs
   *
   * \param lhs   Left hand side time.
   * \param rhs   Right hand side time.
   *
   * \return Returns true or false.
   */
  bool operator>(const struct timespec& lhs, const struct timespec& rhs);

  /*!
   * \brief Less than or equal to compare operator.
   *
   * Compare if the left hand side time is equal or earlier than the right hand
   * side time.
   *
   * lhs \h_le rhs
   *
   * \param lhs   Left hand side time.
   * \param rhs   Right hand side time.
   *
   * \return Returns true or false.
   */
  bool operator<=(const struct timespec& lhs, const struct timespec& rhs);

  /*!
   * \brief Greater than or equal to compare operator.
   *
   * Compare if the left hand side time is equal or later than the right hand
   * side time.
   *
   * lhs \h_ge rhs
   *
   * \param lhs   Left hand side time.
   * \param rhs   Right hand side time.
   *
   * \return Returns true or false.
   */
  bool operator>=(const struct timespec& lhs, const struct timespec& rhs);

  /*!
   * \brief Addition operator.
   *
   * op1 + op2
   *
   * \param op1   Left hand side time.
   * \param op2   Right hand side time.
   *
   * \return Sum of times.
   */
  struct timespec operator+(const struct timespec& op1,
                            const struct timespec& op2);

  /*!
   * \brief Subtraction operator.
   *
   * op1 - op2, op1 \h_ge op2.
   *
   * \param op1   Left hand side time.
   * \param op2   Right hand side time.
   *
   * \return Difference of times.
   */
  struct timespec operator-(const struct timespec& op1,
                            const struct timespec& op2);

  /*!
   * \brief Calculate delta time in nanoseconds.
   *
   * t1 - t0, t1 \h_ge t0
   *
   * \param t1  Later time.
   * \param t0  Earlier time.
   *
   * \return Returns dt in nanoseconds.
   */
  long long dt_nsec(struct timespec& t1, struct timespec& t0);
  
  /*!
   * \brief Calculate delta time.
   *
   * t1 - t0
   *
   * \param t1  Time 1.
   * \param t0  Time 0.
   *
   * \return Returns dt as a double. May be negative.
   */
  double dt(struct timespec& t1, struct timespec& t0);
  

  // . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  // Miscellanea.
  // . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  
  /*!
   * \brief Get real device name.
   *
   * If the given device name is a symbolic link, then the real device the link
   * references is returned. Otherwise the given device name is returned.
   *
   * \param strDevName  Given device name.
   *
   * \return String.
   */
  std::string getRealDeviceName(const std::string &strDevName);

    /*!
   * \brief Split string at the delimiter character.
   *
   * \param s     String to split.
   * \param delem Delimiter character.
   * \param [out] elems   Vector of split strings.
   *
   * \return Reference to vector of split strings.
   */
  std::vector<std::string> &split(const std::string &s,
                                  char delim,
                                  std::vector<std::string> &elems);

  /*!
   * \brief Split string at the delimiter character.
   *
   * \param s     String to split.
   * \param delem Delimiter character.
   *
   * \return Vector of split strings.
   */
  std::vector<std::string> split(const std::string &s, char delim);

  // ---------------------------------------------------------------------------
  // Class Dim
  // ---------------------------------------------------------------------------

  /*!
   * \brief Object width x height x length dimensions class.
   */
  class Dim
  {
  public:
    double  m_width;    ///< object width (meters)
    double  m_height;   ///< object height (meters)
    double  m_length;   ///< object length (meters)
    
    /*!
     * \brief Default constructor.
     */
    Dim()
    {
      clear();
    }

    /*!
     * \brief Initialization constructor.
     *
     * \param width     Object width (meters)
     * \param height    Object height (meters)
     * \param length    Object length (meters)
     */
    Dim(double width, double height, double length)
    {
      m_width   = width;
      m_height  = height;
      m_length  = length;
    }

    /*!
     * \brief Copy constructor.
     *
     * \param src   Source object.
     */
    Dim(const Dim &src)
    {
      m_width   = src.m_width;
      m_height  = src.m_height;
      m_length  = src.m_length;
    }

    /*!
     * \brief Destructor.
     */
    virtual ~Dim()
    {
    }

    /*!
     * \brief Assignment operator.
     *
     * \param rhs   Right hand side object.
     *
     * \return Returns copy of this.
     */
    Dim operator=(const Dim &rhs)
    {
      m_width   = rhs.m_width;
      m_height  = rhs.m_height;
      m_length  = rhs.m_length;

      return *this;
    }

    void clear()
    {
      m_width   = 0.0;
      m_length  = 0.0;
      m_height  = 0.0;
    }

  }; // class Dim


} // namespace laelaps


#endif // _LAE_UTILS_H