/*  This file is part of the KDE libraries
    Copyright (C) 2021 Ivailo Monev <xakepa10@gmail.com>

    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Library General Public
    License version 2, as published by the Free Software Foundation.

    This 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
    Library General Public License for more details.

    You should have received a copy of the GNU Library General Public License
    along with this library; see the file COPYING.LIB.  If not, write to
    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
    Boston, MA 02110-1301, USA.
*/

#ifndef KUNITCONVERSION_H
#define KUNITCONVERSION_H

#include <kdecore_export.h>

#include <QString>

class KUnitConversionPrivate;

/*!
    Class for temperature, velocity, pressure and length conversion

    Converting from one unit to other is pretty simple:
    @code
    KUnitConversion temp(12.3, "°C");
    qDebug() << temp.convertTo(KUnitConversion::Fahrenheit);
    @endcode

    Unlike the original KUnitConversion classes @p KUnitConversion is thread-safe and much
    faster, albeit does not provide as many unit conversion options (that may change). Being
    unable to copy the classes is design choice - storing the unit (string or enum
    representation) however is absolutely possible and you can in fact optimize it for use
    case if you have to store both the number and the unit by using struct:

    @code
    struct TempUnit {
        double number;
        KUnitConversion::UnitType unit;
    };
    @endcode

    vs:
    @code
    struct TempUnit {
        double number;
        QString unit;
    };
    @endcode

    @since 4.20
*/
class KDECORE_EXPORT KUnitConversion
{
public:
    enum UnitType {
        InvalidUnit = 0,
        Celsius = 1,
        Fahrenheit = 2,
        Kelvin = 3,
        KilometerPerHour = 4,
        Knot = 5,
        MeterPerSecond = 6,
        MilePerHour = 7,
        Hectopascal = 8,
        InchesOfMercury = 9,
        Kilopascal = 10,
        Millibar = 11,
        Kilometer = 12,
        Foot = 13,
        Mile = 14
    };

    enum CategoryType {
        InvalidCategory = 0,
        Temperature = 1,
        Velocity = 2,
        Pressure = 3,
        Length = 4
    };

    /*!
        @brief Constructs convertor
        @param number value of the unit
        @param unit unit enum, one of @p KUnitConversion::UnitType
    */
    KUnitConversion(const double number, const KUnitConversion::UnitType unit);
    /*!
        @brief Constructs convertor
        @param number value of the unit
        @param unit string representation of the unit, e.g. "°C", "C", "Celsius", "°F", "F",
        "Fahrenheit", "Kelvin" or "K"
    */
    KUnitConversion(const double number, const QString &unit);
    ~KUnitConversion();

    /*!
        @return Same number as the value passed to the constructor
    */
    double number() const;
    /*!
        @return Short string representing the unit passed to the constructor, e.g. "Unknown" (for
        @p UnitType::InvalidUnit), "°F" or "K"
    */
    QString unit() const;
    /*!
        @return Enum representing the unit passed to the constructor, e.g. @p UnitType::InvalidUnit,
        @p UnitType::Fahrenheit or @p UnitType::Kelvin
    */
    KUnitConversion::UnitType unitEnum() const;
    /*!
        @return Enum representing the unit category, e.g. @p CategoryType::InvalidCategory,
        @p CategoryType::Temperature or @p CategoryType::Velocity
    */
    KUnitConversion::CategoryType categoryEnum() const;
    /*!
        @return Combination of the number and short unit as string, e.g. "12 °C", "123 °F" or
        "123 K"
    */
    QString toString() const;
    /*!
        @return Number converted to different unit
    */
    double convertTo(const KUnitConversion::UnitType unit) const;

    /*!
        @return Translated unit description, e.g. "Unknown" (for @p UnitType::InvalidUnit),
        "Fahrenheitia (°F)" or "Келвин (K)"
    */
    static QString unitName(const KUnitConversion::UnitType unit);
    /*!
        @return Translated unit category description, e.g. "Температура"
    */
    static QString categoryName(const KUnitConversion::CategoryType category);

    /*!
        @return List of all unit categories except @p CategoryType::InvalidCategory
    */
    static QList<KUnitConversion::CategoryType> categories();
    /*!
        @return List of units for category specified by @p category
    */
    static QList<KUnitConversion::UnitType> categoryUnits(const KUnitConversion::CategoryType category);

    /*!
        @return Rounded number up to number of decimal digits specified by @p digits
    */
    static double round(const double number, const uint digits);

private:
    Q_DISABLE_COPY(KUnitConversion);
    KUnitConversionPrivate * const d;
};

#endif // KUNITCONVERSION_H
