std::basic_...:operator>>(3)

📦 version 2024.07.05, in nixpkgs unstable, opensuse-leap 16.0

🌸 NAME 🌸

okay so this is the std::basic_istream::operator>> page from the C++ Standard Library manual, section 3, and it's literally the extraction operator — the >> bestie you use to pull values out of an input stream. The official name is std::basic_istream::operator>>, and yes it shows up twice in the NAME line because the manual is dramatic like that. 💅

✨ SYNOPSIS ✨

vibe check: here's the whole overload lineup, no cap:

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)

💖 DESCRIPTION 💖

The one-line summary is: extracts values from an input stream. That's the main character energy right there. Now here's the overload tea, fr fr:

  • Overloads (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, it extracts a value by calling std::num_get::get(). 🫶
  • Overload (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, it 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.
  • Overload (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, it 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.
  • Overload (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, it 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.
  • Overloads (15)–(17) — calls func(*this), where func is an I/O manipulator. That's the whole thing. Slay. ✨
  • Overload (18) — behaves as an UnformattedInputFunction. After constructing and checking the sentry object, it 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, it 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).

⚠️ extraction-fail tea, bestie: 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 🌈

  • Overloads (1)–(16), (18) — returns *this.
  • Overload (17) — returns 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. iykyk 🧚

🍓 EXAMPLE 🍓

The example says // Run this code, and honestly you should:

#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 ⭐

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.

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

👀 SEE ALSO 👀

okay bestie, here's the whole friend group — every one of these is worth a follow, fr fr:

  • operator>>(std::basic_istream) — the OOP version: extracts characters and character arrays ✨ (function template)
  • operator<< / operator>> — the duo that performs stream input and output on strings 💖 (function template)
  • operator<< / operator>> — same energy but for bitsets — performs stream input and output of bitsets 🎀 (function template)
  • operator<< / operator>> — serializes and deserializes a complex number 🦋 (function template)
  • operator<< / operator>> — performs stream input and output on a pseudo-random number engine 🌸 (C++11) (function template)
  • operator<< / operator>> — performs stream input and output on a pseudo-random number distribution 🌈 (C++11) (function template)
  • read — extracts blocks of characters, the "gimme a whole chunk" icon 👑 (public member function)
  • readsome — extracts already available blocks of characters, the "gimme whatever's ready rn" vibe 💅 (public member function)
  • get — extracts characters, one at a time, main character energy ⭐ (public member function)
  • getline — extracts characters until the given character is found — literally the delulu line-reader we all know and love 😭 (public member function)
  • from_chars — converts a character sequence to an integer or floating-point value, no stream drama, no cap 🔥 (C++17) (function)
lowkey the whole point: if you're doing string stream stuff, these are your people. go say hi 🫶

and that's a wrap on the whole page, bestie!! 💜 this one came straight from http://cppreference.com, dated 2024.06.10 — so if the standard moves, blame the timestamps, not me 🙈 k bye, go write some operator>> overloads that actually compile 💖✨🎀

📦 where this page comes from