Namespaces
Variants
Views
Actions

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

From cppreference.com
< cpp‎ | string‎ | basic string
m (Update links.)
m (→‎Synopsis: +constexpr since)
 
(18 intermediate revisions by 9 users not shown)
Line 1: Line 1:
−
{{cpp/string/basic_string/title | resize}}
+
{{cpp/string/basic_string/title|resize}}
 
{{cpp/string/basic_string/navbar}}
 
{{cpp/string/basic_string/navbar}}
 
{{dcl begin}}
 
{{dcl begin}}
−
{{dcl | num=1 |
+
{{dcl|num=1|notes={{mark constexpr since c++20}}|
 
void resize( size_type count );
 
void resize( size_type count );
 
}}
 
}}
−
{{dcl | num=2 |
+
{{dcl|num=2|notes={{mark constexpr since c++20}}|
 
void resize( size_type count, CharT ch );
 
void resize( size_type count, CharT ch );
 
}}
 
}}
 
{{dcl end}}
 
{{dcl end}}
  
−
Resizes the string to contain {{tt|count}} characters.
+
Resizes the string to contain {{c|count}} characters.
  
−
If the current size is less than {{tt|count}}, additional characters are appended.
+
If the current size is less than {{c|count}}, additional characters are appended:
  
−
If the current size is greater than {{tt|count}}, the string is reduced to its first {{tt|count}} elements.
+
@1@ Initializes appended characters to {{c|CharT()}} ({{c|'\0'}} if {{tt|CharT}} is {{c/core|char}}).
 +
@2@ Initializes appended characters to {{c|ch}}.
  
−
The first version initializes new characters to {{c|CharT()}}, the second version initializes new characters to {{tt|ch}}.
+
If the current size is greater than {{c|count}}, the string is reduced to its first {{c|count}} elements.
  
 
===Parameters===
 
===Parameters===
−
 
 
{{par begin}}
 
{{par begin}}
−
{{par | count | new size of the string}}
+
{{par|count|new size of the string}}
−
{{par | ch | character to initialize the new characters with }}
+
{{par|ch|character to initialize the new characters with}}
 
{{par end}}
 
{{par end}}
  
 
===Return value===
 
===Return value===
 
(none)
 
(none)
−
 
+
<!--
 
===Complexity===
 
===Complexity===
 +
Linear in the size of the string.-->
  
−
linear in the size of the string
+
===Exceptions===
 +
{{lc|std::length_error}} if {{c|count > max_size()}}.
 +
Any exceptions thrown by corresponding {{tt|Allocator}}.
  
−
===See also===
+
{{cpp/strong exception safety guarantee}}
  
 +
===Example===
 +
{{example
 +
|code=
 +
#include <iomanip>
 +
#include <iostream>
 +
#include <stdexcept>
 +
 +
int main()
 +
{
 +
    const unsigned desired_length{8};
 +
    std::string long_string("Where is the end?");
 +
    std::string short_string("H");
 +
   
 +
    std::cout << "Basic functionality:\n"
 +
              << "Shorten:\n"
 +
              << "1. Before: " << std::quoted(long_string) << '\n';
 +
    long_string.resize(desired_length);
 +
    std::cout << "2. After:  " << std::quoted(long_string) << '\n';
 +
   
 +
    std::cout << "Lengthen with a given value 'a':\n"
 +
              << "3. Before: " << std::quoted(short_string) << '\n';
 +
    short_string.resize(desired_length, 'a');
 +
    std::cout << "4. After:  " << std::quoted(short_string) << '\n';
 +
   
 +
    std::cout << "Lengthen with char() == " << static_cast<int>(char()) << '\n'
 +
              << "5. Before: " << std::quoted(short_string) << '\n';
 +
    short_string.resize(desired_length + 3);
 +
    std::cout << "6. After:  \"";
 +
    for (char c : short_string)
 +
        std::cout << (c == char() ? '@' : c);
 +
    std::cout << "\"\n\n";
 +
   
 +
    std::cout << "Errors:\n";
 +
    std::string s;
 +
   
 +
    try
 +
    {
 +
        // size is OK, no length_error
 +
        // (may throw bad_alloc)
 +
        s.resize(s.max_size() - 1, 'x');
 +
    }
 +
    catch (const std::bad_alloc& ex)
 +
    {
 +
        std::cout << "1. Exception: " << ex.what() << '\n';
 +
    }
 +
   
 +
    try
 +
    {
 +
        // size is OK, no length_error
 +
        // (may throw bad_alloc)
 +
        s.resize(s.max_size(), 'x');
 +
    }
 +
    catch (const std::bad_alloc& ex)
 +
    {
 +
        std::cout << "2. Exception: " << ex.what() << '\n';
 +
    }
 +
   
 +
    try
 +
    {
 +
        // size is BAD, throw length_error
 +
        s.resize(s.max_size() + 1, 'x');
 +
    }
 +
    catch (const std::length_error& ex)
 +
    {
 +
        std::cout << "3. Length error: " << ex.what() << '\n';
 +
    }
 +
}
 +
|p=true
 +
|output=
 +
Basic functionality:
 +
Shorten:
 +
1. Before: "Where is the end?"
 +
2. After:  "Where is"
 +
Lengthen with a given value 'a':
 +
3. Before: "H"
 +
4. After:  "Haaaaaaa"
 +
Lengthen with char() == 0
 +
5. Before: "Haaaaaaa"
 +
6. After:  "Haaaaaaa@@@"
 +
 +
Errors:
 +
1. Exception: std::bad_alloc
 +
2. Exception: std::bad_alloc
 +
3. Length error: basic_string::_M_replace_aux
 +
}}
 +
 +
===Defect reports===
 +
{{dr list begin}}
 +
{{dr list item|wg=lwg|dr=847|std=C++98|before=there was no exception safety guarantee|after=added strong exception safety guarantee}}
 +
{{dr list end}}
 +
 +
===See also===
 
{{dsc begin}}
 
{{dsc begin}}
−
{{dsc inc | cpp/string/basic_string/dsc size}}
+
{{dsc inc|cpp/string/basic_string/dsc size}}
 +
{{dsc inc|cpp/string/basic_string/dsc reserve}}
 +
{{dsc inc|cpp/string/basic_string/dsc shrink_to_fit}}
 
{{dsc end}}
 
{{dsc end}}
  
−
[[de:cpp/string/basic string/resize]]
+
{{langlinks|de|es|fr|it|ja|pt|ru|zh}}
−
[[es:cpp/string/basic string/resize]]
+
−
[[fr:cpp/string/basic string/resize]]
+
−
[[it:cpp/string/basic string/resize]]
+
−
[[ja:cpp/string/basic string/resize]]
+
−
[[pt:cpp/string/basic string/resize]]
+
−
[[ru:cpp/string/basic string/resize]]
+
−
[[zh:cpp/string/basic string/resize]]
+

Latest revision as of 11:15, 21 April 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
(C++23)
(DR*)
(C++23)
(C++23)
basic_string::resize
(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 resize( size_type count );
 (1) (constexpr since C++20)
void resize( size_type count, CharT ch );
 (2) (constexpr since C++20)

Resizes the string to contain count characters.

If the current size is less than count, additional characters are appended:

1) Initializes appended characters to CharT() ('\0' if CharT is char).
2) Initializes appended characters to ch.

If the current size is greater than count, the string is reduced to its first count elements.

Contents

[edit] Parameters

count - new size of the string
ch - character to initialize the new characters with

[edit] Return value

(none)

[edit] Exceptions

std::length_error if count > max_size(). Any exceptions thrown by corresponding Allocator.

If an exception is thrown for any reason, this function has no effect (strong exception safety guarantee).

[edit] Example

Run this code
#include <iomanip>
#include <iostream>
#include <stdexcept>
 
int main()
{
    const unsigned desired_length{8};
    std::string long_string("Where is the end?");
    std::string short_string("H");
 
    std::cout << "Basic functionality:\n"
              << "Shorten:\n"
              << "1. Before: " << std::quoted(long_string) << '\n';
    long_string.resize(desired_length);
    std::cout << "2. After:  " << std::quoted(long_string) << '\n';
 
    std::cout << "Lengthen with a given value 'a':\n"
              << "3. Before: " << std::quoted(short_string) << '\n';
    short_string.resize(desired_length, 'a');
    std::cout << "4. After:  " << std::quoted(short_string) << '\n';
 
    std::cout << "Lengthen with char() == " << static_cast<int>(char()) << '\n'
              << "5. Before: " << std::quoted(short_string) << '\n';
    short_string.resize(desired_length + 3);
    std::cout << "6. After:  \"";
    for (char c : short_string)
        std::cout << (c == char() ? '@' : c);
    std::cout << "\"\n\n";
 
    std::cout << "Errors:\n";
    std::string s;
 
    try
    {
        // size is OK, no length_error
        // (may throw bad_alloc)
        s.resize(s.max_size() - 1, 'x');
    }
    catch (const std::bad_alloc& ex)
    {
        std::cout << "1. Exception: " << ex.what() << '\n';
    }
 
    try
    {
        // size is OK, no length_error
        // (may throw bad_alloc)
        s.resize(s.max_size(), 'x');
    }
    catch (const std::bad_alloc& ex)
    {
        std::cout << "2. Exception: " << ex.what() << '\n';
    }
 
    try
    {
        // size is BAD, throw length_error
        s.resize(s.max_size() + 1, 'x');
    }
    catch (const std::length_error& ex)
    {
        std::cout << "3. Length error: " << ex.what() << '\n';
    }
}

Possible output: 

Basic functionality:
Shorten:
1. Before: "Where is the end?"
2. After:  "Where is"
Lengthen with a given value 'a':
3. Before: "H"
4. After:  "Haaaaaaa"
Lengthen with char() == 0
5. Before: "Haaaaaaa"
6. After:  "Haaaaaaa@@@"
 
Errors:
1. Exception: std::bad_alloc
2. Exception: std::bad_alloc
3. Length error: basic_string::_M_replace_aux

[edit] Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

DR Applied to Behavior as published Correct behavior
LWG 847 C++98 there was no exception safety guarantee added strong exception safety guarantee

[edit] See also

 returns the number of characters
(public member function) [edit]
reserves storage
(public member function) [edit]
(DR*)
 reduces memory usage by freeing unused memory
(public member function) [edit]
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/string/basic_string/resize&oldid=171089"