gstring 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 0accef1dd11956fb3f9d63591b265b3a180aeb87
+  data.tar.gz: 72240f555419b95a7eb134aaf945a46350a6e045
+SHA512:
+  metadata.gz: df82a5b5dd451ecbeef30eeee3756ea52723252cdad4aa13373ceb47568c37b3793fc8624ddf584910cea06a83c1b5af893a10c433ca8c27e9a0d890b7f997f3
+  data.tar.gz: 2b3af8e31c06de166105fd82466b52915542ca53cfaa2e01c4d7f6fdf17163006efefc7d12888784edec66a6edd5e2704c4e18f4408b3984a43eee9ceb3b39bd

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in gstring.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2015 Bryan Colvin
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,26 @@
+# gstring
+
+##Purpose:
+The gstring gem adds new functionality to the base `String` class.
+Some existing methods are extended to utilize Set instances (gem: setfu)
+Other methods solve some nasty string manipulation problems with ease.
+Future releases will attempt to add more functionality with the goal
+of making gstring the standard String extension gem.
+
+##Documentation:   
+See: http://bdlsys.com/gems/gstring.html
+
+## Installation
+
+Add these lines to your application's Gemfile:
+    gem 'setfu'
+    gem 'gstring'
+
+And then execute:
+    $ bundle
+
+Or install it yourself as:
+    $ gem install gstring
+
+## Contributing
+One day I will put this on github, but for now, enjoy!

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/gstring.gemspec

@@ -0,0 +1,32 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'gstring/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "gstring"
+  spec.version       = Gstring::VERSION
+  spec.authors       = ["Bryan Colvin"]
+  spec.email         = ["bryan@bdlsys.com"]
+  spec.description   = %q{
+Adds 60+ new methods to the base String class. Most help with parsing, others are more of a hodgepodge of nifty utilities.
+Utilities include: engineering_notation, cryptogram generator, password generator, sort by embedded numbers, etc. 
+Some represent some of the better ideas from other string related gems.
+Most are from 20 years of multiple language string extensions that were used in some project.}
+  spec.summary       = %q{Adds 60+ new methods String class.}
+  spec.homepage      = "http://bdlsys.com/gems/gstring.html"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+  spec.required_ruby_version = '>= 1.9.1'
+  
+  spec.add_runtime_dependency 'setfu', '>= 1.2.1'
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake", ">= 10.1.0"
+  spec.add_development_dependency 'rspec', ">= 3.3.0"
+  spec.add_development_dependency 'byebug', ">= 5.0.0"
+end

data/lib/gstring.rb

@@ -0,0 +1,1403 @@
+## Copyright 2015 Bryan Colvin ... public domain so long as my name is present ##
+#
+#  This gem collects various extensions from competing string gems, and my personal collection.
+#  Expect many future releases as new ideas/needs come to light
+#
+##
+
+require "gstring/version"
+require "setfu"
+
+## ACTION ITEMS ##
+# 1: replace options hash with array ... use *options so you can list them one-by-one
+# 2: index, rindex ... add array of strings ... refactor parse to use new index
+
+## FEATURES TODO NEXT REVISION ##
+# 1: to_morse  (maybe ... limited appeal my guess)
+# 2: encryption?  (maybe a separate gem, or include a wrapper from that gem)
+# 3: format number to engineering notation  ... 15530.to_eng  => 1515.53e3
+
+class String
+  @@gs_bracketing_pairs = 
+  { 
+    '[' => ']',
+    '(' => ')',
+    '{' => '}',
+    '<' => '>'
+  }
+  SI_UNIT_PREFIXES = {1=>'da', 2=>'h', 3=>'k', 6=>'M', 9=>'G', 12=>'T', 15=>'P', 18=>'E', 21=>'Z', 24=>'Y', 27=>'kY', 30=>'MY', 33=>'GY', 36=>'TY', 39=>'PY', 42=>'EY', 45=>'ZY', 48=>'YY',
+                      -1=>'d',-2=>'c', -3=>'m', -6=>'µ',-9=>'n',-12=>'p',-15=>'f',-18=>'a',-21=>'z',-24=>'y',-27=>'my',-30=>'µy', -33=>'ny', -36=>'py', -39=>'fy', -42=>'ay', -45=>'zy', -48=>'yy'}
+  RGX_FLOAT = /\A[\+\-]?(0|[1-9]\d*)(([eE][\+\-]?\d+)|(\.\d+((e)?[\+\-]?\d+)?))/
+  STD_ESCAPE_SET_RUBY = [0..31,'"',"'","\\","\;","\#"].to_set
+  STD_ESCAPE_HASH = {7=>"\\a", 8=>"\\b", 12=>"\\f", 10=>"\\n", 13=>"\\r", 9=>"\\t", 11=>"\\v"}
+  SET_PARSE_CHARS = Set.new.add_parse_chars!
+  SET_SPLIT_CHARS = SET_PARSE_CHARS | "_#`\""
+  SET_UPPERS = Set.uppercase_chars
+  SET_LOWERS = Set.lowercase_chars
+  SET_CHARS  = Set.letter_chars
+  SET_INT_CHARS = Set.digit_chars
+  GS_SENTENCE_TERM = '?!.'.to_set
+  GS_TITLE_EXCEPTIONS = 
+  {
+    "a"    =>true,
+    "an"   =>true,
+    "and"  =>true,
+    "as"   =>true,
+    "at"   =>true,
+    "but"  =>true,
+    "by"   =>true,
+    "for"  =>true,
+    "from" =>true,
+    "in"   =>true,
+    "nor"  =>true,
+    "of"   =>true,
+    "on"   =>true,
+    "or"   =>true,
+    "the"  =>true,
+    "to"   =>true,
+    "up"   =>true
+  }
+  
+  def self.reset_bracket_pairs
+    @@gs_bracketing_pairs = 
+    { 
+      '[' => ']',
+      '(' => ')',
+      '{' => '}',
+      '<' => '>'
+    }
+  end
+  
+  def self.undefine_bracket_pair(str)
+    @@gs_bracketing_pairs.delete(str.first)
+  end
+
+  def self.define_bracket_pair(str)
+    @@gs_bracketing_pairs[str.first] = str.last
+  end
+  
+  #ary.sort &String::inside_int_cmp
+  def self.inside_int_cmp(mode=true)
+    return lambda do |a,b|
+      a,b = (mode) ? [a.to_s, b.to_s] : [b.to_s, a.to_s]
+      if(a==b)
+        0
+      else
+        ta = a.dup
+        tb = b.dup
+        rgx = /\d+/
+        if (ta.find(rgx).nil? || tb.find(rgx).nil?)
+          a <=> b # standard compare
+        else  # int inside one or both
+          rtn=0
+          loop do
+            if(ta==tb)
+              rtn=0
+              break
+            end
+            if(ta.empty? || tb.empty?)
+              rtn = ta <=> tb
+              break
+            end
+            la = ta.parse(rgx, :no_skip, :no_strip)
+            lb = tb.parse(rgx, :no_skip, :no_strip)
+            if(la != lb)
+              rtn = la <=> lb
+              break
+            end
+            if(ta.parsed != tb.parsed)
+              rtn = ta.parsed.to_i <=> tb.parsed.to_i
+              break
+            end
+          end #loop
+          rtn
+        end # if    
+      end # if  
+    end # lambda
+  end  #self.inside_int_cmp
+  
+  def self.chr_uni_esc(num)
+    num = num.to_i
+    return nil if num < 0
+    if num < 256
+      rtn = "\\x" + num.to_s(16).padto(2,'0',:left)
+    elsif num < 0x10000
+      rtn = "\\u" + num.to_s(16).padto(4,'0',:left)
+    elsif num < 0x1000000
+      rtn = "\\u" + num.to_s(16).padto(6,'0',:left)
+    else
+      rtn = "\\u" + num.to_s(16).padto(8,'0',:left)
+    end
+  end
+
+  def upcase?
+    set = self.to_set
+    return false if String::SET_LOWERS ** set    # may not have any lower
+    return nil unless String::SET_UPPERS ** set  # must have at least one upper
+    return true
+  end
+  
+  def downcase?
+    set = self.to_set
+    return false if String::SET_UPPERS ** set    # may not have any lower
+    return nil unless String::SET_LOWERS ** set  # must have at least one lower
+    return true
+  end
+  
+  def mixedcase?
+    set = self.to_set
+    return nil unless set ** (String::SET_LOWERS | String::SET_UPPERS) # must have a letter
+    return (set ** String::SET_LOWERS) && (set ** String::SET_UPPERS) 
+  end
+    
+  # non-alpha chars must match too  
+  def case_match(other)  # true if string same size with same case at all positions
+    return false if (length != other.length)
+    length.times do |idx|
+      if (self[idx].upcase?)
+        return false unless other[idx].upcase?
+      elsif (self[idx].downcase?)
+        return false unless other[idx].downcase?
+      else  # both must be letters at the position
+        return false if self[idx] != other[idx]
+      end
+    end
+    return true
+  end
+
+  def swapchar(pos, ch, *modes)
+    modes = modes.first if modes.first.class==Array
+    rtn = self[pos]
+    return nil if rtn.nil?
+    if ch.empty?
+      return nil unless modes.include? :empty_ok
+    end
+    unless ch.empty?
+      ch = ch.first unless modes.include? :substring
+    end    
+    if modes.include? :casehold
+      if rtn.upcase?
+        self[pos]=ch.upcase
+      elsif rtn.downcase?
+        self[pos]=ch.downcase
+      else
+        self[pos]=ch.first
+      end   
+    else
+      self[pos]=ch  # standard mode
+    end
+    rtn
+  end
+  
+  def find_all(obj, *modes)  # returns an array of all positions of obj in self
+    pos = 0
+    ary = []
+    loop do
+      pos = self.index(obj, pos, modes)
+      break if pos.nil?
+      ary.push pos
+      pos +=1       
+    end
+    return ary
+  end
+  
+  def cryptogram(dat=nil)  # nil==> encode, string==>test for match
+    if (dat.nil?)
+      rtn = dup
+      set = Set.lowercase_chars
+      off_limits = []
+      skey = nil
+      ary = (self.downcase.to_set & String::SET_LOWERS).to_a(false).shuffle
+      loop do
+        break if ary.empty?
+        skey = ary.pop
+        hits = find_all(skey,:ignore) - off_limits
+        off_limits = (off_limits | hits).sort
+        # edge case, set only has 1 element in it
+        rpw = (set.count==1) ? set.to_s : (set - skey).rand(1,:string)
+        set -= rpw #can only use an element once
+    	hits.each do |pos|
+    	  rtn.swapchar(pos, rpw, :casehold)
+    	end
+      end
+      return rtn      
+    elsif (dat.class==String)
+      return false if self.length != dat.length
+      s1 = self.downcase.to_set & Set.lowercase_chars
+      s2 = dat.downcase.to_set & Set.lowercase_chars
+      return false if s1.count != s2.count
+      ary1 = self.downcase.find_all(s1)
+      ary2 = dat.downcase.find_all(s2)
+      return false if ary1 != ary2
+      return false unless case_match(dat)
+      length.times do |idx|  # ::TODO:: find faster way ...
+        ary1 = self.find_all(self[idx],:ignore)
+        ary2 = dat.find_all(dat[idx],:ignore)
+        return false if ary1 != ary2
+      end
+      return true
+    else
+      return nil
+    end
+    nil
+  end
+  
+  def cross_match(pat)
+    s_ptr=0
+    p_ptr=0
+    ch = ''
+    return nil unless pat.class==String
+    return false if empty?
+    return false if pat.empty?
+    loop do
+      return true  if s_ptr >= self.length
+      return false if p_ptr >= pat.length
+      if ch != ''
+        if ch==self[s_ptr]
+          ch=""
+          s_ptr +=1
+          p_ptr +=1
+          if s_ptr >= self.length
+            return false if pat[p_ptr]=='+'
+          end
+        else
+          s_ptr +=1
+          return false if s_ptr >= self.length # ran out before match
+        end
+      elsif (pat[p_ptr]=='_')
+        p_ptr+=1
+        s_ptr+=1        
+      elsif (pat[p_ptr]=='+')
+        s_ptr+=1  # skip next letter
+        p_ptr+=1
+        ch = pat[p_ptr]
+        return true if (ch.nil? || ch=='')  #end of the line
+      elsif (pat[p_ptr]=='*')
+        p_ptr+=1
+        ch = pat[p_ptr]
+        return true if (ch.nil? || ch=='') #end of the line
+      elsif (pat[p_ptr]=='`')
+        p_ptr+=1
+        return false unless pat[p_ptr]==self[s_ptr]
+        p_ptr+=1
+        s_ptr+=1                
+      else # compare chars
+        return false unless pat[p_ptr]==self[s_ptr]
+        p_ptr+=1
+        s_ptr+=1        
+      end
+    end
+    return true
+  end
+  
+  def condense!
+    strip!
+    str = ""
+    sp = false
+    each_char do |ch|
+      if (ch <= ' ')
+        sp = true
+      else
+        str += sp ? ' ' + ch : ch
+        sp = false
+      end  
+    end
+    replace str
+    self
+  end
+  
+  def condense
+    dup.condense!
+  end
+  
+  def sort
+    self.split('').sort.join('')
+  end
+
+  def sort!
+    replace self.split('').sort.join('')
+  end
+  
+  def histogram
+    hash = {}
+    self.split('').sort.each do |ch|
+      hash[ch] = hash[ch].nil? ? 1 : 1 + hash[ch]
+    end
+    return hash
+  end
+  
+  def duplicates?
+    set = self.to_set
+    return false if set.count == length
+    return true    
+  end
+  
+  # ... add new meaning to what would have raised an error ...
+  # now means case insensitive compare
+  alias_method :old_string_rgx_cmp, :=~
+  def =~(str)
+    return old_string_rgx_cmp(str) unless str.class==String
+    self.downcase == str.downcase
+  end
+
+  # generator does not need an instance  
+  def self.random_password(chars=8, special="_-#!~@$%^*+=?:")
+    raise "password must be at least 8 characters" if chars < 8
+    low  = Set.lowercase_chars
+    high = Set.uppercase_chars
+    digits = Set.digit_chars
+    special = special.to_set rescue Set.new 
+    all = low | high | digits | special
+    a,b = low.rand(2,:array_chars)
+    c,d = high.rand(2, :array_chars)
+    e   = digits.rand(1, :array_chars)
+    f   = special.rand(1, :array_chars)
+    pswd = [a,b,c,d,e]
+    pswd.push f unless (f.nil? || f.empty?)
+    filler = all.rand(chars - pswd.length, :array_chars)
+    filler.each do |ch|
+      pswd.push ch
+    end
+    pswd.shuffle!
+    return pswd.join ''
+  end
+  
+  def remove(prm)
+    set = prm.to_set
+    ns = ""
+    self.each_char do |ch|
+      ns += ch unless set.include? ch
+    end
+    return ns
+  end
+
+  def remove!(prm) # remove all characters
+    replace remove(prm)
+  end 
+
+
+  def extract!(prm=1, fill_hole="")
+    return "" if empty?
+    if prm.kind_of? Integer  # extract fron-end of string
+      return "" if prm < 1
+      prm =  prm > length ? length : prm
+      rtn = self[0..(prm-1)]
+      # replace( fill_hole + self[prm..-1] )  # WRONG!   ... we only want the same number of fill
+      replace( fill_hole[0..(prm-1)] + self[prm..-1] )
+      return rtn
+    elsif prm.class == Range
+      start  = prm.first < 0 ? self.length + prm.first : prm.first
+      finish = prm.last < 0 ? self.length + prm.last : prm.last
+      if (start <= finish) # normal forward order
+        return "" if start >= length
+        finish = finish >= length ? length-1 : finish
+        return extract!(finish+1, fill_hole) if start==0  # was extract without the '!'
+        rtn = self[start..finish]
+        replace(self[0..(start-1)] + fill_hole + self[(finish+1)..-1])
+        return rtn
+      else # reverse order
+        return "" if finish >= length
+        start = start >= length ? length - 1 : start
+        rtn = self[finish..start].reverse
+        if(finish==0)
+          replace(fill_hole + self[(start+1)..-1])
+        else
+          replace(self[0..(finish-1)] + fill_hole + self[(start+1)..-1])
+        end
+        return rtn
+      end
+    elsif prm.class == Array
+      rtn = ""
+      # first count number of substitutions
+      cnt = 0
+      prm.each do |item|
+        if item.kind_of? Integer
+          cnt += 1
+        else
+          cnt += item.count
+        end
+      end
+      filler = fill_hole.padto(cnt, "\000", :right, :no_trunc) # use null as place holder
+      prm.each do |item|
+        if item.kind_of? Integer
+          pos = item < 0 ? 0 : item
+          if pos < length
+            rtn += self[pos]
+            self[pos]=filler.first!          
+          end  # ignore if out of range
+        else # use recursion
+          str = self.extract!(item, filler)
+          rtn += str
+          filler.extract! str.length  # remove and discard
+        end  
+      end
+      remove! "\000"
+      return rtn 
+    else # convert to set
+      ary = (prm.to_set & (0..(self.length-1))).to_a  #ignore everything out of range 
+      fill=fill_hole.dup
+      rtn = ""
+      oft = 0
+      ary.each do |idx|
+        ch = fill.extract!
+        rtn += self[idx-oft]
+        self[idx-oft]=ch
+        oft+=1 if ch.empty?
+      end
+      return rtn
+    end
+    return ""
+  end
+  
+  def extract(prm)
+    return dup.extract!(prm, '')
+  end
+  
+  def enclose(pairs, escape=nil, set=String::STD_ESCAPE_SET_RUBY, hash=String::STD_ESCAPE_HASH)
+    return self if pairs.empty?
+    if escape.nil?
+      return pairs.first + self + pairs.last
+    else # look for pairs.first , and replace with {escape}{pairs.first}
+      str = pairs.first
+      self.each_char do |ch|
+        if set.include? ch
+          idx = (set & ch).to_a.first
+          if (ch ** (set-[0..31]))
+            #byebug
+            str += "\\" + ch
+          elsif hash.include? idx
+            #byebug
+            str += hash[idx]
+          else  # use hex format
+            str += String.chr_uni_esc(idx)
+          end
+        else
+          str += ch
+        end        
+      end
+      return str + pairs.last
+      #str = self.gsub(pairs.first) { escape + pairs.first }
+      #return pairs.first + str + pairs.last
+    end
+  end
+  
+  def enclose!(pairs, escape=nil)
+    replace enclose(pairs, escape)
+  end
+  
+  def unenclose(escape=nil) # unescape
+    return nil if length < 2
+    unless first==last
+      return nil unless last == @@gs_bracketing_pairs[first]
+    end
+    if @@gs_bracketing_pairs.include? first
+      return nil if first==last
+    end
+    str = self[1..(length-2)]
+    unless escape.nil?
+      str = str.gsub(escape) { '' }  # blind removal? ... may need to rethink this a tad
+    end
+    return str
+  end
+
+  def unenclose!(escape=nil)
+    str = unenclose(escape)
+    replace str unless str.nil?
+    str.nil? ? nil : self
+  end
+  
+  def indent
+    cnt = 0
+    each_char do |ch|
+      break if ch > ' '
+      cnt += 1
+    end
+    cnt
+  end
+
+  def indent!
+    rtn = indent
+    lstrip!
+    return rtn
+  end 
+  
+# ::todo::   Add flags  :rotate, :stick
+  
+  def padto(tar, *prms)
+    return self if length == tar
+    prms = prms.first if prms.first.kind_of? Array
+    with = ' '
+    flags = []
+    how = :left
+    prms.each do |prm|
+      if prm.kind_of? String
+        with=prm
+        next
+      end
+      case prm
+        when :no_trunc, :rotate, :stick, :space, :swing
+          flags.push prm
+        when :left, :right, :both
+          how = prm
+        else
+          raise "padto unknown parameter"
+      end
+    end
+    if length > tar
+      return self if flags.include? :no_trunc
+      return "" if tar<=0
+      return '…' if tar==1
+      return self[0..(tar-2)]+'…'
+    end
+    with = ' ' if with.empty?
+    rtn = ""
+    flags -= [:no_trunc]
+    flag = flags.empty? ? :stick : flags.first
+    with.access_mode(flag==:space ? :default : flag)
+    case how
+      when :right
+        rtn = self
+        (tar-length).times do |xx|        
+          rtn += with.next
+        end
+      when :both
+        lp = (tar-length) >> 1
+        rp = (tar-length) - lp
+        str = ""
+        (rp).times do |xx|
+          str += with.next
+        end
+        rtn = str[0..(lp-1)].reverse + self + str
+      else # :left
+        str = ""
+        (tar-length).times do |xx|
+          str += with.next
+        end
+        rtn += str.reverse + self
+    end
+    rtn
+  end
+
+  def padto!(tar, *flags)
+    replace padto(tar, flags)
+  end
+  
+  # negative len means position from right to left
+  # positive len means number of chars to capture
+  # exception if pos and len are both negative and pos > len
+  # ... then starting point is the |sum| from the right, and length
+  # ... and the ending point is also the |sum| ??? need more examples   
+  def php_substr(pos=0,len=nil)
+    return "" if len==0
+    len = len.nil? ? length : len
+    r_s = (pos >= 0) ? pos : pos + length
+    r_e = (len >= 0) ? r_s + len - 1 : len + length - 1
+    return self[(r_s)..(r_e)]
+  end
+  
+  def ignore_me
+    self
+  end
+  
+  def parse(search_key = String::SET_PARSE_CHARS, *options)
+    options = options.first if options.first.class==Array
+    meth = options.include?(:no_strip) ? :ignore_me : :strip
+    rtn=""
+    @found = nil
+    if(search_key.class==Set)
+      #skip over first char
+      idx = options.include?(:no_skip) ? 0 : 1
+      sk = options.include?(:ignore) ? search_key.add_opposing_case : search_key
+      sf = idx
+      self[sf...length].each_char do |ch|
+        if(sk.include? ch)
+          @found=ch
+          break
+        end
+        idx += 1
+      end 
+      unless @found.nil?
+        rtn = (idx==0) ? "" : self[0..(idx-1)].send(meth)
+        replace self[(idx+1)..-1].send(meth)
+        return rtn
+      end
+      rtn = clone
+      clear
+      return rtn
+    elsif (search_key.class == Regexp)
+      sf = options.include?(:no_skip) ? 0 : 1
+      pos = index(search_key,sf)
+      @found = pos.nil? ? nil : self.match(search_key)[0]
+      if pos.nil?
+        rtn = clone
+        clear
+        return rtn
+      else # found
+        rtn = pos.zero? ? "" : self[0..(pos-1)].send(meth)
+        replace self[(pos+@found.length)..length].send(meth)
+        return rtn
+      end
+    elsif (search_key.class == String)
+      #skip over first char unless option specifies :no_skip
+      sf = options.include?(:no_skip) ? 0 : 1
+      idx = index(search_key,sf,options)
+      if idx.nil?
+        rtn = clone
+        clear
+        return rtn
+      else
+        rtn = idx.zero? ? "" : self[0..(idx-1)].send(meth)
+        @found = self[idx..(idx+search_key.length-1)]
+        replace self[(idx+search_key.length)..length].send(meth)
+        return rtn
+      end
+    elsif (search_key.class == Array)
+      shortest = nil
+      best = nil
+      start = options.include?(:no_skip) ? 0 : 1
+      search_key.each_with_index do |val,idx|
+        pos = self.index(val,start,options)
+        unless pos.nil?
+          best = idx if best.nil?
+          shortest ||= pos
+          if (pos < shortest)
+            shortest = pos
+            best = idx
+          end
+        end
+      end
+      if shortest.nil?
+        rtn = clone
+        clear
+        return rtn
+      else
+        #opt = options.dup
+        #opt[:no_skip]=true
+        #return parse(search_key[best],opt)
+        return parse(search_key[best],options)
+      end        
+    else  # we are passed something that should have been converted to a set
+      return parse([search_key].to_set,options)
+    end
+  end
+  
+  ##                                              ##
+  #    Updates to existing index, rindex methods   #
+  #    now accepts search types of: Set, Array     #
+  ##                                              ##
+  
+  alias_method :old_string_index_method_4gstring, :index
+  alias_method :old_string_rindex_method_4gstring, :rindex
+
+  def index(search,from=0,*options)
+    while options.first.class==Array
+      options = options.first      
+    end
+    if (search.class==String)
+      return self.downcase.index(search.downcase,from) if (options.include? :ignore)
+      return old_string_index_method_4gstring(search,from)  
+    end
+    
+    if search.class==Array
+      best = nil
+      search.each_with_index do |item,idx|
+        pos = index(item,from,options)
+        unless pos.nil?
+          @best ||= idx
+          best ||= pos
+          if pos < best
+            best = pos 
+            @best = idx
+          end
+        end
+      end
+      return best  # parse uses this to know which item was found
+    end
+
+    # call this for unrecognized options
+    return old_string_index_method_4gstring(search,from) unless search.class == Set
+    if options.include? :ignore
+      return self.downcase.index(search.add_opposing_case,from)
+    end
+    if (from < 0)
+      from = length + from
+    end
+    from = 0 if from < 0
+    ((from)...(length)).each do |ptr|
+      return ptr if search.include? self[ptr]
+    end
+    return nil
+  end
+
+  def rindex(search,from=-1,*options)
+    options = options.first if options.first.class==Array
+    if (search.class==String)
+      return self.downcase.rindex(search.downcase,from) if (options.include? :ignore)
+      return old_string_rindex_method_4gstring(search,from)  
+    end
+    
+    if search.class==Array
+      best = nil
+      search.each_with_index do |item,idx|
+        pos = rindex(item,from,options)
+        unless pos.nil?
+          @best ||= idx
+          best ||= pos
+          if pos > best
+            best = pos 
+            @best = idx
+          end
+        end
+      end
+      return best  # parse uses this to know which item was found
+    end
+    
+    # call this for unrecognized options
+    return old_string_rindex_method_4gstring(search,from) unless search.class == Set
+    if options.include? :ignore
+      return self.downcase.rindex(search.add_opposing_case,from)
+    end
+    idx = (from < 0) ? length + from : from
+    return nil if idx < 0
+    until (search.include? (self[idx])) do
+      idx -= 1
+      return nil if idx < 0
+    end
+    return idx
+  end
+  
+  alias_method :find, :index
+  alias_method :rfind, :rindex
+  
+  def first
+    return "" if empty?
+    self[0]
+  end
+  
+  def last
+    return "" if empty?
+    self[length-1]
+  end
+
+  # removes first char
+  def first!
+    return "" if empty?
+    rtn = self[0]
+    replace self[1..(length-1)]
+    return rtn
+  end
+  
+  # removes last char
+  def last!
+    if length==1
+      rtn = dup
+      self.clear
+      return rtn
+    end
+    return "" if empty?
+    rtn = self[length-1]
+    replace self[0..(length-2)]
+    return rtn
+  end
+  
+  def extract_trailing_int!
+    return nil if empty?
+    return nil unless String::SET_INT_CHARS.include? last
+    str = ""
+    while String::SET_INT_CHARS.include? last
+      str += last!
+      break if empty?
+    end
+    return str.reverse.to_i
+  end
+  
+  def dec!(val=nil)
+    num = extract_trailing_int!
+    return self if num.nil?
+    return self if 0==num
+    val ||= 1
+    return self if (num-val) < 0
+    append!(num-val)
+    dup
+  end
+
+  def dec(val=nil)
+    return dup.dec!(val)
+  end
+  
+  # increments integer at end of string
+  def inc!(val=nil)
+    num = extract_trailing_int!
+    if num.nil?
+      if val.nil?
+        append!(0)
+      else
+        append!(val)
+      end
+    else
+      append! (val.nil? ? (num+1) : (num+val))
+    end
+    dup
+  end
+  
+  def inc(val=nil)
+    return dup.inc!(val)
+  end
+
+  def append!(obj)
+    replace self + obj.to_s
+  end  
+
+  def append(obj)
+    self + obj.to_s
+  end  
+  
+  def zap!  # simple alias
+    clear
+  end
+
+  def parsed
+    @found ||= nil
+  end
+  
+  def extract_leading_set!(set)
+    rtn = ""
+    set = set.to_set
+    while set.include? first do
+      rtn += first!
+    end  
+    return rtn
+  end  
+  
+  def extract_trailing_set!(set)
+    rtn = ""
+    set = set.to_set
+    while set.include? last do
+      rtn += last!
+    end  
+    return rtn.reverse
+  end  
+
+  def split_on_set(set=' ')
+    str = dup
+    if (set.nil? || set.empty?)
+      set = ' '
+    end
+    set = set.to_set
+    prefx = str.extract_leading_set!(set)
+    pstfx = str.extract_trailing_set!(set)
+    dat = []
+    tok = []
+    loop do
+      break if str.empty?
+      dat.push str.parse(set, :no_strip)
+      tmp = str.parsed
+      break if tmp.nil? 
+      tmp += str.extract_leading_set!(set)
+      tok.push tmp
+    end
+    dat.push str unless str.empty?
+    return [dat,tok,prefx,pstfx]
+  end  
+
+  def gs_titlecase
+    downcase!
+    if index(GS_SENTENCE_TERM)
+      ary = self.split_on_set(GS_SENTENCE_TERM)
+      pa = []
+      ary.first.each do |sentence|
+        pa.push(sentence.gs_titlecase.strip)
+      end
+      ary[0] = pa.reverse!
+      ary[1].reverse!
+      rtn = ary.first.pop
+      until ary.first.empty?
+        rtn += "#{ary[1].pop} #{ary.first.pop}"
+      end
+      rtn += ary.last || ""
+      return rtn
+    end
+    ary = self.split(' ')
+    ary.first.capitalize!
+    ary.last.capitalize!
+    (1..(ary.size-2)).each do |idx|
+      ary[idx].capitalize! unless GS_TITLE_EXCEPTIONS.include?(ary[idx]) 
+    end
+    return ary.join ' '
+  end
+  
+  def gs_titlecase!
+    replace gs_titlecase 
+  end
+  
+  def shuffle
+    return self.split('').shuffle.join
+  end
+  
+  def shuffle!
+    replace shuffle
+  end
+  
+  def sublist(*prms)
+    if (prms.first.class==Symbol)
+      if prms.first == :bang
+        prms = prms[1] 
+      else
+        raise "illegal sublist parameter"
+      end
+    end
+    prms.reverse!
+    cls = prms.pop
+    flags = {}
+    dflt = nil
+    subh = nil  # substitution hash
+    suba = nil  # substitution array
+    cnt = nil
+    until prms.empty?
+      tmp = prms.pop
+      if(tmp.class==Array)
+        raise "parameter error" unless suba.nil?
+        suba = tmp.reverse  # make it easy to pop, and makes a new instance
+      elsif (tmp.class==Hash)
+        raise "parameter error" unless subh.nil?
+        subh = {}
+        tmp.each do |key,val|
+          subh[key.to_s] = val.to_s  # convert keys and values to strings
+        end      
+      elsif (tmp.class==Symbol)
+        flags[tmp] = true
+      elsif (tmp.class==Fixnum)
+        raise "count parameter repeated" unless cnt.nil?
+        cnt = tmp
+      elsif (tmp.class==String)
+        raise "parameter error" unless dflt.nil?
+        dflt = tmp      
+      else
+        raise "unknown parameter type"
+      end
+    end
+  
+    str = self.dup
+    ptr = 0
+    rtn = ""
+    cls = [cls] if (String==cls.class)
+    fa = []
+    # add more as needed later ...
+    fa.push :ignore if flags.include? :ignore
+    fass = fa + [:no_strip] + [:no_skip]   
+    cls = [cls] if (Set==cls.class)     # push everything into an array even regx
+    cls = [cls] if (Regexp==cls.class)
+    flst = (flags.include? :first) ? {} : nil
+
+    # remove nil values
+    subh ||= {}
+    suba ||= []
+    dflt ||= ""
+    
+    if flags.include? :ignore  # update substitution hash keys to lower case if :ignore
+      unless subh.empty?
+        tmp = {}
+        subh.each do |key,val|
+          tmp[key.downcase] = val.to_s
+        end
+        subh = tmp
+      end    
+    end
+    
+    unless (Hash==cls.class)
+      loop do
+        unless cnt.nil?
+          if (cnt <= 0)
+            rtn += str
+            return rtn
+          end
+        end
+        rtn += str.parse(cls, fass)  # make sure we are working on arrays of a bunch of stuff including nested === add test case
+        break if str.parsed.nil?
+        
+        unless flst.nil?  # process first flag exceptions
+          key = (flags.include? :ignore) ? str.parsed.downcase : str.parsed 
+          if flst.include? key
+            rtn += str.parsed  # make no substitution
+            cnt -= 1 unless cnt.nil?
+            next
+          else
+            flst[key] = true   # mark as taboo on future substitutions 
+          end
+        end
+        
+        # first check to see if we have a hash match
+        unless subh.empty?
+          key = (flags.include? :ignore) ? str.parsed.downcase : str.parsed
+          dat = subh[key]
+          unless dat.nil?
+            rtn += dat
+            return rtn if str.empty?
+            cnt -= 1 unless cnt.nil?
+            next
+          end           
+        end
+
+        # next check to see if we have substitution data in the array
+        unless suba.empty?
+          rtn += suba.pop
+          return rtn if str.empty?
+          cnt -= 1 unless cnt.nil?
+          next
+        end
+        
+        # at last use the default
+        if flags.include? :stop  # do not make substitutions with default
+          rtn += str.parsed
+          rtn += str
+          return rtn
+        elsif flags.include? :skip  # skip over, then keep going
+          rtn += str.parsed
+        else
+          rtn += dflt  
+        end
+        return rtn if str.empty?
+        cnt -= 1 unless cnt.nil?
+      end # loop 
+      return rtn 
+    else # (Hash==cls.class)
+      cls = cls.dup
+      loop do
+        unless cnt.nil?
+          if (cnt <= 0)
+            rtn += str
+            return rtn
+          end
+        end
+        pos = nil
+        best = nil
+        bval = nil
+        cls.each do |key,val|
+          idx = str.index(key.to_s, 0 , fa)
+          unless idx.nil?
+            pos ||= idx
+            best ||= key.to_s
+            bval ||= val.to_s
+            if(idx < pos)
+              pos = idx
+              best = key.to_s
+              bval = val.to_s
+            end
+            break if idx.zero?  # can't get better than zero, so stop looking
+          end
+        end
+        if best.nil?
+          rtn += str
+          return rtn
+        end
+        # byebug if flags.include? :ignore
+        rtn += str.parse(best, fass)
+        break if str.parsed.nil?
+        if flags.include? :first
+          cls.delete best
+          cls.delete best.to_sym  # just in case
+        end
+        rtn += bval  
+        cnt -= 1 unless cnt.nil?
+      end #loop
+      return rtn
+    end
+  end
+  
+  def sublist!(*prms)
+    replace sublist(:bang, prms)
+  end
+  
+  def to_num  # convert to integer or float depending on format
+    self.dup.extract_num!
+  end
+  
+  def extract_num!
+    dat = parse(String::RGX_FLOAT, :no_skip)
+    if parsed.nil?  # no number found
+      num = dat.extract_leading_set!(Set.digit_chars)
+      replace dat
+      return 0 if num.empty?
+      return num.to_i
+    else
+      return parsed.to_f
+    end  
+  end
+  
+  def limit_to(size, *flags)
+    return self if length <= size
+    if flags.include? :no_break
+      pos = self.rfind(SET_SPLIT_CHARS)
+      return self[0..(size-2)] + '…' if pos.nil?
+      return self[0..(pos-1)] + '…'       
+    else
+      return self[0..(size-2)] + '…'
+    end
+  end
+  
+  def to_eng(pa=6, unit=nil)
+    return self.to_f.to_eng(pa, unit)
+  end
+  
+  def to_scd(dp=nil, delim = ',.')
+    num = to_num
+    if(dp.nil?)
+      if num.class==Float
+        return num.to_scd(2,delim)
+      else
+        return num.to_scd(0,delim)
+      end
+    end
+    return num.to_scd(dp,delim)  
+  end
+  
+  def rand(cnt=1, *prms)
+    return "" if empty?
+    return "" if cnt < 1
+    if length==1
+      return self if prms.include? :set
+      return self * cnt
+    end
+    rnd = Random.new
+    rtn = ""
+    str = prms.include?(:set) ? self.to_set.to_s : self.dup
+    cnt.times do
+      break if str.empty?
+      ch = str[rnd.rand(str.length)]
+      rtn += ch
+      str[str.find(ch)] = "" if prms.include? :once      
+    end
+    return rtn
+  end  
+  
+  def rand!(cnt=1, *prms)  # once is implied
+    return "" if empty?
+    return "" if cnt < 1
+    if length==1
+      return first!
+    end
+    rnd = Random.new
+    rtn = ""
+    cnt.times do
+      break if self.empty?
+      ch = self[rnd.rand(self.length)]
+      rtn += ch
+      if prms.include? :set
+        remove! ch
+      else
+        self[self.find(ch)] = ""
+      end
+    end
+    return rtn
+  end 
+  
+=begin  
+  def rand(cnt=1, unique=true)
+    return "" if empty?
+    return "" if cnt < 1
+    return self if length==1
+    cnt = cnt >= length ? length : cnt
+    if unique
+      sh = shuffle
+      return sh[0..(cnt-1)]
+    else
+      rr = Random.new
+      rtn = ""
+      cnt.times do
+        rtn += self[rr.rand(length)]
+      end
+      return rtn
+    end
+  end  
+
+  def rand!(cnt=1)
+    return "" if empty?
+    return "" if cnt < 1
+    return first! if length==1
+    cnt = cnt >= length ? length : cnt
+    if length==cnt
+      rtn = shuffle
+      zap!
+      return rtn
+    end
+    ary = (0..(length-1)).to_a.shuffle
+    return extract! ary[0..(cnt-1)]   # return is not randomized ... why ???
+  end
+=end  
+  
+  # default char for blank? or new mode
+  def access_mode(md=:stop, dflt=' ') # :swing :stick :default :rotate
+    @gs_access_mode = md
+    @gs_default_str = dflt
+    @gs_np_pos = nil
+    @gs_dir = :up
+    self
+  end
+  
+  def next
+    @gs_np_pos ||= nil
+    @gs_access_mode ||= :stop
+    @gs_dir ||= :up
+    return "" if empty?
+    if @gs_np_pos.nil?
+      ch = first
+      @gs_np_pos = 0
+      return ch
+    else
+      case @gs_access_mode
+        when :stop
+          @gs_np_pos = @gs_np_pos >= length ? length : @gs_np_pos + 1
+          ch = self[@gs_np_pos]
+          return ch.nil? ? "" : ch
+        when :rotate
+          @gs_np_pos += 1
+          @gs_np_pos = @gs_np_pos >= length ? 0 : @gs_np_pos
+          return self[@gs_np_pos]
+        when :stick
+          @gs_np_pos = @gs_np_pos >= length ? length : @gs_np_pos + 1
+          ch = self[@gs_np_pos]
+          return ch.nil? ? last : ch
+        when :default
+          @gs_np_pos = @gs_np_pos >= length ? length : @gs_np_pos + 1
+          ch = self[@gs_np_pos]
+          return ch.nil? ? @gs_default_str : ch
+        when :swing
+          return first if length==1
+          if @gs_dir== :up
+            @gs_np_pos += 1
+            if @gs_np_pos >= length
+              @gs_dir= :down
+              @gs_np_pos = length - 2
+            end
+            return self[@gs_np_pos]            
+          else # :down
+            @gs_np_pos -= 1
+            if @gs_np_pos < 0
+              @gs_dir= :up
+              @gs_np_pos = 1
+            end
+            return self[@gs_np_pos]
+          end
+        else
+          raise "unsupported access mode"  
+      end
+    end
+  end
+
+  def prev
+    @gs_np_pos ||= nil
+    @gs_access_mode ||= :stop
+    @gs_dir ||= :up
+    return "" if empty?
+    if @gs_np_pos.nil?
+      ch = last
+      @gs_np_pos = length - 1
+      return ch
+    else
+      case @gs_access_mode
+        when :stop
+          @gs_np_pos = @gs_np_pos <= 0 ? -1 : @gs_np_pos - 1
+          return "" if @gs_np_pos < 0
+          return self[@gs_np_pos]
+        when :rotate
+          @gs_np_pos -= 1
+          @gs_np_pos = @gs_np_pos < 0 ? length-1 : @gs_np_pos
+          return self[@gs_np_pos]
+        when :stick
+          @gs_np_pos = @gs_np_pos <= 0 ? -1 : @gs_np_pos - 1
+          return first if @gs_np_pos < 0
+          return self[@gs_np_pos]
+        when :default
+          @gs_np_pos = @gs_np_pos <= 0 ? -1 : @gs_np_pos - 1
+          return @gs_default_str if @gs_np_pos < 0
+          return self[@gs_np_pos]
+        when :swing
+          return first if length==1
+          if @gs_dir== :down
+            @gs_np_pos += 1
+            if @gs_np_pos >= length
+              @gs_dir= :up
+              @gs_np_pos = length - 2
+            end
+            return self[@gs_np_pos]            
+          else # :up
+            @gs_np_pos -= 1
+            if @gs_np_pos < 0
+              @gs_dir= :down
+              @gs_np_pos = 1
+            end
+            return self[@gs_np_pos]
+          end
+        else
+          raise "unsupported access mode"            
+      end
+    end
+  end  
+  
+end # String
+
+class Integer
+  def to_num
+    self
+  end
+  def to_scd(dp=0, delim = ',.')
+    return self.to_f.to_scd(dp, delim) unless dp.zero?
+    str = self.to_s.reverse.scan(/\d{1,3}/).join(delim.first).reverse
+    (self < 0) ? "-" + str : str
+  end
+  def to_eng(pa=6, unit=nil)
+    return self.to_f.to_eng(pa, unit)
+  end
+end
+
+class Float
+  def to_num
+    self
+  end
+  def to_scd(dp=2, delim = ',.')
+    num = ((10 ** dp) * self).round.to_s
+    man = num[0..(-dp-1)]
+    man = man.empty? ? '0' : man
+    frt = (num[(-dp)..(-1)] || "").padto(dp,'0',:right)
+    return man.reverse.scan(/\d{1,3}/).join(delim.first).reverse + delim.last + frt
+  end
+  def to_eng(pa=6, unit=nil)
+    pa = pa.to_i
+    pa = (pa<1) ? 1 : (pa>15) ? 15 : pa
+    if self < 0.0
+      num = -self
+      sgn = "-"
+    else
+      num = self
+      sgn = ""  
+    end
+    str = "%.16e" % num
+    str.extract!(1..1)    # remove decimal point
+    num = str.parse('e')
+    exp = str.to_i
+    pos = (exp%3)+1
+    if (exp < 0)
+      esgn = "-"
+      ee  = -(exp/3)*3
+    else
+      esgn = ""
+      ee = (exp/3)*3
+    end
+    pd = pos > pa ? pos : pa
+    num = (num[0..pa].to_f/10).round.to_s[0..(pa-1)].padto(pd,'0',:right)  # round to target size
+    num.insert(pos, '.') unless pos >= (num.length)
+    pfx = String::SI_UNIT_PREFIXES["#{esgn}#{ee}".to_i]
+    unless unit.nil?
+      unless pfx.nil?
+        num += pfx
+        ee=0 # disable 'e' thing
+      end
+    end
+    unit ||= ""  
+    if (ee>0)
+      num += "e#{esgn}#{ee}"
+    end
+    return sgn+num+unit
+  end
+end
+