## Tcl9.0.3/Tk9.0.3 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_GetBytesFromObj, Tcl_GetByteArrayFromObj, Tcl_SetByteArrayLength — Tcl値をバイト配列として扱う manipulate a Tcl value as an array of bytes
  SYNOPSIS
    #include <tcl.h>
    Tcl_Obj *
    Tcl_NewByteArrayObj(bytes, numBytes)
    Tcl_SetByteArrayObj(objPtr, bytes, numBytes)
    unsigned char *
    Tcl_GetBytesFromObj(interp, objPtr, numBytesPtr)
    unsigned char *
    Tcl_GetByteArrayFromObj(objPtr, numBytesPtr)
    unsigned char *
    Tcl_SetByteArrayLength(objPtr, numBytes)
  引数 ARGUMENTS
    const unsigned char *bytes (入力in)
    Tcl_Size numBytes (入力in)
    Tcl_Obj *objPtr (入/出力in/out)
    Tcl_Interp *interp (入力in)
    Tcl_Size &| int *numBytesPtr (出力out)
  説明 DESCRIPTION
  参照回数管理 REFERENCE COUNT MANAGEMENT
  SEE ALSO
  KEYWORDS

### NAME

Tcl_NewByteArrayObj, Tcl_SetByteArrayObj, Tcl_GetBytesFromObj, Tcl_GetByteArrayFromObj, Tcl_SetByteArrayLength — Tcl値をバイト配列として扱う manipulate a Tcl value as an array of bytes

### SYNOPSIS

#include <tcl.h>
Tcl_Obj *
Tcl_NewByteArrayObj(bytes, numBytes)
Tcl_SetByteArrayObj(objPtr, bytes, numBytes)
unsigned char *
Tcl_GetBytesFromObj(interp, objPtr, numBytesPtr)
unsigned char *
Tcl_GetByteArrayFromObj(objPtr, numBytesPtr)
unsigned char *
Tcl_SetByteArrayLength(objPtr, numBytes)

### 引数 ARGUMENTS

const unsigned char *bytes (入力in)
  バイト配列の値を書式化又は設定する為に使われるバイトの配列｡ numBytes が非零であれば､ヌルでも良い｡ The array of bytes used to initialize or set a byte-array value. May be NULL even if numBytes is non-zero.

Tcl_Size numBytes (入力in)
  配列内のバイトの個数｡ The number of bytes in the array.

Tcl_Obj *objPtr (入/出力in/out)
  Tcl_SetByteArrayObj に関して､これはバイト配列によって上書きされる非共有値を指す｡Tcl_GetBytesFromObjとTcl_SetByteArrayLength に関して､そこからバイト配列を曳出す値を指す｡ For Tcl_SetByteArrayObj, this points to an unshared value to be overwritten by a byte-array value. For Tcl_GetBytesFromObj, Tcl_GetByteArrayFromObj and Tcl_SetByteArrayLength, this points to the value from which to extract an array of bytes.

Tcl_Interp *interp (入力in)
  不都合報告の為の解釈実行機能｡ Interpreter to use for error reporting.

Tcl_Size &| int *numBytesPtr (出力out)
  配列内のバイトの個数が書かれ得る空間を指す｡使われない時は寸法無しの (Tcl_Size *)NULL かもしれない｡もし型がTcl_Sizeでない変数を指す場合､機械語翻訳警告が創生される｡もし､使用者の拡張が -DTCL_8_APIを伴って機械語翻訳されている場合､ INT_MAX より大きなバイト配列に関してこの函数はヌル(それは適正な不都合-取扱いを起動すべき)を返す､そうでない場合､それには崩壊を予測する｡ Points to space where the number of bytes in the array may be written. May be (Tcl_Size *)NULL when not used. If it points to a variable which type is not Tcl_Size, a compiler warning will be generated. If your extensions is compiled with -DTCL_8_API, this function will return NULL for byte arrays larger than INT_MAX (which should trigger proper error-handling), otherwise expect it to crash.

### 説明 DESCRIPTION

これらの機能譜は Tcl 値に任意の二進データを創生し､修正し､保存し､送付し､取出す為に使われる｡具体的には､任意のバイト値の並びとして代表され得るデータに対応している｡これは二進通信路から読込んだデータや､binary 命令によって創生された値や､暗号化データや､有限のバイト並びとして現される他の情報を含む｡ These routines are used to create, modify, store, transfer, and retrieve arbitrary binary data in Tcl values. Specifically, data that can be represented as a sequence of arbitrary byte values is supported. This includes data read from binary channels, values created by the binary command, encrypted data, or other information representable as a finite byte sequence.

バイトは固有の意味のない8ビットの量である｡8ビットが整数と解釈される場合､可能な値の範囲は(0-255)である｡バイトを保存する為に 最も適したC 型は 符号無し文字である｡寸法 N の符号無し文字配列は寸法 N バイトの任意の二進値を保存する｡これをバイト配列と表現する｡ここでは､ Tcl 値をバイト配列として操作することを我々に許容する業務譜を､書面化する｡ A byte is an 8-bit quantity with no inherent meaning. When the 8 bits are interpreted as an integer value, the range of possible values is (0-255). The C type best suited to store a byte is the unsigned char. An unsigned char array of size N stores an arbitrary binary value of size N bytes. We call this representation a byte-array. Here we document the routines that allow us to operate on Tcl values as byte-arrays.

全ての Tcl 値は文字列表現に対応せねばならぬ｡バイト配列値が文字列として処理されねばならぬ時､N バイトの並びは対応する N 文字並びに翻訳される､此処で､夫々のバイト値は範囲 (U+0000 - U+00FF)内の同じ文字符号位置値に翻訳される｡バイト配列の文字列表現を(Tcl_GetStringFromObj 呼出しで)得ることは､Tclの､通常の修正 UTF-8 符号内にその文字列を生成する｡ All Tcl values must correspond to a string representation. When a byte-array value must be processed as a string, the sequence of N bytes is transformed into the corresponding sequence of N characters, where each byte value transforms to the same character codepoint value in the range (U+0000 - U+00FF). Obtaining the string representation of a byte-array value (by calling Tcl_GetStringFromObj) produces this string in Tcl's usual Modified UTF-8 encoding.

Tcl_NewByteArrayObj と Tcl_SetByteArrayObj は､ numBytes バイトのバイト配列を保有する為に､それぞれ､新しい値を造るか､既存の非共有値を上書きする｡呼出し者が､非ヌルのバイト値を渡す時､そこから numBytes バイトが読み出せる記憶域を指さねばならない｡これらの業務は､記憶域の numBytes バイトを割当て､ bytes から numBytes バイトをその中に複写し､新しい､或は上書きされた値の内部表現内に結果を保持する｡呼出者が bytes のヌル値を渡すとき､データ複写段階は飛越され､値に保存されたバイトは定義されない｡ヌルの bytes 値は､下に説明された業務の内の一つを呼ぶことにより､知っている内容を､改修したポインタを通してバイト-配列に書く為に呼出者が調整する時にのみ便利である｡ Tcl_NewByteArrayObj and Tcl_SetByteArrayObj create a new value or overwrite an existing unshared value, respectively, to hold a byte-array value of numBytes bytes. When a caller passes a non-NULL value of bytes, it must point to memory from which numBytes bytes can be read. These routines allocate numBytes bytes of memory, copy numBytes bytes from bytes into it, and keep the result in the internal representation of the new or overwritten value. When the caller passes a NULL value of bytes, the data copying step is skipped, and the bytes stored in the value are undefined. A bytes value of NULL is useful only when the caller will arrange to write known contents into the byte-array through a pointer retrieved by a call to one of the routines explained below. Tcl_NewByteArrayObj returns a pointer to the created value with a reference count of zero. Tcl_SetByteArrayObj overwrites and invalidates any old contents of the unshared objPtr as appropriate, and keeps its reference count (0 or 1) unchanged. The value produced by these routines has no string representation. Any memory allocation failure may cause a panic.

Tcl_GetBytesFromObj はTcl_SetByteArrayObjの反対の機能を遂行し､以前にその中に書かれた Tcl 値からバイト配列を読む為の利用を提供する｡ objPtr がTcl_NewByteArrayObjかTcl_SetByteArrayObjに造られた値であると､Tcl_GetBytesFromObjは値の内部表現の中に保持されたバイト配列へのポインターを返す｡もし､呼出側が､ numBytesPtr の為に非ヌル値を提供する場合､それはTcl_GetBytesFromObjが値の内部のバイト配列内にバイトの個数を書くことができる記憶域を指してなければならない｡情報の両方の断片について､呼出側はそれが捜索しているそのバイト配列の内容に関するどの様な情報も回収することができる｡ objPtr が未だ内部バイト配列を含んでない時､Tcl_GetBytesFromObj は値の文字列表現からそれを作ろうと試みる｡範囲 (U+0000 - U+00FF) の外側の符号領域のどの文字も含んでないどの値も､成功裡にユニコードバイト配列値に翻訳される｡作成されたバイト配列に関して､業務譜は前の通りに返る｡忘れられた文字符号位置を含むどの様な文字列表現に関しても､変換は失敗し､且つ､Tcl_GetBytesFromObj は､失敗と通知する為に､ヌルを返す｡失敗すると､ numBytesPtr には何も記入されず､もし interp 引数が非ヌルであれば､不都合伝言文と符号がその不都合に残される｡ Tcl_GetBytesFromObj performs the opposite function of Tcl_SetByteArrayObj, providing access to read a byte-array from a Tcl value that was previously written into it. When objPtr is a value previously produced by Tcl_NewByteArrayObj or Tcl_SetByteArrayObj, then Tcl_GetBytesFromObj returns a pointer to the byte-array kept in the value's internal representation. If the caller provides a non-NULL value for numBytesPtr, it must point to memory where Tcl_GetBytesFromObj can write the number of bytes in the value's internal byte-array. With both pieces of information, the caller is able to retrieve any information about the contents of that byte-array that it seeks. When objPtr does not already contain an internal byte-array, Tcl_GetBytesFromObj will try to create one from the value's string representation. Any string value that does not include any character codepoints outside the range (U+0000 - U+00FF) will successfully translate to a unique byte-array value. With the created byte-array, the routine returns as before. For any string representation which does contain a forbidden character codepoint, the conversion fails, and Tcl_GetBytesFromObj returns NULL to signal that failure. On failure, nothing will be written to numBytesPtr, and if the interp argument is non-NULL, then error messages and codes are left in it recording the error.

Tcl_GetByteArrayFromObj は､値ヌルを渡された interp 引数と共に呼ばれた時に行う Tcl_GetBytesFromObj と同じ正確に同じ機能を遂行する｡これは Tcl 8 版内で函数化された Tcl_GetByteArrayFromObj の方法とは両立しない｡Tcl_GetBytesFromObj は更に有能な対話機能であり､且つ､Tcl_GetByteArrayFromObj を凌いで好まれて使用される｡ Tcl_GetByteArrayFromObj performs exactly the same function as Tcl_GetBytesFromObj does when called with the interp argument passed the value NULL. This is incompatible with the way Tcl_GetByteArrayFromObj functioned in Tcl 8. Tcl_GetBytesFromObj is the more capable interface and should usually be favored for use over Tcl_GetByteArrayFromObj.

Tcl_GetBytesFromObj と Tcl_GetByteArrayFromObj は､両方共､成功するとTcl_Obj の内部表現への指示子を返す｡その指示子は､呼出側によって解放されてはならず､且つ､値の内部表現が動揺してないと判っている時間迄､使用について留まってはならない｡指示子は､値が非共有であり且つどの様な文字列表現も無効化されている限り､内部表現のバイト内容を上書きする為に使い得る｡ On success, both Tcl_GetBytesFromObj and Tcl_GetByteArrayFromObj return a pointer into the internal representation of a Tcl_Obj. That pointer must not be freed by the caller, and should not be retained for use beyond the known time the internal representation of the value has not been disturbed. The pointer may be used to overwrite the byte contents of the internal representation, so long as the value is unshared and any string representation is invalidated.

成功すると､Tcl_GetBytesFromOb と Tcl_GetByteArrayFromObj の両方は objPtr のバイト配列内のバイトの個数を numBytesPtr によって指し示される場所に書く｡その場所は Tcl_Size 型か int 型かであり得る｡呼出側がこの目的の為にTcl_Size場所を提供する事が推奨される｡もし､呼出側が､int 場所のみを提供し､且つ､objPtr のバイト配列内のバイト個数がINT_MAXより大きい場合､呼出側に正しくバイト配列寸法を報告できない為に業務譜は失敗する｡int 場所を提供する能力は､9.0より古いTcl 公開 の操作を続ける為に制約された源譜集の為の移住援助を考慮した最善のものである｡ On success, both Tcl_GetBytesFromObj and Tcl_GetByteArrayFromObj write the number of bytes in the byte-array value of objPtr to the space pointed to by numBytesPtr. This space may be of type Tcl_Size or of type int. It is recommended that callers provide a Tcl_Size space for this purpose. If the caller provides only an int space and the number of bytes in the byte-array value of objPtr is greater than INT_MAX, the routine will fail due to being unable to correctly report the byte-array size to the caller. The ability to provide an int space is best considered a migration aid for codebases constrained to continue operating with Tcl releases older than 9.0.

Tcl_SetByteArrayLength は呼出側に､非共有 objPtr 内部表現内のバイト配列の寸法を numBytes になる様変更する事を可能にする｡これは､内部バイト配列が直接に上書きされた後､且つ､要求された寸法が最初の割当てに使用された見積もりと異なることが発見された時に､しばしば便利である｡Tcl_SetByteArrayLength は寸法変更したバイト配列への指示子を返す｡バイト配列の寸法変更は内部表現を変更するので､Tcl_SetByteArrayLength も objPtr 内のどの様な文字列表現も無効にする｡もし寸法変更がバイト配列を大きくすると､新しいバイト値は未定義になる｡もし objPtr が未だ内部バイト配列を保有してない場合､それは､Tcl_GetBytesFromObj が行っているのと､同じ方法で製作される､亦､ objPtr の中の(そのnumBytes 迄の)どれかの値の文字が適正なバイトでない場合､ヌルを返す｡ Tcl_SetByteArrayLength enables a caller to change the size of a byte-array in the internal representation of an unshared objPtr to become numBytes bytes. This is most often useful after the bytes of the internal byte-array have been directly overwritten and it has been discovered that the required size differs from the first estimate used in the allocation. Tcl_SetByteArrayLength returns a pointer to the resized byte-array. Because resizing the byte-array changes the internal representation, Tcl_SetByteArrayLength also invalidates any string representation in objPtr. If resizing grows the byte-array, the new byte values are undefined. If objPtr does not already possess an internal byte-array, one is produced in the same way that Tcl_GetBytesFromObj does, also returning NULL when any characters of the value in objPtr (up to numBytes of them) are not valid bytes.

### 参照回数管理 REFERENCE COUNT MANAGEMENT

Tcl_NewByteArrayObj は Tcl_NewObj の如く常に零-参照対象を返す｡ Tcl_NewByteArrayObj always returns a zero-reference object, much like Tcl_NewObj.

Tcl_SetByteArrayObjとTcl_SetByteArrayLengthはそのobjPtr引数の参照回数を修正しないが､対象が非共有であることを要求する｡ Tcl_SetByteArrayObj and Tcl_SetByteArrayLength do not modify the reference count of their objPtr arguments, but do require that the object be unshared.

Tcl_GetBytesFromObjとTcl_GetByteArrayFromObjはそのobjPtr引数の参照回数を修正しない､それらは唯読むのみ｡ Tcl_GetBytesFromObj and Tcl_GetByteArrayFromObj do not modify the reference count of objPtr; they only read.

### SEE ALSO

Tcl_GetStringFromObj, Tcl_NewObj, Tcl_IncrRefCount, Tcl_DecrRefCount

### KEYWORDS

value, binary data, byte array, utf, unicode
Copyright © 1997 Sun Microsystems, Inc.