added Swimmer#age_for_category_range (specs still TODO)

Author: steveoro

app/models/goggles_db/swimmer.rb

@@ -4,7 +4,7 @@ module GogglesDb
   #
   # = GogglesDb::Swimmer
   #
-  # - version:  7-0.7.10
+  # - version:  7-0.8.00
   # - author:   Steve A.
   #
   class Swimmer < ApplicationRecord
@@ -65,14 +65,37 @@ class Swimmer < ApplicationRecord
     #-- ------------------------------------------------------------------------
     #++
 
-    # Returns the swimmer age (as a numeric value) for a given +date+.
+    # Returns the approximate swimmer age (as a numeric value) for a given +date+.
     #
     # == Params
     # - <tt>date</tt>: the date for which the age must be computed; default: +today+.
     def age(date = Time.zone.today)
       date.year - year_of_birth
     end
 
+    # Computes the swimmer's age, possily adjusted for the proper current category age range (5-years x category),
+    # according to the given meeting date.
+    #
+    # == Rationale:
+    # Given that Championships usually start in the second half of an year and we only consider the
+    # year of birth (as if the swimmer was born on the 1st of January of that year), the swimmer's age
+    # must be rounded up by 1 if the session month is in the second half of the current year - implying
+    # the first half of its season.
+    #
+    # === Example:
+    # YOB: 2000, current_year: 2024, session_month: 7 => age 24 => category 'M20' (meeting falls inside ending part of season 2023-2024)
+    # YOB: 2000, current_year: 2024, session_month: 9 => age 25 => category 'M25' (meeting falls inside starting part of season 2024-2025)
+    #
+    # == Params:
+    # - <tt>meeting_date</tt>: the meeting +Date+ to be considered; default: +today+
+    #
+    # == Returns:
+    # The swimmer's age (as a numeric value) for a given +date+.
+    # Raises an error unless +meeting_date+ responds to #year & #month (a valid +Date+).
+    def age_for_category_range(meeting_date = Time.zone.today)
+      meeting_date.year - year_of_birth + (meeting_date.month > 8 ? 1 : 0)
+    end
+
     # Returns the array list of all the distinct team IDs associated
     # to the object row through the available Badges.
     # Returns an empty array when nothing is found.