senf/Utils/Format.hh

   1 // $Id$
   2 //
   3 // Copyright (C) 2009
   4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
   5 // Competence Center NETwork research (NET), St. Augustin, GERMANY
   6 //     Stefan Bund <g0dil@berlios.de>
   7 //
   8 // This program is free software; you can redistribute it and/or modify
   9 // it under the terms of the GNU General Public License as published by
  10 // the Free Software Foundation; either version 2 of the License, or
  11 // (at your option) any later version.
  12 //
  13 // This program is distributed in the hope that it will be useful,
  14 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  15 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16 // GNU General Public License for more details.
  17 //
  18 // You should have received a copy of the GNU General Public License
  19 // along with this program; if not, write to the
  20 // Free Software Foundation, Inc.,
  21 // 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
  22
  23 /** \file
  24     \brief Format public header */
  25
  26 #ifndef HH_SENF_senf_Utils_Format_
  27 #define HH_SENF_senf_Utils_Format_ 1
  28
  29 // Custom includes
  30 #include <limits>
  31 #include <iostream>
  32 #include <boost/utility/enable_if.hpp>
  33 #include <boost/type_traits/is_signed.hpp>
  34 #include <boost/type_traits/is_unsigned.hpp>
  35
  36 //#include "Format.mpp"
  37 //-/////////////////////////////////////////////////////////////////////////////////////////////////
  38
  39 namespace senf {
  40 namespace format {
  41
  42     /** \defgroup senf_utils_format Formating
  43      */
  44
  45 #ifdef DOXYGEN
  46
  47     /** \brief Format value in engineering representation
  48
  49         The engineering representation is an exponential representation. Exponents however are
  50         always multiples of 3:
  51         <pre>
  52         123.45   -> 123.450e+00
  53         123.45e2 ->  12.345e+03
  54         </pre>
  55
  56         Additionally, an optional delta value may be displayed:
  57         <pre>
  58         123.45+-1.34e+03
  59         </pre>
  60
  61         senf::format::eng supports several formating options:
  62         \par \c std::\c setw
  63             If the width is set >0, the output will be padded internally. If the width is set to
  64             more than the minimal required output width including internal padding, the output is
  65             padded on the left or right depending on the streams \c ajustfield setting (changed
  66             with \c std::left, \c std:;right or \c std::interal). If the \c adjustfield is set to \c
  67             internal, padding is added between the sign and the number.
  68
  69         \par \c std::\c setprecision
  70             The default stream precision is 6. This will schow values with 6 significant digits. The
  71             count includes the number of digits in front of the decimal point.
  72
  73         \par \c std::\c showbase, \c std::\c noshowbase
  74             If the \c showbase flag is set, Instead of writing out the scale exponent in numeric
  75             form, output the corresponding SI prefix.
  76
  77         \par \c std::\c showpos, \c std::\c noshowpos
  78             If the \c showpos flag is set, positive values will have a '+' sign.
  79
  80         \par \c std::\c showpoint, \c std::\c noshowpoint
  81             If the \c showpoint flag is set, the exponent will be output even if it is 0. Otherwise,
  82             if \c width is set, the exponent will be replaced with 4 blanks.
  83
  84         \par \c std::\c uppercase, \c std::\c nouppercase
  85             If the \c uppercase flag is set, the exponent letter will be an uppercase 'E' instead of
  86             'e'. SI prefixes are \e not uppercased, since some SI prefixes differ only in case.
  87
  88         \par \c std::\c setfill
  89             The fill character is honored for the outside padding but \e not for the internal
  90             padding.
  91
  92         \par \c std::\c left, \c std::\c internal, \c std::\c right
  93             The alignment flags specify the external padding but do not affect the internal
  94             padding.
  95
  96         All these flags may optionally be set by calling members of the senf::format::eng() return
  97         value with the same name.
  98
  99         Examples:
 100         \code
 101         os << senf::format::eng(1.23);
 102           -> "1.230"
 103
 104         os << std::setw(1) << senf::format::eng(1.23);
 105           -> "   1.230    "
 106
 107         os << std::setw(25) << std::setprecision(5) << std::showpos << std::uppercase
 108            << std::internal << senf::format::eng(12345,67);
 109           -> "+       12.35+-000.07E+03"
 110
 111         os << std::showbase << senf::format::eng(12345,67);
 112           -> "12.345+-0.067k"
 113
 114         senf::str(senf::format::eng(12.345,67).setw().setprecision(5).showpoint().uppercase())
 115           -> "  12.35+-67.00E+00"
 116         \endcode
 117
 118         \param[in] v value
 119         \param[in] d optional delta
 120
 121         \ingroup senf_utils_format
 122      */
 123     streamable_type eng(float v, float d=NAN);
 124
 125 #else
 126
 127     class eng
 128     {
 129     public:
 130         eng(float v, float d = std::numeric_limits<float>::quiet_NaN());
 131
 132         eng const & setw(unsigned w = 1) const;
 133         eng const & setprecision(unsigned p) const;
 134         eng const & setfill(char c) const;
 135
 136         eng const & showbase() const;
 137         eng const & noshowbase() const;
 138         eng const & showpos() const;
 139         eng const & noshowpos() const;
 140         eng const & showpoint() const;
 141         eng const & noshowpoint() const;
 142         eng const & uppercase() const;
 143         eng const & nouppercase() const;
 144         eng const & left() const;
 145         eng const & internal() const;
 146         eng const & right() const;
 147
 148     private:
 149         float v_;
 150         float d_;
 151
 152         mutable bool haveWidth_;
 153         mutable unsigned width_;
 154         mutable bool havePrecision_;
 155         mutable unsigned precision_;
 156         mutable bool haveFill_;
 157         mutable char fill_;
 158         mutable std::ios_base::fmtflags mask_;
 159         mutable std::ios_base::fmtflags flags_;
 160
 161         friend std::ostream & operator<<(std::ostream & os, eng const & v);
 162
 163     };
 164
 165     std::ostream & operator<<(std::ostream & os, eng const & v);
 166
 167 #endif
 168
 169 #ifdef DOXYGEN
 170
 171     /** \brief Dump integer value with internal representation
 172
 173         senf::format::dumpint() will output a signed or unsigned numeric argument in the following
 174         representations:
 175         \li hexadecimal notation
 176         \li decimal notation
 177         \li byte values interpreted as ASCII characters (in network byte order)
 178
 179         All fields will be padded depending on the size of the type to a byte boundary (e.g. a 32bit
 180         integer type will be padded to 8 hex-digits, 10 decimal digits and 4 ASCII characters)
 181
 182         \ingroup senf_utils_format
 183      */
 184     template <class T>
 185     streamable_type dumpint(T const & v);
 186
 187 #else
 188
 189     template <class T>
 190     std::string dumpint(T const & v,
 191                         typename boost::enable_if<boost::is_signed<T> >::type * = 0);
 192
 193     template <class T>
 194     std::string dumpint(T const & v,
 195                         typename boost::enable_if<boost::is_unsigned<T> >::type * = 0);
 196
 197     template <class T>
 198     std::string dumpint(T const & v,
 199                         typename boost::enable_if<boost::is_signed<typename T::value_type> >::type * = 0);
 200
 201     template <class T>
 202     std::string dumpint(T const & v,
 203                         typename boost::enable_if<boost::is_unsigned<typename T::value_type> >::type * = 0);
 204
 205 #endif
 206
 207     /** \brief Helper class to easily achieve indent levels
 208
 209         This class helps to achieve indent levels across function calls. Every instance
 210         increases the static indent level. On destruction the level is decreased to the level
 211         before the instance.
 212         The following example illustrates the use of this class:
 213         \code
 214             void f1() {
 215                 senf::format::IndentHelper indent;
 216                 std::cout << indent << "f1\n";
 217             }
 218             void f2() {
 219                 senf::format::IndentHelper indent;
 220                 std::cout << indent << "f2 begin\n";
 221                 f1();
 222                 std::cout << indent << "f2 end\n";
 223             }
 224             f2()
 225         \endcode
 226         Output:
 227         <pre>
 228             f2 begin
 229               f1
 230             f2 end
 231         </pre>
 232         Here <tt>f1()</tt> and <tt>f2()</tt> don't need to know to current indent level,
 233         they just increase the level by instantiating IndentHelper.
 234
 235         \ingroup senf_utils_format
 236      */
 237     class IndentHelper
 238     {
 239         static unsigned int static_level;
 240         unsigned int instance_level;
 241     public:
 242
 243         IndentHelper();                 ///< Construct new IndentHelper instance
 244                                         /**< The static indent level is increased by one. */
 245         ~IndentHelper();                ///< Destruct IndentHelper instance
 246                                         /**< The static indent level will be decreased to the
 247                                              level before the instance. */
 248         void increase();                ///< Increase the indent level
 249                                         /**< The indent level of the instance is increases by one. */
 250         unsigned int level() const;     ///< return the current indent level
 251     };
 252
 253     /** \brief Output indent to given ostream
 254         \related IndentHelper
 255      */
 256     std::ostream & operator<<(std::ostream & os, IndentHelper const & indent);
 257
 258 }}
 259
 260 //-/////////////////////////////////////////////////////////////////////////////////////////////////
 261 #include "Format.cci"
 262 //#include "Format.ct"
 263 #include "Format.cti"
 264 #endif
 265
 266 \f
 267 // Local Variables:
 268 // mode: c++
 269 // fill-column: 100
 270 // comment-column: 40
 271 // c-file-style: "senf"
 272 // indent-tabs-mode: nil
 273 // ispell-local-dictionary: "american"
 274 // compile-command: "scons -u test"
 275 // End: