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



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.


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.


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


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

If Target is omitted, this function returns the required buffer size in bytes, including space for the null-terminator.

If Target is specified, 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.

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.


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.

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


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)

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 utilizing this function.

; 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