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

class CSV + Enumerable + Object

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

要約

このクラスは CSV ファイルやデータに対する完全なインターフェイスを提供します。

読み込み

# ファイルから一行ずつ
CSV.foreach("path/to/file.csv") do |row|
  # use row here...
end

# ファイルから一度に
arr_of_arrs = CSV.read("path/to/file.csv")

# 文字列から一行ずつ
CSV.parse("CSV,data,String") do |row|
  # use row here...
end

# 文字列から一行ずつ
arr_of_arrs = CSV.parse("CSV,data,String")

書き込み

# ファイルへ書き込み
CSV.open("path/to/file.csv", "wb") do |csv|
  csv << ["row", "of", "CSV", "data"]
  csv << ["another", "row"]
  # ...
end

# 文字列へ書き込み
csv_string = CSV.generate do |csv|
  csv << ["row", "of", "CSV", "data"]
  csv << ["another", "row"]
  # ...
end

一行変換

csv_string = ["CSV", "data"].to_csv   # => "CSV,data"
csv_array  = "CSV,String".parse_csv   # => ["CSV", "String"]

ショートカット

CSV             { |csv_out| csv_out << %w{my data here} }  # to $stdout
CSV(csv = "")   { |csv_str| csv_str << %w{my data here} }  # to a String
CSV($stderr)    { |csv_err| csv_err << %w{my data here} }  # to $stderr

CSV と文字エンコーディング (M17n or Multilingualization)

This new CSV parser is m17n savvy. The parser works in the Encoding of the IO or String object being read from or written to. Your data is never transcoded (unless you ask Ruby to transcode it for you) and will literally be parsed in the Encoding it is in. Thus CSV will return Arrays or Rows of Strings in the Encoding of your data. This is accomplished by transcoding the parser itself into your Encoding.

Some transcoding must take place, of course, to accomplish this multiencoding support. For example, <tt>:col_sep</tt>, <tt>:row_sep</tt>, and <tt>:quote_char</tt> must be transcoded to match your data. Hopefully this makes the entire process feel transparent, since CSV's defaults should just magically work for you data. However, you can set these values manually in the target Encoding to avoid the translation.

It's also important to note that while all of CSV's core parser is now Encoding agnostic, some features are not. For example, the built-in converters will try to transcode data to UTF-8 before making conversions. Again, you can provide custom converters that are aware of your Encodings to avoid this translation. It's just too hard for me to support native conversions in all of Ruby's Encodings.

Anyway, the practical side of this is simple: make sure IO and String objects passed into CSV have the proper Encoding set and everything should just work. CSV methods that allow you to open IO objects (CSV::foreach(), CSV::open(), CSV::read(), and CSV::readlines()) do allow you to specify the Encoding.

One minor exception comes when generating CSV into a String with an Encoding that is not ASCII compatible. There's no existing data for CSV to use to prepare itself and thus you will probably need to manually specify the desired Encoding for most of those cases. It will try to guess using the fields in a row of output though, when using CSV::generate_line() or Array#to_csv().

特異メソッド

dump(ary_of_objs, io = "", options = Hash.new) -> String | nil

このメソッドは Ruby オブジェクトの配列を文字列や CSV ファイルにシリアライズすることができます。Marshal や yaml よりは不便ですが、スプレッドシートやデータベースとのやりとりには役に立つでしょう。

このメソッドは単純なオブジェクトや構造体を扱う場合はうまく動くことを意図しています。Struct#members を使ってインスタンス変数をシリアライズします。

もっと複雑なシリアライゼーションが必要な場合は、ダンプしたいクラスにメソッドを追加すると制御することができます。

Object.csv_meta を定義すると、ダンプするデータの一行目を変更することができます。この行は次の形式のハッシュのようなものです。

key_1,value_1,key_2,value_2,...

CSV.load は "class" というキーと文字列化したクラス名を期待しています。Object.csv_meta を定義しなければ CSV.dump はそれを生成します。ary_of_objs の最初の要素の Object.csv_meta だけが呼ばれます。

次に Object#csv_headers を定義することができます。このメソッドはダンプするデータの二行目を出力します。二行目はそれぞれの列のヘッダを与えるために使います。デフォルトでは、CSV.load はヘッダが "@" で始まっていればインスタンス変数に値をセットし、そうでなければヘッダの名前をメソッド名、フィールドの値を引数として Object#send を呼び出します。 ary_of_objs の最初の要素の Object#csv_headers だけが呼ばれます。

最後に、Object#csv_dump を定義することができます。Object#csv_dump の引数はヘッダで返り値はフィールドの配列です。このメソッドは ary_of_objs の全ての要素に対して一度ずつ呼ばれます。

[PARAM] ary_of_objs:: 任意の配列を指定します。
[PARAM] io:: データの出力先を指定します。デフォルトは文字列です。ファイルに出力することもできます。
[PARAM] options:: オプションを指定します。CSV.new と同じです。

[SEE_ALSO] CSV.new

filter(options = Hash.new) {|row| ... }

filter(input, options = Hash.new) {|row| ... }

filter(input, output, options = Hash.new) {|row| ... }

このメソッドは CSV データに対して Unix のツール群のようなフィルタを構築するのに便利です。

与えられたブロックに一行ずつ渡されます。ブロックに渡された行は必要であれば変更することができます。ブロックの評価後に行を全て output に書き込みます。

[PARAM] input:: String か IO のインスタンスを指定します。デフォルトは ARGF です。
[PARAM] output:: String か IO のインスタンスを指定します。デフォルトは $stdout です。
[PARAM] options:: ":in_", ":input_" で始まるキーは input にだけ適用されます。 ":out_", ":output_" で始まるキーは output にだけ適用されます。それ以外のキーは両方に適用されます。 ":output_row_sep" のデフォルト値は $/ です。

[SEE_ALSO] CSV.new

foreach(path, options = Hash.new) {|row| ... } -> nil

このメソッドは CSV ファイルを読むための主要なインターフェイスです。各行が与えられたブロックに渡されます。

例:

# UTF-32BE な CSV ファイルを読み込んで UTF-8 な row をブロックに渡します
CSV.foreach("a.csv", encoding: "UTF-32BE:UTF-8"){|row| p row }

[PARAM] path:: CSV ファイルのパスを指定します。
[PARAM] options:: CSV.new のオプションと同じオプションを指定できます。 :encoding というキーを使用すると入出力のエンコーディングを指定することができます。 Encoding.default_external と異なるエンコーディングを持つ入力を使用する場合は、必ずエンコーディングを指定してください。

[SEE_ALSO] CSV.new, File.open

generate(str = "", options = Hash.new) {|csv| ... } -> String

このメソッドは与えられた文字列をラップして CSV のオブジェクトとしてブロックに渡します。ブロック内で CSV オブジェクトに行を追加することができます。ブロックを評価した結果は文字列を返します。

このメソッドに与えられた文字列は変更されるので、新しい文字列オブジェクトが必要な場合は Object#dup で複製してください。

[PARAM] str:: 文字列を指定します。デフォルトは空文字列です。
[PARAM] options:: CSV.new のオプションと同じオプションを指定できます。 :encoding というキーを使用すると出力のエンコーディングを指定することができます。 ASCII と互換性の無い文字エンコーディングを持つ文字列を出力する場合は、このヒントを指定する必要があります。

[SEE_ALSO] CSV.new

generate_line(row, options = Hash.new) -> String

このメソッドは一つの Array オブジェクトを CSV 文字列に変換するためのショートカットです。

このメソッドは可能であれば row に含まれる最初の nil でない値を用いて出力のエンコーディングを推測します。

[PARAM] row:: 文字列の配列を指定します。
[PARAM] options:: CSV.new のオプションと同じオプションを指定できます。 :encoding というキーを使用すると出力のエンコーディングを指定することができます。 :row_sep というキーの値には $/ がセットされます。

[SEE_ALSO] CSV.new

instance(data = $stdout, options = Hash.new) -> CSV

instance(data = $stdout, options = Hash.new) {|csv| ... } -> object

このメソッドは CSV.new のように CSV のインスタンスを返します。しかし、返される値は Object#object_id と与えられたオプションをキーとしてキャッシュされます。

ブロックが与えられた場合、生成されたインスタンスをブロックに渡して評価した結果を返します。

[PARAM] data:: String か IO のインスタンスを指定します。
[PARAM] options:: CSV.new のオプションと同じオプションを指定できます。

[SEE_ALSO] CSV.new

load(io_or_str, options = Hash.new) -> Array

このメソッドは CSV.dump で出力されたデータを読み込みます。

csv_load という名前のクラスメソッドを追加すると、データを読み込む方法をカスタマイズすることができます。csv_load メソッドはメタデータ、ヘッダ、行の三つのパラメータを受けとります。そしてそれらを元にして復元したオブジェクトを返します。

Remember that all fields will be Strings after this load. If you need something else, use +options+ to setup converters or provide a custom csv_load() implementation.

[PARAM] io_or_str:: IO か String のインスタンスを指定します。
[PARAM] options:: CSV.new のオプションと同じオプションを指定できます。

[SEE_ALSO] CSV.new, CSV.dump

new(data, options = Hash.new) -> CSV

このメソッドは CSV ファイルを読み込んだり、書き出したりするために String か IO のインスタンスをラップします。

ラップされた文字列の先頭から読み込むことになります。文字列に追記したい場合は CSV.generate を使用してください。他の位置から処理したい場合はあらかじめそのように設定した StringIO を渡してください。

[PARAM] data:: String か IO のインスタンスを指定します。 String のインスタンスを指定した場合、CSV#string を使用して後からデータを取り出すことが出来ます。
[PARAM] options:: CSV をパースするためのオプションをハッシュで指定します。パフォーマンス上の理由でインスタンスメソッドではオプションを上書きすることが出来ないので、上書きしたい場合は必ずここで上書きするようにしてください。

:col_sep: フィールドの区切り文字列を指定します。この文字列はパースする前にデータのエンコーディングに変換されます。
:row_sep: 行区切りの文字列を指定します。:auto という特別な値をセットすることができます。 :auto を指定した場合データから自動的に行区切りの文字列を見つけ出します。このときデータの先頭から次の "\r\n", "\n", "\r" の並びまでを読みます。 A sequence will be selected even if it occurs in a quoted field, assuming that you would have the same line endings there. If none of those sequences is found, +data+ is ARGF, Kernel::STDIN, Kernel::STDOUT, or Kernel::STDERR, or the stream is only available for output, the default $INPUT_RECORD_SEPARATOR ($/) is used. Obviously, discovery takes a little time. Set manually if speed is important. Also note that IO objects should be opened in binary mode on Windows if this feature will be used as the line-ending translation can cause problems with resetting the document position to where it was before the read ahead. This String will be transcoded into the data's Encoding before parsing.
:quote_char: フィールドをクオートする文字を指定します。長さ 1 の文字列でなければなりません。正しいダブルクオートではなく間違ったシングルクオートを使用しているアプリケーションで便利です。 CSV will always consider a double sequence this character to be an escaped quote. この文字列はパースする前にデータのエンコーディングに変換されます。
:field_size_limit: This is a maximum size CSV will read ahead looking for the closing quote for a field. (In truth, it reads to the first line ending beyond this size.) If a quote cannot be found within the limit CSV will raise a MalformedCSVError, assuming the data is faulty. You can use this limit to prevent what are effectively DoS attacks on the parser. However, this limit can cause a legitimate parse to fail and thus is set to +nil+, or off, by default.
:converters: CSV::Converters から取り出した名前の配列です。変換器が一つだけの場合は配列に格納する必要はありません。全ての組み込みの変換器は、値を変換する前に UTF-8 にエンコーディング変換を試みます。エンコーディング変換に失敗した場合はフィールドは変換されません。
:unconverted_fields: 真をセットすると CSV::Row#unconverted_fields という変換前のフィールドを返すメソッドを全ての行に追加します。headers オプションによって追加したヘッダはフィールドではないので CSV::Row#unconverted_fields は空の配列を返します。
:headers: :first_row というシンボルか真を指定すると、CSV ファイルの一行目をヘッダとして扱います。配列を指定するとそれをヘッダとして扱います。文字列を指定すると CSV.parse_line を使用してパースした結果をヘッダとして扱います。このとき、:col_sep, :row_sep, :quote_char はこのインスタンスと同じものを使用します。この設定は CSV#shift の返り値を配列のかわりに CSV::Row のインスタンスに変更します。 CSV#read の返り値を配列の配列のかわりに CSV::Table のインスタンスに変更します。
:return_headers: 偽を指定すると、ヘッダ行を無視します。真を指定すると、ヘッダ行をヘッダと値が同一の CSV::Row のインスタンスとして返します。
:write_headers: 真を指定して :headers にも値をセットすると、ヘッダを出力します。
:header_converters: :converters オプションに似ていますが、ヘッダ専用の変換器を定義します。全ての組み込みの変換器は、値を変換する前に UTF-8 にエンコーディング変換を試みます。エンコーディング変換に失敗した場合はヘッダは変換されません。
:skip_blanks: 真を指定すると、空行を読み飛ばします。
:force_quotes: 真を指定すると、全てのフィールドを作成時にクオートします。

[EXCEPTION] CSV::MalformedCSVError:: 不正な CSV をパースしようとしたときに発生します。

[SEE_ALSO] CSV::DEFAULT_OPTIONS, CSV.open

new -> Object

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

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

open(filename, mode = "rb", options = Hash.new) {|csv| ... } -> nil

open(filename, mode = "rb", options = Hash.new) -> CSV

open(filename, options = Hash.new) {|csv| ... } -> nil

open(filename, options = Hash.new) -> CSV

このメソッドは IO オブジェクトをオープンして CSV でラップします。これは CSV ファイルを書くための主要なインターフェイスとして使うことを意図しています。

このメソッドは IO.open と同じように動きます。ブロックが与えられた場合はブロックに CSV オブジェクトを渡し、ブロック終了時にそれをクローズします。ブロックが与えられなかった場合は CSV オブジェクトを返します。この挙動は Ruby1.8 の CSV ライブラリとは違います。Ruby1.8 では行をブロックに渡します。 Ruby1.9 では CSV.foreach を使うとブロックに行を渡します。

データが Encoding.default_external と異なる場合は、mode にエンコーディングを指定する文字列を埋め込まなければなりません。データをどのように解析するか決定するために CSV ライブラリはユーザが mode に指定したエンコーディングをチェックします。"rb:UTF-32BE:UTF-8" のように mode を指定すると UTF-32BE のデータを読み込んでUTF-8 に変換してから解析します。

CSV オブジェクトは多くのメソッドを IO や File に委譲します。

[PARAM] filename:: ファイル名を指定します。
[PARAM] mode:: IO.open に指定できるものと同じものを指定できます。
[PARAM] options:: CSV.new のオプションと同じオプションを指定できます。

[SEE_ALSO] CSV.new, IO.open

parse(str, options = Hash.new) {|row| ... } -> nil

parse(str, options = Hash.new) -> Array

このメソッドは文字列を簡単にパースすることができます。ブロックを与えた場合は、ブロックにそれぞれの行を渡します。ブロックを省略した場合は、配列の配列を返します。

[PARAM] str:: 文字列を指定します。
[PARAM] options:: CSV.new のオプションと同じオプションを指定できます。

parse_line(line, options = Hash.new) -> Array

このメソッドは一行の CSV 文字列を配列に変換するためのショートカットです。

[PARAM] line:: 文字列を指定します。複数行の文字列を指定した場相は、一行目以外は無視します。
[PARAM] options:: CSV.new のオプションと同じオプションを指定できます。

read(path, options = Hash.new) -> [Array]

readlines(path, options = Hash.new) -> [Array]

CSV ファイルを配列の配列にするために使います。

[PARAM] path:: CSV ファイルのパスを指定します。
[PARAM] options:: CSV.new のオプションと同じオプションを指定できます。 :encoding というキーを使用すると入力のエンコーディングを指定することができます。入力のエンコーディングか Encoding.default_external と異なる場合は必ず指定しなければなりません。

[SEE_ALSO] CSV.new

table(path, options = Hash.new) -> Array

以下の例と同等のことを行うメソッドです。日本語の CSV ファイルを扱う場合はあまり使いません。

例:

CSV.read( path, { headers:           true,
                  converters:        :numeric,
                  header_converters: :symbol }.merge(options) )

[PARAM] path:: ファイル名を指定します。
[PARAM] options:: CSV.new のオプションと同じオプションを指定できます。

インスタンスメソッド

self !~ other -> bool

自身が other とマッチしない事を判定します。

self#=~(obj) を反転した結果と同じ結果を返します。

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

[SEE_ALSO] Object#=~

self << row -> self

add_row(row) -> self

puts(row) -> self

自身に row を追加します。

データソースは書き込み用にオープンされていなければなりません。

[PARAM] row:: 配列か CSV::Row のインスタンスを指定します。 CSV::Row のインスタンスが指定された場合は、CSV::Row#fields の値のみが追加されます。

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

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

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

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

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

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

[SEE_ALSO] String#=~

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

binmode -> self

IO#binmode に委譲します。

binmode? -> bool

IO#binmode? に委譲します。

chunk {|elt| ... } -> Enumerator

chunk(initial_state) {|elt, state| ... } -> Enumerator

要素を前から順にブロックで評価し、その結果によって要素をチャンクに分けた(グループ化した)要素を持つ Enumerator を返します。

ブロックの評価値が同じ値が続くものを一つのチャンクとして取り扱います。すなわち、ブロックの評価値が一つ前と異なる所でチャンクが区切られます。

返り値の Enumerator は各チャンクのブロック評価値と各チャンクの要素を持つ配列のペアを各要素とします。そのため、eachだと以下のようになります。

enum.chunk {|elt| key }.each {|key, ary| ... }
enum.chunk(initial_state) {|elt, state| key }.each {|key, ary| ... }

例として、整数列を連続する奇数/偶数に分ける例を見てみます。「n.even?」が変換するところで区切られているのがわかるでしょう。

[3,1,4,1,5,9,2,6,5,3,5].chunk {|n|
  n.even?
}.each {|even, ary|
  p [even, ary]
}
#=> [false, [3, 1]]
#   [true, [4]]
#   [false, [1, 5, 9]]
#   [true, [2, 6]]
#   [false, [5, 3, 5]]

このメソッドは各要素が既にソートされている場合に便利です。以下の例では、テキスト辞書ファイル(中身がソートされている) に含まれる単語を先頭の文字ごとに数えています。

# line.ord は先頭の文字のコードポイントを返す
open("/usr/share/dict/words", "r:iso-8859-1") {|f|
  f.chunk {|line| line.ord }.each {|ch, lines| p [ch.chr, lines.length] }
}
#=> ["\n", 1]
#   ["A", 1327]
#   ["B", 1372]
#   ["C", 1507]
#   ["D", 791]
#   ...

さらにこのメソッドは以下の値を特別扱いします。

ブロックの評価値が nil もしくは :_separator であった場合、その要素を捨てます。チャンクはこの前後で区切られます。
ブロックの評価値 :_alone であった場合はその要素は単独のチャンクをなすものと解釈されます。

アンダースコアで始まるシンボルはこのメソッドでは予約されています。ブロックの返り値としては用いないでください。

nil、 :_separator はある要素を無視したい場合に用います。例として svn log の出力のハイフンの所で区切りたい場合を考えます。

sep = "-"*72 + "\n" # ハイフンが72個の行
IO.popen("svn log README") {|f|
  f.chunk {|line|
    line != sep || nil
  }.each {|_, lines|
    pp lines
  }
}
#=> ["r20018 | knu | 2008-10-29 13:20:42 +0900 (Wed, 29 Oct 2008) | 2 lines\n",
#    "\n",
#    "* README, README.ja: Update the portability section.\n",
#    "\n"]
#   ["r16725 | knu | 2008-05-31 23:34:23 +0900 (Sat, 31 May 2008) | 2 lines\n",
#    "\n",
#    "* README, README.ja: Add a note about default C flags.\n",
#    "\n"]
#   ...

テキストを空行で区切られた段落に分けたい場合にも nil が使えます。

File.foreach("README").chunk {|line|
  /\A\s*\z/ !~ line || nil
}.each {|_, lines|
  pp lines
}

「:_alone」は要素を素通ししたい場合に用います。以下の例では「Foo#bar」という形式の行が連続している場合のみチャンク化し、それ以外は素通しします。

pat = /\A[A-Z][A-Za-z0-9_]+\#/
open(filename) {|f|
  f.chunk {|line| pat =~ line ? $& : :_alone }.each {|key, lines|
    if key != :_alone
      print lines.sort.join('')
    else
      print lines.join('')
    end
  }
}

チャンク化に状態遷移が必要な場合は、オプション引数 initial_state に状態を保持するオブジェクトを渡します。この場合、ブロックの第2引数にはこのオブジェクトが dup で複製されて渡されます。

[PARAM] initial_state:: 状態を保持するオブジェクト
[EXCEPTION] RuntimeError:: 予約されている値を用いた場合に発生します

class -> 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?

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

close -> nil

IO#close に委譲します。

close_read -> nil

IO#close_read に委譲します。

close_write -> nil

IO#close_write に委譲します。

closed? -> bool

IO#closed? に委譲します。

col_sep -> String

カラム区切り文字列として使用する文字列を返します。

[SEE_ALSO] CSV.new

collect -> Enumerator

map -> Enumerator

collect {|item| ... } -> [object]

map {|item| ... } -> [object]

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

ブロックを省略した場合、上で説明した繰り返しを実行し、その結果として得られる配列を返すような Enumerator オブジェクトを返します。

例:

# すべて 3 倍にする
p [1, 2, 3].map {|n| n * 3 }  # => [3, 6, 9]

flat_map -> Enumerator

collect_concat -> Enumerator

flat_map {| obj | block } -> Array

collect_concat {| obj | block } -> Array

各要素をブロックに渡し、その返り値を連結した配列を返します。

ブロックの返り値は基本的に配列を返すべきです。

ブロックを省略した場合は、ブロックを受けとり上で説明した評価をし、その結果の配列を返す Enumerator オブジェクトを返します。

[[1,2], [3,4]].flat_map{|i| i.map{|j| j*2}} # => [2,4,6,8]

convert(name)

convert {|field| ... }

convert {|field, field_info| ... }

組み込みの CSV::Converters を変換器として利用するために使います。また、独自の変換器を追加することもできます。

ブロックパラメータを一つ受け取るブロックを与えた場合は、そのブロックはフィールドを受け取ります。ブロックパラメータを二つ受け取るブロックを与えた場合は、そのブロックは、フィールドと CSV::FieldInfo のインスタンスを受け取ります。ブロックは変換後の値かフィールドそのものを返さなければなりません。

[PARAM] name:: 変換器の名前を指定します。

converters -> Array

現在の変換器のリストを返します。

[SEE_ALSO] CSV::Converters

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

ブロックを省略した場合は、n 回 or 無限回 enum の各要素を繰り返す Enumerator を返します。

[RETURN]: ブロックを指定しなかった場合は、Enumerator を返します。レシーバが空の場合は nil を返します。

find(ifnone = nil) -> Enumerator

detect(ifnone = nil) -> Enumerator

find(ifnone = nil) {|item| ... } -> object

detect(ifnone = nil) {|item| ... } -> object

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

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

ブロックを省略した場合は、各要素に対しブロックを真になるまで評価し、最初に真になった値を返すような Enumerator を返します。

[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 -> Enumerator

drop_while {|element| ... } -> Array

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

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

a = [1, 2, 3, 4, 5, 0]
a.drop_while {|i| i < 3 }   # => [3, 4, 5, 0]

each {|row| ... } -> nil

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

データソースは読み込み用にオープンされていなければなりません。

each_cons(n) -> Enumerator

each_cons(n) {|list| ... } -> nil

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

ブロックを省略した場合は重複ありで n 要素ずつ繰り返す Enumerator を返します。

[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_entry -> Enumerator

each_entry {|obj| block} -> self

ブロックを各要素に一度ずつ適用します。

一要素として複数の値が渡された場合はブロックには配列として渡されます。

class Foo
  include Enumerable
  def each
    yield 1
    yield 1,2
  end
end
Foo.new.each_entry{|o| print o, " -- "}
# => 1 -- [1, 2] --

ブロックを省略した場合は Enumerator が返されます。

[SEE_ALSO] Enumerable#slice_before

each_slice(n) -> Enumerator

each_slice(n) {|list| ... } -> nil

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

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

ブロックを省略した場合は n 要素ずつ繰り返す Enumerator を返します。

[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 -> Enumerator

each_with_index {|item, index| ... } -> self

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

self を返します。

ブロックを省略した場合は、要素とそのインデックスを繰り返すような Enumerator を返します。

例:

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

each_with_object(obj) -> Enumerator

each_with_object(obj) {|(*args), memo_obj| ... } -> object

与えられた任意のオブジェクトと要素をブロックに渡し繰り返し、最初に与えられたオブジェクトを返します。

ブロックを省略した場合は、上の繰り返しをして、最初に与えたオブジェクトを最後に返す Enumerator を返します。

[PARAM] obj:: 任意のオブジェクトを指定します。

evens = (1..10).each_with_object([]) {|i, a| a << i*2 }
# => [2, 4, 6, 8, 10, 12, 14, 16, 18, 20]

[SEE_ALSO] Enumerator#with_object

encoding -> Encoding

読み書きするときに使用するエンコーディングを返します。

to_a -> [object]

entries -> [object]

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

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

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

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) #=> #<Enumerator: [1, 2, 3]:each>

[SEE_ALSO] Enumerator

eof -> bool

eof? -> bool

IO#eof, IO#eof? に委譲します。

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

external_encoding -> Encoding | nil

IO#external_encoding に委譲します。

fcntl(cmd, arg = 0) -> Integer

IO#fcntl に委譲します。

field_size_limit -> Fixnum

フィールドサイズの最大値を返します。

[SEE_ALSO] CSV.new

fileno -> Integer

to_i -> Integer

IO#fileno, IO#to_i に委譲します。

find_all -> Enumerator

select -> Enumerator

find_all {|item| ... } -> [object]

select {|item| ... } -> [object]

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

ブロックを省略した場合は、各要素に対しブロックを評価し真になった値の配列を返すような Enumerator を返します。

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

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

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

flock(operation) -> 0 | false

File#flock に委譲します。

flush -> self

IO#flush に委譲します。

force_quotes? -> bool

出力されるフィールドがクオートされる場合は、真を返します。

[SEE_ALSO] CSV.new

freeze -> self

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

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

凍結されるのはオブジェクトであり、変数ではありません。代入などで変数の指すオブジェクトが変化してしまうことは 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 (RuntimeError)

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

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

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

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

fsync -> 0 | nil

IO#fsync に委譲します。

shift -> Array | CSV::Row

gets -> Array | CSV::Row

readline -> Array | CSV::Row

String や IO をラップしたデータソースから一行だけ読み込んでフィールドの配列か CSV::Row のインスタンスを返します。

データソースは読み込み用にオープンされている必要があります。

[RETURN]: ヘッダを使用しない場合は配列を返します。ヘッダを使用する場合は CSV::Row を返します。

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/) # => [:grep, :group_by]

group_by -> Enumerator

group_by {|obj| ... } -> Hash

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

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

ブロックを省略した場合は、最後に Hash を返す Enumerator オブジェクトを返します。

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?,BasicObject#__id__

header_convert(name)

header_convert {|field| ... }

header_convert {|field, field_info| ... }

CSV#convert に似ていますが、ヘッダ行用のメソッドです。

このメソッドはヘッダ行を読み込む前に呼び出さなければなりません。

[PARAM] name:: 変換器の名前を指定します。

[SEE_ALSO] CSV#convert

header_converters -> Array

現在有効なヘッダ用変換器のリストを返します。

組込みの変換器は名前を返します。それ以外は、オブジェクトを返します。

[SEE_ALSO] CSV.new

header_row? -> bool

次に読み込まれる行が、ヘッダである場合に真を返します。そうでない場合は、偽を返します。

headers -> Array | true | nil

nil を返した場合は、ヘッダは使用されません。真を返した場合は、ヘッダを使用するが、まだ読み込まれていません。配列を返した場合は、ヘッダは既に読み込まれています。

[SEE_ALSO] CSV.new

member?(val) -> bool

include?(val) -> bool

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

[PARAM] val:: 任意のオブジェクト

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"

inspect -> String

ASCII 互換文字列で自身の情報を表したものを返します。

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_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 -> [Symbol]

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

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

internal_encoding -> Encoding | nil

IO#internal_encoding に委譲します。

ioctl(cmd, arg = 0) -> Integer

IO#ioctl に委譲します。

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

isatty -> bool

tty? -> bool

IO#isatty, IO#tty? に委譲します。

lineno -> Fixnum

このファイルから読み込んだ最終行の行番号を返します。フィールドに含まれる改行はこの値には影響しません。

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

max_by {|item| ... } -> object

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

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

Enumerable#max と Enumerable#max_by の違いは Enumerable#sort と Enumerable#sort_by の違いと同じです。

ブロックを省略した場合は、各要素を順番にブロックに渡して評価し、その結果が最小となる値に対応する要素を返す Enumerator を返します。

[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

methods(include_inherited = true) -> [Symbol]

そのオブジェクトに対して呼び出せるメソッド名の一覧を返します。このメソッドは 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)

#実行結果

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

#例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)

#実行結果

[:protected_singleton, :public_singleton, :protected_foo, :public_foo, :protected_parent, :public_parent]
[:public_singleton, :public_foo, :public_parent]
[: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 -> Enumerator

min_by {|item| ... } -> object

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

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

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

ブロックを省略した場合は、各要素を順番にブロックに渡して評価し、その結果が最小となる値に対応する要素を返す Enumerator を返します。

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

ブロックを省略した場合は、Enumerator オブジェクトを返します。

[SEE_ALSO] Enumerable#sort_by

nil? -> bool

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

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

[SEE_ALSO] NilClass

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

object_id -> Integer

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

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

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

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

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

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

partition -> Enumerator

partition {|item| ... } -> [[object], [object]]

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

ブロックを省略した場合は、各要素に対しブロックを評価し、上のようにその値が真であった要素の配列と、偽であった要素の配列のペアを返すような Enumerator を返します。

例:

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

path -> String

IO#path に委譲します。

pid -> Integer | nil

IO#pid に委譲します。

pos -> Integer

tell -> Integer

IO#pos, IO#tell に委譲します。

pos=(n)

IO#pos= に委譲します。

private_methods(include_inherited = true) -> [Symbol]

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

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

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

protected_methods(include_inherited = true) -> [Symbol]

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

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

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

public_methods(include_inherited = true) -> [Symbol]

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

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

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

public_send(name, *args) -> object

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

1.public_send(:+, 2)  # => 3

[PARAM] name:: 文字列かSymbol で指定するメソッド名です。
[PARAM] args:: 呼び出すメソッドに渡す引数です。
[EXCEPTION] ArgumentError:: name を指定しなかった場合に発生します。
[EXCEPTION] NoMethodError:: protected メソッドや private メソッドに対して実行した場合に発生します。

1.public_send(:puts, "hello")  # => NoMethodError

[SEE_ALSO] Object#send

quote_char -> String

フィールドをクオートするのに使用する文字列を返します。

[SEE_ALSO] CSV.new

read -> [Array]

readlines -> [Array]

残りの行を読み込んで配列の配列を返します。

データソースは読み込み用にオープンされている必要があります。

reject -> Enumerator

reject {|item| ... } -> [object]

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

ブロックを省略した場合は、各要素に対しブロックを評価し偽になった値の配列を返すような Enumerator を返します。

例:

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

[SEE_ALSO] Enumerable#select

reopen(io) -> self

IO#reopen に委譲します。

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?

respond_to_missing?(symbol, include_private) -> bool

自身が symbol で表されるメソッドに対し BasicObject#method_missing で反応するつもりならば真を返します。

Object#respond_to? はメソッドが定義されていない場合、デフォルトでこのメソッドを呼びだし問合せます。

BasicObject#method_missing を override した場合にこのメソッドも override されるべきです。

false を返します。

[PARAM] symbol:: メソッド名シンボル
[PARAM] include_private:: private method も含めたい場合に true が渡されます

[SEE_ALSO] Object#respond_to?, BasicObject#method_missing

return_headers? -> bool

ヘッダを返す場合は、真を返します。そうでない場合は、偽を返します。

[SEE_ALSO] CSV.new

reverse_each -> Enumerator

reverse_each {|element| ... } -> self

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

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

ブロックを省略した場合は、各要素を逆順に辿る Enumerator を返します。

rewind -> 0

IO#rewind に似ています。CSV#lineno を 0 にします。

[SEE_ALSO] IO#rewind

row_sep -> String

行区切り文字列として使用する文字列を返します。

[SEE_ALSO] CSV.new

seek(offset, whence = IO::SEEK_SET) -> 0

IO#seek に委譲します。

singleton_class -> Class

レシーバの特異クラスを返します。まだ特異クラスがなければ、新しく作成します。

レシーバが nil か true か false なら、それぞれ NilClass, TrueClass, FalseClass を返します。

[EXCEPTION] TypeError:: レシーバが Fixnum か Symbol の場合に発生します。

Object.new.singleton_class  #=> #<Class:#<Object:0xb7ce1e24>>
String.singleton_class      #=> #<Class:String>
nil.singleton_class         #=> NilClass

[SEE_ALSO] Object#class

singleton_methods(inherited_too = true) -> [Symbol]

そのオブジェクトに対して定義されている特異メソッド名 (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)

#実行結果

[:protected_self, :public_self]
[:protected_self, :public_self]
[:protected_class_foo, :public_class_foo]


#例2:

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

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

#実行結果

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

[SEE_ALSO] Object#methods,Object#extend

skip_blanks? -> bool

真である場合は、空行を読み飛ばします。

[SEE_ALSO] CSV.new

slice_before(pattern) -> Enumerator

slice_before {|elt| bool } -> Enumerator

slice_before(initial_state) {|elt, state| bool } -> Enumerator

パターンがマッチした要素、もしくはブロックが真を返した要素から次にマッチする手前までをチャンク化(グループ化)したものを繰り返す Enumerator を返します。

パターンを渡した場合は各要素に対し === が呼び出され、それが真になったところをチャンクの先頭と見なします。ブロックを渡した場合は、各要素に対しブロックを適用し返り値が真であった要素をチャンクの先頭と見なします。

より厳密にいうと、「先頭要素」の手前で分割していきます。最初の要素の評価は無視されます。

各チャンクは配列として表現されます。

Enumerable#map のようなメソッドを使うこともできます。

# 偶数要素をチャンクの先頭と見なす
[0,2,4,1,2,4,5,3,1,4,2].slice_before(&:even?).to_a
# => [[0], [2], [4, 1], [2], [4, 5, 3, 1], [4], [2]]

# 奇数要素をチャンクの先頭と見なす
[0,2,4,1,2,4,5,3,1,4,2].slice_before(&:odd?).to_a
# => [[0, 2, 4], [1, 2, 4], [5], [3], [1, 4, 2]]

# ChangeLog のエントリーを順に取る
open("ChangeLog") {|f|
  f.slice_before(/\A\S/).each {|e| pp e}
}

# 上と同じだが、パターンでなくブロックを使う
open("ChangeLog") {|f|
  f.slice_before {|line| /\A\S/ === line }.each {|e| pp e}
}

# "svn proplist -R" の結果を分割する
# これは一要素が複数行にまたがっている

IO.popen([{"LC_ALL"=>"C"}, "svn", "proplist", "-R"]) {|f|
  f.lines.slice_before(/\AProp/).each {|lines| p lines }
}
#=> ["Properties on '.':\n", "  svn:ignore\n", "  svk:merge\n"]
#   ["Properties on 'goruby.c':\n", "  svn:eol-style\n"]
#   ["Properties on 'complex.c':\n", "  svn:mime-type\n", "  svn:eol-style\n"]
#   ["Properties on 'regparse.c':\n", "  svn:eol-style\n"]
#   ...

複数要素にわたる状態遷移が必要な場合は、ローカル変数でこれを実現することができます。例えば、連続に増える数値が3つ以上ある場合、これをまとめる処理をするためには以下のようにします。

a = [0,2,3,4,6,7,9]
prev = a[0]
p a.slice_before {|e|
  prev, prev2 = e, prev
  prev2 + 1 != e
}.map {|es|
  es.length <= 2 ? es.join(",") : "#{es.first}-#{es.last}"
}.join(",")
#=> "0,2-4,6,7,9"

しかし、ローカル変数を使うのが不適切な場合もあります。その場合、引数 initial_state に状態を保持するオブジェクトを渡すと、そのオブジェクトを Object#dup したオブジェクトを各要素ごとのブロック呼び出しの第2引数として渡します。

# word wrapping.
# this assumes all characters have same width.
def wordwrap(words, maxwidth)
  # if cols is a local variable, 2nd "each" may start with non-zero cols.
  words.slice_before(cols: 0) {|w, h|
    h[:cols] += 1 if h[:cols] != 0
    h[:cols] += w.length
    if maxwidth < h[:cols]
      h[:cols] = w.length
      true
    else
      false
    end
  }
end
text = (1..20).to_a.join(" ")
enum = wordwrap(text.split(/\s+/), 10)
puts "-"*10
enum.each {|ws| puts ws.join(" ") }
puts "-"*10
#=> ----------
#   1 2 3 4 5
#   6 7 8 9 10
#   11 12 13
#   14 15 16
#   17 18 19
#   20
#   ----------

以下は mbox を分割する例です。mbox 内の各メールは Unix From line で始まっています。そこで slice_before を用います。

# parse mbox
open("mbox") {|f|
  f.slice_before {|line|
    line.start_with? "From "
  }.each {|mail|
    unix_from = mail.shift
    i = mail.index("\n")
    header = mail[0...i]
    body = mail[(i+1)..-1]
    body.pop if body.last == "\n"
    fields = header.slice_before {|line| !" \t".include?(line[0]) }.to_a
    p unix_from
    pp fields
    pp body
  }
}

# split mails in mbox (slice before Unix From line after an empty line)
open("mbox") {|f|
  f.slice_before(emp: true) {|line,h|
    prevemp = h[:emp]
    h[:emp] = line == "\n"
    prevemp && line.start_with?("From ")
  }.each {|mail|
    mail.pop if mail.last == "\n"
    pp mail
  }
}

[PARAM] initial_state:: 状態を保持するオブジェクト

[SEE_ALSO] Enumerable#chunk

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 -> 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)」と言います。

ブロックを省略した場合は、各要素をブロックで評価した値でソートした配列を返すような Enumerator を返します。

[SEE_ALSO] Enumerable#sort

stat -> File::Stat

IO#stat に委譲します。

string -> String

StringIO#string に委譲します。

sync -> bool

IO#sync に委譲します。

sync=(newstate)

IO#sync= に委譲します。

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

take_while {|element| ... } -> Array

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

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

ブロックを省略した場合は、Enumerator オブジェクトを返します。

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

オブジェクトを配列に変換した結果を返します。デフォルトでは定義されていません。

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

p( {'a'=>1}.to_a )  # [["a", 1]]
p ['array'].to_a    # ["array"]
p nil.to_a          # []

[SEE_ALSO] Object#to_ary,Kernel.#Array

to_ary -> Array

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

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

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

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

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

IO#to_io に委譲します。

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

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

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

truncate(path, length) -> 0

File#truncate に委譲します。

trust -> self

[TODO]

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

[SEE_ALSO] Object#untrusted?,Object#untrust

unconverted_fields? -> bool

パースした結果が unconverted_fields というメソッドを持つ場合に真を返します。そうでない場合は、偽を返します。

[SEE_ALSO] CSV.new

untaint -> self

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

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

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

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

[SEE_ALSO] Object#taint,Object#tainted?

untrust -> self

[TODO]

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

[SEE_ALSO] Object#trust,Object#untrusted?

untrusted? -> bool

[TODO]

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

[SEE_ALSO] Object#trust,Object#untrust

write_headers? -> bool

ヘッダを出力先に書き込む場合は真を返します。そうでない場合は偽を返します。

[SEE_ALSO] CSV.new

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

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

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

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

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

例:

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

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

定数

ConverterEncoding -> Encoding

すべての変換器で使用するエンコーディングです。

Converters -> Hash

このハッシュは名前でアクセスできる組み込みの変換器を保持しています。

CSV#convert で使用する変換器として使用できます。また CSV.new のオプションとして使用することもできます。

:integer: Kernel.#Integer を使用してフィールドを変換します。
:float: Kernel.#Float を使用してフィールドを変換します。
:numeric: :integer と :float の組み合わせです。
:date: Date.parse を使用してフィールドを変換します。
:date_time: DateTime.parse を使用してフィールドを変換します。
:all: :date_time と :numeric の組み合わせです。

全ての組み込みの変換器は、実際に変換する前にフィールドのデータの文字エンコーディングを UTF-8 に変換します。そのデータの文字エンコーディングを UTF-8 に変換出来なかった場合は、変換には失敗しますが、データは変更されません。

このハッシュは Object#freeze されていないので、ユーザは自由に値を追加することが出来ます。

複数の変換器を持つ要素を追加するときは、値に名前の配列を指定する必要があります。この要素の値には他の複数の変換器を持つ要素の名前を指定することもできます。

DEFAULT_OPTIONS -> Hash

このオプションは呼び出し側で上書きしなかったときに使用するオプションです。

:col_sep: ","
:row_sep: :auto
:quote_char: '"'
:field_size_limit: nil
:converters: nil
:unconverted_fields: nil
:headers: false
:return_headers: false
:header_converters: nil
:skip_blanks: false
:force_quotes: false

DateMatcher -> Regexp

日付 (Date) 形式のデータを発見したり変換したりするための正規表現です。

DateTimeMatcher -> Regexp

日時 (DateTime) 形式のデータを発見したり変換したりするための正規表現です。

HeaderConverters -> Hash

このハッシュは名前でアクセスできる組み込みのヘッダ用変換器を保存しています。

CSV#header_convert で使用する変換器として使用できます。また CSV.new のオプションとして使用することもできます。

:downcase: ヘッダの文字列に対して String#downcase を呼び出します。
:symbol: ヘッダの文字列を小文字に変換してから、空白文字列 (\s) をアンダースコアに置換し、非英数字 (\W) を削除します。最後に String#to_sym を呼び出します。

全ての組み込みのヘッダ用変換器は、実際に変換する前にヘッダのデータの文字エンコーディングを UTF-8 に変換します。そのヘッダの文字エンコーディングを UTF-8 に変換できなかった場合は、変換には失敗しますが、データは変更されません。

このハッシュは Object#freeze されていないので、ユーザは自由に値を追加することが出来ます。

VERSION -> String

ライブラリのバージョンを表す文字列です。

class CSV