dse-driver 1.0.1

data/lib/dse/geometry/line_string.rb

@@ -0,0 +1,181 @@
+# encoding: utf-8
+
+#--
+#      Copyright (C) 2016 DataStax Inc.
+#
+#      This software can be used solely with DataStax Enterprise. Please consult the license at
+#      http://www.datastax.com/terms/datastax-dse-driver-license-terms
+#++
+
+module Dse
+  module Geometry
+    # Encapsulates a set of lines, characterized by a sequence of {Point}s in the xy-plane. It corresponds to the
+    # `org.apache.cassandra.db.marshal.LineStringType` column type in DSE.
+    #
+    # @see https://en.wikipedia.org/wiki/Well-known_text Wikipedia article on Well Known Text
+    class LineString
+      include Cassandra::CustomData
+
+      # @return [Array<Point>] collection of points that make up this line-string.
+      attr_reader :points
+
+      # @private
+      WKT_RE = /^LINESTRING\s*\(\s*([^)]+)\s*\)$/
+      # @private
+      POINT_SEPARATOR_RE = /\s*,\s*/
+
+      # @param args [Array<Point>,Array<String>] varargs-style arguments in two forms:
+      #   <ul><li>ordered collection of points that make up this line-string.
+      #           Must be empty or have at least two points.</li>
+      #       <li>one-element string array with the wkt representation.</li></ul>
+      #
+      # @example Construct an empty LineString
+      #   line = LineString.new
+      # @example Construct a LineString with Point objects.
+      #   line = LineString.new(Point.new(1.0, 2.0), Point.new(3.0, 4.0))
+      # @example Construct a LineString with a wkt string.
+      #   line = LineString.new('LINESTRING (1.0 2.0, 3.0 4.0)')
+      def initialize(*args)
+        # The constructor has two forms:
+        # 1. 0, 2, or more Point objects in the order in which one connects them to make a line-string.
+        # 2. one String arg as the wkt representation.
+
+        if args.size == 1
+          wkt = args.first
+          Cassandra::Util.assert_instance_of(String, wkt)
+
+          if wkt == 'LINESTRING EMPTY'
+            @points = [].freeze
+          else
+            match = wkt.match(WKT_RE)
+            raise ArgumentError, "#{wkt.inspect} is not a valid WKT representation of a line-string" unless match
+            @points = self.class.parse_wkt_internal(match[1])
+          end
+        else
+          @points = args.freeze
+          @points.each do |p|
+            Cassandra::Util.assert_instance_of(Point, p, "#{p.inspect} is not a Point")
+          end
+        end
+      end
+
+      # @private
+      def self.parse_wkt_internal(line_str)
+        point_strings = line_str.split(POINT_SEPARATOR_RE)
+        points = []
+        point_strings.each do |ps|
+          next if ps.empty?
+          points << Point.new(*Point.parse_wkt_internal(ps))
+        end
+        points.freeze
+      end
+
+      # @return [String] well-known-text representation of this line-string.
+      def wkt
+        @points.empty? ? 'LINESTRING EMPTY' : "LINESTRING (#{wkt_internal})"
+      end
+
+      # @return [String] a human-readable English string describing this {LineString}.
+      def to_s
+        @points.join(' to ')
+      end
+
+      # @private
+      def wkt_internal
+        # This is a helper used to embed point coords into some container (e.g. polygon)
+        @points.map(&:wkt_internal).join(', ')
+      end
+
+      # @private
+      def eql?(other)
+        other.is_a?(LineString) && \
+          @points == other.points
+      end
+      alias == eql?
+
+      # @private
+      def hash
+        @hash ||= 31 * 17 + @points.hash
+      end
+
+      # @private
+      def inspect
+        "#<LineString:0x#{object_id.to_s(16)} " \
+          "@points=#{@points.inspect}>"
+      end
+
+      # methods related to serializing/deserializing.
+
+      # @private
+      TYPE = Cassandra::Types::Custom.new('org.apache.cassandra.db.marshal.LineStringType')
+
+      # @return [Cassandra::Types::Custom] type of column that is processed by this domain object class.
+      def self.type
+        TYPE
+      end
+
+      # Deserialize the given data into an instance of this domain object class.
+      # @param data [String] byte-array representation of a column value of this custom type.
+      # @return [LineString]
+      # @raise [Cassandra::Errors::DecodingError] upon failure.
+      def self.deserialize(data)
+        buffer = Cassandra::Protocol::CqlByteBuffer.new(data)
+        little_endian = buffer.read(1) != "\x00"
+
+        # Depending on the endian-ness of the data, we want to read it differently. Wrap the buffer
+        # with an "endian-aware" reader that reads the desired way.
+        buffer = Dse::Util::EndianBuffer.new(buffer, little_endian)
+
+        type = buffer.read_unsigned
+        raise Cassandra::Errors::DecodingError, "LineString data-type value should be 2, but was #{type}" if type != 2
+
+        deserialize_raw(buffer)
+      end
+
+      # This is a helper function to deserialize the meat of the data (after we've accounted for endianness
+      # and other metadata)
+      # @private
+      def self.deserialize_raw(buffer)
+        # Now comes the number of points in the line-string.
+        num_points = buffer.read_unsigned
+
+        # Read that many x,y coords from the buffer.
+        points = []
+        num_points.times do
+          points << Point.deserialize_raw(buffer)
+        end
+        LineString.new(*points)
+      end
+
+      # Serialize this domain object into a byte array to send to DSE.
+      # @return [String] byte-array representation of this domain object.
+      def serialize
+        buffer = Cassandra::Protocol::CqlByteBuffer.new
+
+        # We serialize in little-endian form.
+
+        buffer << "\x01"
+
+        # This is a line-string.
+        buffer.append([2].pack(Cassandra::Protocol::Formats::INT_FORMAT_LE))
+
+        # Write out the count of how many points we have.
+        serialize_raw(buffer)
+
+        buffer
+      end
+
+      # This is a helper function to serialize the meat of the data (after we've accounted for endianness
+      # and other metadata)
+      # @private
+      def serialize_raw(buffer)
+        buffer.append([@points.size].pack(Cassandra::Protocol::Formats::INT_FORMAT_LE))
+
+        # Now write out x and y for each point.
+        @points.each do |point|
+          point.serialize_raw(buffer)
+        end
+      end
+    end
+  end
+end

data/lib/dse/geometry/point.rb

@@ -0,0 +1,179 @@
+# encoding: utf-8
+
+#--
+#      Copyright (C) 2016 DataStax Inc.
+#
+#      This software can be used solely with DataStax Enterprise. Please consult the license at
+#      http://www.datastax.com/terms/datastax-dse-driver-license-terms
+#++
+
+module Dse
+  module Geometry
+    # Encapsulates a 2D point with x,y coordinates. It corresponds to the `org.apache.cassandra.db.marshal.PointType`
+    # column type in DSE.
+    #
+    # @see https://en.wikipedia.org/wiki/Well-known_text Wikipedia article on Well Known Text
+    class Point
+      include Cassandra::CustomData
+
+      # @return [Float] the x coordinate of the point.
+      attr_reader :x
+      # @return [Float] the y coordinate of the point.
+      attr_reader :y
+
+      # @private
+      WKT_RE = /^POINT\s*\(\s*([^)]+?)\s*\)$/
+      # @private
+      POINT_SPEC_RE = /^([0-9\-\.]+)\s+([0-9\-\.]+)$/
+      # @private
+      EOL_RE = /[\r\n]/
+
+      # @param args [Array<Numeric>,Array<String>] varargs-style arguments in two forms:
+      #   <ul><li>two-element numeric array representing x,y coordinates.</li>
+      #       <li>one-element string array with the wkt representation.</li></ul>
+      #
+      # @example Construct a Point with numeric arguments.
+      #   point = Point.new(3, 4)
+      # @example Construct a Point with a wkt string.
+      #   point = Point.new('POINT (3.0 4.0)')
+      def initialize(*args)
+        # The constructor has two forms:
+        # 1. two numeric args (x,y)
+        # 2. one String arg as the wkt representation.
+
+        case args.size
+        when 2
+          x, y = args
+          Cassandra::Util.assert_instance_of(::Numeric, x)
+          Cassandra::Util.assert_instance_of(::Numeric, y)
+          Cassandra::Util.assert(!x.nan?, 'x cannot be Float::NAN') if x.is_a?(Float)
+          Cassandra::Util.assert(!y.nan?, 'y cannot be Float::NAN') if y.is_a?(Float)
+          @x = x.to_f
+          @y = y.to_f
+        when 1
+          wkt = args.first
+          Cassandra::Util.assert_instance_of(String, wkt)
+          # subsitute eol chars in the string with a space.
+          wkt.gsub!(EOL_RE, ' ')
+          match = wkt.match(WKT_RE)
+          raise ArgumentError, "#{wkt.inspect} is not a valid WKT representation of a point" unless match
+          @x, @y = self.class.parse_wkt_internal(match[1])
+        else
+          raise ArgumentError,
+                'wrong number of arguments: use one string argument (wkt) or two numeric arguments (x,y)'
+        end
+      end
+
+      # @return [String] well-known-text representation of this point.
+      def wkt
+        "POINT (#{wkt_internal})"
+      end
+
+      # @return [String] a human-readable English string describing this {Point}.
+      def to_s
+        "#{@x},#{@y}"
+      end
+
+      # @private
+      def wkt_internal
+        # This is a helper used to embed point coords into some container (e.g. line-string, polygon)
+        "#{@x} #{@y}"
+      end
+
+      # @private
+      def self.parse_wkt_internal(point_str)
+        point_str.rstrip!
+        match = point_str.match(POINT_SPEC_RE)
+        raise ArgumentError, "#{point_str.inspect} is not a valid WKT representation of a point" unless match
+        [match[1].to_f, match[2].to_f]
+      end
+
+      # @private
+      def eql?(other)
+        other.is_a?(Point) && \
+          @x == other.x && \
+          @y == other.y
+      end
+      alias == eql?
+
+      # @private
+      def hash
+        @hash ||= begin
+          h = 17
+          h = 31 * h + @x.hash
+          h = 31 * h + @y.hash
+          h
+        end
+      end
+
+      # @private
+      def inspect
+        "#<Point:0x#{object_id.to_s(16)} " \
+          "@x=#{@x.inspect}, " \
+          "@y=#{@y.inspect}>"
+      end
+
+      # methods related to serializing/deserializing.
+
+      # @private
+      TYPE = Cassandra::Types::Custom.new('org.apache.cassandra.db.marshal.PointType')
+
+      # @return [Cassandra::Types::Custom] type of column that is processed by this domain object class.
+      def self.type
+        TYPE
+      end
+
+      # Deserialize the given data into an instance of this domain object class.
+      # @param data [String] byte-array representation of a column value of this custom type.
+      # @return [Point]
+      # @raise [Cassandra::Errors::DecodingError] upon failure.
+      def self.deserialize(data)
+        buffer = Cassandra::Protocol::CqlByteBuffer.new(data)
+        little_endian = buffer.read(1) != "\x00"
+
+        # Depending on the endian-ness of the data, we want to read it differently. Wrap the buffer
+        # with an "endian-aware" reader that reads the desired way.
+        buffer = Dse::Util::EndianBuffer.new(buffer, little_endian)
+
+        type = buffer.read_unsigned
+        raise Cassandra::Errors::DecodingError, "Point data-type value should be 1, but was #{type}" if type != 1
+        deserialize_raw(buffer)
+      end
+
+      # This is a helper function to deserialize the meat of the data (after we've accounted for endianness
+      # and other metadata)
+      # @private
+      def self.deserialize_raw(buffer)
+        x = buffer.read_double
+        y = buffer.read_double
+        Point.new(x, y)
+      end
+
+      # Serialize this domain object into a byte array to send to DSE.
+      # @return [String] byte-array representation of this domain object.
+      def serialize
+        buffer = Cassandra::Protocol::CqlByteBuffer.new
+
+        # Serialize little-endian.
+
+        buffer << "\x01"
+
+        # This is a point.
+        buffer.append([1].pack(Cassandra::Protocol::Formats::INT_FORMAT_LE))
+
+        # Write out x and y.
+        serialize_raw(buffer)
+
+        buffer
+      end
+
+      # This is a helper function to serialize the meat of the data (after we've accounted for endianness
+      # and other metadata)
+      # @private
+      def serialize_raw(buffer)
+        buffer.append([@x].pack(Cassandra::Protocol::Formats::DOUBLE_FORMAT_LE))
+        buffer.append([@y].pack(Cassandra::Protocol::Formats::DOUBLE_FORMAT_LE))
+      end
+    end
+  end
+end

data/lib/dse/geometry/polygon.rb

@@ -0,0 +1,196 @@
+# encoding: utf-8
+
+#--
+#      Copyright (C) 2016 DataStax Inc.
+#
+#      This software can be used solely with DataStax Enterprise. Please consult the license at
+#      http://www.datastax.com/terms/datastax-dse-driver-license-terms
+#++
+
+module Dse
+  module Geometry
+    # Encapsulates a polygon consisting of a set of linear-rings in the xy-plane. It corresponds to the
+    # `org.apache.cassandra.db.marshal.PolygonType` column type in DSE.
+    #
+    # A linear-ring is a {LineString} whose last point is the same as its first point. The first ring specified
+    # in a polygon defines the outer edges of the polygon and is called the _exterior ring_. A polygon may also have
+    # _holes_ within it, specified by other linear-rings, and those holes may contain linear-rings indicating
+    # _islands_. All such rings are called _interior rings_.
+    #
+    # @see https://en.wikipedia.org/wiki/Well-known_text Wikipedia article on Well Known Text
+    class Polygon
+      include Cassandra::CustomData
+
+      # @private
+      WKT_RE = /^POLYGON\s*\(\s*(.+?)\s*\)$/
+      # @private
+      LINESTRING_SEPARATOR_RE = /\),?/
+      # @private
+      EOL_RE = /[\r\n]/
+
+      # @param args [Array<LineString>,Array<String>] varargs-style arguments in two forms:
+      #   <ul><li>ordered collection of linear-rings that make up this polygon. Can be empty.</li>
+      #       <li>one-element string array with the wkt representation.</li></ul>
+      #
+      # @example Construct an empty Polygon
+      #   polygon = Polygon.new
+      # @example Construct a Polygon with LineString objects.
+      #   exterior_ring = LineString.new(Point.new(0, 0), Point.new(10, 0), Point.new(10, 10), Point.new(0, 0))
+      #   interior_ring = LineString.new(Point.new(1, 1), Point.new(1, 5), Point.new(5, 1), Point.new(1, 1))
+      #   polygon = Polygon.new(exterior_ring, interior_ring)
+      # @example Construct a line-string with a wkt string.
+      #   polygon = Polygon.new('POLYGON ((0.0 0.0, 10.0 0.0, 10.0 10.0, 0.0 0.0), ' \
+      #                         '(1.0 1.0, 1.0 5.0, 5.0 1.0, 1.0 1.0))')
+      def initialize(*args)
+        # The constructor has two forms:
+        # 1. 0 or more LineString objects where the first is the exterior ring and the rest are interior rings.
+        # 2. one String arg as the wkt representation.
+
+        if args.size == 1 && args.first.is_a?(String)
+          # subsitute eol chars in the string with a space.
+          wkt = args.first.gsub(EOL_RE, ' ')
+          # Consolidate whitespace before/after commas and parens.
+          wkt.gsub!(/\s*([,\(\)])\s*/, '\1')
+          if wkt == 'POLYGON EMPTY'
+            @rings = [].freeze
+          else
+            match = wkt.match(WKT_RE)
+            raise ArgumentError, "#{wkt.inspect} is not a valid WKT representation of a polygon" unless match
+            @rings = parse_wkt_internal(match[1])
+          end
+        else
+          @rings = args.freeze
+          @rings.each do |ring|
+            Cassandra::Util.assert_instance_of(LineString, ring, "#{ring.inspect} is not a LineString")
+          end
+        end
+      end
+
+      # @private
+      def parse_wkt_internal(poly_str)
+        # poly_str is everything inside the outer parens. Example:
+        # original: POLYGON ( (1 2, 3 4, 5 6, 1 2), (9 8, 7 6, 5 4, 9 8) )
+        # poly_str: (1 2, 3 4, 5 6, 1 2), (9 8, 7 6, 5 4, 9 8)
+        line_string_strings = poly_str.split(LINESTRING_SEPARATOR_RE)
+        line_strings = []
+        line_string_strings.each do |ls|
+          # ls still has a leading open paren and possibly spaces.
+          ls.sub!(/\s*\(\s*/, '')
+          line_strings << LineString.new(*LineString.parse_wkt_internal(ls))
+        end
+        line_strings.freeze
+      end
+
+      # @return [LineString] linear-ring characterizing the exterior of the polygon. `nil` for empty polygon.
+      def exterior_ring
+        @rings.first
+      end
+
+      # @return [Array<LineString>] ordered collection of linear-rings that make up the interior of this polygon.
+      #     Empty if there are no interior rings.
+      def interior_rings
+        @interior_rings ||= (@rings[1..-1] || []).freeze
+      end
+
+      # @return [String] well-known-text representation of this polygon.
+      def wkt
+        return 'POLYGON EMPTY' if @rings.empty?
+
+        result = 'POLYGON ('
+        first = true
+        @rings.each do |ring|
+          result += ', ' unless first
+          first = false
+          result += "(#{ring.wkt_internal})"
+        end
+        result += ')'
+        result
+      end
+
+      # @return [String] a human-readable English string describing this {Polygon}.
+      def to_s
+        "Exterior ring: #{@rings.first}\n" \
+          "Interior rings:\n    " +
+          interior_rings.join("\n    ")
+      end
+
+      # @private
+      def eql?(other)
+        other.is_a?(Polygon) && \
+          @rings == other.instance_variable_get(:@rings)
+      end
+      alias == eql?
+
+      # @private
+      def hash
+        @hash ||= 31 * 17 + @rings.hash
+      end
+
+      # @private
+      def inspect
+        "#<Polygon:0x#{object_id.to_s(16)} " \
+          "@exterior_ring=#{@rings.first.inspect}, " \
+        "@interior_rings=#{interior_rings.inspect}>"
+      end
+
+      # methods related to serializing/deserializing.
+
+      # @private
+      TYPE = Cassandra::Types::Custom.new('org.apache.cassandra.db.marshal.PolygonType')
+
+      # @return [Cassandra::Types::Custom] type of column that is processed by this domain object class.
+      def self.type
+        TYPE
+      end
+
+      # Deserialize the given data into an instance of this domain object class.
+      # @param data [String] byte-array representation of a column value of this custom type.
+      # @return [Polygon]
+      # @raise [Cassandra::Errors::DecodingError] upon failure.
+      def self.deserialize(data)
+        buffer = Cassandra::Protocol::CqlByteBuffer.new(data)
+        little_endian = buffer.read(1) != "\x00"
+
+        # Depending on the endian-ness of the data, we want to read it differently. Wrap the buffer
+        # with an "endian-aware" reader that reads the desired way.
+        buffer = Dse::Util::EndianBuffer.new(buffer, little_endian)
+
+        type = buffer.read_unsigned
+        raise Cassandra::Errors::DecodingError, "LineString data-type value should be 3, but was #{type}" if type != 3
+
+        # Now comes the number of rings.
+        num_rings = buffer.read_unsigned
+
+        # Read that many line-string's (rings) from the buffer.
+        rings = []
+        num_rings.times do
+          rings << LineString.deserialize_raw(buffer)
+        end
+        Polygon.new(*rings)
+      end
+
+      # Serialize this domain object into a byte array to send to DSE.
+      # @return [String] byte-array representation of this domain object.
+      def serialize
+        buffer = Cassandra::Protocol::CqlByteBuffer.new
+
+        # We serialize in little-endian form.
+
+        buffer << "\x01"
+
+        # This is a polygon.
+        buffer.append([3].pack(Cassandra::Protocol::Formats::INT_FORMAT_LE))
+
+        # Write out the count of how many rings we have.
+        buffer.append([@rings.size].pack(Cassandra::Protocol::Formats::INT_FORMAT_LE))
+
+        # Now write out the raw serialization of each ring (e.g. linestring).
+        @rings.each do |ring|
+          ring.serialize_raw(buffer)
+        end
+
+        buffer
+      end
+    end
+  end
+end