# Date and Time Formatting

NOTE: Starting with build 7.0.7252, Inaport uses a new set of formatting controls for date/time and number formatting, and a new set of functions. The following codes are OBSOLETE - see Formatting Overview for current information.

The date and time functions in Inaportuse a format string to determine how dates will be recognised and displayed. For example, suppose the date is Wednesday 22 August 2001 at 2:39 pm. We can use format patterns to display this date in very different ways.

Format Pattern | Date displayed
"yyyy/mm/dd" | 2001/08/22
"yyyy MMMM dd, hh:mm" | 2001 August 08, 2:39
"'Today is ' EEEE, ' day ' DDD ' in year ' yyyy" | Today is Wednesday, day 234 in year 2001

Inaport has a range of functions for converting between strings and date/times. Some are:

- dtos(date, format) convert date to string in format specified
- date(string, format) convert the string in the format specified into a date

The format pattern is made up of:

- special characters which are translated to elements of the date
- ordinary text that can be mixed in with the date values.

The special characters are listed in the following table:

Symbol | Meaning | Presentation | Example
G | era designator | Text | AD
y | year | Number | 1996
M | month in year | Text or Number | July or 07
d | day in month | Number | 10
h | hour in am/pm format (1 ~ 12) | Number | 11
K | hour in am/pm format (0 ~ 11) | Number | 0
H | hour in day (0 ~ 23) | Number | 13
k | hour in day (1 ~ 24) | Number | 24
m | minute in hour | Number | 32
s | second in minute | Number | 55
S | millisecond | Number | 978
E | day in week | Text | Tuesday
D | day in year | Number | 189
F | day of week in month | Number | 2 (2nd Wednesday in July)
w | week in year | Number | 27
W | week in month | Number | 2
a | am/pm marker | Text | PM
z | time zone | Text | Pacific Standard time
' | escape for text | Text | 'Today is'
" | single quote | Text | '

For each of the special characters, the number of characters used in the pattern determines the format.

- (Text): 4 or more pattern letters means use the full form, less than 4 means use short or abbreviated form if one exists.
  For example, if the day is Wednesday:
  EE gives Wed
  EEEE gives Wednesday
- (Number): the minimum number of digits. Shorter numbers are zero-padded to this amount. Year is handled specially; that is, if the count of 'y' is 2, the Year will be truncated to 2 digits.
- (Text & Number): 3 or over, use text, otherwise use number. For example, if the month is August:
  MM gives 08
  MMM gives Aug
  MMMM gives August

Any characters in the pattern that are not in the ranges of ['a'..'z'] and ['A'..'Z'] will be treated as quoted text. For instance, characters like ':', '.', ' ', '#' and '@' will appear in the resulting time text even they are not embraced within single quotes.

Some more examples of patterns and the corresponding date (assuming a date of Wednesday July 10 1996):

Format Pattern | Result
"yyyy.MM.dd G 'at' hh:mm:ss z" | 1996.07.10 AD at 15:08:56 PDT
"EEE, MMM d, ''yy" | Wed, July 10, '96
"h:mm a" | 12:08 PM
"hh 'o''''clock' a, zzzz" | 12 o'clock PM, Pacific Daylight Time
"K:mm a, z" | 0:00 PM, PST
"yyyyy.MMMMM.dd GGG hh:mm aaa" | 1996.July.10 AD 12:08 PM