fiscal_year 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b2a44c87e166920493e3723924cdf5c0a20cbdca0f148fb87e32a69aee645267
-  data.tar.gz: c6a17528d17f0cb3de8143a01227b06c7e8e527eee3a7ccc5677b637b7b3c41a
+  metadata.gz: 9f35e4820f8a076879f9e461f172479e79899b71b71e4933fb8598b8c91b0dd7
+  data.tar.gz: 7616d720fff1de8d186b6809dfc2c465be1dfee8637808f3d8c490c15b253327
 SHA512:
-  metadata.gz: 5ade0c96554bc2670317108bb74851ccfd485cf4932709eafe479de937db7fab43c864a8372d895b99d774cebe6bb08520191e5015ca4ef38eb1a85a19f3d8f4
-  data.tar.gz: ca421f4b2fa6fd74c319bab2eb739203391f3c71d0fcd592e78018a62900e72edfcc838e7480e1d2a80af1256266c9863e014ec2873f6e8169e1a52dfbe8d1c8
+  metadata.gz: 69d7ffc53eb33c6a65fabd20bd0b8757f40b71d11ce63a6a5754bb3af5312ad0641642a1701fc88820a7fd2764dfe29a140c045d0d524e4557d30304458c5ad5
+  data.tar.gz: d8c1ada946d9fd2e0ca21818e6885903fa99203a847c016759019828ca602ebf15cb03b8d94653c1801ff9a5c0ed942fa4c2afa224675563a875ad24fcf16e97

data/.rubocop.yml

@@ -1,5 +1,5 @@
 AllCops:
-  TargetRubyVersion: 2.6
+  TargetRubyVersion: 3.1
   Exclude:
     - 'Steepfile'
     - 'vendor/**/*'

data/CHANGELOG.md

@@ -1,3 +1,11 @@
+## [0.7.0] - 2024-07-11
+- add YARD comment.
+- fix `FiscalYear::YearToDate.quarter_range_by` logic.
+
+## [0.6.0] - 2024-05-15
+- [BREAK] Ruby 3.0.x, 2.7.x and 2.6.x has no longer support.
+- add `FiscalYear.range_by` method
+
 ## [0.5.0] - 2024-03-18
 - [BREAK] rename and move `FiscalYear::Half.normalize_year_by_month` to `FiscalYear.increase_year_by_month`
 - add `FiscalYear.decrease_year_by_month` method

data/lib/fiscal_year/half.rb

@@ -3,6 +3,7 @@
 module FiscalYear
   class Half
     class << self
+      # @return [Array<Integer>] the first half of the fiscal year.
       def first
         first = FiscalYear.halfs.first
         return first if first.is_a? Array
@@ -10,6 +11,7 @@ module FiscalYear
         []
       end
 
+      # @return [Array<Integer>] the second half of the fiscal year.
       def second
         second = FiscalYear.halfs.second
         return second if second.is_a? Array
@@ -17,14 +19,20 @@ module FiscalYear
         []
       end
 
+      # @param month [Integer] the month
+      # @return [Boolean] true if the month is in the first half of the fiscal year.
       def first?(month)
         FiscalYear.halfs.first.include?(month)
       end
 
+      # @param month [Integer] the month
+      # @return [Boolean] true if the month is in the second half of the fiscal year.
       def second?(month)
         !first?(month)
       end
 
+      # @param year [Integer] the calendar year
+      # @return [Range<Date>] the range of the first half of the fiscal year.
       def first_range_by(year)
         # care Date#parse 2 digit year auto complete.
         # 99 + 1 = 100, but expect 2000 this context.
@@ -37,6 +45,8 @@ module FiscalYear
         Date.parse("#{year}/#{first.first}/01")..Date.parse("#{end_year}/#{end_month}/01").end_of_month
       end
 
+      # @param year [Integer] the calendar year
+      # @return [Range<Date>] the range of the second half of the fiscal year.
       def second_range_by(year)
         # care Date#parse 2 digit year auto complete.
         # 99 + 1 = 100, but expect 2000 this context.
@@ -51,6 +61,8 @@ module FiscalYear
         Date.parse("#{start_year}/#{first_month}/01")..Date.parse("#{end_year}/#{end_month}/01").end_of_month
       end
 
+      # @param date [Date] the date
+      # @return [Range<Date>] the range of the half of the fiscal year by the date.
       def range_by(date)
         month = date.month
         year = date.year
@@ -60,6 +72,8 @@ module FiscalYear
         first?(month) ? first_range_by(year) : second_range_by(year)
       end
 
+      # @param half [Array<Integer>] the half of the fiscal year
+      # @return [Boolean] true if the any month of half are crossed calendar year.
       def cross_year_in_half?(half)
         FiscalYear.cross_year? && half.any? { |month| month == 12 }
       end

data/lib/fiscal_year/quarter.rb

@@ -3,28 +3,49 @@
 module FiscalYear
   class Quarter
     class << self
+      # @!method first
+      # @return [Array<Integer>] the first quarter of the fiscal year.
+
+      # @!method second
+      # @return [Array<Integer>] the second quarter of the fiscal year.
+
+      # @!method third
+      # @return [Array<Integer>] the third quarter of the fiscal year.
+
+      # @!method fourth
+      # @return [Array<Integer>] the fourth quarter of the fiscal year.
       %i[first second third fourth].each do |method_name|
         define_method(method_name) do
           FiscalYear.quarters.public_send(method_name)
         end
       end
 
+      # @param month [Integer] the month
+      # @return [Boolean] true if the month is in the first quarter of the fiscal year.
       def first?(month)
         FiscalYear.quarters.first.include?(month)
       end
 
+      # @param month [Integer] the month
+      # @return [Boolean] true if the month is in the second quarter of the fiscal year.
       def second?(month)
         FiscalYear.quarters.second.include?(month)
       end
 
+      # @param month [Integer] the month
+      # @return [Boolean] true if the month is in the third quarter of the fiscal year.
       def third?(month)
         FiscalYear.quarters.third.include?(month)
       end
 
+      # @param month [Integer] the month
+      # @return [Boolean] true if the month is in the fourth quarter of the fiscal year.
       def fourth?(month)
         FiscalYear.quarters.fourth.include?(month)
       end
 
+      # @param month [Integer] the month
+      # @return [Array<Integer>] the quarter month by the month.
       def months(month)
         months = FiscalYear.quarters.find { |a| a.include?(month) }
         raise ::StandardError if months.nil?
@@ -32,6 +53,8 @@ module FiscalYear
         months
       end
 
+      # @param date [Date] the date
+      # @return [Range<Date>] the range of the quarter by the date.
       def range_by(date)
         year = date.year
         this_quarter = months(date.month)
@@ -40,12 +63,16 @@ module FiscalYear
         Date.parse("#{year}/#{this_quarter.first}/01")..Date.parse("#{last_year}/#{this_quarter.last}/01").end_of_month
       end
 
+      # @param month [Integer] the month
+      # @return [Integer] the quarter number by the month.
       def quarter_num(month)
         rindex = FiscalYear.quarters.rindex(months(month))
 
         rindex.nil? ? 0 : (rindex + 1)
       end
 
+      # @param quarter [Array<Integer>] the quarter
+      # @return [Boolean] true if the quarter is crossed calendar year.
       def cross_year_in_quarter?(quarter)
         FiscalYear.cross_year? && quarter.any? { |month| month == 12 }
       end

data/lib/fiscal_year/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module FiscalYear
-  VERSION = "0.5.0"
+  VERSION = "0.7.0"
 end

data/lib/fiscal_year/year_to_date.rb

@@ -3,6 +3,14 @@
 module FiscalYear
   class YearToDate
     class << self
+      # @param date [Date] the date
+      # @return [Range<Date>] the range of the year to date.
+      # @example
+      #  FiscalYear::YearToDate.range_by(Date.parse("2021-08-01"))
+      #  => Thu, 01 Apr 2021..Tue, 31 Aug 2021
+      #
+      #  FiscalYear::YearToDate.range_by(Date.parse("2021-01-01"))
+      #  =>  Wed, 01 Apr 2020..Sun, 31 Jan 2021
       def range_by(date)
         year = date.year
         month = date.month
@@ -14,48 +22,60 @@ module FiscalYear
         end
       end
 
-      # TODO: fit to Abc size
-      def year_month_pairs(date) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      # @param date [Date] the date
+      # @return [Array<Array<Integer>, Array<Integer>>] the passed year and month pairs.
+      # @example
+      #  FiscalYear::YearToDate.year_month_pairs(Date.parse("2021-08-01"))
+      #  => [[2021, 4], [2021, 5], [2021, 6], [2021, 7], [2021, 8]]
+      #
+      #  FiscalYear::YearToDate.year_month_pairs(Date.parse("2021-01-01"))
+      #  => [
+      #       [2020, 4], [2020, 5], [2020, 6], [2020, 7], [2020, 8], [2020, 9],
+      #       [2020, 10], [2020, 11], [2020, 12], [2021, 1]
+      #     ]
+      def year_month_pairs(date)
         month = date.month
         month_index = FiscalYear.months.index(month)
         months = FiscalYear.months[(0..month_index)]
         raise StandardError if months.nil?
 
-        pair = []
-        [date.year].product(months).each do |e|
-          pair << if FiscalYear.cross_year_month?(month)
-                    (FiscalYear.cross_year_month?(e.second) ? e : [e.first - 1, e.second])
-                  else
-                    e
-                  end
+        [date.year].product(months).map do |e|
+          [FiscalYear.decrease_year_by_month(e.first, e.second), e.second]
         end
-
-        pair
       end
 
-      # TODO: fit to Abc size
-      def half_range_by(date) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      # @param date [Date] the date
+      # @return [Range<Date>] the range of the half year to date.
+      # @example
+      #  FiscalYear::YearToDate.half_range_by(Date.parse("2021-08-01"))
+      #  => Thu, 01 Apr 2021..Tue, 31 Aug 2021
+      #
+      #  FiscalYear::YearToDate.half_range_by(Date.parse("2021-01-01"))
+      #  =>  Thu, 01 Oct 2020..Sun, 31 Jan 2021
+      def half_range_by(date)
         year = date.year
         month = date.month
 
-        if Half.first?(month)
-          return (Date.parse("#{FiscalYear.cross_year_month?(month) ? year - 1 : year}/#{Half.first.first}/01")..
-            date.end_of_month.to_date
-                 )
-        end
+        beginning_year =
+          if Half.first?(month)
+            FiscalYear.cross_year_month?(month) ? year - 1 : year
+          else
+            Half.cross_year_in_half?(Half.second) ? FiscalYear.decrease_year_by_month(year, month) : year
+          end
 
-        Date.parse(
-          "#{
-              if FiscalYear::Half.cross_year_in_half?(Half.second) &&
-              FiscalYear.cross_year_month?(month)
-                year - 1
-              else
-                year
-              end
-            }/#{Half.second.first}"
-        )..date.end_of_month.to_date
+        half_method = Half.first?(month) ? :first : :second
+
+        Date.parse("#{beginning_year}/#{Half.public_send(half_method).first}/01")..date.end_of_month.to_date
       end
 
+      # @param date [Date] the date
+      # @return [Range<Date>] the range of the quarter to date.
+      # @example
+      #  FiscalYear::YearToDate.quarter_range_by(Date.parse("2021-08-01"))
+      #  => Thu, 01 Jul 2021..Tue, 31 Aug 2021
+      #
+      #  FiscalYear::YearToDate.quarter_range_by(Date.parse("2021-01-01"))
+      #  =>  Wed, 01 Jan 2020..Sun, 31 Jan 2021
       def quarter_range_by(date)
         year = date.year
         month = date.month
@@ -66,10 +86,10 @@ module FiscalYear
 
         quarter = Quarter.public_send(quarter_method)
 
-        (
-          Date.parse("#{FiscalYear.cross_year_month?(month) ? year - 1 : year}/#{quarter.first}/01")..
-          date.end_of_month.to_date
-        )
+        beginning_year =
+          Quarter.cross_year_in_quarter?(quarter) ? FiscalYear.decrease_year_by_month(year, month) : year
+
+        Date.parse("#{beginning_year}/#{quarter.first}/01")..date.end_of_month.to_date
       end
     end
   end

data/lib/fiscal_year.rb

@@ -14,24 +14,40 @@ module FiscalYear
   # @type ivar @config: FiscalYear::Config
   @config ||= FiscalYear::Config.new
   class << self
+    # @return [FiscalYear::Config]
     attr_reader :config
 
+    # configure start month of fiscal year.
+    #
+    # @yieldparam config [FiscalYear::Config]
+    # @example
+    #  FiscalYear.configure do |config|
+    #    config.start_month = 6
+    #  end
     def configure
       yield(@config) if block_given?
     end
 
+    # If the fiscal year start from 4, the month 1, 2, 3 are crossed year.
+    #
+    # @param month [Integer] the month to check, 1-12.
+    # @return [Boolean] true if the month is crossed year on calendar year.
+    # Determines if the month passed is beyond the year, By relative to the beginning month of the fiscal year.
     def cross_year_month?(month)
       cross_year_months.include?(month)
     end
 
+    # @return [Boolean] true if the fiscal year is crossed year.
     def cross_year?
       months.rindex(1) != 0
     end
 
+    # @return [Array<Integer>] the months of the fiscal year.
     def months
       (1..12).to_a.tap { |arr| arr.concat(arr.shift(@config.start_month - 1)) }
     end
 
+    # @return [Array<Integer>] the months of the crossed year.
     def cross_year_months
       return [] if @config.start_month == 1
 
@@ -43,16 +59,25 @@ module FiscalYear
       m
     end
 
+    # @return [Array(Array<Integer>, Array<Integer>)] the first half and the second half of the fiscal year.
     def halfs
       # @type self: singleton(FiscalYear)
       months.in_groups(2)
     end
 
+    # @return [Array(Array<Integer>, Array<Integer>, Array<Integer>, Array<Integer>)] the quarters of the fiscal year.
     def quarters
       # @type self: singleton(FiscalYear)
       months.in_groups(4)
     end
 
+    # increate the calendar year by month, if the month is crossed year.
+    #
+    # for example, in case of the fiscal year start from 4, you want to obtain calendar year of the month 1, 2, 3.
+    #
+    # @param year [Integer] the calendar year
+    # @param month [Integer] the month
+    # @return [Integer] year
     def increase_year_by_month(year, month)
       if FiscalYear.cross_year_month?(month)
         year + 1
@@ -61,6 +86,13 @@ module FiscalYear
       end
     end
 
+    # decrease the calendar year by month, if the month is crossed year.
+    #
+    # for example, in case of the fiscal year start from 4, you want to obtain fiscal year from the month 1, 2, 3.
+    #
+    # @param year [Integer] the calendar year
+    # @param month [Integer] the month
+    # @return [Integer] year
     def decrease_year_by_month(year, month)
       if FiscalYear.cross_year_month?(month)
         year - 1
@@ -68,5 +100,15 @@ module FiscalYear
         year
       end
     end
+
+    # @param date [Date] the date
+    # @return [Range<Date>] the range of the fiscal year between beginning and end by the date.
+    def range_by(date)
+      year = date.year
+      month = date.month
+      normalized_year = decrease_year_by_month(year, month)
+
+      FiscalYear::Half.first_range_by(normalized_year).first..FiscalYear::Half.second_range_by(normalized_year).last
+    end
   end
 end

data/sig/fiscal_year/config.rbs

@@ -1,5 +1,6 @@
 module FiscalYear
   class Config
     attr_reader start_month: Integer
+    def initialize: -> Integer
   end
 end

data/sig/fiscal_year.rbs

@@ -12,4 +12,5 @@ module FiscalYear
   def self.quarters: () -> [Array[Integer], Array[Integer], Array[Integer], Array[Integer]]
   def self.increase_year_by_month: (Integer, Integer) -> Integer
   def self.decrease_year_by_month: (Integer, Integer) -> Integer
+  def self.range_by: (Date) -> Range
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fiscal_year
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Tsubasa Kawajiri
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-03-18 00:00:00.000000000 Z
+date: 2024-07-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -70,7 +70,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.6.0
+      version: 3.1.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="