Приложения

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

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

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

А.5.4.13. rdsStringReplace – замена фрагментов строки

Функция rdsStringReplace ищет в переданной ей строке заданные фрагменты и формирует новую динамическую строку, в которой эти фрагменты заменены на другие.

  RDSSTR RDSCALL rdsStringReplaceA( // UTF8
    RDSCSTR String,    // Исходная строка (UTF8)
    RDSCSTR *Search,   // Массив фрагментов для поиска (UTF8)
    RDSCSTR *Replace,  // Массив фрагментов для замены (UTF8)
    int Count,         // Размер массива Search или -1
    DWORD Flags        // Флаги RDS_SRF_*
  );
  RDSWSTR RDSCALL rdsStringReplaceW( // UTF16
    RDSWCSTR String,   // Исходная строка (UTF16)
    RDSWCSTR *Search,  // Массив фрагментов для поиска (UTF16)
    RDSWCSTR *Replace, // Массив фрагментов для замены (UTF16)
    int Count,         // Размер массива Search или -1
    DWORD Flags        // Флаги RDS_SRF_*
  );
  // Функция-псевдоним
  RDSXSTR RDSCALL rdsStringReplace( // Кодировка по умолчанию
    RDSXCSTR String,   // Исходная строка (кодировка по умолчанию)
    RDSXCSTR *Search,  // Массив фрагментов для поиска (кодировка по умолчанию)
    RDSXCSTR *Replace, // Массив фрагментов для замены (кодировка по умолчанию)
    int Count,         // Размер массива Search или -1
    DWORD Flags        // Флаги RDS_SRF_*
  );

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

RDS_SSpSpSIDw (для UTF8) или RDS_WsWspWspWsIDw (для UTF16)

Параметры

String (RDSCSTR, RDSWCSTR, RDSXCSTR)

Указатель на исходную строку, в которой будет выполняться поиск фрагментов.

Search (RDSSTR*, RDSWSTR*, RDSXSTR*)

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

Replace (RDSSTR*, RDSWSTR*, RDSXSTR*)

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

Count (int)

Число строк в массиве Search или −1, если массив Search завершается элементом со значением NULL.

Flags (DWORD)

Битовые флаги, влияющие на поиск и замену фрагментов:

RDS_SRF_IGNORECASE	При поиске не учитывать регистр символов.
RDS_SRF_STDPATHS	Заменить символические обозначения стандартных путей на сами пути после того, как выполнен поиск фрагментов из массива Search и замена их на фрагменты из Replace.

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

Указатель на созданную в динамической памяти строку, в которой фрагменты из массива Search заменены их на фрагменты из массива Replace. В случае ошибки возвращается NULL.

Примечания

Динамическая строка, созданная функцией rdsStringReplace, должна быть обязательно освобождена функцией rdsFree.

Эта функция последовательно просматривает массив Search, начиная с нулевого индекса, до обнаружения в нем значения NULL или до индекса Count, если Count>0. Каждый элемент массива Search ищется в строке String и, если он найден, все его вхождения заменяются на элемент массива Replace с тем же индексом. Если в параметре Flags взведен флаг RDS_SRF_IGNORECASE, поиск осуществляется без учета регистра символов, в противном случае – с его учетом. Если в параметре Flags взведен флаг RDS_SRF_STDPATHS, то, после того, как перебраны все элементы массива Search, оставшиеся в строке символические обозначения путей («$DLL$», «$INI$» и т.п.) заменяются на их значения, причем замена производится не только в начале строки, как в функции rdsGetFullFilePath, но и в любом другом ее месте.

Пример

Выполнение программы

  const wchar_t *names[]={L"_PI_VAL_",L"$PI$",NULL};
  const wchar_t *values[]={L"3.1415926",L"Пи"};
  const wchar_t *result=rdsStringReplaceW(L"Значение $PI$ равно _PI_VAL_",
                                          names,values,-1,0);
  rdsMessageBoxW(result,L"Результат",MB_OK);
  rdsFree(result);

приведет к выводу сообщения с текстом «Значение Пи равно 3.1415926».

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

См. также

rdsFree, rdsGetFullFilePath, rdsTransformFileName.