range_extd 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ddcd6d0416bca878881275877c7b388867fbd51d
-  data.tar.gz: 68631346bbd9735b6362e179294b854429a36d47
+  metadata.gz: c920255a38ca8b0805d5cfe50d4fbabd4718417f
+  data.tar.gz: 47fa8995de09e68a381144751fffe86e42082804
 SHA512:
-  metadata.gz: 0b0b845ea47998f05ffdbcbf4adddafd129ba25418df63fdaaefb21748aa84d9a133618e880edd2009701141a9e1209ca6b67194f57b4c07da2fde4cc1a2c7b3
-  data.tar.gz: cfccffebf7081da3260b93f939a25e7c4f0c7374437a1a264786b727b5bfa7a362b41285d94bc04e868ef36eb44c264a4187351c08d08144011cae5f0b727887
+  metadata.gz: bf51ff3e606ec3b1955fe0978a407ec60130eacf0591fb3c5f85f927f890043e4adc6bd88a094ab14e19d954f40bef24e94048e0078ac8cfcbe0fcb775fccb3a
+  data.tar.gz: c8ac4fb7471a7246b5d238b3acbc7a97355e59d4addf10e8075c3376edfcdcdb8291b631921c76cac5b099ac21ca538dc07f30dddb87e7162844de71f5eb7099

data/ChangeLog

@@ -1,6 +1,12 @@
+-----
+(Version: 0.1.1)
+2014-04-28  Masa Saskano
+ * Merging Japanese README into the same file as the English one.
+
 -----
 (Version: 0.1.0)
-2014-04-27  Masa Saskano
+2014-04-27  Masa Sakano
+
  * Fix range_extd.gemspec
 
 -----

data/README.ja.rdoc

@@ -1,4 +1,322 @@
 
+= RangeExtd - Extended Range class with exclude_begin and open-ends
+
+This package contains RangeExtd class, the Extended Range class that features:
+
+ 1. includes exclude_begin? (to exclude the "begin" boundary),
+ 2. allows open-ended range (to the infinity),
+ 3. defines NONE and EVERYTHING constants,
+ 4. the first self-consistent logical structure,
+ 5. complete backward-compatibility within the built-in Range.
+
+With the introduction of the excluded status of begin, in addition
+to the end as in built-in Range, and open-ended feature,
+the logical completeness of the 1-dimensional range is realised.
+
+Then the validity of range is strictly defined now.
+Following that, this package adds a few methods, most notably
+{Range#valid?} and {Range#empty?}
+to Range, and accordingly its any sub-classes,
+
+For example, <tt>(3...3).valid?</tt>  returns false, because the element 3 is
+inclusive for the begin boundary, yet exclusive for the end boundary,
+which are contradictory to each other.  With this RangeExtd class,
+it is expressed as a valid range,
+* RangeExtd.new(3, 3, true,  true)   # => an empty range
+* RangeExtd.new(3, 3, false, false)  # => a single-point range (3..3)
+
+However, as long as it is within built-in Range, nothing has changed,
+so it is completely compatible with the standard Ruby.
+
+To express open-ended ranges is simple; you just use either of
+the two (negative and positive, or former and later) constants
+defined in the class {RangeExtd::Infinity}
+* RangeExtd::Infinity::NEGATIVE
+* RangeExtd::Infinity::POSITIVE
+
+They are basically the object that generalised <tt>Float::INFINITY</tt> to
+any Comparable object.  For example,
+   ("a"..RangeExtd::Infinity::POSITIVE).each
+gives an infinite iterator with <tt>String#succ</tt>, starting from "a"
+(therefore, make sure to code so it breaks the iterator at one stage!).
+
+
+The built-in Range class is very useful, and has given Ruby users
+a power to make easy coding.  Yet, the lack of definition of
+exclusive begin boundary is a nuisance in some cases.
+
+Having said that, there is a definite and understandable reason;
+Range in Ruby is not limited at all to Numeric (or strictly speaking,
+Real number or its representative).  Range with any object that has a method
+of <tt>succ()</tt> is found to be useful, whereas there is no reverse method for
+<tt>succ()</tt> in general.
+In that sense Range is inherently not symmetric.  In addition
+some regular Range objects are continuous (like Float), while others are discrete
+(like Integer or String).  That may add some confusion to the strict definition.
+
+To add the feature of the exclusive begin boundary is in that sense
+not 100 per cent trivial.  The definition I adopt for the behaviour of
+RangeExtd is probably not the only solution.  Personally, I am content
+with it, and I think it achieves the good logical completeness within the frame.
+
+I hope you find it to be useful.
+
+
+== Install
+
+  gem install range_extd
+
+Two files
+  range_extd/range_extd.rb
+  range_extd/infinity/infinity.rb
+should be installed in one of your <tt>$LOAD_PATH</tt> 
+
+Alternatively get it from
+  http://rubygems.org/gems/range_extd
+
+Then all you need to do is
+  require 'range_extd/range_extd'
+or, possibly as follows, if you manually install it
+  require 'range_extd'
+in your Ruby script (or irb).  The other file
+  range_extd/infinity/infinity.rb
+is called (required) from it automatically.
+
+Have fun!
+
+
+== Simple Examples
+
+=== How to create a RangeExtd instance
+
+Here are some simple examples.
+
+   r = RangeExtd(?a...?d, true)  # => a<...d
+   r.exclude_begin?              # => true 
+   r.to_a                        # => ["b", "c"]
+   RangeExtd(1...2)            == (1...2)          # => true
+   RangeExtd(1, 2, false, true)== (1...2)          # => true
+   RangeExtd(1, 1, false, false)==(1..1)           # => true
+   RangeExtd(1, 1, true, true) == RangeExtd::NONE  # => true
+   RangeExtd(1, 1, false, true)  # => ArgumentError
+   (RangeExtd::Infinity::NEGATIVE..RangeExtd::Infinity::POSITIVE) \
+    == RangeExtd::EVERYTHING  # => true
+
+Basically, there are two forms:
+
+   RangeExtd(range, [exclude_begin=false, [exclude_end=false]])
+   RangeExtd(obj_begin, obj_end, [exclude_begin=false, [exclude_end=false]])
+
+The last two parameters specify the respective boundary to be excluded if true,
+or included if false (Default).  If they contradict to the first
+parameter of the range (Range or RangeExtd), those latter two parameters are used.
+<tt>RangeExtd.new()</tt> is the same thing.
+
+=== Slightly more advanced uses
+
+   (1..RangeExtd::Infinity::POSITIVE).each do |i|
+     print i
+     break if i >= 9
+   end    # => self ( "123456789" => STDOUT )
+   (nil..nil).valid?  # => false
+   (1...1).valid?     # => false
+   (1...1).null?      # => true
+   RangeExtd.valid?(1...1)              # => false
+   RangeExtd(1, 1, true, true).valid?   # => true
+   RangeExtd(1, 1, true, true).empty?   # => true
+   RangeExtd(?a, ?b, true, true).to_a?  # => []
+   RangeExtd(?a, ?b, true, true).empty? # => true
+   RangeExtd(?a, ?e, true, true).to_a?  # => ["b", "c", "d"]
+   RangeExtd(?a, ?e, true, true).empty? # => false
+   RangeExtd::NONE.is_none?             # => true
+   RangeExtd::EVERYTHING.is_everything? # => true
+
+All the methods that are in the built-in Range can be used.
+
+
+== Description
+
+Once the file range_extd.rb is required, the two classes are defined:
+
+* RangeExtd
+* RangeExtd::Infinity
+
+Also, several methods are added or altered in Range class.
+All the changes made in Range are backward-compatible with the original.
+
+=== RangeExtd::Infinity Class
+
+Class {RangeExtd::Infinity} has basically only two constant instances.
+
+* RangeExtd::Infinity::NEGATIVE
+* RangeExtd::Infinity::POSITIVE
+
+They are the objects that generalise the concept of
+<tt>Float::INFINITY</tt> 
+to any Comparable objects.  The methods <tt><=></tt> and <tt>succ</tt>  are defined.
+
+You can use them the same as other objects, such as,
+  ("k"..RangeExtd::Infinity::POSITIVE)
+However as they do not have any other methods,
+the use out of Range-type class is probably meaningless.
+
+Note for any Numeric object, please use <tt>Float::INFINITY</tt> instead in principle.
+
+Any objects in any user-defined Comparable class are commutatively comparable with
+those two constants, as long as the cmp method of the class is written
+politely.
+
+For more detail, see its documents (YARD or RDoc-style
+documents embedded in the code, or see RubyGems webpage).
+
+
+=== RangeExtd Class
+
+RangeExtd objects are immutable, the same as Range.
+Hence once an instance is created, it would not change.
+
+How to create an instance is explained above (in the Examples
+sections).  Any attempt to try to create an instance that is not
+"valid" as a range (see below) raises an exception (<tt>ArgumentError</tt>), and fails.
+
+There are two constants defined in this class:
+
+* RangeExtd::NONE
+* RangeExtd::EVERYTHING
+
+The former represents the empty range and the latter does the range
+covers everything, namely open-ended for the both negative and
+positive directions.
+
+In addition to all the standard methods of Range, the following
+methods are added to both RangeExtd and Range classes.
+See the document of each method for detail (some are defined only in
+Range class, as RangeExtd inherits it).
+
+* <tt>exclude_begin?</tt> 
+* <tt>valid?</tt> 
+* <tt>empty?</tt> 
+* <tt>null?</tt> 
+* <tt>is_none?</tt> 
+* <tt>is_everything?</tt> 
+
+There is a class method, which is equivalent to the instance
+method <tt>valid?</tt>.
+* <tt>RangeExtd.valid?</tt> 
+
+What is valid (<tt>#valid?</tt> => true) as a range is defined as follows.
+
+1. Both <tt>begin</tt> and <tt>end</tt> elements must be Comparable to each other,
+   and the comparison results must be consistent between the two.
+   The sole exception is {RangeExtd::NONE}, which is valid.
+   For example, <tt>(nil..nil)</tt> is NOT valid (nb., it raised Exception in Ruby 1.8).
+2. begin must be smaller than or equal (<tt>==</tt>) to end,
+   that is, <tt>(begin <=> end)</tt> must be either -1 or 0.
+3. If begin is equal to end, namely, <tt>(begin <=> end) == 0</tt>,
+   the exclude status of the both ends must agree.
+   That is, if the <tt>begin</tt> is excluded, <tt>end</tt> must be also excluded,
+   and vice versa.
+   For example, <tt>(1...1)</tt> is NOT valid for that reason,
+   because any built-in Range object has the exclude status
+   of false (namely, inclusive) for <tt>begin</tt>.
+
+For more detail and examples see the documents of
+{RangeExtd.valid?} and {Range#valid?} 
+
+The definition of what is empty (<tt>#empty?</tt> => true) as a range is as follows;
+
+1. the range must be valid: <tt>valid?</tt> => true
+2. if the range id discrete, that is, begin has
+   <tt>succ</tt> method, there must be no member within the range
+   (which means the begin must be excluded, too): 
+   <tt>to_a.empty?</tt> => true
+3. if the range is continuous, that is, begin does not have
+   <tt>succ</tt> method, begin and end must be equal
+   (<tt>(begin <=> end)</tt> => 0) and both the boundaries must
+   be excluded: <tt>(exclude_begin? && exclude_end?)</tt> => true.
+
+Note that ranges with equal <tt>begin</tt> and <tt>end</tt> with inconsistent two
+exclude status are not valid, as mentioned in the previous paragraph.
+The built-in Range always has the begin-exclude status of
+<tt>false</tt>.  For that reason, no instance of built-in Range 
+has the status of <tt>empty?</tt> of <tt>true</tt>.
+
+For more detail and examples see the documents of
+{Range#empty?} 
+
+Finally, {Range#null?} is equivalent to "either empty or not valid".
+Therefore, for RangeExtd objects <tt>null?</tt> is equivalent to
+<tt>empty?</tt>.
+
+In comparison (<tt><=></tt>) between a RangeExtd and another RangeExtd or Range
+object, those definitions are taken into account.
+Some of them are shown in the above Examples section.
+For more detail, see {Range#==}> and {RangeExtd#==}>, as
+well as <tt>#eql?</tt>.
+
+Note that as long as the operation is within Range objects, the
+behaviour is identical to the standard Ruby -- it is completely
+compatible.  Therefore, requiring this library would not affect any
+existing code in principle.
+
+
+== Known bugs
+
+* <tt>hash()</tt> method does not always guarantee to return a unique
+  and exclusive number for the equal RangeExtd object, though such an
+  exception is extremely unlikely to happen in reality.
+
+Note this library does not work in Ruby 1.8 or earlier.
+For Ruby 1.9.3 it is probably all right, however I have never tested
+it.
+
+Extensive tests have been performed, as included in the package.
+
+
+== ToDo
+
+Nothing planned.
+
+
+== Final notes
+
+All the behaviours within RangeExtd (not Range), such as
+any comparison between two RangeExtd, should be (or hopefully?)
+natural for you.  At least it is well-defined and self-consistent, as
+the logical structure of the ranges is now complete with RangeExtd.
+Note some behaviours for open-ended or begin-excluded ranges may
+give you a little shock at first.  For example, the method
+<tt>member?(obj)</tt> for an open-ended range for the negative direction with
+discrete elements returns <tt>nil</tt>.  That is because no meaningful method
+of <tt>succ()</tt> is defined for the (negative) infinity, hence it is
+theoretically impossible in general to check whether the given obj is a member of
+the range or not.  You may find it to be weird, but that just means
+the concept of the infinity is unfamiliar to us mortals!
+
+On the other hand, the comparison between RangeExtd and Range may have
+more occasional surprises.  That is because some of the accepted
+ranges by built-in Range class are no longer valid in this framework with the
+inclusion of exclude-status of the begin boundary, as explained.
+Hopefully you will feel it to be natural as you get accustomed to it.
+And I bet once you have got accustomed to it, you will never want to
+go back to the messy world of logical incompleteness, that is, the
+current behaviour of Range!
+
+Enjoy.
+
+
+
+== Miscellaneous
+
+== Copyright etc
+
+Author::  Masa Sakano < imagine a_t sakano dot co dot uk >
+License:: MIT.
+Warranty:: No warranty whatsoever.
+Versions:: The versions of this package follow Semantic Versioning (2.0.0) http://semver.org/
+
+
+
 = RangeExtd - 拡張Rangeクラス - exclude_begin と無限大に開いた範囲と
 
 このパッケージは、Range を拡張した RangeExtd クラスを定義しています。

data/lib/range_extd/infinity/infinity.rb

@@ -31,17 +31,17 @@ class RangeExtd < Range
   # respectively, than any other Comparable objects (1 or -1 by i{#<=>}(obj))
   # except for infinities with the same polarity, that is, positive or negative,
   # in which case 0 is returned.
-  # See the document of the method #{==} for the definition of "infinity".
+  # See the document of the method {#==} for the definition of "infinity".
   # Also, {#succ} is defined, which just returns self.
   #
   # There is a note of caution.
   # The method {#<=>} is defined in this class as mentioned above.
-  #  However any operator is, by Ruby's definition, not commutative,
+  # However any operator is, by Ruby's definition, not commutative,
   # unless both the classes define so.
   #
   # There are only two built-in classes that are Comparable: String and Numeric
   # (except for Complex).
-  # For String class objects, the #{<=>} operator work as expected
+  # For String class objects, the [#<=>] operator work as expected
   # in the commutative way.
   #    ?z <=> RangeExtd::Infinity::POSITIVE    # => nil
   #    RangeExtd::Infinity::POSITIVE <=> ?z    # => 1.
@@ -66,7 +66,7 @@ class RangeExtd < Range
   # whether you or authors of libraries.
   # The comparison with {RangeExtd::Infinity} instances are
   # implemented in {Object#<=>} in this library.  Hence, as long as
-  # the method <=> in the classes is written sensibly, that is, if it
+  # the method [#<=>] in the classes is written sensibly, that is, if it
   # respects the method of the super-class when it does not know
   # how to deal with an unknown object, there is no need for
   # modification.  Any object in your class (say, YourComparable) 
@@ -84,11 +84,11 @@ class RangeExtd < Range
   # For that sort of circumstances,
   # the class method {RangeExtd::Infinity.overwrite_compare} provides
   # a convenient way to overcome this problem to make
-  # the operator <=> commutative for a given Comparable class.
+  # the operator [#<=>] commutative for a given Comparable class.
   #
   # Note {RangeExtd::Infinity.overwrite_compare} does nothing for the classes
   # registered in the Class constant Array {RangeExtd::Infinity::CLASSES_ACCEPTABLE}.
-  # So, if you want to avoid such modification of the method <=>, perhaps
+  # So, if you want to avoid such modification of the method [#<=>], perhaps
   # by some other end users, you can register the class in that array.
   #
   # Only the methods defined in this class are
@@ -129,7 +129,7 @@ class RangeExtd < Range
 
     # Always -1 or 1 except for itself and the corresponding infinities (== 0).  See {#==}.
     # Or, nil (as defined by Object), if the argument is not Comparable, such as, nil and IO.
-    # @return [Integer] or possibly nil.
+    # @return [Integer, nil]
     def <=>(c)
       if c.nil?
         super
@@ -189,7 +189,7 @@ class RangeExtd < Range
     alias :to_s :inspect
   
 
-  # Overwrite "<=>" method of the given class, if necessary,
+  # Overwrite [#<=>] method of the given class, if necessary,
   # to make its instances be comparable with RangeExtd::Infinity objects (constants).
   # For example,
   #   RangeExtd::Infinity::NEGATIVE.<=>(any_comparable)
@@ -199,7 +199,7 @@ class RangeExtd < Range
   # Therefore, this function (Class method) provides a convenient
   # way to overcome it, that is, if the given class
   # (or the class of the given object) is Comparable,
-  # its "<=>" method is modified (and true is returned),
+  # its [#<=>] method is modified (and true is returned),
   # unless it has been already done so, or some classes as listed below,
   # such as Numeric and String, in which case nil is returned.
   # If it is not Comparable, false is returned.
@@ -214,7 +214,7 @@ class RangeExtd < Range
   # the class in the array.
   #
   # @param obj [Object] Either Class or its object.
-  # @return [Boolean] or possibly nil (see the description).
+  # @return [Boolean, nil] (see the description).
   def self.overwrite_compare(obj)
     if defined? obj.instance_methods
       klass = obj
@@ -315,21 +315,21 @@ end	# class RangeExtd < Range
 #
 # = class Object
 #
-# Overwrite Object#<=>() so all its sub-classes can be
-# aware of RangeExtd::Infinity objects (the two constants).
+# Overwrite {Object#<=>}() so all its sub-classes can be
+# aware of {RangeExtd::Infinity} objects (the two constants).
 #
 class Object
   alias :compare_obj_before_infinity :==  if ! self.method_defined?(:compare_obj_before_infinity)	# No overwriting.
 
-  # Overwrite #{Object#<=>}().  Then, all its sub-classes can be
+  # Overwrite {Object#<=>}().  Then, all its sub-classes can be
   # aware of RangeExtd::Infinity objects (the two constants).
   #
-  # In this definition of "<=>", if self is Comparable
-  # (by judging whether it has the method "<="),
+  # In this definition of {#<=>}, if self is Comparable
+  # (by judging whether it has the method [#<=]),
   # it always returns, unless infinity? and positive? are set
   # accordingly, either -1 or 1, depending which of
   #   RangeExtd::Infinity::(NEGATIVE|POSITIVE)
-  # is compared.  If self is not Comparable, the original "<=>"
+  # is compared.  If self is not Comparable, the original [#<=>]
   # is called, which should return nil (unless both the object_id
   # agree, eg., nil and nil, in which case 0 is returned).
   #
@@ -337,6 +337,7 @@ class Object
   # define the method "<=>" as follows, as in the standard practice
   # when you redefine a method that exists in a superclass;
   #
+  # @example A method definition of user-defined Comparable class
   #    class MyComparableClass 
   #      include Comparable
   #      # alias :cmp_orig :<=> if !self.method_defined?(:cmp_orig)	# if you want

data/lib/range_extd/range_extd.rb

@@ -71,10 +71,7 @@ end
 # the two (negative and positive, or former and later) constants
 # in RangeExtd::Infinity class.  See the document for detail.
 #
-# ==Examples
-#
-# An instance of a range of 5 to 8 with both ends being exclusive is created as
-#
+# @example An instance of a range of 5 to 8 with both ends being exclusive is created as
 #   r = RangeExtd(5...8, true) 
 #   r.exclude_begin?  # => true 
 #
@@ -145,6 +142,7 @@ class RangeExtd < Range
 
   # true if self is identical to {RangeExtd::NONE}.
   # This is different from {#==} method!
+  # @example 
   #    RangeExtd(0,0,false,false) == RangeExtd::NONE  # => true
   #    RangeExtd(0,0,false,false).empty?    # => true
   #    RangeExtd(0,0,false,false).is_none?  # => false
@@ -153,7 +151,8 @@ class RangeExtd < Range
     self.begin.nil? && self.end.nil? && @exclude_begin && @exclude_end	# Direct comparison with object_id should be OK?
   end
 
-  # true if self is identical to RangeExtd::EVERYTHING ({#==} does not mean it at all!)
+  # true if self is identical to {RangeExtd::EVERYTHING} ({#==} does not mean it at all!)
+  # @example
   #    (RangeExtd::Infinity::NEGATIVE..RangeExtd::Infinity::POSITIVE).is_everything?  # => false
   def is_everything?
     self.begin.object_id == Infinity::NEGATIVE.object_id && self.end.object_id == Infinity::POSITIVE.object_id && !@exclude_begin && !@exclude_end	# Direct comparison with object_id should not work for this one!! (because users can create an identical one.)
@@ -179,7 +178,11 @@ class RangeExtd < Range
   # this returns true, regardless of their boundary values.
   # And any empty range is equal to RangeExtd::Infinity::NONE.
   # 
-  # For example,
+  # Note the last example will return false for {#eql?} -- see {#eql?}
+  # 
+  # See {#eql?}
+  # 
+  # @example
   #   (1<...1)   == RangeExtd::NONE # => true
   #   (?a<...?b) == RangeExtd::NONE # => true
   #   (1<...1) == (2<...2)     # => true
@@ -188,9 +191,6 @@ class RangeExtd < Range
   #   (1<...1) != (?c<...?c)   # - because of Fixnum and String
   #   (1.0<...1.0) == (3<...4) # => true
   # 
-  # Note the last example will return false for {#eql?} -- see {#eql?}
-  # 
-  # See {#eql?}
   # @return [Boolean]
   def ==(r)
     re_equal_core(r, :==)
@@ -201,6 +201,7 @@ class RangeExtd < Range
   # the immediate class has to agree to return true.
   # Only the exception is the comparison with RangeExtd::Infinity::NONE.
   # Therefore, 
+  # @example
   #   (1...5) ==  (1.0...5.0)  # => true
   #   (1...5).eql?(1.0...5.0)  # => false
   #   (1<...1).eql?(  RangeExtd::NONE)  # => true
@@ -221,15 +222,15 @@ class RangeExtd < Range
   # In the standard Range, this checks whether the given object is a member, hence,
   #    (?D..?z) === ?c    # => true
   #    (?a..?z) === "cc"  # => false
-  # In the case of the former, after finite trials of succ() from ?c, it reaches the end (?z).
-  # In the latter, after finit trials of succ() from the begin ?a, it reaches the end (?z).
+  # In the case of the former, after finite trials of [#succ] from ?c, it reaches the end (?z).
+  # In the latter, after finit trials of [#succ] from the begin ?a, it reaches the end (?z).
   # Therefore it is theoretically possible to prove it (n.b., the actual
   # algorithm of built-in {Range#include?} is different and cheating!
   # See below.).
   #
   # However, in the case of
   #    (?D..Infinity) === ?c
-  # it can never prove ?c is a member after infinite trials of succ(),
+  # it can never prove ?c is a member after infinite trials of [#succ],
   # whether it starts the trials from the begin (?D) or the object (?c).
   #
   # For anything but Numeric, use {#cover?} instead.
@@ -238,7 +239,7 @@ class RangeExtd < Range
   #    (?B..?z) === 'dd'  # => false
   # as Ruby's {Range} knows the algorithm of {String#succ} and {String#<=>}
   # and specifically checks with it, before using {Enumerable#include?}.
-  # @see https://github.com/ruby/ruby/blob/trunk/range.c
+  # {https://github.com/ruby/ruby/blob/trunk/range.c}
   #
   # Therefore, even if you change the definition of {String#succ}
   # so that 'B'.succ => 'dd', 'dd'.succ => 'z', as follows,
@@ -262,7 +263,8 @@ class RangeExtd < Range
   #   (?X..?z).each do |i| print i;end  # => "XYZ[\]^_`abcdefghijklmnopqrstuvwxyz"
   #   ?Z.succ  # => 'AA'
   #
-  # @param obj [Object] If this Object is a member?
+  # @param [Object] obj If this Object is a member?
+  # @return [Boolean]
   def ===(obj)
     # ("a".."z")===("cc")	# => false
 
@@ -337,7 +339,7 @@ class RangeExtd < Range
   # 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, RangeExtd#bsearch follows basically the same, even when exclude_begin? is true.
+  # Given that, {RangeExtd#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, {RangeExtd#bsearch} is identical to {Range#bsearch}.
@@ -420,8 +422,9 @@ class RangeExtd < Range
   # 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 and if {#exclude_begin?} is true, yet if {#begin}().succ is not defined, or yet if {#none}?
-  # @param [Numeric] Optional.  Must be non-negative.  Consult {Range#first} for detail.
-  #
+  # @param [Integer] Optional.  Must be non-negative.  Consult {Range#first} for detail.
+  # @return [Object] if no argument is given, equivalent to {#end}.
+  # @return [Array] if an argument is given.
   def first(*rest)
     # (1...3.1).last	# => 3.1
     # (1...3.1).last(1)	# => [3]
@@ -491,7 +494,8 @@ class RangeExtd < Range
   # an argument in practice, the number of the members of the returned array.
   #
   # @raise [TypeError] If self.begin.succ is not defined, or if either side is Infinity.
-  # @return [Object] if no argument is given, equivalent to {#end}.  Otherwise Array.
+  # @return [Object] if no argument is given, equivalent to {#end}.
+  # @return [Array] if an argument is given.
   def last(*rest)
     return nil if null?
     nSize = rest.size
@@ -568,7 +572,8 @@ class RangeExtd < Range
   # 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 {Range#size} behaves (in Japanese).
   #
-  # @return [Integer] or nil if the range is non-Numeric.  0 if RangeExtd::NONE.
+  # @return [Integer]  0 if {RangeExtd::NONE}
+  # @return [nil] if the range is non-Numeric.
   def size(*rest)
     # (1..5).size	# => 5
     # (1...5).size	# => 4
@@ -744,7 +749,9 @@ class RangeExtd < Range
   #    because any built-in Range object has the exclude status
   #    of false (namely, inclusive) for {#begin}.
   #
-  # === Examples
+  # Note the last example may change in the future release.
+  #
+  # @example
   #
   #    RangeExtd.valid?(nil..nil)     # => false
   #    RangeExtd.valid?(nil...nil)    # => false
@@ -760,8 +767,6 @@ class RangeExtd < Range
   #    RangeExtd.valid?(RangeExtd::Infinity::NEGATIVE..?d)        # => true
   #    RangeExtd.valid?(RangeExtd::Infinity::NEGATIVE..?d, true)  # => true
   #
-  # Note the last example may change in the future release.
-  #
   # @overload new(range, [exclude_begin=false, [exclude_end=false]])
   #   @param [Object] range Instance of Range or its subclasses, including RangeExtd
   #   @param exclude_begin [Object] true or false(Default) or any
@@ -821,8 +826,7 @@ class RangeExtd < Range
   private
 
   # Core routine for {#inspect} and {#to_s}
-  # @param r [Object] to compare.
-  # @param method [Symbol] of the method name.
+  # @param [Symbol] method the method name.
   def re_inspect_core(method)
     if @exclude_end
       midStr = "..."
@@ -840,8 +844,8 @@ class RangeExtd < Range
 
 
   # Core routine for {#===} and {#eql?}
-  # @param r [Object] to compare.
-  # @param method [Symbol] of the method name.
+  # @param [Object] r to compare.
+  # @param [Symbol] method of the method name.
   def re_equal_core(r, method)
     if defined? r.empty?
       is_r_empty = r.empty?
@@ -964,9 +968,10 @@ class Range
   #
   # See {RangeExtd.valid?} for the definition of what is valid
   # and more examples.
+  #
+  # See {#empty?} and {#null?}, too.
   # 
-  # === Examples
-  # 
+  # @example
   #    (nil..nil).valid? # => false
   #    (0..0).valid?     # => true
   #    (0...0).valid?    # => false
@@ -975,8 +980,6 @@ class Range
   #    (3..Float::INFINITY).valid?   # => true
   #    RangeExtd::NONE.valid?        # => true
   #    RangeExtd::EVERYTHING.valid?  # => true
-  #
-  # See {#empty?} and {#null?}, too.
   # 
   # @note By definition, all the {RangeExtd} instances are valid,
   #  because {RangeExtd#new} checks the validity.
@@ -1005,8 +1008,7 @@ class Range
   #
   # In these conditions, none of Range instance would return true in {#empty}.
   #
-  # === Examples
-  #
+  # @example
   #   (nil..nil).empty?  # => nil
   #   (1...1).empty?     # => nil
   #   (1..1).empty?      # => false
@@ -1018,6 +1020,8 @@ class Range
   #
   # @note to check whether it is either empty or invalid, use {#null?}.
   # See {#valid?} and {RangeExtd.valid}, too.
+  #
+  # @return [Boolean, nil]
   def empty?
     # This is basically for the sake of sub-classes, as any built-in Range instance
     # always returns either nil or false.

data/range_extd.gemspec

@@ -2,12 +2,12 @@
 
 Gem::Specification.new do |s|
   s.name = %q{range_extd}
-  s.version = "0.1.0"
+  s.version = "0.1.1"
   # s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   # s.executables << 'hola'
   # s.bindir = 'bin'
   s.authors = ["Masa Sakano"]
-  s.date = %q{2014-04-27}
+  s.date = %q{2014-04-28}
   s.summary = %q{RangeExtd - Extended Range class with exclude_begin and open-ends}
   s.description = %q{This defines a subclass of Range, RangeExtd and its subclass, RangeExtd::Infinity.  The former defines a range that enables an exclusion of the begin boundary, in addition to the end boundary as in the built-in Range, and accepts open-ended ranges to infinity for either (or both) positive/negative direction.  The latter has the two constant objects, POSITIVE and NEGATIVE, and they are a generalised Infinity of Float::INFINITY to any Comparable objects.}
   # s.email = %q{abc@example.com}

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: range_extd
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Masa Sakano
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-04-27 00:00:00.000000000 Z
+date: 2014-04-28 00:00:00.000000000 Z
 dependencies: []
 description: This defines a subclass of Range, RangeExtd and its subclass, RangeExtd::Infinity.  The
   former defines a range that enables an exclusion of the begin boundary, in addition