1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
|
// Copyright (C) 2021 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\qmltype Date
\inqmlmodule QtQml
\brief Provides date functions.
The QML Date object extends the
\l{ECMAScript Specification of Date}{JS Date object} with
locale aware functions.
Functions that accept a \c format argument take either Locale.LongFormat,
Locale.ShortFormat, Locale.NarrowFormat enumeration values,
or a string specifying the format.
The form of the supported format strings is as described in the
documentation of \l QDate::toString(), \l QTime::toString() and \l
QDateTime::toString().
If the date is invalid, an empty string is returned.
\section1 Format Enumeration Values
Use the enumeration values when you want a format that matches the locale
preferences.
\table
\row \li Locale.LongFormat \li Longer format
\row \li Locale.ShortFormat \li Shorter format
\row \li Locale.NarrowFormat \li In this context same as Locale.ShortFormat
\endtable
The format that the enumerations represent will depend on your locale, but also
the method that the enumeration is used for.
For example, for the \c en_US locale, these format strings are used:
\table
\header \li Function \li Locale Enum \li Format String
\row \li fromLocaleDateString, toLocaleDateString \li Locale.LongFormat \li \c{dddd, MMMM d, yyyy}
\row \li fromLocaleDateString, toLocaleDateString \li Locale.ShortFormat \li \c{M/d/yy}
\row \li fromLocaleTimeString, toLocaleTimeString \li Locale.LongFormat \li \c{h:mm:ss AP t}
\row \li fromLocaleTimeString, toLocaleTimeString \li Locale.ShortFormat \li \c{h:mm AP}
\row \li fromLocaleString, toLocaleString \li Locale.LongFormat \li \c{dddd, MMMM d, yyyy h:mm:ss AP t}
\row \li fromLocaleString, toLocaleString \li Locale.ShortFormat \li \c{M/d/yy h:mm AP}
\endtable
\section1 Further Notes
Using the locale-aware functions to perform date or time formatting can
result in incorrectly formatted times, due to an inconsistency in specification
between Qt and JS. ECMA-262 specifies that historical dates should be intrepreted
by projecting the current rules for daylight-saving onto past years, while Qt uses
historical data (where available) to determine whether daylight-saving was in
effect for a given date. Therefore, constructing a Date value in JS and converting
it to a string using the locale-aware functions can yield a result incorrect by one
hour, if DST is currently in effect, while it was not for the time specified, or
vice versa.
There are different date formats with different understandings of negative years. Common
human language does not have a year 0. The year after 1BC is 1AD. This understanding is
reflected when printing or parsing dates in one of the formats not standardized by ECMAScript.
That is: toString(), toLocaleString(), toUTCString() and friends. ECMAScript does standardize
one format: ISO 8601. This is what you get when you call toISOString(). This format does include
a year 0, which is 1BC in other formats. Thus you get different years when printing negative
dates with toISOString() and toString().
When setting the year using the Date constructor or set(UTC)FullYear(), the convention set by
ISO 8601 is used and 0 is a valid year. This means negative years set with the constructor or
set(UTC)FullYear() are zero-based and thus offset by one year from what is printed with
toString() and friends. Parsing the output of any of the to*String() methods will yield the same
date value you printed from. Date.parse() will recognize the different formats and their
convention on the existence of year 0.
Note that all this is different from what you get in other JavaScript implementations which
usually treat year 0 as valid in all string representations. As the date formats are
"implementation-dependent" in the ECMAScript standard, this is still valid, though.
\sa {QtQml::Locale}{Locale}
*/
/*!
\qmlmethod string Date::toLocaleString(locale, format)
Converts the Date to a string containing the date and time
suitable for the specified \a locale
in the specified \a format.
If \a format is not specified, \l {QtQml::Locale}{Locale.LongFormat} will
be used.
If \a locale is not specified, the default locale will be used.
The following example shows the current date and time formatted
for the German locale:
\code
import QtQuick 2.0
Text {
text: "The date is: " + new Date().toLocaleString(Qt.locale("de_DE"))
}
\endcode
*/
/*!
\qmlmethod string Date::toLocaleDateString(locale, format)
Converts the Date to a string containing the date suitable for the specified \a locale
in the specified \a format.
If \a format is not specified, \l {QtQml::Locale}{Locale.LongFormat} will
be used.
If \a locale is not specified, the default locale will be used.
The following example shows the current date formatted
for the German locale:
\code
import QtQuick 2.0
Text {
text: "The date is: " + new Date().toLocaleDateString(Qt.locale("de_DE"))
}
\endcode
*/
/*!
\qmlmethod string Date::toLocaleTimeString(locale, format)
Converts the Date to a string containing the time suitable for the specified \a locale
in the specified \a format.
If \a format is not specified, \l {QtQml::Locale}{Locale.LongFormat} will
be used.
If \a locale is not specified, the default locale will be used.
The following example shows the current time formatted
for the German locale:
\code
import QtQuick 2.0
Text {
text: "The date is: " + new Date().toLocaleTimeString(Qt.locale("de_DE"))
}
\endcode
*/
/*!
\qmlmethod string Date::fromLocaleString(locale, dateTimeString, format)
Converts the datetime string \a dateTimeString to a \l {QtQml::Date}{Date}
object using \a locale and \a format.
If \a format is not specified, \l {QtQml::Locale}{Locale.LongFormat} will
be used.
If \a locale is not specified, the default locale will be used.
The following example shows a datetime being parsed from a datetime string
in a certain format using the default locale:
\code
import QtQml 2.0
QtObject {
property var locale: Qt.locale()
property string dateTimeString: "Tue 2013-09-17 10:56:06"
Component.onCompleted: {
print(Date.fromLocaleString(locale, dateTimeString, "ddd yyyy-MM-dd hh:mm:ss"));
}
}
\endcode
*/
/*!
\qmlmethod string Date::fromLocaleDateString(locale, dateString, format)
Converts the date string \a dateString to a \l {QtQml::Date}{Date} object
using \a locale and \a format.
If \a format is not specified, \l {QtQml::Locale}{Locale.LongFormat} will
be used.
If \a locale is not specified, the default locale will be used.
The following example shows the current date first being formatted as a date
string using the default locale and format, then parsed back again in the
same manner:
\code
import QtQml 2.0
QtObject {
property var locale: Qt.locale()
property date currentDate: new Date()
property string dateString
Component.onCompleted: {
dateString = currentDate.toLocaleDateString();
print(Date.fromLocaleDateString(dateString));
}
}
\endcode
*/
/*!
\qmlmethod string Date::fromLocaleTimeString(locale, timeString, format)
Converts the time string \a timeString to a \l {QtQml::Date}{Date} object
using \a locale and \a format.
If \a format is not specified, \l {QtQml::Locale}{Locale.LongFormat} will
be used.
If \a locale is not specified, the default locale will be used.
The following example shows the current time first being formatted as a time
string using the default locale and a short format, then parsed back again
in the same manner:
\code
import QtQml 2.2
QtObject {
property var locale: Qt.locale()
property date currentTime: new Date()
property string timeString
Component.onCompleted: {
timeString = currentTime.toLocaleTimeString(locale, Locale.ShortFormat);
print(Date.fromLocaleTimeString(locale, timeString, Locale.ShortFormat));
}
}
\endcode
*/
/*!
\qmlmethod string Date::timeZoneUpdated()
Informs the JS engine that the system's timezone has been changed, which is necessary
for the correct manipulation of datetime data.
JS stores Date objects in UTC time; all access to and from Date components in local
time involves the application of the current offset from UTC. If the current offset
changes due to the timezone being updated, the JS engine needs to be informed so that
it can recalculate the offset.
This function should be called after the system's timezone has been updated.
For example, an application that changes the timezone would call timeZoneUpdated() after
setting the new time zone:
\code
property string selectedTimeZone
onSelectedTimeZoneChanged: {
MyFunctions.setSystemTimeZone(selectedTimeZone)
Date.timeZoneUpdated()
}
\endcode
*/
|
