StrPut

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

StrPut String , Encoding := None 
StrPut String, Target , Length , Encoding := None

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 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 Source and Encoding.

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

The target encoding; for example, "UTF-8", "UTF-16" or "CP936". For numeric identifiers, the prefix "CP" can be omitted only if Length is specified. Specify an empty string or "CP0" to use the system default ANSI code page.

Return Value

Type: Integer

This function returns the number of bytes written. If no Target was given, it returns the required buffer size in bytes. If Length is exactly the length of the converted string, the string is not null-terminated; otherwise the returned size includes the null-terminator.

Error Handling

An exception is thrown if invalid parameters are detected, or if the conversion cannot 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 measured or copied without any conversion taking place.

Related

String Encoding, StrGet, Script Compatibility, FileEncoding, DllCall, BufferAlloc, Buffer object, VarSetStrCapacity

Examples

#1: Either Length or Encoding may be specified directly after Target, but in those cases Encoding must be non-numeric:

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)

#2: StrPut may be called once to calculate the required buffer size for a string in a particular encoding, then again to encode and write the string into the buffer. The process can be simplified by adding one of these functions to your library:

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