KFormat
#include <KFormat>
Public Types | |
enum | BinarySizeUnits { DefaultBinaryUnits = -1 , UnitByte , UnitKiloByte , UnitMegaByte , UnitGigaByte , UnitTeraByte , UnitPetaByte , UnitExaByte , UnitZettaByte , UnitYottaByte , UnitLastUnit = UnitYottaByte } |
enum | BinaryUnitDialect { DefaultBinaryDialect = -1 , IECBinaryDialect , JEDECBinaryDialect , MetricBinaryDialect , LastBinaryDialect = MetricBinaryDialect } |
enum | DurationFormatOption { DefaultDuration = 0x0 , InitialDuration = 0x1 , ShowMilliseconds = 0x2 , HideSeconds = 0x4 , FoldHours = 0x8 } |
typedef QFlags< DurationFormatOption > | DurationFormatOptions |
enum class | Unit { Other , Bit , Byte , Meter , Hertz } |
enum class | UnitPrefix { AutoAdjust = -128 , Yocto = 0 , Zepto , Atto , Femto , Pico , Nano , Micro , Milli , Centi , Deci , Unity , Deca , Hecto , Kilo , Mega , Giga , Tera , Peta , Exa , Zetta , Yotta } |
Detailed Description
KFormat provides support for formatting numbers and datetimes in formats that are not supported by QLocale.
Class for formatting numbers and datetimes.
- Since
- 5.0
Member Typedef Documentation
◆ DurationFormatOptions
Stores a combination of DurationFormatOption values.
Member Enumeration Documentation
◆ BinarySizeUnits
These binary units are used in KDE by the formatByteSize() function.
NOTE: There are several different units standards: 1) SI (i.e. metric), powers-of-10. 2) IEC, powers-of-2, with specific units KiB, MiB, etc. 3) JEDEC, powers-of-2, used for solid state memory sizing which is why you see flash cards labels as e.g. 4GB. These (ab)use the metric units. Although JEDEC only defines KB, MB, GB, if JEDEC is selected all units will be powers-of-2 with metric prefixes for clarity in the event of sizes larger than 1024 GB.
Although 3 different dialects are possible this enum only uses metric names since adding all 3 different names of essentially the same unit would be pointless. Use BinaryUnitDialect to control the exact units returned.
- See also
- BinaryUnitDialect
- formatByteSize
◆ BinaryUnitDialect
This enum chooses what dialect is used for binary units.
Note: Although JEDEC abuses the metric prefixes and can therefore be confusing, it has been used to describe memory sizes for quite some time and programs should therefore use either Default, JEDEC, or IEC 60027-2 for memory sizes.
On the other hand network transmission rates are typically in metric so Default, Metric, or IEC (which is unambiguous) should be chosen.
Normally choosing DefaultBinaryDialect is the best option as that uses the user's selection for units. If the user has not selected a preference, IECBinaryDialect will typically be used.
- See also
- BinarySizeUnits
- formatByteSize
Enumerator | |
---|---|
DefaultBinaryDialect | Used if no specific preference. |
IECBinaryDialect | KiB, MiB, etc. 2^(10*n) |
JEDECBinaryDialect | KB, MB, etc. 2^(10*n) |
MetricBinaryDialect | SI Units, kB, MB, etc. 10^(3*n) |
◆ DurationFormatOption
Format flags for formatDuration()
- See also
- DurationFormatOptions
◆ Unit
|
strong |
These units are used in KDE by the formatValue() function.
- See also
- formatValue
- Since
- 5.49
Enumerator | |
---|---|
Bit | "bit" |
Byte | "B" |
Meter | "m" |
Hertz | "Hz" |
◆ UnitPrefix
|
strong |
These prefixes are used in KDE by the formatValue() function.
IEC prefixes are only defined for integral units of information, e.g. bits and bytes.
- See also
- BinarySizeUnits
- formatValue
- Since
- 5.49
Constructor & Destructor Documentation
◆ KFormat() [1/2]
Constructs a KFormat.
- Parameters
-
locale the locale to use, defaults to the system locale
Definition at line 14 of file kformat.cpp.
◆ KFormat() [2/2]
KFormat::KFormat | ( | const KFormat & | other | ) |
Copy constructor.
Definition at line 19 of file kformat.cpp.
◆ ~KFormat()
KFormat::~KFormat | ( | ) |
Destructor.
Definition at line 30 of file kformat.cpp.
Member Function Documentation
◆ formatByteSize()
QString KFormat::formatByteSize | ( | double | size, |
int | precision = 1, | ||
KFormat::BinaryUnitDialect | dialect = KFormat::DefaultBinaryDialect, | ||
KFormat::BinarySizeUnits | units = KFormat::DefaultBinaryUnits ) const |
Converts size
from bytes to the appropriate string representation using the binary unit dialect dialect
and the specific units units
.
Example:
- Parameters
-
size size in bytes precision number of places after the decimal point to use. KDE uses 1 by default so when in doubt use 1. Whenever KFormat::UnitByte is used (either explicitly or autoselected from KFormat::DefaultBinaryUnits), the fractional part is always omitted. dialect binary unit standard to use. Use DefaultBinaryDialect to use the localized user selection unless you need to use a specific unit type (such as displaying a flash memory size in JEDEC). units specific unit size to use in result. Use DefaultBinaryUnits to automatically select a unit that will return a sanely-sized number.
- Returns
- converted size as a translated string including the units. E.g. "1.23 KiB", "2 GB" (JEDEC), "4.2 kB" (Metric).
- See also
- BinarySizeUnits
- BinaryUnitDialect
Definition at line 34 of file kformat.cpp.
◆ formatDecimalDuration()
QString KFormat::formatDecimalDuration | ( | quint64 | msecs, |
int | decimalPlaces = 2 ) const |
Given a number of milliseconds, converts that to a string containing the localized equivalent to the requested decimal places.
e.g. given formatDuration(60000), returns "1.0 minutes"
- Parameters
-
msecs Time duration in milliseconds decimalPlaces Decimal places to round off to, defaults to 2
- Returns
- converted duration as a string - e.g. "5.5 seconds" "23.0 minutes"
Definition at line 60 of file kformat.cpp.
◆ formatDuration()
QString KFormat::formatDuration | ( | quint64 | msecs, |
KFormat::DurationFormatOptions | options = KFormat::DefaultDuration ) const |
Given a number of milliseconds, converts that to a string containing the localized equivalent, e.g.
1:23:45
- Parameters
-
msecs Time duration in milliseconds options options to use in the duration format
- Returns
- converted duration as a string - e.g. "1:23:45" "1h23m"
Definition at line 55 of file kformat.cpp.
◆ formatRelativeDate()
QString KFormat::formatRelativeDate | ( | const QDate & | date, |
QLocale::FormatType | format ) const |
Returns a string formatted to a relative date style.
If the date
falls within one week before or after the current date then a relative date string will be returned, such as:
- Yesterday
- Today
- Tomorrow
- Last Tuesday
- Next Wednesday
If the date
falls outside this period then the format
is used.
- Parameters
-
date the date to be formatted format the date format to use
- Returns
- the date as a string
Definition at line 70 of file kformat.cpp.
◆ formatRelativeDateTime()
QString KFormat::formatRelativeDateTime | ( | const QDateTime & | dateTime, |
QLocale::FormatType | format ) const |
Returns a string formatted to a relative datetime style.
If the dateTime
falls within one week before or after the current date then a relative date string will be returned, such as:
- Yesterday at 3:00pm
- Today at 3:00pm
- Tomorrow at 3:00pm
- Last Tuesday at 3:00pm
- Next Wednesday at 3:00pm
If the dateTime
falls within one hour of the current time. Then a shorter version is displayed:
- Just a moment ago (for within the same minute)
- 15 minutes ago
If the dateTime
falls outside this period then the date is rendered as:
- Monday, 7 September, 2021 at 7:00 PM : date formatted
format
+ " at " + time formatted withformat
With format
LongFormat, time format used is set to ShortFormat (to omit timezone and seconds).
First character is capitalized.
- Parameters
-
dateTime the date to be formatted format the date format to use
- Returns
- the date as a string
Definition at line 75 of file kformat.cpp.
◆ formatSpelloutDuration()
QString KFormat::formatSpelloutDuration | ( | quint64 | msecs | ) | const |
Given a number of milliseconds, converts that to a spell-out string containing the localized equivalent.
e.g. given formatSpelloutDuration(60001) returns "1 minute" given formatSpelloutDuration(62005) returns "1 minute and 2 seconds" given formatSpelloutDuration(90060000) returns "1 day and 1 hour"
- Parameters
-
msecs Time duration in milliseconds
- Returns
- converted duration as a string. Units not interesting to the user, for example seconds or minutes when the first unit is day, are not returned because they are irrelevant. The same applies for seconds when the first unit is hour.
Definition at line 65 of file kformat.cpp.
◆ formatValue() [1/3]
QString KFormat::formatValue | ( | double | value, |
const QString & | unit, | ||
int | precision, | ||
KFormat::UnitPrefix | prefix, | ||
KFormat::BinaryUnitDialect | dialect ) const |
Converts value
to the appropriate string representation.
Example:
- Parameters
-
value value to be formatted precision number of places after the decimal point to use. 1 is used by default; when in doubt use 1 unit unit to use in result prefix specific prefix to use in result. Use UnitPrefix::AutoAdjust to automatically select an appropriate prefix dialect prefix standard to use. Use DefaultBinaryDialect to use the localized user selection unless you need to use a specific unit type
- Returns
- converted size as a translated string including prefix and unit. E.g. "1.2 kbit", "2.4 kB", "12.3 Mbit/s"
- See also
- UnitPrefix
- Since
- 5.74
Definition at line 50 of file kformat.cpp.
◆ formatValue() [2/3]
QString KFormat::formatValue | ( | double | value, |
const QString & | unit, | ||
int | precision = 1, | ||
KFormat::UnitPrefix | prefix = KFormat::UnitPrefix::AutoAdjust ) const |
Converts value
to the appropriate string representation.
Example:
- Parameters
-
value value to be formatted precision number of places after the decimal point to use. KDE uses 1 by default so when in doubt use 1. unit unit to use in result. prefix specific prefix to use in result. Use UnitPrefix::AutoAdjust to automatically select an appropriate prefix.
- Returns
- converted size as a translated string including prefix and unit. E.g. "1.2 kbit", "2.4 kB", "12.3 Mbit/s"
- See also
- UnitPrefix
- Since
- 5.49
Definition at line 44 of file kformat.cpp.
◆ formatValue() [3/3]
QString KFormat::formatValue | ( | double | value, |
KFormat::Unit | unit, | ||
int | precision = 1, | ||
KFormat::UnitPrefix | prefix = KFormat::UnitPrefix::AutoAdjust, | ||
KFormat::BinaryUnitDialect | dialect = KFormat::DefaultBinaryDialect ) const |
Converts value
to the appropriate string representation.
Example:
- Parameters
-
value value to be formatted precision number of places after the decimal point to use. KDE uses 1 by default so when in doubt use 1. unit unit to use in result. prefix specific prefix to use in result. Use UnitPrefix::AutoAdjust to automatically select an appropriate prefix. dialect prefix standard to use. Use DefaultBinaryDialect to use the localized user selection unless you need to use a specific unit type. Only meaningful for KFormat::Unit::Byte, and ignored for all other units.
- Returns
- converted size as a translated string including prefix and unit. E.g. "1.23 KiB", "2 GB" (JEDEC), "4.2 kB" (Metric), "1.2 kbit".
- See also
- Unit
- UnitPrefix
- BinaryUnitDialect
- Since
- 5.49
Definition at line 39 of file kformat.cpp.
◆ operator=()
Definition at line 24 of file kformat.cpp.
The documentation for this class was generated from the following files:
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Nov 1 2024 18:53:59 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006
KDE's Doxygen guidelines are available online.