# std::basic_istream<CharT,Traits>::operator>>

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

Extracts values from an input stream.

## Official Specification Summary (cppreference)

```cpp
basic_istream& operator>>( unsigned short& value ); // (1)

basic_istream& operator>>( unsigned int& value ); // (2)

basic_istream& operator>>( long& value ); // (3)

basic_istream& operator>>( unsigned long& value ); // (4)

basic_istream& operator>>( long long& value ); // (5) (since C++11)

basic_istream& operator>>( unsigned long long& value ); // (6) (since C++11)

basic_istream& operator>>( float& value ); // (7)

basic_istream& operator>>( double& value ); // (8)

basic_istream& operator>>( long double& value ); // (9)

basic_istream& operator>>( bool& value ); // (10)

basic_istream& operator>>( void*& value ); // (11)

basic_istream& operator>>( short& value ); // (12)

basic_istream& operator>>( int& value ); // (13)

basic_istream& operator>>( /* extended-floating-point-type */& value ); // (14) (since C++23)

basic_istream& operator>>( std::ios_base& (*func)(std::ios_base&) ); // (15)

basic_istream& operator>>( std::basic_ios<CharT, Traits>&
                               (*func)(std::basic_ios<CharT, Traits>&) ); // (16)

basic_istream& operator>>( basic_istream& (*func)(basic_istream&) ); // (17)

basic_istream& operator>>( std::basic_streambuf<CharT, Traits>* sb ); // (18)
```

Extracts values from an input stream.

1-11) Extracts a value potentially skipping preceding whitespace. The value is stored to a given reference `value`.

This function behaves as a *FormattedInputFunction*. After constructing and checking the sentry object, which may skip leading whitespace, extracts a value by calling `std::num_get::get()`.

12) Extracts a `short` value potentially skipping preceding whitespace. The value is stored to a given reference `value`.

This function behaves as a *FormattedInputFunction*. After constructing and checking the sentry object, which may skip leading whitespace, extracts a `long` value `lval` by calling `std::num_get::get()`. After that:

   - If `lval < std::numeric_limits<short>::min()`, sets `failbit` and stores `std::numeric_limits<short>::min()` to `val`.
   - Otherwise, if `std::numeric_limits<short>::max() < lval`, sets `failbit` and stores `std::numeric_limits<short>::max()` to `val`.
   - Otherwise, stores `static_cast<short>(lval)` to `val`.

13) Extracts an `int` value potentially skipping preceding whitespace. The value is stored to a given reference `value`.

This function behaves as a *FormattedInputFunction*. After constructing and checking the sentry object, which may skip leading whitespace, extracts a `long` value `lval` by calling `std::num_get::get()`. After that:

   - If `lval < std::numeric_limits<int>::min()`, sets `failbit` and stores `std::numeric_limits<int>::min()` to `val`.
   - Otherwise, if `std::numeric_limits<int>::max() < lval`, sets `failbit` and stores `std::numeric_limits<int>::max()` to `val`.
   - Otherwise, stores `static_cast<int>(lval)` to `val`.

14) Extracts an extended floating-point value potentially skipping preceding whitespace. The value is stored to a given reference `value`. The library provides overloads for all cv-unqualified extended floating-point types as the referenced type of the parameter `value`.

Determines the standard floating-point type `FP` as follows:

   - If the floating-point conversion rank of `/* extended-floating-point-type */` is less than or equal to that of `float`, then `FP` is `float`.
   - Otherwise, if the floating-point conversion rank of `/* extended-floating-point-type */` is less than or equal to that of `double`, then `FP` is `double`.
   - Otherwise, `FP` is `long double`.

This function behaves as a *FormattedInputFunction*. After constructing and checking the sentry object, which may skip leading whitespace, extracts an `FP` value `fval` by calling `std::num_get::get()`. After that:

   - If `fval < -std::numeric_limits</* extended-floating-point-type */>::max()`, sets `failbit` and stores `-std::numeric_limits</* extended-floating-point-type */>::max()` to `val`.
   - Otherwise, if `std::numeric_limits</* extended-floating-point-type */>::max() < fval`, sets `failbit` and stores `std::numeric_limits</* extended-floating-point-type */>::max()` to `val`.
   - Otherwise, stores `static_cast</* extended-floating-point-type */>(fval)` to `val`.

15-17) Calls `func(*this)`, where `func` is an I/O manipulator.

18) Behaves as an *UnformattedInputFunction*. After constructing and checking the sentry object, extracts all data from `*this` and stores it to `sb`. The extraction stops if one of the following conditions are met:

     - end-of-file occurs on the input sequence;
     - inserting in the output sequence fails (in which case the character to be inserted is not extracted);
     - an exception occurs (in which case the exception is caught, and only rethrown if it inserted no characters and `failbit` is enabled in `exceptions()`).

   In either case, stores the number of characters extracted in the member variable accessed by subsequent calls to `gcount()`. If `sb` is a null pointer or if no characters were inserted into `sb`, calls `setstate(failbit)` (which may throw `std::ios_base::failure` if enabled).

If extraction fails (e.g. if a letter was entered where a digit is expected), zero is written to `value` and `failbit` is set. For signed integers, if extraction results in the value too large or too small to fit in `value`, `std::numeric_limits<T>::max()` or `std::numeric_limits<T>::min()` (respectively) is written and `failbit` flag is set. For unsigned integers, if extraction results in the value too large or too small to fit in `value`, `std::numeric_limits<T>::max()` is written and `failbit` flag is set.

### Parameters

- `value` - reference to an integer or floating-point value to store the extracted value to
- `func` - pointer to I/O manipulator function
- `sb` - pointer to the stream buffer to write all the data to

### Return value

1-16,18) `*this`

17) `func(*this)`

### Notes

For overload (14), when the extended floating-point type has a floating-point conversion rank that is not equal to the rank of any standard floating-point type, then double rounding during the conversion can result in inaccurate results. `std::from_chars()` can be used in situations where maximum accuracy is important.

### Example

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

int main()
{
    std::string input = "41 3.14 false hello world";
    std::istringstream stream(input);

    int n;
    double f;
    bool b;

    stream >> n >> f >> std::boolalpha >> b;
    std::cout << "n = " << n << '\n'
              << "f = " << f << '\n'
              << "b = " << std::boolalpha << b << '\n';

    // extract the rest using the streambuf overload
    stream >> std::cout.rdbuf();
    std::cout << '\n';
}
```

Output:

```text
n = 41
f = 3.14
b = false
hello world
```

### 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 64 | C++98 | it was unclear whether overload (18) can only rethrow the `std::ios_base::failure` thrown by calling `setstate(failbit)` | all exceptions caught can be rethrown |
| LWG 118 | C++98 | overload (12,13) delegated the extraction to `num_get::get`, but it does not have overloads for `short` and `int` | a `long` value is extracted instead of `short` or `int` |
| LWG 413 | C++98 | overload (18) only rethrew exceptions thrown while extracting characters from `sb`, but characters are extracted from `*this` | corrected `sb` to `*this` |
| LWG 567 | C++98 | overload (18) behaved as a *FormattedInputFunction* because of the resolution of LWG issue 60 | it behaves as an *UnformattedInputFunction* |
| LWG 661 | C++98 | overloads (12,13) did not store the extracted number to `value` due to the resolution of LWG issue 118 | stores the number if no overflow occurs |
| LWG 696 | C++98 | `value` was unchanged on extraction failure | set to zero or minimum/ maximum values |

### See also

- [`operator>>(std::basic_istream)`](https://en.cppreference.com/w/cpp/io/basic_istream/operator_gtgt2): extracts characters and character arrays (function template)
- [`operator<<`](https://en.cppreference.com/w/cpp/string/basic_string/operator_ltltgtgt), [`operator>>`](https://en.cppreference.com/w/cpp/string/basic_string/operator_ltltgtgt): performs stream input and output on strings (function template)
- [`operator<<`](https://en.cppreference.com/w/cpp/utility/bitset/operator_ltltgtgt2), [`operator>>`](https://en.cppreference.com/w/cpp/utility/bitset/operator_ltltgtgt2): performs stream input and output of bitsets (function template)
- [`operator<<`](https://en.cppreference.com/w/cpp/numeric/complex/operator_ltltgtgt), [`operator>>`](https://en.cppreference.com/w/cpp/numeric/complex/operator_ltltgtgt): serializes and deserializes a complex number (function template)
- [`operator<<`](https://en.cppreference.com/w/cpp/numeric/random/linear_congruential_engine/operator_ltltgtgt) (C++11), [`operator>>`](https://en.cppreference.com/w/cpp/numeric/random/linear_congruential_engine/operator_ltltgtgt): performs stream input and output on pseudo-random number engine (function template)
- [`operator<<`](https://en.cppreference.com/w/cpp/numeric/random/uniform_int_distribution/operator_ltltgtgt) (C++11), [`operator>>`](https://en.cppreference.com/w/cpp/numeric/random/uniform_int_distribution/operator_ltltgtgt): performs stream input and output on pseudo-random number distribution (function template)
- [`read`](https://en.cppreference.com/w/cpp/io/basic_istream/read): extracts blocks of characters (public member function)
- [`readsome`](https://en.cppreference.com/w/cpp/io/basic_istream/readsome): extracts already available blocks of characters (public member function)
- [`get`](https://en.cppreference.com/w/cpp/io/basic_istream/get): extracts characters (public member function)
- [`getline`](https://en.cppreference.com/w/cpp/io/basic_istream/getline): extracts characters until the given character is found (public member function)
- [`from_chars`](https://en.cppreference.com/w/cpp/utility/from_chars) (C++17): converts a character sequence to an integer or floating-point value (function)

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