Ruby 2.5.0 リファレンスマニュアル > ライブラリ一覧 > 組み込みライブラリ > IOクラス
クラス・モジュールの継承リスト: IO < Enumerable < File::Constants < Object < Kernel < BasicObject
基本的な入出力機能のためのクラスです。
File::Constants は、File から 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 からテキスト読み込みメソッドによって読み込まれた文字列のエンコーディングは Encoding.default_external に設定されます。このとき実際の文字エンコーディングは検査されず、変換もされません。
IO からテキスト読み込みメソッドによって読み込まれた文字列のエンコーディングは外部エンコーディングに設定されます。このとき実際の文字エンコーディングは検査されず、変換もされません。
IO へ書き込まれる文字列は外部エンコーディングへと変換されます。外部エンコーディングへの変換方法が分からない場合は例外が発生します。
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 です。
Windows の IO にはテキストモードとバイナリモードという2種類のモードが存在します。これらのモードは上で説明した IO のエンコーディングとは独立です。改行の変換にしか影響しません。
空ファイルや 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 通常どおり
定義 | 説明 | |
---|---|---|
self << object -> self
|
object を出力します。object が文字列でない時にはメソッド to_s を用いて文字列に変換します。 |
|
advise(advice, offset=0, len=0) -> nil
|
posix_fadvise(2) を呼びだし、ファイルへのアクセスパターンをOSに知らせます。 |
|
autoclose=(bool)
|
auto-close フラグを設定します。 |
|
autoclose? -> bool
|
auto-close フラグを返します。 |
|
binmode -> self
|
ストリームをバイナリモードにします。MSDOS などバイナリモードの存在する OS でのみ有効です。そうでない場合このメソッドは何もしません。 |
|
binmode? -> bool
|
自身がバイナリモードなら true を返します。そうでない場合、false を返します。 |
|
bytes {|ch| ... } -> self
|
このメソッドは obsolete です。代わりに IO#each_byte を使用してください。使用すると警告メッセージが表示されます。 |
|
chars {|c| ... } -> self
|
このメソッドは obsolete です。代わりに IO#each_char を使用してください。 |
|
clone -> IO
|
レシーバと同じ IO を参照する新しい IO オブジェクトを返します。参照しているファイル記述子は dup(2) されます。 |
|
close -> nil
|
入出力ポートをクローズします。 |
|
close_on_exec=(bool)
|
自身に close-on-exec フラグを設定します。 |
|
close_on_exec? -> bool
|
自身に close-on-exec フラグが設定されていた場合 true を返します。そうでない場合に false を返します。 |
|
close_read -> nil
|
読み込み用の IO を close します。主にパイプや読み書き両用に作成した IO オブジェクトで使用します。 |
|
close_write -> nil
|
書き込み用の IO を close します。 |
|
closed? -> bool
|
self が完全に(読み込み用と書き込み用の両方が)クローズされている場合に true を返します。そうでない場合は false を返します。 |
|
codepoints {|c| ... } -> self
|
このメソッドは obsolete です。代わりに IO#each_codepoint を使用してください。 |
|
each(rs = $/, chomp: false) {|line| ... } -> self
|
IO の現在位置から 1 行ずつ文字列として読み込み、それを引数として与えられたブロックを実行します。 |
|
each_byte {|ch| ... } -> self
|
IO の現在位置から 1 バイトずつ読み込み、それを整数として与え、ブロックを実行します。 |
|
each_char {|c| ... } -> self
|
self に含まれる文字を一文字ずつブロックに渡して評価します。 |
|
each_codepoint {|c| ... } -> self
|
IO の各コードポイントに対して繰り返しブロックを呼びだします。 |
|
eof -> bool
|
ストリームがファイルの終端に達した場合、true を返します。そうでない場合、false を返します。 |
|
external_encoding -> Encoding | nil
|
IO の外部エンコーディングを返します。外部エンコーディングが指定されていない場合は nil を返します。ただし読み込み専用モードの場合は Encoding.default_external になります。 |
|
fcntl(cmd, arg = 0) -> Integer
|
IOに対してシステムコール fcntl を実行します。機能の詳細は fcntl(2) を参照してください。 fcntl(2) が返した整数を返します。 |
|
fdatasync -> 0
|
IO のすべてのバッファされているデータを直ちにディスクに書き込みます。 |
|
fileno -> Integer
|
ファイル記述子を表す整数を返します。 |
|
flush -> self
|
IO ポートの内部バッファをフラッシュします。 |
|
fsync -> 0
|
書き込み用の IO に対して、システムコール fsync(2) を実行します。IO#flush を行ったあと、(OSレベルで)まだディスクに書き込まれていないメモリ上にあるデータをディスクに書き出します。 |
|
getbyte -> Integer | nil
|
IO から1バイトを読み込み整数として返します。既に EOF に達していれば nil を返します。 |
|
getc -> String | nil
|
IO ポートから外部エンコーディングに従い 1 文字読み込んで返します。 EOF に到達した時には nil を返します。 |
|
gets(rs = $/, chomp: false) -> String | nil
|
一行読み込んで、読み込みに成功した時にはその文字列を返します。 EOF に到達した時には nil を返します。 |
|
internal_encoding -> Encoding | nil
|
IO の内部エンコーディングを返します。内部エンコーディングが指定されていない場合は nil を返します。 |
|
ioctl(cmd, arg = 0) -> Integer
|
IO に対してシステムコール ioctl を実行し、その結果を返します。機能の詳細は ioctl(2) を参照してください。 |
|
isatty -> bool
|
入出力ポートがttyに結合している時、真を返します。そうでない場合 false を返します。 |
|
lineno -> Integer
|
現在の行番号を整数で返します。実際には IO#gets が呼ばれた回数です。改行以外のセパレータで gets が呼ばれた場合など、実際の行番号と異なる場合があります。 |
|
lineno=(number)
|
現在の行番号を number にセットします。 $. は次回の読み込みの時に更新されます。 |
|
lines(rs = $/) {|line| ... } -> self
|
このメソッドは obsolete です。代わりに IO#each_line を使用してください。 |
|
pid -> Integer | nil
|
自身が IO.popen で作られたIOポートなら、子プロセスのプロセス ID を返します。それ以外は nil を返します。 |
|
pos -> Integer
|
ファイルポインタの現在の位置を整数で返します。 |
|
pos=(n)
|
ファイルポインタを指定位置に移動します。 IO#seek(n, IO::SEEK_SET) と同じです。 |
|
pread(maxlen, offset, outbuf = "") -> string
|
preadシステムコールを使ってファイルポインタを変更せずに、また現在のファイルポインタに依存せずにmaxlenバイト読み込みます。 |
|
print(*arg) -> nil
|
引数を IO ポートに順に出力します。引数を省略した場合は、$_ を出力します。 |
|
printf(format, *arg) -> nil
|
C 言語の printf と同じように、format に従い引数を文字列に変換して、self に出力します。 |
|
putc(ch) -> object
|
文字 ch を self に出力します。引数の扱いは Kernel.#putc と同じです。詳細はこちらを参照してください。ch を返します。 |
|
puts(*obj) -> nil
|
各 obj を self に出力し、それぞれの後に改行を出力します。引数の扱いは Kernel.#puts と同じです。詳細はこちらを参照してください。 |
|
pwrite(string, offset) -> Integer
|
stringをoffsetの位置にpwrite()システムコールを使って書き込みます。 |
|
read(length = nil, outbuf = "") -> String | nil
|
length バイト読み込んで、その文字列を返します。 |
|
read_nonblock(maxlen, outbuf = nil, exception: true) -> String | Symbol | nil
|
IO をノンブロッキングモードに設定し、その後で read(2) システムコールにより長さ maxlen を上限として読み込み、文字列として返します。 EAGAIN, EINTR などは Errno::EXXX 例外として呼出元に報告されます。 |
|
readbyte -> Integer
|
IO から1バイトを読み込み整数として返します。既に EOF に達していれば EOFError が発生します。 |
|
readchar -> String
|
IO ポートから 1 文字読み込んで返します。 EOF に到達した時には EOFError が発生します。 |
|
readline(rs = $/, chomp: false) -> String
|
一行読み込んで、読み込みに成功した時にはその文字列を返します。 EOF に到達した時には EOFError が発生します。 |
|
readlines(rs = $/, chomp: false) -> [String]
|
データを全て読み込んで、その各行を要素としてもつ配列を返します。既に EOF に達していれば空配列 [] を返します。 |
|
readpartial(maxlen, outbuf = "") -> String
|
IO から長さ maxlen を上限として読み込み、文字列として返します。即座に得られるデータが存在しないときにはブロックしてデータの到着を待ちます。即座に得られるデータが 1byte でも存在すればブロックしません。 |
|
reopen(io) -> self
|
自身を指定された io に繋ぎ換えます。 |
|
reopen(path) -> self
|
path で指定されたファイルにストリームを繋ぎ換えます。 |
|
rewind -> 0
|
ファイルポインタを先頭に移動します。IO#lineno は 0 になります。 |
|
seek(offset, whence = IO::SEEK_SET) -> 0
|
ファイルポインタを whence の位置から offset だけ移動させます。 offset 位置への移動が成功すれば 0 を返します。 |
|
set_encoding(enc_str, **opts) -> self
|
IO のエンコーディングを設定します。 |
|
stat -> File::Stat
|
ファイルのステータスを含む File::Stat オブジェクトを生成して返します。 |
|
sync -> bool
|
現在の出力が同期モードならば true を返します。そうでない場合は false を返します。 |
|
sync=(newstate)
|
自身を同期モードに設定すると、出力関数の呼出毎にバッファがフラッシュされます。 |
|
sysread(maxlen, outbuf = "") -> String
|
read(2) を用いて入力を行ない、入力されたデータを含む文字列を返します。stdio を経由しないので gets や getc や eof? などと混用すると思わぬ動作をすることがあります。 |
|
sysseek(offset, whence = IO::SEEK_SET) -> Integer
|
lseek(2) と同じです。IO#seek では、 IO#sysread, IO#syswrite と併用すると正しく動作しないので代わりにこのメソッドを使います。位置 offset への移動が成功すれば移動した位置(ファイル先頭からのオフセット)を返します。 |
|
syswrite(string) -> Integer
|
write(2) を用いて string を出力します。 string が文字列でなければ to_s による文字列化を試みます。実際に出力できたバイト数を返します。 |
|
to_io -> self
|
self を返します。 |
|
ungetbyte(c) -> nil
|
指定したバイト列を書き戻します。 |
|
ungetc(char) -> nil
|
指定された char を読み戻します。 |
|
write(*str) -> Integer
|
IOポートに対して str を出力します。str が文字列でなければ to_s による文字列化を試みます。実際に出力できたバイト数を返します。 |
|
write_nonblock(string, exception: true) -> Integer | :wait_writable
|
IO をノンブロッキングモードに設定し、string を write(2) システムコールで書き出します。 |
定義 | 説明 | |
---|---|---|
SEEK_CUR -> Integer
|
IO#seek を参照してください。 |
|
SEEK_DATA -> Integer
|
IO#seek を参照してください。 |
|
SEEK_END -> Integer
|
IO#seek を参照してください。 |
|
SEEK_HOLE -> Integer
|
IO#seek を参照してください。 |
|
SEEK_SET -> Integer
|
IO#seek を参照してください。 |
!
!=
__id__
__send__
instance_eval
instance_exec
method_missing
singleton_method_added
singleton_method_removed
singleton_method_undefined
!~
<=>
==
===
=~
_dump
class
define_singleton_method
display
enum_for
eql?
equal?
extend
freeze
frozen?
hash
initialize
initialize_copy
inspect
instance_of?
instance_variable_defined?
instance_variable_get
instance_variable_set
instance_variables
is_a?
itself
marshal_dump
marshal_load
method
methods
nil?
object_id
pretty_inspect
pretty_print
pretty_print_cycle
pretty_print_inspect
pretty_print_instance_variables
private_methods
protected_methods
psych_to_yaml
public_method
public_methods
public_send
remove_instance_variable
respond_to?
respond_to_missing?
send
singleton_class
singleton_method
singleton_methods
taint
tainted?
tap
to_a
to_ary
to_hash
to_int
to_proc
to_regexp
to_s
to_str
trust
untaint
untrust
untrusted?
yield_self
.yaml_tag
::ARGF
::ARGV
::DATA
::ENV
::FALSE
::NIL
::RUBY_COPYRIGHT
::RUBY_DESCRIPTION
::RUBY_ENGINE
::RUBY_ENGINE_VERSION
::RUBY_PATCHLEVEL
::RUBY_PLATFORM
::RUBY_RELEASE_DATE
::RUBY_REVISION
::RUBY_VERSION
::SCRIPT_LINES__
::STDERR
::STDIN
::STDOUT
::TOPLEVEL_BINDING
::TRUE