Changeset View
Changeset View
Standalone View
Standalone View
src/lib/util/kformat.h
Show First 20 Lines • Show All 105 Lines • ▼ Show 20 Line(s) | 96 | enum BinarySizeUnits { | |||
---|---|---|---|---|---|
106 | UnitPetaByte, ///< PiB/PB/PB 2^50/10^15 bytes. | 106 | UnitPetaByte, ///< PiB/PB/PB 2^50/10^15 bytes. | ||
107 | UnitExaByte, ///< EiB/EB/EB 2^60/10^18 bytes. | 107 | UnitExaByte, ///< EiB/EB/EB 2^60/10^18 bytes. | ||
108 | UnitZettaByte, ///< ZiB/ZB/ZB 2^70/10^21 bytes. | 108 | UnitZettaByte, ///< ZiB/ZB/ZB 2^70/10^21 bytes. | ||
109 | UnitYottaByte, ///< YiB/YB/YB 2^80/10^24 bytes. | 109 | UnitYottaByte, ///< YiB/YB/YB 2^80/10^24 bytes. | ||
110 | UnitLastUnit = UnitYottaByte | 110 | UnitLastUnit = UnitYottaByte | ||
111 | }; | 111 | }; | ||
112 | 112 | | |||
113 | /** | 113 | /** | ||
114 | * These units are used in KDE by the formatValue() function. | ||||
115 | * | ||||
116 | * @see formatValue | ||||
117 | * @since 5.48 | ||||
kossebau: Please add missing "@since 5.48"
(as last item, following https://community.kde. | |||||
118 | */ | ||||
119 | enum class Unit { | ||||
120 | Other, | ||||
121 | Bit, ///< "bit" | ||||
122 | Byte, ///< "B" | ||||
123 | Meter, ///< "m" | ||||
124 | Hertz, ///< "Hz" | ||||
125 | }; | ||||
126 | | ||||
127 | /** | ||||
128 | * These prefixes are used in KDE by the formatValue() | ||||
129 | * function. | ||||
130 | * | ||||
131 | * IEC prefixes are only defined for integral units of information, e.g. | ||||
132 | * bits and bytes. | ||||
133 | * | ||||
134 | * @see BinarySizeUnits | ||||
kossebau: @since 5.48 | |||||
135 | * @see formatValue | ||||
136 | * @since 5.48 | ||||
137 | */ | ||||
138 | enum class UnitPrefix { | ||||
139 | /// Auto-choose a unit such that the result is in the range [0, 1000 or 1024) | ||||
140 | AutoAdjust = -128, | ||||
141 | | ||||
142 | Yocto = 0, ///< --/-/y 10^-24 | ||||
143 | Zepto, ///< --/-/z 10^-21 | ||||
144 | Atto, ///< --/-/a 10^-18 | ||||
145 | Femto, ///< --/-/f 10^-15 | ||||
146 | Pico, ///< --/-/p 10^-12 | ||||
147 | Nano, ///< --/-/n 10^-9 | ||||
148 | Micro, ///< --/-/µ 10^-6 | ||||
149 | Mili, ///< --/-/m 10^-3 | ||||
150 | Centi, ///< --/-/c 0.01 | ||||
151 | Deci, ///< --/-/d 0.1 | ||||
152 | Unity, ///< "" 1 | ||||
153 | Deca, ///< --/-/da 10 | ||||
154 | Hecto, ///< --/-/h 100 | ||||
155 | Kilo, ///< Ki/K/k 1024/1000 | ||||
156 | Mega, ///< Mi/M/M 2^20/10^06 | ||||
157 | Giga, ///< Gi/G/G 2^30/10^09 | ||||
158 | Tera, ///< Ti/T/T 2^40/10^12 | ||||
159 | Peta, ///< Pi/P/P 2^50/10^15 | ||||
160 | Exa, ///< Ei/E/E 2^60/10^18 | ||||
161 | Zetta, ///< Zi/Z/Z 2^70/10^21 | ||||
162 | Yotta, ///< Yi/Y/Y 2^80/10^24 | ||||
163 | }; | ||||
164 | | ||||
165 | /** | ||||
114 | * This enum chooses what dialect is used for binary units. | 166 | * This enum chooses what dialect is used for binary units. | ||
115 | * | 167 | * | ||
116 | * Note: Although JEDEC abuses the metric prefixes and can therefore be | 168 | * Note: Although JEDEC abuses the metric prefixes and can therefore be | ||
117 | * confusing, it has been used to describe *memory* sizes for quite some time | 169 | * confusing, it has been used to describe *memory* sizes for quite some time | ||
118 | * and programs should therefore use either Default, JEDEC, or IEC 60027-2 | 170 | * and programs should therefore use either Default, JEDEC, or IEC 60027-2 | ||
119 | * for memory sizes. | 171 | * for memory sizes. | ||
120 | * | 172 | * | ||
121 | * On the other hand network transmission rates are typically in metric so | 173 | * On the other hand network transmission rates are typically in metric so | ||
▲ Show 20 Lines • Show All 161 Lines • ▼ Show 20 Line(s) | |||||
283 | * @param dateTime the date to be formatted | 335 | * @param dateTime the date to be formatted | ||
284 | * @param format the date format to use | 336 | * @param format the date format to use | ||
285 | * | 337 | * | ||
286 | * @return the date as a string | 338 | * @return the date as a string | ||
287 | */ | 339 | */ | ||
288 | QString formatRelativeDateTime(const QDateTime &dateTime, | 340 | QString formatRelativeDateTime(const QDateTime &dateTime, | ||
289 | QLocale::FormatType format) const; | 341 | QLocale::FormatType format) const; | ||
290 | 342 | | |||
343 | /** | ||||
344 | * Converts @p value to the appropriate string representation | ||||
345 | * | ||||
346 | * Example: | ||||
347 | * @code | ||||
Please wrap example code with tags for nice highlighting, and for that adapt also string to be real code, e.g. like this: * @code * // sets value to "1.0 kbit" * auto value = format.formatValue(1000, KFormat::Unit::Bit, 1, KFormat::UnitPrefix::Kilo); * @endcode kossebau: Please wrap example code with tags for nice highlighting, and for that adapt also string to be… | |||||
348 | * // sets formatted to "1.0 kbit" | ||||
349 | * auto formatted = format.formatValue(1000, KFormat::Unit::Bit, 1, KFormat::UnitPrefix::Kilo); | ||||
350 | * @endcode | ||||
351 | * | ||||
352 | * @param value value to be formatted | ||||
353 | * @param precision number of places after the decimal point to use. KDE uses | ||||
354 | * 1 by default so when in doubt use 1. | ||||
355 | * @param unit unit to use in result. | ||||
356 | * @param prefix specific prefix to use in result. Use UnitPrefix::AutoAdjust | ||||
357 | * to automatically select an appropriate prefix. | ||||
358 | * @param dialect prefix standard to use. Use DefaultBinaryDialect to | ||||
359 | * use the localized user selection unless you need to use a specific | ||||
360 | * unit type. Only meaningful for KFormat::Unit::Byte, and ignored for | ||||
361 | * all other units. | ||||
362 | * @return converted size as a translated string including prefix and unit. | ||||
363 | * E.g. "1.23 KiB", "2 GB" (JEDEC), "4.2 kB" (Metric), "1.2 kbit". | ||||
364 | * @see Unit | ||||
kossebau: @since 5.48 | |||||
365 | * @see UnitPrefix | ||||
366 | * @see BinaryUnitDialect | ||||
367 | * @since 5.48 | ||||
368 | */ | ||||
369 | QString formatValue(double value, | ||||
370 | KFormat::Unit unit, | ||||
371 | int precision = 1, | ||||
372 | KFormat::UnitPrefix prefix = KFormat::UnitPrefix::AutoAdjust, | ||||
373 | KFormat::BinaryUnitDialect dialect = KFormat::DefaultBinaryDialect) const; | ||||
374 | | ||||
375 | /** | ||||
376 | * Converts @p value to the appropriate string representation | ||||
377 | * | ||||
kossebau: same code/endcode treatment please | |||||
378 | * Example: | ||||
379 | * @code | ||||
380 | * QString bits, slow, fast; | ||||
381 | * // sets bits to "1.0 kbit", slow to "1.0 kbit/s" and fast to "12.3 Mbit/s". | ||||
382 | * bits = format.formatValue(1000, QStringLiteral("bit"), 1, KFormat::UnitPrefix::Kilo); | ||||
383 | * slow = format.formatValue(1000, QStringLiteral("bit/s"); | ||||
384 | * fast = format.formatValue(12.3e6, QStringLiteral("bit/s"); | ||||
385 | * @endcode | ||||
386 | * | ||||
387 | * @param value value to be formatted | ||||
388 | * @param precision number of places after the decimal point to use. KDE uses | ||||
kossebau: @since 5.48 | |||||
389 | * 1 by default so when in doubt use 1. | ||||
390 | * @param unit unit to use in result. | ||||
pass by const reference -> const QString& unit That the unitstring argument is modified internally in the private method is a current implementation detail which should not leak into the public API kossebau: pass by const reference -> const QString& unit
That the unitstring argument is modified… | |||||
391 | * @param prefix specific prefix to use in result. Use UnitPrefix::AutoAdjust | ||||
392 | * to automatically select an appropriate prefix. | ||||
393 | * @return converted size as a translated string including prefix and unit. | ||||
394 | * E.g. "1.2 kbit", "2.4 kB", "12.3 Mbit/s" | ||||
395 | * @see UnitPrefix | ||||
396 | * @since 5.48 | ||||
397 | */ | ||||
398 | QString formatValue(double value, | ||||
399 | const QString& unit, | ||||
400 | int precision = 1, | ||||
401 | KFormat::UnitPrefix prefix = KFormat::UnitPrefix::AutoAdjust) const; | ||||
402 | | ||||
291 | private: | 403 | private: | ||
292 | QSharedDataPointer<KFormatPrivate> d; | 404 | QSharedDataPointer<KFormatPrivate> d; | ||
293 | }; | 405 | }; | ||
294 | 406 | | |||
295 | #endif // KFORMAT_H | 407 | #endif // KFORMAT_H |
Please add missing "@since 5.48"
(as last item, following https://community.kde.org/Frameworks/Frameworks_Documentation_Policy#Document_Public_and_Protected_Members)