Rangesmaller - Range with exclude_begin (obsolete for Ruby 2)

This package contains Rangesmaller class, a sub-class of Range and that behaves almost exactly like the super-class Range class, but holds an additional status of whether the boundary of the beginning of the object is included or excluded.

NOTE: This package is obsolete for Ruby 2.0 and above. Please use range_extd package instead.: https://rubygems.org/gems/range_extd

Rangesmaller objects are immutable, just like Range. Hence once the object is created, it would not change.

Any (pair of) objects that can consist of Range can be given in initialising, though that does not mean it would always successfully run any methods, like (nil..nil).each().

Two methods are added from the original Range:

:exclude_begin?  # => true or false(Default)
:rangepart       # Range object without the flag of :exclude_begin?

In default, both the begin and end boundaries are inclusive, unless specified otherwise in creating it.

Install

gem install rangesmaller

A file

rangesmaller/rangesmaller.rb

should be installed in one of your $LOAD_PATH

Alternatively get it from

http://rubygems.org/gems/rangesmaller

Then all you need to do is

require 'rangesmaller/rangesmaller'

or, possibly as follows, if you manually install it

require 'rangesmaller'

in your Ruby script (or irb).

Have fun!

Simple Example

How to create an instance

Almost all you need to know is this:

r = Rangesmaller(5...8, :exclude_begin => true) 
r.exclude_begin?  # => true

Other forms are as follows:

r1 = Rangesmaller.new((r0=(1..5)), :exclude_begin => false)
r2 = Rangesmaller.new(r1)
r3 = Rangesmaller.new(1, 5, exclude_end=false)    # This form is not recomended (only for compatibility with Range).
r4 = Rangesmaller.new(1, 5, :exclude_begin => true, :exclude_end => false)
r5 = Rangesmaller(    1, 5, :exclude_begin => true) 
r7 = Rangesmaller.new((?a...?z), :exclude_begin => true)
r8 = Rangesmaller.new(r0, :exclude_end => true)   # => warning (r0.exclude_end? is used)

Note: in the last example of new(), it issues a warning. In this case a Range object is given in new(); accordingly the status of :exclude_end? of the created Rangesmaller object is inherited from the given Range object, whereas the option given contradicts to it. What you should do instead is,

r8 = Rangesmaller.new(r0.begin, r0.end, :exclude_end => true)

They are evaluated as follows:

r1 == r0   # => true
r1 == r2   # => true
r1 == r3   # => true
r1 == r8   # => true
r1 == r4   # => false
r4 == r5   # => true

r1.exclude_end?      # => false
r1.exclude_begin?    # => false
r4.exclude_begin?    # => true
r1.rangepart    # => (1..5)
r4.rangepart    # => (1..5)

General operation

s1 = Rangesmaller(1..5, :exclude_begin => true)	# => 1<...5
s1.size     # => 3
s1.to_a     # => [2, 3, 4]
s1.begin    # => 1
s1.first(2) # => [2, 3]
s1.max{|a,b| -a<=>-b}   # => 2

Known bugs

* hash() method does not always guarantee to creat a unique number for the equal Rangesmall object, though such an exception is extremely unlikely to happen.
* size() method for Float/Rational has a bug when exclude_begin? is
  true (which anyway does not work for Ruby 1.8 or earlier, as there
  is no Range#size implemented up to Ruby 1.8).
* No thorough test for Ruby 1.8 or earlier has been done, although there is no known fault.

NOTE: This package is not supported any more. Please use range_extd package (which does not work in Ruby 1.8 or earlier though) instead: https://rubygems.org/gems/range_extd

range_extd package has the same features as this package, but also supports open-ended (to infinity) ranges. The interface is very similar, though not identical. Many, if not all, codes using Rangesmaller should work with the minimum amount of modification, such as, changing the class name from Rangesmaller to RangeExtd.

ToDo

* Eventually a warning message will be printed to prompt to upgrade
  to range_extd package when loaded from Ruby earlier than 2.0.

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) semver.org/