Ruby 1.9.3 リファレンスマニュアル > ライブラリ一覧 > 組み込みライブラリ > Arrayクラス

class Array

クラスの継承リスト: Array < Enumerable < Object < Kernel < BasicObject
dynamic include: JSON::Generator::GeneratorMethods::Array (by json)

要約

配列クラスです。配列は任意の Ruby オブジェクトを要素として持つことができます。

一般的には配列は配列式を使って

[1, 2, 3]

のように生成します。

特異メソッド: [] new try_convert
インスタンスメソッド: & * + - << <=> == [] at []= assoc clear clone dup collect! map! combination compact compact! concat cycle delete delete_at delete_if reject! each each_index empty? eql? fetch fill find_index index first flatten flatten! hash include? insert inspect to_s join keep_if last length size pack permutation pop product push rassoc repeated_combination repeated_permutation replace reverse reverse! reverse_each rindex rotate rotate! sample select! shift shuffle shuffle! slice slice! sort sort! sort_by! to_a to_ary transpose uniq uniq! unshift values_at zip |

特異メソッド

self[*item] -> Array[permalink][rdoc]

引数 item を要素として持つ配列を生成して返します。

Array のサブクラスを作成したしたときに、そのサブクラスのインスタンスを作成しやすくするために用意されている。

[PARAM] item:: 配列の要素を指定します。

例:

Array[1, 2, 3] #=> [1, 2, 3]

class SubArray < Array
  # ...
end
p SubArray[1, 2, 3] # => [1, 2, 3]

new(size = 0, val = nil) -> Array[permalink][rdoc]

長さ size の配列を生成し、各要素を val で初期化して返します。

要素毎に val が複製されるわけではないことに注意してください。全要素が同じオブジェクト val を参照します。後述の例では、配列の各要素は全て同一の文字列を指します。

[PARAM] size:: 配列の長さを数値で指定します。
[PARAM] val:: 配列の要素の値を指定します。

例:

ary = Array.new(3, "foo")
p ary                     #=> ["foo", "foo", "foo"]
ary[0].capitalize!
p ary                     #=> ["Foo", "Foo", "Foo"]  (各要素は同一のオブジェクトである)

new(ary) -> Array[permalink][rdoc]

指定された配列 ary を複製して返します。 Array#dup 同様要素を複製しない浅い複製です。

[PARAM] ary:: 複製したい配列を指定します。

例:

p Array.new([1,2,3]) # => [1,2,3]

a = ["a", "b", "c"]
b = Array.new(a)
a.each{|s| s.capitalize! }
p a                        #=> ["A", "B", "C"]
p b                        #=> ["A", "B", "C"]   (b は a と要素を共有する)

new(size) {|index| ... } -> Array[permalink][rdoc]

長さ size の配列を生成し、各要素のインデックスを引数としてブロックを実行し、各要素の値をブロックの評価結果に設定します。

ブロックは要素毎に実行されるので、全要素をあるオブジェクトの複製にすることができます。

[PARAM] size:: 配列の長さを数値で指定します。

例:

ary = Array.new(3){|index| "hoge#{index}"}
p ary                      #=> ["hoge0", "hoge1", "hoge2"]

例:

ary = Array.new(3){ "foo" }
p ary                      #=> ["foo", "foo", "foo"]
ary[0].capitalize!
p ary                      #=> ["Foo", "foo", "foo"]  (各要素は違うオブジェクトである)

try_convert(obj) -> Array | nil[permalink][rdoc]

to_ary メソッドを用いて obj を配列に変換しようとします。

何らかの理由で変換できないときには nil を返します。このメソッドは引数が配列であるかどうかを調べるために使えます。

例:

Array.try_convert([1])   # => [1]
Array.try_convert("1")   # => nil

if tmp = Array.try_convert(arg)
  # the argument is an array
elsif tmp = String.try_convert(arg)
  # the argument is a string
end

インスタンスメソッド

self & other -> Array[permalink][rdoc]

集合の積演算です。両方の配列に含まれる要素からなる新しい配列を返します。重複する要素は取り除かれます。

要素の重複判定は、Object#eql? により行われます。

[PARAM] other:: 配列を指定します。配列以外のオブジェクトを指定した場合は to_ary メソッドによる暗黙の型変換を試みます。
[EXCEPTION] TypeError:: 引数に配列以外の(暗黙の型変換が行えない)オブジェクトを指定した場合に発生します。

[1, 1, 2, 3] & [1, 3, 4] #=> [1, 3]

[SEE_ALSO] Array#|

self * times -> Array[permalink][rdoc]

配列の内容を times 回繰り返した新しい配列を作成して返します。値はコピーされないことに注意してください[[trap:Array]]。

[PARAM] times:: 繰り返したい回数を整数で指定します。整数以外のオブジェクトを指定した場合は to_int メソッドによる暗黙の型変換を試みます。
[EXCEPTION] TypeError:: 引数に整数以外の(暗黙の型変換が行えない)オブジェクトを指定した場合に発生します。
[EXCEPTION] ArgumentError:: 引数に負の数を指定した場合に発生します。

p [1, 2, 3] * 3  #=> [1, 2, 3, 1, 2, 3, 1, 2, 3]

self * sep -> String[permalink][rdoc]

指定された sep を間にはさんで連結した文字列を生成して返します。Array#join(sep) と同じ動作をします。

[PARAM] sep:: 文字列を指定します。文字列以外のオブジェクトを指定した場合は to_str メソッドによる暗黙の型変換を試みます。

p [1,2,3] * ","
# => "1,2,3"

[SEE_ALSO] Array#join

self + other -> Array[permalink][rdoc]

自身と other の内容を繋げた配列を生成して返します。

[PARAM] other:: 自身と繋げたい配列を指定します。配列以外のオブジェクトを指定した場合は to_ary メソッドによる暗黙の型変換を試みます。
[EXCEPTION] TypeError:: 引数に配列以外の(暗黙の型変換が行えない)オブジェクトを指定した場合に発生します。

a = [1, 2]
b = [8, 9]
p a + b     #=> [1, 2, 8, 9]
p a         #=> [1, 2]        (変化なし)
p b         #=> [8, 9]        (こちらも変化なし)

self - other -> Array[permalink][rdoc]

自身から other の要素を取り除いた配列を生成して返します。

要素の同一性は Object#eql? により評価されます。 self 中で重複していて、other中に存在していなかった要素は、その重複が保持されます。

[PARAM] other:: 自身から取り除きたい要素の配列を指定します。配列以外のオブジェクトを指定した場合は to_ary メソッドによる暗黙の型変換を試みます。
[EXCEPTION] TypeError:: 引数に配列以外の(暗黙の型変換が行えない)オブジェクトを指定した場合に発生します。

[1, 2, 1, 3, 1, 4, 1, 5] - [2, 3, 4, 5]       # => [1, 1, 1, 1]

[1, 2, 1, 3, 1, 4, 1, 5] - [1, 2, 3, 4, 5]    # => []

self << obj -> self[permalink][rdoc]

指定された obj を自身の末尾に破壊的に追加します。

ary = [1]
ary << 2
p ary      # [1, 2]

またこのメソッドは self を返すので、以下のように連続して書くことができます。

ary = [1]
ary << 2 << 3 << 4
p ary   #=> [1, 2, 3, 4]

[PARAM] obj:: 自身に加えたいオブジェクトを指定します。Array#push と違って引数は一つしか指定できません。

[SEE_ALSO] Array#push

self <=> other -> -1 | 0 | 1 | nil[permalink][rdoc]

自身と other の各要素をそれぞれ順に <=> で比較していき、結果が 0 でなかった場合にその値を返します。各要素が等しく、配列の長さも等しい場合には 0 を返します。各要素が等しいまま一方だけ配列の末尾に達した時、自身の方が短ければ -1 をそうでなければ 1 を返します。 other に配列以外のオブジェクトを指定した場合は nil を返します。

[PARAM] other:: 自身と比較したい配列を指定します。配列以外のオブジェクトを指定した場合は to_ary メソッドによる暗黙の型変換を試みます。

[ 1, 2, 3 ] <=> [ 1, 3, 2 ]       #=> -1
[ 1, 2, 3 ] <=> [ 1, 2, 3 ]       #=> 0
[ 1, 2, 3 ] <=> [ 1, 2 ]          #=> 1

self == other -> bool[permalink][rdoc]

自身と other の各要素をそれぞれ順に == で比較して、全要素が等しければ true を返します。そうでない場合には false を返します。

[PARAM] other:: 自身と比較したい配列を指定します。

[SEE_ALSO] Object#==

[ "a", "c" ]    == [ "a", "c", 7 ]     #=> false
[ "a", "c", 7 ] == [ "a", "c", 7 ]     #=> true
[ "a", "c", 7 ] == [ "a", "d", "f" ]   #=> false

self[nth] -> object | nil[permalink][rdoc]

at(nth) -> object | nil

nth 番目の要素を返します。nth 番目の要素が存在しない時には nil を返します。

[PARAM] nth:: インデックスを整数で指定します。先頭の要素が 0 番目になります。nth の値が負の時には末尾からのインデックスと見倣します。末尾の要素が -1 番目になります。整数以外のオブジェクトを指定した場合は to_int メソッドによる暗黙の型変換を試みます。
[EXCEPTION] TypeError:: 引数に整数以外の(暗黙の型変換が行えない)オブジェクトを指定した場合に発生します。

例:

a = [ "a", "b", "c", "d", "e" ]
a[0]  #=> "a"
a[1]  #=> "b"
a[-1] #=> "e"
a[-2] #=> "d"
a[10] #=> nil

self[range] -> Array | nil[permalink][rdoc]

Range オブジェクト range の範囲にある要素からなる部分配列を返します。 range の first の値が配列の範囲に収まらない場合 nil を返します。 range の first が end より後にある場合には空の配列を返します。

[PARAM] range:: 生成したい部分配列の範囲を Range オブジェクトで指定します。 range の first や end の値が負の時には末尾からのインデックスと見倣します。末尾の要素が -1 番目になります。 end の値が配列の範囲を越える時には、越えた分は無視されます。

例:

a = [ "a", "b", "c", "d", "e" ]
a[0..1]   #=> ["a", "b"]
a[0...1]  #=> ["a"]
a[0..-1]  #=> ["a", "b", "c", "d", "e"]
a[-2..-1] #=> ["d", "e"]
a[-2..4]  #=> ["d", "e"]  (start は末尾から -2 番目、end は先頭から (4+1) 番目となる。)
a[0..10]  #=> ["a", "b", "c", "d", "e"]
a[10..11] #=> nil
a[2..1]   #=> []
a[-1..-2] #=> []

# 特殊なケース。first が自身の長さと同じ場合には以下のようになります。
a[5]                   #=> nil
a[5, 1]                #=> []
a[5..10]               #=> []

self[start, length] -> Array | nil[permalink][rdoc]

start 番目から length 個の要素を含む部分配列を返します。 length が負の時、start が自身の範囲を越えた時には nil を返します。

[PARAM] start:: 生成したい部分配列の先頭のインデックスを整数で指定します。 start の値が負の時には末尾からのインデックスと見倣します。末尾の要素が -1 番目になります。整数以外のオブジェクトを指定した場合は to_int メソッドによる暗黙の型変換を試みます。
[PARAM] length:: 生成したい部分配列の長さを整数で指定します。 length が start 番目からの配列の長さより長い時には、越えた分の長さは無視されます。整数以外のオブジェクトを指定した場合は to_int メソッドによる暗黙の型変換を試みます。
[EXCEPTION] TypeError:: 引数に整数以外の(暗黙の型変換が行えない)オブジェクトを指定した場合に発生します。

例:

a = [ "a", "b", "c", "d", "e" ]
a[0, 1]    #=> ["a"]
a[-1, 1]   #=> ["e"]
a[0, 10]   #=> ["a", "b", "c", "d", "e"]
a[0, 0]    #=> []
a[0, -1]   #=> nil
a[10, 1]   #=> nil

# 特殊なケース。start が自身の長さと同じ場合には以下のようになります。
a[5]                   #=> nil
a[5, 1]                #=> []
a[5..10]               #=> []

self[nth] = val[permalink][rdoc]

nth 番目の要素を val に設定します。nth が配列の範囲を越える時には配列の長さを自動的に拡張し、拡張した領域を nil で初期化します。

[PARAM] nth:: インデックスを整数で指定します。整数以外のオブジェクトを指定した場合は to_int メソッドによる暗黙の型変換を試みます。
[PARAM] val:: 設定したい要素の値を指定します。
[EXCEPTION] TypeError:: 引数 nth に整数以外の(暗黙の型変換が行えない)オブジェクトを指定した場合に発生します。
[EXCEPTION] IndexError:: 指定された nth が自身の始点よりも前を指している場合に発生します。

例:

a = [0, 1, 2, 3, 4, 5]
a[0] = "a"
p a  #=> ["a", 1, 2, 3, 4, 5]
a[10] = "x"
p a  #=> ["a", 1, 2, 3, 4, 5, nil, nil, nil, nil, "x"]

a = [0, 1, 2, 3, 4, 5]
a[-100] = 1           #=> IndexError

self[range] = val[permalink][rdoc]

Range オブジェクト range の範囲にある要素を配列 val の内容に置換します。 range の first が自身の末尾を越える時には配列の長さを自動的に拡張し、拡張した領域を nil で初期化します。

ary = [0, 1, 2, 3, 4, 5]
ary[0..2] = ["a", "b"]
p ary  # => ["a", "b", 3, 4, 5]

ary = [0, 1, 2]
ary[5..6] = "x"
p ary  # => [0, 1, 2, nil, nil, "x"]

ary = [0, 1, 2, 3, 4, 5]
ary[1..3] = "x"
p ary  # => [0, "x", 4, 5]

[PARAM] range:

設定したい配列の範囲を Range オブジェクトで指定します。 range の first や end の値が負の時には末尾からのインデックスと見倣します。末尾の要素が -1 番目になります。 range の first が end より後にある場合には first の直前に val を挿入します。

    ary = [0, 1, 2, 3, 4, 5]
    ary[2..0] = ["a", "b", "c"]
    p ary   # => [0, 1, "a", "b", "c", 2, 3, 4, 5]

[PARAM] val:

range の範囲に設定したい要素を配列で指定します。配列以外のオブジェクトを指定した場合は to_ary メソッドによる暗黙の型変換を試みます。to_ary メソッドに応答できない場合は [val] を用います。 val の要素の数の方が range の長さより大きい時には、後ろの要素がずれます。 val が空の配列 [] なら start から end までの要素が削除されます。

    ary = [0, 1, 2, 3, 4, 5]
    ary[2..4] = []
    p ary   # => [0, 1, 5]

[EXCEPTION] RangeError:

指定された範囲の始点が自身の始点よりも前にある場合に発生します。

例:

a = [0, 1, 2, 3, 4, 5]
a[-10..10] = 1        #=> RangeError

self[start, length] = val[permalink][rdoc]

インデックス start から length 個の要素を配列 val の内容で置き換えます。 start が自身の末尾を越える時には配列の長さを自動的に拡張し、拡張した領域を nil で初期化します。

ary = [0, 1, 2, 3]
ary[1, 2] = ["a", "b", "c", "d"]
p ary                        #=> [0, "a", "b", "c", "d", 3]

ary = [0, 1, 2]
ary[5, 1] = "Z"
p ary                        #=> [0, 1, 2, nil, nil, "Z"]

ary = [0, 1, 2, 3]
ary[0, 10] = ["a"]
p ary                        #=> ["a"]

[PARAM] start:

置き換えたい範囲の先頭のインデックスを指定します。 start の値が負の時には末尾からのインデックスと見倣します。末尾の要素が -1 番目になります。整数以外のオブジェクトを指定した場合は to_int メソッドによる暗黙の型変換を試みます。

[PARAM] length:

置き換えたい要素の個数を指定します。 length の値が 0 のときは start の直前に val を挿入します。整数以外のオブジェクトを指定した場合は to_int メソッドによる暗黙の型変換を試みます。

    ary = [0, 1, 2, 3]
    ary[1, 0] = ["inserted"]
    p ary                        # => [0, "inserted", 1, 2, 3]

[PARAM] val:

設定したい要素を配列で指定します。配列以外のオブジェクトを指定した場合は to_ary メソッドによる暗黙の型変換を試みます。to_ary メソッドに応答できない場合は [val] を用います。 val の長さが length と等しくない場合には、val の長さに合わせて要素が削除されたりずれたりします。 val が空の配列 [] なら start から end までの要素が削除されます。

    a = [0, 1, 2, 3, 4, 5]
    a[2, 3] = []
    p a   # => [0, 1, 5]

[EXCEPTION] TypeError:

引数 start、length に整数以外の(暗黙の型変換が行えない)オブジェクトを指定した場合に発生します。

[EXCEPTION] TypeError:

引数 val に配列以外の(暗黙の型変換が行えない)オブジェクトを指定した場合に発生します。

[EXCEPTION] IndexError:

引数 start が自身の始点よりも前を指している場合に発生します。

[EXCEPTION] IndexError:

引数 length に負の数を指定した場合に発生します。

assoc(key) -> Array | nil[permalink][rdoc]

配列の配列を検索して、その 0 番目の要素が key に == で等しい最初の要素を返します。該当する要素がなければ nil を返します。

[PARAM] key:: 検索するオブジェクトを指定します。

ary = [[1,15], [2,25], [3,35]]
p ary.assoc(2)           # => [2, 25]
p ary.assoc(100)         # => nil
p ary.assoc(15)          # => nil

[SEE_ALSO] Array#rassoc

clear -> self[permalink][rdoc]

配列の要素をすべて削除して空にします。

ary = [1, 2]
ary.clear
p ary     #=> []

clone -> Array[permalink][rdoc]

dup -> Array

レシーバと同じ内容を持つ新しい配列を返します。

clone は frozen tainted singleton-class の情報も含めてコピーしますが、 dup は内容だけをコピーします。またどちらのメソッドも要素それ自体のコピーはしません。つまり「浅い(shallow)」コピーを行います。

ary = ['string']
p ary             #=> ["string"]
copy = ary.dup
p copy            #=> ["string"]

ary[0][0...3] = ''
p ary             #=> ["ing"]
p copy            #=> ["ing"]

collect! {|item| ..} -> self[permalink][rdoc]

map! {|item| ..} -> self

collect! -> Enumerator

map! -> Enumerator

各要素を順番にブロックに渡して評価し、その結果で要素を置き換えます。

ブロックが与えられなかった場合は、自身と map! から生成した Enumerator オブジェクトを返します。

例:

ary = [1, 2, 3]
ary.map! {|i| i * 3 }
p ary   #=> [3, 6, 9]

ary = [1, 2, 3]
e = ary.map!
e.each{ 1 }
p ary           #=> [1, 1, 1]

[SEE_ALSO] Enumerable#collect, Enumerator

combination(n) {|c| block } -> Array[permalink][rdoc]

combination(n) -> Enumerator

サイズ n の組み合わせをすべて生成し、それを引数としてブロックを実行します。

得られる組み合わせの順序は保証されません。ブロックなしで呼び出されると、組み合わせを生成する Enumerator オブジェクトを返します。

[PARAM] n:: 生成される配列のサイズを整数で指定します。整数以外のオブジェクトを指定した場合は to_int メソッドによる暗黙の型変換を試みます。
[EXCEPTION] TypeError:: 引数に整数以外の(暗黙の型変換が行えない)オブジェクトを指定した場合に発生します。

例:

a = [1, 2, 3, 4]
a.combination(1).to_a  #=> [[1],[2],[3],[4]]
a.combination(2).to_a  #=> [[1,2],[1,3],[1,4],[2,3],[2,4],[3,4]]
a.combination(3).to_a  #=> [[1,2,3],[1,2,4],[1,3,4],[2,3,4]]
a.combination(4).to_a  #=> [[1,2,3,4]]
a.combination(0).to_a  #=> [[]]: one combination of length 0
a.combination(5).to_a  #=> []  : no combinations of length 5

[SEE_ALSO] Array#permutation, Array#repeated_combination

compact -> Array[permalink][rdoc]

compact! -> self | nil

compact は自身から nil を取り除いた配列を生成して返します。 compact! は自身から破壊的に nil を取り除き、変更が行われた場合は self を、そうでなければ nil を返します。

ary = [1, nil, 2, nil, 3, nil]
p ary.compact   #=> [1, 2, 3]
p ary           #=> [1, nil, 2, nil, 3, nil]
ary.compact!
p ary           #=> [1, 2, 3]
p ary.compact!  #=> nil

concat(other) -> self[permalink][rdoc]

配列 other を自身の末尾に破壊的に連結します。

[PARAM] other:: 自身と連結したい配列を指定します。

array = [1, 2]
a     = [3, 4]
array.concat a
p array          # => [1, 2, 3, 4]
p a              # => [3, 4]       # こちらは変わらない

cycle(n=nil) {|obj| block } -> nil[permalink][rdoc]

cycle(n=nil) -> Enumerator

配列の全要素を n 回(nilの場合は無限に)繰り返しブロックを呼びだします。

ブロックを省略した場合は、以上のような繰り返しを行う Enumerator を返します。

[PARAM] n:: 繰り返したい回数を整数で指定します。整数以外のオブジェクトを指定した場合は to_int メソッドによる暗黙の型変換を試みます。
[EXCEPTION] TypeError:: 引数に整数以外の(暗黙の型変換が行えない)オブジェクトを指定した場合に発生します。

例:

a = ["a", "b", "c"]
a.cycle {|x| puts x }  # print, a, b, c, a, b, c,.. forever.

delete(val) -> object | nil[permalink][rdoc]

delete(val) { ... } -> object

指定された val と == で等しい要素を自身からすべて取り除きます。等しい要素が見つかった場合は最後に見つかった要素を、そうでない場合には nil を返します。

ブロックが与えられた場合、val と等しい要素が見つからなかったときにブロックを評価してその結果を返します。

[PARAM] val:: 自身から削除したい値を指定します。

array = [1, 2, 3, 2, 1]
p array.delete(2)       #=> 2
p array                 #=> [1, 3, 1]

# ブロックなしの引数に nil を渡すとその戻り値から削除が
# 行われたかどうかの判定をすることはできない
ary = [nil,nil,nil]
p ary.delete(nil)       #=> nil
p ary                   #=> []
p ary.delete(nil)       #=> nil

delete_at(pos) -> object | nil[permalink][rdoc]

指定された位置 pos にある要素を取り除きそれを返します。 pos が範囲外であったら nil を返します。

Array#at と同様に負のインデックスで末尾から位置を指定することができます。

[PARAM] pos:: 削除したい要素のインデックスを整数で指定します。整数以外のオブジェクトを指定した場合は to_int メソッドによる暗黙の型変換を試みます。
[EXCEPTION] TypeError:: 引数に整数以外の(暗黙の型変換が行えない)オブジェクトを指定した場合に発生します。

array = [0, 1, 2, 3, 4]
array.delete_at 2
p array             #=> [0, 1, 3, 4]

delete_if {|x| ... } -> self[permalink][rdoc]

reject! {|x| ... } -> self | nil

delete_if -> Enumerator

reject! -> Enumerator

要素を順番にブロックに渡して評価し、その結果が真になった要素をすべて削除します。 delete_if は常に self を返しますが、reject! は要素が 1 つ以上削除されれば self を、 1 つも削除されなければ nil を返します。

ブロックが与えられなかった場合は、自身と reject! から生成した Enumerator オブジェクトを返します。返された Enumerator オブジェクトの each メソッドには、もとの配列に対して副作用があることに注意してください。

例:

a = [0, 1, 2, 3, 4, 5]
a.delete_if{|x| x % 2 == 0}
p a #=> [1, 3, 5]

a = [0, 1, 2, 3, 4, 5]
e = a.reject!
e.each{|i| i % 2 == 0}
p a                    #=> [1, 3, 5]  もとの配列から削除されていることに注意。

each {|item| .... } -> self[permalink][rdoc]

each -> Enumerator

各要素に対してブロックを評価します。

ブロックが与えられなかった場合は、自身と each から生成した Enumerator オブジェクトを返します。

[1, 2, 3].each do |i|
  puts i
end
#=> 1
    2
    3

each_index {|index| .... } -> self[permalink][rdoc]

each_index -> Enumerator

各要素のインデックスに対してブロックを評価します。

以下と同じです。

(0 ... ary.size).each {|index| ....  }

ブロックが与えられなかった場合は、自身と each_index から生成した Enumerator オブジェクトを返します。

empty? -> bool[permalink][rdoc]

自身の要素の数が 0 の時に真を返します。そうでない場合に false を返します。

p [].empty?         #=> true
p [1, 2, 3].empty?  #=> false

eql?(other) -> bool[permalink][rdoc]

自身と other の各要素をそれぞれ順に Object#eql? で比較して、全要素が等しければ真を返します。そうでない場合に false を返します。

[PARAM] other:: 自身と比較したい配列を指定します。

["a", "b", "c"].eql? ["a", "b", "c"]      #=> true
["a", "b", "c"].eql? ["a", "c", "b"]      #=> false
["a", "b", 1].eql?   ["a", "b", 1.0]      #=> false (1.eql?(1.0) が false なので)

[SEE_ALSO] Object#eql?

fetch(nth) -> object[permalink][rdoc]

fetch(nth, ifnone) -> object

fetch(nth) {|nth| ... } -> object

nth 番目の要素を返します。

Array#[](nth) とは nth 番目の要素が存在しない場合の振舞いが異なります。最初の形式では、例外 IndexError が発生します。二番目の形式では、引数 ifnone を返します。三番目の形式では、ブロックを評価した結果を返します。

[PARAM] nth:: 取得したい要素のインデックスを整数で指定します。整数以外のオブジェクトを指定した場合は to_int メソッドによる暗黙の型変換を試みます。
[PARAM] ifnone:: 要素が存在しなかった場合に返すべき値を指定します。
[EXCEPTION] TypeError:: 引数 nth に整数以外の(暗黙の型変換が行えない)オブジェクトを指定した場合に発生します。
[EXCEPTION] IndexError:: 引数 ifnone もブロックも指定しておらず、 nth 番目の要素も存在しなかった場合に発生します。

例:

a = [1, 2, 3, 4, 5]
begin
  p a.fetch(10)
rescue IndexError => err
  puts err #=> index 10 out of array
end

p a.fetch(10, 999) #=> 999

result = a.fetch(10){|nth|
  print "#{nth} はありません。\n"
  999
}
p result #=> 999

fill(val) -> self[permalink][rdoc]

fill {|index| ... } -> self

すべての要素に val をセットします。

このメソッドが val のコピーでなく val 自身をセットすることに注意してください([[trap:Array]])。 val の代わりにブロックを指定するとブロックの評価結果を値とします。

[PARAM] val:: 自身にセットしたいオブジェクトを指定します。

a = [0, 1, 2, 3, 4]
a.fill(10)
p a #=> [10, 10, 10, 10, 10]

a = [0, 1, 2, 3, 4]
a.fill("a")
p a #=> ["a", "a", "a", "a", "a"]
a[0].capitalize!
p a #=> ["A", "A", "A", "A", "A"]

fill(val, start, length = nil) -> self[permalink][rdoc]

fill(val, range) -> self

fill(start, length = nil) {|index| ... } -> self

fill(range) {|index| ... } -> self

配列の指定された範囲すべてに val をセットします。

範囲の始点が自身の末尾を越える時には配列の長さを自動的に拡張し、拡張した領域を nil で初期化します。範囲の終点が自身の末尾を越える時は長さを自動的に拡張し、拡張した部分を val で初期化します。このメソッドが val のコピーでなく val 自身をセットすることに注意してください([[trap:Array]])。

a = [0, 1, 2]
a.fill("x", 5..10)
p a #=> [0, 1, 2, nil, nil, "x", "x", "x", "x", "x", "x"]

val の代わりにブロックを指定するとブロックの評価結果を値とします。ブロックは要素毎に実行されるので、セットする値のそれぞれをあるオブジェクトの複製にすることができます。ブロックのパラメータには start からのインデックスが渡されます。

ary = []
p ary.fill(1..2) {|i| i}         # => [nil, 1, 2]
p ary.fill(0,3) {|i| i}          # => [0, 1, 2]
p ary.fill { "foo" }             # => ["foo", "foo", "foo"]
p ary.collect {|v| v.object_id } # => [537770124, 537770112, 537770100]

[PARAM] val:: 自身に設定したいオブジェクトを指定します。
[PARAM] start:: val を設定する範囲の始点のインデックスを整数で指定します。start の値が負の時には末尾からのインデックスと見倣します。末尾の要素が -1 番目になります。
[PARAM] length:: val を設定する要素の個数を指定します。nil が指定された時は配列の終りまでの長さを意味します。
[PARAM] range:: val を設定する範囲を Range オブジェクトで指定します。

find_index(val) -> Integer | nil[permalink][rdoc]

index(val) -> Integer | nil

find_index {|item| ...} -> Integer | nil

index {|item| ...} -> Integer | nil

find_index -> Enumerator

index -> Enumerator

条件に一致する最初の要素の位置を返します。

[PARAM] val:: 位置を知りたいオブジェクトを指定します。

指定された val と == で等しい最初の要素の位置を返します。等しい要素がひとつもなかった場合は nil を返します。

p [1, 0, 0, 1, 0].index(1)   #=> 0
p [1, 0, 0, 0, 0].index(1)   #=> 0
p [0, 0, 0, 0, 0].index(1)   #=> nil

ブロックが与えられた場合には、各要素を引数として順にブロックを実行し、ブロックが真を返した最初の要素の位置を返します。一つも真にならなかった場合は nil を返します。

p [0, 1, 0, 1, 0].index {|v| v > 0}   #=> 1

引数、ブロックのどちらも与えられなかった場合は、 Enumerator のインスタンスを返します。

[SEE_ALSO] Array#rindex

first -> object | nil[permalink][rdoc]

配列の先頭の要素を返します。要素がなければ nil を返します。

p [0, 1, 2].first   #=> 0
p [].first          #=> nil

[SEE_ALSO] Array#last

first(n) -> Array[permalink][rdoc]

先頭の n 要素を配列で返します。n は 0 以上でなければなりません。

[PARAM] n:: 取得したい要素の個数を整数で指定します。整数以外のオブジェクトを指定した場合は to_int メソッドによる暗黙の型変換を試みます。
[EXCEPTION] TypeError:: 引数に整数以外の(暗黙の型変換が行えない)オブジェクトを指定した場合に発生します。
[EXCEPTION] ArgumentError:: n が負値の場合発生します。

ary =  [0, 1, 2]
p ary.first(0)
p ary.first(1)
p ary.first(2)
p ary.first(3)
p ary.first(4)
# => []
     [0]
     [0, 1]
     [0, 1, 2]
     [0, 1, 2]

[SEE_ALSO] Array#last

flatten(lv = nil) -> Array[permalink][rdoc]

flatten!(lv = nil) -> self | nil

flatten は自身を再帰的に平坦化した配列を生成して返します。flatten! は自身を再帰的かつ破壊的に平坦化し、平坦化が行われた場合は self をそうでない場合は nil を返します。 lv が指定された場合、lv の深さまで再帰的に平坦化します。

[PARAM] lv:: 平坦化の再帰の深さを整数で指定します。nil を指定した場合、再帰の深さの制限無しに平坦化します。整数以外のオブジェクトを指定した場合は to_int メソッドによる暗黙の型変換を試みます。
[EXCEPTION] TypeError:: 引数に整数以外の(暗黙の型変換が行えない)オブジェクトを指定した場合に発生します。
[EXCEPTION] ArgumentError:: 配列要素が自身を含むような無限にネストした配列に対して flatten を呼んだ場合に発生します。

# 自身を再帰的に平坦化する例。
a = [1, [2, 3, [4], 5]]
p a.flatten                     #=> [1, 2, 3, 4, 5]
p a                             #=> [1, [2, 3, [4], 5]]

# 自身を破壊的に平坦化する例。
a = [[[1, [2, 3]]]]
p a.flatten!                    #=> [1, 2, 3]
p a                             #=> [1, 2, 3]

# 平坦化が行われない場合は nil を返す。
p [1, 2, 3].flatten!            #=> nil

# 平坦化の再帰の深さを指定する例。
a = [ 1, 2, [3, [4, 5] ] ]
a.flatten(1)              #=> [1, 2, 3, [4, 5]]

hash -> Integer[permalink][rdoc]

自身のハッシュ値を整数で返します。ハッシュ値は自身の各要素のハッシュ値から計算されます。Array#eql? で比較して等しい配列同士は同じハッシュ値を返します。

a = ["a", "b", 1]
a.hash                #=>  321
b = a.dup
b.hash                #=>  321

["a", 1, "b"].hash    #=>  491
["a", 1.0, "b"].hash  #=>  466227

include?(val) -> bool[permalink][rdoc]

配列が val と == で等しい要素を持つ時に真を返します。

[PARAM] val:: オブジェクトを指定します。

a = [ "a", "b", "c" ]
a.include?("b")       #=> true
a.include?("z")       #=> false

insert(nth, *val) -> self[permalink][rdoc]

インデックス nth の要素の直前(nth が負の場合は直後)に第 2 引数以降の値を挿入します。引数 val を一つも指定しなければ何もしません。

[PARAM] nth:: val を挿入する位置を整数で指定します。整数以外のオブジェクトを指定した場合は to_int メソッドによる暗黙の型変換を試みます。
[PARAM] val:: 自身に挿入するオブジェクトを指定します。
[EXCEPTION] TypeError:: 引数に整数以外の(暗黙の型変換が行えない)オブジェクトを指定した場合に発生します。

ary = [1, 2, 3]
ary.insert(2, "a", "b")
p ary                  # => [1, 2, "a", "b", 3]
ary.insert(-2, "X")
p ary                  # => [1, 2, "a", "b", "X", 3]

to_s -> String[permalink][rdoc]

inspect -> String

自身の情報を人間に読みやすい文字列にして返します。

[1, 2, 3, 4].to_s    # => "[1, 2, 3, 4]"
[1, 2, 3, 4].inspect # => "[1, 2, 3, 4]"

join(sep = $,) -> String[permalink][rdoc]

配列の要素を文字列 sep を間に挟んで連結した文字列を返します。

文字列でない要素に対しては、to_str があれば to_str、なければ to_s した結果を連結します。要素がまた配列であれば再帰的に (同じ sep を利用して) join した文字列を連結します。ただし、配列要素が自身を含むような無限にネストした配列に対しては、以下のような結果になります。

ary = [1,2,3]
ary.push ary
p ary           # => [1, 2, 3, [...]]
p ary.join      # => ArgumentError: recursive array join

[PARAM] sep:: 間に挟む文字列を指定します。nil のときは空文字列を使います。文字列以外のオブジェクトを指定した場合は to_str メソッドによる暗黙の型変換を試みます。
[EXCEPTION] TypeError:: 引数に文字列以外の(暗黙の型変換が行えない)オブジェクトを指定した場合に発生します。
[EXCEPTION] ArgumentError:: 配列要素が自身を含むような無限にネストした配列に対して join を呼んだ場合に発生します。

[1, 2, 3].join('-') #=> "1-2-3"

[SEE_ALSO] Array#*, $,

keep_if {|item| ... } -> self[permalink][rdoc]

keep_if -> Enumerator

ブロックが false を返した要素を削除します。

a = %w{ a b c d e f }
a.keep_if {|v| v =~ /[aeiou]/}   # => ["a", "e"]
a # => ["a", "e"]

Array#select! と同様に自身を上書きしますが、削除する要素がなかった場合には修正を行いません。

a = %w{ a b c d e f }
a.keep_if {|v| v =~ /[a-z]/ }   # => ["a", "b", "c", "d", "e", "f"]
a # => ["a", "b", "c", "d", "e", "f"]

ブロックが与えられなかった場合は、自身と keep_if から生成した Enumerator オブジェクトを返します。

[SEE_ALSO] Array#select!

last -> object | nil[permalink][rdoc]

配列の末尾の要素を返します。配列が空のときは nil を返します。

p [0, 1, 2].last   #=> 2
p [].last          #=> nil

[SEE_ALSO] Array#first

last(n) -> Array[permalink][rdoc]

末尾の n 要素を配列で返します。n は 0 以上でなければなりません。

[PARAM] n:: 取得したい要素の個数を整数で指定します。整数以外のオブジェクトを指定した場合は to_int メソッドによる暗黙の型変換を試みます。
[EXCEPTION] TypeError:: 引数に整数以外の(暗黙の型変換が行えない)オブジェクトを指定した場合に発生します。
[EXCEPTION] ArgumentError:: n が負値の場合発生します。

ary =  [0, 1, 2]
p ary.last(0)
p ary.last(1)
p ary.last(2)
p ary.last(3)
p ary.last(4)
# => []
     [2]
     [1, 2]
     [0, 1, 2]
     [0, 1, 2]

[SEE_ALSO] Array#first

length -> Integer[permalink][rdoc]

size -> Integer

配列の長さを返します。配列が空のときは 0 を返します。

p [1, nil, 3, nil].size    #=> 4

pack(template) -> String[permalink][rdoc]

配列の内容を template で指定された文字列にしたがって、バイナリとしてパックした文字列を返します。

テンプレートは型指定文字列とその長さ(省略時は1)を並べたものです。長さとして * が指定された時は「残りのデータ全て」の長さを表します。型指定文字は以下で述べる pack テンプレート文字列の通りです。

[PARAM] template:: 自身のバイナリとしてパックするためのテンプレートを文字列で指定します。

以下にあげるものは、Array#pack、String#unpack のテンプレート文字の一覧です。テンプレート文字は後に「長さ」を表す数字を続けることができます。「長さ」の代わりに`*'とすることで「残り全て」を表すこともできます。

長さの意味はテンプレート文字により異なりますが大抵、

"iiii"

のように連続するテンプレート文字は

"i4"

と書き換えることができます。

テンプレート文字列中の空白類は無視されます。また、`#' から改行あるいはテンプレート文字列の最後まではコメントとみなされ無視されます。

整数のテンプレート文字のシステム依存性

各テンプレート文字の説明の中で、 short や long はシステムによらずそれぞれ 2, 4バイトサイズの数値(32ビットマシンで一般的なshort, longのサイズ)を意味しています。s, S, l, L に対しては直後に _ または ! を "s_" あるいは "s!" のように続けることでシステム依存の short, long のサイズにすることもできます。

i, I (int)のサイズは常にシステム依存であり、n, N, v, V のサイズは常にシステム依存ではない(!をつけられない)ことに注意してください。

つまり、IO#ioctl などで C の構造体を渡すときのように、システム依存のサイズとエンディアンに合わせる必要があるときには s!, S!, i!, I!, l!, L!, q!, Q! を用います。また、ネットワークプロトコルやファイルフォーマットのように、システムに依存しないデータを扱うときには n, N, v, V を用います。

強制的にエンディアンを指定したいときは、リトルエンディアンなら< ビッグエンディアンなら> を後ろにつけます。!と組み合わせることも可能です。

まとめると以下のようになります。

エンディアン非依存、整数サイズ非依存 (ネットワークプロトコルなどに適切)

  n: big endian unsigned 16bit
  N: big endian unsigned 32bit
  v: little endian unsigned 16bit
  V: little endian unsigned 32bit

エンディアン依存、整数サイズ依存 (C の構造体などに適切)

  s!: signed short
  S!: unsigned short
  i!: signed int
  I!: unsigned int
  l!: signed long
  L!: unsigned long
  q!: signed long long
  Q!: unsigned long long

エンディアン依存、整数サイズ非依存 (C99 の stdint.h にある厳密な幅を持つ整数型に適切)

  s: int16_t
  S: uint16_t
  l: int32_t
  L: uint32_t

エンディアンの強制指定(バイナリ解析などに適切)

  S>:  big endian unsigned 16bit(nと同じ)
  s>:  big endian int16_t
  s!>: big endian signed short
  l<:  little endian int32_t
  l!<: little endian signed long

各テンプレート文字の説明

説明中、Array#pack と String#unpack で違いのあるものは `/' で区切って「Array#pack の説明 / String#unpack の説明」としています。

a

ASCII文字列(null文字を詰める/後続するnull文字やスペースを残す)

    ["abc"].pack("a")    # => "a"
    ["abc"].pack("a*")   # => "abc"
    ["abc"].pack("a4")   # => "abc\0"

    "abc\0".unpack("a4") # => ["abc\0"]
    "abc ".unpack("a4")  # => ["abc "]

A

ASCII文字列(スペースを詰める/後続するnull文字やスペースを削除)

    ["abc"].pack("A")    # => "a"
    ["abc"].pack("A*")   # => "abc"
    ["abc"].pack("A4")   # => "abc "

    "abc ".unpack("A4")  # => ["abc"]
    "abc\0".unpack("A4") # => ["abc"]

Z

null終端文字列(長さが`*'の場合も含め、null文字を詰める/後続するnull文字を削除)

    ["abc"].pack("Z")  # => "a"
    ["abc"].pack("Z*") # => "abc\0"
    ["abc"].pack("Z4") # => "abc\0"

    "abc\0".unpack("Z4") # => ["abc"]
    "abc ".unpack("Z4")  # => ["abc "]

b

ビットストリング(各バイトごとに下位ビットから上位ビット)

    "\377\000".unpack("b*") # => ["1111111100000000"]
    "\001\002".unpack("b*") # => ["1000000001000000"]
    "\001\002".unpack("b3") # => ["100"]


    ["1000000001000000"].pack("b*") # => "\001\002"

B

ビットストリング(各バイトごとに上位ビットから下位ビット)

    "\377\000".unpack("B*")  # => ["1111111100000000"]
    "\001\002".unpack("B*")  # => ["0000000100000010"]
    "\001\002".unpack("B9")  # => ["000000010"]
    "\001\002".unpack("B15") # => ["000000010000001"]

    ["0000000100000010"].pack("B*")  # => "\001\002"
    ["0000000100000010"].pack("B0")  # => ""
    ["0000000100000010"].pack("B1")  # => "\000"
    ["0000000100000010"].pack("B7")  # => "\000"
    ["0000000100000010"].pack("B8")  # => "\001"
    ["0000000100000010"].pack("B9")  # => "\001\000"
    ["0000000100000010"].pack("B14") # => "\001\000"
    ["0000000100000010"].pack("B15") # => "\001\002"
    ["0000000100000010"].pack("B16") # => "\001\002"

h

16進文字列(下位ニブルが先)

    "\x01\xfe".unpack("h*") # => ["10ef"]
    "\x01\xfe".unpack("h3") # => ["10e"]

    ["10ef"].pack("h*") # => "\001\376"

H

16進文字列(上位ニブルが先)

    "\x01\xfe".unpack("H*") # => ["01fe"]
    "\x01\xfe".unpack("H3") # => ["01f"]
    "~".unpack("H2")        # => ["7e"]

    ["01fe"].pack("H*") # => "\001\376"
    ["7e"].pack("H2")   # => "~"

c

char (8bit 符号つき整数)

    "\001\376".unpack("c*") # => [1, -2]

    [1, -2].pack("c*")  # => "\001\376"
    [1, 254].pack("c*") # => "\001\376"

C

unsigned char (8bit 符号なし整数)

    "\001\376".unpack("C*") # => [1, 254]

    [1, -2].pack("C*")  # => "\001\376"
    [1, 254].pack("C*") # => "\001\376"

s

short (16bit 符号つき整数, エンディアンに依存) (s! は 16bit でなく、short のサイズに依存)

リトルエンディアン:

    "\001\002\376\375".unpack("s*") # => [513, -514]

    [513, 65022].pack("s*") # => "\001\002\376\375"
    [513, -514].pack("s*")  # => "\001\002\376\375"

ビッグエンディアン:

    "\001\002\376\375".unpack("s*") # => [258, -259]

    [258, 65277].pack("s*") # => "\001\002\376\375"
    [258, -259].pack("s*")  # => "\001\002\376\375"

S

unsigned short (16bit 符号なし整数, エンディアンに依存) (S! は 16bit でなく、short のサイズに依存)

リトルエンディアン:

    "\001\002\376\375".unpack("S*") # => [513, 65022]

    [513, 65022].pack("s*") # => "\001\002\376\375"
    [513, -514].pack("s*")  # => "\001\002\376\375"

ビッグエンディアン:

    "\001\002\376\375".unpack("S*") # => [258, 65277]

    [258, 65277].pack("S*") # => "\001\002\376\375"
    [258, -259].pack("S*")  # => "\001\002\376\375"

i

int (符号つき整数, エンディアンと int のサイズに依存)

リトルエンディアン, 32bit int:

    "\001\002\003\004\377\376\375\374".unpack("i*") # => [67305985, -50462977]

    [67305985, 4244504319].pack("i*") # => RangeError
    [67305985, -50462977].pack("i*")  # => "\001\002\003\004\377\376\375\374"

ビッグエンディアン, 32bit int:

    "\001\002\003\004\377\376\375\374".unpack("i*") # => [16909060, -66052]

    [16909060, 4294901244].pack("i*") # => RangeError
    [16909060, -66052].pack("i*")     # => "\001\002\003\004\377\376\375\374"

I

unsigned int (符号なし整数, エンディアンと int のサイズに依存)

リトルエンディアン, 32bit int:

    "\001\002\003\004\377\376\375\374".unpack("I*") # => [67305985, 4244504319]

    [67305985, 4244504319].pack("I*") # => "\001\002\003\004\377\376\375\374"
    [67305985, -50462977].pack("I*")  # => "\001\002\003\004\377\376\375\374"

ビッグエンディアン, 32bit int:

    "\001\002\003\004\377\376\375\374".unpack("I*") # => [16909060, 4294901244]

    [16909060, 4294901244].pack("I*") # => "\001\002\003\004\377\376\375\374"
    [16909060, -66052].pack("I*")     # => "\001\002\003\004\377\376\375\374"

l

long (32bit 符号つき整数, エンディアンに依存) (l! は 32bit でなく、long のサイズに依存)

リトルエンディアン, 32bit long:

    "\001\002\003\004\377\376\375\374".unpack("l*") # => [67305985, -50462977]

    [67305985, 4244504319].pack("l*") # => RangeError
    [67305985, -50462977].pack("l*")  # => "\001\002\003\004\377\376\375\374"

L

unsigned long (32bit 符号なし整数, エンディアンに依存) (L! は 32bit でなく、long のサイズに依存)

リトルエンディアン, 32bit long:

    "\001\002\003\004\377\376\375\374".unpack("L*") # => [67305985, 4244504319]

    [67305985, 4244504319].pack("L*") # => "\001\002\003\004\377\376\375\374"
    [67305985, -50462977].pack("L*")  # => "\001\002\003\004\377\376\375\374"

q

long long (符号付き整数, エンディアンと long long のサイズに依存) (C で long long が扱えない場合には 64bit)

リトルエンディアン, 64bit long long:

    "\001\002\003\004\005\006\007\010\377\376\375\374\373\372\371\370".unpack("q*")
    # => [578437695752307201, -506097522914230529]

    [578437695752307201, -506097522914230529].pack("q*")
    # => "\001\002\003\004\005\006\a\010\377\376\375\374\373\372\371\370"
    [578437695752307201, 17940646550795321087].pack("q*")
    # => "\001\002\003\004\005\006\a\010\377\376\375\374\373\372\371\370"

Q

unsigned long long (符号なし整数, エンディアンと long long のサイズに依存) (C で long long が扱えない場合には 64bit)

リトルエンディアン, 64bit long long:

    "\001\002\003\004\005\006\007\010\377\376\375\374\373\372\371\370".unpack("Q*")
    # => [578437695752307201, 17940646550795321087]

    [578437695752307201, 17940646550795321087].pack("Q*")
    # => "\001\002\003\004\005\006\a\010\377\376\375\374\373\372\371\370"
    [578437695752307201, -506097522914230529].pack("Q*")
    # => "\001\002\003\004\005\006\a\010\377\376\375\374\373\372\371\370"

m

base64された文字列。60 オクテットごと(と最後)に改行コードが付加されます。

Base64は、3オクテット(8bits * 3 = 24bits)のバイナリコードをASCII文字のうちの65文字 ([A-Za-z0-9+/]の64文字とpaddingのための'=')だけを使用して 4オクテット(6bits * 4 = 24bits)の印字可能文字列に変換するエンコーディング法です。[RFC2045], [RFC4648] で定義されています。

    [""].pack("m")             # => ""
    ["\0"].pack("m")           # => "AA==\n"
    ["\0\0"].pack("m")         # => "AAA=\n"
    ["\0\0\0"].pack("m")       # => "AAAA\n"
    ["\377"].pack("m")         # => "/w==\n"
    ["\377\377"].pack("m")     # => "//8=\n"
    ["\377\377\377"].pack("m") # => "////\n"

    ["abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"].pack("m")
    # => "YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXpBQkNERUZHSElKS0xNTk9QUVJT\nVFVWV1hZWg==\n"
    ["abcdefghijklmnopqrstuvwxyz"].pack("m3")
    # => "YWJj\nZGVm\nZ2hp\namts\nbW5v\ncHFy\nc3R1\ndnd4\neXo=\n"

    "".unpack("m")       # => [""]
    "AA==\n".unpack("m") # => ["\000"]
    "AA==".unpack("m")   # => ["\000"]

    "YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXpBQkNERUZHSElKS0xNTk9QUVJT\nVFVWV1hZWg==\n".unpack("m")
    # => ["abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"]
    "YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXpBQkNERUZHSElKS0xNTk9QUVJTVFVWV1hZWg==\n".unpack("m")
    # => ["abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"]

m0 は [RFC4648] 対応

    [""].pack("m0")             # => ""
    ["\0"].pack("m0")           # => "AA=="
    ["\0\0"].pack("m0")         # => "AAA="
    ["\0\0\0"].pack("m0")       # => "AAAA"
    ["\377"].pack("m0")         # => "/w=="
    ["\377\377"].pack("m0")     # => "//8="
    ["\377\377\377"].pack("m0") # => "////"

    ["abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"].pack("m0")
    # => "YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXpBQkNERUZHSElKS0xNTk9QUVJTVFVWV1hZWg=="

    "".unpack("m0")       # => [""]
    "AA==\n".unpack("m0") # => ArgumentError
    "AA==".unpack("m0")   # => ["\x00"]

    "YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXpBQkNERUZHSElKS0xNTk9QUVJTVFVWV1hZWg==".unpack("m0")
    # => ["abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"]

[SEE_ALSO] base64

M

quoted-printable encoding された文字列

    ["a b c\td \ne"].pack("M") # => "a b c\td =\n\ne=\n"

    "a b c\td =\n\ne=\n".unpack("M") # => ["a b c\td \ne"]

n

ネットワークバイトオーダー(ビッグエンディアン)のunsigned short (16bit 符号なし整数)

    [0,1,-1,32767,-32768,65535].pack("n*")
    # => "\000\000\000\001\377\377\177\377\200\000\377\377"

    "\000\000\000\001\377\377\177\377\200\000\377\377".unpack("n*")
    # => [0, 1, 65535, 32767, 32768, 65535]

N

ネットワークバイトオーダー(ビッグエンディアン)のunsigned long (32bit 符号なし整数)

    [0,1,-1].pack("N*") # => "\000\000\000\000\000\000\000\001\377\377\377\377"

    "\000\000\000\000\000\000\000\001\377\377\377\377".unpack("N*") # => [0, 1, 4294967295]

v

"VAX"バイトオーダー(リトルエンディアン)のunsigned short (16bit 符号なし整数)

    [0,1,-1,32767,-32768,65535].pack("v*")
    # => "\000\000\001\000\377\377\377\177\000\200\377\377"

    "\000\000\001\000\377\377\377\177\000\200\377\377".unpack("v*")
    # => [0, 1, 65535, 32767, 32768, 65535]

V

"VAX"バイトオーダー(リトルエンディアン)のunsigned long (32bit 符号なし整数)

    [0,1,-1].pack("V*") # => "\000\000\000\000\001\000\000\000\377\377\377\377"

    "\000\000\000\000\001\000\000\000\377\377\377\377".unpack("V*") # => [0, 1, 4294967295]

f

単精度浮動小数点数(機種依存)

IA-32 (x86) (IEEE754 単精度リトルエンディアン):

    [1.0].pack("f")      # => "\000\000\200?"
    [0.0/0.0].pack("f")  # => "\000\000\300\377"      # NaN
    [1.0/0.0].pack("f")  # => "\000\000\200\177"      # +Inf
    [-1.0/0.0].pack("f") # => "\000\000\200\377"      # -Inf

SPARC (IEEE754 単精度ビッグエンディアン):

    [1.0].pack("f")      # => "?\200\000\000"
    [0.0/0.0].pack("f")  # => "\177\377\377\377"      # NaN
    [1.0/0.0].pack("f")  # => "\177\200\000\000"      # +Inf
    [-1.0/0.0].pack("f") # => "\377\200\000\000"      # -Inf

VAX (NetBSD 3.0) (非IEEE754):

    [1.0].pack("f") # => "\200@\000\000"

d

倍精度浮動小数点数(機種依存)

IA-32 (IEEE754 倍精度リトルエンディアン):

    [1.0].pack("d")      # => "\000\000\000\000\000\000\360?"
    [0.0/0.0].pack("d")  # => "\000\000\000\000\000\000\370\377"      # NaN
    [1.0/0.0].pack("d")  # => "\000\000\000\000\000\000\360\177"      # +Inf
    [-1.0/0.0].pack("d") # => "\000\000\000\000\000\000\360\377"      # -Inf

SPARC (IEEE754 倍精度ビッグエンディアン):

    [1.0].pack("d")      # => "?\360\000\000\000\000\000\000"
    [0.0/0.0].pack("d")  # => "\177\377\377\377\377\377\377\377"      # NaN
    [1.0/0.0].pack("d")  # => "\177\360\000\000\000\000\000\000"      # +Inf
    [-1.0/0.0].pack("d") # => "\377\360\000\000\000\000\000\000"      # -Inf

VAX (NetBSD 3.0) (非IEEE754):

    [1.0].pack("d") # => "\200@\000\000\000\000\000\000"

e

リトルエンディアンの単精度浮動小数点数(機種依存)

IA-32 (IEEE754):

    [1.0].pack("e") # => "\000\000\200?"

SPARC (IEEE754):

    [1.0].pack("e") # => "\000\000\200?"

E

リトルエンディアンの倍精度浮動小数点数(機種依存)

IA-32 (IEEE754):

    [1.0].pack("E") # => "\000\000\000\000\000\000\360?"

SPARC (IEEE754):

    [1.0].pack("E") # => "\000\000\000\000\000\000\360?"

g

ビッグエンディアンの単精度浮動小数点数(機種依存)

IA-32 (IEEE754):

    [1.0].pack("g") # => "?\200\000\000"

SPARC (IEEE754):

    [1.0].pack("g") # => "?\200\000\000"

IEEE754準拠な環境の場合、以下のようにして符号、指数部、仮数部を取り出せます。

    s = [v].pack("g").unpack("B*")[0][0,1]      # 符号
    e = [v].pack("g").unpack("B*")[0][1,8]      # 指数部
    f = [v].pack("g").unpack("B*")[0][9,23]     # 仮数部

そして、s, e, f の意味は以下の通りです。

    sgn = s == "0" ? +1.0 : -1.0
    exp = Integer("0b" + e)
    fra = Integer("0b" + f)
    if exp == 0
      if fra == 0
        sgn * 0                     # ±0 (positive/negative zero)
      else
        sgn * fra * 2**(-126-23)    # 非正規化数 (denormalized number)
      end
    elsif exp == 255
      if fra == 0
        sgn * Inf                   # ±∞ (positive/negative infinity)
      else
        NaN                         # 非数 (not a number)
      end
    else
      fra += 1 << 23                # ゲタ
      sgn * fra * 2**(exp-127-23)   # 正規化数 (normalized number)
    end

G

ビッグエンディアンの倍精度浮動小数点数(機種依存)

IA-32:

    [1.0].pack("G") # => "?\360\000\000\000\000\000\000"

SPARC:

    [1.0].pack("G") # => "?\360\000\000\000\000\000\000"

IEEE754準拠な環境の場合、以下のようにして符号、指数部、仮数部を取り出せます。

    s = [v].pack("G").unpack("B*")[0][0,1]    # 符号
    e = [v].pack("G").unpack("B*")[0][1,11]   # 指数部
    f = [v].pack("G").unpack("B*")[0][12,52]  # 仮数部

そして、s, e, f の意味は以下の通りです。

    sgn = s == "0" ? +1.0 : -1.0
    exp = Integer("0b" + e)
    fra = Integer("0b" + f)
    if exp == 0
      if fra == 0
        sgn * 0                     # ±0 (positive/negative zero)
      else
        sgn * fra * 2**(-1022-52)   # 非正規化数 (denormalized number)
      end
    elsif exp == 2047
      if fra == 0
        sgn * Inf                   # ±∞ (positive/negative infinity)
      else
        NaN                         # 非数 (not a number)
      end
    else
      fra += 1 << 52                # ゲタ
      sgn * fra * 2**(exp-1023-52)  # 正規化数 (normalized number)
    end

p

ナル終端の文字列へのポインタ

    [""].pack("p")             # => "\310\037\034\010"
    ["a", "b", "c"].pack("p3") # => " =\030\010\340^\030\010\360^\030\010"
    [nil].pack("p")            # => "\000\000\000\000"

P

構造体(固定長文字列)へのポインタ

    [nil].pack("P")    # => "\000\000\000\000"
    ["abc"].pack("P3") # => "x*\024\010"

    ["abc"].pack("P4") # => ArgumentError: too short buffer for P(3 for 4)
    [""].pack("P")     # => ArgumentError: too short buffer for P(0 for 1)

u

uuencodeされた文字列

    [""].pack("u")           # => ""
    ["a"].pack("u")          # => "!80``\n"
    ["abc"].pack("u")        # => "#86)C\n"
    ["abcd"].pack("u")       # => "$86)C9```\n"
    ["a"*45].pack("u")       # => "M86%A86%A86%A86%A86%A86%A86%A86%A86%A86%A86%A86%A86%A86%A86%A\n"
    ["a"*46].pack("u")       # => "M86%A86%A86%A86%A86%A86%A86%A86%A86%A86%A86%A86%A86%A86%A86%A\n!80``\n"
    ["abcdefghi"].pack("u6") # => "&86)C9&5F\n#9VAI\n"

U

UTF-8

    [0].pack("U")                               # => "\000"
    [1].pack("U")                               # => "\001"
    [0x7f].pack("U")                            # => "\177"
    [0x80].pack("U")                            # => "\302\200"
    [0x7fffffff].pack("U")                      # => "\375\277\277\277\277\277"
    [0x80000000].pack("U")                      # => RangeError
    [0,256,65536].pack("U3")                    # => "\000\304\200\360\220\200\200"

    "\000\304\200\360\220\200\200".unpack("U3") # => [0, 256, 65536]
    "\000\304\200\360\220\200\200".unpack("U")  # => [0]
    "\000\304\200\360\220\200\200".unpack("U*") # => [0, 256, 65536]

w

BER圧縮整数

1バイトあたり7ビットを使用して必要最小限のバイト数で任意サイズの 0以上の整数を表す数値表現。各バイトの最上位ビットはデータの最後を除いて必ず1が立っている(つまり最上位ビットはどこまでデータがあるかを示している)。

ISO/IEC 8825-1:1995 : Information technology−ASN.1 encoding rules : Specification of Basic Encoding Rules(BER) に定められる整数の符号化方法。

    [0].pack("w")             # => "\000"
    [1].pack("w")             # => "\001"
    [127].pack("w")           # => "\177"
    [128].pack("w")           # => "\201\000"
    [0x3fff].pack("w")        # => "\377\177"
    [0x4000].pack("w")        # => "\201\200\000"
    [0x3fffffff].pack("w")    # => "\203\377\377\377\177"
    [0x40000000].pack("w")    # => "\204\200\200\200\000"
    [0xffffffff].pack("w")    # => "\217\377\377\377\177"
    [0x100000000].pack("w")   # => "\220\200\200\200\000"

    "\0".unpack("w")          # => [0]
    "\0\201\0\1".unpack("w*") # => [0, 128, 1]

なお、BER圧縮整数でエンコードした結果は大小関係を保存しない。たとえば、[0x3fff].pack("w") > [0x4000].pack("w") である。

x

ナルバイト/1バイト読み飛ばす

    [?a, ?b].pack("CxC")    # => "a\000b"
    [?a, ?b].pack("Cx3C")   # => "a\000\000\000b"

    "a\000b".unpack("CxC")  # => [97, 98]
    "a\377b".unpack("CxC")  # => [97, 98]
    "a\377b".unpack("Cx3C") # => ArgumentError: x outside of string

X

1バイト後退

    [?a, ?b, ?c].pack("CCXC") # => "ac"

    "abcdef".unpack("x*XC") # => [102]

@

絶対位置への移動

    [?a, ?b].pack("C @3 C") # => "a\000\000b"

    "a\000\000b".unpack("C @3 C") # => [97, 98]

使用例

以下、pack/unpack の使用例の一部です。

pack を使用しなくても同じことができる場合はその例も載せています。 pack は暗号になりやすい面があることを考慮し、pack を使いたくない人に別解を示すためです。

数値(文字コード)の配列を文字列に変換する例

    [82, 117, 98, 121].pack("cccc")  # => "Ruby"
    [82, 117, 98, 121].pack("c4")    # => "Ruby"
    [82, 117, 98, 121].pack("c*")    # => "Ruby"

    s = ""
    [82, 117, 98, 121].each {|c| s << c}
    s    # => "Ruby"

    [82, 117, 98, 121].collect {|c| sprintf "%c", c}.join   # => "Ruby"

    [82, 117, 98, 121].inject("") {|s, c| s << c}    # => "Ruby"

文字列を数値(文字コード)の配列に変換する例

    "Ruby".unpack('C*')    # => [82, 117, 98, 121]

    a = []
    "Ruby".each_byte {|c| a << c}
    a    # => [82, 117, 98, 121]

"x" でナルバイトを埋めることができる

    [82, 117, 98, 121].pack("ccxxcc")    # => "Ru\000\000by"

"x" で文字を読み飛ばす事が出来る

    "Ru\0\0by".unpack('ccxxcc')    # => [82, 117, 98, 121]

Hexダンプを数値の配列に変換する例

    "61 62 63 64 65 66".delete(' ').to_a.pack('H*').unpack('C*')
    # => [97, 98, 99, 100, 101, 102]

    "61 62 63 64 65 66".split.collect {|c| c.hex}
    # => [97, 98, 99, 100, 101, 102]

バイナリと16進数のpackでは長さ指定は生成されるバイト数ではなく、ビットやニブルの個数を表す

    [0b01010010, 0b01110101, 0b01100010, 0b01111001].pack("C4")
    # => "Ruby"
    ["01010010011101010110001001111001"].pack("B32") # 8 bits * 4
    # => "Ruby"

    [0x52, 0x75, 0x62, 0x79].pack("C4")
    # => "Ruby"
    ["52756279"].pack("H8")  # 2 nybbles * 4
    # => "Ruby"

テンプレート文字'a'の長さ指定は1つの文字列だけに適用される

    ["RUBY", "u", "b", "y"].pack("a4")
    # => "RUBY"

    ["RUBY", "u", "b", "y"].pack("aaaa")
    # => "Ruby"

    ["RUBY", "u", "b", "y"].pack("a*aaa")
    # => "RUBYuby"

テンプレート文字"a"は、長さが足りない分をヌル文字で補う

    ["Ruby"].pack("a8")
    # => "Ruby\000\000\000\000"

リトルエンディアンとビッグエンディアン

    [1,2].pack("s2")
    # => "\000\001\000\002" # ビッグエンディアンのシステムでの出力
    # => "\001\000\002\000" # リトルエンディアンのシステムでの出力

    [1,2].pack("n2")
    # => "\000\001\000\002" # システムによらずビッグエンディアン

    [1,2].pack("v2")
    # => "\001\000\002\000" # システムによらずリトルエンディアン

ネットワークバイトオーダの signed long

      s = "\xff\xff\xff\xfe"
      n = s.unpack("N")[0]
      if n[31] == 1
        n = -((n ^ 0xffff_ffff) + 1)
      end
      n # => -2

ネットワークバイトオーダの signed long(その2)

      s = "\xff\xff\xff\xfe"
      n = s.unpack("N").pack("l").unpack("l")[0]
      n # => -2

IPアドレス

      require 'socket'
      Socket.gethostbyname("localhost")[3].unpack("C4").join(".")
      # => "127.0.0.1"

      "127.0.0.1".split(".").collect {|c| c.to_i}.pack("C4")
      # => "\177\000\000\001"

sockaddr_in 構造体

      require 'socket'
      [Socket::AF_INET,
       Socket.getservbyname('echo'),
       127, 0, 0, 1].pack("s n C4 x8")
      # => "\002\000\000\a\177\000\000\001\000\000\000\000\000\000\000\000"

pack/unpack を使う代わりに Socket.pack_sockaddr_in, Socket.unpack_sockaddr_in メソッドがあります。

'\0'終端文字列のアドレス

テンプレート文字 "p" や "P" は、C 言語レベルのインタフェースのためにあります(例えば IO#ioctl)。

    ["foo"].pack("p")    # => "8\266\021\010"

結果の文字列はゴミに見えますが、実際は文字列"foo\0"を指すアドレス(のバイナリ表現)です。以下のようにすれば見慣れた表記で見ることが出来ます

    printf "%#010x\n", "8\266\021\010".unpack("L")[0] # => 0x0811b638

アドレスが指す先のオブジェクト(この例で "foo\0") は、pack の結果が GC されるまではGCされないことが保証されています。

unpack("p"), unpack("P") は、pack の結果からしか unpack できません。

    ["foo"].pack("p").unpack("p") # => ["foo"]
    "8\266\021\010".unpack("p")
    # => -:1:in `unpack': no associated pointer (ArgumentError)
    #         from -:1

"p" や "P" は、nil を特別に扱い NULL ポインタとして解釈します。(以下は、32bitマシンで一般的な結果)

      [nil].pack("p")        # => "\000\000\000\000"
      "\0\0\0\0".unpack("p") # => [nil]

構造体のアドレス

例えば、

      struct {
        int   a;
        short b;
        long  c;
      } v = {1,2,3};

を表す文字列は

      v = [1,2,3].pack("i!s!l!")

です。(byte alignment の問題から実際は適当な padding が必要になるかもしれません)

この構造体を指すアドレスは

      [v].pack("P")  # => "\300\265\021\010"

で得られます。

UTF-8からUCS-2への変換 (サロゲートを処理していないので UTF-16 とはいえない)

Little endian:

    ("Comments").unpack("U*").pack("v*") # => "C\000o\000m\000m\000e\000n\000t\000s\000"

Big endian:

    ("Comments").unpack("U*").pack("n*") # => "\000C\000o\000m\000m\000e\000n\000t\000s"

permutation(n = self.length) { |p| block } -> Array[permalink][rdoc]

permutation(n = self.length) -> Enumerator

サイズ n の順列をすべて生成し，それを引数としてブロックを実行します。

引数を省略した場合は配列の要素数と同じサイズの順列に対してブロックを実行します。

得られる順列の順序は保証されません。ブロックなしで呼び出されると，順列を生成する Enumerator オブジェクトを返します。

[PARAM] n:: 生成する配列のサイズを整数で指定します。整数以外のオブジェクトを指定した場合は to_int メソッドによる暗黙の型変換を試みます。
[EXCEPTION] TypeError:: 引数に整数以外の(暗黙の型変換が行えない)オブジェクトを指定した場合に発生します。

例:

a = [1, 2, 3]
a.permutation.to_a     #=> [[1,2,3],[1,3,2],[2,1,3],[2,3,1],[3,1,2],[3,2,1]]
a.permutation(1).to_a  #=> [[1],[2],[3]]
a.permutation(2).to_a  #=> [[1,2],[1,3],[2,1],[2,3],[3,1],[3,2]]
a.permutation(3).to_a  #=> [[1,2,3],[1,3,2],[2,1,3],[2,3,1],[3,1,2],[3,2,1]]
a.permutation(0).to_a  #=> [[]]: one permutation of length 0
a.permutation(4).to_a  #=> []  : no permutations of length 4

[SEE_ALSO] Array#combination, Array#repeated_permutation

pop -> object | nil[permalink][rdoc]

pop(n) -> Array

自身の末尾から要素を取り除いてそれを返します。引数を指定した場合はその個数だけ取り除き、それを配列で返します。

空配列の場合、n が指定されていない場合は nil を、指定されている場合は空配列を返します。また、n が自身の要素数より少ない場合はその要素数の配列を返します。どちらの場合も自身は空配列となります。

返す値と副作用の両方を利用して、個数を指定して配列を 2 分する簡単な方法として使えます。

[PARAM] n:: 自身から取り除きたい要素の個数を整数で指定します。整数以外のオブジェクトを指定した場合は to_int メソッドによる暗黙の型変換を試みます。
[EXCEPTION] TypeError:: 引数に整数以外の(暗黙の型変換が行えない)オブジェクトを指定した場合に発生します。

例:

array = [1, [2, 3], 4]
p array.pop      # => 4
p array.pop      # => [2, 3]
p array          # => [1]

p array.pop      # => 1
p array.pop      # => nil
p array          # => []
array = [1, 2, 3]
p array.pop(2)   #=> [2, 3]
p array          #=> [1]

[SEE_ALSO] Array#push, Array#shift, Array#unshift

product(*lists) -> Array[permalink][rdoc]

product(*lists) { |e| ... } -> self

レシーバの配列と引数で与えられた配列（複数可）のそれぞれから要素を1 個ずつとって配列とし，それらのすべての配列を要素とする配列を返します。

返される配列の長さは，レシーバと引数で与えられた配列の長さのすべての積になります。

[PARAM] lists:: 配列。複数指定可能。

例:

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

ブロックが与えられた場合、作成した配列の各要素を引数としてブロックを実行して self を返します。

a = []
[1,2,3].product([4,5]) {|e| a << e} # => [1,2,3]
a # => [[1,4],[1,5],[2,4],[2,5],[3,4],[3,5]]

push(*obj) -> self[permalink][rdoc]

指定された obj を順番に配列の末尾に追加します。引数を指定しなければ何もしません。

[PARAM] obj:: 自身に追加したいオブジェクトを指定します。

array = [1, 2, 3]
array.push 4
array.push [5, 6]
array.push 7, 8
p array          # => [1, 2, 3, 4, [5, 6], 7, 8]

[SEE_ALSO] Array#pop, Array#shift, Array#unshift, Array#<<

rassoc(obj) -> Array | nil[permalink][rdoc]

自身が配列の配列であると仮定して、要素の配列でインデックス 1 の要素が obj に等しいものを検索し見つかった最初の要素を返します。該当する要素がなければ nil を返します。

比較は == 演算子を使って行われます。

[PARAM] obj:: 検索するオブジェクトを指定します。

a = [[15,1], [25,2], [35,3]]
p a.rassoc(2)    # => [25, 2]

[SEE_ALSO] Array#assoc

repeated_combination(n) { |c| ... } -> Array[permalink][rdoc]

repeated_combination(n) -> Enumerator

サイズ n の重複組み合わせをすべて生成し、それを引数としてブロックを実行します。

得られる組み合わせの順序は保証されません。ブロックなしで呼び出されると、組み合わせを生成する Enumerator オブジェクトを返します。

[PARAM] n:: 生成される配列のサイズを整数で指定します。整数以外のオブジェクトを指定した場合は to_int メソッドによる暗黙の型変換を試みます。
[EXCEPTION] TypeError:: 引数に整数以外の(暗黙の型変換が行えない)オブジェクトを指定した場合に発生します。

例:

a = [1, 2, 3]
a.repeated_combination(1).to_a  #=> [[1], [2], [3]]
a.repeated_combination(2).to_a  #=> [[1,1],[1,2],[1,3],[2,2],[2,3],[3,3]]
a.repeated_combination(3).to_a  #=> [[1,1,1],[1,1,2],[1,1,3],[1,2,2],[1,2,3],
                                #    [1,3,3],[2,2,2],[2,2,3],[2,3,3],[3,3,3]]
a.repeated_combination(4).to_a  #=> [[1,1,1,1],[1,1,1,2],[1,1,1,3],[1,1,2,2],[1,1,2,3],
                                #    [1,1,3,3],[1,2,2,2],[1,2,2,3],[1,2,3,3],[1,3,3,3],
                                #    [2,2,2,2],[2,2,2,3],[2,2,3,3],[2,3,3,3],[3,3,3,3]]
a.repeated_combination(0).to_a  #=> [[]] # one combination of length 0

[SEE_ALSO] Array#repeated_permutation, Array#combination

repeated_permutation(n) { |p| ... } -> Array[permalink][rdoc]

repeated_permutation(n) -> Enumerator

サイズ n の重複順列をすべて生成し，それを引数としてブロックを実行します。

得られる順列の順序は保証されません。ブロックなしで呼び出されると，順列を生成する Enumerator オブジェクトを返します。

[PARAM] n:: 生成する配列のサイズを整数で指定します。整数以外のオブジェクトを指定した場合は to_int メソッドによる暗黙の型変換を試みます。
[EXCEPTION] TypeError:: 引数に整数以外の(暗黙の型変換が行えない)オブジェクトを指定した場合に発生します。

例:

a = [1, 2]
a.repeated_permutation(1).to_a  #=> [[1], [2]]
a.repeated_permutation(2).to_a  #=> [[1,1],[1,2],[2,1],[2,2]]
a.repeated_permutation(3).to_a  #=> [[1,1,1],[1,1,2],[1,2,1],[1,2,2],
                                #    [2,1,1],[2,1,2],[2,2,1],[2,2,2]]
a.repeated_permutation(0).to_a  #=> [[]] # one permutation of length 0

[SEE_ALSO] Array#repeated_combination, Array#permutation

replace(another) -> self[permalink][rdoc]

配列の内容を配列 another の内容で置き換えます。

[PARAM] another:: 配列を指定します。配列以外のオブジェクトを指定した場合は to_ary メソッドによる暗黙の型変換を試みます。
[EXCEPTION] TypeError:: 引数に配列以外の(暗黙の型変換が行えない)オブジェクトを指定した場合に発生します。

a = [1, 2, 3]
a.replace [4, 5, 6]
p a                 #=> [4, 5, 6]

reverse -> Array[permalink][rdoc]

reverse! -> self

reverse は自身の要素を逆順に並べた新しい配列を生成して返します。 reverse! は自身を破壊的に並べ替えます。 reverse! は self を返します。

a = ["a", 2, true]
p a.reverse         #=> [true, 2, "a"]
p a                 #=> ["a", 2, true] (変化なし)

a = ["a", 2, true]
p a.reverse!        #=> [true, 2, "a"]
p a                 #=> [true, 2, "a"]

reverse_each {|item| ... } -> self[permalink][rdoc]

reverse_each -> Enumerator

各要素に対して逆順にブロックを評価します。

ブロックが与えられなかった場合は、自身と reverse_each から生成した Enumerator オブジェクトを返します。

rindex(val) -> Integer | nil[permalink][rdoc]

rindex {|item| ... } -> Integer | nil

rindex -> Enumerator

指定された val と == で等しい最後の要素の位置を返します。等しい要素がひとつもなかった時には nil を返します。

ブロックが与えられた時には、各要素を引数として順にブロックを実行し、ブロックが真を返した最初の要素の位置を返します。

引数、ブロックのどちらも与えられなかった時には、自身と rindex から生成した Enumerator オブジェクトを返します。

[PARAM] val:: オブジェクトを指定します。

p [1, 0, 0, 1, 0].rindex(1)   #=> 3
p [1, 0, 0, 0, 0].rindex(1)   #=> 0
p [0, 0, 0, 0, 0].rindex(1)   #=> nil
p [0, 1, 0, 1, 0].rindex {|v| v > 0}   #=> 3

[SEE_ALSO] Array#index

rotate(cnt = 1) -> Array[permalink][rdoc]

cnt で指定したインデックスの要素が先頭になる配列を新しく作成します。 cnt より前の要素は末尾に移動します。cnt に負の数を指定した場合、逆の操作を行います。

[PARAM] cnt:: 先頭にする要素のインデックスを指定します。指定しなかった場合は 1 になります。整数以外のオブジェクトを指定した場合は to_int メソッドによる暗黙の型変換を試みます。
[EXCEPTION] TypeError:: 引数に整数以外の(暗黙の型変換が行えない)オブジェクトを指定した場合に発生します。

例:

a = [ "a", "b", "c", "d" ]
a.rotate         # => ["b", "c", "d", "a"]
a                # => ["a", "b", "c", "d"]
a.rotate(2)      # => ["c", "d", "a", "b"]
a.rotate(-1)     # => ["d", "a", "b", "c"]
a.rotate(-3)     # => ["b", "c", "d", "a"]

[SEE_ALSO] Array#rotate!

rotate!(cnt = 1) -> self[permalink][rdoc]

cnt で指定したインデックスの要素が先頭になるように自身の順番を変更します。cnt より前の要素は末尾に移動します。cnt に負の数を指定した場合、逆の操作を行います。

[PARAM] cnt:: 先頭にする要素のインデックスを指定します。指定しなかった場合は 1 になります。整数以外のオブジェクトを指定した場合は to_int メソッドによる暗黙の型変換を試みます。
[EXCEPTION] TypeError:: 引数に整数以外の(暗黙の型変換が行えない)オブジェクトを指定した場合に発生します。

例:

a = [ "a", "b", "c", "d" ]
a.rotate!        #=> ["b", "c", "d", "a"]
a                #=> ["b", "c", "d", "a"]
a.rotate!(2)     #=> ["d", "a", "b", "c"]
a.rotate!(-3)    #=> ["a", "b", "c", "d"]

[SEE_ALSO] Array#rotate

sample -> object | nil[permalink][rdoc]

sample(n) -> Array

sample(random: rng) -> object | nil

sample(n, random: rng) -> Array

配列の要素を1個(引数を指定した場合は自身の要素数を越えない範囲で n 個) ランダムに選んで返します。

重複したインデックスは選択されません。そのため、自身がユニークな配列の場合は返り値もユニークな配列になります。

配列が空の場合、無引数の場合は nil を、個数を指定した場合は空配列を返します。

srand()が有効です。

[PARAM] n:: 取得する要素の数を指定します。自身の要素数(self.length)以上の値を指定した場合は要素数と同じ数の配列を返します。整数以外のオブジェクトを指定した場合は to_int メソッドによる暗黙の型変換を試みます。
[PARAM] rng:: 乱数生成器(主に Random オブジェクト)を指定します。 0 以上 1 未満の値を返す rand メソッドに応答するオブジェクトであれば指定する事ができます。 Kernel.#rand、Random を使用しないオブジェクトを指定した場合、Kernel.#srandの指定に影響されません。
[EXCEPTION] TypeError:: 引数 n に整数以外の(暗黙の型変換が行えない)オブジェクトを指定した場合に発生します。
[EXCEPTION] ArgumentError:: 引数 n に負の数を指定した場合に発生します。

例:

a = (1..10).to_a
p a.sample        #=>  9
p a.sample        #=> 10
p a.sample(3)     #=> [1, 9, 3]
p a               #=> [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

select! {|item| block } -> self | nil[permalink][rdoc]

select! -> Enumerator

ブロックが false を返した要素を自身から削除します。変更があった場合は self を、変更がなかった場合には nil を返します。

a = %w{ a b c d e f }
a.select! {|v| v =~ /[a-z]/ }   # => nil
a # => ["a", "b", "c", "d", "e", "f"]

ブロックが与えられなかった場合は、自身と select! から生成した Enumerator オブジェクトを返します。

[SEE_ALSO] Array#keep_if

shift -> object | nil[permalink][rdoc]

shift(n) -> Array

配列の先頭の要素を取り除いてそれを返します。引数を指定した場合はその個数だけ取り除き、それを配列で返します。

返す値と副作用の両方を利用して、個数を指定して配列を 2 分する簡単な方法として使えます。

[PARAM] n:: 自身から取り除きたい要素の個数を非負整数で指定します。整数以外のオブジェクトを指定した場合は to_int メソッドによる暗黙の型変換を試みます。
[EXCEPTION] TypeError:: 引数に整数以外の(暗黙の型変換が行えない)オブジェクトを指定した場合に発生します。
[EXCEPTION] ArgumentError:: 引数に負の数を指定した場合に発生します。

例:

a = [0, 1, 2, 3, 4]
p a.shift            #=> 0
p a                  #=> [1, 2, 3, 4]

p [].shift           #=> nil
p [].shift(1)        #=> []

[SEE_ALSO] Array#push, Array#pop, Array#unshift

shuffle -> Array[permalink][rdoc]

shuffle(random: rng) -> Array

配列の要素をランダムシャッフルして，その結果を配列として返します。

引数に Random オブジェクトを渡すことでそのオブジェクトが生成する疑似乱数列を用いることができます。

例:

a = [ 1, 2, 3 ]           #=> [1, 2, 3]
a.shuffle                 #=> [2, 3, 1]
rng = Random.new
rng2 = rng.dup # RNGを複製
# 以下の2つは同じ結果を返す
[1,2,3].shuffle(random: rng)
[1,2,3].shuffle(random: rng2)

[SEE_ALSO] Array#shuffle!

shuffle! -> self[permalink][rdoc]

shuffle!(random: rng) -> self

配列を破壊的にランダムシャッフルします。

[PARAM] rng:: 乱数生成器(主に Random オブジェクト)を指定します。 0 以上 1 未満の値を返す rand メソッドに応答するオブジェクトであれば指定する事ができます。 Kernel.#rand、Random を使用しないオブジェクトを指定した場合、Kernel.#srandの指定に影響されません。

例:

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

[SEE_ALSO] Array#shuffle

slice(nth) -> object | nil[permalink][rdoc]

指定された自身の要素を返します。Array#[] と同じです。

[PARAM] nth:: 要素のインデックスを整数で指定します。Array#[] と同じです。

例:

p [0, 1, 2].slice(1)    #=> 1
p [0, 1, 2].slice(2)    #=> 2
p [0, 1, 2].slice(10)   #=> nil

slice(pos, len) -> Array | nil[permalink][rdoc]

slice(range) -> Array | nil

指定された自身の部分配列を返します。Array#[] と同じです。

[PARAM] pos:: Array#[] と同じです。
[PARAM] len:: Array#[] と同じです。
[PARAM] range:: Array#[] と同じです。

例:

p [0, 1, 2].slice(0, 2)    #=> [0, 1]
p [0, 1, 2].slice(2..3)    #=> [2]
p [0, 1, 2].slice(10, 1)   #=> nil

slice!(nth) -> object | nil[permalink][rdoc]

指定した要素を自身から取り除き、取り除いた要素を返します。取り除く要素がなければ nil を返します。

[PARAM] nth:: 取り除く要素のインデックスを整数で指定します。

例:

a = [ "a", "b", "c" ]
a.slice!(1)     #=> "b"
a               #=> ["a", "c"]
a.slice!(-1)    #=> "c"
a               #=> ["a"]
a.slice!(100)   #=> nil
a               #=> ["a"]

slice!(start, len) -> Array | nil[permalink][rdoc]

slice!(range) -> Array | nil

指定した部分配列を自身から取り除き、取り除いた部分配列を返します。取り除く要素がなければ nil を返します。

[PARAM] start:: 削除したい部分配列の先頭のインデックスを整数で指定します。
[PARAM] len:: 削除したい部分配列の長さを整数で指定します。
[PARAM] range:: 削除したい配列の範囲を Range オブジェクトで指定します。

例:

a = [ "a", "b", "c" ]
a.slice!(1, 2)     #=> ["b", "c"]
a                  #=> ["a"]

a = [ "a", "b", "c" ]
a.slice!(1, 0)     #=> []
a                  #=> [ "a", "b", "c" ]

sort -> Array[permalink][rdoc]

sort! -> self

sort {|a, b| ... } -> Array

sort! {|a, b| ... } -> self

配列の内容をソートします。要素同士の比較は <=> 演算子を使って行います。sort はソートされた配列を生成して返します。 sort! は self を破壊的にソートし、self を返します。

ブロックとともに呼び出された時には、要素同士の比較をブロックを用いて行います。ブロックに2つの要素を引数として与えて評価し、その結果で比較します。ブロックは <=> 演算子と同様に整数を返すことが期待されています。つまり、ブロックは第1引数が大きいなら正の整数、両者が等しいなら0、そして第1引数の方が小さいなら負の整数を返さなければいけません。両者を比較できない時は nil を返します。

a = [ "d", "a", "e", "c", "b" ]
p a.sort                                #=> ["a", "b", "c", "d", "e"]

b = ["9", "7", "10", "11", "8"]
p b.sort                                #=> ["10", "11", "7", "8", "9"] (文字列としてソートするとこうなる)
p b.sort{|x, y| x.to_i <=> y.to_i }     #=> ["7", "8", "9", "10", "11"] (ブロックを使って数字としてソート)

# sort_by を使っても良い
p b.sort_by{|x| x.to_i }                #=> ["7", "8", "9", "10", "11"]

[SEE_ALSO] Enumerable#sort_by , Array#sort_by!

sort_by! -> Enumerator[permalink][rdoc]

sort_by! {|item| ... } -> self

sort_by の破壊的バージョンです。

ブロックを省略した場合は返り値によって配列を破壊的にソートする Enumerator を返します。

[SEE_ALSO] Enumerable#sort_by

to_a -> Array[permalink][rdoc]

self を返します。ただし、Array のサブクラスのインスタンスに対して呼ばれた時は、自身を Array に変換したものを返します。

to_ary -> self[permalink][rdoc]

self をそのまま返します。

transpose -> Array[permalink][rdoc]

自身を行列と見立てて、行列の転置(行と列の入れ換え)を行います。転置した配列を生成して返します。空の配列に対しては空の配列を生成して返します。

それ以外の一次元の配列に対しては、例外 TypeError が発生します。各要素のサイズが不揃いな配列に対しては、例外 IndexError が発生します。

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

p [].transpose
# => []

p [1,2,3].transpose

# => -:1:in `transpose': cannot convert Fixnum into Array (TypeError)
        from -:1

p [[1,2],
   [3,4,5],
   [6,7]].transpose
# => -:3:in `transpose': element size differ (3 should be 2) (IndexError)

uniq -> Array[permalink][rdoc]

uniq! -> self | nil

uniq {|item| ... } -> Array

uniq! {|item| ... } -> self | nil

uniq は配列から重複した要素を取り除いた新しい配列を返します。 uniq! は削除を破壊的に行い、削除が行われた場合は self を、そうでなければnil を返します。

取り除かれた要素の部分は前に詰められます。要素の重複判定は、Object#eql? により行われます。

p [1, 1, 1].uniq         # => [1]
p [1, 4, 1].uniq         # => [1, 4]
p [1, 3, 2, 2, 3].uniq   # => [1, 3, 2]

ブロックが与えられた場合、ブロックが返した値が重複した要素を取り除いた配列を返します。

p [1, 3, 2, "2", "3"].uniq                # => [1, 3, 2, "2", "3"]
p [1, 3, 2, "2", "3"].uniq { |n| n.to_s } # => [1, 3, 2]

unshift(*obj) -> self[permalink][rdoc]

指定された obj を引数の最後から順番に配列の先頭に挿入します。引数を指定しなければ何もしません。

[PARAM] obj:: 自身に追加したいオブジェクトを指定します。

arr = [1,2,3]
arr.unshift 0
p arr             #=> [0, 1, 2, 3]
arr.unshift [0]
p arr             #=> [[0], 0, 1, 2, 3]
arr.unshift 1, 2
p arr             #=> [1, 2, [0], 0, 1, 2, 3]

[SEE_ALSO] Array#push, Array#pop, Array#shift

values_at(*selectors) -> Array[permalink][rdoc]

引数で指定されたインデックスに対応する要素を配列で返します。インデックスに対応する値がなければ nil が要素になります。

[PARAM] selectors:: インデックスを整数もしくは整数の Range で指定します。 Range の場合は、Range#begin が配列のサイズを越える場合は無視され、 Range#end が配列のサイズを越えるまで対応する要素が選択されます。ちょうど配列のサイズを指す場合は、nil で埋められます。

ary = %w( a b c d e )
p ary.values_at( 0, 2, 4 )          #=> ["a", "c", "e"]
p ary.values_at( 3, 4, 5, 6, 35 )   #=> ["d", "e", nil, nil, nil]
p ary.values_at( 0, -1, -2 )        #=> ["a", "e", "d"]
p ary.values_at( -4, -5, -6, -35 )  #=> ["b", "a", nil, nil]
p ary.values_at( 1..2 )             #=> ["b", "c"]
p ary.values_at( 3..10 )            #=> ["d", "e", nil]
p ary.values_at( 6..7 )             #=> []
p ary.values_at( 0, 3..5 )          #=> ["a", "d", "e", nil]

zip(*lists) -> [[object]][permalink][rdoc]

zip(*lists) {|v1, v2, ...| ...} -> nil

自身と引数に渡した配列の各要素からなる配列の配列を生成して返します。生成される配列の要素数は self の要素数と同じです。

ブロック付きで呼び出した場合は、 self と引数に渡した配列の各要素を順番にブロックに渡します。

[PARAM] lists:: 配列を指定します。配列以外のオブジェクトを指定した場合は to_ary メソッドによる暗黙の型変換を試みます。to_ary メソッドに応答できない場合は each メソッドによる暗黙の型変換を試みます。
[EXCEPTION] NoMethodError:: 引数に配列以外の(暗黙の型変換が行えない)オブジェクトを指定した場合に発生します。

例:

p [1,2,3].zip([4,5,6], [7,8,9])
    # => [[1, 4, 7], [2, 5, 8], [3, 6, 9]]

p [1,2].zip([:a,:b,:c], [:A,:B,:C,:D])
    # => [[1, :a, :A], [2, :b, :B]]

p [1,2,3,4,5].zip([:a,:b,:c], [:A,:B,:C,:D])
    # => [[1, :a, :A], [2, :b, :B],
    #     [3, :c, :C], [4, nil, :D], [5, nil, nil]]

p [1,2,3].zip([4,5,6], [7,8,9]) {|ary|
  p ary
}
    # => [1, 4, 7]
    #    [2, 5, 8]
    #    [3, 6, 9]
    #    nil

self | other -> Array[permalink][rdoc]

集合の和演算です。両方の配列にいずれかに含まれる要素を全て含む新しい配列を返します。重複する要素は取り除かれます。

要素の重複判定は、Object#eql? により行われます。

[PARAM] other:: 配列を指定します。配列以外のオブジェクトを指定した場合は to_ary メソッドによる暗黙の型変換を試みます。
[EXCEPTION] TypeError:: 引数に配列以外の(暗黙の型変換が行えない)オブジェクトを指定した場合に発生します。

[1, 1, 4, 2, 3] | [4, 5, 5]  #=> [1, 4, 2, 3, 5]

[SEE_ALSO] Array#&

class Array

要約

目次

特異メソッド

インスタンスメソッド

整数のテンプレート文字のシステム依存性

各テンプレート文字の説明

使用例