Gecko [ www.beriskala.com ]

Name	Size	Permission	Date
FormatSpecifier	[ DIR ]	drwxr-xr-x	2026-05-01 04:24
FormatString	[ DIR ]	drwxr-xr-x	2026-05-01 04:24
cdesc-Scanf.ri	10.66 KB	-rw-r--r--	2023-07-26 17:26

Rename

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"Qscanf is an implementation of the C function scanf(3), modified as necessary;TI"for ruby compatibility.;T@o;	;[	I"9the methods provided are String#scanf, IO#scanf, and;TI"JKernel#scanf. Kernel#scanf is a wrapper around STDIN.scanf. IO#scanf;TI"Fcan 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"KScanf scans an input string or stream according to a format, as;TI"Ldescribed below in Conversions, and returns an array of matches between;TI"Ithe format and the input. The format is defined in a string, and is;TI"Lsimilar (though not identical) to the formats used in Kernel#printf and;TI"Kernel#sprintf.;T@o;	;[
I"JThe format may contain conversion specifiers, which tell scanf;TI"Kwhat form (type) each particular matched substring should be converted;TI"Fto (e.g., decimal integer, floating point number, literal string,;TI"Jetc.) The matches and conversions take place from left to right, and;TI"9the conversions themselves are returned as an array.;T@o;	;[	I"JThe format string may also contain characters other than those in the;TI"Kconversion specifiers. White space (blanks, tabs, or newlines) in the;TI"Hformat string matches any amount of white space, including none, in;TI"5the input. Everything else matches only itself.;T@o;	;[
I"IScanning stops, and scanf returns, when any input character fails to;TI"Dmatch the specifications in the format string, or when input is;TI"@exhausted, or when everything in the format string has been;TI"Hmatched. 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'
;FI"
;FI"K# String#scanf and IO#scanf take a single argument, the format string
;FI"$array = a_string.scanf("%d%s")
;FI"!array = an_io.scanf("%d%s")
;FI"
;FI"%# Kernel#scanf reads from STDIN
;FI"array = scanf("%d%s")
;FS;;i;
I"Block usage;T@o;	;[I"KWhen called with a block, scanf keeps scanning the input, cycling back;TI"Eto the beginning of the format string, and yields a new array of;TI"Econversions to the block every time the format string is matched;TI"K(including partial matches, but not including complete failures). The;TI"Factual 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"
;FI"=str.scanf("%d%s") { |num,str| [ num * 2, str.upcase ] }
;FI"6# => [[246, "ABC"], [912, "DEF"], [1578, "GHI"]]
;FS;;i;
I"Conversions;T@o;	;[
I"EThe single argument to scanf is a format string, which generally;TI"Gincludes one or more conversion specifiers. Conversion specifiers;TI"Ibegin with the percent character ('%') and include information about;TI"Dwhat scanf should next scan for (string, decimal number, single;TI"character, etc.).;T@o;	;[
I"IThere may be an optional maximum field width, expressed as a decimal;TI"Hinteger, between the % and the conversion. If no width is given, a;TI"Kdefault of `infinity' is used (with the exception of the %c specifier;;TI"Jsee below). Otherwise, given a field width of n for a given;TI"Hconversion, at most n characters are scanned in processing;TI"Fthat conversion. Before conversion begins, most conversions skip;TI"Ewhite 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:@labelI"%;T;[o;	;[I"HMatches a literal `%'. That is, `%%' in the format string matches a;TI"Isingle 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"FMatches an optionally signed integer. The integer is read in base;TI"H16 if it begins with `0x' or `0X', in base 8 if it begins with `0',;TI"Gand 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"OMatches 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"LMatches a single character, or a sequence of n characters if a;TI"Lfield width of n is specified. The usual skip of leading white;TI"Mspace is suppressed. To skip white space first, use an explicit space in;TI"the format.;T@o;;I"[;T;[o;	;[I"EMatches a nonempty sequence of characters from the specified set;TI"Fof accepted characters. The usual skip of leading white space is;TI"Msuppressed. This bracketed sub-expression is interpreted exactly like a;TI"Pcharacter class in a Ruby regular expression. (In fact, it is placed as-is;TI"Oin a regular expression.) The matching against the input string ends with;TI"Nthe 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"OTo require that a particular match occur, but without including the result;TI"Pin the return array, place the assignment suppression flag, which is;TI"Lthe 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"Pscanf 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"HThe only flag implemented in scanf for Ruby is '<tt>*</tt>' (ignore;TI"Hupcoming conversion). Many of the flags available in C versions of;TI"Mscanf(3) have to do with the type of upcoming pointer arguments, and are;TI"meaningless in Ruby.;T@o;;0;[o;	;[I"LThe <tt>n</tt> specifier (store number of characters consumed so far in;TI"&next pointer) is not implemented.;T@o;;0;[o;	;[I"IThe <tt>p</tt> 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"MIn 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"Gscanf for Ruby returns an array of successful conversions, whereas;TI"<scanf(3) returns the number of conversions successfully;TI"Fcompleted. (See below for more details on scanf for Ruby's return;TI"
values.);T@S;;i;
I"Return values;T@o;	;[I"KWithout a block, scanf returns an array containing all the conversions;TI"Kit has found. If none are found, scanf will return an empty array. An;TI"Kunsuccessful match is never ignored, but rather always signals the end;TI"Lof the scanning operation. If the first unsuccessful match takes place;TI"Gafter one or more successful matches have already taken place, the;TI"Ireturned array will contain the results of those successful matches.;T@o;	;[	I"JWith a block scanf returns a 'map'-like array of transformations from;TI"Kthe block -- that is, an array reflecting what the block did with each;TI"Dyielded result from the iterative scanf operation. (See "Block;TI"usage", above.);T@S;;i;
I"!Current limitations and bugs;T@o;	;[I"HWhen using IO#scanf under Windows, make sure you open your files in;TI"binary mode:;T@o;;[I"!File.open("filename", "rb")
;Fo;	;[I":so that scanf can keep track of characters correctly.;T@o;	;[I"CSupport for character classes is reasonably complete (since it;TI"Eessentially piggy-backs on Ruby's regular expression handling of;TI"Kcharacter classes), but users are advised that character class testing;TI"Hhas not been exhaustive, and that they should exercise some caution;TI"Cin 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"IThis software is provided "as is" and without any express or implied;TI"Iwarranties, 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"Jscanf 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"HThe text for parts of this document, especially the Description and;TI"JConversions 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"Bscanf for Ruby is based on something of an amalgam of C scanf;TI"Iimplementations and documentation, rather than on a single canonical;TI"Idescription. Suggestions for features and behaviors which appear in;TI"Gother scanfs, and would be meaningful in Ruby, are welcome, as are;TI"Kreports of suspicious behaviors and/or bugs. (Please see "Credits and;TI"4acknowledgements", above, for email addresses.);T:
@fileI"lib/scanf.rb;T;0[�[�[�[[I"
class;F[[:public[�[:protected[�[:private[�[I"
instance;F[[;[�[;[�[;[�