BaseFunctions.hpp

Go to the documentation of this file.

/*--------------------------------------------------------------------------------------------
Copyright (c) 2019, NDEVR LLC
tyler.parke@ndevr.org
  __    __   ____     _____ __     __  _______
 |  \  |  | |  __ \  |  ___|\ \   / / |   __  \
 |   \ |  | | |  \ \ | |___  \ \ / /  |  |__)  |
 |  . \|  | | |__/ / | |___   \ V /   |   _   /
 |  |\    |_|_____/__|_____|___\_/____|  | \  \
 |__| \__________________________________|  \__\
 
Subject to the terms of the Enterprise+ Agreement, NDEVR hereby grants 
Licensee a limited, non-exclusive, non-transferable, royalty-free license 
(without the right to sublicense) to use the API solely for the purpose of 
Licensee's internal development efforts to develop applications for which 
the API was provided.
 
The above copyright notice and this permission notice shall be included in all 
copies or substantial portions of the Software.
 
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE
FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
 
Library: Base
File: BaseFunctions
Included in API: True
Author(s): Tyler Parke
 *-----------------------------------------------------------------------------------------**/
#pragma once
#include <NDEVR/BaseValues.h>
#include <NDEVR/LibAssert.h>
namespace NDEVR
{
 
    /**
    \brief Finds the minimum of the given arguments based on the < operator
    Author: Tyler Parke
    Date: 2017-11-05
    \param[in] left A t_type to process.
    \param[in] right A t_type to process.
 
    The only requirement is that t_type have > operator defined.
 
    For Vector-based structures a new object is created that, for each dimension stores the max for that
        dimension.
 
    Note integers, use same as the templated getMax, however, we can optimize specially for integers using
        some bit twiddling tricks. This removes a branch statement entirely and is likely faster on a modern CPU
 
    \return The calculated minimum.
    **/
    template <typename t_type>
    constexpr t_type getMin(const t_type& left, const t_type& right) { return left < right ? left : right; }
    template <typename t_type>
    constexpr t_type getMin(const t_type& left, const t_type& middle, const t_type& right) { return getMin(getMin(left, middle), right); }
 
    template<>
    constexpr sint01 getMin(const sint01& left, const sint01& right) { return left ^ ((right ^ left) & -(right < left)); }
    template<>
    constexpr uint01 getMin(const uint01& left, const uint01& right) { return static_cast<uint01>(left ^ ((right ^ left) & -(right < left))); }
 
    template<>
    constexpr sint02 getMin(const sint02& left, const sint02& right) { return left ^ ((right ^ left) & -(right < left)); }
    template<>
    constexpr uint02 getMin(const uint02& left, const uint02& right) { return static_cast<uint02>(left ^ ((right ^ left) & -(right < left))); }
 
    template<>
    constexpr sint04 getMin(const sint04& left, const sint04& right) { return left ^ ((right ^ left) & -(right < left)); }
    template<>
    constexpr uint04 getMin(const uint04& left, const uint04& right) { return  static_cast<uint04>(left ^ ((right ^ left) & -(right < left))); }
 
    template<>
    constexpr sint08 getMin(const sint08& left, const sint08& right) { return left ^ ((right ^ left) & -(right < left)); }
    template<>
    constexpr uint08 getMin(const uint08& left, const uint08& right) { return static_cast<uint08>(left ^ ((right ^ left) & -(right < left))); }
 
    /**
    \brief Finds the max of the given arguments using the > operator
    The only requirement is that t_type have > operator defined.
 
    For Vector-based structures a new object is created that, for each dimension stores the max for that
        dimension.
 
    Note integers, use same as the templated getMax, however, we can optimize specially for integers using
        some bit twiddling tricks. This removes a branch statement entirely and is likely faster on a modern CPU
    \param[in] left -    One of two comparators to determine the max of.
    \param[in] right -    One of two comparators to determine the max of.
    \return The calculated maximum.
    **/
    template <typename t_type>
    constexpr t_type getMax(const t_type& left, const t_type& right) { return left > right ? left : right; }
    template <typename t_type>
    constexpr t_type getMax(const t_type& left, const t_type& middle, const t_type& right) { return getMax(getMax(left, middle), right); }
 
    template<>
    constexpr sint01 getMax(const sint01& left, const sint01& right) { return left ^ ((left ^ right) & -(left < right)); }
    template<>
    constexpr uint01 getMax(const uint01& left, const uint01& right) { return static_cast<uint01>(left ^ ((left ^ right) & -(left < right))); }
 
    template<>
    constexpr sint02 getMax(const sint02& left, const sint02& right) { return left ^ ((left ^ right) & -(left < right)); }
    template<>
    constexpr uint02 getMax(const uint02& left, const uint02& right) { return static_cast<uint02>(left ^ ((left ^ right) & -(left < right))); }
 
    template<>
    constexpr sint04 getMax(const sint04& left, const sint04& right) { return left ^ ((left ^ right) & -(left < right)); }
    template<>
    constexpr uint04 getMax(const uint04& left, const uint04& right) { return static_cast<uint04>(left ^ ((left ^ right) & -(left < right))); }
 
    template<>
    constexpr sint08 getMax(const sint08& left, const sint08& right) { return left ^ ((left ^ right) & -(left < right)); }
    template<>
    constexpr uint08 getMax(const uint08& left, const uint08& right) { return static_cast<uint08>(left ^ ((left ^ right) & -(left < right))); }
 
 
 
    /**
    \brief Rounds the value to the nearest multiple given and returns that value.
 
    For example quantize(.8, .25) would return .75.
        quantize(.8, .1) would return .8 and quantize(.8, .5) would return 1.0
    Author: Tyler Parke
 
    Date: 2017-11-05
 
    \param[in] value A t_type to process.
    \param[in] d (Optional) A t_type to process. Default value is 1.
    \return The nearest multiple from the given input. 
    **/
    template <typename t_type>
    constexpr t_type quantize(t_type value, t_type d = cast<t_type>(1))
    {
        return cast<t_type>(cast<sint08>(value / d + cast<t_type>(value < 0 ? -0.5 : 0.5))) * d;
    }
 
    /**
    \brief A simple function that returns 1 for all values greater than or equal to 0 and -1 for all values less than 0
 
    Author: Tyler Parke
 
    Date: 2017-11-05
 
    \param[in] value -  The value to check the sign of.
 
    \return 1 for all values greater than or equal to 0 and -1 for all values less than 0.
    **/
    template <typename t_type>
    constexpr t_type sign(t_type value)
    {
        return value >= 0 ? cast<t_type>(1) : cast<t_type>(-1);
    }
 
 
    /**
    \brief Query if 'value' is valid or invalid. Invalid values should return invalid if used for
        calculations or false for operator checks, when possible.
 
    Author: Tyler Parke
 
    Date: 2017-11-05
 
    \param[in] value The value.
 
    \return True if the value is invalid, false if the value is valid.
    **/
    template<class t_type>
    constexpr bool IsInvalid(const t_type& value)
    {
        return value == Constant<t_type>::Invalid;
    }
    template<>
    constexpr bool IsInvalid(const fltp04& value)
    {
        // ReSharper disable once CppIdenticalOperandsInBinaryExpression
        return value != value;
    }
    template<>
    constexpr bool IsInvalid(const fltp08& value)
    {
        // ReSharper disable once CppIdenticalOperandsInBinaryExpression
        return value != value;
    }
 
    /**
    \brief Clips the value given so that that the returned value falls between upper and lower bound.
 
    For example, clip(-1, 0, 10) would return 0, clip(.5, 0, 10) would return .5, and clip(11.5, 0, 10)
        would return 10.
 
    Author: Tyler Parke
 
    Date: 2017-11-05
 
    \param[in] value The value. If this falls between the upper and lower bound it is returned.
    \param[in] lower_bound The lower bound. It is assumed that this will always be a value less than or equal to
        the upper bound.
    \param[in] upper_bound The upper bound. It is assumed that this will always be a value greater than or equal to
        the lower bound.
 
    \return the value if it falls between the upper or lower bound, otherwise if less than lower bound.
        returns lower bound and if greater than upper bound returns upper bound.
    **/
    template <typename t_type>
    constexpr t_type clip(const t_type& value, const t_type& lower_bound, const t_type& upper_bound)
    {
        lib_assert(IsInvalid(lower_bound) || IsInvalid(upper_bound) || (lower_bound <= upper_bound), "Invalid clip: upper bound is less than lower bound");
        return getMax(lower_bound, getMin(value, upper_bound));
    }
};