NAME
Tcl_NewByteArrayObj, Tcl_SetByteArrayObj, Tcl_GetByteAr
rayFromObj, Tcl_SetByteArrayLength - manipulate Tcl
objects as a arrays of bytes
SYNOPSIS
#include <tcl.h>
Tcl_Obj *
Tcl_NewByteArrayObj(bytes, length)
void
Tcl_SetByteArrayObj(objPtr, bytes, length)
unsigned char *
Tcl_GetByteArrayFromObj(objPtr, lengthPtr)
unsigned char *
Tcl_SetByteArrayLength(objPtr, length)
ARGUMENTS
unsigned char *bytes (in) The array of bytes
used to initialize
or set a byte-array
object.
int length (in) The length of the
array of bytes. It
must be >= 0.
Tcl_Obj *objPtr (in/out) For Tcl_SetByteAr
rayObj, this points
to the object to be
converted to byte-
array type. For
Tcl_GetByteAr
rayFromObj and
Tcl_SetByteAr
rayLength, this
points to the
object from which
to get the byte-
array value; if
objPtr does not
already point to a
byte-array object,
it will be con
verted to one.
int *lengthPtr (out) If non-NULL, filled
with the length of
the array of bytes
_________________________________________________________________
DESCRIPTION
These procedures are used to create, modify, and read Tcl
byte-array objects from C code. Byte-array objects are
typically used to hold the results of binary IO operations
or data structures created with the binary command. In
Tcl, an array of bytes is not equivalent to a string.
Conceptually, a string is an array of Unicode characters,
while a byte-array is an array of 8-bit quantities with no
implicit meaning. Accesser functions are provided to get
the string representation of a byte-array or to convert an
arbitrary object to a byte-array. Obtaining the string
representation of a byte-array object (by calling Tcl_Get
StringFromObj) produces a properly formed UTF-8 sequence
with a one-to-one mapping between the bytes in the inter
nal representation and the UTF-8 characters in the string
representation.
Tcl_NewByteArrayObj and Tcl_SetByteArrayObj will create a
new object of byte-array type or modify an existing object
to have a byte-array type. Both of these procedures set
the object's type to be byte-array and set the object's
internal representation to a copy of the array of bytes
given by bytes. Tcl_NewByteArrayObj returns a pointer to a
newly allocated object with a reference count of zero.
Tcl_SetByteArrayObj invalidates any old string representa
tion and, if the object is not already a byte-array
object, frees any old internal representation.
Tcl_GetByteArrayFromObj converts a Tcl object to byte-
array type and returns a pointer to the object's new
internal representation as an array of bytes. The length
of this array is stored in lengthPtr if lengthPtr is non-
NULL. The storage for the array of bytes is owned by the
object and should not be freed. The contents of the array
may be modified by the caller only if the object is not
shared and the caller invalidates the string representa
tion.
Tcl_SetByteArrayLength converts the Tcl object to byte-
array type and changes the length of the object's internal
representation as an array of bytes. If length is greater
than the space currently allocated for the array, the
array is reallocated to the new length; the newly allo
cated bytes at the end of the array have arbitrary values.
If length is less than the space currently allocated for
the array, the length of array is reduced to the new
length. The return value is a pointer to the object's new
array of bytes.
Tcl_GetStringFromObj, Tcl_NewObj, Tcl_IncrRefCount,
Tcl_DecrRefCount
KEYWORDS
object, byte array, utf, unicode, internationalization
Man(1) output converted with
man2html