fast-polylines 2.0.0 → 2.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a3a21f83abca7c1b9ef3bb824145ceea3189fbdb9d428a2faff1daa94e2a50fb
-  data.tar.gz: 0e6578cb705d0121daadb0a019bedd2d0d1b2589b2905134f933f4ae0859d3e2
+  metadata.gz: fd26a9400977f70c17d07fbbc97484bc33fa5c2a876ec72739379b9650b00403
+  data.tar.gz: b2caa0bcaa90d269bd92b948b01ecc080c006a1304500edd1435513671a2b465
 SHA512:
-  metadata.gz: 16c293fc12361086fc39002b10fd81faaeb68632e4c6e670de1c2ec242b8277a7c453da2e5f1a9176104ccdafab99447807871f8afdb09188d97f07ed6a307d0
-  data.tar.gz: e48e91654bc2746c4c36d3d6ce744914941ec4966f1aa6b56bbe61cacdcce841dc936b997dd477794ad8a0546ebb7c9317afc007dc1b9f74dd630d9de5d2f417
+  metadata.gz: 7fb523730effba875e1eb7f557904bfdf11f44e419cbea433f11d29c73587b29956339075ac3b6af8f7e83de2a5b17241d93bb806f703a69f2ca81ff439fcd2a
+  data.tar.gz: 4311f966e39d44e47fd039712549466fa29a828f7470e5c33238f8997540f95327e2befd182bc79ceebfe9c5c728e001a41cd57ab7250ea80b676023a3a8913f

data/.rspec

@@ -0,0 +1 @@
+--require spec_helper

data/.yardopts

@@ -0,0 +1,7 @@
+--markup markdown
+--output-dir ./yardoc
+lib/**/*.rb
+ext/**/*.c
+-
+README.md
+CHANGELOG.md

data/CHANGELOG.md

@@ -0,0 +1,55 @@
+
+# Changelog
+
+All notable changes to this project will be documented in this file.
+The format is based on [Keep a Changelog](http://keepachangelog.com/).
+This project adheres to [Semantic Versioning](http://semver.org/).
+
+## [unreleased] —
+
+### Added
+
+### Changed
+
+### Fixed
+
+## [2.2.2] — 2022-01-11
+
+### Added
+
+- C API documentation.
+
+## [2.2.0] — 2020-11-24
+
+### Added
+
+- support for windows (#19 #23) by [@mohits]
+
+### Changed
+
+- Speedup calculation by avoiding calling pow(10,x) (#22) by [@mohits]
+
+### Fixed
+
+- move from travis to github actions
+
+[@mohits]: https://github.com/mohits
+
+## [2.1.0] — 2020-04-30
+
+### Added
+
+- A Require ptah that match the gem name (#18)
+
+## [2.0.1] — 2020-04-02
+
+### Fixed
+
+- Broken behavior when approaching the chunk size limit (#16)
+
+
+[unreleased]: https://github.com/klaxit/fast-polylines/compare/v2.2.2...HEAD
+[2.2.2]: https://github.com/klaxit/fast-polylines/compare/v2.2.0...v2.2.2
+[2.2.0]: https://github.com/klaxit/fast-polylines/compare/v2.1.0...v2.2.0
+[2.1.0]: https://github.com/klaxit/fast-polylines/compare/v2.0.1...v2.1.0
+[2.0.1]: https://github.com/klaxit/fast-polylines/compare/v2.0.0...v2.0.1

data/README.md

@@ -1,11 +1,11 @@
 # Fast Polylines
 
-[![Gem Version](https://badge.fury.io/rb/fast-polylines.svg)](https://badge.fury.io/rb/fast-polylines)
-[![Build Status](https://travis-ci.org/klaxit/fast-polylines.svg?branch=master)](https://travis-ci.org/klaxit/fast-polylines)
+[![Gem](https://img.shields.io/gem/v/fast-polylines)](https://rubygems.org/gems/fast-polylines)
+[![GitHub Workflow Status](https://img.shields.io/github/workflow/status/klaxit/fast-polylines/Continuous%20Integration)](https://github.com/klaxit/fast-polylines/actions?query=workflow%3A%22Continuous+Integration%22)
 
 Implementation of the [Google polyline algorithm][algorithm].
 
-**BREAKING CHANGES:** The version 2.0.0 of FastPolylines includes breaking changes, see [Migrate from 1.0.0](#migrate-from-1.0.0)
+**BREAKING CHANGES:** The version 2 of FastPolylines includes breaking changes, see [Migrate from V1](#migrate-from-V1)
 
 
 About **300x faster encoding and decoding**  than [Joshua Clayton's gem][polylines].
@@ -16,35 +16,35 @@ About **300x faster encoding and decoding**  than [Joshua Clayton's gem][polylin
 ——————————————————————————————— ENCODING ————————————————————————————————
 
 Warming up --------------------------------------
-           Polylines   277.000  i/100ms
-     FastPolylinesV1     2.050k i/100ms
-     FastPolylinesV2    73.822k i/100ms
+           Polylines   310.000  i/100ms
+     FastPolylinesV1     2.607k i/100ms
+     FastPolylinesV2    59.833k i/100ms
 Calculating -------------------------------------
-           Polylines      3.254k (± 1.8%) i/s -     16.343k in   5.023767s
-     FastPolylinesV1     25.715k (± 3.7%) i/s -    129.150k in   5.029675s
-     FastPolylinesV2    933.751k (± 4.3%) i/s -      4.725M in   5.072446s
+           Polylines      2.957k (± 5.9%) i/s -     14.880k in   5.049867s
+     FastPolylinesV1     25.644k (± 5.8%) i/s -    127.743k in   4.999954s
+     FastPolylinesV2    682.981k (± 7.7%) i/s -      3.410M in   5.025952s
 
 Comparison:
-     FastPolylinesV2:   933750.7 i/s
-     FastPolylinesV1:    25715.1 i/s - 36.31x  slower
-           Polylines:     3254.3 i/s - 286.93x  slower
+     FastPolylinesV2:   682980.7 i/s
+     FastPolylinesV1:    25643.7 i/s - 26.63x  slower
+           Polylines:     2957.1 i/s - 230.97x  slower
 
 
 ———————————————————————————————  DECODING ————————————————————————————————
 
 Warming up --------------------------------------
-           Polylines   140.000  i/100ms
-     FastPolylinesV1     1.602k i/100ms
-     FastPolylinesV2    36.432k i/100ms
+           Polylines   127.000  i/100ms
+     FastPolylinesV1     1.225k i/100ms
+     FastPolylinesV2    40.667k i/100ms
 Calculating -------------------------------------
-           Polylines      1.401k (± 2.2%) i/s -      7.000k in   5.000321s
-     FastPolylinesV1     16.465k (± 3.7%) i/s -     83.304k in   5.067786s
-     FastPolylinesV2    396.100k (± 5.2%) i/s -      2.004M in   5.074500s
+           Polylines      1.289k (± 6.1%) i/s -      6.477k in   5.046552s
+     FastPolylinesV1     15.445k (± 4.4%) i/s -     77.175k in   5.006896s
+     FastPolylinesV2    468.413k (± 7.8%) i/s -      2.359M in   5.068936s
 
 Comparison:
-     FastPolylinesV2:   396100.0 i/s
-     FastPolylinesV1:    16464.6 i/s - 24.06x  slower
-           Polylines:     1400.6 i/s - 282.81x  slower
+     FastPolylinesV2:   468412.8 i/s
+     FastPolylinesV1:    15445.4 i/s - 30.33x  slower
+           Polylines:     1288.8 i/s - 363.46x  slower
 ```
 
 ## Install
@@ -61,7 +61,7 @@ gem "fast-polylines", "~> 2.0.0"
 ## Usage
 
 ```ruby
-require "fast-polylines"
+require "fast_polylines"
 
 FastPolylines.encode([[38.5, -120.2], [40.7, -120.95], [43.252, -126.453]])
 # "_p~iF~ps|U_ulLnnqC_mqNvxq`@"
@@ -74,7 +74,7 @@ FastPolylines.decode("_p~iF~ps|U_ulLnnqC_mqNvxq`@")
 
 **Use a different precision**
 
-Default precision is `5` decimals, to use a precision of `6` decimals:
+Default precision is `5` decimals, to use a precision of `6`:
 ```ruby
 FastPolylines.encode([[38.5, -120.2], [40.7, -120.95], [43.252, -126.453]], 6)
 # "_izlhA~rlgdF_{geC~ywl@_kwzCn`{nI"
@@ -84,17 +84,21 @@ FastPolylines.decode("_izlhA~rlgdF_{geC~ywl@_kwzCn`{nI", 6)
 ```
 The precision max is `13`.
 
-## Migrate from 1.0.0
+## Migrate from V1
 
 **TL;DR:**
 
 ```ruby
 # before
+require "fast-polylines"
 FastPolylines::Encoder.encode([[1.2, 1.2], [2.4, 2.4]], 1e6)
 # after
+require "fast_polylines"
 FastPolylines.encode([[1.2, 1.2], [2.4, 2.4]], 6)
 ```
 
+**Detailled:**
+
 The new version of `FastPolylines` doesn't support precision more than `1e13`,
 you should not consider using it anyway since [it is way too precise][xkcd].
 
@@ -106,6 +110,9 @@ The precision is now an integer representing the number of decimals. It is
 slightly smaller, and mostly this will avoid having any float value as
 precision.
 
+The file name to require is now snake_cased, you'll have to require
+`fast_polylines`. The gem name stays the same however.
+
 ## Run the Benchmark
 
 You can run the benchmark with `make benchmark`.

data/ext/fast_polylines/extconf.rb

@@ -1,4 +1,14 @@
 # frozen_string_literal: true
 
 require "mkmf"
+
+if ENV["DEBUG"]
+  warn "DEBUG MODE."
+  $CFLAGS << " " << %w(
+    -Wall
+    -ggdb
+    -DDEBUG
+    -pedantic
+  ) * " "
+end
 create_makefile "fast_polylines/fast_polylines"

data/ext/fast_polylines/fast_polylines.c

@@ -1,4 +1,25 @@
-#include <ruby/ruby.h>
+/**
+ * Document-module: FastPolylines
+ *
+ * Implementation of the [Google polyline algorithm](https://code.google.com/apis/maps/documentation/utilities/polylinealgorithm.html).
+ *
+ * Install it with `gem install fast-polylines`, and then:
+ *
+ *     require "fast_polylines"
+ *
+ *     FastPolylines.encode([[38.5, -120.2], [40.7, -120.95], [43.252, -126.453]])
+ *     # "_p~iF~ps|U_ulLnnqC_mqNvxq`@"
+ *
+ *     FastPolylines.decode("_p~iF~ps|U_ulLnnqC_mqNvxq`@")
+ *     # [[38.5, -120.2], [40.7, -120.95], [43.252, -126.453]]
+ *
+ * You can set an arbitrary precision for your coordinates to be encoded/decoded. It may be from 1
+ * to 13 decimal digits. However, 13 may be too much.
+ *
+ * [![https://xkcd.com/2170/](https://imgs.xkcd.com/comics/coordinate_precision.png)](https://www.explainxkcd.com/wiki/index.php/2170:_Coordinate_Precision)
+ */
+
+#include <ruby.h>
 
 // An encoded number can have at most _precision_ characters. However,
 // it seems like we have a fuzzy behavior on low precisions. Hence a guard
@@ -24,6 +45,21 @@
 #define rdbg(...)
 #endif
 
+typedef unsigned int uint;
+
+// Speed up the code a bit by not calling pow(10.0, precision) since it is
+// always 10^precision. Convert that into a lookup instead of doing the
+// calculation.
+// The precision parameter is already checked in +_get_precision()+ to ensure
+// that it is within the range.
+static inline double _fast_pow10(uint precision) {
+	const double lookup[MAX_PRECISION + 1] = {
+		1.0, 10.0, 1.0e+2, 1.0e+3, 1.0e+4, 1.0e+5, 1.0e+6, 1.0e+7,
+		1.0e+8, 1.0e+9, 1.0e+10, 1.0e+11, 1.0e+12, 1.0e+13
+	};
+	return lookup[precision];
+}
+
 static inline uint _get_precision(VALUE value) {
 	int precision = NIL_P(value) ? DEFAULT_PRECISION : NUM2INT(value);
 	if (precision > MAX_PRECISION) rb_raise(rb_eArgError, "precision too high (https://xkcd.com/2170/)");
@@ -31,13 +67,22 @@ static inline uint _get_precision(VALUE value) {
 	return (uint)precision;
 }
 
-static inline VALUE
+/**
+ * call-seq:
+ *   FastPolylines.decode(polyline, precision = 5) -> [[lat, lng], ...]
+ *
+ * Decode a polyline to a list of coordinates (lat, lng tuples). You may
+ * set an arbitrary coordinate precision, however, it **must match** the precision
+ * that was used for encoding.
+ */
+static VALUE
 rb_FastPolylines__decode(int argc, VALUE *argv, VALUE self) {
 	rb_check_arity(argc, 1, 2);
 	Check_Type(argv[0], T_STRING);
 	char* polyline = StringValueCStr(argv[0]);
 	uint precision = _get_precision(argc > 1 ? argv[1] : Qnil);
-	double precision_value = pow(10.0, precision);
+	double precision_value = _fast_pow10(precision);
+
 	VALUE ary = rb_ary_new();
 	// Helps keeping track of whether we are computing lat (0) or lng (1).
 	uint8_t index = 0;
@@ -72,19 +117,30 @@ rb_FastPolylines__decode(int argc, VALUE *argv, VALUE self) {
 
 static inline uint8_t
 _polyline_encode_number(char *chunks, int64_t number) {
+	dbg("_polyline_encode_number(\"%s\", %lli)\n", chunks, number);
 	number = number < 0 ? ~(number << 1) : (number << 1);
 	uint8_t i = 0;
-	while (number > 0x20) {
+	while (number >= 0x20) {
 		uint8_t chunk = number & 0x1f;
 		chunks[i++] = (0x20 | chunk) + 63;
 		number = number >> 5;
 	}
-	dbg("%u encoded chunks\n", i);
 	chunks[i++] = number + 63;
+	dbg("%u encoded chunks\n", i);
+	dbg("chunks: %s\n", chunks);
+	dbg("/_polyline_encode_number\n");
 	return i;
 }
 
-static inline VALUE
+/**
+ * call-seq:
+ *   FastPolylines.encode([[lat, lng], ...], precision = 5) -> string
+ *
+ * Encode a list of coordinates to a polyline, you may give a specific precision
+ * if you want to retain more (or less) than 5 digits of precision. The maximum
+ * is 13, and may really be [too much](https://xkcd.com/2170/).
+ */
+static VALUE
 rb_FastPolylines__encode(int argc, VALUE *argv, VALUE self) {
 	rb_check_arity(argc, 1, 2);
 	Check_Type(argv[0], T_ARRAY);
@@ -95,7 +151,8 @@ rb_FastPolylines__encode(int argc, VALUE *argv, VALUE self) {
 	uint precision = _get_precision(argc > 1 ? argv[1] : Qnil);
 	dbg("rb_FastPolylines__encode(..., %u)\n", precision);
 	rdbg(argv[0]);
-	double precision_value = pow(10.0, precision);
+	double precision_value = _fast_pow10(precision);
+
 	// This is the maximum possible size the polyline may have. This
 	// being **without** null character. To copy it later as a Ruby
 	// string we'll have to use `rb_str_new` with the length.
@@ -108,6 +165,7 @@ rb_FastPolylines__encode(int argc, VALUE *argv, VALUE self) {
 	for (i = 0; i < len; i++) {
 			current_pair = RARRAY_AREF(argv[0], i);
 			uint8_t j;
+			Check_Type(current_pair, T_ARRAY);
 			if (RARRAY_LEN(current_pair) != 2) {
 				free(chunks);
 				rb_raise(rb_eArgError, "wrong number of coordinates");
@@ -136,6 +194,7 @@ rb_FastPolylines__encode(int argc, VALUE *argv, VALUE self) {
 				// We pass a pointer to the current chunk that need to be filled. Doing so
 				// avoid having to copy the string every single iteration.
 				chunks_index += _polyline_encode_number(chunks + chunks_index * sizeof(char), delta);
+				dbg("%s\n", chunks);
 			}
 	}
 	dbg("final chunks_index: %zu\n", chunks_index);

data/lib/fast-polylines.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+# Allow both snake_case and kebab-case way to require
+require_relative "fast_polylines"

data/lib/fast_polylines/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module FastPolylines
-  VERSION = "2.0.0"
+  VERSION = "2.2.2"
 end

data/lib/fast_polylines.rb

@@ -3,17 +3,19 @@
 require "fast_polylines/fast_polylines"
 
 module FastPolylines::Encoder
-  module_function def encode(points, precision = 1e5)
+  # @deprecated Use {FastPolylines.encode} instead.
+  def self.encode(points, precision = 1e5)
     warn "Deprecated use of `FastPolylines::Encoder.encode`, " \
-          "use `FastPolylines.encode`."
+         "use `FastPolylines.encode`."
     FastPolylines.encode(points, Math.log10(precision))
   end
 end
 
 module FastPolylines::Decoder
-  module_function def decode(polyline, precision = 1e5)
+  # @deprecated Use {FastPolylines.decode} instead.
+  def self.decode(polyline, precision = 1e5)
     warn "Deprecated use of `FastPolylines::Decoder.decode`, " \
-          "use `FastPolylines.decode`."
+         "use `FastPolylines.decode`."
     FastPolylines.decode(polyline, Math.log10(precision))
   end
 end

data/spec/fast-polylines_spec.rb

@@ -0,0 +1,10 @@
+require "fast-polylines"
+
+describe FastPolylines do
+  let(:points) { [[38.5, -120.2], [40.7, -120.95], [43.252, -126.453]] }
+  let(:polyline) { "_p~iF~ps|U_ulLnnqC_mqNvxq`@" }
+  it "should work with kebab-case requirement" do
+    expect(FastPolylines.encode(points)).to eq polyline
+    expect(FastPolylines.decode(polyline)).to eq points
+  end
+end

data/spec/fast_polylines_spec.rb

@@ -1,10 +1,10 @@
-require "spec_helper"
+require "fast_polylines"
 
 describe FastPolylines do
   describe ".decode" do
     let(:points) { [[38.5, -120.2], [40.7, -120.95], [43.252, -126.453]] }
+    let(:polyline) { "_p~iF~ps|U_ulLnnqC_mqNvxq`@" }
     context "with default precision" do
-      let(:polyline) { "_p~iF~ps|U_ulLnnqC_mqNvxq`@" }
       it "should decode a polyline correctly" do
         expect(described_class.decode(polyline)).to eq points
       end
@@ -47,9 +47,34 @@ describe FastPolylines do
   end
 
   describe ".encode" do
-    let(:points)   { [[38.5, -120.2], [40.7, -120.95], [43.252, -126.453]] }
+    let(:points) { [[38.5, -120.2], [40.7, -120.95], [43.252, -126.453]] }
+    let(:polyline) { "_p~iF~ps|U_ulLnnqC_mqNvxq`@" }
+    it "should raise for invalid input" do
+      expect { described_class.encode(points[0]) }.to raise_error(
+        TypeError,
+        "wrong argument type Float (expected Array)"
+      )
+      expect { described_class.encode([points]) }.to raise_error(
+        ArgumentError,
+        "wrong number of coordinates"
+      )
+      expect { described_class.encode([points[0..1]]) }.to raise_error(
+        TypeError,
+        "no implicit conversion to Float from Array"
+      )
+    end
+    # The method `_polyline_encode_number("", 16)` will check for a chunk
+    # of the size 32, which is the chunk size limit. This was errored due to
+    # a bad sign.
+    # Reported in issue #15, closed in PR #16
+    context "with points close to the chunk size limit" do
+      let(:points) { [[0, 0.00016]] }
+      let(:polyline) { "?_@" }
+      it "should encode points correctly" do
+        expect(described_class.encode(points)).to eq polyline
+      end
+    end
     context "with default precision" do
-      let(:polyline) { "_p~iF~ps|U_ulLnnqC_mqNvxq`@" }
       it "should encode points correctly" do
         expect(described_class.encode(points)).to eq polyline
       end

data/spec/spec_helper.rb

@@ -1,7 +1,8 @@
 require "rubygems"
 require "bundler/setup"
 
-require "fast_polylines"
+$LOAD_PATH.unshift File.join(__dir__, "..", "lib")
+$LOAD_PATH.unshift File.join(__dir__, "..", "ext")
 
 RSpec.configure do |config|
   # Additional config goes here

metadata

@@ -1,15 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: fast-polylines
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.2.2
 platform: ruby
 authors:
 - Cyrille Courtière
 - Ulysse Buonomo
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-03-26 00:00:00.000000000 Z
+date: 2022-01-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: benchmark-ips
@@ -53,7 +53,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.5'
-description: 
+description:
 email:
 - dev@klaxit.com
 executables: []
@@ -61,19 +61,23 @@ extensions:
 - ext/fast_polylines/extconf.rb
 extra_rdoc_files: []
 files:
+- ".rspec"
+- ".yardopts"
+- CHANGELOG.md
 - README.md
-- ext/fast_polylines/.gitignore
 - ext/fast_polylines/extconf.rb
 - ext/fast_polylines/fast_polylines.c
+- lib/fast-polylines.rb
 - lib/fast_polylines.rb
 - lib/fast_polylines/version.rb
+- spec/fast-polylines_spec.rb
 - spec/fast_polylines_spec.rb
 - spec/spec_helper.rb
 homepage: https://github.com/klaxit/fast-polylines
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -81,17 +85,19 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 2.4.6
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.2
-signing_key: 
+rubygems_version: 3.2.3
+signing_key:
 specification_version: 4
 summary: Fast & easy Google polylines
 test_files:
+- spec/fast-polylines_spec.rb
 - spec/fast_polylines_spec.rb
 - spec/spec_helper.rb
+- ".rspec"

data/ext/fast_polylines/.gitignore

@@ -1,3 +0,0 @@
-*.o
-*.bundle
-Makefile