diff options
| -rw-r--r-- | ChangeLog | 6 | ||||
| -rw-r--r-- | doc/binary.n | 38 |
2 files changed, 26 insertions, 18 deletions
@@ -1,3 +1,9 @@ +2005-10-21 Donal K. Fellows <dkf@users.sf.net> + + * doc/binary.n: Clarify that virtually all code that uses the 'h' + format in [binary scan] should be using the 'H' format instead. It + is nearly always a bug to use the other! + 2005-10-20 Miguel Sofer <msofer@users.sf.net> * generic/tclListObj.c (TclLsetFlat): diff --git a/doc/binary.n b/doc/binary.n index f2b7155..3caf872 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.26 2005/05/10 18:33:59 kennykb Exp $ +'\" RCS: @(#) $Id: binary.n,v 1.27 2005/10/21 10:27:03 dkf Exp $ '\" .so man.macros .TH binary n 8.0 Tcl "Tcl Built-In Commands" @@ -488,32 +488,34 @@ high-to-low order within each byte. For example, will return \fB2\fR with \fB01110\fR stored in \fIvar1\fR and \fB1000011100000101\fR stored in \fIvar2\fR. .RE -.IP \fBh\fR 5 +.IP \fBH\fR 5 The data is turned into a string of \fIcount\fR 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 \fIcount\fR -is \fB*\fR, then all of the remaining hex digits in \fIstring\fR will be -scanned. If \fIcount\fR is omitted, then one hex digit will be -scanned. For example, +high-to-low 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 high-to-low order within each +byte. Any extra bits in the last byte are ignored. If \fIcount\fR is +\fB*\fR, then all of the remaining hex digits in \fIstring\fR will be +scanned. If \fIcount\fR is omitted, then one hex digit will be +scanned. For example, .RS .CS -\fBbinary scan\fR \\x07\\x86\\x05 h3h* var1 var2 +\fBbinary scan\fR \\x07\\x86\\x05\\x12\\x34 H3H* var1 var2 .CE -will return \fB2\fR with \fB706\fR stored in \fIvar1\fR and -\fB50\fR stored in \fIvar2\fR. +will return \fB2\fR with \fB078\fR stored in \fIvar1\fR and +\fB051234\fR stored in \fIvar2\fR. .RE -.IP \fBH\fR 5 -This form is the same as \fBh\fR, except the digits are taken in -high-to-low order within each byte. For example, +.IP \fBh\fR 5 +This form is the same as \fBH\fR, except the digits are taken in +reverse (low-to-high) order within each byte. For example, .RS .CS -\fBbinary scan\fR \\x07\\x86\\x05 H3H* var1 var2 +\fBbinary scan\fR \\x07\\x86\\x05\\x12\\x34 h3h* var1 var2 .CE -will return \fB2\fR with \fB078\fR stored in \fIvar1\fR and -\fB05\fR stored in \fIvar2\fR. +will return \fB2\fR with \fB706\fR stored in \fIvar1\fR and +\fB502143\fR stored in \fIvar2\fR. .RE +Note that most code that wishes to parse the hexadecimal digits from +multiple bytes in order should use the \fBH\fR format. .IP \fBc\fR 5 The data is turned into \fIcount\fR 8-bit signed integers and stored in the corresponding variable as a list. If \fIcount\fR is \fB*\fR, |