CodePage Functions

A CodePage is an integer value stored in each object. This value is used when SDS <> DDS conversions are performed (explicitly or automatically).

Windows system CodePages
Code Pages Identifiers
Windows Locale Identifiers



[1]
xStr(#sysCP) | strX.sysCP() get System CodPage
  Returns Integer CodePage / <err>
     
  Description Returns the system's code page
     
  Examples put xStr(#sysCP) --or: put _s().sysCP()
-- 1253
     
  Notes  

[2]
xStr(#glbCP {, CP})  |  strX.glbCP( {CP} ) get / set Xtra's default CodePage
  Returns Integer CodePage / <err>
  CP Integer new default CodePage
     
  Description When used with no arguments, or CP is non integer, this command will return the Xtra's default CodePage, which will initially be the system's CodePage.
When a non-zero integer CP is passed, and if CP is a valid CodePage, it will become the Xtra's default CodePage - and will be returned as the result of this command. Otherwise, an <err> will be returned.
If CP is -1, the glbCP value will be reset to the system's default code page.
The glbCP will be used as the CodePage of strings created without explicitly specifying one.
     
  Examples put xStr(#glbCP)       --get / or: put _s().glbCP()
-- 1253
put _s("abc").cp
-- 1253
put xStr(#glbCP, 1255) --set / or: _s().glbCP(1251
-- 1255
put _s("someData").cp
-- 1255
put _s().glbCP(-1)      --reset to system's CP
-- 1253
     
  Notes When changing the glbCP, the Xtra will automatically convert certain internal strings, so that they comply to the new setting, in order to increase performance on certain operations.
It will not change however user modifiable values, like the item and word delimiters. After changing the glbCP, resetting these values will increase performance on commands that use them.

[3]
xStr(#cpList {, #all} )  |  strX.cpList( {#all} ) get Installed / Supported Code Pages
  Returns List / <err>
  #all Return all supported CodePages.
     
  Description Returns a list containing the code page conversion tables installed to the system.
If the optional #all argument is used, the list will contain all code page tables - both installed and supported but not installed.
     
  Examples put xStr(#cpList) --or: put _s().cpList()
-- [10000, 10006, 10007, 10010, 10017, 10029, 10079, 10081, 10082, 1026, 1250, 1251, 1252, 1253, 1254, 1255, 1256, 1257, 1258, 1361, 20127, 20261, 20866, 21866, 28591, 28592, 28594, 28595, 28597, 28599, 28605, 37, 437, 500, 737, 775, 850, 852, 855, 857, 860, 861, 863, 865, 866, 869, 874, 875, 932, 936, 949, 950, 28603, 65000, 65001]

put xStr(#cpList, #all)
-- [10000, 10001, 10002, 10003, 10004, 10005, 10006, 10007, 10008, 10010, 10017, 10021, 10029, 10079, 10081, 10082, 1026, 1047, 1140, 1141, 1142, 1143, 1144, 1145, 1146, 1147, 1148, 1149, 1250, 1251, 1252, 1253, 1254, 1255, 1256, 1257, 1258, 1361, 20000, 20001, 20002, 20003, 20004, 20005, 20105, 20106, 20107, 20108, 20127, 20261, 20269, 20273, 20277, 20278, 20280, 20284, 20285, 20290, 20297, 20420, 20423, 20424, 20833, 20838, 20866, 20871, 20880, 20905, 20924, 20932, 20936, 20949, 21025, 21027, 21866, 28591, 28592, 28593, 28594, 28595, 28596, 28597, 28598, 28599, 28605, 37, 38598, 437, 500, 51949, 50220, 50221, 50222, 50225, 50227, 50229, 52936, 57002, 57003, 57004, 57005, 57006, 57007, 57008, 57009, 57010, 57011, 708, 720, 737, 775, 850, 852, 855, 857, 858, 860, 861, 862, 863, 864, 865, 866, 869, 870, 874, 875, 932, 936, 949, 950, 28603, 54936, 65000, 65001]
     
  Notes Windows: Code Pages can be added/removed from the Regional and Language options, advanced Tab.
Windows: When removing an installed code page, though the code page will not be included in the cpList , the cp will be valid for creating strings until the next system boot.

[4]
xStr(#cpInfo, CP)  |  strX.cpInfo( { CP } ) get CodePage Info
  Returns PropList / <err>
  CP Integer CodePage to return info for.
     
  Description Returns a propList containing info for the CP code page. If CP is not a valid code page, or the operation fails, an <err> is returned.
If CP is zero, or non integer, info for the glbCP will be returned.
When used on a string, and if no CP is passed, info for the string's code page will be returned.
If used on strX, and CP is not defined, the command will return info for the strX's CP.

result PropList Entries:
#cp CodePage
#sysName The name of the code page, as defined by the underlying OS.
#netName

The name of the code page, as used by network apps (e.g. 'charset' for html pages).

Note: these values are pooled from an internal database. Please report possible errors / omissions for your own, or other known languages.

#maxBPC Maximum BytesPerCharacter. For SDSs, a value of 1 indicates a SBCS, while 2 an MBCS string.
#sysNMC Usually '?'. The character that the system will use to display characters not belonging to this character set, while converting a double to a single byte per digit string.
#lbtArr For SBCS code pages, this will be an empty List. For MBCS code pages, it will be a list containing lead byte ranges: If an SDS's digit (byte) belongs in one of these ranges, then it is the first digit of a two-digit character.
     
  Examples put _s().cpInfo(1251) --or: put xStr(#cpInfo, 1251)
-- [#cp: 1251, #sysName: ANSI - Cyrillic, #netName: windows-1251, #maxBPC: 1, #sysNMC: ?, #lbtArr: []]

put _s("abc", 1255).cpInfo(932)
-- [#cp: 932, #sysName: ANSI/OEM - Japanese Shift-JIS, #netName: shift_jis, #maxBPC: 2, #sysNMC: ?, #lbtArr: [[129, 159], [224, 252]]]

put _s("abc", 1255).cpInfo()
-- [#cp: 1255, #sysName: ANSI - Hebrew, #netName: windows-1255, #maxBPC: 1, #sysNMC: ?, #lbtArr: []]
     
  Notes  

[5]
strX.cp( { CP } )  | strX.cp get / set object's CodePage
  Returns Integer / strX / <err>
  CP Integer CodePage to set as the object's code page.
     
  Description get: When used with no arguments, returns the string's code page - same as accessing the .cp property.

set: When an integer CP is passed to the command, and if CP is a valid code page (or -1, for glbCP), strX's code page will be changed to CP. If CP is invalid, an <err> will be returned. Otherwise, the original strX will be returned to the command line.
     
  Examples put _s("abc").cp()
-- 1253
put _s("abc").cp(1255).cp
-- 1255
     
  Notes When setting a new code page, the new value is applied to the original string object. The object's binary contents remain untouched, as opposed to e.g. using the str.toS(newCP) command, which will return a new object after performing data conversion.

[6]
strX.lc( { LC } ) get object's LocaleID / set object's CP from LocaleID
  Returns Integer / strX / <err>
  LC Integer LocaleID.
     
  Description get: When used with no arguments, returns the first Locale ID compatible with the string's code page.
set: When an integer LC is passed to the command, the Xtra will try to find the CodePage that matches the Locale ID LC. If successful, it will set the result as the strX's code page, and the original strX will be returned to the command line.
Like with setting the .cp(), the string's binary content is not affected by the .lc() command.
     
  Examples put _s("abc", 1252).lc()          
-- 1027                            -- 1027 = hex0403 = Catalan
put _s("abc", 1252).lc(1033).cp()  -- 1033 = hex0409 = English US.
-- 1252

Both Catalan and English US use the CodePage 1252 (ANSI - Latin I).
1027 is less than 1033, so 1027 is returned as the lc of a string whose code page is 1252.
     
  Notes The same code page may be used by more than one Locale IDs: a code page defines a character set, while a locale, a country-language pair. When instructed to return a locale, the Xtra will browse the available locales, and return the first one compatible with the strings' code page.

[7]
_s({#standard}).getSCPL() returns a list containing the supported SBCS CodePages
  #standard #win (default) or #mac
  Returns 0 / <err>
     
  Description Returns a list containing all the available SBCS code pages. If the codepage of a specific language is not installed, unicode strings containing characters of that language cant be split to a list of SDS strings (toSL command). This affects mostly mac conversions, and older Windows platforms - all Windows SBCS code pages are installed by default on Win 2k and newer.
     
  Examples

put _s().getSCPL()
-- [1250, 1251, 1252, 1253, 1254, 1255, 1256, 1257, 1258, 874]
put _S().getSCPL(#mac)
-- [10029, 10000, 10006, 10007, 10010, 10017, 10079, 10081, 10082]
     
  Notes Support for mac code pages is not installed by default on Windows machines. To add mac support, you'll have to add the desired code pages through the Regional Options in the Control Panel.

[8]
_s().renewSCPL() refresh the SBCS list
  Returns 0 / <err>
     
  Description The list of the supported CodePages is requested from the sustem upon initialization. At that time, special buffers are being created, in order to speed up the toSL command. If support for a codepage is added or removed, this command can be used to refresh internal lists, and rebuild and required buffers.
     
  Examples

put _s().renewSCPL()

-- 0

     
  Notes