nth_weekday 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 69519a49798e6edd6879ae4f8ce20ebec5f09ed7761380d592b6770ed40d13a9
-  data.tar.gz: eb41eb2c8e89dd6689b04b607a000e8e0c8ef93886372a721f8e47987b7e5ade
+  metadata.gz: e28ea963f943f3e81ebc4875aae5e1fd589e59ccb0805255e32b9e56aa33548b
+  data.tar.gz: adb591ba5a6e1438f514631081414236e94eb10ef86cc1b76fb87a12b92abed8
 SHA512:
-  metadata.gz: 40caf4872dc1ef615b8667a6c415aedcc46eec7975b80784d73d09ebbcabd1609dc6c9690b763e80cbbc8c74400d010fec2b2c7277791b50f9ad9f0bb1a1aad9
-  data.tar.gz: 95680caaea53204cb06df51c79b7484d3b3aa539355e01dcdf568754a4409ff0aa92f20f4c61552dfec97b68fb9eabb63ef86e5729fd4d1e5afc3d2caeee87d5
+  metadata.gz: 9ced69b3dc9394c73dae6ce531cc2946e0cec722d6f049abf5f33cd36c12e11dce1da87475243fa38e77e7d3bf08f509c66162e85e0e247f100ec340c6076d58
+  data.tar.gz: 9c5ecc75f439b0c174d87afd85defa3f8b70d35ef999c950830ab76c47a83439d19c4f103b897242767c9911fde974c52387849805c61f862645f510f729d266

data/README.md

@@ -46,16 +46,27 @@ NthWeekday.get(year: 2025, month: 4, weekday: :we, nth: 3)
 # 最後の金曜日（2025年12月）
 NthWeekday.get(year: 2025, month: 12, weekday: :fr, nth: -1)
 # => #<Date: 2025-12-26>
+
+# 日付文字列として取得
+NthWeekday.get(year: 2025, month: 4, weekday: :we, nth: 3, format: '%Y-%m-%d')
+# => "2025-04-16"
+
+# UNIXタイムスタンプとして取得（UTC 00:00:00基準）
+NthWeekday.get(year: 2025, month: 4, weekday: :we, nth: 3, format: :unix)
+# => 1744761600
 ```
 
 ## 📘 Parameters / パラメータ
 
-| パラメータ名 | 型     | 説明                                                  |
-|--------------|--------|-------------------------------------------------------|
-| `year`       | Integer| 対象年（例: 2025）                                   |
-| `month`      | Integer| 対象月（1〜12）                                       |
-| `weekday`    | Symbol | 対象曜日（`:su`, `:mo`, `:tu`, `:we`, `:th`, `:fr`, `:sa`）      |
-| `nth`        | Integer| 第n◯曜日。1〜5、または `-1` で「最後の◯曜日」を指定 |
+| パラメータ名 | 型                    | 説明                                                  |
+|--------------|-----------------------|-------------------------------------------------------|
+| `year`       | Integer               | 対象年（例: 2025）                                   |
+| `month`      | Integer               | 対象月（1〜12）                                       |
+| `weekday`    | Symbol                | 対象曜日（`:su`, `:mo`, `:tu`, `:we`, `:th`, `:fr`, `:sa`）      |
+| `nth`        | Integer               | 第n◯曜日。1〜5、または `-1` で「最後の◯曜日」を指定 |
+| `format`     | String, Symbol, nil   | 省略可。`String` は `Date#strftime` 形式、`:unix` は UTC 00:00:00 基準の UNIX タイムスタンプ |
+
+`format` を省略した場合は、従来通り `Date` オブジェクトを返します。
 
 ### 曜日シンボル一覧
 - `:su` - 日曜日 (Sunday)

data/VERSION

@@ -1 +1 @@
-0.1.2
+0.2.0

data/lib/nth_weekday.rb

@@ -21,10 +21,11 @@ module NthWeekday
     # @param month [Integer] Month (1-12)
     # @param weekday [Symbol] Weekday symbol (:mo, :tu, :we, :th, :fr, :sa, :su)
     # @param nth [Integer] The occurrence of the weekday (1-5, or -1 for last occurrence)
-    # @return [Date] Date object representing the requested day
+    # @param format [String, Symbol, nil] Optional output format. String uses Date#strftime, :unix returns UTC midnight timestamp.
+    # @return [Date, String, Integer, nil] Date object, formatted string, UNIX timestamp, or nil when no matching date exists
     # @raise [ArgumentError] If parameters are invalid
-    def get(year:, month:, weekday:, nth:)
-      validate_params(year, month, weekday, nth)
+    def get(year:, month:, weekday:, nth:, format: nil)
+      validate_params(year, month, weekday, nth, format)
 
       wday = WEEKDAY_MAP[weekday.to_sym]
       raise ArgumentError, 'Invalid weekday symbol' unless wday
@@ -34,19 +35,34 @@ module NthWeekday
 
       days = (first_day..last_day).select { |date| date.wday == wday }
 
-      if nth == -1
-        days.last
-      else
-        days[nth - 1]
-      end
+      date = if nth == -1
+               days.last
+             else
+               days[nth - 1]
+             end
+
+      format_date(date, format)
     end
 
     private
 
-    def validate_params(year, month, _weekday, nth)
+    def validate_params(year, month, _weekday, nth, format)
       raise ArgumentError, "Invalid year: #{year}" unless year.is_a?(Integer) && year.positive?
       raise ArgumentError, "Invalid month: #{month}" unless month.is_a?(Integer) && month.between?(1, 12)
       raise ArgumentError, "Invalid nth: #{nth}" unless nth.is_a?(Integer) && (nth.between?(1, 5) || nth == -1)
+      raise ArgumentError, "Invalid format: #{format}" unless valid_format?(format)
+    end
+
+    def valid_format?(format)
+      format.nil? || format.is_a?(String) || format == :unix
+    end
+
+    def format_date(date, format)
+      return nil if date.nil?
+      return date if format.nil?
+      return Time.utc(date.year, date.month, date.day).to_i if format == :unix
+
+      date.strftime(format)
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nth_weekday
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Yusuke Higasa