kbe/src/lib/dependencies/fmt/doc/html/api.html
The {fmt} library API consists of the following parts:
std::ostream supportprintf formattingAll functions and types provided by the library reside in namespace fmt and macros have prefix FMT_ or fmt.
fmt/core.h defines the core API which provides argument handling facilities and a lightweight subset of formatting functions.
The following functions use format string syntax imilar to that of Python’s str.format. They take format_str and args as arguments.
format_str is a format string that contains literal text and replacement fields surrounded by braces {}. The fields are replaced with formatted arguments in the resulting string.
args is an argument list representing objects to be formatted.
template <typename String, typename... Args>std::basic_string<typename internal::format_string_traits<String>::char_type> fmt::``format(const String &format_str, const Args&... args)¶
Formats arguments and returns the result as a string.
Example :
#include\<fmt/core.h\>std::stringmessage=fmt::format("The answer is {}",42);
template <typename String, typename Char = typename internal::format_string_traits<String>::char_type>std::basic_string<Char> fmt::``vformat(const String &format_str, basic_format_args<typename buffer_context<Char>::type> args)¶template <typename... Args>void fmt::``print(string_view format_str, const Args&... args)¶
Prints formatted data to stdout.
Example :
fmt::print("Elapsed time: {0:.2f} seconds",1.23);
void fmt::``vprint(string_view format_str, format_args args)¶template <typename... Args>void fmt::``print(std::FILE *f, string_view format_str, const Args&... args)¶
Prints formatted data to the file f.
Example :
fmt::print(stderr,"Don't {}!","panic");
void fmt::``vprint(std::FILE *f, string_view format_str, format_args args)¶template <typename... Args>void fmt::``print(std::FILE *f, wstring_view format_str, const Args&... args)¶
Prints formatted data to the file f which should be in wide-oriented mode set via fwide(f, 1) or _setmode(_fileno(f), _O_U8TEXT) on Windows.
void fmt::``vprint(std::FILE *f, wstring_view format_str, wformat_args args)¶
template <typename T>internal::named_arg<T, char> fmt::``arg(string_view name, const T &arg)¶
Returns a named argument to be used in a formatting function.
Example :
fmt::print("Elapsed time: {s:.2f} seconds",fmt::arg("s",1.23));
template <typename Context, typename ... Args>format_arg_store<Context, Args...> fmt::``make_format_args(const Args&... args)¶
Constructs an format_arg_store object that contains references to arguments and can be implicitly converted to format_args. Context can be omitted in which case it defaults to context.
template <typename Context, typename ... Args>class fmt::``format_arg_store¶
An array of references to arguments. It can be implicitly converted into basic_format_args for passing into type-erased formatting functions such as vformat().
template <typename Context>class fmt::``basic_format_args¶
Formatting arguments.
Public Functions
template <typename... Args>basic_format_args(const format_arg_store<Context, Args...> &store)¶
Constructs a basic_format_args object from format_arg_store.
basic_format_args(const format_arg *args, size_type count)¶
Constructs a basic_format_args object from a dynamic set of arguments.
format_arg get(size_type index) const¶
Returns the argument at specified index.
struct fmt::``format_args¶
An alias to basic_format_args<context>.
Inherits from [fmt::basic_format_args< format_context >](#formatclassfmt_1_1basic format args)
template <typename Context>class fmt::``basic_format_arg¶
template <typename Char>class fmt::``basic_string_view¶
An implementation of std::basic_string_view for pre-C++17.
It provides a subset of the API. fmt::basic_string_view is used for format strings even if std::string_view is available to prevent issues when a library is compiled with a different -std option than the client code (which is not recommended).
Public Functions
basic_string_view(const Char *s, size_t count)¶
Constructs a string reference object from a C string and a size.
basic_string_view(const Char *s)¶
Constructs a string reference object from a C string computing the size with std::char_traits<Char>::length.
template <typename Alloc>basic_string_view(const std::basic_string<Char, Alloc> &s)¶
Constructs a string reference from a std::basic_string object.
const Char *data() const¶
Returns a pointer to the string data.
size_t size() const¶
Returns the string size.
typedef basic_string_view<char> fmt::``string_view¶typedef basic_string_view<wchar_t> fmt::``wstring_view¶
fmt/format.h defines the full format API providing compile-time format string checks, output iterator and user-defined type support.
fmt(s)¶
Constructs a compile-time format string. This macro is disabled by default to prevent potential name collisions. To enable it define FMT_STRING_ALIAS to 1 before including fmt/format.h.
Example :
#define FMT\_STRING\_ALIAS 1#include\<fmt/format.h\>// A compile-time error because 'd' is an invalid specifier for strings.std::strings=format(fmt("{:d}"),"foo");
To make a user-defined type formattable, specialize the formatter<T> struct template and implement parse and format methods:
#include\<fmt/format.h\>structpoint{doublex,y;};namespacefmt{template\<\>structformatter\<point\>{template\<typenameParseContext\>constexprautoparse(ParseContext&ctx){returnctx.begin();}template\<typenameFormatContext\>autoformat(constpoint&p,FormatContext&ctx){returnformat\_to(ctx.begin(),"({:.1f}, {:.1f})",p.x,p.y);}};}
Then you can pass objects of type point to any formatting function:
pointp={1,2};std::strings=fmt::format("{}",p);// s == "(1.0, 2.0)"
In the example above the formatter<point>::parse function ignores the contents of the format string referred to by ctx.begin() so the object will always be formatted in the same way. See formatter<tm>::parse in fmt/time.h for an advanced example of how to parse the format string and customize the formatted output.
You can also reuse existing formatters, for example:
enumclasscolor{red,green,blue};template\<\>structfmt::formatter\<color\>:formatter\<string\_view\>{// parse is inherited from formatter\<string\_view\>.template\<typenameFormatContext\>autoformat(colorc,FormatContext&ctx){string\_viewname="unknown";switch(c){casecolor::red:name="red";break;casecolor::green:name="green";break;casecolor::blue:name="blue";break;}returnformatter\<string\_view\>::format(name,ctx);}};
This section shows how to define a custom format function for a user-defined type. The next section describes how to get fmt to use a conventional stream output operator<< when one is defined for a user-defined type.
template <typename OutputIt, typename... Args>OutputIt fmt::``format_to(OutputIt out, string_view format_str, const Args&... args)¶
Formats arguments, writes the result to the output iterator out and returns the iterator past the end of the output range.
Example :
std::vector\<char\>out;fmt::format\_to(std::back\_inserter(out),"{}",42);
template <typename OutputIt, typename... Args>format_to_n_result<OutputIt> fmt::``format_to_n(OutputIt out, std::size_t n, string_view format_str, const Args&... args)¶
Formats arguments, writes up to n characters of the result to the output iterator out and returns the total output size and the iterator past the end of the output range.
template <typename OutputIt>struct fmt::``format_to_n_result¶
Public Members
OutputIt out¶
Iterator past the end of the output range.
std::size_t size¶
Total (not truncated) output size.
The following user-defined literals are defined in fmt/format.h.
Warning
doxygenfunction: Cannot find function “operator”“_format” in doxygen xml output for project “format” from directory: /Users/viz/work/fmt/support/build/fmt/doc/doxyxml
Warning
doxygenfunction: Cannot find function “operator”“_a” in doxygen xml output for project “format” from directory: /Users/viz/work/fmt/support/build/fmt/doc/doxyxml
template <typename... Args>std::size_t fmt::``formatted_size(string_view format_str, const Args&... args)¶
Returns the number of characters in the output of format(format_str, args...).
template <typename T>std::string fmt::``to_string(const T &value)¶
Converts value to std::string using the default format for type T. It doesn’t support user-defined types with custom formatters.
Example :
#include\<fmt/format.h\>std::stringanswer=fmt::to\_string(42);
template <typename T>std::wstring fmt::``to_wstring(const T &value)¶
Converts value to std::wstring using the default format for type T.
template <typename T, std::size_t SIZE = inline_buffer_size, typename Allocator = std::allocator<T>>class fmt::``basic_memory_buffer¶
A dynamically growing memory buffer for trivially copyable/constructible types with the first SIZE elements stored in the object itself.
You can use one of the following typedefs for common character types:
| Type | Definition |
|---|---|
| memory_buffer | basic_memory_buffer<char> |
| wmemory_buffer | basic_memory_buffer<wchar_t> |
Example :
fmt::memory\_bufferout;format\_to(out,"The answer is {}.",42);
This will write the following output to the out object:
The answer is 42.
The output can be converted to an std::string with to_string(out).
Inherits from Allocator, fmt::internal::basic_buffer< T >
Public Functions
basic_memory_buffer(basic_memory_buffer &&other)¶
Constructs a fmt::basic_memory_buffer object moving the content of the other object to it.
basic_memory_buffer &operator=(basic_memory_buffer &&other)¶
Moves the content of the other basic_memory_buffer object to this one.
fmt does not use errno to communicate errors to the user, but it may call system functions which set errno. Users should not make any assumptions about the value of errno being preserved by library functions.
class fmt::``system_error¶
An error returned by an operating system or a language runtime, for example a file opening error.
Inherits from runtime_error
Subclassed by fmt::windows_error
Public Functions
template <typename... Args>system_error(int error_code, string_view message, const Args&... args)¶
Constructs a fmt::system_error object with a description formatted with fmt::format_system_error(). message and additional arguments passed into the constructor are formatted similarly to fmt::format().
Example :
// This throws a system\_error with the description// cannot open file 'madeup': No such file or directory// or similar (system message may vary).constchar\*filename="madeup";std::FILE\*file=std::fopen(filename,"r");if(!file)throwfmt::system\_error(errno,"cannot open file '{}'",filename);
void fmt::``format_system_error(internal::buffer &out, int error_code, fmt::string_view message)¶
Formats an error returned by an operating system or a language runtime, for example a file opening error, and writes it to out in the following form:
_\<message\>_:_\_
where <message> is the passed message and __ is the system message corresponding to the error code. error_code is a system error code as given by errno. If error_code is not a valid error code such as -1, the system message may look like “Unknown error -1” and is platform-dependent.
class fmt::``windows_error¶
A Windows error.
Inherits from fmt::system_error
Public Functions
template <typename... Args>windows_error(int error_code, string_view message, const Args&... args)¶
Constructs a fmt::windows_error object with the description of the form
_\<message\>_:_\_
where <message> is the formatted message and __ is the system message corresponding to the error code. error_code is a Windows error code as given by GetLastError. If error_code is not a valid error code such as -1, the system message will look like “error -1”.
Example :
// This throws a windows\_error with the description// cannot open file 'madeup': The system cannot find the file specified.// or similar (system message may vary).constchar\*filename="madeup";LPOFSTRUCTof=LPOFSTRUCT();HFILEfile=OpenFile(filename,&of,OF\_READ);if(file==HFILE\_ERROR){throwfmt::windows\_error(GetLastError(),"cannot open file '{}'",filename);}
The {fmt} library supports custom dynamic memory allocators. A custom allocator class can be specified as a template argument to fmt::basic_memory_buffer:
usingcustom\_memory\_buffer=fmt::basic\_memory\_buffer\<char,fmt::inline\_buffer\_size,custom\_allocator\>;
It is also possible to write a formatting function that uses a custom allocator:
usingcustom\_string=std::basic\_string\<char,std::char\_traits\<char\>,custom\_allocator\>;custom\_stringvformat(custom\_allocatoralloc,fmt::string\_viewformat\_str,fmt::format\_argsargs){custom\_memory\_bufferbuf(alloc);fmt::vformat\_to(buf,format\_str,args);returncustom\_string(buf.data(),buf.size(),alloc);}template\<typename...Args\>inlinecustom\_stringformat(custom\_allocatoralloc,fmt::string\_viewformat\_str,constArgs&...args){returnvformat(alloc,format\_str,fmt::make\_format\_args(args...));}
The allocator will be used for the output container only. If you are using named arguments, the container that stores pointers to them will be allocated using the default allocator. Also floating-point formatting falls back on sprintf which may do allocations.
It is possible to change the way arguments are formatted by providing a custom argument formatter class:
usingarg\_formatter=fmt::arg\_formatter\<fmt::back\_insert\_range\<fmt::internal::buffer\>\>;// A custom argument formatter that formats negative integers as unsigned// with the ``x`` format specifier.classcustom\_arg\_formatter:publicarg\_formatter{public:custom\_arg\_formatter(fmt::format\_context&ctx,fmt::format\_specs&spec):arg\_formatter(ctx,spec){}usingarg\_formatter::operator();autooperator()(intvalue){if(spec().type()=='x')return(\*this)(static\_cast\<unsigned\>(value));// convert to unsigned and formatreturnarg\_formatter::operator()(value);}};std::stringcustom\_vformat(fmt::string\_viewformat\_str,fmt::format\_argsargs){fmt::memory\_bufferbuffer;// Pass custom argument formatter as a template arg to vformat\_to.fmt::vformat\_to\<custom\_arg\_formatter\>(buffer,format\_str,args);returnfmt::to\_string(buffer);}template\<typename...Args\>inlinestd::stringcustom\_format(fmt::string\_viewformat\_str,constArgs&...args){returncustom\_vformat(format\_str,fmt::make\_format\_args(args...));}std::strings=custom\_format("{:x}",-42);// s == "ffffffd6"
template <typename Range>class fmt::``arg_formatter¶
The default argument formatter.
Inherits from fmt::internal::function< internal::arg_formatter_base< Range >::iterator >, fmt::internal::arg_formatter_base< Range >
Public Functions
arg_formatter(context_type &ctx, format_specs *spec = {})¶
Constructs an argument formatter object. ctx is a reference to the formatting context, spec contains format specifier information for standard argument types.
iterator operator()(typename basic_format_arg<context_type>::handle handle)¶
Formats an argument of a user-defined type.
The library supports strftime-like date and time formatting:
#include\<fmt/time.h\>std::time\_tt=std::time(nullptr);// Prints "The date is 2016-04-29." (with the current date)fmt::print("The date is {:%Y-%m-%d}.",\*std::localtime(&t));
The format string syntax is described in the documentation of strftime.
std::ostream support¶fmt/ostream.h provides std::ostream support including formatting of user-defined types that have overloaded operator<<:
#include\<fmt/ostream.h\>classdate{intyear\_,month\_,day\_;public:date(intyear,intmonth,intday):year\_(year),month\_(month),day\_(day){}friendstd::ostream&operator\<\<(std::ostream&os,constdate&d){returnos\<\<d.year\_\<\<'-'\<\<d.month\_\<\<'-'\<\<d.day\_;}};std::strings=fmt::format("The date is {}",date(2012,12,9));// s == "The date is 2012-12-9"
template <typename... Args>void fmt::``print(std::ostream &os, string_view format_str, const Args&... args)¶
Prints formatted data to the stream os.
Example :
fmt::print(cerr,"Don't {}!","panic");
printf formatting¶The header fmt/printf.h provides printf-like formatting functionality. The following functions use printf format string syntax with the POSIX extension for positional arguments. Unlike their standard counterparts, the fmt functions are type-safe and throw an exception if an argument type doesn’t match its format specification.
template <typename... Args>int fmt::``printf(string_view format_str, const Args&... args)¶
Prints formatted data to stdout.
Example :
fmt::printf("Elapsed time: %.2f seconds",1.23);
template <typename... Args>int fmt::``fprintf(std::FILE *f, string_view format_str, const Args&... args)¶
Prints formatted data to the file f.
Example :
fmt::fprintf(stderr,"Don't %s!","panic");
template <typename... Args>int fmt::``fprintf(std::ostream &os, string_view format_str, const Args&... args)¶
Prints formatted data to the stream os.
Example :
fmt::fprintf(cerr,"Don't %s!","panic");
template <typename... Args>std::string fmt::``sprintf(string_view format_str, const Args&... args)¶
Formats arguments and returns the result as a string.
Example :
std::stringmessage=fmt::sprintf("The answer is %d",42);