proj4rb 4.1.0 → 5.0.0

data/lib/proj/database.rb

@@ -1,305 +1,310 @@
-module Proj
-  CelestialBody = Struct.new(:auth_name, :name)
-
-  # This class provides access the Proj SQLite database called proj.db. The database
-  # stores transformation information that must be accessible for the library to work properly.
-  #
-  # @see https://proj.org/resource_files.html#proj-db
-  class Database
-    attr_reader :context
-
-    # Create a new database instance to query the Proj database
-    #
-    # @param context [Context] A proj Context
-    #
-    # @return [Database]
-    def initialize(context)
-      @context = context
-    end
-
-    # Returns the path the Proj database
-    #
-    # @see https://proj.org/development/reference/functions.html#c.proj_context_get_database_path
-    #
-    # return [String]
-    def path
-      if Api.method_defined?(:proj_context_get_database_path)
-        Api.proj_context_get_database_path(self.context)
-      end
-    end
-
-    # Sets the path to the Proj database
-    #
-    # @see https://proj.org/development/reference/functions.html#c.proj_context_set_database_path
-    #
-    # @param value [String] Path to the proj database
-    #
-    # @return [Database] Returns reference to the current database instance
-    def path=(value)
-      result = Api.proj_context_set_database_path(self.context, value, nil, nil)
-      unless result == 1
-        Error.check_context(self.context)
-      end
-      self
-    end
-
-    # Returns SQL statements to run to initiate a new valid auxiliary empty database.
-    #
-    # @see https://proj.org/development/reference/functions.html#c.proj_context_get_database_structure
-    #
-    # @return [Array<Strings>] List of sql statements
-    def structure
-      ptr = Api.proj_context_get_database_structure(self.context, nil)
-      Strings.new(ptr)
-    end
-
-    # Return a metadata from the database.
-    #
-    # @see https://proj.org/development/reference/functions.html#c.proj_context_get_database_metadata
-    #
-    # @param key [String] The name of the metadata item. Must not be nil
-    #                       Available keys:
-    #                         DATABASE.LAYOUT.VERSION.MAJOR
-    #                         DATABASE.LAYOUT.VERSION.MINOR
-    #                         EPSG.VERSION
-    #                         EPSG.DATE
-    #                         ESRI.VERSION
-    #                         ESRI.DATE
-    #                         IGNF.SOURCE
-    #                         IGNF.VERSION
-    #                         IGNF.DATE
-    #                         NKG.SOURCE
-    #                         NKG.VERSION
-    #                         NKG.DATE
-    #                         PROJ.VERSION
-    #                         PROJ_DATA.VERSION
-    #
-    # @return [String] Returned metadata
-    def metadata(key)
-      Api.proj_context_get_database_metadata(self.context, key)
-    end
-
-    # Returns the set of authority codes of the given object type.
-    #
-    # @see https://proj.org/development/reference/functions.html#c.proj_get_codes_from_database
-    #
-    # @param auth_name [String] Authority name. Must not be nil.
-    # @param pj_type [PJ_TYPE] Proj Object type.
-    # @param allow_deprecated [Boolean] Specifies if deprecated objects should be returned. Default is false.
-    #
-    # @return [Strings] Returned authority codes
-    def codes(auth_name, pj_type, allow_deprecated = false)
-      ptr = Api.proj_get_codes_from_database(self.context, auth_name, pj_type, allow_deprecated ? 1 : 0)
-      Strings.new(ptr)
-    end
-
-    # Return a list of authorities used in the database
-    #
-    # @see https://proj.org/development/reference/functions.html#c.proj_get_authorities_from_database
-    #
-    # @return [Array<Strings>] List of authorities
-    def authorities
-      ptr = Api.proj_get_authorities_from_database(self.context)
-      Strings.new(ptr)
-    end
-
-    # Enumerate CRS infos from the database, taking into account various criteria.
-    #
-    # @see https://proj.org/development/reference/functions.html#c.proj_get_crs_info_list_from_database
-    #
-    # @param auth_name [String] Authority name. Use nil to specify all authorities
-    # @param parameters [Parameters] Parameters to specify search criteria. May be nil
-    #
-    # @return [Array<CrsInfo>] Returned crs infos
-    def crs_info(auth_name = nil, parameters = nil)
-      out_result_count = FFI::MemoryPointer.new(:int)
-      ptr = Api.proj_get_crs_info_list_from_database(self.context, auth_name, parameters, out_result_count)
-
-      result = out_result_count.read_int.times.map do |index|
-        index_ptr = ptr + (index * FFI::Pointer::SIZE)
-        struct = Api::PROJ_CRS_INFO.new(index_ptr.read_pointer)
-        CrsInfo.from_proj_crs_info(struct)
-      end
-
-      Api.proj_crs_info_list_destroy(ptr)
-      result
-    end
-
-    # Returns information about a Grid from the database
-    #
-    # @see https://proj.org/development/reference/functions.html#c.proj_grid_get_info_from_database
-    #
-    # @param name [String] The name of the grid
-    #
-    # @return [Grid]
-    def grid(name)
-      out_full_name = FFI::MemoryPointer.new(:string)
-      out_package_name = FFI::MemoryPointer.new(:string)
-      out_url = FFI::MemoryPointer.new(:string)
-      out_downloadable = FFI::MemoryPointer.new(:int)
-      out_open_license = FFI::MemoryPointer.new(:int)
-      out_available = FFI::MemoryPointer.new(:int)
-
-      result = Api.proj_grid_get_info_from_database(self.context, name,
-                                                    out_full_name, out_package_name, out_url,
-                                                    out_downloadable, out_open_license, out_available)
-
-      if result == 1
-        full_name_ptr = out_full_name.read_pointer
-        package_name_ptr = out_package_name.read_pointer
-        url_ptr = out_url.read_pointer
-
-        downloadable_ptr = out_downloadable
-        open_license_ptr = out_open_license
-        available_ptr = out_available
-
-        full_name = full_name_ptr.read_string_to_null
-        package_name = package_name_ptr.read_string_to_null
-        url = url_ptr.read_string_to_null
-
-        downloadable = downloadable_ptr.read_int == 1 ? true : false
-        open_license = open_license_ptr.read_int == 1 ? true : false
-        available = available_ptr.read_int == 1 ? true : false
-
-        Grid.new(name, self.context,
-                 full_name: full_name, package_name: package_name,
-                 url: url ? URI(url) : nil,
-                 downloadable: downloadable, open_license: open_license, available: available)
-      else
-        Error.check_context(self.context)
-      end
-    end
-
-    # Returns a list of geoid models available
-    #
-    # @see https://proj.org/development/reference/functions.html#c.proj_get_geoid_models_from_database
-    #
-    # @param authority [String] Authority name into which the object will be inserted. Must not be nil
-    # @param code [Integer] Code with which the object will be inserted.Must not be nil
-    #
-    # @return [Strings] List of insert statements
-    def geoid_models(authority, code)
-      ptr = Api.proj_get_geoid_models_from_database(self.context, authority, code, nil)
-      Strings.new(ptr)
-    end
-
-    # Returns a list of celestial bodies from the database
-    #
-    # @see https://proj.org/development/reference/functions.html#c.proj_get_celestial_body_list_from_database
-    #
-    # @param authority [String] Authority name, used to restrict the search. Set to nil for all authorities.
-    #
-    # @return [Array<CelestialBody>] List of insert statements
-    def celestial_bodies(authority = nil)
-      out_result_count = FFI::MemoryPointer.new(:int)
-      ptr = Api.proj_get_celestial_body_list_from_database(self.context, authority, out_result_count)
-
-      body_ptrs = ptr.read_array_of_pointer(out_result_count.read_int)
-      result = body_ptrs.map do |body_ptr|
-        # First read the pointer to a structure
-        struct = Api::ProjCelestialBodyInfo.new(body_ptr)
-
-        # Now map this to a Ruby Struct
-        CelestialBody.new(struct[:auth_name], struct[:name])
-      end
-
-      Api.proj_celestial_body_list_destroy(ptr)
-
-      result
-    end
-
-    # Return the name of the celestial body of the specified object.
-    #
-    # @see https://proj.org/development/reference/functions.html#c.proj_get_celestial_body_name
-    #
-    # @param object [PjObject] Object of type CRS, Datum or Ellipsoid. Must not be nil.
-    #
-    # @return [String] The name of the celestial body or nil
-    def celestial_body_name(object)
-      Api.proj_get_celestial_body_name(self.context, object)
-    end
-
-    # Suggests a database code for the specified object.
-    #
-    # @see https://proj.org/development/reference/functions.html#c.proj_suggests_code_for
-    #
-    # @param object [PjObject] Object for which to suggest a code.
-    # @param authority [String]  Authority name into which the object will be inserted.
-    # @param numeric_code [Boolean] Whether the code should be numeric, or derived from the object name.
-    #
-    # @return [String] The suggested code
-    def suggest_code_for(object, authority, numeric_code)
-      ptr = Api.proj_suggests_code_for(self.context, object, authority, numeric_code ? 1 : 0, nil)
-      result = ptr.read_string_to_null
-      Api.proj_string_destroy(ptr)
-      result
-    end
-
-    # Returns a list of units from the database
-    #
-    # @see https://proj.org/development/reference/functions.html#c.proj_get_units_from_database
-    #
-    # @param auth_name [String] Authority name, used to restrict the search. Or nil for all authorities.
-    # @param category [String] Filter by category, if this parameter is not nil. Category is one of "linear", "linear_per_time", "angular", "angular_per_time", "scale", "scale_per_time" or "time
-    # @param allow_deprecated [Boolean] Whether deprecated units should also be returned. Default false.
-    #
-    # @return [Array<Unit>] Array of units
-    def units(auth_name: nil, category: nil, allow_deprecated: false)
-      # Create pointer to read the count output parameter
-      out_result_count = FFI::MemoryPointer.new(:int)
-
-      # Result is an array of pointers to structures
-      pp_units = Api.proj_get_units_from_database(Context.current, auth_name, category, allow_deprecated ? 1 : 0, out_result_count)
-      count = out_result_count.read(:int)
-      array_p_units = pp_units.read_array_of_pointer(count)
-
-      result = Array.new(count)
-      count.times do |i|
-        unit_info = Api::PROJ_UNIT_INFO.new(array_p_units[i])
-
-        result[i] = Unit.new(unit_info[:auth_name],
-                             unit_info[:code],
-                             unit_info[:name],
-                             unit_info[:category],
-                             unit_info[:conv_factor],
-                             unit_info[:proj_short_name],
-                             unit_info[:deprecated])
-      end
-
-      Api.proj_unit_list_destroy(pp_units)
-
-      result
-    end
-
-    # Returns information for a unit of measure from a database lookup
-    #
-    # @see https://proj.org/development/reference/functions.html#c.proj_uom_get_info_from_database
-    #
-    # @param auth_name [String] Authority name
-    # @param code [String] Unit of measure code
-    #
-    # @return [Unit] Unit
-    def unit(auth_name, code)
-      out_name = FFI::MemoryPointer.new(:string)
-      out_conv_factor = FFI::MemoryPointer.new(:double)
-      out_category = FFI::MemoryPointer.new(:string)
-
-      result = Api.proj_uom_get_info_from_database(self.context, auth_name, code,
-                                                    out_name, out_conv_factor , out_category)
-
-      if result == 1
-        name_ptr = out_name.read_pointer
-        conv_factor_ptr = out_conv_factor
-        category_ptr = out_category.read_pointer
-
-        name = name_ptr.read_string_to_null
-        conv_factor = conv_factor_ptr.read_double
-        category = category_ptr.read_string_to_null
-
-        Unit.new(auth_name, code, name, category, conv_factor, nil, false)
-      else
-        Error.check_context(self.context)
-      end
-    end
-  end
-end
+require 'uri'
+
+module Proj
+  CelestialBody = Struct.new(:auth_name, :name)
+
+  # This class provides access the Proj SQLite database called proj.db. The database
+  # stores transformation information that must be accessible for the library to work properly.
+  #
+  # @see https://proj.org/resource_files.html#proj-db
+  class Database
+    attr_reader :context
+
+    # Create a new database instance to query the Proj database
+    #
+    # @param context [Context] A proj Context
+    #
+    # @return [Database]
+    def initialize(context)
+      Error.validate_context!(context)
+      @context = context
+    end
+
+    # Returns the path the Proj database
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_context_get_database_path
+    #
+    # return [String]
+    def path
+      if Api.method_defined?(:proj_context_get_database_path)
+        Api.proj_context_get_database_path(self.context)
+      end
+    end
+
+    # Sets the path to the Proj database
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_context_set_database_path
+    #
+    # @param value [String] Path to the proj database
+    #
+    # @return [Database] Returns reference to the current database instance
+    def path=(value)
+      result = Api.proj_context_set_database_path(self.context, value, nil, nil)
+      unless result == 1
+        Error.check_context(self.context)
+      end
+      self
+    end
+
+    # Returns SQL statements to run to initiate a new valid auxiliary empty database.
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_context_get_database_structure
+    #
+    # @return [Array<Strings>] List of sql statements
+    def structure
+      ptr = Api.proj_context_get_database_structure(self.context, nil)
+      Strings.new(ptr)
+    end
+
+    # Return a metadata from the database.
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_context_get_database_metadata
+    #
+    # @param key [String] The name of the metadata item. Must not be nil
+    #                       Available keys:
+    #                         DATABASE.LAYOUT.VERSION.MAJOR
+    #                         DATABASE.LAYOUT.VERSION.MINOR
+    #                         EPSG.VERSION
+    #                         EPSG.DATE
+    #                         ESRI.VERSION
+    #                         ESRI.DATE
+    #                         IGNF.SOURCE
+    #                         IGNF.VERSION
+    #                         IGNF.DATE
+    #                         NKG.SOURCE
+    #                         NKG.VERSION
+    #                         NKG.DATE
+    #                         PROJ.VERSION
+    #                         PROJ_DATA.VERSION
+    #
+    # @return [String] Returned metadata
+    def metadata(key)
+      Api.proj_context_get_database_metadata(self.context, key)
+    end
+
+    # Returns the set of authority codes of the given object type.
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_get_codes_from_database
+    #
+    # @param auth_name [String] Authority name. Must not be nil.
+    # @param pj_type [PjType] Proj Object type.
+    # @param allow_deprecated [Boolean] Specifies if deprecated objects should be returned. Default is false.
+    #
+    # @return [Strings] Returned authority codes
+    def codes(auth_name, pj_type, allow_deprecated = false)
+      ptr = Api.proj_get_codes_from_database(self.context, auth_name, pj_type, allow_deprecated ? 1 : 0)
+      Strings.new(ptr)
+    end
+
+    # Return a list of authorities used in the database
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_get_authorities_from_database
+    #
+    # @return [Array<Strings>] List of authorities
+    def authorities
+      ptr = Api.proj_get_authorities_from_database(self.context)
+      Strings.new(ptr)
+    end
+
+    # Enumerate CRS infos from the database, taking into account various criteria.
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_get_crs_info_list_from_database
+    #
+    # @param auth_name [String] Authority name. Use nil to specify all authorities
+    # @param parameters [Parameters] Parameters to specify search criteria. May be nil
+    #
+    # @return [Array<CrsInfo>] Returned crs infos
+    def crs_info(auth_name = nil, parameters = nil)
+      out_result_count = FFI::MemoryPointer.new(:int)
+      params = parameters.is_a?(Parameters) ? parameters.instance_variable_get(:@params) : parameters
+      ptr = Api.proj_get_crs_info_list_from_database(self.context, auth_name, params, out_result_count)
+
+      result = out_result_count.read_int.times.map do |index|
+        index_ptr = ptr + (index * FFI::Pointer::SIZE)
+        struct = Api::ProjCrsInfo.new(index_ptr.read_pointer)
+        CrsInfo.from_proj_crs_info(struct)
+      end
+
+      Api.proj_crs_info_list_destroy(ptr)
+      result
+    end
+
+    # Returns information about a Grid from the database
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_grid_get_info_from_database
+    #
+    # @param name [String] The name of the grid
+    #
+    # @return [Grid]
+    def grid(name)
+      out_full_name = FFI::MemoryPointer.new(:string)
+      out_package_name = FFI::MemoryPointer.new(:string)
+      out_url = FFI::MemoryPointer.new(:string)
+      out_downloadable = FFI::MemoryPointer.new(:int)
+      out_open_license = FFI::MemoryPointer.new(:int)
+      out_available = FFI::MemoryPointer.new(:int)
+
+      result = Api.proj_grid_get_info_from_database(self.context, name,
+                                                    out_full_name, out_package_name, out_url,
+                                                    out_downloadable, out_open_license, out_available)
+
+      if result == 1
+        full_name_ptr = out_full_name.read_pointer
+        package_name_ptr = out_package_name.read_pointer
+        url_ptr = out_url.read_pointer
+
+        downloadable_ptr = out_downloadable
+        open_license_ptr = out_open_license
+        available_ptr = out_available
+
+        full_name = full_name_ptr.read_string_to_null
+        package_name = package_name_ptr.read_string_to_null
+        url = url_ptr.read_string_to_null
+
+        downloadable = downloadable_ptr.read_int == 1 ? true : false
+        open_license = open_license_ptr.read_int == 1 ? true : false
+        available = available_ptr.read_int == 1 ? true : false
+
+        Grid.new(name, self.context,
+                 full_name: full_name, package_name: package_name,
+                 url: url ? URI(url) : nil,
+                 downloadable: downloadable, open_license: open_license, available: available)
+      else
+        Error.check_context(self.context)
+      end
+    end
+
+    # Returns a list of geoid models available
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_get_geoid_models_from_database
+    #
+    # @param authority [String] Authority name into which the object will be inserted. Must not be nil
+    # @param code [Integer] Code with which the object will be inserted.Must not be nil
+    #
+    # @return [Strings] List of insert statements
+    def geoid_models(authority, code)
+      ptr = Api.proj_get_geoid_models_from_database(self.context, authority, code, nil)
+      Strings.new(ptr)
+    end
+
+    # Returns a list of celestial bodies from the database
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_get_celestial_body_list_from_database
+    #
+    # @param authority [String] Authority name, used to restrict the search. Set to nil for all authorities.
+    #
+    # @return [Array<CelestialBody>] List of insert statements
+    def celestial_bodies(authority = nil)
+      out_result_count = FFI::MemoryPointer.new(:int)
+      ptr = Api.proj_get_celestial_body_list_from_database(self.context, authority, out_result_count)
+
+      body_ptrs = ptr.read_array_of_pointer(out_result_count.read_int)
+      result = body_ptrs.map do |body_ptr|
+        # First read the pointer to a structure
+        struct = Api::ProjCelestialBodyInfo.new(body_ptr)
+
+        # Now map this to a Ruby Struct
+        CelestialBody.new(struct[:auth_name].read_string_to_null, struct[:name].read_string_to_null)
+      end
+
+      Api.proj_celestial_body_list_destroy(ptr)
+
+      result
+    end
+
+    # Return the name of the celestial body of the specified object.
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_get_celestial_body_name
+    #
+    # @param object [PjObject] Object of type CRS, Datum or Ellipsoid. Must not be nil.
+    #
+    # @return [String] The name of the celestial body or nil
+    def celestial_body_name(object)
+      Api.proj_get_celestial_body_name(self.context, object)
+    end
+
+    # Suggests a database code for the specified object.
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_suggests_code_for
+    #
+    # @param object [PjObject] Object for which to suggest a code.
+    # @param authority [String]  Authority name into which the object will be inserted.
+    # @param numeric_code [Boolean] Whether the code should be numeric, or derived from the object name.
+    #
+    # @return [String] The suggested code
+    def suggest_code_for(object, authority, numeric_code)
+      ptr = Api.proj_suggests_code_for(self.context, object, authority, numeric_code ? 1 : 0, nil)
+      return nil if ptr.null?
+      result = ptr.read_string_to_null
+      Api.proj_string_destroy(ptr)
+      result
+    end
+
+    # Returns a list of units from the database
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_get_units_from_database
+    #
+    # @param auth_name [String] Authority name, used to restrict the search. Or nil for all authorities.
+    # @param category [String] Filter by category, if this parameter is not nil. Category is one of "linear", "linear_per_time", "angular", "angular_per_time", "scale", "scale_per_time" or "time
+    # @param allow_deprecated [Boolean] Whether deprecated units should also be returned. Default false.
+    #
+    # @return [Array<Unit>] Array of units
+    def units(auth_name: nil, category: nil, allow_deprecated: false)
+      # Create pointer to read the count output parameter
+      out_result_count = FFI::MemoryPointer.new(:int)
+
+      # Result is an array of pointers to structures
+      pp_units = Api.proj_get_units_from_database(self.context, auth_name, category, allow_deprecated ? 1 : 0, out_result_count)
+      count = out_result_count.read(:int)
+      array_p_units = pp_units.read_array_of_pointer(count)
+
+      result = Array.new(count)
+      count.times do |i|
+        unit_info = Api::ProjUnitInfo.new(array_p_units[i])
+
+        result[i] = Unit.new(unit_info[:auth_name].read_string_to_null,
+                             unit_info[:code].read_string_to_null,
+                             unit_info[:name].read_string_to_null,
+                             unit_info[:category].read_string_to_null,
+                             unit_info[:conv_factor],
+                             unit_info[:proj_short_name].null? ? nil : unit_info[:proj_short_name].read_string_to_null,
+                             unit_info[:deprecated])
+      end
+
+      Api.proj_unit_list_destroy(pp_units)
+
+      result
+    end
+
+    # Returns information for a unit of measure from a database lookup
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_uom_get_info_from_database
+    #
+    # @param auth_name [String] Authority name
+    # @param code [String] Unit of measure code
+    #
+    # @return [Unit] Unit
+    def unit(auth_name, code)
+      out_name = FFI::MemoryPointer.new(:string)
+      out_conv_factor = FFI::MemoryPointer.new(:double)
+      out_category = FFI::MemoryPointer.new(:string)
+
+      result = Api.proj_uom_get_info_from_database(self.context, auth_name, code,
+                                                    out_name, out_conv_factor , out_category)
+
+      if result == 1
+        name_ptr = out_name.read_pointer
+        conv_factor_ptr = out_conv_factor
+        category_ptr = out_category.read_pointer
+
+        name = name_ptr.read_string_to_null
+        conv_factor = conv_factor_ptr.read_double
+        category = category_ptr.read_string_to_null
+
+        Unit.new(auth_name, code, name, category, conv_factor, nil, false)
+      else
+        Error.check_context(self.context)
+      end
+    end
+  end
+end