SenseTalk Date and Time Formats
In SenseTalk, date/time values are displayed in a wide variety of formats. These formats are specified using format strings. SenseTalk's date and time format strings are used by the formattedTime function, in the timeFormat global property and the timeInputFormat global property, and in a variable's format property.
SenseTalk accepts and supports three different methods of defining a date/time format:
- Bracket style: Tokens enclosed in square brackets,
[and].
Examples:[year],[weekday]
This style is the most readable and so is usually preferred. The bracket style is used in all of SenseTalk's built-in formats, such as those inthe timeFormatandthe timeInputFormatglobal properties. - Percent style: Tokens identified by the percent character,
%.
Examples:%Y,%A
Note that this style is used by thestrftimefunction in other programming languages such as C, Python, and PHP. - Unicode style: Tokens as defined by the ICU standard.
Examples:yyyy,EEEE
These date/time formats are compatible with a wide range of other software that also uses the ICU libraries.
Each of the following examples results in a date in this format: April 8, 2019 10:04:37
- Bracket format:
[month name] [day], [year] [hr]:[mi]:[se] - Percent format:
%B %e, %Y %H:%M:%S - Unicode format:
MMMM d, yyyy HH:mm:ss
Any characters you include in a date/time definition string in addition to tokens are treated as literal. In the examples above for each format, spaces, the comma , and colons : are placed between tokens where they need to appear in the formatted date/time sequence.
SenseTalk's mechanism for formatting date and time values, and for recognizing dates and times displayed in different configurations (i.e., 1/7/19 or Jan. 7, 2019), relies on the underlying formats established by the International Components for Unicode (ICU) standard (SenseTalk's "Unicode" format). You can learn about this standard in the ICU User Guide.
Date and Time Definitions
The table below shows the specific tokens needed to define each part of a date/time sequence in various formats. The Displays column shows what each token displays for the date: January 7, 2019 2:34:56.01234567 PM
| Bracket Style | Percent Style | Unicode Style | Displays | Description |
|---|---|---|---|---|
| [year] | %Y | yyyy | 2019 | The full year (4-digit year number) |
| [yr] | %y | yy | 19 | The last 2 digits of the year (always 2 digits, with leading zero for years 1-9) |
| [y] | %1y | y | 2019 | The year number (1 or more digits) (Note: [y] and y might not behave exactly the same as %1y in all cases.) |
| [long monthName] [monthName] [long month] | %B | MMMM | January | The full month name |
| [mon] [abbreviated monthName] [abbrev monthName] [abbr month] | %b | MMM | Jan | The abbreviated month name (first 3 characters of the name) |
| [month] [m] | %1m | M | 1 | The month number (1 or 2 digits) |
| [short month] [mo] [short monthName] | %m | MM | 01 | The month number (always 2 digits, with leading zero for months 1-9) |
| [day] [d] | %1d %e | d | 7 | The day of the month (1 or 2 digits) |
| [da] | %d | dd | 07 | The day of the month (always 2 digits, with leading zero for days 1-9) |
| [era] | G | AD | The abbreviated name of the era (BC or AD) | |
| [eraName] | GGGG | Anno Domini | The full name of the era | |
| [weekday] [weekday name] [long weekday] [long weekdayName] | %A | EEEE | Monday | The full name of the day of the week |
| [wkday] [abbr(ev(iated)) weekday] [abbr(ev(iated)) weekdayName] | %a | E | Mon | The abbreviated name of the day of the week (first 3 characters) |
| [short weekday] [short weekdayName] | EEEEEE | Mo | The short abbreviation of the day of the week (first 2 characters) | |
| [dayOfWeek] | %w | e | 2 | The number of the day of the week, from 1 to 7. The number 1 represents the local starting day of the week (which can vary depending on system settings). For this example, Sunday is the first day of the week. |
| [am] [pm] | %p | a | PM | The period of the day (AM or PM) |
| [hour] [hour24] | %1H | H | 14 | The hour of day using a 24-hour clock (from 0 to 23) |
| [hr] [hr24] | %H | HH | 14 | The hour of day using a 24-hour clock (from 00 to 23, always 2 digits, with leading zero for hours 0-9) |
| [hour12] | %1I | h | 2 | The hour of day using a 12-hour clock (from 1 to 12) |
| [hr12] | %I | hh | 02 | The hour of day using a 12-hour clock (from 01 to 12, always 2 digits, with leading zero for hours 1-9) |
| [minute] [min] | %1M | m | 34 | The minute of the hour (from 0 to 59) |
| [mi] | %M | mm | 34 | The minute of the hour (from 00 to 59, always 2 digits, with leading zero for minutes 0-9) |
| [second] [sec] | %1S | s | 56 | The second of the minute (from 0 to 59) |
| [se] | %S | ss | 56 | The second of the minute (from 00 to 59, always 2 digits, with leading zero for seconds 0-9) |
| [millisecond] | %F | SSS | 012 | The millisecond (thousandth of a second) within the second (from 000 to 999, always 3 digits) |
| [nanosecond] | SSSSSS | 012346 | The nanosecond (millionth of a second) within the second (from 000000 to 999999, always 6 digits) | |
| [timeZone] | %z | ZZZ | 0800 | The time zone offset from GMT in hours and minutes (±hhmm) |
| [short timeZone] | x | 08 | The time zone offset from GMT in hours (and minutes if not zero) | |
| [long TimeZone] | ZZZZ | GMT-08:00 | Long localized GMT offset in hours and minutes (GMT±hh:mm) | |
| [timeZone ID] [long timeZone ID] | %Z | VV | America/Los Angeles | Long time zone identifier |
| [short timeZone ID] | V | uslax | Short time zone identifier | |
| [timeZone City] | VVV | Los Angeles | Time zone exemplar city | |
| [timeZoneName] | vvvv | Pacific Time | Time zone generic name | |
| [short timeZoneName] | v | PT | Time zone generic abbreviation | |
| [long timeZoneName] | zzzz | Pacific Standard Time | Time zone specific name | |
| [abbr(ev(iated)) timeZone Name] | z | PST | Time zone specific abbreviation | |
| [timeZoneISO] | XX | -0800 or Z | The time zone offset from GMT in hours and minutes (±hhmm) or Z for zero offset | |
| [short timeZoneISO] | -08 or Z | The time zone offset from GMT in hours (and minutes if not zero) or Z for zero offset | ||
| [long timeZoneISO] | -08:00 or Z | The time zone offset from GMT in hours and minutes (±hh:mm) or Z for zero offset | ||
| [dayOfYear] | %1j | D | 7 | The day of the year (from 1 to 366) |
| [dayOfYear3] | %j | DDD | 007 | The day of the year (from 001 to 366, always 3 digits) |
| [weekYear] | YYYY | 2019 | The year number in Week of Year* calculations. This is the year used in the ISO year-week calendar as defined by ISO 8601. The value might be different from the calendar year for dates that are within the first or last 3 days of the year. | |
| [weekOfYear] | w | 2 | The week number within the year (from 1 to 52 or 53)* | |
| [wkOfYear] | ww | 02 | The week number within the year (from 1 to 52 or 53, always 2 digits, with leading zero for weeks 0-9)* | |
| [weekOfMonth] | W | 2 | The week number within the month (from 1 to 5)* | |
| [dayOfWeekInMonth] | F | 1 | The ordinal number of the weekday within the month (from 1 to 5). In this example, the value 1 indicates that January 7, 2019, is the first Monday of the month.* | |
| %c | The complete localized date and time | |||
| %x | The localized date | |||
| %X | The localized time | |||
| ['quoted'] | 'quoted' | quoted | When using the bracket style, anything outside of [ ] is always literal, so this is needed only to treat text containing square brackets as literal (extremely rare). |
* Week Of Year
Values calculated for the [weekYear], [weekOfYear], or [wkOfYear] fields first determine which week of the year a date falls within, from 1 to 53. Week 1 for a year is the week that contains at least 4 days in that year (or in other words, that contains January 4 of that year).
For example, because January 1 of 2019 fell on a Tuesday, week 1 of that year encompasses the dates from December 30, 2018 (Sunday), through January 5, 2019 (Saturday). Weeks between week 1 of one year and week 1 of the following year are numbered sequentially from 2 to 52 or 53 (if needed). The [weekYear] of December 30 and 31 of 2018 is therefore 2019, not 2018, because those days fall within the first week of 2019.
Values are similarly calculated for [weekOfMonth] and [dayOfWeekInMonth].
When using the bracket format, the token names are not case-sensitive, and spaces are ignored. So for example the following are all acceptable and equivalent:
[short month name]
[Short MonthName]
[shortMONTHname]