class VirtualTime

Included Modules

Defined in:

virtualtime.cr

Constant Summary

VERSION = [VERSION_MAJOR, VERSION_MINOR, VERSION_REVISION].join('.')
VERSION_MAJOR = 1
VERSION_MINOR = 2
VERSION_REVISION = 3

Constructors

Class Method Summary

Instance Method Summary

Macro Summary

Constructor Detail

def self.new(year : Array(Int32) | Bool | Int32 | Int32 -> Bool | Range(Int32, Int32) | Set(Int32) | Steppable::StepIterator(Int32, Int32, Int32) | Nil, month : Array(Int32) | Bool | Int32 | Int32 -> Bool | Range(Int32, Int32) | Set(Int32) | Steppable::StepIterator(Int32, Int32, Int32) | Nil, day : Array(Int32) | Bool | Int32 | Int32 -> Bool | Range(Int32, Int32) | Set(Int32) | Steppable::StepIterator(Int32, Int32, Int32) | Nil, week : Array(Int32) | Bool | Int32 | Int32 -> Bool | Range(Int32, Int32) | Set(Int32) | Steppable::StepIterator(Int32, Int32, Int32) | Nil, day_of_week : Array(Int32) | Bool | Int32 | Int32 -> Bool | Range(Int32, Int32) | Set(Int32) | Steppable::StepIterator(Int32, Int32, Int32) | Nil, day_of_year : Array(Int32) | Bool | Int32 | Int32 -> Bool | Range(Int32, Int32) | Set(Int32) | Steppable::StepIterator(Int32, Int32, Int32) | Nil, hour : Array(Int32) | Bool | Int32 | Int32 -> Bool | Range(Int32, Int32) | Set(Int32) | Steppable::StepIterator(Int32, Int32, Int32) | Nil, minute : Array(Int32) | Bool | Int32 | Int32 -> Bool | Range(Int32, Int32) | Set(Int32) | Steppable::StepIterator(Int32, Int32, Int32) | Nil, second : Array(Int32) | Bool | Int32 | Int32 -> Bool | Range(Int32, Int32) | Set(Int32) | Steppable::StepIterator(Int32, Int32, Int32) | Nil, millisecond : Array(Int32) | Bool | Int32 | Int32 -> Bool | Range(Int32, Int32) | Set(Int32) | Steppable::StepIterator(Int32, Int32, Int32) | Nil, nanosecond : Array(Int32) | Bool | Int32 | Int32 -> Bool | Range(Int32, Int32) | Set(Int32) | Steppable::StepIterator(Int32, Int32, Int32) | Nil, location : Nil | Time::Location, default_match : Bool = true) #

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

[View source]
def self.new(year : Array(Int32) | Bool | Int32 | Int32 -> Bool | Range(Int32, Int32) | Set(Int32) | Steppable::StepIterator(Int32, Int32, Int32) | Nil = nil, month : Array(Int32) | Bool | Int32 | Int32 -> Bool | Range(Int32, Int32) | Set(Int32) | Steppable::StepIterator(Int32, Int32, Int32) | Nil = nil, day : Array(Int32) | Bool | Int32 | Int32 -> Bool | Range(Int32, Int32) | Set(Int32) | Steppable::StepIterator(Int32, Int32, Int32) | Nil = nil, hour : Array(Int32) | Bool | Int32 | Int32 -> Bool | Range(Int32, Int32) | Set(Int32) | Steppable::StepIterator(Int32, Int32, Int32) | Nil = nil, minute : Array(Int32) | Bool | Int32 | Int32 -> Bool | Range(Int32, Int32) | Set(Int32) | Steppable::StepIterator(Int32, Int32, Int32) | Nil = nil, second : Array(Int32) | Bool | Int32 | Int32 -> Bool | Range(Int32, Int32) | Set(Int32) | Steppable::StepIterator(Int32, Int32, Int32) | Nil = nil, *, millisecond : Array(Int32) | Bool | Int32 | Int32 -> Bool | Range(Int32, Int32) | Set(Int32) | Steppable::StepIterator(Int32, Int32, Int32) | Nil = nil, nanosecond : Array(Int32) | Bool | Int32 | Int32 -> Bool | Range(Int32, Int32) | Set(Int32) | Steppable::StepIterator(Int32, Int32, Int32) | Nil = nil, day_of_week : Array(Int32) | Bool | Int32 | Int32 -> Bool | Range(Int32, Int32) | Set(Int32) | Steppable::StepIterator(Int32, Int32, Int32) | Nil = nil, day_of_year : Array(Int32) | Bool | Int32 | Int32 -> Bool | Range(Int32, Int32) | Set(Int32) | Steppable::StepIterator(Int32, Int32, Int32) | Nil = nil, week : Array(Int32) | Bool | Int32 | Int32 -> Bool | Range(Int32, Int32) | Set(Int32) | Steppable::StepIterator(Int32, Int32, Int32) | Nil = nil, location : Nil | Time::Location = nil, default_match : Bool = true) #

[View source]
def self.new(*, year : Array(Int32) | Bool | Int32 | Int32 -> Bool | Range(Int32, Int32) | Set(Int32) | Steppable::StepIterator(Int32, Int32, Int32) | Nil, week : Array(Int32) | Bool | Int32 | Int32 -> Bool | Range(Int32, Int32) | Set(Int32) | Steppable::StepIterator(Int32, Int32, Int32) | Nil, day_of_week : Array(Int32) | Bool | Int32 | Int32 -> Bool | Range(Int32, Int32) | Set(Int32) | Steppable::StepIterator(Int32, Int32, Int32) | Nil = nil, hour : Array(Int32) | Bool | Int32 | Int32 -> Bool | Range(Int32, Int32) | Set(Int32) | Steppable::StepIterator(Int32, Int32, Int32) | Nil = nil, minute : Array(Int32) | Bool | Int32 | Int32 -> Bool | Range(Int32, Int32) | Set(Int32) | Steppable::StepIterator(Int32, Int32, Int32) | Nil = nil, second : Array(Int32) | Bool | Int32 | Int32 -> Bool | Range(Int32, Int32) | Set(Int32) | Steppable::StepIterator(Int32, Int32, Int32) | Nil = nil, millisecond : Array(Int32) | Bool | Int32 | Int32 -> Bool | Range(Int32, Int32) | Set(Int32) | Steppable::StepIterator(Int32, Int32, Int32) | Nil = nil, nanosecond : Array(Int32) | Bool | Int32 | Int32 -> Bool | Range(Int32, Int32) | Set(Int32) | Steppable::StepIterator(Int32, Int32, Int32) | Nil = nil, location : Nil | Time::Location = ni, default_match : Bool = true) #

[View source]

Class Method Detail

def self.from_time(time : Time, *, milliseconds = false, nanoseconds = true) #

Creates VirtualTime from Time. This can be useful to produce a VT with many fields filled in quickly, and then set fields of choice to more interesting values rather than fixed integers.

Note that this copies all values from Time to VirtualTime, including week number, day of week, day of year. That results in a very fixed VirtualTime which is probably not useful unless some values are afterwards reset to nil or set to other VT-specific options.

Millisecond and nanosecond values are copied from Time into VirtualTime only if options milliseconds= and nanoseconds= are set to true. Default is currently true for nanoseconds. Whether these options are useful, or whether they should be removed, or whether all fields should get a corresponding option like this, remains be seen.


[View source]

Instance Method Detail

def <=>(other : Time) #

Compares VirtualTime to Time instance


[View source]
def ==(other : self) #
Description copied from class Reference

Returns true if this reference is the same as other. Invokes same?.


[View source]
def ==(time : TimeOrVirtualTime) #

Compares VirtualTime to Time instance

Alias for #matches?.


[View source]
def adjust_day(day : Int, acceptable_day : Int, wrap_day : Int) #

"Rewinds" #day forward enough to reach acceptable_day.

It wraps around wrap_day, so e.g. #adjust_day(25, 5, 30) returns 10.days


[View source]
def adjust_location(time) #

Ensures that Time's timezone is equal to VT's timezone. Raises ArgumentError if comparing two VTs with different timezones.


[View source]
def adjust_value(a, max) #

Adjusts values to be suitable for use in comparisons. At the moment, that includes converting negative values to offsets from end of range, reorganizing ranges so ttat begin <= end, and sorting Arrays and Sets, If calling this function yourself, provide max whenever possible.


[View source]
def clear! #

Sets all fields to nil


[View source]
def clear_date! #

Sets date-related fields to nil


[View source]
def clear_time! #

Sets time-related fields to nil


[View source]
def day : Virtual #

def day=(day : Virtual) #

def day_of_week : Virtual #

def day_of_week=(day_of_week : Virtual) #

def day_of_year : Virtual #

def day_of_year=(day_of_year : Virtual) #

def default_match=(default_match : Bool) #

Instance-default match result if one of field values matched is nil


[View source]
def default_match? : Bool #

Instance-default match result if one of field values matched is nil


[View source]
def expand #

Expands VirtualTime containing ranges or lists into a list of individual VirtualTimes with specific values E.g. VirtualTime with day=1..2 gets expanded into two separate VirtualTimes, day=1 and day=2

This function is used only in tests.


[View source]
def hour : Virtual #

def hour=(hour : Virtual) #

def location : Time::Location | Nil #

[View source]
def location=(location : Time::Location | Nil) #

[View source]
def matches?(a, b, max = nil) : Bool #

Performs matching between VirtualTime and other supported types


[View source]
def matches?(time : TimeOrVirtualTime = Time.local) #

Returns whether VirtualTime matches the specified time


[View source]
def matches_date?(time : TimeOrVirtualTime = Time.local) #

Returns whether VirtualTime matches the date part of specified time


[View source]
def matches_time?(time : TimeOrVirtualTime = Time.local) #

Returns whether VirtualTime matches the time part of specified time


[View source]
def materialize(allowed, wanted : Int, min, max = nil, strict = true) #

Materialize a particular value with the help of a wanted/wanted value. If 'strict' is true and wanted value does not satisfy predefined range or requirements, it is replaced with the first/earliest value from allowed range.


[View source]
def materialize(hint = Time.local.at_beginning_of_minute, strict = true) #

Returns a new, "materialized" VirtualTime, i.e. an object where all fields have "materialized"/specific values


[View source]
def materialize_date_with_hint(time : Time = Time.local.at_beginning_of_minute, carry = 0) #

Materialize date part of current VT


[View source]
def materialize_time_with_hint(time : Time = Time.local.at_beginning_of_minute, carry = 0) #

Materialize time part of current VT


[View source]
def materialize_with_hint(time : Time = Time.local.at_beginning_of_minute, carry = 0) #

Materializes VT and returns fields needed to create a Time object. This function does not check that the materialized values match the week number, day of week, and day of year constraints. If you need those values checked, use #to_time.


[View source]
def millisecond : Virtual #

def millisecond=(millisecond : Virtual) #

def minute : Virtual #

def minute=(minute : Virtual) #

def month : Virtual #

def month=(month : Virtual) #

def nanosecond : Virtual #

def nanosecond=(nanosecond : Virtual) #

def second : Virtual #

def second=(second : Virtual) #

def step(interval = 1.minute, by = 1, from = Time.local.at_end_of_minute) : Iterator #

Returns Iterator


[View source]
def succ(from : Time = Time.local.at_end_of_minute) #

Produces closest-next Time that matches the current VT, starting with from + 1 nanosecond onwards


[View source]
def to_time(hint = Time.local.at_beginning_of_minute, strict = true) #

Converts a VirtualTime to a specific Time object that matches the VirtualTime.

Value is converted using a time hint, which defaults to the current time. Lists and ranges of values materialize to their min / begin value.

Additionally, any requirements for week number, day of week, and day of year are also met, possibly by doing multiple iterations to find a suitable date. The process is limited to some max attempts of trying to find a value that simultaneously satisfies all constraints.


[View source]
def to_tuple #

Outputs VirtualTime instance as a tuple with signature Tuple(11x Virtual, Time::Location?)


[View source]
def week : Virtual #

def week=(week : Virtual) #

def year : Virtual #

def year=(year : Virtual) #

Macro Detail

macro adjust_wanted_re_max #

If max is specified, adjusts hint in respect to max.

Specifically, if hint is equal or greater than max, it wraps it around by increasing carry by 1 and reducing hint by max.

The current implementation does not support wrapping more than once, e.g. a wanted of 120 with a max of 60 would produce an error. That is because some of VirtualTimes fields (like e.g. #day) do not have a fixed max value (it can be 28, 29, 30, or 31, depending on month).


[View source]
macro virtual_time_property(*properties) #

Macro to define properties with a common YAML converter


[View source]