TclByteArrayObj(3) Tcl Library Procedures TclByteArrayObj(3)

NAME
       TclNewByteArrayObj,    TclSetByteArrayObj,   TclGetByteArrayFromObj,
       TclSetByteArrayLength - manipulate Tcl objects as a arrays of bytes

SYNOPSIS
       ##iinncclluuddee <>

       TclObj *
       TTccllNNeewwBByytteeAArrrraayyOObbjj(bytes, length)

       void
       TTccllSSeettBByytteeAArrrraayyOObbjj(objPtr, bytes, length)

       unsigned char *
       TTccllGGeettBByytteeAArrrraayyFFrroommOObbjj(objPtr, lengthPtr)

       unsigned char *
       TTccllSSeettBByytteeAArrrraayyLLeennggtthh(objPtr, length)

AARRGGUUMMEENNTTSS
       CONST unsigned char          *bytes(in)
                                              The array of bytes used to  ini-
                                              tialize   or  set  a  byte-array
                                              object.

       int             length       (in)      The  length  of  the  array   of
                                              bytes.  It must be >= 0.

       TclObj         *objPtr      (in/out)  For   TTccllSSeettBByytteeAArrrraayyOObbjj,  this
                                              points to the object to be  con-
                                              verted  to byte-array type.  For
                                              TTccllGGeettBByytteeAArrrraayyFFrroommOObbjj      and
                                              TTccllSSeettBByytteeAArrrraayyLLeennggtthh,     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
       bbiinnaarryy  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 representa-
       tion 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
       TTccllGGeettSSttrriinnggFFrroommOObbjj)  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.

       TTccllNNeewwBByytteeAArrrraayyOObbjj and TTccllSSeettBByytteeAArrrraayyOObbjj 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. TTccllNNeewwBByytteeAArrrraayyOObbjj returns a pointer to a newly allo-
       cated object with  a  reference  count  of  zero.   TTccllSSeettBByytteeAArrrraayyOObbjj
       invalidates  any  old  string  representation and, if the object is not
       already a byte-array object, frees any old internal representation.

       TTccllGGeettBByytteeAArrrraayyFFrroommOObbjj 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.

       TTccllSSeettBByytteeAArrrraayyLLeennggtthh 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.


SEE ALSO
       TclGetStringFromObj, TclNewObj, TclIncrRefCount, TclDecrRefCount


KKEEYYWWOORRDDSS
       object, byte array, utf, unicode, internationalization



Tcl                                   8.1                  TclByteArrayObj(3)