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

_________________________________________________________________



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