diff options
Diffstat (limited to 'tcl/doc/binary.n')
| -rw-r--r-- | tcl/doc/binary.n | 69 |
1 files changed, 60 insertions, 9 deletions
diff --git a/tcl/doc/binary.n b/tcl/doc/binary.n index f21d691e4ae..07ab50fce7d 100644 --- a/tcl/doc/binary.n +++ b/tcl/doc/binary.n @@ -22,11 +22,11 @@ binary \- Insert and extract fields from binary strings .PP This command provides facilities for manipulating binary data. The first form, \fBbinary format\fR, creates a binary string from normal -Tcl values. For example, given the values 16 and 22, 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, -\fBbinary scan\fR, does the opposite: it extracts data from a binary -string and returns it as ordinary Tcl string values. +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, \fBbinary scan\fR, does the opposite: it extracts data +from a binary string and returns it as ordinary Tcl string values. .SH "BINARY FORMAT" .PP @@ -199,6 +199,30 @@ For example, will return a string equivalent to \fB\\x00\\x00\\x00\\x03\\xff\\xff\\xff\\xfd\\x00\\x01\\x00\\x00\fR .RE +.IP \fBw\fR 5 +.VS 8.4 +This form is the same as \fBw\fR except that it stores one or more +64-bit integers in little-endian byte order in the output string. The +low-order 64-bits of each integer are stored as an eight-byte value at +the cursor position with the least significant byte stored first. For +example, +.RS +.CS +\fBbinary format w 7810179016327718216\fR +.CE +will return the string \fBHelloTcl\fR +.RE +.IP \fBW\fR 5 +This form is the same as \fBw\fR except that it stores one or more one +or more 64-bit integers in big-endian byte order in the output string. +For example, +.RS +.CS +\fBbinary format W 4785469626960341345\fR +.CE +will return the string \fBBigEndian\fR +.VE +.RE .IP \fBf\fR 5 This form is the same as \fBc\fR except that it stores one or more one or more single-precision floating in the machine's native @@ -259,7 +283,7 @@ will return \fBdghi\fR. Moves the cursor to the absolute location in the output string specified by \fIcount\fR. Position 0 refers to the first byte in the output string. If \fIcount\fR refers to a position beyond the last -byte stored so far, then null bytes will be placed in the unitialized +byte stored so far, then null bytes will be placed in the uninitialized locations and the cursor will be placed at the specified location. If \fIcount\fR is \fB*\fR, then the cursor is moved to the current end of the output string. If \fIcount\fR is omitted, then an error will be @@ -458,11 +482,39 @@ as \fIcount\fR 32-bit signed integers represented in big-endian byte order. For example, .RS .CS -\fBbinary \\x00\\x00\\x00\\x05\\x00\\x00\\x00\\x07\\xff\\xff\\xff\\xf0 I2I* var1 var2\fR +\fBbinary scan \\x00\\x00\\x00\\x05\\x00\\x00\\x00\\x07\\xff\\xff\\xff\\xf0 I2I* var1 var2\fR .CE will return \fB2\fR with \fB5 7\fR stored in \fBvar1\fR and \fB-16\fR stored in \fBvar2\fR. .RE +.IP \fBw\fR 5 +.VS 8.4 +The data is interpreted as \fIcount\fR 64-bit signed integers +represented in little-endian byte order. The integers are stored in +the corresponding variable as a list. If \fIcount\fR is \fB*\fR, then +all of the remaining bytes in \fBstring\fR will be scanned. If +\fIcount\fR is omitted, then one 64-bit integer will be scanned. For +example, +.RS +.CS +\fBbinary scan \\x05\\x00\\x00\\x00\\x07\\x00\\x00\\x00\\xf0\\xff\\xff\\xff wi* var1 var2\fR +.CE +will return \fB2\fR with \fB30064771077\fR stored in \fBvar1\fR and +\fB-16\fR stored in \fBvar2\fR. Note that the integers returned are +signed and cannot be represented by Tcl as unsigned values. +.RE +.IP \fBW\fR 5 +This form is the same as \fBw\fR except that the data is interpreted +as \fIcount\fR 64-bit signed integers represented in big-endian byte +order. For example, +.RS +.CS +\fBbinary scan \\x00\\x00\\x00\\x05\\x00\\x00\\x00\\x07\\xff\\xff\\xff\\xf0 WI* var1 var2\fR +.CE +will return \fB2\fR with \fB21474836487\fR stored in \fBvar1\fR and \fB-16\fR +stored in \fBvar2\fR. +.VE +.RE .IP \fBf\fR 5 The data is interpreted as \fIcount\fR single-precision floating point numbers in the machine's native representation. The floating point @@ -542,8 +594,7 @@ element of the \fBtcl_platform\fR array to decide which type character to use when formatting or scanning integers. .SH "SEE ALSO" -format, scan, tclvars +format(n), scan(n), tclvars(n) .SH KEYWORDS binary, format, scan - |