[25] | 1 | '\" |
---|
| 2 | '\" Copyright (c) 1997 Sun Microsystems, Inc. |
---|
| 3 | '\" |
---|
| 4 | '\" See the file "license.terms" for information on usage and redistribution |
---|
| 5 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
---|
| 6 | '\" |
---|
| 7 | '\" RCS: @(#) $Id: ByteArrObj.3,v 1.6 2004/10/07 15:15:35 dkf Exp $ |
---|
| 8 | '\" |
---|
| 9 | .so man.macros |
---|
| 10 | .TH Tcl_ByteArrayObj 3 8.1 Tcl "Tcl Library Procedures" |
---|
| 11 | .BS |
---|
| 12 | .SH NAME |
---|
| 13 | Tcl_NewByteArrayObj, Tcl_SetByteArrayObj, Tcl_GetByteArrayFromObj, Tcl_SetByteArrayLength \- manipulate Tcl objects as a arrays of bytes |
---|
| 14 | .SH SYNOPSIS |
---|
| 15 | .nf |
---|
| 16 | \fB#include <tcl.h>\fR |
---|
| 17 | .sp |
---|
| 18 | Tcl_Obj * |
---|
| 19 | \fBTcl_NewByteArrayObj\fR(\fIbytes, length\fR) |
---|
| 20 | .sp |
---|
| 21 | void |
---|
| 22 | \fBTcl_SetByteArrayObj\fR(\fIobjPtr, bytes, length\fR) |
---|
| 23 | .sp |
---|
| 24 | unsigned char * |
---|
| 25 | \fBTcl_GetByteArrayFromObj\fR(\fIobjPtr, lengthPtr\fR) |
---|
| 26 | .sp |
---|
| 27 | unsigned char * |
---|
| 28 | \fBTcl_SetByteArrayLength\fR(\fIobjPtr, length\fR) |
---|
| 29 | .SH ARGUMENTS |
---|
| 30 | .AS "const unsigned char" *lengthPtr in/out |
---|
| 31 | .AP "const unsigned char" *bytes in |
---|
| 32 | The array of bytes used to initialize or set a byte-array object. |
---|
| 33 | .AP int length in |
---|
| 34 | The length of the array of bytes. It must be >= 0. |
---|
| 35 | .AP Tcl_Obj *objPtr in/out |
---|
| 36 | For \fBTcl_SetByteArrayObj\fR, this points to the object to be converted to |
---|
| 37 | byte-array type. For \fBTcl_GetByteArrayFromObj\fR and |
---|
| 38 | \fBTcl_SetByteArrayLength\fR, this points to the object from which to get |
---|
| 39 | the byte-array value; if \fIobjPtr\fR does not already point to a byte-array |
---|
| 40 | object, it will be converted to one. |
---|
| 41 | .AP int *lengthPtr out |
---|
| 42 | If non-NULL, filled with the length of the array of bytes in the object. |
---|
| 43 | .BE |
---|
| 44 | |
---|
| 45 | .SH DESCRIPTION |
---|
| 46 | .PP |
---|
| 47 | These procedures are used to create, modify, and read Tcl byte-array objects |
---|
| 48 | from C code. Byte-array objects are typically used to hold the |
---|
| 49 | results of binary IO operations or data structures created with the |
---|
| 50 | \fBbinary\fR command. In Tcl, an array of bytes is not equivalent to a |
---|
| 51 | string. Conceptually, a string is an array of Unicode characters, while a |
---|
| 52 | byte-array is an array of 8-bit quantities with no implicit meaning. |
---|
| 53 | Accessor functions are provided to get the string representation of a |
---|
| 54 | byte-array or to convert an arbitrary object to a byte-array. Obtaining the |
---|
| 55 | string representation of a byte-array object (by calling |
---|
| 56 | \fBTcl_GetStringFromObj\fR) produces a properly formed UTF-8 sequence with a |
---|
| 57 | one-to-one mapping between the bytes in the internal representation and the |
---|
| 58 | UTF-8 characters in the string representation. |
---|
| 59 | .PP |
---|
| 60 | \fBTcl_NewByteArrayObj\fR and \fBTcl_SetByteArrayObj\fR will |
---|
| 61 | create a new object of byte-array type or modify an existing object to have a |
---|
| 62 | byte-array type. Both of these procedures set the object's type to be |
---|
| 63 | byte-array and set the object's internal representation to a copy of the |
---|
| 64 | array of bytes given by \fIbytes\fR. \fBTcl_NewByteArrayObj\fR returns a |
---|
| 65 | pointer to a newly allocated object with a reference count of zero. |
---|
| 66 | \fBTcl_SetByteArrayObj\fR invalidates any old string representation and, if |
---|
| 67 | the object is not already a byte-array object, frees any old internal |
---|
| 68 | representation. |
---|
| 69 | .PP |
---|
| 70 | \fBTcl_GetByteArrayFromObj\fR converts a Tcl object to byte-array type and |
---|
| 71 | returns a pointer to the object's new internal representation as an array of |
---|
| 72 | bytes. The length of this array is stored in \fIlengthPtr\fR if |
---|
| 73 | \fIlengthPtr\fR is non-NULL. The storage for the array of bytes is owned by |
---|
| 74 | the object and should not be freed. The contents of the array may be |
---|
| 75 | modified by the caller only if the object is not shared and the caller |
---|
| 76 | invalidates the string representation. |
---|
| 77 | .PP |
---|
| 78 | \fBTcl_SetByteArrayLength\fR converts the Tcl object to byte-array type |
---|
| 79 | and changes the length of the object's internal representation as an |
---|
| 80 | array of bytes. If \fIlength\fR is greater than the space currently |
---|
| 81 | allocated for the array, the array is reallocated to the new length; the |
---|
| 82 | newly allocated bytes at the end of the array have arbitrary values. If |
---|
| 83 | \fIlength\fR is less than the space currently allocated for the array, |
---|
| 84 | the length of array is reduced to the new length. The return value is a |
---|
| 85 | pointer to the object's new array of bytes. |
---|
| 86 | |
---|
| 87 | .SH "SEE ALSO" |
---|
| 88 | Tcl_GetStringFromObj, Tcl_NewObj, Tcl_IncrRefCount, Tcl_DecrRefCount |
---|
| 89 | |
---|
| 90 | .SH KEYWORDS |
---|
| 91 | object, byte array, utf, unicode, internationalization |
---|