module Indexable(T)
Overview
A container that allows accessing elements via a numeric index.
Indexing starts at 0
. A negative index is assumed to be
relative to the end of the container: -1
indicates the last element,
-2
is the next to last element, and so on.
Types including this module are typically Array
-like types.
Included Modules
Direct including types
Defined in:
indexable.crInstance Method Summary
-
#[](index : Int)
Returns the element at the given index.
-
#[]?(index : Int)
Returns the element at the given index.
-
#at(index : Int, &block)
Returns the element at the given index, if in bounds, otherwise executes the given block and returns its value.
-
#at(index : Int)
Returns the element at the given index, if in bounds, otherwise raises
IndexError
. -
#bsearch(&block)
By using binary search, returns the first element for which the passed block returns
true
. -
#bsearch_index(&block)
By using binary search, returns the index of the first element for which the passed block returns
true
. -
#each(&block)
Calls the given block once for each element in
self
, passing that element as a parameter. -
#each
Returns an
Iterator
for the elements ofself
. -
#each(*, start : Int, count : Int, &block)
Calls the given block once for
count
number of elements inself
starting from indexstart
, passing each element as a parameter. -
#each(*, within range : Range(Int, Int), &block)
Calls the given block once for all elements at indices within the given
range
, passing each element as a parameter. -
#each_index(*, start : Int, count : Int, &block)
Calls the given block once for
count
number of indices inself
starting from indexstart
, passing each index as a parameter. -
#each_index(&block) : Nil
Calls the given block once for each index in
self
, passing that index as a parameter. -
#each_index
Returns an
Iterator
for each index inself
. -
#empty?
Returns
true
ifself
is empty,false
otherwise. -
#equals?(other, &block)
Determines if
self
equals other according to a comparison done by the given block. - #equals?(other : Indexable, &block)
-
#first(&block)
Returns the first element of
self
if it's not empty, or the given block's value. -
#first
Returns the first element of
self
if it's not empty, or raisesIndexError
. -
#first?
Returns the first element of
self
if it's not empty, ornil
. - #hash(hasher)
-
#index(object, offset : Int = 0)
Returns the index of the first appearance of value in
self
starting from the given offset, ornil
if the value is not inself
. -
#index(offset : Int = 0, &block)
Returns the index of the first object in
self
for which the block returnstrue
, starting from the given offset, ornil
if no match is found. -
#last(&block)
Returns the last element of
self
if it's not empty, or the given block's value. -
#last
Returns the last element of
self
if it's not empty, or raisesIndexError
. -
#last?
Returns the last element of
self
if it's not empty, ornil
. -
#reverse_each(&block) : Nil
Same as
#each
, but works in reverse. -
#reverse_each
Returns an
Iterator
over the elements ofself
in reverse order. -
#rindex(value, offset = size - 1)
Returns the index of the last appearance of value in
self
, ornil
if the value is not inself
. -
#rindex(offset = size - 1, &block)
Returns the index of the first object in
self
for which the block returnstrue
, starting from the last object, ornil
if no match is found. -
#sample(random = Random::DEFAULT)
Returns a random element from
self
, using the given random number generator. -
#size
Returns the number of elements in this container.
-
#to_a
Returns an
Array
with all the elements in the collection. -
#unsafe_at(index : Int)
Returns the element at the given index, without doing any bounds check.
-
#values_at(*indexes : Int)
Returns a
Tuple
populated with the elements at the given indexes. -
#zip(other : Indexable(U), &block : T, U -> ) forall U
Calls the given block for each index in
self
, passing in the elements{self[i], other[i]}
for each index. -
#zip(other : Indexable(U)) : Array(Tuple(T, U)) forall U
Returns an
Array
of tuples populated with the ith indexed element fromself
followed by the ith indexed element fromother
. -
#zip?(other : Indexable(U), &block : T, U? -> ) forall U
Calls the given block for each index in
self
, passing in the elements{self[i], other[i]}
for each index. -
#zip?(other : Indexable(U)) : Array(Tuple(T, U?)) forall U
Returns an
Array
of tuples populated with the ith indexed element fromself
followed by the ith indexed element fromother
.
Instance methods inherited from module Enumerable(T)
all?(&block)all? all?, any?(&block)
any? any?, chunks(&block : T -> U) forall U chunks, compact_map(&block) compact_map, count(&block)
count(item) count, cycle(n, &block)
cycle(&block) cycle, each(&block : T -> _) each, each_cons(count : Int, reuse = false, &block) each_cons, each_slice(count : Int, reuse = false, &block) each_slice, each_with_index(offset = 0, &block) each_with_index, each_with_object(obj, &block) each_with_object, find(if_none = nil, &block) find, first(count : Int)
first first, first? first?, flat_map(&block : T -> Array(U) | Iterator(U) | U) forall U flat_map, grep(pattern) grep, group_by(&block : T -> U) forall U group_by, in_groups_of(size : Int, filled_up_with : U = nil) forall U
in_groups_of(size : Int, filled_up_with : U = nil, reuse = false, &block) forall U in_groups_of, includes?(obj) includes?, index(&block)
index(obj) index, index_by(&block : T -> U) forall U index_by, join(separator, io)
join(separator = "")
join(separator, io, &block)
join(separator = "", &block) join, map(&block : T -> U) forall U map, map_with_index(&block : T, Int32 -> U) forall U map_with_index, max max, max? max?, max_by(&block : T -> U) forall U max_by, max_by?(&block : T -> U) forall U max_by?, max_of(&block : T -> U) forall U max_of, max_of?(&block : T -> U) forall U max_of?, min min, min? min?, min_by(&block : T -> U) forall U min_by, min_by?(&block : T -> U) forall U min_by?, min_of(&block : T -> U) forall U min_of, min_of?(&block : T -> U) forall U min_of?, minmax minmax, minmax? minmax?, minmax_by(&block : T -> U) forall U minmax_by, minmax_by?(&block : T -> U) forall U minmax_by?, minmax_of(&block : T -> U) forall U minmax_of, minmax_of?(&block : T -> U) forall U minmax_of?, none?(&block)
none? none?, one?(&block) one?, partition(&block) partition, product(&block)
product(initial : Number, &block)
product
product(initial : Number) product, reduce(&block)
reduce(memo, &block) reduce, reject(&block : T -> ) reject, select(&block : T -> ) select, size size, skip(count : Int) skip, skip_while(&block) skip_while, sum(initial)
sum
sum(initial, &block)
sum(&block) sum, take_while(&block) take_while, to_a to_a, to_h to_h, to_set to_set
Instance methods inherited from module Iterable(T)
chunk(reuse = false, &block : T -> U) forall U
chunk,
cycle(n)cycle cycle, each each, each_cons(count : Int, reuse = false) each_cons, each_slice(count : Int, reuse = false) each_slice, each_with_index(offset = 0) each_with_index, each_with_object(obj) each_with_object
Instance Method Detail
Returns the element at the given index.
Negative indices can be used to start counting from the end of the array.
Raises IndexError
if trying to access an element outside the array's range.
ary = ['a', 'b', 'c']
ary[0] # => 'a'
ary[2] # => 'c'
ary[-1] # => 'c'
ary[-2] # => 'b'
ary[3] # raises IndexError
ary[-4] # raises IndexError
Returns the element at the given index.
Negative indices can be used to start counting from the end of the array.
Returns nil
if trying to access an element outside the array's range.
ary = ['a', 'b', 'c']
ary[0]? # => 'a'
ary[2]? # => 'c'
ary[-1]? # => 'c'
ary[-2]? # => 'b'
ary[3]? # nil
ary[-4]? # nil
Returns the element at the given index, if in bounds, otherwise executes the given block and returns its value.
a = [:foo, :bar]
a.at(0) { :baz } # => :foo
a.at(2) { :baz } # => :baz
Returns the element at the given index, if in bounds,
otherwise raises IndexError
.
a = [:foo, :bar]
a.at(0) # => :foo
a.at(2) # raises IndexError
By using binary search, returns the first element
for which the passed block returns true
.
If the block returns false
, the finding element exists
behind. If the block returns true
, the finding element
is itself or exists infront.
Binary search needs sorted array, so self
has to be sorted.
Returns nil
if the block didn't return true
for any element.
[2, 5, 7, 10].bsearch { |x| x >= 4 } # => 5
[2, 5, 7, 10].bsearch { |x| x > 10 } # => nil
By using binary search, returns the index of the first element
for which the passed block returns true
.
If the block returns false
, the finding element exists
behind. If the block returns true
, the finding element
is itself or exists infront.
Binary search needs sorted array, so self
has to be sorted.
Returns nil
if the block didn't return true
for any element.
[2, 5, 7, 10].bsearch_index { |x, i| x >= 4 } # => 1
[2, 5, 7, 10].bsearch_index { |x, i| x > 10 } # => nil
Calls the given block once for each element in self
, passing that
element as a parameter.
a = ["a", "b", "c"]
a.each { |x| print x, " -- " }
produces:
a -- b -- c --
Returns an Iterator
for the elements of self
.
a = ["a", "b", "c"]
iter = a.each
iter.next # => "a"
iter.next # => "b"
The returned iterator keeps a reference to self
: if the array
changes, the returned values of the iterator change as well.
Calls the given block once for count
number of elements in self
starting from index start
, passing each element as a parameter.
Negative indices count backward from the end of the array. (-1 is the last element).
Raises IndexError
if the starting index is out of range.
Raises ArgumentError
if count
is a negative number.
array = ["a", "b", "c", "d", "e"]
array.each(start: 1, count: 3) { |x| print x, " -- " }
produces:
b -- c -- d --
Calls the given block once for all elements at indices within the given
range
, passing each element as a parameter.
Raises IndexError
if the starting index is out of range.
array = ["a", "b", "c", "d", "e"]
array.each(within: 1..3) { |x| print x, " -- " }
produces:
b -- c -- d --
Calls the given block once for count
number of indices in self
starting from index start
, passing each index as a parameter.
Negative indices count backward from the end of the array. (-1 is the last element).
Raises IndexError
if the starting index is out of range.
Raises ArgumentError
if count
is a negative number.
array = ["a", "b", "c", "d", "e"]
array.each_index(start: -3, count: 2) { |x| print x, " -- " }
produces:
2 -- 3 --
Calls the given block once for each index in self
, passing that
index as a parameter.
a = ["a", "b", "c"]
a.each_index { |x| print x, " -- " }
produces:
0 -- 1 -- 2 --
Returns an Iterator
for each index in self
.
a = ["a", "b", "c"]
iter = a.each_index
iter.next # => 0
iter.next # => 1
The returned iterator keeps a reference to self
. If the array
changes, the returned values of the iterator will change as well.
Returns true
if self
is empty, false
otherwise.
([] of Int32).empty? # => true
([1]).empty? # => false
Determines if self
equals other according to a comparison
done by the given block.
If self
's size is the same as other's size, this method yields
elements from self
and other in tandem: if the block returns true
for all of them, this method returns true
. Otherwise it returns false
.
a = [1, 2, 3]
b = ["a", "ab", "abc"]
a.equals?(b) { |x, y| x == y.size } # => true
a.equals?(b) { |x, y| x == y } # => false
Returns the first element of self
if it's not empty, or the given block's value.
([1, 2, 3]).first { 4 } # => 1
([] of Int32).first { 4 } # => 4
Returns the first element of self
if it's not empty, or raises IndexError
.
([1, 2, 3]).first # => 1
([] of Int32).first # raises IndexError
Returns the first element of self
if it's not empty, or nil
.
([1, 2, 3]).first? # => 1
([] of Int32).first? # => nil
Returns the index of the first appearance of value in self
starting from the given offset, or nil
if the value is not in self
.
[1, 2, 3, 1, 2, 3].index(2, offset: 2) # => 4
Returns the index of the first object in self
for which the block
returns true
, starting from the given offset, or nil
if no match
is found.
[1, 2, 3, 1, 2, 3].index(offset: 2) { |x| x < 2 } # => 3
Returns the last element of self
if it's not empty, or the given block's value.
([1, 2, 3]).last { 4 } # => 3
([] of Int32).last { 4 } # => 4
Returns the last element of self
if it's not empty, or raises IndexError
.
([1, 2, 3]).last # => 3
([] of Int32).last # raises IndexError
Returns the last element of self
if it's not empty, or nil
.
([1, 2, 3]).last? # => 3
([] of Int32).last? # => nil
Returns the index of the last appearance of value in self
, or
nil
if the value is not in self
.
If offset is given, it defines the position to end the search (elements beyond this point are ignored).
[1, 2, 3, 2, 3].rindex(2) # => 3
[1, 2, 3, 2, 3].rindex(2, offset: 2) # => 1
Returns the index of the first object in self
for which the block
returns true
, starting from the last object, or nil
if no match
is found.
If offset is given, the search starts from that index towards the
first elements in self
.
[1, 2, 3, 2, 3].rindex { |x| x < 3 } # => 3
[1, 2, 3, 2, 3].rindex(offset: 2) { |x| x < 3 } # => 1
Returns a random element from self
, using the given random number generator.
Raises IndexError
if self
is empty.
a = [1, 2, 3]
a.sample # => 2
a.sample # => 1
a.sample(Random.new(1)) # => 3
Returns the element at the given index, without doing any bounds check.
Indexable
makes sure to invoke this method with index in 0...size
,
so converting negative indices to positive ones is not needed here.
Clients never invoke this method directly. Instead, they access
elements with #
and #[]?(index)
.
This method should only be directly invoked if you are absolutely sure the index is in bounds, to avoid a bounds check for a small boost of performance.
Returns a Tuple
populated with the elements at the given indexes.
Raises IndexError
if any index is invalid.
["a", "b", "c", "d"].values_at(0, 2) # => {"a", "c"}
Calls the given block for each index in self
, passing in the elements
{self[i], other[i]}
for each index.
Raises an IndexError
if other
is shorter than self
.
a = [1, 2, 3]
b = ["a", "b", "c"]
a.zip(b) { |x, y| puts "#{x} -- #{y}" }
The above produces:
1 --- a
2 --- b
3 --- c
Returns an Array
of tuples populated with the ith indexed element from
self
followed by the ith indexed element from other
.
Raises an IndexError
if other
is shorter than self
.
a = [1, 2, 3]
b = ["a", "b", "c"]
a.zip(b) # => [{1, "a"}, {2, "b"}, {3, "c"}]
Calls the given block for each index in self
, passing in the elements
{self[i], other[i]}
for each index.
If other
is shorter than self
, missing values are filled up with nil
.
a = [1, 2, 3]
b = ["a", "b"]
a.zip?(b) { |x, y| puts "#{x} -- #{y}" }
The above produces:
1 --- a
2 --- b
3 ---
Returns an Array
of tuples populated with the ith indexed element from
self
followed by the ith indexed element from other
.
If other
is shorter than self
, missing values are filled up with nil
.
a = [1, 2, 3]
b = ["a", "b"]
a.zip?(b) # => [{1, "a"}, {2, "b"}, {3, nil}]