## Tcl8.6.17/Tk8.6.17 Documentation > Tcl C API > ByteArrObj

### Tcl/Tk Applications | Tcl Commands | Tk Commands | [incr Tcl] Package Commands | SQLite3 Package Commands | TDBC Package Commands | tdbc::mysql Package Commands | tdbc::odbc Package Commands | tdbc::postgres Package Commands | tdbc::sqlite3 Package Commands | Thread Package Commands | Tcl C API | Tk C API | [incr Tcl] Package C API | TDBC Package C API

  NAME
    Tcl_NewByteArrayObj, Tcl_SetByteArrayObj, Tcl_GetByteArrayFromObj, Tcl_SetByteArrayLength — Tcl 値をバイト配列として扱う 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)
    int length (入力in)
    Tcl_Obj *objPtr (入力/出力in/out)
    int *lengthPtr (出力out)
  説明 DESCRIPTION
  SEE ALSO
  KEYWORDS

### NAME

Tcl_NewByteArrayObj, Tcl_SetByteArrayObj, Tcl_GetByteArrayFromObj, Tcl_SetByteArrayLength — Tcl 値をバイト配列として扱う 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)
  バイト配列値を初期化又は設定する為に使われるバイト配列｡仮令 length でも NULL になり得る｡ 　　 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)
  Tcl_SetByteArrayObj については､これは､バイト配列型に変換される値への位置を指す｡Tcl_GetByteArrayFromObj と Tcl_SetByteArrayLength については､これは､そこからバイト配列を得る値の位置を指す;もし objPtr が未だバイト配列値を指さない時は､それに変換される｡ 　　 For Tcl_SetByteArrayObj, this points to the value to be converted to byte-array type. For Tcl_GetByteArrayFromObj and Tcl_SetByteArrayLength, this points to the value from which to get the byte-array value; if objPtr does not already point to a byte-array value, it will be converted to one.

int *lengthPtr (出力out)
  もし非NULL であれば､値内のバイト配列の長さで満たされる｡ 　　 If non-NULL, filled with the length of the array of bytes in the value.

### 説明 DESCRIPTION

これ等の手続函数は C 符号譜からの Tcl バイト配列値を作成修正読込みする為に使われる｡バイト配列値は典型的には２進入出力の結果､或は､ binary 命令によって作成されたデータ構造の保有に使用される｡ Tcl 内ではバイトの配列は文字列と等価ではない｡概念的に､文字列はユニコード文字の配列であり､一方バイト配列は意味を含まない８ビット量の配列である｡利用する機能はバイト配列が表現する文字列を得ることか､又は任意の値をバイト配列に変換することを提供する｡バイト配列値の表現する文字列を得ることは(Tcl_GetStringFromObj の呼出しによる)､内部表現によるバイトと､文字列の表現による UTF-8 文字との間の､一対一の対応により適切な UTF-8 並びを生産する｡ 　　　 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 binary 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 Tcl_GetStringFromObj) 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 と Tcl_SetByteArrayObj は新しいバイト配列型の値を作成するか､既存の値をバイト配列型を有する様修正する｡この両方の手続函数共に対象の型をバイト配列に設定し値の内部表現を bytes.によって与えられるバイトの配列の複写に設定する｡ Tcl_NewByteArrayObj は参照回数零を伴う新しく割付けられた値へのポインタを返す｡Tcl_SetByteArrayObj はどの古い文字列表現も無効にし､もし値が未だバイト配列値でない場合､どの古い内部表現も解放する｡もし bytes が NULL の場合､新しいバイト配列は任意の値を含む｡ 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 allocated value with a reference count of zero. Tcl_SetByteArrayObj invalidates 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 は Tcl 対象をバイト配列型に変換し､バイトの配列としての対象の新しい内部表現へのポインタを返す｡もし lengthPtr が非NULL.の場合､この配列の長さは lengthPtr に保存される｡バイトの配列への記憶域は対象によって所有され解放されていない｡もし対象が共有されず､呼出者が文字列表現を無効にする場合に限り､配列の内容は呼出者に修正されるかもしれない｡ Tcl_GetByteArrayFromObj 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 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 は Tcl 対象をバイト配列型に変換し､バイト配列としての対象の内部表現の長さを変更する｡もし length が配列の為に現在割付けている空白より大きい場合､配列は新しい長さに再割付される; 配列末尾の新しく割付られたバイトは任意の値を有する｡もし length が配列に割付けられた空白より小さい場合､配列の長さは新しい長さに減じられる｡返り値は新しいバイト配列の対象へのポインタである｡ 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 allocated 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
Copyright © 1997 Sun Microsystems, Inc.