fiscal_year 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0917960fc403b45d283863bad77ac8e35fc8b5a3c216a13f1ca2cdb68c95410a'
-  data.tar.gz: 68506d80a59973356f41d5bd1c55af3164542378ec8d9bea7d31be14bd90e302
+  metadata.gz: 9f35e4820f8a076879f9e461f172479e79899b71b71e4933fb8598b8c91b0dd7
+  data.tar.gz: 7616d720fff1de8d186b6809dfc2c465be1dfee8637808f3d8c490c15b253327
 SHA512:
-  metadata.gz: 74e0c8c7ddff795d9c64754dde60b462073f45afd04892dcad3e1595970d1bc2a7ac4ebf3bc464ccc112f10bfe33393023bf008cf08b349c27839994a00c4199
-  data.tar.gz: 50c1f1e00478c28ee72bc301ab8ab5fe42c1d142e822cc2d8747ff25f631ff62aff2e3e457e8bb852cde09676b38c0826057f8dedd503e5ad8ad2c3ad37a7e90
+  metadata.gz: 69d7ffc53eb33c6a65fabd20bd0b8757f40b71d11ce63a6a5754bb3af5312ad0641642a1701fc88820a7fd2764dfe29a140c045d0d524e4557d30304458c5ad5
+  data.tar.gz: d8c1ada946d9fd2e0ca21818e6885903fa99203a847c016759019828ca602ebf15cb03b8d94653c1801ff9a5c0ed942fa4c2afa224675563a875ad24fcf16e97

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+## [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

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.6.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,45 +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?
 
         [date.year].product(months).map do |e|
-          if FiscalYear.cross_year_month?(month)
-            (FiscalYear.cross_year_month?(e.second) ? e : [e.first - 1, e.second])
-          else
-            e
-          end
+          [FiscalYear.decrease_year_by_month(e.first, e.second), e.second]
         end
       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
+
+        half_method = Half.first?(month) ? :first : :second
 
-        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
+        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
@@ -63,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
@@ -69,6 +101,8 @@ module FiscalYear
       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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fiscal_year
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Tsubasa Kawajiri
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-05-15 00:00:00.000000000 Z
+date: 2024-07-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport