diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/binary.n | 29 |
1 files changed, 28 insertions, 1 deletions
diff --git a/doc/binary.n b/doc/binary.n index 82a3631..7064b99 100644 --- a/doc/binary.n +++ b/doc/binary.n @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: binary.n,v 1.9 2002/07/01 18:24:39 jenglish Exp $ +'\" RCS: @(#) $Id: binary.n,v 1.10 2002/10/04 10:23:33 dkf Exp $ '\" .so man.macros .TH binary n 8.0 Tcl "Tcl Built-In Commands" @@ -46,6 +46,18 @@ 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. .PP +Here is a small example to clarify the relation between the field +specifiers and the arguments: +.CS +\fBbinary format d3d {1.0 2.0 3.0 4.0} 0.1\fR +.CE +.PP +The first argument is a list of four numbers, but because of the count +of 3 for the associated field specifier, only the first three will be +used. The second argument is associated with the second field +specifier. The resulting binary string contains the four numbers 10, +2.0, 3.0 and 0.1. +.PP 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 @@ -321,6 +333,21 @@ 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. .PP +A similar example as with \fBbinary format\fR should explain the +relation between field specifiers and arguments in case of the binary +scan subcommand: +.CS +\fBbinary scan $bytes i3i first second\fR +.CE +.PP +This command (provided the binary string in the variable \fIbytes\fR +is long enough) assigns a list of three integers to the variable +\fIfirst\fR and assigns a single value to the variable \fIsecond\fR. +If \fIbytes\fR contains fewer than 16 bytes (i.e. four 4-byte +integers), no assignment to \fIsecond\fR will be made, and if +\fIbytes\fR contains fewer than 12 bytes (i.e. three 4-byte integers), +no assignment to \fIfirst\fR will be made. +.PP It is \fBimportant\fR to note that the \fBc\fR, \fBs\fR, and \fBS\fR (and \fBi\fR and \fBI\fR on 64bit systems) will be scanned into long data size values. In doing this, values that have their high |