文章目录
ConvertString
使用格式
函数作用
将字符串从一种编码转换为另一种编码。 转换后的字符串的长度取决于请求的编码。 输出字节数组中使用的字节数写入encodedSize。 如果输出数组 maxOutputSize 的大小不足以容纳转换后的字符串和终止的“\0”，则函数返回错误并且输出的内容未定义。 无法在请求的编码中表示的字符将替换为最佳匹配字符，由 Windows 函数 WideCharToMultiByte 选择。
示例
// Convert a system variable string value (e.g. input from a panel) into UTF-16 and vice versa
includes
{
#include "Encoding.cin"
}
// handle input of a string, e.g. from a panel
on sysvar TestVars::StringSV
{
byte data[100]; long nrOfBytes; byte data2[200]; long res;
// get the string in UTF-8
sysGetVariableData(sysvar::TestVars::StringSV, data, nrOfBytes);
// convert it to UTF-16
res = ConvertString(data2, nrOfBytes, elcount(data2), CP_UTF16, data, nrOfBytes, CP_UTF8);
// now use the UTF-16 bytes, e.g. send them over a network
// here simulated by using a system variable of type data
sysSetVariableData(sysvar::TestVars::DataVar, data2, nrOfBytes);
}
// receive UTF-16 data, e.g. from a network
// here simulated by using a system variable of type data
on sysvar TestVars::DataVar
{
byte data[200]; long nrOfBytes; byte data2[100]; long res;
sysGetVariableData(sysvar::TestVars::DataVar, data, nrOfBytes);
// data is the string in UTF-16; convert it to UTF-8
res = ConvertString(data2, nrOfBytes, elcount(bytes), CP_UTF8, data, nrOfBytes, CP_UTF16);
// copy the string into a system variable of type string, e.g. to display it in a panel
sysSetVariableData(sysvar::TestVars::OutStringVar, data2, nrOfBytes);
}
DecodeString
使用格式
函数作用
解码字符串的长度取决于给定的编码。 如果输出数组 outputSize 的大小不足以容纳解码的字符串和终止的“\0”，则函数将返回错误并且输出的内容未定义。 无法在当前编码中表示的字符将替换为由 Windows 函数 WideCharToMultiByte 选择的最佳匹配字符。 与 WideCharToMultiByte Windows 函数不同，char 数组输出总是以“\0”结尾。 CAPL 字符串编码通常与源文件的编码相匹配。 当您使用 CAPL 浏览器创建文件时，它会以与您计算机的语言设置相匹配的编码保存文件，并将编码写入文件开头的特殊注释中。 如果源文件以 UTF-16 编码，或者包含文件的编码与源文件不同，则 CAPL 字符串编码将为 UTF-8。
示例
includes
{
#include "Encoding.cin"
}
...
{
int result;
char text[10];
byte stream[6] = {0xC3, 0xA4, 0xC3, 0xB6, 0xC3, 0xBC};
result = DecodeString(text, 10, stream, 6, CP_UTF8);
// on German Windows, text is now {‘ä’, ‘ö’, ‘ü’, 0}
if (result == 0) {
write(text);
// Output (on a German Windows): äöü
}
}
EncodeString
使用格式
函数作用
使用编码代码页对输入的字符串进行编码。编码字符串的长度和终止的“\0”取决于请求的编码。输出字节数组中使用的字节数写入encodedSize。如果输出数组 maxOutputSize 的大小不足以容纳编码字符串和“\0”，则函数返回错误并且输出数组的内容未定义。无法在请求的编码中表示的字符将被替换与最佳匹配字符，由 Windows 函数 WideCharToMultiByte 选择。CAPL 字符串编码通常与源文件的编码匹配。当您使用 CAPL 浏览器创建文件时，它会以与您计算机的语言设置相匹配的编码保存文件，并将编码写入文件开头的特殊注释中。如果源文件以 UTF-16 编码，或者包含文件的编码与源文件不同，则 CAPL 字符串编码将为 UTF-8。
示例
includes
{
#include "Encoding.cin"
}
...
{
int result;
char text[4] = "äöü";
byte stream[10];
long len;
result = EncodeString(stream, len, 10, text, CP_UTF8);
// on German Windows, len is now 7, stream is now {0xC3, 0xA4, 0xC3, 0xB6, 0xC3, 0xBC, 0};
if (result == 0) {...}
}
ltoa
使用格式
函数作用
数字 val 被转换为字符串 s。 在这种情况下，base 表示一个介于 2 和 36 之间的数字基数。s 必须足够大以接受转换后的数字！
示例
char s1[9];
char s2[9];
ltoa(z,s1,2);
ltoa(z,s2,10);
write("z: %d s1= %s",z, s1);
write("z: %d s2= %s",z, s2);
...
Result:
z: 255 s1= 11111111
z: 255 s2= 255
mbstrlen
使用格式
函数作用
函数结果是字符串 s 的长度（以字符为单位）。
示例
long length;
char s1[10] = "door";
char s2[10] = "Tür";
write("%d %d", mbstrlen(s1), strlen(s1)); // 4 4
write("%d %d", mbstrlen(s2), strlen(s2)); // 3 [3 or 4 depending on file encoding]
mbstrncmp / mbstrncmp_off
使用格式
函数作用
此函数将 s1 与 s2 进行最多 len 个字符的比较。如果它们相同，则函数结果为 0。如果 s1 小于 s2，则结果为 -1，否则为 +1。比较从 s1 处的 s1offset（形式 3）开始，并且 在 s2 处的 s2offset（表格 2 和表格 3）。
示例
char s[50] = "'Tür' is the german word for 'door'.";
write("%d", mbstrncmp_off(s, 13, "german", 0, 6)); // 0
mbstrncpy / mbstrncpy_off
使用格式
函数作用
mbstrncpy 函数将 src 复制到 dest。 len 表示要复制的字符数； 使用 -1 表示将尽可能多地复制到 dest 中（最大直到 src 结束）。 该函数确保有一个终止的 0 字节； 但与 strncpy 相比，该字节不计入 len.mbstrncpy_off 覆盖目标缓冲区中从字符偏移 destOffset 开始的字符。
示例
char s1[50] = "eine grüne "; // german for 'a green'
char s2[10] = "Türen"; // german for 'doors'
mbstrncpy_off(s1, 11, s2, 3);
write("%s", s1); // eine grüne Tür (german for 'a green door')
mbstrstr / mbstrstr_off
使用格式
函数作用
在 s1 中搜索 s2。
示例
long pos;
char s[50] = "'Tür' is german for 'door'";
pos = mbstrstr(s, "german");
write("%d", pos); // 9
mbsubstr_cpy / mbsubstr_cpy_off
使用格式
函数作用
mbsubstr_cpy 将 src 的一个子串复制到 dest。 len 表示要复制的字符数； 使用 -1 表示将尽可能多地复制到 dest 中（最大直到 src 结束）。 该函数确保有一个终止的 0 字节； 但与 substr_cpy/substr_cpy_off 相比，该字节不计入 len.mbsubstr_cpy_off 覆盖目标缓冲区中从字符偏移 destOffset 开始的字符。
示例
char s1[50] = "eine grüne "; // german for 'a green'
char s2[20] = "schöne Türen"; // german for 'beautiful doors'
mbsubstr_cpy_off(s1, 11, s2, 7, 3);
write("%s", s1); // eine grüne Tür (german for 'a green door')