StrPut

文字列をメモリアドレスまたはバッファにコピーし、オプションで指定されたコードページに変換します。

BytesWritten := StrPut(String, Target , Length, Encoding)
BytesWritten := StrPut(String, Target , Encoding)
ReqBufSize   := StrPut(String , Encoding)

パラメータ

String

型：文字列

Any string. 数値が与えられると、自動的に文字列に変換される。

文字列は ネイティブ・エンコーディングであると仮定される。

Target

型：オブジェクトまたは整数

文字列が書き込まれるバッファのようなオブジェクトまたはメモリアドレス。

PtrプロパティとSizeプロパティを実装したオブジェクトであれば何でも使用できますが、この関数はネイティブのBufferオブジェクトに最適化されています。これらのプロパティを持つオブジェクトを渡すことで、関数が不正な場所にメモリーを書き込まないようにします。

注：コード・ページ間の変換が必要な場合、必要なバッファ・サイズはソース文字列のサイズと異なる場合がある。このような場合は、StrPutに2つのパラメータを付けて呼び出し、必要なサイズを計算する。

Length

型：整数

The maximum number of characters to write, including the null-terminator if required.

Lengthがゼロか、変換後の投影長（変換が不要な場合はソース文字列の長さ）より小さい場合、例外がスローされる。

Length must not be omitted when Target is a plain memory address, unless the buffer size is known to be sufficient, such as if the buffer was allocated based on a previous call to StrPut with the same String and Encoding.

Targetがオブジェクトの場合、Target.Sizeから計算されるバッファサイズを超えるLengthを指定すると、変換後の文字列がバッファ内に収まる場合でもエラーとみなされます。

注意：Encodingが指定されている場合、Lengthはバッファのサイズ（文字数）であるべきで、Stringや部分文字列の長さではないはずです。

注： 長さは文字単位で測定されるが、バッファ・サイズは通常バイト単位で測定される。バッファサイズをバイト単位で指定するには、TargetパラメータにBufferライクなオブジェクトを使用します。

Encoding

型：文字列または整数

If omitted, the string is simply copied or measured without any conversion taking place. そうでない場合は、ターゲット・エンコーディングを指定する。例えば、"UTF-8"、"UTF-16"、"CP936"などである。For numeric identifiers, the prefix "CP" can be omitted only in 4-parameter mode. システム・デフォルトのANSIコード・ページを使用する場合は、空文字列または"CP0"を指定する。

戻り値

型：整数

In 4- or 3-parameter mode, this function returns the number of bytes written. A null-terminator is written and included in the return value only when there is sufficient space; that is, it is omitted when Length or Target.Size (multiplied by the size of a character) exactly equals the length of the converted string.

In 2-parameter mode, this function returns the required buffer size in bytes, including space for the null-terminator.

エラー処理

変換後の文字列がLengthや Target.Sizeで許容される長さよりも長い場合など、無効なパラメータが検出された場合はValueErrorがスローされます。

変換が実行できなかった場合はOSErrorがスローされます。

備考

Stringパラメータは常に現在の実行ファイルのネイティブエンコーディングを使用すると仮定されるのに対し、Encodingは指定されたTargetに書き込まれる文字列のエンコーディングを指定することに注意してください。Encodingが指定されていない場合、文字列は変換されることなく、単にコピーまたは測定される。

関連

文字列のエンコード、StrGet、バイナリ互換性、FileEncoding、DllCall、Bufferオブジェクト、VarSetStrCapacity

例

StrPut(str, address, "cp0")  ; Code page 0, unspecified buffer size
StrPut(str, address, n, 0)   ; Maximum n chars, code page 0
StrPut(str, address, 0)      ; Unsupported (maximum 0 chars)

; Returns a Buffer object containing the string.
StrBuf(str, encoding)
{
    ; Calculate required size and allocate a buffer.
    buf := Buffer(StrPut(str, encoding))
    ; Copy or convert the string.
    StrPut(str, buf, encoding)
    return buf
}