Текущий раздел:

Описания RDS

Приложения

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

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

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

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

# Приложения

## Приложение А. Функции, константы и структуры 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 согласно следующей таблице:

Символ или его код | Условное обозначение (по правилам языка C)
--- | ---
Пробел, печатаемые спецсимволы, символы латинского и русского алфавитов | Условного обозначения нет, символ не изменяется
Код 7 (код звукового сигнала) | \a
Код 8 (Backspace) | \b
Код 12 (перевод страницы) | \f
Код 10 (перевод строки) | \n
Код 13 (возврат каретки, Enter) | \r
Код 9 (табуляция) | \t
Код 11 (вертикальная табуляция) | \v
Обратная косая черта | Удвоенная обратная косая черта («\\»)
' (апостроф, код 39) | \' (обратная косая черта, за которой следует апостроф)
" (кавычка, код 34) | \" (обратная косая черта, за которой следует кавычка)
Прочие непечатаемые символы | \xNN, где NN – шестнадцатеричный код символа. Например, символ с кодом 255 будет преобразован в «\xff».

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

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

Символ | Константа типа в RDS | Название типа согласно RDS_PT_VARTYPETEXT
--- | --- | ---
S | RDS_VARTYPE_SIGNAL | «double»
L | RDS_VARTYPE_LOGICAL | «Логический»
C | RDS_VARTYPE_CHAR | «char»
H | RDS_VARTYPE_SHORT | «short»
I | RDS_VARTYPE_INT | «int»
F | RDS_VARTYPE_FLOAT | «float»
D | RDS_VARTYPE_DOUBLE | «double»
A | RDS_VARTYPE_STRING | «Строка»
V | RDS_VARTYPE_RUNTIME | «произвольный» (при обратном преобразовании допускается «Произв.»)
M | RDS_VARTYPE_ARRAY | «Матрица» (при обратном преобразовании допускается «Массив»)

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

См. также

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