[Tcl-bugs] [ tcl-Patches-616480 ] binary command: addition to man page

[<no...@so...>]

Patches item #616480, was opened at 2002-09-30 11:56
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=310894&aid=616480&group_id=10894

Category: 15. Commands A-H
Group: None
>Status: Closed
>Resolution: Fixed
>Priority: 3
Submitted By: Arjen Markus (arjenmarkus)
Assigned to: Donal K. Fellows (dkf)
Summary: binary command: addition to man page

Initial Comment:
I find the binary command very useful for certain
tasks, yet the description of the command in the man
page is slightly confusing. Therefore I would like to
submit some additional text for the man page that, I
think, will clarify how to use it. (All the information
is there, but it is spread over the various options,
the additional text should summarise some aspects).

[binary format]
After the paragraph starting with "The formatString
consists of ..."
a new paragraph:

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.


[binary scan]
After the paragraph "As with binary format ..."

A similar example as with [binary format] should
explain the relation
between field specifiers and arguments in case of the
binary scan
subcommand:

   binary scan $bytes d3d first second

This command (provided the binary string in "bytes" is
long enough)
turns the variable "first" into a list of three numbers
and it assigns a
single value to the variable "second".


Option "a" in the section on "binary scan": explain why
variable var2 
is left unmodified (I could not quite figure it out :-)


----------------------------------------------------------------------

>Comment By: Donal K. Fellows (dkf)
Date: 2002-10-04 11:19

Message:
Logged In: YES 
user_id=79902

Thanks for this.  On the final point, part way through the
second paragraph of "BINARY SCAN" we see:
   .... If there are not enough bytes left after the current
cursor position to satisfy the current field specifier, then
the corresponding variable is left untouched and binary scan
returns immediately with the number of variables that were
set. ....
This is why var2 is unmodified; it can't get all the chars
it wants so it does nothing.  To warn you of this, [binary
scan] just returns '1' to indicate that only one field was
read from.

----------------------------------------------------------------------

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=310894&aid=616480&group_id=10894