Date/Time Format Strings

10 min

The datatype/DateTime object supports date/time conversion into a string through the FormatUniversalTime() and FormatLocalTime() functions. They both work the same except for which timezone the datatype/DateTime should be interpreted in.

The first argument passed to these functions must be a string representing one of the tokens shown below. The tokens are then replaced with a specific value depending on the provided locale.

			
				Expected Output
			
				Expand
				
			local dt = DateTime.now()

-- The "dddd" token is replaced with the full day of the week
print("Today is " .. dt:FormatLocalTime("dddd", "en-us"))

-- For the "en-us" locale, the "LL" token equals "MMMM D, YYYY"
print("The date is " .. dt:FormatLocalTime("LL", "en-us"))
		
				Copy Code
			
				Light Theme

Composite Tokens

Depending on locale, these tokens replace to specific combinations of the elemental tokens described in the next section. This produces a correct date/time string depending on the locale. For example, English locales write dates “[month] [day]” as in June 11. Contrast this to French locales where dates are written “[day] [month]” as in 11 juin. These special rules are handled for you automatically through the following composite tokens, so use these if you’re displaying simple time and/or date information.

Token(s)	Locale Examples (Format)
Time
`LT`	`en-us` : `8:30 PM` (`h:mm A`) `zh-cn` : `20:30` (`HH:mm`)
Time with Seconds
`LTS`	`en-us` : `8:30:25 PM` (`h:mm:ss A`) `zh-cn` : `20:30:25` (`HH:mm:ss`)
Month (Number), Day, Year
`L`	`en-us` : `09/04/1986` (`MM/DD/YYYY`) `zh-cn` : `1986/09/04` (`YYYY/MM/DD`)
`l`	`en-us` : `9/4/1986` (`M/D/YYYY`) `zh-cn` : `1986/9/4` (`YYYY/M/D`)
Month (Name), Day, Year
`LL`	`en-us` : `September 4, 1986` (`MMMM D, YYYY`) `zh-cn` : `1986年9月4日` (`YYYY年M月D日`)
`ll`	`en-us` : `Sep 4, 1986` (`MMM D, YYYY`) `zh-cn` : `1986年9月4日` (`YYYY年M月D日`)
Month (Name), Day, Year, Time
`LLL`	`en-us` : `September 4, 1986 8:30 PM` (`MMMM D, YYYY h:mm A`) `zh-cn` : `1986年9月4日晚上8点30分` (`YYYY年M月D日Ah点mm分`)
`lll`	`en-us` : `Sep 4, 1986 8:30 PM` (`MMM D, YYYY h:mm A`) `zh-cn` : `1986年9月4日 20:30` (`YYYY年M月D日 HH:mm`)
Day of Week, Month (Name), Day, Year, Time
`LLLL`	`en-us` : `Thursday, September 4, 1986 8:30 PM` (`dddd, MMMM D, YYYY h:mm A`) `zh-cn` : `1986年9月4日星期四晚上8点30分` (`YYYY年M月D日ddddAh点mm分`)
`llll`	`en-us` : `Thu, Sep 4, 1986 8:30 PM` (`ddd, MMM D, YYYY h:mm A`) `zh-cn` : `1986年9月4日星期四 20:30` (`YYYY年M月D日dddd HH:mm`)

Elemental Tokens

Each of these tokens replace to a single value and can be used as elements of a larger time string. Generally, you should avoid using these if you only need simple date and time information, as the composite tokens above are more suited to such a purpose.

Token(s)	Examples
Year
`YY`	`70`, `71`, …, `29`, `30`
`YYYY`	`1970`, `1971`, …, `2029`, `2030`
Month
`M`	`1`, `2`, …, `11`, `12`
`MM`	`01`, `02`, …, `11`, `12`
`MMM`	`Jan`, `Feb`, …, `Nov`, `Dec`
`MMMM`	`January`, `February`, …, `November`, `December`
Day of Month
`D`	`1`, `2`, …, `30`, `31`
`DD`	`01`, `02`, …, `30`, `31`
Day of Year
`DDD`	`1`, `2`, …, `364`, `365`
`DDDD`	`001`, `002`, …, `364`, `365`
Day of Week
`d`	`0`, `1`, …, `5`, `6`
`dd`	`Su`, `Mo`, …, `Fr`, `Sa`
`ddd`	`Sun`, `Mon`, …, `Fri`, `Sat`
`dddd`	`Sunday`, `Monday`, …, `Friday`, `Saturday`
Hour
`H`	`0`, `1`, …, `22`, `23`
`HH`	`00`, `01`, …, `22`, `23`
`h`	`1`, `2`, …, `11`, `12`
`hh`	`01`, `02`, …, `11`, `12`
Minute
`m`	`0`, `1`, …, `58`, `59`
`mm`	`00`, `01`, …, `58`, `59`
Second
`s`	`0`, `1`, …, `58`, `59`
`ss`	`00`, `01`, …, `58`, `59`
Fractional Second
`S`	`0`, `1`, …, `8`, `9`
`SS`	`00`, `01`, …, `98`, `99`
`SSS`	`000`, `001`, …, `998`, `999`
AM/PM
`A`	`en-us` : `AM`, `PM` `zh-cn` : `凌晨\|早上\|上午\|中午\|下午\|晚上`
`a`	`en-us` : `am`, `pm` `zh-cn` : `凌晨\|早上\|上午\|中午\|下午\|晚上`

Tags:

date
time
format

Date/Time Format Strings

Date/Time Format Strings

Composite Tokens

Elemental Tokens

Related Articles

Localization Format Strings