class Proj::Database

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 proj.org/resource_files.html#proj-db

Attributes

context[R]

Public Class Methods

new(context) click to toggle source

Create a new database instance to query the Proj database

@param context [Context] A proj Context

@return [Database]

# File lib/proj/database.rb, line 16
def initialize(context)
  @context = context
end

Public Instance Methods

authorities() click to toggle source

Return a list of authorities used in the database

@see proj.org/development/reference/functions.html#c.proj_get_authorities_from_database

@return [Array<Strings>] List of authorities

# File lib/proj/database.rb, line 101
def authorities
  ptr = Api.proj_get_authorities_from_database(self.context)
  Strings.new(ptr)
end
celestial_bodies(authority = nil) click to toggle source

Returns a list of celestial bodies from the database

@see 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

# File lib/proj/database.rb, line 193
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
celestial_body_name(object) click to toggle source

Return the name of the celestial body of the specified object.

@see 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

# File lib/proj/database.rb, line 218
def celestial_body_name(object)
  Api.proj_get_celestial_body_name(self.context, object)
end
codes(auth_name, pj_type, allow_deprecated = false) click to toggle source

Returns the set of authority codes of the given object type.

@see 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

# File lib/proj/database.rb, line 91
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
crs_info(auth_name = nil, parameters = nil) click to toggle source

Enumerate CRS infos from the database, taking into account various criteria.

@see 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

# File lib/proj/database.rb, line 114
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
geoid_models(authority, code) click to toggle source

Returns a list of geoid models available

@see 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

# File lib/proj/database.rb, line 181
def geoid_models(authority, code)
  ptr = Api.proj_get_geoid_models_from_database(self.context, authority, code, nil)
  Strings.new(ptr)
end
grid(name) click to toggle source

Returns information about a Grid from the database

@see proj.org/development/reference/functions.html#c.proj_grid_get_info_from_database

@param name [String] The name of the grid

@return [Grid]

# File lib/proj/database.rb, line 135
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
metadata(key) click to toggle source

Return a metadata from the database.

@see 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

# File lib/proj/database.rb, line 78
def metadata(key)
  Api.proj_context_get_database_metadata(self.context, key)
end
path() click to toggle source

Returns the path the Proj database

@see proj.org/development/reference/functions.html#c.proj_context_get_database_path

return [String]

# File lib/proj/database.rb, line 25
def path
  if Api.method_defined?(:proj_context_get_database_path)
    Api.proj_context_get_database_path(self.context)
  end
end
path=(value) click to toggle source

Sets the path to the Proj database

@see 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

# File lib/proj/database.rb, line 38
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
structure() click to toggle source

Returns SQL statements to run to initiate a new valid auxiliary empty database.

@see proj.org/development/reference/functions.html#c.proj_context_get_database_structure

@return [Array<Strings>] List of sql statements

# File lib/proj/database.rb, line 51
def structure
  ptr = Api.proj_context_get_database_structure(self.context, nil)
  Strings.new(ptr)
end
suggest_code_for(object, authority, numeric_code) click to toggle source

Suggests a database code for the specified object.

@see 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

# File lib/proj/database.rb, line 231
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
unit(auth_name, code) click to toggle source

Returns information for a unit of measure from a database lookup

@see 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

# File lib/proj/database.rb, line 282
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
units(auth_name: nil, category: nil, allow_deprecated: false) click to toggle source

Returns a list of units from the database

@see 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

# File lib/proj/database.rb, line 247
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