Qwt User's Guide: QwtDate Class Reference

Qwt User's Guide 6.1.5

Public Types | Static Public Member Functions | List of all members
QwtDate Class Reference

A collection of methods around date/time values. More...

`#include <qwt_date.h>`

## Public Types
enum | Week0Type { FirstThursday, FirstDay }
enum | IntervalType { Millisecond, Second, Minute, Hour, Day, Week, Month, Year }
enum | { JulianDayForEpoch = 2440588 }

## Static Public Member Functions
static QDate | minDate ()
static QDate | maxDate ()
static QDateTime | toDateTime (double value, Qt::TimeSpec=Qt::UTC)
static double | toDouble (const QDateTime &)
static QDateTime | ceil (const QDateTime &, IntervalType)
static QDateTime | floor (const QDateTime &, IntervalType)
static QDate | dateOfWeek0 (int year, Week0Type)
| Date of the first day of the first week for a year. More...
static int | weekNumber (const QDate &, Week0Type)
static int | utcOffset (const QDateTime &)
static QString | toString (const QDateTime &, const QString &format, Week0Type)

## Detailed Description

A collection of methods around date/time values.

Qt offers convenient classes for dealing with date/time values, but Qwt uses coordinate systems that are based on doubles. QwtDate offers methods to translate from QDateTime to double and v.v.

A double is interpreted as the number of milliseconds since 1970-01-01T00:00:00 Universal Coordinated Time - also known as "The Epoch".

While the range of the Julian day in Qt4 is limited to [0, MAX_INT], Qt5 stores it as qint64 offering a huge range of valid dates. As the significance of a double is below this ( assuming a fraction of 52 bits ) the translation is not bijective with rounding errors for dates very far from Epoch. For a resolution of 1 ms those start to happen for dates above the year 144683.

An axis for a date/time interval is expected to be aligned and divided in time/date units like seconds, minutes, ... QwtDate offers several algorithms that are needed to calculate these axes.

See also
  QwtDateScaleEngine, QwtDateScaleDraw, QDate, QTime

## Member Enumeration Documentation

## ◆ anonymous enum

anonymous enum

Enumerator
JulianDayForEpoch | The Julian day of "The Epoch".

## ◆ IntervalType

enum QwtDate::IntervalType

Classification of an time interval

Time intervals needs to be classified to decide how to align and divide it.

Enumerator
Millisecond | The interval is related to milliseconds.
Second | The interval is related to seconds.
Minute | The interval is related to minutes.
Hour | The interval is related to hours.
Day | The interval is related to days.
Week | The interval is related to weeks.
Month | The interval is related to months.
Year | The interval is related to years.

## ◆ Week0Type

enum QwtDate::Week0Type

How to identify the first week of year differs between countries.

Enumerator
FirstThursday | According to ISO 8601 the first week of a year is defined as "the week with the year's first Thursday in it". FirstThursday corresponds to the numbering that is implemented in QDate::weekNumber().
FirstDay | "The week with January 1.1 in it." In the U.S. this definition is more common than FirstThursday.

## Member Function Documentation

## ◆ ceil()

QDateTime QwtDate::ceil | ( | const QDateTime & | dateTime,
|  | IntervalType | intervalType
| ) |  |
| static

Ceil a datetime according the interval type

Parameters

  dateTime | Datetime value
  intervalType | Interval type, how to ceil. F.e. when intervalType = QwtDate::Months, the result will be ceiled to the next beginning of a month

Returns
  Ceiled datetime

See also
  floor()

## ◆ dateOfWeek0()

QDate QwtDate::dateOfWeek0 | ( | int | year,
|  | Week0Type | type
| ) |  |
| static

Date of the first day of the first week for a year.

The first day of a week depends on the current locale ( QLocale::firstDayOfWeek() ).

Parameters

  year | Year
  type | Option how to identify the first week

Returns
  First day of week 0

See also
  QLocale::firstDayOfWeek(), weekNumber()

## ◆ floor()

QDateTime QwtDate::floor | ( | const QDateTime & | dateTime,
|  | IntervalType | intervalType
| ) |  |
| static

Floor a datetime according the interval type

Parameters

  dateTime | Datetime value
  intervalType | Interval type, how to ceil. F.e. when intervalType = QwtDate::Months, the result will be ceiled to the next beginning of a month

Returns
  Floored datetime

See also
  floor()

## ◆ maxDate()

QDate QwtDate::maxDate | ( |  | ) |
| static

Maximum for the supported date range

The range of valid dates depends on how QDate stores the Julian day internally.

- For Qt4 it is "Tue Jun 3 5874898"
- For Qt5 it is "Tue Dec 31 2147483647"

Returns
  maximum of the date range

See also
  minDate()

Note
  The maximum differs between Qt4 and Qt5

## ◆ minDate()

QDate QwtDate::minDate | ( |  | ) |
| static

Minimum for the supported date range

The range of valid dates depends on how QDate stores the Julian day internally.

- For Qt4 it is "Tue Jan 2 -4713"
- For Qt5 it is "Thu Jan 1 -2147483648"

Returns
  minimum of the date range

See also
  maxDate()

## ◆ toDateTime()

QDateTime QwtDate::toDateTime | ( | double | value,
|  | Qt::TimeSpec | timeSpec = `Qt::UTC`
| ) |  |
| static

Translate from double to QDateTime

Parameters

  value | Number of milliseconds since the epoch, 1970-01-01T00:00:00 UTC
  timeSpec | Time specification

Returns
  Datetime value

See also
  toDouble(), QDateTime::setMSecsSinceEpoch()

Note
  The return datetime for Qt::OffsetFromUTC will be Qt::UTC

## ◆ toDouble()

double QwtDate::toDouble | ( | const QDateTime & | dateTime | ) |
| static

Translate from QDateTime to double

Parameters

  dateTime | Datetime value

Returns
  Number of milliseconds since 1970-01-01T00:00:00 UTC has passed.

See also
  toDateTime(), QDateTime::toMSecsSinceEpoch()

Warning
  For values very far below or above 1970-01-01 UTC rounding errors will happen due to the limited significance of a double.

## ◆ toString()

QString QwtDate::toString | ( | const QDateTime & | dateTime,
|  | const QString & | format,
|  | Week0Type | week0Type
| ) |  |
| static

Translate a datetime into a string

Beside the format expressions documented in QDateTime::toString() the following expressions are supported:

- w
  week number: ( 1 - 53 )
- ww
  week number with a leading zero ( 01 - 53 )

As week 1 usually starts in the previous year a special rule is applied for formats, where the year is expected to match the week number - even if the date belongs to the previous year.

Parameters

  dateTime | Datetime value
  format | Format string
  week0Type | Specification of week 0

Returns
  Datetime string

See also
  QDateTime::toString(), weekNumber(), QwtDateScaleDraw

## ◆ utcOffset()

int QwtDate::utcOffset | ( | const QDateTime & | dateTime | ) |
| static

Offset in seconds from Coordinated Universal Time

The offset depends on the time specification of dateTime:

- Qt::UTC 0, dateTime has no offset
- Qt::OffsetFromUTC returns dateTime.utcOffset()
- Qt::LocalTime: number of seconds from the UTC

For Qt::LocalTime the offset depends on the timezone and daylight savings.

Parameters

  dateTime | Datetime value

Returns
  Offset in seconds

## ◆ weekNumber()

int QwtDate::weekNumber | ( | const QDate & | date,
|  | Week0Type | type
| ) |  |
| static

Find the week number of a date

- QwtDate::FirstThursday
  Corresponding to ISO 8601 ( see QDate::weekNumber() ).
- QwtDate::FirstDay
  Number of weeks that have begun since dateOfWeek0().

Parameters

  date | Date
  type | Option how to identify the first week

Returns
  Week number, starting with 1