[ruby-core:110459] [Ruby master Feature#19071] Add Time#deconstruct, #deconstruct_keys, and #to_h

["zverok (Victor Shepelev)" <noreply@ruby-lang.org>]

Issue #19071 has been updated by zverok (Victor Shepelev).


@matz Understood, thanks, I'll adjust the PR.

@sawa, for the sake of the argument
> The sequence `[year, month, mday, hour, min, sec, subsec]` is culturally biased and is arbitrarily selected.

I don't think this statement is fair. This sequence of units is not natural for some particular culture. E.g. 18:10 at Oct 21 would be written "10/21/22 6:10pm" in US, and "18:10 21.10.2022" in Ukraine, but `"2022-10-21 18:10:00"` is rather a common engineering implementation, logically structured for unambiguous parsing and sorting. 

I understand there are different cultures out there (and for some, it is not "Oct 21, 2022" at all, but maybe "26 Tishrei, 5783" or "25 Rabi ul Awal 1444", or something else), but I believe it can be said with a high confidence that 
1. when seeing a sequence of numbers starting with `2022,` or `year,`, most of **developers** can guess the forthcoming units.
2. when trying to design or guess sequence of units of Time/Date representation _today_ (with widespread standardization, JSON serializations etc.), the best guess would be close to ISO8601 Date & Time format.

----------------------------------------
Feature #19071: Add Time#deconstruct, #deconstruct_keys, and #to_h
https://bugs.ruby-lang.org/issues/19071#change-99777

* Author: zverok (Victor Shepelev)
* Status: Open
* Priority: Normal
----------------------------------------
I believe that `Time` being suitable for pattern-matching is a reasonable feature with many possible usages, which will increase usability of `Time` and would be a good show case for pattern matching.

**Implementation decisions**

`Time#deconstruct`: 
* returns time components in order `[year, month, mday, hour, min, sec, subsec]`
* I believe the highest-to-lowest order is the only reasonable/guessable, and there is no point to put into the array _all_ of the time information available (e.g. zone, wday, yday)
* I am not sure (and open to discussion) about `subsec`. It seems to me the most basic sub-second unit of Time, but I might be wrong; also, it might be not that useful for array deconstruction.

Possible usage:
```ruby
case tm
in [...2022, *]
  puts "previous year"
in [2022, 1..6, *]
  puts "Q1-2"
in [2022, 7..9, *]
  puts "Q3"
in [2022, month, day, *]
  puts "Current quarter, #{day}/#{month}"
end
```

`Time#deconstruct_keys`: 
* chosen keys: `[:year, :month, :day, :yday, :wday, :hour, :min, :sec, :subsec, :dst, :zone]` 
* I am open to discussing whether we should include other subsecond units (or any whatsoever)
* It might be useful (but too loose interface) to support `mon` as a synonym for `month`?.. But might be confusing if somebody will unpack the `**rest`
* `day`, not `mday`, seems most reasonable

Possible usages:
```ruby
case t
in year: ...2022
  puts "too old"
in month: ..9
  puts "quarter 1-3"
in wday: 1..5, month:
  puts "working day in month #{month}"
end

if t in Time(wday: 3, day: ..7)
  puts "first Wednesday of the month"
end
```

`Time#to_h`:
* added on a "why not" basis :) As we already have "convert to hash" in the form of `deconstruct_keys(nil)`, having a canonic form seems harmles. Open for discussion.
* keys are the same as for `deconstruct_keys`

Pull request: https://github.com/ruby/ruby/pull/6594



-- 
https://bugs.ruby-lang.org/