KFormat

KFormat Class Referencefinal

#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< DurationFormatOptionDurationFormatOptions
 
enum  Unit {
  Other, Unit::Bit, Unit::Byte, Unit::Meter,
  Unit::Hertz
}
 
enum  UnitPrefix {
  UnitPrefix::AutoAdjust = -128, UnitPrefix::Yocto = 0, UnitPrefix::Zepto, UnitPrefix::Atto,
  UnitPrefix::Femto, UnitPrefix::Pico, UnitPrefix::Nano, UnitPrefix::Micro,
  UnitPrefix::Milli, UnitPrefix::Centi, UnitPrefix::Deci, UnitPrefix::Unity,
  UnitPrefix::Deca, UnitPrefix::Hecto, UnitPrefix::Kilo, UnitPrefix::Mega,
  UnitPrefix::Giga, UnitPrefix::Tera, UnitPrefix::Peta, UnitPrefix::Exa,
  UnitPrefix::Zetta, UnitPrefix::Yotta
}
 

Public Member Functions

 KFormat (const QLocale &locale=QLocale())
 
 KFormat (const KFormat &other)
 
 ~KFormat ()
 
QString formatByteSize (double size, int precision=1, KFormat::BinaryUnitDialect dialect=KFormat::DefaultBinaryDialect, KFormat::BinarySizeUnits units=KFormat::DefaultBinaryUnits) const
 
QString formatDecimalDuration (quint64 msecs, int decimalPlaces=2) const
 
QString formatDuration (quint64 msecs, KFormat::DurationFormatOptions options=KFormat::DefaultDuration) const
 
QString formatRelativeDate (const QDate &date, QLocale::FormatType format) const
 
QString formatRelativeDateTime (const QDateTime &dateTime, QLocale::FormatType format) const
 
QString formatSpelloutDuration (quint64 msecs) const
 
QString formatValue (double value, KFormat::Unit unit, int precision=1, KFormat::UnitPrefix prefix=KFormat::UnitPrefix::AutoAdjust, KFormat::BinaryUnitDialect dialect=KFormat::DefaultBinaryDialect) const
 
QString formatValue (double value, const QString &unit, int precision=1, KFormat::UnitPrefix prefix=KFormat::UnitPrefix::AutoAdjust) const
 
KFormatoperator= (const KFormat &other)
 

Detailed Description

KFormat provides support for formatting numbers and datetimes in formats that are not supported by QLocale.

Author
John Layt jlayt[email protected]@kde[email protected].org, Michael Pyne mpyne[email protected]@kde[email protected].org, Albert Astals Cid aacid[email protected]@kde[email protected].org,

Class for formatting numbers and datetimes.

Since
5.0

Definition at line 58 of file kformat.h.

Member Typedef Documentation

Stores a combination of DurationFormatOption values.

Definition at line 193 of file kformat.h.

Member Enumeration Documentation

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
Enumerator
DefaultBinaryUnits 

Auto-choose a unit such that the result is in the range [0, 1000 or 1024)

UnitByte 

B 1 byte.

UnitKiloByte 

KiB/KB/kB 1024/1000 bytes.

UnitMegaByte 

MiB/MB/MB 2^20/10^06 bytes.

UnitGigaByte 

GiB/GB/GB 2^30/10^09 bytes.

UnitTeraByte 

TiB/TB/TB 2^40/10^12 bytes.

UnitPetaByte 

PiB/PB/PB 2^50/10^15 bytes.

UnitExaByte 

EiB/EB/EB 2^60/10^18 bytes.

UnitZettaByte 

ZiB/ZB/ZB 2^70/10^21 bytes.

UnitYottaByte 

YiB/YB/YB 2^80/10^24 bytes.

Definition at line 84 of file kformat.h.

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)

Definition at line 171 of file kformat.h.

Format flags for formatDuration()

See also
DurationFormatOptions
Enumerator
DefaultDuration 

Default formatting in localized 1:23:45 format.

InitialDuration 

Default formatting in localized 1h23m45s format.

ShowMilliseconds 

Include milliseconds in format, e.g. 1:23:45.678.

HideSeconds 

Hide the seconds, e.g. 1:23 or 1h23m, overrides ShowMilliseconds.

FoldHours 

Fold the hours into the minutes, e.g. 83:45 or 83m45s, overrides HideSeconds.

Definition at line 183 of file kformat.h.

enum KFormat::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"

Definition at line 107 of file kformat.h.

enum KFormat::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
Enumerator
AutoAdjust 

Auto-choose a unit such that the result is in the range [0, 1000 or 1024)

Yocto 

–/-/y 10^-24

Zepto 

–/-/z 10^-21

Atto 

–/-/a 10^-18

Femto 

–/-/f 10^-15

Pico 

–/-/p 10^-12

Nano 

–/-/n 10^-9

Micro 

–/-/ยต 10^-6

Milli 

–/-/m 10^-3

Centi 

–/-/c 0.01

Deci 

–/-/d 0.1

Unity 

"" 1

Deca 

–/-/da 10

Hecto 

–/-/h 100

Kilo 

Ki/K/k 1024/1000.

Mega 

Mi/M/M 2^20/10^06.

Giga 

Gi/G/G 2^30/10^09.

Tera 

Ti/T/T 2^40/10^12.

Peta 

Pi/P/P 2^50/10^15.

Exa 

Ei/E/E 2^60/10^18.

Zetta 

Zi/Z/Z 2^70/10^21.

Yotta 

Yi/Y/Y 2^80/10^24.

Definition at line 126 of file kformat.h.

Constructor & Destructor Documentation

KFormat::KFormat ( const QLocale locale = QLocale())
explicit

Constructs a KFormat.

Parameters
localethe locale to use, defaults to the system locale

Definition at line 14 of file kformat.cpp.

KFormat::KFormat ( const KFormat other)

Copy constructor.

Definition at line 19 of file kformat.cpp.

KFormat::~KFormat ( )

Destructor.

Definition at line 30 of file kformat.cpp.

Member Function Documentation

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:

QString metric, iec, jedec, small;
small = formatByteSize(100);
// metric == "1.0 kB", iec == "1.0 KiB", jedec == "1.0 KB", small == "100 B"
Parameters
sizesize in bytes
precisionnumber 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.
dialectbinary 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).
unitsspecific 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.

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
msecsTime duration in milliseconds
decimalPlacesDecimal 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 65 of file kformat.cpp.

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
msecsTime duration in milliseconds
optionsoptions to use in the duration format
Returns
converted duration as a string - e.g. "1:23:45" "1h23m"

Definition at line 59 of file kformat.cpp.

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
datethe date to be formatted
formatthe date format to use
Returns
the date as a string

Definition at line 76 of file kformat.cpp.

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, 3:00pm
  • Today, 3:00pm
  • Tomorrow, 3:00pm
  • Last Tuesday, 3:00pm
  • Next Wednesday, 3:00pm

If the dateTime falls outside this period then the format is used.

Parameters
dateTimethe date to be formatted
formatthe date format to use
Returns
the date as a string

Definition at line 82 of file kformat.cpp.

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
msecsTime 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 71 of file kformat.cpp.

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:

// sets formatted to "1.0 kbit"
auto formatted = format.formatValue(1000, KFormat::Unit::Bit, 1, KFormat::UnitPrefix::Kilo);
Parameters
valuevalue to be formatted
precisionnumber of places after the decimal point to use. KDE uses 1 by default so when in doubt use 1.
unitunit to use in result.
prefixspecific prefix to use in result. Use UnitPrefix::AutoAdjust to automatically select an appropriate prefix.
dialectprefix 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 42 of file kformat.cpp.

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:

QString bits, slow, fast;
// sets bits to "1.0 kbit", slow to "1.0 kbit/s" and fast to "12.3 Mbit/s".
bits = format.formatValue(1000, QStringLiteral("bit"), 1, KFormat::UnitPrefix::Kilo);
slow = format.formatValue(1000, QStringLiteral("bit/s");
fast = format.formatValue(12.3e6, QStringLiteral("bit/s");
Parameters
valuevalue to be formatted
precisionnumber of places after the decimal point to use. KDE uses 1 by default so when in doubt use 1.
unitunit to use in result.
prefixspecific 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 51 of file kformat.cpp.


The documentation for this class was generated from the following files:
This file is part of the KDE documentation.
Documentation copyright © 1996-2020 The KDE developers.
Generated on Thu Jul 9 2020 23:01:14 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.