Приложения

Приложение А. Функции, константы и структуры RDS

А.5. Сервисные функции и макросы RDS

А.5.4. Отведение памяти и преобразование строк

А.5.4.12. rdsProcessText – обработка строки

Функция rdsProcessText выполняет над переданной ей строкой указанную операцию и возвращает результат в виде динамически созданной строки.

  RDSSTR RDSCALL rdsProcessTextA( // UTF8
    RDSCSTR String,  // Исходная строка (UTF8)
    int Operation,   // Операция (RDS_PT_*)
    int *pLength     // Возвращаемая длина строки
  );
  RDSWSTR RDSCALL rdsProcessTextW( // UTF16
    RDSWCSTR String, // Исходная строка (UTF16)
    int Operation,   // Операция (RDS_PT_*)
    int *pLength     // Возвращаемая длина строки
  );
  // Функция-псевдоним
  RDSXSTR RDSCALL rdsProcessText( // Кодировка по умолчанию
    RDSXCSTR String, // Исходная строка (кодировка по умолчанию)
    int Operation,   // Операция (RDS_PT_*)
    int *pLength     // Возвращаемая длина строки
  );

Тип указателя на эту функцию

RDS_SSIpI (для UTF8) или RDS_WsWsIpI (для UTF16)

Параметры

String (RDSCSTR, RDSWCSTR, RDSXCSTR)

Указатель на исходную строку.

Operation (int)

Выполняемое над строкой преобразование:

RDS_PT_ANSITOUTF8	Строка в старой кодировке (например, CP1251) преобразуется в кодировку UTF8. Преобразование выполняется только в версии функции rdsProcessTextA, то есть только для строк с однобайтовыми символами char. Для строк в UTF16 всегда возвращается NULL.
RDS_PT_UTF8TOANSI	Строка в кодировке UTF8 преобразуется в старую кодировку согласно текущей кодовой странице. Преобразование выполняется только в версии функции rdsProcessTextA, то есть только для строк с однобайтовыми символами char. Для строк в UTF16 всегда возвращается NULL.
RDS_PT_CODEHIGHCHARSU8	Все байты в строке UTF8 с взведенным старшим битом заменяются на «\xNN», где NN – шестнадцатеричный код байта. При вызове функции rdsProcessTextW для строки в кодировке UTF16 эта строка сначала переводится в UTF8, а затем выполняется преобразование.
RDS_PT_QUOTECHIGHCHARSU8	Переданный в функцию текст анализируется как программа на языке C, и внутри всех строк в двойных кавычках без префиксов выполняется описанное выше преобразование RDS_PT_CODEHIGHCHARSU8.
RDS_PT_ENCODEURICOMP	Все байты в строке UTF8, не являющиеся символами латинского алфавита, цифрами, а также символами из набора «~!*()'», заменяются на «%NN», где NN – шестнадцатеричный код байта (подобным образом преобразуются URI в языке JavaScript). При вызове функции rdsProcessTextW для строки в кодировке UTF16 эта строка сначала переводится в UTF8, а затем выполняется преобразование.
RDS_PT_DECODEURICOMP	Преобразование, обратное у описанному выше RDS_PT_ENCODEURICOMP.
RDS_PT_FIXLEGACYSYMBOL	Перекодировка различных специальных символов шрифта «Symbol» в соответствующие символы Unicode. Это преобразование может использоваться при загрузке личных данных блоков схем, сохраненных в версии RDS 1.x.
RDS_PT_GETVARNAME	Находит в строке первый пробел, апостроф или двойную кавычку, и возвращает начальный фрагмент строки после этого символа без начальных и конечных пробелов. Может использоваться для разбора имен переменных блоков с комментариями вида «имя комментарий», в этом случае возвращает имя переменной.
RDS_PT_GETVARREMARK	Находит в строке первый пробел, апостроф или двойную кавычку, и возвращает конечный фрагмент строки до этого символа без начальных и конечных пробелов и кавычек. Может использоваться для разбора имен переменных блоков с комментариями вида «имя комментарий», в этом случае возвращает комментарий.
RDS_PT_LOWERCASE	Все символы строки преобразуются в нижний регистр.
RDS_PT_UPPERCASE	Все символы строки преобразуются в верхний регистр.
RDS_PT_ANSILOWERCASE	Устаревший синоним RDS_PT_LOWERCASE.
RDS_PT_ANSIUPPERCASE	Устаревший синоним RDS_PT_UPPERCASE.
RDS_PT_REMOVECRLF	Заменяет все коды переводов строк (10, «\n») на пробелы и удаляет все коды возвратов каретки (13, «\r»).
RDS_PT_TEXTTOSTRING	Непечатаемые символы в строке заменяются на их символические обозначения (возврат каретки заменяется на «\r», перед знаком кавычки вставляется обратная косая черта, нестандартные коды заменяются на их шестнадцатеричное представление с префиксом «\x» и т.д.). После такого преобразования строка гарантированно содержит только печатаемые коды символов и ее можно, например, записать в INI-файл. Такая строка может быть однозначно преобразована обратно вызовом этой же функции с параметром RDS_PT_STRINGTOTEXT.
RDS_PT_TEXTTOSTRINGSL	Выполняет описанное выше преобразование RDS_PT_TEXTTOSTRING, дополнительно заменяя символ «/» на его код с префиксом «\x».
RDS_PT_STRINGTOTEXT	Символические представления непечатаемых символов в строке заменяются на коды этих символов. Это операция, обратная операции RDS_PT_TEXTTOSTRING.
RDS_PT_TRIM	Удаляет начальные и конечные пробелы, символы табуляции, переводы строк и возвраты каретки.
RDS_PT_VARTYPETEXT	Формируется строка, содержащая текстовое описание типа переменной, которое соответствует первому символу строки String, если считать его однобайтовой константой типа RDS_VARTYPE_*. Полученные в результате этой операции строки можно показывать пользователю при редактировании переменных блоков.
RDS_PT_VARTYPECHAR	Текстовое описание переменной из строки String преобразуется в строку, состоящую из единственного символа типа этой переменной RDS_VARTYPE_*. Это операция, обратная операции RDS_PT_VARTYPETEXT.

Любое другое значение параметра Operation приводит к возврату значения NULL.

pLength (int*)

Указатель на целую переменную, в которую функция запишет длину созданной динамической строки. Если вызвавшей программе не нужно это значение, в pLength можно передать NULL.

Возвращаемое значение

Указатель на созданную в динамической памяти строку, являющуюся результатом преобразования Operation, примененного к строке String. В случае недопустимой операции возвращается NULL.

Примечания

Динамическая строка, созданная функцией rdsProcessText, должна быть обязательно освобождена функцией rdsFree.

Операция RDS_PT_TEXTTOSTRING переводит произвольную строку в текст, пригодный для сохранения, записи или вставки в программу путем замены символов на их условные обозначения по правилам языка C согласно следующей таблице:

Обратная операция, RDS_PT_STRINGTOTEXT, преобразует строку с условными обозначениями символов в строку с кодами этих символов.

Операция RDS_PT_VARTYPETEXT переводит однобайтовый тип переменной в его название, пригодное для показа пользователю:

Остальные типы после выполнения операция RDS_PT_VARTYPETEXT дают пустую строку. Обратная операция, RDS_PT_VARTYPECHAR, переводит название типа (включая альтернативные варианты, указанные в скобках) в строку с константой этого типа. Если название типа не опознано, тип считается структурой и возвращается строка из одного символа «{» (RDS_VARTYPE_STRUCT).

См. также

Типы переменных RDS, rdsListVarTypes, rdsFree, rdsGetFullFilePath, rdsGetRelFilePath, rdsStringReplace.