Chris@16: /* 
Chris@16:    Copyright (c) Marshall Clow 2008-2012.
Chris@16: 
Chris@16:    Distributed under the Boost Software License, Version 1.0. (See accompanying
Chris@16:    file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
Chris@16: 
Chris@16:  Revision history:
Chris@16:    27 June 2009 mtc First version
Chris@16:    23 Oct  2010 mtc Added predicate version
Chris@16:    
Chris@16: */
Chris@16: 
Chris@16: /// \file clamp.hpp
Chris@16: /// \brief Clamp algorithm
Chris@16: /// \author Marshall Clow
Chris@16: ///
Chris@16: /// Suggested by olafvdspek in https://svn.boost.org/trac/boost/ticket/3215
Chris@16: 
Chris@16: #ifndef BOOST_ALGORITHM_CLAMP_HPP
Chris@16: #define BOOST_ALGORITHM_CLAMP_HPP
Chris@16: 
Chris@16: #include <functional>       //  For std::less
Chris@16: #include <iterator>         //  For std::iterator_traits
Chris@16: #include <cassert>
Chris@16: 
Chris@16: #include <boost/range/begin.hpp>
Chris@16: #include <boost/range/end.hpp>
Chris@16: #include <boost/mpl/identity.hpp>      // for identity
Chris@16: #include <boost/utility/enable_if.hpp> // for boost::disable_if
Chris@16: 
Chris@16: namespace boost { namespace algorithm {
Chris@16: 
Chris@16: /// \fn clamp ( T const& val, 
Chris@101: ///               typename boost::mpl::identity<T>::type const & lo, 
Chris@101: ///               typename boost::mpl::identity<T>::type const & hi, Pred p )
Chris@16: /// \return the value "val" brought into the range [ lo, hi ]
Chris@16: ///     using the comparison predicate p.
Chris@16: ///     If p ( val, lo ) return lo.
Chris@16: ///     If p ( hi, val ) return hi.
Chris@16: ///     Otherwise, return the original value.
Chris@16: /// 
Chris@16: /// \param val   The value to be clamped
Chris@16: /// \param lo    The lower bound of the range to be clamped to
Chris@16: /// \param hi    The upper bound of the range to be clamped to
Chris@16: /// \param p     A predicate to use to compare the values.
Chris@16: ///                 p ( a, b ) returns a boolean.
Chris@16: ///
Chris@16:   template<typename T, typename Pred> 
Chris@16:   T const & clamp ( T const& val, 
Chris@16:     typename boost::mpl::identity<T>::type const & lo, 
Chris@16:     typename boost::mpl::identity<T>::type const & hi, Pred p )
Chris@16:   {
Chris@16: //    assert ( !p ( hi, lo ));    // Can't assert p ( lo, hi ) b/c they might be equal
Chris@16:     return p ( val, lo ) ? lo : p ( hi, val ) ? hi : val;
Chris@16:   } 
Chris@16: 
Chris@16: 
Chris@16: /// \fn clamp ( T const& val, 
Chris@101: ///               typename boost::mpl::identity<T>::type const & lo, 
Chris@101: ///               typename boost::mpl::identity<T>::type const & hi )
Chris@16: /// \return the value "val" brought into the range [ lo, hi ].
Chris@16: ///     If the value is less than lo, return lo.
Chris@16: ///     If the value is greater than "hi", return hi.
Chris@16: ///     Otherwise, return the original value.
Chris@16: ///
Chris@16: /// \param val   The value to be clamped
Chris@16: /// \param lo    The lower bound of the range to be clamped to
Chris@16: /// \param hi    The upper bound of the range to be clamped to
Chris@16: ///
Chris@16:   template<typename T> 
Chris@16:   T const& clamp ( const T& val, 
Chris@16:     typename boost::mpl::identity<T>::type const & lo, 
Chris@16:     typename boost::mpl::identity<T>::type const & hi )
Chris@16:   {
Chris@16:     return (clamp) ( val, lo, hi, std::less<T>());
Chris@16:   } 
Chris@16: 
Chris@16: /// \fn clamp_range ( InputIterator first, InputIterator last, OutputIterator out, 
Chris@101: ///       std::iterator_traits<InputIterator>::value_type const & lo, 
Chris@101: ///       std::iterator_traits<InputIterator>::value_type const & hi )
Chris@16: /// \return clamp the sequence of values [first, last) into [ lo, hi ]
Chris@16: /// 
Chris@16: /// \param first The start of the range of values
Chris@16: /// \param last  One past the end of the range of input values
Chris@16: /// \param out   An output iterator to write the clamped values into
Chris@16: /// \param lo    The lower bound of the range to be clamped to
Chris@16: /// \param hi    The upper bound of the range to be clamped to
Chris@16: ///
Chris@16:   template<typename InputIterator, typename OutputIterator> 
Chris@16:   OutputIterator clamp_range ( InputIterator first, InputIterator last, OutputIterator out,
Chris@101:     typename std::iterator_traits<InputIterator>::value_type const & lo, 
Chris@101:     typename std::iterator_traits<InputIterator>::value_type const & hi )
Chris@16:   {
Chris@16:   // this could also be written with bind and std::transform
Chris@16:     while ( first != last )
Chris@16:         *out++ = clamp ( *first++, lo, hi );
Chris@16:     return out;
Chris@16:   } 
Chris@16: 
Chris@16: /// \fn clamp_range ( const Range &r, OutputIterator out, 
Chris@101: ///       typename std::iterator_traits<typename boost::range_iterator<const Range>::type>::value_type const & lo,
Chris@101: ///       typename std::iterator_traits<typename boost::range_iterator<const Range>::type>::value_type const & hi )
Chris@16: /// \return clamp the sequence of values [first, last) into [ lo, hi ]
Chris@16: /// 
Chris@16: /// \param r     The range of values to be clamped
Chris@16: /// \param out   An output iterator to write the clamped values into
Chris@16: /// \param lo    The lower bound of the range to be clamped to
Chris@16: /// \param hi    The upper bound of the range to be clamped to
Chris@16: ///
Chris@16:   template<typename Range, typename OutputIterator> 
Chris@16:   typename boost::disable_if_c<boost::is_same<Range, OutputIterator>::value, OutputIterator>::type
Chris@16:   clamp_range ( const Range &r, OutputIterator out,
Chris@101:     typename std::iterator_traits<typename boost::range_iterator<const Range>::type>::value_type const & lo, 
Chris@101:     typename std::iterator_traits<typename boost::range_iterator<const Range>::type>::value_type const & hi )
Chris@16:   {
Chris@16:     return clamp_range ( boost::begin ( r ), boost::end ( r ), out, lo, hi );
Chris@16:   } 
Chris@16: 
Chris@16: 
Chris@16: /// \fn clamp_range ( InputIterator first, InputIterator last, OutputIterator out, 
Chris@101: ///       std::iterator_traits<InputIterator>::value_type const & lo, 
Chris@101: ///       std::iterator_traits<InputIterator>::value_type const & hi, Pred p )
Chris@16: /// \return clamp the sequence of values [first, last) into [ lo, hi ]
Chris@16: ///     using the comparison predicate p.
Chris@16: /// 
Chris@16: /// \param first The start of the range of values
Chris@16: /// \param last  One past the end of the range of input values
Chris@16: /// \param out   An output iterator to write the clamped values into
Chris@16: /// \param lo    The lower bound of the range to be clamped to
Chris@16: /// \param hi    The upper bound of the range to be clamped to
Chris@16: /// \param p     A predicate to use to compare the values.
Chris@16: ///                 p ( a, b ) returns a boolean.
Chris@16: 
Chris@16: ///
Chris@16:   template<typename InputIterator, typename OutputIterator, typename Pred> 
Chris@16:   OutputIterator clamp_range ( InputIterator first, InputIterator last, OutputIterator out,
Chris@101:     typename std::iterator_traits<InputIterator>::value_type const & lo, 
Chris@101:     typename std::iterator_traits<InputIterator>::value_type const & hi, Pred p )
Chris@16:   {
Chris@16:   // this could also be written with bind and std::transform
Chris@16:     while ( first != last )
Chris@16:         *out++ = clamp ( *first++, lo, hi, p );
Chris@16:     return out;
Chris@16:   } 
Chris@16: 
Chris@16: /// \fn clamp_range ( const Range &r, OutputIterator out, 
Chris@101: ///       typename std::iterator_traits<typename boost::range_iterator<const Range>::type>::value_type const & lo,
Chris@101: ///       typename std::iterator_traits<typename boost::range_iterator<const Range>::type>::value_type const & hi,
Chris@16: ///       Pred p )
Chris@16: /// \return clamp the sequence of values [first, last) into [ lo, hi ]
Chris@16: ///     using the comparison predicate p.
Chris@16: /// 
Chris@16: /// \param r     The range of values to be clamped
Chris@16: /// \param out   An output iterator to write the clamped values into
Chris@16: /// \param lo    The lower bound of the range to be clamped to
Chris@16: /// \param hi    The upper bound of the range to be clamped to
Chris@16: /// \param p     A predicate to use to compare the values.
Chris@16: ///                 p ( a, b ) returns a boolean.
Chris@16: //
Chris@16: //  Disable this template if the first two parameters are the same type;
Chris@16: //  In that case, the user will get the two iterator version.
Chris@16:   template<typename Range, typename OutputIterator, typename Pred> 
Chris@16:   typename boost::disable_if_c<boost::is_same<Range, OutputIterator>::value, OutputIterator>::type
Chris@16:   clamp_range ( const Range &r, OutputIterator out,
Chris@101:     typename std::iterator_traits<typename boost::range_iterator<const Range>::type>::value_type const & lo, 
Chris@101:     typename std::iterator_traits<typename boost::range_iterator<const Range>::type>::value_type const & hi,
Chris@16:     Pred p )
Chris@16:   {
Chris@16:     return clamp_range ( boost::begin ( r ), boost::end ( r ), out, lo, hi, p );
Chris@16:   } 
Chris@16: 
Chris@16: 
Chris@16: }}
Chris@16: 
Chris@16: #endif // BOOST_ALGORITHM_CLAMP_HPP