CLX C++ Libraries - format
Author: clown

CLX C++ Libraries
Home >> format

# Declarations

    template <
        class CharT,
        class Traits = std::char_traits<CharT>
    >
    class basic_format;

    typedef basic_format<char> format;
    #ifdef CLX_USE_WCHAR
    typedef basic_tormat<wchar_t> wformat;
    #endif

    template <class Ch, class Tr>
    std::basic_string<Ch, Tr> str(const basic_format<Ch, Tr>& f);

# Overview

format は，C標準ライブラリにおける printf()，sprintf(), fprintf() のような書式付き出力を行うためのクラスです．printf() などとは異なり， format には出力する順番を指定することはできません．format は， 書式文字列を基にして std::ostream に対してマニピュレータを設定することで， printf() などと同じ動きをするように実装しています．

書式文字列には，通常文字と変換指定が存在します．通常文字とは % 以外の文字を表し， 出力ストリームにそのままコピーされます．一方，各変換指定は文字 % で始まり， 変換指定子で終わります．% と変換指定子の間には，0 個以上のフラグ，最小フィールド幅， 精度を（この順序で）記述することができます．

## フラグ文字

#
  x,X 変換の場合先頭に "0x"，o 変換の場合先頭に "0" が付加されます．
0
  値をゼロで埋めます．0 と - が両方とも指定された場合は， 0 フラグは無視されます．
-
  値をフィールド境界で左揃えにします（デフォルトは右揃え）．
' '
  （1個の半角スペース）数字の前に空白が置かれます．
+
  符号付き変換によって出力される数字の前に，常に符号（+ か -） が置かれます．

## フィールド幅

最小のフィールド幅を指定する 10 進数の数字文字列（文字列の最初の文字はゼロ以外） です．本項目は，オプションです．変換された値の文字数がフィールド長よりも少ない場合， フィールドの左側を指定された文字（半角スペース，またゼロ）で埋めます．

## 精度

オプションである精度は，ピリオド (".") とそれに続く 10 進数という形式で指定します（10 進数はオプション）．精度として "." だけが指定された場合，精度はゼロと見なされます．

## 変換指定子

適用される変換の型を指定する文字．現状，"oxX" 以外の指定子には， 意味がありません．ここで指定した型と実際の引数の型が異なる場合は， 引数の型が優先されます．

d,i
  int 引数を符号付き 10 進表記に変換します．
o,u,x,X
  unsigned int 引数を符号なし 8 進数 (o)，符号なし 10 進数 (u)， 符号なし 16 進数 (x,X) に変換します．x 変換では abcdef が使用され，X 変換では ABCDEF が使用されます．
e,E
  double 引数を丸めて [-]d.ddde±xx の形に変換します． 小数点の前には一桁の数字があり，小数点以下の桁数は精度で指定された桁数になります． 精度は指定されなかった場合は 6 桁と見なされます．E 変換では，指数を表現するときに E が使用されます．
f,F
  double 引数を丸めて [-]ddd.ddd の形に変換します．小数点の後の桁数は， 精度で指定された値となります．制度が指定されなかった場合は 6 桁と見なされます．
g,G
  double 引数を f か e（G 変換の場合は F か E）の形式に変換します． 精度は表示する桁数を指定します．精度が指定されない場合は，6 桁と見なされます．
c
  unsigned char に変換して，その結果に対応する文字を出力します．
s
  const char* 型または std::string を引数に取り，その文字列を出力します．

# Example

example_format.cpp

    #include <iostream>
    #include <string>
    #include <cstdio>
    #include "clx/format.h"

    int main(int argc, char* argv[]) {
        double pi = 3.141592684;
        std::string hello = "Hello, world. This is a test program";
        std::string test = "Output pi with two kinds of format";
        std::string fmt = "%s.\n%s: %#+10.7f, %.5e.";

        std::cout << "Output by using format class." << std::endl;
        std::cout << "---" << std::endl;
        std::cout << clx::format(fmt) % hello % test % pi % pi << std::endl;
        std::cout << std::endl;

        // compared with the printf() function
        printf("Output by using printf function\n");
        printf("---\n");
        printf(fmt.c_str(), hello.c_str(), test.c_str(), pi, pi);

        std::cout << "Test of str() function" << std::endl;
        std::cout << "---" << std::endl;
        std::string dest = clx::str(clx::format(fmt) % hello % test % pi % pi);
        std::cout << dest << std::endl;

        return 0;
    }

    Result
    Output by using format class.
    ---
    Hello, world. This is a test program.
    Output pi with two kinds of format: +3.1415927, 3.14159e+00.

    Output by using printf function
    ---
    Hello, world. This is a test program.
    Output pi with two kinds of format: +3.1415927, 3.14159e+00.

    Test of str() function
    ---
    Hello, world. This is a test program.
    Output pi with two kinds of format: +3.1415927, 3.14159e+00.

# Template Parameters

CharT
  文字の型を指定します．
Traits
  文字列を扱うためのtraitsを指定します．デフォルト値は， std::char_traits<CharT>．

# Related Types

    typedef CharT char_type;
    typedef unsigned int size_type;
    typedef typename std::basic_string<CharT, Traits> string_type;

# Construction and Member Functions

    basic_format()
    explicit basic_format(const char_type* fmt);
    explicit basic_format(const string_type& fmt);

    template <class ValueT>
    basic_format& operator%(const ValueT& x);

    string_type str() const;

    template <class Ch, class Tr>
    friend std::basic_ostream<Ch, Tr>& operator<<(
        std::basic_ostream<Ch, Tr>& sout, const basic_format<Ch, Tr>& f);

# References

1. Manpage of PRINTF
2. Boost C++ Libraries - The Boost Format library