Range.h

Go to the documentation of this file.

////////////////////////////////////////////////////////////////////////
//
// Copyright (C) 1993-2022 The Octave Project Developers
//
// See the file COPYRIGHT.md in the top-level directory of this
// distribution or <https://octave.org/copyright/>.
//
// This file is part of Octave.
//
// Octave is free software: you can redistribute it and/or modify it
// under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Octave is distributed in the hope that it will be useful, but
// WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Octave; see the file COPYING.  If not, see
// <https://www.gnu.org/licenses/>.
//
////////////////////////////////////////////////////////////////////////
 
#if ! defined (octave_Range_h)
#define octave_Range_h 1
 
#include "octave-config.h"
 
#include <iosfwd>
#include <type_traits>
 
#include "Array-fwd.h"
#include "dMatrix.h"
#include "dim-vector.h"
#include "lo-error.h"
#include "oct-sort.h"
#include "range-fwd.h"
 
namespace octave
{
  // For now, only define for floating point types.  However, we only
  // need range<float> as a temporary local variable in make_float_range
  // in ov.cc.
 
  template <typename T>
  class
  range<T, typename std::enable_if<std::is_floating_point<T>::value>::type>
  {
  public:
 
    range (void)
      : m_base (0), m_increment (0), m_limit (0), m_final (0), m_numel (0),
        m_reverse (false)
    { }
 
    // LIMIT is an upper limit and may be outside the range of actual
    // values.  For floating point ranges, we perform a tolerant check
    // to attempt to capture limit in the set of values if it is "close"
    // to the value of base + a multiple of the increment.
 
    range (const T& base, const T& increment, const T& limit,
           bool reverse = false)
      : m_base (base), m_increment (increment), m_limit (limit),
        m_final (), m_numel (), m_reverse (reverse)
    {
      init ();
    }
 
    range (const T& base, const T& limit)
      : m_base (base), m_increment (1), m_limit (limit), m_final (), m_numel (),
        m_reverse (false)
    {
      init ();
    }
 
    // Allow conversion from (presumably) properly constructed Range
    // objects.  The values of base, limit, increment, and numel must be
    // consistent.
 
    // FIXME: Actually check that base, limit, increment, and numel are
    // consistent?
 
    range (const T& base, const T& increment, const T& limit,
           octave_idx_type numel, bool reverse = false)
      : m_base (base), m_increment (increment), m_limit (limit),
        m_final (limit), m_numel (numel), m_reverse (reverse)
    { }
 
    // We don't use a constructor for this because it will conflict with
    // range<T> (base, limit, increment) when T is octave_idx_type.
 
    static range<T> make_n_element_range (const T& base, const T& increment,
                                          octave_idx_type numel,
                                          bool reverse = false)
    {
      // We could just make this constructor public, but it allows
      // inconsistent ranges to be constructed.  And it is probably much
      // clearer to see "make_n_element_range" instead of puzzling over the
      // purpose of this strange constructor form.
 
      T final_val = (reverse ? base - (numel - 1) * increment
                             : base + (numel - 1) * increment);
 
      return range<T> (base, increment, final_val, numel, reverse);
    }
 
    range (const range<T>& r)
      : m_base (r.m_base), m_increment (r.m_increment),
        m_limit (r.m_limit), m_final (r.m_final),
        m_numel (r.m_numel), m_reverse (r.m_reverse)
    { }
 
    range<T>& operator = (const range<T>& r)
    {
      if (this != &r)
        {
          m_base = r.m_base;
          m_increment = r.m_increment;
          m_limit = r.m_limit;
          m_final = r.m_final;
          m_numel = r.m_numel;
          m_reverse = r.m_reverse;
        }
 
      return *this;
    }
 
    ~range (void) = default;
 
    T base (void) const { return m_base; }
    T increment (void) const { return m_increment; }
    T limit (void) const { return m_limit; }
    bool reverse (void) const { return m_reverse; }
 
    T final_value (void) const { return m_final; }
 
    T min (void) const
    {
      return (m_numel > 0
              ? ((m_reverse ? m_increment > T (0)
                            : m_increment > T (0)) ? base () : final_value ())
              : T (0));
    }
 
    T max (void) const
    {
      return (m_numel > 0
              ? ((m_reverse ? m_increment < T (0)
                            : m_increment > T (0)) ? final_value () : base ())
              : T (0));
    }
 
    octave_idx_type numel (void) const { return m_numel; }
 
    // To support things like "for i = 1:Inf; ...; end" that are
    // required for Matlab compatibility, creation of a range object
    // like 1:Inf is allowed with m_numel set to
    // numeric_limits<octave_idx_type>::max().  However, it is not
    // possible to store these ranges.  The following function allows
    // us to easily distinguish ranges with an infinite number of
    // elements.  There are specializations for double and float.
 
    bool is_storable (void) const { return true; }
 
    dim_vector dims (void) const { return dim_vector (1, m_numel); }
 
    octave_idx_type rows (void) const { return 1; }
 
    octave_idx_type cols (void) const { return numel (); }
    octave_idx_type columns (void) const { return numel (); }
 
    bool isempty (void) const { return numel () == 0; }
 
    bool all_elements_are_ints (void) const { return true; }
 
    sortmode issorted (sortmode mode = ASCENDING) const
    {
      if (m_numel > 1 && (m_reverse ? m_increment < T (0)
                                    : m_increment > T (0)))
        mode = ((mode == DESCENDING) ? UNSORTED : ASCENDING);
      else if (m_numel > 1 && (m_reverse ? m_increment > T (0)
                                         : m_increment < T (0)))
        mode = ((mode == ASCENDING) ? UNSORTED : DESCENDING);
      else
        mode = ((mode == UNSORTED) ? ASCENDING : mode);
 
      return mode;
    }
 
    OCTAVE_API octave_idx_type nnz (void) const;
 
    // Support for single-index subscripting, without generating matrix cache.
 
    T checkelem (octave_idx_type i) const
    {
      if (i < 0 || i >= m_numel)
        err_index_out_of_range (2, 2, i+1, m_numel, dims ());
 
      if (i == 0)
        // Required for proper NaN handling.
        return (m_numel == 1 ? final_value () : m_base);
      else if (i < m_numel - 1)
        return (m_reverse ? m_base + T (i) * m_increment
                          : m_base + T (i) * m_increment);
      else
        return final_value ();
    }
 
    T checkelem (octave_idx_type i, octave_idx_type j) const
    {
      // Ranges are *always* row vectors.
      if (i != 0)
        err_index_out_of_range (1, 1, i+1, m_numel, dims ());
 
      return checkelem (j);
    }
 
    T elem (octave_idx_type i) const
    {
      if (i == 0)
        // Required for proper NaN handling.
        return (m_numel == 1 ? final_value () : m_base);
      else if (i < m_numel - 1)
        return (m_reverse ? m_base - T (i) * m_increment
                          : m_base + T (i) * m_increment);
      else
        return final_value ();
    }
 
    T elem (octave_idx_type /* i */, octave_idx_type j) const
    {
      return elem (j);
    }
 
    T operator () (octave_idx_type i) const
    {
      return elem (i);
    }
 
    T operator () (octave_idx_type i, octave_idx_type j) const
    {
      return elem (i, j);
    }
 
    Array<T> index (const idx_vector& idx) const
    {
      Array<T> retval;
 
      octave_idx_type n = m_numel;
 
      if (idx.is_colon ())
        {
          retval = array_value ().reshape (dim_vector (m_numel, 1));
        }
      else
        {
          if (idx.extent (n) != n)
            err_index_out_of_range (1, 1, idx.extent (n), n, dims ());
 
          dim_vector idx_dims = idx.orig_dimensions ();
          octave_idx_type idx_len = idx.length (n);
 
          // taken from Array.cc.
          if (n != 1 && idx_dims.isvector ())
            idx_dims = dim_vector (1, idx_len);
 
          retval.clear (idx_dims);
 
          // Loop over all values in IDX, executing the lambda
          // expression for each index value.
 
          T *array = retval.fortran_vec ();
 
          idx.loop (n, [=, &array] (octave_idx_type i)
          {
            if (i == 0)
              // Required for proper NaN handling.
              *array++ = (m_numel == 0 ? m_final : m_base);
            else if (i < m_numel - 1)
              *array++ = (m_reverse ? m_base - T (i) * m_increment
                                    : m_base + T (i) * m_increment);
            else
              *array++ = m_final;
          });
        }
 
      return retval;
    }
 
    Array<T> diag (octave_idx_type k) const
    {
      return array_value ().diag (k);
    }
 
    Array<T> array_value (void) const
    {
      octave_idx_type nel = numel ();
 
      Array<T> retval (dim_vector (1, nel));
 
      if (nel == 1)
        // Required for proper NaN handling.
        retval(0) = final_value ();
      else if (nel > 1)
        {
          // The first element must always be *exactly* the base.
          // E.g, -0 would otherwise become +0 in the loop (-0 + 0*increment).
          retval(0) = m_base;
 
          if (m_reverse)
            for (octave_idx_type i = 1; i < nel - 1; i++)
              retval.xelem (i) = m_base - i * m_increment;
          else
            for (octave_idx_type i = 1; i < nel - 1; i++)
              retval.xelem (i) = m_base + i * m_increment;
 
          retval.xelem (nel - 1) = final_value ();
        }
 
      return retval;
    }
 
  private:
 
    T m_base;
    T m_increment;
    T m_limit;
    T m_final;
    octave_idx_type m_numel;
    bool m_reverse;
 
    // Setting the number of elements to zero when the increment is zero
    // is intentional and matches the behavior of Matlab's colon
    // operator.
 
    // These calculations are appropriate for integer ranges.  There are
    // specializations for double and float.
 
    void init (void)
    {
      if (m_reverse)
        {
          m_numel = ((m_increment == T (0)
                      || (m_limit > m_base && m_increment > T (0))
                      || (m_limit < m_base && m_increment < T (0)))
                     ? T (0)
                     : (m_base - m_limit - m_increment) / m_increment);
 
          m_final = m_base - (m_numel - 1) * m_increment;
        }
      else
        {
          m_numel = ((m_increment == T (0)
                      || (m_limit > m_base && m_increment < T (0))
                      || (m_limit < m_base && m_increment > T (0)))
                     ? T (0)
                     : (m_limit - m_base + m_increment) / m_increment);
 
          m_final = m_base + (m_numel - 1) * m_increment;
        }
    }
  };
 
  // Specializations defined externally.
 
  template <> OCTAVE_API bool range<double>::all_elements_are_ints (void) const;
  template <> OCTAVE_API bool range<float>::all_elements_are_ints (void) const;
 
  template <> OCTAVE_API void range<double>::init (void);
  template <> OCTAVE_API void range<float>::init (void);
 
  // For now, only define for floating point types.  However, we only
  // need range<float> as a temporary local variable in make_float_range
  // in ov.cc.
 
#if 0
 
  template <> OCTAVE_API void range<octave_int8>::init (void);
  template <> OCTAVE_API void range<octave_int16>::init (void);
  template <> OCTAVE_API void range<octave_int32>::init (void);
  template <> OCTAVE_API void range<octave_int64>::init (void);
  template <> OCTAVE_API void range<octave_uint8>::init (void);
  template <> OCTAVE_API void range<octave_uint16>::init (void);
  template <> OCTAVE_API void range<octave_uint32>::init (void);
  template <> OCTAVE_API void range<octave_uint64>::init (void);
 
#endif
 
  template <> OCTAVE_API bool range<double>::is_storable (void) const;
  template <> OCTAVE_API bool range<float>::is_storable (void) const;
 
  template <> OCTAVE_API octave_idx_type range<double>::nnz (void) const;
  template <> OCTAVE_API octave_idx_type range<float>::nnz (void) const;
}
 
class
Range
{
public:
 
  OCTAVE_DEPRECATED (7, "use the 'octave::range<double>' class instead")
  Range (void)
    : m_base (0), m_limit (0), m_inc (0), m_numel (0)
  { }
 
  // Assume range is already properly constructed, so just copy internal
  // values.  However, we set LIMIT to the computed final value because
  // that mimics the behavior of the other Range class constructors that
  // reset limit to the computed final value.
 
  OCTAVE_DEPRECATED (7, "use the 'octave::range<double>' class instead")
  Range (const octave::range<double>& r)
    : m_base (r.base ()), m_limit (r.final_value ()), m_inc (r.increment ()),
      m_numel (r.numel ())
  { }
 
  Range (const Range& r) = default;
 
  Range& operator = (const Range& r) = default;
 
  ~Range (void) = default;
 
  OCTAVE_DEPRECATED (7, "use the 'octave::range<double>' class instead")
  Range (double b, double l)
    : m_base (b), m_limit (l), m_inc (1), m_numel (numel_internal ())
  {
    if (! octave::math::isinf (m_limit))
      m_limit = limit_internal ();
  }
 
  OCTAVE_DEPRECATED (7, "use the 'octave::range<double>' class instead")
  Range (double b, double l, double i)
    : m_base (b), m_limit (l), m_inc (i), m_numel (numel_internal ())
  {
    if (! octave::math::isinf (m_limit))
      m_limit = limit_internal ();
  }
 
  // NOTE: The following constructor may be deprecated and removed after
  // the arithmetic operators are removed.
 
  // For operators' usage (to preserve element count) and to create
  // constant row vectors (obsolete usage).
 
  OCTAVE_DEPRECATED (7, "use the 'octave::range<double>' class instead")
  Range (double b, double i, octave_idx_type n)
    : m_base (b), m_limit (b + (n-1) * i), m_inc (i), m_numel (n)
  {
    if (! octave::math::isinf (m_limit))
      m_limit = limit_internal ();
  }
 
  // The range has a finite number of elements.
  bool ok (void) const
  {
    return (octave::math::isfinite (m_limit)
            && (m_numel >= 0 || m_numel == -2));
  }
 
  double base (void) const { return m_base; }
  double limit (void) const { return m_limit; }
  double inc (void) const { return m_inc; }
  double increment (void) const { return m_inc; }
 
  // We adjust the limit to be the final value, so return that.  We
  // could introduce a new variable to store the final value separately,
  // but it seems like that would just add confusion.  If we changed
  // the meaning of the limit function, we would change the behavior of
  // programs that expect limit to be the final value instead of the
  // value of the limit when the range was created.  This problem will
  // be fixed with the new template range class.
  double final_value (void) const { return m_limit; }
 
  octave_idx_type numel (void) const { return m_numel; }
 
  dim_vector dims (void) const { return dim_vector (1, m_numel); }
 
  octave_idx_type rows (void) const { return 1; }
 
  octave_idx_type cols (void) const { return numel (); }
  octave_idx_type columns (void) const { return numel (); }
 
  bool isempty (void) const { return numel () == 0; }
 
  OCTAVE_API bool all_elements_are_ints (void) const;
 
  OCTAVE_API Matrix matrix_value (void) const;
 
  OCTAVE_API double min (void) const;
  OCTAVE_API double max (void) const;
 
  OCTAVE_API void sort_internal (bool ascending = true);
  OCTAVE_API void sort_internal (Array<octave_idx_type>& sidx, bool ascending = true);
 
  OCTAVE_API Matrix diag (octave_idx_type k = 0) const;
 
  OCTAVE_API Range sort (octave_idx_type dim = 0, sortmode mode = ASCENDING) const;
  OCTAVE_API Range sort (Array<octave_idx_type>& sidx, octave_idx_type dim = 0,
              sortmode mode = ASCENDING) const;
 
  OCTAVE_API sortmode issorted (sortmode mode = ASCENDING) const;
 
  OCTAVE_API octave_idx_type nnz (void) const;
 
  // Support for single-index subscripting, without generating matrix cache.
 
  OCTAVE_API double checkelem (octave_idx_type i) const;
  OCTAVE_API double checkelem (octave_idx_type i, octave_idx_type j) const;
 
  OCTAVE_API double elem (octave_idx_type i) const;
  double elem (octave_idx_type /* i */, octave_idx_type j) const
  { return elem (j); }
 
  double operator () (octave_idx_type i) const { return elem (i); }
  double operator () (octave_idx_type i, octave_idx_type j) const
  { return elem (i, j); }
 
  OCTAVE_API Array<double> index (const octave::idx_vector& i) const;
 
  OCTAVE_API void set_base (double b);
 
  OCTAVE_API void set_limit (double l);
 
  OCTAVE_API void set_inc (double i);
 
  friend OCTAVE_API std::ostream& operator << (std::ostream& os,
                                               const Range& r);
  friend OCTAVE_API std::istream& operator >> (std::istream& is, Range& r);
 
  friend OCTAVE_API Range operator - (const Range& r);
  friend OCTAVE_API Range operator + (double x, const Range& r);
  friend OCTAVE_API Range operator + (const Range& r, double x);
  friend OCTAVE_API Range operator - (double x, const Range& r);
  friend OCTAVE_API Range operator - (const Range& r, double x);
  friend OCTAVE_API Range operator * (double x, const Range& r);
  friend OCTAVE_API Range operator * (const Range& r, double x);
 
private:
 
  double m_base;
  double m_limit;
  double m_inc;
 
  octave_idx_type m_numel;
 
  OCTAVE_API octave_idx_type numel_internal (void) const;
 
  OCTAVE_API double limit_internal (void) const;
 
  OCTAVE_API void init (void);
 
protected:
 
  // NOTE: The following constructor may be removed when the arithmetic
  // operators are removed.
 
  // For operators' usage (to allow all values to be set directly).
  Range (double b, double l, double i, octave_idx_type n)
    : m_base (b), m_limit (l), m_inc (i), m_numel (n)
  { }
};
 
#if defined (OCTAVE_PROVIDE_DEPRECATED_SYMBOLS)
OCTAVE_DEPRECATED (7, "arithmetic operations on Range objects are unreliable")
extern OCTAVE_API Range operator - (const Range& r);
 
OCTAVE_DEPRECATED (7, "arithmetic operations on Range objects are unreliable")
extern OCTAVE_API Range operator + (double x, const Range& r);
 
OCTAVE_DEPRECATED (7, "arithmetic operations on Range objects are unreliable")
extern OCTAVE_API Range operator + (const Range& r, double x);
 
OCTAVE_DEPRECATED (7, "arithmetic operations on Range objects are unreliable")
extern OCTAVE_API Range operator - (double x, const Range& r);
 
OCTAVE_DEPRECATED (7, "arithmetic operations on Range objects are unreliable")
extern OCTAVE_API Range operator - (const Range& r, double x);
 
OCTAVE_DEPRECATED (7, "arithmetic operations on Range objects are unreliable")
extern OCTAVE_API Range operator * (double x, const Range& r);
 
OCTAVE_DEPRECATED (7, "arithmetic operations on Range objects are unreliable")
extern OCTAVE_API Range operator * (const Range& r, double x);
#endif
 
#endif