From 04284b7663e40098e688c15b5b206a47760588dc Mon Sep 17 00:00:00 2001 From: nobu Date: Tue, 15 Mar 2005 14:52:59 +0000 Subject: * ext/stringio/stringio.c: add rdoc. git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@8153 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- ext/stringio/stringio.c | 284 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 284 insertions(+) (limited to 'ext/stringio') diff --git a/ext/stringio/stringio.c b/ext/stringio/stringio.c index 4426786c41..256720baff 100644 --- a/ext/stringio/stringio.c +++ b/ext/stringio/stringio.c @@ -185,6 +185,13 @@ strio_s_allocate(klass) return Data_Wrap_Struct(klass, strio_mark, strio_free, 0); } +/* + * call-seq: StringIO.open(string=""[, mode]) {|strio| ...} + * + * Equivalent to StringIO.new except that when it is called with a block, it + * yields with the new instance and closes it, and returns the result which + * returned from the block. + */ static VALUE strio_s_open(argc, argv, klass) int argc; @@ -196,6 +203,11 @@ strio_s_open(argc, argv, klass) return rb_ensure(rb_yield, obj, strio_finalize, obj); } +/* + * call-seq: StringIO.new(string=""[, mode]) + * + * Creates new StringIO instance from with _string_ and _mode_. + */ static VALUE strio_initialize(argc, argv, self) int argc; @@ -254,6 +266,9 @@ strio_finalize(self) return self; } +/* + * Returns +false+. Just for compatibility to IO. + */ static VALUE strio_false(self) VALUE self; @@ -262,6 +277,9 @@ strio_false(self) return Qfalse; } +/* + * Returns +nil+. Just for compatibility to IO. + */ static VALUE strio_nil(self) VALUE self; @@ -270,6 +288,9 @@ strio_nil(self) return Qnil; } +/* + * Returns *strio* itself. Just for compatibility to IO. + */ static VALUE strio_self(self) VALUE self; @@ -278,6 +299,9 @@ strio_self(self) return self; } +/* + * Returns 0. Just for compatibility to IO. + */ static VALUE strio_0(self) VALUE self; @@ -286,6 +310,9 @@ strio_0(self) return INT2FIX(0); } +/* + * Returns the argument unchanged. Just for compatibility to IO. + */ static VALUE strio_first(self, arg) VALUE self, arg; @@ -294,6 +321,9 @@ strio_first(self, arg) return arg; } +/* + * Raises NotImplementedError. + */ static VALUE strio_unimpl(argc, argv, self) int argc; @@ -305,6 +335,11 @@ strio_unimpl(argc, argv, self) return Qnil; /* not reached */ } +/* + * call-seq: strio.string -> string + * + * Returns underlying String object, the subject of IO. + */ static VALUE strio_get_string(self) VALUE self; @@ -312,6 +347,12 @@ strio_get_string(self) return StringIO(self)->string; } +/* + * call-seq: + * strio.string = string -> string + * + * Changes underlying String object, the subject of IO. + */ static VALUE strio_set_string(self, string) VALUE self, string; @@ -329,6 +370,13 @@ strio_set_string(self, string) return ptr->string = string; } +/* + * call-seq: + * strio.close -> nil + * + * Closes strio. The *strio* is unavailable for any further data + * operations; an +IOError+ is raised if such an attempt is made. + */ static VALUE strio_close(self) VALUE self; @@ -342,6 +390,13 @@ strio_close(self) return Qnil; } +/* + * call-seq: + * strio.close_read -> nil + * + * Closes the read end of a StringIO. Will raise an +IOError+ if the + * *strio* is not readable. + */ static VALUE strio_close_read(self) VALUE self; @@ -356,6 +411,13 @@ strio_close_read(self) return Qnil; } +/* + * call-seq: + * strio.close_write -> nil + * + * Closes the write end of a StringIO. Will raise an +IOError+ if the + * *strio* is not writeable. + */ static VALUE strio_close_write(self) VALUE self; @@ -370,6 +432,12 @@ strio_close_write(self) return Qnil; } +/* + * call-seq: + * strio.closed? -> true or false + * + * Returns +true+ if *strio* is completely closed, +false+ otherwise. + */ static VALUE strio_closed(self) VALUE self; @@ -379,6 +447,12 @@ strio_closed(self) return Qtrue; } +/* + * call-seq: + * strio.closed_read? -> true or false + * + * Returns +true+ if *strio* is not readable, +false+ otherwise. + */ static VALUE strio_closed_read(self) VALUE self; @@ -388,6 +462,12 @@ strio_closed_read(self) return Qtrue; } +/* + * call-seq: + * strio.closed_write? -> true or false + * + * Returns +true+ if *strio* is not writable, +false+ otherwise. + */ static VALUE strio_closed_write(self) VALUE self; @@ -397,6 +477,14 @@ strio_closed_write(self) return Qtrue; } +/* + * call-seq: + * strio.eof -> true or false + * strio.eof? -> true or false + * + * Returns true if *strio* is at end of file. The stringio must be + * opened for reading or an +IOError+ will be raised. + */ static VALUE strio_eof(self) VALUE self; @@ -406,6 +494,7 @@ strio_eof(self) return Qtrue; } +/* :nodoc: */ static VALUE strio_copy(copy, orig) VALUE copy, orig; @@ -424,6 +513,16 @@ strio_copy(copy, orig) return copy; } +/* + * call-seq: + * strio.lineno -> integer + * + * Returns the current line number in *strio*. The stringio must be + * opened for reading. +lineno+ counts the number of times +gets+ is + * called, rather than the number of newlines encountered. The two + * values will differ if +gets+ is called with a separator other than + * newline. See also the $. variable. + */ static VALUE strio_get_lineno(self) VALUE self; @@ -431,6 +530,13 @@ strio_get_lineno(self) return LONG2NUM(StringIO(self)->lineno); } +/* + * call-seq: + * strio.lineno = integer -> integer + * + * Manually sets the current line number to the given value. + * $. is updated only on the next read. + */ static VALUE strio_set_lineno(self, lineno) VALUE self, lineno; @@ -439,14 +545,26 @@ strio_set_lineno(self, lineno) return lineno; } +/* call-seq: strio.binmode -> true */ #define strio_binmode strio_self +/* call-seq: strio.fcntl */ #define strio_fcntl strio_unimpl +/* call-seq: strio.flush -> strio */ #define strio_flush strio_self +/* call-seq: strio.fsync -> 0 */ #define strio_fsync strio_0 +/* + * call-seq: + * strio.reopen(other_StrIO) -> strio + * strio.reopen(string, mode) -> strio + * + * Reinitializes *strio* with the given other_StrIO or _string_ + * and _mode_ (see StringIO#new). + */ static VALUE strio_reopen(argc, argv, self) int argc; @@ -460,6 +578,13 @@ strio_reopen(argc, argv, self) return strio_initialize(argc, argv, self); } +/* + * call-seq: + * strio.pos -> integer + * strio.tell -> integer + * + * Returns the current offset (in bytes) of *strio*. + */ static VALUE strio_get_pos(self) VALUE self; @@ -467,6 +592,12 @@ strio_get_pos(self) return LONG2NUM(StringIO(self)->pos); } +/* + * call-seq: + * strio.pos = integer -> integer + * + * Seeks to the given position (in bytes) in *strio*. + */ static VALUE strio_set_pos(self, pos) VALUE self; @@ -481,6 +612,13 @@ strio_set_pos(self, pos) return pos; } +/* + * call-seq: + * strio.rewind -> 0 + * + * Positions *strio* to the beginning of input, resetting + * +lineno+ to zero. + */ static VALUE strio_rewind(self) VALUE self; @@ -491,6 +629,13 @@ strio_rewind(self) return INT2FIX(0); } +/* + * call-seq: + * strio.seek(amount, whence=SEEK_SET) -> 0 + * + * Seeks to a given offset _amount_ in the stream according to + * the value of _whence_ (see IO#seek). + */ static VALUE strio_seek(argc, argv, self) int argc; @@ -522,6 +667,12 @@ strio_seek(argc, argv, self) return INT2FIX(0); } +/* + * call-seq: + * strio.sync -> true + * + * Returns +true+ always. + */ static VALUE strio_get_sync(self) VALUE self; @@ -530,10 +681,17 @@ strio_get_sync(self) return Qtrue; } +/* call-seq: strio.sync = boolean -> boolean */ #define strio_set_sync strio_first #define strio_tell strio_get_pos +/* + * call-seq: + * strio.each_byte {|byte| block } -> strio + * + * See IO#each_byte. + */ static VALUE strio_each_byte(self) VALUE self; @@ -546,6 +704,12 @@ strio_each_byte(self) return Qnil; } +/* + * call-seq: + * strio.getc -> fixnum or nil + * + * See IO#getc. + */ static VALUE strio_getc(self) VALUE self; @@ -578,6 +742,16 @@ strio_extend(ptr, pos, len) } } +/* + * call-seq: + * strio.ungetc(integer) -> nil + * + * Pushes back one character (passed as a parameter) onto *strio* + * such that a subsequent buffered read will return it. Pushing back + * behind the beginning of the buffer string is not possible. Nothing + * will be done if such an attempt is made. + * In other case, there is no limitation for multiple pushbacks. + */ static VALUE strio_ungetc(self, ch) VALUE self, ch; @@ -599,6 +773,12 @@ strio_ungetc(self, ch) return Qnil; } +/* + * call-seq: + * strio.readchar => fixnum + * + * See IO#readchar. + */ static VALUE strio_readchar(self) VALUE self; @@ -724,6 +904,12 @@ strio_getline(argc, argv, ptr) return str; } +/* + * call-seq: + * strio.gets(sep_string=$/) -> string or nil + * + * See IO#gets. + */ static VALUE strio_gets(argc, argv, self) int argc; @@ -736,6 +922,12 @@ strio_gets(argc, argv, self) return str; } +/* + * call-seq: + * strio.readline(sep_string=$/) -> string + * + * See IO#readline. + */ static VALUE strio_readline(argc, argv, self) int argc; @@ -747,6 +939,13 @@ strio_readline(argc, argv, self) return line; } +/* + * call-seq: + * strio.each(sep_string=$/) {|line| block } => strio + * strio.each_line(sep_string=$/) {|line| block } => strio + * + * See IO#each. + */ static VALUE strio_each(argc, argv, self) int argc; @@ -762,6 +961,12 @@ strio_each(argc, argv, self) return self; } +/* + * call-seq: + * strio.readlines(sep_string=$/) => array + * + * See IO#readlines. + */ static VALUE strio_readlines(argc, argv, self) int argc; @@ -776,6 +981,16 @@ strio_readlines(argc, argv, self) return ary; } +/* + * call-seq: + * strio.write(string) => integer + * strio.syswrite(string) => integer + * + * Appends the given string to the underlying buffer string of *strio*. + * The stream must be opened for writing. If the argument is not a + * string, it will be converted to a string using to_s. + * Returns the number of bytes written. See IO#write. + */ static VALUE strio_write(self, str) VALUE self, str; @@ -804,12 +1019,37 @@ strio_write(self, str) return LONG2NUM(len); } +/* + * call-seq: + * strio << obj => strio + * + * See IO#<<. + */ #define strio_addstr rb_io_addstr +/* + * call-seq: + * strio.print() => nil + * strio.print(obj, ...) => nil + * + * See IO#print. + */ #define strio_print rb_io_print +/* + * call-seq: + * strio.printf(format_string [, obj, ...] ) => nil + * + * See IO#printf. + */ #define strio_printf rb_io_printf +/* + * call-seq: + * strio.putc(obj) => obj + * + * See IO#putc. + */ static VALUE strio_putc(self, ch) VALUE self, ch; @@ -829,8 +1069,20 @@ strio_putc(self, ch) return ch; } +/* + * call-seq: + * strio.puts(obj, ...) => nil + * + * See IO#puts. + */ #define strio_puts rb_io_puts +/* + * call-seq: + * strio.read([length [, buffer]]) => string, buffer, or nil + * + * See IO#read. + */ static VALUE strio_read(argc, argv, self) int argc; @@ -897,6 +1149,13 @@ strio_read(argc, argv, self) return str; } +/* + * call-seq: + * strio.sysread(integer[, outbuf]) => string + * + * Similar to #read, but raises +EOFError+ at end of string instead of + * returning +nil+, as well as IO#sysread does. + */ static VALUE strio_sysread(argc, argv, self) int argc; @@ -912,14 +1171,29 @@ strio_sysread(argc, argv, self) #define strio_syswrite strio_write +/* call-seq: strio.path -> nil */ #define strio_path strio_nil +/* + * call-seq: + * strio.isatty -> nil + * strio.tty? -> nil + * + */ #define strio_isatty strio_false +/* call-seq: strio.pid -> nil */ #define strio_pid strio_nil +/* call-seq: strio.fileno -> nil */ #define strio_fileno strio_nil +/* + * call-seq: + * strio.size => integer + * + * Returns the size of the buffer string. + */ static VALUE strio_size(self) VALUE self; @@ -931,6 +1205,13 @@ strio_size(self) return ULONG2NUM(RSTRING(string)->len); } +/* + * call-seq: + * strio.truncate(integer) => 0 + * + * Truncates the buffer string to at most _integer_ bytes. The *strio* + * must be opened for writing. + */ static VALUE strio_truncate(self, len) VALUE self, len; @@ -948,6 +1229,9 @@ strio_truncate(self, len) return len; } +/* + * Pseudo I/O on String object. + */ void Init_stringio() { -- cgit v1.2.3