1Tcl_ByteArrayObj(3)         Tcl Library Procedures         Tcl_ByteArrayObj(3)
2
3
4
5______________________________________________________________________________
6

NAME

8       Tcl_NewByteArrayObj,    Tcl_SetByteArrayObj,   Tcl_GetByteArrayFromObj,
9       Tcl_SetByteArrayLength - manipulate Tcl objects as a arrays of bytes
10

SYNOPSIS

12       #include <tcl.h>
13
14       Tcl_Obj *
15       Tcl_NewByteArrayObj(bytes, length)
16
17       void
18       Tcl_SetByteArrayObj(objPtr, bytes, length)
19
20       unsigned char *
21       Tcl_GetByteArrayFromObj(objPtr, lengthPtr)
22
23       unsigned char *
24       Tcl_SetByteArrayLength(objPtr, length)
25

ARGUMENTS

27       const unsigned char *bytes (in)              The array of bytes used to
28                                                    initialize  or set a byte-
29                                                    array object.
30
31       int length (in)                              The length of the array of
32                                                    bytes.  It must be >= 0.
33
34       Tcl_Obj *objPtr (in/out)                     For   Tcl_SetByteArrayObj,
35                                                    this points to the  object
36                                                    to  be  converted to byte-
37                                                    array type.  For  Tcl_Get‐
38                                                    ByteArrayFromObj       and
39                                                    Tcl_SetByteArrayLength,
40                                                    this  points to the object
41                                                    from  which  to  get   the
42                                                    byte-array    value;    if
43                                                    objPtr  does  not  already
44                                                    point   to   a  byte-array
45                                                    object, it  will  be  con‐
46                                                    verted to one.
47
48       int *lengthPtr (out)                         If  non-NULL,  filled with
49                                                    the length of the array of
50                                                    bytes in the object.
51_________________________________________________________________
52
53

DESCRIPTION

55       These  procedures  are  used to create, modify, and read Tcl byte-array
56       objects from C code.  Byte-array objects are typically used to hold the
57       results  of  binary  IO  operations or data structures created with the
58       binary command.  In Tcl, an array of  bytes  is  not  equivalent  to  a
59       string.   Conceptually,  a  string  is  an array of Unicode characters,
60       while a byte-array is an array of 8-bit  quantities  with  no  implicit
61       meaning.  Accessor functions are provided to get the string representa‐
62       tion of a byte-array or to convert an arbitrary object to a byte-array.
63       Obtaining  the string representation of a byte-array object (by calling
64       Tcl_GetStringFromObj) produces a properly formed UTF-8 sequence with  a
65       one-to-one mapping between the bytes in the internal representation and
66       the UTF-8 characters in the string representation.
67
68       Tcl_NewByteArrayObj and Tcl_SetByteArrayObj will create a new object of
69       byte-array type or modify an existing object to have a byte-array type.
70       Both of these procedures set the object's type to be byte-array and set
71       the  object's  internal  representation to a copy of the array of bytes
72       given by bytes. Tcl_NewByteArrayObj returns a pointer to a newly  allo‐
73       cated  object  with  a  reference  count  of zero.  Tcl_SetByteArrayObj
74       invalidates any old string representation and, if  the  object  is  not
75       already a byte-array object, frees any old internal representation.
76
77       Tcl_GetByteArrayFromObj  converts  a  Tcl object to byte-array type and
78       returns a pointer to the object's new  internal  representation  as  an
79       array  of  bytes.   The  length of this array is stored in lengthPtr if
80       lengthPtr is non-NULL.  The storage for the array of bytes is owned  by
81       the  object  and should not be freed.  The contents of the array may be
82       modified by the caller only if the object is not shared and the  caller
83       invalidates the string representation.
84
85       Tcl_SetByteArrayLength  converts  the Tcl object to byte-array type and
86       changes the length of the object's internal representation as an  array
87       of  bytes.  If length is greater than the space currently allocated for
88       the array, the array is reallocated to the new length; the newly  allo‐
89       cated  bytes  at the end of the array have arbitrary values.  If length
90       is less than the space currently allocated for the array, the length of
91       array  is  reduced to the new length.  The return value is a pointer to
92       the object's new array of bytes.
93
94

SEE ALSO

96       Tcl_GetStringFromObj, Tcl_NewObj, Tcl_IncrRefCount, Tcl_DecrRefCount
97
98

KEYWORDS

100       object, byte array, utf, unicode, internationalization
101
102
103
104Tcl                                   8.1                  Tcl_ByteArrayObj(3)
Impressum