NAME

       Tcl_NewByteArrayObj,  Tcl_SetByteArrayObj, Tcl_GetByteArrayFromObj, 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_SetByteArrayObj, this points to the object
                                              to  be   converted   to   byte-array   type.    For
                                              Tcl_GetByteArrayFromObj and Tcl_SetByteArrayLength,
                                              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  converted  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_GetStringFromObj)  produces a properly formed UTF-8 sequence with a one-to-one mapping
       between the bytes in the internal 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 representation 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
       representation.

       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  allocated  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