Skip to content

Latest commit

 

History

History
178 lines (122 loc) · 6.15 KB

FAQ.md

File metadata and controls

178 lines (122 loc) · 6.15 KB
Raw

FastFormat - FAQ

Updated: 11th December 2010

The FAQ list is under (constant) development. If you post a question on the Tutorials forum (https://sourceforge.net/forum/forum.php?forum_id=828687) it will be used to create one.

FAQs:

Q1: "How do I build FastFormat?"

A1: There are two ways:

1. Build from the command-line
2. Build from the Visual Studio IDE

Method 1 is prefered, because FastFormat comes with a comprehensive set of makefiles for all supported compilers, whereas it (currently) comes with project files comprehensive only for Visual Studio '98 (aka Visual C++ 6), along with an incomplete set for Visual Studio 2005 and 2008. (FYI: this is solely due to a delay in finalising the project file generator to produce all version of Visual C++ project files, along with Borland, XCode, and more. It should not be interpreted to mean that FastFormat works only with the anachronistic Visual C++ 6.)

To build from the command-line you need to do the following:

A. Download and extract the latest FastFormat and STLSoft distributions,
   according to the instructions given in FAQ #2
B. Open a console/command-box and change directory to reside in the
   $FASTFORMAT_ROOT/build directory. For example, if you're on UNIX and
   have installed FastFormat to /3pty/fastformat-0.7.1, then cd to 
   /3pty/fastformat-0.7.1/build.
C. Next cd to the directory reflecting your compiler. For example, if
   you're using Visual C++ 9 for x64, you would cd to 'vc9.x64'
D. Finally, build the library, using the appropriate make command for
   your compiler (make for GCC, nmake for VC++, etc.). We suggest you
   make and test, by the command

     > make build test

   Alternatively, if you want to build the FastFormat core libraries and
   nothing else, issue the command

     > make build.libs.core

Q2: "How do I install FastFormat?"

A2: There are four steps: 1. Download the latest distribution of FastFormat, from http://fastformat.org/ 2. Extract it to a directory of your choice, e.g c:\3pty\fastformat-0.7.1 3. Define an environment variable FASTFORMAT_ROOT, whose value is the directory in which you unzipped it, e.g. FASTFORMAT_ROOT=c:\3pty\fastformat-0.7.1 4. Download the latest distribution of STLSoft, from http://stlsoft.org/ 5. Extract it to a directory of your choice, e.g c:\3pty\stlsoft-1.9.104 6. Define an environment variable STLSOFT, whose value is the directory in which you unzipped it, e.g. STLSOFT=c:\3pty\stlsoft-1.9.104

Q3: "How do I use FastFormat?"

A3: Assuming you've built and installed it (as per instructions in FAQ #1 and FAQ #2):

In your IDE settings, add the include directories $(FASTFORMAT_ROOT)/include and $(STLSOFT)/include, OR in your makefiles, add the include directories: * -I$FASTFORMAT_ROOT/include and -I$STLSOFT/include (if you're on UNIX), OR * -I%FASTFORMAT_ROOT%/include and -I%STLSOFT%/include (if you're on Windows)

Then you simply #include the headers you want, and use the components. For example, to use fstream without Abstraction Dissonance (see A4 & A5), you could do the following:

#include <fastformat/fastformat.hpp>

#include <iostream>
#include <string>

int main()
{
  char         arg0[] = "abc";
  std::string  arg1   = "def";
  int          arg3   = -101;

  std::string  result;

  // format to a string
  fastformat::fmt(result, "Arguments in arbitrary order, such as {2}, {0} and {1}", arg0, arg1, arg2);

  // format to cout, with a newline
  fastformat::fmtln(std::cout, "Arguments in arbitrary order, such as {2}, {0} and {1}", arg0, arg1, arg2);

  return 0;
}

Q4: "How does FastFormat work?"

A4: It defines a Type Tunnel whose interface is N-ary Generated Function Templates, and whose tunnel mechanism is Shims.

Q5: "What is a 'Type Tunnel', what are 'N-ary Generated Function Templates', and what are 'Shims' ?"

A5: Those things are all explained in in detail in the forthcoming book "Breaking Up The Monolith: Advanced C++ Design Without Compromise". See http://breakingupthemonolith.com/glossary.html#type-tunnel for a start on finding out.

Q6: "Is it possible to set the width, precision, alignment, etc. of [floating point] numbers in FastFormat?"

A6: As of version 0.3.1 beta 4 (released 9th March 2009) it is. You can use the fastformat::real() inserter function(s) suite, as shown in the test.component.inserter.real test program.

Q7: "Why have both "Write" and "Format" APIs?"

A7: It's simply because there are two ways of doing formatted output: concatenation-based (a la FastFormat.Write, IOStreams) and replacement-based (a la FastFormat.Format, Boost.Format, Streams)

Each has their pros and cons:

  • FastFormat.Write is usually faster, and is 100% robust - it is impossible to compile defective code using it!
  • FastFormat.Format is more flexible, only uses arguments once, and supports I18N/L10N

By supporting both, you get to choose whichever is more appropriate. None of the other major formatting libraries allow this (as well as being less robust, less flexible, and a lot less efficient.)

You can read more about the issues in the series of articles in the ACCU's Overload magazine. The first instalment is now online at http://accu.org/index.php/journals/1539

Q8: "What's the fastest way to convert an integer to a string?"

A8: The answer to this is quite involved, so the best thing is to consult the publication lists on http://synesis.com.au/publications.html and http://fastformat.org/

However, in brief, you should consider the following:

  • prefer write() over fmt() (and writeln() over fmtln())
  • consider using the char_buffer_sink or c_string_sink instead of writing to a (std::string / std::wstring) instance
  • maybe using stlsoft::integer_to_string() directly, and skipping FastFormat altogether

Q9: "How do I verify the performance claims made on the FastFormat website, and in the articles?"

A9: Type "make test.performance"

=============================== End of file ================================