HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
UT_Format.h File Reference

Type-safe formatting, modeled on the Python str.format function. More...

#include "UT_API.h"
#include "UT_Assert.h"
#include "UT_NonCopyable.h"
#include <SYS/SYS_Types.h>
#include <initializer_list>
#include <iosfwd>
#include <limits>
#include <string>
#include <type_traits>
+ Include dependency graph for UT_Format.h:
+ This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes

class  UT_Array< T >
 
struct  UT::Format::CustomWriter
 
struct  UT::Format::Writer
 
struct  UT::Format::Impl::TrueType< typename >
 
struct  UT::Format::HasFormat< T >
 
class  UT::Format::ArgValue
 
struct  UT::Format::ArgValue::SizedString
 
struct  UT::Format::ArgValue::Custom
 
class  UT::Format::Formatter
 

Namespaces

 UT
 
 UT::Format
 
 UT::Format::Impl
 

Macros

#define UT_ENABLE_IF(T)   typename std::enable_if<T>::type * = nullptr
 
#define UT_HAS_FMT(T)   HasFormat<T>::value
 
#define UT_REMOVE_PTR(T)   typename std::remove_pointer<T>::type
 
#define UT_IS_PTR(T)   std::is_pointer<T>::value
 
#define UT_IS_ENUM(T)   std::is_enum<T>::value
 

Functions

UT_API size_t UT::Format::format (FILE *file, const char *format, std::initializer_list< ArgValue > args)
 
UT_API size_t UT::Format::format (std::ostream &, const char *format, std::initializer_list< ArgValue > args)
 
UT_API size_t UT::Format::format (char *, size_t, const char *format, std::initializer_list< ArgValue > args)
 
UT_API size_t UT::Format::printf (FILE *file, const char *format, std::initializer_list< ArgValue > args)
 
UT_API size_t UT::Format::printf (std::ostream &, const char *format, std::initializer_list< ArgValue > args)
 
UT_API size_t UT::Format::printf (char *, size_t, const char *format, std::initializer_list< ArgValue > args)
 
Standalone formatting functions
template<typename... Args>
size_t UTformat (FILE *file, const char *format, const Args &...args)
 
template<typename... Args>
size_t UTformat (const char *format, const Args &...args)
 
template<typename... Args>
size_t UTformat (std::ostream &os, const char *format, const Args &...args)
 
template<typename... Args>
size_t UTformat (char *buffer, size_t buffer_size, const char *format, const Args &...args)
 
Standalone printf-like functions
template<typename... Args>
size_t UTprintf (FILE *file, const char *format, const Args &...args)
 
template<typename... Args>
size_t UTprintf (const char *format, const Args &...args)
 
template<typename... Args>
size_t UTprintf (std::ostream &os, const char *format, const Args &...args)
 
template<typename... Args>
size_t UTprintf (char *buffer, size_t buffer_size, const char *format, const Args &...args)
 

Detailed Description

Type-safe formatting, modeled on the Python str.format function.

This formatter supports a sub-set of the Python format syntax. Notably, only indexed arguments are supported for now, not named ones.

Like with the printf() formatting, the format string contains replacement fields that will be substituted by the textual representation of the arguments to the various format functions. The replacement fields for this formatter are surrounded by curly braces {}, rather than prefixed with a %.

Note the string {{ or }} will result in a single { or } being output.

Format Grammar

The grammar for the replacement field is as follows:

{[<index>][:<spec>]}

The <index> is an optional integer value, which refers to the position of the argument after the format string. If the <index> is omitted for all replacement fields, then they are automatically substituted with 0, 1, 2, ... It is not permitted to mix indexed and non-indexed.

If a colon separator is found, the string after that is interpreted as a formatting specification. The grammar for the <spec> field is as follows:

[[<fill>]<align>][<sign>][#][,][0][<width>][.<precision>][<type>]

Where:

  • <fill> is the fill character to use when the width of the field is greater than the length of the argument value being printed.
  • <align> is a single character code which sets the alignment of the value within the field:
    • <: The field is left-aligned. This is the default for non-numeric values.
    • >: The field is right-aligned. This is the default for numeric values.
    • ^: The field is center-aligned.
    • =: The field is number aligned. This is the same as right-aligned, except the fill value is inserted between the sign indicator and the numeric value. This alignment is only available for numeric values.
  • <sign> is a single character that specifies how the sign is printed for numeric values:
    • +: Always print a sign, whether positive or negative.
    • -: Only print a sign when the number is negative.
    • <space>: Use a leading space on positive numbers, minus sign for negative.
  • The '#' option is only available for binary, octal or hexadecimal output. It indicates that they should be prefixed with '0b', '0' and '0x', respectively.
  • The ',' option will add digit grouping to numerical outputs. For float

Definition in file UT_Format.h.

Macro Definition Documentation

#define UT_ENABLE_IF (   T)    typename std::enable_if<T>::type * = nullptr

Definition at line 320 of file UT_Format.h.

#define UT_HAS_FMT (   T)    HasFormat<T>::value

Definition at line 321 of file UT_Format.h.

#define UT_IS_ENUM (   T)    std::is_enum<T>::value

Definition at line 324 of file UT_Format.h.

#define UT_IS_PTR (   T)    std::is_pointer<T>::value

Definition at line 323 of file UT_Format.h.

#define UT_REMOVE_PTR (   T)    typename std::remove_pointer<T>::type

Definition at line 322 of file UT_Format.h.

Function Documentation

template<typename... Args>
size_t UTformat ( FILE *  file,
const char *  format,
const Args &...  args 
)

Takes a formatting string and a set of arguments and writes out the formatted string to the FILE pointer.

Parameters
fileThe FILE pointer to write to. The FILE must be opened in write or append mode.
formatThe formatting codes, as defined in Format Grammar.
argsThe arguments to the formatting.
Returns
The number of bytes successfully written out.
Examples:
IMG/TIL_NullFilter.C.

Definition at line 665 of file UT_Format.h.

template<typename... Args>
size_t UTformat ( const char *  format,
const Args &...  args 
)

Takes a formatting string and a set of arguments and writes out the formatted string to stdout.

Parameters
formatThe formatting codes, as defined in Format Grammar.
argsThe arguments to the formatting.
Returns
The number of bytes successfully written out.

Definition at line 676 of file UT_Format.h.

template<typename... Args>
size_t UTformat ( std::ostream &  os,
const char *  format,
const Args &...  args 
)

Takes a formatting string and a set of arguments and writes out the formatted string to the output stream object.

Parameters
osThe output stream to write to.
formatThe formatting codes, as defined in Format Grammar.
argsThe arguments to the formatting.
Returns
The number of bytes successfully written out.

Definition at line 688 of file UT_Format.h.

template<typename... Args>
size_t UTformat ( char *  buffer,
size_t  buffer_size,
const char *  format,
const Args &...  args 
)

Takes a formatting string and a set of arguments and writes out the formatted string into the buffer provided. If buffer is nullptr, then nothing is written out, but the number of bytes needed to store the entire formatted string is returned. A termination byte is not written out to the buffer. If termination is required, the caller must take care of it.

Parameters
bufferThe character buffer to write the formatted string to.
buffer_sizeThe size of the character buffer.
formatThe formatting codes, as defined in Format Grammar.
argsThe arguments to the formatting.
Returns
The number of bytes successfully written out.

Definition at line 705 of file UT_Format.h.

template<typename... Args>
size_t UTprintf ( FILE *  file,
const char *  format,
const Args &...  args 
)

Takes a formatting string and a set of arguments and writes out the formatted string to the FILE pointer.

Parameters
fileThe FILE pointer to write to. The FILE must be opened in write or append mode.
formatThe formatting codes, as defined in Printf Grammar.
argsThe arguments to the formatting.
Returns
The number of bytes successfully written out.

Definition at line 724 of file UT_Format.h.

template<typename... Args>
size_t UTprintf ( const char *  format,
const Args &...  args 
)

Takes a formatting string and a set of arguments and writes out the formatted string to stdout.

Parameters
formatThe formatting codes, as defined in Printf Grammar.
argsThe arguments to the formatting.
Returns
The number of bytes successfully written out.

Definition at line 735 of file UT_Format.h.

template<typename... Args>
size_t UTprintf ( std::ostream &  os,
const char *  format,
const Args &...  args 
)

Takes a formatting string and a set of arguments and writes out the formatted string to the output stream object.

Parameters
osThe output stream to write to.
formatThe formatting codes, as defined in Printf Grammar.
argsThe arguments to the formatting.
Returns
The number of bytes successfully written out.

Definition at line 747 of file UT_Format.h.

template<typename... Args>
size_t UTprintf ( char *  buffer,
size_t  buffer_size,
const char *  format,
const Args &...  args 
)

Takes a formatting string and a set of arguments and writes out the formatted string into the buffer provided. If buffer is nullptr, then nothing is written out, but the number of bytes needed to store the entire formatted string is returned. A termination byte is not written out to the buffer. If termination is required, the caller must take care of it.

Parameters
bufferThe character buffer to write the formatted string to.
buffer_sizeThe size of the character buffer.
formatThe formatting codes, as defined in Printf Grammar.
argsThe arguments to the formatting.
Returns
The number of bytes successfully written out.

Definition at line 764 of file UT_Format.h.