Namespaces
Variants
Views
Actions

Difference between revisions of "cpp/string/basic string/clear"

From cppreference.com
< cpp‎ | string‎ | basic string
m (§ 21.4.4 of N3485)
m (→‎Example: `assert`=>`cout` for no-warranty case; {{ddcla}})
 
(19 intermediate revisions by 10 users not shown)
Line 1: Line 1:
−
{{cpp/string/basic_string/title | clear}}
+
{{cpp/string/basic_string/title|clear}}
 
{{cpp/string/basic_string/navbar}}
 
{{cpp/string/basic_string/navbar}}
−
{{ddcl |  
+
{{ddcla|noexcept=c++11|constexpr=c++20|
 
void clear();
 
void clear();
 
}}
 
}}
  
−
Removes all characters from the string. The allocated memory will not be released, effectively leaving the {{lc|capacity}} of the string unchanged. The past-the-end iterators are not invalidated.  
+
Removes all characters from the string as if by executing {{c|erase(begin(), end())}}.
 +
 
 +
All pointers, references, and iterators are invalidated.
  
 
===Parameters===
 
===Parameters===
Line 13: Line 15:
 
(none)
 
(none)
  
−
===Exceptions===
+
===Notes===
−
{{noexcept}}
+
Unlike for {{lc|std::vector::clear}}, the C++ standard does not explicitly require that {{lc|capacity}} is unchanged by this function, but existing implementations do not change capacity. This means that they do not release the allocated memory (see also {{lc|shrink_to_fit}}).
  
 
===Complexity===
 
===Complexity===
−
Linear in the size of the string.
+
Linear in the size of the string, although existing implementations operate in constant time.
 +
 
 +
===Example===
 +
{{example
 +
|code=
 +
#include <cassert>
 +
#include <iostream>
 +
#include <string>
 +
 
 +
int main()
 +
{
 +
    std::string s{"Exemplar"};
 +
    std::string::size_type const capacity = s.capacity();
 +
 
 +
    s.clear();
 +
    assert(s.empty());
 +
    assert(s.size() == 0);
 +
    std::cout << std::boolalpha << (s.capacity() == capacity) << '\n';
 +
}
 +
|p=true
 +
|output=
 +
true
 +
}}
  
 
===See also===
 
===See also===
 
{{dsc begin}}
 
{{dsc begin}}
−
{{dsc inc | cpp/string/basic_string/dsc erase}}
+
{{dsc inc|cpp/string/basic_string/dsc erase}}
 
{{dsc end}}
 
{{dsc end}}
  
−
[[de:cpp/string/basic string/clear]]
+
{{langlinks|de|es|fr|it|ja|pl|pt|ru|zh}}
−
[[es:cpp/string/basic string/clear]]
+
−
[[fr:cpp/string/basic string/clear]]
+
−
[[it:cpp/string/basic string/clear]]
+
−
[[ja:cpp/string/basic string/clear]]
+
−
[[pl:cpp/string/basic string/clear]]
+
−
[[pt:cpp/string/basic string/clear]]
+
−
[[ru:cpp/string/basic string/clear]]
+
−
[[zh:cpp/string/basic string/clear]]
+

Latest revision as of 13:58, 18 October 2024

 
C++
 
Strings library
 
std::basic_string
Member functions
(C++23)
Element access
(DR*)
(DR*)
(C++17)
Iterators
(C++11)
(C++11)
(C++11)
(C++11)
Capacity
(DR*)
Modifiers
basic_string::clear
(C++23)
(DR*)
(C++23)
(C++23)
(C++23)  
Search
Operations
(C++20)
(C++20)
(C++23)
Constants
Non-member functions
(C++20)(C++20)
I/O
Comparison
(until C++20)(until C++20)(until C++20)(until C++20)(until C++20)(C++20)
Numeric conversions
(C++11)(C++11)(C++11)
(C++11)(C++11)
(C++11)(C++11)(C++11)
(C++11)
(C++11)
Literals
(C++14)
Helper classes
(C++11)
Deduction guides (C++17)

 
void clear();
 (noexcept since C++11)
(constexpr since C++20)

Removes all characters from the string as if by executing erase(begin(), end()).

All pointers, references, and iterators are invalidated.

Contents

[edit] Parameters

(none)

[edit] Return value

(none)

[edit] Notes

Unlike for std::vector::clear, the C++ standard does not explicitly require that capacity is unchanged by this function, but existing implementations do not change capacity. This means that they do not release the allocated memory (see also shrink_to_fit).

[edit] Complexity

Linear in the size of the string, although existing implementations operate in constant time.

[edit] Example

Run this code
#include <cassert>
#include <iostream>
#include <string>
 
int main()
{
    std::string s{"Exemplar"};
    std::string::size_type const capacity = s.capacity();
 
    s.clear();
    assert(s.empty());
    assert(s.size() == 0);
    std::cout << std::boolalpha << (s.capacity() == capacity) << '\n';
}

Possible output: 

true

[edit] See also

 removes characters
(public member function) [edit]
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/string/basic_string/clear&oldid=177141"