W3cubDocs

/Crystal 0.31

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.cr

Instance Method Summary

Instance methods inherited from module Enumerable(T)

all?(&block)
all?(pattern)
all? all?
, any?(&block)
any?(pattern)
any? any?
, chunks(&block : T -> U) forall U chunks, compact_map(&block) compact_map, count(item)
count(&block) count
, cycle(&block)
cycle(n, &block) cycle
, each(&block : T -> UNDERSCORE) 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 = "", &block)
join(separator, io, &block)
join(separator, io)
join(separator = "") 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?
none?(pattern)
none?(&block) none?
, one?(&block)
one?(pattern)
one? one?
, partition(&block) partition, product(&block)
product(initial : Number, &block)
product
product(initial : Number) product
, reduce(memo, &block)
reduce(&block) reduce
, reduce?(&block) reduce?, reject(&block : T -> )
reject(type : U.class) forall U
reject(pattern) reject
, select(pattern)
select(type : U.class) forall U
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, tally : Hash(T, Int32) tally, to_a to_a, to_h
to_h(&block : T -> Tuple(K, V)) forall K, V to_h
, to_set to_set, zip(*others : Indexable | Iterable | Iterator, &block)
zip(*others : Indexable | Iterable | Iterator) zip
, zip?(*others : Indexable | Iterable | Iterator, &block)
zip?(*others : Indexable | Iterable | Iterator) zip?

Instance methods inherited from module Iterable(T)

chunk(reuse = false, &block : T -> U) forall U chunk, chunk_while(reuse : Bool | Array(T) = false, &block : T, T -> B) forall B chunk_while, 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, slice_after(reuse : Bool | Array(T) = false, &block : T -> B) forall B
slice_after(pattern, reuse : Bool | Array(T) = false) slice_after
, slice_before(reuse : Bool | Array(T) = false, &block : T -> B) forall B
slice_before(pattern, reuse : Bool | Array(T) = false) slice_before
, slice_when(reuse : Bool | Array(T) = false, &block : T, T -> B) forall B slice_when

Instance Method Detail

def [](index : Int)Source

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

def []?(index : Int)Source

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

def bsearch(&block : T -> Bool)Source

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

def bsearch_index(&block : T, Int32 -> Bool)Source

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

def dig(index : Int, *subindexes)Source

Traverses the depth of a structure and returns the value, otherwise raises IndexError.

ary = [{1, 2, 3, {4, 5, 6}}]
ary.dig(0, 3, 2) # => 6
ary.dig(0, 3, 3) # raises IndexError

def dig?(index : Int, *subindexes)Source

Traverses the depth of a structure and returns the value. Returns nil if not found.

ary = [{1, 2, 3, {4, 5, 6}}]
ary.dig?(0, 3, 2) # => 6
ary.dig?(0, 3, 3) # => nil

def each(*, start : Int, count : Int, &block)Source

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 --

def each(*, within range : Range, &block)Source

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 --

def each(&block)Source

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 --

def eachSource

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.

def each_index(*, start : Int, count : Int, &block)Source

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 --

def each_index(&block) : NilSource

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 --

def each_indexSource

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.

def empty?Source

Returns true if self is empty, false otherwise.

([] of Int32).empty? # => true
([1]).empty?         # => false

def equals?(other : Indexable, &block)Source

Optimized version of #equals? used when other is also an Indexable.

def equals?(other, &block)Source

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

def fetch(index, default)Source

Returns the value at the index given by index, or when not found the value given by default.

a = [:foo, :bar]
a.fetch(0, :default_value) # => :foo
a.fetch(2, :default_value) # => :default_value

def fetch(index : Int, &block)Source

Returns the element at the given index, if in bounds, otherwise executes the given block with the index and returns its value.

a = [:foo, :bar]
a.fetch(0) { :default_value }    # => :foo
a.fetch(2) { :default_value }    # => :default_value
a.fetch(2) { |index| index * 3 } # => 6

def firstSource

Returns the first element of self if it's not empty, or raises IndexError.

([1, 2, 3]).first   # => 1
([] of Int32).first # raises IndexError

def first(&block)Source

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

def first?Source

Returns the first element of self if it's not empty, or nil.

([1, 2, 3]).first?   # => 1
([] of Int32).first? # => nil

def hash(hasher)Source

def index(object, offset : Int = 0)Source

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

def index(offset : Int = 0, &block)Source

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

def join(separator = "")Source

Optimized version of Enumerable#join that performs better when all of the elements in this indexable are strings: the total string bytesize to return can be computed before creating the final string, which performs better because there's no need to do reallocations.

def lastSource

Returns the last element of self if it's not empty, or raises IndexError.

([1, 2, 3]).last   # => 3
([] of Int32).last # raises IndexError

def last(&block)Source

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

def last?Source

Returns the last element of self if it's not empty, or nil.

([1, 2, 3]).last?   # => 3
([] of Int32).last? # => nil

def reverse_each(&block) : NilSource

Same as #each, but works in reverse.

def reverse_eachSource

Returns an Iterator over the elements of self in reverse order.

def rindex(offset = size - 1, &block)Source

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

def rindex(value, offset = size - 1)Source

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

def sample(random = Random::DEFAULT)Source

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

abstract def sizeSource

Returns the number of elements in this container.

def to_aSource

Returns an Array with all the elements in the collection.

{1, 2, 3}.to_a # => [1, 2, 3]

abstract def unsafe_fetch(index : Int)Source

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 #[](index) 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.

def values_at(*indexes : Int)Source

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"}

© 2012–2019 Manas Technology Solutions.
Licensed under the Apache License, Version 2.0.
https://crystal-lang.org/api/0.31.1/Indexable.html