fix time parse doc

[icyleaf]

Fixed document but i still ask why not use Time::Location.local by default if time string was not contain timezone?

[RX14]

The output is actually 2016-04-05 00:00:00.0 +01:00 now.

[icyleaf]

I did not verify it. 😞
In fact the output is 2016-04-05 00:00:00.0 +08:00 Local now.

[straight-shoota]

i still ask why not use Time::Location.local by default if time string was not contain timezone?

Using the local time zone is not always a sane default and can lead to unexpected errors.
See #5324 (comment) for details.

[straight-shoota]

The exact output of the zone offset depends on the local time zone, so it will inevitably vary. It would probably be better to just use a specific time zone for this.

[icyleaf]

Ping, could it merge?

[asterite]

I don't understand this api. Location is optional, but if a location can't be determined it raises? Like, imagine the time comes from user input: sometimes it works, sometimes it raises.

I think the default should be UTC, or else require a location, and maybe have parse_utc, parse_local and parse_with_location.

Just an opinion, though, but I think every other language assumes a location.

[straight-shoota]

Assuming any location (be it UTC, local or anything else) is error prone and such an errors would be hard to detect.

But it could be an improvement to always require a value for location and maybe provide short cuts parse_utc and parse_local. It could still allow a nil value to enforce the parser raises when the formatted string doesn't provide location information. and/or have parse_with_location for that.

It could just be like this:

def self.parse(time : String, pattern : String, location : Location) : Time
  Format.new(pattern, location).parse(time)
end

def self.parse_utc(time : String, pattern : String) : Time
  Format.new(pattern, Location::UTC).parse(time)
end

def self.parse_local(time : String, pattern : String) : Time
  Format.new(pattern, Location.local).parse(time)
end

def self.parse_with_location(time : String, pattern : String) : Time
  Format.new(pattern, nil).parse(time)
end

[straight-shoota]

This can be closed due to #6369. The fix was included there.