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.

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).

Macro to define properties with a common YAML converter

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.

Compares VirtualTime to Time instance

Alias for #matches?.

"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 all VT fields, #location included, to nil

Sets date-related VT fields to nil

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

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

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.