# operator>>(std::basic_istream)

> C++ Atlas: `cppatlas.com/w/cpp/io/basic_istream/operator_gtgt2` | Source: https://en.cppreference.com/w/cpp/io/basic_istream/operator_gtgt2 | Domain: Input/output | Standards: C++11, C++20

Extracting a single character that is the last character of the stream does not set eofbit: this is different from other formatted input functions, such as extracting the last integer with operator>>, but this behavior matches the…

## Official Specification Summary (cppreference)

```cpp
// Defined in header <istream>

template< class CharT, class Traits >
basic_istream<CharT, Traits>&
    operator>>( basic_istream<CharT, Traits>& st, CharT& ch );

template< class Traits >
basic_istream<char, Traits>&
    operator>>( basic_istream<char, Traits>& st, signed char& ch );

template< class Traits >
basic_istream<char, Traits>&
    operator>>( basic_istream<char, Traits>& st, unsigned char& ch ); // (1)

template< class CharT, class Traits>
basic_istream<CharT, Traits>&
    operator>>( basic_istream<CharT, Traits>& st, CharT* s );

template< class Traits >
basic_istream<char, Traits>&
    operator>>( basic_istream<char, Traits>& st, signed char* s );

template< class Traits >
basic_istream<char, Traits>&
    operator>>( basic_istream<char, Traits>& st, unsigned char* s ); // (2) (until C++20)

template< class CharT, class Traits, std::size_t N >
basic_istream<CharT, Traits>&
    operator>>( basic_istream<CharT, Traits>& st, CharT (&s)[N] );

template< class Traits, std::size_t N >
basic_istream<char, Traits>&
    operator>>( basic_istream<char, Traits>& st, signed char (&s)[N] );

template< class Traits, std::size_t N >
basic_istream<char, Traits>&
    operator>>( basic_istream<char, Traits>& st, unsigned char (&s)[N] ); // (2) (since C++20)

template< class Istream, class T >
Istream&&
    operator>>( Istream&& st, T&& value ); // (3) (since C++11)
```

1,2) Performs character input operations.

1) Behaves as a *FormattedInputFunction*. After constructing and checking the sentry object, which may skip leading whitespace, extracts a character and stores it to `ch`. If no character is available, sets `failbit` (in addition to `eofbit` that is set as required of a *FormattedInputFunction*).

2) Behaves as a *FormattedInputFunction*. After constructing and checking the sentry object, which may skip leading whitespace, extracts successive characters and stores them at successive locations of a character array whose first element is pointed to by (until C++20) `s`. The extraction stops if any of the following conditions is met:

   - A whitespace character (as determined by the `ctype<CharT>` facet) is found. The whitespace character is not extracted.

   (until C++20):

   - If `st.width()` is greater than zero, `st.width() - 1` characters are stored.

   (since C++20):

   - `n - 1` characters are stored, where `n` is defined as follows:

     - If `st.width()` is greater than zero, `std::min(std::size_t(st.width()), N)`;
     - otherwise, `n` is `N`.

   - End of file occurs in the input sequence (this also sets `eofbit`).

   In either case, an additional null character value `CharT()` is stored at the end of the output. If no characters were extracted, sets `failbit` (the null character is still written, to the first position in the output). Finally, calls `st.width(0)` to cancel the effects of `std::setw`, if any.

3) Calls the appropriate extraction operator, given an rvalue reference to an input stream object (equivalent to `st >> std::forward<T>(value)`). This overload participates in overload resolution only if `st >> std::forward<T>(value)` is well-formed and `Istream` is a class type publicly and unambiguously derived from `std::ios_base`.

### Notes

Extracting a single character that is the last character of the stream does not set `eofbit`: this is different from other formatted input functions, such as extracting the last integer with `operator>>`, but this behavior matches the behavior of `std::scanf` with `"%c"` format specifier.

### Parameters

- `st` - input stream to extract the data from
- `ch` - reference to a character to store the extracted character to
- `s` - pointer to (until C++20) a character array to store the extracted characters to

### Return value

1,2) `st`

3) `std::move(st)`

### Example

```cpp
#include <iomanip>
#include <iostream>
#include <sstream>

int main()
{
    std::string input = "n greetings";
    std::istringstream stream(input);

    char c;
    const int MAX = 6;
    char cstr[MAX];

    stream >> c >> std::setw(MAX) >> cstr;
    std::cout << "c = " << c << '\n'
              << "cstr = " << cstr << '\n';

    double f;
    std::istringstream("1.23") >> f; // rvalue stream extraction
    std::cout << "f = " << f << '\n';
}
```

Output:

```text
c = n
cstr = greet
f = 1.23
```

### 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 13 | C++98 | the definition of `n` mentioned a non-existing name `eos` | replaced with `CharT()` |
| LWG 68 | C++98 | no null characters were stored at the end of the output for overload (2) | stores a null character |
| LWG 1203 | C++98 | overload for rvalue stream returned lvalue reference to the base class | returns rvalue reference to the derived class |
| LWG 2328 | C++98 | overload for rvalue stream required another argument to be lvalue | made to accept rvalue |
| LWG 2534 | C++98 | overload for rvalue stream was not constrained | constrained |

### See also

- [`operator>>`](https://en.cppreference.com/w/cpp/io/basic_istream/operator_gtgt): extracts formatted data (public member function)

---
Attribution: content from https://en.cppreference.com/w/cpp/io/basic_istream/operator_gtgt2 (cppreference.com), licensed under CC-BY-SA 3.0 and GFDL. Modified: converted to markdown, study notes added. Offline snapshot of 9 February 2025.