KDE 5.0 PyKDE API Reference
  • KDE's Python API
  • Overview
  • PyKDE Home
  • Sitemap
  • Contact Us
 

KFormat Class Reference

from PyKDE5.kcoreaddons import *

Detailed Description

Abstract class:
This class can be used as a base class for new classes, but can not be instantiated directly.

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

Author:
John Layt <jlayt@kde.org>,
Michael Pyne <mpyne@kde.org>, Albert Astals Cid <aacid@kde.org>,

Class for formatting numbers and datetimes.

Since:
5.0


Enumerations

BinarySizeUnits { DefaultBinaryUnits, UnitByte, UnitKiloByte, UnitMegaByte, UnitGigaByte, UnitTeraByte, UnitPetaByte, UnitExaByte, UnitZettaByte, UnitYottaByte, UnitLastUnit }
BinaryUnitDialect { DefaultBinaryDialect, IECBinaryDialect, JEDECBinaryDialect, MetricBinaryDialect, LastBinaryDialect }
DurationFormatOption { DefaultDuration, InitialDuration, ShowMilliseconds, HideSeconds, FoldHours }

Methods

 __init__ (self, QLocale locale=QLocale())
 __init__ (self, KFormat other)
QString formatByteSize (self, float size, int precision=1, KFormat::BinaryUnitDialect dialect=KFormat.DefaultBinaryDialect, KFormat::BinarySizeUnits units=KFormat.DefaultBinaryUnits)
QString formatDecimalDuration (self, long msecs, int decimalPlaces=2)
QString formatDuration (self, long msecs, KFormat::DurationFormatOptions options=KFormat.DefaultDuration)
QString formatRelativeDate (self, QDate date, QLocale::FormatType format)
QString formatRelativeDateTime (self, QDateTime dateTime, QLocale::FormatType format)
QString formatSpelloutDuration (self, long msecs)

Method Documentation

__init__ (  self,
QLocale  locale=QLocale()
)

Constructs a KFormat.

Parameters:
locale  the locale to use, defaults to the system locale

__init__ (  self,
KFormat  other
)

Copy constructor

QString formatByteSize (  self,
float  size,
int  precision=1,
KFormat::BinaryUnitDialect  dialect=KFormat.DefaultBinaryDialect,
KFormat::BinarySizeUnits  units=KFormat.DefaultBinaryUnits
)

Converts size from bytes to the appropriate string representation using the binary unit dialect dialect and the specific units specificUnit.

Example: formatByteSize(1000, unit, KFormat.UnitKiloByte) returns: for KFormat.MetricBinaryDialect, "1.0 kB", for KFormat.IECBinaryDialect, "0.9 KiB", for KFormat.JEDECBinaryDialect, "0.9 KB".

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.
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).
specificUnit  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
See also:
BinaryUnitDialect

QString formatDecimalDuration (  self,
long  msecs,
int  decimalPlaces=2
)

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  Deciaml places to round off to, defaults to 2

Returns:
converted duration as a string - e.g. "5.5 seconds" "23.0 minutes"

QString formatDuration (  self,
long  msecs,
KFormat::DurationFormatOptions  options=KFormat.DefaultDuration
)

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"

QString formatRelativeDate (  self,
QDate  date,
QLocale::FormatType  format
)

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

QString formatRelativeDateTime (  self,
QDateTime  dateTime,
QLocale::FormatType  format
)

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:
dateTime  the date to be formatted
format  the date format to use

Returns:
the date as a string

QString formatSpelloutDuration (  self,
long  msecs
)

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.


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
See also:
formatByteSize

Enumerator:
DefaultBinaryUnits = -1
UnitByte 
UnitKiloByte 
UnitMegaByte 
UnitGigaByte 
UnitTeraByte 
UnitPetaByte 
UnitExaByte 
UnitZettaByte 
UnitYottaByte 
UnitLastUnit = UnitYottaByte

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
See also:
formatByteSize

Enumerator:
DefaultBinaryDialect = -1
IECBinaryDialect 
JEDECBinaryDialect 
MetricBinaryDialect 
LastBinaryDialect = MetricBinaryDialect

DurationFormatOption

Format flags for formatDuration()

Enumerator:
DefaultDuration = 0x0
InitialDuration = 0x1
ShowMilliseconds = 0x2
HideSeconds = 0x4
FoldHours = 0x8

  • Full Index

Modules

  • karchive
  • kcoreaddons
  • kguiaddons
  • kitemmodels
  • kitemviews
  • kplotting
  • kwidgetsaddons
  • solid
  • sonnet
This documentation is maintained by Simon Edwards.
KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V. | Legal