diff options
Diffstat (limited to 'src/qml/doc/src/javascript/date.qdoc')
| -rw-r--r-- | src/qml/doc/src/javascript/date.qdoc | 132 |
1 files changed, 29 insertions, 103 deletions
diff --git a/src/qml/doc/src/javascript/date.qdoc b/src/qml/doc/src/javascript/date.qdoc index 431f9649a0..26ce1d5d29 100644 --- a/src/qml/doc/src/javascript/date.qdoc +++ b/src/qml/doc/src/javascript/date.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \qmltype Date @@ -31,98 +7,48 @@ \brief Provides date functions. The QML Date object extends the - \l{Mozilla Developer Network Date Reference}{JS Date object} with + \l{ECMAScript Specification of Date}{JS Date object} with locale aware functions. - Functions that accept a locale format may be either an enumeration - value: - \table - \row \li Locale.LongFormat \li The long version of the string; for example, returning "January" as a month name. - \row \li Locale.ShortFormat \li The short version of the string; for example, returning "Jan" as a month name. - \row \li Locale.NarrowFormat \li A special version for use when space is limited; - for example, returning "J" as a month name. Note that the narrow format might contain - the same text for different months and days or it can even be an empty string if the - locale doesn't support narrow names, so you should avoid using it for date formatting. - Also, for the system locale this format is the same as ShortFormat. - \endtable + Functions that accept a \c format argument take either Locale.LongFormat, + Locale.ShortFormat, Locale.NarrowFormat enumeration values, + or a string specifying the format. - or a string specifying the format These expressions may be used for format dates: - \table - \header \li Expression \li Output - \row \li d \li the day as number without a leading zero (1 to 31) - \row \li dd \li the day as number with a leading zero (01 to 31) - \row \li ddd - \li the abbreviated localized day name (e.g. 'Mon' to 'Sun'). - \row \li dddd - \li the long localized day name (e.g. 'Monday' to 'Sunday'). - \row \li M \li the month as number without a leading zero (1 to 12) - \row \li MM \li the month as number with a leading zero (01 to 12) - \row \li MMM - \li the abbreviated localized month name (e.g. 'Jan' to 'Dec'). - \row \li MMMM - \li the long localized month name (e.g. 'January' to 'December'). - \row \li yy \li the year as two digit number (00 to 99) - \row \li yyyy \li the year as four digit number. If the year is negative, - a minus sign is prepended in addition. - \endtable + The form of the supported format strings is as described in the + documentation of \l QDate::toString(), \l QTime::toString() and \l + QDateTime::toString(). - All other input characters will be ignored. Any sequence of characters that - are enclosed in singlequotes will be treated as text and not be used as an - expression. Two consecutive singlequotes ("''") are replaced by a singlequote - in the output. + If the date is invalid, an empty string is returned. - Example format strings (assuming that the Date is the 20 July - 1969): - - \table - \header \li Format \li Result - \row \li dd.MM.yyyy \li 20.07.1969 - \row \li ddd MMMM d yy \li Sun July 20 69 - \row \li 'The day is' dddd \li The day is Sunday - \endtable + \section1 Format Enumeration Values - These expressions may be used for formatting time: + Use the enumeration values when you want a format that matches the locale + preferences. \table - \header \li Expression \li Output - \row \li h - \li the hour without a leading zero (0 to 23 or 1 to 12 if AM/PM display) - \row \li hh - \li the hour with a leading zero (00 to 23 or 01 to 12 if AM/PM display) - \row \li H - \li the hour without a leading zero (0 to 23, even with AM/PM display) - \row \li HH - \li the hour with a leading zero (00 to 23, even with AM/PM display) - \row \li m \li the minute without a leading zero (0 to 59) - \row \li mm \li the minute with a leading zero (00 to 59) - \row \li s \li the second without a leading zero (0 to 59) - \row \li ss \li the second with a leading zero (00 to 59) - \row \li z \li the milliseconds without leading zeroes (0 to 999) - \row \li zzz \li the milliseconds with leading zeroes (000 to 999) - \row \li AP or A - \li use AM/PM display. \e AP will be replaced by either "AM" or "PM". - \row \li ap or a - \li use am/pm display. \e ap will be replaced by either "am" or "pm". - \row \li t \li the timezone (for example "CEST") + \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 - All other input characters will be ignored. Any sequence of characters that - are enclosed in singlequotes will be treated as text and not be used as an - expression. Two consecutive singlequotes ("''") are replaced by a singlequote - in the output. + The format that the enumerations represent will depend on your locale, but also + the method that the enumeration is used for. - Example format strings (assuming that the QTime is 14:13:09.042) + For example, for the \c en_US locale, these format strings are used: \table - \header \li Format \li Result - \row \li hh:mm:ss.zzz \li 14:13:09.042 - \row \li h:m:s ap \li 2:13:9 pm - \row \li H:m:s a \li 14:13:9 pm + \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 - If the date is invalid, an empty string will be returned. + \section1 Further Notes - Note: Using the locale-aware functions to perform date or time formatting can + 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 @@ -132,7 +58,7 @@ hour, if DST is currently in effect, while it was not for the time specified, or vice versa. - Note: There are different date formats with different understandings of negative years. Common + 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 |