Add Time#to_local_in

[straight-shoota]

Closes #5789

[wooster0]

Typo: time1

[asterite]

This looks a bit redundant: Time.from_wall_clock(time, ...). It reminds me of elixir: String.length(string).

Can we somehow provide an instance method instead?

[straight-shoota]

It would of course also work as an instance method.
However, I purposely chose a constructor because it creates a new instance from combining the wall readings of the time argument with the given location.

This way it is not likely to be confused with Time#in(location).

I'm definitely open to change it to an instance method. Suggestions are welcome!

[asterite]

time.to_wall_clock_in(location)

I'm not sure it reads well (grammatically), so if we can't come up with an instance name the class method is fine.

[jhass]

I'm fine with the class method but could also live with something like same_wall_clock_in.

[paulcsmith]

It might be helpful to talk about how this differs from Time#in. Right now it is difficult to tell which one to use and how they are different

[jhass]

Maybe we can use two real timezones like New York and Tokyo and then call the vars new_york_time, tokyo_wall_clock_time or so? (Admittedly not great names yet). time, time2 gets confusing fast here :/

[RX14]

Needs to not be a class method.

[bcardiff]

If Time is seen as an immutable struct, like record maybe we can keep the recent idiom of #copy_with method that will allow the user to override any specific part of the value.

[straight-shoota]

@bcardiff copy_with might be a useful addition to Time, but I'm not sure it would be a great here, because it doesn't tell there's a difference to #in. In fact, I would expect #copy_with with a location to do the same thing as #in because it just copies the instance with the bew location.

[straight-shoota]

If there was a local date time representation (floating time), this could be expressed for example like in the Java 8 Date Time API as time.toLocal().atZone(location).
Without the intermediary step, this could become time.to_local_in(location) in Crystal. That's similar to @asterite proposal but with a more formal term.

[straight-shoota]

Rebased and renamed Time.from_wall_clock to Time#to_local_in.

[ysbaddaden]

This is too abstract. The naming doesn't give much hint at what the method means to achieve, and the documentation doesn't really help until the last example.

The following would be more helpful, and enough to understand:

Creates a new Time instance with only the location changed. Unlike #in that will shift the date time so the new Time instance still refers to the same UTC timestamp, #to_local_in keeps the same date and time but for another location.

For example:

halloween = Time.utc(2018, 10, 31, 17, 30, 0)
tokyo = halloween.to_local_in(Time::Location.load("Asia/Tokyo"))
new_york = halloween.to_local_in(Time::Location.load("America/New_York"))
tokyo.to_s    # => 2018-10-31 17:30:00 Asia/Tokyo
new_york.to_s # => 2018-09-31 17:30:00 America/New_York

[straight-shoota]

Creates a new Time instance with only the location changed.

This reduces the time instance to it's local date-time representation, but in fact, this method also changes the instant on the time-line.

But I'll try to improve the documentation.

[RX14]

which always preserves the same instant in time

[straight-shoota]

Let me squash this before merging 👍