diff options
| -rw-r--r-- | ChangeLog | 4 | ||||
| -rw-r--r-- | doc/binary.n | 192 | ||||
| -rw-r--r-- | doc/upvar.n | 23 |
3 files changed, 113 insertions, 106 deletions
@@ -1,3 +1,7 @@ +2004-11-12 Donal K. Fellows <donal.k.fellows@man.ac.uk> + + * doc/binary.n, doc/upvar.n: More minor fixes. + 2004-11-12 Daniel Steffen <das@users.sourceforge.net> * doc/CrtChannel.3: diff --git a/doc/binary.n b/doc/binary.n index a4f7008..51e9bab 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.23 2004/11/12 09:01:25 das Exp $ +'\" RCS: @(#) $Id: binary.n,v 1.24 2004/11/12 11:03:16 dkf Exp $ '\" .so man.macros .TH binary n 8.0 Tcl "Tcl Built-In Commands" @@ -48,7 +48,7 @@ that consume arguments, then an error is generated. 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 +\fBbinary format\fR d3d {1.0 2.0 3.0 4.0} 0.1 .CE .PP The first argument is a list of four numbers, but because of the count @@ -78,11 +78,11 @@ formatted. If \fIcount\fR is omitted, then one character will be formatted. For example, .RS .CS -\fBbinary format a7a*a alpha bravo charlie\fR +\fBbinary format\fR a7a*a alpha bravo charlie .CE will return a string equivalent to \fBalpha\\000\\000bravoc\fR and .CS -\fBbinary format a* [encoding convertto utf-8 \\u20ac]\fR +\fBbinary format\fR a* [encoding convertto utf-8 \\u20ac] .CE will return a string equivalent to \fB\\342\\202\\254\fR (which is the UTF-8 byte sequence for a Euro-currency character). @@ -92,7 +92,7 @@ This form is the same as \fBa\fR except that spaces are used for padding instead of nulls. For example, .RS .CS -\fBbinary format A6A*A alpha bravo charlie\fR +\fBbinary format\fR A6A*A alpha bravo charlie .CE will return \fBalpha bravoc\fR. .RE @@ -111,7 +111,7 @@ does not end at a byte boundary, the remaining bits of the last byte will be zeros. For example, .RS .CS -\fBbinary format b5b* 11100 111000011010\fR +\fBbinary format\fR b5b* 11100 111000011010 .CE will return a string equivalent to \fB\\x07\\x87\\x05\fR. .RE @@ -120,7 +120,7 @@ This form is the same as \fBb\fR except that the bits are stored in high-to-low order within each byte. For example, .RS .CS -\fBbinary format B5B* 11100 111000011010\fR +\fBbinary format\fR B5B* 11100 111000011010 .CE will return a string equivalent to \fB\\xe0\\xe1\\xa0\fR. .RE @@ -139,7 +139,7 @@ number of digits formatted does not end at a byte boundary, the remaining bits of the last byte will be zeros. For example, .RS .CS -\fBbinary format h3h* AB def\fR +\fBbinary format\fR h3h* AB def .CE will return a string equivalent to \fB\\xba\\x00\\xed\\x0f\fR. .RE @@ -148,7 +148,7 @@ This form is the same as \fBh\fR except that the digits are stored in high-to-low order within each byte. For example, .RS .CS -\fBbinary format H3H* ab DEF\fR +\fBbinary format\fR H3H* ab DEF .CE will return a string equivalent to \fB\\xab\\x00\\xde\\xf0\fR. .RE @@ -164,12 +164,12 @@ error is generated. If the number of elements in the list is greater than \fIcount\fR, then the extra elements are ignored. For example, .RS .CS -\fBbinary format c3cc* {3 -3 128 1} 260 {2 5}\fR +\fBbinary format\fR c3cc* {3 -3 128 1} 260 {2 5} .CE will return a string equivalent to \fB\\x03\\xfd\\x80\\x04\\x02\\x05\fR, whereas .CS -\fBbinary format c {2 5}\fR +\fBbinary format\fR c {2 5} .CE will generate an error. .RE @@ -181,7 +181,7 @@ the cursor position with the least significant byte stored first. For example, .RS .CS -\fBbinary format s3 {3 -3 258 1}\fR +\fBbinary format\fR s3 {3 -3 258 1} .CE will return a string equivalent to \fB\\x03\\x00\\xfd\\xff\\x02\\x01\fR. @@ -192,7 +192,7 @@ This form is the same as \fBs\fR except that it stores one or more example, .RS .CS -\fBbinary format S3 {3 -3 258 1}\fR +\fBbinary format\fR S3 {3 -3 258 1} .CE will return a string equivalent to \fB\\x00\\x03\\xff\\xfd\\x01\\x02\fR. @@ -213,7 +213,7 @@ the cursor position with the least significant byte stored first. For example, .RS .CS -\fBbinary format i3 {3 -3 65536 1}\fR +\fBbinary format\fR i3 {3 -3 65536 1} .CE will return a string equivalent to \fB\\x03\\x00\\x00\\x00\\xfd\\xff\\xff\\xff\\x00\\x00\\x01\\x00\fR @@ -224,7 +224,7 @@ or more 32-bit integers in big-endian byte order in the output string. For example, .RS .CS -\fBbinary format I3 {3 -3 65536 1}\fR +\fBbinary format\fR I3 {3 -3 65536 1} .CE will return a string equivalent to \fB\\x00\\x00\\x00\\x03\\xff\\xff\\xff\\xfd\\x00\\x01\\x00\\x00\fR @@ -246,7 +246,7 @@ the cursor position with the least significant byte stored first. For example, .RS .CS -\fBbinary format w 7810179016327718216\fR +\fBbinary format\fR w 7810179016327718216 .CE will return the string \fBHelloTcl\fR .RE @@ -256,7 +256,7 @@ or more 64-bit integers in big-endian byte order in the output string. For example, .RS .CS -\fBbinary format Wc 4785469626960341345 110\fR +\fBbinary format\fR Wc 4785469626960341345 110 .CE will return the string \fBBigEndian\fR .RE @@ -284,7 +284,7 @@ loss of precision in the conversion to single-precision. For example, on a Windows system running on an Intel Pentium processor, .RS .CS -\fBbinary format f2 {1.6 3.4}\fR +\fBbinary format\fR f2 {1.6 3.4} .CE will return a string equivalent to \fB\\xcd\\xcc\\xcc\\x3f\\x9a\\x99\\x59\\x40\fR. @@ -309,7 +309,7 @@ representation in the output string. For example, on a Windows system running on an Intel Pentium processor, .RS .CS -\fBbinary format d1 {1.6}\fR +\fBbinary format\fR d1 {1.6} .CE will return a string equivalent to \fB\\x9a\\x99\\x99\\x99\\x99\\x99\\xf9\\x3f\fR. @@ -334,7 +334,7 @@ generates an error. This type does not consume an argument. For example, .RS .CS -\fBbinary format a3xa3x2a3 abc def ghi\fR +\fBbinary format\fR a3xa3x2a3 abc def ghi .CE will return a string equivalent to \fBabc\\000def\\000\\000ghi\fR. .RE @@ -347,7 +347,7 @@ omitted then the cursor is moved back one byte. This type does not consume an argument. For example, .RS .CS -\fBbinary format a3X*a3X2a3 abc def ghi\fR +\fBbinary format\fR a3X*a3X2a3 abc def ghi .CE will return \fBdghi\fR. .RE @@ -362,7 +362,7 @@ the output string. If \fIcount\fR is omitted, then an error will be generated. This type does not consume an argument. For example, .RS .CS -\fBbinary format a5@2a1@*a3@10a1 abcde f ghi j\fR +\fBbinary format\fR a5@2a1@*a3@10a1 abcde f ghi j .CE will return \fBabfdeghi\\000\\000j\fR. .RE @@ -396,7 +396,7 @@ 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 s3s first second\fR +\fBbinary scan\fR $bytes s3s first second .CE .PP This command (provided the binary string in the variable \fIbytes\fR @@ -407,31 +407,31 @@ integers), no assignment to \fIsecond\fR will be made, and if \fIbytes\fR contains fewer than 6 bytes (i.e. three 2-byte integers), no assignment to \fIfirst\fR will be made. Hence: .CS -\fBputs [binary scan abcdefg s3s first second]\fR -\fBputs $first\fR -\fBputs $second\fR +puts [\fBbinary scan\fR abcdefg s3s first second] +puts $first +puts $second .CE will print (assuming neither variable is set previously): .CS -\fB1\fR -\fB25185 25699 26213\fR -\fIcan't read "second": no such variable\fR +1 +25185 25699 26213 +can't read "second": no such variable .CE .PP -It is \fBimportant\fR to note that the \fBc\fR, \fBs\fR, and \fBS\fR +It is \fIimportant\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 bit set (0x80 for chars, 0x8000 for shorts, 0x80000000 for ints), will be sign extended. Thus the following will occur: .CS -\fBset signShort [binary format s1 0x8000]\fR -\fBbinary scan $signShort s1 val; \fI# val == 0xFFFF8000\fR +set signShort [\fBbinary format\fR s1 0x8000] +\fBbinary scan\fR $signShort s1 val; \fI# val == 0xFFFF8000\fR .CE If you want to produce an unsigned value, then you can mask the return value to the desired size. For example, to produce an unsigned short value: .CS -\fBset val [expr {$val & 0xFFFF}]; \fI# val == 0x8000\fR +set val [expr {$val & 0xFFFF}]; \fI# val == 0x8000\fR .CE .PP Each type-count pair moves an imaginary cursor through the binary data, @@ -449,19 +449,19 @@ needed if the string is not an ISO 8859\-1 string. For example, .RS .CS -\fBbinary scan abcde\\000fghi a6a10 var1 var2\fR +\fBbinary scan\fR abcde\\000fghi a6a10 var1 var2 .CE will return \fB1\fR with the string equivalent to \fBabcde\\000\fR -stored in \fBvar1\fR and \fBvar2\fR left unmodified. +stored in \fIvar1\fR and \fIvar2\fR left unmodified. .RE .IP \fBA\fR 5 This form is the same as \fBa\fR, except trailing blanks and nulls are stripped from the scanned value before it is stored in the variable. For example, .RS .CS -\fBbinary scan "abc efghi \\000" A* var1\fR +\fBbinary scan\fR "abc efghi \\000" A* var1 .CE -will return \fB1\fR with \fBabc efghi\fR stored in \fBvar1\fR. +will return \fB1\fR with \fBabc efghi\fR stored in \fIvar1\fR. .RE .IP \fBb\fR 5 The data is turned into a string of \fIcount\fR binary digits in @@ -469,24 +469,24 @@ low-to-high order represented as a sequence of ``1'' and ``0'' characters. The data bytes are scanned in first to last order with the bits 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 bits in \fBstring\fR will be scanned. If +all of the remaining bits in \fIstring\fR will be scanned. If \fIcount\fR is omitted, then one bit will be scanned. For example, .RS .CS -\fBbinary scan \\x07\\x87\\x05 b5b* var1 var2\fR +\fBbinary scan\fR \\x07\\x87\\x05 b5b* var1 var2 .CE -will return \fB2\fR with \fB11100\fR stored in \fBvar1\fR and -\fB1110000110100000\fR stored in \fBvar2\fR. +will return \fB2\fR with \fB11100\fR stored in \fIvar1\fR and +\fB1110000110100000\fR stored in \fIvar2\fR. .RE .IP \fBB\fR 5 This form is the same as \fBb\fR, except the bits are taken in high-to-low order within each byte. For example, .RS .CS -\fBbinary scan \\x70\\x87\\x05 B5B* var1 var2\fR +\fBbinary scan\fR \\x70\\x87\\x05 B5B* var1 var2 .CE -will return \fB2\fR with \fB01110\fR stored in \fBvar1\fR and -\fB1000011100000101\fR stored in \fBvar2\fR. +will return \fB2\fR with \fB01110\fR stored in \fIvar1\fR and +\fB1000011100000101\fR stored in \fIvar2\fR. .RE .IP \fBh\fR 5 The data is turned into a string of \fIcount\fR hexadecimal digits in @@ -494,61 +494,61 @@ 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 \fBstring\fR will be +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 \\x07\\x86\\x05 h3h* var1 var2\fR +\fBbinary scan\fR \\x07\\x86\\x05 h3h* var1 var2 .CE -will return \fB2\fR with \fB706\fR stored in \fBvar1\fR and -\fB50\fR stored in \fBvar2\fR. +will return \fB2\fR with \fB706\fR stored in \fIvar1\fR and +\fB50\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, .RS .CS -\fBbinary scan \\x07\\x86\\x05 H3H* var1 var2\fR +\fBbinary scan\fR \\x07\\x86\\x05 H3H* var1 var2 .CE -will return \fB2\fR with \fB078\fR stored in \fBvar1\fR and -\fB05\fR stored in \fBvar2\fR. +will return \fB2\fR with \fB078\fR stored in \fIvar1\fR and +\fB05\fR stored in \fIvar2\fR. .RE .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, -then all of the remaining bytes in \fBstring\fR will be scanned. If +then all of the remaining bytes in \fIstring\fR will be scanned. If \fIcount\fR is omitted, then one 8-bit integer will be scanned. For example, .RS .CS -\fBbinary scan \\x07\\x86\\x05 c2c* var1 var2\fR +\fBbinary scan\fR \\x07\\x86\\x05 c2c* var1 var2 .CE -will return \fB2\fR with \fB7 -122\fR stored in \fBvar1\fR and \fB5\fR -stored in \fBvar2\fR. Note that the integers returned are signed, but +will return \fB2\fR with \fB7 -122\fR stored in \fIvar1\fR and \fB5\fR +stored in \fIvar2\fR. Note that the integers returned are signed, but they can be converted to unsigned 8-bit quantities using an expression like: .CS -\fBexpr ( $num + 0x100 ) % 0x100\fR +expr { ( $num + 0x100 ) % 0x100 } .CE .RE .IP \fBs\fR 5 The data is interpreted as \fIcount\fR 16-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 +all of the remaining bytes in \fIstring\fR will be scanned. If \fIcount\fR is omitted, then one 16-bit integer will be scanned. For example, .RS .CS -\fBbinary scan \\x05\\x00\\x07\\x00\\xf0\\xff s2s* var1 var2\fR +\fBbinary scan\fR \\x05\\x00\\x07\\x00\\xf0\\xff s2s* var1 var2 .CE -will return \fB2\fR with \fB5 7\fR stored in \fBvar1\fR and \fB-16\fR -stored in \fBvar2\fR. Note that the integers returned are signed, but +will return \fB2\fR with \fB5 7\fR stored in \fIvar1\fR and \fB-16\fR +stored in \fIvar2\fR. Note that the integers returned are signed, but they can be converted to unsigned 16-bit quantities using an expression like: .CS -\fBexpr ( $num + 0x10000 ) % 0x10000\fR +expr { ( $num + 0x10000 ) % 0x10000 } .CE .RE .IP \fBS\fR 5 @@ -557,10 +557,10 @@ as \fIcount\fR 16-bit signed integers represented in big-endian byte order. For example, .RS .CS -\fBbinary scan \\x00\\x05\\x00\\x07\\xff\\xf0 S2S* var1 var2\fR +\fBbinary scan\fR \\x00\\x05\\x00\\x07\\xff\\xf0 S2S* var1 var2 .CE -will return \fB2\fR with \fB5 7\fR stored in \fBvar1\fR and \fB-16\fR -stored in \fBvar2\fR. +will return \fB2\fR with \fB5 7\fR stored in \fIvar1\fR and \fB-16\fR +stored in \fIvar2\fR. .RE .IP \fBt\fR 5 .VS 8.5 @@ -574,15 +574,16 @@ the \fBbyteOrder\fR element of the \fBtcl_platform\fR array. The data is interpreted as \fIcount\fR 32-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 +all of the remaining bytes in \fIstring\fR will be scanned. If \fIcount\fR is omitted, then one 32-bit integer will be scanned. For example, .RS .CS -\fBbinary scan \\x05\\x00\\x00\\x00\\x07\\x00\\x00\\x00\\xf0\\xff\\xff\\xff i2i* var1 var2\fR +set str \\x05\\x00\\x00\\x00\\x07\\x00\\x00\\x00\\xf0\\xff\\xff\\xff +\fBbinary scan\fR $str i2i* var1 var2 .CE -will return \fB2\fR with \fB5 7\fR stored in \fBvar1\fR and \fB-16\fR -stored in \fBvar2\fR. Note that the integers returned are signed and +will return \fB2\fR with \fB5 7\fR stored in \fIvar1\fR and \fB-16\fR +stored in \fIvar2\fR. Note that the integers returned are signed and cannot be represented by Tcl as unsigned values. .RE .IP \fBI\fR 5 @@ -591,10 +592,11 @@ as \fIcount\fR 32-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 I2I* var1 var2\fR +set str \\x00\\x00\\x00\\x05\\x00\\x00\\x00\\x07\\xff\\xff\\xff\\xf0 +\fBbinary scan\fR $str I2I* var1 var2 .CE -will return \fB2\fR with \fB5 7\fR stored in \fBvar1\fR and \fB-16\fR -stored in \fBvar2\fR. +will return \fB2\fR with \fB5 7\fR stored in \fIvar1\fR and \fB-16\fR +stored in \fIvar2\fR. .RE .IP \fBn\fR 5 .VS 8.5 @@ -608,15 +610,16 @@ the \fBbyteOrder\fR element of the \fBtcl_platform\fR array. 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 +all of the remaining bytes in \fIstring\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 +set str \\x05\\x00\\x00\\x00\\x07\\x00\\x00\\x00\\xf0\\xff\\xff\\xff +\fBbinary scan\fR $str wi* var1 var2 .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 +will return \fB2\fR with \fB30064771077\fR stored in \fIvar1\fR and +\fB-16\fR stored in \fIvar2\fR. Note that the integers returned are signed and cannot be represented by Tcl as unsigned values. .RE .IP \fBW\fR 5 @@ -625,10 +628,11 @@ 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 +set str \\x00\\x00\\x00\\x05\\x00\\x00\\x00\\x07\\xff\\xff\\xff\\xf0 +\fBbinary scan\fR $str WI* var1 var2 .CE -will return \fB2\fR with \fB21474836487\fR stored in \fBvar1\fR and \fB-16\fR -stored in \fBvar2\fR. +will return \fB2\fR with \fB21474836487\fR stored in \fIvar1\fR and \fB-16\fR +stored in \fIvar2\fR. .RE .IP \fBm\fR 5 .VS 8.5 @@ -643,7 +647,7 @@ The data is interpreted as \fIcount\fR single-precision floating point numbers in the machine's native representation. The floating point numbers 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 +\fIstring\fR will be scanned. If \fIcount\fR is omitted, then one single-precision floating point number will be scanned. The size of a floating point number may vary across architectures, so the number of bytes that are scanned may vary. If the data does not represent a @@ -652,10 +656,10 @@ compiler dependent. For example, on a Windows system running on an Intel Pentium processor, .RS .CS -\fBbinary scan \\x3f\\xcc\\xcc\\xcd f var1\fR +\fBbinary scan\fR \\x3f\\xcc\\xcc\\xcd f var1 .CE will return \fB1\fR with \fB1.6000000238418579\fR stored in -\fBvar1\fR. +\fIvar1\fR. .RE .IP \fBr\fR 5 .VS 8.5 @@ -678,10 +682,10 @@ machine's native representation. For example, on a Windows system running on an Intel Pentium processor, .RS .CS -\fBbinary scan \\x9a\\x99\\x99\\x99\\x99\\x99\\xf9\\x3f d var1\fR +\fBbinary scan\fR \\x9a\\x99\\x99\\x99\\x99\\x99\\xf9\\x3f d var1 .CE will return \fB1\fR with \fB1.6000000000000001\fR -stored in \fBvar1\fR. +stored in \fIvar1\fR. .RE .IP \fBq\fR 5 .VS 8.5 @@ -706,9 +710,9 @@ cursor is moved forward one byte. Note that this type does not consume an argument. For example, .RS .CS -\fBbinary scan \\x01\\x02\\x03\\x04 x2H* var1\fR +\fBbinary scan\fR \\x01\\x02\\x03\\x04 x2H* var1 .CE -will return \fB1\fR with \fB0304\fR stored in \fBvar1\fR. +will return \fB1\fR with \fB0304\fR stored in \fIvar1\fR. .RE .IP \fBX\fR 5 Moves the cursor back \fIcount\fR bytes in \fIstring\fR. If @@ -719,10 +723,10 @@ is omitted then the cursor is moved back one byte. Note that this type does not consume an argument. For example, .RS .CS -\fBbinary scan \\x01\\x02\\x03\\x04 c2XH* var1 var2\fR +\fBbinary scan\fR \\x01\\x02\\x03\\x04 c2XH* var1 var2 .CE -will return \fB2\fR with \fB1 2\fR stored in \fBvar1\fR and \fB020304\fR -stored in \fBvar2\fR. +will return \fB2\fR with \fB1 2\fR stored in \fIvar1\fR and \fB020304\fR +stored in \fIvar2\fR. .RE .IP \fB@\fR 5 Moves the cursor to the absolute location in the data string specified @@ -732,10 +736,10 @@ by \fIcount\fR. Note that position 0 refers to the first byte in \fIcount\fR is omitted, then an error will be generated. For example, .RS .CS -\fBbinary scan \\x01\\x02\\x03\\x04 c2@1H* var1 var2\fR +\fBbinary scan\fR \\x01\\x02\\x03\\x04 c2@1H* var1 var2 .CE -will return \fB2\fR with \fB1 2\fR stored in \fBvar1\fR and \fB020304\fR -stored in \fBvar2\fR. +will return \fB2\fR with \fB1 2\fR stored in \fIvar1\fR and \fB020304\fR +stored in \fIvar2\fR. .RE .SH "PORTABILITY ISSUES" The \fBr\fR, \fBR\fR, \fBq\fR and \fBQ\fR conversions will only work @@ -748,7 +752,7 @@ architectures, use their textual representation (as produced by This is a procedure to write a Tcl string to a binary-encoded channel as UTF-8 data preceded by a length word: .CS -proc writeString {channel string} { +proc \fIwriteString\fR {channel string} { set data [encoding convertto utf-8 $string] puts -nonewline [\fBbinary format\fR Ia* \e [string length $data] $data] @@ -756,9 +760,9 @@ proc writeString {channel string} { .CE .PP This procedure reads a string from a channel that was written by the -previously presented \fBwriteString\fR procedure: +previously presented \fIwriteString\fR procedure: .CS -proc readString {channel} { +proc \fIreadString\fR {channel} { if {![\fBbinary scan\fR [read $channel 4] I length]} { error "missing length" } diff --git a/doc/upvar.n b/doc/upvar.n index 145adf9..15fc3b8 100644 --- a/doc/upvar.n +++ b/doc/upvar.n @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: upvar.n,v 1.9 2004/11/12 09:01:25 das Exp $ +'\" RCS: @(#) $Id: upvar.n,v 1.10 2004/11/12 11:03:16 dkf Exp $ '\" .so man.macros .TH upvar n "" Tcl "Tcl Built-In Commands" @@ -46,14 +46,14 @@ procedure calling and also makes it easier to build new control constructs as Tcl procedures. For example, consider the following procedure: .CS -proc \fBadd2\fR name { +proc \fIadd2\fR name { \fBupvar\fR $name x - set x [expr $x+2] + set x [expr {$x + 2}] } .CE -\fBadd2\fR is invoked with an argument giving the name of a variable, -and it adds two to the value of that variable. -Although \fBadd2\fR could have been implemented using \fBuplevel\fR +If \fIadd2\fR is invoked with an argument giving the name of a variable, +it adds two to the value of that variable. +Although \fIadd2\fR could have been implemented using \fBuplevel\fR instead of \fBupvar\fR, \fBupvar\fR makes it simpler for \fBadd2\fR to access the variable in the caller's procedure frame. .PP @@ -82,19 +82,18 @@ unexpected manner. If a variable trace is defined on \fIotherVar\fR, that trace will be triggered by actions involving \fImyVar\fR. However, the trace procedure will be passed the name of \fImyVar\fR, rather than the name of \fIotherVar\fR. Thus, the output of the following code -will be \fBlocalVar\fR rather than \fBoriginalVar\fR: +will be "\fIlocalVar\fR" rather than "\fIoriginalVar\fR": .CS -proc \fBtraceproc\fR { name index op } { +proc \fItraceproc\fR { name index op } { puts $name } -proc \fBsetByUpvar\fR { name value } { +proc \fIsetByUpvar\fR { name value } { \fBupvar\fR $name localVar set localVar $value } set originalVar 1 -trace variable originalVar w \fBtraceproc\fR -\fBsetByUpvar\fR originalVar 2 -} +trace variable originalVar w \fItraceproc\fR +\fIsetByUpvar\fR originalVar 2 .CE .PP If \fIotherVar\fR refers to an element of an array, then variable |