or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

date-time-operations.mdduration-period-operations.mdenum-extensions.mdindex.mdlegacy-conversion.mdparsing-factory-methods.mdtemporal-iteration.mdyear-month-operations.mdzone-offset-operations.md
tile.json

tessl/maven-org-codehaus-groovy--groovy-datetime

Groovy extensions for working with Java 8+ date/time types, providing convenient methods for temporal operations and transformations

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/org.codehaus.groovy/groovy-datetime@3.0.x

To install, run

npx @tessl/cli install tessl/maven-org-codehaus-groovy--groovy-datetime@3.0.0

index.mddocs/

Groovy DateTime Extensions

Groovy DateTime Extensions provides enhanced date/time functionality for Groovy applications by extending Java 8+ java.time API classes with convenient methods. The library offers operator overloading, iteration capabilities, formatting utilities, and seamless conversion between legacy java.util.Date/Calendar and modern java.time types.

Package Information

  • Package Name: org.codehaus.groovy:groovy-datetime
  • Package Type: maven
  • Language: Java/Groovy
  • Installation: Add to Gradle: implementation 'org.codehaus.groovy:groovy-datetime:3.0.25'

Core Imports

The package provides extension methods that are automatically available in Groovy when the library is in the classpath. Import temporal types as needed:

@Grab('org.codehaus.groovy:groovy-datetime:3.0.25')

import java.time.*
import java.time.format.*
import java.time.temporal.*

Java usage requires static imports:

import static org.apache.groovy.datetime.extensions.DateTimeExtensions.*;
import static org.apache.groovy.datetime.extensions.DateTimeStaticExtensions.*;

Basic Usage

import java.time.*

// Operator overloading for arithmetic
def today = LocalDate.now()
def nextWeek = today + 7  // Add 7 days
def lastMonth = today - 30  // Subtract 30 days

// Iteration over date ranges
def start = LocalDate.of(2024, 1, 1)
def end = start + 5
start.upto(end) { date ->
    println date.dayOfWeek
}

// Formatting with patterns
def datetime = LocalDateTime.now()
println datetime.format('yyyy-MM-dd HH:mm:ss')
println datetime.dateString  // ISO format

// Static parsing
def parsed = LocalDate.parse('2024-12-25', 'yyyy-MM-dd')

// Conversion between legacy and modern types
def legacyDate = new Date()
def localDate = legacyDate.toLocalDate()
def backToDate = localDate.toDate()

// Zone and offset operations  
def zoned = LocalDateTime.now() << ZoneId.of('America/New_York')
def offset = LocalTime.now() << ZoneOffset.ofHours(-5)

Architecture

The library consists of two main extension classes:

  • DateTimeExtensions: Instance methods added to java.time types (formatting, arithmetic, iteration, conversion)
  • DateTimeStaticExtensions: Static factory and parsing methods for java.time types

Extensions follow Groovy conventions for operator overloading:

  • + and - operators for temporal arithmetic
  • ++ and -- for next/previous operations
  • << (left shift) for combining temporal objects
  • >> (right shift) for calculating periods/durations between objects
  • [] (subscript) for accessing temporal fields and units

Capabilities

Core Date/Time Operations

Essential operations for date, time, and datetime manipulation including arithmetic, formatting, and navigation.

// LocalDate operations
LocalDate plus(LocalDate self, long days)
LocalDate minus(LocalDate self, long days)
String format(LocalDate self, String pattern)
String getDateString(LocalDate self)

// LocalDateTime operations  
LocalDateTime plus(LocalDateTime self, long seconds)
LocalDateTime clearTime(LocalDateTime self)
String getDateTimeString(LocalDateTime self)

// LocalTime operations
LocalTime plus(LocalTime self, long seconds)
String getTimeString(LocalTime self)

Date and Time Operations

Zoned and Offset Date/Time

Working with time zones, offsets, and zone-aware temporal operations.

// Zone operations
ZonedDateTime leftShift(LocalDateTime self, ZoneId zone)
OffsetDateTime leftShift(LocalDateTime self, ZoneOffset offset)
ZoneOffset getOffset(ZoneId self)
String getShortName(ZoneId self)

// Offset operations
int getHours(ZoneOffset self)
TimeZone toTimeZone(ZoneOffset self)

Zoned and Offset Operations

Temporal Iteration and Ranges

Iterating over temporal ranges with custom units and step sizes.

// Iteration methods
void upto(Temporal from, Temporal to, Closure closure)
void upto(Temporal from, Temporal to, TemporalUnit unit, Closure closure)
void downto(Temporal from, Temporal to, Closure closure)
TemporalAmount rightShift(Temporal self, Temporal other)

Temporal Iteration

Duration and Period Arithmetic

Mathematical operations on durations and periods with operator overloading.

// Duration operations
Duration plus(Duration self, long seconds)
Duration multiply(Duration self, long scalar)
Duration negative(Duration self)
boolean isPositive(Duration self)

// Period operations  
Period plus(Period self, long days)
Period multiply(Period self, int scalar)
Period positive(Period self)

Duration and Period Operations

Parsing and Static Methods

Static parsing methods with custom patterns and factory methods.

// Static parsing methods
LocalDate parse(LocalDate type, CharSequence text, String pattern)
LocalDateTime parse(LocalDateTime type, CharSequence text, String pattern)
ZonedDateTime parse(ZonedDateTime type, CharSequence text, String pattern)

// Factory methods
ZoneOffset systemDefault(ZoneOffset type)
Period between(Period type, Year startInclusive, Year endExclusive)

Parsing and Factory Methods

Legacy Date/Calendar Conversion

Bidirectional conversion between legacy java.util.Date/Calendar and modern java.time types.

// Calendar to java.time conversions
LocalDate toLocalDate(Calendar self)
LocalDateTime toLocalDateTime(Calendar self)
ZonedDateTime toZonedDateTime(Calendar self)
ZoneId getZoneId(Calendar self)

// java.time to legacy conversions
Date toDate(LocalDate self)
Calendar toCalendar(LocalDateTime self)

Legacy Conversion

Enum Extensions

Enhanced functionality for DayOfWeek and Month enums with arithmetic and utility methods.

// DayOfWeek operations
DayOfWeek plus(DayOfWeek self, int days)
boolean isWeekend(DayOfWeek self)
boolean isWeekday(DayOfWeek self)

// Month operations
Month plus(Month self, int months)
MonthDay leftShift(Month self, int dayOfMonth)

Enum Extensions

Year and YearMonth Operations

Comprehensive operations for Year and YearMonth temporal objects including arithmetic, period calculations, and temporal object creation.

// Year operations
Year plus(Year self, long years)
Year minus(Year self, long years)
Period rightShift(Year self, Year year)
YearMonth leftShift(Year self, Month month)

// YearMonth operations
YearMonth plus(YearMonth self, long months)
YearMonth minus(YearMonth self, long months)
LocalDate leftShift(YearMonth self, int dayOfMonth)
Period rightShift(YearMonth self, YearMonth other)

Year and YearMonth Operations

Types

// All standard java.time types are supported:
// LocalDate, LocalTime, LocalDateTime
// OffsetTime, OffsetDateTime  
// ZonedDateTime, Instant
// Duration, Period
// Year, YearMonth, MonthDay
// DayOfWeek, Month
// ZoneId, ZoneOffset
// TemporalAccessor, TemporalAmount, Temporal
// TemporalField, TemporalUnit
// DateTimeFormatter, FormatStyle