tcl_bytearrayobj(3)
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
- CONST 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 bytearray type. For
Tcl_GetByteAr rayFromObj and Tcl_SetByteAr rayLength, this points to the
object from which
to get the bytearray 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
in the object.
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 bytearray 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 nonNULL. 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 bytearray 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.
SEE ALSO
Tcl_GetStringFromObj, Tcl_NewObj, Tcl_IncrRefCount,
Tcl_DecrRefCount
KEYWORDS
- object, byte array, utf, unicode, internationalization