Приложения

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

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

А.5.11. Разбор текста

А.5.11.3. rdsGetTextWordDyn – извлечение слова из текста

Функция rdsGetTextWordDyn считывает из переданной в параметрах строки очередное слово и возвращает его в виде динамически созданной строки. Переданная в параметрах строка должна иметь кодировку UTF8.

  RDSSTR RDSCALL rdsGetTextWordDynA( // UTF8
    RDSCSTR Start,       // Начало текста (UTF8)
    RDSCSTR *pNextWord,  // Возврат – следующее слово (UTF8)
    char *pSym,          // Вид слова
    BOOL LowerCase       // Перевести в нижний регистр
  );
  RDSWSTR RDSCALL rdsGetTextWordDynW( // UTF16
    RDSCSTR Start,       // Начало текста (UTF8)
    RDSCSTR *pNextWord,  // Возврат – следующее слово (UTF8)
    char *pSym,          // Вид слова
    BOOL LowerCase       // Перевести в нижний регистр
  );
  // Функция-псевдоним
  RDSXSTR RDSCALL rdsGetTextWordDyn( // Кодировка по умолчанию
    RDSCSTR Start,       // Начало текста (UTF8)
    RDSCSTR *pNextWord,  // Возврат – следующее слово (UTF8)
    char *pSym,          // Вид слова
    BOOL LowerCase       // Перевести в нижний регистр
  );

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

RDS_SSpSpCB (для UTF8) или RDS_WsSpSpCB (для UTF16)

Параметры

Start (RDSCSTR): Указатель на начало текста (char*), из которого нужно извлечь слово. Все пробелы и табуляции перед словом будут пропущены.
pNextWord (RDSCSTR*): Указатель на переменную типа char*, в которую будет записан указатель на начало следующего слова. Если вызывающей программе оно не нужно, в этом параметре можно передать NULL.
pSym (char*): Указатель на переменную типа char, в которую будет записан вид считанного слова, или NULL, если вызывающей программе не нужен вид слова. От вида слова зависит его предварительная обработка внутри функции, от него также может зависеть реакция на это слово вызвавшей функцию программы.
LowerCase (BOOL): TRUE – считанное слово нужно перевести в нижний регистр (за исключением считанных строк в кавычках – их регистр никогда не изменяется). FALSE – считанное слово возвращается как есть.

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

Указатель (char* или wchar_t*) на созданную в динамической памяти строку, содержащую считанное слово, или NULL, если эта строка пустая (текст закончился).

Примечания

Функция rdsGetTextWordDyn полностью аналогична функции rdsGetTextWord, за исключением того, что последняя возвращает указатель на считанное слово во внутреннем буфере RDS, а эта функция формирует из считанного слова динамическую строку, которая обязательно должна быть освобождена вызовом rdsFree. Принципы разбора текста и смысл параметров у этих двух функций полностью совпадают. Эта функция обычно используется в тех случаях, когда необходимо сначала выделить из текста несколько слов, а потом уже их анализировать. rdsGetTextWord для этого не годится, поскольку каждый ее вызов приводит к изменению строки во внутреннем буфере и, следовательно, к потере предыдущего выделенного из текста слова.

Передаваемая в функцию строка должна иметь кодировку UTF8, поскольку текстовые данные блока всегда хранятся и передаются в модель в этой кодировке. Версия функции с суффиксом W возвращает извлеченное из строки слово в кодировке UTF16, но обрабатываемая строка при этом все равно должна быть в UTF8. Если необходимо разбивать на слова строку в UTF16, необходимо предварительно преобразовать ее функцией rdsUTF16toUTF8.

См. также

rdsGetTextWord, rdsFree, RDS_BFM_LOADTXT.