STFF-Utility.h

Go to the documentation of this file.

///
/// @file STFF-Utility.h
///
/// Header file containing declarations for free functions in the STFF::
/// namespace that perform
/// - @link conversion_functions units conversions @endlink, and
/// - @link validation_functions validation @endlink of enumerations
///   defined in STFF-Types.h.
///
/// @copyright
/// Copyright (c) 2012-2015 Sifferman Technology, LLC. All rights reserved.
///

#ifndef STFF_Utility_h_
#define STFF_Utility_h_


namespace STFF {

    ////////////////////////////////////////////////////////////////////////////
    //
    // NON-MEMBER FUNCTIONS
    //
    ////////////////////////////////////////////////////////////////////////////

    ////////////////////////////////////////////////////////////////////////////
    /// @defgroup   stff_non_member_functions       Non-Member Functions
    ///
    /// Free functions within the STFF namespace that are not members of any class.
    ///
    /// @see stff_member_functions
    ////////////////////////////////////////////////////////////////////////////


    ////////////////////////////////////
    // CONVERSION FUNCTIONS
    ////////////////////////////////////

    ////////////////////////////////////////////////////////////////////////////
    /// @defgroup   conversion_functions            Conversion Functions
    /// @ingroup    stff_non_member_functions
    ///
    /// These functions provide a convenient facility for converting data
    /// values from one set of units to another.
    /// For example, the STFF::ConvertSpeed function
    /// will convert a speed in knots into its equivalent in miles per hour
    /// or kilometers per hour.
    ///
    /// These are non-member functions that reside in the STFF namespace.
    ////////////////////////////////////////////////////////////////////////////

    ////////////////////////////////////////////////////////////////////////////
    /// @fn ConvertDepth (FF_DepthUnits_t, FF_DepthUnits_t, double, double*)
    ///
    /// Convert a depth value from one set of units (feet, meters, or fathoms)
    /// to another.
    ///
    /// @note       If the input value is in a fraction of the @p fromUnits
    ///             parameter (e.g. hundredths of a foot), then the output
    ///             value will be in the same fraction of the @p toUnits
    ///             parameter (e.g. hundredths of a meter).
    ///
    /// @param[in]  fromUnits
    ///             Units corresponding to the @p input parameter
    ///
    /// @param[in]  toUnits
    ///             Units corresponding to the @p pOutput parameter
    ///
    /// @param[in]  input
    ///             The value to be converted
    ///
    /// @param[out] pOutput
    ///             Pointer to the location where the converted value will
    ///             be stored
    ///
    /// @retval     ::FF_ERR_NO_ERROR
    ///             if the conversion succeeded
    ///
    /// @retval     ::FF_ERR_ARGUMENT_OUT_OF_RANGE
    ///             if @p fromUnits, @p toUnits, or @p input contain
    ///             illegal values
    ///
    /// @retval     ::FF_ERR_INVALID_POINTER
    ///             if @p pOutput is a null pointer
    ///
    /// @see        ::FF_DepthUnits_t
    ///
    /// @ingroup    conversion_functions
    ///
    FF_Error_t ConvertDepth (FF_DepthUnits_t fromUnits,
                             FF_DepthUnits_t toUnits,
                             double input,
                             double *pOutput);


    ////////////////////////////////////////////////////////////////////////////
    /// @fn ConvertSpeed (FF_SpeedUnits_t, FF_SpeedUnits_t, double, double*)
    ///
    /// Convert a speed value from one set of units (knots, miles per hour,
    /// or kilometers per hour) to another.
    ///
    /// Note that if the input value is in a fraction of the @p fromUnits
    /// parameter (e.g. hundredths of a knot), then the output value will be
    /// in the same fraction of the @p toUnits parameter (e.g. hundredths of a
    /// mph).
    ///
    /// @param[in]  fromUnits
    ///             Units corresponding to the @p input parameter
    ///
    /// @param[in]  toUnits
    ///             Units corresponding to the @p pOutput parameter
    ///
    /// @param[in]  input
    ///             The value to be converted
    ///
    /// @param[out] pOutput
    ///             Pointer to the location where the converted
    ///             value will be stored
    ///
    /// @retval     ::FF_ERR_NO_ERROR
    ///             if the conversion succeeded
    ///
    /// @retval     ::FF_ERR_ARGUMENT_OUT_OF_RANGE
    ///             if @p fromUnits, @p toUnits, or @p input contain
    ///             illegal values
    ///
    /// @retval     ::FF_ERR_INVALID_POINTER
    ///             if @p pOutput is a null pointer
    ///
    /// @see        ::FF_SpeedUnits_t
    ///
    /// @ingroup    conversion_functions
    ///
    FF_Error_t ConvertSpeed (FF_SpeedUnits_t fromUnits,
                             FF_SpeedUnits_t toUnits,
                             double input,
                             double *pOutput);


    ////////////////////////////////////////////////////////////////////////////
    /// @fn ConvertTemperature (FF_TemperatureUnits_t, FF_TemperatureUnits_t, double, double*)
    ///
    /// Convert a temperature value from one set of units (degrees Celsius or
    /// degrees Fahrenheit) to the other.
    ///
    /// Note that if the input value is in a fraction of the @p fromUnits
    /// parameter (e.g. hundredths of a degree C), then the output value will be
    /// in the same fraction of the @p toUnits parameter (e.g. hundredths of a
    /// degree F).
    ///
    /// @param[in]  fromUnits
    ///             Units corresponding to the @p input parameter
    ///
    /// @param[in]  toUnits
    ///             Units corresponding to the @p pOutput parameter
    ///
    /// @param[in]  input
    ///             The value to be converted
    ///
    /// @param[out] pOutput
    ///             Pointer to the location where the converted
    ///             value will be stored
    ///
    /// @retval     ::FF_ERR_NO_ERROR
    ///             if the conversion succeeded
    ///
    /// @retval     ::FF_ERR_ARGUMENT_OUT_OF_RANGE
    ///             if @p fromUnits, @p toUnits, or @p input contain
    ///             illegal values
    ///
    /// @retval     ::FF_ERR_INVALID_POINTER
    ///             if @p pOutput is a null pointer
    ///
    /// @see        ::FF_TemperatureUnits_t
    ///
    /// @ingroup    conversion_functions
    ///
    FF_Error_t ConvertTemperature (FF_TemperatureUnits_t fromUnits,
                                   FF_TemperatureUnits_t toUnits,
                                   double input,
                                   double *pOutput);


    ////////////////////////////////////
    // VALIDATION FUNCTIONS
    ////////////////////////////////////

    ////////////////////////////////////////////////////////////////////////////
    /// @defgroup   validation_functions            Validation Functions
    /// @ingroup    stff_non_member_functions
    ///
    /// Functions that provide a quick test to verify that an enumeration value
    /// falls within the range of valid values for the given type.  These are
    /// overloaded functions, all having the same name @e valid, but each with
    /// a distinct argument list.
    ///
    /// These are non-member functions that reside in the STFF namespace.
    ////////////////////////////////////////////////////////////////////////////


    ////////////////////////////////////////////////////////////////////////////
    /// @fn valid (FF_Frequency_t frequency)
    ///
    /// Test that a value is valid for a variable of type ::FF_Frequency_t.
    ///
    /// @param[in]  frequency
    ///             the value to be tested
    ///
    /// @retval     true
    ///             if the value of the @p frequency parameter is valid
    ///             for a variable of type ::FF_Frequency_t
    ///
    /// @retval     false
    ///             otherwise
    ///
    /// @remark     This is an overloaded function that differs from other
    ///             valid() functions in the argument(s) it accepts.
    ///
    /// @see        ::FF_Frequency_t
    ///
    /// @ingroup    validation_functions
    ///
    inline bool valid (FF_Frequency_t frequency)
    {
        return (frequency > FF_INVALID_FREQUENCY &&
                frequency < FF_TOTAL_FREQUENCIES);
    }


    ////////////////////////////////////////////////////////////////////////////
    /// @fn valid (FF_DepthUnits_t units)
    ///
    /// Test that a value is valid for a variable of type ::FF_DepthUnits_t.
    ///
    /// @param[in]  units
    ///             the value to be tested
    ///
    /// @retval     true
    ///             if the value of the @p units parameter is valid
    ///             for a variable of type ::FF_DepthUnits_t
    //
    /// @retval     false
    ///             otherwise
    ///
    /// @remark     This is an overloaded function that differs from other
    ///             valid() functions in the argument(s) it accepts.
    ///
    /// @see        ::FF_DepthUnits_t
    ///
    /// @ingroup    validation_functions
    ///
    inline bool valid (FF_DepthUnits_t units)
    {
        return (units > FF_INVALID_DEPTH_UNITS &&
                units < FF_TOTAL_DEPTH_UNITS);
    }


    ////////////////////////////////////////////////////////////////////////////
    /// @fn valid (FF_SpeedUnits_t units)
    ///
    /// Test that a value is valid for a variable of type ::FF_SpeedUnits_t.
    ///
    /// @param[in]  units
    ///             the value to be tested
    ///
    /// @retval     true
    ///             if the value of the @p units parameter is valid
    ///             for a variable of type ::FF_SpeedUnits_t
    ///
    /// @retval     false
    ///             otherwise
    ///
    /// @remark     This is an overloaded function that differs from other
    ///             valid() functions in the argument(s) it accepts.
    ///
    /// @see        ::FF_SpeedUnits_t
    ///
    /// @ingroup    validation_functions
    ///
    inline bool valid (FF_SpeedUnits_t units)
    {
        return (units > FF_INVALID_SPEED_UNITS &&
                units < FF_TOTAL_SPEED_UNITS);
    }


    ////////////////////////////////////////////////////////////////////////////
    /// @fn valid (FF_TemperatureUnits_t units)
    ///
    /// Test that a value is valid for a variable of type
    /// ::FF_TemperatureUnits_t.
    ///
    /// @param[in]  units
    ///             the value to be tested
    ///
    /// @retval     true
    ///             if the value of the @p units parameter is valid
    ///             for a variable of type ::FF_TemperatureUnits_t
    ///
    /// @retval     false
    ///             otherwise
    ///
    /// @remark     This is an overloaded function that differs from other
    ///             valid() functions in the argument(s) it accepts.
    ///
    /// @see        ::FF_TemperatureUnits_t
    ///
    /// @ingroup    validation_functions
    ///
    inline bool valid (FF_TemperatureUnits_t units)
    {
        return (units > FF_INVALID_TEMPERATURE_UNITS &&
                units < FF_TOTAL_TEMPERATURE_UNITS);
    }


    ////////////////////////////////////////////////////////////////////////////
    /// @fn valid (FF_SettingType_t settingType)
    ///
    /// Test that a value is valid for a variable of type ::FF_SettingType_t.
    ///
    /// @param[in]  settingType
    ///             the value to be tested
    ///
    /// @retval     true
    ///             if the value of the @p settingType parameter is valid
    ///             for a variable of type ::FF_SettingType_t
    ///
    /// @retval     false
    ///             otherwise
    ///
    /// @remark     This is an overloaded function that differs from other
    ///             valid() functions in the argument(s) it accepts.
    ///
    /// @see        ::FF_SettingType_t
    ///
    /// @ingroup    validation_functions
    ///
    inline bool valid (FF_SettingType_t settingType)
    {
        return (settingType > FF_INVALID_SETTING_TYPE &&
                settingType < FF_TOTAL_SETTING_TYPES);
    }


    ////////////////////////////////////////////////////////////////////////////
    /// @fn valid (FF_DataType_t dataType)
    ///
    /// Test that a value is valid for a variable of type ::FF_DataType_t.
    ///
    /// @param[in]  dataType
    ///             the value to be tested
    ///
    /// @retval     true
    ///             if the value of the @p dataType parameter is valid
    ///             for a variable of type ::FF_DataType_t
    ///
    /// @retval     false
    ///             otherwise
    ///
    /// @remark     This is an overloaded function that differs from other
    ///             valid() functions in the argument(s) it accepts.
    ///
    /// @see        ::FF_DataType_t
    ///
    /// @ingroup    validation_functions
    ///
    inline bool valid (FF_DataType_t dataType)
    {
        return (dataType > FF_INVALID_DATA_TYPE &&
                dataType < FF_TOTAL_DATA_TYPES);
    }


    ////////////////////////////////////////////////////////////////////////////
    /// @fn valid (FF_ControlCommand_t controlCommand)
    ///
    /// Test that a value is valid for a variable of type
    /// ::FF_ControlCommand_t.
    ///
    /// @param[in]  controlCommand
    ///             the value to be tested
    ///
    /// @retval     true
    ///             if the value of the @p controlCommand parameter is valid
    ///             for a variable of type ::FF_ControlCommand_t
    ///
    /// @retval     false
    ///             otherwise
    ///
    /// @remark     This is an overloaded function that differs from other
    ///             valid() functions in the argument(s) it accepts.
    ///
    /// @see        ::FF_ControlCommand_t
    ///
    /// @ingroup    validation_functions
    ///
    inline bool valid (FF_ControlCommand_t controlCommand)
    {
        return (controlCommand > FF_INVALID_CONTROL_COMMAND &&
                controlCommand < FF_TOTAL_CONTROL_COMMANDS);
    }


    ////////////////////////////////////////////////////////////////////////////
    /// @fn valid (FF_FrequencyMode_t frequencyMode)
    ///
    /// Test that a value is valid for a variable of type ::FF_FrequencyMode_t.
    ///
    /// @param[in]  frequencyMode
    ///             the value to be tested
    ///
    /// @retval     true
    ///             if the value of the @p frequencyMode parameter is valid
    ///             for a variable of type ::FF_FrequencyMode_t
    ///
    /// @retval     false
    ///             otherwise
    ///
    /// @remark     This is an overloaded function that differs from other
    ///             valid() functions in the argument(s) it accepts.
    ///
    /// @see        ::FF_FrequencyMode_t
    ///
    /// @ingroup    validation_functions
    ///
    inline bool valid (FF_FrequencyMode_t frequencyMode)
    {
        return (frequencyMode > FF_INVALID_FREQUENCY_MODE &&
                frequencyMode < FF_TOTAL_FREQUENCY_MODES);
    }


    ////////////////////////////////////////////////////////////////////////////
    /// @fn valid (FF_AutoRangeSetting_t autoRangeSetting)
    ///
    /// Test that a value is valid for a variable of type
    /// ::FF_AutoRangeSetting_t.
    ///
    /// @param[in]  autoRangeSetting
    ///             the value to be tested
    ///
    /// @retval     true
    ///             if the value of the @p autoRangeSetting parameter is valid
    ///             for a variable of type ::FF_AutoRangeSetting_t
    ///
    /// @retval     false
    ///             otherwise
    ///
    /// @remark     This is an overloaded function that differs from other
    ///             valid() functions in the argument(s) it accepts.
    ///
    /// @see        ::FF_AutoRangeSetting_t
    ///
    /// @ingroup    validation_functions
    ///
    inline bool valid (FF_AutoRangeSetting_t autoRangeSetting)
    {
        return (autoRangeSetting > FF_INVALID_AUTO_RANGE_SETTING &&
                autoRangeSetting < FF_TOTAL_AUTO_RANGE_SETTINGS);
    }


    ////////////////////////////////////////////////////////////////////////////
    /// @fn valid (FF_AutoGainSetting_t autoGainSetting)
    ///
    /// Test that a value is valid for a variable of type
    /// ::FF_AutoGainSetting_t.
    ///
    /// @param[in]  autoGainSetting
    ///             the value to be tested
    ///
    /// @retval     true
    ///             if the value of the @p autoGainSetting parameter is valid
    ///             for a variable of type ::FF_AutoGainSetting_t
    ///
    /// @retval     false
    ///             otherwise
    ///
    /// @remark     This is an overloaded function that differs from other
    ///             valid() functions in the argument(s) it accepts.
    ///
    /// @see        ::FF_AutoGainSetting_t
    ///
    /// @ingroup    validation_functions
    ///
    inline bool valid (FF_AutoGainSetting_t autoGainSetting)
    {
        return (autoGainSetting > FF_INVALID_AUTO_GAIN_SETTING &&
                autoGainSetting < FF_TOTAL_AUTO_GAIN_SETTINGS);
    }


    ////////////////////////////////////////////////////////////////////////////
    /// @fn valid (FF_DepthAlarmType_t depthAlarmType)
    ///
    /// Test that a value is valid for a variable of type
    /// ::FF_DepthAlarmType_t.
    ///
    /// @param[in]  depthAlarmType
    ///             the value to be tested
    ///
    /// @retval     true
    ///             if the value of the @p depthAlarmType parameter is valid
    ///             for a variable of type ::FF_DepthAlarmType_t
    ///
    /// @retval     false
    ///             otherwise
    ///
    /// @remark     This is an overloaded function that differs from other
    ///             valid() functions in the argument(s) it accepts.
    ///
    /// @see        ::FF_DepthAlarmType_t
    ///
    /// @ingroup    validation_functions
    ///
    inline bool valid (FF_DepthAlarmType_t depthAlarmType)
    {
        return (depthAlarmType > FF_INVALID_DEPTH_ALARM_TYPE &&
                depthAlarmType < FF_TOTAL_DEPTH_ALARM_TYPES);
    }


    ////////////////////////////////////////////////////////////////////////////
    /// @fn valid (FF_DepthAlarmState_t depthAlarmState)
    ///
    /// Test that a value is valid for a variable of type
    /// ::FF_DepthAlarmState_t.
    ///
    /// @param[in]  depthAlarmState
    ///             the value to be tested
    ///
    /// @retval     true
    ///             if the value of the @p depthAlarmState parameter is valid
    ///             for a variable of type ::FF_DepthAlarmState_t
    ///
    /// @retval     false
    ///             otherwise
    ///
    /// @remark     This is an overloaded function that differs from other
    ///             valid() functions in the argument(s) it accepts.
    ///
    /// @see        ::FF_DepthAlarmState_t
    ///
    /// @ingroup    validation_functions
    ///
    inline bool valid (FF_DepthAlarmState_t depthAlarmState)
    {
        return (depthAlarmState > FF_INVALID_DEPTH_ALARM_STATE &&
                depthAlarmState < FF_TOTAL_DEPTH_ALARM_STATES);
    }


    ////////////////////////////////////////////////////////////////////////////
    /// @fn valid (FF_FishAlarmSetting_t fishAlarmSetting)
    ///
    /// Test that a value is valid for a variable of type
    /// ::FF_FishAlarmSetting_t.
    ///
    /// @param[in]  fishAlarmSetting
    ///             the value to be tested
    ///
    /// @retval     true
    ///             if the value of the @p fishAlarmSetting parameter is valid
    ///             for a variable of type ::FF_FishAlarmSetting_t
    ///
    /// @retval     false
    ///             otherwise
    ///
    /// @remark     This is an overloaded function that differs from other
    ///             valid() functions in the argument(s) it accepts.
    ///
    /// @see        ::FF_FishAlarmSetting_t
    ///
    /// @ingroup    validation_functions
    ///
    inline bool valid (FF_FishAlarmSetting_t fishAlarmSetting)
    {
        return (fishAlarmSetting > FF_INVALID_FISH_ALARM_SETTING &&
                fishAlarmSetting < FF_TOTAL_FISH_ALARM_SETTINGS);
    }


    ////////////////////////////////////////////////////////////////////////////
    /// @fn valid (FF_ApiStatus_t apiStatus)
    ///
    /// Test that a value is valid for a variable of type ::FF_ApiStatus_t.
    ///
    /// @param[in]  apiStatus
    ///             the value to be tested
    ///
    /// @retval     true
    ///             if the value of the @p apiStatus parameter is valid
    ///             for a variable of type ::FF_ApiStatus_t
    ///
    /// @retval     false
    ///             otherwise
    ///
    /// @remark     This is an overloaded function that differs from other
    ///             valid() functions in the argument(s) it accepts.
    ///
    /// @see        ::FF_ApiStatus_t
    ///
    /// @ingroup    validation_functions
    ///
    inline bool valid (FF_ApiStatus_t apiStatus)
    {
        return (apiStatus > FF_INVALID_API_STATUS &&
                apiStatus < FF_TOTAL_API_STATUSES);
    }
    
}       // namespace STFF

#endif  // defined (STFF_Utility_h_)