dwww Home | Manual pages | Find package

Tcl_ByteArrayObj(3tcl)      Tcl Library Procedures      Tcl_ByteArrayObj(3tcl)

______________________________________________________________________________

NAME
       Tcl_NewByteArrayObj,    Tcl_SetByteArrayObj,   Tcl_GetByteArrayFromObj,
       Tcl_SetByteArrayLength - manipulate Tcl values 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 value. May  be  NULL
                                                    even  if  length  is  non-
                                                    zero.

       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  value
                                                    to  be  converted to byte-
                                                    array type.  For  Tcl_Get-
                                                    ByteArrayFromObj       and
                                                    Tcl_SetByteArrayLength,
                                                    this  points  to the value
                                                    from  which  to  get   the
                                                    byte-array  value;  if ob-
                                                    jPtr  does   not   already
                                                    point   to   a  byte-array
                                                    value,  it  will  be  con-
                                                    verted to one.

       int *lengthPtr (out)                         If  non-NULL,  filled with
                                                    the length of the array of
                                                    bytes in the value.
______________________________________________________________________________

DESCRIPTION
       These  procedures  are  used to create, modify, and read Tcl byte-array
       values from C code.  Byte-array values are typically used to  hold  the
       results of binary IO operations or data structures created with the bi-
       nary 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.  Acces-
       sor  functions are provided to get the string representation of a byte-
       array or to convert an arbitrary value to a byte-array.  Obtaining  the
       string  representation  of  a  byte-array  value  (by  calling Tcl_Get-
       StringFromObj) 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 value  of
       byte-array  type or modify an existing value to have a byte-array type.
       Both of these procedures set the value's type to be byte-array and  set
       the  value's  internal  representation  to a copy of the array of bytes
       given by bytes. Tcl_NewByteArrayObj returns a pointer to a newly  allo-
       cated value with a reference count of zero.  Tcl_SetByteArrayObj inval-
       idates any old string representation and, if the value is not already a
       byte-array  value,  frees  any old internal representation. If bytes is
       NULL then the new byte array contains arbitrary values.

       Tcl_GetByteArrayFromObj converts a Tcl value to byte-array type and re-
       turns  a pointer to the value'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 value
       and should not be freed.  The contents of the array may be modified  by
       the  caller  only if the value is not shared and the caller invalidates
       the string representation.

       Tcl_SetByteArrayLength converts the Tcl value to  byte-array  type  and
       changes  the  length of the value'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 allo-
       cated 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 value's new array of bytes.

SEE ALSO
       Tcl_GetStringFromObj, Tcl_NewObj, Tcl_IncrRefCount, Tcl_DecrRefCount

KEYWORDS
       value, binary data, byte array, utf, unicode, internationalization

Tcl                                   8.1               Tcl_ByteArrayObj(3tcl)

Generated by dwww version 1.14 on Thu Jan 23 00:14:02 CET 2025.