U:RDoc::NormalModule[iI"
Scanf:EF@0o:RDoc::Markup::Document: @parts[o;;[^o: RDoc::Markup::Paragraph;[I"scanf for Ruby;To: RDoc::Markup::BlankLine S:RDoc::Markup::Heading:
leveli: textI"Description;T@o; ;[I"Rscanf is an implementation of the C function scanf(3), modified as necessary ;TI" for Ruby compatibility.;T@o; ;[ I":the methods provided are String#scanf, IO#scanf, and ;TI"KKernel#scanf. Kernel#scanf is a wrapper around STDIN.scanf. IO#scanf ;TI"Gcan be used on any IO stream, including file handles and sockets. ;TI"8scanf can be called either with or without a block.;T@o; ;[
I"LScanf scans an input string or stream according to a format, as ;TI"Mdescribed below in Conversions, and returns an array of matches between ;TI"Jthe format and the input. The format is defined in a string, and is ;TI"Msimilar (though not identical) to the formats used in Kernel#printf and ;TI"Kernel#sprintf.;T@o; ;[
I"KThe format may contain conversion specifiers, which tell scanf ;TI"Lwhat form (type) each particular matched substring should be converted ;TI"Gto (e.g., decimal integer, floating point number, literal string, ;TI"Ketc.) The matches and conversions take place from left to right, and ;TI"9the conversions themselves are returned as an array.;T@o; ;[ I"KThe format string may also contain characters other than those in the ;TI"Lconversion specifiers. White space (blanks, tabs, or newlines) in the ;TI"Iformat string matches any amount of white space, including none, in ;TI"5the input. Everything else matches only itself.;T@o; ;[
I"JScanning stops, and scanf returns, when any input character fails to ;TI"Ematch the specifications in the format string, or when input is ;TI"Aexhausted, or when everything in the format string has been ;TI"Imatched. All matches found up to the stopping point are returned in ;TI"Fthe return array (or yielded to the block, if a block was given).;T@S; ; i;
I"Basic usage;T@o:RDoc::Markup::Verbatim;[
I"require 'scanf'
;TI"
;TI"K# String#scanf and IO#scanf take a single argument, the format string
;TI"$array = a_string.scanf("%d%s")
;TI"!array = an_io.scanf("%d%s")
;TI"
;TI"%# Kernel#scanf reads from STDIN
;TI"array = scanf("%d%s")
;T: @format0S; ; i;
I"Block usage;T@o; ;[ I"LWhen called with a block, scanf keeps scanning the input, cycling back ;TI"Fto the beginning of the format string, and yields a new array of ;TI"Fconversions to the block every time the format string is matched ;TI"L(including partial matches, but not including complete failures). The ;TI"Gactual return value of scanf when called with a block is an array ;TI"?containing the results of all the executions of the block.;T@o;;[I"%str = "123 abc 456 def 789 ghi"
;TI"=str.scanf("%d%s") { |num,str| [ num * 2, str.upcase ] }
;TI"6# => [[246, "ABC"], [912, "DEF"], [1578, "GHI"]]
;T;0S; ; i;
I"Conversions;T@o; ;[
I"FThe single argument to scanf is a format string, which generally ;TI"Hincludes one or more conversion specifiers. Conversion specifiers ;TI"Jbegin with the percent character ('%') and include information about ;TI"Ewhat scanf should next scan for (string, decimal number, single ;TI"character, etc.).;T@o; ;[
I"JThere may be an optional maximum field width, expressed as a decimal ;TI"Iinteger, between the % and the conversion. If no width is given, a ;TI"Ldefault of `infinity' is used (with the exception of the %c specifier; ;TI"Ksee below). Otherwise, given a field width of n for a given ;TI"Iconversion, at most n characters are scanned in processing ;TI"Gthat conversion. Before conversion begins, most conversions skip ;TI"Fwhite space in the input string; this white space is not counted ;TI" against the field width.;T@o; ;[I"-The following conversions are available.;T@o:RDoc::Markup::List:
@type:
LABEL: @items[o:RDoc::Markup::ListItem: @label[I"%;T;[o; ;[I"IMatches a literal `%'. That is, `%%' in the format string matches a ;TI"Jsingle input `%' character. No conversion is done, and the resulting ;TI"-'%' is not included in the return array.;T@o;;[I"d;T;[o; ;[I"2Matches an optionally signed decimal integer.;T@o;;[I"u;T;[o; ;[I"Same as d.;T@o;;[I"i;T;[o; ;[ I"GMatches an optionally signed integer. The integer is read in base ;TI"I16 if it begins with `0x' or `0X', in base 8 if it begins with `0', ;TI"Hand in base 10 other- wise. Only characters that correspond to the ;TI"base are recognized.;T@o;;[I"o;T;[o; ;[I"0Matches an optionally signed octal integer.;T@o;;[I" x, X;T;[o; ;[I"6Matches an optionally signed hexadecimal integer,;T@o;;[I"a, e, f, g, A, E, F, G;T;[o; ;[I"8Matches an optionally signed floating-point number.;T@o;;[I"s;T;[o; ;[I"PMatches a sequence of non-white-space character. The input string stops at ;TI"Gwhite space or at the maximum field width, whichever occurs first.;T@o;;[I"c;T;[o; ;[ I"MMatches a single character, or a sequence of n characters if a ;TI"Mfield width of n is specified. The usual skip of leading white ;TI"Nspace is suppressed. To skip white space first, use an explicit space in ;TI"the format.;T@o;;[I"[;T;[o; ;[ I"FMatches a nonempty sequence of characters from the specified set ;TI"Gof accepted characters. The usual skip of leading white space is ;TI"Nsuppressed. This bracketed sub-expression is interpreted exactly like a ;TI"Qcharacter class in a Ruby regular expression. (In fact, it is placed as-is ;TI"Pin a regular expression.) The matching against the input string ends with ;TI"Othe appearance of a character not in (or, with a circumflex, in) the set, ;TI"=or when the field width runs out, whichever comes first.;T@S; ; i;
I"Assignment suppression;T@o; ;[ I"PTo require that a particular match occur, but without including the result ;TI"Qin the return array, place the assignment suppression flag, which is ;TI"Mthe star character ('*'), immediately after the leading '%' of a format ;TI"5specifier (just before the field width, if any).;T@S; ; i;
I",scanf for Ruby compared with scanf in C;T@o; ;[I"Qscanf for Ruby is based on the C function scanf(3), but with modifications, ;TI"Idictated mainly by the underlying differences between the languages.;T@S; ; i;
I"'Unimplemented flags and specifiers;T@o;;: BULLET;[o;;0;[o; ;[ I"IThe only flag implemented in scanf for Ruby is '*' (ignore ;TI"Iupcoming conversion). Many of the flags available in C versions of ;TI"Nscanf(3) have to do with the type of upcoming pointer arguments, and are ;TI"meaningless in Ruby.;T@o;;0;[o; ;[I"MThe n specifier (store number of characters consumed so far in ;TI"&next pointer) is not implemented.;T@o;;0;[o; ;[I"IThe p specifier (match a pointer value) is not implemented.;T@S; ; i;
I"Altered specifiers;T@o;;;;[o;;[I"o, u, x, X;T;[o; ;[I"NIn scanf for Ruby, all of these specifiers scan for an optionally signed ;TI"Linteger, rather than for an unsigned integer like their C counterparts.;T@S; ; i;
I"Return values;T@o; ;[ I"Hscanf for Ruby returns an array of successful conversions, whereas ;TI"=scanf(3) returns the number of conversions successfully ;TI"Gcompleted. (See below for more details on scanf for Ruby's return ;TI"
values.);T@S; ; i;
I"Return values;T@o; ;[ I"LWithout a block, scanf returns an array containing all the conversions ;TI"Lit has found. If none are found, scanf will return an empty array. An ;TI"Lunsuccessful match is never ignored, but rather always signals the end ;TI"Mof the scanning operation. If the first unsuccessful match takes place ;TI"Hafter one or more successful matches have already taken place, the ;TI"Ireturned array will contain the results of those successful matches.;T@o; ;[ I"KWith a block scanf returns a 'map'-like array of transformations from ;TI"Lthe block -- that is, an array reflecting what the block did with each ;TI"Eyielded result from the iterative scanf operation. (See "Block ;TI"usage", above.);T@S; ; i;
I"!Current limitations and bugs;T@o; ;[I"IWhen using IO#scanf under Windows, make sure you open your files in ;TI"binary mode:;T@o;;[I"!File.open("filename", "rb")
;T;0o; ;[I":so that scanf can keep track of characters correctly.;T@o; ;[ I"DSupport for character classes is reasonably complete (since it ;TI"Fessentially piggy-backs on Ruby's regular expression handling of ;TI"Lcharacter classes), but users are advised that character class testing ;TI"Ihas not been exhaustive, and that they should exercise some caution ;TI"Din using any of the more complex and/or arcane character class ;TI" idioms.;T@S; ; i;
I"License and copyright;T@o;;: NOTE;[o;;[I"Copyright;T;[o; ;[I"#(c) 2002-2003 David Alan Black;To;;[I" License;T;[o; ;[I";Distributed on the same licensing terms as Ruby itself;T@S; ; i;
I"Warranty disclaimer;T@o; ;[I"JThis software is provided "as is" and without any express or implied ;TI"Jwarranties, including, without limitation, the implied warranties of ;TI":merchantability and fitness for a particular purpose.;T@S; ; i;
I"!Credits and acknowledgements;T@o; ;[I"Kscanf was developed as the major activity of the Austin Ruby Codefest ;TI""(Austin, Texas, August 2002).;T@o;;;;[o;;[I"Principal author;T;[o; ;[I"3David Alan Black (mailto:dblack@superlink.net);To;;[I"Co-author;T;[o; ;[I"1Hal Fulton (mailto:hal9000@hypermetrics.com);To;;[I"Project contributors;T;[o; ;[I""Nolan Darilek, Jason Johnston;T@o; ;[I"3Thanks to Hal Fulton for hosting the Codefest.;T@o; ;[I";Thanks to Matz for suggestions about the class design.;T@o; ;[I"EThanks to Gavin Sinclair for some feedback on the documentation.;T@o; ;[I"IThe text for parts of this document, especially the Description and ;TI"KConversions sections, above, were adapted from the Linux Programmer's ;TI"3Manual manpage for scanf(3), dated 1995-11-01.;T@S; ; i;
I"Bugs and bug reports;T@o; ;[ I"Cscanf for Ruby is based on something of an amalgam of C scanf ;TI"Jimplementations and documentation, rather than on a single canonical ;TI"Jdescription. Suggestions for features and behaviors which appear in ;TI"Hother scanfs, and would be meaningful in Ruby, are welcome, as are ;TI"Lreports of suspicious behaviors and/or bugs. (Please see "Credits and ;TI"4acknowledgements", above, for email addresses.);T:
@fileI"lib/scanf.rb;T:0@omit_headings_from_table_of_contents_below0;0;0[ [ [ [[I"
class;T[[: public[ [:protected[ [: private[ [I"
instance;T[[;[ [;[ [; [ [ [U:RDoc::Context::Section[i 0o;;[ ;0;0[@e@ecRDoc::TopLevel