IOF Library Documentation

0.8.0a

About

This is the top level page for the iof library. The iof library greatly facilitates formatted output and input with C++ STL streams by providing a replacement or C++ equivalent to C's printf and scanf family of functions.

Sub-pages available are:

Hello World

For formatted output:

#include "iof/fmtr.hpp"

int main()
{
    std::string world("world");
    std::cout << iof::fmtr("Hello %s\n") << world;
}

For formatted input:

#include "iof/fmtr.hpp"

int main()
{
    std::istringstream inData("123_abc");
    int inNumber = 0;
    std::string inWord;
    inData >> iof::fmtr("%s_%s") >> inNumber >> inWord;
}

More Advanced Examples

Format strings really shine when you have to make use of formatting:

std::cout << iof::fmtr("Ground is '%>s' at z=%.2fs\n") 
          << objName << zz;

Without iof you would have to write:

std::cout << "Ground is '" << std::right << objName << "' at z="  
          << std::iof::precision(2) << std::fixed << zz 
          << std::endl;

Here is a common idiom for formatted input:

std::istringstream input("1_2 3\n4_5 6\n7_8 9\nA B C")
iof::fmtr fmtr("%s_%s %s\n");
iof::validity parseOK;

int a, b, c;
// echo everything that is read:
while (input >> fmtr >> a >> b >> c >> ok)
    std::cout << "Read: " << fmtr << a << b << c;

if (!parseOK) 
    std::cout << "Problem at position %s of '%s'" 
              << parseOK.problemPos << parseOK.fmt;

Doing the above input example using raw STL streams would take 100 lines.

But you get much more than just a compact, convenient format representation with iof: you get scoping of stream format, controlled "persistence", format composition, format aggregates, better error status on input operations, etc. And when compared to C's printf/scanf, you get the myriad benefits of STL streams, namely type safety, robustness, etc.

Compatilibity with Printf

The format strings accepted by iof are not 100% compatible with those of printf/scanf, but pretty close. If you absolutely need it, you can append an "s" to the end of every format marker of every format string and that will get you 95% there in 95% of cases. The rest you can probably afford to do by hand or via conversion scripts.

Why not 100% compatibility? Because compared to libraries like iof, printf/scanf are brain-dead. A formatting library can't have its cake and eat it too; i.e., it must give up some power/convenience if it is to be backwards compatible. An example of this: with iof you no longer have to worry about giving type information, since the C++ compiler has it, so all formatting is "%s", rather than "%f" for floats, "%d" for ints, "%uc" for unsigned chars, etc etc.

System Requirements

The extensive test suite was compiled/built with g++ 3.4.2 and VC++.Net 2003 and run on a Windows XP PC. If you can build it with a different compiler (or just different compiler version) please let me know (see Feedback/bug reports/etc).

License

BSD License. Basically you can use for free in any type of application, commercial or non. Details are in the license file in the subversion repository, http://svn.sourceforge.net/viewcvs.cgi/iof/trunk/ioflib/LICENSE_IOF_1_0.txt?view=markup

News

The major revisions can be summarized as follows:

Version Changes from previous version
0.8a Clean-up, error info for formatted input, better docs
0.7 Object-based centering and alignment
0.6 Exception safety, better persistence model
0.5 First release after branch off from the original "coutf" v1.2 library

Feedback/bug reports/etc

Please use the bug reporting, feature request and forum facilities at http://www.sf.net/projects/iof. You may email me (schoenborno) directly, at users.sf.net.

Keywords


Generated on Sun Nov 26 23:04:06 2006 for IOF Library by doxygen 1.5.1-p1
Thanks to SourceForge.net Logo for hosting