ruby_sscanf 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9b3aff8ecf681b1e92152004c653cfdc2925206d
-  data.tar.gz: e17f0677bae7aa9fa6eefb4307bab0f37f1490d2
+  metadata.gz: ec28a950c28b1a0af3450694cb4c79bcee8847c1
+  data.tar.gz: 1f37bacdef6e1e8b04b34614f50e925c771e49d8
 SHA512:
-  metadata.gz: d7fc559a57dfdf39e518d42c9fed379003c775e6faf10ddcc0dffeaebd308a3e7d27b6bc4b3dcd7550cba3b4776d9c7d971c576137b5de58efbb278b324bfa86
-  data.tar.gz: 018dbf925c84f151a2186db83f99e2056c7f14043009fc3d19f5b3d4e4241b5c6dfeb266c5332a5ff7b0371aab9051f18fed27da4ea128a086caeb5292648e43
+  metadata.gz: 826961429f3d5ada3a4e2b4a21313d4187abe41e2c2c0313c8684b3755e71a615df2550381dd996df38acb3887db909ce1dd7bfca125d8c96c7dd55d14f73463
+  data.tar.gz: 3193a380491b336751702198518cc956273234101b04acce068307c82900e410dfdcb126931bb951caa681fc4d60097b9383f881e9ecfbe7e41c0031152ecb6b

data/README.md

@@ -32,23 +32,30 @@ format string is a description of that format. The output of the sscanf method
 is an array of data extracted from the input string.
 
 The format string consists of literal string components and format specifiers.
+During execution of the sscanf method, each element in the format string is
+used to find the corresponding data in the input string, optionally placing
+the extracted data in the aforementioned output array. If a format element
+cannot be matched to input data, processing stops at that point. Otherwise
+processing continues until all the format elements are done.
 
 Literal string components match themselves in the input string. If the literal
-has a trailing space, then this matches zero or more spaces. The special
-sequence '%%' matches one '%'.
+has a trailing space, then this matches zero or more spaces.
+The special sequence '%%' matches one '%' in the input string.
 
 The layout of a format specifier is:
 
     %[skip_flag][width]format
 
 * The % sign is the lead-in character.
-* The optional skip flag, the * causes any data extracted to be ignored.
-* The width field is an integer field that determines the amount of text to be
+* The optional skip flag, the *, causes any data extracted to be ignored.
+* The width field is an integer that determines the amount of text to be
 parsed.
 * The format field determines the type of data being parsed.
 
 The supported format field values are:
 <br>
+* a,e,f,g,A,E,F,G - Scan for an (optionally signed) floating point or
+scientific notation number.
 * b - Scan for an (optionally signed) binary number with an optional
 leading '0b' or '0B'.
 * c - Grab the next character. If a positive width is specified, grab width
@@ -56,7 +63,6 @@ characters. For a negative width, grab characters to the position from the
 end of the input. For example a width of -1 will grab all of the remaining
 input data.
 * d - Scan for an (optionally signed) decimal number.
-* f - Scan for an (optionally signed) floating point number.
 * i - Scan for an (optionally signed) integer. If the number begins with '0x'
 or '0X', process hexadecimal; with '0b' or '0B', process binary, if '0', '0o',
 or '0O', process octal, else process decimal.
@@ -70,7 +76,7 @@ or "...".
 [+-]?decimal/decimal[r]?
 * s - Scan for a space terminated string.
 * u - Scan for a decimal number.
-* x - Scan for an (optionally signed) hexadecimal number with an optional
+* x,X - Scan for an (optionally signed) hexadecimal number with an optional
 leading '0x' or '0X'.
 * [chars] - Scan for a contiguous string of characters in the set [chars].
 * [^chars] - Scan for a contiguous string of characters not in the set [^chars]
@@ -78,56 +84,80 @@ leading '0x' or '0X'.
 ## Examples
 Here are a few exmaples of the sscanf method in action.
 
+```ruby
 "12 34 -56".sscanf "%d %2d %4d"
-<br>returns   [12, 34, -56]
+returns   [12, 34, -56]
 
 "255 0b11111111 0377 0xFF 0 ".sscanf "%i %i %i %i %i"
-<br>returns   [255, 255, 255, 255, 0]
+returns   [255, 255, 255, 255, 0]
 
 "7 10 377".sscanf "%o %o %o"
-<br>returns   [7, 8, 255]
+returns   [7, 8, 255]
 
 "10 10011 11110000".sscanf "%b %b %b"
-<br>returns   [2, 19, 240]
+returns   [2, 19, 240]
 
 "0 F FF FFF FFFF".sscanf "%x %x %x %x %x"
-<br>returns   [0, 15, 255, 4095, 65535]
+returns   [0, 15, 255, 4095, 65535]
 
 "Hello Silly World".sscanf "%s %*s %s"
-<br>returns   ["Hello", "World"]
+returns   ["Hello", "World"]
 
 "Hello Silly World".sscanf "%5c %*5c %5c"
-<br>returns   ["Hello", "World"]
+returns   ["Hello", "World"]
 
 "42 The secret is X".sscanf "%i %-1c"
-<br>returns   [42, "The secret is X"]
+returns   [42, "The secret is X"]
 
 "42 The secret is X".sscanf "%i %-2c%c"
-<br>returns   [42, "The secret is ", "X"]
+returns   [42, "The secret is ", "X"]
 
 "42 The secret is X".sscanf "%i %*-2c%c"
-<br>returns   [42,  "X"]
+returns   [42,  "X"]
 
 "9.99 1.234e56 -1e100".sscanf "%f %f %f"
-<br>returns   [9.99, 1.234e56, -1e100]
+returns   [9.99, 1.234e56, -1e100]
 
 "85% 75%".sscanf "%f%% %f%%"
-<br>returns   [85, 75]
+returns   [85, 75]
 
 "12 34 -56".sscanf "%u %u %u"
-<br>returns   [12, 34]
+returns   [12, 34]
 
 "1/2 3/4r -5/6".sscanf "%r %r %r"
-<br>returns   ['1/2'.to_r, '3/4'.to_r, '-5/6'.to_r]
+returns   ['1/2'.to_r, '3/4'.to_r, '-5/6'.to_r]
 
 "1+2i 3+4j -5e10-6.2i".sscanf "%j %j %j"
-<br>returns   [Complex('1+2i'), Complex('3+4j'), Complex('-5e10-6.2i')]
+returns   [Complex('1+2i'), Complex('3+4j'), Complex('-5e10-6.2i')]
 
 "'quote' 'silly' \"un quote\" 'a \\''  ".sscanf "%q %*q %q %q"
-<br>returns   ["quote", "un quote", "a '"]
+returns   ["quote", "un quote", "a '"]
 
 "a b c".sscanf "%[a] %[b] %[c]"
-<br>returns   ["a", "b", "c"]
+returns   ["a", "b", "c"]
+```
+
+## Benchmarks
+
+I ran a test just to make sure that ruby_sscanf was not terribly
+under-performant when compared to the ruby standard library version. I was
+please to see that in fact ruby_sscanf was faster. Here are the results:
+
+    Calculating -------------------------------------
+    Scan strings with ruby_sscanf
+                             1.520k i/100ms
+    Scan strings with scanf
+                           308.000  i/100ms
+    -------------------------------------------------
+    Scan strings with ruby_sscanf
+                             15.844k (± 5.2%) i/s -     79.040k
+    Scan strings with scanf
+                              3.127k (± 4.2%) i/s -     15.708k
+
+    Comparison:
+    Scan strings with ruby_sscanf:    15843.8 i/s
+    Scan strings with scanf:     3126.7 i/s - 5.07x slower
+
 
 ## Contributing
 

data/bench/bench.rb

@@ -0,0 +1,18 @@
+require "benchmark/ips"
+require 'scanf'
+require 'ruby_sscanf'
+
+def use_scanf
+  '12 34 56 89 1.234 1.0e10'.scanf('%d %d %d %d %f %f')
+end
+
+def use_ruby_sscanf
+  '12 34 56 89 1.234 1.0e10'.sscanf('%d %d %d %d %f %f')
+end
+
+Benchmark.ips do |x|
+  x.report("Scan strings with ruby_sscanf") { use_ruby_sscanf }
+  x.report("Scan strings with scanf")       { use_scanf }
+  x.compare!
+end
+

data/lib/ruby_sscanf.rb

@@ -1,61 +1,118 @@
-
 require 'format_engine'
 require_relative 'ruby_sscanf/version'
 
+#The String class is monkey patched to support sscanf.
 class String
 
-  DECIMAL  = /[+-]?\d+/
-  HEX      = /[+-]?(0[xX])?\h+/
-  OCTAL    = /[+-]?(0[oO])?[0-7]+/
-  BINARY   = /[+-]?(0[bB])?[01]+/
-  INTEGER  = /[+-]?((0[xX]\h+)|(0[bB][01]+)|(0[oO]?[0-7]*)|([1-9]\d*))/
-  FLOAT    = /[+-]?\d+(\.\d+)?([eE][+-]?\d+)?/
-  RATIONAL = /[+-]?\d+\/\d+(r)?/
-  COMPLEX  = %r{(?<num> \d+(\.\d+)?([eE][+-]?\d+)?){0}
-                [+-]?\g<num>[+-]\g<num>[ij]
-               }x
-  QUOTED   = /("([^\\"]|\\.)*")|('([^\\']|\\.)*')/
-
-  #Get the parsing engine.
+  #A regular expression for decimal integers.
+  RSF_DECIMAL  = /[+-]?\d+/
+
+  #A regular expression for unsigned decimal integers.
+  RSF_UNSIGNED = /[+]?\d+/
+
+  #A regular expression for hexadecimal integers.
+  RSF_HEX      = /[+-]?(0[xX])?\h+/
+  RSF_HEX_PARSE = lambda {parse(RSF_HEX) ? dst << found.to_i(16) : :break}
+  RSF_HEX_SKIP  = lambda {parse(RSF_HEX) || :break}
+
+  #A regular expression for octal integers.
+  RSF_OCTAL    = /[+-]?(0[oO])?[0-7]+/
+
+  #A regular expression for binary integers.
+  RSF_BINARY   = /[+-]?(0[bB])?[01]+/
+
+  #A regular expression for flexible base integers.
+  RSF_INTEGER  = /[+-]?((0[xX]\h+)|(0[bB][01]+)|(0[oO]?[0-7]*)|([1-9]\d*))/
+
+  #A regular expression for floating point and scientific notation numbers.
+  RSF_FLOAT    = /[+-]?\d+(\.\d+)?([eE][+-]?\d+)?/
+  RSF_FLOAT_PARSE = lambda {parse(RSF_FLOAT) ? dst << found.to_f : :break}
+  RSF_FLOAT_SKIP  = lambda {parse(RSF_FLOAT) || :break}
+
+  #A regular expression for rational numbers.
+  RSF_RATIONAL = /[+-]?\d+\/\d+(r)?/
+
+  #A regular expression for complex numbers.
+  RSF_COMPLEX  = %r{(?<num> \d+(\.\d+)?([eE][+-]?\d+)?){0}
+                    [+-]?\g<num>[+-]\g<num>[ij]
+                   }x
+
+  #A regular expression for a string.
+  RSF_STRING   = /\S+/
+
+  #A regular expression for quoted strings.
+  RSF_QUOTED   = /("([^\\"]|\\.)*")|('([^\\']|\\.)*')/
+
+  #Get the parsing engine. This is cached on a per-thread basis. That is to
+  #say, each thread gets its own \FormatEngine::Engine instance.
   def self.get_engine
     Thread.current[:ruby_sscanf_engine] ||= FormatEngine::Engine.new(
-      "%b"  => lambda {parse(BINARY) ? dst << found.to_i(2) : :break},
-      "%*b" => lambda {parse(BINARY) || :break},
+      "%a"  => RSF_FLOAT_PARSE,
+      "%*a" => RSF_FLOAT_SKIP,
+
+      "%A"  => RSF_FLOAT_PARSE,
+      "%*A" => RSF_FLOAT_SKIP,
+
+      "%b"  => lambda {parse(RSF_BINARY) ? dst << found.to_i(2) : :break},
+      "%*b" => lambda {parse(RSF_BINARY) || :break},
 
       "%c"  => lambda {dst << grab},
       "%*c" => lambda {grab},
 
-      "%d"  => lambda {parse(DECIMAL) ? dst << found.to_i : :break},
-      "%*d" => lambda {parse(DECIMAL) || :break},
+      "%d"  => lambda {parse(RSF_DECIMAL) ? dst << found.to_i : :break},
+      "%*d" => lambda {parse(RSF_DECIMAL) || :break},
+
+      "%e"  => RSF_FLOAT_PARSE,
+      "%*e" => RSF_FLOAT_SKIP,
+
+      "%E"  => RSF_FLOAT_PARSE,
+      "%*E" => RSF_FLOAT_SKIP,
 
-      "%f"  => lambda {parse(FLOAT) ? dst << found.to_f : :break},
-      "%*f" => lambda {parse(FLOAT) || :break},
+      "%f"  => RSF_FLOAT_PARSE,
+      "%*f" => RSF_FLOAT_SKIP,
 
-      "%i"  => lambda {parse(INTEGER) ? dst << found.to_i(0) : :break},
-      "%*i" => lambda {parse(INTEGER) || :break},
+      "%F"  => RSF_FLOAT_PARSE,
+      "%*F" => RSF_FLOAT_SKIP,
 
-      "%j"  => lambda {parse(COMPLEX) ? dst << Complex(found) : :break},
-      "%*j" => lambda {parse(COMPLEX) || :break},
+      "%g"  => RSF_FLOAT_PARSE,
+      "%*g" => RSF_FLOAT_SKIP,
 
-      "%o"  => lambda {parse(OCTAL) ? dst << found.to_i(8) : :break},
-      "%*o" => lambda {parse(OCTAL) || :break},
+      "%G"  => RSF_FLOAT_PARSE,
+      "%*G" => RSF_FLOAT_SKIP,
+
+      "%i"  => lambda {parse(RSF_INTEGER) ? dst << found.to_i(0) : :break},
+      "%*i" => lambda {parse(RSF_INTEGER) || :break},
+
+      "%j"  => lambda {parse(RSF_COMPLEX) ? dst << Complex(found) : :break},
+      "%*j" => lambda {parse(RSF_COMPLEX) || :break},
+
+      "%o"  => lambda {parse(RSF_OCTAL) ? dst << found.to_i(8) : :break},
+      "%*o" => lambda {parse(RSF_OCTAL) || :break},
 
       "%q"  => lambda do
-        parse(QUOTED) ? dst << found[1..-2].gsub(/\\./) {|seq| seq[-1]} : :break
+        if parse(RSF_QUOTED)
+          dst << found[1..-2].gsub(/\\./) {|seq| seq[-1]}
+        else
+          :break
+        end
       end,
-      "%*q" => lambda {parse(QUOTED) || :break},
 
-      "%r"  => lambda {parse(RATIONAL) ? dst << found.to_r : :break},
-      "%*r" => lambda {parse(RATIONAL) || :break},
+      "%*q" => lambda {parse(RSF_QUOTED) || :break},
+
+      "%r"  => lambda {parse(RSF_RATIONAL) ? dst << found.to_r : :break},
+      "%*r" => lambda {parse(RSF_RATIONAL) || :break},
+
+      "%s"  => lambda {parse(RSF_STRING) ? dst << found : :break},
+      "%*s" => lambda {parse(RSF_STRING) || :break},
 
-      "%s"  => lambda {parse(/\S+/) ? dst << found : :break},
-      "%*s" => lambda {parse(/\S+/) || :break},
+      "%u"  => lambda {parse(RSF_UNSIGNED) ? dst << found.to_i : :break},
+      "%*u" => lambda {parse(RSF_UNSIGNED) || :break},
 
-      "%u"  => lambda {parse(/\d+/) ? dst << found.to_i : :break},
-      "%*u" => lambda {parse(/\d+/) || :break},
+      "%x"  => RSF_HEX_PARSE,
+      "%*x" => RSF_HEX_SKIP,
 
-      "%x"  => lambda {parse(HEX) ? dst << found.to_i(16) : :break},
-      "%*x" => lambda {parse(HEX) || :break},
+      "%X"  => RSF_HEX_PARSE,
+      "%*X" => RSF_HEX_SKIP,
 
       "%["  => lambda {parse(fmt.regex) ? dst << found : :break},
       "%*[" => lambda {parse(fmt.regex) || :break})

data/lib/ruby_sscanf/version.rb

@@ -1,3 +1,5 @@
+#The ruby_sscanf doesn't really live here.
 module RubySscanf
-  VERSION = "0.1.1"
+  #The gem's version.
+  VERSION = "0.1.2"
 end

data/tests/scan_tests.rb

@@ -26,6 +26,9 @@ class ScanTester < Minitest::Test
     result = "0 F FF FFF FFFF".sscanf "%x %x %x %x %x"
     assert_equal([0, 15, 255, 4095, 65535] , result)
 
+    result = "0 F FF FFF FFFF".sscanf "%X %*x %*X %x %X"
+    assert_equal([0, 4095, 65535] , result)
+
     result = "Hello Silly World".sscanf "%s %*s %s"
     assert_equal(["Hello", "World"] , result)
 
@@ -41,9 +44,30 @@ class ScanTester < Minitest::Test
     result = "42 The secret is X".sscanf "%i %*-2c%c"
     assert_equal([42,  "X"] , result)
 
+    result = "9.99 1.234e56 -1e100".sscanf "%a %e %g"
+    assert_equal([9.99, 1.234e56, -1e100] , result)
+
+    result = "9.99 1.234e56 -1e100".sscanf "%*a %e %g"
+    assert_equal([1.234e56, -1e100] , result)
+
+    result = "9.99 1.234e56 -1e100".sscanf "%a %*e %g"
+    assert_equal([9.99, -1e100] , result)
+
+    result = "9.99 1.234e56 -1e100".sscanf "%a %e %*g"
+    assert_equal([9.99, 1.234e56] , result)
+
+    result = "9.99 1.234e56 -1e100".sscanf "%A %E %G"
+    assert_equal([9.99, 1.234e56, -1e100] , result)
+
+    result = "9.99 1.234e56 -1e100".sscanf "%A %*E %G"
+    assert_equal([9.99, -1e100] , result)
+
     result = "9.99 1.234e56 -1e100".sscanf "%f %f %f"
     assert_equal([9.99, 1.234e56, -1e100] , result)
 
+    result = "9.99 1.234e56 -1e100".sscanf "%F %*F %F"
+    assert_equal([9.99, -1e100] , result)
+
     result = "85% 75%".sscanf "%f%% %f%%"
     assert_equal([85, 75] , result)
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby_sscanf
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Peter Camilleri
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-02-06 00:00:00.000000000 Z
+date: 2016-02-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: format_engine
@@ -106,6 +106,7 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- bench/bench.rb
 - lib/ruby_sscanf.rb
 - lib/ruby_sscanf/version.rb
 - ruby_sscanf.gemspec
@@ -135,3 +136,4 @@ signing_key:
 specification_version: 4
 summary: A string parser.
 test_files: []
+has_rdoc: