hotwater 0.1.0 → 0.1.2

data/.travis.yml

@@ -0,0 +1,6 @@
+language: ruby
+rvm:
+  - 1.9.3
+  - jruby-19mode
+  - jruby-head
+  

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+# 0.1.0, 02-25-2013
+- initial release
+
+# 0.1.2, 02-25-2013
+- linux compilation issue
+- travis support

data/README.md

@@ -1,26 +1,33 @@
-# Hotwater v0.1.0
+# Hotwater v0.1.2
 
-Ruby & JRuby gem with fast **string edit distance** C implementations using FFI bindings.
+[![build status](https://secure.travis-ci.org/colinsurprenant/hotwater.png)](http://travis-ci.org/colinsurprenant/hotwater)
+
+Ruby & JRuby gem with fast **string edit distance** algorithms C implementations with FFI bindings.
 
 ### Algorithms
 
-- Levenshtein & Damerau Levenshtein
-- Jaro & Jaro Winkler
-- N-Gram
+- [Levenshtein](https://en.wikipedia.org/wiki/Levenshtein_distance) & [Damerau Levenshtein](https://en.wikipedia.org/wiki/Damerau%E2%80%93Levenshtein_distance) distance
+- [Jaro & Jaro-Winkler](https://en.wikipedia.org/wiki/Jaro%E2%80%93Winkler_distance) distance
+- [N-Gram](https://en.wikipedia.org/wiki/N-gram) distance
 
 ## Installation
 
-Add this line to your application's Gemfile:
-
-    gem 'hotwater'
+Tested on **OSX 10.8.2** and **Linux 12.10** with
+- MRI Ruby 1.9.3 p385
+- JRuby 1.7.2 (1.9.3 p327)
 
+Add this line to your application's Gemfile:
+```ruby
+gem 'hotwater'
+```
 And then execute:
-
-    $ bundle
-
+```sh
+$ bundle
+```
 Or install it yourself as:
-
-    $ gem install hotwater
+```sh
+$ gem install hotwater
+```
 
 ## Usage
 
@@ -28,7 +35,8 @@ Or install it yourself as:
 Hotwater.levenshtein_distance("abc", "acb") # => 2
 Hotwater.damerau_levenshtein_distance("abc", "acb") # => 1
 
-# do normalization based on the string sizes
+# normalization based on the string sizes
+# where an edit on a small string has more weight than on a longer string
 Hotwater.normalized_levenshtein_distance("abc", "acb").round(4) # => 0.3333
 Hotwater.normalized_damerau_levenshtein_distance("abc", "acb").round(4) # => 0.6667
 
@@ -59,12 +67,19 @@ Hotwater.ngram_distance("natural", "contrary", 3).round(4) # => 0.2083
 5. Create new Pull Request
 
 ## Credits
+
 - Some C code from the https://github.com/sunlightlabs/jellyfish project
 - N-Gram ported from Apache Lucene 4.0.0 NGramDistance.java 
 
+## Why?
+
+Why Hotwater? as stated in the credits section, some of the C code comes from the [jellyfish Python project](https://github.com/sunlightlabs/jellyfish). Jelly fish made me think right away about New Brunswick beaches where I have been a couple of times in the past years. There is this legend about New Brunswick having warm water beaches. I even saw a tourism promotion TV commercial selling NB has having warm water. This is a lie! :P I never experienced warm water (in the generaly accepted definition) in NB, only lots of jellyfish :D (that being said, I have enjoyed every bit of my visits in New Brunswick and I really do not care about warm water really ;)
+
 ## Author
+
 Colin Surprenant, [@colinsurprenant](http://twitter.com/colinsurprenant), [http://github.com/colinsurprenant](http://github.com/colinsurprenant), colin.surprenant@gmail.com
 
 ## License
+
 Hotwater is distributed under the Apache License, Version 2.0. 
 

data/Rakefile

@@ -5,7 +5,7 @@ require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
 require 'ffi-compiler/compile_task'
 
-task :default => :spec
+task :default => [:clean, :compile, :spec]
 
 desc "run specs"
 task :spec do

data/ext/hotwater/Rakefile

@@ -1,5 +1,5 @@
 require 'ffi-compiler/compile_task'
 
 FFI::Compiler::CompileTask.new('hotwater') do |c|
-  # nothing yet bro
+  # nothing to see here, move along
 end

data/ext/hotwater/jaro.c

@@ -10,6 +10,7 @@ Colin Surprenant, Feb 2013
 #include <string.h>
 #include <stdio.h>
 #include <stdlib.h>
+#include <alloca.h>
 #include "hotwater.h"
 
 #define NOTNUM(c)   ((c>57) || (c<48))
@@ -52,7 +53,7 @@ double _jaro_winkler(const char *ying, const char *yang, bool long_tolerance, bo
     search_range = min_len = (ying_length > yang_length) ? ying_length : yang_length;
 
     // Blank out the flags
-    ying_flag = alloca(ying_length + 1);
+    ying_flag = (char *)alloca(ying_length + 1);
     if (!ying_flag) return -1.0;
 
     yang_flag = alloca(yang_length + 1);

data/ext/hotwater/ngram.c

@@ -1,7 +1,7 @@
 /* 
 Colin Surprenant, Feb 2013
 - converted in C from org/apache/lucene/search/spell/NGramDistance.java v4.0.0
-- fixed segfault bug in substring n parameter, which did not surface in Java
+- fixed segfault bug in call to substring for n parameter, which did not surface in Java
 */
 
 /* package org.apache.lucene.search.spell; */
@@ -66,7 +66,8 @@ double ngram_distance (const char *source, const char *target, int n) {
   int cost = 0;
   if (sl < n || tl < n) {
     int ni = MIN(sl, tl);
-    for (int i = 0; i < ni; i++) {
+    int i;
+    for (i = 0; i < ni; i++) {
       if (source[i] == target[i]) {
         cost++;
       }
@@ -85,7 +86,8 @@ double ngram_distance (const char *source, const char *target, int n) {
   double* _d; // placeholder to assist in swapping p and d
   
   // construct sa with prefix
-  for (int i = 0; i < sa_len; i++) {
+  int i;
+  for (i = 0; i < sa_len; i++) {
     if (i < n - 1) {
       sa[i] = 0 ; //add prefix
     }
@@ -108,7 +110,7 @@ double ngram_distance (const char *source, const char *target, int n) {
   }
   
   // indexes into strings s and t
-  int i = 0; // iterates through source
+  i = 0; // iterates through source
   int j = 0; // iterates through target
   
   char* t_j = calloc(n + 1, sizeof(char)); // jth n-gram of t
@@ -125,10 +127,11 @@ double ngram_distance (const char *source, const char *target, int n) {
   for (j = 1; j <= tl; j++) {
     // construct t_j n-gram 
     if (j < n) {
-      for (int ti = 0; ti < n - j; ti++) {
+      int ti;
+      for (ti = 0; ti < n - j; ti++) {
         t_j[ti] = 0; //add prefix
       }
-      for (int ti = n - j; ti < n; ti++) {
+      for (ti = n - j; ti < n; ti++) {
          t_j[ti] = target[ti - (n - j)];
       }
     }
@@ -142,7 +145,8 @@ double ngram_distance (const char *source, const char *target, int n) {
       int tn = n;
       // compare sa to t_j
 
-      for (int ni = 0; ni < n; ni++) {
+      int ni;
+      for (ni = 0; ni < n; ni++) {
         if (sa[i - 1 + ni] != t_j[ni]) {
           cost++;
         }

data/hotwater.gemspec

@@ -8,7 +8,7 @@ Gem::Specification.new do |gem|
   gem.version       = Hotwater::VERSION
   gem.authors       = ["Colin Surprenant"]
   gem.email         = ["colin.surprenant@gmail.com"]
-  gem.description   = "Ruby & JRuby gem with fast string edit distance C implementation using FFI bindings"
+  gem.description   = "Ruby & JRuby gem with fast string edit distance algorithms C implementations with FFI bindings"
   gem.summary       = "Fast string edit distance"
   gem.homepage      = "http://github.com/colinsurprenant/hotwater"
 

data/lib/hotwater/damerau_levenshtein_ffi.rb

@@ -7,16 +7,26 @@ module Hotwater
     attach_function :damerau_levenshtein_distance, [:string, :string], :int
   end
 
+  # compute Damerau Levenshtein edit distance between 2 strings
+  # @param s1 [String] first string
+  # @param s2 [String] seconds string
+  # @return [Integer] edit distance
   def damerau_levenshtein_distance(s1, s2)
     result = C::damerau_levenshtein_distance(s1, s2)
     raise("memory allocation error") if result == -1
     result
   end
 
+  # compute normalized Damerau Levenshtein edit distance between 2 strings
+  # normalization weight the edit distance using the string lengths where 
+  # an edit on a small string has more impact than on a longer string
+  # @param s1 [String] first string
+  # @param s2 [String] seconds string
+  # @return [Float] edit distance between 0.0 and 1.0
   def normalized_damerau_levenshtein_distance(s1, s2)
     result = C::damerau_levenshtein_distance(s1, s2)
     raise("memory allocation error") if result == -1
-    return 0.0 if result == 0
+    return 0.0 if result == 0.0
     max = [s1.size, s2.size].max
     (max - result.to_f) / max
   end

data/lib/hotwater/jaro_ffi.rb

@@ -10,12 +10,27 @@ module Hotwater
     attach_function :jaro_winkler_distance, [:string, :string, :bool], :double
   end
 
+  # compute Jaro edit distance between 2 strings
+  # @param s1 [String] first string
+  # @param s2 [String] seconds string
+  # @return [Float] edit distance between 0.0 and 1.0
   def jaro_distance(s1, s2)
     result = C::jaro_distance(s1, s2)
     raise("memory allocation error") if result < 0.0
     result
   end
 
+  # compute Jaro-Winkler edit distance between 2 strings
+  #
+  # setting `long_tolerance = true` increases the probability of a match when the number
+  # of matched characters is large.  This option allows for a little more
+  # tolerance when the strings are large.  It is not an appropriate
+  # test when comparing fixed length fields such as phone and social security numbers.
+  #
+  # @param s1 [String] first string
+  # @param s2 [String] seconds string
+  # @param long_tolerance [Boolean] add more tolerance when the strings are large. Default `false`
+  # @return [Float] edit distance between 0.0 and 1.0
   def jaro_winkler_distance(s1, s2, long_tolerance = false)
     result = C::jaro_winkler_distance(s1, s2, long_tolerance)
     raise("memory allocation error") if result < 0.0

data/lib/hotwater/levenshtein_ffi.rb

@@ -7,16 +7,26 @@ module Hotwater
     attach_function :levenshtein_distance, [:string, :string], :int
   end
 
+  # compute Levenshtein edit distance between 2 strings
+  # @param s1 [String] first string
+  # @param s2 [String] seconds string
+  # @return [Integer] edit distance
   def levenshtein_distance(s1, s2)
     result = C::levenshtein_distance(s1, s2)
     raise("memory allocation error") if result == -1
     result
   end
 
+  # compute normalized Levenshtein edit distance between 2 strings
+  # normalization weight the edit distance using the string lengths where 
+  # an edit on a small string has more impact than on a longer string
+  # @param s1 [String] first string
+  # @param s2 [String] seconds string
+  # @return [Float] edit distance between 0.0 and 1.0
   def normalized_levenshtein_distance(s1, s2)
     result = C::levenshtein_distance(s1, s2)
     raise("memory allocation error") if result == -1
-    return 0.0 if result == 0
+    return 0.0 if result == 0.0
     max = [s1.size, s2.size].max
     (max - result.to_f) / max
   end

data/lib/hotwater/ngram_ffi.rb

@@ -7,6 +7,11 @@ module Hotwater
     attach_function :ngram_distance, [:string, :string, :int], :double
   end
 
+  # compute N-Gram distance between 2 strings
+  # @param s1 [String] first string
+  # @param s2 [String] seconds string
+  # @param n [Integer] number of characters per gram, default is 2
+  # @return [Float] edit distance between 0.0 and 1.0
   def ngram_distance(s1, s2, n = 2)
     result = C::ngram_distance(s1, s2, n)
     raise("memory allocation error") if result == -1

data/lib/hotwater/version.rb

@@ -1,3 +1,3 @@
 module Hotwater
-  VERSION = "0.1.0"
+  VERSION = "0.1.2"
 end

data/spec/hotwater/damerau_levenshtein_ffi_spec.rb

@@ -25,5 +25,9 @@ describe Hotwater do
     Hotwater.normalized_damerau_levenshtein_distance("Saturday", "Sunday").round(4).should == 0.625
     Hotwater.normalized_damerau_levenshtein_distance("teusday", "tuesday").round(4).should == 0.8571
     Hotwater.normalized_damerau_levenshtein_distance("teusday", "thursday").round(4).should == 0.75
+
+    Hotwater.normalized_levenshtein_distance("aaaa", "aaab").round(4).should == 0.75
+    Hotwater.normalized_levenshtein_distance("aaaaa", "aaaab").round(4).should == 0.8
+    Hotwater.normalized_levenshtein_distance("aaaaaa", "aaaaab").round(4).should == 0.8333
   end
 end

data/spec/hotwater/levenshtein_ffi_spec.rb

@@ -25,5 +25,9 @@ describe Hotwater do
     Hotwater.normalized_levenshtein_distance("Saturday", "Sunday").round(4).should == 0.625
     Hotwater.normalized_levenshtein_distance("teusday", "tuesday").round(4).should == 0.7143
     Hotwater.normalized_levenshtein_distance("teusday", "thursday").round(4).should == 0.75
+
+    Hotwater.normalized_levenshtein_distance("aaaa", "aaab").round(4).should == 0.75
+    Hotwater.normalized_levenshtein_distance("aaaaa", "aaaab").round(4).should == 0.8
+    Hotwater.normalized_levenshtein_distance("aaaaaa", "aaaaab").round(4).should == 0.8333
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hotwater
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
   prerelease: 
 platform: ruby
 authors:
@@ -75,8 +75,8 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
-description: Ruby & JRuby gem with fast string edit distance C implementation using
-  FFI bindings
+description: Ruby & JRuby gem with fast string edit distance algorithms C implementations
+  with FFI bindings
 email:
 - colin.surprenant@gmail.com
 executables: []
@@ -85,6 +85,8 @@ extensions:
 extra_rdoc_files: []
 files:
 - .gitignore
+- .travis.yml
+- CHANGELOG.md
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -120,7 +122,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -289401610859280349
+      hash: 3182707895951543481
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -129,7 +131,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -289401610859280349
+      hash: 3182707895951543481
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.23