StrPut

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

OutputVar := StrPut(String , Address, Length, Encoding = None)

Command  Example: StrPut "Hello World!", &string, 10, "UTF-8"
Function Example: ChrCount := StrPut("Hello World!", &string, 10, "UTF-8")

Parameters

String

Any string. Numbers are also acceptable.

Address

The address at which the string will be written to/read from.

Length

The maximum number of characters to read/write, including the null-terminator if required. See Return Value.

Encoding

The source encoding for StrGet or target encoding for StrPut; for example, "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, the required buffer size in characters if no Address was given, 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 performing any necessary conversion.

Remarks

Note that the String parameter of StrPut and return value of StrGet are always in the native encoding of the current executable, whereas Encoding specifies the encoding of the string written to or read from the given Address. 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.

Scripts which are required to be compatible with AutoHotkey Basic can still use StrPut and StrGet provided that the appropriate script files are installed in a function library. These scripts can be found at the AutoHotkey Community Forum.

Related

Script Compatibility, StrGet,, StrPutVar,, 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)
}