Routines for converting between different character encodings. On UNIX, this uses the iconv library, on Windows the Windows API.
The following example shows how to change character encodings.
Example:
import std/encodings when defined(windows): let orig = "öäüß" # convert `orig` from "UTF-8" to "CP1252" cp1252 = convert(orig, "CP1252", "UTF-8") # convert `cp1252` from "CP1252" to "ibm850" ibm850 = convert(cp1252, "ibm850", "CP1252") current = getCurrentEncoding() assert orig == "\195\182\195\164\195\188\195\159" assert ibm850 == "\148\132\129\225" assert convert(ibm850, current, "ibm850") == origThe example below uses a reuseable EncodingConverter object which is created by open with destEncoding and srcEncoding specified. You can use convert on this object multiple times.
Example:
import std/encodings when defined(windows): var fromGB2312 = open("utf-8", "gb2312") let first = "\203\173\197\194\163\191\210\187" & "\203\242\209\204\211\234\200\206\198\189\201\250" assert fromGB2312.convert(first) == "谁怕?一蓑烟雨任平生" let second = "\211\208\176\215\205\183\200\231" & "\208\194\163\172\199\227\184\199\200\231\185\202" assert fromGB2312.convert(second) == "有白头如新,倾盖如故"
Types
EncodingConverter = ptr ConverterObj
- Can convert between two character sets. Source Edit
EncodingError = object of ValueError
- Exception that is raised for encoding errors. Source Edit
Procs
proc close(c: EncodingConverter) {....raises: [], tags: [].}
- Frees the resources the converter c holds. Source Edit
proc convert(c: EncodingConverter; s: string): string {....raises: [OSError], tags: [].}
-
Converts s to destEncoding that was given to the converter c. It assumes that s is in srcEncoding.Warning: UTF-16BE and UTF-32 conversions are not supported on Windows.Source Edit
proc convert(s: string; destEncoding = "UTF-8"; srcEncoding = "CP1252"): string {. ...raises: [EncodingError, OSError], tags: [].}
-
Converts s to destEncoding. It assumed that s is in srcEncoding. This opens a converter, uses it and closes it again and is thus more convenient but also likely less efficient than re-using a converter.Warning: UTF-16BE and UTF-32 conversions are not supported on Windows.Source Edit
proc getCurrentEncoding(uiApp = false): string {....raises: [], tags: [].}
- Retrieves the current encoding. On Unix, "UTF-8" is always returned. The uiApp parameter is Windows specific. If true, the UI's code-page is returned, if false, the Console's code-page is returned. Source Edit
proc open(destEncoding = "UTF-8"; srcEncoding = "CP1252"): EncodingConverter {. ...raises: [EncodingError], tags: [].}
- Opens a converter that can convert from srcEncoding to destEncoding. Raises IOError if it cannot fulfill the request. Source Edit