Manual Pages for UNIX Operating System command usage for man Tcl_NewByteArrayObj

Tcl Library Procedures                     Tcl_ByteArrayObj(3TCL)



_________________________________________________________________

NAME
     Tcl_NewByteArrayObj,                    Tcl_SetByteArrayObj,
     Tcl_GetByteArrayFromObj, Tcl_SetByteArrayLength - manipulate
     Tcl objects as a arrays of bytes

SYNOPSIS
     #include 

     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  con-
                                            verted 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



Tcl                     Last change: 8.1                        1






Tcl Library Procedures                     Tcl_ByteArrayObj(3TCL)



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




Tcl                     Last change: 8.1                        2






Tcl Library Procedures                     Tcl_ByteArrayObj(3TCL)



SEE ALSO
     Tcl_GetStringFromObj,     Tcl_NewObj,      Tcl_IncrRefCount,
     Tcl_DecrRefCount


KEYWORDS
     object, byte array, utf, unicode, internationalization

ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:

     _______________________________________
    |   ATTRIBUTE TYPE   |  ATTRIBUTE VALUE|
    |____________________|__________________|_
    | Availability       |  runtime/tcl-8  |
    |____________________|__________________|_
    | Interface Stability|  Uncommitted    |
    |____________________|_________________|

NOTES
     Source for Tcl is available on http://opensolaris.org.

































Tcl                     Last change: 8.1                        3