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

class IO + Enumerable

クラスの継承リスト: IO < Enumerable < File::Constants < Object < Kernel < BasicObject

要約

基本的な入出力機能のためのクラスです。

File::Constants は、File から IO へ移動しました。

多言語化と IO のエンコーディング

IO オブジェクトはエンコーディングを持ちます。エンコーディングの影響を受けるメソッドと受けないメソッドがあります。

影響を受けるメソッドでは、IO のエンコーディングに従い読み込まれた文字列のエンコーディングが決定されます。また IO のエンコーディングを適切に設定することにより、読み込み時・書き込み時に文字列のエンコーディングを変換させることもできます。

エンコーディングの影響を受けるメソッドと受けないメソッド

IO の読み込みメソッドは2種類存在します。テキスト読み込みメソッドとバイナリ読み込みメソッドです。

テキスト読み込みメソッドは IO のエンコーディングの影響をうけます。詳しくは「IO のエンコーディングとエンコーディングの変換」を参照して下さい。以下がテキスト読み込みメソッドです。

バイナリ読み込みメソッドは IO のエンコーディングの影響を受けません。返す文字列のエンコーディングは常に ASCII-8BIT になります。以下がバイナリ読み込みメソッドです。

また書き込みメソッド IO#write も IO のエンコーディングの影響を受けます。 IO のすべての書き込みメソッドは内部で IO#write を呼びますので、書き込みメソッドはすべて IO のエンコーディングの影響を受けます。

シーク関連のメソッドはエンコーディングの影響を受けません。常に1バイトを単位として動作します。

例:

f = File.open('t.txt', 'r+:euc-jp')
p f.getc.encoding                             #=> Encoding::EUC_JP
p f.read(1).encoding                          #=> Encoding::ASCII_8BIT

IO のエンコーディングとエンコーディングの変換

IO オブジェクトは外部エンコーディングと内部エンコーディングを持ちます。外部エンコーディングとは IO が表すファイルなどの文字エンコーディングです。内部エンコーディングとは IO から読み込まれた文字列、あるいは IO の書き込みメソッドへ渡す文字列の文字エンコーディングです。

以下の三通りがあります。

IO のエンコーディングが指定されていない場合

IO からテキスト読み込みメソッドによって読み込まれた文字列のエンコーディングは Encoding.default_external に設定されます。このとき実際の文字エンコーディングは検査されず、変換もされません。

外部エンコーディングのみが指定されている場合

IO からテキスト読み込みメソッドによって読み込まれた文字列のエンコーディングは外部エンコーディングに設定されます。このとき実際の文字エンコーディングは検査されず、変換もされません。

IO へ書き込まれる文字列は外部エンコーディングへと変換されます。外部エンコーディングへの変換方法が分からない場合は例外が発生します。

外部エンコーディングと内部エンコーディング(あるいは default_internal)が指定されている場合

IO からテキスト読み込みメソッドによって読み込まれた文字列は、外部エンコーディングから内部エンコーディング(あるいは default_internal)へと変換されます。指定された文字エンコーディングと実際の文字エンコーディングが違っていた場合、例外が発生します。内部エンコーディングと Encoding.default_internal が両方とも指定されている場合は、内部エンコーディングが優先されます。

IO へ書き込まれる文字列は外部エンコーディングへと変換されます。外部エンコーディングへの変換方法が分からない場合は例外が発生します。

IO に対してエンコーディングを指定する方法には、生成時に IO.open や File.open に渡すモードとともに指定するものと生成後に IO#set_encoding を使って指定するものの二通りがあります。詳しくはそれぞれのメソッドの項を参照して下さい。通常は前者の方法を使います。

例1:

f = File.open('file1')
p f.getc.encoding        #=> Encoding::EUC_JP

例2:

f = File.open('t.txt', 'w+:shift_jis:euc-jp')
f.write "\xB4\xC1\xBB\xFA"            # 文字列 "漢字" の EUC-JP リテラル
f.rewind
s = f.read(4)
puts s.dump                           #=> "\x8A\xBF\x8E\x9A"
                                      # エンコーディングがSJISへ変換されていることが分かる。

まとめ

以上をまとめると以下の表のようになります。Encoding.default_external は常に設定されているので、省略してあります。

読み込んだ文字列のエンコーディング

                                                   バイナリ読み込みメソッド      テキスト読み込みメソッド
----------------------------------------------------------------------------------------------------------
                                        指定無し        ASCII-8BIT                   default_external

                           default_internal のみ        ASCII-8BIT                   default_internal

                        外部エンコーディングのみ        ASCII-8BIT                 外部エンコーディング

                    内部エンコーディング指定あり        ASCII-8BIT                 内部エンコーディング

    内部エンコーディングと default_internal 両方        ASCII-8BIT                 内部エンコーディング

エンコーディングの変換

                                              バイナリ読み込みメソッド   テキスト読み込みメソッド   書き込みメソッド
---------------------------------------------------------------------------------------------------------------------
                                  指定無し           変換なし                 変換なし                   変換なし

                  外部エンコーディングのみ           変換なし                 変換なし                   変換あり

                     default_internal のみ           変換なし                 変換あり                   変換あり

                  内部エンコーディングのみ           変換なし                 変換あり                   変換あり

外部エンコーディングと内部エンコーディング           変換なし                 変換あり                   変換あり

   外部エンコーディングと default_internal           変換なし                 変換あり                   変換あり

デフォルトの外部エンコーディングの指定

Encoding.default_external はコマンドオプション -E で指定します。 -E が指定されなかった場合は次のような優先順位で決定されます。

-E (最優先) > -K > locale

ファイル名のエンコーディング

ファイル名の文字エンコーディングはプラットフォームに依存します。ファイル名の文字エンコーディングが固定されているプラットフォーム(Win, Mac)では、エンコーディングは暗黙に変換されます(予定)。UNIX では変換されずそのままシステムコールに渡されます。

Dir.glob, Dir.foreach などが返すファイル名のエンコーディングも同様にプラットフォーム依存です。 UNIX では ASCII-8BIT です。

binmode

Windows の IO にはテキストモードとバイナリモードという2種類のモードが存在します。これらのモードは上で説明した IO のエンコーディングとは独立です。改行の変換にしか影響しません。

EOF での読み込みメソッドの振る舞いの違い

空ファイルや EOF での各読み込みメソッドの振る舞いは以下のとおりです。ただし、length を指定できるメソッドに関しては、length に nil または 0 を指定した場合、 EOF であっても常に空文字列 "" を返します。

メソッド                      空のファイルに対して

IO.read(空ファイル)           ""
IO.read(空ファイル, length)   nil
IO.readlines(空ファイル)      []
IO.foreach(空ファイル)        何もしない

メソッド                      既にEOFだったら

IO#each_byte                  何もしない
IO#getc                       nil
IO#gets                       nil
IO#read()                     ""
IO#read(length)               nil
IO#read_nonblock              EOFError
IO#readchar                   EOFError
IO#readline                   EOFError
IO#readlines                  []
IO#readpartial                EOFError
IO#sysread                    EOFError
IO#bytes                      通常どおり
IO#lines                      通常どおり

特異メソッド

binread(path, length = nil, offset = 0) -> String | nil

path で指定したファイルを open し、offset の所まで seek し、 length バイト読み込みます。

length を省略するとファイルの末尾まで読み込みます。

ファイルを開くときの mode は "rb:ASCII-8BIT" です。

[SEE_ALSO] IO.read

binwrite(path, string, offset=nil) -> Integer

path で指定されるファイルを開き、string を書き込み、閉じます。

offset を指定するとその位置までシークします。

offset を指定しないと、書き込みの末尾でファイルを切り捨てます。

[PARAM] path:: ファイル名文字列
[PARAM] string:: 書き込む文字列
[PARAM] offset:: 書き込み開始位置

[SEE_ALSO] IO.write

copy_stream(src, dst, copy_length = nil) -> Integer

copy_stream(src, dst, copy_length, src_offset) -> Integer

指定された src から dst へコピーします。コピーしたバイト数を返します。

コピー元の src が IO オブジェクトの場合は、src のオフセットからファイル名の場合はファイルの最初からコピーを開始します。コピー先の dst に関しても同様です。

dst にファイル名を指定し、そのファイルが存在しない場合、ファイルは作成されます。ファイルが存在する場合は長さ 0 に切り詰められます。

src が IO オブジェクトでかつ src_offset が指定されている場合、 src のオフセット(src.pos)は変更されません。

[PARAM] src:: コピー元となる IO オブジェクトかファイル名を指定します。
[PARAM] dst:: コピー先となる IO オブジェクトかファイル名を指定します。
[PARAM] copy_length:: コピーする長さをバイト単位で指定します。最大 copy_length までコピーされます。 nil を指定した場合、コピーする長さに制限はありません。
[PARAM] src_offset:: コピーを始めるオフセットを数値で指定します。

new(fd, mode = "r", opt={}) -> IO

for_fd(fd, mode = "r", opt={}) -> IO

open(fd, mode = "r", opt={}) -> IO

open(fd, mode = "r" opt={}) {|io| ... } -> object

オープン済みのファイルディスクリプタ fd に対する新しい IO オブジェクトを生成して返します。

IO.open にブロックが与えられた場合、IO オブジェクトを生成しそれを引数としてブロックを実行します。ブロックの終了とともに fd はクローズされます。ブロックの結果を返します。 IO.new, IO.for_fd はブロックを受け付けません。

オプション引数

このメソッドは以下のオプションを利用できます。

:mode mode引数と同じ意味です
:external_encoding 外部エンコーディング。"-" はデフォルト外部エンコーディングの別名です。
:internal_encoding 内部エンコーディング。"-" はデフォルト内部エンコーディングの別名です。nilなら変換しません。
:encoding "extenc:intenc" の形で外部/内部エンコーディングを指定します。
:textmode 真を渡すと mode の "t" と同じ意味になります。
:binmode 真を渡すと mode の "b" と同じ意味になります。
:autoclose 偽を渡すと close時/GCでのファイナライザ呼出時に fd を close しません。

また、String#encode で説明されている :invalid => :replace などの変換オプションも指定することができます。外部エンコーディングから内部エンコーディングへの変換をするときに用いられます。

[PARAM] fd:: ファイルディスクリプタである整数を指定します。
[PARAM] mode:: Kernel.#open と同じ形式で IO のモードを指定します。File::Constants::RDONLY などの定数(数値)でモードを指定できます。詳細は組み込み関数 Kernel.#open を参照してください。 mode は省略可能で、省略時のデフォルトのモードは、 fcntl(2) で F_GETFL フラグが利用できる環境では第一引数で指定した fd のモードを引き継ぎ、利用できない環境では "r" になります。
[PARAM] opt:: オプション引数
[EXCEPTION] Errno::EXXX:: IO オブジェクトの生成に失敗した場合に発生します。

foreach(path, rs = $/) {|line| ... } -> nil

foreach(path, rs = $/) -> Enumerator

path で指定されたファイルの各行を引数としてブロックを繰り返し実行します。 path のオープンに成功すれば nil を返します。

ブロックが与えられなかった場合は、path で指定されたファイルの各行を繰り返す Enumerator オブジェクトを生成して返します。

テキスト読み込みメソッドとして動作します。 path が空ファイルの場合、何もせずに nil を返します。 Kernel.#open と同様 path の先頭が "|" ならば、"|" に続くコマンドの出力を読み取ります。

[PARAM] path:: ファイル名を表す文字列か "|コマンド名" を指定します。
[PARAM] rs:: 行の区切りを文字列で指定します。rs に nil を指定すると行区切りなしとみなします。空文字列 "" を指定すると連続する改行を行の区切りとみなします(パラグラフモード)。
[EXCEPTION] Errno::EXXX:: path のオープンに失敗した場合、発生します。

[SEE_ALSO] $/

pipe -> [IO]

pipe(ext_enc) -> [IO]

pipe(enc_str, opts={}) -> [IO]

pipe(ext_enc, int_enc, opts={}) -> [IO]

pipe {|read_io, write_io| ... } -> object

pipe(ext_enc) {|read_io, write_io| ... } -> object

pipe(enc_str, opt={}) {|read_io, write_io| ... } -> object

pipe(ext_enc, int_enc, opt={}) {|read_io, write_io| ... } -> object

pipe(2) を実行して、相互につながった2つの IO オブジェクトを要素とする配列を返します。

戻り値の配列は最初の要素が読み込み側で、次の要素が書き込み側です。

ブロックが渡された場合は、そのブロックに2つの IO オブジェクトが渡され、ブロックの返り値がこのメソッドの返り値となります。ブロック終了時に IO オブジェクトがもし close されていないならば close します(close されていてるオブジェクトはそのままです)。

得られる2つの IO オブジェクトのエンコーディングを引数で指定することができます。

[PARAM] enc_str:: 読み込み側の外部エンコーディングを文字列で指定します。文字列がコロンを挟んだ二つのエンコーディング名 "A:B" である場合最初のものが外部エンコーディング、次が内部エンコーディングを意味します。
[PARAM] ext_enc:: 読み込み側の外部エンコーディングを Encoding オブジェクトで指定します。
[PARAM] int_enc:: 読み込み側の内部エンコーディングを Encoding オブジェクトで指定します。
[PARAM] opt:: エンコーディングなどを設定するオプション引数(see IO.new)
[EXCEPTION] Errno::EXXX:: IO オブジェクトの作成に失敗した場合に発生します。

r, w = IO.pipe
p [r, w]            # => [#<IO:0x401b90f8>, #<IO:0x401b7718>]
Thread.new do
  w.puts "foo"
  w.close
end
p r.gets           # => "foo\n"

popen(command, mode = "r", opt={}) -> IO

popen(command, mode = "r", opt={}) {|io| ... } -> object

command をサブプロセスとして実行し、そのプロセスの標準入出力との間にパイプラインを確立します。生成したパイプを IO オブジェクトとして返します。

command が文字列の場合は、シェルを経由して子プロセスを実行します。 command が配列の場合は、シェルを経由せずに子プロセスを実行します。

p io = IO.popen("cat", "r+")  # => #<IO:0x401b75c8>
io.puts "foo"
io.close_write
p io.gets                     # => "foo\n"

ブロックが与えられた場合は生成した IO オブジェクトを引数にブロックを実行し、その結果を返します。ブロックの実行後、生成したパイプは自動的にクローズされます。

p IO.popen("cat", "r+") {|io|
  io.puts "foo"
  io.close_write
  io.gets
}
# => "foo\n"

[PARAM] command:: コマンド名を文字列か配列で指定します。配列が指定された場合には、シェルを経由せずに子プロセスを実行します。
[PARAM] mode:: オープンする IO ポートのモードを指定します。mode の詳細は Kernel.#open 参照して下さい。
[PARAM] opt:: エンコーディングなどを設定するオプション引数(see IO.new)
[EXCEPTION] Errno::EXXX:: パイプ、あるいは子プロセスの生成に失敗した場合に発生します。

popen("-", mode = "r", opt={}) -> IO

popen("-", mode = "r", opt={}) {|io| ... } -> object

第一引数に文字列 "-" が指定された時、fork(2) を行い子プロセスの標準入出力との間にパイプラインを確立します。親プロセスでは IO オブジェクトを返し、子プロセスでは nil を返します。

io = IO.popen("-", "r+")
if io  # parent
  io.puts "foo"
  p io.gets                   # => "child output: foo\n"
  io.close
else   # child
  s = gets
  print "child output: " + s
  exit
end

ブロックを与えられた場合、親プロセスでは生成した IO オブジェクトを引数にブロックを実行し、その結果を返します。ブロックの実行後、生成したパイプは自動的にクローズされます。子プロセスでは nil を引数にブロックを実行し終了します。

p IO.popen("-", "r+") {|io|
  if io   # parent
    io.puts "foo"
    io.gets
  else    # child
    s = gets
    puts "child output: " + s
  end
}
# => "child output: foo\n"

[PARAM] mode:: オープンする IO ポートのモードを指定します。mode の詳細は Kernel.#open 参照して下さい。
[PARAM] opt:: エンコーディングなどを設定するオプション引数(see IO.new)
[EXCEPTION] Errno::EXXX:: パイプ、あるいは子プロセスの生成に失敗した場合に発生します。

read(path, opt = {}) -> String | nil

read(path, length = nil, opt = {}) -> String | nil

read(path, length = nil, offset = 0, opt = {}) -> String | nil

path で指定されたファイルを offset 位置から length バイト分読み込んで返します。

既に EOF に達している場合は nil を返します。ただし、length に nil か 0 が指定されている場合は、空文字列 "" を返します。例えば、IO.read(空ファイル) は "" を返します。

引数 length が指定された場合はバイナリ読み込みメソッド、そうでない場合はテキスト読み込みメソッドとして動作します。

Kernel.#open と同様 path の先頭が "|" ならば、"|" に続くコマンドの出力を読み取ります。

[PARAM] path:: ファイル名を表す文字列か "|コマンド名" を指定します。
[PARAM] length:: 読み込む長さを整数で指定します。nil であるか省略した場合には、EOF まで読み込みます。
[PARAM] offset:: 読み込みを始めるオフセットを整数で指定します。
[PARAM] opt:: ファイル path を open する時に使われるオプションを Hash で指定します。
[EXCEPTION] Errno::EXXX:: path のオープン、offset 位置への設定、ファイルの読み込みに失敗した場合に発生します。
[EXCEPTION] ArgumentError:: length が負の場合に発生します。

引数 opt で有効なキーと値は以下のとおりです。キーはいずれも Symbol オブジェクトです。

:encoding: 読み込んだ文字列のエンコーディングを指定します。読み込む長さを指定した場合はこれは無視されます。
:mode: IO.open のモードを指定します。 "r" で始まる文字列である必要があります。
:open_args: IO.open に渡される引数を配列で指定します。

これらの他、 :external_encoding など IO.open のオプション引数が指定できます。

[SEE_ALSO] IO.binread

例:

IO.read(empty_file)             #=> ""
IO.read(empty_file, 1)          #=> nil
IO.read(one_byte_file, 0, 10)   #=> ""
IO.read(one_byte_file, nil, 10) #=> ""
IO.read(one_byte_file, 1, 10)   #=> nil

readlines(path, rs = $/, opts={})

readlines(path, limit, opts={})

readlines(path, rs, limit, opts={})

path で指定されたファイルを全て読み込んで、その各行を要素としてもつ配列を返します。

Kernel.#open と同様 path の先頭が "|" ならば、"|" に続くコマンドの出力を読み取ります。

テキスト読み込みメソッドとして動作します。

limit で最大読み込みバイト数を指定します。ただしマルチバイト文字が途中で切れないように余分に読み込む場合があります。

opts でファイルを開くときのオプションを指定します。エンコーディングなどを指定できます。 File.open と同様なのでそちらを参照してください。

[PARAM] path:: ファイル名を表す文字列か "|コマンド名" を指定します。
[PARAM] rs:: 行の区切りを文字列で指定します。rs に nil を指定すると行区切りなしとみなします。空文字列 "" を指定すると連続する改行を行の区切りとみなします(パラグラフモード)。
[PARAM] limit:: 最大の読み込みバイト数
[PARAM] opts:: ファイルを開くときのオプション引数
[EXCEPTION] Errno::EXXX:: path のオープン、ファイルの読み込みに失敗した場合に発生します。

select(reads, writes = [], excepts = [], timeout = nil) -> [[IO]] | nil

select(2) を実行します。

与えられた入力/出力/例外待ちの IO オブジェクトの中から準備ができたものをそれぞれ配列にして、配列の配列として返します。タイムアウトした時には nil を返します。

Kernel.#select と同じです。

[PARAM] reads:: 入力待ちする IO オブジェクトの配列を渡します。
[PARAM] writes:: 出力待ちする IO オブジェクトの配列を渡します。
[PARAM] excepts:: 例外待ちする IO オブジェクトの配列を渡します。
[PARAM] timeout:: タイムアウトまでの時間を表す数値または nil を指定します。数値で指定したときの単位は秒です。nil を指定した時には IO がどれかひとつレディ状態になるまで待ち続けます。
[EXCEPTION] IOError:: 与えられた IO オブジェクトが閉じられていた時に発生します。
[EXCEPTION] Errno::EXXX:: select(2) に失敗した場合に発生します。

rp, wp = IO.pipe
mesg = "ping "
100.times{
  rs, ws, = IO.select([rp], [wp])
  if r = rs[0]
    ret = r.read(5)
    print ret
    case ret
    when /ping/
      mesg = "pong\n"
    when /pong/
      mesg = "ping "
    end
  end
  if w = ws[0]
    w.write(mesg)
  end
}

sysopen(path, mode = "r", perm = 0666) -> Integer

path で指定されるファイルをオープンし、ファイル記述子を返します。

IO.for_fd などで IO オブジェクトにしない限り、このメソッドでオープンしたファイルをクローズする手段はありません。

[PARAM] path:: ファイル名を表す文字列を指定します。
[PARAM] mode:: モードを文字列か定数の論理和で指定します。Kernel.#open と同じです。
[PARAM] perm:: open(2) の第 3 引数のように、ファイルを生成する場合のファイルのパーミッションを整数で指定します。Kernel.#open と同じです。
[EXCEPTION] Errno::EXXX:: ファイルのオープンに失敗した場合に発生します。

[SEE_ALSO] Kernel.#open

try_convert(obj) -> IO | nil

obj を to_io メソッドによって IO オブジェクトに変換します。変換できなかった場合は nil を返します。

IO.try_convert(STDOUT)     # => STDOUT
IO.try_convert("STDOUT")   # => nil

write(path, string, offset=nil, opt={}) -> Integer

path で指定されるファイルを開き、string を書き込み、閉じます。

offset を指定するとその位置までシークします。

offset を指定しないと、書き込みの末尾でファイルを切り捨てます。

引数最後のハッシュはファイルを開くときに使われます。エンコーディングなどを指定することができます。詳しくは IO.open を見てください。

[PARAM] path:: ファイル名文字列
[PARAM] string:: 書き込む文字列
[PARAM] offset:: 書き込み開始位置
[PARAM] opt:: ファイルを開くときのオプション引数

[SEE_ALSO] IO.binwrite

インスタンスメソッド

self << object -> self

object を出力します。object が文字列でない時にはメソッド to_s を用いて文字列に変換します。

以下のような << の連鎖を使うことができます。

STDOUT << 1 << " is a " << Fixnum << "\n"

[PARAM] object:: 出力したいオブジェクトを与えます。
[EXCEPTION] Errno::EXXX:: 出力に失敗した場合に発生します。

advise(advice, offset=0, len=0) -> nil

posix_fadvise(2) を呼びだし、ファイルへのアクセスパターンをOSに知らせます。

advice には以下のいずれかのシンボルを指定します。

:normal - デフォルト
:sequential - データは前から順にアクセスされる
:random - データはランダムアクセスされる
:willneed - データはこの直後にアクセスされる
:dontneed - データは直後にはアクセスしない
:noreuse - データは一度しかアクセスされない

これらの advice が具体的に何をするのかはプラットフォーム依存です。

ここでいう「データ」は offset と len で特定することができます。 len が 0 ならば、offset からファイル末尾までを指定したことになります。デフォルトでは offset と len がともに 0 なので、ファイル全体を指定したことになります。

posix_fadvise をサポートしていないプラットフォーム上では何もしません。

[PARAM] advice:: アクセスパターンを表すシンボル
[PARAM] offset:: パターンを指定するデータの先頭位置
[PARAM] len:: パターンを指定するデータの長さ
[EXCEPTION] IOError:: ストリームが既に閉じられているときに発生する例外
[EXCEPTION] Errno::EBADF:: ファイルデスクリプタが不正であるときに発生する例外
[EXCEPTION] Errno::EINVAL:: advice が不正
[EXCEPTION] Errno::ESPIPE:: ファイルデスクリプタが FIFO か pipe を指している場合に発生する例外(Linux はこの場合には Errno::EINVAL を発生する)
[EXCEPTION] RangeError:: offset,lenが有効範囲から出ている場合に発生する例外

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

autoclose=(bool)

auto-close フラグを設定します。

フラグが設定されているオブジェクトは close時/GCでのファイナライザ呼出時にファイルデスクリプタを close します。設定されていない場合は close しません。

[PARAM] bool:: 真偽値でフラグを設定します

[SEE_ALSO] IO#autoclose?

f = open("/dev/null")
IO.for_fd(f.fileno)
# ...
f.gets # may cause IOError

f = open("/dev/null")
IO.for_fd(f.fileno).autoclose = true
# ...
f.gets # won't cause IOError

autoclose? -> bool

auto-close フラグを返します。

[SEE_ALSO] IO#autoclose=

binmode -> self

ストリームをバイナリモードにします。MSDOS などバイナリモードの存在する OS でのみ有効です。そうでない場合このメソッドは何もしません。

バイナリモードから通常のモードに戻す方法は再オープンしかありません。

[EXCEPTION] Errno::EXXX:: モードの変更に失敗した場合に発生します。

binmode? -> bool

自身がバイナリモードなら true を返します。そうでない場合、false を返します。

bytes -> Enumerator

自身を 1 バイトずつ整数としてイテレートするような Enumerator オブジェクトを生成して返します。

"hello".bytes.to_a        #=> [104, 101, 108, 108, 111]

each_char {|c| ... } -> self

chars {|c| ... } -> self

each_char -> Enumerator

chars -> Enumerator

self に含まれる文字を一文字つつブロックに渡して評価します。

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

ブロックを省略した場合は各文字について繰り返す Enumerator を返します。

[EXCEPTION] IOError:: self が読み込み用にオープンされていない場合に発生します。

f = File.new("testfile")
f.each_char {|c| print c, ' ' }   #=> #<File:testfile>

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

clone -> IO

dup -> IO

レシーバと同じ IO を参照する新しい IO オブジェクトを返します。参照しているファイル記述子は dup(2) されます。

clone の際に self は一旦 IO#flush されます。フリーズした IO の clone は同様にフリーズされた IO を返しますが、 dup は内容の等しいフリーズされていない IO を返します。

[EXCEPTION] IOError:: 既に close されていた場合に発生します。

close -> nil

入出力ポートをクローズします。

以後このポートに対して入出力を行うと例外 IOError が発生します。ガーベージコレクトの際にはクローズされていない IO ポートはクローズされます。 self がパイプでプロセスにつながっていれば、そのプロセスの終了を待ち合わせます。

[EXCEPTION] Errno::EXXX:: close に失敗した場合に発生します。
[EXCEPTION] IOError:: 既に close されていた場合に発生します。

close_on_exec=(bool)

自身に close-on-exec フラグを設定します。

このフラグをセットすると exec(2) 時にそのファイルデスクリプタを close します。

[SEE_ALSO] fcntl(2)

[PARAM] bool:: 自身の close-on-exec フラグを true か false で指定します。

f = open("/dev/null")
f.close_on_exec = true
system("cat", "/proc/self/fd/#{f.fileno}") # cat: /proc/self/fd/3: No such file or directory
f.closed?                #=> false

[SEE_ALSO] IO#close_on_exec?

close_on_exec? -> bool

自身に close-on-exec フラグが設定されていた場合 true を返します。そうでない場合に false を返します。

f = open("/dev/null")
f.close_on_exec?                 #=> false
f.close_on_exec = true
f.close_on_exec?                 #=> true
f.close_on_exec = false
f.close_on_exec?                 #=> false

[SEE_ALSO] IO#close_on_exec=

close_read -> nil

読み込み用の IO を close します。主にパイプや読み書き両用に作成した IO オブジェクトで使用します。

[EXCEPTION] IOError:: 自身が読み込み用にオープンされていなければ発生します。
[EXCEPTION] Errno::EXXX:: close に失敗した場合に発生します。

close_write -> nil

書き込み用の IO を close します。

[EXCEPTION] IOError:: 自身が書き込み用にオープンされていなければ発生します。
[EXCEPTION] Errno::EXXX:: close に失敗した場合に発生します。

closed? -> bool

ポートがクローズされている時に真を返します。

each_codepoint {|c| ... } -> self

codepoints {|c| ... } -> self

each_codepoint -> Enumerator

codepoints -> Enumerator

IO の各コードポイントに対して繰り返しブロックを呼びだします。

ブロックの引数にはコードポイントを表す整数が渡されます。

ブロックを省略した場合には、Enumerator を返します。

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]

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_byte {|ch| ... } -> self

each_byte -> Enumerator

IO の現在位置から 1 バイトずつ読み込み、それを整数として与え、ブロックを実行します。

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

バイナリ読み込みメソッドとして動作します。

[EXCEPTION] IOError:: 自身が読み込み用にオープンされていなければ発生します。

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_line(rs = $/) {|line| ... } -> self

each_line(limit) {|line| ... } -> self

each_line(rs, limit) {|line| ... } -> self

each_line(rs = $/) -> Enumerator

each_line(limit) -> Enumerator

each_line(rs, limit) -> Enumerator

lines(rs = $/) {|line| ... } -> self

lines(limit) {|line| ... } -> self

lines(rs, limit) {|line| ... } -> self

lines(rs = $/) -> Enumerator

lines(limit) -> Enumerator

lines(rs, limit) -> Enumerator

IO の現在位置から 1 行ずつ文字列として読み込み、それを引数として与えられたブロックを実行します。

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

テキスト読み込みメソッドとして動作します。

limit で最大読み込みバイト数を指定します。ただしマルチバイト文字が途中で切れないように余分に読み込む場合があります。

[PARAM] rs:: 行の区切りを文字列で指定します。rs に nil を指定すると行区切りなしとみなします。空文字列 "" を指定すると連続する改行を行の区切りとみなします(パラグラフモード)。
[PARAM] limit:: 最大の読み込みバイト数
[EXCEPTION] IOError:: 自身が読み込み用にオープンされていなければ発生します。

[SEE_ALSO] $/, IO#gets

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

to_a -> [object]

entries -> [object]

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

eof -> bool

eof? -> bool

ストリームがファイルの終端に達した場合、true を返します。そうでない場合、false を返します。

f = File.new("testfile")
dummy = f.readlines
f.eof   #=> true

自身がパイプやソケットなどのストリームであった場合、相手がデータを送るか close するまでブロックします。

r, w = IO.pipe
Thread.new { sleep 10; w.close }
r.eof?  #=> 10秒ブロックしてから true を返す。

r, w = IO.pipe
Thread.new { sleep 10; w.puts "a" }
r.eof?  #=> 10秒ブロックしてから false を返す。

r, w = IO.pipe
r.eof?  # 永久にブロックします。

eof, eof? は入力バッファにデータを読み込むので、IO#sysread と同時に使うと正常に動作しません。

[EXCEPTION] IOError:: 自身が読み込み用にオープンされていなければ発生します。

external_encoding -> Encoding | nil

IO の外部エンコーディングを返します。外部エンコーディングが指定されていない場合は nil を返します。

fcntl(cmd, arg = 0) -> Integer

IOに対してシステムコール fcntl を実行します。機能の詳細は fcntl(2) を参照してください。 fcntl(2) が返した整数を返します。

[PARAM] cmd:: IO に対するコマンドを、添付ライブラリ fcntl が提供している定数で指定します。
[PARAM] arg:: cmd に対する引数を整数、文字列、booleanのいずれかで指定します。整数の時にはその値を fcntl(2) に渡します。文字列の場合には Array#pack した構造体だとみなして渡します。 arg が nil か false の場合には 0を、true の場合には 1 を渡します。
[EXCEPTION] Errno::EXXX:: fcntl の実行に失敗した場合に発生します。
[EXCEPTION] IOError:: 既に close されている場合に発生します。

fdatasync -> 0 | nil

IO のすべてのバッファされているデータを直ちにディスクに書き込みます。

fdatasync(2) をサポートしていない OS 上では代わりに IO#fsync を呼びだします。

IO#fsync との違いは fdatasync(2) を参照してください。

[EXCEPTION] NotImplementedError:: fdatasync(2) も fsync(2) もサポートされていない OS で発生します。

fileno -> Integer

to_i -> Integer

ファイル記述子を表す整数を返します。

[EXCEPTION] IOError:: 既に close されている場合に発生します。

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

flush -> self

IO ポートの内部バッファをフラッシュします。

[EXCEPTION] IOError:: 自身が書き込み用にオープンされていなければ発生します。
[EXCEPTION] Errno::EXXX:: fflush(3) が失敗した場合に発生します。

fsync -> 0 | nil

書き込み用の IO に対して、システムコール fsync(2) を実行します。IO#flush を行ったあと、(OSレベルで)まだディスクに書き込まれていないメモリ上にあるデータをディスクに書き出します。

成功すれば 0 を返します。 fsync(2) がサポートされていない場合は nil を返します。

[EXCEPTION] Errno::EXXX:: 失敗した場合に発生します。
[EXCEPTION] IOError:: 既に close されている場合に発生します。

getbyte -> Integer | nil

IO から1バイトを読み込み整数として返します。既に EOF に達していれば nil を返します。

f = File.new("testfile")
f.getbyte   #=> 84
f.getbyte   #=> 104

getc -> String | nil

IO ポートから外部エンコーディングに従い 1 文字読み込んで返します。 EOF に到達した時には nil を返します。

テキスト読み込みメソッドとして動作します。 IO#readchar との違いは EOF での振る舞いのみです。

[EXCEPTION] IOError:: 自身が読み込み用にオープンされていなければ発生します。

例:

[SEE_ALSO] IO#readchar

gets(rs = $/) -> String | nil

gets(limit) -> String | nil

gets(rs, limit) -> String | nil

一行読み込んで、読み込みに成功した時にはその文字列を返します。 EOF に到達した時には nil を返します。

テキスト読み込みメソッドとして動作します。読み込んだ文字列を変数 $_ にセットします。 IO#readline との違いは EOF での振る舞いのみです。

limit で最大の読み込みバイト数を指定します。ただしファイルのエンコーディングがマルチバイトエンコーディングである場合には読み込んだ文字列がマルチバイト文字の途中で切れないように数バイト余分に読み込む場合があります。

[PARAM] rs:: 行の区切りを文字列で指定します。rs に nil を指定すると行区切りなしとみなします。空文字列 "" を指定すると連続する改行を行の区切りとみなします(パラグラフモード)。
[PARAM] limit:: 最大の読み込みバイト数
[EXCEPTION] IOError:: 自身が読み込み用にオープンされていなければ発生します。

f = File.new("oneline_file")
f.gets                          #=> "This is line one\n"
$_                              #=> "This is line one\n"
f.gets                          #=> nil
$_                              #=> nil

[SEE_ALSO] $/, IO#readline

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

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"

internal_encoding -> Encoding | nil

IO の内部エンコーディングを返します。内部エンコーディングが指定されていない場合は nil を返します。

ioctl(cmd, arg = 0) -> Integer

IO に対してシステムコール ioctl を実行し、その結果を返します。機能の詳細は ioctl(2) を参照してください。

[PARAM] cmd:: IO に対するコマンドを整数で指定します。どのようなコマンドが使えるかはプラットフォームに依存します。
[PARAM] arg:: cmd に対する引数を指定します。整数の時にはその値を ioctl に渡します。文字列の場合には Array#pack した構造体だとみなして渡します。 arg が nil か false の場合には 0を、true の場合には 1 を渡します。
[EXCEPTION] IOError:: 既に close されている場合に発生します。

isatty -> bool

tty? -> bool

入出力ポートがttyに結合している時、真を返します。そうでない場合 false を返します。

[EXCEPTION] IOError:: 既に close されている場合に発生します。

lineno -> Integer

現在の行番号を整数で返します。実際には IO#gets が呼ばれた回数です。改行以外のセパレータで gets が呼ばれた場合など、実際の行番号と異なる場合があります。

[EXCEPTION] IOError:: 読み込み用にオープンされていなければ発生します。

f = File.new("testfile")
f.lineno                 #=> 0
f.gets                   #=> "This is line one\n"
f.lineno                 #=> 1
f.gets                   #=> "This is line two\n"
f.lineno                 #=> 2

[SEE_ALSO] $.

lineno=(number)

現在の行番号を number にセットします。 $. は次回の読み込みの時に更新されます。

[PARAM] number:: 行番号を整数で指定します。
[EXCEPTION] IOError:: 読み込み用にオープンされていなければ発生します。

f = File.new("testfile")
f.gets                     #=> "This is line one\n"
$.                         #=> 1
f.lineno = 1000
f.lineno                   #=> 1000
$.                         #=> 1
f.gets                     #=> "This is line two\n"
$.                         #=> 1001

[SEE_ALSO] $.

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

pid -> Integer | nil

自身が IO.popen で作られたIOポートなら、子プロセスのプロセス ID を返します。それ以外は nil を返します。

[EXCEPTION] IOError:: 既に close されている場合に発生します。

pos -> Integer

tell -> Integer

ファイルポインタの現在の位置を整数で返します。

[EXCEPTION] IOError:: 既に close されている場合に発生します。

pos=(n)

ファイルポインタを指定位置に移動します。 IO#seek(n, IO::SEEK_SET) と同じです。

[PARAM] n:: 先頭からのオフセットを整数で指定します。
[EXCEPTION] IOError:: 既に close されている場合に発生します。

print(*arg) -> nil

引数を IO ポートに順に出力します。引数を省略した場合は、$_ を出力します。

[PARAM] arg:: Kernel.#print と同じです。
[EXCEPTION] IOError:: 自身が書き込み用にオープンされていなければ発生します。
[EXCEPTION] Errno::EXXX:: 出力に失敗した場合に発生します。

printf(format, *arg) -> nil

C 言語の printf と同じように、format に従い引数を文字列に変換して、self に出力します。

第一引数に IO を指定できないこと、引数を省略できないことを除けば Kernel.#printf と同じです。

[PARAM] format:: Kernel.#printf と同じです。sprintf フォーマットを参照してください。
[PARAM] arg:: Kernel.#printf と同じです。
[EXCEPTION] IOError:: 自身が書き込み用にオープンされていなければ発生します。
[EXCEPTION] Errno::EXXX:: 出力に失敗した場合に発生します。

[SEE_ALSO] Kernel.#printf

putc(ch) -> object

文字 ch を self に出力します。引数の扱いは Kernel.#putc と同じです。詳細はこちらを参照してください。ch を返します。

[PARAM] ch:: 出力したい文字を、文字列か文字コード(整数)で与えます。
[EXCEPTION] IOError:: 自身が書き込み用にオープンされていなければ発生します。
[EXCEPTION] Errno::EXXX:: 出力に失敗した場合に発生します。

[SEE_ALSO] Kernel.#putc

puts(*obj) -> nil

各 obj を self に出力し、それぞれの後に改行を出力します。引数の扱いは Kernel.#puts と同じです。詳細はこちらを参照してください。

[PARAM] obj:: 出力したいオブジェクトを指定します。Kernel.#puts と同じです。
[EXCEPTION] IOError:: 自身が書き込み用にオープンされていなければ発生します。
[EXCEPTION] Errno::EXXX:: 出力に失敗した場合に発生します。

$stdout.puts("this", "is", "a", "test", [1, [nil, 3]])

#=>
this
is
a
test
1
nil
3

[SEE_ALSO] Kernel.#puts

read(length = nil, outbuf = "") -> String | nil

length バイト読み込んで、その文字列を返します。

引数 length が指定された場合はバイナリ読み込みメソッド、そうでない場合はテキスト読み込みメソッドとして動作します。既に EOF に達していれば nil を返します。ただし、length に nil か 0 が指定されている場合は、空文字列 "" を返します。例えば、open(空ファイル) {|f| f.read } は "" となります。

[PARAM] length:: 読み込むサイズを整数で指定します。 nil が指定された場合、EOF までの全てのデータを読み込んで、その文字列を返します。
[PARAM] outbuf:: 出力用のバッファを文字列で指定します。IO#read は読み込んだデータをその文字列オブジェクトに上書きして返します。指定した文字列オブジェクトがあらかじめ length 長の領域であれば、余計なメモリの割当てが行われません。指定した文字列の長さが length と異なる場合、その文字列は一旦 length 長に拡張(あるいは縮小)されたあと、実際に読み込んだデータのサイズになります。
[EXCEPTION] IOError:: 自身が読み込み用にオープンされていなければ発生します。
[EXCEPTION] Errno::EXXX:: データの読み込みに失敗した場合に発生します。
[EXCEPTION] ArgumentError:: length が負の場合に発生します。

第二引数を指定した read の呼び出しでデータが空であった場合 (read が nil を返す場合)、outbuf は空文字列になります。

outbuf = "x" * 20;
io = File.open("/dev/null")
p io.read(10,outbuf)
p outbuf
=> nil
   ""

read_nonblock(maxlen, outbuf = "") -> String

IO をノンブロッキングモードに設定し、その後で read(2) システムコールにより長さ maxlen を上限として読み込み、文字列として返します。 EAGAIN, EINTR などは Errno::EXXX 例外として呼出元に報告されます。

発生した例外がErrno::EAGAIN、 Errno::EWOULDBLOCK である場合は、その例外オブジェクトに IO::WaitReadable が Object#extend されます。

なお、バッファが空でない場合は、read_nonblock はバッファから読み込みます。この場合、read(2) システムコールは呼ばれません。

このメソッドはノンブロッキングモードにする点を除いて IO#readpartial と同じであることに注意してください。

バイナリ読み込みメソッドとして動作します。既に EOF に達していれば EOFError が発生します。ただし、maxlen に 0 が指定されている場合は、空文字列 "" を返します。

[PARAM] maxlen:: 読み込む長さの上限を整数で指定します。
[PARAM] outbuf:: 文字列で指定します。IO#read_nonblock は読み込んだデータを outbuf に破壊的に格納し、返り値は outbuf となります。outbuf は一旦 maxlen 長に拡張(あるいは縮小)されたあと、実際に読み込んだデータのサイズになります。read(2) システムコールが 0 を返した場合は、空文字列になります。
[EXCEPTION] IOError:: 自身が読み込み用にオープンされていなければ発生します。
[EXCEPTION] Errno::EXXX:: read(2) システムコールの結果としてエラーが起きた場合に発生します。
[EXCEPTION] EOFError:: read(2) システムコールが 0 を返した場合に発生します。これは、IO が既に EOF に達していることを意味します。

readbyte -> Integer

IO から1バイトを読み込み整数として返します。既に EOF に達していれば EOFError が発生します。

[EXCEPTION] EOFError:: 既に EOF に達している場合に発生します。

readchar -> String

IO ポートから 1 文字読み込んで返します。 EOF に到達した時には EOFError が発生します。

テキスト読み込みメソッドとして動作します。 IO#getc との違いは EOF での振る舞いのみです。

[EXCEPTION] EOFError:: EOF に到達した時に発生します。
[EXCEPTION] IOError:: 自身が読み込み用にオープンされていなければ発生します。

f = File.new("testfile")
p f.readchar                   #=> "い"
p f.readchar                   #=> "ろ"
p f.readchar                   #=> "は"
f.read
f.readchar                   #=> EOFError

[SEE_ALSO] IO#getc

readline(rs = $/) -> String

readline(limit) -> String

readline(rs, limit) -> String

一行読み込んで、読み込みに成功した時にはその文字列を返します。 EOF に到達した時には EOFError が発生します。

テキスト読み込みメソッドとして動作します。読み込んだ文字列を変数 $_ にセットします。IO#gets との違いは EOF での振る舞いのみです。

limit で最大読み込みバイト数を指定します。ただしマルチバイト文字が途中で切れないように余分に読み込む場合があります。

[PARAM] rs:: 行の区切りを文字列で指定します。rs に nil を指定すると行区切りなしとみなします。空文字列 "" を指定すると連続する改行を行の区切りとみなします(パラグラフモード)。
[PARAM] limit:: 最大の読み込みバイト数
[EXCEPTION] EOFError:: EOF に到達した時に発生します。
[EXCEPTION] IOError:: 自身が読み込み用にオープンされていなければ発生します。

f = File.new("oneline_file")
f.readline                      #=> "This is line one\n"
$_                              #=> "This is line one\n"
f.readline                      #=> EOFError
$_                              #=> nil

[SEE_ALSO] $/, IO#gets

readlines(rs = $/) -> [String]

readlines(limit) -> [String]

readlines(rs = $/, limit) -> [String]

データを全て読み込んで、その各行を要素としてもつ配列を返します。既に EOF に達していれば空配列 [] を返します。

テキスト読み込みメソッドとして動作します。

limit で最大読み込みバイト数を指定します。ただしマルチバイト文字が途中で切れないように余分に読み込む場合があります。

[PARAM] rs:: 行の区切りを文字列で指定します。rs に nil を指定すると行区切りなしとみなします。空文字列 "" を指定すると連続する改行を行の区切りとみなします(パラグラフモード)。
[PARAM] limit:: 最大の読み込みバイト数
[EXCEPTION] IOError:: 自身が読み込み用にオープンされていなければ発生します。

[SEE_ALSO] $/, IO#gets

readpartial(maxlen, outbuf = "") -> String

IO から長さ maxlen を上限として読み込み、文字列として返します。即座に得られるデータが存在しないときにはブロックしてデータの到着を待ちます。即座に得られるデータが 1byte でも存在すればブロックしません。

readpartial はブロックを最小限に抑えることによって、パイプ、ソケット、端末などのストリームに対して適切に動作するよう設計されています。 readpartial がブロックするのは次の全ての条件が満たされたときだけです。

IO オブジェクト内のバッファが空
ストリームにデータが到着していない
ストリームが EOF になっていない

これらの条件が満たされる場合、何らかのデータが到着するか EOF になるまで readpartial はブロックします。

readpartial の結果は以下のようになります。

バッファが空でなければ、そのバッファのデータを読み込んで返します。
ストリームにデータがあれば、ストリームからデータを読み込んで返します。
ストリームが EOF になっていれば、例外 EOFError を発生させます。

例えば、パイプに対しては次のように動作します。

r, w = IO.pipe           #               buffer          pipe content
w << "abc"               #               ""              "abc".
r.readpartial(4096)      #=> "abc"       ""              ""
r.readpartial(4096)      # バッファにもパイプにもデータがないのでブロックする

r, w = IO.pipe           #               buffer          pipe content
w << "abc"               #               ""              "abc"
w.close                  #               ""              "abc" EOF
r.readpartial(4096)      #=> "abc"       ""              EOF
r.readpartial(4096)      # 例外 EOFError 発生

r, w = IO.pipe           #               buffer          pipe content
w << "abc\ndef\n"        #               ""              "abc\ndef\n"
r.gets                   #=> "abc\n"     "def\n"         ""
w << "ghi\n"             #               "def\n"         "ghi\n"
r.readpartial(4096)      #=> "def\n"     ""              "ghi\n"
r.readpartial(4096)      #=> "ghi\n"     ""              ""

なお、readpartial は nonblock フラグに影響されません。つまり、nonblock フラグが設定されていて sysread であれば Errno::EAGAIN になる場合でもブロックします。

また、readpartial の挙動は sysread によく似ています。とくに、バッファが空の場合には同じ挙動を示します。ただし、EAGAIN および EINTR エラーは内部で発生したとしても通知されず、データが到着するまでブロックし続けます。

[PARAM] maxlen:: 読み込む長さの上限を整数で指定します。
[PARAM] outbuf:: 文字列で指定します。IO#readpartial は読み込んだデータを outbuf に破壊的に格納し、返り値は outbuf となります。outbuf は一旦 maxlen 長に拡張(あるいは縮小)されたあと、実際に読み込んだデータのサイズになります。IO が既に EOF に達していれば、空文字列になります。
[EXCEPTION] IOError:: 自身が読み込み用にオープンされていなければ発生します。
[EXCEPTION] EOFError:: IO が既に EOF に達していれば発生します。

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 に繋ぎ換えます。

クラスも io に等しくなることに注意してください。 IO#pos, IO#lineno などは指定された io と等しくなります。

[PARAM] io:: 自身を繋ぎ換えたい IO オブジェクトを指定します。
[EXCEPTION] IOError:: 指定された io が close されている場合に発生します。

reopen(path) -> self

reopen(path, mode) -> self

path で指定されたファイルにストリームを繋ぎ換えます。

第二引数を省略したとき self のモードをそのまま引き継ぎます。 IO#pos, IO#lineno などはリセットされます。

[PARAM] path:: パスを表す文字列を指定します。
[PARAM] mode:: パスを開く際のモードを文字列で指定します。
[EXCEPTION] Errno::EXXX:: 失敗した場合に発生します。

[SEE_ALSO] Kernel.#open

reverse_each -> Enumerator

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

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

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

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

rewind -> 0

ファイルポインタを先頭に移動します。IO#lineno は 0 になります。

[EXCEPTION] IOError:: 既に close されている場合に発生します。

f = File.new("testfile")
f.readline               #=> "This is line one\n"
f.rewind                 #=> 0
f.lineno                 #=> 0
f.readline               #=> "This is line one\n"

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

ファイルポインタを whence の位置から offset だけ移動させます。 offset 位置への移動が成功すれば 0 を返します。

[PARAM] offset:: ファイルポインタを移動させるオフセットを整数で指定します。
[PARAM] whence:: 値は以下のいずれかです。

IO::SEEK_SET: ファイルの先頭から (デフォルト)
IO::SEEK_CUR: 現在のファイルポインタから
IO::SEEK_END: ファイルの末尾から

[EXCEPTION] Errno::EXXX:: ファイルポインタの移動に失敗した場合に発生します。
[EXCEPTION] IOError:: 既に close されていた場合に発生します。

f = File.new("testfile")
f.seek(-13, IO::SEEK_END)   #=> 0
f.readline                  #=> "And so on...\n"

[SEE_ALSO] IO#sysseek

set_encoding(enc_str, opt={}) -> self

set_encoding(ext_enc) -> self

set_encoding(ext_enc, int_enc, opt={}) -> self

IO のエンコーディングを設定します。

引数が "A:B" のようにコロンで区切られた文字列の場合は、 A を外部エンコーディング、 B を内部エンコーディングに指定します。

引数が一つで、上のような形式でない場合には、それが外部エンコーディングと見なされます。

引数が2つの場合はそのそれぞれを外部エンコーディング、内部エンコーディングに設定します。

opt のハッシュで外部エンコーディングを内部エンコーディングに変換する際のオプションを指定します。詳しくは String#encode を参照してください。

[PARAM] enc_str:: エンコーディングを表す文字列を指定します。"A:B" のようにコロンで区切られた文字列を指定した場合 A が外部エンコーディング、B が内部エンコーディングを表します。
[PARAM] ext_enc:: 外部エンコーディングを表す文字列か Encoding オブジェクトを指定します。
[PARAM] int_enc:: 内部エンコーディングを表す文字列か Encoding オブジェクトを指定します。
[PARAM] opt:: エンコーディング変換のオプション

例:

io = File.open(file)
io.set_encoding("ASCII-8BIT", "EUC-JP")

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

ファイルのステータスを含む File::Stat オブジェクトを生成して返します。

[EXCEPTION] Errno::EXXX:: ステータスの読み込みに失敗した場合に発生します。
[EXCEPTION] IOError:: 既に close されていた場合に発生します。

[SEE_ALSO] File#lstat, File.stat, File.lstat

sync -> bool

現在の出力が同期モードならば true を返します。そうでない場合は false を返します。

[EXCEPTION] IOError:: 既に close されていた場合に発生します。

sync=(newstate)

自身を同期モードに設定すると、出力関数の呼出毎にバッファがフラッシュされます。

[PARAM] newstate:: 自身を同期モードに設定するかを boolean で指定します。
[EXCEPTION] IOError:: 既に close されていた場合に発生します。

sysread(maxlen, outbuf = "") -> String

read(2) を用いて入力を行ない、入力されたデータを含む文字列を返します。stdio を経由しないので gets や getc や eof? などと混用すると思わぬ動作をすることがあります。

[PARAM] maxlen:: 入力のサイズを整数で指定します。
[PARAM] outbuf:: 出力用のバッファを文字列で指定します。IO#sysread は読み込んだデータをその文字列オブジェクトに上書きして返します。指定した文字列オブジェクトがあらかじめ maxlen 長の領域であれば、余計なメモリの割当てが行われません。指定した文字列の長さが maxlen と異なる場合、その文字列は一旦 maxlen 長に拡張(あるいは縮小)されたあと、実際に読み込んだデータのサイズになります。
[EXCEPTION] IOError:: 自身が読み込み用にオープンされていなければ発生します。
[EXCEPTION] EOFError:: IO が既に EOF に達していれば発生します。
[EXCEPTION] Errno::EXXX:: データの読み込みに失敗した場合に発生します。

第二引数を指定した sysread の呼び出しでデータが空であった場合(sysread が例外 EOFError を発生させる場合)、 outbuf は空文字列になります。

outbuf = "x" * 20;
io = File.open("/dev/null")
p((io.sysread(10,outbuf) rescue nil))
p outbuf
=> nil
   ""

sysseek(offset, whence = IO::SEEK_SET) -> Integer

lseek(2) と同じです。IO#seek では、 IO#sysread, IO#syswrite と併用すると正しく動作しないので代わりにこのメソッドを使います。位置 offset への移動が成功すれば移動した位置(ファイル先頭からのオフセット)を返します。

書き込み用にバッファリングされた IO に対して実行すると警告が出ます。

File.open("/dev/zero") {|f|
  buf = f.read(3)
  f.sysseek(0)
}
# => -:3:in `sysseek': sysseek for buffered IO (IOError)

File.open("/dev/null", "w") {|f|
  f.print "foo"
  f.sysseek(0)
}
# => -:3: warning: sysseek for buffered IO

[PARAM] offset:: ファイルポインタを移動させるオフセットを整数で指定します。
[PARAM] whence:: 値は以下のいずれかです。

IO::SEEK_SET: ファイルの先頭から (デフォルト)
IO::SEEK_CUR: 現在のファイルポインタから
IO::SEEK_END: ファイルの末尾から

[EXCEPTION] IOError:: 読み込み用にバッファリングされた IO に対して実行すると発生します。既に close されていた場合にも発生します。
[EXCEPTION] Errno::EXXX:: 移動に失敗した場合に発生します。

[SEE_ALSO] IO#seek

syswrite(string) -> Integer

write(2) を用いて string を出力します。 string が文字列でなければ to_s による文字列化を試みます。実際に出力できたバイト数を返します。

stdio を経由しないので他の出力メソッドと混用すると思わぬ動作をすることがあります。

[PARAM] string:: 自身に書き込みたい文字列を指定します。
[EXCEPTION] IOError:: 自身が書き込み用にオープンされていなければ発生します。
[EXCEPTION] Errno::EXXX:: 出力に失敗した場合に発生します。

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

self を返します。

ungetbyte(c) -> nil

指定したバイト列を書き戻します。

2バイト以上の書き戻しは仕様として保証しません。

このメソッドはバッファを経由しない読み出し(IO#sysread など) には影響しません。

[PARAM] c:: バイト列(文字列)、もしくは0から255までの整数

例:

f = File.new("testfile")   #=> #<File:testfile>
b = f.getbyte              #=> 0x38
f.ungetbyte(b)             #=> nil
f.getbyte                  #=> 0x38

ungetc(char) -> nil

指定された char を読み戻します。

[PARAM] char:: 読み戻したい1文字かそのコードポイントを指定します。
[EXCEPTION] IOError:: 読み戻しに失敗した場合に発生します。また、自身が読み込み用にオープンされていない時、自身がまだ一度も read されていない時に発生します。

write(str) -> Integer

IOポートに対して str を出力します。str が文字列でなければ to_s による文字列化を試みます。実際に出力できたバイト数を返します。

IO#syswrite を除く全ての出力メソッドは、最終的に "write" という名のメソッドを呼び出すので、このメソッドを置き換えることで出力関数の挙動を変更することができます。

[PARAM] str:: 自身に書き込みたい文字列を指定します。
[EXCEPTION] IOError:: 自身が書き込み用にオープンされていなければ発生します。
[EXCEPTION] Errno::EXXX:: 出力に失敗した場合に発生します。

write_nonblock(string) -> Integer

IO をノンブロッキングモードに設定し、string を write(2) システムコールで書き出します。

write(2) が成功した場合、書き込んだ長さを返します。 EAGAIN, EINTR などは例外 Errno::EXXX として呼出元に報告されます。書き込んだバイト数(つまり返り値)は String#bytesize の値より小さい可能性があります。

発生した例外がErrno::EAGAIN、 Errno::EWOULDBLOCK である場合は、その例外オブジェクトに IO::WaitWritable が Object#extend されます。よって IO::WaitWritable を write_nonblock のリトライが必要かの判定に用いることができます。

[PARAM] string:: 自身に書き込みたい文字列を指定します。
[EXCEPTION] IOError:: 自身が書き込み用にオープンされていなければ発生します。
[EXCEPTION] Errno::EXXX:: write(2) が失敗した場合に発生します。

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

定数

SEEK_CUR -> Fixnum: IO#seek を参照してください。
SEEK_END -> Fixnum: IO#seek を参照してください。
SEEK_SET -> Fixnum: IO#seek を参照してください。

class IO

Ruby 1.9.3 リファレンスマニュアル