tetralabo

膨大な数の拡張メソッドが収録されているRuby Facets。現時点で日本語のドキュメントが存在しないため、普通は英語のドキュメントを解読していくことになるのですが、メソッドを一つ一つ解読していくのは大変です。そこでこのblogでは、私的なメモも兼ねて、Ruby Facetsに収録されたライブラリを日本語で解説していきます。

第1回はTimeクラスを拡張する facets/time です。Ruby Facets 2.8.1に準拠しています。

• 駆け足紹介（クイックツアー）
• クラスメソッド
  • Time.elapse { ... }
  • Time.stamp(fmt)
• インスタンスメソッド
  • advance(options)
  • ago(number, units=:seconds)
  • hence(number, units=:seconds)
  • change(options)
  • round(amount)
  • set(options)
  • stamp(fmt = nil)
  • trunc(amount)

駆け足紹介（クイックツアー）

require 'facets/time'

# Time.elapse: ブロックの実行時間を計測する
p Time.elapse{ sleep(1) }  # => 1.07800006866455


time = Time.now
p time  # => Sat Jan 30 21:41:42 +0900 2010

# hence, ago: 時間を進めたり戻したりできる
p time.hence(5, :days)  # => Thu Feb 04 21:41:42 +0900 2010
p time.ago(2, :weeks)   # => Sat Jan 16 21:41:42 +0900 2010


# change: 時刻のうち一部だけを書き換える
p time.change(:day => 2, :minute => 30) #=> Sat Jan 02 21:41:42 +0900 2010


# trunc, round: 時刻を指定した単位（秒）で丸める
#               60 なら1分単位、60 * 60 なら1時間単位
p time.trunc(60)       # => Sat Jan 30 21:41:00 +0900 2010
p time.trunc(60 * 60)  # => Sat Jan 30 21:00:00 +0900 2010
p time.round(60)       # => Sat Jan 30 21:42:00 +0900 2010
p time.round(60 * 60)  # => Sat Jan 30 22:00:00 +0900 2010


# stamp: 時刻を指定したフォーマットで文字列化
p time.stamp(:short)  # => "30 Jan 21:41"
p time.stamp(:time)   # => "21:41"
p time.stamp(:number) # => "20100130214142"
p time.stamp(:db)     # => "2010-01-30 21:41:42"

p Time.stamp(:db)     # Time.now.stamp(:db)と同じ

クラスメソッド

Time.elapse { ... }

ブロックの実行時間を計測し、結果をFloatで返す（Benchmark.realtime と同じ）。

require 'facets/time/elapse'

Time.elapse { sleep 1 }  #=> 0.999188899993896

Time.stamp(fmt)

Time.now.stamp(fmt) と同じ。詳しくはstampメソッドを参照。

インスタンスメソッド

advance(options)

ActiveSupportの Time#advance と同じ。

ago(number, units=:seconds)

hence(number, units=:seconds)

agoなら時間を戻し、henceなら時間を進めた、新しいTimeオブジェクトを生成して返す。 動かす量は数値（number）と単位（units）の組み合わせで指定でき、単位には :seconds, :minutes, :hours, :days, :weeks, :months, :years のいずれかを指定できる。

require 'facets/time/ago'
require 'facets/time/hence'

time = Time.now
p time                     # => Sat Jan 30 18:59:29 +0900 2010
p time.hence(5)            # => Sat Jan 30 18:59:34 +0900 2010
p time.hence(5, :seconds)  # 上の例と同じ
p time.hence(30, :minutes) # => Sat Jan 30 19:29:29 +0900 2010
p time.hence(7, :days)     # => Sat Feb 06 18:59:29 +0900 2010
p time.ago(3, :weeks)      # => Sat Jan 09 18:59:29 +0900 2010

numberに負の数（-20）を指定した場合には、逆方向のメソッドが呼び出される。

time.hence(-10) # time.ago(10) と同じ

change(options)

時刻を部分的に変更した、新しいTimeオブジェクトを生成して返す。 「年だけを2009年に変更」「時間を13時30分に変更」などの処理が可能。

時間（:hour）、分（:minute）、秒（:second）を変更した場合、それより下の時間要素は0に設定される。 たとえば「15時30分」であるTimeオブジェクトに対して、changeで時間だけを13時に変更すると、時刻は「13時00分」となる。

require 'facets/time/change'

time = Time.now
p time                                    # => Sat Jan 30 20:45:12 +0900 2010
p time.change(:year => 2000, :month => 3) # => Thu Mar 30 20:45:38 +0900 2000
p time.change(:hour => 23)                # => Sat Jan 30 23:00:00 +0900 2010

round(amount)

時刻をamount秒単位で丸めた、新しいTimeオブジェクトを生成して返す。 たとえばamountが60であれば、時刻を1分単位で割り、四捨五入のように近いほうの時刻へ丸める。

近いほうの時刻にするのではなく切り捨てたい場合には、truncメソッドを使う。

require 'facets/time/round'

time = Time.now
p time                     # => Sat Jan 30 20:57:56 +0900 2010
p time.round(60)           # => Sat Jan 30 20:58:00 +0900 2010
p time.round(60 * 60)      # => Sat Jan 30 21:00:00 +0900 2010

set(options)

changeメソッドと同じだが、時間・分・秒を変更しても、その下の時間要素を0にしない。

stamp(fmt = nil)

時刻を指定したフォーマットの文字列に整形する。fmtはフォーマットの種類を表すSymbol。

require 'facets/time/stamp'

time = Time.now
p time.stamp(:short) # => "30 Jan 18:18"
p time.stamp(:long) # => "January 30, 2010 18:18"
p time.stamp(:time) # => "18:18"
p time.stamp(:number) # => "20100130181814"
p time.stamp(:utc) # =>"2010-01-30 18:18:14"

使用可能なフォーマットとその内容については、Time::FORMAT定数を見れば確認できる。

require 'facets/time/stamp'

p Time::FORMAT.class # => Hash
p Time::FORMAT.keys  # => [:datbase, :day1st, :utc, nil, :long, :number, :dmYHM, :short, :rfc822, :db, :time, :dbase]
p Time::FORMAT[:db]  # => "%Y-%m-%d %H:%M:%S"

なお、Symbolではなく文字列を引数にすると、Time#strftimeとほぼ同じ動作を行う。

trunc(amount)

時刻をamount秒単位で切り捨てた、新しいTimeオブジェクトを生成して返す。たとえばamountが60であれば、時刻を1分単位で割り、余り（秒）は切り捨てる。

切り捨てでなく近いほうの時刻にしたい場合には、roundメソッドを使う。

require 'facets/time/trunc'

time = Time.now
p time                     # => Sat Jan 30 20:57:56 +0900 2010
p time.trunc(60)           # => Sat Jan 30 20:57:00 +0900 2010
p time.trunc(60 * 60)      # => Sat Jan 30 20:00:00 +0900 2010