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

class Array + Enumerable

クラスの継承リスト: Array < Enumerable < Object < Kernel

要約

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

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

[1, 2, 3]

のように生成します。

特異メソッド

self[*item] -> Array

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

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

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

[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

指定された配列 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

長さ 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"]  (各要素は違うオブジェクトである)

インスタンスメソッド

self & other -> Array

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

要素の重複判定は、Object#eql? により行われます。 処理の高速化のために内部で Hash を使用しているためです。

[PARAM] other:
配列を指定します。other が配列でなければ to_ary メソッドによる暗黙の型変換を試みます。
[1, 1, 2, 3] & [1, 3, 4] #=> [1, 3]
self * times -> Array

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

[PARAM] times:
繰り返したい回数を整数で指定します。
p [1, 2, 3] * 3  #=> [1, 2, 3, 1, 2, 3, 1, 2, 3]
self * sep -> String

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

[PARAM] sep:
文字列を指定します。
p [1,2,3] * ","
# => "1,2,3"

[SEE_ALSO] Array#join

self + other -> Array

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

[PARAM] other:
自身と繋げたい配列を指定します。other が配列でなければ other.to_ary の戻り値を用います。
[EXCEPTION] TypeError:
other が配列でなく、さらに other.to_ary の戻り値がまた配列でなかった場合に発生します。
a = [1, 2]
b = [8, 9]
p a + b     #=> [1, 2, 8, 9]
p a         #=> [1, 2]        (変化なし)
p b         #=> [8, 9]        (こちらも変化なし)
self - other -> Array

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

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

[PARAM] other:
自身から取り除きたい要素の配列を指定します。other が配列でなければ to_ary メソッドによる暗黙の型変換を試みます。
[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

指定された obj を自身の末尾に破壊的に追加します。Array#push と同じです。

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

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

ary = [1]
ary << 2 << 3 << 4
p ary   #=> [1, 2, 3, 4]
[PARAM] obj:
自身に加えたいオブジェクトを指定します。
self <=> other -> -1 | 0 | 1

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

[PARAM] other:
自身と比較したい配列を指定します。
[ 1, 2, 3 ] <=> [ 1, 3, 2 ]       #=> -1
[ 1, 2, 3 ] <=> [ 1, 2 ]          #=> 1
self == other -> bool

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

[PARAM] other:
自身と比較したい配列を指定します。
self[nth] -> object | nil
at(nth) -> object | nil

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

[PARAM] nth:
インデックスを整数で指定します。 先頭の要素が 0 番目になります。nth の値が負の時には末尾からのインデックスと見倣します。末尾 の要素が -1 番目になります。

例:

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

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

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

[PARAM] start:
生成したい部分配列の先頭のインデックスを整数で指定します。 start の値が負の時には末尾からのインデックスと見倣します。末尾の要素が -1 番目になります。
[PARAM] length:
生成したい部分配列の長さを整数で指定します。 length が start 番目からの配列の長さより長い時には、越えた分の長さは無視されます。

例:

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

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

[PARAM] nth:
インデックスを整数で指定します。
[PARAM] val:
設定したい要素の値を指定します。
[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

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 の範囲に設定したい要素を配列で指定します。 val が配列でないときには val.to_ary もしくは [val] の内容で置換します。 val の要素の数の方が range の長さより大きい時には、後ろの要素がずれます。 val が nil か 空の配列 [] なら start から end までの要素が削除されます。
    ary = [0, 1, 2, 3, 4, 5]
    ary[2..4] = nil
    p ary   # => [0, 1, 5]
[EXCEPTION] RangeError:
指定された範囲の始点が自身の始点よりも前にある場合に発生します。

例:

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

インデックス 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 番目になります。
[PARAM] length:
置き換えたい要素の個数を指定します。 length の値が 0 のときは start の直前に val を挿入します。
    ary = [0, 1, 2, 3]
    ary[1, 0] = ["inserted"]
    p ary                        # => [0, "inserted", 1, 2, 3]
[PARAM] val:
設定したい要素を配列で指定します。 val が配列でないときには val.to_ary もしくは [val] の内容で置換します。 val の長さが length と等しくない場合には、val の長さに合わせて要素が削除されたりずれたりします。 val が nil か 空の配列 [] なら start から end までの要素が削除されます。
    a = [0, 1, 2, 3, 4, 5]
    a[2, 3] = nil
    p a   # => [0, 1, 5]
[EXCEPTION] IndexError:
指定された start が自身の始点よりも前を指している場合に発生します。
all? -> bool
all? {|item| ... } -> bool

すべての要素が真である場合に true を返します。 偽である要素があれば、ただちに false を返します。

ブロックを伴う場合は、各要素に対してブロックを評価し、すべての結果 が真である場合に true を返します。ブロックが偽を返した時点で、 ただちに false を返します。

例:

# すべて正の数か?
p [5,  6, 7].all? {|v| v > 0 }   # => true
p [5, -1, 7].all? {|v| v > 0 }   # => false
any? -> bool
any? {|item| ... } -> bool

すべての要素が偽である場合に false を返します。 真である要素があれば、ただちに true を返します。

ブロックを伴う場合は、各要素に対してブロックを評価し、すべての結果 が偽である場合に false を返します。ブロックが真を返した時点 で、ただちに true を返します。

例:

p [1, 2, 3].any? {|v| v > 3 }   # => false
p [1, 2, 3].any? {|v| v > 1 }   # => true
assoc(key) -> Array | nil

配列の配列を検索して、その 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

choice -> object | nil

配列の要素を1個ランダムに選んで返します。

配列が空の場合は nil を返します。

srand()が有効です。

このメソッドは Ruby 1.8.7 と Ruby 1.9.0 にしか存在しないメソッドです。 Ruby 1.8.8 以降では Array#sample を使ってください。

例:

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

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

ary = [1, 2]
ary.clear
p ary     #=> []
clone -> Array
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| ... } -> [object]
map {|item| ... } -> [object]

各要素に対してブロックを評価した結果を全て含む配列を返します。

ブロックを省略した場合、 obj.collect {|item| item } を実行します。 これは Enumerable#to_a と同じです。

例:

# すべて 3 倍にする
p [1, 2, 3].map {|n| n * 3 }  # => [3, 6, 9]
collect! {|item| ..} -> self
map! {|item| ..} -> self
collect! -> Enumerable::Enumerator
map! -> Enumerable::Enumerator

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

ブロックが与えられなかった場合は、自身と map! から生成した Enumerable::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, Enumerable::Enumerator

combination(n) {|c| block } -> Array
combination(n) -> Enumerable::Enumerator

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

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

[PARAM] n:
生成される配列のサイズ。

例:

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

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

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

[PARAM] other:
自身と連結したい配列を指定します。
array = [1, 2]
a     = [3, 4]
array.concat a
p array          # => [1, 2, 3, 4]
p a              # => [3, 4]       # こちらは変わらない
count -> Integer
count(item) -> Integer
count {|obj| ... } -> Integer

レシーバの要素数を返します。

引数を指定しない場合は、レシーバの要素数を返します。 このとき、レシーバが size メソッドを持っていればそちらを使用します。 レシーバが size メソッドを持っていない場合は、要素数を一つずつカウントします。

引数を一つ指定した場合は、レシーバの要素のうち引数に一致するものの 個数をカウントして返します(一致は == で判定します)。

ブロックを指定した場合は、ブロックを評価して真になった要素の個数を カウントして返します。

[PARAM] item:
カウント対象となる値。

例:

ary = [1, 2, 4, 2]
ary.count             # => 4
ary.count(2)          # => 2
ary.count{|x|x%2==0}  # => 3
cycle(n=nil) {|obj| block } -> nil
cycle(n=nil) -> Enumerable::Enumerator

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

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

例:

a = ["a", "b", "c"]
a.cycle {|x| puts x }  # print, a, b, c, a, b, c,.. forever.
cycle(n=nil) -> Enumerable::Enumerator
cycle(n=nil) {|obj| ... } -> object | nil

Enumerable オブジェクトの各要素を n 回 or 無限回(n=nil)繰り返し ブロックを呼びだします。

n に 0 もしくは負の値を渡した場合は何もしません。 繰り返しが最後まで終了した場合(つまりbreakなどで中断しなかった場合) は nil を返します。 このメソッドは内部の配列に各要素を保存しておくため、 一度 Enumerable の終端に到達した後に自分自身を変更しても このメソッドの動作に影響を与えません。

a = ["a", "b", "c"]
a.cycle {|x| puts x }  # print, a, b, c, a, b, c,.. forever.
a.cycle(2) {|x| puts x }  # print, a, b, c, a, b, c.
[RETURN]
ブロックを指定しなかった場合は、Enumerable::Enumerator を返します。 レシーバが空の場合は nil を返します。
delete(val) -> object | nil
delete(val) { ... } -> object

指定された val と == で等しい要素を自身からすべて取り除きます。 val と等しい要素が見つかった場合は、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

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

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

[PARAM] pos:
削除したい要素のインデックスを整数で指定します。
array = [0, 1, 2, 3, 4]
array.delete_at 2
p array             #=> [0, 1, 3, 4]
delete_if {|x| ... } -> self
reject! {|x| ... } -> self | nil
delete_if -> Enumerable::Enumerator
reject! -> Enumerable::Enumerator

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

ブロックが与えられなかった場合は、自身と reject! から生成した Enumerable::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]  もとの配列から削除されていることに注意。
find(ifnone = nil) -> Enumerable::Enumerator
detect(ifnone = nil) -> Enumerable::Enumerator
find(ifnone = nil) {|item| ... } -> object
detect(ifnone = nil) {|item| ... } -> object

要素に対してブロックを評価した値が真になった最初の要素を返します。

真になる要素が見つからず、ifnone も指定されていないときは nil を返します。 真になる要素が見つからず、ifnone が指定されているときは ifnone を call した結果を返します。

[PARAM] ifnone:
call メソッドを持つオブジェクト (例えば Proc) を指定します。

例:

# 最初の 3 の倍数を探す
p [1, 2, 3, 4, 5].find {|i| i % 3 == 0 }   # => 3
p [2, 2, 2, 2, 2].find {|i| i % 3 == 0 }   # => nil

# ifnone の使用例
ifnone = proc { raise ArgumentError, "item not found" }
p [1, 2, 3, 4, 5].find(ifnone) {|i| i % 7 == 0 }
    # ArgumentError: item not found
drop(n) -> Array

Enumerable オブジェクトの先頭の n 要素を捨てて、 残りの要素を配列として返します。

[PARAM] n:
捨てる要素数。
a = [1, 2, 3, 4, 5, 0]
a.drop(3)             # => [4, 5, 0]
drop_while -> Enumerable::Enumerator
drop_while {|element| ... } -> Array

ブロックを評価して最初に偽となった要素の手前の要素まで捨て、 残りの要素を配列として返します。

ブロックを指定しなかった場合は、Enumerable::Enumerator を返します。

a = [1, 2, 3, 4, 5, 0]
a.drop_while {|i| i < 3 }   # => [3, 4, 5, 0]
each {|item| .... } -> self
each -> Enumerable::Enumerator

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

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

[1, 2, 3].each do |i|
  puts i
end
#=> 1
    2
    3
each_cons(n) -> Enumerable::Enumerator
enum_cons(n) -> Enumerable::Enumerator
each_cons(n) {|list| ... } -> nil
enum_cons(n) {|list| ... } -> nil

要素を重複ありで n 要素ずつに区切り、 ブロックに渡して繰り返します。

enum_cons は 1.9.1 以降ではなくなっています。 代わりに each_cons を使ってください。

[PARAM] n:
ブロックに渡す要素の数です。正の整数を与えます。 要素数より大きな数を与えると、ブロックは一度も実行されません。

例:

(1..10).each_cons(3){|v| p v }
# => [1, 2, 3]
#    [2, 3, 4]
#    [3, 4, 5]
#    [4, 5, 6]
#    [5, 6, 7]
#    [6, 7, 8]
#    [7, 8, 9]
#    [8, 9, 10]

[SEE_ALSO] Enumerable#each_slice

each_index {|index| .... } -> self
each_index -> Enumerable::Enumerator

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

以下と同じです。

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

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

each_slice(n) -> Enumerable::Enumerator
enum_slice(n) -> Enumerable::Enumerator
each_slice(n) {|list| ... } -> nil
enum_slice(n) {|list| ... } -> nil

n 要素ずつブロックに渡して繰り返します。

要素数が n で割り切れないときは、最後の回だけ要素数が減ります。

enum_slice は 1.9.1 以降ではなくなっています。 代わりに each_slice を使ってください。

[PARAM] n:
区切る要素数を示す整数です。

例:

(1..10).each_slice(3) {|a| p a}
    # => [1, 2, 3]
    #    [4, 5, 6]
    #    [7, 8, 9]
    #    [10]

[SEE_ALSO] Enumerable#each_cons

each_with_index -> Enumerable::Enumerator
enum_with_index -> Enumerable::Enumerator
each_with_index {|item, index| ... } -> self

要素とそのインデックスをブロックに渡して繰り返します。

self を返します。

例:

[5, 10, 15].each_with_index do |n, idx|
  p [n, idx]
end
    # => [5, 0]
    #    [10, 1]
    #    [15, 2]
empty? -> bool

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

p [].empty?         #=> true
p [1, 2, 3].empty?  #=> false
to_a -> [object]
entries -> [object]

全ての要素を含む配列を返します。

eql?(other) -> bool

自身と 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
fetch(nth, ifnone) -> object
fetch(nth) {|nth| ... } -> object

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

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

[PARAM] nth:
取得したい要素のインデックスを整数で指定します。
[PARAM] ifnone:
要素が存在しなかった場合に返すべき値を指定します。

例:

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
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
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_all -> Enumerable::Enumerator
select -> Enumerable::Enumerator
find_all {|item| ... } -> [object]
select {|item| ... } -> [object]

各要素に対してブロックを評価した値が真であった要素を全て含む配列を 返します。真になる要素がひとつもなかった場合は空の配列を返します。

find_index -> Enumerable::Enumerator
find_index {|obj| ... } -> Integer | nil

要素を先頭から順にブロックに渡して評価し、最初に真になった要素のインデックスを返します。 一つも真にならなければ nil を返します。

(1..10).find_index  {|i| i % 5 == 0 and i % 7 == 0 }   #=> nil
(1..100).find_index {|i| i % 5 == 0 and i % 7 == 0 }   #=> 34

ブロックを指定しなかった場合は、Enumerable::Enumerator を返します。

first -> object | nil

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

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

[SEE_ALSO] Array#last

first(n) -> Array

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

[PARAM] n:
取得したい要素の個数を整数で指定します。
[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

first -> object | nil
first(n) -> Array

Enumerable オブジェクトの最初の要素、もしくは最初の n 要素を返します。

Enumerable オブジェクトが空の場合、引数を指定しない形式では nil を返します。 引数を指定する形式では、空の配列を返します。

[PARAM] n:
取得する要素数。
e = "abcd".each_byte
e.first #=> 97
e.first(2) #=> [97,98]
e = "".each_byte
e.first #=> nil
e.first(2) #=> []
flatten(lv = nil) -> Array
flatten!(lv = nil) -> self | nil

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

[PARAM] lv:
平滑化の再帰の深さを整数で指定します。nil を指定した場合、再帰の深さの制限無しに平滑化します。
[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]]
grep(pattern) -> [object]
grep(pattern) {|item| ... } -> [object]

pattern === item が成立する要素を全て含んだ配列を返します。

ブロックとともに呼び出された時には条件の成立した要素に対して それぞれブロックを評価し、その結果の配列を返します。 マッチする要素がひとつもなかった場合は空の配列を返します。

[PARAM] pattern:
「===」メソッドを持つオブジェクトを指定します。

例:

  ['aa', 'bb', 'cc', 'dd', 'ee'].grep(/[bc]/)  # => ["bb", "cc"]

Array.instance_methods.grep(/gr/) # => ["group_by", "grep"]
group_by -> Enumerable::Enumerator
group_by {|obj| ... } -> Hash

ブロックを評価した結果をキー、対応する要素の配列を値とするハッシュを返します。

(1..6).group_by {|i| i%3}   #=> {0=>[3, 6], 1=>[1, 4], 2=>[2, 5]}
hash -> Integer

自身のハッシュ値を整数で返します。ハッシュ値は自身の各要素のハッシュ値から 計算されます。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

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

[PARAM] val:
オブジェクトを指定します。
a = [ "a", "b", "c" ]
a.include?("b")       #=> true
a.include?("z")       #=> false
member?(val) -> bool
include?(val) -> bool

val と == の関係にある要素を含むとき真を返します。

[PARAM] val:
任意のオブジェクト
index(val) -> Integer | nil
index {|item| ...} -> Integer | nil

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

ブロックが指定された場合は、各要素を引数として順にブロックを実行し、 ブロックが真を返した最初の要素の位置を返します。

[PARAM] val:
インデックスを知りたいオブジェクトを指定します。
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
p [0, 1, 0, 1, 0].index {|v| v > 0}   #=> 1

[SEE_ALSO] Array#rindex

indexes(*index) -> Array
indices(*index) -> Array

このメソッドは obsolete です。 代わりに Array#values_at を使用します。 使用すると警告メッセージが表示されます。

各引数の値をインデックスとする要素の配列を返します。範囲外の インデックス指定に対しては nil が対応します。

ary = %w( a b c d e )
p ary.indexes( 0, 2, 4 )          #=> ["a", "c", "e"]
p ary.indexes( 3, 4, 5, 6, 35 )   #=> ["d", "e", nil, nil]
p ary.indexes( 0, -1, -2 )        #=> ["a", "e", "d"]
p ary.indexes( -4, -5, -6, -35 )  #=> ["b", "a", nil, nil]
inject(init = self.first) {|result, item| ... } -> object
inject(sym) -> object
inject(init, sym) -> object
reduce(init = self.first) {|result, item| ... } -> object
reduce(sym) -> object
reduce(init, sym) -> object

リストのたたみこみ演算を行います。

最初に初期値 init と self の最初の要素を引数にブロックを実行します。 2 回目以降のループでは、前のブロックの実行結果と self の次の要素を引数に順次ブロックを実行します。 そうして最後の要素まで繰り返し、最後のブロックの実行結果を返します。

要素が存在しない場合は init を返します。

初期値 init を省略した場合は、 最初に先頭の要素と 2 番目の要素をブロックに渡します。 また要素が 1 つしかなければブロックを実行せずに最初の要素を返します。 要素がなければブロックを実行せずに nil を返します。

[PARAM] init:
最初の result の値です。任意のオブジェクトが渡せます。
[PARAM] sym:
ブロックの代わりに使われるメソッド名を表す Symbol オブジェクトを指定します。 実行結果に対して sym という名前のメソッドが呼ばれます。

例:

# 合計を計算する。
p [2, 3, 4, 5].inject {|result, item| result + item }        #=> 14

# 自乗和を計算する。初期値をセットする必要がある。
p [2, 3, 4, 5].inject(0) {|result, item| result + item**2 }  #=> 54

この式は以下のように書いても同じ結果が得られます。

result = 0
[1, 2, 3, 4, 5].each {|v| result += v }
p result   # => 15

p [1, 2, 3, 4, 5].inject(:+)                    #=> 15
p ["b", "c", "d"].inject("abbccddde", :squeeze) #=> "abcde"
insert(nth, *val) -> self

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

[PARAM] nth:
val を挿入する位置を整数で指定します。
[PARAM] val:
自身に挿入するオブジェクトを指定します。
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]
inspect -> String

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

[1, 2, 3, 4].inspect # => "[1, 2, 3, 4]"
join(sep = $,) -> String

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

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

ary = [1,2,3]
ary.push ary
p ary           # => [1, 2, 3, [...]]
p ary.join      # => "123123[...]"
[PARAM] sep:
間に挟む文字列を指定します。nil のときは空文字列を使います。
[1, 2, 3].join('-') #=> "1-2-3"

[SEE_ALSO] Array#*, $,

last -> object | nil

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

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

[SEE_ALSO] Array#first

last(n) -> Array

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

[PARAM] n:
取得したい要素の個数を整数で指定します。
[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
size -> Integer

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

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

最大の要素を返します。 全要素が互いに <=> メソッドで比較できることを仮定しています。

要素が存在しなければ nil を返します。 該当する要素が複数存在する場合、どの要素を返すかは不定です。

max {|a, b| ... } -> object

ブロックの評価結果で各要素の大小判定を行い、最大の要素を返します。 要素が存在しなければ nil を返します。

ブロックの値は、a > b のとき正、 a == b のとき 0、a < b のとき負の整数を、期待しています。

該当する要素が複数存在する場合、どの要素を返すかは不定です。

[EXCEPTION] TypeError:
ブロックが整数以外を返したときに発生します。
max_by -> Enumerable::Enumerator
max_by {|item| ... } -> object

各要素を順番にブロックに渡して実行し、 その評価結果を <=> で比較して、 最大であった値に対応する元の要素を返します。

要素が存在しないときは nil を返します。 該当する要素が複数存在する場合、どの要素を返すかは不定です。

Enumerable#maxEnumerable#max_by の 違いは Enumerable#sortEnumerable#sort_by の違いと同じです。

[SEE_ALSO] Enumerable#sort_by

min -> object

最小の要素を返します。 全要素が互いに <=> メソッドで比較できることを仮定しています。

要素が存在しなければ nil を返します。 該当する要素が複数存在する場合、どの要素を返すかは不定です。

min {|a, b| ... } -> object

ブロックの評価結果で各要素の大小判定を行い、最小の要素を返します。 要素が存在しなければ nil を返します。

ブロックの値は、a > b のとき正、a == b のとき 0、 a < b のとき負の整数を、期待しています。

該当する要素が複数存在する場合、どの要素を返すかは不定です。

[EXCEPTION] TypeError:
ブロックが整数以外を返したときに発生します。
min_by -> Enumerable::Enumerator
min_by {|item| ... } -> object

各要素を順番にブロックに渡して評価し、 その評価結果を <=> で比較して、 最小であった値に対応する元の要素を返します。

要素が存在しないときは nil を返します。

該当する要素が複数存在する場合、どの要素を返すかは不定です。

Enumerable#minEnumerable#min_by の 違いは Enumerable#sortEnumerable#sort_by の違いと同じです。

[SEE_ALSO] Enumerable#sort_by

minmax -> [object, object]
minmax {|a, b| ... } -> [object, object]

Enumerable オブジェクトの各要素のうち最小の要素と最大の要素を 要素とするサイズ 2 の配列を返します。

該当する要素が複数存在する場合、どの要素を返すかは不定です。

一つ目の形式は、Enumerable オブジェクトのすべての要素が Comparable を 実装していることを仮定しています。二つ目の形式では、要素同士の比較を ブロックを用いて行います。

a = %w(albatross dog horse)
a.minmax                                 #=> ["albatross", "horse"]
a.minmax{|a,b| a.length <=> b.length }   #=> ["dog", "albatross"]
[].minmax # => [nil, nil]

[SEE_ALSO] Enumerable#sort

minmax_by -> Enumerable::Enumerator
minmax_by {|obj| ... } -> [object, object]

Enumerable オブジェクトの各要素をブロックに渡して評価し、その結果を <=> で比較して 最小の要素と最大の要素を要素とするサイズ 2 の配列を返します。

該当する要素が複数存在する場合、どの要素を返すかは不定です。

Enumerable#minmaxEnumerable#minmax_by の 違いは sort と sort_by の違いと同じです。 詳細は Enumerable#sort_by を参照してください。

a = %w(albatross dog horse)
a.minmax_by {|x| x.length }   #=> ["dog", "albatross"]

[].minmax_by{} # => [nil, nil]

[SEE_ALSO] Enumerable#sort_by

nitems -> Integer
nitems {|obj| ... } -> Integer

nil でない要素の数を返します。

ブロックが与えられた場合は、各要素を引数として評価し nil でない値を返した 要素の数を返します。

例:

p [1, nil, 3, nil].nitems              #=> 2
p [1, nil, 3, nil].nitems{|e| e == 1}  #=> 2
none? -> bool
none? {|obj| ... } -> bool

ブロックを指定しない場合は、 Enumerable オブジェクトのすべての 要素が偽であれば真を返します。そうでなければ偽を返します。

ブロックを指定した場合は、Enumerable オブジェクトのすべての要素を ブロックで評価した結果が、すべて偽であれば真を返します。 そうでなければ偽を返します。

%w{ant bear cat}.none? {|word| word.length == 5}  #=> true
%w{ant bear cat}.none? {|word| word.length >= 4}  #=> false
[].none?                                          #=> true
[nil].none?                                       #=> true
[nil,false].none?                                 #=> true
one? -> bool
one? {|obj| ... } -> bool

ブロックを指定しない場合は、 Enumerable オブジェクトの要素のうち ちょうど一つだけが真であれば、真を返します。 そうでなければ偽を返します。

ブロックを指定した場合は、Enumerable オブジェクトの要素を ブロックで評価した結果、一つの要素だけが真であれば真を返します。 そうでなければ偽を返します。

%w{ant bear cat}.one? {|word| word.length == 4}   #=> true
%w{ant bear cat}.one? {|word| word.length >= 4}   #=> false
[ nil, true, 99 ].one?                            #=> false
[ nil, true, false ].one?                         #=> true
pack(template) -> String

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

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

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

以下にあげるものは、Array#packString#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

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

説明中、Array#packString#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終端文字列(aと同じ / 後続するnull文字を削除)

    ["abc"].pack("Z")  # => "a"
    ["abc"].pack("Z*") # => "abc"
    ["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] で定義されています。

    [""].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"]
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"
partition -> Enumerable::Enumerator
partition {|item| ... } -> [[object], [object]]

各要素を、ブロックの条件を満たす要素と満たさない要素に分割します。 各要素に対してブロックを評価して、その値が真であった要素の配列と、 偽であった要素の配列の 2 つを配列に入れて返します。

例:

[10, 9, 8, 7, 6, 5, 4, 3, 2, 1, 0].partition {|i| i % 3 == 0 }
 #=> [[9, 6, 3, 0], [10, 8, 7, 5, 4, 2, 1]]
permutation(n) { |p| block } -> Array
permutation(n) -> Enumerable::Enumerator

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

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

[PARAM] n:
生成する配列のサイズ

例:

a = [1, 2, 3]
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

pop(n = 1) -> object | Array | nil

自身の末尾から指定された n 個の要素を取り除いてそれを返します。 n を指定しなかった場合は要素そのものか nil を、n を指定した場合は、 足りればサイズが n の配列を返します。n よりも自身のサイズが 小さい時は自身のサイズになります。返す値について、順序は逆転しません (例を参照) 。

また、自身が空配列の時は n が指定されていない場合は nil を、 n が明示的に指定されている場合は (たとえ n = 1 でも) 空の配列を返します。

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

[PARAM] n:
自身から取り除きたい要素の個数を整数で指定します。

例:

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

レシーバの配列と引数で与えられた配列(複数可)のそれぞれから要素を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([])          # => []
push(*obj) -> self

指定された 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

rassoc(obj) -> Array | nil

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

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

[PARAM] obj:
オブジェクトを指定します。
a = [[15,1], [25,2], [35,3]]
p a.rassoc(2)    # => [25, 2]

[SEE_ALSO] Array#assoc

reject -> Enumerable::Enumerator
reject {|item| ... } -> [object]

各要素に対してブロックを評価し、 その値が偽であった要素を集めた新しい配列を返します。 条件を反転させた select です。

例:

# 偶数を除外する (奇数を集める)
[1, 2, 3, 4, 5, 6].reject {|i| i % 2 == 0 }  # => [1, 3, 5]

[SEE_ALSO] Enumerable#select

replace(another) -> self

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

[PARAM] another:
配列を指定します。
a = [1, 2, 3]
a.replace [4, 5, 6]
p a                 #=> [4, 5, 6]
reverse -> Array
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
reverse_each -> Enumerable::Enumerator

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

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

reverse_each -> Enumerable::Enumerator
reverse_each {|element| ... } -> self

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

内部で各要素を保持した配列を作ります。

rindex(val) -> Integer | nil
rindex {|item| ... } -> Integer | nil

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

ブロックが与えられた時には、ブロックが真を返した最後の要素の位置を返し ます。ブロックには、要素が順に渡されます。

[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

shift(n = 1) -> Array | nil

自身の先頭から指定された n 個の要素を取り除いてそれを返します。 n を指定しなかった場合は要素そのものか nil を、n を指定した場合は、 足りればサイズが n の配列を返します。n よりも自身のサイズが 小さい時は自身のサイズになります。残りの要素は前に詰められます。

また、自身が空配列の時は n が指定されていない場合は nil を、 n が明示的に指定されている場合は (たとえ n = 1 でも) 空の配列を返します。

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

[PARAM] n:
自身から取り除きたい要素の個数を非負整数で指定します。

例:

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

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

例:

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

[SEE_ALSO] Array#shuffle!

shuffle! -> self

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

例:

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

[SEE_ALSO] Array#shuffle

slice(nth) -> object | nil

指定された自身の要素を返します。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
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

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

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

例:

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
slice!(range) -> Array | nil

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

以下のコードと同値です。

def slice!(*args)
   result = self[*args]
   self[*args] = nil
   result
end

ですので以下のように配列の長さが拡張される場合もありえます。

a = [ "a", "b", "c" ]
p a.slice!(5, 1)       #=> nil
p a                    #=> ["a", "b", "c", nil, nil]
[PARAM] start:
削除したい部分配列の先頭のインデックスを整数で指定します。Array#[] と同じです。
[PARAM] len:
削除したい部分配列の長さを整数で指定します。Array#[] と同じです。
[PARAM] range:
削除したい配列の範囲を Range オブジェクトで指定します。Array#[] と同じです。
[EXCEPTION] IndexError:
指定された範囲の始点が自身の始点より前にある場合に発生します。

例:

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

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

a = [ "a", "b", "c" ]
a.slice!(-10, 1)   #=> IndexError
sort -> Array
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

sort -> [object]
sort {|a, b| ... } -> [object]

全ての要素を昇順にソートした配列を生成して返します。

ブロックなしのときは <=> メソッドを要素に対して呼び、 その結果をもとにソートします。

<=> 以外でソートしたい場合は、ブロックを指定します。 この場合、ブロックの評価結果を元にソートします。 ブロックの値は、a > b のとき正、a == b のとき 0、 a < b のとき負の整数を、期待しています。 ブロックが整数以外を返したときは例外 TypeError が発生します。

Enumerable#sort は安定ではありません (unstable sort)。 安定なソートが必要な場合は Enumerable#sort_by を使って工夫する必要があります。 詳しくは Enumerable#sort_by の項目を参照してください。

※ 比較結果が同じ要素は元の順序通りに並ぶソートを 「安定なソート (stable sort)」と言います。

[SEE_ALSO] Enumerable#sort_by

sort_by -> Enumerable::Enumerator
sort_by {|item| ... } -> [object]

ブロックの評価結果を <=> メソッドで比較することで、self を昇 順にソートします。ソートされた配列を新たに生成して返します。

つまり、以下とほぼ同じ動作をします。

class Array
  def sort_by
    self.map {|i| [yield(i), i] }.
       sort {|a, b| a[0] <=> b[0] }.
       map {|i| i[1]}
  end
end

Enumerable#sort と比較して sort_by が優れている点として、 比較条件が複雑な場合の速度が挙げられます。 sort_by を使わない以下の例では比較を行う度に downcase が実行されます。 従って downcase の実行速度が遅ければ sort の速度が致命的に低下します。

p ["BAR", "FOO", "bar", "foo"].sort {|a, b| a.downcase <=> b.downcase }

一方、次のように sort_by を使うと downcase の実行回数は要素数と同じです。 つまり、その部分の実行時間は O(n) のオーダーです。

p ["BAR", "FOO", "bar", "foo"].sort_by {|v| v.downcase }

以下の、実行回数の検証結果を参照してみてください。

class Integer
  def count
    $n += 1
    self
  end
end

ary = []
1.upto(1000) {|v| ary << rand(v) }

$n = 0
ary.sort {|a,b| a.count <=> b.count }
p $n          # => 18200

$n = 0
ary.sort_by {|v| v.count }
p $n          # => 1000

Enumerable#sort_by は安定ではありません (unstable sort)。 ただし、sort_by を以下のように使うと安定なソートを実装できます。

i = 0
ary.sort_by {|v| [v, i += 1] }

※ 比較結果が同じ要素は元の順序通りに並ぶソートを 「安定なソート (stable sort)」と言います。

[SEE_ALSO] Enumerable#sort

take(n) -> Array

Enumerable オブジェクトの先頭から n 要素を配列として返します。

[PARAM] n:
要素数を指定します。
a = [1, 2, 3, 4, 5, 0]
a.take(3)             # => [1, 2, 3]
take_while -> Enumerable::Enumerator
take_while {|element| ... } -> Array

Enumerable オブジェクトの要素を順に偽になるまでブロックで評価します。 最初に偽になった要素の手前の要素までを配列として返します。

a = [1, 2, 3, 4, 5, 0]
a.take_while {|i| i < 3 }   # => [1, 2]
to_a -> Array

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

to_ary -> self

self をそのまま返します。

to_s -> String

Array#join($,) と同じです。

[1, 2, 3, 4].to_s    # => "1234"
transpose -> Array

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

それ以外の一次元の配列に対しては、例外 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
uniq! -> 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]
unshift(*obj) -> self

指定された 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

引数で指定されたインデックスに対応する要素を配列で返します。インデッ クスに対応する値がなければ 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]]
zip(*lists) {|v1, v2, ...| ...} -> nil

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

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

[PARAM] lists:
配列を指定します。配列でない場合は Enumerable#zip と違い to_ary メソッドにより配列に変換します。

例:

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
zip(*lists) -> [[object]]
zip(*lists) {|v1, v2, ...| ...} -> nil

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

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

[PARAM] lists:
配列を指定します。配列でない場合は to_a メソッドにより配列に変換します。

例:

p (1..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..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

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

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

[PARAM] other:
配列を指定します。other が配列でなければ to_ary メソッドによる暗黙の型変換を試みます。
[1, 1, 4, 2, 3] | [4, 5, 5]  #=> [1, 4, 2, 3, 5]
class Array