Ruby 1.8.7 リファレンスマニュアル > ライブラリ一覧 > csvライブラリ > CSV::Rowクラス

class CSV::Row + Array + Enumerable + Object

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

要約

CSV形式1行分のデータ（Row）を操作するためのクラス。

特異メソッド

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

new -> Object

Objectクラスのインスタンスを生成して返します。

some = Object.new
p some #=> #<Object:0x2b696d8>

インスタンスメソッド

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 == other -> bool

オブジェクトと other が等しければ真を返します。

このメソッドは各クラスの性質に合わせて再定義すべきです。多くの場合、オブジェクトの内容が等しければ真を返すように（同値性を判定するように）再定義されることが期待されています。

デフォルトでは equal? と同じオブジェクトの同一性判定になっています。

[PARAM] other:: 比較するオブジェクトです。

p("foo" == "bar") #=> false
p("foo" == "foo") #=> true

p(4 == 4) #=> true
p(4 == 4.0) #=> true

[SEE_ALSO] Object#equal?,Object#eql?

self === other -> bool

メソッド Object#== の別名です。 case 式で使用されます。このメソッドは case 式での振る舞いを考慮して、各クラスの性質に合わせて再定義すべきです。

一般的に所属性のチェックを実現するため適宜再定義されます。

when 節の式をレシーバーとして === を呼び出すことに注意してください。

また Enumerable#grep でも使用されます。

[PARAM] other:: 比較するオブジェクトです。

age = 12
result =
case age
when 0 .. 2
  "baby"
when 3 .. 6
  "little child"
when 7 .. 12
  "child"
when 13 .. 18
  "youth"
else
  "adult"
end

puts result #=> "child"

def check arg
  case arg
  when /ruby(?!\s*on\s*rails)/i
    "hit! #{arg}"
  when String
    "Instance of String class. But don't hit."
  else
    "unknown"
  end
end

puts check([]) #=> unknown
puts check("mash-up in Ruby on Rails") #=> instance of String class. But not hit...
puts check("<Ruby's world>") #=> hit! <Ruby's world>

[SEE_ALSO] Object#==, Range#===, Module#===, Enumerable#grep

self =~ other -> false

右辺に正規表現オブジェクトを置いた正規表現マッチ obj =~ /RE/ をサポートするためのメソッドです。常に false を返します。

この定義により、=~ が再定義されたオブジェクトでは正常にマッチを行い、それ以外のものは false を返すようになります。

[PARAM] other:: 任意のオブジェクトです。結果に影響しません。

obj = 'regexp'
p(obj =~ /re/) #=> 0

obj = nil
p(obj =~ /re/) #=> false

[SEE_ALSO] String#=~

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 が自身の始点よりも前を指している場合に発生します。

__id__ -> Integer

object_id -> Integer

id -> Integer

各オブジェクトに対して一意な整数を返します。あるオブジェクトに対してどのような整数が割り当てられるかは不定です。

Rubyでは、(Garbage Collectされていない)アクティブなオブジェクト間で重複しない整数(object_id)が各オブジェクトにひとつずつ割り当てられています。このメソッドはその値を返します。

TrueClass, FalseClass, NilClass, Symbol, Fixnum クラスのインスタンスなど Immutable（変更不可）なオブジェクトの一部は同じ内容ならば必ず同じ object_id になります。

これは、Immutable ならば複数の場所から参照されても`破壊的操作'による問題が発生しないので、同じ内容のインスタンスを複数生成しないという内部実装が理由です。

Symbol#to_iで得られる整数と object_id は別物です。

id メソッドの再定義に備えて別名 __id__ が用意されており、ライブラリでは後者の利用が推奨されます。また __id__ を再定義すべきではありません。

id は obsolete なので、object_id か __id__ を使用してください。

p "ruby".object_id #=> 22759500
p "ruby".object_id #=> 22759400

p [].object_id #=> 22759360
p [].object_id #=> 22759340

p :ruby.object_id #=> 103538
p :ruby.object_id #=> 103538

p 11.object_id #=> 23
p 11.object_id #=> 23

p true.object_id #=> 2
p true.object_id #=> 2

[SEE_ALSO] Object#equal?,Symbol

send(name, *args) -> object

send(name, *args) { .... } -> object

__send__(name, *args) -> object

__send__(name, *args) { .... } -> object

オブジェクトのメソッド name を args を引数にして呼び出し、メソッドの実行結果を返します。

ブロック付きで呼ばれたときはブロックもそのまま引き渡します。

send が再定義された場合に備えて別名 __send__ も用意されており、ライブラリではこちらを使うべきです。また __send__ は再定義すべきではありません。

send, __send__ は、メソッドの呼び出し制限にかかわらず任意のメソッドを呼び出せます。クラス／メソッドの定義/呼び出し制限も参照してください。

[PARAM] name:: 文字列かSymbol で指定するメソッド名です。
[PARAM] args:: 呼び出すメソッドに渡す引数です。

p -365.send(:abs) #=> 365
p "ruby".send(:sub,/./,"R") #=> "Ruby"


class Foo
  def foo() "foo" end
  def bar() "bar" end
  def baz() "baz" end
end

# 任意のキーとメソッド(の名前)の関係をハッシュに保持しておく
# レシーバの情報がここにはないことに注意
methods = {1 => :foo,
  2 => :bar,
  3 => :baz}

# キーを使って関連するメソッドを呼び出す
# レシーバは任意(Foo クラスのインスタンスである必要もない)
p Foo.new.send(methods[1])      # => "foo"
p Foo.new.send(methods[2])      # => "bar"
p Foo.new.send(methods[3])      # => "baz"

[SEE_ALSO] Object#method, Kernel.#eval, Proc, Method

_dump(limit) -> String

Marshal.#dump において出力するオブジェクトがメソッド _dump を定義している場合には、そのメソッドの結果が書き出されます。

バージョン1.8.0以降ではObject#marshal_dump, Object#marshal_loadの使用が推奨されます。 Marshal.dump するオブジェクトが _dump と marshal_dump の両方のメソッドを持つ場合は marshal_dump が優先されます。

メソッド _dump は引数として再帰を制限するレベル limit を受け取り、オブジェクトを文字列化したものを返します。

インスタンスがメソッド _dump を持つクラスは必ず同じフォーマットを読み戻すクラスメソッド _load を定義する必要があります。_load はオブジェクトを表現した文字列を受け取り、それをオブジェクトに戻したものを返す必要があります。

[PARAM] limit:: 再帰の制限レベルを表す整数です。
[RETURN]: オブジェクトを文字列化したものを返すように定義すべきです。

class Foo
  def initialize(arg)
    @foo = arg
  end
  def _dump(limit)
    Marshal.dump(@foo, limit)
  end
  def self._load(obj)
    p obj
    Foo.new(Marshal.load(obj))
  end
end
foo = Foo.new(['foo', 'bar'])
p foo                      #=> #<Foo:0xbaf234 @foo=["foo", "bar"]>
dms = Marshal.dump(foo)
p dms                      #=> "\004\bu:\bFoo\023\004\b[\a\"\bfoo\"\bbar"
result = Marshal.load(dms) #=> "\004\b[\a\"\bfoo\"\bbar" # self._load の引数
p result                   #=> #<Foo:0xbaf07c @foo=["foo", "bar"]>

インスタンス変数の情報は普通マーシャルデータに含まれるので、上例のように _dump を定義する必要はありません(ただし _dump を定義するとインスタンス変数の情報は dump されなくなります)。 _dump/_load はより高度な制御を行いたい場合や拡張ライブラリで定義したクラスのインスタンスがインスタンス変数以外に情報を保持する場合に利用します。(例えば、クラス Time は、_dump/_load を定義しています)

[SEE_ALSO] Object#marshal_dump,Object#marshal_load

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]

class -> Class

type -> Class

レシーバのクラスを返します。

p "ruby".class #=> String
p 999999999999999.class #=> Bignum
p ARGV.class #=> Array
p self.class #=> Object
p Class.class #=> Class
p Kernel.class #=> Module

[SEE_ALSO] Class#superclass,Object#kind_of?,Object#instance_of?

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

clone -> object

dup -> object

オブジェクトの複製を作成して返します。

dup はオブジェクトの内容, taint 情報をコピーし、 clone はそれに加えて freeze, 特異メソッドなどの情報も含めた完全な複製を作成します。

clone や dup は浅い(shallow)コピーであることに注意してください。後述。

[EXCEPTION] TypeError:: TrueClass, FalseClass, NilClass, Symbol, そして Numeric クラスのインスタンスなど一部のオブジェクトを複製しようとすると発生します。

obj = "string"
obj.taint
def obj.fuga
end
obj.freeze

p(obj.equal?(obj))          #=> true
p(obj == obj)               #=> true
p(obj.tainted?)             #=> true
p(obj.frozen?)              #=> true
p(obj.respond_to?(:fuga))   #=> true

obj_c = obj.clone

p(obj.equal?(obj_c))        #=> false
p(obj == obj_c)             #=> true
p(obj_c.tainted?)           #=> true
p(obj_c.frozen?)            #=> true
p(obj_c.respond_to?(:fuga)) #=> true

obj_d = obj.dup

p(obj.equal?(obj_d))        #=> false
p(obj == obj_d)             #=> true
p(obj_d.tainted?)           #=> true
p(obj_d.frozen?)            #=> false
p(obj_d.respond_to?(:fuga)) #=> false

[SEE_ALSO] Object#initialize_copy

深いコピーと浅いコピー

clone や dup はオブジェクト自身を複製するだけで、オブジェクトの指している先(たとえば配列の要素など)までは複製しません。これを浅いコピー(shallow copy)といいます。

深い(deep)コピーが必要な場合には、 Marshalモジュールを利用して

Marshal.load(Marshal.dump(obj))

このように複製を作成する方法があります。ただしMarshal出来ないオブジェクトが含まれている場合には使えません。

obj = ["a","b","c"]

obj_d = obj.dup
obj_d[0] << "PLUS"

p obj   #=> ["aPLUS", "b", "c"]
p obj_d #=> ["aPLUS", "b", "c"]

obj_m = Marshal.load(Marshal.dump(obj))
obj_m[1] << "PLUS"

p obj   #=> ["aPLUS", "b", "c"]
p obj_m #=> ["aPLUS", "bPLUS", "c"]

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

display(out = $stdout) -> nil

オブジェクトを out に出力します。

以下のように定義されています。

class Object
  def display(out = $stdout)
    out.print self.to_s
    nil
  end
end

[PARAM] out:: 出力先のIOオブジェクトです。指定しない場合は標準出力に出力されます。
[RETURN]: nil を返します。

Object.new.display #=> #<Object:0xbb0210>

[SEE_ALSO] $stdout

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]

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

to_enum(method = :each, *args) -> Enumerable::Enumerator

enum_for(method = :each, *args) -> Enumerable::Enumerator

Enumerable::Enumerator.new(self, method, *args) を返します。

[PARAM] method:: メソッド名の文字列かシンボルです。
[PARAM] args:: 呼び出すメソッドに渡される引数です。
[EXCEPTION] NameError:: 存在しないメソッド名を指定すると発生します。

str = "xyz"

enum = str.enum_for(:each_byte)
p(a = enum.map{|b| '%02x' % b }) #=> ["78", "79", "7a"]

# protects an array from being modified
a = [1, 2, 3]
p(a.to_enum) #=> #<Enumerable::Enumerator:0xbaf7ac>

[SEE_ALSO] Enumerable::Enumerator

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?

eql?(other) -> bool

オブジェクトと other が等しければ真を返します。Hash で二つのキーが等しいかどうかを判定するのに使われます。

このメソッドは各クラスの性質に合わせて再定義すべきです。多くの場合、 == と同様に同値性の判定をするように再定義されていますが、適切にキー判定ができるようにより厳しくなっている場合もあります。

デフォルトでは equal? と同じオブジェクトの同一性判定になっています。

このメソッドを再定義した時には Object#hash メソッドも再定義しなければなりません。

[PARAM] other:: 比較するオブジェクトです。

p("foo".eql?("bar")) #=> false
p("foo".eql?("foo")) #=> true

p(4.eql?(4)) #=> true
p(4.eql?(4.0)) #=> false

[SEE_ALSO] Object#hash,Object#equal?,Object#==

equal?(other) -> bool

other が self 自身の時、真を返します。

二つのオブジェクトが同一のものかどうか調べる時に使用します。このメソッドを再定義してはいけません。

お互いのObject#object_idが一致するかどうかを調べます。

[PARAM] other:: 比較するオブジェクトです。

p("foo".equal?("bar")) #=> false
p("foo".equal?("foo")) #=> false

p(4.equal?(4)) #=> true
p(4.equal?(4.0)) #=> false

p(:foo.equal? :foo) #=> true

[SEE_ALSO] Object#object_id,Object#==,Object#eql?,Symbol

extend(*modules) -> self

引数で指定したモジュールのインスタンスメソッドを self の特異メソッドとして追加します。

Module#include は、クラス(のインスタンス)に機能を追加しますが、extend は、ある特定のオブジェクトだけにモジュールの機能を追加したいときに使用します。

引数に複数のモジュールを指定した場合、最後の引数から逆順に extend を行います。

[PARAM] modules:: モジュールを任意個指定します（クラスは不可）。
[RETURN]: self を返します。

module Foo
  def a
    'ok Foo'
  end
end

module Bar
  def b
    'ok Bar'
  end
end

obj = Object.new
obj.extend Foo, Bar
p obj.a #=> "ok Foo"
p obj.b #=> "ok Bar"

class Klass
  include Foo
  extend Bar
end

p Klass.new.a #=> "ok Foo"
p Klass.b     #=> "ok Bar"

extend の機能は、「特異クラスに対する Module#include」と言い替えることもできます。ただしその場合、フック用のメソッドが Module#extended ではなく Module#included になるという違いがあります。

# obj.extend Foo, Bar とほぼ同じ
class << obj
  include Foo, Bar
end

[SEE_ALSO] Module#extend_object,Module#include,Module#extended

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

freeze -> self

オブジェクトを凍結（内容の変更を禁止）します。

凍結されたオブジェクトの変更は例外 TypeError を発生させます。いったん凍結されたオブジェクトを元に戻す方法はありません。

凍結されるのはオブジェクトであり、変数ではありません。代入などで変数の指すオブジェクトが変化してしまうことは freeze では防げません。 freeze が防ぐのは、 `破壊的な操作' と呼ばれるもの一般です。変数への参照自体を凍結したい場合は、グローバル変数なら Kernel.#trace_var が使えます。

[RETURN]: self を返します。

a1 = "foo".freeze
a1 = "bar"
p a1 #=> "bar"

a2 = "foo".freeze
a2.replace("bar")# can't modify frozen string (TypeError)

凍結を解除することはできませんが、Object#dup を使えばほぼ同じ内容の凍結されていないオブジェクトを得ることはできます。

a = [1].freeze
p a.frozen?     #=> true

a[0] = "foo"
p a             # can't modify frozen array (TypeError)

b = a.dup
p b             #=> [1]
p b.frozen?     #=> false

b[0] = "foo"
p b             #=> ["foo"]

[SEE_ALSO] Object#frozen?,Object#dup,Kernel.#trace_var

frozen? -> bool

オブジェクトが凍結（内容の変更を禁止）されているときに真を返します。

obj = "someone"
p obj.frozen? #=> false
obj.freeze
p obj.frozen? #=> true

[SEE_ALSO] Object#freeze

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

hash -> Fixnum

オブジェクトのハッシュ値を返します。Hash クラスでオブジェクトを格納するのに用いられています。

メソッド hash は Object#eql? と組み合わせて Hash クラスで利用されます。その際

A.eql?(B) ならば A.hash == B.hash

の関係を必ず満たしていなければいけません。eql? を再定義した時には必ずこちらも合わせて再定義してください。

デフォルトでは、Object#object_id と同じ値を返します。ただし、Fixnum, Symbol, String だけは組込みのハッシュ関数が使用されます(これを変えることはできません)。

hash を再定義する場合は、一様に分布する任意の整数を返すようにします。

[RETURN]: ハッシュ値を返します。Fixnumに収まらない場合は切り捨てられます。

p self.hash #=> 21658870
p 0.hash #=> 1
p 0.0.hash #=> 0
p nil.hash #=> 4

p "ruby".hash #=> -241670986
p "ruby".hash #=> -241670986
p :ruby.hash #=> 103538
p :ruby.hash #=> 103538

[SEE_ALSO] Object#eql?,Object#__id__

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

inspect -> String

オブジェクトを人間が読める形式に変換した文字列を返します。

組み込み関数 Kernel.#p は、このメソッドの結果を使用してオブジェクトを表示します。

puts Class.new.inspect #=> #<Class:0xbafd88>
puts Time.now.inspect #=> 2007-10-15 21:01:37 +0900

[SEE_ALSO] Kernel.#p

instance_eval(expr, filename = "(eval)", lineno = 1) -> object

instance_eval {|obj| ... } -> object

オブジェクトのコンテキストで文字列 expr またはオブジェクト自身をブロックパラメータとするブロックを評価してその結果を返します。

オブジェクトのコンテキストで評価するとは評価中の self をそのオブジェクトにして実行するということです。また、文字列 expr やブロック中でメソッドを定義すればそのオブジェクトの特異メソッドが定義されます。

ただし、ローカル変数だけは、文字列 expr の評価では instance_eval の外側のスコープと、ブロックの評価ではそのブロックの外側のスコープと、共有します。

メソッド定義の中で instance_eval でメソッドを定義した場合は、囲むメソッドが実行されたときに初めて instance_eval 内のメソッドが定義されます。これはメソッド定義のネストと同じです。クラス／メソッドの定義/メソッド定義のネストを参照してください。

[PARAM] expr:: 評価する文字列です。
[PARAM] filename:: 文字列を指定します。ファイル filename に文字列 expr が書かれているかのように実行されます。スタックトレースの表示などを差し替えることができます。
[PARAM] lineno:: 文字列を指定します。行番号 lineno から文字列 expr が書かれているかのように実行されます。スタックトレースの表示などを差し替えることができます。

例:

class Foo
  def initialize data
    @key = data
  end
private
  def do_fuga
    p 'secret'
  end
end

some = Foo.new 'XXX'
some.instance_eval{p @key} #=> "XXX"
some.instance_eval{do_fuga } #=> "secret" # private メソッドも呼び出せる

some.instance_eval 'raise' # ..:10: (eval):1:  (RuntimeError)
messg = 'unknown'
some.instance_eval 'raise messg','file.rb',999 # file.rb:999: unknown (RuntimeError)

[SEE_ALSO] Module#module_eval, Kernel.#eval

instance_exec(*args) {|*vars| ... } -> object

与えられたブロックをレシーバのコンテキストで実行します。

ブロック実行中は、 self がレシーバのコンテキストになるのでレシーバの持つインスタンス変数にアクセスすることができます。

[PARAM] args:: ブロックパラメータに渡す値です。

class KlassWithSecret
  def initialize
    @secret = 99
  end
end
k = KlassWithSecret.new
# 以下で x には 5 が渡される
k.instance_exec(5) {|x| @secret + x }   #=> 104

[SEE_ALSO] Module#class_exec, Module#module_exec, Object#instance_eval

instance_of?(klass) -> bool

オブジェクトがクラス klass の直接のインスタンスである時真を返します。

obj.instance_of?(c) が成立する時には、常に obj.kind_of?(c) も成立します。

[PARAM] klass:: Classかそのサブクラスのインスタンスです。

class C < Object
end
class S < C
end

obj = S.new
p obj.instance_of?(S)       # true
p obj.instance_of?(C)       # false

[SEE_ALSO] Object#kind_of?,Object#class

instance_variable_defined?(var) -> bool

インスタンス変数 var が定義されていたら真を返します。

[PARAM] var:: インスタンス変数名を文字列か Symbol で指定します。

class Fred
  def initialize(p1, p2)
    @a, @b = p1, p2
  end
end
fred = Fred.new('cat', 99)
p fred.instance_variable_defined?(:@a)    #=> true
p fred.instance_variable_defined?("@b")   #=> true
p fred.instance_variable_defined?("@c")   #=> false

[SEE_ALSO] Object#instance_variable_get,Object#instance_variable_set,Object#instance_variables

instance_variable_get(var) -> object|nil

オブジェクトのインスタンス変数の値を取得して返します。

インスタンス変数が定義されていなければ nil を返します。

[PARAM] var:: インスタンス変数名を文字列か Symbol で指定します。

class Foo
  def initialize
    @foo = 1
  end
end

obj = Foo.new
p obj.instance_variable_get("@foo")     #=> 1
p obj.instance_variable_get(:@foo)      #=> 1
p obj.instance_variable_get(:@bar)      #=> nil

[SEE_ALSO] Object#instance_variable_set,Object#instance_variables,Object#instance_variable_defined?

instance_variable_set(var, value) -> object

オブジェクトのインスタンス変数 var に値 value を設定します。

インスタンス変数が定義されていなければ新たに定義されます。

[PARAM] var:: インスタンス変数名を文字列か Symbol で指定します。
[PARAM] value:: 設定する値です。
[RETURN]: value を返します。

obj = Object.new
p obj.instance_variable_set("@foo", 1)  #=> 1
p obj.instance_variable_set(:@foo, 2)   #=> 2
p obj.instance_variable_get(:@foo)      #=> 2

[SEE_ALSO] Object#instance_variable_get,Object#instance_variables,Object#instance_variable_defined?

instance_variables -> [String]

オブジェクトのインスタンス変数名を文字列の配列として返します。

obj = Object.new
obj.instance_eval { @foo, @bar = nil }
p obj.instance_variables

#=> ["@foo", "@bar"]

[SEE_ALSO] Object#instance_variable_get,Kernel.#local_variables,Kernel.#global_variables,Module.constants,Module#constants,Module#class_variables

is_a?(mod) -> bool

kind_of?(mod) -> bool

オブジェクトが指定されたクラス mod かそのサブクラスのインスタンスであるとき真を返します。

また、オブジェクトがモジュール mod をインクルードしたクラスかそのサブクラスのインスタンスである場合にも真を返します。上記のいずれでもない場合に false を返します。

[PARAM] mod:: クラスやモジュールなど、Moduleかそのサブクラスのインスタンスです。

module M
end
class C < Object
  include M
end
class S < C
end

obj = S.new
p obj.is_a?(S)       # true
p obj.is_a?(C)       # true
p obj.is_a?(Object)  # true
p obj.is_a?(M)       # true
p obj.is_a?(Hash)    # false

[SEE_ALSO] Object#instance_of?,Module#===,Object#class

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

marshal_dump -> object

Marshal.#dump を制御するメソッドです。

Marshal.dump(some) において、出力するオブジェクト some がメソッド marshal_dump を持つ場合には、その返り値がダンプされたものが Marshal.dump(some) の返り値となります。

marshal_dump/marshal_load の仕組みは Ruby 1.8.0 から導入されました。これから書くプログラムでは _dump/_load ではなく marshal_dump/marshal_load を使うべきです。

[RETURN]: 任意のオブジェクトで marshal_load の引数に利用できます。

class Foo
  def initialize(arg)
    @foo = arg
  end
  def marshal_dump
    @foo
  end
  def marshal_load(obj)
    p obj
    @foo = obj
  end
end
foo = Foo.new(['foo', 'bar'])
p foo                      #=> #<Foo:0xbaf3b0 @foo=["foo", "bar"]>
dms = Marshal.dump(foo)
p dms                      #=> "\004\bU:\bFoo[\a\"\bfoo\"\bbar"
result = Marshal.load(dms) #=> ["foo", "bar"] # marshal_load の引数
p result                   #=> #<Foo:0xbaf2ac @foo=["foo", "bar"]>

インスタンス変数の情報は普通マーシャルデータに含まれるので、上例のように marshal_dump を定義する必要はありません (ただし marshal_dump を定義するとインスタンス変数の情報はダンプされなくなるので、marshal_dump/marshal_load で扱う必要があります)。 marshal_dump/marshal_load はより高度な制御を行いたい場合や拡張ライブラリで定義したクラスのインスタンスがインスタンス変数以外に情報を保持する場合に利用します。

特に、marshal_dump/marshal_load を定義したオブジェクトは特異メソッドが定義されていてもマーシャルできるようになります (特異メソッドの情報が自動的に dump されるようになるわけではなく、 marshal_dump/marshal_load によりそれを実現する余地があるということです)。

[SEE_ALSO] Object#marshal_load, Marshal

marshal_load(obj) -> object

Marshal.#load を制御するメソッドです。

some のダンプ結果（Marshal.dump(some)）をロードする（Marshal.load(Marshal.dump(some))）には some がメソッド marshal_load を持っていなければなりません。このとき、marshal_dump の返り値が marshal_load の引数に利用されます。 marshal_load 時の self は、生成されたばかり（Class#allocate されたばかり）の状態です。

marshal_dump/marshal_load の仕組みは Ruby 1.8.0 から導入されました。これから書くプログラムでは _dump/_load ではなく marshal_dump/marshal_load を使うべきです。

[PARAM] obj:: marshal_dump の返り値のコピーです。
[RETURN]: 返り値は無視されます。

[SEE_ALSO] Object#marshal_dump, Marshal

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#max と Enumerable#max_by の違いは Enumerable#sort と Enumerable#sort_by の違いと同じです。

[SEE_ALSO] Enumerable#sort_by

method(name) -> Method

オブジェクトのメソッド name をオブジェクト化した Method オブジェクトを返します。

[PARAM] name:: メソッド名をSymbol またはStringで指定します。
[EXCEPTION] NameError:: 定義されていないメソッド名を引数として与えると発生します。

me = -365.method(:abs)
p me #=> #<Method: Fixnum#abs>
p me.call #=> 365

[SEE_ALSO] Module#instance_method,Method,Object#__send__,Kernel.#eval

method_missing(name, *args) -> object

呼びだされたメソッドが定義されていなかった時、Rubyインタプリタがこのメソッドを呼び出します。

呼び出しに失敗したメソッドの名前 (Symbol) が name にその時の引数が第二引数以降に渡されます。

デフォルトではこのメソッドは例外 NameError を発生させます。

[PARAM] name:: 未定義メソッドの名前（シンボル）です。
[PARAM] args:: 未定義メソッドに渡された引数です。
[RETURN]: ユーザー定義の method_missing メソッドの返り値が未定義メソッドの返り値であるかのように見えます。

class Foo
  def initialize(data)
    @data = data
  end
  def method_missing(name, lang)
    if name.to_s =~ /\Afind_(\d+)_in\z/
      if @data[lang]
        p @data[lang][$1.to_i]
      else
        raise "#{lang} unknown"
      end
    else
      super
    end
  end
end

dic = Foo.new({:English => %w(zero one two), :Esperanto => %w(nulo unu du)})
dic.find_2_in :Esperanto #=> "du"

methods(include_inherited = true) -> [String]

そのオブジェクトに対して呼び出せるメソッド名の一覧を返します。このメソッドは public メソッドおよび protected メソッドの名前を返します。

ただし特別に、引数が偽の時は Object#singleton_methods(false) と同じになっています。

[PARAM] include_inherited:: 引数が偽の時は Object#singleton_methods(false) と同じになります。

#例1:

class Parent
  private;   def private_parent()   end
  protected; def protected_parent() end
  public;    def public_parent()    end
end

class Foo < Parent
  private;   def private_foo()   end
  protected; def protected_foo() end
  public;    def public_foo()    end
end

obj = Foo.new
class <<obj
    private;   def private_singleton()   end
    protected; def protected_singleton() end
    public;    def public_singleton()    end
end

# あるオブジェクトの応答できるメソッドの一覧を得る。
p obj.methods(false)
p obj.public_methods(false)
p obj.private_methods(false)
p obj.protected_methods(false)

#実行結果

["public_singleton", "protected_singleton"]
["public_foo", "public_singleton"]
["private_foo", "private_singleton"]
["protected_foo", "protected_singleton"]

#例2:

# あるオブジェクトの応答できるメソッドの一覧を得る。
# 自身のクラスの親クラスのインスタンスメソッドも含めるために true を指定して
# いるが、Object のインスタンスメソッドは一覧から排除している。
p obj.methods(true)           - Object.instance_methods(true)
p obj.public_methods(true)    - Object.public_instance_methods(true)
p obj.private_methods(true)   - Object.private_instance_methods(true)
p obj.protected_methods(true) - Object.protected_instance_methods(true)

#実行結果

["public_foo", "public_parent", "protected_singleton", "public_singleton", "protected_foo", "protected_parent"]
["public_foo", "public_parent", "public_singleton"]
["private_singleton", "private_foo", "private_parent"]
["protected_singleton", "protected_foo", "protected_parent"]

[SEE_ALSO] Module#instance_methods,Object#singleton_methods

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#min と Enumerable#min_by の違いは Enumerable#sort と Enumerable#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#minmax と Enumerable#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

nil? -> bool

レシーバが nil であれば真を返します。

p false.nil? #=> false
p nil.nil? #=> true

[SEE_ALSO] NilClass

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#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 を使いたくない人に別解を示すためです。

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

    [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

private_methods(include_inherited = true) -> [String]

そのオブジェクトが理解できる private メソッド名の一覧を返します。

[PARAM] include_inherited:: 偽となる値を指定すると自身のクラスのスーパークラスで定義されたメソッドを除きます。

[SEE_ALSO] Module#private_instance_methods,Object#methods,Object#singleton_methods

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

protected_methods(include_inherited = true) -> [String]

そのオブジェクトが理解できる protected メソッド名の一覧を返します。

[PARAM] include_inherited:: 偽となる値を指定すると自身のクラスのスーパークラスで定義されたメソッドを除きます。

[SEE_ALSO] Module#protected_instance_methods,Object#methods,Object#singleton_methods

public_methods(include_inherited = true) -> [String]

そのオブジェクトが理解できる public メソッド名の一覧を返します。

[PARAM] include_inherited:: 偽となる値を指定すると自身のクラスのスーパークラスで定義されたメソッドを除きます。

[SEE_ALSO] Module#public_instance_methods,Object#methods,Object#singleton_methods

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]

respond_to?(name, include_private = false) -> bool

オブジェクトがメソッド name を持つとき真を返します。

オブジェクトがメソッド name を持つというのは、オブジェクトがメソッド name に応答することができることをいいます。

[PARAM] name:: Symbol または文字列で指定するメソッド名です。
[PARAM] include_private:: private メソッドを確認の対象に含めるかを true か false で指定します。省略した場合は false(含めない) を指定した事になります。

class F
  def hello
    "Bonjour"
  end
end

class D
private
  def hello
    "Guten Tag"
  end
end
list = [F.new,D.new]

list.each{|it| puts it.hello if it.respond_to?(:hello)}
#=> Bonjour

list.each{|it| it.instance_eval("puts hello if it.respond_to?(:hello, true)")}
#=> Bonjour
#   Guten Tag

[SEE_ALSO] Module#method_defined?

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

singleton_methods(inherited_too = true) -> [String]

そのオブジェクトに対して定義されている特異メソッド名 (public あるいは protected メソッド) の一覧を返します。

クラスメソッド(Classのインスタンスの特異メソッド)に関しては引数が真のとき、スーパークラスのクラスメソッドも対象になります。

singleton_methods(false) は、Object#methods(false) と同じです。

[PARAM] inherited_too:: 引数が真のとき、スーパークラスのクラスメソッドも対象になります。これが意味を持つのは self がクラスオブジェクトであるときだけです。

#例1:

Parent = Class.new

class <<Parent
  private;   def private_class_parent() end
  protected; def protected_class_parent() end
  public;    def public_class_parent() end
end

Foo = Class.new(Parent)

class <<Foo
  private;   def private_class_foo() end
  protected; def protected_class_foo() end
  public;    def public_class_foo() end
end

module Bar
  private;   def private_bar()   end
  protected; def protected_bar() end
  public;    def public_bar()    end
end

obj = Foo.new
class <<obj
  include Bar
  private;   def private_self()   end
  protected; def protected_self() end
  public;    def public_self()    end
end

# あるオブジェクトの特異メソッドの一覧を得る。
p obj.singleton_methods(false)
p obj.methods(false)
p Foo.singleton_methods(false)

#実行結果

["public_self", "protected_self"]
["public_self", "protected_self"]
["public_class_foo", "protected_class_foo"]


#例2:

# あるオブジェクトの特異メソッドの一覧を得る。
# 親クラスのクラスメソッドも含まれるよう true を指定したが、
# Object のクラスメソッドは一覧から排除している。

p obj.singleton_methods(true)
p Foo.singleton_methods(true) - Object.singleton_methods(true)

#実行結果

["public_bar", "public_self", "protected_bar", "protected_self"]
["public_class_foo", "public_class_parent", "protected_class_foo", "protected_class_parent"]

[SEE_ALSO] Object#methods,Object#extend

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

taint -> self

オブジェクトの「汚染マーク」をセットします。

環境変数（ENVで得られる文字列）など一部のオブジェクトは最初から汚染されています。オブジェクトの汚染に関してはセキュリティモデルを参照してください。

$SAFE = 1

some = "puts '@&%&(#!'"
p some.tainted? #=> false
eval(some) #=> @&%&(#!

some.taint
p some.tainted? #=> true
eval(some) # Insecure operation - eval (SecurityError)

some.untaint
p some.tainted? #=> false
eval(some) #=> @&%&(#!

p ENV['OS'].tainted? #=> true

[SEE_ALSO] Object#tainted?,Object#untaint,Object#freeze

tainted? -> bool

オブジェクトの「汚染マーク」がセットされている時真を返します。

オブジェクトの汚染に関してはセキュリティモデルを参照してください。

p String.new.tainted? #=> false
p ENV['OS'].tainted? #=> true

[SEE_ALSO] Object#taint,Object#untaint

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]

tap {|x| ... } -> self

self を引数としてブロックを評価し、self を返します。

メソッドチェインの途中で直ちに操作結果を表示するためにメソッドチェインに "入り込む" ことが、このメソッドの主目的です。

(1..10)                    .tap {|x| puts "original: #{x.inspect}"}.
   to_a                    .tap {|x| puts "array: #{x.inspect}"}.
   select {|x| x % 2 == 0} .tap {|x| puts "evens: #{x.inspect}"}.
   map { |x| x * x }       .tap {|x| puts "squares: #{x.inspect}"}

to_a -> Array

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

to_a -> Array

オブジェクトを配列に変換した結果を返します。

配列に変換できない(to_ary を持たない)オブジェクトは、自身のみを含む長さ 1 の配列に変換されます。このメソッドは、将来 Object のメソッドからは取り除かれます。なので to_a を使用する場合、

すべてのオブジェクトに to_a が定義されているという期待はしない。
ユーザー定義のクラスには必要に応じて自分で定義する

などということが必要です。

p( {'a'=>1}.to_a )  # [["a", 1]]
p ['array'].to_a    # ["array"]
p 1.to_a            # [1]       (warning: default `to_a' will be obsolete)
p nil.to_a          # []

[SEE_ALSO] Object#to_ary,Kernel.#Array

to_ary -> self

self をそのまま返します。

to_ary -> Array

オブジェクトの Array への暗黙の変換が必要なときに内部で呼ばれます。デフォルトでは定義されていません。

説明のためここに記載してありますが、このメソッドは実際には Object クラスには定義されていません。必要に応じてサブクラスで定義すべきものです。

このメソッドを定義する条件は、

配列が使われるすべての場面で代置可能であるような、
配列そのものとみなせるようなもの

という厳しいものになっています。

class Foo
 def to_ary
   [3,4]
 end
end

it = Foo.new
p([1,2] + it) #=> [1, 2, 3, 4]

[SEE_ALSO] Object#to_a,Kernel.#Array

to_hash -> Hash

オブジェクトの Hash への暗黙の変換が必要なときに内部で呼ばれます。デフォルトでは定義されていません。

このメソッドを定義する条件は、

ハッシュが使われるすべての場面で代置可能であるような、
ハッシュそのものとみなせるようなもの

という厳しいものになっています。

class Foo
 def to_hash
   {'as' => 24}
 end
end

it = Foo.new
p({:as => 12}.merge(it)) #=> {"as"=>24, :as=>12}

to_int -> Integer

オブジェクトの Integer への暗黙の変換が必要なときに内部で呼ばれます。デフォルトでは定義されていません。

このメソッドを定義する条件は、

整数が使われるすべての場面で代置可能であるような、
整数そのものとみなせるようなもの

という厳しいものになっています。

class Foo
 def to_int
   666
 end
end

it = Foo.new
p(9**9 & it) #=> 8

[SEE_ALSO] Kernel.#Integer

to_io -> IO

オブジェクトの IO への暗黙の変換が必要なときに内部で呼ばれます。デフォルトでは定義されていません。

このメソッドを定義する条件は、

IOオブジェクトが使われるすべての場面で代置可能であるような、
IOオブジェクトそのものとみなせるようなもの

という厳しいものになっています。

to_proc -> Proc

オブジェクトの Proc への暗黙の変換が必要なときに内部で呼ばれます。デフォルトでは定義されていません。

def doing
  yield
end

class Foo
 def to_proc
   Proc.new{p 'ok'}
 end
end

it = Foo.new
doing(&it) #=> "ok"

to_regexp -> Regexp

オブジェクトの Regexp への暗黙の変換が必要なときに内部で呼ばれます。デフォルトでは定義されていません。

このメソッドを定義する条件は、

正規表現が使われるすべての場面で代置可能であるような、
正規表現そのものとみなせるようなもの

という厳しいものになっています。

class Foo
 def to_regexp
   /[\d]+/
 end
end

it = Foo.new
p Regexp.union(/^at/, it) #=> /(?-mix:^at)|(?-mix:[\d]+)/

to_s -> String

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

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

to_s -> String

オブジェクトの文字列表現を返します。

Kernel.#print や Kernel.#sprintf は文字列以外のオブジェクトが引数に渡された場合このメソッドを使って文字列に変換します。

class Foo
  def initialize num
    @num = num
  end
end
it = Foo.new(40)

puts it #=> #<Foo:0x2b69110>

class Foo
 def to_s
   "Class:Foo Number:#{@num}"
 end
end

puts it #=> Class:Foo Number:40

[SEE_ALSO] Object#to_str,Kernel.#String

to_str -> String

オブジェクトの String への暗黙の変換が必要なときに内部で呼ばれます。デフォルトでは定義されていません。

このメソッドを定義する条件は、

文字列が使われるすべての場面で代置可能であるような、
文字列そのものとみなせるようなもの

という厳しいものになっています。

class Foo
 def to_str
   'Edition'
 end
end

it = Foo.new
p('Second' + it) #=> "SecondEdition"

[SEE_ALSO] Object#to_s,Kernel.#String

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

untaint -> self

オブジェクトの「汚染マーク」を取り除きます。

汚染マークを取り除くことによる危険性はプログラマが責任を負う必要があります。

オブジェクトの汚染に関してはセキュリティモデルを参照してください。

[EXCEPTION] SecurityError:: セキュリティレベルが3以上の時にこのメソッドを使用すると発生します。

[SEE_ALSO] Object#taint,Object#tainted?

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]

privateメソッド

initialize(*args, &block) -> object

ユーザ定義クラスのオブジェクト初期化メソッド。

このメソッドは Class#new から新しく生成されたオブジェクトの初期化のために呼び出されます。他の言語のコンストラクタに相当します。デフォルトの動作ではなにもしません。

initialize には Class#new に与えられた引数がそのまま渡されます。

サブクラスではこのメソッドを必要に応じて再定義されることが期待されています。

initialize という名前のメソッドは自動的に private に設定されます。

[PARAM] args:: 初期化時の引数です。
[PARAM] block:: 初期化時のブロック引数です。必須ではありません。

class Foo
  def initialize name
    puts "initialize Foo"
    @name = name
  end
end

class Bar < Foo
  def initialize name, pass
    puts "initialize Bar"
    super name
    @pass = pass
  end
end

it = Bar.new('myname','0500')
p it
#=> initialize Bar
#   initialize Foo
#   #<Bar:0x2b68f08 @name="myname", @pass="0500">

[SEE_ALSO] Class#new

initialize_copy(obj) -> object

(拡張ライブラリによる) ユーザ定義クラスのオブジェクトコピーの初期化メソッド。

このメソッドは self を obj の内容で置き換えます。ただし、self のインスタンス変数や特異メソッドは変化しません。 Object#clone, Object#dupの内部で使われています。

initialize_copy は、Ruby インタプリタが知り得ない情報をコピーするために使用(定義)されます。例えば C 言語でクラスを実装する場合、情報をインスタンス変数に保持させない場合がありますが、そういった内部情報を initialize_copy でコピーするよう定義しておくことで、dup や clone を再定義する必要がなくなります。

デフォルトの Object#initialize_copy は、 freeze チェックおよび型のチェックを行い self を返すだけのメソッドです。

initialize_copy という名前のメソッドは自動的に private に設定されます。

[EXCEPTION] TypeError:: レシーバが freeze されているか、obj のクラスがレシーバのクラスと異なる場合に発生します。

[SEE_ALSO] Object#clone,Object#dup

以下に例として、dup や clone がこのメソッドをどのように利用しているかを示します。

obj.dup は、新たに生成したオブジェクトに対して initialize_copy を呼び

obj2 = obj.class.allocate
obj2.initialize_copy(obj)

obj2 に対してさらに obj の汚染状態、インスタンス変数、ファイナライザをコピーすることで複製を作ります。 obj.clone は、さらに特異メソッドのコピーも行います。

obj = Object.new
class <<obj
  attr_accessor :foo
  def bar
    :bar
  end
end

def check(obj)
  puts "instance variables: #{obj.inspect}"
  puts "tainted?: #{obj.tainted?}"
  print "singleton methods: "
  begin
    p obj.bar
  rescue NameError
    p $!
  end
end

obj.foo = 1
obj.taint

check Object.new.send(:initialize_copy, obj)
        #=> instance variables: #<Object:0x4019c9d4>
        #   tainted?: false
        #   singleton methods: #<NoMethodError: ...>
check obj.dup
        #=> instance variables: #<Object:0x4019c9c0 @foo=1>
        #   tainted?: true
        #   singleton methods: #<NoMethodError: ...>
check obj.clone
        #=> instance variables: #<Object:0x4019c880 @foo=1>
        #   tainted?: true
        #   singleton methods: :bar

remove_instance_variable(name) -> object

オブジェクトからインスタンス変数 name を取り除き、そのインスタンス変数に設定されていた値を返します。

[PARAM] name:: 削除するインスタンス変数の名前をシンボルか文字列で指定します。
[EXCEPTION] NameError:: オブジェクトがインスタンス変数 name を持たない場合に発生します。

class Foo
  def foo
    @foo = 1
    p remove_instance_variable(:@foo) #=> 1
    p remove_instance_variable(:@foo) # instance variable @foo not defined (NameError)
  end
end
Foo.new.foo

[SEE_ALSO] Module#remove_class_variable,Module#remove_const

singleton_method_added(name) -> object

特異メソッドが追加された時にインタプリタから呼び出されます。

通常のメソッドの追加に対するフックには Module#method_addedを使います。

[PARAM] name:: 追加されたメソッド名が Symbol で渡されます。

class Foo
  def singleton_method_added(name)
    puts "singleton method \"#{name}\" was added"
  end
end

obj = Foo.new
def obj.foo
end

#=> singleton method "foo" was added

[SEE_ALSO] Module#method_added,Object#singleton_method_removed,Object#singleton_method_undefined

singleton_method_removed(name) -> object

特異メソッドが Module#remove_method により削除された時にインタプリタから呼び出されます。

通常のメソッドの削除に対するフックには Module#method_removedを使います。

[PARAM] name:: 削除されたメソッド名が Symbol で渡されます。

class Foo
  def singleton_method_removed(name)
    puts "singleton method \"#{name}\" was removed"
  end
end

obj = Foo.new
def obj.foo
end

class << obj
  remove_method :foo
end

#=> singleton method "foo" was removed

[SEE_ALSO] Module#method_removed,Object#singleton_method_added,Object#singleton_method_undefined

singleton_method_undefined(name) -> object

特異メソッドが Module#undef_method または undef により未定義にされた時にインタプリタから呼び出されます。

通常のメソッドの未定義に対するフックには Module#method_undefined を使います。

[PARAM] name:: 未定義にされたメソッド名が Symbol で渡されます。

class Foo
  def singleton_method_undefined(name)
    puts "singleton method \"#{name}\" was undefined"
  end
end

obj = Foo.new
def obj.foo
end
def obj.bar
end

class << obj
  undef_method :foo
end
obj.instance_eval {undef bar}

#=> singleton method "foo" was undefined
#   singleton method "bar" was undefined

[SEE_ALSO] Module#method_undefined,Object#singleton_method_added,Object#singleton_method_removed , クラス／メソッドの定義/undef

class CSV::Row

Ruby 1.8.7 リファレンスマニュアル
- はじめに
- コマンド
- Rubyの起動
- 環境変数
- Ruby言語仕様
- 組み込みライブラリ
- 標準添付ライブラリ
  - CUI
    - curses
    - expect
    - io/console
    - pty
    - readline
    - shell
  - 文字コード
    - iconv
    - kconv
    - nkf
  - コマンドライン
    - getoptlong
    - optparse
  - データベース
    - dbm
    - gdbm
    - pstore
    - sdbm
  - 日付・時間
    - date
    - time
  - デザインパターン
  - 開発
    - benchmark
    - coverage
    - debug
    - irb
    - minitest/mock
    - minitest/spec
    - minitest/unit
    - mkmf
    - pp
    - profile
    - profiler
    - rake
    - rbconfig
    - test/unit
    - tracer
  - ファイル
    - fileutils
    - find
    - pathname
    - tempfile
    - tmpdir
    - un
  - ファイルフォーマット
    - csv
    - json
    - psych
    - rdoc
    - rexml
    - rss
    - syck
    - yaml
    - zlib
  - GC
    - weakref
  - GUI
    - tk
  - 入出力
    - fcntl
    - io/nonblock
    - io/wait
    - open3
    - scanf
  - 数学
    - bigdecimal
    - cmath
    - complex
    - mathn
    - matrix
    - prime
    - rational
    - set
    - tsort
  - ネットワーク
    - cgi
    - drb
    - gserver
    - ipaddr
    - net/ftp
    - net/http
    - net/https
    - net/imap
    - net/pop
    - net/protocol
    - net/smtp
    - net/telnet
    - open-uri
    - openssl
    - resolv
    - resolv-replace
    - socket
    - uri
    - webrick
    - xmlrpc
  - テキスト
    - digest
    - erb
    - ripper
    - shellwords
    - stringio
    - strscan
  - スレッド
    - monitor
    - mutex_m
    - sync
    - thread
    - thwait
    - timeout
  - Unix
    - etc
    - syslog
  - Windows
  - その他
    - abbrev
    - base64
    - continuation
    - dl
    - e2mmap
    - English
    - fiber
    - logger
    - objspace
    - ostruct
    - prettyprint
    - racc/parser
    - rinda/rinda
    - rinda/tuplespace
    - rubygems
    - securerandom
    - ubygems
- pack テンプレート文字列
- sprintf フォーマット
- Ruby用語集
- Rubyで使われる記号の意味
- 疑似BNFによるRubyの文法
- バージョン情報 / このリファレンスについて