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:

time.cr
json/to_json.cr
yaml/to_yaml.cr

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

[View source]
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

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

[View source]
def self.new #

[View source]
def self.new(pull : JSON::PullParser) #

[View source]
def self.new(ctx : YAML::ParseContext, node : YAML::Nodes::Node) #

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

[View source]
def self.now : Time #

Returns the current time in the local time zone.


[View source]
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

[View source]
def self.utc(*, seconds : Int64, nanoseconds : Int32) : Time #

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


[View source]
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.


[View source]
def self.utc_now : Time #

Returns the current time in UTC time zone.


[View source]

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

[View source]
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

[View source]
def self.leap_year?(year : Int) : Bool #

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


[View source]
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

[View source]
def self.measure(&block) : Time::Span #

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


[View source]
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.


[View source]

Instance Method Detail

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

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


[View source]
def +(other : Time::MonthSpan) : Time #

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


[View source]
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.


[View source]
def -(span : Time::Span) : Time #

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


[View source]
def -(other : Time::MonthSpan) : Time #

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


[View source]
def <=>(other : self) #

[View source]
def add_span(seconds : Int, nanoseconds : Int) : Time #

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


[View source]
def at_beginning_of_day : Time #

Returns the time when the day that contains self starts.


[View source]
def at_beginning_of_hour : Time #

Returns the time when the hour that contains self starts.


[View source]
def at_beginning_of_minute : Time #

Returns the time when the minute that contains self starts.


[View source]
def at_beginning_of_month : Time #

Returns the time when the month that contains self starts.


[View source]
def at_beginning_of_quarter : Time #

Returns the time when the quarter that contains self starts.


[View source]
def at_beginning_of_semester : Time #

Returns the time when the semester that contains self starts.


[View source]
def at_beginning_of_week : Time #

Returns the time when the week that includes self starts.


[View source]
def at_beginning_of_year : Time #

Returns the time when the year that contains self starts.


[View source]
def at_end_of_day : Time #

Returns the time when the day that includes self ends.


[View source]
def at_end_of_hour : Time #

Returns the time when the hour that includes self ends.


[View source]
def at_end_of_minute : Time #

Returns the time when the minute that includes self ends.


[View source]
def at_end_of_month : Time #

Returns the time when the month that includes self ends.


[View source]
def at_end_of_quarter : Time #

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


[View source]
def at_end_of_semester : Time #

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


[View source]
def at_end_of_week : Time #

Returns the time when the week that includes self ends.


[View source]
def at_end_of_year : Time #

Returns the time when the year that includes self ends.


[View source]
def at_midday : Time #

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


[View source]
def clone : self #

[View source]
def date : Time #

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


[View source]
def day : Int32 #

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


[View source]
def day_of_week : Time::DayOfWeek #

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


[View source]
def day_of_year : Int32 #

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


[View source]
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

[View source]
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

[View source]
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

[View source]
def friday? : Bool #

Does self happen on Friday?


[View source]
def hash(hasher) #

[View source]
def hour : Int32 #

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


[View source]
def inspect(io : IO) #

[View source]
def kind : Kind #

Returns Kind (UTC/local) of the instance.


[View source]
def local? : Bool #

Returns true if Kind is set to Local.


[View source]
def millisecond : Int32 #

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


[View source]
def minute : Int32 #

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


[View source]
def monday? : Bool #

Does self happen on Monday?


[View source]
def month : Int32 #

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


[View source]
def nanosecond : Int32 #

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


[View source]
def saturday? : Bool #

Does self happen on Saturday?


[View source]
def second : Int32 #

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


[View source]
def sunday? : Bool #

Does self happen on Sunday?


[View source]
def thursday? : Bool #

Does self happen on Thursday?


[View source]
def time_of_day : Time::Span #

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


[View source]
def to_json(json : JSON::Builder) #

[View source]
def to_local : Time #

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


[View source]
def to_s(format : String, io : IO) : Nil #

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


[View source]
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"

[View source]
def to_utc : Time #

Returns a copy of this Time converted to UTC.


[View source]
def to_yaml(yaml : YAML::Nodes::Builder) #

[View source]
def tuesday? : Bool #

Does self happen on Tuesday?


[View source]
def utc? : Bool #

Returns true if Kind is set to Utc.


[View source]
def wednesday? : Bool #

Does self happen on Wednesday?


[View source]
def year : Int32 #

Returns the year number (in the Common Era).


[View source]