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

source code of kunitconversion/src/unitcategory.h