StrPut() / StrGet()

Author: Lexikos Last Modified: 20100629


Copies a string to or from a memory address, optionally converting it between code pages. Behaviour should be identical to their built-in counterparts in AutoHotkey_L.

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

Recommended usage: copy StrPut.ahk and StrGet.ahk into a function library folder. Do not #include. This way, if your script is run on AutoHotkey_L, it will use the built-in functions rather than these script functions.

The two functions are not depend on each other. I *Tuncay* decided to mark them as standalone (usable without another library), but make a dependency note. At least the examples work then correctly.

For update's details and remarks related to the functions, please see the AutoHotkey Forum: http://www.autohotkey.com/forum/viewtopic.php?t=59738

License

The functions is an open source item under the Public Domain license. For details, please see lexikos-license.txt

Example

; #Include strPut.ahk
; #Include strGet.ahk
#NoEnv
SendMode Input
SetWorkingDir %A_ScriptDir%

input := ""
output := ""

; Write the string "Hello World!" into variable with default ANSI code page.
; Display how many characters are written.
MsgBox % StrPutVar("Hello World!", input, "cp0")

; Get string from adress of variable "input" with default ANSI code page.
output := StrGet(&input, "cp0")

; Display the output string.
MsgBox %output%

; If you use frequently StrPut() with variables, consider to add this function.
; Function copied from StrPutGet-documentation written by Lexikos.
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)
}

; 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) }