ffi-gdal 1.0.0.beta16 → 1.0.0

data/lib/ogr/feature.rb

@@ -3,11 +3,15 @@
 require 'date'
 require_relative '../ogr'
 require_relative '../gdal'
-require_relative 'feature_extensions'
 
 module OGR
   class Feature
-    include FeatureExtensions
+    # @param pointer [FFI::Pointer]
+    def self.release(pointer)
+      return unless pointer && !pointer.null?
+
+      FFI::OGR::API.OGR_F_Destroy(pointer)
+    end
 
     # @return [FFI::Pointer] C pointer of the C Feature.
     attr_reader :c_pointer
@@ -16,27 +20,35 @@ module OGR
     #   a FeatureDefinition (i.e. normal Feature creation) or a Pointer (in the
     #   case a handle to a C OGR Feature needs to be wrapped with this object).
     def initialize(fd_or_pointer)
-      @c_pointer = if fd_or_pointer.is_a? OGR::FeatureDefinition
-                     FFI::OGR::API.OGR_F_Create(fd_or_pointer.c_pointer)
-                   else
-                     fd_or_pointer
-                   end
+      pointer = case fd_or_pointer
+                when OGR::FeatureDefinition then FFI::OGR::API.OGR_F_Create(fd_or_pointer.c_pointer)
+                when FFI::Pointer
+                  fd_or_pointer.autorelease = false
+                  fd_or_pointer
+                else
+                  raise OGR::InvalidFeature, 'OGR::Feature must be instantiated with valid feature'
+                end
+
+      if !pointer.is_a?(FFI::Pointer) || pointer.null?
+        raise OGR::InvalidFeature, "Unable to create Feature with #{fd_or_pointer}"
+      end
 
-      return if @c_pointer.is_a?(FFI::Pointer) && !@c_pointer.null?
+      # pointer.autorelease = false
 
-      raise OGR::InvalidFeature, "Unable to create Feature with #{fd_or_pointer}"
+      # @c_pointer = FFI::AutoPointer.new(pointer, Feature.method(:release))
+      @c_pointer = pointer
     end
 
     def destroy!
-      return unless @c_pointer
+      Feature.release(@c_pointer)
 
-      FFI::OGR::API.OGR_F_Destroy(@c_pointer)
       @c_pointer = nil
     end
 
     # @return [OGR::Feature]
     # @raise [OGR::Failure] If, for some reason, the clone fails.
     def clone
+      # This new feature is owned by the caller and must be released accordingly.
       feature_ptr = FFI::OGR::API.OGR_F_Clone(@c_pointer)
       raise OGR::Failure, 'Unable to clone feature' if feature_ptr.nil?
 
@@ -58,43 +70,44 @@ module OGR
     # @param _other_feature [OGR::Feature]
     # @param _be_forgiving [Boolean] +true+ if the operation should continue
     #   despite lacking output fields matching some of the source fields.
-    # @param with_map [Array<Fixnum>]
+    # @param with_map [Array<Integer>]
+    # @raise [OGR::Failure]
     # TODO: Implement +with_map+
-    def set_from!(_other_feature, _be_forgiving = false, with_map: nil)
+    def set_from!(_other_feature, _be_forgiving: false, with_map: nil)
       raise NotImplementedError, 'with_map: is not yet supported' if with_map
 
-      ogr_err = FFI::OGR::API.OGR_F_SetFrom(@c_pointer, other_feature_ptr)
-
-      ogr_err.handle_result
+      OGR::ErrorHandling.handle_ogr_err('Unable to set from other feature') do
+        FFI::OGR::API.OGR_F_SetFrom(@c_pointer, other_feature_ptr)
+      end
     end
 
     # This will always be the same as the field count for the feature
     # definition.
     #
-    # @return [Fixnum]
+    # @return [Integer]
     def field_count
       FFI::OGR::API.OGR_F_GetFieldCount(@c_pointer)
     end
 
-    # @param index [Fixnum]
+    # @param index [Integer]
     # @param value [String]
     def set_field_string(index, value)
       FFI::OGR::API.OGR_F_SetFieldString(@c_pointer, index, value)
     end
 
-    # @param index [Fixnum]
-    # @param value [Fixnum]
+    # @param index [Integer]
+    # @param value [Integer]
     def set_field_integer(index, value)
       FFI::OGR::API.OGR_F_SetFieldInteger(@c_pointer, index, value)
     end
 
-    # @param index [Fixnum]
+    # @param index [Integer]
     # @param value [Float]
     def set_field_double(index, value)
       FFI::OGR::API.OGR_F_SetFieldDouble(@c_pointer, index, value)
     end
 
-    # @param index [Fixnum]
+    # @param index [Integer]
     # @param values [Array<String>]
     # @raise [GDAL::Error] If index isn't valid
     def set_field_string_list(index, values)
@@ -107,8 +120,8 @@ module OGR
       )
     end
 
-    # @param index [Fixnum]
-    # @param values [Array<Fixnum>]
+    # @param index [Integer]
+    # @param values [Array<Integer>]
     def set_field_integer_list(index, values)
       values_ptr = FFI::MemoryPointer.new(:int, values.size)
       values_ptr.write_array_of_int(values)
@@ -121,7 +134,7 @@ module OGR
       )
     end
 
-    # @param index [Fixnum]
+    # @param index [Integer]
     # @param values [Array<Float>]
     def set_field_double_list(index, values)
       values_ptr = FFI::MemoryPointer.new(:double, values.size)
@@ -135,7 +148,7 @@ module OGR
       )
     end
 
-    # @param index [Fixnum]
+    # @param index [Integer]
     # @param field [OGR::Field]
     def set_field_raw(index, field)
       usable_raw_field = field.c_struct
@@ -143,7 +156,7 @@ module OGR
       FFI::OGR::API.OGR_F_SetFieldRaw(@c_pointer, index, usable_raw_field)
     end
 
-    # @param index [Fixnum]
+    # @param index [Integer]
     # @param value [String]
     def set_field_binary(index, value)
       raise TypeError, 'value must be a binary string' unless value.is_a? String
@@ -159,46 +172,51 @@ module OGR
       )
     end
 
-    # @param index [Fixnum]
+    # @param index [Integer]
     # @param value [Date, Time, DateTime]
     def set_field_date_time(index, value)
       time = value.to_time
       zone = OGR._format_time_zone_for_ogr(value.zone)
 
       FFI::OGR::API.OGR_F_SetFieldDateTime(@c_pointer, index,
-        time.year,
-        time.month,
-        time.day,
-        time.hour,
-        time.min,
-        time.sec,
-        zone)
+                                           time.year,
+                                           time.month,
+                                           time.day,
+                                           time.hour,
+                                           time.min,
+                                           time.sec,
+                                           zone)
     end
 
-    # @param index [Fixnum]
+    # NOTE: Do not modify the FieldDefinition that's returned here.
+    #
+    # @param index [Integer]
     # @return [OGR::FieldDefinition]
     def field_definition(index)
+      # This returns an internal reference and should not be deleted or modified
       field_pointer = FFI::OGR::API.OGR_F_GetFieldDefnRef(@c_pointer, index)
+      field_pointer.autorelease = false
+
       return nil if field_pointer.null?
 
       OGR::FieldDefinition.new(field_pointer, nil)
     end
 
     # @param name [String]
-    # @return [Fixnum, nil]
+    # @return [Integer, nil]
     def field_index(name)
       result = FFI::OGR::API.OGR_F_GetFieldIndex(@c_pointer, name)
 
-      result < 0 ? nil : result
+      result.negative? ? nil : result
     end
 
-    # @param index [Fixnum]
+    # @param index [Integer]
     # @return [Boolean]
     def field_set?(index)
       FFI::OGR::API.OGR_F_IsFieldSet(@c_pointer, index)
     end
 
-    # @param index [Fixnum]
+    # @param index [Integer]
     def unset_field(index)
       FFI::OGR::API.OGR_F_UnsetField(@c_pointer, index)
     end
@@ -206,62 +224,91 @@ module OGR
     # @return [OGR::FeatureDefinition,nil]
     def definition
       feature_defn_ptr = FFI::OGR::API.OGR_F_GetDefnRef(@c_pointer)
+      feature_defn_ptr.autorelease = false
+
       return nil if feature_defn_ptr.null?
 
       OGR::FeatureDefinition.new(feature_defn_ptr)
     end
 
+    # NOTE: Do not modify the Geometry that's returned here.
+    #
     # @return [OGR::Geometry]
     def geometry
+      # This returns an internal reference and should not be deleted or modified
       geometry_ptr = FFI::OGR::API.OGR_F_GetGeometryRef(@c_pointer)
+      geometry_ptr.autorelease = false
+
       return nil if geometry_ptr.null?
 
       OGR::Geometry.factory(geometry_ptr)
     end
 
+    # Sets the geometry of the feature by making a copy of +new_geometry+.
+    #
+    # @param new_geometry [OGR::Geometry]
+    # @raise [OGR::Failure]
+    def set_geometry(new_geometry) # rubocop:disable Naming/AccessorMethodName
+      OGR::ErrorHandling.handle_ogr_err('Unable to set geometry on feature') do
+        FFI::OGR::API.OGR_F_SetGeometry(@c_pointer, new_geometry.c_pointer)
+      end
+    end
+
+    # Sets the geometry of the feature by taking ownership of +new_geometry.
+    #
     # @param new_geometry [OGR::Geometry]
-    # @return +true+ if successful, otherwise raises an OGR exception.
-    def geometry=(new_geometry)
-      ogr_err = FFI::OGR::API.OGR_F_SetGeometryDirectly(@c_pointer, new_geometry.c_pointer)
+    # @raise [OGR::Failure]
+    def set_geometry_directly(new_geometry) # rubocop:disable Naming/AccessorMethodName
+      new_geometry.c_pointer.autorelease = false
 
-      ogr_err.handle_result
+      OGR::ErrorHandling.handle_ogr_err('Unable to set geometry directly on feature') do
+        FFI::OGR::API.OGR_F_SetGeometryDirectly(@c_pointer, new_geometry.c_pointer)
+      end
     end
+    alias geometry= set_geometry_directly
 
+    # Takes away ownership of the Feature's Geometry and returns it to the caller.
+    #
     # @return [OGR::Geometry]
     def steal_geometry
       geometry_ptr = FFI::OGR::API.OGR_F_StealGeometry(@c_pointer)
-      raise OGR::Failure, 'Unable to steal geometry.' if geometry_ptr.nil?
+      raise OGR::Failure, 'Unable to steal geometry.' if geometry_ptr.nil? || geometry_ptr.null?
 
       OGR::Geometry.factory(geometry_ptr)
     end
 
-    # @return [Fixnum]
+    # @return [Integer]
     def fid
       FFI::OGR::API.OGR_F_GetFID(@c_pointer)
     end
 
-    # @param new_fid [Fixnum]
-    # @return +true+ if successful, otherwise raises an OGR exception.
+    # @param new_fid [Integer]
+    # @raise [OGR::Failure]
     def fid=(new_fid)
-      ogr_err = FFI::OGR::API.OGR_F_SetFID(@c_pointer, new_fid)
-
-      ogr_err.handle_result
+      OGR::ErrorHandling.handle_ogr_err('Unable to set FID') do
+        FFI::OGR::API.OGR_F_SetFID(@c_pointer, new_fid)
+      end
     end
 
     # The number of Geometries in this feature.
     #
-    # @return [Fixnum]
+    # @return [Integer]
     def geometry_field_count
       FFI::OGR::API.OGR_F_GetGeomFieldCount(@c_pointer)
     end
 
-    # @param index [Fixnum]
+    # NOTE: Do not modify the GeometryFieldDefinition that's returned here.
+    #
+    # @param index [Integer]
     # @return [OGR::GeometryFieldDefinition] A read-only
     #   OGR::GeometryFieldDefinition.
     # @raise [OGR::InvalidGeometryFieldDefinition] If there isn't one at
     #   +index+.
     def geometry_field_definition(index)
+      # This returns an internal reference and should not be deleted or modified
       gfd_ptr = FFI::OGR::API.OGR_F_GetGeomFieldDefnRef(@c_pointer, index)
+      gfd_ptr.autorelease = false
+
       return nil if gfd_ptr.nil?
 
       gfd = OGR::GeometryFieldDefinition.new(gfd_ptr)
@@ -271,29 +318,54 @@ module OGR
     end
 
     # @param name [String]
-    # @return [Fixnum]
+    # @return [Integer]
     def geometry_field_index(name)
       FFI::OGR::API.OGR_F_GetGeomFieldIndex(@c_pointer, name)
     end
 
-    # @param index [Fixnum]
+    # NOTE: Do not modify the Geometry that's returned here.
+    #
+    # @param index [Integer]
     # @return [OGR::Geometry, nil] A read-only OGR::Geometry.
     def geometry_field(index)
+      # This returns an internal reference and should not be deleted or modified
       geometry_ptr = FFI::OGR::API.OGR_F_GetGeomFieldRef(@c_pointer, index)
+      geometry_ptr.autorelease = false
+
       return nil if geometry_ptr.nil? || geometry_ptr.null?
 
       OGR::Geometry.factory(geometry_ptr)
     end
 
-    # @param index [Fixnum]
+    # Sets the feature geometry of a specified geometry field by making a copy
+    # of +geometry+.
+    #
+    # @param index [Integer]
     # @param geometry [OGR::Geometry]
+    # @raise [OGR::Failure]
     def set_geometry_field(index, geometry)
       geometry_ptr = GDAL._pointer(OGR::Geometry, geometry)
       raise OGR::InvalidGeometry if geometry_ptr.nil?
 
-      ogr_err = FFI::OGR::API.OGR_F_SetGeomField(@c_pointer, index, geometry_ptr)
+      OGR::ErrorHandling.handle_ogr_err("Unable to set geometry field at index #{index}") do
+        FFI::OGR::API.OGR_F_SetGeomField(@c_pointer, index, geometry_ptr)
+      end
+    end
 
-      ogr_err.handle_result
+    # Sets the feature geometry of a specified geometry field by taking ownership
+    # of +geometry+.
+    #
+    # @param index [Integer]
+    # @param geometry [OGR::Geometry]
+    # @raise [OGR::Failure]
+    def set_geometry_field_directly(index, geometry)
+      geometry_ptr = GDAL._pointer(OGR::Geometry, geometry, autorelease: false)
+
+      raise OGR::InvalidGeometry if geometry_ptr.nil?
+
+      OGR::ErrorHandling.handle_ogr_err("Unable to set geometry field directly at index #{index}") do
+        FFI::OGR::API.OGR_F_SetGeomFieldDirectly(@c_pointer, index, geometry_ptr)
+      end
     end
 
     # @return [Boolean]
@@ -302,68 +374,76 @@ module OGR
     end
     alias equals? equal?
 
-    # @param index [Fixnum]
-    # @return [Fixnum]
+    # @param index [Integer]
+    # @return [Integer]
     def field_as_integer(index)
       FFI::OGR::API.OGR_F_GetFieldAsInteger(@c_pointer, index)
     end
 
-    # @param index [Fixnum]
-    # @return [Array<Fixnum>]
+    # @param index [Integer]
+    # @return [Array<Integer>]
     def field_as_integer_list(index)
       list_size_ptr = FFI::MemoryPointer.new(:int)
-      list_ptr =
-        FFI::OGR::API.OGR_F_GetFieldAsIntegerList(@c_pointer, index, list_size_ptr)
+      #  This list is internal, and should not be modified, or freed. Its lifetime may be very brief.
+      list_ptr = FFI::OGR::API.OGR_F_GetFieldAsIntegerList(@c_pointer, index, list_size_ptr)
+      list_ptr.autorelease = false
+
       return [] if list_ptr.null?
 
       list_ptr.read_array_of_int(list_size_ptr.read_int)
     end
 
-    # @param index [Fixnum]
+    # @param index [Integer]
     # @return [Float]
     def field_as_double(index)
       FFI::OGR::API.OGR_F_GetFieldAsDouble(@c_pointer, index)
     end
 
-    # @param index [Fixnum]
+    # @param index [Integer]
     # @return [Array<Float>]
     def field_as_double_list(index)
       list_size_ptr = FFI::MemoryPointer.new(:int)
-      list_ptr =
-        FFI::OGR::API.OGR_F_GetFieldAsDoubleList(@c_pointer, index, list_size_ptr)
+      # This list is internal, and should not be modified, or freed. Its lifetime may be very brief.
+      list_ptr = FFI::OGR::API.OGR_F_GetFieldAsDoubleList(@c_pointer, index, list_size_ptr)
+      list_ptr.autorelease = false
+
       return [] if list_ptr.null?
 
       list_ptr.read_array_of_double(list_size_ptr.read_int)
     end
 
-    # @param index [Fixnum]
+    # @param index [Integer]
     # @return [String]
     def field_as_string(index)
-      FFI::OGR::API.OGR_F_GetFieldAsString(@c_pointer, index).force_encoding(Encoding::UTF_8)
+      field, ptr = FFI::OGR::API.OGR_F_GetFieldAsString(@c_pointer, index)
+      ptr.autorelease = false
+
+      field.force_encoding(Encoding::UTF_8)
     end
 
-    # @param index [Fixnum]
+    # @param index [Integer]
     # @return [Array<String>]
     def field_as_string_list(index)
-      list_ptr =
-        FFI::OGR::API.OGR_F_GetFieldAsStringList(@c_pointer, index)
+      # This list is internal, and should not be modified, or freed. Its lifetime may be very brief.
+      list_ptr = FFI::OGR::API.OGR_F_GetFieldAsStringList(@c_pointer, index)
+      list_ptr.autorelease = false
+
       return [] if list_ptr.null?
 
       list_ptr.get_array_of_string(0)
     end
 
-    # @param index [Fixnum]
+    # @param index [Integer]
     # @return [String]
     def field_as_binary(index)
       byte_count_ptr = FFI::MemoryPointer.new(:int)
-      binary_data = FFI::OGR::API.OGR_F_GetFieldAsBinary(
-        @c_pointer,
-        index,
-        byte_count_ptr
-      )
+
+      # This list is internal, and should not be modified, or freed. Its lifetime may be very brief.
+      binary_data_ptr = FFI::OGR::API.OGR_F_GetFieldAsBinary(@c_pointer, index, byte_count_ptr)
+      binary_data_ptr.autorelease = false
 
       byte_count = byte_count_ptr.read_int
-      string = byte_count > 0 ? binary_data.read_bytes(byte_count) : ''
+      string = byte_count.positive? ? binary_data_ptr.read_bytes(byte_count) : ''
 
       string.unpack('C*')
     end
@@ -377,7 +457,7 @@ module OGR
       second_ptr = FFI::MemoryPointer.new(:int)
       time_zone_flag_ptr = FFI::MemoryPointer.new(:int)
 
-      result = FFI::OGR::API.OGR_F_GetFieldAsDateTime(
+      success = FFI::OGR::API.OGR_F_GetFieldAsDateTime(
         @c_pointer,
         index,
         year_ptr,
@@ -388,11 +468,10 @@ module OGR
         second_ptr,
         time_zone_flag_ptr
       )
-      return nil unless result
+      return nil unless success
 
       formatted_tz = OGR._format_time_zone_for_ruby(time_zone_flag_ptr.read_int)
 
-      # rubocop:disable Style/DateTime
       if formatted_tz
         DateTime.new(
           year_ptr.read_int,
@@ -413,12 +492,14 @@ module OGR
           second_ptr.read_int
         )
       end
-      # rubocop:enable Style/DateTime
     end
 
     # @return [String]
     def style_string
-      FFI::OGR::API.OGR_F_GetStyleString(@c_pointer)
+      style, ptr = FFI::OGR::API.OGR_F_GetStyleString(@c_pointer)
+      ptr.autorelease = false
+
+      style
     end
 
     # @param new_style [String]
@@ -429,6 +510,8 @@ module OGR
     # @return [OGR::StyleTable]
     def style_table
       style_table_ptr = FFI::OGR::API.OGR_F_GetStyleTable(@c_pointer)
+      style_table_ptr.autorelease = false
+
       return nil if style_table_ptr.nil? || style_table_ptr.null?
 
       OGR::StyleTable.new(style_table_ptr)
@@ -436,7 +519,8 @@ module OGR
 
     # @param new_style_table [OGR::StyleTable]
     def style_table=(new_style_table)
-      new_style_table_ptr = GDAL._pointer(OGR::StyleTable, new_style_table)
+      new_style_table_ptr = GDAL._pointer(OGR::StyleTable, new_style_table, autorelease: false)
+
       raise OGR::InvalidStyleTable unless new_style_table_ptr
 
       FFI::OGR::API.OGR_F_SetStyleTableDirectly(@c_pointer, new_style_table_ptr)
@@ -445,9 +529,10 @@ module OGR
     private
 
     def c_pointer_from(feature)
-      if feature.is_a? OGR::Feature
+      case feature
+      when OGR::Feature
         feature.c_pointer
-      elsif feature.is_a? FFI::Pointer
+      when FFI::Pointer
         feature
       end
     end