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

class CSV + Enumerable

クラスの継承リスト: 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

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

add_row(row) -> self

puts(row) -> self

自身に row を追加します。

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

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

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:: 予約されている値を用いた場合に発生します

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

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]

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

eof -> bool

eof? -> bool

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

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

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

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 互換文字列で自身の情報を表したものを返します。

internal_encoding -> Encoding | nil

IO#internal_encoding に委譲します。

ioctl(cmd, arg = 0) -> Integer

IO#ioctl に委譲します。

isatty -> bool

tty? -> bool

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

lineno -> Fixnum

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

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

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

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

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= に委譲します。

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 に委譲します。

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 に委譲します。

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= に委譲します。

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

to_io -> self

IO#to_io に委譲します。

truncate(path, length) -> 0

File#truncate に委譲します。

unconverted_fields? -> bool

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

[SEE_ALSO] CSV.new

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

定数

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