Groovy Dates And Times Cheat Sheet

Author: Paul King
Published: 2022-10-24 07:27AM

Java has had a Date class from the very beginning and Groovy supports using it and several related classes like Calendar. Throughout this blog post we refer to those classes as the legacy date classes. Groovy enhances the experience of using the legacy date classes with simpler mechanisms for formatting, parsing and extracting fields from the related classes.

Since Java 8, the JDK has included the JSR-310 Date Time API. We refer to these classes as the new date classes. The new date classes remove many limitations of the legacy date classes and bring some greatly appreciated additional consistency. Groovy provides similar enhancements for the new date classes too.

Groovy’s enhancements for the legacy date classes are in the groovy-dateutil module (prior to Groovy 2.5, this functionality was built in to the core module). The groovy-datetime module has the enhancements for the new date classes. You can include a dependency to this module in your build file or reference the groovy-all pom dependency. Both modules are part of a standard Groovy install.

The next few sections illustrate common date and time tasks and the code to perform them using the new and legacy classes with Groovy enhancements in numerous places.

Please note: that some of the formatting commands are Locale dependent and the output may vary slightly if you run these examples yourself.

Representing the current date/time

The legacy date classes have an abstraction which includes date and time. If you are only interested in one of those two aspects, you simply ignore the other aspect. The new date classes allow you to have date-only, time-only and date-time representations.

The examples create instances representing the current date and/or time. Various information is extracted from the instances and they are printed in various ways. Some of the examples use the SV macro which prints the name and string value of one or more variables.

task	java.time	legacy
current date and time	println LocalDateTime.now() println Instant.now() 2022-10-24T12:40:02.218130200 2022-10-24T02:40:02.223131Z	println new Date() println Calendar.instance.time Mon Oct 24 12:40:02 AEST 2022 Mon Oct 24 12:40:02 AEST 2022
day of current year & day of current month	println LocalDateTime.now().dayOfYear println LocalDateTime.now().dayOfMonth 297 24	println Calendar.instance[DAY_OF_YEAR] println Calendar.instance[DAY_OF_MONTH] 297 24
extract today's year, month & day	var now = LocalDate.now() // or LocalDateTime println SV(now.year, now.monthValue, now.dayOfMonth) (Y, M, D) = now[YEAR, MONTH_OF_YEAR, DAY_OF_MONTH] println "Today is $Y $M $D" now.year=2022, now.monthValue=10, now.dayOfMonth=24 Today is 2022 10 24	var now = Calendar.instance (_E, Y, M, _WY, _WM, D) = now println "Today is $Y ${M+1} $D" (Y, M, D) = now[YEAR, MONTH, DAY_OF_MONTH] println "Today is $Y ${M+1} $D" Today is 2022 10 24 Today is 2022 10 24
alternatives to print today	println now.format("'Today is 'YYYY-MM-dd") printf 'Today is %1$tY-%1$tm-%1$te%n', now Today is 2022-10-24 Today is 2022-10-24	println now.format("'Today is 'YYYY-MM-dd") printf 'Today is %1$tY-%1$tm-%1$te%n', now Today is 2022-10-24 Today is 2022-10-24
extract parts of current time	now = LocalTime.now() // or LocalDateTime println SV(now.hour, now.minute, now.second) (H, M, S) = now[HOUR_OF_DAY, MINUTE_OF_HOUR, SECOND_OF_MINUTE] printf 'The time is %02d:%02d:%02d\n', H, M, S now.hour=12, now.minute=40, now.second=2 The time is 12:40:02	(H, M, S) = now[HOUR_OF_DAY, MINUTE, SECOND] println SV(H, M, S) printf 'The time is %02d:%02d:%02d%n', H, M, S H=12, M=40, S=2 The time is 12:40:02
alternatives to print time	println now.format("'The time is 'HH:mm:ss") printf 'The time is %1$tH:%1$tM:%1$tS%n', now The time is 12:40:02 The time is 12:40:02	println now.format("'The time is 'HH:mm:ss") printf 'The time is %1$tH:%1$tM:%1$tS%n', now The time is 12:40:02 The time is 12:40:02

task

java.time

legacy

current date and time

println LocalDateTime.now()      
println Instant.now()

2022-10-24T12:40:02.218130200
2022-10-24T02:40:02.223131Z

println new Date()               
println Calendar.instance.time

Mon Oct 24 12:40:02 AEST 2022
Mon Oct 24 12:40:02 AEST 2022

day of current year &
day of current month

println LocalDateTime.now().dayOfYear
println LocalDateTime.now().dayOfMonth

297
24

println Calendar.instance[DAY_OF_YEAR]
println Calendar.instance[DAY_OF_MONTH]

297
24

extract today's
year, month & day

var now = LocalDate.now()     // or LocalDateTime

println SV(now.year, now.monthValue, now.dayOfMonth)

(Y, M, D) = now[YEAR, MONTH_OF_YEAR, DAY_OF_MONTH]
println "Today is $Y $M $D"

now.year=2022, now.monthValue=10, now.dayOfMonth=24
Today is 2022 10 24

var now = Calendar.instance
(_E, Y, M, _WY, _WM, D) = now
println "Today is $Y ${M+1} $D"

(Y, M, D) = now[YEAR, MONTH, DAY_OF_MONTH]
println "Today is $Y ${M+1} $D"

Today is 2022 10 24
Today is 2022 10 24

alternatives to print today

println now.format("'Today is 'YYYY-MM-dd")
printf 'Today is %1$tY-%1$tm-%1$te%n', now

Today is 2022-10-24
Today is 2022-10-24

println now.format("'Today is 'YYYY-MM-dd")
printf 'Today is %1$tY-%1$tm-%1$te%n', now

Today is 2022-10-24
Today is 2022-10-24

extract parts of current time

now = LocalTime.now() // or LocalDateTime
println SV(now.hour, now.minute, now.second)
(H, M, S) = now[HOUR_OF_DAY, MINUTE_OF_HOUR,
                SECOND_OF_MINUTE]
printf 'The time is %02d:%02d:%02d\n', H, M, S

now.hour=12, now.minute=40, now.second=2
The time is 12:40:02

(H, M, S) = now[HOUR_OF_DAY, MINUTE, SECOND]

println SV(H, M, S)

printf 'The time is %02d:%02d:%02d%n', H, M, S

H=12, M=40, S=2
The time is 12:40:02

alternatives to print time

println now.format("'The time is 'HH:mm:ss")
printf 'The time is %1$tH:%1$tM:%1$tS%n', now

The time is 12:40:02
The time is 12:40:02

println now.format("'The time is 'HH:mm:ss")
printf 'The time is %1$tH:%1$tM:%1$tS%n', now

The time is 12:40:02
The time is 12:40:02

Processing times

The new date classes have a LocalTime class specifically for representing time-only quantities. The legacy date classes don’t have such a purpose-built abstraction; you essentially just ignore the day, month, and year parts of a date. The java.sql.Time class could be used as an alternative but rarely is. The Java documentation comparing the new date classes to their legacy equivalents, talks about using GregorianCalendar with the date set to the epoch value of 1970-01-01 as an approximation of the LocalTime class. We’ll follow that approach here to provide a comparison but we strongly recommend upgrading to the new classes if you need to represent time-only values or use the Joda-Time library on JDK versions prior to 8.

The examples look at representing a minute before and after midnight, and some times at which you might eat your meals. For the meals, as well as printing various values, we might be interested in calculating new times in terms of existing times, e.g. lunch and dinner are 7 hours apart.

task	java.time	legacy
one min after midnight	LocalTime.of(0, 1).with { println format('HH:mm') println format('hh:mm a') println format('K:mm a') } 00:01 12:01 am 0:01 am	Calendar.instance.with { clear() set(MINUTE, 1) println format('HH:mm') println format('hh:mm a') println format('K:mm a') } 00:01 12:01 am 0:01 am
one min before midnight	LocalTime.of(23, 59).with { println format('HH:mm') println format('hh:mm a') println format('K:mm a') } 23:59 11:59 pm 11:59 pm	Calendar.instance.with { clear() set(hourOfDay: 23, minute: 59) println format('HH:mm') println format('hh:mm a') println format('K:mm a') } 23:59 11:59 pm 11:59 pm
meal times	var breakfast = LocalTime.of(7, 30) var lunch = LocalTime.parse('12:30') assert lunch == LocalTime.parse('12:30.00 pm', 'hh:mm.ss a') lunch.with { assert hour == 12 && minute == 30 } var dinner = lunch.plusHours(7) assert dinner == lunch.plus(7, ChronoUnit.HOURS) assert Duration.between(lunch, dinner).toHours() == 7 assert breakfast.isBefore(lunch) // Java API assert lunch < dinner // Groovy shorthand assert lunch in breakfast..dinner assert dinner.format('hh:mm a') == '07:30 pm' assert dinner.format('k:mm') == '19:30' assert dinner.format(FormatStyle.MEDIUM) == '7:30:00 pm' assert dinner.timeString == '19:30:00'	var breakfast = Date.parse('hh:mm', '07:30') var lunch = Calendar.instance.tap { clear() set(hourOfDay: 12, minute: 30) } assert lunch[HOUR_OF_DAY, MINUTE] == [12, 30] var dinner = lunch.clone().tap { it[HOUR_OF_DAY] += 7 } assert dinner == lunch.copyWith(hourOfDay: 19) assert dinner.format('hh:mm a') == '07:30 pm' assert dinner.format('k:mm') == '19:30' assert dinner.time.timeString == '7:30:00 pm' assert breakfast.before(lunch.time) // Java API assert lunch < dinner // Groovy shorthand

task

java.time

legacy

one min after midnight

LocalTime.of(0, 1).with {
    println format('HH:mm')
    println format('hh:mm a')
    println format('K:mm a')
}

00:01
12:01 am
0:01 am

Calendar.instance.with {
    clear()
    set(MINUTE, 1)
    println format('HH:mm')
    println format('hh:mm a')
    println format('K:mm a')
}

00:01
12:01 am
0:01 am

one min before midnight

LocalTime.of(23, 59).with {
    println format('HH:mm')
    println format('hh:mm a')
    println format('K:mm a')
}

23:59
11:59 pm
11:59 pm

Calendar.instance.with {
    clear()
    set(hourOfDay: 23, minute: 59)
    println format('HH:mm')
    println format('hh:mm a')
    println format('K:mm a')
}

23:59
11:59 pm
11:59 pm

meal times

var breakfast = LocalTime.of(7, 30)
var lunch = LocalTime.parse('12:30')
assert lunch == LocalTime.parse('12:30.00 pm', 'hh:mm.ss a')
lunch.with { assert hour == 12 && minute == 30 }
var dinner = lunch.plusHours(7)
assert dinner == lunch.plus(7, ChronoUnit.HOURS)
assert Duration.between(lunch, dinner).toHours() == 7
assert breakfast.isBefore(lunch)   // Java API
assert lunch < dinner              // Groovy shorthand
assert lunch in breakfast..dinner
assert dinner.format('hh:mm a') == '07:30 pm'
assert dinner.format('k:mm') == '19:30'
assert dinner.format(FormatStyle.MEDIUM) == '7:30:00 pm'
assert dinner.timeString == '19:30:00'

var breakfast = Date.parse('hh:mm', '07:30')
var lunch = Calendar.instance.tap {
    clear()
    set(hourOfDay: 12, minute: 30)
}
assert lunch[HOUR_OF_DAY, MINUTE] == [12, 30]
var dinner = lunch.clone().tap { it[HOUR_OF_DAY] += 7 }
assert dinner == lunch.copyWith(hourOfDay: 19)
assert dinner.format('hh:mm a') == '07:30 pm'
assert dinner.format('k:mm') == '19:30'
assert dinner.time.timeString == '7:30:00 pm'
assert breakfast.before(lunch.time)  // Java API
assert lunch < dinner                // Groovy shorthand

Processing dates

To represent date-only information with the legacy date classes, you set the time aspects to zero, or simply ignore them. Alternatively, you could consider the less commonly used java.sql.Date class. The new date classes have the special LocalDate class for this purpose which we highly recommend.

The examples create dates for Halloween and Melbourne Cup day (a public holiday in the Australia state of Victoria). We look at various properties of those two dates.

task	java.time	legacy
holidays	var halloween22 = LocalDate.of(2022, 10, 31) var halloween23 = LocalDate.parse('2023-Oct-31', 'yyyy-LLL-dd') assert halloween22 == halloween23 - 365 assert halloween23 == halloween22.plusYears(1) var melbourneCup22 = LocalDate.of(2022, 11, 1) assert halloween22 < melbourneCup22 assert melbourneCup22 - halloween22 == 1 assert Period.between(halloween22, melbourneCup22).days == 1 assert ChronoUnit.DAYS.between(halloween22, melbourneCup22) == 1L var days = [] halloween22.upto(melbourneCup22) {days << "$it.dayOfWeek" } assert days == ['MONDAY', 'TUESDAY'] var hols = halloween22..melbourneCup22 assert hols.size() == 2	var halloween21 = Date.parse('dd/MM/yyyy', '31/10/2021') var halloween22 = Date.parse('yyyy-MMM-dd', '2022-Oct-31') assert halloween21 + 365 == halloween22 var melbourneCup22 = new GregorianCalendar(2022, 10, 1).time assert melbourneCup22.dateString == '1/11/22' // AU Locale assert halloween22 < melbourneCup22 assert melbourneCup22 - halloween22 == 1 assert melbourneCup22 == halloween22.copyWith(month: 10, date: 1) var days = [] halloween22.upto(melbourneCup22) { days << it.format('EEEEE') } assert days == ['Monday', 'Tuesday'] var hols = halloween22..melbourneCup22 assert hols.size() == 2

task

java.time

legacy

holidays

var halloween22 = LocalDate.of(2022, 10, 31)
var halloween23 = LocalDate.parse('2023-Oct-31', 'yyyy-LLL-dd')
assert halloween22 == halloween23 - 365
assert halloween23 == halloween22.plusYears(1)
var melbourneCup22 = LocalDate.of(2022, 11, 1)
assert halloween22 < melbourneCup22
assert melbourneCup22 - halloween22 == 1
assert Period.between(halloween22, melbourneCup22).days == 1
assert ChronoUnit.DAYS.between(halloween22, melbourneCup22) == 1L
var days = []
halloween22.upto(melbourneCup22) {days << "$it.dayOfWeek" }
assert days == ['MONDAY', 'TUESDAY']
var hols = halloween22..melbourneCup22
assert hols.size() == 2

var halloween21 = Date.parse('dd/MM/yyyy', '31/10/2021')
var halloween22 = Date.parse('yyyy-MMM-dd', '2022-Oct-31')
assert halloween21 + 365 == halloween22
var melbourneCup22 = new GregorianCalendar(2022, 10, 1).time
assert melbourneCup22.dateString == '1/11/22' // AU Locale
assert halloween22 < melbourneCup22
assert melbourneCup22 - halloween22 == 1
assert melbourneCup22 == halloween22.copyWith(month: 10, date: 1)
var days = []
halloween22.upto(melbourneCup22) { days << it.format('EEEEE') }
assert days == ['Monday', 'Tuesday']
var hols = halloween22..melbourneCup22
assert hols.size() == 2

Processing date and time combinations

The new date classes use LocalDateTime to represent a quantity with both date and time aspects. Many of the methods seen earlier will also be applicable here.

The examples show creating and printing a representation of lunch on Melbourne Cup day.

task	java.time	legacy
holidays	var melbourneCupLunch = LocalDateTime.of(2022, 11, 1, 12, 30) assert melbourneCupLunch.timeString == '12:30:00' assert melbourneCupLunch.dateString == '2022-11-01' assert melbourneCupLunch.dateTimeString == '2022-11-01T12:30:00' assert melbourneCupLunch.toLocalDate() == melbourneCup22 assert melbourneCupLunch.toLocalTime() == lunch assert melbourneCupLunch == melbourneCup22 << lunch	var melbourneCupLunch = new GregorianCalendar(2022, 10, 1, 12, 30).time assert melbourneCupLunch.timeString == '12:30:00 pm' // Locale specific assert melbourneCupLunch.dateString == '1/11/22' // Locale specific assert melbourneCupLunch.dateTimeString == '1/11/22, 12:30:00 pm' // Locale specific assert melbourneCupLunch.clearTime() == melbourneCup22

task

java.time

legacy

holidays

var melbourneCupLunch = LocalDateTime.of(2022, 11, 1, 12, 30)
assert melbourneCupLunch.timeString == '12:30:00'
assert melbourneCupLunch.dateString == '2022-11-01'
assert melbourneCupLunch.dateTimeString == '2022-11-01T12:30:00'
assert melbourneCupLunch.toLocalDate() == melbourneCup22
assert melbourneCupLunch.toLocalTime() == lunch
assert melbourneCupLunch == melbourneCup22 << lunch

var melbourneCupLunch = new GregorianCalendar(2022, 10, 1, 12, 30).time
assert melbourneCupLunch.timeString == '12:30:00 pm'              // Locale specific
assert melbourneCupLunch.dateString == '1/11/22'                  // Locale specific
assert melbourneCupLunch.dateTimeString == '1/11/22, 12:30:00 pm' // Locale specific
assert melbourneCupLunch.clearTime() == melbourneCup22

Processing zoned date and times

The legacy date classes have the concept of a TimeZone, predominantly used by the Calendar class. The new date classes has a similar concept but uses the ZoneId, ZoneOffset, and ZonedDateTime classes (among others).

The examples show various properties of zones and show that during the Melbourne cup breakfast, it would still be the night before (Halloween) in Los Angeles. They also show that those two zones are 18 hours apart at that time of the year.

task	java.time	legacy
holidays	var aet = ZoneId.of('Australia/Sydney') assert aet.fullName == 'Australian Eastern Time' && aet.shortName == 'AET' assert aet.offset == ZoneOffset.of('+11:00') var melbCupBreakfastInAU = ZonedDateTime.of(melbourneCup22, breakfast, aet) var melbCupBreakfast = LocalDateTime.of(melbourneCup22, breakfast) assert melbCupBreakfastInAU == melbCupBreakfast << aet var pst = ZoneId.of('America/Los_Angeles') assert pst.fullName == 'Pacific Time' && pst.shortName == 'GMT-08:00' var meanwhileInLA = melbCupBreakfastInAU.withZoneSameInstant(pst) assert halloween22 == meanwhileInLA.toLocalDate() assert aet.offset.hours - pst.offset.hours == 18	var aet = TimeZone.getTimeZone('Australia/Sydney') assert aet.displayName == 'Australian Eastern Standard Time' assert aet.observesDaylightTime() var melbourneCupBreakfast = new GregorianCalendar(aet).tap { set(year: 2022, month: 10, date: 1, hourOfDay: 7, minute: 30) } var pst = TimeZone.getTimeZone('America/Los_Angeles') assert pst.displayName == 'Pacific Standard Time' var meanwhileInLA = new GregorianCalendar(pst).tap { setTimeInMillis(melbourneCupBreakfast.timeInMillis) } assert meanwhileInLA.time.format('MMM dd', pst) == halloween22.format('MMM dd') assert aet.rawOffset / 3600000 - pst.rawOffset / 3600000 == 18

task

java.time

legacy

holidays

var aet = ZoneId.of('Australia/Sydney')
assert aet.fullName == 'Australian Eastern Time' && aet.shortName == 'AET'
assert aet.offset == ZoneOffset.of('+11:00')
var melbCupBreakfastInAU = ZonedDateTime.of(melbourneCup22, breakfast, aet)
var melbCupBreakfast = LocalDateTime.of(melbourneCup22, breakfast)
assert melbCupBreakfastInAU == melbCupBreakfast << aet
var pst = ZoneId.of('America/Los_Angeles')
assert pst.fullName == 'Pacific Time' && pst.shortName == 'GMT-08:00'
var meanwhileInLA = melbCupBreakfastInAU.withZoneSameInstant(pst)
assert halloween22 == meanwhileInLA.toLocalDate()
assert aet.offset.hours - pst.offset.hours == 18

var aet = TimeZone.getTimeZone('Australia/Sydney')
assert aet.displayName == 'Australian Eastern Standard Time'
assert aet.observesDaylightTime()
var melbourneCupBreakfast = new GregorianCalendar(aet).tap {
    set(year: 2022, month: 10, date: 1, hourOfDay: 7, minute: 30)
}
var pst = TimeZone.getTimeZone('America/Los_Angeles')
assert pst.displayName == 'Pacific Standard Time'
var meanwhileInLA = new GregorianCalendar(pst).tap {
    setTimeInMillis(melbourneCupBreakfast.timeInMillis)
}
assert meanwhileInLA.time.format('MMM dd', pst) == halloween22.format('MMM dd')
assert aet.rawOffset / 3600000 - pst.rawOffset / 3600000 == 18

Other useful classes

The new date classes offer a few more useful classes. Here are some of the common ones:

OffsetDateTime - like ZonedDateTime but with just an offset from UTC rather than a full time-zone
Instant - like OffsetDateTime but tied to UTC
YearMonth - like a LocalDate but with no day component
MonthDay - like a LocalDate but with no year component
Period - used to represent periods of time, e.g. `Period.ofDays(14), `Period.ofYears(2); see also the LocalDate example above.
Duration - a time-based amount of time, e.g. Duration.ofSeconds(30), Duration.ofHours(7); see also the LocalTime example above.

Conversions

It is useful to convert between the new and legacy classes. Some useful conversion methods are shown below with Groovy enhancements shown in blue.

From	Conversion method/property
GregorianCalendar	toInstant() toZonedDateTime() from(ZonedDateTime)
Calendar	toInstant() toZonedDateTime() toOffsetDateTime() toLocalDateTime() toLocalDate() toLocalTime() toOffsetTime() toDayOfWeek() toYear() toYearMonth() toMonth() toMonthDay() zoneOffset zoneId
Date	toInstant() from(Instant) toZonedDateTime() toOffsetDateTime() toLocalDateTime() toLocalDate() toLocalTime() toOffsetTime() toDayOfWeek() toYear() toYearMonth() toMonth() toMonthDay() zoneOffset zoneId
ZonedDateTime OffsetDateTime LocalDateTime LocalDate LocalTime	toDate() toCalendar()

SimpleDateFormat patterns

We saw several examples above using the format and parse methods. For the legacy date classes, numerous Groovy enhancements delegate to SimpleDateFormat. This class represents date/time formats using pattern strings. These are special letters to represent some time or date component mixed with escaped literal strings. The special letters are often repeated to represent the minimum size field for number components and whether the full or an abbreviated form is used for other components.

As an example, for the U.S. locale and U.S. Pacific Time time zone, the following pattern:

yyyy.MM.dd G 'at' HH:mm:ss z

would apply to the following text:

2001.07.04 AD at 12:08:56 PDT

Letter	Description
G	Era designator `AD`
y	Year `1996; 96`
Y	Week year (similar to year but allotted by weeks; the first/last few days of a year might be allotted to finish/start the last/previous week)
M	Month in year (context sensitive) `July; Jul; 07`
L	Month in year (standalone form) `July; Jul; 07`
w	Week in year `27`
W	Week in month `2`
D	Day in year `189`
d	Day in month `10`
F	Day of week in month `2`
E	Day name in week `Tuesday; Tue`
u	Day number of week (1 = Monday, ..., 7 = Sunday)
a	Am/pm marker `PM`
H	Hour in day (0-23) `0`
k	Hour in day (1-24) `24`
K	Hour in am/pm (0-11) `0`
h	Hour in am/pm (1-12) `12`
m	Minute in hour `30`
s	Second in minute `55`
S	Millisecond `978`
z	Time zone `Pacific Standard Time; PST; GMT-08:00`
Z	Time zone (RFC 822) `-0800`
X	Time zone (ISO 8601) `-08; -0800; -08:00`
'	to escape text put a single quote on either side
''	two single quotes for a literal single quote `'`

DateTimeFormatter patterns

Groovy’s format and parse enhancements for the new date classes delegate to the DateTimeFormatter class. Its behavior is similar to what we saw for SimpleDateFormat but with slightly different conversion letters:

Conversion suffix	Description
G	era `AD`
u	year `2004; 04`
y	year-of-era `2004; 04`
D	day-of-year `189`
M/L	month-of-year `7; 07; Jul; July; J`
d	day-of-month `10`
Q/q	quarter-of-year `3; 03; Q3; 3rd quarter`
Y	week-based-year `1996; 96`
w	week-of-week-based-year `27`
W	week-of-month `4`
E	day-of-week `Tue; Tuesday; T`
e/c	localized day-of-week `2; 02; Tue; Tuesday; T`
F	week-of-month `3`
a	am-pm-of-day `PM`
h	clock-hour-of-am-pm (1-12) `12`
K	hour-of-am-pm (0-11) `0`
k	clock-hour-of-am-pm (1-24) `0`
H	hour-of-day (0-23) `0`
m	minute-of-hour `30`
s	second-of-minute `55`
S	fraction-of-second `978`
A	milli-of-day `1234`
n	nano-of-second `987654321`
N	nano-of-day `1234000000`
V	time-zone ID `America/Los_Angeles; Z; -08:30`
z	time-zone name `Pacific Standard Time; PST`
O	localized zone-offset `GMT+8; GMT+08:00; UTC-08:00;`
X	zone-offset 'Z' for zero `Z; -08; -0830; -08:30; -083015; -08:30:15;`
x	zone-offset `+0000; -08; -0830; -08:30; -083015; -08:30:15;`
Z	zone-offset `+0000; -0800; -08:00;`
p	pad next
'	to escape text put a single quote on either side
''	two single quotes for a literal single quote `'`

Localized Patterns

JDK19 adds the ofLocalizedPattern(String requestedTemplate) method. The requested template is one or more regular expression pattern symbols ordered from the largest to the smallest unit, and consisting of the following patterns:

     "G{0,5}" +        // Era
     "y*" +            // Year
     "Q{0,5}" +        // Quarter
     "M{0,5}" +        // Month
     "w*" +            // Week of Week Based Year
     "E{0,5}" +        // Day of Week
     "d{0,2}" +        // Day of Month
     "B{0,5}" +        // Period/AmPm of Day
     "[hHjC]{0,2}" +   // Hour of Day/AmPm (refer to LDML for 'j' and 'C')
     "m{0,2}" +        // Minute of Hour
     "s{0,2}" +        // Second of Minute
     "[vz]{0,4}"       // Zone

The requested template is mapped to the closest of available localized format as defined by the Unicode LDML specification. Here is an example of usage:

var now = ZonedDateTime.now()
var columns = '%7s | %10s | %10s | %10s | %14s%n'
printf columns, 'locale', 'GDK', 'custom', 'local', 'both'
[locale('en', 'US'),
 locale('ro', 'RO'),
 locale('vi', 'VN')].each { locale ->
    Locale.default = locale
    var gdk = now.format('y-MM-dd')
    var custom = now.format(ofPattern('y-MM-dd'))
    var local = now.format(ofLocalizedDate(SHORT))
    var both = now.format(ofLocalizedPattern('yMM'))
    printf columns, locale, gdk, custom, local, both
}

Which has this output:

locale |        GDK |     custom |      local |           both
 en_US | 2022-12-18 | 2022-12-18 |   12/18/22 |        12/2022
 ro_RO | 2022-12-18 | 2022-12-18 | 18.12.2022 |        12.2022
 vi_VN | 2022-12-18 | 2022-12-18 | 18/12/2022 | tháng 12, 2022

Example credit: this example from Nicolai Parlog.

Formatter formats

The java.util.Formatter class is a base class in Java for various kinds of formatting. It can be used directly, via String.format, parse, printf, or Groovy’s sprintf. We saw several examples of using printf and parse formatting in the above examples.

The Formatter class has methods which take a format string as its first argument and zero or more additional arguments. The format string typically has one or more format specifiers (starting with a percent character) which indicate that a formatted version of one of the additional arguments should be placed into the string at that point. The general form of a format specifier is:

%[argument_index$][flag][width][.precision]conversion

Most of the parts are optional. The argument_index part is only used when referencing one of the additional arguments more than once (or out of order). The precision part is only used for floating point numbers. The flag part is used to indicate always include sign(+), zero-padding(0), locale-specific comma delimiters(,), and left justification(-). The width indicates the minimum number of characters for the output. The conversion indicates how the argument should be processed, e.g. as a numeric field, a date, a special character, or some other special processing. Upper and lowercase variants exist for most conversions which, for the uppercase variant, will call toUpperCase after the conversion is complete.

Conversion	Description
'b', 'B'	Treat as a boolean or false if null
'h', 'H'	Output the arguments hashcode as a hex string
's', 'S'	Treat as a String
'c', 'C'	Treat as a Unicode character
'd'	Treat as a decimal integer
'o'	Treat as an octal integer
'x', 'X'	Treat as a hexadecimal integer
'e', 'E'	Treat as a decimal number in scientific notation
'f'	Treat as a floating point number
'g', 'G'	Treat as a floating point in either decimal or scientific notation
'a', 'A'	Treat as a hexadecimal floating-point number
't', 'T'	Treat as the prefix for a date/time conversion
'%'	A literal percent
'n'	A line separator

When the date/time prefix is used, additional suffixes are applicable.

For formatting times:

Conversion suffix	Description
'H'	Hour of the day for the 24-hour clock as two digits `00 - 23`
'I'	Hour for the 12-hour clock as two digits `01 - 12`
'k'	Hour of the day for the 24-hour clock `0 - 23`
'l'	Hour for the 12-hour clock `1 - 12`
'M'	Minute within the hour as two digits `00 - 59`
'S'	Seconds within the minute as two digits `00 - 60` ("60" is used for leap seconds)
'L'	Millisecond within the second as three digits `000 - 999`
'N'	Nanosecond within the second as nine digits `000000000 - 999999999`
'p'	Locale-specific morning or afternoon marker in lower case, `am` or `pm` (The conversion prefix 'T' forces this output to upper case)
'z'	RFC 822 style numeric time zone offset from GMT `-0800` (Adjusted as needed for Daylight Saving Time)
'Z'	Abbreviated time zone
's'	Seconds since the beginning of the epoch starting at 1 January 1970 00:00:00 UTC
'Q'	Milliseconds since the beginning of the epoch starting at 1 January 1970 00:00:00 UTC

For formatting dates:

Conversion suffix	Description
'B'	Locale-specific full month name `January`
'b', 'h'	Locale-specific abbreviated month name `Jan`
'A'	Locale-specific full name of the day of the week `Sunday`
'a'	Locale-specific short name of the day of the week `Sun`
'C'	First two digits of four-digit year `00 - 99`
'Y'	Year as four digits `0092`
'y'	Last two digits of the year `00 - 99`
'j'	Day of year as three digits `001 - 366`
'm'	Month as two digits `01 - 13`
'd'	Day of month as two digits `01 - 31`
'e'	Day of month `1 - 31`

For formatting date/time compositions:

Conversion suffix	Description
'R'	Time formatted for the 24-hour clock as "%tH:%tM"
'T'	Time formatted for the 24-hour clock as "%tH:%tM:%tS"
'r'	Time formatted for the 12-hour clock as "%tI:%tM:%tS %Tp" The location of the morning or afternoon marker ('%Tp') may be locale-dependent.
'D'	Date formatted as "%tm/%td/%ty"
'F'	ISO 8601 date formatted as "%tY-%tm-%td"
'c'	Date and time formatted as "%ta %tb %td %tT %tZ %tY" `Sun Jul 21 15:17:00 EDT 1973`

Further information

Java 8 LocalDate, LocalDateTime, Instant tutorial
Introduction to the Java 8 Date/Time API
A guide to SimpleDateFormat
Joda-Time website
Guidelines for Date-Time/legacy date interoperability
Source code: examples for new date classes
Source code: examples for legacy date classes