452 lines
25 KiB
HTML
452 lines
25 KiB
HTML
<HTML><HEAD><TITLE>Tcl Built-In Commands - binary manual page</TITLE></HEAD><BODY>
|
|
<DL>
|
|
<DD><A HREF="binary.htm#M2" NAME="L54">NAME</A>
|
|
<DL><DD>binary - Insert and extract fields from binary strings</DL>
|
|
<DD><A HREF="binary.htm#M3" NAME="L55">SYNOPSIS</A>
|
|
<DL>
|
|
<DD><B>binary format </B><I>formatString </I>?<I>arg arg ...</I>?
|
|
<DD><B>binary scan </B><I>string formatString </I>?<I>varName varName ...</I>?
|
|
</DL>
|
|
<DD><A HREF="binary.htm#M4" NAME="L56">DESCRIPTION</A>
|
|
<DD><A HREF="binary.htm#M5" NAME="L57">BINARY FORMAT</A>
|
|
<DL>
|
|
<DD><A HREF="binary.htm#M6" NAME="L58"><B>a</B></A>
|
|
<DD><A HREF="binary.htm#M7" NAME="L59"><B>A</B></A>
|
|
<DD><A HREF="binary.htm#M8" NAME="L60"><B>b</B></A>
|
|
<DD><A HREF="binary.htm#M9" NAME="L61"><B>B</B></A>
|
|
<DD><A HREF="binary.htm#M10" NAME="L62"><B>h</B></A>
|
|
<DD><A HREF="binary.htm#M11" NAME="L63"><B>H</B></A>
|
|
<DD><A HREF="binary.htm#M12" NAME="L64"><B>c</B></A>
|
|
<DD><A HREF="binary.htm#M13" NAME="L65"><B>s</B></A>
|
|
<DD><A HREF="binary.htm#M14" NAME="L66"><B>S</B></A>
|
|
<DD><A HREF="binary.htm#M15" NAME="L67"><B>i</B></A>
|
|
<DD><A HREF="binary.htm#M16" NAME="L68"><B>I</B></A>
|
|
<DD><A HREF="binary.htm#M17" NAME="L69"><B>f</B></A>
|
|
<DD><A HREF="binary.htm#M18" NAME="L70"><B>d</B></A>
|
|
<DD><A HREF="binary.htm#M19" NAME="L71"><B>x</B></A>
|
|
<DD><A HREF="binary.htm#M20" NAME="L72"><B>X</B></A>
|
|
<DD><A HREF="binary.htm#M21" NAME="L73"><B>@</B></A>
|
|
</DL>
|
|
<DD><A HREF="binary.htm#M22" NAME="L74">BINARY SCAN</A>
|
|
<DL>
|
|
<DD><A HREF="binary.htm#M23" NAME="L75"><B>a</B></A>
|
|
<DD><A HREF="binary.htm#M24" NAME="L76"><B>A</B></A>
|
|
<DD><A HREF="binary.htm#M25" NAME="L77"><B>b</B></A>
|
|
<DD><A HREF="binary.htm#M26" NAME="L78"><B>B</B></A>
|
|
<DD><A HREF="binary.htm#M27" NAME="L79"><B>h</B></A>
|
|
<DD><A HREF="binary.htm#M28" NAME="L80"><B>H</B></A>
|
|
<DD><A HREF="binary.htm#M29" NAME="L81"><B>c</B></A>
|
|
<DD><A HREF="binary.htm#M30" NAME="L82"><B>s</B></A>
|
|
<DD><A HREF="binary.htm#M31" NAME="L83"><B>S</B></A>
|
|
<DD><A HREF="binary.htm#M32" NAME="L84"><B>i</B></A>
|
|
<DD><A HREF="binary.htm#M33" NAME="L85"><B>I</B></A>
|
|
<DD><A HREF="binary.htm#M34" NAME="L86"><B>f</B></A>
|
|
<DD><A HREF="binary.htm#M35" NAME="L87"><B>d</B></A>
|
|
<DD><A HREF="binary.htm#M36" NAME="L88"><B>x</B></A>
|
|
<DD><A HREF="binary.htm#M37" NAME="L89"><B>X</B></A>
|
|
<DD><A HREF="binary.htm#M38" NAME="L90"><B>@</B></A>
|
|
</DL>
|
|
<DD><A HREF="binary.htm#M39" NAME="L91">PLATFORM ISSUES</A>
|
|
<DD><A HREF="binary.htm#M40" NAME="L92">SEE ALSO</A>
|
|
<DD><A HREF="binary.htm#M41" NAME="L93">KEYWORDS</A>
|
|
</DL><HR>
|
|
<H3><A NAME="M2">NAME</A></H3>
|
|
binary - Insert and extract fields from binary strings
|
|
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
|
<B>binary format </B><I>formatString </I>?<I>arg arg ...</I>?<BR>
|
|
<B>binary scan </B><I>string formatString </I>?<I>varName varName ...</I>?<BR>
|
|
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
|
This command provides facilities for manipulating binary data. The
|
|
first form, <B>binary format</B>, creates a binary string from normal
|
|
Tcl values. For example, given the values 16 and 22, on a 32 bit
|
|
architecture, it might produce an 8-byte binary string consisting of
|
|
two 4-byte integers, one for each of the numbers. The second form of
|
|
the command, <B>binary scan</B>, does the opposite: it extracts data
|
|
from a binary string and returns it as ordinary Tcl string values.
|
|
|
|
<H3><A NAME="M5">BINARY FORMAT</A></H3>
|
|
The <B>binary format</B> command generates a binary string whose layout
|
|
is specified by the <I>formatString</I> and whose contents come from
|
|
the additional arguments. The resulting binary value is returned.
|
|
<P>
|
|
The <I>formatString</I> consists of a sequence of zero or more field
|
|
specifiers separated by zero or more spaces. Each field specifier is
|
|
a single type character followed by an optional numeric <I>count</I>.
|
|
Most field specifiers consume one argument to obtain the value to be
|
|
formatted. The type character specifies how the value is to be
|
|
formatted. The <I>count</I> typically indicates how many items of the
|
|
specified type are taken from the value. If present, the <I>count</I>
|
|
is a non-negative decimal integer or <B>*</B>, which normally indicates
|
|
that all of the items in the value are to be used. If the number of
|
|
arguments does not match the number of fields in the format string
|
|
that consume arguments, then an error is generated.
|
|
<P>
|
|
Each type-count pair moves an imaginary cursor through the binary
|
|
data, storing bytes at the current position and advancing the cursor
|
|
to just after the last byte stored. The cursor is initially at
|
|
position 0 at the beginning of the data. The type may be any one of
|
|
the following characters:
|
|
<P>
|
|
<DL>
|
|
<P><DT><A NAME="M6"><B>a</B></A><DD>
|
|
Stores a character string of length <I>count</I> in the output string.
|
|
If <I>arg</I> has fewer than <I>count</I> bytes, then additional zero
|
|
bytes are used to pad out the field. If <I>arg</I> is longer than the
|
|
specified length, the extra characters will be ignored. If
|
|
<I>count</I> is <B>*</B>, then all of the bytes in <I>arg</I> will be
|
|
formatted. If <I>count</I> is omitted, then one character will be
|
|
formatted. For example,
|
|
<PRE><B>binary format a7a*a alpha bravo charlie</B></PRE>
|
|
will return a string equivalent to <B>alpha\000\000bravoc</B>.
|
|
<P><DT><A NAME="M7"><B>A</B></A><DD>
|
|
This form is the same as <B>a</B> except that spaces are used for
|
|
padding instead of nulls. For example,
|
|
<PRE><B>binary format A6A*A alpha bravo charlie</B></PRE>
|
|
will return <B>alpha bravoc</B>.
|
|
<P><DT><A NAME="M8"><B>b</B></A><DD>
|
|
Stores a string of <I>count</I> binary digits in low-to-high order
|
|
within each byte in the output string. <I>Arg</I> must contain a
|
|
sequence of <B>1</B> and <B>0</B> characters. The resulting bytes are
|
|
emitted in first to last order with the bits being formatted in
|
|
low-to-high order within each byte. If <I>arg</I> has fewer than
|
|
<I>count</I> digits, then zeros will be used for the remaining bits.
|
|
If <I>arg</I> has more than the specified number of digits, the extra
|
|
digits will be ignored. If <I>count</I> is <B>*</B>, then all of the
|
|
digits in <I>arg</I> will be formatted. If <I>count</I> is omitted,
|
|
then one digit will be formatted. If the number of bits formatted
|
|
does not end at a byte boundary, the remaining bits of the last byte
|
|
will be zeros. For example,
|
|
<PRE><B>binary format b5b* 11100 111000011010</B></PRE>
|
|
will return a string equivalent to <B>\x07\x87\x05</B>.
|
|
<P><DT><A NAME="M9"><B>B</B></A><DD>
|
|
This form is the same as <B>b</B> except that the bits are stored in
|
|
high-to-low order within each byte. For example,
|
|
<PRE><B>binary format B5B* 11100 111000011010</B></PRE>
|
|
will return a string equivalent to <B>\xe0\xe1\xa0</B>.
|
|
<P><DT><A NAME="M10"><B>h</B></A><DD>
|
|
Stores a string of <I>count</I> hexadecimal digits in low-to-high
|
|
within each byte in the output string. <I>Arg</I> must contain a
|
|
sequence of characters in the set ``0123456789abcdefABCDEF''. The
|
|
resulting bytes are emitted in first to last order with the hex digits
|
|
being formatted in low-to-high order within each byte. If <I>arg</I>
|
|
has fewer than <I>count</I> digits, then zeros will be used for the
|
|
remaining digits. If <I>arg</I> has more than the specified number of
|
|
digits, the extra digits will be ignored. If <I>count</I> is
|
|
<B>*</B>, then all of the digits in <I>arg</I> will be formatted. If
|
|
<I>count</I> is omitted, then one digit will be formatted. If the
|
|
number of digits formatted does not end at a byte boundary, the
|
|
remaining bits of the last byte will be zeros. For example,
|
|
<PRE><B>binary format h3h* AB def</B></PRE>
|
|
will return a string equivalent to <B>\xba\x00\xed\x0f</B>.
|
|
<P><DT><A NAME="M11"><B>H</B></A><DD>
|
|
This form is the same as <B>h</B> except that the digits are stored in
|
|
high-to-low order within each byte. For example,
|
|
<PRE><B>binary format H3H* ab DEF</B></PRE>
|
|
will return a string equivalent to <B>\xab\x00\xde\xf0</B>.
|
|
<P><DT><A NAME="M12"><B>c</B></A><DD>
|
|
Stores one or more 8-bit integer values in the output string. If no
|
|
<I>count</I> is specified, then <I>arg</I> must consist of an integer
|
|
value; otherwise <I>arg</I> must consist of a list containing at least
|
|
<I>count</I> integer elements. The low-order 8 bits of each integer
|
|
are stored as a one-byte value at the cursor position. If <I>count</I>
|
|
is <B>*</B>, then all of the integers in the list are formatted. If
|
|
the number of elements in the list is fewer than <I>count</I>, then an
|
|
error is generated. If the number of elements in the list is greater
|
|
than <I>count</I>, then the extra elements are ignored. For example,
|
|
<PRE><B>binary format c3cc* {3 -3 128 1} 260 {2 5}</B></PRE>
|
|
will return a string equivalent to
|
|
<B>\x03\xfd\x80\x04\x02\x05</B>, whereas
|
|
<PRE><B>binary format c {2 5}</B></PRE>
|
|
will generate an error.
|
|
<P><DT><A NAME="M13"><B>s</B></A><DD>
|
|
This form is the same as <B>c</B> except that it stores one or more
|
|
16-bit integers in little-endian byte order in the output string. The
|
|
low-order 16-bits of each integer are stored as a two-byte value at
|
|
the cursor position with the least significant byte stored first. For
|
|
example,
|
|
<PRE><B>binary format s3 {3 -3 258 1}</B></PRE>
|
|
will return a string equivalent to
|
|
<B>\x03\x00\xfd\xff\x02\x01</B>.
|
|
<P><DT><A NAME="M14"><B>S</B></A><DD>
|
|
This form is the same as <B>s</B> except that it stores one or more
|
|
16-bit integers in big-endian byte order in the output string. For
|
|
example,
|
|
<PRE><B>binary format S3 {3 -3 258 1}</B></PRE>
|
|
will return a string equivalent to
|
|
<B>\x00\x03\xff\xfd\x01\x02</B>.
|
|
<P><DT><A NAME="M15"><B>i</B></A><DD>
|
|
This form is the same as <B>c</B> except that it stores one or more
|
|
32-bit integers in little-endian byte order in the output string. The
|
|
low-order 32-bits of each integer are stored as a four-byte value at
|
|
the cursor position with the least significant byte stored first. For
|
|
example,
|
|
<PRE><B>binary format i3 {3 -3 65536 1}</B></PRE>
|
|
will return a string equivalent to
|
|
<B>\x03\x00\x00\x00\xfd\xff\xff\xff\x00\x00\x01\x00</B>
|
|
<P><DT><A NAME="M16"><B>I</B></A><DD>
|
|
This form is the same as <B>i</B> except that it stores one or more one
|
|
or more 32-bit integers in big-endian byte order in the output string.
|
|
For example,
|
|
<PRE><B>binary format I3 {3 -3 65536 1}</B></PRE>
|
|
will return a string equivalent to
|
|
<B>\x00\x00\x00\x03\xff\xff\xff\xfd\x00\x01\x00\x00</B>
|
|
<P><DT><A NAME="M17"><B>f</B></A><DD>
|
|
This form is the same as <B>c</B> except that it stores one or more one
|
|
or more single-precision floating in the machine's native
|
|
representation in the output string. This representation is not
|
|
portable across architectures, so it should not be used to communicate
|
|
floating point numbers across the network. The size of a floating
|
|
point number may vary across architectures, so the number of bytes
|
|
that are generated may vary. If the value overflows the
|
|
machine's native representation, then the value of FLT_MAX
|
|
as defined by the system will be used instead. Because Tcl uses
|
|
double-precision floating-point numbers internally, there may be some
|
|
loss of precision in the conversion to single-precision. For example,
|
|
on a Windows system running on an Intel Pentium processor,
|
|
<PRE><B>binary format f2 {1.6 3.4}</B></PRE>
|
|
will return a string equivalent to
|
|
<B>\xcd\xcc\xcc\x3f\x9a\x99\x59\x40</B>.
|
|
<P><DT><A NAME="M18"><B>d</B></A><DD>
|
|
This form is the same as <B>f</B> except that it stores one or more one
|
|
or more double-precision floating in the machine's native
|
|
representation in the output string. For example, on a
|
|
Windows system running on an Intel Pentium processor,
|
|
<PRE><B>binary format d1 {1.6}</B></PRE>
|
|
will return a string equivalent to
|
|
<B>\x9a\x99\x99\x99\x99\x99\xf9\x3f</B>.
|
|
<P><DT><A NAME="M19"><B>x</B></A><DD>
|
|
Stores <I>count</I> null bytes in the output string. If <I>count</I> is
|
|
not specified, stores one null byte. If <I>count</I> is <B>*</B>,
|
|
generates an error. This type does not consume an argument. For
|
|
example,
|
|
<PRE><B>binary format a3xa3x2a3 abc def ghi</B></PRE>
|
|
will return a string equivalent to <B>abc\000def\000\000ghi</B>.
|
|
<P><DT><A NAME="M20"><B>X</B></A><DD>
|
|
Moves the cursor back <I>count</I> bytes in the output string. If
|
|
<I>count</I> is <B>*</B> or is larger than the current cursor position,
|
|
then the cursor is positioned at location 0 so that the next byte
|
|
stored will be the first byte in the result string. If <I>count</I> is
|
|
omitted then the cursor is moved back one byte. This type does not
|
|
consume an argument. For example,
|
|
<PRE><B>binary format a3X*a3X2a3 abc def ghi</B></PRE>
|
|
will return <B>dghi</B>.
|
|
<P><DT><A NAME="M21"><B>@</B></A><DD>
|
|
Moves the cursor to the absolute location in the output string
|
|
specified by <I>count</I>. Position 0 refers to the first byte in the
|
|
output string. If <I>count</I> refers to a position beyond the last
|
|
byte stored so far, then null bytes will be placed in the unitialized
|
|
locations and the cursor will be placed at the specified location. If
|
|
<I>count</I> is <B>*</B>, then the cursor is moved to the current end of
|
|
the output string. If <I>count</I> is omitted, then an error will be
|
|
generated. This type does not consume an argument. For example,
|
|
<PRE><B>binary format a5@2a1@*a3@10a1 abcde f ghi j</B></PRE>
|
|
will return <B>abfdeghi\000\000j</B>.
|
|
<P></DL>
|
|
<H3><A NAME="M22">BINARY SCAN</A></H3>
|
|
The <B>binary scan</B> command parses fields from a binary string,
|
|
returning the number of conversions performed. <I>String</I> gives the
|
|
input to be parsed and <I>formatString</I> indicates how to parse it.
|
|
Each <I>varName</I> gives the name of a variable; when a field is
|
|
scanned from <I>string</I> the result is assigned to the corresponding
|
|
variable.
|
|
<P>
|
|
As with <B>binary format</B>, the <I>formatString</I> consists of a
|
|
sequence of zero or more field specifiers separated by zero or more
|
|
spaces. Each field specifier is a single type character followed by
|
|
an optional numeric <I>count</I>. Most field specifiers consume one
|
|
argument to obtain the variable into which the scanned values should
|
|
be placed. The type character specifies how the binary data is to be
|
|
interpreted. The <I>count</I> typically indicates how many items of
|
|
the specified type are taken from the data. If present, the
|
|
<I>count</I> is a non-negative decimal integer or <B>*</B>, which
|
|
normally indicates that all of the remaining items in the data are to
|
|
be used. If there are not enough bytes left after the current cursor
|
|
position to satisfy the current field specifier, then the
|
|
corresponding variable is left untouched and <B>binary scan</B> returns
|
|
immediately with the number of variables that were set. If there are
|
|
not enough arguments for all of the fields in the format string that
|
|
consume arguments, then an error is generated.
|
|
<P>
|
|
It is <B>important</B> to note that the <B>c</B>, <B>s</B>, and <B>S</B>
|
|
(and <B>i</B> and <B>I</B> on 64bit systems) will be scanned into
|
|
long data size values. In doing this, values that have their high
|
|
bit set (0x80 for chars, 0x8000 for shorts, 0x80000000 for ints),
|
|
will be sign extended. Thus the following will occur:
|
|
<PRE><B>set signShort [binary format s1 0x8000]</B>
|
|
<B>binary scan $signShort s1 val; </B><I># val == 0xFFFF8000</I></PRE>
|
|
If you want to produce an unsigned value, then you can mask the return
|
|
value to the desired size. For example, to produce an unsigned short
|
|
value:
|
|
<PRE><B>set val [expr {$val & 0xFFFF}]; </B><I># val == 0x8000</I></PRE>
|
|
<P>
|
|
Each type-count pair moves an imaginary cursor through the binary data,
|
|
reading bytes from the current position. The cursor is initially
|
|
at position 0 at the beginning of the data. The type may be any one of
|
|
the following characters:
|
|
<P>
|
|
<DL>
|
|
<P><DT><A NAME="M23"><B>a</B></A><DD>
|
|
The data is a character string of length <I>count</I>. If <I>count</I>
|
|
is <B>*</B>, then all of the remaining bytes in <I>string</I> will be
|
|
scanned into the variable. If <I>count</I> is omitted, then one
|
|
character will be scanned. For example,
|
|
<PRE><B>binary scan abcde\000fghi a6a10 var1 var2</B></PRE>
|
|
will return <B>1</B> with the string equivalent to <B>abcde\000</B>
|
|
stored in <B>var1</B> and <B>var2</B> left unmodified.
|
|
<P><DT><A NAME="M24"><B>A</B></A><DD>
|
|
This form is the same as <B>a</B>, except trailing blanks and nulls are stripped from
|
|
the scanned value before it is stored in the variable. For example,
|
|
<PRE><B>binary scan "abc efghi \000" A* var1</B></PRE>
|
|
will return <B>1</B> with <B>abc efghi</B> stored in <B>var1</B>.
|
|
<P><DT><A NAME="M25"><B>b</B></A><DD>
|
|
The data is turned into a string of <I>count</I> binary digits in
|
|
low-to-high order represented as a sequence of ``1'' and ``0''
|
|
characters. The data bytes are scanned in first to last order with
|
|
the bits being taken in low-to-high order within each byte. Any extra
|
|
bits in the last byte are ignored. If <I>count</I> is <B>*</B>, then
|
|
all of the remaining bits in <B><A HREF="../TkCmd/string.htm">string</A></B> will be scanned. If
|
|
<I>count</I> is omitted, then one bit will be scanned. For example,
|
|
<PRE><B>binary scan \x07\x87\x05 b5b* var1 var2</B></PRE>
|
|
will return <B>2</B> with <B>11100</B> stored in <B>var1</B> and
|
|
<B>1110000110100000</B> stored in <B>var2</B>.
|
|
<P><DT><A NAME="M26"><B>B</B></A><DD>
|
|
This form is the same as <B>b</B>, except the bits are taken in
|
|
high-to-low order within each byte. For example,
|
|
<PRE><B>binary scan \x70\x87\x05 B5B* var1 var2</B></PRE>
|
|
will return <B>2</B> with <B>01110</B> stored in <B>var1</B> and
|
|
<B>1000011100000101</B> stored in <B>var2</B>.
|
|
<P><DT><A NAME="M27"><B>h</B></A><DD>
|
|
The data is turned into a string of <I>count</I> hexadecimal digits in
|
|
low-to-high order represented as a sequence of characters in the set
|
|
``0123456789abcdef''. The data bytes are scanned in first to last
|
|
order with the hex digits being taken in low-to-high order within each
|
|
byte. Any extra bits in the last byte are ignored. If <I>count</I>
|
|
is <B>*</B>, then all of the remaining hex digits in <B><A HREF="../TkCmd/string.htm">string</A></B> will be
|
|
scanned. If <I>count</I> is omitted, then one hex digit will be
|
|
scanned. For example,
|
|
<PRE><B>binary scan \x07\x86\x05 h3h* var1 var2</B></PRE>
|
|
will return <B>2</B> with <B>706</B> stored in <B>var1</B> and
|
|
<B>50</B> stored in <B>var2</B>.
|
|
<P><DT><A NAME="M28"><B>H</B></A><DD>
|
|
This form is the same as <B>h</B>, except the digits are taken in
|
|
high-to-low order within each byte. For example,
|
|
<PRE><B>binary scan \x07\x86\x05 H3H* var1 var2</B></PRE>
|
|
will return <B>2</B> with <B>078</B> stored in <B>var1</B> and
|
|
<B>05</B> stored in <B>var2</B>.
|
|
<P><DT><A NAME="M29"><B>c</B></A><DD>
|
|
The data is turned into <I>count</I> 8-bit signed integers and stored
|
|
in the corresponding variable as a list. If <I>count</I> is <B>*</B>,
|
|
then all of the remaining bytes in <B><A HREF="../TkCmd/string.htm">string</A></B> will be scanned. If
|
|
<I>count</I> is omitted, then one 8-bit integer will be scanned. For
|
|
example,
|
|
<PRE><B>binary scan \x07\x86\x05 c2c* var1 var2</B></PRE>
|
|
will return <B>2</B> with <B>7 -122</B> stored in <B>var1</B> and <B>5</B>
|
|
stored in <B>var2</B>. Note that the integers returned are signed, but
|
|
they can be converted to unsigned 8-bit quantities using an expression
|
|
like:
|
|
<PRE><B>expr ( $num + 0x100 ) % 0x100</B></PRE>
|
|
<P><DT><A NAME="M30"><B>s</B></A><DD>
|
|
The data is interpreted as <I>count</I> 16-bit signed integers
|
|
represented in little-endian byte order. The integers are stored in
|
|
the corresponding variable as a list. If <I>count</I> is <B>*</B>, then
|
|
all of the remaining bytes in <B><A HREF="../TkCmd/string.htm">string</A></B> will be scanned. If
|
|
<I>count</I> is omitted, then one 16-bit integer will be scanned. For
|
|
example,
|
|
<PRE><B>binary scan \x05\x00\x07\x00\xf0\xff s2s* var1 var2</B></PRE>
|
|
will return <B>2</B> with <B>5 7</B> stored in <B>var1</B> and <B>-16</B>
|
|
stored in <B>var2</B>. Note that the integers returned are signed, but
|
|
they can be converted to unsigned 16-bit quantities using an expression
|
|
like:
|
|
<PRE><B>expr ( $num + 0x10000 ) % 0x10000</B></PRE>
|
|
<P><DT><A NAME="M31"><B>S</B></A><DD>
|
|
This form is the same as <B>s</B> except that the data is interpreted
|
|
as <I>count</I> 16-bit signed integers represented in big-endian byte
|
|
order. For example,
|
|
<PRE><B>binary scan \x00\x05\x00\x07\xff\xf0 S2S* var1 var2</B></PRE>
|
|
will return <B>2</B> with <B>5 7</B> stored in <B>var1</B> and <B>-16</B>
|
|
stored in <B>var2</B>.
|
|
<P><DT><A NAME="M32"><B>i</B></A><DD>
|
|
The data is interpreted as <I>count</I> 32-bit signed integers
|
|
represented in little-endian byte order. The integers are stored in
|
|
the corresponding variable as a list. If <I>count</I> is <B>*</B>, then
|
|
all of the remaining bytes in <B><A HREF="../TkCmd/string.htm">string</A></B> will be scanned. If
|
|
<I>count</I> is omitted, then one 32-bit integer will be scanned. For
|
|
example,
|
|
<PRE><B>binary scan \x05\x00\x00\x00\x07\x00\x00\x00\xf0\xff\xff\xff i2i* var1 var2</B></PRE>
|
|
will return <B>2</B> with <B>5 7</B> stored in <B>var1</B> and <B>-16</B>
|
|
stored in <B>var2</B>. Note that the integers returned are signed and
|
|
cannot be represented by Tcl as unsigned values.
|
|
<P><DT><A NAME="M33"><B>I</B></A><DD>
|
|
This form is the same as <B>I</B> except that the data is interpreted
|
|
as <I>count</I> 32-bit signed integers represented in big-endian byte
|
|
order. For example,
|
|
<PRE><B>binary \x00\x00\x00\x05\x00\x00\x00\x07\xff\xff\xff\xf0 I2I* var1 var2</B></PRE>
|
|
will return <B>2</B> with <B>5 7</B> stored in <B>var1</B> and <B>-16</B>
|
|
stored in <B>var2</B>.
|
|
<P><DT><A NAME="M34"><B>f</B></A><DD>
|
|
The data is interpreted as <I>count</I> single-precision floating point
|
|
numbers in the machine's native representation. The floating point
|
|
numbers are stored in the corresponding variable as a list. If
|
|
<I>count</I> is <B>*</B>, then all of the remaining bytes in
|
|
<B><A HREF="../TkCmd/string.htm">string</A></B> will be scanned. If <I>count</I> is omitted, then one
|
|
single-precision floating point number will be scanned. The size of a
|
|
floating point number may vary across architectures, so the number of
|
|
bytes that are scanned may vary. If the data does not represent a
|
|
valid floating point number, the resulting value is undefined and
|
|
compiler dependent. For example, on a Windows system running on an
|
|
Intel Pentium processor,
|
|
<PRE><B>binary scan \x3f\xcc\xcc\xcd f var1</B></PRE>
|
|
will return <B>1</B> with <B>1.6000000238418579</B> stored in
|
|
<B>var1</B>.
|
|
<P><DT><A NAME="M35"><B>d</B></A><DD>
|
|
This form is the same as <B>f</B> except that the data is interpreted
|
|
as <I>count</I> double-precision floating point numbers in the
|
|
machine's native representation. For example, on a Windows system
|
|
running on an Intel Pentium processor,
|
|
<PRE><B>binary scan \x9a\x99\x99\x99\x99\x99\xf9\x3f d var1</B></PRE>
|
|
will return <B>1</B> with <B>1.6000000000000001</B>
|
|
stored in <B>var1</B>.
|
|
<P><DT><A NAME="M36"><B>x</B></A><DD>
|
|
Moves the cursor forward <I>count</I> bytes in <I>string</I>. If
|
|
<I>count</I> is <B>*</B> or is larger than the number of bytes after the
|
|
current cursor cursor position, then the cursor is positioned after
|
|
the last byte in <I>string</I>. If <I>count</I> is omitted, then the
|
|
cursor is moved forward one byte. Note that this type does not
|
|
consume an argument. For example,
|
|
<PRE><B>binary scan \x01\x02\x03\x04 x2H* var1</B></PRE>
|
|
will return <B>1</B> with <B>0304</B> stored in <B>var1</B>.
|
|
<P><DT><A NAME="M37"><B>X</B></A><DD>
|
|
Moves the cursor back <I>count</I> bytes in <I>string</I>. If
|
|
<I>count</I> is <B>*</B> or is larger than the current cursor position,
|
|
then the cursor is positioned at location 0 so that the next byte
|
|
scanned will be the first byte in <I>string</I>. If <I>count</I>
|
|
is omitted then the cursor is moved back one byte. Note that this
|
|
type does not consume an argument. For example,
|
|
<PRE><B>binary scan \x01\x02\x03\x04 c2XH* var1 var2</B></PRE>
|
|
will return <B>2</B> with <B>1 2</B> stored in <B>var1</B> and <B>020304</B>
|
|
stored in <B>var2</B>.
|
|
<P><DT><A NAME="M38"><B>@</B></A><DD>
|
|
Moves the cursor to the absolute location in the data string specified
|
|
by <I>count</I>. Note that position 0 refers to the first byte in
|
|
<I>string</I>. If <I>count</I> refers to a position beyond the end of
|
|
<I>string</I>, then the cursor is positioned after the last byte. If
|
|
<I>count</I> is omitted, then an error will be generated. For example,
|
|
<PRE><B>binary scan \x01\x02\x03\x04 c2@1H* var1 var2</B></PRE>
|
|
will return <B>2</B> with <B>1 2</B> stored in <B>var1</B> and <B>020304</B>
|
|
stored in <B>var2</B>.
|
|
<P></DL>
|
|
<H3><A NAME="M39">PLATFORM ISSUES</A></H3>
|
|
Sometimes it is desirable to format or scan integer values in the
|
|
native byte order for the machine. Refer to the <B>byteOrder</B>
|
|
element of the <B>tcl_platform</B> array to decide which type character
|
|
to use when formatting or scanning integers.
|
|
|
|
<H3><A NAME="M40">SEE ALSO</A></H3>
|
|
<B><A HREF="../TkCmd/format.htm">format</A></B>, <B><A HREF="../TkCmd/scan.htm">scan</A></B>, <B><A HREF="../TkCmd/tclvars.htm">tclvars</A></B>
|
|
<H3><A NAME="M41">KEYWORDS</A></H3>
|
|
<A href="../Keywords/B.htm#binary">binary</A>, <A href="../Keywords/F.htm#format">format</A>, <A href="../Keywords/S.htm#scan">scan</A>
|
|
<HR><PRE>
|
|
<A HREF="../copyright.htm">Copyright</A> © 1997 by Sun Microsystems, Inc.
|
|
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
|
</BODY></HTML>
|