Приложения

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

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

А.5.26. Вспомогательный объект для разбора текста

А.5.26.4. rdsSTRGetWord – считать из текста очередное слово

Функция rdsSTRGetWord считывает очередное слово из текста, переданного в объект командой RDS_HSTR_SETTEXT, и возвращает указатель на это слово, указатель на следующую за словом часть текста, а также идентификатор этого слова, если оно совпало с одним из ключевых.

  int RDSCALL rdsSTRGetWordA(
    RDS_HOBJECT Parser, // Объект
    RDSSTR *pWord,      // Возвращаемый указатель на слово (UTF8)
    RDSSTR *pNext,      // Возвращаемый остаток текста (UTF8)
    RDSSTR pWordType,   // Возвращаемый тип слова (UTF8)
    BOOL Analyse        // Сравнивать с ключевыми
  );
  int RDSCALL rdsSTRGetWordW(
    RDS_HOBJECT Parser, // Объект
    RDSWSTR *pWord,     // Возвращаемый указатель на слово (UTF16)
    RDSWSTR *pNext,     // Возвращаемый остаток текста (UTF16)
    RDSWSTR pWordType,  // Возвращаемый тип слова (UTF16)
    BOOL Analyse        // Сравнивать с ключевыми
  );
  // Функция-псевдоним
  int RDSCALL rdsSTRGetWord(
    RDS_HOBJECT Parser, // Объект
    RDSXSTR *pWord,     // Возвращаемый указатель на слово (кодировка по умолчанию)
    RDSXSTR *pNext,     // Возвращаемый остаток текста (кодировка по умолчанию)
    RDSXSTR pWordType,  // Возвращаемый тип слова (кодировка по умолчанию)
    BOOL Analyse        // Сравнивать с ключевыми
  );

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

RDS_IHopSpSpCB (для UTF8) или RDS_IHopWspWspCB (для UTF16)

Параметры

Parser (RDS_HOBJECT)

Идентификатор вспомогательного объекта для разбора текста, ранее созданного функцией rdsSTRCreateTextReader.

pWord (RDSSTR*, RDSWSTR*, RDSXSTR*)

Указатель типа char** или wchar_t** (в зависимости от версии функции) на переменную, в которую будет записан указатель на извлеченное из текста слово, находящееся во внутренней памяти объекта Parser. Если вызывающей программе не нужно это слово, в этом параметре можно передать NULL.

pNext (RDSSTR*, RDSWSTR*, RDSXSTR*)

Указатель типа char** или wchar_t** (в зависимости от версии функции) на переменную, в которую будет записан указатель на следующую за извлеченным словом часть текста. Допускается обработать часть этого текста вручную, после чего снова передать объекту продолжение текста командой RDS_HSTR_SETTEXT (см. пример ниже). Если вызывающей программе не нужен указатель на продолжение текста, в этом параметре можно передать NULL.

pWordType (RDSCSTR, RDSWCSTR, RDSXCSTR)

Указатель на переменную типа char или wchar_t (в зависимости от версии функции), в которую будет записан вид считанного слова (аналогично параметру pSym функции rdsGetTextWord). Если вызывающей программе не нужен вид слова, в этом параметре можно передать NULL. От вида слова зависит его предварительная обработка внутри функции, от него также может зависеть реакция на это слово вызвавшей функцию программы. По указателю pWordType может быть записан один из следующих символов:

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

Analyse (BOOL)

TRUE – сравнивать слова, извлекаемые из текста, с ключевыми словами, записанными в объект функциями rdsSTRAddKeyword и rdsSTRAddKeywordsArray. FALSE – не сравнивать слова с ключевыми.

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

Если в параметре Analyse передано TRUE и извлеченное из текста слово совпало с одним из ключевых слов объекта, функция вернет идентификатор этого ключевого слова. В противном случае результат функции будет следующим:

Если достигнут конец текста (завершающий нулевой байт), функция вернет специальный идентификатор конца текста. По умолчанию это константа RDS_HSTR_DEFENDOFTEXT, но этот идентификатор может быть, при необходимости, изменен командой RDS_HSTR_ENDOFTEXTID.
Если достигнут конец строки (символ перевода строки, байт с кодом 10), функция вернет специальный идентификатор конца строки. По умолчанию это константа RDS_HSTR_DEFENDOFLINE, но этот идентификатор может быть, при необходимости, изменен командой RDS_HSTR_ENDOFLINEID.
Если сравнение с ключевыми словами не разрешено (Analyse==FALSE) или извлеченное слово не совпало ни с одним из ключевых, функция вернет специальный идентификатор неизвестного слова. По умолчанию это константа RDS_HSTR_DEFUNKNOWNWORD, но этот идентификатор может быть, при необходимости, изменен командой RDS_HSTR_UNKNOWNID.

Примечания

Эта функция во многом похожа на функцию rdsGetTextWord, поэтому их параметры частично совпадают. Однако, в отличие от rdsGetTextWord, функция rdsSTRGetWord не только извлекает из текста слово, ограниченное пробелами или заключенное в кавычки, но и сравнивает его (если это разрешено параметром Analyse) с набором ключевых слов объекта. Это упрощает анализ извлеченного слова в вызвавшей программе.

Словом текста, как и в функции rdsGetTextWord, считается либо последовательность любых печатаемых символов, либо строка в двойных кавычках. Разделителями слов считаются пробелы и табуляции. Код перевода строки «\n» считается отдельным словом из одного символа. Нулевой байт, завершающий текст, тоже считается отдельным словом (пустой строкой).

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

  word1 word2 +
  + word3 "word 4"

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

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

  word5 "abcd"+
  +"efgh" word6

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

Работу функции rdsSTRGetWord можно комбинировать с общими функциями разбора текста, для этого можно использовать параметр pNext, через который возвращается указатель на следующий за извлеченным словом участок текста. Рассмотрим, например, следующий фрагмент программы:

  // Создание объекта
  RDS_HOBJECT obj=rdsSTRCreateTextReader(TRUE);
  // Занесение ключевых слов
  rdsSTRAddKeywordA(obj,"color",100);
  rdsSTRAddKeywordA(obj,"line",101);
    …
  const char text[]="color rgb 0 0 0 line 1";
  char *word,*next;
  COLORREF col;
  BOOL loop=TRUE;
  // Установка разбираемого текста
  rdsSetObjectStrA(obj,RDS_HSTR_SETTEXT,0,text);
  // Цикл обработки текста
  while(loop)
    switch(rdsSTRGetWordA(obj,NULL,&next,NULL,TRUE))
      { case RDS_HSTR_DEFENDOFTEXT: // Конец текста
          loop=FALSE; break;
        case 100: // Опознано слово "color"
          // Считываем и обрабатываем продолжение строки
          col=rdsReadColorTextA(next,&word);
          // Новый текст - со следующего слова
          rdsSetObjectStrA(obj,RDS_HSTR_SETTEXT,0,word);
          break;
        …
      }

В этом примере в объект obj добавлено два ключевых слова: «color» с идентификатором 100 и «line» с идентификатором 101. После передачи в объект указателя на начало разбираемого текста text командой RDS_HSTR_SETTEXT, в цикле while(loop) слова считываются из текста и разбираются в операторе switch. Если считано слово «color» (идентификатор 100), следующий за ним фрагмент текста передается в функцию rdsReadColorText, которая без участия объекта obj разберет фрагмент «rgb 0 0 0», преобразует его в значение цвета col и запишет в переменную word указатель на следующий за этим фрагмент текста, т.е на «line 1». Этот указатель командой RDS_HSTR_SETTEXT будет передан в объект obj как новое начало текста, и разбор продолжится.

Пример

Другой пример использования функции rdsSTRGetWord приведен в §2.8.4 руководства программиста.

См. также

rdsSTRCreateTextReader, RDS_HSTR_SETTEXT, RDS_HSTR_ENDOFTEXTID, RDS_HSTR_ENDOFLINEID, RDS_HSTR_UNKNOWNID, rdsSTRAddKeyword, rdsSTRAddKeywordsArray.