Snails

Module: Snails::DateAndTime::Calculations

Defined in:
runtime/snails/date_and_time/calculations.rbs,
runtime/snails/date_and_time/calculations.rb

Class Method Summary collapse

Class Method Details

.beginning_of_day(t) ⇒ Time

midnight at the start of t's day.

Examples:

Snails::DateAndTime::Calculations.beginning_of_day(Time.utc(2024, 1, 2, 3, 4, 5))
# => 2024-01-02 00:00:00 UTC

Parameters:

  • t (Time) —

    the instant whose day is measured

Returns:

  • (Time) —

    the day's midnight



219
 
# File 'runtime/snails/date_and_time/calculations.rb', line 219

def self.beginning_of_day: (Time t) -> Time

.beginning_of_hour(t) ⇒ Time

the start of t's hour: minutes and smaller fields are zeroed.

Examples:

Snails::DateAndTime::Calculations.beginning_of_hour(Time.utc(2024, 1, 2, 3, 4, 5))
# => 2024-01-02 03:00:00 UTC

Parameters:

  • t (Time) —

    the instant whose hour is measured

Returns:

  • (Time) —

    the hour's start



196
 
# File 'runtime/snails/date_and_time/calculations.rb', line 196

def self.beginning_of_hour: (Time t) -> Time

.beginning_of_minute(t) ⇒ Time

the start of t's minute: seconds and smaller fields are zeroed.

Examples:

Snails::DateAndTime::Calculations.beginning_of_minute(Time.utc(2024, 1, 2, 3, 4, 5))
# => 2024-01-02 03:04:00 UTC

Parameters:

  • t (Time) —

    the instant whose minute is measured

Returns:

  • (Time) —

    the minute's start



173
 
# File 'runtime/snails/date_and_time/calculations.rb', line 173

def self.beginning_of_minute: (Time t) -> Time

.beginning_of_month(t) ⇒ Time

the 1st at 00:00 of t's month.

Examples:

Snails::DateAndTime::Calculations.beginning_of_month(Time.utc(2024, 1, 2, 3, 4, 5))
# => 2024-01-01 00:00:00 UTC

Parameters:

  • t (Time) —

    the instant whose month is measured

Returns:

  • (Time) —

    the month's first day at midnight



297
 
# File 'runtime/snails/date_and_time/calculations.rb', line 297

def self.beginning_of_month: (Time t) -> Time

.beginning_of_week(t) ⇒ Time

Monday 00:00 of the week containing t; weeks start on Monday.

Examples:

Snails::DateAndTime::Calculations.beginning_of_week(Time.utc(2024, 1, 3, 3, 4, 5))
# => 2024-01-01 00:00:00 UTC

Parameters:

  • t (Time) —

    the instant whose week is measured

Returns:

  • (Time) —

    the week's Monday at midnight



253
 
# File 'runtime/snails/date_and_time/calculations.rb', line 253

def self.beginning_of_week: (Time t) -> Time

.beginning_of_year(t) ⇒ Time

January 1st at 00:00 of t's year.

Examples:

Snails::DateAndTime::Calculations.beginning_of_year(Time.utc(2024, 1, 2, 3, 4, 5))
# => 2024-01-01 00:00:00 UTC

Parameters:

  • t (Time) —

    the instant whose year is measured

Returns:

  • (Time) —

    the year's first day at midnight



319
 
# File 'runtime/snails/date_and_time/calculations.rb', line 319

def self.beginning_of_year: (Time t) -> Time

.civil_days(y, m, d) ⇒ Integer

the civil date as a day count from 1970-01-01, derived from the calendar fields rather than an instant's epoch seconds.

Examples:

Snails::DateAndTime::Calculations.civil_days(2024, 1, 2)  # => 19724

Parameters:

Returns:

  • (Integer) —

    days since the epoch



18
 
# File 'runtime/snails/date_and_time/calculations.rb', line 18

def self.civil_days: (Integer y, Integer m, Integer d) -> Integer

.days_ago(t, n = 1) ⇒ Time

n civil days earlier at the same wall-clock time; the negative twin of days_since.

Examples:

Snails::DateAndTime::Calculations.days_ago(Time.utc(2024, 1, 2, 3, 4, 5))
# => 2024-01-01 03:04:05 UTC

Parameters:

  • t (Time) —

    the instant to shift

  • n (Integer) (defaults to: 1) —

    the day count (default 1)

Returns:

  • (Time) —

    the shifted instant



60
 
# File 'runtime/snails/date_and_time/calculations.rb', line 60

def self.days_ago: (Time t, ?Integer n) -> Time

.days_in_month(y, m) ⇒ Integer

the number of days in the civil month.

Examples:

Snails::DateAndTime::Calculations.days_in_month(2024, 2)  # => 29

Parameters:

  • y (Integer) —

    the civil year

  • m (Integer) —

    the civil month (1–12)

Returns:



34
 
# File 'runtime/snails/date_and_time/calculations.rb', line 34

def self.days_in_month: (Integer y, Integer m) -> Integer

.days_since(t, n = 1) ⇒ Time

n civil days later at the same wall-clock time; the day count walks the calendar, so a DST transition cannot move the clock.

Examples:

Snails::DateAndTime::Calculations.days_since(Time.utc(2024, 1, 2, 3, 4, 5))
# => 2024-01-03 03:04:05 UTC

Parameters:

  • t (Time) —

    the instant to shift

  • n (Integer) (defaults to: 1) —

    the day count (default 1)

Returns:

  • (Time) —

    the shifted instant



47
 
# File 'runtime/snails/date_and_time/calculations.rb', line 47

def self.days_since: (Time t, ?Integer n) -> Time

.end_of_day(t) ⇒ Time

the inclusive end of t's day, on the last nanosecond (23:59:59.999999999).

Examples:

Snails::DateAndTime::Calculations.end_of_day(Time.utc(2024, 1, 2, 3, 4, 5))
# => 2024-01-02 23:59:59.999999999 UTC

Parameters:

  • t (Time) —

    the instant whose day is measured

Returns:

  • (Time) —

    the day's inclusive end



231
 
# File 'runtime/snails/date_and_time/calculations.rb', line 231

def self.end_of_day: (Time t) -> Time

.end_of_hour(t) ⇒ Time

the inclusive end of t's hour, on the last nanosecond (…:59.999999999).

Examples:

Snails::DateAndTime::Calculations.end_of_hour(Time.utc(2024, 1, 2, 3, 4, 5))
# => 2024-01-02 03:59:59.999999999 UTC

Parameters:

  • t (Time) —

    the instant whose hour is measured

Returns:

  • (Time) —

    the hour's inclusive end



208
 
# File 'runtime/snails/date_and_time/calculations.rb', line 208

def self.end_of_hour: (Time t) -> Time

.end_of_minute(t) ⇒ Time

the inclusive end of t's minute, on the last nanosecond (…:59.999999999).

Examples:

Snails::DateAndTime::Calculations.end_of_minute(Time.utc(2024, 1, 2, 3, 4, 5))
# => 2024-01-02 03:04:59.999999999 UTC

Parameters:

  • t (Time) —

    the instant whose minute is measured

Returns:

  • (Time) —

    the minute's inclusive end



185
 
# File 'runtime/snails/date_and_time/calculations.rb', line 185

def self.end_of_minute: (Time t) -> Time

.end_of_month(t) ⇒ Time

the last day of t's month at its inclusive end (leap years included).

Examples:

Snails::DateAndTime::Calculations.end_of_month(Time.utc(2024, 1, 2, 3, 4, 5))
# => 2024-01-31 23:59:59.999999999 UTC

Parameters:

  • t (Time) —

    the instant whose month is measured

Returns:

  • (Time) —

    the month's last day at its inclusive end



308
 
# File 'runtime/snails/date_and_time/calculations.rb', line 308

def self.end_of_month: (Time t) -> Time

.end_of_week(t) ⇒ Time

Sunday 23:59:59.999999999 of the week containing t.

Examples:

Snails::DateAndTime::Calculations.end_of_week(Time.utc(2024, 1, 3, 3, 4, 5))
# => 2024-01-07 23:59:59.999999999 UTC

Parameters:

  • t (Time) —

    the instant whose week is measured

Returns:

  • (Time) —

    the week's Sunday at its inclusive end



264
 
# File 'runtime/snails/date_and_time/calculations.rb', line 264

def self.end_of_week: (Time t) -> Time

.end_of_year(t) ⇒ Time

December 31st at its inclusive end of t's year.

Examples:

Snails::DateAndTime::Calculations.end_of_year(Time.utc(2024, 1, 2, 3, 4, 5))
# => 2024-12-31 23:59:59.999999999 UTC

Parameters:

  • t (Time) —

    the instant whose year is measured

Returns:

  • (Time) —

    the year's last day at its inclusive end



330
 
# File 'runtime/snails/date_and_time/calculations.rb', line 330

def self.end_of_year: (Time t) -> Time

.future?(t, now) ⇒ Boolean

t is later than now.

Examples:

Snails::DateAndTime::Calculations.future?(Time.utc(2024, 1, 2), Time.utc(2024, 1, 1))
# => true

Parameters:

  • t (Time) —

    the instant under test

  • now (Time) —

    the clock to compare against

Returns:

  • (Boolean) —

    true when t follows now



402
 
# File 'runtime/snails/date_and_time/calculations.rb', line 402

def self.future?: (Time t, Time now) -> bool

.months_ago(t, n = 1) ⇒ Time

n calendar months earlier at the same wall-clock time; the negative twin of months_since.

Examples:

Snails::DateAndTime::Calculations.months_ago(Time.utc(2024, 3, 31, 3, 4, 5))
# => 2024-02-29 03:04:05 UTC

Parameters:

  • t (Time) —

    the instant to shift

  • n (Integer) (defaults to: 1) —

    the month count (default 1)

Returns:

  • (Time) —

    the shifted instant



136
 
# File 'runtime/snails/date_and_time/calculations.rb', line 136

def self.months_ago: (Time t, ?Integer n) -> Time

.months_since(t, n = 1) ⇒ Time

n calendar months later at the same wall-clock time; the day clamps to the target month's last day (Jan 31 + 1 month is Feb 29 in a leap year).

Examples:

Snails::DateAndTime::Calculations.months_since(Time.utc(2024, 1, 31, 3, 4, 5))
# => 2024-02-29 03:04:05 UTC

Parameters:

  • t (Time) —

    the instant to shift

  • n (Integer) (defaults to: 1) —

    the month count (default 1)

Returns:

  • (Time) —

    the shifted instant



119
 
# File 'runtime/snails/date_and_time/calculations.rb', line 119

def self.months_since: (Time t, ?Integer n) -> Time

.next_week(t) ⇒ Time

Monday 00:00 of the week after t's week.

Examples:

Snails::DateAndTime::Calculations.next_week(Time.utc(2024, 1, 3, 3, 4, 5))
# => 2024-01-08 00:00:00 UTC

Parameters:

  • t (Time) —

    the instant whose week is measured

Returns:

  • (Time) —

    the following week's Monday at midnight



275
 
# File 'runtime/snails/date_and_time/calculations.rb', line 275

def self.next_week: (Time t) -> Time

.noon(t) ⇒ Time

12:00:00 of t's day.

Examples:

Snails::DateAndTime::Calculations.noon(Time.utc(2024, 1, 2, 3, 4, 5))
# => 2024-01-02 12:00:00 UTC

Parameters:

  • t (Time) —

    the instant whose day is measured

Returns:

  • (Time) —

    the day's midpoint



242
 
# File 'runtime/snails/date_and_time/calculations.rb', line 242

def self.noon: (Time t) -> Time

.on_wday?(t, wday) ⇒ Boolean

t falls on the given Sunday-based weekday (0 Sunday … 6 Saturday).

Examples:

Snails::DateAndTime::Calculations.on_wday?(Time.utc(2024, 1, 6), 6)  # => true

Parameters:

  • t (Time) —

    the instant under test

  • wday (Integer) —

    the Sunday-based weekday, 0 to 6

Returns:

  • (Boolean) —

    true when t.wday equals wday



433
 
# File 'runtime/snails/date_and_time/calculations.rb', line 433

def self.on_wday?: (Time t, Integer wday) -> bool

.on_weekday?(t) ⇒ Boolean

t falls on Monday through Friday.

Examples:

Snails::DateAndTime::Calculations.on_weekday?(Time.utc(2024, 1, 6))  # => false

Parameters:

  • t (Time) —

    the instant under test

Returns:

  • (Boolean) —

    true on a weekday



422
 
# File 'runtime/snails/date_and_time/calculations.rb', line 422

def self.on_weekday?: (Time t) -> bool

.on_weekend?(t) ⇒ Boolean

t falls on Saturday or Sunday.

Examples:

Snails::DateAndTime::Calculations.on_weekend?(Time.utc(2024, 1, 6))  # => true

Parameters:

  • t (Time) —

    the instant under test

Returns:

  • (Boolean) —

    true on the weekend



412
 
# File 'runtime/snails/date_and_time/calculations.rb', line 412

def self.on_weekend?: (Time t) -> bool

.past?(t, now) ⇒ Boolean

t is earlier than now.

Examples:

Snails::DateAndTime::Calculations.past?(Time.utc(2024, 1, 2), Time.utc(2024, 1, 3))
# => true

Parameters:

  • t (Time) —

    the instant under test

  • now (Time) —

    the clock to compare against

Returns:

  • (Boolean) —

    true when t precedes now



390
 
# File 'runtime/snails/date_and_time/calculations.rb', line 390

def self.past?: (Time t, Time now) -> bool

.prev_week(t) ⇒ Time

Monday 00:00 of the week before t's week.

Examples:

Snails::DateAndTime::Calculations.prev_week(Time.utc(2024, 1, 3, 3, 4, 5))
# => 2023-12-25 00:00:00 UTC

Parameters:

  • t (Time) —

    the instant whose week is measured

Returns:

  • (Time) —

    the previous week's Monday at midnight



286
 
# File 'runtime/snails/date_and_time/calculations.rb', line 286

def self.prev_week: (Time t) -> Time

.same_day?(a, b) ⇒ Boolean

both instants fall on the same civil date.

Examples:

Snails::DateAndTime::Calculations.same_day?(Time.utc(2024, 1, 2, 1), Time.utc(2024, 1, 2, 23))
# => true

Parameters:

  • a (Time) —

    one instant

  • b (Time) —

    the other instant

Returns:

  • (Boolean) —

    true when year, month, and day match



342
 
# File 'runtime/snails/date_and_time/calculations.rb', line 342

def self.same_day?: (Time a, Time b) -> bool

.today?(t, now) ⇒ Boolean

t falls on now's civil date.

Examples:

Snails::DateAndTime::Calculations.today?(Time.utc(2024, 1, 2, 1), Time.utc(2024, 1, 2, 23))
# => true

Parameters:

  • t (Time) —

    the instant under test

  • now (Time) —

    the clock to compare against

Returns:

  • (Boolean) —

    true when both instants fall on the same day



354
 
# File 'runtime/snails/date_and_time/calculations.rb', line 354

def self.today?: (Time t, Time now) -> bool

.tomorrow(t) ⇒ Time

one civil day later at the same wall-clock time.

Examples:

Snails::DateAndTime::Calculations.tomorrow(Time.utc(2024, 1, 2, 3, 4, 5))
# => 2024-01-03 03:04:05 UTC

Parameters:

  • t (Time) —

    the instant to shift

Returns:

  • (Time) —

    the next day at the same clock time



82
 
# File 'runtime/snails/date_and_time/calculations.rb', line 82

def self.tomorrow: (Time t) -> Time

.tomorrow?(t, now) ⇒ Boolean

t falls on the civil date after now.

Examples:

Snails::DateAndTime::Calculations.tomorrow?(Time.utc(2024, 1, 2, 3), Time.utc(2024, 1, 1, 3))
# => true

Parameters:

  • t (Time) —

    the instant under test

  • now (Time) —

    the clock to compare against

Returns:

  • (Boolean) —

    true when t falls on the day after now



378
 
# File 'runtime/snails/date_and_time/calculations.rb', line 378

def self.tomorrow?: (Time t, Time now) -> bool

.weeks_ago(t, n = 1) ⇒ Time

n weeks (7 days each) earlier at the same wall-clock time.

Examples:

Snails::DateAndTime::Calculations.weeks_ago(Time.utc(2024, 1, 2, 3, 4, 5), 2)
# => 2023-12-19 03:04:05 UTC

Parameters:

  • t (Time) —

    the instant to shift

  • n (Integer) (defaults to: 1) —

    the week count (default 1)

Returns:

  • (Time) —

    the shifted instant



106
 
# File 'runtime/snails/date_and_time/calculations.rb', line 106

def self.weeks_ago: (Time t, ?Integer n) -> Time

.weeks_since(t, n = 1) ⇒ Time

n weeks (7 days each) later at the same wall-clock time.

Examples:

Snails::DateAndTime::Calculations.weeks_since(Time.utc(2024, 1, 2, 3, 4, 5), 2)
# => 2024-01-16 03:04:05 UTC

Parameters:

  • t (Time) —

    the instant to shift

  • n (Integer) (defaults to: 1) —

    the week count (default 1)

Returns:

  • (Time) —

    the shifted instant



94
 
# File 'runtime/snails/date_and_time/calculations.rb', line 94

def self.weeks_since: (Time t, ?Integer n) -> Time

.years_ago(t, n = 1) ⇒ Time

n calendar years (12 months each) earlier at the same wall-clock time; the negative twin of years_since.

Examples:

Snails::DateAndTime::Calculations.years_ago(Time.utc(2024, 3, 31, 3, 4, 5))
# => 2023-03-31 03:04:05 UTC

Parameters:

  • t (Time) —

    the instant to shift

  • n (Integer) (defaults to: 1) —

    the year count (default 1)

Returns:

  • (Time) —

    the shifted instant



162
 
# File 'runtime/snails/date_and_time/calculations.rb', line 162

def self.years_ago: (Time t, ?Integer n) -> Time

.years_since(t, n = 1) ⇒ Time

n calendar years (12 months each) later at the same wall-clock time; a leap day clamps to the target month's last day.

Examples:

Snails::DateAndTime::Calculations.years_since(Time.utc(2024, 2, 29, 3, 4, 5))
# => 2025-02-28 03:04:05 UTC

Parameters:

  • t (Time) —

    the instant to shift

  • n (Integer) (defaults to: 1) —

    the year count (default 1)

Returns:

  • (Time) —

    the shifted instant



149
 
# File 'runtime/snails/date_and_time/calculations.rb', line 149

def self.years_since: (Time t, ?Integer n) -> Time

.yesterday(t) ⇒ Time

one civil day earlier at the same wall-clock time.

Examples:

Snails::DateAndTime::Calculations.yesterday(Time.utc(2024, 1, 2, 3, 4, 5))
# => 2024-01-01 03:04:05 UTC

Parameters:

  • t (Time) —

    the instant to shift

Returns:

  • (Time) —

    the previous day at the same clock time



71
 
# File 'runtime/snails/date_and_time/calculations.rb', line 71

def self.yesterday: (Time t) -> Time

.yesterday?(t, now) ⇒ Boolean

t falls on the civil date before now.

Examples:

Snails::DateAndTime::Calculations.yesterday?(Time.utc(2024, 1, 2, 3), Time.utc(2024, 1, 3, 3))
# => true

Parameters:

  • t (Time) —

    the instant under test

  • now (Time) —

    the clock to compare against

Returns:

  • (Boolean) —

    true when t falls on the day before now



366
 
# File 'runtime/snails/date_and_time/calculations.rb', line 366

def self.yesterday?: (Time t, Time now) -> bool