readme.txt

delphi 实现的 sscanf 函数

**************************************
*  Scanf for Delphi  and  DeFormat   *
************************************** 
 
These are the programs which I hope will help Delphi users and those
who port programs from C/C++ to Delphi. 

The current version (1.0) is distributed with the complete source code.
I welcome any comments or suggestions, especially what concerns bugs, 
compatibility conflicts, and additional features.  


If you are familiar with scanf and do not intend to use DeFormat,
proceed directly to "Compatibility with C/C++ scanf". 


The package is free for private and academic use.
For commercial use, please contact the author.

***********************************************

 Evgeni Sorokin 
 TU Vienna 
 Gusshausstrasse 27/387             
 A-1040 Vienna                         
 Austria
 email: [e-mail]
 
***********************************************



************
*  Purpose *
************

Scanf package provide tools for formatted input, using the same 
principle as Delphi's Format function. Its original purpose was to provide 
experienced C/C++ users a scanf-type function for converting C/C++ 
codes to Delphi.

I hope however, that Delphi users can also benefit from a DeFormat 
function, even if they never used scanf. In addition, the package 
also contains support of Comp type as an integer, which is not 
available in Delphi 2 and 3.


****************************
* Structure of the package *
****************************

The package consists of the two units:

  Scanf.pas 
  Scanf_c.pas

of which the first is the user-oriented interface to the second, 
where actual conversion takes place.

In the Scanf. pas:

  Functions following C/C++ semantics:
 
*    sscanf
*    fscanf

  The two functions are identical except that sscanf uses PChar as input 
  while fscanf takes it sinput from a TStream. A valid implementation of 
  TStream must support moving the Position property backwards. 
  In what follows, sscanf and fscanf will be referred as to "scanf".

  Routines following Delphi Format semantics:

*    DeFormat
*    StrDeFmt
*    DeFormatBuf

  are different callers of one and the same function. 
  These functions follow the calling patterns of Format, StrFmt and FormatBuf,
  corrrspondingly. 
  In the rest of this document these functions are referred to as "DeFormat".


  Extensions to the library functions with thousand separators' support:

*     TextToFloatS (like TextToFloat)
*     StrToCurrS   (like StrToCurr)
*     StrToFloatS  (like StrToFloat)
 
  Decimal, hex, and octal representations of an int64 (Comp) type (the first 
  two are probably obsolete for Delphi 4):

*     int64ToStr
*     int64ToHex
*     int64ToOct
 
  A function for scanning the currency in "formatted" form:

*     StrToCurrF
 
The package also includes the scTutor program (source code in the Tutor subdir; 
compiled under Delphi 4 in $Q+ mode and with exceptions enabled). This program 
serves both learning  purposes for those uncommon with scanf, and as a handy 
standalone check utility helping to trace the problem if any. Additionally, 
the users are encouraged to have a look at Examples.pas file, which is executed 
in the initiation part of the Learn.pas unit. You might stepwise follow the calls 
and inspect the results to get comfortable with scanf and DeFormat ideology.

  
***************************************
* Extensions to the library functions *
***************************************

Starting with version 1.0, scanf package uses its own scanners.
Compared to the library Val and TextToFloat functions scanf package 
supports following extended features:

 + Floating-point conversion accepts (-)INF  and (-)NAN numbers
   (must be upper-case!).
 + Hex conversion accepts minus sign (i.e. -$ffffffff gives 1).
 + Both "$" and "0x" hex prefixes are allowed.
 + Octal integer format is supported. 
 + Comp type is scanned as integer under D2, D3.
 + Thousand separators in floating-point numbers are supported.
 + Currency type is supported (with thousand separators).

   

****************
* How it works *
****************

DeFormat, StrDeFmt, and DeFormatBuf are direct counterparts of library 
Format, StrFmt, and DeFormatBuf functions. The syntax of the format 
string is the generally the same, with size specifiers and pattern type
(search-set) added. Note, however, that you should provide *pointers* 
to the variables, rather than variables themselves in the Args 
array. The only exception is the PChar variable, which is supplied by 
itself, since it is already a pointer.

DeFormat and scanf compare format string with input string character by 
character (case sensitive or insensitive, see "Implementation Notes" below) 
until either a discrepance or a format specifier is found. Discrepance causes 
immediate return. White space in the format string is somewhat special, because
it corresponds to a white space of any length (including zero-length) in the 
input string. Additionally, any white space is automatically skipped before 
all format conversions excluding "c" and pattern types.
 
When a format specifier is found, conversion of the input string starts. 
The format specifier has the general form  
 "%" [index ":"] [width] ["." precision] "type"  
and is almost the same as used by Format function with following changes:

 1. Width parameter specify MAXIMUM width of the input to be 
    converted. In Format, it is MINIMUM width. Left justification
    character ("-") and precision are allowed, but ignored.

 2. If string format type ("s") is given, then the source string is copied   
    into the specified location until next white space is found. 

 4. Pattern scan behaves in the same manner, but it does not skip initial 
    white space and scans the input as long as all characters satisfy the 
    pattern. Pattern constructor is very much like a "set of char" constructor,
    but without commas and quotes, using "-" instead of "..". 
    A "^" character placed immediately after the opening bracket means
    logical negation of the pattern. 
    Examples: 
      [a-zA-Z] : All characters in ['a'..'z','A'..'Z']   
      [^0-9]   : Anything except ['0'..'9']

 5. Integer type specifier "i" allows input of integers in decimal, hex 
    (and octal in scanf) bases. If the number starts with "$", "0x", or 
    "0X", then it is assumed to be hex, otherwise decimal. In scanf, if a
    number starts with "0" then it is considered octal (I do not like this, 
    because it is error prone, but it is a standard behaviour of scanf in C/C++). 

 6. An input field is scanned until the first inconvertible character is met 
    or until Width is reached. The incorrect input may still result in 
    conversion and assignment if the input starts with legal characters. 
    For example, decimal conversion of "7FF" field will be scanned as 7, and
    octal number "05678" as octal 567.

 7. Types. All possible types have the meaning according to the following table:

========================================================================
 Type letter            DeFormat                        scanf      
------------------------------------------------------------------------
   d,D                decimal integer               decimal integer
   u,U             unsigned decimal integer    unsigned decimal integer
   x,X                  hex integer                    hex integer
   o,O                 octal integer                  octal integer
   i,I            integer(hex or decimal)(*)    integer(hex,decimal,octal)(*)

   n,N                 floating-point              number of characters
                  with thousand separators (*)  scanned so far, cardinal(*)     
     
f,F,e,E,g,G           floating-point                 floating-point  

    m                    currency                     not supported(*)
                  with thousand separators (*)

    M                formatted currency                not supported(*)
                  

    s                    string                          string
   [..]                  pattern                         pattern

    c                    character(s)                 character(s)

   p,P           32-bit pointer in hex form     32-bit pointer in hex form

========================================================================
(*) Marks differences between scanf and  DeFormat.


 8. Size specifiers. Since DeFormat and scanf get only pointers in the Args 
    array (with the exception of integers for indirect "*" flags), you must 
    provide additional information about the size of the variable if it 
    differs from default. Size specifier immediately precedes the format 
    letter and has the meaning according to the following table:

========================================================================
    Type        Size spec.              DeFormat              scanf      
------------------------------------------------------------------------