source: trunk/yat/utility/KernelMatrix.h @ 3190

#ifndef _theplu_yat_utility_kernel_matrix_
#define _theplu_yat_utility_kernel_matrix_

// $Id: KernelMatrix.h 3190 2014-03-30 07:47:40Z peter $

/*
  Copyright (C) 2014 Peter Johansson

  This file is part of the yat library, http://dev.thep.lu.se/yat

  The yat library 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.

  The yat library 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 yat. If not, see <http://www.gnu.org/licenses/>.
*/

#include "Container2DIterator.h"
#include "StrideIterator.h"

namespace theplu {
namespace yat {
namespace utility {

  /**
     \brief A KernelMatrix is a \ref concept_container_2d

     A matrix-like object constructed from two
     <a href="http://www.sgi.com/tech/stl/RandomAccessContainer.html">

     RandomAccessContainer</a>s and Functor. Each row in the matrix
     correspond to an element in the RandomAccessRange1 and each
     column correspond to an element in RandomAccessRange2. Number of
     rows in the matrix equals number of element in RandomAccessRange1
     and number of columns equals number of elements in
     RandomAccessRange2. An element in row \a row and column \a column
     is calculated by taking the element \a row in RandomAccessRange1
     and element \a column in RandomAccessRange2, and passing these
     elements to BinaryFunctor.

     Type Requirements:
     - \c RandomAccessContainer1 must be a
     <a href="http://www.sgi.com/tech/stl/RandomAccessContainer.html">
     RandomAccessContainer</a>
     - \c RandomAccessContainer2 must be a
     <a href="http://www.sgi.com/tech/stl/RandomAccessContainer.html">
     RandomAccessContainer</a>
     - \c BinaryFunctor must be a
     <a href="http://www.sgi.com/tech/stl/AdaptableBinaryFunction.html">
     AdaptableBinaryFunctor</a>
     - \c RandomAccessContainer1::reference must be convertible to
     \c BinaryFunctor::first_argument_type
     - \c RandomAccessContainer2::reference must be convertible to
     \c BinaryFunctor::second_argument_type
   */
  template <class RandomAccessRange1, class RandomAccessRange2,
            class BinaryFunctor>
  class KernelMatrix
  {
  public:
    /// \c value_type is same as BinaryFunctor's result_type
    typedef typename BinaryFunctor::result_type value_type;

    /// \c const_reference is same as \c value_type
    typedef value_type const_reference;

    /// \brief \c const_iterator
    typedef Container2DIterator<const KernelMatrix, value_type, const_reference>
    const_iterator;

    /// \brief \c const_column_iterator
    typedef StrideIterator<const_iterator> const_column_iterator;

    /// \brief \c const_row_iterator_iterator
    typedef const_iterator const_row_iterator;

    /**
       \brief constructor

       Same as three-argument constructor, but using default
       constructor of class BinaryFunctor.
     */
    KernelMatrix(const RandomAccessRange1& r1, const RandomAccessRange2& r2)
      : range1_(r1), range2_(r2) {}

    /**
       \brief constructor
     */
    KernelMatrix(const RandomAccessRange1& r1, const RandomAccessRange2& r2,
                 const BinaryFunctor& bf)
      : range1_(r1), range2_(r2), func_(bf) {}

    /**
       Iterator iterates along a row. When end of row is reached it
       jumps to beginning of next row.

       \return const_iterator pointing to upper-left element.
     */
    const_iterator begin(void) const { return const_iterator(*this, 0, 0); }


    /**
       Iterator iterates along a column.

       \return const_iterator pointing to first element of column \a column.
     */
    const_column_iterator begin_column(size_t column) const
    {
      return const_column_iterator(const_iterator(*this, 0, column),
                                   this->columns());
    }


    /**
       Iterator iterates along a row.

       \return const_iterator pointing to first element of row \a row.
     */
    const_row_iterator begin_row(size_t row) const
    { return const_row_iterator(*this, row, 0); }


    /**
       \return const_iterator pointing to end of matrix
     */
    const_iterator end(void) const
    { return const_iterator(*this, rows(), 0); }


    /**
       \return const_iterator pointing to end of column \a i
     */
    const_column_iterator end_column(size_t column) const
    {
      return const_column_iterator(const_iterator(*this, this->rows(), column),
                                   this->columns());
    }


    /**
       \return const_iterator pointing to end of row \a i
     */
    const_row_iterator end_row(size_t row) const
    { return const_row_iterator(*this, row, this->columns()); }


    /**
       Number of rows is defined by RandomAccessRange2::size(void)

       \return The number of columns in the matrix.
    */
    typename RandomAccessRange2::size_type columns(void) const
    { return range2_.size(); }


    /**
       Number of rows is defined by RandomAccessRange1::size(void)

       \return The number of rows in the matrix.
    */
    typename RandomAccessRange1::size_type rows(void) const
    { return range1_.size(); }


    /**
       \brief Element access operator.

       Element is calculated using BinaryFunctor passing
       \c row th element of RandomAccessRange1 and \c column th element in
       RandomAccessRange2.

       \return Reference to the element position (\a row, \a column).
    */
    const_reference operator()(size_t row, size_t column) const
    { return func_(range1_[row], range2_[column]); }

  private:
    RandomAccessRange1 range1_;
    RandomAccessRange2 range2_;
    BinaryFunctor func_;
  };

}}} // of namespace utility, yat, and theplu

#endif