home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _d15d1c825844a676502fe84f7795e219 < prev    next >
Text File  |  2000-03-23  |  7KB  |  167 lines
  1.  
  2. <HTML>
  3. <HEAD>
  4. <TITLE>sscanf - emulate the sscanf of the C<C> stdio library</TITLE>
  5. <LINK REL="stylesheet" HREF="../../../Active.css" TYPE="text/css">
  6. <LINK REV="made" HREF="mailto:">
  7. </HEAD>
  8.  
  9. <BODY>
  10. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  11. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  12. <STRONG><P CLASS=block> sscanf - emulate the sscanf of the C<C> stdio library</P></STRONG>
  13. </TD></TR>
  14. </TABLE>
  15.  
  16. <A NAME="__index__"></A>
  17. <!-- INDEX BEGIN -->
  18.  
  19. <UL>
  20.  
  21.     <LI><A HREF="#name">NAME</A></LI><LI><A HREF="#supportedplatforms">SUPPORTED PLATFORMS</A></LI>
  22.  
  23.     <LI><A HREF="#synopsis">SYNOPSIS</A></LI>
  24.     <LI><A HREF="#description">DESCRIPTION</A></LI>
  25.     <LI><A HREF="#features">FEATURES</A></LI>
  26.     <LI><A HREF="#limitations">LIMITATIONS</A></LI>
  27.     <LI><A HREF="#examples">EXAMPLES</A></LI>
  28.     <LI><A HREF="#internals">INTERNALS</A></LI>
  29.     <LI><A HREF="#version">VERSION</A></LI>
  30.     <LI><A HREF="#author">AUTHOR</A></LI>
  31. </UL>
  32. <!-- INDEX END -->
  33.  
  34. <HR>
  35. <P>
  36. <H1><A NAME="name">NAME</A></H1>
  37. <P>sscanf - emulate the <CODE>sscanf()</CODE> of the <CODE>C</CODE> stdio library</P>
  38. <P>
  39. <HR>
  40. <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1>
  41. <UL>
  42. <LI>Linux</LI>
  43. <LI>Solaris</LI>
  44. <LI>Windows</LI>
  45. </UL>
  46. <HR>
  47. <H1><A NAME="synopsis">SYNOPSIS</A></H1>
  48. <PRE>
  49.         use String::Scanf;      # this will import sscanf() into the
  50.                                 # current namespace</PRE>
  51. <PRE>
  52.         @values = sscanf($scanf_format_string, $scalar_to_scan);</PRE>
  53. <PRE>
  54.         # the default scan target is the $_
  55.         @values = sscanf($scanf_format_string);</PRE>
  56. <PRE>
  57.         # converting scanf formats to regexps (::format_to_re
  58.         # is never exported to the current namespace)</PRE>
  59. <PRE>
  60.         $regexp_string = String::Scanf::format_to_re($scanf_format_string);</PRE>
  61. <P>
  62. <HR>
  63. <H1><A NAME="description">DESCRIPTION</A></H1>
  64. <P>Perl <CODE>sscanf()</CODE> can be used very much like the <CODE>C</CODE> stdio sscanf(), for
  65. detailed <CODE>sscanf()</CODE> documentation please refer to your usual
  66. documentation resources. The supported formats are: <CODE>[diuoxefgsc]</CODE>
  67. and the character class <CODE>[]</CODE>.</P>
  68. <P><STRONG>All</STRONG> of the format must match. If not, an empty list is returned
  69. and all the values end up empty.</P>
  70. <P>The <CODE>c</CODE> format returns an anonymous list (see perlref)
  71. containing the numeric values of the characters it matched.</P>
  72. <P>The ::format_to_re() function may be helpful if one wants to
  73. develop her own parsing routines.</P>
  74. <P>
  75. <HR>
  76. <H1><A NAME="features">FEATURES</A></H1>
  77. <P>Embedded underscores are accepted in numbers just like in Perl, even
  78. in octal/hexadecimal numbers (Perl does not currently support
  79. this). Please note the word <STRONG>embedded</STRONG>, not leading or trailing.</P>
  80. <P>If the <CODE>oh</CODE> formats are used, the octal/hexadecimal interpretation
  81. is forced even without the leading <CODE>0</CODE> or <CODE>0x</CODE>.</P>
  82. <P>
  83. <HR>
  84. <H1><A NAME="limitations">LIMITATIONS</A></H1>
  85. <P>Certain features of the C <CODE>sscanf()</CODE> are unsupported:</P>
  86. <PRE>
  87.         * the formats C<[npSC]>
  88.         * in the C<[efg]> formats the C<INF> and various C<NaN>s</PRE>
  89. <P>The numeric formats are scanned in as strings, this meaning that
  90. numeric overflows may occur. For example: <CODE>1.2345e67890</CODE> will match
  91. the <CODE>%g</CODE> format but in most machines Perl cannot handle that large
  92. floating point numbers and bizarre values may end up in the Perl
  93. variable. Similar caveats apply for integer-type numbers. Results of
  94. such huge numbers (or very tiny numbers, say, <CODE>1.24345e-67890</CODE>) are
  95. implementation-defined, which translates quite often as <EM>garbage</EM>.
  96. <STRONG>NOTE</STRONG>: if you really want <STRONG>Big</STRONG> numbers please consider
  97. using the <CODE>Math::BigInt</CODE> and <CODE>Math::BigFloat</CODE>, these packages come
  98. standard with Perl 5, or the <CODE>Math::Pari</CODE> package, available from
  99. <CODE>CPAN</CODE>.</P>
  100. <P>For Perl <integers> and <EM>floating point numbers</EM> are the same thing.
  101. Also, the possible <CODE>hl</CODE> modifiers for the <EM>integers</EM> mean nothing:
  102. they are accepted but still they do nothing because Perl does not care
  103. about short/long integer differences.</P>
  104. <P>The character class format is not so rigorously checked for
  105. correctness that an illegal character class definition could
  106. not be sneaked in. For example <CODE>[z-a,X]</CODE> is a <CODE>bad</CODE> example:
  107. perfectly illegal as a character class but <CODE>String::Scanf</CODE> will
  108. happily accept it. Beware.</P>
  109. <P>The ::format_to_re() only does the scanf format -> regular expression
  110. conversion. It ignores tricky things like the <CODE>c</CODE> format (see above)
  111. and the %n$ argument reordering. If you want these, you may as well use
  112. the full ::sscanf().</P>
  113. <P>
  114. <HR>
  115. <H1><A NAME="examples">EXAMPLES</A></H1>
  116. <PRE>
  117.         # business as usual</PRE>
  118. <PRE>
  119.         ($i, $s, $x) = sscanf('%d %3s %g', ' -5_678     abc 3.14e-99 9');</PRE>
  120. <PRE>
  121.         # 'skip leading whitespace': $x becomes 42 despite the leading space
  122.         # 'the illegal character': $y becomes 'ab' despite the '3'
  123.         # 'c' format: $z becomes [120 100], the numeric values of 'x'
  124.         # and 'd' (assuming ASCII or ISO Latin 1)</PRE>
  125. <PRE>
  126.         ($x, $y, $z) = sscanf('%i%3[a-e]%2c', ' 42acxde');</PRE>
  127. <PRE>
  128.         # reordering the arguments: $a becomes 34, $b becomes 12</PRE>
  129. <PRE>
  130.         ($a, $b) = sscanf('%2$d %1$d', '12 34');</PRE>
  131. <PRE>
  132.         # converting scanf formats to regexps</PRE>
  133. <PRE>
  134.         $re = String::Scanf::format_to_re('%x');</PRE>
  135. <P>More examples in the test set <CODE>t/scanf.t</CODE>.</P>
  136. <P>
  137. <HR>
  138. <H1><A NAME="internals">INTERNALS</A></H1>
  139. <P>The Perl <CODE>sscanf()</CODE> turns the <CODE>C</CODE>-<CODE>stdio</CODE> style <CODE>sscanf()</CODE> format
  140. string into a Perl regexp (see perlre) which captures the wanted
  141. values into submatches and returns the submatches as a list.</P>
  142. <P>Originally written for purposes of debugging but also useful
  143. for educational purposes:</P>
  144. <PRE>
  145.         String::Scanf::debug(1);        # turn on debugging: shows the regexps
  146.                                 # used and the possible reordering list
  147.                                 # and the character (%c) conversion targets
  148.         String::Scanf::debug(0);                # turn off debugging
  149.         print String::Scanf::debug(), "\n";     # the current debug status</PRE>
  150. <P>
  151. <HR>
  152. <H1><A NAME="version">VERSION</A></H1>
  153. <P>v1.1, $Id: Scanf.pm,v 1.8 1995/12/27 08:32:28 jhi Exp $</P>
  154. <P>
  155. <HR>
  156. <H1><A NAME="author">AUTHOR</A></H1>
  157. <P>Jarkko Hietaniemi, <CODE>Jarkko.Hietaniemi@iki.fi</CODE></P>
  158. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  159. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  160. <STRONG><P CLASS=block> sscanf - emulate the sscanf of the C<C> stdio library</P></STRONG>
  161. </TD></TR>
  162. </TABLE>
  163.  
  164. </BODY>
  165.  
  166. </HTML>
  167.