source/utility.hxx

   1 /**
   2  * @file
   3  *
   4  * Declarations of auxiliary formatting functions intended
   5  * for internal use only.
   6  */
   7
   8 #ifndef LIBSEX_UTILITY_HXX
   9 #define LIBSEX_UTILITY_HXX
  10
  11 #include <source/Exception.hxx>
  12
  13 #include <cstdarg> // variadic argument fun
  14 #include <cstdio>  // size_t
  15
  16 namespace libsex
  17 {
  18         /**
  19          * Formats a message and writes it into @a buffer.
  20          *
  21          * It is guaranteed that not more than @a length
  22          * characters are written to @a buffer.
  23          *
  24          * @param buffer  String to be filled.
  25          * @param length  Size of buffer.
  26          * @param file    Filename in which the error occured.
  27          * @param line    Line number in which the error occured.
  28          * @param message printf formatstring template
  29          * @param ap      variadic argument list, holds parameters
  30          *                to be used when formatting (vsnprintf()).
  31          * @return true if buffer was large enough, false otherwise
  32          */
  33         bool vformat(
  34                 char* const buffer,
  35                 size_t length,
  36                 const char* const file,
  37                 unsigned short line,
  38                 const char* const message,
  39                 va_list ap) throw();
  40
  41         /// @see vformat()
  42         bool format(
  43                 char* const buffer,
  44                 size_t length,
  45                 const char* const file,
  46                 unsigned short line,
  47                 const char* const message,
  48                 ...) throw();
  49
  50         /**
  51          * Instanciates T with properly formatted message.
  52          *
  53          * T is supposed to have a static const char* TEMPLATE
  54          * field, which will be used as formatstring for vformat().
  55          *
  56          * @param file To be passed on to format().
  57          * @param line To be passed on to format().
  58          * @param ...  Passed to vformat() (sprintf() like).
  59          * @return Instance of T.
  60          */
  61         template <typename T>
  62         T formatted(
  63                 const char* const file,
  64                 unsigned short line,
  65                 ...) throw();
  66
  67         /**
  68          * Instanciates T with properly formatted message and
  69          * a previous exception.
  70          *
  71          * @see formatted()
  72          */
  73         template <typename T>
  74         T formatted(
  75                 const Exception& previous,
  76                 const char* const file,
  77                 unsigned short line,
  78                 ...) throw();
  79 }
  80
  81 #include "utility.ixx"
  82
  83 #endif