StrPut() / StrGet() [AHK_L 46+]

Copies a string to or from a memory address, optionally converting it between code pages.

StrPut(String [, Encoding = None ] )
StrPut(String, Address [, Length] [, Encoding = None ] )
StrGet(Address [, Length] [, Encoding = None ] )

Parameters

StringAny string. Numbers are also acceptable.
AddressThe address at which the string will be written to/read from.
LengthThe maximum number of characters to read/write, including the null-terminator if required. See Return Value.
EncodingAn encoding, such as "UTF-8", "UTF-16" or "CP936". If Address and Length are not specified, numeric identifiers must be prefixed with "CP". Specify an empty string or "CP0" to use the system default ANSI code page.

Return Value

For either function, invalid parameters cause an empty string to be returned.

StrPut returns the number of characters written, or 0 if an error occurred. If Length is less than the length of the source string, the function fails and returns 0. If Length is exactly the length of the source string, the string is not null-terminated; otherwise the returned count includes the null-terminator.

StrGet returns the requested string after any necessary conversion.

Remarks

If no Encoding is specified, the string is simply measured or copied without any conversion taking place.

If conversion between code pages is necessary, the required buffer size may differ from the size of the source String.

Related

Script Compatibility, FileEncoding, VarSetCapacity()

Examples

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

strA := StrGet(addressA, "cp0")     ; OK
strA := StrGet(addressA, length, 0) ; OK
strA := StrGet(addressA, 0)         ; Error

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. If you frequently use variables with StrPut, consider adding this function to your library:

StrPutVar(string, ByRef var, encoding)
{
    ; Ensure capacity.
    VarSetCapacity( var, StrPut(string, encoding)
        ; StrPut returns char count, but VarSetCapacity needs bytes.
        * ((encoding="utf-16"||encoding="cp1200") ? 2 : 1) )
    ; Copy or convert the string.
    return StrPut(string, &var, encoding)
}