readme.txt

delphi 实现的 sscanf 函数

                (default)               integer              integer
 all integer      H, l8                 ShortInt             ShortInt
   types:         h, l16                SmallInt             SmallInt  
  i,d,u,x         l, l32                LongInt              LongInt 
                 L, ll, l64              Comp                 Comp


 floating-      (default)               Extended(*)         Single(*)    
  point            H                      Real                Real
  types:           h                     Single              Single
  f,g,e            l                     Double              Double
                  L, ll                 Extended            Extended 
                             
   n                               like floating-point     like integer        

  m,M           not allowed            currency(*)        not supported(*)    

  p,P           not allowed             pointer              pointer

 string         (default)                PChar                PChar
 types:            h                  ShortString           ShortString
 s, pattern        l                   AnsiString            AnsiString     

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


 9. Modifiers. The usage and meaning of modifiers in DeFormat is the same
    as in Format (except that precision and justification modifiers are
    ignored). In scanf, there are only two possible modifiers: assignment 
    suppression ("*" character right after the "%" sign) and width as a 
    decimal integer. With DeFormat, assignment suppression is achieved by 
    supplying NIL pointer into the Args array. With scanf, NIL pointer is 
    illegal and terminates scanning (standard behaviour in C/C++ scanf).

10. String types automatically append #0 to the end of the string if it is
    a PChar or AnsiString. For PChar type, you should provide enough allocated 
    space, including this additional character. If "%ls" format specifier is
    used, then AnsiString is created anew and necessary space is allocated 
    automatically.

11. Return value. Both functions return the number of successfully assigned 
    variables. In addition, scanf retuns -1 if it reaches the end of the input
    and no assignments have been made. The core functions scanf_core and 
    DeFormat_core also return the final positions in the input and format
    strings (see "Implementation Notes"). Note that "n" specifier in scanf does
    not count. If an exception is raised, then return value is undefined 
    (see "Exceptions Handling").

12. Currency support. In DeFormat, %m specifier scans in a numerical currency 
    value (with thousand separators and decimal separators). %M specifier scans in 
    a formatted currency value, using CurrencyString, CurrencyFormat and 
    NegCurrFormat.



**********************************
* Compatibility with C/C++ scanf *
**********************************

Scanf for Delphi has been designed to be as compatible to the C/C++
scanf() as possible. I took GNU scanf for Win32 (Cygnis) 
for a basic set and added some extensions from Borland C++ 5.01. 

Hex string identification accepts both C-type ("0x") and Pascal-type ("$")
hex prefixes. While this may create some problems with "i" type when "$" 
sign is used as currency specifier, it is undispensible for Delphi 
environment. If in doubt, use explicit "d" or "x" specifiers.

A "very short" size specifier "H" has been added. For integer types, it 
means an 8-bit integer (ShortInt or Byte), for floating-point types, 
the old Real type. All integer and floating-point type specifiers are 
case-insensitive.

Since there is no wide character support in the current version, 
upper-case C and S specifiers behave as lower-case counterparts, but 
this may change in the future. You should be safe using all-lower-case
specifiers, though.

The table below summarizes the differences in types:

======================================================================
  scanf        Delphi               BC++                  Cygnis
  spec.         type                type                   type  
======================================================================

   hs       ShortString              char *                char *  
   hS       SHortString              char *                  -
   ls       AnsiString             widechar *              char * 
   lS       AnsiString             widechar *                - 
    s         PChar                  char *                char *
    S         PChar                widechar *                - 
    c         char                   char                   char
    C         char                 widechar                  - 
   hc         char                   char                   char    
   hC         char                   char                    -    
   lc         char                 widechar                 char
   lC         char                 widechar                  -

   Hi       ShortInt                  -                      -
  l8i       ShortInt                 char                    -
   hi       SmallInt               short int              short int
  l16i      SmallInt               short int                 -
    i       Integer                   int                   int
  l32i      Integer                   int                    -
   li       LongInt                long int               long int
   Li       int64 (Comp)            __int64                  - 
  l64i      int64 (Comp)            __int64                  - 

          "i" stands for any integer type (i, d, u, o, n, and x).


   Hf         Real                     -                     -
   hf        Single                  float                 float
    f        Single                  float                 float
   lf        Double                  double                double
   Lf       Extended               long double           long double    

          "f" stands for any floating-point type (e, g, and f).   

======================================================================


**********************
* Exception handling *
**********************

In {$Q+} mode, overflow in integer, floating-point, and currency raises 
EOverflow exception.

If scanf_c.pas unit is compiled with DEFORMAT_EXCEPTIONS or SCANF_EXCEPTIONS 
defined, following exceptions are raised:

 - If a numerical field can not be converted.
 - If function attempts an assignment, but index of the pointer lies outside
   of Low(Args)..High(Args)
 - If format specifier has incorrect syntax.
 - If scanf attempts to assign to NIL.
 - If type of a variable for indirect input in DeFormat is not vtInteger.

Important note: If an exception is raised, then the return values of scanf_core 
and DeFormat_core are undefined (normally they correspond to some pointer value).
This is an unfortunate feature of Delphi exception handler. It is therefore 
reasanble to use either exceptions or check the return values, but not both.


************************
* Implementation notes *
************************

The routines in the scanf_c.pas unit are loosely documented and badly structured. 
They are not supposed to be debugged, but optimized for flexibility and 
performance. You are NOT encouraged to debug them yourself, but rather contact 
the author. The source code is provided only for the recompilation purposes. 

The actual conversion is performed by assembler-level routines and by scanf_core, 
scanf_stream, DeFormat_core, and StrToCurrF_core functions in the Scanf_c.pas unit. 
The user-friendly functions in the Scanf.pas unit provide corresponding calls and 
entry points. You may wish to create your own procedures using the conversion motors. 
For this purpose, all core routines set input pointers to point past the last 
successfully scanned (converted) character, which allows to analyse the failure 
and continue processing, if necessary.  

The programs in the package do not use VCL calls, do not modify static variables 
and do not modify input strings. They should be therefore reentrant and thread-safe. 
In fact, %M specifier in DeFormat works recursively. 

NOTE: The fscanf (scanf_stream) routine uses and modifies the Position property of 
the input stream. For some stream implementations, this may be not reentrant. 
The valid TStream implementation MUST support moving Position backward.

In accordance to C and Pascal traditions, scanf is case-sensitive 
but DeFormat is case-insensitive (this is marginally slower).
This behaviour can be changed in the Scanf_c.pas unit by commenting (out) the
corresponding compiler directives in the unit header. 


Not implemented:

 - wide string support


*****************
* Release Notes *
*****************

26.08.1998 
  Beta version 0.9 released.

09.09.1998 
  Added octal base support. 
  Removed bugs in variable indexing.
  Optimized hex scanner and search-set parser.

20.10.1998
  Added independent decimal integer and floating point scanners and removed
  library Val routine. FP scanner supports thousand separators and currency.
  Restructured package, moving assembler level routines into separate unit.
  Removed bug in Int64ToXXX, producing empty string on zero value.

10.11.1998
  Converted case-sensitivity and verbose switches to compiler directives.
  Added overflow control.
  Added TextToFloatS routine.
  Adapted to Delphi 4.

20.11.1998
  Added formatted currency conversion (StrToCurrF_core) and %M as separate specifier
  for DeFormat family.
  Added StrToFloatS and StrToCurrS.
  A couple of bugs removed.

7.12.1998
  Added scTutor program.

12.12.1998
  Fscanf added.

17.12.1998 
  Assembler-level routines included back into the scanf_c.pas unit.

6.9.1999
  A couple of cosmetic changes.