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 values 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 value. May  be  NULL
30                                                    even  if  length  is  non-
31                                                    zero.
32
33       int length (in)                              The length of the array of
34                                                    bytes.  It must be >= 0.
35
36       Tcl_Obj *objPtr (in/out)                     For   Tcl_SetByteArrayObj,
37                                                    this points to  the  value
38                                                    to  be  converted to byte-
39                                                    array type.  For  Tcl_Get‐
40                                                    ByteArrayFromObj       and
41                                                    Tcl_SetByteArrayLength,
42                                                    this  points  to the value
43                                                    from  which  to  get   the
44                                                    byte-array    value;    if
45                                                    objPtr  does  not  already
46                                                    point   to   a  byte-array
47                                                    value,  it  will  be  con‐
48                                                    verted to one.
49
50       int *lengthPtr (out)                         If  non-NULL,  filled with
51                                                    the length of the array of
52                                                    bytes in the value.
53______________________________________________________________________________
54
55

DESCRIPTION

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

SEE ALSO

99       Tcl_GetStringFromObj, Tcl_NewObj, Tcl_IncrRefCount, Tcl_DecrRefCount
100
101

KEYWORDS

103       value, binary data, byte array, utf, unicode, internationalization
104
105
106
107Tcl                                   8.1                  Tcl_ByteArrayObj(3)
Impressum