rangesmaller 1.0.0 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: fc2c175fd0a6852787d486eb15569707b6120222
-  data.tar.gz: ffeacff7e8c94e70a96723a34525f6a1a31ba055
+  metadata.gz: c2f34ade6a7332bb19809904e8b89b419c5c71c1
+  data.tar.gz: 2931d7e5c7e98cedffab98faf3dfb45f83e638dd
 SHA512:
-  metadata.gz: e2e4c8422b98bde05a3caae8c8e4c143ad6a495b30f0930f69f972f5a0ac4085a87d3f2b1b55ebb0d35ba4ffc95edd90ae162917097ee6e8397dbb117328660a
-  data.tar.gz: 1b7f0a09ccd0e66acee41ea4ef08a9d87c5579a4dc47bcbaf2830cae14974bf71d47ca7eee176f28689e6e0ce29acb7b5b4c56799c6c0608cffe9b47de86eebe
+  metadata.gz: 48ee7f0ef72c8cf5db14554f2843b69fa3d06728c5eede5092bbd8b9c2b0a5516922d8131d0a3442c1e55c92af997d001860d2085876c47cd3b6c81fdb7b0947
+  data.tar.gz: 7990cd5e77b37a10d1be51a069e97c36eabf56834fb9725764c542e3b302882b2d81a57e08f2956e99e0c38f62e7481102fcf506e30b098a73ca890d45b74df3

data/README.rdoc

@@ -21,7 +21,10 @@ A file
   rangesmaller/rangesmaller.rb
 should be installed in one of your $LOAD_PATH
 
-Then all you need to do now is
+Alternatively get it from
+  http://rubygems.org/gems/rangesmaller
+
+Then all you need to do is
   require 'rangesmaller'
 in your Ruby script (or irb).
 
@@ -82,10 +85,14 @@ They are evaluated as follows:
  * No thorough test for Ruby 1.8 or earlier has been done, although there is no known fault.
 
 
+== ToDo
+
+Nothing planned.
+
 == Copyright etc
 
 Author::  Masa Sakano < imagine a_t sakano dot co dot uk >
-License:: The same as Ruby.  www.ruby-lang.org
+License:: MIT.
 Warranty:: No warranty whatsoever.
 
 

data/lib/rangesmaller/rangesmaller.rb

@@ -25,23 +25,23 @@ class Rangesmaller < Range
   #   @param [Rangesmaller] key describe key param
   #
   # @overload new(range, opts)
-  #   @param [Range] standard Range object
-  #   @option opts [Object] :exclude_begin the begin boundary is excluded, if false (Default)
+  #   @param range range [Range] standard Range object
+  #   @option opts opts [Object] :exclude_begin the begin boundary is excluded, if false (Default)
   #
-  # @overload new(begin, end, exclude_end=false)
+  # @overload new(obj_begin, obj_end, exclude_end=false)
   #   This form is not recomended, but for the sake of compatibility with Range.
-  #   @param [Object] Any object (preferably {#Comparable})
-  #   @param [Object] Any object, compatible with begin
-  #   @param [Object] true or false(Default) or any.
+  #   @param obj_begin [Object] Any object (preferably {Comparable})
+  #   @param obj_end [Object] Any object, compatible with begin
+  #   @param exclude_end [Object] true or false(Default) or any.
   #
-  # @overload new(begin, end, opts)
-  #   @param [Object] Any object (preferably {#Comparable})
-  #   @param [Object] Any object, compatible with begin
-  #   @param [Hash] see below
+  # @overload new(obj_begin, obj_end, opts)
+  #   @param obj_begin [Object] Any object (preferably {#Comparable})
+  #   @param obj_end [Object] Any object, compatible with begin
+  #   @param opts [Hash] see below
   #   @option opts [Object] :exclude_end the end boundary is excluded, if false (Default)
   #   @option opts [Object] :exclude_begin the begin boundary is excluded, if false (Default)
   #
-  # @note The above-mentioned "any" object means any object that can consist of Range.
+  # @note The here-mentioned "any" object means any object that can consist of {Range}.
   #   For example, (nil..nil) is accepted, but (Complex(2,3)..Complex(2,3)) is not.
   #
   def initialize(*inar)
@@ -90,7 +90,7 @@ class Rangesmaller < Range
           @rangepart = r
           begin
             if inar[1].has_key?(:exclude_end)
-              if inar[1][:exclude_end] != r.exclude_end?
+              if inar[1][:exclude_end] ^ r.exclude_end?
                 warn "Warning(Rangesmaller.new): Option :exclude_end is given, but is meaningless, as Range is also given."
               end
             end
@@ -139,21 +139,20 @@ class Rangesmaller < Range
 
 
   # Returns false if the "begin" boundary is excluded, or true otherwise.
-  # @return [TrueClass]
-  # @return [FalseClass]
   def exclude_begin?
     @exclude_begin
   end
 
 
-  # Return the object equivalent to the Range part (namely, without the definition of exclude_begin?)
+  # Return the object equivalent to the {Range} part (namely, without the definition of {#exclude_begin?})
   # @return [Range]
   def rangepart 
     @rangepart ||= Range.new(self.begin, self.end, self.exclude_end?)
   end
 
 
-  # Like Range, returns true only if it is either {#Rangesmaller} or {#Range}, and in addition if both {#exclude_begin?} and {#exclude_end?} match between the two objects.
+  # Like {Range}, returns true only if it is either {Rangesmaller} or {Range}, and in addition if both {#exclude_begin?} and {#exclude_end?} match between the two objects.
+  # @return [Boolean]
   def ==(r)
     if defined? r.rangepart 
       rangepart = r.rangepart 
@@ -175,7 +174,8 @@ class Rangesmaller < Range
   alias :eql? :==
 
 
-  # @see {#cover?} and {#Range#===}
+  # See also {#cover?} and {Range#===}
+  # @return [Boolean]
   def ===(obj)
     # ("a".."z")===("cc")	# => false
     begin
@@ -199,9 +199,8 @@ class Rangesmaller < Range
   alias :member? :===
 
 
-  # @note Comment on Rangesmaller#bsearch() :
-  #  bsearch is internally implemented by converting a float into 64-bit integer.
-  #  The following examples demonstrate what is going on.
+  # bsearch is internally implemented by converting a float into 64-bit integer.
+  # The following examples demonstrate what is going on.
   # 
   #    ary = [0, 4, 7, 10, 12]
   #    (3...4).bsearch{    |i| ary[i] >= 11}	# => nil
@@ -226,16 +225,16 @@ class Rangesmaller < Range
   #    (Rational(36,10)..5).bsearch{|i| ary[i] >= 11}	=> # TypeError: can't do binary search for Rational (Ruby 2.1)
   #    (3..Rational(61,10)).bsearch{|i| ary[i] >= 11}	=> # TypeError: can't do binary search for Fixnum (Ruby 2.1)
   #
-  #  In short, bsearch works only with Integer and/or Float (as in Ruby 2.1).
-  #  If either of begin and end is an Float, the search is conducted in Float and the returned value will be Float, unless nil.
-  #  If Float, it searches on the binary plane.
-  #  If Integer, the search is conducted on the descrete Integer points only,
-  #  and no search will be made in between the adjascent integers.
+  # In short, bsearch works only with Integer and/or Float (as in Ruby 2.1).
+  # If either of begin and end is an Float, the search is conducted in Float and the returned value will be Float, unless nil.
+  # If Float, it searches on the binary plane.
+  # If Integer, the search is conducted on the descrete Integer points only,
+  # and no search will be made in between the adjascent integers.
   #
-  #  Given that, Rangesmaller#bsearch follows basically the same, even when exclude_begin? is true.
-  #  If either end is Float, it searches between begin*(1+Float::EPSILON) and end.
-  #  If both are Integer, it searches from begin+1.
-  #  When exclude_begin? is false, Rangesmaller#bsearch is identical to Range#bsearch.
+  # Given that, Rangesmaller#bsearch follows basically the same, even when exclude_begin? is true.
+  # If either end is Float, it searches between begin*(1+Float::EPSILON) and end.
+  # If both are Integer, it searches from begin+1.
+  # When {#exclude_begin?} is false, {Rangesmaller#bsearch} is identical to {Range#bsearch}.
   #
   def bsearch(*rest, &bloc)
     if @exclude_begin
@@ -256,7 +255,7 @@ class Rangesmaller < Range
   end	# def bsearch(*rest, &bloc)
 
 
-  # @see {#include?} or {#===}, and {#Range#cover?}
+  # See {#include?} or {#===}, and {Range#cover?}
   def cover?(i)
     # ("a".."z").cover?("cc")	# => true
     if @exclude_begin
@@ -275,30 +274,36 @@ class Rangesmaller < Range
   end	# def cover?(i)
 
 
-  # @raise [TypeError] If {#exclude_begin?} is true, and {#begin()} or {#rangepart} does not have a method of #{succ}, then even if no block is given, this method raises TypeError straightaway.
+  # @raise [TypeError] If {#exclude_begin?} is true, and {#begin}() or {#rangepart} does not have a method of {#succ}, then even if no block is given, this method raises TypeError straightaway.
+  # @return [Rangesmaller] self
+  # @return [Enumerator] if block is not given.
   #
   def each(*rest, &bloc)
     # (1...3.5).each{|i|print i}	# => '123' to STDOUT
     # (1.3...3.5).each	# => #<Enumerator: 1.3...3.5:each>
     # (1.3...3.5).each{|i|print i}	# => TypeError: can't iterate from Float
+    # Note: If the block is not given and if @exclude_begin is true, the self in the returned Enumerator is not the same as self here.
     if @exclude_begin
       if defined? self.begin.succ
-        Range.new(self.begin.succ,self.end,exclude_end?).send(__method__, *rest, &bloc)
+        ret = Range.new(self.begin.succ,self.end,exclude_end?).send(__method__, *rest, &bloc)
+        if block_given?
+          self
+        else
+          ret
+        end
       else
         raise TypeError, "can't iterate from "+self.begin.class.name
-        # if block_given?
       end
     else
       super
     end
-    self
   end
 
 
-  # @param [Numeric] Optional.  Must be non-negative.  Consult {#Range#first} for detail.
-  # @note Like {#Range#last}, if no argument is given, it behaves like {#begin()}, that is, it returns the initial value, regardless of {#exclude_begin?}.
-  #  However, if an argument is given (nb., acceptable since Ruby 1.9) when {#exclude_begin?} is true, it returns the array that starts from {#begin()}.{#succ}.
-  # @raise [TypeError] if the argument (Numeric) is given, yet if {#begin()}.{#succ} is not defined.
+  # @param [Numeric] Optional.  Must be non-negative.  Consult {Range#first} for detail.
+  # @note Like {Range#last}, if no argument is given, it behaves like {#begin()}, that is, it returns the initial value, regardless of {#exclude_begin?}.
+  #  However, if an argument is given (nb., acceptable since Ruby 1.9) when {#exclude_begin?} is true, it returns the array that starts from {#begin}().succ().
+  # @raise [TypeError] if the argument (Numeric) is given, yet if {#begin}().succ is not defined.
   #
   def first(*rest)
     # (1...3.1).last	# => 3.1
@@ -351,7 +356,7 @@ class Rangesmaller < Range
   end	# def first(*rest)
 
 
-  # @note When {#exclude_begin?} == true, the returned value for (a<...b) is not strictly guaranteed to be unique, though in pracrtice it is most likely to be so.
+  # @note When {#exclude_begin?} is true, the returned value is not strictly guaranteed to be unique, though in pracrtice it is most likely to be so.
   # 
   def hash(*rest)
     if @exclude_begin
@@ -362,6 +367,8 @@ class Rangesmaller < Range
   end
 
 
+  # @return [String] eg., "(1<...5)", "(1<..5)", if {#exclude_begin?} is true,
+  #  or else, identical to those for {Range}.
   def inspect
     if @exclude_begin
       if exclude_end?
@@ -377,7 +384,7 @@ class Rangesmaller < Range
   alias :to_s :inspect
 
 
-  # @see {#first} for the definition when {#exclude_begin?} is true.
+  # See {#first} for the definition when {#exclude_begin?} is true.
   #
   def min(*rest, &bloc)
     # (1...3.5).max	# => TypeError: cannot exclude non Integer end value
@@ -394,7 +401,7 @@ class Rangesmaller < Range
   end
 
 
-  # @see {#first} for the definition when {#exclude_begin?} is true.
+  # See {#first} for the definition when {#exclude_begin?} is true.
   #
   def min_by(*rest, &bloc)
     # (1...3.5).max	# => TypeError: cannot exclude non Integer end value
@@ -411,7 +418,7 @@ class Rangesmaller < Range
   end
 
 
-  # @see {#first} for the definition when {#exclude_begin?} is true.
+  # See {#first} for the definition when {#exclude_begin?} is true.
   #
   def minmax(*rest, &bloc)
     # (0...3.5).minmax	# => [0, 3]
@@ -433,7 +440,7 @@ class Rangesmaller < Range
   end
 
 
-  # @see {#first} for the definition when {#exclude_begin?} is true.
+  # See {#first} for the definition when {#exclude_begin?} is true.
   #
   def minmax_by(*rest, &bloc)
     # (0...3.5).minmax	# => [0, 3]
@@ -454,8 +461,8 @@ class Rangesmaller < Range
   end	# def minmax_by(*rest)
 
 
-  # @see {#first} for the definition when {#exclude_begin?} is true.
-  # @see [ruby-list:49797] from matz for how {#size} behaves.
+  # See {#first} for the definition when {#exclude_begin?} is true.
+  # @see http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-list/49797 [ruby-list:49797] from matz for how {#size} behaves (in Japanese).
   #
   def size(*rest)
     # (1..5).size	# => 5
@@ -505,19 +512,26 @@ class Rangesmaller < Range
   end	# def size
 
 
-  # @raise [TypeError] If {#exclude_begin?} is true, and {#begin()} or {#rangepart} does not have a method of #{succ}, then even if no block is given, this method raises TypeError straightaway.
-  # @see {#each}.
+  # See {#each}.
+  # @raise [TypeError] If {#exclude_begin?} is true, and {#begin}() or {#rangepart} does not have a method of {#succ}, then even if no block is given, this method raises TypeError straightaway.
+  # @return [Rangesmaller] self
+  # @return [Enumerator] if block is not given.
   #
   def step(*rest, &bloc)
     # (1...3.5).each{|i|print i}	# => '123' to STDOUT
     # (1.3...3.5).each	# => #<Enumerator: 1.3...3.5:each>
     # (1.3...3.5).each{|i|print i}	# => TypeError: can't iterate from Float
+    # Note: If the block is not given and if @exclude_begin is true, the self in the returned Enumerator is not the same as self here.
     if @exclude_begin
       if defined? self.begin.succ
-        Range.new(self.begin.succ,self.end,exclude_end?).send(__method__, *rest, &bloc)
+        ret = Range.new(self.begin.succ,self.end,exclude_end?).send(__method__, *rest, &bloc)
+        if block_given?
+          self
+        else
+          ret
+        end
       else
         raise TypeError, "can't iterate from "+self.begin.class.name
-        # if block_given?
       end
     else
       super
@@ -529,12 +543,14 @@ end	# class Rangesmaller < Range
 
 
 #
-#=== Redefine a method {#==} so as to handle {#Rangesmaller}.
+#=== Redefine a method {#==} so as to handle a comparison with {Rangesmaller}.
 #
 class Range
 
   alias :eql_orig? :==
 
+  # When compared with a {Rangesmaller} object, it compares with {Rangesmaller#rangepart}.
+  # Namely, if {#begin}, {#end}, {#exclude_end?} agree between them and if {Rangesmaller#exclude_begin?} of the argument is false, it returns true, or false otherwise.
   def eql?(r)
     if defined? r.exclude_begin?
       if r.exclude_begin?

data/rangesmaller.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |s|
   s.name = %q{rangesmaller}
-  s.version = "1.0.0"
+  s.version = "1.0.2"
   # s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   # s.executables << 'hola'
   # s.bindir = 'bin'

data/test/test_rangesmaller.rb

@@ -287,8 +287,10 @@ p $LOADED_FEATURES.grep(/#{Regexp.quote(libfilebase)}$/)
       assert_equal(@r12.reduce(:+), ns)
       ns=0; @s21.each{|i| ns+=i}
       assert_equal(((@ib+1)..@ie).reduce(:+), ns)
-      ns=0; @s22.each{|i| ns+=i}
+      ns=0; ret=@s22.each{|i| ns+=i}
       assert_equal(((@ib+1)...@ie).reduce(:+), ns)
+      assert_equal(@s22, ret)
+      assert(Enumerator === @s22.each)
 
       ## Arbitrary Class
       sx1 = Rangesmaller.new(Xs.new(3), Xs.new(6), :exclude_begin => true, :exclude_end => true)
@@ -502,8 +504,10 @@ p $LOADED_FEATURES.grep(/#{Regexp.quote(libfilebase)}$/)
       assert_equal(1+3+5, ns)
       ns=0; @s21.step(2){|i| ns+=i}
       assert_equal(2+4+6, ns)
-      ns=0; @s22.step(2){|i| ns+=i}
+      ns=0; ret=@s22.step(2){|i| ns+=i}
       assert_equal(2+4, ns)
+      assert_equal(@s22, ret)
+      assert(Enumerator === @s22.step(2))
 
       ## Arbitrary Class
       sx1 = Rangesmaller.new(Xs.new(3), Xs.new(6), :exclude_begin => true, :exclude_end => true)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rangesmaller
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.2
 platform: ruby
 authors:
 - Masa Sakano
@@ -51,3 +51,4 @@ specification_version: 4
 summary: Rangesmaller class -- Range with include_begin?()
 test_files:
 - test/test_rangesmaller.rb
+has_rdoc: