std::basic_string<CharT,Traits,Allocator>::compare

 

C++

Поддержка компилятором

Автономные и размещённые реализации

Язык

Стандартная библиотека

Заголовки стандартной библиотеки

Требования к именованию

Макросы тестирования функциональности (C++20)

Поддержка языка

Библиотека концептов(C++20)

Библиотека метапрограммирования(C++11)

Библиотека диагностики

Библиотека общих утилит

Библиотека строк

Библиотека контейнеров

Библиотека итераторов

Библиотека диапазонов(C++20)

Библиотека алгоритмов

Библиотека численных данных

Библиотека ввода/вывода

Библиотека локализаций

Регулярные выражения(C++11)

Атомарные операции(C++11)

Библиотека поддержки конкуренции(C++11)

Библиотека файловой системы(C++17)

Технические спецификации

Указатель символов

Внешние библиотеки

 

Строки

Строки с завершающим нулём

Однобайтовые строки

Многобайтовые строки

Широкие строки

Классы

basic_string

basic_string_view (C++17)

char_traits

 

std::basic_string

Функции-элементы basic_string::basic_string basic_string::~basic_string basic_string::operator= basic_string::assign basic_string::assign_range (C++23) basic_string::get_allocator Доступ к элементам basic_string::at basic_string::operator[] basic_string::front (DR*) basic_string::back (DR*) basic_string::data basic_string::c_str basic_string::operator  basic_string_view (C++17) Итераторы basic_string::beginbasic_string::cbegin (DR*) basic_string::endbasic_string::cend (DR*) basic_string::rbeginbasic_string::crbegin (DR*) basic_string::rendbasic_string::crend (DR*) Ёмкость basic_string::empty basic_string::sizebasic_string::length basic_string::max_size basic_string::reserve basic_string::capacity basic_string::shrink_to_fit (DR*) Операции basic_string::clear basic_string::insert basic_string::insert_range (C++23) basic_string::erase basic_string::push_back basic_string::pop_back (DR*) basic_string::append basic_string::append_range (C++23) basic_string::operator+= basic_string::compare basic_string::replace basic_string::replace_with_range (C++23) basic_string::substr basic_string::copy basic_string::resize basic_string::resize_and_overwrite (C++23)   basic_string::swap

Поиск basic_string::starts_with (C++20)   basic_string::ends_with (C++20) basic_string::contains (C++23) basic_string::find basic_string::rfind basic_string::find_first_of basic_string::find_first_not_of basic_string::find_last_of basic_string::find_last_not_of Константы basic_string::npos Правила вывода(C++17) Функции, не являющиеся элементами operator+ swap(std::basic_string) operator""s (C++14) erase(std::basic_string)erase_if(std::basic_string) (C++20)(C++20) Ввод/Вывод operator<<operator>> getline Сравнение operator==operator!=operator<operator>operator<=operator>=operator<=> (до C++20)(до C++20)(до C++20)(до C++20)(до C++20)(C++20) Числовые преобразования stoistolstoll (C++11)(C++11)(C++11) stoulstoull (C++11)(C++11) stofstodstold (C++11)(C++11)(C++11) to_string (C++11) to_wstring (C++11) Вспомогательные классы hash<std::string>hash<std::wstring>hash<std::u32string>hash<std::u16string>hash<std::u8string> (C++11)  (C++11)(C++11)(C++11)(C++20) hash<std::pmr::string>hash<std::pmr::wstring>hash<std::pmr::u32string>hash<std::pmr::u16string>hash<std::pmr::u8string> (C++17)(C++17)(C++17)(C++17)(C++20)

 

	(1)
int compare(const basic_string& str )const;			(до C++11)
int compare(const basic_string& str )constnoexcept;			(начиная с C++11) (до C++20)
constexprint compare(const basic_string& str )constnoexcept;			(начиная с C++20)
		(2)
int compare( size_type pos1, size_type count1,              const basic_string& str )const;				(до C++20)
constexprint compare( size_type pos1, size_type count1,                        const basic_string& str )const;				(начиная с C++20)
			(3)
int compare( size_type pos1, size_type count1,              const basic_string& str,              size_type pos2, size_type count2 )const;					(до C++14)
int compare( size_type pos1, size_type count1,              const basic_string& str,              size_type pos2, size_type count2 = npos )const;					(начиная с C++14) (до C++20)
constexprint compare( size_type pos1, size_type count1,                        const basic_string& str,                        size_type pos2, size_type count2 = npos )const;					(начиная с C++20)
				(4)
int compare(const CharT* s )const;						(до C++20)
constexprint compare(const CharT* s )const;						(начиная с C++20)
					(5)
int compare( size_type pos1, size_type count1,              const CharT* s )const;							(до C++20)
constexprint compare( size_type pos1, size_type count1,                        const CharT* s )const;							(начиная с C++20)
						(6)
int compare( size_type pos1, size_type count1,              const CharT* s, size_type count2 )const;								(до C++20)
constexprint compare( size_type pos1, size_type count1,                        const CharT* s, size_type count2 )const;								(начиная с C++20)
							(7)
template<class StringViewLike > int compare(const StringViewLike& t )constnoexcept(/* смотрите ниже */);									(начиная с C++17) (до C++20)
template<class StringViewLike > constexprint     compare(const StringViewLike& t )constnoexcept(/* смотрите ниже */);									(начиная с C++20)
								(8)
template<class StringViewLike > int compare( size_type pos1, size_type count1,              const StringViewLike& t )const;										(начиная с C++17) (до C++20)
template<class StringViewLike > constexprint compare( size_type pos1, size_type count1,                        const StringViewLike& t )const;										(начиная с C++20)
									(9)
template<class StringViewLike > int compare( size_type pos1, size_type count1,              const StringViewLike& t,              size_type pos2, size_type count2 = npos)const;											(начиная с C++17) (до C++20)
template<class StringViewLike > constexprint compare( size_type pos1, size_type count1,                        const StringViewLike& t,                        size_type pos2, size_type count2 = npos)const;											(начиная с C++20)

Сравнивает две последовательности символов.

1) Сравнивает строку с str.

2) Сравнивает подстроку [pos1, pos1 + count1) текущей строки с str.

• Если count1 > size()- pos1, подстрока равна [pos1, size()).

3) Сравнивает подстроку [pos1, pos1 + count1) текущей строки с подстрокой [pos2, pos2 + count2) строки str.

• Если count1 > size()- pos1, первая подстрока равна [pos1, size()).
• Если count2 > str.size()- pos2, вторая подстрока равна [pos2, str.size()).

4) Сравнивает текущую строку с последовательностью символов, завершающейся нулём, начиная с символа, на который указывает s, с длиной Traits::length(s).

5) Сравнивает подстроку [pos1, pos1 + count1) текущей строки с последовательностью символов, завершающейся нулём, начиная с символа, на который указывает s, с длиной Traits::length(s).

• Если count1 > size()- pos1, подстрока равна [pos1, size()).

6) Сравнивает подстроку [pos1, pos1 + count1) текущей строки с символами в диапазоне [s, s + count2). Символы в [s, s + count2) могут включать нулевые символы.

• Если count1 > size()- pos1, подстрока равна [pos1, size()).

7-9) Неявно преобразует t в строковое представление sv, как если бы с помощью std::basic_string_view<CharT, Traits> sv = t;, затем

7) сравнивает текущую строку с sv;

8) сравнивает подстроку [pos1, pos1 + count1) текущей строки с sv, как если бы с помощью std::basic_string_view<CharT, Traits>(*this).substr(pos1, count1).compare(sv);

9) сравнивает подстроку [pos1, pos1 + count1) текущей строки с подстрокой [pos2, pos2 + count2) строки sv, как если бы с помощью std::basic_string_view<CharT, Traits>(*this)
    .substr(pos1, count1).compare(sv.substr(pos2, count2)).

Эти перегрузки участвуют в разрешении перегрузки, только если std::is_convertible_v<const StringViewLike&,
                      std::basic_string_view<CharT, Traits>> равно true и std::is_convertible_v<const StringViewLike&, const CharT*> равно false.

Последовательность символов, состоящая из count1 символов, начинающихся с data1, сравнивается с последовательностью символов, состоящей из count2 символов, начинающихся с data2, следующим образом:

• Сначала вычисляется количество символов для сравнения, как если бы с помощью size_type rlen =std::min(count1, count2).
• Затем сравниваются последовательности, вызовом Traits::compare(data1, data2, rlen). Для стандартных строк эта функция выполняет посимвольное лексикографическое сравнение. Если результат нулевой (последовательности символов пока равны), то их размеры сравниваются следующим образом:

Условие		Результат	Возвращаемое значение
Traits::compare(data1, data2, rlen) < 0		data1меньше чем data2	<0
Traits::compare(data1, data2, rlen) == 0	size1 < size2	data1меньше чем data2	<0
	size1 == size2	data1равноdata2	​0​
	size1 > size2	data1больше чем data2	>0
Traits::compare(data1, data2, rlen) > 0		data1больше чем data2	>0

Параметры

str	—	другая строка для сравнения
s	—	указатель на строку символов для сравнения
count1	—	количество символов текущей строки для сравнения
pos1	—	позиция первого символа в текущей строке для сравнения
count2	—	количество символов данной строки для сравнения
pos2	—	позиция первого символа данной строки для сравнения
t	—	объект (конвертируемый в std::basic_string_view) для сравнения

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

• Отрицательное значение, если *this появляется перед последовательностью символов, указанной аргументами, в лексикографическом порядке.
• Ноль, если обе последовательности символов при сравнении эквивалентны.
• Положительное значение, если *this появляется после последовательности символов, указанной аргументами, в лексикографическом порядке.

Исключения

Перегрузки, принимающие параметры с именем pos1 или pos2, генерируют std::out_of_range, если аргумент выходит за пределы диапазона.

7)

спецификация noexcept:  

noexcept(std::is_nothrow_convertible_v<const T&, std::basic_string_view<CharT, Traits>>)

8,9) Генерирует всё, что генерируется при преобразовании в std::basic_string_view.

Если по какой-либо причине генерируется исключение, эта функция не имеет эффекта (строгая гарантия безопасности исключений).

Возможная реализация

template<class CharT, class Traits, class Alloc>intstd::basic_string<CharT, Traits, Alloc>::compare(conststd::basic_string& s)constnoexcept{ size_type lhs_sz = size(); size_type rhs_sz = s.size();int result = traits_type::compare(data(), s.data(), std::min(lhs_sz, rhs_sz));if(result !=0)return result;if(lhs_sz < rhs_sz)return-1;if(lhs_sz > rhs_sz)return1;return0;}

Примечание

Для ситуаций, когда трёхстороннее сравнение не требуется, std::basic_string предоставляет обычные операторы отношения (<, <=, ==, > и т.д.).

По умолчанию (со значением по умолчанию std::char_traits) эта функция не зависит от локали. Смотрите std::collate::compare для трёхстороннего сравнения строк с учётом локали.

Пример

Запустить этот код

#include <cassert>#include <iomanip>#include <iostream>#include <string>#include <string_view>   void print_compare_result(std::string_view str1, std::string_view str2, int compare_result){if(compare_result <0)std::cout<<std::quoted(str1)<<" находится перед "<<std::quoted(str2)<<".\n";elseif(compare_result >0)std::cout<<std::quoted(str2)<<" находится перед "<<std::quoted(str1)<<".\n";elsestd::cout<<std::quoted(str1)<<" и "<<std::quoted(str2)<<" одинаковы.\n";}   int main(){std::string batman{"Batman"};std::string superman{"Superman"};int compare_result{0};   // 1) Сравнивает с другой строкой compare_result = batman.compare(superman);std::cout<<"1) "; print_compare_result("Batman", "Superman", compare_result);   // 2) Сравнивает подстроку с другой строкой compare_result = batman.compare(3, 3, superman);std::cout<<"2) "; print_compare_result("man", "Superman", compare_result);   // 3) Сравнивает подстроку с другой подстрокой compare_result = batman.compare(3, 3, superman, 5, 3);std::cout<<"3) "; print_compare_result("man", "man", compare_result);   // Сравнивает подстроку с другой подстрокой// по умолчанию до конца другой строкиassert(compare_result == batman.compare(3, 3, superman, 5));   // 4) Сравнивает с указателем на char compare_result = batman.compare("Superman");std::cout<<"4) "; print_compare_result("Batman", "Superman", compare_result);   // 5) Сравнивает подстроку с указателем на char compare_result = batman.compare(3, 3, "Superman");std::cout<<"5) "; print_compare_result("man", "Superman", compare_result);   // 6) Сравнивает подстроку с подстрокой указателя на char compare_result = batman.compare(0, 3, "Superman", 5);std::cout<<"6) "; print_compare_result("Bat", "Super", compare_result);}

Вывод:

1) "Batman" находится перед "Superman". 2) "Superman" находится перед "man". 3) "man" и "man" одинаковы. 4) "Batman" находится перед "Superman". 5) "Superman" находится перед "man". 6) "Bat" находится перед "Super".

Отчёты о дефектах

Следующие изменения поведения были применены с обратной силой к ранее опубликованным стандартам C++:

Номер	Применён	Поведение в стандарте	Корректное поведение
LWG 5	C++98	параметр count2 перегрузки (6) имел аргумент по умолчанию npos	аргумент по умолчанию удалён, разделив перегрузки (5) и (6)
LWG 847	C++98	не было гарантии безопасности исключений	добавлена надёжная гарантия безопасности исключений
LWG 2946	C++17	перегрузка (7) в некоторых случаях вызывала двусмысленность	исправлено, сделав её шаблоном
WG не указан	C++17	noexcept перегрузки (7) было случайно удалено из-за разрешения LWG2946	восстановлено

Смотрите также

operator==operator!=operator<operator>operator<=operator>=operator<=> (удалено в C++20)(удалено в C++20)(удалено в C++20)(удалено в C++20)(удалено в C++20)(C++20)	лексикографически сравнивает две строки (шаблон функции)
substr	возвращает подстроку (public функция-элемент)
collate	определяет лексикографическое сравнение и хеширование строк (шаблон класса)
strcoll	сравнивает две строки в соответствии с текущей локалью (функция)
lexicographical_compare	возвращает true, если один диапазон лексикографически меньше другого (шаблон функции)
compare (C++17)	сравнивает два представления (public функция-элемент std::basic_string_view<CharT,Traits>)