summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authordkf <donal.k.fellows@manchester.ac.uk>2005-10-21 10:27:02 (GMT)
committerdkf <donal.k.fellows@manchester.ac.uk>2005-10-21 10:27:02 (GMT)
commitdacbf9e09166753bf47d7f39ac5131efbd93daf5 (patch)
tree539900f1340ec0ded7b77435b7174a7d9e6548f6
parenta0feec1fb2a5f9df57b07ec94fb444727887574b (diff)
downloadtcl-dacbf9e09166753bf47d7f39ac5131efbd93daf5.zip
tcl-dacbf9e09166753bf47d7f39ac5131efbd93daf5.tar.gz
tcl-dacbf9e09166753bf47d7f39ac5131efbd93daf5.tar.bz2
Improve the documentation of [binary scan] a little.
-rw-r--r--ChangeLog6
-rw-r--r--doc/binary.n38
2 files changed, 26 insertions, 18 deletions
diff --git a/ChangeLog b/ChangeLog
index cb999e0..b76ae62 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -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,