ffi-gdal 1.0.0.beta3 → 1.0.0.beta4

data/lib/ogr/layer_mixins/ogr_field_methods.rb

@@ -0,0 +1,143 @@
+require_relative '../field_definition'
+require_relative '../field'
+require_relative '../geometry_field_definition'
+
+module OGR
+  module LayerMixins
+    module OGRFieldMethods
+      # Creates and writes a new field to the layer. This adds the field to the
+      # internal FeatureDefinition; C API says not to update the FeatureDefinition
+      # directly.
+      #
+      # @param field_definition [OGR::FieldDefinition]
+      # @param approx_ok [Boolean] If +true+ the field may be created in a slightly
+      #   different form, depending on the limitations of the format driver.
+      # @return [Boolean]
+      def create_field(field_definition, approx_ok = false)
+        unless can_create_field?
+          fail OGR::UnsupportedOperation, 'This layer does not support field creation.'
+        end
+
+        field_definition_ptr = GDAL._pointer(OGR::FieldDefinition, field_definition)
+        ogr_err = FFI::OGR::API.OGR_L_CreateField(@c_pointer, field_definition_ptr, approx_ok)
+
+        ogr_err.handle_result
+      end
+
+      # Deletes the field definition from the layer.
+      #
+      # @return +true+ if successful, otherwise raises an OGR exception.
+      def delete_field(field_id)
+        unless can_delete_field?
+          fail OGR::UnsupportedOperation, 'This driver does not support field deletion.'
+        end
+
+        ogr_err = FFI::OGR::API.OGR_L_DeleteField(@c_pointer, field_id)
+
+        ogr_err.handle_result
+      end
+
+      # @param new_order [Array<Fixnum>] An array that orders field indexes by
+      #   which they should be reordered.  I.e. [0, 2, 3, 1, 4].
+      # @return [Boolean]
+      def reorder_fields(*new_order)
+        unless can_reorder_fields?
+          fail OGR::UnsupportedOperation, 'This driver does not support field reordering.'
+        end
+
+        return false if new_order.empty?
+        return false if new_order.any? { |i| i > feature_definition.field_count }
+
+        map_array_ptr = FFI::MemoryPointer.new(:int, new_order.size).write_array_of_int(new_order)
+        ogr_err = FFI::OGR::API.OGR_L_ReorderFields(@c_pointer, map_array_ptr)
+
+        ogr_err.handle_result
+      end
+
+      # Puts the field whose index is +old_position+ into index at +new_position+
+      # and shuffles the other indexes accordingly.
+      #
+      # @param old_position [Fixnum]
+      # @param new_position [Fixnum]
+      def reorder_field(old_position, new_position)
+        unless can_reorder_fields?
+          fail OGR::UnsupportedOperation, 'This driver does not support field reordering.'
+        end
+
+        ogr_err = FFI::OGR::API.OGR_L_ReorderField(@c_pointer, old_position, new_position)
+
+        ogr_err.handle_result
+      end
+
+      # @param field_index [Fixnum]
+      # @param new_field_definition [OGR::FieldDefinition] The definition for
+      #   which to base the Field at +field_index+ off of.
+      # @param flags [Fixnum] ALTER_NAME_FLAG, ALTER_TYPE_FLAG,
+      #   ALTER_WIDTH_PRECISION_FLAG, or ALTER_ALL_FLAG.
+      def alter_field_definition(field_index, new_field_definition, flags)
+        unless can_alter_field_definition?
+          fail OGR::UnsupportedOperation, 'This layer does not support field definition altering.'
+        end
+
+        new_field_definition_ptr = GDAL._pointer(OGR::FieldDefinition, new_field_definition)
+
+        ogr_err = FFI::OGR::API.OGR_L_AlterFieldDefn(
+          @c_pointer,
+          field_index,
+          new_field_definition_ptr,
+          flags)
+
+        ogr_err.handle_result
+      end
+
+      # Finds the index of a field in this Layer.
+      #
+      # @param field_name [String]
+      # @param exact_match [Boolean] If +false+ and the field doesn't exist in the
+      #   given form, the driver will try to make changes to make a match.
+      # @return [Fixnum] Index of the field or +nil+ if the field doesn't exist.
+      def find_field_index(field_name, exact_match = true)
+        result = FFI::OGR::API.OGR_L_FindFieldIndex(@c_pointer, field_name, exact_match)
+
+        result < 0 ? nil : result
+      end
+
+      # Creates and writes a new geometry to the layer. Note: not all drivers
+      # support this.
+      #
+      # @param geometry_field_def [OGR::GeometryFieldDefinition] The definition
+      #   to use for creating the new field.
+      # @param approx_ok [Boolean]
+      # @return [Boolean]
+      def create_geometry_field(geometry_field_def, approx_ok = false)
+        unless can_create_geometry_field?
+          fail OGR::UnsupportedOperation, 'This layer does not support geometry field creation'
+        end
+
+        geometry_field_definition_ptr = GDAL._pointer(OGR::GeometryFieldDefinition, geometry_field_def)
+
+        ogr_err = FFI::OGR::API.OGR_L_CreateGeomField(
+          @c_pointer,
+          geometry_field_definition_ptr,
+          approx_ok)
+
+        ogr_err.handle_result
+      end
+
+      # If the driver supports this functionality, it will not fetch the
+      # specified fields in subsequent calls to #feature / #next_feature and
+      # thus save some processing time and/or bandwidth.
+      #
+      # @param field_names [Array<String>]
+      # @return [Boolean]
+      def set_ignored_fields(*field_names)
+        return false if field_names.empty?
+
+        fields_ptr = GDAL._string_array_to_pointer(field_names)
+        ogr_err = FFI::OGR::API.OGR_L_SetIgnoredFields(@c_pointer, fields_ptr)
+
+        ogr_err.handle_result "Unable to ignore fields with names: #{field_names}"
+      end
+    end
+  end
+end

data/lib/ogr/layer_mixins/ogr_layer_method_methods.rb

@@ -0,0 +1,163 @@
+module OGR
+  module LayerMixins
+    # OGR::Layer methods: Ruby methods that operate on a OGR::Layer using a
+    # "method layer". The method layer is combined with the current layer in some
+    # fashion, which results in a new OGR::Layer.
+    module OGRLayerMethodMethods
+      # Clip off areas of this layer that are not covered by the method layer. The
+      # result layer contains features whose geometries represent areas that are
+      # in the input layer and in the method layer. The features in the result
+      # layer have the (possibly clipped) areas of features in the input layer and
+      # the attributes from the same features.
+      #
+      # @param method_layer [OGR::Layer]
+      # @param options [Hash]
+      # @option options [:yes, :no] skip_failures (:no) Setting to :yes lets
+      #   the function continue even when a feature could not be inserted.
+      # @option options [:yes, :no] promote_to_multi (:no) Setting to :yes
+      #   converts Polygons to MultiPolygons, LineStrings to MultiLineStrings.
+      # @option options [String] input_prefix Set a prefix for the field names
+      #   that will be created from the fields of the input Layer.
+      # @option options [String] method_prefix Set a prefix for the field names
+      #   that will be created from the fields of the method Layer.
+      def clip(method_layer, **options, &progress)
+        run_layer_method(:OGR_L_Clip, method_layer, **options, &progress)
+      end
+
+      # Remove areas in this layer that are covered by the method layer.
+      #
+      # The result layer contains features whose geometries represent areas that
+      # are in this layer but not in the method layer. The features in the result
+      # layer have attributes from this layer.
+      #
+      # @param method_layer [OGR::Layer]
+      # @param options [Hash]
+      # @option options [:yes, :no] skip_failures (:no) Setting to :yes lets
+      #   the function continue even when a feature could not be inserted.
+      # @option options [:yes, :no] promote_to_multi (:no) Setting to :yes
+      #   converts Polygons to MultiPolygons, LineStrings to MultiLineStrings.
+      # @option options [String] input_prefix Set a prefix for the field names
+      #   that will be created from the fields of the input Layer.
+      # @option options [String] method_prefix Set a prefix for the field names
+      #   that will be created from the fields of the method Layer.
+      def erase(method_layer, **options, &progress)
+        run_layer_method(:OGR_L_Erase, method_layer, **options, &progress)
+      end
+
+      # The result layer contains features whose geometries represent areas that
+      # are in the input layer.  The features in the result layer have attributes
+      # from both input and method layers.
+      #
+      # @param method_layer [OGR::Layer]
+      # @param options [Hash]
+      # @option options [:yes, :no] skip_failures (:no) Setting to :yes lets
+      #   the function continue even when a feature could not be inserted.
+      # @option options [:yes, :no] promote_to_multi (:no) Setting to :yes
+      #   converts Polygons to MultiPolygons, LineStrings to MultiLineStrings.
+      # @option options [String] input_prefix Set a prefix for the field names
+      #   that will be created from the fields of the input Layer.
+      # @option options [String] method_prefix Set a prefix for the field names
+      #   that will be created from the fields of the method Layer.
+      def identity(method_layer, **options, &progress)
+        run_layer_method(:OGR_L_Identity, method_layer, **options, &progress)
+      end
+
+      # Intersection of this layer and +method_layer+.
+      #
+      # @param method_layer [OGR::Layer]
+      # @param options [Hash]
+      # @option options [:yes, :no] skip_failures (:no) Setting to :yes lets
+      #   the function continue even when a feature could not be inserted.
+      # @option options [:yes, :no] promote_to_multi (:no) Setting to :yes
+      #   converts Polygons to MultiPolygons, LineStrings to MultiLineStrings.
+      # @option options [String] input_prefix Set a prefix for the field names
+      #   that will be created from the fields of the input Layer.
+      # @option options [String] method_prefix Set a prefix for the field names
+      #   that will be created from the fields of the method Layer.
+      def intersection(method_layer, **options, &progress)
+        run_layer_method(:OGR_L_Intersection, method_layer, **options, &progress)
+      end
+
+      # The result layer contains features whose geometries represent areas that
+      # are either in this layer or the method layer, but not in both. The
+      # features in the result layer have attributes from both this layer and
+      # the method layer.  For features which represent areas that are only in
+      # this layer or the method layer, the respective attributes have undefined
+      # values.
+      #
+      # @param method_layer [OGR::Layer]
+      # @param options [Hash]
+      # @option options [:yes, :no] skip_failures (:no) Setting to :yes lets
+      #   the function continue even when a feature could not be inserted.
+      # @option options [:yes, :no] promote_to_multi (:no) Setting to :yes
+      #   converts Polygons to MultiPolygons, LineStrings to MultiLineStrings.
+      # @option options [String] input_prefix Set a prefix for the field names
+      #   that will be created from the fields of the input Layer.
+      # @option options [String] method_prefix Set a prefix for the field names
+      #   that will be created from the fields of the method Layer.
+      def symmetrical_difference(method_layer, **options, &progress)
+        run_layer_method(:OGR_L_SymDifference, method_layer, **options, &progress)
+      end
+
+      # The result layer contains features whose geometries represent areas that
+      # are either in this layer or the method layer. The features in the result
+      # layer have attributes from both this layer and the method layer. For
+      # features which represent areas that are only in this or in the method
+      # layer, the respective attributes have undefined values.
+      #
+      # @param method_layer [OGR::Layer]
+      # @param options [Hash]
+      # @option options [:yes, :no] skip_failures (:no) Setting to :yes lets
+      #   the function continue even when a feature could not be inserted.
+      # @option options [:yes, :no] promote_to_multi (:no) Setting to :yes
+      #   converts Polygons to MultiPolygons, LineStrings to MultiLineStrings.
+      # @option options [String] input_prefix Set a prefix for the field names
+      #   that will be created from the fields of the input Layer.
+      # @option options [String] method_prefix Set a prefix for the field names
+      #   that will be created from the fields of the method Layer.
+      def union(method_layer, **options, &progress)
+        run_layer_method(:OGR_L_Union, method_layer, **options, &progress)
+      end
+
+      # Update this layer with features from the update layer. The result layer
+      # contains features whose geometries represent areas that are either in this
+      # layer or the method layer. The features in the result layer have areas
+      # of the features of the method layer or those areas of the features of this
+      # layer that are not covered by the method layer. The features of the result
+      # layer get their attributes from this layer.
+      #
+      # @param method_layer [OGR::Layer]
+      # @param options [Hash]
+      # @option options [:yes, :no] skip_failures (:no) Setting to :yes lets
+      #   the function continue even when a feature could not be inserted.
+      # @option options [:yes, :no] promote_to_multi (:no) Setting to :yes
+      #   converts Polygons to MultiPolygons, LineStrings to MultiLineStrings.
+      # @option options [String] input_prefix Set a prefix for the field names
+      #   that will be created from the fields of the input Layer.
+      # @option options [String] method_prefix Set a prefix for the field names
+      #   that will be created from the fields of the method Layer.
+      def update(method_layer, **options, &progress)
+        run_layer_method(:OGR_L_Update, method_layer, **options, &progress)
+      end
+
+      private
+
+      def run_layer_method(method_name, method_layer, **options, &progress)
+        method_layer_ptr = GDAL._pointer(OGR::Layer, method_layer)
+        options_ptr = GDAL::Options.pointer(options)
+        result_layer_ptr = FFI::MemoryPointer.new(:OGRLayerH)
+
+        ogr_err = FFI::GDAL.send(method_name,
+          @c_pointer,
+          method_layer_ptr,
+          result_layer_ptr,
+          options_ptr,
+          progress,
+          nil)
+        ogr_err.handle_result
+
+        OGR::Layer.new(result_layer_ptr)
+      end
+    end
+  end
+end

data/lib/ogr/layer_mixins/ogr_query_filter_methods.rb

@@ -0,0 +1,89 @@
+require_relative '../geometry'
+
+module OGR
+  module LayerMixins
+    module OGRQueryFilterMethods
+      # TODO: per the GDAL docs: "The returned pointer is to an internally owned
+      # object, and should not be altered or deleted by the caller."
+      #
+      # @return [OGR::Geometry]
+      def spatial_filter
+        filter_pointer = FFI::OGR::API.OGR_L_GetSpatialFilter(@c_pointer)
+        return nil if filter_pointer.null?
+
+        OGR::Geometry.factory(filter_pointer)
+      end
+
+      # @param new_spatial_filter [OGR::Geometry, FFI::Pointer]
+      def spatial_filter=(new_spatial_filter)
+        spatial_filter_ptr = GDAL._pointer(OGR::Geometry, new_spatial_filter)
+
+        FFI::OGR::API.OGR_L_SetSpatialFilter(@c_pointer, spatial_filter_ptr)
+      end
+
+      # Only feature which intersect the filter geometry will be returned.
+      #
+      # @param geometry_field_index [Fixnum] The spatial filter operates on this
+      #   geometry field.
+      # @param geometry [OGR::Geometry] Use this geometry as the filtering
+      #   region.
+      def set_spatial_filter_ex(geometry_field_index, geometry)
+        geometry_ptr = GDAL._pointer(OGR::Geometry, geometry)
+
+        FFI::OGR::API.OGR_L_SetSpatialFilterEx(
+          @c_pointer, geometry_field_index, geometry_ptr)
+      end
+
+      # Only features that geometrically intersect the given rectangle will be
+      # returned.  X/Y values should be in the same coordinate system as the
+      # layer as a whole (different from #set_spatial_filter_rectangle_ex).  To
+      # clear the filter, set #spatial_filter = nil.
+      #
+      # @param min_x [Float]
+      # @param min_y [Float]
+      # @param max_x [Float]
+      # @param max_y [Float]
+      def set_spatial_filter_rectangle(min_x, min_y, max_x, max_y)
+        FFI::OGR::API.OGR_L_SetSpatialFilterRect(
+          @c_pointer,
+          min_x,
+          min_y,
+          max_x,
+          max_y)
+      end
+
+      # Only features that geometrically intersect the given rectangle will be
+      # returned.  X/Y values should be in the same coordinate system as the
+      # layer as the given  GeometryFieldDefinition at the given index (different
+      # from #set_spatial_filter_rectangle).  To clear the filter, set
+      # #spatial_filter = nil.
+      #
+      # @param geometry_field_index [Fixnum]
+      # @param min_x [Float]
+      # @param min_y [Float]
+      # @param max_x [Float]
+      # @param max_y [Float]
+      def set_spatial_filter_rectangle_ex(geometry_field_index, min_x, min_y, max_x, max_y)
+        FFI::OGR::API.OGR_L_SetSpatialFilterRectEx(
+          @c_pointer,
+          geometry_field_index,
+          min_x,
+          min_y,
+          max_x,
+          max_y)
+      end
+
+      # Sets the attribute query string to be used when fetching Features using
+      # #next_feature.  Should be in the form of an `SQL WHERE` clause.  Note
+      # that this will generally result in resetting the current reading position.
+      #
+      # @param query [String]
+      # @see http://ogdi.sourceforge.net/prop/6.2.CapabilitiesMetadata.html
+      def set_attribute_filter(query)
+        ogr_err = FFI::OGR::API.OGR_L_SetAttributeFilter(@c_pointer, query)
+
+        ogr_err.handle_result
+      end
+    end
+  end
+end

data/lib/ogr/layer_mixins/ogr_sql_methods.rb

@@ -0,0 +1,48 @@
+module OGR
+  module LayerMixins
+    module OGRSQLMethods
+      # @return [Boolean]
+      def start_transaction
+        transact { FFI::OGR::API.OGR_L_StartTransaction(@c_pointer) }
+      end
+
+      # @return [Boolean]
+      def commit_transaction
+        transact { FFI::OGR::API.OGR_L_CommitTransaction(@c_pointer) }
+      end
+
+      # @return [Boolean]
+      def rollback_transaction
+        transact { FFI::OGR::API.OGR_L_RollbackTransaction(@c_pointer) }
+      end
+
+      # The name of the underlying database column or "" if not supported.
+      #
+      # @return [String]
+      def fid_column
+        FFI::OGR::API.OGR_L_GetFIDColumn(@c_pointer)
+      end
+
+      # The name of the underlying database column being used as the geometry
+      # column.  Returns "" if not supported.
+      #
+      # @return [String]
+      def geometry_column
+        FFI::OGR::API.OGR_L_GetGeometryColumn(@c_pointer)
+      end
+
+      private
+
+      # @return [Boolean]
+      def transact
+        unless supports_transactions?
+          fail OGR::UnsupportedOperation, 'This layer does not support transactions.'
+        end
+
+        ogr_err = yield
+
+        ogr_err.handle_result
+      end
+    end
+  end
+end