Приложения

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

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

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

А.5.11.2. rdsGetTextWord – извлечение слова из текста

Функция rdsGetTextWord считывает из переданной в параметрах строки очередное слово и возвращает указатель на это слово во внутреннем буфере RDS. Строка должна иметь кодировку UTF8.

  RDSSTR RDSCALL rdsGetTextWordA( // UTF8
    RDSCSTR Start,       // Начало текста (UTF8)
    RDSCSTR *pNextWord,  // Возврат – следующее слово (UTF8)
    char *pSym,          // Вид слова
    BOOL LowerCase       // Перевести в нижний регистр
  );
  RDSWSTR RDSCALL rdsGetTextWordW( // UTF16
    RDSCSTR Start,       // Начало текста (UTF8)
    RDSCSTR *pNextWord,  // Возврат – следующее слово (UTF8)
    char *pSym,          // Вид слова
    BOOL LowerCase       // Перевести в нижний регистр
  );
  // Функция-псевдоним
  RDSXSTR RDSCALL rdsGetTextWord( // Кодировка по умолчанию
    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, если вызывающей программе не нужен вид слова. От вида слова зависит его предварительная обработка внутри функции, от него также может зависеть реакция на это слово вызвавшей функцию программы. По указателю pSym может быть записан один из следующих символов:

*pSym (код)	Значение
0	Считан конец текста, в нем больше нет слов. Функция при этом вернет пустую строку.
10 («\n»)	Считан конец строки, следующее слово находится на следующей строке. Функция при этом вернет слово, состоящее из единственного символа «\n».
Двойная кавычка («\"»)	Считанное слово на самом деле является строкой в двойных кавычках (возможно, с пробелами), в которой непечатаемые символы заменены на их символические обозначения. Функция при этом вернет строку без кавычек, в которой символические обозначения заменены на сами символы, в т.ч. и непечатаемые.
Другие коды	Считано слово, состоящее из слитно набранных печатаемых символов. Функция вернет это слово, а в *pSym будет записан первый символ этого слова.

LowerCase (BOOL)

TRUE – считанное слово нужно перевести в нижний регистр (за исключением считанных строк в кавычках – их регистр никогда не изменяется). FALSE – считанное слово возвращается как есть.

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

Указатель (char* или wchar_t*) на внутренний буфер RDS, в котором размещено считанное слово. Функция никогда не возвращает NULL – даже если слова нет (текст закончился), она вернет указатель на буфер с пустой строкой.

Примечания

Обычно эта функция используется для разбиения текста на слова (например, в процессе загрузки данных блока в текстовом формате) с целью последующего анализа этих слов. Она извлекает из текста, указатель на который передан в параметре Start, первое слово, записывает его во внутренний буфер, записывает в *pNextWord указатель на начало следующего слова (этот указатель можно передать в параметре Start при следующем вызове этой функции для чтения очередного слова), в *pSym – тип считанного слова как указано выше, и возвращает указатель на внутренний буфер со считанным словом. Словом считается либо последовательность любых печатаемых символов, либо строка в двойных кавычках, разделителями слов – пробелы и табуляции. Код перевода строки «\n» считается отдельным словом из одного символа. Нулевой байт, завершающий текст, тоже считается отдельным словом (пустой строкой). Если в параметре LowerCase передано TRUE, считанное слово, если оно не является строкой в кавычках, будет переведено в нижний регистр.

Функция отдельно обрабатывает знак продолжения «+», используемый в текстовом формате схем RDS. Обнаружив его, она пропускает следующий за ним перевод строки и повторение знака продолжения, считая следующую строку текста продолжением текущей строки и не возвращая отдельно слово конца строки «\n». Таким образом, например, текст

  word1 word2 +
  + word3 "word 4"

будет считаться одной строкой, состоящей из четырех слов: «word1», «word2», «word3» и «word 4».

Строка в кавычках считается одним словом, какой бы длинной она ни была и сколько бы пробелов внутри ни содержала. В приведенном выше примере «word 4» будет считано функцией как одно слово, а не как два. Длинные строки тоже могут быть разбиты с помощью символов продолжения «+», при этом функция автоматически соберет их вместе. Например, текст

  word5 "abcd"+
  +"efgh" word6

будет разобран на три слова: «word5», «abcdefgh» и «word6».

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

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

Пример

Использование функции rdsGetTextWord подробно рассматривается в §2.8.3 руководства программиста.

См. также

rdsGetTextWordDyn, RDS_BFM_LOADTXT.