diff options
Diffstat (limited to 'doc/ByteArrObj.3')
| -rw-r--r-- | doc/ByteArrObj.3 | 91 |
1 files changed, 0 insertions, 91 deletions
diff --git a/doc/ByteArrObj.3 b/doc/ByteArrObj.3 deleted file mode 100644 index b3ed34f..0000000 --- a/doc/ByteArrObj.3 +++ /dev/null @@ -1,91 +0,0 @@ -'\" -'\" Copyright (c) 1997 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: ByteArrObj.3,v 1.2 1999/03/03 00:38:36 stanton Exp $ -'\" -.so man.macros -.TH Tcl_ByteArrayObj 3 8.1 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_NewByteArrayObj, Tcl_SetByteArrayObj, Tcl_GetByteArrayFromObj, Tcl_SetByteArrayLength \- manipulate Tcl objects as a arrays of bytes -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -Tcl_Obj * -\fBTcl_NewByteArrayObj\fR(\fIbytes, length\fR) -.sp -void -\fBTcl_SetByteArrayObj\fR(\fIobjPtr, bytes, length\fR) -.sp -unsigned char * -\fBTcl_GetByteArrayFromObj\fR(\fIobjPtr, lengthPtr\fR) -.sp -unsigned char * -\fBTcl_SetByteArrayLength\fR(\fIobjPtr, length\fR) -.SH ARGUMENTS -.AS "unsigned char" *lengthPtr in/out -.AP "unsigned char" *bytes in -The array of bytes used to initialize or set a byte-array object. -.AP int length in -The length of the array of bytes. It must be >= 0. -.AP Tcl_Obj *objPtr in/out -For \fBTcl_SetByteArrayObj\fR, this points to the object to be converted to -byte-array type. For \fBTcl_GetByteArrayFromObj\fR and -\fBTcl_SetByteArrayLength\fR, this points to the object from which to get -the byte-array value; if \fIobjPtr\fR does not already point to a byte-array -object, it will be converted to one. -.AP int *lengthPtr out -If non-NULL, filled with the length of the array of bytes in the object. -.BE - -.SH DESCRIPTION -.PP -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 -\fBbinary\fR 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. -Accesser 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 -\fBTcl_GetStringFromObj\fR) 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. -.PP -\fBTcl_NewByteArrayObj\fR and \fBTcl_SetByteArrayObj\fR 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 \fIbytes\fR. \fBTcl_NewByteArrayObj\fR returns a -pointer to a newly allocated object with a reference count of zero. -\fBTcl_SetByteArrayObj\fR invalidates any old string representation and, if -the object is not already a byte-array object, frees any old internal -representation. -.PP -\fBTcl_GetByteArrayFromObj\fR converts a Tcl object to byte-array type and -returns a pointer to the object's new internal representation as an array of -bytes. The length of this array is stored in \fIlengthPtr\fR if -\fIlengthPtr\fR 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. -.PP -\fBTcl_SetByteArrayLength\fR converts the Tcl object to byte-array type -and changes the length of the object's internal representation as an -array of bytes. If \fIlength\fR is greater than the space currently -allocated for the array, the array is reallocated to the new length; the -newly allocated bytes at the end of the array have arbitrary values. If -\fIlength\fR 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. - -.SH "SEE ALSO" -Tcl_GetStringFromObj, Tcl_NewObj, Tcl_IncrRefCount, Tcl_DecrRefCount - -.SH KEYWORDS -object, byte array, utf, unicode, internationalization |