1mNAME0m
       scan - Parse string using conversion specifiers in the style of sscanf

1mSYNOPSIS0m
       1mscan 4m22mstring24m 4mformat24m ?4mvarName24m 4mvarName24m 4m...24m?


1mINTRODUCTION0m
       This  command parses fields from an input string in the same fashion as
       the ANSI C 1msscanf 22mprocedure and returns a count of the number  of  con-
       versions  performed,  or  -1  if the end of the input string is reached
       before any conversions have been performed.  4mString24m gives the input  to
       be  parsed  and  4mformat24m  indicates  how to parse it, using 1m% 22mconversion
       specifiers as in 1msscanf22m.  Each 4mvarName24m gives the name  of  a  variable;
       when a field is scanned from 4mstring24m the result is converted back into a
       string and assigned to the corresponding variable.  If no 4mvarName24m vari-
       ables are specified, then 1mscan 22mworks in an inline manner, returning the
       data that would otherwise be stored in the variables as a list.  In the
       inline  case,  an  empty  string  is returned when the end of the input
       string is reached before any conversions have been performed.

1mDETAILS ON SCANNING0m
       1mScan 22moperates by scanning 4mstring24m and  4mformat24m  together.   If  the  next
       character  in  4mformat24m  is  a blank or tab then it matches any number of
       white space characters in 4mstring24m (including zero).   Otherwise,  if  it
       isn't  a  1m%  22mcharacter then it must match the next character of 4mstring24m.
       When a 1m% 22mis encountered in 4mformat24m, it indicates the start of a  conver-
       sion  specifier.   A  conversion  specifier  contains up to four fields
       after the 1m%22m: a 1m*22m, which indicates that the converted  value  is  to  be
       discarded instead of assigned to a variable; a XPG3 position specifier;
       a number indicating a maximum field width; a field size modifier; and a
       conversion  character.  All of these fields are optional except for the
       conversion character.  The fields that are present must appear  in  the
       order given above.

       When  1mscan  22mfinds  a conversion specifier in 4mformat24m, it first skips any
       white-space characters in 4mstring24m (unless the  specifier  is  1m[  22mor  1mc22m).
       Then  it converts the next input characters according to the conversion
       specifier and stores the result in the variable given by the next argu-
       ment to 1mscan22m.

       If  the 1m% 22mis followed by a decimal number and a 1m$22m, as in ``1m%2$d22m'', then
       the variable to use is not taken from  the  next  sequential  argument.
       Instead, it is taken from the argument indicated by the number, where 1
       corresponds to the first 4mvarName24m.  If there are any  positional  speci-
       fiers  in  4mformat24m then all of the specifiers must be positional.  Every
       4mvarName24m on the argument list must correspond to exactly one  conversion
       specifier or an error is generated, or in the inline case, any position
       can be specified at most once and the empty positions will be filled in
       with empty strings.

       The following conversion characters are supported:

       1md         22mThe input field must be a decimal integer.  It is read in and
                 the value is stored in the variable as a decimal string.   If
                 the  1ml  22mor  1mL 22mfield size modifier is given, the scanned value
                 will have an internal representation that is at least 64-bits
                 in size.

       1mo         22mThe  input  field must be an octal integer. It is read in and
                 the value is stored in the variable as a decimal string.   If
                 the  1ml  22mor  1mL 22mfield size modifier is given, the scanned value
                 will have an internal representation that is at least 64-bits
                 in size.  If the value exceeds MAX_INT (017777777777 on plat-
                 forms using 32-bit integers when the 1ml 22mand  1mL  22mmodifiers  are
                 not given), it will be truncated to a signed integer.  Hence,
                 037777777777 will  appear  as  -1  on  a  32-bit  machine  by
                 default.

       1mx         22mThe  input field must be a hexadecimal integer. It is read in
                 and the value is stored in the variable as a decimal  string.
                 If the 1ml 22mor 1mL 22mfield size modifier is given, the scanned value
                 will have an internal representation that is at least 64-bits
                 in  size.   If the value exceeds MAX_INT (0x7FFFFFFF on plat-
                 forms using 32-bit integers when the 1ml 22mand  1mL  22mmodifiers  are
                 not given), it will be truncated to a signed integer.  Hence,
                 0xFFFFFFFF will appear as -1 on a 32-bit machine.

       1mu         22mThe input field must be a  decimal  integer.   The  value  is
                 stored in the variable as an unsigned decimal integer string.
                 If the 1ml 22mor 1mL 22mfield size modifier is given, the scanned value
                 will have an internal representation that is at least 64-bits
                 in size.

       1mi         22mThe input field must be an integer.  The base (i.e.  decimal,
                 octal,  or  hexadecimal) is determined in the same fashion as
                 described in 1mexpr22m.  The value is stored in the variable as  a
                 decimal  string.  If the 1ml 22mor 1mL 22mfield size modifier is given,
                 the scanned value will have an internal  representation  that
                 is at least 64-bits in size.

       1mc         22mA  single character is read in and its binary value is stored
                 in the variable as a decimal string.  Initial white space  is
                 not  skipped in this case, so the input field may be a white-
                 space character.  This conversion is different from the  ANSI
                 standard  in that the input field always consists of a single
                 character and no field width may be specified.

       1ms         22mThe input field consists of all the characters up to the next
                 white-space character; the characters are copied to the vari-
                 able.

       1me 22mor 1mf 22mor 1mg0m
                 The input field must be a floating-point number consisting of
                 an  optional  sign,  a string of decimal digits possibly con-
                 taining a decimal point, and an optional exponent  consisting
                 of  an  1me  22mor  1mE 22mfollowed by an optional sign and a string of
                 decimal digits.  It is read in and stored in the variable  as
                 a floating-point string.

       1m[4m22mchars24m1m]   22mThe  input  field  consists  of  any  number of characters in
                 4mchars24m.  The matching string is stored in  the  variable.   If
                 the  first  character  between the brackets is a 1m] 22mthen it is
                 treated as part of 4mchars24m rather than the closing bracket  for
                 the  set.   If 4mchars24m contains a sequence of the form 4ma24m1m-4m22mb24m then
                 any character between 4ma24m and 4mb24m (inclusive) will match.  If the
                 first  or last character between the brackets is a 1m-22m, then it
                 is treated as part of 4mchars24m rather than indicating a range.

       1m[^4m22mchars24m1m]  22mThe input field consists of any number of characters  not  in
                 4mchars24m.   The  matching  string is stored in the variable.  If
                 the character immediately following the 1m^ 22mis a 1m] 22mthen  it  is
                 treated  as  part  of the set rather than the closing bracket
                 for the set.  If 4mchars24m contains a sequence of  the  form  4ma24m1m-4m22mb0m
                 then  any  character  between  4ma24m  and  4mb24m  (inclusive) will be
                 excluded from the  set.   If  the  first  or  last  character
                 between  the  brackets  is a 1m-22m, then it is treated as part of
                 4mchars24m rather than indicating a range.

       1mn         22mNo input is consumed from the  input  string.   Instead,  the
                 total  number  of characters scanned from the input string so
                 far is stored in the variable.

       The number of characters read from the input for a  conversion  is  the
       largest  number  that  makes sense for that particular conversion (e.g.
       as many decimal digits as possible for 1m%d22m, as many octal digits as pos-
       sible  for 1m%o22m, and so on).  The input field for a given conversion ter-
       minates either when a white-space character is encountered or when  the
       maximum field width has been reached, whichever comes first.  If a 1m* 22mis
       present in the conversion specifier then no variable  is  assigned  and
       the next scan argument is not consumed.

1mDIFFERENCES FROM ANSI SSCANF0m
       The  behavior  of  the  1mscan 22mcommand is the same as the behavior of the
       ANSI C 1msscanf 22mprocedure except for the following differences:

       [1]    1m%p 22mconversion specifier is not currently supported.

       [2]    For 1m%c 22mconversions a single character value is  converted  to  a
              decimal string, which is then assigned to the corresponding 4mvar-0m
              4mName24m; no field width may be specified for this conversion.

       [3]    The 1mh 22mmodifier is always ignored and the 1ml 22mand 1mL  22mmodifiers  are
              ignored  when  converting  real values (i.e. type 1mdouble 22mis used
              for the internal representation).

       [4]    If the end of the input string is reached before any conversions
              have  been performed and no variables are given, an empty string
              is returned.

1mEXAMPLES0m
       Parse a simple color specification of the form 4m#RRGGBB24m using  hexadeci-
       mal conversions with field sizes:
              set string "#08D03F"
              1mscan 22m$string "#%2x%2x%2x" r g b

       Parse  a 4mHH:MM24m time string, noting that this avoids problems with octal
       numbers by forcing interpretation as decimals (if we did not  care,  we
       would use the 1m%i 22mconversion instead):
              set string "08:08"   ;# *Not* octal!
              if {[1mscan 22m$string "%d:%d" hours minutes] != 2} {
                 error "not a valid time string"
              }
              # We have to understand numeric ranges ourselves...
              if {$minutes < 0 || $minutes > 59} {
                 error "invalid number of minutes"
              }

       Break a string up into sequences of non-whitespace characters (note the
       use of the 1m%n 22mconversion so that we get skipping  over  leading  white-
       space correct):
              set string " a string {with braced words} + leading space "
              set words {}
              while {[1mscan 22m$string %s%n word length] == 2} {
                 lappend words $word
                 set string [string range $string $length end]
              }

       Parse a simple coordinate string, checking that it is complete by look-
       ing for the terminating character explicitly:
              set string "(5.2,-4e-2)"
              # Note that the spaces before the literal parts of
              # the scan pattern are significant, and that ")" is
              # the Unicode character \u0029
              if {
                 [1mscan 22m$string " (%f ,%f %c" x y last] != 3
                 || $last != 0x0029
              } then {
                 error "invalid coordinate string"
              }
              puts "X=$x, Y=$y"


1mSEE ALSO0m
       format(n), sscanf(3)


1mKEYWORDS0m
