Version 3 of binary format

Updated 2004-07-27 13:24:58 by RJM

binary format formatString ?arg arg ...?

The binary format command generates a binary string whose layout is specified by the formatString and whose contents come from the additional arguments. The resulting binary value is returned.

The formatString 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 count. 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 count typically indicates how many items of the specified type are taken from the value. If present, the count is a non-negative decimal integer or *, 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.

The binary format command takes tcl values, converts them into binary values according to the commands in the format string, concatenates them and then returns this binary string as its result.

Here is a small example to clarify the relation between the field specifiers and the arguments:

 binary format d3d {1.0 2.0 3.0 4.0} 0.1

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.

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.

See also:

RJM asks (2004-07-27): What about sending numeric expression results as binary representation to files or communication channels? It can be coded this way (example with one and two values to being sent):

 puts $fid [binary format S1 [expr {...}]]
 puts $fid [binary format S2 "[expr {...}] [expr {...}]"]

Contrary to the simple case of

 set a [expr {...}]

where no intermediate number<->string conversions takes place, since smart Tcl writes the real or int value result directly in a. However, conversion to binary output seems to involve string conversion (expr result) and then conversion to binary during binary format execution, as time investigations seem to confirm. binary scan does not necessarily have this superfluous string conversion, because the command provides a reference to a target variable and hence can handle the processing from source (binary) to target (binary representation) monolithically.

Expert contributions very welcome!

Tcl syntax help - Category Command