Returning istream from a function

[Nikhar]

Hey guys...Can you please help me explain what does returning an istream object mean.

I am currently studying Accelerated C++ and at many places a function returns istream object. What does it mean?

For example:-

istream& read(istream& is, Student_info& s)
{
// read and store the student's name and midterm and final exam grades
is >> s.name >> s.midterm >> s.final;
read_hw(is, s.homework); // read and store all the student's homework grades
return is;
}

istream& read_hw(istream& in, vector<double>& hw)
{
if (in) {
// get rid of previous contents
hw.clear() ;
// read homework grades
double x;
while (in >> x)
hw.push_back(x);
// clear the stream so that input will work for the next student
in.clear();
}
return in;
}

What do the two functions mean? Basically, I want to ask what does passing an istream object mean and returning an istream object do?

And they are using "is" with ">>". Isn't cin used there?

[Fbody]

istream is the input stream base class that nearly all inputs are derived from. The class can be linked to files, hardware ports (such as USB or COM), etc... The object cin is a special globally-scoped object/instance of the istream class that is automatically linked to the console/keyboard.

Without seeing the rest of the code, I can't say for sure, but considering the context, this particular instance of istream is probably linked to a file and is not within the global scope. As such, it must be passed into and out of any scopes that it needs to be available in.

Keep tracing the istream object backward through the function calls in the code to find out where the object is originally initialized, that should tell you for sure what it's linked to.

[mrnutty]

The function uses the & operator. That operator makes a variable
synonym.

For example :

int num = 10  ;
int &ref_num = num;
ref_num = 4;   //same as doing    num = 4

So similarly, since this function :

istream& read(istream& is, Student_info& s)

Take a look at this part :

istream& is, Student_info& s

What ever we pass to that function ( assuming its acceptable),
is becomes a synonym, and s becomes a synonym.

So say this is how we call the that function

read( cin,  anStudentObject ); //function call

Since the prototype is :

istream& read(istream& is, Student_info& s)

and since cin is a istream object, and anStudentObject is a Student_info object, that function call is acceptable.
You remember what the & operator does right? Passing in , cin and
Student_info makes the variable, "is" and "s" synonym to cin and anStudentObject , respectively. So using the "is" variable is like
using the cin variable, its just a different name. Ok?

The reason it returns a istream object is to show you that it can.
And when you get to operator overloading you will see the significance
of it.

But know that you can do this :

Student_info& student;
//...insert info into s

//call your read function and since it returns an object, we can use it cin again
read(cin , student).clear()

[Nikhar]

Thanks fbody. :)

Thanks fperson.:)

read(cin , student).clear()

This simple statement explained a lot.