Stream Insertion Operator overloading

Question

Im really unsure how to call the function:

friend ostream& operator<<(ostream& out, stack::myItem& theItem);

that is public to my stack object:

class stack
{
public:
    stack(int capacity);
    ~stack(void);
     void method1();
     ...

private:

    struct myItem
    {
        int             item;
    };

      ...
public:
    friend ostream& operator<<(ostream& out, stack& s);
    friend ostream& operator<<(ostream& out, stack::myItem& theItem);
};

Answer 1

It's no different than using stream operator << for any other type (it is called operator overloading for a reason).

However, outputting should not modify an object, hence you really should pass it by const reference (otherwise calls with temporaries would fail to compile).

friend ostream& operator<<(ostream& out, const stack& s);
friend ostream& operator<<(ostream& out, const stack::myItem& theItem);

Answer 2

Call it from where? As it's coded only the class knows about the private struct. No code external to the class could use that method since it couldn't create an instance of the struct. Marking it as friend doesn't do you much good.

Answer 3

This operator is a classic binary operator.

// Say I have an operator declared like this:
return_type operator@(left_type lhs, right_type rhs);

// Then the invocation is done this way:
left_type L;
right_type R;
return_type result = L @ R;

In the case of the streaming operator, it is a bit special since the left hand argument and the return type actually have the same type (and indeed, will refer to the same object, albeit at different times). This has been done to allow chaining.

// Chaining
std::cout << "<Output>  " << 1 << std::endl;

// Which can be analyzed like such
operator<<(
  operator<<(
    operator<<(
      std::cout ,
      "<Output>  "
    ),
    1
  ),
  std::endl
);

As you can see, the syntax merely allows a convenient invocation. One might note that the order is very well defined, it is a strict left to right evaluation.

So with your object, it would become:

stack s;
std::cout << s << std::endl;

Just like that!