Страницы справочника OS X

Эта страница руководства является частью версии 5.0 Инструментов XCode

Читать страницы руководства

Tcl_ByteArrayObj(3)                        Tcl Library Procedures                        Tcl_ByteArrayObj(3)



____________________________________________________________________________________________________________

NAME
       Tcl_NewByteArrayObj,  Tcl_SetByteArrayObj,  Tcl_GetByteArrayFromObj, Tcl_SetByteArrayLength - manipu-late manipulate
       late 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 bytearray
                                                    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_GetByteArrayFro-mObj Tcl_GetByteArrayFromObj
                                                    mObj  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.   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 bytearray
       array  object (by calling Tcl_GetStringFromObj) produces a properly formed UTF-8 sequence with a one-to-one oneto-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



Tcl                                                  8.1                                 Tcl_ByteArrayObj(3)