`<string>` 函数

2025-05-30

标头 <string> 提供以下函数：

`getline`

将字符串从输入流中一行一行地提取出来。

// (1) delimiter as parameter
template <class CharType, class Traits, class Allocator>
basic_istream<CharType, Traits>& getline(
    basic_istream<CharType, Traits>& in_stream,
    basic_string<CharType, Traits, Allocator>& str,
    CharType delimiter);

template <class CharType, class Traits, class Allocator>
basic_istream<CharType, Traits>& getline(
    basic_istream<CharType, Traits>&& in_stream,
    basic_string<CharType, Traits, Allocator>& str,
    const CharType delimiter);

// (2) default delimiter used
template <class CharType, class Traits, class Allocator>
basic_istream<CharType, Traits>& getline(
    basic_istream<CharType, Traits>& in_stream,
    basic_string<CharType, Traits, Allocator>& str);

template <class Allocator, class Traits, class Allocator>
basic_istream<Allocator, Traits>& getline(
    basic_istream<Allocator, Traits>&& in_stream,
    basic_string<Allocator, Traits, Allocator>& str);

参数

in_stream
要从其中提取字符串的输入流。

str
从输入流读取的字符将放入的字符串。

delimiter
行分隔符。

返回值

输入流 in_stream。

备注

标记为 (1) 的一对函数签名从 in_stream 中提取字符，直到找到 delimiter，同时将它们存储在 str 中。

这对标记为 (2) 的函数签名使用换行符作为默认行分隔符，并且像 getline(in_stream, str, in_stream. widen('\n')) 那样执行。

每对函数中的第二个函数是第一个的模拟，它的作用是支持 rvalue 引用。

发生下列情况之一时，提取将停止：

在文件末尾的情况下，in_stream 的内部状态标志被设置为 ios_base::eofbit。
函数提取经比较与 delimiter 相等的元素后。元素不会被放回或追加到受控序列。
函数提取 str.max_size 个元素后。 in_stream 的内部状态标志设置为 ios_base::failbit。
除之前列出的错误之外的其他一些错误；in_stream 的内部状态标志设置为 ios_base::badbit。

有关内部状态标志的信息，请参阅 ios_base::iostate。

如果函数没有提取任何元素，则 in_stream 的内部状态标志被设置为 ios_base::failbit。在任何情况下，getline 返回 in_stream。

如果引发了异常，in_stream 和 str 将处于异常状态。

示例

以下代码演示两种模式下的 getline()：第一种使用默认分隔符（换行），第二种使用空格作为分隔符。文件尾字符（键盘上的 CTRL-Z）用于控制 while 循环的终止。此值会将 cin 的内部状态标志设置为 eofbit，后者必须使用 basic_ios::clear() 进行消除，这样第二个 while 循环才能正确运行。

// compile with: /EHsc /W4
#include <string>
#include <iostream>
#include <vector>

using namespace std;

int main()
{
    string str;
    vector<string> v1;
    cout << "Enter a sentence, press ENTER between sentences. (Ctrl-Z to stop): " << endl;
    // Loop until end-of-file (Ctrl-Z) is input, store each sentence in a vector.
    // Default delimiter is the newline character.
    while (getline(cin, str)) {
        v1.push_back(str);
    }

    cout << "The following input was stored with newline delimiter:" << endl;
    for (const auto& p : v1) {
        cout << p << endl;
    }

    cin.clear();

    vector<string> v2;
    // Now try it with a whitespace delimiter
    while (getline(cin, str, ' ')) {
        v2.push_back(str);
    }

    cout << "The following input was stored with whitespace as delimiter:" << endl;
    for (const auto& p : v2) {
        cout << p << endl;
    }
}

`stod`

将字符序列转换为 double。

double stod(
    const string& str,
    size_t* idx = 0);

double stod(
    const wstring& str,
    size_t* idx = 0);

参数

str
要转换的字符序列。

idx
首个未转换字符的索引值。

返回值

double 值。

备注

该函数将 str 中元素的序列转换为类型 double 的值，就像通过调用 strtod( str.c_str(), _Eptr) 实现一样，其中，_Eptr 是该函数的内部对象。如果 str.c_str() == *_Eptr，则将引发 invalid_argument 类型的对象。如果此类调用将设置 errno，它将引发 out_of_range 类型的对象。否则，如果 idx 不是 null 指针，则该函数会将 *_Eptr - str.c_str() 存储在 *idx 中并返回值。

`stof`

将字符序列转换为浮动的。

float stof(
    const string& str,
    size_t* idx = 0);

float stof(
    const wstring& str,
    size_t* idx = 0);

参数

str
要转换的字符序列。

idx
首个未转换字符的索引值。

返回值

float 值。

备注

该函数将 str 中元素的序列转换为类型 float 的值，就像通过调用 strtof( str.c_str(), _Eptr) 实现一样，其中，_Eptr 是该函数的内部对象。如果 str.c_str() == *_Eptr，则将引发 invalid_argument 类型的对象。如果此类调用将设置 errno，它将引发 out_of_range 类型的对象。否则，如果 idx 不是 null 指针，则该函数会将 *_Eptr - str.c_str() 存储在 *idx 中并返回值。

`stoi`

将字符序列转换为整数。

int stoi(
    const string& str,
    size_t* idx = 0,
    int base = 10);

int stoi(
    const wstring& str,
    size_t* idx = 0,
    int base = 10);

返回值

整数值。

参数

str
要转换的字符序列。

idx
首个未转换字符的索引值。

base
要使用的号码基。

备注

函数 stoi 将 str 中的字符序列转换为类型的值并返回该值int。例如，在传递字符序列“10”时，stoi 返回的值为整数 10.

当以 stoi 方式调用时，strtol 的行为方式与针对单字节字符的 strtol( str.c_str(), _Eptr, idx) 函数相似，其中，_Eptr 是函数的内部对象；而当以类似的方式调用 wcstol 时，其行为与针对宽字符的 wcstol(Str.c_str(), _Eptr, idx) 相似。有关详细信息，请参阅 strtol、wcstol、_strtol_l、_wcstol_l。

如果 str.c_str() == *_Eptr、stoi 引发 invalid_argument 类型的对象。如果此类调用将设置 errno，或者如果返回值无法表示为 int 类型的对象，则它将引发 out_of_range 类型的对象。否则，如果 idx 不是 null 指针，则该函数会将存储在 *_Eptr - str.c_str() 中*idx。

`stol`

将字符序列转换为 long。

long stol(
    const string& str,
    size_t* idx = 0,
    int base = 10);

long stol(
    const wstring& str,
    size_t* idx = 0,
    int base = 10);

参数

str
要转换的字符序列。

idx
首个未转换字符的索引值。

base
要使用的号码基。

返回值

长整数的值。

备注

该函数将 str 中元素的序列转换为类型的值，就像通过调用 long 实现一样，其中，strtol( str.c_str(), _Eptr, idx) 是该函数的内部对象_Eptr。如果 str.c_str() == *_Eptr，则将引发 invalid_argument 类型的对象。如果此类调用将设置 errno，它将引发 out_of_range 类型的对象。否则，如果 idx 不是 null 指针，则该函数会将 *_Eptr - str.c_str() 存储在 *idx 中并返回值。

`stold`

将字符序列转换为 long double。

double stold(
    const string& str,
    size_t* idx = 0);

double stold(
    const wstring& str,
    size_t* idx = 0);

参数

str
要转换的字符序列。

idx
首个未转换字符的索引值。

返回值

long double 值。

备注

该函数将 str 中元素的序列转换为类型的值，就像通过调用 long double 实现一样，其中，strtold( str.c_str(), _Eptr) 是该函数的内部对象_Eptr。如果 str.c_str() == *_Eptr，则将引发 invalid_argument 类型的对象。如果此类调用将设置 errno，它将引发 out_of_range 类型的对象。否则，如果 idx 不是 null 指针，则该函数会将 *_Eptr - str.c_str() 存储在 *idx 中并返回值。

`stoll`

将字符序列转换为 long long。

long long stoll(
    const string& str,
    size_t* idx = 0,
    int base = 10);

long long stoll(
    const wstring& str,
    size_t* idx = 0,
    int base = 10);

参数

str
要转换的字符序列。

idx
首个未转换字符的索引值。

base
要使用的号码基。

返回值

long long 值。

备注

该函数将 str 中元素的序列转换为类型的值，就像通过调用 long long 实现一样，其中，strtoll( str.c_str(), _Eptr, idx) 是该函数的内部对象_Eptr。如果 str.c_str() == *_Eptr，则将引发 invalid_argument 类型的对象。如果此类调用将设置 errno，它将引发 out_of_range 类型的对象。否则，如果 idx 不是 null 指针，则该函数会将存储在 *_Eptr - str.c_str() 中并返回值*idx。

`stoul`

将字符序列转换为无符号长整数。

unsigned long stoul(
    const string& str,
    size_t* idx = 0,
    int base = 10);

unsigned long stoul(
    const wstring& str,
    size_t* idx = 0,
    int base = 10);

参数

str
要转换的字符序列。

idx
首个未转换字符的索引值。

base
要使用的号码基。

返回值

无符号长整数的值。

备注

该函数将 str 中元素的序列转换为类型的值，就像通过调用 unsigned long 实现一样，其中，strtoul( str.c_str(), _Eptr, idx) 是该函数的内部对象_Eptr。如果 str.c_str() == *_Eptr，则将引发 invalid_argument 类型的对象。如果此类调用将设置 errno，它将引发 out_of_range 类型的对象。否则，如果 idx 不是 null 指针，则该函数会将存储在 *_Eptr - str.c_str() 中并返回值*idx。

`stoull`

将字符序列转换为 unsigned long long。

unsigned long long stoull(
    const string& str,
    size_t* idx = 0,
    int base = 10);

unsigned long long stoull(
    const wstring& str,
    size_t* idx = 0,
    int base = 10);

参数

str
要转换的字符序列。

idx
首个未转换字符的索引值。

base
要使用的号码基。

返回值

unsigned long long 值。

备注

该函数将 str 中元素的序列转换为类型的值，就像通过调用 unsigned long long 实现一样，其中，strtoull( str.c_str(), _Eptr, idx) 是该函数的内部对象_Eptr。如果 str.c_str() == *_Eptr，则将引发 invalid_argument 类型的对象。如果此类调用将设置 errno，它将引发 out_of_range 类型的对象。否则，如果 idx 不是 null 指针，则该函数会将 *_Eptr - str.c_str() 存储在 *idx 中并返回值。

`swap`

交换两个字符串的字符数组。

template <class Traits, class Allocator>
void swap(basic_string<CharType, Traits, Allocator>& left, basic_string<CharType, Traits, Allocator>& right);

参数

left
一个字符串，其元素将与另一个字符串的元素交换。

right
要与第一个字符串交换元素的另一个字符串。

备注

模板函数为字符串执行专用成员函数 left.swap(right)，此函数可保证恒定的复杂性。

示例

// string_swap.cpp
// compile with: /EHsc
#include <string>
#include <iostream>

int main( )
{
   using namespace std;
   // Declaring an object of type basic_string<char>
   string s1 ( "Tweedledee" );
   string s2 ( "Tweedledum" );
   cout << "Before swapping string s1 and s2:" << endl;
   cout << "The basic_string s1 = " << s1 << "." << endl;
   cout << "The basic_string s2 = " << s2 << "." << endl;

   swap ( s1 , s2 );
   cout << "\nAfter swapping string s1 and s2:" << endl;
   cout << "The basic_string s1 = " << s1 << "." << endl;
   cout << "The basic_string s2 = " << s2 << "." << endl;
}

Before swapping string s1 and s2:
The basic_string s1 = Tweedledee.
The basic_string s2 = Tweedledum.

After swapping string s1 and s2:
The basic_string s1 = Tweedledum.
The basic_string s2 = Tweedledee.

`to_string`

将一个值转换为 string。

string to_string(int value);
string to_string(unsigned int value);
string to_string(long value);
string to_string(unsigned long value);
string to_string(long long value);
string to_string(unsigned long long value);
string to_string(float value);
string to_string(double value);
string to_string(long double value);

参数

value
要转换的值。

返回值

表示该值的 string。

备注

此函数可将 value 转换为存储在函数内部数组对象中的元素序列，就像调用 Buf 一样，其中 sprintf(Buf, Fmt, value) 是Fmt

"%d"（如果 value 的类型为 int）
"%u"（如果 value 的类型为 unsigned int）
"%ld"（如果 value 的类型为 long）
"%lu"（如果 value 的类型为 unsigned long）
"%lld"（如果 value 的类型为 long long）
"%llu"（如果 value 的类型为 unsigned long long）
"%f"（如果 value 的类型为 float 或 double）
"%Lf"（如果 value 的类型为 long double）

该函数返回 string(Buf)。

`to_wstring`

将一个值转换为宽字符串。

wstring to_wstring(int value);
wstring to_wstring(unsigned int value);
wstring to_wstring(long value);
wstring to_wstring(unsigned long value);
wstring to_wstring(long long value);
wstring to_wstring(unsigned long long value);
wstring to_wstring(float value);
wstring to_wstring(double value);
wstring to_wstring(long double value);

参数

value
要转换的值。

返回值

表示该值的宽字符串。

备注

此函数可将 value 转换为存储在函数内部数组对象 Buf 中的元素序列，就像调用 swprintf(Buf, Len, Fmt, value) 一样，其中 Fmt 是

L"%d"（如果 value 的类型为 int）
L"%u"（如果 value 的类型为 unsigned int）
L"%ld"（如果 value 的类型为 long）
L"%lu"（如果 value 的类型为 unsigned long）
L"%lld"（如果 value 的类型为 long long）
L"%llu"（如果 value 的类型为 unsigned long long）
L"%f"（如果 value 的类型为 float 或 double）
L"%Lf"（如果 value 的类型为 long double）

该函数返回 wstring(Buf)。

另请参阅

<string>

反馈

此页面是否有帮助？

通过

<string> 函数

getline

参数

返回值

备注

示例

stod

参数

返回值

备注

stof

参数

返回值

备注

stoi

返回值

参数

备注

stol

参数

返回值

备注

stold

参数

返回值

备注

stoll

参数

返回值

备注

stoul

参数

返回值

备注

stoull

参数

返回值

备注

swap

参数

备注

示例

to_string

参数

返回值

备注

to_wstring

参数

返回值

备注

另请参阅

反馈

其他资源

`<string>` 函数

`getline`

`stod`

`stof`

`stoi`

`stol`

`stold`

`stoll`

`stoul`

`stoull`

`swap`

`to_string`

`to_wstring`