Skip to content
Reference > Methods



String formatDate(Number unixEpoch, String pattern, String timezone)


Formats the supplied unix epoch time and returns a legible string date/time based on the supplied pattern and timezone. The pattern is constructed by combining words listed below


Words for including number components. (Note: Including fewer repeating characters will result in variable-width formatting while extra repeating chars will pad with unncessary extra zeros):
  • yy - 2 Digit Year
  • yyyy - 4 Digit Year
  • MM - Month in year
  • ww - Week in year
  • WW - Week in month
  • DDD - Day in year
  • dd - Day in month
  • FF - Day of week in month
  • HH - Hour in day ranging from 0-23
  • kk - Hour in day ranging from 1-24
  • KK - Hour in AM/PM ranging from 0-11
  • hh - Hour in AM/PM ranging from 1-12
  • mm - Minute in hour
  • ss - Second in minute
  • SSS - Millisecond
  • rrr - Microsecond (Note: See below section on supplying unix epoch time)
  • RRR - Nanosecond (Note: See below section on supplying unix epoch time)

Words for including text components:

  • MMM - Month in year as 3 letter code. Ex: Jan
  • MMMM - Month in year as full name. Ex: January
  • E - Day in week as 3 letter code. Ex: Mon
  • EEEE - Day in week as full name. Ex: Monday
  • z - Time zone code Ex: EST
  • zzzz - Time zone full name. Ex: Eastern Standard Time
  • Z - Timezone offset from UTC in hours and minutes, of the form [+-]hhmm. Ex: -0500
  • a - AM/PM marker. Ex: AM
  • G - Era designator. Ex: AD
Syntax for including literal text:
  • '' - Single quote. Ex: '
  • 'Some Text' - Literal text with quotes removed. Ex: Some Text
  • non-letters - Interpreted as a literal. Ex: :

Supplying unix epoch time

When passing in the unixEpoch as a UTC or UTCN, the formatter will automatically understand the supplied precision. When Supplying as a number it is normally interpreted in milliseconds, unless the pattern calls for greater precision by using the letters r or R:
  • Nanoseconds -If the pattern contains the letter R the unix epoch time should be in nanoseconds since 1/1/1970
  • Microseconds - If the pattern has r letter but not the letter R, the unix epoch time should be in microseconds since 1/1/1970
  • Milliseconds - If the pattern does not have the letter r nor the letter R the unix epoch time should be in milliseconds since 1/1/1970

Parameter Definition

Name Type Description
unixEpoch Number Number of milli, micro or nanoseconds since 1/1/1970 in UTC timezone, depending on pattern. If the pattern contains n then nanoseconds, If the pattern contains u then microseconds, otherwise milliseconds.
pattern String Pattern string. See Letters above for details.
timezone String TimeZone to format time in


String r1 = formatDate(1464215270786L,"yyyyMMdd-HH:mm:ss.SSS","EST5EDT"); // r1 == 20160525-18:27:50.786
String r2 = formatDate(1464215270786L,"MMMM/dd/yyyy-HH:mm:ss zzz","EST5EDT"); // r2 == May/25/2016-18:27:50 EDT
String r3 = formatDate(1540407446123456L,"MMMM/dd/yyyy-HH:mm:ss.SSS.rrr zzz","EST5EDT"); // r3 == October/24/2018-14:57:26.123.456 EDT
String r4 = formatDate(1540407446123456789L,"MMMM/dd/yyyy-HH:mm:ss.SSS.rrr.RRR zzz","EST5EDT"); // r4 == October/24/2018-14:57:26.123.456.789 EDT
String r5 = formatDate(113232L,"HH:mm:ss","UTC"); // r5 == 00:01:53