DecodeText$ ( bank[,offset][,count][,code_page] )
Parameters
|
bank - the Bank holding the encoded bytes offset (optional) - first byte of the range to decode; 0 (default) count (optional) - number of bytes to decode; -1 decodes everything from offset to the end of the Bank (default) code_page (optional) - the codec the bytes are in: TEXT_UTF8: strict UTF-8 (default) TEXT_WINDOWS_1252: Windows-1252 TEXT_SYSTEM_ANSI: the machine's active ANSI code page |
Description
|
Decodes a range of Bank bytes into a String using a strict codec. This is the exact inverse of EncodeText, and the tool for reading text out of binary data: a player name field inside an old save file, a chat line received into a network Bank, or a legacy export written in Windows-1252 before your game moved to UTF-8. The offset and count parameters let you decode just the text field without copying it out of the Bank first. The codecs are strict: if the bytes are not valid in the chosen codec (for example broken UTF-8 from a corrupt file), DecodeText does not guess or substitute characters - it returns an empty String and TextCodecError tells you what was wrong. Since a genuinely empty range also returns an empty String, check TextCodecError when "" is a surprise. Passing a code page other than the three constants is a programming error and stops the program. TEXT_SYSTEM_ANSI depends on the machine your game is running on and exists for legacy compatibility only - files you intend to read back anywhere should be written as TEXT_UTF8. For the full rules, see the Application Data language reference. Requires Extended mode. See also: EncodeText, TextCodecError, PeekByte, ReadBytes. |
Example
; DecodeText Example ; ------------------ ; Requires Extended mode. ; An old game's save file stored the player name in the legacy ; Windows-1252 code page: C a f é as the bytes 67 97 102 233 bank=CreateBank(4) PokeByte bank,0,67 PokeByte bank,1,97 PokeByte bank,2,102 PokeByte bank,3,233 Print "Legacy bytes in the bank: 67 97 102 233" Print "" ; DecodeText converts a Bank range to a UTF-8 String using the ; selected strict codec - name the legacy code page explicitly name$=DecodeText(bank,0,BankSize(bank),TEXT_WINDOWS_1252) If name="" Then RuntimeError TextCodecError() Print "Decoded as Windows-1252: "+name Print "" ; Offset and count select a sub-range - just the first 3 bytes Print "First three bytes only: "+DecodeText(bank,0,3,TEXT_WINDOWS_1252) Print "" ; Note: byte 233 alone is NOT valid UTF-8, so decoding the same ; bank with the default strict UTF-8 codec would fail - always ; know which encoding legacy data really uses. FreeBank bank Print "" Print "Press any key to close the example" WaitKey End
Index