struct Tuple(*T)

Overview

A tuple is a fixed-size, immutable, stack-allocated sequence of values of possibly different types.

You can think of a Tuple as an immutable Array whose types for each position are known at compile time.

A tuple can be created with the usual .new method or with a tuple literal:

tuple = {1, "hello", 'x'} # Tuple(Int32, String, Char)
tuple[0]                  # => 1
tuple[1]                  # => "hello"
tuple[2]                  # => 'x'

See Tuple literals in the language reference.

The compiler knows what types are in each position, so when indexing a tuple with an integer literal the compiler will return the value in that index and with the expected type, like in the above snippet. Indexing with an integer literal outside the bounds of the tuple will give a compile-time error.

Indexing with an integer value that is only known at runtime will return a value whose type is the union of all the types in the tuple, and might raise IndexError.

Indexing with a range literal known at compile-time is also allowed, and the returned value will have the correct sub-tuple type:

tuple = {1, "hello", 'x'} # Tuple(Int32, String, Char)
sub = tuple[0..1]         # => {1, "hello"}
typeof(sub)               # => Tuple(Int32, String)

Tuples are the preferred way to return fixed-size multiple return values because no memory is needed to be allocated for them:

def one_and_hello
  {1, "hello"}
end

one, hello = one_and_hello
one   # => 1
hello # => "hello"

Good examples of the above are Number#divmod and Enumerable#minmax.

Tuples can be splat with the * operator and passed to methods:

def multiply(string, value)
  string * value
end

tuple = {"hey", 2}
value = multiply(*tuple) # same as multiply tuple[0], tuple[1]
value                    # => "heyhey"

Finally, when using a splat argument in a method definition its type will be a tuple of the call arguments:

def splat_test(*args)
  args
end

tuple = splat_test 1, "hello", 'x'
tuple.class # => Tuple(Int32, String, Char)
tuple       # => {1, "hello", 'x'}

Included Modules

Defined in:

json/to_json.cr
tuple.cr
yaml/to_yaml.cr

Constructors

.from(array : Array) : self
Creates a tuple from the given array, with elements casted to the given types.
.new(ctx : YAML::ParseContext, node : YAML::Nodes::Node)
.new(pull : JSON::PullParser)
.new(*args : *T)
Creates a tuple that will contain the given values.

Class Method Summary

.types
Returns the types of this tuple type.

Instance Method Summary

#+(other : Tuple)
Returns a tuple that contains self's elements followed by other's elements.
#<=>(other : self)
The comparison operator.
#<=>(other : Tuple)
The comparison operator.
#==(other : self)
Returns true if this tuple has the same size as the other tuple and their elements are equal to each other when compared with #==.
#==(other : Tuple)
Returns true if this tuple has the same size as the other tuple and their elements are equal to each other when compared with #==.
#==(other)
Returns false.
#===(other : self)
Returns true if case equality holds for the elements in self and other.
#===(other : Tuple)
Returns true if self and other have the same size and case equality holds for the elements in self and other.
#[](index : Int)
Returns the element at the given index.
#[](range : Range)
Returns all elements that are within the given range.
#[]?(index : Int)
Returns the element at the given index or nil if out of bounds.
#at(index : Int)
Returns the element at the given index or raises IndexError if out of bounds.
#at(index : Int, &)
Returns the element at the given index or the value returned by the block if out of bounds.
#clone
Returns a tuple containing cloned elements of this tuple using the #clone method.
#each(& : Union(*T) -> ) : Nil
Yields each of the elements in this tuple.
#first
Returns the first element of this tuple.
#first?
Returns the first element of this tuple, or nil if this is the empty tuple.
#from(array : Array)
Expects to be called on a tuple of types, creates a tuple from the given array, with types casted appropriately.
#hash(hasher)
See Object#hash(hasher)
#inspect : String
Same as #to_s.
#last
Returns the last element of this tuple.
#last?
Returns the last element of this tuple, or nil if this is the empty tuple.
#map(& : Union(*T) -> )
Returns a new tuple where elements are mapped by the given block.
#map_with_index(offset = 0, &)
Like #map, but the block gets passed both the element and its index.
#pretty_print(pp) : Nil
#reduce(memo, &)
Just like the other variant, but you can set the initial value of the accumulator.
#reduce(&)
Combines all elements in the collection by applying a binary operation, specified by a block, so as to reduce them to a single value.
#reduce?(&)
Similar to #reduce, but instead of raising when the input is empty, return nil
#reverse
Returns a new tuple where the elements are in reverse order.
#reverse_each(& : Union(*T) -> )
Yields each of the elements in this tuple in reverse order.
#size
Returns the number of elements in this tuple.
#to_a
Returns an Array with all the elements in the collection.
#to_json(json : JSON::Builder) : Nil
#to_s(io : IO) : Nil
Appends a string representation of this tuple to the given IO.
#to_yaml(yaml : YAML::Nodes::Builder) : Nil
#unsafe_fetch(index : Int)
Returns the element at the given index, without doing any bounds check.

Instance methods inherited from module `Comparable(Tuple(*T))`

, , , , , ,

Instance methods inherited from module `Indexable(Union(*T))`

, , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ,

Class methods inherited from module `Indexable(Union(*T))`

Instance methods inherited from module `Enumerable(Union(*T))`

, , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ,

Class methods inherited from module `Enumerable(Union(*T))`

Instance methods inherited from module `Iterable(Union(*T))`

, , , , , , , , , ,

Instance methods inherited from struct `Value`

Instance methods inherited from class `Object`

, , , , , , , , , , , , , , , , , , , , , , , , , ,

Class methods inherited from class `Object`

Constructor Detail

def self.from(array : Array) : selfSource

Creates a tuple from the given array, with elements casted to the given types.

Tuple(String, Int64).from(["world", 2_i64])       # => {"world", 2_i64}
Tuple(String, Int64).from(["world", 2_i64]).class # => Tuple(String, Int64)

def self.new(ctx : YAML::ParseContext, node : YAML::Nodes::Node)Source

def self.new(pull : JSON::PullParser)Source

def self.new(args : T)Source

Creates a tuple that will contain the given values.

This method is useful in macros and generic code because with it you can create empty tuples, something that you can't do with a tuple literal.

Tuple.new(1, "hello", 'x') #=> {1, "hello", 'x'}
Tuple.new                  #=> {}

{}                         # syntax error

Class Method Detail

def self.typesSource

Returns the types of this tuple type.

tuple = {1, "hello", 'x'}
tuple.class.types # => {Int32, String, Char}

Instance Method Detail

def +(other : Tuple)Source

Returns a tuple that contains self's elements followed by other's elements.

t1 = {1, 2}
t2 = {"foo", "bar"}
t3 = t1 + t2
t3         # => {1, 2, "foo", "bar"}
typeof(t3) # => Tuple(Int32, Int32, String, String)

def <=>(other : self)Source

The comparison operator.

Each object in each tuple is compared using the #<=> operator.

Tuples are compared in an "element-wise" manner; the first element of this tuple is compared with the first one of other using the #<=> operator, then each of the second elements, etc. As soon as the result of any such comparison is non-zero (i.e. the two corresponding elements are not equal), that result is returned for the whole tuple comparison.

If all the elements are equal, then the result is based on a comparison of the tuple sizes. Thus, two tuples are "equal" according to #<=> if, and only if, they have the same size and the value of each element is equal to the value of the corresponding element in the other tuple.

{"a", "a", "c"} <=> {"a", "b", "c"} # => -1
{1, 2, 3, 4, 5, 6} <=> {1, 2}       # => 1
{1, 2} <=> {1, 2.0}                 # => 0

def <=>(other : Tuple)Source

The comparison operator.

Each object in each tuple is compared using the #<=> operator.

{"a", "a", "c"} <=> {"a", "b", "c"} # => -1
{1, 2, 3, 4, 5, 6} <=> {1, 2}       # => 1
{1, 2} <=> {1, 2.0}                 # => 0

def ==(other : self)Source

Returns true if this tuple has the same size as the other tuple and their elements are equal to each other when compared with #==.

t1 = {1, "hello"}
t2 = {1.0, "hello"}
t3 = {2, "hello"}

t1 == t2 # => true
t1 == t3 # => false

def ==(other : Tuple)Source

Returns true if this tuple has the same size as the other tuple and their elements are equal to each other when compared with #==.

t1 = {1, "hello"}
t2 = {1.0, "hello"}
t3 = {2, "hello"}

t1 == t2 # => true
t1 == t3 # => false

def ==(other)Source

Description copied from struct Value

Returns false.

def ===(other : self)Source

Returns true if case equality holds for the elements in self and other.

{1, 2} === {1, 2} # => true
{1, 2} === {1, 3} # => false

def ===(other : Tuple)Source

Returns true if self and other have the same size and case equality holds for the elements in self and other.

{1, 2} === {1, 2, 3}             # => false
{/o+/, "bar"} === {"foo", "bar"} # => true

def [](index : Int)Source

Returns the element at the given index. Read the type docs to understand the difference between indexing with a number literal or a variable.

tuple = {1, "hello", 'x'}
tuple[0] # => 1 (Int32)
tuple[3] # compile error: index out of bounds for tuple {Int32, String, Char}

i = 0
tuple[i] # => 1 (Int32 | String | Char)

i = 3
tuple[i] # raises IndexError

def [](range : Range)Source

Returns all elements that are within the given range. range must be a range literal whose value is known at compile-time.

Negative indices count backward from the end of the array (-1 is the last element). Additionally, an empty array is returned when the starting index for an element range is at the end of the array.

Raises a compile-time error if range.begin is out of range.

tuple = {1, "hello", 'x'}
tuple[0..1] # => {1, "hello"}
tuple[-2..] # => {"hello", 'x'}
tuple[...1] # => {1}
tuple[4..]  # Error: begin index out of bounds for Tuple(Int32, Char, Array(Int32), String) (5 not in -4..4)

i = 0
tuple[i..2] # Error: Tuple#[](Range) can only be called with range literals known at compile-time

i = 0..2
tuple[i] # Error: Tuple#[](Range) can only be called with range literals known at compile-time

def []?(index : Int)Source

Returns the element at the given index or nil if out of bounds.

tuple = {1, "hello", 'x'}
tuple[0]? # => 1
tuple[3]? # => nil

def at(index : Int)Source

Returns the element at the given index or raises IndexError if out of bounds.

tuple = {1, "hello", 'x'}
tuple.at(0) # => 1
tuple.at(3) # raises IndexError

def at(index : Int, &)Source

Returns the element at the given index or the value returned by the block if out of bounds.

tuple = {1, "hello", 'x'}
tuple.at(0) { 10 } # => 1
tuple.at(3) { 10 } # => 10

def cloneSource

Returns a tuple containing cloned elements of this tuple using the #clone method.

def each(& : Union(*T) -> ) : Nil Source

Yields each of the elements in this tuple.

tuple = {1, "hello", 'x'}
tuple.each do |value|
  puts value
end

Output:

1
"hello"
'x'

def firstSource

Returns the first element of this tuple. Doesn't compile if the tuple is empty.

tuple = {1, 2.5}
tuple.first # => 1

def first?Source

Returns the first element of this tuple, or nil if this is the empty tuple.

tuple = {1, 2.5}
tuple.first? # => 1

empty = Tuple.new
empty.first? # => nil

def from(array : Array)Source

Expects to be called on a tuple of types, creates a tuple from the given array, with types casted appropriately.

This allows you to easily pass an array as individual arguments to a method.

require "json"

def speak_about(thing : String, n : Int64)
  "I see #{n} #{thing}s"
end

data = JSON.parse(%(["world", 2])).as_a.map(&.raw)
speak_about(*{String, Int64}.from(data)) # => "I see 2 worlds"

def hash(hasher)Source

See Object#hash(hasher)

def inspect : String Source

Same as #to_s.

def lastSource

Returns the last element of this tuple. Doesn't compile if the tuple is empty.

tuple = {1, 2.5}
tuple.last # => 2.5

def last?Source

Returns the last element of this tuple, or nil if this is the empty tuple.

tuple = {1, 2.5}
tuple.last? # => 2.5

empty = Tuple.new
empty.last? # => nil

def map(& : Union(*T) -> )Source

Returns a new tuple where elements are mapped by the given block.

tuple = {1, 2.5, "a"}
tuple.map &.to_s # => {"1", "2.5", "a"}

def map_with_index(offset = 0, &)Source

Like #map, but the block gets passed both the element and its index.

tuple = {1, 2.5, "a"}
tuple.map_with_index { |e, i| "tuple[#{i}]: #{e}" } # => {"tuple[0]: 1", "tuple[1]: 2.5", "tuple[2]: a"}

Accepts an optional offset parameter, which tells it to start counting from there.

def pretty_print(pp) : Nil Source

def reduce(memo, &)Source

Just like the other variant, but you can set the initial value of the accumulator.

[1, 2, 3, 4, 5].reduce(10) { |acc, i| acc + i }             # => 25
[1, 2, 3].reduce([] of Int32) { |memo, i| memo.unshift(i) } # => [3, 2, 1]

def reduce(&)Source

Combines all elements in the collection by applying a binary operation, specified by a block, so as to reduce them to a single value.

For each element in the collection the block is passed an accumulator value (memo) and the element. The result becomes the new value for memo. At the end of the iteration, the final value of memo is the return value for the method. The initial value for the accumulator is the first element in the collection. If the collection has only one element, that element is returned.

Raises Enumerable::EmptyError if the collection is empty.

[1, 2, 3, 4, 5].reduce { |acc, i| acc + i } # => 15
[1].reduce { |acc, i| acc + i }             # => 1
([] of Int32).reduce { |acc, i| acc + i }   # raises Enumerable::EmptyError

The block is not required to return a T, in which case the accumulator's type includes whatever the block returns.

# `acc` is an `Int32 | String`
[1, 2, 3, 4, 5].reduce { |acc, i| "#{acc}-#{i}" } # => "1-2-3-4-5"
[1].reduce { |acc, i| "#{acc}-#{i}" }             # => 1

def reduce?(&)Source

Similar to #reduce, but instead of raising when the input is empty, return nil

([] of Int32).reduce? { |acc, i| acc + i } # => nil

def reverseSource

Returns a new tuple where the elements are in reverse order.

tuple = {1, 2.5, "a"}
tuple.reverse # => {"a", 2.5, 1}

def reverse_each(& : Union(*T) -> )Source

Yields each of the elements in this tuple in reverse order.

tuple = {1, "hello", 'x'}
tuple.reverse_each do |value|
  puts value
end

Output:

'x'
"hello"
1

def sizeSource

Returns the number of elements in this tuple.

{'a', 'b'}.size # => 2

def to_aSource

Description copied from module Indexable(Union(*T))

Returns an Array with all the elements in the collection.

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

def to_json(json : JSON::Builder) : Nil Source

def to_s(io : IO) : Nil Source

Appends a string representation of this tuple to the given IO.

tuple = {1, "hello"}
tuple.to_s # => "{1, \"hello\"}"

def to_yaml(yaml : YAML::Nodes::Builder) : Nil Source

def unsafe_fetch(index : Int)Source

Description copied from module Indexable(Union(*T))

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.

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

struct Tuple(*T)

Overview

Included Modules

Defined in:

Constructors

Class Method Summary

Instance Method Summary

Instance methods inherited from module Comparable(Tuple(*T))

Instance methods inherited from module Indexable(Union(*T))

Class methods inherited from module Indexable(Union(*T))

Instance methods inherited from module Enumerable(Union(*T))

Class methods inherited from module Enumerable(Union(*T))

Instance methods inherited from module Iterable(Union(*T))

Instance methods inherited from struct Value

Instance methods inherited from class Object

Class methods inherited from class Object

Constructor Detail

def self.from(array : Array) : selfSource

def self.new(ctx : YAML::ParseContext, node : YAML::Nodes::Node)Source

def self.new(pull : JSON::PullParser)Source

def self.new(*args : *T)Source

Class Method Detail

def self.typesSource

Instance Method Detail

def +(other : Tuple)Source

def <=>(other : self)Source

def <=>(other : Tuple)Source

def ==(other : self)Source

def ==(other : Tuple)Source

def ==(other)Source

def ===(other : self)Source

def ===(other : Tuple)Source

def [](index : Int)Source

def [](range : Range)Source

def []?(index : Int)Source

def at(index : Int)Source

def at(index : Int, &)Source

def cloneSource

def each(& : Union(*T) -> ) : NilSource

def firstSource

def first?Source

def from(array : Array)Source

def hash(hasher)Source

def inspect : StringSource

def lastSource

def last?Source

def map(& : Union(*T) -> )Source

def map_with_index(offset = 0, &)Source

def pretty_print(pp) : NilSource

def reduce(memo, &)Source

def reduce(&)Source

def reduce?(&)Source

def reverseSource

def reverse_each(& : Union(*T) -> )Source

def sizeSource

def to_aSource

def to_json(json : JSON::Builder) : NilSource

def to_s(io : IO) : NilSource

def to_yaml(yaml : YAML::Nodes::Builder) : NilSource

def unsafe_fetch(index : Int)Source

Instance methods inherited from module `Comparable(Tuple(*T))`

Instance methods inherited from module `Indexable(Union(*T))`

Class methods inherited from module `Indexable(Union(*T))`

Instance methods inherited from module `Enumerable(Union(*T))`

Class methods inherited from module `Enumerable(Union(*T))`

Instance methods inherited from module `Iterable(Union(*T))`

Instance methods inherited from struct `Value`

Instance methods inherited from class `Object`

Class methods inherited from class `Object`

def self.new(args : T)Source

def each(& : Union(*T) -> ) : Nil Source

def inspect : String Source

def pretty_print(pp) : Nil Source

def to_json(json : JSON::Builder) : Nil Source

def to_s(io : IO) : Nil Source

def to_yaml(yaml : YAML::Nodes::Builder) : Nil Source