com.cedarsoftware.util

Class DateUtilities

java.lang.Object

com.cedarsoftware.util.DateUtilities

public final class DateUtilities
extends Object

Utility for parsing String dates with optional times, especially when the input String formats may be inconsistent. This will parse the following formats:

 12-31-2023, 12/31/2023, 12.31.2023     mm is 1-12 or 01-12, dd is 1-31 or 01-31, and yyyy can be 0000 to 9999.
                                  
 2023-12-31, 2023/12/31, 2023.12.31     mm is 1-12 or 01-12, dd is 1-31 or 01-31, and yyyy can be 0000 to 9999.
                                  
 January 6th, 2024                Month (3-4 digit abbreviation or full English name), white-space and optional comma,
                                  day of month (1-31) with optional suffixes 1st, 3rd, 22nd, whitespace and
                                  optional comma, and yyyy (0000-9999)

 17th January 2024                day of month (1-31) with optional suffixes (e.g. 1st, 3rd, 22nd),
                                  Month (3-4 digit abbreviation or full English name), whites space and optional comma,
                                  and yyyy (0000-9999)

 2024 January 31st                4 digit year, white space and optional comma, Month (3-4 digit abbreviation or full
                                  English name), white space and optional command, and day of month with optional
                                  suffixes (1st, 3rd, 22nd)

 Sat Jan 6 11:06:10 EST 2024      Unix/Linux style.  Day of week (3-letter or full name), Month (3-4 digit or full
                                  English name), time hh:mm:ss, TimeZone (Java supported Timezone names), Year
 

All dates can be followed by a Time, or the time can precede the Date. Whitespace or a single letter T must separate the date and the time for the non-Unix time formats. The Time formats supported:

 hh:mm                            hours (00-23), minutes (00-59).  24 hour format.
 
 hh:mm:ss                         hours (00-23), minutes (00-59), seconds (00-59).  24 hour format.

 hh:mm:ss.sssss                   hh:mm:ss and fractional seconds. Variable fractional seconds supported.

 hh:mm:offset -or-                offset can be specified as +HH:mm, +HHmm, +HH, -HH:mm, -HHmm, -HH, or Z (GMT)
 hh:mm:ss.sss:offset              which will match: "12:34", "12:34:56", "12:34.789", "12:34:56.789", "12:34+01:00",
                                  "12:34:56+1:00", "12:34-01", "12:34:56-1", "12:34Z", "12:34:56Z"

 hh:mm:zone -or-                  Zone can be specified as Z (Zulu = UTC), older short forms: GMT, EST, CST, MST,
 hh:mm:ss.sss:zone                PST, IST, JST, BST etc. as well as the long forms: "America/New_York", "Asia/Saigon",
                                  etc. See ZoneId.getAvailableZoneIds().
 

DateUtilities will parse Epoch-based integer-based value. It is considered number of milliseconds since Jan, 1970 GMT.

 "0" to                           A string of numeric digits will be parsed and returned as the number of milliseconds
 "999999999999999999"             the Unix Epoch, January 1st, 1970 00:00:00 UTC.
 

On all patterns above (excluding the numeric epoch millis), if a day-of-week (e.g. Thu, Sunday, etc.) is included (front, back, or between date and time), it will be ignored, allowing for even more formats than listed here. The day-of-week is not be used to influence the Date calculation.

Author:

John DeRegnaucourt ([email protected])
Copyright (c) Cedar Software LLC

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

License

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Method Summary

Modifier and Type	Method and Description
static Date	parseDate(String dateStr) Original API.
static ZonedDateTime	parseDate(String dateStr, ZoneId defaultZoneId, boolean ensureDateTimeAlone) Main API.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

parseDate

public static Date parseDate(String dateStr)

Original API. If the date-time given does not include a timezone offset or name, then ZoneId.systemDefault() will be used. We recommend using parseDate(String, ZoneId, boolean) version, so you can control the default timezone used when one is not specified.

Parameters:

dateStr - String containing a date. If there is excess content, it will throw an IllegalArgumentException.

Returns:

Date instance that represents the passed in date. See comments at top of class for supported formats. This API is intended to be super flexible in terms of what it can parse. If a null or empty String is passed in, null will be returned.

parseDate

public static ZonedDateTime parseDate(String dateStr,
                                      ZoneId defaultZoneId,
                                      boolean ensureDateTimeAlone)

Main API. Retrieve date-time from passed in String. The boolean ensureDateTimeAlone, if set true, ensures that no other non-date content existed in the String.

Parameters:

dateStr - String containing a date. See DateUtilities class Javadoc for all the supported formats.

defaultZoneId - ZoneId to use if no timezone offset or name is given. Cannot be null.

ensureDateTimeAlone - If true, if there is excess non-Date content, it will throw an IllegalArgument exception.

Returns:

ZonedDateTime instance converted from the passed in date String. See comments at top of class for supported formats. This API is intended to be super flexible in terms of what it can parse. If a null or empty String is passed in, null will be returned.