diff --git a/doc/stringio/getc.rdoc b/doc/stringio/getc.rdoc new file mode 100644 index 00000000..c021789c --- /dev/null +++ b/doc/stringio/getc.rdoc @@ -0,0 +1,34 @@ +Reads and returns the next character (or byte; see below) from the stream: + + strio = StringIO.new('foo') + strio.getc # => "f" + strio.getc # => "o" + strio.getc # => "o" + +Returns +nil+ if at end-of-stream: + + strio.eof? # => true + strio.getc # => nil + +Returns characters, not bytes: + + strio = StringIO.new('тест') + strio.getc # => "т" + strio.getc # => "е" + + strio = StringIO.new('こんにちは') + strio.getc # => "こ" + strio.getc # => "ん" + +In each of the examples above, the stream is positioned at the beginning of a character; +in other cases that need not be true: + + strio = StringIO.new('こんにちは') # Five 3-byte characters. + strio.pos = 3 # => 3 # At beginning of second character; returns character. + strio.getc # => "ん" + strio.pos = 4 # => 4 # At second byte of second character; returns byte. + strio.getc # => "\x82" + strio.pos = 5 # => 5 # At third byte of second character; returns byte. + strio.getc # => "\x93" + +Related: StringIO.getbyte. diff --git a/ext/stringio/stringio.c b/ext/stringio/stringio.c index 874a3a1b..320537f3 100644 --- a/ext/stringio/stringio.c +++ b/ext/stringio/stringio.c @@ -956,10 +956,10 @@ strio_each_byte(VALUE self) /* * call-seq: - * getc -> character or nil + * getc -> character, byte, or nil + * + * :include: stringio/getc.rdoc * - * Reads and returns the next character from the stream; - * see {Character IO}[rdoc-ref:IO@Character+IO]. */ static VALUE strio_getc(VALUE self)