Access Keys:
Skip to content (Access Key - 0)

Adaptavist Documentation Move

This documentation is deprecated. Adaptavist's documentation has moved to a new location where it is maintained and updated. Please visit Adaptavist's new Documentation area.

Date Formats

Date Formats

This tutorial explains how dates are formatted in Confluence...

There are several places where dates are used in Confluence such as the General Configuration settings (which set the default formats for dates and times) and various macros including the chart macro, date-data macro and page-info macro.

All dates and times are stored in the same way, however they can be displayed in many different formats. To set the format, you use a "date pattern" which is a series of characters that define where particular pieces of information are shown, for example:

Date Pattern Notes Example
HH:mm Hours (24hr) and minutes 16:45
yyyy Four digit year 2006
yyyy G Year followed by era 2006 AD
h 'o''clock' Hour followed by o'clock 4 o'clock
h:mm a 'on' EEEE, d MMMM yyyy 12-hour time and full date 9:45 AM on Tuesday, 7 March 2006

Using date patterns, you can format dates and time in almost any concievable way.

Date and time formats are specified by date and time pattern strings. Within date and time pattern strings, unquoted letters from 'A' to 'Z' and from 'a' to 'z' are interpreted as pattern letters representing the components of a date or time string.

Text can be quoted using single quotes (') to avoid interpretation. Two single quotes together ('') results in a single quote (') being displayed.

All other characters are not interpreted; they're simply copied into the output string during formatting or matched against the input string during parsing.

Pattern Letters

Symbol Meaning Presentation Examples
G Era designator Text #Text] AD
y Year Year #Year] 1996
M Month of year Month #Month] July; Jul; 07; 7
w Week in year Number #Number] 07; 7
W Week in month Number #Number] 07; 7
D Day of year Number #Number] 189
d Day of month Number #Number] 10
F Day in week of month Number #Number] 2; 2
E Day of week Text #Text] Tuesday; Tue
a Halfday of day Text #Text] PM
H Hour of day (0~23) Number #Number] 0
k Clockhour of day (1~24) Number #Number] 24
K Hour of halfday (0~11) Number #Number] 0
h Clockhour of halfday (1~12) Number #Number] 12
m Minute of hour Number #Number] 30
s Second of minute Number #Number] 55
S Fraction of second Number #Number] 978
z Time zone General Time Zone #General Time Zone] Pacific Standard Time; PST
Z Time zone offset/id RFC 822 Time Zone #RFC 822 Time Zone] -0800; -08:00; Asia/Tokyo
' Escape for text Delimiter #Delimiter]  
'' Single quote Quote #Quote] '
other All other characters Literal #Literal]  
Case Senstitive!
The characters used in the date patterns are case sensitive. For example, "m" (minute) and "M" (month) are obviously very different things.

Presentation

As you'll see from the table above, each character has a designated "presentation" that defines how it will look when output. Different presentations have different special properties as listed below...

Note:
When using macros such as the chart macro, date patterns can also be used to parse dates in tables, etc. Parsed dates sometimes have slightly different settings and are detailed at the end of each presentation type.

Text

If the number of pattern letters is 4 or more, the full form is used; otherwise a short or abbreviated form is used if available as shown in the examples below:

EEEE Tuesday
EEE Tue
EE Tue
E Tue

For parsing, both forms (three letter abbreviation and full day name) are accepted, independent of the number of pattern letters.

Number

The number of pattern letters defines the minimum number of digits, and shorter numbers are zero-padded to ensure the desired number of digits as shown in the example below:

h 12
hh 12
hhh 012

For parsing, the number of pattern letters is ignored unless it's needed to separate two adjacent fields.

Month

If the number of pattern letters is 3 or more, the month is interpreted as Text; otherwise, it is interpreted as a Number.

M 3
MM 03
MMM Mar
MMMM March

Year

If the number of pattern letters is 2 digits, the last two digits of the year are shown, otherwise it is treated as a Number.

y 2006
yy 06
yyy 2006
yyyy 2006

For parsing, if the number of pattern letters is more than 2, the year is interpreted literally, regardless of the number of digits. So using the pattern "MM/dd/yyyy", "01/11/12" parses to Jan 11, 12 A.D.

For parsing with the abbreviated year pattern ("y" or "yy"), it must interpret the abbreviated year relative to some century. It does this by adjusting dates to be within 80 years before and 20 years after the time the current year (usually).

For example, using a pattern of "MM/dd/yy" and a SimpleDateFormat instance created on Jan 1, 1997, the string "01/11/12" would be interpreted as Jan 11, 2012 while the string "05/04/64" would be interpreted as May 4, 1964.

During parsing, only strings consisting of exactly two digits, will be parsed into the default century. Any other numeric string, such as a one digit string, a three or more digit string, or a two digit string that isn't all digits (for example, "-1"), is interpreted literally. So "01/02/3" or "01/02/003" are parsed, using the same pattern, as Jan 2, 3 AD. Likewise, "01/02/-3" is parsed as Jan 2, 4 BC.

General Time Zone

Time zones are interpreted as Text if they have names:

z PST
zz PST
zzz PST
zzzz Pacific Standard Time

As shown in the last example, if a time zone does not have a name, a GMT offset will be shown in the format:

GMT Sign H:mm

For example: GMT-8:00

RFC 822 Time Zone

An IETF RFC 822 time zone always shows the offset from Greenwich Mean Time.

If the number of pattern characters is 3 or less, an offset in the form hhmm is given. If the number of pattern characters is 4 or more, an offset in the form hh:mm is given.

Z -0800
ZZ -0800
ZZZ -0800
ZZZZ -08:00

Delimiter

A delimiter is used to display text when formatting a date/time string, for example:

d MMMM yyyy 'at' hh:mm --> 7 March 2006 at 15:32

The text at will be treated as literal.

Without the quotes, the a would be treated as the AM/PM marker:

d MMMM yyyy at hh:mm --> March 2006 PMt 15:32

Because additional letters may have specific meaning assigned to them in later versions, you should always enclose Literal text in Delimiters.

Quote

Obviously, there may be occasions when you want to display a quote - to do this, simply place two quotes together:

h 'O''clock' --> 3 O'clock

Literal

Literal text is not processed - it is merely output when formatting and when parsing it is skipped.

Any text can be made literal by using Delimiters as stated above.

Any character that does not have any special meaning (i.e. not a letter of the alphabet), such as a colon (:), is also treated as literal text.

See Also

  • SimpleDateFormat – Java's date utility classes are generally used for formatting dates in Confluence.
  • Joda Time – Another library that's used in several 3rd party macros.



View old comments


Adaptavist Theme Builder Powered by Atlassian Confluence