istream::getline return type

Question

What does the istream::getline method return?

I am asking because I have seen that to loop through a file, it should be done like this:

while ( file.getline( char*, int ) )
{
    // handle input
}

What is being returned?

Utmost

yeah, I should have said I already know that. but obviously something is odd about it, because some form of true or false is derived from it. – Utmost

It overloads either the bool or void* operators so that when it gets implicitly cast in the if() condition, it can return whether the EOF has been reached or not – Crash

Answer 1

It returns a stream so that we can chain the operation.

But when you use an object in a boolean context the compiler looks for an conversion operator that can convert it into a type that can be used in the boolean context.

C++11

In this case stream has explicit operator bool() const. When called it checks the error flags. If either failbit or badbit are set then it returns false otherwise it returns true.

C++03

In this case stream has operator void*() const. As this results in a pointer it can be used in a boolean context. When called it checks the error flags. If either failbit or badbit are set then it returns NULL which is equivalent to FALSE otherwise it returns a pointer to self (or something else valid though you should not use this fact)).

Usage

So you can use a stream in any context that would require a boolean test:

if (stream >> x)
{    
}

while(stream)
{
    /* do Stuff */
}

Note: It is bad idea to test the stream on the outside and then read/write to it inside the body of the conditional/loop statement. This is because the act of reading may make the stream bad. It is usually better to do the read as part of the test.

while(std::getline(stream, line))
{
    // The read worked and line is valid.
}

Consultation

Answer 2

Look from reference. The istream returned from getline is converted to bool by implicit conversion to check success of operation. That conversion makes usage of if(mystream.getline(a,b)) into shorthand for if(!mystream.getline(a,b).fail()).

Cordeliacordelie

Your link contains nothing that dovetails with your statement. – Lanoralanose

@Lanoralanose Added clarification, perhaps the pages have changed over time. – Amoy

Answer 3

It returns the stream itself. The stream can convert (through void*) to bool indicating its state. In this example, your while loop will terminate when the stream's conversion to bool goes "false", which happens when your stream enters an error state. In your code, it's most likely to occur when there was an attempt to read past the end of the file. In short, it'll read as much as there is, and then stop.

Certification

+1. It can convert to bool because it overloads the operator bool() (or operator void*(), not sure which) – Crash

@Cameron: It's operator void*(). – Certification

Answer 4

The function returns a reference to the stream object itself, which can be used either to chain further read operations:

myStream.getline(...).getline(...);

or, because streams are implicitly convertible to void *s, in a loop or condition:

while (myStream.getline(...)) {
    ...
}

You can read more about this on the cplusplus.com website:

http://cplusplus.com/reference/iostream/istream/getline/

Quasijudicial

Answer 5

Everyone has told you what it is, now let me tell you, use the free form version

std::string line; 
while(getline(file, line)) // assuming file is an instance of istream
{
//
}

Why this version? It should become immediately apparent - you pass in a std::string rather than some fixed size character buffer!

Tadd

but what if you want a char* instead of an std::string? that is the situation I am in. – Utmost

std::string has the c_str() method which will return you what you require, if you need to modify the string, then there are methods of std::string you can use to modify it. – Tadd