Member Function Documentation

[explicit] KFormat::KFormat(const QLocale &locale = QLocale())

Constructs a KFormat.

locale the locale to use, defaults to the system locale

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"

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 and BinaryUnitDialect.

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"

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"

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

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"

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.

date the date to be formatted

format the date format to use

Returns the date as a string

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.

dateTime the date to be formatted

format the date format to use

Returns the date as a string

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"

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.

[since 5.49] 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");

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"

This function was introduced in 5.49.

See also UnitPrefix.

[since 5.49] 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);

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".

This function was introduced in 5.49.

See also Unit, UnitPrefix, and BinaryUnitDialect.

[since 5.74] 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);

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"

This function was introduced in 5.74.

See also UnitPrefix.