Приложения

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

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

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

Описываются функции управления памятью, которые можно использовать для работы с областями памяти, создаваемыми и уничтожаемыми RDS – в частности, динамически отводимыми строками. Вместе с ними описываются и другие функции, формирующие в результате своей работы динамические строки или преобразующие строки в числа.

А.5.4.1. rdsAddToDynStr – добавление строки к динамически отведенной строке

Функция rdsAddToDynStr добавляет строку в конец динамически созданной другими функциями строки.

  void RDSCALL rdsAddToDynStrA(
    RDSSTR *pString,   // Указатель на указатель на динамическую строку (UTF8)
    RDSCSTR AddStr,    // Добавляемая строка (UTF8)
    BOOL NullEmpty     // Можно ли возвращать NULL
  );
  void RDSCALL rdsAddToDynStrW(
    RDSWSTR *pString,  // Указатель на указатель на динамическую строку (UTF16)
    RDSWCSTR AddStr,   // Добавляемая строка (UTF16)
    BOOL NullEmpty     // Можно ли возвращать NULL
  );
  // Функция-псевдоним
  void RDSCALL rdsAddToDynStr(
    RDSXSTR *pString,  // Указатель на указатель на динамическую строку (кодировка по умолчанию)
    RDSXCSTR AddStr,   // Добавляемая строка (кодировка по умолчанию)
    BOOL NullEmpty     // Можно ли возвращать NULL
  );

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

RDS_VpSSB (для UTF8) или RDS_VpWsWsB (для UTF16)

Параметры

pString (RDSSTR*, RDSWSTR*, RDSXSTR*)

Указатель на переменную типа RDSSTR (char*) или RDSWSTR (wchar_t*), в которой содержится указатель на динамическую строку, в конец которой нужно добавить новую. После выполнения функции старая динамическая строка освобождается, а в эту переменную запишется указатель на новую строку, полученную объединением старой строки с AddStr. pString не может иметь значение NULL (в этом случае функция немедленно завершится), но в переменной, на которую указывает pString, вполне может находиться NULL вместо указателя на динамическую строку. В этом случае старая динамическая строка будет считаться пустой, и новая строка будет динамической копией параметра AddStr.

AddStr (RDSCSTR, RDSWCSTR, RDSXCSTR)

Указатель на строку, которую нужно добавить в конец строки *pString. Это может быть указатель на статическую или динамическую строку – для работы функции это не важно, в отличие от *pString, эта строка никак не изменяется в процессе выполнения функции. Если передать в этом параметре NULL, это будет считаться добавлением к *pString пустой строки.

NullEmpty (BOOL)

TRUE, если вместо пустой строки функция должна записывать в *pString значение NULL, и FALSE, если она должна будет динамически отвести в памяти пустую строку (то есть массив char или wchar_t из единственного символа с нулевым кодом) и записать в *pString указатель на нее.

Примечания

Функция rdsAddToDynStr введена в набор сервисных функций RDS только для улучшения читаемости программ, работающих с динамическими строками – ее можно полностью заменить последовательными вызовами rdsDynStrCat и rdsFree.

Первый параметр этой функции (pString) всегда должен содержать указатель на переменную, в которой содержится указатель на динамически отведенную сервисными функциями RDS строку. Если эта строка будет статической, при работе функции возникнут серьезные ошибки, поскольку после объединения строк она попытается освободить старую строку вызовом rdsFree, что приведет к непредсказуемым последствиям.

Фактически, внутри функции rdsAddToDynStr находится конструкция следующего вида (пример приведен для кодировки UTF8):

  void rdsAddToDynStrA(RDSSTR *pString,RDSCSTR AddStr,BOOL NullEmpty)
  { char *oldstr=*pString;
    *pString=rdsDynStrCatA(*pString,AddStr,NullEmpty);
    rdsFree(oldstr);
  }

Пример

Пример использования функции rdsAddToDynStr приведен в §2.11 руководства программиста.

См. также

rdsDynStrCat, rdsFree.