92 lines
4.0 KiB
Groff
92 lines
4.0 KiB
Groff
|
'\"
|
||
|
|
'\" 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.
|
||
|
|
'\"
|
||
|
|
.TH Tcl_ByteArrayObj 3 8.1 Tcl "Tcl Library Procedures"
|
||
|
|
.so man.macros
|
||
|
|
.BS
|
||
|
|
.SH NAME
|
||
|
|
Tcl_NewByteArrayObj, Tcl_SetByteArrayObj, Tcl_GetByteArrayFromObj, Tcl_SetByteArrayLength \- manipulate Tcl values 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 "const unsigned char" *lengthPtr in/out
|
||
|
|
.AP "const unsigned char" *bytes in
|
||
|
|
The array of bytes used to initialize or set a byte-array value. May be NULL
|
||
|
|
even if \fIlength\fR is non-zero.
|
||
|
|
.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 value to be converted to
|
||
|
|
byte-array type. For \fBTcl_GetByteArrayFromObj\fR and
|
||
|
|
\fBTcl_SetByteArrayLength\fR, this points to the value from which to get
|
||
|
|
the byte-array value; if \fIobjPtr\fR does not already point to a byte-array
|
||
|
|
value, it will be converted to one.
|
||
|
|
.AP int *lengthPtr out
|
||
|
|
If non-NULL, filled with the length of the array of bytes in the value.
|
||
|
|
.BE
|
||
|
|
|
||
|
|
.SH DESCRIPTION
|
||
|
|
.PP
|
||
|
|
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
|
||
|
|
\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.
|
||
|
|
Accessor 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
|
||
|
|
\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 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 \fIbytes\fR. \fBTcl_NewByteArrayObj\fR returns a
|
||
|
|
pointer to a newly allocated value with a reference count of zero.
|
||
|
|
\fBTcl_SetByteArrayObj\fR invalidates any old string representation and, if
|
||
|
|
the value is not already a byte-array value, frees any old internal
|
||
|
|
representation. If \fIbytes\fR is NULL then the new byte array contains
|
||
|
|
arbitrary values.
|
||
|
|
.PP
|
||
|
|
\fBTcl_GetByteArrayFromObj\fR converts a Tcl value to byte-array type and
|
||
|
|
returns a pointer to the value'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 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.
|
||
|
|
.PP
|
||
|
|
\fBTcl_SetByteArrayLength\fR converts the Tcl value to byte-array type
|
||
|
|
and changes the length of the value'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 value's new array of bytes.
|
||
|
|
|
||
|
|
.SH "SEE ALSO"
|
||
|
|
Tcl_GetStringFromObj, Tcl_NewObj, Tcl_IncrRefCount, Tcl_DecrRefCount
|
||
|
|
|
||
|
|
.SH KEYWORDS
|
||
|
|
value, binary data, byte array, utf, unicode, internationalization
|