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