Class: Time

Inherits:
Object show all
Defined in:
lib/more/facets/duration.rb,
lib/more/facets/times.rb,
lib/more/facets/typecast.rb,
lib/core/facets/conversion.rb,
lib/core/facets/time/stamp.rb,
lib/core/facets/time/change.rb,
lib/core/facets/time/elapse.rb

Overview

Time#duration has been added to convert the UNIX timestamp into a Duration. See Time#duration for an example.

Constant Summary collapse

NEVER = 
Time.mktime(2038)
ZERO = 
Time.mktime(1972)
FORMAT = 
{
  :db      => "%Y-%m-%d %H:%M:%S",
  :dbase   => "%Y-%m-%d %H:%M:%S",
  :datbase => "%Y-%m-%d %H:%M:%S",
  :utc     => "%Y-%m-%d %H:%M:%S",
  :short   => "%d %b %H:%M",
  :long    => "%B %d, %Y %H:%M",
  :day1st  => "%d-%m-%Y %H:%M",
  :dmYHM   => "%d-%m-%Y %H:%M",
  :rfc822  => "%a, %d %b %Y %H:%M:%S %z",
  nil      => "%a %b %d %H:%M:%S %Z %Y"
}

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.days_extrema(time1, time2 = nil) ⇒ Object

This method calculates the days extrema given two time objects.

start time is the given time1 at 00:00:00
end time is the given time2 at 23:59:59:999

Input:

  • the two times (if only time1 is provided then you get an extrema of exactly one day extrema.

Output:

  • the time range. you can get the start/end times using range methods.



187
188
189
190
191
192
193
 
# File 'lib/more/facets/times.rb', line 187

def self.days_extrema(time1, time2=nil)
  time2 = time1 if (not time2.valid? Time)
  time2 = NEVER if (time2 <= time1)
  start_time = Time.self.start_of_day(time1)
  end_time = self.end_of_day(time2)
  return (start_time..end_time)
end

.elapse ⇒ Object

Tracks the elapse time of a code block.

Time.elapse { sleep 1 }  #=> 0.999188899993896

CREDIT: Hal Fulton



9
10
11
12
13
14
 
# File 'lib/core/facets/time/elapse.rb', line 9

def self.elapse
  raise "Need block" unless block_given?
  t0 = Time.now.to_f
  yield
  Time.now.to_f - t0
end

.from_string(string, options = {}) ⇒ Object 



223
224
225
226
227
 
# File 'lib/more/facets/typecast.rb', line 223

def from_string(string, options={})
  parse(string)
rescue
  nil
end

.stamp(*args) ⇒ Object

Produce time stamp for Time.now. See #stamp.

CREDIT: Trans



24
25
26
 
# File 'lib/core/facets/time/stamp.rb', line 24

def self.stamp(*args)
  now.stamp(*args)
end

Instance Method Details

#ago(seconds) ⇒ Object

Returns a new Time representing the time a number of seconds ago. Do not use this method in combination with x.months, use months_ago instead!



202
203
204
205
206
 
# File 'lib/more/facets/times.rb', line 202

def ago(seconds)
  # This is basically a wrapper around the Numeric extension.
  #seconds.until(self)
  self - seconds
end

#beginning_of_day ⇒ Object Also known as: midnight, at_midnight, at_beginning_of_day, start_of_day

Returns a new Time representing the start of the day (0:00)



288
289
290
 
# File 'lib/more/facets/times.rb', line 288

def beginning_of_day
  self - self.seconds_since_midnight
end

#beginning_of_month ⇒ Object Also known as: at_beginning_of_month

Returns a new Time representing the start of the month (1st of the month, 0:00)



298
299
300
301
 
# File 'lib/more/facets/times.rb', line 298

def beginning_of_month
  #self - ((self.mday-1).days + self.seconds_since_midnight)
  change(:day => 1,:hour => 0, :min => 0, :sec => 0, :usec => 0)
end

#beginning_of_week ⇒ Object Also known as: monday, at_beginning_of_week

Returns a new Time representing the “start” of this week (Monday, 0:00)



267
268
269
 
# File 'lib/more/facets/times.rb', line 267

def beginning_of_week
  (self - self.wday.days).midnight + 1.day
end

#beginning_of_year ⇒ Object Also known as: at_beginning_of_year

Returns a new Time representing the start of the year (1st of january, 0:00)



305
306
307
 
# File 'lib/more/facets/times.rb', line 305

def beginning_of_year
  change(:month => 1,:day => 1,:hour => 0, :min => 0, :sec => 0, :usec => 0)
end

#change(options) ⇒ Object

Returns a new Time where one or more of the elements have been changed according to the options parameter. The time options (hour, minute, sec, usec) reset cascadingly, so if only the hour is passed, then minute, sec, and usec is set to 0. If the hour and minute is passed, then sec and usec is set to 0.

t = Time.now            #=> Sat Dec 01 14:10:15 -0500 2007
t.change(:hour => 11)   #=> Sat Dec 01 11:00:00 -0500 2007

CREDIT: David Hansson (?)



15
16
17
18
19
20
21
22
23
24
25
26
 
# File 'lib/core/facets/time/change.rb', line 15

def change(options)
  opts={}; options.each_pair{ |k,v| opts[k] = v.to_i }
  self.class.send( self.utc? ? :utc : :local,
    opts[:year]  || self.year,
    opts[:month] || self.month,
    opts[:day]   || self.day,
    opts[:hour]  || self.hour,
    opts[:min]   || (opts[:hour] ? 0 : self.min),
    opts[:sec]   || ((opts[:hour] || opts[:min]) ? 0 : self.sec),
    opts[:usec]  || ((opts[:hour] || opts[:min] || opts[:usec]) ? 0 : self.usec)
  )
end

#duration(type = nil) ⇒ Object

Create a Duration object from the UNIX timestamp.

Example

Time.now.duration
=> #<Duration: 1898 weeks, 6 days, 1 hour, 12 minutes and 1 second>



531
532
533
 
# File 'lib/more/facets/duration.rb', line 531

def duration(type = nil)
    if type == :big then BigDuration.new(to_i) else Duration.new(to_i) end
end

#in_day_range?(stime = ZERO, etime = NEVER) ⇒ Boolean

Returns true only if day of time is included in the range (stime..etime). Only year days are checked.

Returns:

  • (Boolean) 


334
335
336
337
338
339
340
341
342
343
344
 
# File 'lib/more/facets/times.rb', line 334

def in_day_range?(stime=ZERO, etime=NEVER)
  if (etime <= stime)
    warn "invalid end time (#{etime} < #{stime})" if $DEBUG
    etime = NEVER
  end

  stime = stime.to_start_of_day
  etime = etime.to_end_of_day

  return (stime..etime).include?(time)
end

#last_month ⇒ Object

Short-hand for months_ago(1)



257
258
259
 
# File 'lib/more/facets/times.rb', line 257

def last_month
  months_ago(1)
end

#last_year ⇒ Object

Short-hand for months_ago(1)



247
248
249
 
# File 'lib/more/facets/times.rb', line 247

def last_year
  years_since(1)
end

#months_ago(months) ⇒ Object

Returns a new Time representing the time a number of specified months ago.



220
221
222
223
224
225
226
 
# File 'lib/more/facets/times.rb', line 220

def months_ago(months)
  if months >= self.month
    change(:year => self.year - 1, :month => 12).months_ago(months - self.month)
  else
    change(:year => self.year, :month => self.month - months)
  end
end

#months_since(months) ⇒ Object 



228
229
230
231
232
233
234
 
# File 'lib/more/facets/times.rb', line 228

def months_since(months)
  if months + self.month > 12
    change(:year => self.year + 1, :month => 1).months_since(months - (self.month == 1 ? 12 : (self.month + 1)))
  else
    change(:year => self.year, :month => self.month + months)
  end
end

#next_month ⇒ Object

Short-hand for months_since(1)



262
263
264
 
# File 'lib/more/facets/times.rb', line 262

def next_month
  months_since(1)
end

#next_week(day = :monday) ⇒ Object

Returns a new Time representing the start of the given day in next week (default is Monday).



275
276
277
278
279
280
 
# File 'lib/more/facets/times.rb', line 275

def next_week(day = :monday)
  days_into_week = { :monday => 0, :tuesday => 1, :wednesday => 2,
                     :thursday => 3, :friday => 4, :saturday => 5,
                     :sunday => 6 }
  since(1.week).beginning_of_week.since(days_into_week[day].day).change(:hour => 0)
end

#next_year ⇒ Object

Short-hand for months_since(1)



252
253
254
 
# File 'lib/more/facets/times.rb', line 252

def next_year
  years_since(1)
end

#seconds_since_midnight ⇒ Object

Seconds since midnight: Time.now.seconds_since_midnight



196
197
198
 
# File 'lib/more/facets/times.rb', line 196

def seconds_since_midnight
  self.hour.hours + self.min.minutes + self.sec + (self.usec/1.0e+6)
end

#since(seconds) ⇒ Object Also known as: in

Returns a new Time representing the time a number of seconds since the instance time. Do not use this method in combination with x.months, use months_since instead!



211
212
213
214
215
 
# File 'lib/more/facets/times.rb', line 211

def since(seconds)
  # This is basically a wrapper around the Numeric extension.
  #seconds.since(self)
  self + seconds
end

#stamp(fmt = nil) ⇒ Object

Create a time stamp.

Time.now.stamp(:short)    #=> "01 Dec 15:15"

Supported formats come from the Time::FORMAT constant.

CREDIT: Trans



36
37
38
39
40
41
 
# File 'lib/core/facets/time/stamp.rb', line 36

def stamp(fmt = nil)
  unless String === fmt
    fmt = FORMAT[fmt]
  end
  strftime(fmt).strip
end

#to_date ⇒ Object

Convert a Time to a Date. Time is a superset of Date. It is the year, month and day that are carried over.

CREDIT: Trans



489
490
491
492
 
# File 'lib/core/facets/conversion.rb', line 489

def to_date
  require 'date'
  ::Date.new(year, month, day)
end

#to_end_of_day ⇒ Object

Rrturns a new time at end of day



328
329
330
 
# File 'lib/more/facets/times.rb', line 328

def to_end_of_day
  return Time.mktime(year, month, day, 23, 59, 59, 999)
end

#to_start_of_day ⇒ Object

Returns a new time at start of day



323
324
325
 
# File 'lib/more/facets/times.rb', line 323

def to_start_of_day
  return Time.mktime(year, month, day, 0, 0, 0, 0)
end

#to_time ⇒ Object

To be able to keep Dates and Times interchangeable on conversions.

CREDIT: Trans



499
500
501
 
# File 'lib/core/facets/conversion.rb', line 499

def to_time
  self
end

#tomorrow ⇒ Object

Convenience method which returns a new Time representing the time 1 day since the instance time



318
319
320
 
# File 'lib/more/facets/times.rb', line 318

def tomorrow
  self.since(1.day)
end

#years_ago(years) ⇒ Object

Returns a new Time representing the time a number of specified years ago.



238
239
240
 
# File 'lib/more/facets/times.rb', line 238

def years_ago(years)
  change(:year => self.year - years)
end

#years_since(years) ⇒ Object 



242
243
244
 
# File 'lib/more/facets/times.rb', line 242

def years_since(years)
  change(:year => self.year + years)
end

#yesterday ⇒ Object

Convenience method which returns a new Time representing the time 1 day ago



312
313
314
 
# File 'lib/more/facets/times.rb', line 312

def yesterday
  self.ago(1.day)
end