1/*
2 * SPDX-FileCopyrightText: 2007-2009 Petri Damstén <damu@iki.fi>
3 * SPDX-FileCopyrightText: 2014 John Layt <jlayt@kde.org>
4 *
5 * SPDX-License-Identifier: LGPL-2.0-or-later
6 */
7
8#ifndef KUNITCONVERSION_UNITCATEGORY_H
9#define KUNITCONVERSION_UNITCATEGORY_H
10
11#include "kunitconversion/kunitconversion_export.h"
12#include "unit.h"
13#include "value.h"
14
15#include <QExplicitlySharedDataPointer>
16#include <QObject>
17#include <QString>
18#include <QStringList>
19
20#include <chrono>
21
22class QNetworkReply;
23
24namespace KUnitConversion
25{
26class UnitCategoryPrivate;
27class UpdateJob;
28
29/*!
30 * \class KUnitConversion::UnitCategory
31 * \inmodule KUnitConversion
32 *
33 * \brief Class to define a category of units of measurement.
34 *
35 * This is a class to define a category of units of measurement.
36 *
37 * \sa Converter, Unit, Value
38 */
39class KUNITCONVERSION_EXPORT UnitCategory
40{
41public:
42 /*!
43 * Null constructor
44 **/
45 UnitCategory();
46
47 UnitCategory(const UnitCategory &other);
48
49 ~UnitCategory();
50
51 UnitCategory &operator=(const UnitCategory &other);
52
53 UnitCategory &operator=(UnitCategory &&other);
54
55 /*!
56 * Returns true if this UnitCategory is equal to the \a other UnitCategory.
57 **/
58 bool operator==(const UnitCategory &other) const;
59
60 bool operator!=(const UnitCategory &other) const;
61
62 /*!
63 * Returns true if this UnitCategory is null
64 **/
65 bool isNull() const;
66
67 /*!
68 * Returns category id.
69 **/
70 CategoryId id() const;
71
72 /*!
73 * Returns translated name for the unit category.
74 **/
75 QString name() const;
76
77 /*!
78 * Returns unit category description
79 **/
80 QString description() const;
81
82 /*!
83 * Returns default unit.
84 **/
85 Unit defaultUnit() const;
86
87 /*!
88 * Returns if unit category has a unit.
89 **/
90 bool hasUnit(const QString &unit) const;
91
92 /*!
93 * Returns unit for string.
94 **/
95 Unit unit(const QString &s) const;
96
97 /*!
98 * Returns unit for unit enum.
99 **/
100 Unit unit(UnitId unitId) const;
101
102 /*!
103 * Returns units in this category.
104 **/
105 QList<Unit> units() const;
106
107 /*!
108 * Returns most common units in this category.
109 **/
110 QList<Unit> mostCommonUnits() const;
111
112 /*!
113 * Returns all unit names, short names and unit synonyms in this category.
114 **/
115 QStringList allUnits() const;
116
117 /*!
118 * Convert value to another unit selected by string.
119 *
120 * \a value value to convert
121 *
122 * \a toUnit unit to convert to. If empty default unit is used.
123 *
124 * Returns converted value
125 **/
126 Value convert(const Value &value, const QString &toUnit = QString()) const;
127
128 /*!
129 * \overload UnitCategory::convert()
130 *
131 * Convert value to another unit selected by enum.
132 *
133 * \a value value to convert
134 *
135 * \a toUnit unit to convert to.
136 *
137 * Returns converted value
138 **/
139 Value convert(const Value &value, UnitId toUnit) const;
140
141 /*!
142 * \overload UnitCategory::convert()
143 *
144 * Convert value to another unit.
145 *
146 * \a value value to convert
147 *
148 * \a toUnit unit to be used for conversion
149 *
150 * Returns converted value
151 **/
152 Value convert(const Value &value, const Unit &toUnit) const;
153
154 /*!
155 * Returns true if category has conversion table that needs to be updated via online access, otherwise false
156 * \sa syncConversionTable()
157 */
158 bool hasOnlineConversionTable() const;
159
160 /*!
161 * Request an update of the online conversion table when it is older than \a updateSkipPeriod.
162 *
163 * Returned jobs are automatically deleted, ie. it is safe to ignore the return value if you
164 * do not care about being notified about the completion (or failure) of the update process.
165 * Calling this method while another update is already in progress will not trigger another update
166 * but instead allows you to watch the already ongoing update.
167 *
168 * Performing conversions before the update has completed will return results based on the old
169 * conversion table, if available.
170 *
171 * \note This method must be called from the main thread!
172 *
173 * Returns an UpdateJob if an update is necessary or already running, nullptr otherwise.
174 *
175 * \sa UpdateJob
176 * \since 6.0
177 */
178 UpdateJob *syncConversionTable(std::chrono::seconds updateSkipPeriod = std::chrono::hours(24));
179
180private:
181 friend class Unit;
182 friend class UnitCategoryPrivate;
183
184 KUNITCONVERSION_NO_EXPORT explicit UnitCategory(UnitCategoryPrivate *dd);
185
186protected:
187 QExplicitlySharedDataPointer<UnitCategoryPrivate> d;
188};
189
190/*!
191 * \class KUnitConversion::UpdateJob
192 * \inmodule KUnitConversion
193 * \inheaderfile KUnitConversion/UnitCategory
194 *
195 * \brief Dynamic conversion data update job.
196 *
197 * Created via the factory methods in KUnitConversion::Updater, useful for
198 * getting notified about an update having completed.
199 * Update jobs are automatically deleted on completion, but it is also save to delete
200 * instances manually.
201 *
202 * \sa UnitCategory
203 * \since 6.0
204 */
205class KUNITCONVERSION_EXPORT UpdateJob : public QObject
206{
207 Q_OBJECT
208public:
209 ~UpdateJob();
210
211Q_SIGNALS:
212 /*! */
213 void finished();
214
215private:
216 friend class UnitCategoryPrivate;
217 explicit UpdateJob(QNetworkReply *dd);
218 QNetworkReply *d;
219};
220
221} // KUnitConversion namespace
222
223Q_DECLARE_TYPEINFO(KUnitConversion::UnitCategory, Q_RELOCATABLE_TYPE);
224
225#endif
226

source code of kunitconversion/src/unitcategory.h