Author:         Arjen Markus <arjen.markus895@gmail.com>
Author:         Donal K. Fellows <donal.k.fellows@manchester.ac.uk>
State:          Draft
Type:           Project
Vote:           Pending
Created:        18-Jul-2016
Post-History: 
Tcl-Version:    8.7
Keywords:       Tcl, binary data
Tcl-Branch:     tip-450

Abstract

This TIP proposes a simpler extension of the binary command than the related [418], namely just a subcommand set that updates an existing byte array in a variable instead of creating a new one like binary format. It does not propose an extension of the various formatting codes.

Rationale

As already argued in [418], the binary command is efficient in creating new objects of binary data or in parsing existing objects with such data. It is not currently efficient in updating existing objects. However, such data objects are commonly used by compiled extensions.

As a consequence, if you want to manipulate such data objects from Tcl directly, it is easier to parse the object into, say, a list of numbers, use list commands like lset to replace individual values and pack it into a new binary array before passing it to a compiled extension.

Specification

This TIP proposes to add a subcommand set to the binary command with the following signature:

binary set varName formatString arg1 arg2 arg3 ...

The effect of this subcommand is that the byte array data contained in the variable "varName" is updated in a manner analogous to lset, but using a format string like binary format. It could be implemented in Tcl as:

set varName [binary format "a*$formatString" $varName $arg1 $arg2 $arg3 ...]

except that this allocates a new block of memory, sets that to null, copies the contents of varName into that new block and then does the update.

The new command will have the effect that the first few steps are not necessary anymore.

Implementation Notes

Besides the nominal case of a variable that contains a binary array that is to be updated within the bounds of that array, four other cases exist and need to be prepared for:

The variable varName does not exist yet: we must create the variable when writing back the binary value.
The variable varName does not contain a binary string: we must convert the variable to a binary string (using the usual algorithm).
The variable varName contains a binary string that is shared with other uses (such as being stored in other variables): we must duplicate the binary string in this case before updating it.
The updating would go past the memory allocated for the binary array: we must extend the binary array.

It is the Tcl programmer's responsibility to avoid these cases if they matter to them. The binary set command will act in accordance with existing Tcl standard semantics.

Reference Implementation

See the tip-450 branch.

Copyright