Tcl_NewByteArrayObj(3tcl)

Tcl_ByteArrayObj(3)  Tcl Library Procedures   Tcl_ByteArrayObj(3)

_________________________________________________________________

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

Tcl                     Last change: 8.1                        1

Tcl_ByteArrayObj(3)  Tcl Library Procedures   Tcl_ByteArrayObj(3)

                                                  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 typ-
     ically 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 mean-
     ing.   Accessor  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 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 modi-
     fied 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

Tcl                     Last change: 8.1                        2

Tcl_ByteArrayObj(3)  Tcl Library Procedures   Tcl_ByteArrayObj(3)

     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

Tcl                     Last change: 8.1                        3