Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Tcl_ByteArrayObj(3)	    Tcl	Library	Procedures	   Tcl_ByteArrayObj(3)


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

       #include	<tcl.h>

       Tcl_Obj *
       Tcl_NewByteArrayObj(bytes, length)

       Tcl_SetByteArrayObj(objPtr, bytes, length)

       unsigned	char *
       Tcl_GetByteArrayFromObj(objPtr, lengthPtr)

       unsigned	char *
       Tcl_SetByteArrayLength(objPtr, length)

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

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

       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 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	object to a byte-array.	 Obtaining the
       string  representation  of  a  byte-array  object  (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 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	 allo-
       cated  object  with a reference count of	zero.  Tcl_SetByteArrayObj in-
       validates any old string	representation and, if the object is  not  al-
       ready 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 ar-
       ray  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	 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 object's new	array of bytes.

       Tcl_GetStringFromObj, Tcl_NewObj, Tcl_IncrRefCount, Tcl_DecrRefCount

       object, byte array, utf,	unicode, internationalization

Tcl				      8.1		   Tcl_ByteArrayObj(3)


Want to link to this manual page? Use this URL:

home | help