README.asciidoc

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