README.asciidoc

   1 = 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"]
   2 Sebastian Hoß <https://github.com/sebhoss[@sebhoss]>
   3 :github-org: sebhoss
   4 :project-name: fiscal-year
   5 :project-group: de.xn--ho-hia.utils.fiscal_year
   6 :coverity-project: 9338
   7 :codacy-project: cd259740862044fa9d06e7788b7d577f
   8 :toc:
   9 :toc-placement: preamble
  10
  11 image:https://img.shields.io/badge/license-cc%20zero-000000.svg?style=flat-square["CC Zero", link="http://creativecommons.org/publicdomain/zero/1.0/"]
  12 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>]
  13 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>]
  14 image:https://reposs.herokuapp.com/?path={github-org}/{project-name}&style=flat-square["Repository size"]
  15 image:https://www.openhub.net/p/{project-name}/widgets/project_thin_badge.gif["Open Hub statistics", link="https://www.openhub.net/p/{project-name}"]
  16
  17 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}/"]
  18 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>]
  19 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>]
  20 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}"]
  21 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}"]
  22 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}"]
  23 image:https://img.shields.io/maintenance/yes/2017.svg?style=flat-square["Is this thing still maintained?"]
  24 image:https://img.shields.io/bountysource/team/metio/activity.svg?style=flat-square["Bounties on open tickets", link="https://www.bountysource.com/teams/metio"]
  25
  26 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].
  27
  28 == Features
  29
  30 * Immutable data structure
  31 * Convert from/to Java 8 `LocalDate`
  32 * Math operations like `plusDays`, `minusWeeks`
  33 * Factories to create/configure
  34
  35 == Development Status
  36
  37 All currently required feature are implemented. This project is in maintenance mode.
  38
  39 == Usage
  40
  41 First create a `FiscalYearFactory` which holds the configuration of your company's fiscal year:
  42
  43 [source, java]
  44 ----
  45 // fiscal year starts at month 11 of the 'previous' year
  46 FiscalYearFactory earlyYearFactory = FiscalYears.earlyFiscalYear(11);
  47
  48 // fiscal year starts at month 3 in the 'current' year
  49 FiscalYearFactory lateYearFactory = FiscalYears.lateFiscalYear(3);
  50 ----
  51
  52 Then use this factory to convert a calendar-year based `LocalDate` to a corresponding `FiscalDate`:
  53
  54 [source, java]
  55 ----
  56 LocalDate calendarDate = LocalDate.now();
  57 FiscalDate fiscalDate = factory.createFromCalendarDate(calendarDate);
  58 ----
  59
  60 Use fiscal-year based values directly to create an instance of `FiscalDate`:
  61
  62 [source, java]
  63 ----
  64 FiscalDate fiscalDate = factory.create(2015, 3, 25);
  65 ----
  66
  67 Query the newly created `FiscalDate` to retrieve the usual suspects of attributes:
  68
  69 [source, java]
  70 ----
  71 int fiscalYear = fiscalDate.getFiscalYear();
  72 int fiscalMonth = fiscalDate.getFiscalMonth();
  73 int fiscalDayOfYear = fiscalDate.getFiscalDayOfYear();
  74 int fiscalWeekOfWeekyear = fiscalDate.getFiscalWeekOfWeekyear();
  75
  76 int calendarYear = fiscalDate.getCalendarYear();
  77 int calendarMonth = fiscalDate.getCalendarMonth();
  78 int calendarDayOfMonth = fiscalDate.getCalendarDayOfMonth();
  79 int calendarDayOfYear = fiscalDate.getCalendarDayOfYear();
  80 int calendarWeekOfWeekyear = fiscalDate.getCalendarWeekOfWeekyear();
  81 ----
  82
  83 Do some math with dates as follows:
  84
  85 [source, java]
  86 ----
  87 FiscalDate newDate = fiscalDate.plusYears(int years);
  88 FiscalDate newDate = fiscalDate.plusMonths(int months);
  89 FiscalDate newDate = fiscalDate.plusWeeks(int weeks);
  90 FiscalDate newDate = fiscalDate.plusDays(int days);
  91 FiscalDate newDate = fiscalDate.minusYears(int years);
  92 FiscalDate newDate = fiscalDate.minusMonths(int months);
  93 FiscalDate newDate = fiscalDate.minusWeeks(int weeks);
  94 FiscalDate newDate = fiscalDate.minusDays(int days);
  95 ----
  96
  97 Or finally convert it back to a `LocalDate`:
  98
  99 [source, java]
 100 ----
 101 LocalDate calendarDate = fiscalDate.asLocalDate();
 102 ----
 103
 104 === Integration
 105
 106 To use this project just declare the following dependency inside your POM:
 107
 108 [source, xml, subs="attributes,verbatim"]
 109 ----
 110 <dependency>
 111   <groupId>{project-group}</groupId>
 112   <artifactId>{project-name}</artifactId>
 113   <version>${version.fiscal-year}</version>
 114 </dependency>
 115 ----
 116
 117 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].
 118
 119 === Compatibility
 120
 121 This project is compatible with the following Java versions:
 122
 123 .Java compatibility
 124 |===
 125 | | 1.X.Y | 2.X.Y | 3.X.Y
 126
 127 | Java 8
 128 | ✓
 129 | ✓
 130 | ✓
 131 |===
 132
 133 == License
 134
 135 To the extent possible under law, the author(s) have dedicated all copyright
 136 and related and neighboring rights to this software to the public domain
 137 worldwide. This software is distributed without any warranty.
 138
 139 You should have received a copy of the CC0 Public Domain Dedication along
 140 with this software. If not, see http://creativecommons.org/publicdomain/zero/1.0/.
 141
 142 == Mirrors
 143
 144 * https://github.com/sebhoss/{project-name}
 145 * https://bitbucket.org/sebhoss/{project-name}
 146 * https://gitlab.com/sebastian.hoss/{project-name}
 147 * http://v2.pikacode.com/sebhoss/{project-name}
 148 * http://repo.or.cz/fiscal-year.java.git