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 ] )
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 | An 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. |
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.
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.
Script Compatibility, FileEncoding, VarSetCapacity()
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) }