sub_string 1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c328fe148dea22de40b0b91fcb890ecad51ec98b52579bd963ec3595a5c5d312
+  data.tar.gz: 2490b15f6bab5c743d02db40e5857acf9fd6b3b38b75fa7d155869e7dce957e3
+SHA512:
+  metadata.gz: 573037a06377750a49a90d0ed95ca0ab59deb693eec7410b9a618352f334927e229a10a621e0c7a380f8deb4f201d5925b112871442b0fbb4d32ef86bc4dafb3
+  data.tar.gz: bab762511ada2c4e0c5b959c243605ad503d7e38f11ec1eebab0acbfa84eb95e6b3bbd9b9a3d0b6a609001521d455fde94489436dcbbfd0ebd31ea014adb1449

data/.gitignore

@@ -0,0 +1,51 @@
+# See https://help.github.com/articles/ignoring-files for more about ignoring files.
+#
+# If you find yourself ignoring temporary files generated by your text editor
+# or operating system, you probably want to add a global ignore instead:
+#   git config --global core.excludesfile '~/.gitignore_global'
+
+# Ignore bundler config.
+/.bundle
+/vendor/bundle
+
+# Ignore all logfiles and tempfiles.
+/log/*
+/tmp/*
+!/log/.keep
+!/tmp/.keep
+
+.rbenv-version
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc
+
+/node_modules
+/yarn-error.log
+
+.byebug_history
+
+*.[oa]
+*.so
+*~
+*.nogem
+*nogem.*
+*.bak
+*.BAK
+*.backup
+*.org
+*.orig
+*.elc
+*.pyc
+\#*\#
+
+# Elastic Beanstalk Files
+.elasticbeanstalk/*
+!.elasticbeanstalk/*.cfg.yml
+!.elasticbeanstalk/*.global.yml
+
+# yard
+*.yardoc
+
+# Ruby Gem doc
+*.gem
+doc/*
+

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2012-2018 Scott Chacon and others
+
+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/Makefile

@@ -0,0 +1,23 @@
+ALL	= 
+
+objs	= 
+
+.SUFFIXES:	.so .o .c .f
+
+#.o.so:
+#	${LD} ${LFLAGS} -o $@ $< ${LINK_LIB}
+
+all: ${ALL}
+
+
+.PHONY: clean test doc
+clean:
+	$(RM) bin/*~
+
+## You may need RUBYLIB=`pwd`/lib:$RUBYLIB
+test:
+	rake test
+
+doc:
+	yard doc; [[ -x ".github" && ( "README.en.rdoc" -nt ".github/README.md" ) ]] && ( ruby -r rdoc -e 'puts RDoc::Markup::ToMarkdown.new.convert ARGF.read' < README.en.rdoc > .github/README.md ; echo ".github/README.md is updated." ) || exit 0
+

data/README.en.rdoc

@@ -0,0 +1,173 @@
+
+= SubString - Duck-typed String class with negligible memory use
+
+== Summary
+
+Class {SubString} that expresses Ruby sub-String but taking up negligible memory space, as its instance holds the positional information only.  It behaves exactly like String (duck-typing), except destructive modification is prohibited.  If the original string is destructively modified, warning is issued.
+
+For the detailed background concept (and algorithm), see the reference page of the
+generalized parent class, SubObject, either at the
+{Ruby Gems page}[http://rubygems.org/gems/sub_object]
+or in
+{Github}[https://github.com/masasakano/sub_object] .
+
+The full package of this class is found also in
+{SubString Ruby Gems page}[http://rubygems.org/gems/sub_string] and
+in {Github}[https://github.com/masasakano/sub_string]
+
+
+== Description
+
+This class takes three parameters in the initialization: *source*, *pos*
+(starting positional character-index), and *size* (of the substring of the original String *source*.
+
+  SubObject.new( source, position, size )
+
+The constructed instance of this class keeps only these three pieces
+of information (plus a hash value, strictly speaking), and hence uses negligible internal memory space on its own.
+Note that only the information this instance needs for *source* is
++source.object_id+ or equivalent, which is really negligible in size. 
+In other words, this class does not create the copy of sub-Object from
+the original source object as the Ruby default +String#[i,j]+ does.
+
+Then, whenever it is referred to, it reconstructs the original
+sub-String object:
+
+  source[pos, size]
+
+and works exactly like *source*
+({duck-typing}[https://en.wikipedia.org/wiki/Duck_typing]).
+
+As an example, the child class {SubString}[http://rubygems.org/gems/sub_string] (provided as a different Gem)
+works as:
+
+  src = "abcdef"
+  ss = SubString.new(src, -4, 3)  # => Similar to "abcdef"[-4,3]
+  print ss     # => "cde" (STDOUT)
+  ss+'3p'      # => "cde3p"
+  ss.upcase    # => "CDE"
+  ss.sub(/^./, 'Q') # => "Qde"
+  ss.is_a?(String)  # => true
+  "xy_"+ss     # => "xy_cde"
+  "cde" == ss  # => true
+
+Internally the instance holds the source object.  Therefore, as long
+as the instance is alive, the source object is never garbage-collected (GC).
+
+=== Instance methods
+
+The following is the instance methods of {SubObject}[http://rubygems.org/gems/sub_object] unique to this class.
+
++#source()+::  Returns the first argument (+source+ String) given in initialization. The returned value is dup-ped and **frozen**.
++#pos()+::  Returns the second argument (positional index) given in initialization.
++#subsize()+::  Returns the third argument (size) given in initialization.  Equivalent to the method +#size+.
++#pos_size()+::  Returns the two-component array of +[pos, subsize]+
++#to_source()+::  Returns the instance projected with +to_src+
+
+In addition, +#inspect+ is redefined.
+
+Any public methods but destructive ones that are defined for the +source+ can
+be applied to the instance of this class.
+
+=== Potential use
+
+Each sub-String in Ruby like +String[i, j]+ or +String[i..j]+ takes up memory
+according to the length of the sub-String.  Consider an example:
+
+  src = "Some very extremely lengthy string.... (snipped)".
+  sub = src[1..-1]
+
+The variable +sub+ uses up about the same memory of +src+.
+If a great number of +sub+ is created and held alive, the total memory
+used by the process can become quicly multifold, even by orders of magnitude.
+
+This is where this class comes in handy.  For example, a parsing
+program applied to a huge text document with a complex grammar may
+hold a number of such String variables.  By using this class instead
+of String, it can save some valuable memory.
+
+=== Warning about destructive methods to this instance or worse, to the source
+
+If the source object has been destructively altered, such as with the
+destructive method +clear+, the corresponding object of this class
+is likely not to make sense any more.  This class can detect such destructive
+modification (using the method +Object#hash+) and issues a warning
+whenever it is accessed after the source object has been destructively
+altered, unless the appropriate global settings (see the next section)
+are set to suppress it.
+
+Similarly, because this class supplies an object with the filter +String#to_str+
+when it receives any message (i.e., method),
+it does not make sense to apply a destructive change on the instance of this class.
+Therefore, whenever a destructive method (such as, +String#sub!+ and
++String#replace+ or even +String#force_encoding+) is applied to an
+instance of this class, it
+raises NoMethodError exception (or tries to with the best effort).  The routine to identify the
+destructive method relies thoroughly on the method name.
+The methods ending with "!" are regarded as destructive and all the
+built-in destructive methods of String (as of Ruby 2.6.5).
+
+If a user library adds destructive methods with the name not ending
+with "!" in the String class, you can register it in the inherited class constant
+DESTRUCTIVE_METHODS so the instances of this class will
+recognize them (Note that it is recommended to use a destructive
+method for it, perhaps with one of +Array#<<+, +Array#append+, +Array#push+, +Array#concat+ etc).
+The reference of the parent
+{SubObject}[http://rubygems.org/gems/sub_object] class describes the
+detail of the mechanism of how it works (if you are interested).
+
+Note that if a (user-defined) desturctive method of String passes the
+check by this class objects,
+the result is most likely to be different from intended.  It certainly
+never alters this instance destructively, and
+the returned value may be not like the expected value.
+
+=== Suppressing the warning
+
+This class objects issues a warning in default every time it detects the *source*
+String object has been destructively modified.  My best advice is,
+never alter the *source* object destructively!  It makes no sense to
+use this object in such a case.
+
+However if you want to suppress the warning message, set the Ruby
+global variable +$VERBOSE+ to nil.  Alternatively, you can control it with
+a class instance variable as
+
+  SubObject.verbose       # => getter
+  SubObject.verbose=true  # => setter
+
+If it is set either TRUE or FALSE, this verbosity level has a
+priority, regardless of the value of +$VERBOSE+.
+In default it is nil and $VERBOSE is referred to.
+
+
+== Install
+
+This script requires {Ruby}[http://www.ruby-lang.org] Version 2.0
+or above.
+
+You can install it from the usual Ruby gem command.
+Or, alternatively, download it and put the library file in one of your Ruby library search paths.
+
+== Developer's note
+
+The master of this README file is found in
+{RubyGems/sub_object}[https://rubygems.org/gems/sub_object]
+
+=== Tests
+
+Ruby codes under the directory <tt>test/</tt> are the test scripts.
+You can run them from the top directory as <tt>ruby test/test_****.rb</tt>
+or simply run <tt>make test</tt>.
+
+== Known bugs and Todo items
+
+* This class ignores any optional (keyword) parameters for the methods.  It is due to the fact Ruby {BasicObject#method_missing}[https://ruby-doc.org/core-2.6.5/BasicObject.html#method-i-method_missing] does not take them into account as of Ruby-2.6.5.  It may change in future versions of Ruby. As far as the Ruby built-in methods of String are concerned, it does not matter because none of them uses one.  However, if String uses such user-defined methods, it may encounter a trouble.
+
+
+== Copyright
+
+Author::  Masa Sakano < info a_t wisebabel dot com >
+Versions:: The versions of this package follow Semantic Versioning (2.0.0) http://semver.org/
+License:: MIT
+

data/Rakefile

@@ -0,0 +1,9 @@
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+end
+
+desc "Run tests"
+task :default => :test
+

data/lib/sub_string.rb

@@ -0,0 +1,22 @@
+# -*- coding: utf-8 -*-
+
+require 'sub_object'  # Gem: {SubObject}[http://rubygems.org/gems/sub_object]
+
+# Child class of SubObject for String: SubString
+#
+# See for detail the full reference in the top page
+# {SubString}[http://rubygems.org/gems/sub_string]
+# and in {Github}[https://github.com/masasakano/sub_string]
+# and also
+# {SubObject}[http://rubygems.org/gems/sub_object]
+# and that in {Github}[https://github.com/masasakano/sub_object]
+#
+# @author Masa Sakano (Wise Babel Ltd)
+#
+class SubString < SubObject
+  # Symbol of the method that projects to (returns) the original-like instance;
+  # e.g., :to_str for String. The value should be overwritten in the child class of SubObject.
+  TO_SOURCE_METHOD = :to_str
+  alias_method TO_SOURCE_METHOD, :to_source
+end
+

data/sub_string.gemspec

@@ -0,0 +1,52 @@
+# -*- encoding: utf-8 -*-
+
+require 'rake'
+require 'date'
+
+Gem::Specification.new do |s|
+  s.name = %q{sub_string}.sub(/.*/){|c| (c == File.basename(Dir.pwd)) ? c : raise("ERROR: s.name=(#{c}) in gemspec seems wrong!")}
+  s.version = "1.0"
+  # s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  # s.bindir = 'bin'
+  # %w(sub_string).each do |f|
+  #   path = s.bindir+'/'+f
+  #   File.executable?(path) ? s.executables << f : raise("ERROR: Executable (#{path}) is not executable!")
+  # end
+  s.authors = ["Masa Sakano"]
+  s.date = %q{2019-11-05}.sub(/.*/){|c| (Date.parse(c) == Date.today) ? c : raise("ERROR: s.date=(#{c}) is not today!")}
+  s.summary = %q{Duck-typed String class with negligible memory use}
+  s.description = %q{Class SubString that expresses Ruby sub-String but taking up negligible memory space, as its instance holds the positional information only.  It behaves exactly like String (duck-typing), except destructive modification is prohibited.  If the original string is destructively altered, warning is issued.}
+  # s.email = %q{abc@example.com}
+  s.extra_rdoc_files = [
+     #"LICENSE.txt",
+     "README.en.rdoc",
+  ]
+  s.license = 'MIT'
+  s.files = FileList['.gitignore','lib/**/*.rb','[A-Z]*','test/**/*.rb', '*.gemspec'].to_a.delete_if{ |f|
+    ret = false
+    arignore = IO.readlines('.gitignore')
+    arignore.map{|i| i.chomp}.each do |suffix|
+      if File.fnmatch(suffix, File.basename(f))
+        ret = true
+        break
+      end
+    end
+    ret
+  }
+  s.files.reject! { |fn| File.symlink? fn }
+
+  s.add_runtime_dependency 'sub_object', '>= 1.0'
+  # s.add_development_dependency "bourne", [">= 0"]
+  s.homepage = %q{https://www.wisebabel.com}
+  s.rdoc_options = ["--charset=UTF-8"]
+
+  # s.require_paths = ["lib"]	# Default "lib"
+  s.required_ruby_version = '>= 2.0'  # respond_to_missing?
+  s.test_files = Dir['test/**/*.rb']
+  s.test_files.reject! { |fn| File.symlink? fn }
+  # s.requirements << 'libmagick, v6.0' # Simply, info to users.
+  # s.rubygems_version = %q{1.3.5}      # This is always set automatically!!
+
+  s.metadata["yard.run"] = "yri" # use "yard" to build full HTML docs.
+end
+

data/test/test_sub_string.rb

@@ -0,0 +1,124 @@
+# -*- encoding: utf-8 -*-
+
+# @author Masa Sakano (Wise Babel Ltd)
+
+#require 'open3'
+require 'sub_object'
+require 'sub_string'
+
+$stdout.sync=true
+$stderr.sync=true
+# print '$LOAD_PATH=';p $LOAD_PATH
+
+#################################################
+# Unit Test
+#################################################
+
+gem "minitest"
+# require 'minitest/unit'
+require 'minitest/autorun'
+
+class TestUnitSubString < MiniTest::Test
+  T = true
+  F = false
+  SCFNAME = File.basename(__FILE__)
+  EXE = "%s/../bin/%s" % [File.dirname(__FILE__), File.basename(__FILE__).sub(/^test_(.+)\.rb/, '\1')]
+
+  def setup
+  end
+
+  def teardown
+  end
+
+  def test_sub_string01
+    assert_raises(TypeError){ SubString.new [9,8], -3, 2 }
+
+    str = 'abcdefghijklm'
+    obj = SubString.new str, -5, 2
+    assert_raises(TypeError){ SubString.new str, -3, :a }
+    assert_equal obj,    "ij"
+    assert_equal "ij",   obj
+    assert( "ij"==obj )
+    assert_operator obj, ">", "ii"
+    assert_operator "ii", "<", obj
+    assert( SubString.method_defined?(:to_str), "obj=#{obj.inspect}" )
+    assert( obj.methods.include? :to_str )
+    assert_equal 'ijKL', obj+"KL"
+    assert_equal "IJ",   obj.upcase
+    assert            obj.instance_of?(SubString)
+    refute            obj.instance_of?(SubObject)
+    assert            obj.respond_to?(:upcase), "upcase: to_source = (#{obj.to_source.inspect}); methods: #{obj.methods.sort.inspect}"
+    assert            obj.respond_to?(:gsub), "to_source = (#{obj.to_source.inspect}); methods: #{obj.methods.sort.inspect}"
+    refute            obj.respond_to?(:gsub!)
+    refute            obj.respond_to?(:naiyo)
+    assert_raises(NoMethodError){ obj.push 5 }
+    assert_raises(NoMethodError){ obj.keep_if{} }
+    assert_raises(NoMethodError){ obj.sub! }
+    assert_raises(NoMethodError){ obj.replace }
+    
+    mutex = Mutex.new
+    exclu = Thread.new {
+      mutex.synchronize {
+      org_verbose = $VERBOSE
+      assert_output('', ''){ _ = SubString.verbose }
+      begin
+        $VERBOSE = true
+        assert_nil          SubString.verbose
+        SubString.verbose=nil;
+        assert_nil          SubString.verbose
+        str.sub!(/^./){|c| c.upcase}
+        assert_output('', /destructively/){ obj.source }
+        $VERBOSE = false
+        assert_output('', /destructively/){ obj.source }
+        $VERBOSE = nil
+        assert_output('', ''){ obj.source }
+
+        SubString.verbose = true
+        assert_equal true,  SubString.verbose
+        assert_equal true,  SubString.instance_variable_get(:@verbosity)
+        assert_output('', /destructively/){ obj.source }
+        SubString.verbose = false
+        assert_equal false, SubString.verbose
+        assert_output('', ''){ obj.source }
+        $VERBOSE = true
+        assert_output('', ''){ obj.source }
+        SubString.verbose=nil;
+        assert_output('', /destructively/){ obj.source }
+
+        # Original String recovered, hence its hash value.
+        str.sub!(/^./){|c| c.downcase}
+        assert_output('', ''){ obj.source }
+      ensure
+        $VERBOSE = org_verbose
+        SubString.verbose=nil;
+      end
+      }
+    }
+    exclu.join
+  end
+
+  def test_sub_string02
+    str = 'abcdefghijklm'*20
+    obj = SubString.new str, 0, 120
+    str.upcase!
+    siz = nil
+    _, err = capture_io { siz = obj.size }
+    assert_equal '..."'+"\n", err[-5..-1]
+    assert_equal  60, (err.split(']')[-1].size-4)/10.0.round*10
+    assert_equal 120, siz
+  end
+
+  # As in README.en.rdoc
+  def test_sub_string03
+    src = "abcdef"
+    ss = SubString.new(src, -4, 3)  # => Similar to "abcdef"[-4,3]
+    assert_operator "cde", '==', ss
+    assert_equal "cde",    ss.to_s
+    assert_equal "cde3p",  ss+'3p'
+    assert_equal "CDE",    ss.upcase
+    assert_equal "Qde",    ss.sub(/^./, 'Q')
+    assert                 ss.is_a?(String)
+    assert_equal "xy_cde", "xy_"+ss
+  end
+end # class TestUnitSubString < MiniTest::Test
+

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification
+name: sub_string
+version: !ruby/object:Gem::Version
+  version: '1.0'
+platform: ruby
+authors:
+- Masa Sakano
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2019-11-05 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: sub_object
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: Class SubString that expresses Ruby sub-String but taking up negligible
+  memory space, as its instance holds the positional information only.  It behaves
+  exactly like String (duck-typing), except destructive modification is prohibited.  If
+  the original string is destructively altered, warning is issued.
+email: 
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.en.rdoc
+files:
+- ".gitignore"
+- LICENSE.txt
+- Makefile
+- README.en.rdoc
+- Rakefile
+- lib/sub_string.rb
+- sub_string.gemspec
+- test/test_sub_string.rb
+homepage: https://www.wisebabel.com
+licenses:
+- MIT
+metadata:
+  yard.run: yri
+post_install_message: 
+rdoc_options:
+- "--charset=UTF-8"
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3
+signing_key: 
+specification_version: 4
+summary: Duck-typed String class with negligible memory use
+test_files:
+- test/test_sub_string.rb