StrPut

Copies a string to a memory address or buffer, optionally converting it to a given code page.

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

Parameters

String

Type: String

Any string. If a number is given, it is automatically converted to a string.

String is assumed to be in the native encoding.

Target

Type: Object or Integer

A Buffer-like object or memory address to which the string will be written.

Any object which implements Ptr and Size properties may be used, but this function is optimized for the native Buffer object. Passing an object with these properties ensures that the function does not write memory to an invalid location; doing so could cause crashes or other unpredictable behaviour.

Note: If conversion between code pages is necessary, the required buffer size may differ from the size of the source string. For such cases, call StrPut with two parameters to calculate the required size.

Length

Type: Integer

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

If Length is zero or less than the projected length after conversion (or the length of the source string if conversion is not required), an exception is thrown.

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.

If Target is an object, specifying a Length that exceeds the buffer size calculated from Target.Size is considered an error, even if the converted string would fit within the buffer.

Note: When Encoding is specified, Length should be the size of the buffer (in characters), not the length of String or a substring, as conversion may increase its length.

Note: Length is measured in characters, whereas buffer sizes are usually measured in bytes, as is StrPut's return value. To specify the buffer size in bytes, use a Buffer-like object in the Target parameter.

Encoding

Type: String or Integer

If omitted, the string is simply copied or measured without any conversion taking place. Otherwise, specify the target encoding; for example, "UTF-8", "UTF-16" or "CP936". For numeric identifiers, the prefix "CP" can be omitted only in 4-parameter mode. Specify an empty string or "CP0" to use the system default ANSI code page.

Return Value

Type: Integer

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.

Error Handling

A ValueError is thrown if invalid parameters are detected, such as if the converted string would be longer than allowed by Length or Target.Size.

An OSError is thrown if the conversion could not be performed.

Remarks

Note that the String parameter is always assumed to use the native encoding of the current executable, whereas Encoding specifies the encoding of the string written to the given Target. If no Encoding is specified, the string is simply copied or measured without any conversion taking place.

Related

String Encoding, StrGet, Binary Compatibility, FileEncoding, DllCall, Buffer object, VarSetStrCapacity

Examples

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
}