Add Time::Location.load? (#16121)

Author: straight-shoota

spec/std/time/location_spec.cr

@@ -198,6 +198,67 @@ class Time::Location
       end
     end
 
+    describe ".load?" do
+      it "loads Europe/Berlin" do
+        with_zoneinfo do
+          Time::Location.load?("Europe/Berlin").should eq Time::Location.load("Europe/Berlin")
+        end
+      end
+
+      it "returns nil if unavailable" do
+        Location.load?("Foobar/Baz").should be_nil
+
+        with_zoneinfo(datapath("zoneinfo")) do
+          Location.load?("Foobar/Baz").should be_nil
+        end
+      end
+
+      it "invalid zone file" do
+        expect_raises(Time::Location::InvalidTZDataError) do
+          Location.load?("Foo/invalid", [datapath("zoneinfo")])
+        end
+      end
+
+      it "treats UTC as special case" do
+        with_zoneinfo do
+          Location.load?("UTC").should eq Location::UTC
+          Location.load?("").should eq Location::UTC
+          Location.load?("Etc/UTC").should eq Location::UTC
+        end
+      end
+
+      describe "raises on invalid location name" do
+        it "absolute path" do
+          with_zoneinfo do
+            expect_raises(InvalidLocationNameError) do
+              Location.load?("/America/New_York")
+            end
+            expect_raises(InvalidLocationNameError) do
+              Location.load?("\\Zulu")
+            end
+          end
+        end
+
+        it "dot dot" do
+          with_zoneinfo do
+            expect_raises(InvalidLocationNameError) do
+              Location.load?("../zoneinfo/America/New_York")
+            end
+            expect_raises(InvalidLocationNameError) do
+              Location.load?("a..")
+            end
+          end
+        end
+      end
+
+      it "caches result" do
+        with_zoneinfo do
+          location = Location.load?("Europe/Berlin")
+          Location.load?("Europe/Berlin").should be location
+        end
+      end
+    end
+
     describe ".load_android" do
       it "loads Europe/Berlin" do
         Location.__clear_location_cache

src/time/location.cr

@@ -299,7 +299,26 @@ class Time::Location
   # Files are cached based on the modification time, so subsequent request for
   # the same location name will most likely return the same instance of
   # `Location`, unless the time zone database has been updated in between.
+  #
+  # - `.load?` returns `nil` if the location is unavailable.
   def self.load(name : String) : Location
+    load?(name) { |source| raise InvalidLocationNameError.new(name, source) }
+  end
+
+  # :ditto:
+  #
+  # Returns `nil` if the location is unavailable.
+  # Raises `InvalidLocationNameError` if the name is invalid.
+  # Raises `InvalidTZDataError` if the loader encounters a format error in the
+  # time zone database.
+  #
+  # - `.load` raises if the location is unavailable.
+  def self.load?(name : String) : Location?
+    load?(name) { return }
+  end
+
+  # :nodoc:
+  def self.load?(name : String, & : String? ->) : Location?
     case name
     when "", "UTC", "Etc/UTC"
       # `UTC` is a special identifier, empty string represents a fallback mechanism.
@@ -318,11 +337,11 @@ class Time::Location
         if location = load_from_dir_or_zip(name, zoneinfo)
           return location
         else
-          raise InvalidLocationNameError.new(name, zoneinfo)
+          yield zoneinfo
         end
       end
 
-      if location = load(name, Crystal::System::Time.zone_sources)
+      if location = load(name, Crystal::System::Time.zone_sources) { |source| yield source }
         return location
       end
 
@@ -341,7 +360,7 @@ class Time::Location
         return location
       end
 
-      raise InvalidLocationNameError.new(name)
+      yield nil
     end
   end
 

src/time/location/loader.cr

@@ -20,15 +20,25 @@ class Time::Location
 
   # :nodoc:
   def self.load(name : String, sources : Enumerable(String)) : Time::Location?
+    load(name, sources) { |source| raise InvalidLocationNameError.new(name, source) }
+  end
+
+  # :nodoc:
+  def self.load(name : String, sources : Enumerable(String), &) : Time::Location?
     if source = find_zoneinfo_file(name, sources)
-      load_from_dir_or_zip(name, source) || raise InvalidLocationNameError.new(name, source)
+      load_from_dir_or_zip(name, source) || yield source
     end
   end
 
   # :nodoc:
   def self.load_android(name : String, sources : Enumerable(String)) : Time::Location?
+    load_android(name, sources) { |path| raise InvalidLocationNameError.new(name, path) }
+  end
+
+  # :nodoc:
+  def self.load_android(name : String, sources : Enumerable(String), &) : Time::Location?
     if path = find_android_tzdata_file(sources)
-      load_from_android_tzdata(name, path) || raise InvalidLocationNameError.new(name, path)
+      load_from_android_tzdata(name, path) || yield path
     end
   end