VirtualTime
Inherits YAML::Serializable / Comparable / Reference / Object
Constants
Names of the value-carrying properties, in the order they are serialized
Number of hints #materialize_to_time tries before giving up on finding a
month in which the materialized date exists.
Widest field a Proc is asked about value by value. Everything but the
nanosecond fits, and a second's worth of nanoseconds does not.
Number of times #materialize_with_hint lets the finer fields start over.
Materializes time part of current VT
How many times a #millisecond and a #nanosecond rule are played off
against each other before the pair is taken as settled.
How many times #to_time starts the walk again in a later year the rule
allows, when the year it was in only holds matches behind the hint.
Constructors
Class methods
Creates VirtualTime from Time.
This can be useful to produce a VT with values filled in quickly, and then set some fields 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.
Instance methods
Compares VirtualTime to Time instance.
Returns 0 if the time matches the VirtualTime, and nil otherwise.
A VirtualTime is a pattern without a meaningful position relative to a
specific point in time, so < and > are always false, and <= and
>= are true exactly when the time matches (Comparable semantics for an
undefined ordering, where the only defined outcome is "equal").
Returns whether the two describe the same rule.
#location and #default_match? count towards that: both decide which
Times the object matches, so leaving them out would call two objects
equal that match disjoint sets of times -- and collapse them in a Set.
"Rewinds" day forward enough to reach acceptable_day.
It wraps around wrap_day, so e.g. adjust_day(25, 5, 30) returns 10.days
Ensures that Time's timezone is equal to VT's timezone.
Raises ArgumentError if comparing two VTs with different timezones.
Adjusts values to be suitable for use in comparisons.
At the moment, that includes converting negative values to offsets from end of range, and sorting Arrays and Sets.
If calling this function yourself, provide max whenever possible.
A range whose begin exceeds its end is left as it is, and matches nothing:
wrapping ranges are not supported, so hour: -1..1 is an empty rule rather
than "23:00 through 01:00". Write those as two rules, or as a list.
Sets time-related VT fields to nil
#location is left alone: it converts the whole timestamp before matching,
so it bears on the date as much as on the time of day, and dropping it here
would quietly change what #matches_date? answers. #clear! resets it.
Instance-default match result if one of field values matched is nil
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 so far.
#default_match? is carried over, since without it the expansion of a VT
that matches nothing would be a set of VTs that match nearly everything.
Hashes the same fields #== compares, so that two VirtualTimes that
compare equal also land in the same Hash bucket and dedupe in a Set.
Location/timezone in which to perform matching, if any
Performs matching between VirtualTime and other supported types
An unconstrained (nil) value is governed by the #default_match? of the
VirtualTime it belongs to. a is this one's own field, so a_default
defaults to this one's setting; b_default names the setting on the other
side, and only differs when matching against another VirtualTime that
was built with a different one.
Returns whether VirtualTime matches the specified time
Returns whether VirtualTime matches the date part of specified time
Returns whether VirtualTime matches the time part of specified time
Materializes a particular value with the help of a wanted/hint value.
If 'strict' is true and some of the wanted fields would not match? VT's requirements,
they are replaced/overriden with the first/earliest value from the allowed range.
variable_max says the supplied max varies with the hint -- the length
of a month, the weeks of an ISO year, the days of a year. Only then can a
negative-bound value that adjusts to empty be empty for this hint alone,
and only then is the below-floor sentinel returned instead of raising;
a field with a fixed max (hour, minute, ...) that adjusts to empty is
empty for every hint and raises outright.
Returns a new, "materialized" VirtualTime, i.e. an object where all fields have "materialized"/specific values
#location and #default_match? are carried over to the new object; the
week number, day of week, and day of year are left unset, since they are
implied by the materialized date.
Materializes date part of current VT
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.
Returns Iterator
interval is how far past the last match the search for the next one
resumes, and by is how many matches each #next advances by. Both have
to be positive: a zero interval or by would make the iterator hand back
the same Time forever, and a negative interval would walk backwards.
Produces closest-next Time that matches the current VT, starting with from + 1 nanosecond onwards.
(Because it always finds the "next" time, the default value is at_end_of_minute (:99).)
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.
Outputs VirtualTime instance as a tuple with signature Tuple(11x Virtual, Time::Location?)
Writes self as a YAML mapping.
The mapping is built here rather than generated because
YAML::Serializable tests a converter-backed property for truthiness
before handing it to the converter: a field set to false (never match)
would be written out as null and read back as nil (match anything),
inverting the rule. Reading still goes through VirtualConverter, which
the @[YAML::Field] annotations above take care of.
Macros
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).