Module | Indexable
In: | lib/core/facets/indexable.rb

# Indexable

Indexable is a mixin that provides index based methods, working soley with four methods: index, slice, splice and size.

These methods work in harmony. Where index returns a position of a given element, slice returns elements for given positions. splice is like slice but replaces the given position with new values. This mehtod is not part of ruby core, but it generally just an alias for #[]=, just as slice is an alias of #[]. size of course simply returns the total length of the indexable object.

NOTE: To test the folowing methods Indexable needs to be included into Array and array must have splice defined.

      require 'facets/array/splice'

      class ::Array
        include Indexable
      end

CREDIT: Thomas Sawyer

### Methods

body ends first first! first= foot from head index index_of last last! last= mid middle pos range tail thru

### Public Instance methods

body()

Returns an array of the first element upto, but not including, the last element.

      [1,2,3].body  #=> [1,2]

ends()

A shorting of "ends at", returns the last index of the indexable object. Returns nil if there are no elements.

      [1,2,3,4,5].ends  #=> 4

This nearly equivalent to +size - 1+.

first(n=1)

Returns first n elements.

      %w{H e l l o}.first(3)  #=> %w{H e l}

first!()

Remove and return the first element.

      a = [1,2,3]
      a.first!      #=> 1
      a             #=> [2,3]

first=(x)

Change the first element.

      a = ["a","y","z"]
      a.first = "x"
      a           #=> ["x","y","z"]

foot()

Like last, returning the last element in an array.

      [1,2,3].foot  #=> [3]

from(i)

Returns last n elements.

      %w{W o r l d}.from(3)  #=> %w{l d}

head()

Like first but returns the first element in a new array.

      [1,2,3].head  #=> [1]

index(obj=nil) {|slice(i)| ...}

Returns the index of the first element equal to the given object or satisfying the block condition.

      [1,2,3,4].index{ |e| e == 3 }  #=> 2
      [1,2,3,4].index{ |e| e > 3 }   #=> 3

index_of(obj=nil, &block)

Alias for index

last(n=1)

Returns last n elements.

      %w{H e l l o}.last(3)  #=> %w{l l o}

last!()

Remove and return the last element.

      a = [1,2,3]
      a.last!       #=> 3
      a             #=> [1,2]

last=(x)

Change the last element.

      a = [1,2,5]
      a.last = 3
      a           #=> [1,2,3]

mid(offset=0)

Returns the middle element of an array, or the element offset from middle if the parameter is given. Even-sized arrays, not having an exact middle, return the middle-right element.

      [1,2,3,4,5].mid        #=> 3
      [1,2,3,4,5,6].mid      #=> 4
      [1,2,3,4,5,6].mid(-1)  #=> 3
      [1,2,3,4,5,6].mid(-2)  #=> 2
      [1,2,3,4,5,6].mid(1)   #=> 5

In other words, If there are an even number of elements the higher-indexed of the two center elements is indexed as orgin (0).

middle(birth=0)

Returns an Array of the middle element(s) of an array. Even-sized arrays, not having an exact middle, return a two-element array of the two middle elements.

      [1,2,3,4,5].middle        #=> [3]
      [1,2,3,4,5,6].middle      #=> [3,4]

A `birth` can be give to widen the middle on either side.

      [1,2,3,4,5].middle(1)   #=> [2,3,4]
      [1,2,3,4,5,6].middle(1)   #=> [2,3,4,5]

In contrast to mid which utilizes an offset.

pos(i)

Returns the positive ordinal index given a cardinal position, 1 to n or -n to -1.

      [1,2,3,4,5].pos(1)   #=> 0
      [1,2,3,4,5].pos(-1)  #=> 4

range(a=nil,z=-1)

Returns the index range between two elements. If no elements are given, returns the range from first to last.

      ['a','b','c','d'].range            #=> (0..3)
      ['a','b','c','d'].range('b','d')   #=> (1..3)

tail()

Returns an array from second element to last element.

      [1,2,3].tail  #=> [2,3]

thru(from, to=nil)

Fetch values from a start index thru an end index.

      [1,2,3,4,5].thru(0,2)  #=> [1,2,3]
      [1,2,3,4,5].thru(2,4)  #=> [3,4,5]

      [1,2,3,4,5].thru(2)  #=> [1,2,3]
      [1,2,3,4,5].thru(4)  #=> [1,2,3,4,5]

[Validate]