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

class Array

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

Abstract

配列クラスです。配列は任意の 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"]  (各要素は違うオブジェクトである)

try_convert(obj) -> Array | nil

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

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

要素の重複判定は、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"

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

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 が空の配列 [] なら 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 が空の配列 [] なら start から end までの要素が削除されます。

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

[EXCEPTION] IndexError:

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

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

at(pos) -> object

配列の pos の位置にある要素を返します。 self[pos] と同じです。

[PARAM] pos:: インデックスを整数で指定します。

a = [0, 1, 2, 3]
p a.at(1)        #=> 1

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| ..} -> 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 の組み合わせをすべて生成し、それを引数としてブロックを実行します。

得られる組み合わせの順序は保証されません。ブロックなしで呼び出されると、組み合わせを生成する 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

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]       # こちらは変わらない

cycle {|obj| block }

Enumerable オブジェクトの要素を、繰り返し無限に生成し続けます。

例:

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

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]  もとの配列から削除されていることに注意。

each {|item| .... } -> self

each -> Enumerable::Enumerator

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

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

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

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

each_index -> Enumerable::Enumerator

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

以下と同じです。

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

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

empty? -> bool

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

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

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 オブジェクトで指定します。

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

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

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

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)

indices(*index)

このメソッド 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]

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]

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] [[m:$, ]]

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

pack(template) -> String

配列の内容を 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

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

説明中、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終端文字列(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 を使いたくない人に別解を示すためです。

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

    p [82, 117, 98, 121].pack("cccc")
    => "Ruby"

    p [82, 117, 98, 121].pack("c4")
    => "Ruby"

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    p [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
      p n
      => -2

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

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

IPアドレス

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

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

sockaddr_in 構造体

      require 'socket'
      p [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)。

    p ["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 できません。

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

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

      p [nil].pack("p")        #=> "\000\000\000\000"
      p "\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 が必要になるかもしれません)

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

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

で得られます。

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

Little endian:

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

Big endian:

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

permutation(n) { |p| block } -> Array

permutation(n) -> Enumerable::Enumerator

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

得られる順列の順序は保証されません。ブロックなしで呼び出されると，順列を生成する 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

pop(n = 1) -> Array | nil

自身の末尾から指定された n 個だけ要素を取り除いてそれを返します。自身が空配列の時は nil を返します。

[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

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 オブジェクトを返します。

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

sample -> object

sample(n) -> Array

配列の要素を1個(引数を指定した場合は n 個)ランダムに選んで返します。配列が空の場合は、無引数の場合は nil を、個数を指定した場合は空配列を返します。

srand()が有効です。

例:

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

shift(n = 1) -> Array | nil

自身の先頭から指定された n 個だけ要素を取り除いてそれを返します。自身が空配列の時は nil を返します。

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

例:

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

p [].shift           #=> nil

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

shuffle -> Array

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

srand()が有効です。

例:

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

shuffle! -> self

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

例:

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

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_by! -> Enumerator

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

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

[SEE_ALSO] Enumerable#sort_by

to_a -> Array

to_splat -> Array

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

to_ary -> self

self をそのまま返します

to_s -> String

Array#inspect と同じです。

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(*index) -> Array | nil

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

[PARAM] index:: インデックスを整数で指定します。

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]

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

追加されるメソッド

abbrev(pattern = nil) -> Hash [added by abbrev]

self が文字列の配列の場合、self から一意に決まる短縮形を計算し、短縮形をキー、元の文字列を値とするハッシュを返します。

引数に正規表現を指定すると、self のうちそのパターンにマッチしたものから短縮形を計算します。引数に文字列を指定すると、self のうちその文字列で始まるものから短縮形を計算します。

Abbrev.#abbrev(self, pattern) と同じです。

[PARAM] pattern:: Regexp か String を指定します。

p %w[ruby rubyist].abbrev
#=> {"ruby"    => "ruby",
#    "rubyi"   => "rubyist",
#    "rubyis"  => "rubyist",
#    "rubyist" => "rubyist"}

[SEE_ALSO] Abbrev.#abbrev

dclone [added by rexml]

shelljoin -> String [added by shellwords]

配列の各要素である文字列に対して、Bourne シェルのコマンドライン中で安全に使えるためのエスケープを適用し、空白文字を介してそれらを連結したコマンドライン文字列を生成します。

array.shelljoin は、Shellwords.shelljoin(array) と等価です。

[RETURN]: エスケープ結果を連結した文字列を返します。

[SEE_ALSO] Shellwords.#shelljoin

class Array

Abstract

特異メソッド

インスタンスメソッド

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

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

使用例

追加されるメソッド

Methods

Classes