こんにちは、hachi8833です。
Active Support探訪シリーズ、今回は週刊Railsウォッチに何度か登場したActiveSupport::Durationにお邪魔します。Core Extensionsの外としては初めてですね。何回かに分けてお送りします。
今回のメソッド
- メソッド: ActiveSupport::Duration以下の演算、比較、期間関連のメソッド
- ディレクトリ配置: https://github.com/rails/rails/blob/5-0-stable/activesupport/lib/active_support/duration.rb
- 歴史: Rails 2.0より導入
以下もご覧ください。
条件
- Railsバージョン: 5-0-stable
- Rubyバージョン: 2.4.0
ActiveSupport::Durationのpublicメソッド
active_support/duration.rbにあるActiveSupport::Durationのメソッドです。各コードについては次回のぞいてみます。
コードの冒頭コメント↓にあるように、ActiveSupport::Durationは日付や時刻の正確な測定値を提供するためのライブラリです。
Provides accurate date and time measurements using Date#advance and Time#advance, respectively. It mainly supports the methods on Numeric.
http://devdocs.io/rails~5.0/activesupport/durationで確認できるメソッドは以下です。
演算系
| メソッド | 説明 |
|---|---|
#+ |
Durationに別のDurationまたはNumericを足す Numericの単位は秒 |
#- |
Durationから別のDurationまたはNumericを引く Numericの単位は秒 |
以下はRailsコンソールでの実行結果です（Rubyのirbやpryで試す場合は明示的に`require ‘active_support/all’を実行しておく必要があります）。
# サンプル
1.month + 3.days #=> 1 month and 3 days
1.month - 1.years #=> -1 year and 1 month
(1.month + 3.days).class #=> ActiveSupport::Duration
生成されているのはStringではなく、ActiveSupport::Durationクラスのオブジェクトです。
比較系
| メソッド | 説明 |
|---|---|
#== |
引数（Durationの場合はその値）が同じ値を持つ場合trueを返す |
#eql |
引数がDurationクラスかつ値が同じ場合にtrueを返す |
# サンプル
dr1 = 1.month
dr2 = 30 * 24 * 60 * 60 # 1か月を秒で表す
dr1 == dr2 #=> true （値が同じ）
dr1.eql? dr2 #=> false（値は同じだがDurationではない）
dr2 = 10.months - 9.month
dr1.eql? dr2 #=> true （Durationかつ値も同じ）
dr2 = 31.days
dr1 == dr2 #=> false（1か月と31日は等しくない）
dr1.eql? dr2 #=> false（1か月と31日は等しくない）
期間系
| メソッド | 説明 |
|---|---|
#agoと#until |
引数をDurationで表される分さかのぼった新しいTimeかDateを返す デフォルトは現在時刻 |
#sinceと#from_now |
引数をDurationで表される分未来に進んだ新しいTimeかDateを返す デフォルトは現在時刻 |
Duration#untilはDuration#agoのエイリアス、Duration#from_nowはDuration#sinceのエイリアスです。
なお、これらのメソッドはDurationとDateTimeで実装状況が異なっていますので注意が必要です。
DateTime#agoとDateTime#sinceは実装されているDateTime#untilとDateTime#from_nowは実装されていない（エイリアスがない）
dr = 3.days #=> drはActiveSupport::Duration
dt = DateTime.now #=> dtはDateTimeオブジェクト
dr.method(:ago).owner #=> ActiveSupport::Duration
dt.method(:ago).owner #=> DateTime
dr.method(:until).owner #=> ActiveSupport::Duration
dt.method(:until).owner # NameError（未実装）
dr.method(:since).owner #=> ActiveSupport::Duration
dt.method(:since).owner #=> DateTime
dr.method(:from_now).owner #=> ActiveSupport::Duration
dt.method(:from_now).owner # NameError（未実装）
このため、DateTimeオブジェクトをレシーバーにすると#untilと#from_nowは動きません。
dr.ago dt #=> Sun, 29 Jan 2017 14:19:40 +0900
dt.ago 3.days #=> Sun, 29 Jan 2017 14:19:40 +0900
dr.until dt #=> Sun, 29 Jan 2017 14:19:40 +0900
dt.until 3.days # NoMethodError:
kazzさんが掘り当ててくれたActiveSupport::DateTimeの該当箇所のコードには#untilや#from_nowといったエイリアスは特に設定されていません。その割には#inというエイリアスはあります。
#calculations.rb
class DateTime
def ago(seconds)
since(-seconds)
end
def since(seconds)
self + seconds
rescue
to_datetime.since(seconds)
end
alias :in :since
...
理由は不明ですが、untilという名前が制御文っぽいから嫌がられたのか、英語っぽくするためのシンタックスシュガーの必要を感じなかったのか、単にこれからエイリアスを設定するつもりなのか、あるいはDurationでは概念上#untilや#from_nowが必要だったのだろうか、などと考えてしまいました。機会があればもう少し追ってみたいと思います。
ActiveSupport::Durationの残りのメソッドについては次回扱います。ご期待ください。
関連記事
- [Rails5] Active Support Core ExtensionsのStringの小粒なメソッドたち: 文字列定数は#freezeしよう
- [Rails5] Active Support Core ExtensionsのString#inquiryでメタプログラミング
- [Rails5] Active Support::Inflectorの便利な活用形メソッド群
- [Rails5] Active Support Core ExtensionsのString#pluralize
- [Rails5] Active Support Core ExtensionsのString#acts_like_string?
- [Rails5] Active Support Core ExtensionsのStringクラス（3）#to_time、#to_date、#to_datetime
- [Rails5] Active Support Core ExtensionsのStringクラス（2）html_safe
- [Rails5] Active Support Core ExtensionsのStringクラス（1）String#blank?
- [Rails5] Active Supportの概要をつかむ
- [Rails5] Railsの主要なライブラリ構成
- [Ruby] module_functionでモジュールの特異メソッドを簡潔に書く
- Active Support core_extのHash#diffはRails 4で非推奨化・廃止された
- RailsビューのHTMLエスケープは#link_toなどのヘルパーメソッドで解除されることがある
- Rails 4.0.2, 3.2.16リリース！重大なセキュリティFIXがあります