Java Date Generation with Lamma Date Library (1)

• Download source - 3.1 KB

Introduction

This tip discusses the basic date manipulation with Lamma date library in Java.

Background

Pre JDK8's standard date and time library is known for its limited functionality and a number of design problems. Joda time is in general a very good and mature replacement but its API is sometimes a bit of an overkill for some simple use cases. Lamma date library is a new date library developed recently that aims to provide a simpler and neater API from basic date manipulation to complicated schedule generation.

Using the Code

Date Object Creation

Instance of io.lamma.Date can be created from (year, month, day) integer tuple or a string of ISO 8601 format. Following 3 ways are interchangeable:

new Date(2014, 5, 5));    // create with constructor

import static io.lamma.LammaJavaImports.date; 

date(2014, 10, 7);        // create with helper method
date("2014-10-07");       // create with ISO 8601 String

Comparison

Date can be compared by isBefore, isAfter, isOnOrBefore and isOnOrAfter. Because there is no time and timezone information in the io.lamma.Date object, there won't be any ambiguity on the definition of same day. For example:

date(2014, 7, 7).isBefore(date(2014, 7, 8)); // => true

Day Operations

Calculate days between two days:

date(2016, 3, 3).minus(date(2016, 2, 25));  // => 7, note there is a leap day (2016-02-29) in between

Shift by days with plusDays and minusDays:

date(2016, 2, 29).plusDays(5);
date(2016, 2, 29).minusDays(5);

Week Operations

Check day of week with is method:

date(2014, 7, 7).is(DayOfWeek.MONDAY);  // true

Get previous / next day of week with respect to a given date:

date(2014, 7, 7).next(DayOfWeek.MONDAY);   // => Date(2014,7,14)
date(2014, 7, 7).previous(DayOfWeek.MONDAY);  // => Date(2014,6,30)
date(2014, 7, 7).nextOrSame(DayOfWeek.MONDAY);  // => Date(2014,7,7)
date(2014, 7, 7).previousOrSame(DayOfWeek.WEDNESDAY); // => Date(2014,7,2)

Get by day of week within the current week. In Lamma, a week begins with Monday according to ISO 8601:

date(2014, 7, 7).withDayOfWeek(DayOfWeek.MONDAY);  // => Date(2014,7,7)
date(2014, 7, 7).withDayOfWeek(DayOfWeek.SUNDAY);  //=> Date(2014,7,13)

daysOfWeek4j will return an Iterable<Date> containing all days of current week. The reason why there is a 4j suffix is because calling daysOfWeek will return a Scala Iterable[Date], which is not quite Java friendly.

date(2014, 7, 7).daysOfWeek4j(); //  => [Date(2014,7,7), Date(2014,7,8), 
        //Date(2014,7,9), Date(2014,7,10), Date(2014,7,11), Date(2014,7,12), Date(2014,7,13)]

Similarly, shift by weeks with plusWeeks and minusWeeks:

date(2016, 2, 29).plusWeeks(2);    // => Date(2016,3,14)
date(2016, 2, 29).minusWeeks(3);   // => Date(2016,2,8)

Month Operations

maxDayOfMonth will return the maximum calendar days of the current month. Following code will return 29. Again, the leap day is considered. Lamma will take care of leap year / leap day whenever necessary.

date(2016, 2, 5).maxDayOfMonth(); 

daysOfMonth4j returns an Iterable<Date> containing all days of current month:

date(2014, 7, 7).daysOfMonth4j(); // => [Date(2014,7,1), Date(2014,7,2), 
        // Date(2014,7,3), ... Date(2014,7,31)]

and sameWeekdaysOfMonth4j returns an Iterable<Date> containing all days with the same day of week of current month.

date(2016, 2, 5).sameWeekdaysOfMonth4j(); // all Fridays in Feb, 
        // 2016 => [Date(2016,2,5), Date(2016,2,12), Date(2016,2,19), Date(2016,2,26)]

Similarly, shift by months with plusMonths and minusMonths. Month end will be handled properly.

date(2016, 1, 31).plusMonths(3);   // => Date(2016,4,30) (note how month end is handled)
date(2016, 1, 10).minusMonths(5);  // => Date(2015,8,10)

Year Operations

maxDayOfYear returns the maximum calendar days of current year:

date(2016, 2, 5).maxDayOfYear(); // => 366

dayOfYear returns the ordinal day of current year:

date(2016, 2, 5).dayOfYear(); // => 36. 2016-02-05 is the 36th day of 2016

Similarly, daysOfYear4j returns an Iterable<Date> containing all days of current year:

date(2016, 2, 5).daysOfYear4j(); // => [Date(2016,1,1), Date(2016,1,2), 
            // Date(2016,1,3) ... Date(2016,12,31)]

and sameWeekdaysOfYear4j returns an Iterable<Date> containing all days of current year with the same day of week.

date(2016, 2, 5).sameWeekdaysOfYear4j(); // => [Date(2016,1,1), Date(2016,1,8), 
                // Date(2016,1,15) ... Date(2016,12,30)]

How to Run Sample Code

The sample project requires maven to run. Once you have maven installed, go to lamma-java-1/ (the one with pom.xml) and execute the following command:

mvn exec:java -Dexec.mainClass="io.lammasample1.Sample"

Facts about Lamma Date Library

• io.lamma.Date instance is Immutable and thus thread-safe.
• io.lamma.Date#toString / hashCode and equals are well implemented, thus can be safely used in Set / HashMap etc.
• Lamma date is designed for basic date manipulations like comparison, shifting, etc. (covered above).
• Lamma date is designed for date generations like: give me every other Friday from 2014-05-01 to 2014-07-30 (will be covered in coming articles)
• Lamma date is designed for complicated schedule generation. For example, generate full mortgage schedule from 2014-07-01 to 2015-06-30 where payment dates are the last working day of every quarter and the settlement dates are two working days after payment date. UK public holidays and weekends are considered as non working days (will be covered in coming articles).
• Lamma date is NOT designed for time related or timezone related calculations.