Blitz3D+ Command Reference

TextCodecError$ ( )

Parameters

None.

Description

Returns the diagnostic message from the most recent text codec failure.

When EncodeText refuses a lossy conversion (returning 0) or DecodeText hits bytes that are not valid in the chosen codec (returning an empty String), the reason lands here as a plain-words message you can show, log, or turn into your own error handling. A typical use: an import screen that tells the player exactly why an old save file could not be read instead of silently mangling their name.

The message describes the most recent codec failure in the current context and is replaced by the next one, so read it straight after the call that failed. It is context-local: a failure inside a Worker Function does not overwrite the main program's message.

Note this covers only the strict text codecs. Filesystem problems report through FilesystemError, and JSON parsing problems through JsonError.

For the full rules, see the Application Data language reference.

Requires Extended mode.

See also: EncodeText, DecodeText, FilesystemError, JsonError.

Example

; TextCodecError Example
; ----------------------
; Requires Extended mode.

; A player picked a name in Chinese - fine in UTF-8, but our
; legacy export format uses the Windows-1252 code page
name$="δΈ–η•Œ"
Print "Exporting player name: "+name
Print ""

; The strict codec refuses a lossy conversion instead of
; silently writing '?' characters - it returns 0
bank=EncodeText(name,TEXT_WINDOWS_1252)
Print "EncodeText(...,TEXT_WINDOWS_1252) returned "+bank+" (0 = failed)"
Print ""

; TextCodecError explains the recoverable codec failure
Print "TextCodecError:"
Print "  "+TextCodecError()
Print ""

; The same name encodes fine as UTF-8
utf8_bank=EncodeText(name,TEXT_UTF8)
Print "As UTF-8 it works: "+BankSize(utf8_bank)+" bytes"
FreeBank utf8_bank

Print ""
Print "Press any key to close the example"
WaitKey

End

Index