StrGet

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

String := StrGet(Source , Length , Encoding := None)

Parameters

Source

Type: Object or Integer

A Buffer-like object containing the string, or the memory address of the string.

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 read memory from an invalid location; doing so could cause crashes or other unpredictable behaviour.

The string is not required to be null-terminated if a Buffer-like object is provided, or if the Length parameter is specified.

Length

Type: Integer

The maximum number of characters to read. This can be omitted if the string is null-terminated.

By default, StrGet only copies up to the first binary zero. If Length is negative, its absolute value indicates the exact number of characters to convert, including any binary zeros that the string might contain - in other words, the result is always a string of exactly that length.

Note: Omitting Length when the string is not null-terminated may cause an access violation which terminates the program, or some other undesired result. Specifying an incorrect length may produce unexpected behaviour.

Encoding

Type: String or Integer

The source 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: String

This function returns the copied or converted string. If the source encoding was specified correctly, the return value always uses the native encoding. It is always null-terminated, but the null-terminator is not included in the return value's length except when Length is negative as described above.

Error Handling

An exception is thrown if invalid parameters are detected, or if the conversion cannot be performed.

Remarks

Note that the return value is always in the native encoding of the current executable, whereas Encoding specifies how to interpret the string read from the given Source. If no Encoding is specified, the string is simply copied without any conversion taking place.

In other words, StrGet is used to retrieve text from a memory address or buffer, or convert it to a format the script can understand.

If conversion between code pages is necessary, the length of the return value may differ from the length of the source string.

Related

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

Examples

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

str := StrGet(address, "cp0")  ; Code page 0, unspecified length
str := StrGet(address, n, 0)   ; Maximum n chars, code page 0
str := StrGet(address, 0)      ; Maximum 0 chars (always blank)