struct Time

Overview

Time represents an instance in time. Here are some examples:

Basic Usage

time = Time.new(2016, 2, 15, 10, 20, 30)

time.year    # => 2016
time.month   # => 2
time.day     # => 15
time.hour    # => 10
time.minute  # => 20
time.second  # => 30
time.monday? # => true

# Creating a time instance with a date only
Time.new(2016, 2, 15) # => 2016-02-15 00:00:00

# Specifying a time
Time.new(2016, 2, 15, 10, 20, 30) # => 2016-02-15 10:20:30

# Creating a time instance in UTC
Time.utc(2016, 2, 15, 10, 20, 30) # => 2016-02-15 10:20:30 UTC

Formatting Time

The #to_s method returns a String value in the assigned format.

time = Time.new(2015, 10, 12)
time.to_s("%Y-%m-%d") # => "2015-10-12"

See Time::Format for all the directives.

Calculation

Time.new(2015, 10, 10) - 5.days # => 2015-10-05 00:00:00

# Time calculation returns a Time::Span instance
span = Time.new(2015, 10, 10) - Time.new(2015, 9, 10)
span.days          # => 30
span.total_hours   # => 720
span.total_minutes # => 43200

# Calculation between Time::Span instances
span_a = Time::Span.new(3, 0, 0)
span_b = Time::Span.new(2, 0, 0)
span = span_a - span_b
span       # => 01:00:00
span.class # => Time::Span
span.hours # => 1

Included Modules

Defined in:

Constructors

Class Method Summary

Instance Method Summary

Instance methods inherited from module Comparable(self)

<(other : T) <, <=(other : T) <=, <=>(other : T) <=>, ==(other : T) ==, >(other : T) >, >=(other : T) >=

Instance methods inherited from struct Struct

==(other) : Bool ==, hash(hasher) hash, inspect(io : IO) : Nil inspect, pretty_print(pp) : Nil pretty_print, to_s(io) to_s

Instance methods inherited from struct Value

==(other) ==, dup dup

Instance methods inherited from class Object

!=(other) !=, !~(other) !~, ==(other) ==, ===(other : JSON::Any)
===(other : YAML::Any)
===(other)
===
, =~(other) =~, class class, dup dup, hash(hasher)
hash
hash
, inspect(io : IO)
inspect
inspect
, itself itself, not_nil! not_nil!, pretty_inspect(width = 79, newline = "\n", indent = 0) : String pretty_inspect, pretty_print(pp : PrettyPrint) : Nil pretty_print, tap(&block) tap, to_json(io : IO)
to_json
to_json
, to_pretty_json(indent : String = " ")
to_pretty_json(io : IO, indent : String = " ")
to_pretty_json
, to_s
to_s(io : IO)
to_s
, to_yaml(io : IO)
to_yaml
to_yaml
, try(&block) try, unsafe_as(type : T.class) forall T unsafe_as

Constructor methods inherited from class Object

from_json(string_or_io, root : String) : self
from_json(string_or_io) : self
from_json
, from_yaml(string_or_io : String | IO) : self from_yaml

Constructor Detail

def self.epoch(seconds : Int) : Time #

Returns a new Time instance that corresponds to the number seconds elapsed since the unix epoch (00:00:00 UTC on 1 January 1970).

Time.epoch(981173106) # => 2001-02-03 04:05:06 UTC

def self.epoch_ms(milliseconds : Int) : Time #

Returns a new Time instance that corresponds to the number milliseconds elapsed since the unix epoch (00:00:00 UTC on 1 January 1970).

time = Time.epoch_ms(981173106789) # => 2001-02-03 04:05:06.789 UTC
time.millisecond                   # => 789

def self.new(*, seconds : Int64, nanoseconds : Int32, kind : Kind) #

def self.new #

def self.new(pull : JSON::PullParser) #

def self.new(ctx : YAML::ParseContext, node : YAML::Nodes::Node) #

def self.new(year, month, day, hour = 0, minute = 0, second = 0, *, nanosecond = 0, kind = Kind::Unspecified) #

def self.now : Time #

Returns the current time in the local time zone.


def self.parse(time : String, pattern : String, kind = Time::Kind::Unspecified) : Time #

Parses a Time in the given time string, using the given pattern (see Time::Format).

Time.parse("2016-04-05", "%F") # => 2016-04-05 00:00:00

def self.utc(*, seconds : Int64, nanoseconds : Int32) : Time #

Returns a new Time instance at the specified time in UTC time zone.


def self.utc(year, month, day, hour = 0, minute = 0, second = 0, *, nanosecond = 0) : Time #

Returns a new Time instance at the specified time in UTC time zone.


def self.utc_now : Time #

Returns the current time in UTC time zone.


Class Method Detail

def self.days_in_month(year : Int, month : Int) : Int32 #

Returns how many days this month (1..12) of this year has (28, 29, 30 or 31).

Time.days_in_month(2016, 2) # => 29
Time.days_in_month(1990, 4) # => 30

def self.days_in_year(year : Int) : Int32 #

Returns number of days in year.

Time.days_in_year(1990) # => 365
Time.days_in_year(2004) # => 366

def self.leap_year?(year : Int) : Bool #

Returns whether this year is leap (February has one more day).


def self.local_offset_in_minutes #

Returns the local time offset in minutes relative to GMT.

# Assume in Argentina, where it's GMT-3
Time.local_offset_in_minutes # => -180

def self.measure(&block) : Time::Span #

Measures how long the block took to run. Relies on .monotonic to not be affected by time fluctuations.


def self.monotonic : Time::Span #

Returns a clock from an unspecified starting point, but strictly linearly increasing. This clock should be independent from discontinuous jumps in the system time, such as leap seconds, time zone adjustments or manual changes to the computer's time.

For example, the monotonic clock must always be used to measure an elapsed time.


Instance Method Detail

def +(span : Time::Span) : Time #

Returns a Time that is later than this Time by the Time::Span span.


def +(other : Time::MonthSpan) : Time #

Adds a number of months specified by other's value.


def -(other : Time) : Time::Span #

Returns the amount of time between other and self.

The amount can be negative if self is a Time that happens before other.


def -(span : Time::Span) : Time #

Returns a Time that is earlier than this Time by the Time::Span span.


def -(other : Time::MonthSpan) : Time #

Subtracts a number of months specified by other's value.


def <=>(other : self) #

def add_span(seconds : Int, nanoseconds : Int) : Time #

Returns a Time that is this number of seconds and nanoseconds later.


def at_beginning_of_day : Time #

Returns the time when the day that contains self starts.


def at_beginning_of_hour : Time #

Returns the time when the hour that contains self starts.


def at_beginning_of_minute : Time #

Returns the time when the minute that contains self starts.


def at_beginning_of_month : Time #

Returns the time when the month that contains self starts.


def at_beginning_of_quarter : Time #

Returns the time when the quarter that contains self starts.


def at_beginning_of_semester : Time #

Returns the time when the semester that contains self starts.


def at_beginning_of_week : Time #

Returns the time when the week that includes self starts.


def at_beginning_of_year : Time #

Returns the time when the year that contains self starts.


def at_end_of_day : Time #

Returns the time when the day that includes self ends.


def at_end_of_hour : Time #

Returns the time when the hour that includes self ends.


def at_end_of_minute : Time #

Returns the time when the minute that includes self ends.


def at_end_of_month : Time #

Returns the time when the month that includes self ends.


def at_end_of_quarter : Time #

Returns the time when the quarter-year that includes self ends.


def at_end_of_semester : Time #

Returns the time when the half-year that includes self ends.


def at_end_of_week : Time #

Returns the time when the week that includes self ends.


def at_end_of_year : Time #

Returns the time when the year that includes self ends.


def at_midday : Time #

Returns the midday (12:00) of the day represented by self.


def clone : self #

def date : Time #

Returns a copy of self with time-of-day components (hour, minute, ...) set to zero.


def day : Int32 #

Returns the day number of the month (1..31).


def day_of_week : Time::DayOfWeek #

Returns the day of the week (Sunday..Saturday).


def day_of_year : Int32 #

Returns the day number of the year (1..365, or 1..366 on leap years).


def epoch : Int64 #

Returns the number of seconds since the Epoch for this time.

time = Time.parse("2016-01-12 03:04:05 UTC", "%F %T %z")
time.epoch # => 1452567845

def epoch_f : Float64 #

Returns the number of seconds since the Epoch for this time, as a Float64.

time = Time.parse("2016-01-12 03:04:05.678 UTC", "%F %T.%L %z")
time.epoch_f # => 1452567845.678

def epoch_ms : Int64 #

Returns the number of milliseconds since the Epoch for this time.

time = Time.parse("2016-01-12 03:04:05.678 UTC", "%F %T.%L %z")
time.epoch_ms # => 1452567845678

def friday? : Bool #

Does self happen on Friday?


def hash(hasher) #

def hour : Int32 #

Returns the hour of the day (0..23).


def inspect(io : IO) #

def kind : Kind #

Returns Kind (UTC/local) of the instance.


def local? : Bool #

Returns true if Kind is set to Local.


def millisecond : Int32 #

Returns the millisecond of the second (0..999).


def minute : Int32 #

Returns the minute of the hour (0..59).


def monday? : Bool #

Does self happen on Monday?


def month : Int32 #

Returns the month number of the year (1..12).


def nanosecond : Int32 #

Returns the nanosecond of the second (0..999_999_999).


def saturday? : Bool #

Does self happen on Saturday?


def second : Int32 #

Returns the second of the minute (0..59).


def sunday? : Bool #

Does self happen on Sunday?


def thursday? : Bool #

Does self happen on Thursday?


def time_of_day : Time::Span #

Returns how much time has passed since midnight of this day.


def to_json(json : JSON::Builder) #

def to_local : Time #

Returns a copy of this Time converted to the local time zone.


def to_s(format : String, io : IO) : Nil #

Formats this time using the given format (see Time::Format) into the given io.


def to_s(format : String) : String #

Formats this time using the given format (see Time::Format).

time = Time.new(2016, 4, 5)
time.to_s("%F") # => "2016-04-05"

def to_utc : Time #

Returns a copy of this Time converted to UTC.


def to_yaml(yaml : YAML::Nodes::Builder) #

def tuesday? : Bool #

Does self happen on Tuesday?


def utc? : Bool #

Returns true if Kind is set to Utc.


def wednesday? : Bool #

Does self happen on Wednesday?


def year : Int32 #

Returns the year number (in the Common Era).