What does it mean to return a class object in a member function?

Question

I'm quite new to programming in C++ so sorry if this is stupid. I have been working through the c++ primer book, and there is something i just cant get my head around. Take this function for example:

Sales_data& Sales_data::combine(const Sales_data &rhs)
{
    units_sold += rhs.units_sold;
    revenue += rhs.revenue;
    return *this;
}

And we called the function using:

total.combine(trans);

I get that the units sold & revenue in the total object will be combined with that in the trans object, working much like the compound assignment operator (+=).

I get that this would return the total object, but I dont get what returning the total object means...

Answer 1

Returning by reference (to the object being called on) means you could chain the calls in one line code; all these calls would be bound to the same object:

total.combine(trans).combine(trans2).combine(trans3);

which is equivalent with:

total.combine(trans);
total.combine(trans2);
total.combine(trans3);

(Of course it doesn't mean you have to call the same method, you could mix with other methods with similar characteristic.)

This idiom is often used in the implementations of operators like operator=, operator<<, operator>> etc, which are also possible to be called with chaining:

a = b = c;
cout << a << b << c;

Answer 2

It returns a reference to itself, this allows method chaining. For example, say you have 2 Sales_data objects and you want to combine both of them, you can then "chain" the calls:

Sales_data s1, s2, total;
//stuff..
total.combine(s1).combine(s2);

Because you return a reference this allows the total object to be modified in between calls, which is why it's called a "chain".