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 }

Public Member Functions
	KFormat (const KFormat &other)

	KFormat (const QLocale &locale=QLocale())

	~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, const QString &unit, int precision, KFormat::UnitPrefix prefix, KFormat::BinaryUnitDialect dialect) const

QString	formatValue (double value, const QString &unit, int precision=1, KFormat::UnitPrefix prefix=KFormat::UnitPrefix::AutoAdjust) const

QString	formatValue (double value, KFormat::Unit unit, int precision=1, KFormat::UnitPrefix prefix=KFormat::UnitPrefix::AutoAdjust, KFormat::BinaryUnitDialect dialect=KFormat::DefaultBinaryDialect) const

KFormat &	operator= (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.nosp@m.@kde.nosp@m..org, Michael Pyne mpyne.nosp@m.@kde.nosp@m..org, Albert Astals Cid aacid.nosp@m.@kde.nosp@m..org,

Class for formatting numbers and datetimes.

Since: 5.0

Definition at line 58 of file kformat.h.

Member Typedef Documentation

◆ DurationFormatOptions

QFlags< DurationFormatOption > KFormat::DurationFormatOptions

Stores a combination of DurationFormatOption values.

Definition at line 193 of file kformat.h.

Member Enumeration Documentation

◆ BinarySizeUnits

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

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.

◆ BinaryUnitDialect

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

Definition at line 171 of file kformat.h.

◆ DurationFormatOption

enum KFormat::DurationFormatOption

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.

◆ Unit

enum class 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.

◆ UnitPrefix

enum class 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() [1/2]

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

explicit

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:

QString metric, iec, jedec, small;
metric = formatByteSize(1000, 1, KFormat::MetricBinaryDialect, KFormat::UnitKiloByte);
iec    = formatByteSize(1024, 1, KFormat::IECBinaryDialect, KFormat::UnitKiloByte);
jedec  = formatByteSize(1024, 1, KFormat::JEDECBinaryDialect, KFormat::UnitKiloByte);
small  = formatByteSize(100);
// metric == "1.0 kB", iec == "1.0 KiB", jedec == "1.0 KB", small == "100 B"

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 with format

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:

QString iec, jedec, metric;
// Sets iec to "1.0 KiB/s", jedec to "1.0 KB/s" and metric to "1.0 kB/s"
iec = format.formatValue(1024, QStringLiteral("B/s"), 1, KFormat::UnitPrefix::AutoAdjust, KFormat::IECBinaryDialect);
jedec = format.formatValue(1024, QStringLiteral("B/s"), 1, KFormat::UnitPrefix::AutoAdjust, KFormat::JEDECBinaryDialect);
metric = format.formatValue(1000, QStringLiteral("B/s"), 1, KFormat::UnitPrefix::AutoAdjust, KFormat::MetricBinaryDialect);

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:

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

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:

// sets formatted to "1.0 kbit"

auto formatted = format.formatValue(1000, KFormat::Unit::Bit, 1, KFormat::UnitPrefix::Kilo);

KFormat::Unit::Bit

@ Bit

"bit"

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=()

KFormat & KFormat::operator= ( const KFormat & other )

Definition at line 24 of file kformat.cpp.

The documentation for this class was generated from the following files:

KDE's Doxygen guidelines are available online.

Class Picker

Quick Links

About KCoreAddons

KFormat

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

◆ DurationFormatOptions

Member Enumeration Documentation

◆ BinarySizeUnits

◆ BinaryUnitDialect

◆ DurationFormatOption

◆ Unit

◆ UnitPrefix

Constructor & Destructor Documentation

◆ KFormat() [1/2]

◆ KFormat() [2/2]

◆ ~KFormat()

Member Function Documentation

◆ formatByteSize()

◆ formatDecimalDuration()

◆ formatDuration()

◆ formatRelativeDate()

◆ formatRelativeDateTime()

◆ formatSpelloutDuration()

◆ formatValue() [1/3]

◆ formatValue() [2/3]

◆ formatValue() [3/3]

◆ operator=()