= Fiscal-Year image:https://img.shields.io/badge/email-%40metio-brightgreen.svg?style=social&label=mail["Discuss on Google Groups", link="https://groups.google.com/forum/#!forum/metio"] image:https://img.shields.io/badge/irc-%23metio.wtf-brightgreen.svg?style=social&label=IRC["Chat on IRC", link="http://webchat.freenode.net/?channels=metio.wtf"]
Sebastian Hoß <https://github.com/sebhoss[@sebhoss]>
:github-org: sebhoss
:project-name: fiscal-year
:project-group: de.xn--ho-hia.utils.fiscal_year
:coverity-project: 9338
:codacy-project: cd259740862044fa9d06e7788b7d577f
:toc:
:toc-placement: preamble

image:https://img.shields.io/badge/license-cc%20zero-000000.svg?style=flat-square["CC Zero", link="http://creativecommons.org/publicdomain/zero/1.0/"]
pass:[<span class="image"><a class="image" href="https://maven-badges.herokuapp.com/maven-central/de.xn--ho-hia.utils.fiscal_year/fiscal-year"><img src="https://img.shields.io/maven-central/v/de.xn--ho-hia.utils.fiscal_year/fiscal-year.svg?style=flat-square" alt="Maven Central"></a></span>]
pass:[<span class="image"><a class="image" href="https://www.javadoc.io/doc/de.xn--ho-hia.utils.fiscal_year/fiscal-year"><img src="https://www.javadoc.io/badge/de.xn--ho-hia.utils.fiscal_year/fiscal-year.svg?style=flat-square&color=blue" alt="Read JavaDocs"></a></span>]
image:https://reposs.herokuapp.com/?path={github-org}/{project-name}&style=flat-square["Repository size"]
image:https://www.openhub.net/p/{project-name}/widgets/project_thin_badge.gif["Open Hub statistics", link="https://www.openhub.net/p/{project-name}"]

image:https://img.shields.io/jenkins/s/https/build.metio.wtf/job/{github-org}/job/{project-name}/job/{project-name}_verify.svg?style=flat-square["Build Status", link="https://build.metio.wtf/job/{github-org}/job/{project-name}/"]
pass:[<span class="image"><a class="image" href="https://quality.metio.wtf/dashboard?id=de.xn--ho-hia.utils.fiscal_year%3Afiscal-year"><img src="https://img.shields.io/sonar/https/quality.metio.wtf/de.xn--ho-hia.utils.fiscal_year:fiscal-year/coverage.svg?style=flat-square" alt="Code Coverage"></a></span>]
pass:[<span class="image"><a class="image" href="https://quality.metio.wtf/dashboard?id=de.xn--ho-hia.utils.fiscal_year%3Afiscal-year"><img src="https://img.shields.io/sonar/https/quality.metio.wtf/de.xn--ho-hia.utils.fiscal_year:fiscal-year/tech_debt.svg?style=flat-square" alt="Technical Debt"></a></span>]
image:https://img.shields.io/coverity/scan/{coverity-project}.svg?style=flat-square["Coverity Scan Result", link="https://scan.coverity.com/projects/{github-org}-{project-name}"]
image:https://img.shields.io/codacy/grade/{codacy-project}.svg?style=flat-square["Codacy Code Quality", link="https://www.codacy.com/app/mail_7/{project-name}"]
image:https://img.shields.io/badge/forkable-yes-brightgreen.svg?style=flat-square["Can this project be forked?", link="https://basicallydan.github.io/forkability/?u={github-org}&r={project-name}"]
image:https://img.shields.io/maintenance/yes/2017.svg?style=flat-square["Is this thing still maintained?"]
image:https://img.shields.io/bountysource/team/metio/activity.svg?style=flat-square["Bounties on open tickets", link="https://www.bountysource.com/teams/metio"]

Your company doesn't work from January 1 to December 31? Try fiscal-year, a small Java library which converts calendar-year based dates to corresponding dates in a link:http://en.wikipedia.org/wiki/Fiscal_year[fiscal year].

== Features

* Immutable data structure
* Convert from/to Java 8 `LocalDate`
* Math operations like `plusDays`, `minusWeeks`
* Factories to create/configure

== Development Status

All currently required feature are implemented. This project is in maintenance mode.

== Usage

First create a `FiscalYearFactory` which holds the configuration of your company's fiscal year:

[source, java]
----
// fiscal year starts at month 11 of the 'previous' year
FiscalYearFactory earlyYearFactory = FiscalYears.earlyFiscalYear(11);

// fiscal year starts at month 3 in the 'current' year
FiscalYearFactory lateYearFactory = FiscalYears.lateFiscalYear(3);
----

Then use this factory to convert a calendar-year based `LocalDate` to a corresponding `FiscalDate`:

[source, java]
----
LocalDate calendarDate = LocalDate.now();
FiscalDate fiscalDate = factory.createFromCalendarDate(calendarDate);
----

Use fiscal-year based values directly to create an instance of `FiscalDate`:

[source, java]
----
FiscalDate fiscalDate = factory.create(2015, 3, 25);
----

Query the newly created `FiscalDate` to retrieve the usual suspects of attributes:

[source, java]
----
int fiscalYear = fiscalDate.getFiscalYear();
int fiscalMonth = fiscalDate.getFiscalMonth();
int fiscalDayOfYear = fiscalDate.getFiscalDayOfYear();
int fiscalWeekOfWeekyear = fiscalDate.getFiscalWeekOfWeekyear();

int calendarYear = fiscalDate.getCalendarYear();
int calendarMonth = fiscalDate.getCalendarMonth();
int calendarDayOfMonth = fiscalDate.getCalendarDayOfMonth();
int calendarDayOfYear = fiscalDate.getCalendarDayOfYear();
int calendarWeekOfWeekyear = fiscalDate.getCalendarWeekOfWeekyear();
----

Do some math with dates as follows:

[source, java]
----
FiscalDate newDate = fiscalDate.plusYears(int years);
FiscalDate newDate = fiscalDate.plusMonths(int months);
FiscalDate newDate = fiscalDate.plusWeeks(int weeks);
FiscalDate newDate = fiscalDate.plusDays(int days);
FiscalDate newDate = fiscalDate.minusYears(int years);
FiscalDate newDate = fiscalDate.minusMonths(int months);
FiscalDate newDate = fiscalDate.minusWeeks(int weeks);
FiscalDate newDate = fiscalDate.minusDays(int days);
----

Or finally convert it back to a `LocalDate`:

[source, java]
----
LocalDate calendarDate = fiscalDate.asLocalDate();
----

=== Integration

To use this project just declare the following dependency inside your POM:

[source, xml, subs="attributes,verbatim"]
----
<dependency>
  <groupId>{project-group}</groupId>
  <artifactId>{project-name}</artifactId>
  <version>${version.fiscal-year}</version>
</dependency>
----

Replace `${version.fiscal-year}` with the link:++http://search.maven.org/#search%7Cga%7C1%7Cg%3Ade.xn--ho-hia.utils.fiscal_year%20a%3Afiscal-year++[latest release]. This project follows the link:http://semver.org/[semantic versioning guidelines].

=== Compatibility

This project is compatible with the following Java versions:

.Java compatibility
|===
| | 1.X.Y | 2.X.Y | 3.X.Y

| Java 8
| ✓
| ✓
| ✓
|===

== License

To the extent possible under law, the author(s) have dedicated all copyright
and related and neighboring rights to this software to the public domain
worldwide. This software is distributed without any warranty.

You should have received a copy of the CC0 Public Domain Dedication along
with this software. If not, see http://creativecommons.org/publicdomain/zero/1.0/.

== Mirrors

* https://github.com/sebhoss/{project-name}
* https://bitbucket.org/sebhoss/{project-name}
* https://gitlab.com/sebastian.hoss/{project-name}
* http://v2.pikacode.com/sebhoss/{project-name}
* http://repo.or.cz/fiscal-year.java.git