Overview
Having previously written an article on iostream inserters and extractors, I
decided to write an article on modifiers. Most people use iostream
modifiers without even realising. std::endl is the most common modifier,
it is simply an item that can be passed into a stream that affects the output.
std::endl
We're going to start by picking on std::endl. How often do you see code
like this ?
for(int i = 0; i < 100; ++i) myStream << "This is function
number " << lNum << " " << m_szArray[i] << endl;
What is often not understood is that std::endl does not just pass in a line
break. It also sends a flush to the stream, which can be a real
performance hit, if done as seen above. Basically, a buffered stream will
unload when flush is called, or the stream is destroyed. The advantage
of the buffer is almost entirely lost in the above case. So, as a simply
first example, I am going to show how to create a new modifier which does the
line break without the flush. It looks like this:
#include <iosfwd>
class Newline
{
public:
friend std::ostream & operator <<(std::ostream &os, const Newline nl)
{
os << "\r\n";
return os;
}
};
This leaves us able to create a new line like this:
cout << "Here is my line " << Newline();
It works like this. Our code creates a new, unnamed instance of our
class. During it's (brief) lifetime, the stream inserter is called, and
the instance is passed in. Our implementation of a stream operator is
rudimentary, it simply passes in the new line and returns the stream object (as it
should).
Gettin' jiggy with it
The prior example was deliberately simple in order to illustrate the core
functionality which any modifier will need to have. Our next will be a
little more complex: it will accept parameters. In my work I do a lot of
interacting with databases, and I quite often construct queries using an
ostringstream. Under those circumstances I am quite often querying a
range based on date, and so I wrote a modifier to insert a
datestamp. We will build this modifier now, a step at a time.
Constants
The first thing we will need is values to pass into the constructor. I
have built only four, but it will be easy for you to add more. Some
obvious ones to add would be dd/mm/yyyy and mm/dd/yyyy formats. For my
purposes, we generally want ISO8601 format, with or without the time, and I've
added one which includes the month in a text format, which is the other format
that is universally readable ( i.e. it does not cause confusion as to which
number is the month and which is the day ). After much agonising, I
elected to include this code in namespace std, because while overall I would
not use std as a dumping ground for stuff I wanted to protect with a namespace,
this code does interact directly with the std library and it's not
illogical for it to live with it.
namespace std
{
const int DT_ISO8601 = 1;
const int DT_ISO8601DateOnly = 2;
const int DT_DD_MMM_YYYY = 3;
const int DT_HH_MM = 4;
const std::string DateStamp::Dates [12] =
{
"Jan.", "Feb.", "March", "Apr.", "May", "June",
"July", "Aug", "Sept.", "Oct.", "Nov.", "Dec."
};
The constructor
Our constructor will use the keyword explicit to ensure that no implicit
conversions take place with values passed into it. All parameters have
default values, so it is easy to build our preferred datestamp format.
The parameters are the format constant, an offset ( so you can pass in -7 to
get the date a week ago, or 1 to get tomorrow's date ), and the delimiters used
between date elements and time elements. Note I have used strings instead
of chars so you can have multicharacter delimiters if you want to.
class DateStamp
{
public:
explicit DateStamp(int nType = DT_ISO8601, int nOffset = 0,
std::string sDateDelimiter = "-",
std::string sTimeDelimiter = ":")
: datetype(nType), dateDelimiter(sDateDelimiter),
timeDelimiter(sTimeDelimiter), offset(nOffset) {}
The inserter
The guts of the inserter are reasonable obvious and uninteresting. I
use ::time and ::localtime to get to the point of having a tm struct with the
timestamp in it, then do a switch on the format value in order to figure out
what to stream into a stringstream, which we then dump into the target
stream. Probably the most important thing is to note that it is defined
inside the class, and is defined as a friend of the class. This means we
can make our variables private, and still have access to them within the
inserter.
friend std::ostream & operator <<(std::ostream &os, const DateStamp &mm)
{
time_t lTime; ::time(&lTime);
lTime += mm.offset * 86400;
tm* ptmDate = ::localtime(&lTime);
std::ostringstream ss;
ss.fill('0');
switch(mm.datetype)
{
case DT_ISO8601:
case DT_ISO8601DateOnly:
ss << ptmDate->tm_year + 1900 << mm.dateDelimiter;
ss << std::setw(2) << ptmDate->tm_mon + 1 << mm.dateDelimiter;
ss << std::setw(2) << ptmDate->tm_mday;
if (mm.datetype == DT_ISO8601DateOnly) break;
ss << "T" << std::setw(2) << ptmDate->tm_hour << mm.timeDelimiter;
ss << std::setw(2) << ptmDate->tm_min << mm.timeDelimiter;
ss << std::setw(2) << ptmDate->tm_sec;
break;
case DT_DD_MMM_YYYY:
ss << std::setw(2) << ptmDate->tm_mday << mm.dateDelimiter;
ss << Dates[ptmDate->tm_mon] << mm.dateDelimiter
<< ptmDate->tm_year + 1900;
break;
case DT_HH_MM:
ss << std::setw(2) << ptmDate->tm_hour << mm.timeDelimiter;
ss << std::setw(2) << ptmDate->tm_min;
break;
}
os << ss.str();
return os;
};
Modifiers with state
The date modifiers above all force a month or day less than 10 to have a
preceding 0 by passing in first std::setw(2). How does this work ?
Obviously at the point that the modifier is passed in, iostreams does not yet
know the value it needs to force to this width. The answer is that
modifiers can have state. It is a beautiful thing, and it works like
this. When we write a modifier which will have state, we put a
static int into the class declaration, and we initialise it with a call to
std::ios_base::xalloc(). This returns an int, which could well be
different between times that it is run. I believe it is an
index into a linked list ( only because that makes the most sense ), but
whatever it is, it can then be used to set and get either a void *, or an
integer, using either the iword or pword functions, which are present
in your stream object passed in, but the values are shared through
iostreams, so if you wanted to set or get a value and did not have a
stream to use, you could just as well use cout, or any other standard
stream, or even construct one ( although I don't know why you would ). To
illustrate, our final example is a simple class which is designed to hold
someone's name details. The constructor takes two strings, a first name
and a second name. We once again place these in std, although I usually
would put them elsewhere, I don't expect anyone to use this example apart
from for illustrative purposes. We also again set values for the
formats we will be able to use.
namespace std
{
const int NAME_FIRST_LAST = 1;
const int NAME_LAST_FIRST = 2;
const int NAME_INITAL_LAST = 3;
const int NAME_INITIALS = 4;
class CName
{
friend class NameFormat;
public:
CName(std::string first, std::string last)
: m_sFirst(first), m_sLast(last)
{};
Pretty straightforward stuff so far. The next line is where things get
interesting. For the sake of clarity, I have shown the variable inside
the class scope, and then shown how we declare it's value outside it.
class CName
{
...
static int GetAlloc(){return m_nAlloc;};
private:
std::string m_sFirst, m_sLast;
static const int m_nAlloc;
...
}
const int CName::m_nAlloc = std::ios_base::xalloc();
As I've already mentioned, the call to xalloc returns an index which we will
then use to pass values through iostreams. I say 'through', because the
fact is that our modifier will use this index for the purpose of storing a
value, and the inserter for the class will pull it out and use it to decide how
to format the output. It is therefore a matter of personal taste if you
feel the value belongs in the class or in the modifier. I go for the
class, because the modifier is defined inside the class also. So inside
the class definition, we define our inserter as follows:
friend std::ostream & operator <<(std::ostream &os, const CName &nm)
{
if (!os.good())
return os;
std::ostream::sentry sentry(os);
if(sentry)
{
std::ostringstream ss;
switch(os.iword(nm.m_nAlloc))
{
default:
case NAME_FIRST_LAST:
ss << nm.m_sFirst << " " << nm.m_sLast;
break;
case NAME_LAST_FIRST:
ss << nm.m_sLast << ", " << nm.m_sFirst;
break;
case NAME_INITAL_LAST:
ss << nm.m_sFirst[0] << ". " << nm.m_sLast;
break;
case NAME_INITIALS:
ss << nm.m_sFirst[0] << nm.m_sLast[0];
break;
}
os << ss.str();
}
return os;
};
If you'd like to know more about writing iostream inserters and extractors,
please refer to my article on the subject.
All that remains is to define the stream modifier, which will set the value
stored in iostreams and retrieved by our inserter.
class NameFormat
{
public:
explicit NameFormat(int nFormat) : m_nFormat(nFormat){}
template<class charT class Traits class="",>
friend std::basic_ostream<charT Traits,> & operator <<
(std::basic_ostream<charT Traits ,>& os,
const NameFormat & nf)
{
os.iword(CName::GetAlloc()) = nf.m_nFormat;
return os;
}
private:
int m_nFormat;
};
And there it is. We can now print different formats from the same name,
simply by passing them in through our modifier. Here is the full listing
of the example program:
#include "stdafx.h"
#include
#include "Date Inserter.h"
#include "Newline.h"
#include "Name.h"
using std::cout;
using std::cin;
using std::endl;
using std::CName;
using std::NameFormat;
using std::DateStamp;
int _tmain(int argc, _TCHAR* argv[])
{
cout << "My output " << endl;
cout << "My other output " << Newline();
cout << "And some more.... " << Newline();
CName name("Christian", "Graus");
cout << name << Newline();
cout << NameFormat(std::NAME_LAST_FIRST) << name << Newline();
cout << NameFormat(std::NAME_INITAL_LAST) << name << Newline();
cout << NameFormat(std::NAME_INITIALS) << name << Newline();
cout << DateStamp() << Newline();
cout << DateStamp(std::DT_ISO8601DateOnly) << Newline();
cout << DateStamp(std::DT_DD_MMM_YYYY) << Newline();
cout << DateStamp(std::DT_HH_MM) << Newline();
int i;
cin >> i;
return 0;
}
and the output look like this:
My output
My other output
And some more....
Christian Graus
Graus, Christian
C. Graus
CG
2002-07-15T20:19:59
2002-07-15
15-July-2002
20:19
I hope you agree with me that iostreams is a highly flexible and useful
framework. Add the ability to define your own stream types and you have a
system by which you can easily pass any information you please, where-ever you
choose. My detractors often bring up the fact that iostreams seems to add
80 odd kilobytes to your executable. This is probably true (that is to
say, I have not checked, but I believe the people who have told me).
However, this is hardly a concern to me, because I use iostreams *constantly*,
and so see a lot of benefit for my 80k. In the interest of a balanced
account, however, I mention this so that you are aware of it when deciding if
you will use them on a particular project or not.
