Add ktx
This commit is contained in:
+3290
File diff suppressed because it is too large
Load Diff
Vendored
+679
@@ -0,0 +1,679 @@
|
||||
# API Reference
|
||||
|
||||
The {fmt} library API consists of the following components:
|
||||
|
||||
- [`fmt/base.h`](#base-api): the base API providing main formatting functions
|
||||
for `char`/UTF-8 with C++20 compile-time checks and minimal dependencies
|
||||
- [`fmt/format.h`](#format-api): `fmt::format` and other formatting functions
|
||||
as well as locale support
|
||||
- [`fmt/ranges.h`](#ranges-api): formatting of ranges and tuples
|
||||
- [`fmt/chrono.h`](#chrono-api): date and time formatting
|
||||
- [`fmt/std.h`](#std-api): formatters for standard library types
|
||||
- [`fmt/compile.h`](#compile-api): format string compilation
|
||||
- [`fmt/color.h`](#color-api): terminal colors and text styles
|
||||
- [`fmt/os.h`](#os-api): system APIs
|
||||
- [`fmt/ostream.h`](#ostream-api): `std::ostream` support
|
||||
- [`fmt/args.h`](#args-api): dynamic argument lists
|
||||
- [`fmt/printf.h`](#printf-api): safe `printf`
|
||||
- [`fmt/xchar.h`](#xchar-api): optional `wchar_t` support
|
||||
|
||||
All functions and types provided by the library reside in namespace `fmt`
|
||||
and macros have prefix `FMT_`.
|
||||
|
||||
## Base API
|
||||
|
||||
`fmt/base.h` defines the base API which provides main formatting functions
|
||||
for `char`/UTF-8 with C++20 compile-time checks. It has minimal include
|
||||
dependencies for better compile times. This header is only beneficial when
|
||||
using {fmt} as a library (the default) and not in the header-only mode.
|
||||
It also provides `formatter` specializations for the following types:
|
||||
|
||||
- `int`, `long long`,
|
||||
- `unsigned`, `unsigned long long`
|
||||
- `float`, `double`, `long double`
|
||||
- `bool`
|
||||
- `char`
|
||||
- `const char*`, [`fmt::string_view`](#basic_string_view)
|
||||
- `const void*`
|
||||
|
||||
The following functions use [format string syntax](syntax.md) similar to that
|
||||
of [str.format](https://docs.python.org/3/library/stdtypes.html#str.format)
|
||||
in Python. They take *fmt* and *args* as arguments.
|
||||
|
||||
*fmt* 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. [`fmt::format_string`](#format_string) is a format
|
||||
string which can be implicitly constructed from a string literal or a
|
||||
`constexpr` string and is checked at compile time in C++20. To pass a runtime
|
||||
format string wrap it in [`fmt::runtime`](#runtime).
|
||||
|
||||
*args* is an argument list representing objects to be formatted.
|
||||
|
||||
I/O errors are reported as [`std::system_error`](
|
||||
https://en.cppreference.com/w/cpp/error/system_error) exceptions unless
|
||||
specified otherwise.
|
||||
|
||||
::: print(format_string<T...>, T&&...)
|
||||
|
||||
::: print(FILE*, format_string<T...>, T&&...)
|
||||
|
||||
::: println(format_string<T...>, T&&...)
|
||||
|
||||
::: println(FILE*, format_string<T...>, T&&...)
|
||||
|
||||
::: format_to(OutputIt&&, format_string<T...>, T&&...)
|
||||
|
||||
::: format_to_n(OutputIt, size_t, format_string<T...>, T&&...)
|
||||
|
||||
::: format_to_n_result
|
||||
|
||||
::: formatted_size(format_string<T...>, T&&...)
|
||||
|
||||
<a id="udt"></a>
|
||||
### Formatting User-Defined Types
|
||||
|
||||
The {fmt} library provides formatters for many standard C++ types.
|
||||
See [`fmt/ranges.h`](#ranges-api) for ranges and tuples including standard
|
||||
containers such as `std::vector`, [`fmt/chrono.h`](#chrono-api) for date and
|
||||
time formatting and [`fmt/std.h`](#std-api) for other standard library types.
|
||||
|
||||
There are two ways to make a user-defined type formattable: providing a
|
||||
`format_as` function or specializing the `formatter` struct template.
|
||||
|
||||
Use `format_as` if you want to make your type formattable as some other
|
||||
type with the same format specifiers. The `format_as` function should
|
||||
take an object of your type and return an object of a formattable type.
|
||||
It should be defined in the same namespace as your type.
|
||||
|
||||
Example ([run](https://godbolt.org/z/nvME4arz8)):
|
||||
|
||||
#include <fmt/format.h>
|
||||
|
||||
namespace kevin_namespacy {
|
||||
|
||||
enum class film {
|
||||
house_of_cards, american_beauty, se7en = 7
|
||||
};
|
||||
|
||||
auto format_as(film f) { return fmt::underlying(f); }
|
||||
|
||||
}
|
||||
|
||||
int main() {
|
||||
fmt::print("{}\n", kevin_namespacy::film::se7en); // Output: 7
|
||||
}
|
||||
|
||||
Using specialization is more complex but gives you full control over
|
||||
parsing and formatting. To use this method specialize the `formatter`
|
||||
struct template for your type and implement `parse` and `format`
|
||||
methods.
|
||||
|
||||
The recommended way of defining a formatter is by reusing an existing
|
||||
one via inheritance or composition. This way you can support standard
|
||||
format specifiers without implementing them yourself. For example:
|
||||
|
||||
```c++
|
||||
// color.h:
|
||||
#include <fmt/base.h>
|
||||
|
||||
enum class color {red, green, blue};
|
||||
|
||||
template <> struct fmt::formatter<color>: formatter<string_view> {
|
||||
// parse is inherited from formatter<string_view>.
|
||||
|
||||
auto format(color c, format_context& ctx) const
|
||||
-> format_context::iterator;
|
||||
};
|
||||
```
|
||||
|
||||
```c++
|
||||
// color.cc:
|
||||
#include "color.h"
|
||||
#include <fmt/format.h>
|
||||
|
||||
auto fmt::formatter<color>::format(color c, format_context& ctx) const
|
||||
-> format_context::iterator {
|
||||
string_view name = "unknown";
|
||||
switch (c) {
|
||||
case color::red: name = "red"; break;
|
||||
case color::green: name = "green"; break;
|
||||
case color::blue: name = "blue"; break;
|
||||
}
|
||||
return formatter<string_view>::format(name, ctx);
|
||||
}
|
||||
```
|
||||
|
||||
Note that `formatter<string_view>::format` is defined in `fmt/format.h`
|
||||
so it has to be included in the source file. Since `parse` is inherited
|
||||
from `formatter<string_view>` it will recognize all string format
|
||||
specifications, for example
|
||||
|
||||
```c++
|
||||
fmt::format("{:>10}", color::blue)
|
||||
```
|
||||
|
||||
will return `" blue"`.
|
||||
|
||||
<!-- The experimental `nested_formatter` provides an easy way of applying a
|
||||
formatter to one or more subobjects.
|
||||
|
||||
For example:
|
||||
|
||||
#include <fmt/format.h>
|
||||
|
||||
struct point {
|
||||
double x, y;
|
||||
};
|
||||
|
||||
template <>
|
||||
struct fmt::formatter<point> : nested_formatter<double> {
|
||||
auto format(point p, format_context& ctx) const {
|
||||
return write_padded(ctx, [=](auto out) {
|
||||
return format_to(out, "({}, {})", this->nested(p.x),
|
||||
this->nested(p.y));
|
||||
});
|
||||
}
|
||||
};
|
||||
|
||||
int main() {
|
||||
fmt::print("[{:>20.2f}]", point{1, 2});
|
||||
}
|
||||
|
||||
prints:
|
||||
|
||||
[ (1.00, 2.00)]
|
||||
|
||||
Notice that fill, align and width are applied to the whole object which
|
||||
is the recommended behavior while the remaining specifiers apply to
|
||||
elements. -->
|
||||
|
||||
In general the formatter has the following form:
|
||||
|
||||
template <> struct fmt::formatter<T> {
|
||||
// Parses format specifiers and stores them in the formatter.
|
||||
//
|
||||
// [ctx.begin(), ctx.end()) is a, possibly empty, character range that
|
||||
// contains a part of the format string starting from the format
|
||||
// specifications to be parsed, e.g. in
|
||||
//
|
||||
// fmt::format("{:f} continued", ...);
|
||||
//
|
||||
// the range will contain "f} continued". The formatter should parse
|
||||
// specifiers until '}' or the end of the range. In this example the
|
||||
// formatter should parse the 'f' specifier and return an iterator
|
||||
// pointing to '}'.
|
||||
constexpr auto parse(format_parse_context& ctx)
|
||||
-> format_parse_context::iterator;
|
||||
|
||||
// Formats value using the parsed format specification stored in this
|
||||
// formatter and writes the output to ctx.out().
|
||||
auto format(const T& value, format_context& ctx) const
|
||||
-> format_context::iterator;
|
||||
};
|
||||
|
||||
It is recommended to at least support fill, align and width that apply
|
||||
to the whole object and have the same semantics as in standard
|
||||
formatters.
|
||||
|
||||
You can also write a formatter for a hierarchy of classes:
|
||||
|
||||
```c++
|
||||
// demo.h:
|
||||
#include <type_traits>
|
||||
#include <fmt/format.h>
|
||||
|
||||
struct A {
|
||||
virtual ~A() {}
|
||||
virtual std::string name() const { return "A"; }
|
||||
};
|
||||
|
||||
struct B : A {
|
||||
virtual std::string name() const { return "B"; }
|
||||
};
|
||||
|
||||
template <typename T>
|
||||
struct fmt::formatter<T, std::enable_if_t<std::is_base_of_v<A, T>, char>> :
|
||||
fmt::formatter<std::string> {
|
||||
auto format(const A& a, format_context& ctx) const {
|
||||
return formatter<std::string>::format(a.name(), ctx);
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
```c++
|
||||
// demo.cc:
|
||||
#include "demo.h"
|
||||
#include <fmt/format.h>
|
||||
|
||||
int main() {
|
||||
B b;
|
||||
A& a = b;
|
||||
fmt::print("{}", a); // Output: B
|
||||
}
|
||||
```
|
||||
|
||||
Providing both a `formatter` specialization and a `format_as` overload is
|
||||
disallowed.
|
||||
|
||||
::: basic_format_parse_context
|
||||
|
||||
::: context
|
||||
|
||||
::: format_context
|
||||
|
||||
### Compile-Time Checks
|
||||
|
||||
Compile-time format string checks are enabled by default on compilers
|
||||
that support C++20 `consteval`. On older compilers you can use the
|
||||
[FMT_STRING](#legacy-checks) macro defined in `fmt/format.h` instead.
|
||||
|
||||
Unused arguments are allowed as in Python's `str.format` and ordinary functions.
|
||||
|
||||
See [Type Erasure](#type-erasure) for an example of how to enable compile-time
|
||||
checks in your own functions with `fmt::format_string` while avoiding template
|
||||
bloat.
|
||||
|
||||
::: fstring
|
||||
|
||||
::: format_string
|
||||
|
||||
::: runtime(string_view)
|
||||
|
||||
### Type Erasure
|
||||
|
||||
You can create your own formatting function with compile-time checks and
|
||||
small binary footprint, for example ([run](https://godbolt.org/z/b9Pbasvzc)):
|
||||
|
||||
```c++
|
||||
#include <fmt/format.h>
|
||||
|
||||
void vlog(const char* file, int line,
|
||||
fmt::string_view fmt, fmt::format_args args) {
|
||||
fmt::print("{}: {}: {}", file, line, fmt::vformat(fmt, args));
|
||||
}
|
||||
|
||||
template <typename... T>
|
||||
void log(const char* file, int line,
|
||||
fmt::format_string<T...> fmt, T&&... args) {
|
||||
vlog(file, line, fmt, fmt::make_format_args(args...));
|
||||
}
|
||||
|
||||
#define MY_LOG(fmt, ...) log(__FILE__, __LINE__, fmt, __VA_ARGS__)
|
||||
|
||||
MY_LOG("invalid squishiness: {}", 42);
|
||||
```
|
||||
|
||||
Note that `vlog` is not parameterized on argument types which improves
|
||||
compile times and reduces binary code size compared to a fully
|
||||
parameterized version.
|
||||
|
||||
::: make_format_args(T&...)
|
||||
|
||||
::: basic_format_args
|
||||
|
||||
::: format_args
|
||||
|
||||
::: basic_format_arg
|
||||
|
||||
### Named Arguments
|
||||
|
||||
::: arg(const Char*, const T&)
|
||||
|
||||
Named arguments are not supported in compile-time checks at the moment.
|
||||
|
||||
### Compatibility
|
||||
|
||||
::: basic_string_view
|
||||
|
||||
::: string_view
|
||||
|
||||
## Format API
|
||||
|
||||
`fmt/format.h` defines the full format API providing additional
|
||||
formatting functions and locale support.
|
||||
|
||||
<a id="format"></a>
|
||||
::: format(format_string<T...>, T&&...)
|
||||
|
||||
::: vformat(string_view, format_args)
|
||||
|
||||
::: operator""_a()
|
||||
|
||||
### Utilities
|
||||
|
||||
::: ptr(T)
|
||||
|
||||
::: underlying(Enum)
|
||||
|
||||
::: to_string(const T&)
|
||||
|
||||
::: group_digits(T)
|
||||
|
||||
::: detail::buffer
|
||||
|
||||
::: basic_memory_buffer
|
||||
|
||||
### System Errors
|
||||
|
||||
{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.
|
||||
|
||||
::: system_error
|
||||
|
||||
::: format_system_error
|
||||
|
||||
### Custom Allocators
|
||||
|
||||
The {fmt} library supports custom dynamic memory allocators. A custom
|
||||
allocator class can be specified as a template argument to
|
||||
[`fmt::basic_memory_buffer`](#basic_memory_buffer):
|
||||
|
||||
using custom_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:
|
||||
|
||||
using custom_string =
|
||||
std::basic_string<char, std::char_traits<char>, custom_allocator>;
|
||||
|
||||
auto vformat(custom_allocator alloc, fmt::string_view fmt,
|
||||
fmt::format_args args) -> custom_string {
|
||||
auto buf = custom_memory_buffer(alloc);
|
||||
fmt::vformat_to(std::back_inserter(buf), fmt, args);
|
||||
return custom_string(buf.data(), buf.size(), alloc);
|
||||
}
|
||||
|
||||
template <typename ...Args>
|
||||
auto format(custom_allocator alloc, fmt::string_view fmt,
|
||||
const Args& ... args) -> custom_string {
|
||||
return vformat(alloc, fmt, fmt::make_format_args(args...));
|
||||
}
|
||||
|
||||
The allocator will be used for the output container only. Formatting
|
||||
functions normally don't do any allocations for built-in and string
|
||||
types except for non-default floating-point formatting that occasionally
|
||||
falls back on `sprintf`.
|
||||
|
||||
### Locale
|
||||
|
||||
All formatting is locale-independent by default. Use the `'L'` format
|
||||
specifier to insert the appropriate number separator characters from the
|
||||
locale:
|
||||
|
||||
#include <fmt/format.h>
|
||||
#include <locale>
|
||||
|
||||
std::locale::global(std::locale("en_US.UTF-8"));
|
||||
auto s = fmt::format("{:L}", 1000000); // s == "1,000,000"
|
||||
|
||||
`fmt/format.h` provides the following overloads of formatting functions
|
||||
that take `std::locale` as a parameter. The locale type is a template
|
||||
parameter to avoid the expensive `<locale>` include.
|
||||
|
||||
::: format(const Locale&, format_string<T...>, T&&...)
|
||||
|
||||
::: format_to(OutputIt, const Locale&, format_string<T...>, T&&...)
|
||||
|
||||
::: formatted_size(const Locale&, format_string<T...>, T&&...)
|
||||
|
||||
<a id="legacy-checks"></a>
|
||||
### Legacy Compile-Time Checks
|
||||
|
||||
`FMT_STRING` enables compile-time checks on older compilers. It requires
|
||||
C++14 or later and is a no-op in C++11.
|
||||
|
||||
::: FMT_STRING
|
||||
|
||||
To force the use of legacy compile-time checks, define the preprocessor
|
||||
variable `FMT_ENFORCE_COMPILE_STRING`. When set, functions accepting
|
||||
`FMT_STRING` will fail to compile with regular strings.
|
||||
|
||||
<a id="ranges-api"></a>
|
||||
## Range and Tuple Formatting
|
||||
|
||||
`fmt/ranges.h` provides formatting support for ranges and tuples:
|
||||
|
||||
#include <fmt/ranges.h>
|
||||
|
||||
fmt::print("{}", std::tuple<char, int>{'a', 42});
|
||||
// Output: ('a', 42)
|
||||
|
||||
Using `fmt::join`, you can separate tuple elements with a custom separator:
|
||||
|
||||
#include <fmt/ranges.h>
|
||||
|
||||
auto t = std::tuple<int, char>{1, 'a'};
|
||||
fmt::print("{}", fmt::join(t, ", "));
|
||||
// Output: 1, a
|
||||
|
||||
::: join(Range&&, string_view)
|
||||
|
||||
::: join(It, Sentinel, string_view)
|
||||
|
||||
::: join(std::initializer_list<T>, string_view)
|
||||
|
||||
<a id="chrono-api"></a>
|
||||
## Date and Time Formatting
|
||||
|
||||
`fmt/chrono.h` provides formatters for
|
||||
|
||||
- [`std::chrono::duration`](https://en.cppreference.com/w/cpp/chrono/duration)
|
||||
- [`std::chrono::time_point`](
|
||||
https://en.cppreference.com/w/cpp/chrono/time_point)
|
||||
- [`std::tm`](https://en.cppreference.com/w/cpp/chrono/c/tm)
|
||||
|
||||
The format syntax is described in [Chrono Format Specifications](syntax.md#
|
||||
chrono-format-specifications).
|
||||
|
||||
**Example**:
|
||||
|
||||
#include <fmt/chrono.h>
|
||||
|
||||
int main() {
|
||||
auto now = std::chrono::system_clock::now();
|
||||
|
||||
fmt::print("The date is {:%Y-%m-%d}.\n", now);
|
||||
// Output: The date is 2020-11-07.
|
||||
// (with 2020-11-07 replaced by the current date)
|
||||
|
||||
using namespace std::literals::chrono_literals;
|
||||
|
||||
fmt::print("Default format: {} {}\n", 42s, 100ms);
|
||||
// Output: Default format: 42s 100ms
|
||||
|
||||
fmt::print("strftime-like format: {:%H:%M:%S}\n", 3h + 15min + 30s);
|
||||
// Output: strftime-like format: 03:15:30
|
||||
}
|
||||
|
||||
::: gmtime(std::time_t)
|
||||
|
||||
<a id="std-api"></a>
|
||||
## Standard Library Types Formatting
|
||||
|
||||
`fmt/std.h` provides formatters for:
|
||||
|
||||
- [`std::atomic`](https://en.cppreference.com/w/cpp/atomic/atomic)
|
||||
- [`std::atomic_flag`](https://en.cppreference.com/w/cpp/atomic/atomic_flag)
|
||||
- [`std::bitset`](https://en.cppreference.com/w/cpp/utility/bitset)
|
||||
- [`std::error_code`](https://en.cppreference.com/w/cpp/error/error_code)
|
||||
- [`std::exception`](https://en.cppreference.com/w/cpp/error/exception)
|
||||
- [`std::filesystem::path`](https://en.cppreference.com/w/cpp/filesystem/path)
|
||||
- [`std::monostate`](
|
||||
https://en.cppreference.com/w/cpp/utility/variant/monostate)
|
||||
- [`std::optional`](https://en.cppreference.com/w/cpp/utility/optional)
|
||||
- [`std::source_location`](
|
||||
https://en.cppreference.com/w/cpp/utility/source_location)
|
||||
- [`std::thread::id`](https://en.cppreference.com/w/cpp/thread/thread/id)
|
||||
- [`std::variant`](https://en.cppreference.com/w/cpp/utility/variant/variant)
|
||||
|
||||
::: ptr(const std::unique_ptr<T, Deleter>&)
|
||||
|
||||
::: ptr(const std::shared_ptr<T>&)
|
||||
|
||||
### Variants
|
||||
|
||||
A `std::variant` is only formattable if every variant alternative is
|
||||
formattable, and requires the `__cpp_lib_variant` [library
|
||||
feature](https://en.cppreference.com/w/cpp/feature_test).
|
||||
|
||||
**Example**:
|
||||
|
||||
#include <fmt/std.h>
|
||||
|
||||
fmt::print("{}", std::variant<char, float>('x'));
|
||||
// Output: variant('x')
|
||||
|
||||
fmt::print("{}", std::variant<std::monostate, char>());
|
||||
// Output: variant(monostate)
|
||||
|
||||
## Bit-Fields and Packed Structs
|
||||
|
||||
To format a bit-field or a field of a struct with `__attribute__((packed))`
|
||||
applied to it, you need to convert it to the underlying or compatible type via
|
||||
a cast or a unary `+` ([godbolt](https://www.godbolt.org/z/3qKKs6T5Y)):
|
||||
|
||||
```c++
|
||||
struct smol {
|
||||
int bit : 1;
|
||||
};
|
||||
|
||||
auto s = smol();
|
||||
fmt::print("{}", +s.bit);
|
||||
```
|
||||
|
||||
This is a known limitation of "perfect" forwarding in C++.
|
||||
|
||||
<a id="compile-api"></a>
|
||||
## Format String Compilation
|
||||
|
||||
`fmt/compile.h` provides format string compilation and compile-time
|
||||
(`constexpr`) formatting enabled via the `FMT_COMPILE` macro or the `_cf`
|
||||
user-defined literal defined in namespace `fmt::literals`. Format strings
|
||||
marked with `FMT_COMPILE` or `_cf` are parsed, checked and converted into
|
||||
efficient formatting code at compile-time. This supports arguments of built-in
|
||||
and string types as well as user-defined types with `format` functions taking
|
||||
the format context type as a template parameter in their `formatter`
|
||||
specializations. For example:
|
||||
|
||||
template <> struct fmt::formatter<point> {
|
||||
constexpr auto parse(format_parse_context& ctx);
|
||||
|
||||
template <typename FormatContext>
|
||||
auto format(const point& p, FormatContext& ctx) const;
|
||||
};
|
||||
|
||||
Format string compilation can generate more binary code compared to the
|
||||
default API and is only recommended in places where formatting is a
|
||||
performance bottleneck.
|
||||
|
||||
::: FMT_COMPILE
|
||||
|
||||
::: operator""_cf
|
||||
|
||||
<a id="color-api"></a>
|
||||
## Terminal Colors and Text Styles
|
||||
|
||||
`fmt/color.h` provides support for terminal color and text style output.
|
||||
|
||||
::: print(text_style, format_string<T...>, T&&...)
|
||||
|
||||
::: fg(detail::color_type)
|
||||
|
||||
::: bg(detail::color_type)
|
||||
|
||||
::: styled(const T&, text_style)
|
||||
|
||||
<a id="os-api"></a>
|
||||
## System APIs
|
||||
|
||||
::: ostream
|
||||
|
||||
::: windows_error
|
||||
|
||||
<a id="ostream-api"></a>
|
||||
## `std::ostream` Support
|
||||
|
||||
`fmt/ostream.h` provides `std::ostream` support including formatting of
|
||||
user-defined types that have an overloaded insertion operator
|
||||
(`operator<<`). In order to make a type formattable via `std::ostream`
|
||||
you should provide a `formatter` specialization inherited from
|
||||
`ostream_formatter`:
|
||||
|
||||
#include <fmt/ostream.h>
|
||||
|
||||
struct date {
|
||||
int year, month, day;
|
||||
|
||||
friend std::ostream& operator<<(std::ostream& os, const date& d) {
|
||||
return os << d.year << '-' << d.month << '-' << d.day;
|
||||
}
|
||||
};
|
||||
|
||||
template <> struct fmt::formatter<date> : ostream_formatter {};
|
||||
|
||||
std::string s = fmt::format("The date is {}", date{2012, 12, 9});
|
||||
// s == "The date is 2012-12-9"
|
||||
|
||||
::: streamed(const T&)
|
||||
|
||||
::: print(std::ostream&, format_string<T...>, T&&...)
|
||||
|
||||
<a id="args-api"></a>
|
||||
## Dynamic Argument Lists
|
||||
|
||||
The header `fmt/args.h` provides `dynamic_format_arg_store`, a builder-like API
|
||||
that can be used to construct format argument lists dynamically.
|
||||
|
||||
::: dynamic_format_arg_store
|
||||
|
||||
<a id="printf-api"></a>
|
||||
## Safe `printf`
|
||||
|
||||
The header `fmt/printf.h` provides `printf`-like formatting
|
||||
functionality. The following functions use [printf format string
|
||||
syntax](https://pubs.opengroup.org/onlinepubs/009695399/functions/fprintf.html)
|
||||
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.
|
||||
|
||||
::: printf(string_view, const T&...)
|
||||
|
||||
::: fprintf(std::FILE*, const S&, const T&...)
|
||||
|
||||
::: sprintf(const S&, const T&...)
|
||||
|
||||
<a id="xchar-api"></a>
|
||||
## Wide Strings
|
||||
|
||||
The optional header `fmt/xchar.h` provides support for `wchar_t` and
|
||||
exotic character types.
|
||||
|
||||
::: is_char
|
||||
|
||||
::: wstring_view
|
||||
|
||||
::: wformat_context
|
||||
|
||||
::: to_wstring(const T&)
|
||||
|
||||
## Compatibility with C++20 `std::format`
|
||||
|
||||
{fmt} implements nearly all of the [C++20 formatting
|
||||
library](https://en.cppreference.com/w/cpp/utility/format) with the
|
||||
following differences:
|
||||
|
||||
- Names are defined in the `fmt` namespace instead of `std` to avoid
|
||||
collisions with standard library implementations.
|
||||
|
||||
- Width calculation doesn't use grapheme clusterization. The latter has
|
||||
been implemented in a separate branch but hasn't been integrated yet.
|
||||
|
||||
- The default floating-point representation in {fmt} uses the smallest
|
||||
precision that provides round-trip guarantees similarly to other languages
|
||||
like Java and Python. `std::format` is currently specified in terms of
|
||||
`std::to_chars` which tries to generate the smallest number of characters
|
||||
(ignoring redundant digits and sign in exponent) and may procude more
|
||||
decimal digits than necessary.
|
||||
Vendored
+61
@@ -0,0 +1,61 @@
|
||||
:root {
|
||||
--md-primary-fg-color: #0050D0;
|
||||
}
|
||||
|
||||
.md-grid {
|
||||
max-width: 960px;
|
||||
}
|
||||
|
||||
@media (min-width: 400px) {
|
||||
.md-tabs {
|
||||
display: block;
|
||||
}
|
||||
}
|
||||
|
||||
.docblock {
|
||||
border-left: .05rem solid var(--md-primary-fg-color);
|
||||
}
|
||||
|
||||
.docblock-desc {
|
||||
margin-left: 1em;
|
||||
}
|
||||
|
||||
pre > code.decl {
|
||||
white-space: pre-wrap;
|
||||
}
|
||||
|
||||
|
||||
code.decl > div {
|
||||
text-indent: -2ch; /* Negative indent to counteract the indent on the first line */
|
||||
padding-left: 2ch; /* Add padding to the left to create an indent */
|
||||
}
|
||||
|
||||
.features-container {
|
||||
display: flex;
|
||||
flex-wrap: wrap;
|
||||
gap: 20px;
|
||||
justify-content: center; /* Center the items horizontally */
|
||||
}
|
||||
|
||||
.feature {
|
||||
flex: 1 1 calc(50% - 20px); /* Two columns with space between */
|
||||
max-width: 600px; /* Set the maximum width for the feature boxes */
|
||||
box-sizing: border-box;
|
||||
padding: 10px;
|
||||
overflow: hidden; /* Hide overflow content */
|
||||
text-overflow: ellipsis; /* Handle text overflow */
|
||||
white-space: normal; /* Allow text wrapping */
|
||||
}
|
||||
|
||||
.feature h2 {
|
||||
margin-top: 0px;
|
||||
font-weight: bold;
|
||||
}
|
||||
|
||||
@media (max-width: 768px) {
|
||||
.feature {
|
||||
flex: 1 1 100%; /* Stack columns on smaller screens */
|
||||
max-width: 100%; /* Allow full width on smaller screens */
|
||||
white-space: normal; /* Allow text wrapping on smaller screens */
|
||||
}
|
||||
}
|
||||
Vendored
+4
@@ -0,0 +1,4 @@
|
||||
document$.subscribe(() => {
|
||||
hljs.highlightAll(),
|
||||
{ language: 'c++' }
|
||||
})
|
||||
Vendored
+222
@@ -0,0 +1,222 @@
|
||||
# Get Started
|
||||
|
||||
Compile and run {fmt} examples online with [Compiler Explorer](
|
||||
https://godbolt.org/z/P7h6cd6o3).
|
||||
|
||||
{fmt} is compatible with any build system. The next section describes its usage
|
||||
with CMake, while the [Build Systems](#build-systems) section covers the rest.
|
||||
|
||||
## CMake
|
||||
|
||||
{fmt} provides two CMake targets: `fmt::fmt` for the compiled library and
|
||||
`fmt::fmt-header-only` for the header-only library. It is recommended to use
|
||||
the compiled library for improved build times.
|
||||
|
||||
There are three primary ways to use {fmt} with CMake:
|
||||
|
||||
* **FetchContent**: Starting from CMake 3.11, you can use [`FetchContent`](
|
||||
https://cmake.org/cmake/help/v3.30/module/FetchContent.html) to automatically
|
||||
download {fmt} as a dependency at configure time:
|
||||
|
||||
include(FetchContent)
|
||||
|
||||
FetchContent_Declare(
|
||||
fmt
|
||||
GIT_REPOSITORY https://github.com/fmtlib/fmt
|
||||
GIT_TAG e69e5f977d458f2650bb346dadf2ad30c5320281) # 10.2.1
|
||||
FetchContent_MakeAvailable(fmt)
|
||||
|
||||
target_link_libraries(<your-target> fmt::fmt)
|
||||
|
||||
* **Installed**: You can find and use an [installed](#installation) version of
|
||||
{fmt} in your `CMakeLists.txt` file as follows:
|
||||
|
||||
find_package(fmt)
|
||||
target_link_libraries(<your-target> fmt::fmt)
|
||||
|
||||
* **Embedded**: You can add the {fmt} source tree to your project and include it
|
||||
in your `CMakeLists.txt` file:
|
||||
|
||||
add_subdirectory(fmt)
|
||||
target_link_libraries(<your-target> fmt::fmt)
|
||||
|
||||
## Installation
|
||||
|
||||
### Debian/Ubuntu
|
||||
|
||||
To install {fmt} on Debian, Ubuntu, or any other Debian-based Linux
|
||||
distribution, use the following command:
|
||||
|
||||
apt install libfmt-dev
|
||||
|
||||
### Homebrew
|
||||
|
||||
Install {fmt} on macOS using [Homebrew](https://brew.sh/):
|
||||
|
||||
brew install fmt
|
||||
|
||||
### Conda
|
||||
|
||||
Install {fmt} on Linux, macOS, and Windows with [Conda](
|
||||
https://docs.conda.io/en/latest/), using its [conda-forge package](
|
||||
https://github.com/conda-forge/fmt-feedstock):
|
||||
|
||||
conda install -c conda-forge fmt
|
||||
|
||||
### vcpkg
|
||||
|
||||
Download and install {fmt} using the vcpkg package manager:
|
||||
|
||||
git clone https://github.com/Microsoft/vcpkg.git
|
||||
cd vcpkg
|
||||
./bootstrap-vcpkg.sh
|
||||
./vcpkg integrate install
|
||||
./vcpkg install fmt
|
||||
|
||||
<!-- The fmt package in vcpkg is kept up to date by Microsoft team members and
|
||||
community contributors. If the version is out of date, please [create an
|
||||
issue or pull request](https://github.com/Microsoft/vcpkg) on the vcpkg
|
||||
repository. -->
|
||||
|
||||
## Building from Source
|
||||
|
||||
CMake works by generating native makefiles or project files that can be
|
||||
used in the compiler environment of your choice. The typical workflow
|
||||
starts with:
|
||||
|
||||
mkdir build # Create a directory to hold the build output.
|
||||
cd build
|
||||
cmake .. # Generate native build scripts.
|
||||
|
||||
run in the `fmt` repository.
|
||||
|
||||
If you are on a Unix-like system, you should now see a Makefile in the
|
||||
current directory. Now you can build the library by running `make`.
|
||||
|
||||
Once the library has been built you can invoke `make test` to run the tests.
|
||||
|
||||
You can control generation of the make `test` target with the `FMT_TEST`
|
||||
CMake option. This can be useful if you include fmt as a subdirectory in
|
||||
your project but don't want to add fmt's tests to your `test` target.
|
||||
|
||||
To build a shared library set the `BUILD_SHARED_LIBS` CMake variable to `TRUE`:
|
||||
|
||||
cmake -DBUILD_SHARED_LIBS=TRUE ..
|
||||
|
||||
To build a static library with position-independent code (e.g. for
|
||||
linking it into another shared library such as a Python extension), set the
|
||||
`CMAKE_POSITION_INDEPENDENT_CODE` CMake variable to `TRUE`:
|
||||
|
||||
cmake -DCMAKE_POSITION_INDEPENDENT_CODE=TRUE ..
|
||||
|
||||
After building the library you can install it on a Unix-like system by
|
||||
running `sudo make install`.
|
||||
|
||||
### Building the Docs
|
||||
|
||||
To build the documentation you need the following software installed on
|
||||
your system:
|
||||
|
||||
- [Python](https://www.python.org/)
|
||||
- [Doxygen](http://www.stack.nl/~dimitri/doxygen/)
|
||||
- [MkDocs](https://www.mkdocs.org/) with `mkdocs-material`, `mkdocstrings`,
|
||||
`pymdown-extensions` and `mike`
|
||||
|
||||
First generate makefiles or project files using CMake as described in
|
||||
the previous section. Then compile the `doc` target/project, for example:
|
||||
|
||||
make doc
|
||||
|
||||
This will generate the HTML documentation in `doc/html`.
|
||||
|
||||
## Build Systems
|
||||
|
||||
### build2
|
||||
|
||||
You can use [build2](https://build2.org), a dependency manager and a build
|
||||
system, to use {fmt}.
|
||||
|
||||
Currently this package is available in these package repositories:
|
||||
|
||||
- <https://cppget.org/fmt/> for released and published versions.
|
||||
- <https://github.com/build2-packaging/fmt> for unreleased or custom versions.
|
||||
|
||||
**Usage:**
|
||||
|
||||
- `build2` package name: `fmt`
|
||||
- Library target name: `lib{fmt}`
|
||||
|
||||
To make your `build2` project depend on `fmt`:
|
||||
|
||||
- Add one of the repositories to your configurations, or in your
|
||||
`repositories.manifest`, if not already there:
|
||||
|
||||
:
|
||||
role: prerequisite
|
||||
location: https://pkg.cppget.org/1/stable
|
||||
|
||||
- Add this package as a dependency to your `manifest` file (example
|
||||
for version 10):
|
||||
|
||||
depends: fmt ~10.0.0
|
||||
|
||||
- Import the target and use it as a prerequisite to your own target
|
||||
using `fmt` in the appropriate `buildfile`:
|
||||
|
||||
import fmt = fmt%lib{fmt}
|
||||
lib{mylib} : cxx{**} ... $fmt
|
||||
|
||||
Then build your project as usual with `b` or `bdep update`.
|
||||
|
||||
### Meson
|
||||
|
||||
[Meson WrapDB](https://mesonbuild.com/Wrapdb-projects.html) includes an `fmt`
|
||||
package.
|
||||
|
||||
**Usage:**
|
||||
|
||||
- Install the `fmt` subproject from the WrapDB by running:
|
||||
|
||||
meson wrap install fmt
|
||||
|
||||
from the root of your project.
|
||||
|
||||
- In your project's `meson.build` file, add an entry for the new subproject:
|
||||
|
||||
fmt = subproject('fmt')
|
||||
fmt_dep = fmt.get_variable('fmt_dep')
|
||||
|
||||
- Include the new dependency object to link with fmt:
|
||||
|
||||
my_build_target = executable(
|
||||
'name', 'src/main.cc', dependencies: [fmt_dep])
|
||||
|
||||
**Options:**
|
||||
|
||||
If desired, {fmt} can be built as a static library, or as a header-only library.
|
||||
|
||||
For a static build, use the following subproject definition:
|
||||
|
||||
fmt = subproject('fmt', default_options: 'default_library=static')
|
||||
fmt_dep = fmt.get_variable('fmt_dep')
|
||||
|
||||
For the header-only version, use:
|
||||
|
||||
fmt = subproject('fmt', default_options: ['header-only=true'])
|
||||
fmt_dep = fmt.get_variable('fmt_header_only_dep')
|
||||
|
||||
### Android NDK
|
||||
|
||||
{fmt} provides [Android.mk file](
|
||||
https://github.com/fmtlib/fmt/blob/master/support/Android.mk) that can be used
|
||||
to build the library with [Android NDK](
|
||||
https://developer.android.com/tools/sdk/ndk/index.html).
|
||||
|
||||
### Other
|
||||
|
||||
To use the {fmt} library with any other build system, add
|
||||
`include/fmt/base.h`, `include/fmt/format.h`, `include/fmt/format-inl.h`,
|
||||
`src/format.cc` and optionally other headers from a [release archive](
|
||||
https://github.com/fmtlib/fmt/releases) or the [git repository](
|
||||
https://github.com/fmtlib/fmt) to your project, add `include` to include
|
||||
directories and make sure `src/format.cc` is compiled and linked with your code.
|
||||
Vendored
+151
@@ -0,0 +1,151 @@
|
||||
---
|
||||
hide:
|
||||
- navigation
|
||||
- toc
|
||||
---
|
||||
|
||||
# A modern formatting library
|
||||
|
||||
<div class="features-container">
|
||||
|
||||
<div class="feature">
|
||||
<h2>Safety</h2>
|
||||
<p>
|
||||
Inspired by Python's formatting facility, {fmt} provides a safe replacement
|
||||
for the <code>printf</code> family of functions. Errors in format strings,
|
||||
which are a common source of vulnerabilities in C, are <b>reported at
|
||||
compile time</b>. For example:
|
||||
|
||||
<pre><code class="language-cpp"
|
||||
>fmt::format("{:d}", "I am not a number");</code></pre>
|
||||
|
||||
will give a compile-time error because <code>d</code> is not a valid
|
||||
format specifier for strings. APIs like <a href="api/#format">
|
||||
<code>fmt::format</code></a> <b>prevent buffer overflow errors</b> via
|
||||
automatic memory management.
|
||||
</p>
|
||||
<a href="api#compile-time-checks">→ Learn more</a>
|
||||
</div>
|
||||
|
||||
<div class="feature">
|
||||
<h2>Extensibility</h2>
|
||||
<p>
|
||||
Formatting of most <b>standard types</b>, including all containers, dates,
|
||||
and times is <b>supported out-of-the-box</b>. For example:
|
||||
|
||||
<pre><code class="language-cpp"
|
||||
>fmt::print("{}", std::vector{1, 2, 3});</code></pre>
|
||||
|
||||
prints the vector in a JSON-like format:
|
||||
|
||||
<pre><code>[1, 2, 3]</code></pre>
|
||||
|
||||
You can <b>make your own types formattable</b> and even make compile-time
|
||||
checks work for them.
|
||||
</p>
|
||||
<a href="api#udt">→ Learn more</a>
|
||||
</div>
|
||||
|
||||
<div class="feature">
|
||||
<h2>Performance</h2>
|
||||
<p>
|
||||
{fmt} can be anywhere from <b>tens of percent to 20-30 times faster</b> than
|
||||
iostreams and <code>sprintf</code>, especially for numeric formatting.
|
||||
|
||||
<a href="https://github.com/fmtlib/fmt?tab=readme-ov-file#benchmarks">
|
||||
<img src="perf.svg">
|
||||
</a>
|
||||
|
||||
The library <b>minimizes dynamic memory allocations</b> and can optionally
|
||||
<a href="api#compile-api">compile format strings</a> to optimal code.
|
||||
</p>
|
||||
</div>
|
||||
|
||||
<div class="feature">
|
||||
<h2>Unicode support</h2>
|
||||
<p>
|
||||
{fmt} provides <b>portable Unicode support</b> on major operating systems
|
||||
with UTF-8 and <code>char</code> strings. For example:
|
||||
|
||||
<pre><code class="language-cpp"
|
||||
>fmt::print("Слава Україні!");</code></pre>
|
||||
|
||||
will be printed correctly on Linux, macOS, and even Windows console,
|
||||
irrespective of the codepages.
|
||||
</p>
|
||||
<p>
|
||||
The default is <b>locale-independent</b>, but you can opt into localized
|
||||
formatting and {fmt} makes it work with Unicode, addressing issues in the
|
||||
standard libary.
|
||||
</p>
|
||||
</div>
|
||||
|
||||
<div class="feature">
|
||||
<h2>Fast compilation</h2>
|
||||
<p>
|
||||
The library makes extensive use of <b>type erasure</b> to achieve fast
|
||||
compilation. <code>fmt/base.h</code> provides a subset of the API with
|
||||
<b>minimal include dependencies</b> and enough functionality to replace
|
||||
all uses of <code>*printf</code>.
|
||||
</p>
|
||||
<p>
|
||||
Code using {fmt} is usually several times faster to compile than the
|
||||
equivalent iostreams code, and while <code>printf</code> compiles faster
|
||||
still, the gap is narrowing.
|
||||
</p>
|
||||
<a href=
|
||||
"https://github.com/fmtlib/fmt?tab=readme-ov-file#compile-time-and-code-bloat">
|
||||
→ Learn more</a>
|
||||
</div>
|
||||
|
||||
<div class="feature">
|
||||
<h2>Small binary footprint</h2>
|
||||
<p>
|
||||
Type erasure is also used to prevent template bloat, resulting in <b>compact
|
||||
per-call binary code</b>. For example, a call to <code>fmt::print</code> with
|
||||
a single argument is just <a href="https://godbolt.org/g/TZU4KF">a few
|
||||
instructions</a>, comparable to <code>printf</code> despite adding
|
||||
runtime safety, and much smaller than the equivalent iostreams code.
|
||||
</p>
|
||||
<p>
|
||||
The library itself has small binary footprint and some components such as
|
||||
floating-point formatting can be disabled to make it even smaller for
|
||||
resource-constrained devices.
|
||||
</p>
|
||||
</div>
|
||||
|
||||
<div class="feature">
|
||||
<h2>Portability</h2>
|
||||
<p>
|
||||
{fmt} has a <b>small self-contained codebase</b> with the core consisting of
|
||||
just three headers and no external dependencies.
|
||||
</p>
|
||||
<p>
|
||||
The library is highly portable and requires only a minimal <b>subset of
|
||||
C++11</b> features which are available in GCC 4.9, Clang 3.6, MSVC 19.10
|
||||
(2017) and later. Newer compiler and standard library features are used
|
||||
if available, and enable additional functionality.
|
||||
</p>
|
||||
<p>
|
||||
Where possible, the output of formatting functions is <b>consistent across
|
||||
platforms</b>.
|
||||
</p>
|
||||
</p>
|
||||
</div>
|
||||
|
||||
<div class="feature">
|
||||
<h2>Open source</h2>
|
||||
<p>
|
||||
{fmt} is in the top hundred open-source C++ libraries on GitHub and has
|
||||
<a href="https://github.com/fmtlib/fmt/graphs/contributors">hundreds of
|
||||
all-time contributors</a>.
|
||||
</p>
|
||||
<p>
|
||||
The library is distributed under a permissive MIT
|
||||
<a href="https://github.com/fmtlib/fmt#license">license</a> and is
|
||||
<b>relied upon by many open-source projects</b>, including Blender, PyTorch,
|
||||
Apple's FoundationDB, Windows Terminal, MongoDB, and others.
|
||||
</p>
|
||||
</div>
|
||||
|
||||
</div>
|
||||
Vendored
+1
@@ -0,0 +1 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" version="1.1" viewBox="20 0 550 300" aria-label="A chart." style="overflow: hidden;"><defs id="_ABSTRACT_RENDERER_ID_0"><clipPath id="_ABSTRACT_RENDERER_ID_1"><rect x="120" y="45" width="560" height="210"></rect></clipPath></defs><rect x="0" y="0" width="800" height="300" stroke="none" stroke-width="0" fill="#ffffff"></rect><g><text text-anchor="start" x="120" y="27.05" font-family="Arial" font-size="13" font-weight="bold" stroke="none" stroke-width="0" fill="#000000">double to string</text><rect x="120" y="16" width="560" height="13" stroke="none" stroke-width="0" fill-opacity="0" fill="#ffffff"></rect></g><g><rect x="120" y="45" width="560" height="210" stroke="none" stroke-width="0" fill-opacity="0" fill="#ffffff"></rect><g clip-path="url(#_ABSTRACT_RENDERER_ID_1)"><g><rect x="120" y="45" width="1" height="210" stroke="none" stroke-width="0" fill="#cccccc"></rect><rect x="213" y="45" width="1" height="210" stroke="none" stroke-width="0" fill="#cccccc"></rect><rect x="306" y="45" width="1" height="210" stroke="none" stroke-width="0" fill="#cccccc"></rect><rect x="400" y="45" width="1" height="210" stroke="none" stroke-width="0" fill="#cccccc"></rect><rect x="493" y="45" width="1" height="210" stroke="none" stroke-width="0" fill="#cccccc"></rect><rect x="586" y="45" width="1" height="210" stroke="none" stroke-width="0" fill="#cccccc"></rect><rect x="679" y="45" width="1" height="210" stroke="none" stroke-width="0" fill="#cccccc"></rect></g><g><rect x="121" y="53" width="450" height="26" stroke="#ff9900" stroke-width="1" fill="#ff9900"></rect><rect x="121" y="95" width="421" height="26" stroke="#109618" stroke-width="1" fill="#109618"></rect><rect x="121" y="137" width="341" height="26" stroke="#990099" stroke-width="1" fill="#990099"></rect><rect x="121" y="179" width="31" height="26" stroke="#3366cc" stroke-width="1" fill="#3366cc"></rect><rect x="121" y="221" width="15" height="26" stroke="#dc3912" stroke-width="1" fill="#dc3912"></rect></g><g><rect x="120" y="45" width="1" height="210" stroke="none" stroke-width="0" fill="#333333"></rect></g></g><g></g><g><g><text text-anchor="middle" x="120.5" y="272.3833333333333" font-family="Arial" font-size="13" stroke="none" stroke-width="0" fill="#444444">0</text></g><g><text text-anchor="middle" x="213.6667" y="272.3833333333333" font-family="Arial" font-size="13" stroke="none" stroke-width="0" fill="#444444">250</text></g><g><text text-anchor="middle" x="306.8333" y="272.3833333333333" font-family="Arial" font-size="13" stroke="none" stroke-width="0" fill="#444444">500</text></g><g><text text-anchor="middle" x="400" y="272.3833333333333" font-family="Arial" font-size="13" stroke="none" stroke-width="0" fill="#444444">750</text></g><g><text text-anchor="middle" x="493.1667" y="272.3833333333333" font-family="Arial" font-size="13" stroke="none" stroke-width="0" fill="#444444">1,000</text></g><g><text text-anchor="middle" x="586.3333" y="272.3833333333333" font-family="Arial" font-size="13" stroke="none" stroke-width="0" fill="#444444">1,250</text></g><g><text text-anchor="middle" x="679.5" y="272.3833333333333" font-family="Arial" font-size="13" stroke="none" stroke-width="0" fill="#444444">1,500</text></g><g><text text-anchor="end" x="107" y="70.95" font-family="Arial" font-size="13" stroke="none" stroke-width="0" fill="#222222">ostringstream</text></g><g><text text-anchor="end" x="107" y="112.74999999999999" font-family="Arial" font-size="13" stroke="none" stroke-width="0" fill="#222222">ostrstream</text></g><g><text text-anchor="end" x="107" y="154.55" font-family="Arial" font-size="13" stroke="none" stroke-width="0" fill="#222222">sprintf</text></g><g><text text-anchor="end" x="107" y="196.35" font-family="Arial" font-size="13" stroke="none" stroke-width="0" fill="#222222">doubleconv</text></g><g><text text-anchor="end" x="107" y="238.15" font-family="Arial" font-size="13" stroke="none" stroke-width="0" fill="#222222">fmt</text></g></g></g><g><g><text text-anchor="middle" x="300" y="291.71666666666664" font-family="Arial" font-size="13" font-style="italic" stroke="none" stroke-width="0" fill="#222222">Time (ns), smaller is better</text><rect x="120" y="280.66666666666663" width="560" height="13" stroke="none" stroke-width="0" fill-opacity="0" fill="#ffffff"></rect></g></g><g></g></svg>
|
||||
|
After Width: | Height: | Size: 4.3 KiB |
+290
@@ -0,0 +1,290 @@
|
||||
A. HISTORY OF THE SOFTWARE
|
||||
==========================
|
||||
|
||||
Python was created in the early 1990s by Guido van Rossum at Stichting
|
||||
Mathematisch Centrum (CWI, see http://www.cwi.nl) in the Netherlands
|
||||
as a successor of a language called ABC. Guido remains Python's
|
||||
principal author, although it includes many contributions from others.
|
||||
|
||||
In 1995, Guido continued his work on Python at the Corporation for
|
||||
National Research Initiatives (CNRI, see http://www.cnri.reston.va.us)
|
||||
in Reston, Virginia where he released several versions of the
|
||||
software.
|
||||
|
||||
In May 2000, Guido and the Python core development team moved to
|
||||
BeOpen.com to form the BeOpen PythonLabs team. In October of the same
|
||||
year, the PythonLabs team moved to Digital Creations (now Zope
|
||||
Corporation, see http://www.zope.com). In 2001, the Python Software
|
||||
Foundation (PSF, see http://www.python.org/psf/) was formed, a
|
||||
non-profit organization created specifically to own Python-related
|
||||
Intellectual Property. Zope Corporation is a sponsoring member of
|
||||
the PSF.
|
||||
|
||||
All Python releases are Open Source (see http://www.opensource.org for
|
||||
the Open Source Definition). Historically, most, but not all, Python
|
||||
releases have also been GPL-compatible; the table below summarizes
|
||||
the various releases.
|
||||
|
||||
Release Derived Year Owner GPL-
|
||||
from compatible? (1)
|
||||
|
||||
0.9.0 thru 1.2 1991-1995 CWI yes
|
||||
1.3 thru 1.5.2 1.2 1995-1999 CNRI yes
|
||||
1.6 1.5.2 2000 CNRI no
|
||||
2.0 1.6 2000 BeOpen.com no
|
||||
1.6.1 1.6 2001 CNRI yes (2)
|
||||
2.1 2.0+1.6.1 2001 PSF no
|
||||
2.0.1 2.0+1.6.1 2001 PSF yes
|
||||
2.1.1 2.1+2.0.1 2001 PSF yes
|
||||
2.2 2.1.1 2001 PSF yes
|
||||
2.1.2 2.1.1 2002 PSF yes
|
||||
2.1.3 2.1.2 2002 PSF yes
|
||||
2.2.1 2.2 2002 PSF yes
|
||||
2.2.2 2.2.1 2002 PSF yes
|
||||
2.2.3 2.2.2 2003 PSF yes
|
||||
2.3 2.2.2 2002-2003 PSF yes
|
||||
2.3.1 2.3 2002-2003 PSF yes
|
||||
2.3.2 2.3.1 2002-2003 PSF yes
|
||||
2.3.3 2.3.2 2002-2003 PSF yes
|
||||
2.3.4 2.3.3 2004 PSF yes
|
||||
2.3.5 2.3.4 2005 PSF yes
|
||||
2.4 2.3 2004 PSF yes
|
||||
2.4.1 2.4 2005 PSF yes
|
||||
2.4.2 2.4.1 2005 PSF yes
|
||||
2.4.3 2.4.2 2006 PSF yes
|
||||
2.4.4 2.4.3 2006 PSF yes
|
||||
2.5 2.4 2006 PSF yes
|
||||
2.5.1 2.5 2007 PSF yes
|
||||
2.5.2 2.5.1 2008 PSF yes
|
||||
2.5.3 2.5.2 2008 PSF yes
|
||||
2.6 2.5 2008 PSF yes
|
||||
2.6.1 2.6 2008 PSF yes
|
||||
2.6.2 2.6.1 2009 PSF yes
|
||||
2.6.3 2.6.2 2009 PSF yes
|
||||
2.6.4 2.6.3 2009 PSF yes
|
||||
2.6.5 2.6.4 2010 PSF yes
|
||||
3.0 2.6 2008 PSF yes
|
||||
3.0.1 3.0 2009 PSF yes
|
||||
3.1 3.0.1 2009 PSF yes
|
||||
3.1.1 3.1 2009 PSF yes
|
||||
3.1.2 3.1.1 2010 PSF yes
|
||||
3.1.3 3.1.2 2010 PSF yes
|
||||
3.1.4 3.1.3 2011 PSF yes
|
||||
3.2 3.1 2011 PSF yes
|
||||
3.2.1 3.2 2011 PSF yes
|
||||
3.2.2 3.2.1 2011 PSF yes
|
||||
3.2.3 3.2.2 2012 PSF yes
|
||||
3.3.0 3.2 2012 PSF yes
|
||||
|
||||
Footnotes:
|
||||
|
||||
(1) GPL-compatible doesn't mean that we're distributing Python under
|
||||
the GPL. All Python licenses, unlike the GPL, let you distribute
|
||||
a modified version without making your changes open source. The
|
||||
GPL-compatible licenses make it possible to combine Python with
|
||||
other software that is released under the GPL; the others don't.
|
||||
|
||||
(2) According to Richard Stallman, 1.6.1 is not GPL-compatible,
|
||||
because its license has a choice of law clause. According to
|
||||
CNRI, however, Stallman's lawyer has told CNRI's lawyer that 1.6.1
|
||||
is "not incompatible" with the GPL.
|
||||
|
||||
Thanks to the many outside volunteers who have worked under Guido's
|
||||
direction to make these releases possible.
|
||||
|
||||
|
||||
B. TERMS AND CONDITIONS FOR ACCESSING OR OTHERWISE USING PYTHON
|
||||
===============================================================
|
||||
|
||||
PYTHON SOFTWARE FOUNDATION LICENSE VERSION 2
|
||||
--------------------------------------------
|
||||
|
||||
1. This LICENSE AGREEMENT is between the Python Software Foundation
|
||||
("PSF"), and the Individual or Organization ("Licensee") accessing and
|
||||
otherwise using this software ("Python") in source or binary form and
|
||||
its associated documentation.
|
||||
|
||||
2. Subject to the terms and conditions of this License Agreement, PSF hereby
|
||||
grants Licensee a nonexclusive, royalty-free, world-wide license to reproduce,
|
||||
analyze, test, perform and/or display publicly, prepare derivative works,
|
||||
distribute, and otherwise use Python alone or in any derivative version,
|
||||
provided, however, that PSF's License Agreement and PSF's notice of copyright,
|
||||
i.e., "Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010,
|
||||
2011, 2012 Python Software Foundation; All Rights Reserved" are retained in Python
|
||||
alone or in any derivative version prepared by Licensee.
|
||||
|
||||
3. In the event Licensee prepares a derivative work that is based on
|
||||
or incorporates Python or any part thereof, and wants to make
|
||||
the derivative work available to others as provided herein, then
|
||||
Licensee hereby agrees to include in any such work a brief summary of
|
||||
the changes made to Python.
|
||||
|
||||
4. PSF is making Python available to Licensee on an "AS IS"
|
||||
basis. PSF MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR
|
||||
IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, PSF MAKES NO AND
|
||||
DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS
|
||||
FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF PYTHON WILL NOT
|
||||
INFRINGE ANY THIRD PARTY RIGHTS.
|
||||
|
||||
5. PSF SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON
|
||||
FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS
|
||||
A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON,
|
||||
OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.
|
||||
|
||||
6. This License Agreement will automatically terminate upon a material
|
||||
breach of its terms and conditions.
|
||||
|
||||
7. Nothing in this License Agreement shall be deemed to create any
|
||||
relationship of agency, partnership, or joint venture between PSF and
|
||||
Licensee. This License Agreement does not grant permission to use PSF
|
||||
trademarks or trade name in a trademark sense to endorse or promote
|
||||
products or services of Licensee, or any third party.
|
||||
|
||||
8. By copying, installing or otherwise using Python, Licensee
|
||||
agrees to be bound by the terms and conditions of this License
|
||||
Agreement.
|
||||
|
||||
|
||||
BEOPEN.COM LICENSE AGREEMENT FOR PYTHON 2.0
|
||||
-------------------------------------------
|
||||
|
||||
BEOPEN PYTHON OPEN SOURCE LICENSE AGREEMENT VERSION 1
|
||||
|
||||
1. This LICENSE AGREEMENT is between BeOpen.com ("BeOpen"), having an
|
||||
office at 160 Saratoga Avenue, Santa Clara, CA 95051, and the
|
||||
Individual or Organization ("Licensee") accessing and otherwise using
|
||||
this software in source or binary form and its associated
|
||||
documentation ("the Software").
|
||||
|
||||
2. Subject to the terms and conditions of this BeOpen Python License
|
||||
Agreement, BeOpen hereby grants Licensee a non-exclusive,
|
||||
royalty-free, world-wide license to reproduce, analyze, test, perform
|
||||
and/or display publicly, prepare derivative works, distribute, and
|
||||
otherwise use the Software alone or in any derivative version,
|
||||
provided, however, that the BeOpen Python License is retained in the
|
||||
Software, alone or in any derivative version prepared by Licensee.
|
||||
|
||||
3. BeOpen is making the Software available to Licensee on an "AS IS"
|
||||
basis. BEOPEN MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR
|
||||
IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, BEOPEN MAKES NO AND
|
||||
DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS
|
||||
FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF THE SOFTWARE WILL NOT
|
||||
INFRINGE ANY THIRD PARTY RIGHTS.
|
||||
|
||||
4. BEOPEN SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF THE
|
||||
SOFTWARE FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS
|
||||
AS A RESULT OF USING, MODIFYING OR DISTRIBUTING THE SOFTWARE, OR ANY
|
||||
DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.
|
||||
|
||||
5. This License Agreement will automatically terminate upon a material
|
||||
breach of its terms and conditions.
|
||||
|
||||
6. This License Agreement shall be governed by and interpreted in all
|
||||
respects by the law of the State of California, excluding conflict of
|
||||
law provisions. Nothing in this License Agreement shall be deemed to
|
||||
create any relationship of agency, partnership, or joint venture
|
||||
between BeOpen and Licensee. This License Agreement does not grant
|
||||
permission to use BeOpen trademarks or trade names in a trademark
|
||||
sense to endorse or promote products or services of Licensee, or any
|
||||
third party. As an exception, the "BeOpen Python" logos available at
|
||||
http://www.pythonlabs.com/logos.html may be used according to the
|
||||
permissions granted on that web page.
|
||||
|
||||
7. By copying, installing or otherwise using the software, Licensee
|
||||
agrees to be bound by the terms and conditions of this License
|
||||
Agreement.
|
||||
|
||||
|
||||
CNRI LICENSE AGREEMENT FOR PYTHON 1.6.1
|
||||
---------------------------------------
|
||||
|
||||
1. This LICENSE AGREEMENT is between the Corporation for National
|
||||
Research Initiatives, having an office at 1895 Preston White Drive,
|
||||
Reston, VA 20191 ("CNRI"), and the Individual or Organization
|
||||
("Licensee") accessing and otherwise using Python 1.6.1 software in
|
||||
source or binary form and its associated documentation.
|
||||
|
||||
2. Subject to the terms and conditions of this License Agreement, CNRI
|
||||
hereby grants Licensee a nonexclusive, royalty-free, world-wide
|
||||
license to reproduce, analyze, test, perform and/or display publicly,
|
||||
prepare derivative works, distribute, and otherwise use Python 1.6.1
|
||||
alone or in any derivative version, provided, however, that CNRI's
|
||||
License Agreement and CNRI's notice of copyright, i.e., "Copyright (c)
|
||||
1995-2001 Corporation for National Research Initiatives; All Rights
|
||||
Reserved" are retained in Python 1.6.1 alone or in any derivative
|
||||
version prepared by Licensee. Alternately, in lieu of CNRI's License
|
||||
Agreement, Licensee may substitute the following text (omitting the
|
||||
quotes): "Python 1.6.1 is made available subject to the terms and
|
||||
conditions in CNRI's License Agreement. This Agreement together with
|
||||
Python 1.6.1 may be located on the Internet using the following
|
||||
unique, persistent identifier (known as a handle): 1895.22/1013. This
|
||||
Agreement may also be obtained from a proxy server on the Internet
|
||||
using the following URL: http://hdl.handle.net/1895.22/1013".
|
||||
|
||||
3. In the event Licensee prepares a derivative work that is based on
|
||||
or incorporates Python 1.6.1 or any part thereof, and wants to make
|
||||
the derivative work available to others as provided herein, then
|
||||
Licensee hereby agrees to include in any such work a brief summary of
|
||||
the changes made to Python 1.6.1.
|
||||
|
||||
4. CNRI is making Python 1.6.1 available to Licensee on an "AS IS"
|
||||
basis. CNRI MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR
|
||||
IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, CNRI MAKES NO AND
|
||||
DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS
|
||||
FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF PYTHON 1.6.1 WILL NOT
|
||||
INFRINGE ANY THIRD PARTY RIGHTS.
|
||||
|
||||
5. CNRI SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON
|
||||
1.6.1 FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS
|
||||
A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON 1.6.1,
|
||||
OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.
|
||||
|
||||
6. This License Agreement will automatically terminate upon a material
|
||||
breach of its terms and conditions.
|
||||
|
||||
7. This License Agreement shall be governed by the federal
|
||||
intellectual property law of the United States, including without
|
||||
limitation the federal copyright law, and, to the extent such
|
||||
U.S. federal law does not apply, by the law of the Commonwealth of
|
||||
Virginia, excluding Virginia's conflict of law provisions.
|
||||
Notwithstanding the foregoing, with regard to derivative works based
|
||||
on Python 1.6.1 that incorporate non-separable material that was
|
||||
previously distributed under the GNU General Public License (GPL), the
|
||||
law of the Commonwealth of Virginia shall govern this License
|
||||
Agreement only as to issues arising under or with respect to
|
||||
Paragraphs 4, 5, and 7 of this License Agreement. Nothing in this
|
||||
License Agreement shall be deemed to create any relationship of
|
||||
agency, partnership, or joint venture between CNRI and Licensee. This
|
||||
License Agreement does not grant permission to use CNRI trademarks or
|
||||
trade name in a trademark sense to endorse or promote products or
|
||||
services of Licensee, or any third party.
|
||||
|
||||
8. By clicking on the "ACCEPT" button where indicated, or by copying,
|
||||
installing or otherwise using Python 1.6.1, Licensee agrees to be
|
||||
bound by the terms and conditions of this License Agreement.
|
||||
|
||||
ACCEPT
|
||||
|
||||
|
||||
CWI LICENSE AGREEMENT FOR PYTHON 0.9.0 THROUGH 1.2
|
||||
--------------------------------------------------
|
||||
|
||||
Copyright (c) 1991 - 1995, Stichting Mathematisch Centrum Amsterdam,
|
||||
The Netherlands. All rights reserved.
|
||||
|
||||
Permission to use, copy, modify, and distribute this software and its
|
||||
documentation for any purpose and without fee is hereby granted,
|
||||
provided that the above copyright notice appear in all copies and that
|
||||
both that copyright notice and this permission notice appear in
|
||||
supporting documentation, and that the name of Stichting Mathematisch
|
||||
Centrum or CWI not be used in advertising or publicity pertaining to
|
||||
distribution of the software without specific, written prior
|
||||
permission.
|
||||
|
||||
STICHTING MATHEMATISCH CENTRUM DISCLAIMS ALL WARRANTIES WITH REGARD TO
|
||||
THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
|
||||
FITNESS, IN NO EVENT SHALL STICHTING MATHEMATISCH CENTRUM BE LIABLE
|
||||
FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
|
||||
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
|
||||
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
|
||||
OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
Vendored
+886
@@ -0,0 +1,886 @@
|
||||
# Format String Syntax
|
||||
|
||||
Formatting functions such as [`fmt::format`](api.md#format) and [`fmt::print`](
|
||||
api.md#print) use the same format string syntax described in this section.
|
||||
|
||||
Format strings contain "replacement fields" surrounded by curly braces `{}`.
|
||||
Anything that is not contained in braces is considered literal text, which is
|
||||
copied unchanged to the output. If you need to include a brace character in
|
||||
the literal text, it can be escaped by doubling: `{{` and `}}`.
|
||||
|
||||
The grammar for a replacement field is as follows:
|
||||
|
||||
<a id="replacement-field"></a>
|
||||
<pre><code class="language-json"
|
||||
>replacement_field ::= "{" [arg_id] [":" (<a href="#format-spec"
|
||||
>format_spec</a> | <a href="#chrono-format-spec">chrono_format_spec</a>)] "}"
|
||||
arg_id ::= integer | identifier
|
||||
integer ::= digit+
|
||||
digit ::= "0"..."9"
|
||||
identifier ::= id_start id_continue*
|
||||
id_start ::= "a"..."z" | "A"..."Z" | "_"
|
||||
id_continue ::= id_start | digit</code>
|
||||
</pre>
|
||||
|
||||
In less formal terms, the replacement field can start with an *arg_id* that
|
||||
specifies the argument whose value is to be formatted and inserted into the
|
||||
output instead of the replacement field. The *arg_id* is optionally followed
|
||||
by a *format_spec*, which is preceded by a colon `':'`. These specify a
|
||||
non-default format for the replacement value.
|
||||
|
||||
See also the [Format Specification
|
||||
Mini-Language](#format-specification-mini-language) section.
|
||||
|
||||
If the numerical arg_ids in a format string are 0, 1, 2, ... in sequence,
|
||||
they can all be omitted (not just some) and the numbers 0, 1, 2, ... will be
|
||||
automatically inserted in that order.
|
||||
|
||||
Named arguments can be referred to by their names or indices.
|
||||
|
||||
Some simple format string examples:
|
||||
|
||||
```c++
|
||||
"First, thou shalt count to {0}" // References the first argument
|
||||
"Bring me a {}" // Implicitly references the first argument
|
||||
"From {} to {}" // Same as "From {0} to {1}"
|
||||
```
|
||||
|
||||
The *format_spec* field contains a specification of how the value should
|
||||
be presented, including such details as field width, alignment, padding,
|
||||
decimal precision and so on. Each value type can define its own
|
||||
"formatting mini-language" or interpretation of the *format_spec*.
|
||||
|
||||
Most built-in types support a common formatting mini-language, which is
|
||||
described in the next section.
|
||||
|
||||
A *format_spec* field can also include nested replacement fields in
|
||||
certain positions within it. These nested replacement fields can contain
|
||||
only an argument id; format specifications are not allowed. This allows
|
||||
the formatting of a value to be dynamically specified.
|
||||
|
||||
See the [Format Examples](#format-examples) section for some examples.
|
||||
|
||||
## Format Specification Mini-Language
|
||||
|
||||
"Format specifications" are used within replacement fields contained within a
|
||||
format string to define how individual values are presented. Each formattable
|
||||
type may define how the format specification is to be interpreted.
|
||||
|
||||
Most built-in types implement the following options for format
|
||||
specifications, although some of the formatting options are only
|
||||
supported by the numeric types.
|
||||
|
||||
The general form of a *standard format specifier* is:
|
||||
|
||||
<a id="format-spec"></a>
|
||||
<pre><code class="language-json"
|
||||
>format_spec ::= [[fill]align][sign]["#"]["0"][width]["." precision]["L"][type]
|
||||
fill ::= <a character other than '{' or '}'>
|
||||
align ::= "<" | ">" | "^"
|
||||
sign ::= "+" | "-" | " "
|
||||
width ::= <a href="#replacement-field">integer</a> | "{" [<a
|
||||
href="#replacement-field">arg_id</a>] "}"
|
||||
precision ::= <a href="#replacement-field">integer</a> | "{" [<a
|
||||
href="#replacement-field">arg_id</a>] "}"
|
||||
type ::= "a" | "A" | "b" | "B" | "c" | "d" | "e" | "E" | "f" | "F" |
|
||||
"g" | "G" | "o" | "p" | "s" | "x" | "X" | "?"</code>
|
||||
</pre>
|
||||
|
||||
The *fill* character can be any Unicode code point other than `'{'` or `'}'`.
|
||||
The presence of a fill character is signaled by the character following it,
|
||||
which must be one of the alignment options. If the second character of
|
||||
*format_spec* is not a valid alignment option, then it is assumed that both
|
||||
the fill character and the alignment option are absent.
|
||||
|
||||
The meaning of the various alignment options is as follows:
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th>Option</th>
|
||||
<th>Meaning</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'<'</code></td>
|
||||
<td>
|
||||
Forces the field to be left-aligned within the available space (this is the
|
||||
default for most objects).
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'>'</code></td>
|
||||
<td>
|
||||
Forces the field to be right-aligned within the available space (this is
|
||||
the default for numbers).
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'^'</code></td>
|
||||
<td>Forces the field to be centered within the available space.</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
Note that unless a minimum field width is defined, the field width will
|
||||
always be the same size as the data to fill it, so that the alignment
|
||||
option has no meaning in this case.
|
||||
|
||||
The *sign* option is only valid for floating point and signed integer types,
|
||||
and can be one of the following:
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th>Option</th>
|
||||
<th>Meaning</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'+'</code></td>
|
||||
<td>
|
||||
Indicates that a sign should be used for both nonnegative as well as
|
||||
negative numbers.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'-'</code></td>
|
||||
<td>
|
||||
Indicates that a sign should be used only for negative numbers (this is the
|
||||
default behavior).
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>space</td>
|
||||
<td>
|
||||
Indicates that a leading space should be used on nonnegative numbers, and a
|
||||
minus sign on negative numbers.
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
The `'#'` option causes the "alternate form" to be used for the
|
||||
conversion. The alternate form is defined differently for different
|
||||
types. This option is only valid for integer and floating-point types.
|
||||
For integers, when binary, octal, or hexadecimal output is used, this
|
||||
option adds the prefix respective `"0b"` (`"0B"`), `"0"`, or `"0x"`
|
||||
(`"0X"`) to the output value. Whether the prefix is lower-case or
|
||||
upper-case is determined by the case of the type specifier, for example,
|
||||
the prefix `"0x"` is used for the type `'x'` and `"0X"` is used for
|
||||
`'X'`. For floating-point numbers the alternate form causes the result
|
||||
of the conversion to always contain a decimal-point character, even if
|
||||
no digits follow it. Normally, a decimal-point character appears in the
|
||||
result of these conversions only if a digit follows it. In addition, for
|
||||
`'g'` and `'G'` conversions, trailing zeros are not removed from the
|
||||
result.
|
||||
|
||||
*width* is a decimal integer defining the minimum field width. If not
|
||||
specified, then the field width will be determined by the content.
|
||||
|
||||
Preceding the *width* field by a zero (`'0'`) character enables
|
||||
sign-aware zero-padding for numeric types. It forces the padding to be
|
||||
placed after the sign or base (if any) but before the digits. This is
|
||||
used for printing fields in the form "+000000120". This option is only
|
||||
valid for numeric types and it has no effect on formatting of infinity
|
||||
and NaN. This option is ignored when any alignment specifier is present.
|
||||
|
||||
The *precision* is a decimal number indicating how many digits should be
|
||||
displayed after the decimal point for a floating-point value formatted
|
||||
with `'f'` and `'F'`, or before and after the decimal point for a
|
||||
floating-point value formatted with `'g'` or `'G'`. For non-number types
|
||||
the field indicates the maximum field size - in other words, how many
|
||||
characters will be used from the field content. The *precision* is not
|
||||
allowed for integer, character, Boolean, and pointer values. Note that a
|
||||
C string must be null-terminated even if precision is specified.
|
||||
|
||||
The `'L'` option uses the current locale setting to insert the appropriate
|
||||
number separator characters. This option is only valid for numeric types.
|
||||
|
||||
Finally, the *type* determines how the data should be presented.
|
||||
|
||||
The available string presentation types are:
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th>Type</th>
|
||||
<th>Meaning</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'s'</code></td>
|
||||
<td>
|
||||
String format. This is the default type for strings and may be omitted.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'?'</code></td>
|
||||
<td>Debug format. The string is quoted and special characters escaped.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>none</td>
|
||||
<td>The same as <code>'s'</code>.</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
The available character presentation types are:
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th>Type</th>
|
||||
<th>Meaning</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'c'</code></td>
|
||||
<td>
|
||||
Character format. This is the default type for characters and may be
|
||||
omitted.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'?'</code></td>
|
||||
<td>Debug format. The character is quoted and special characters escaped.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>none</td>
|
||||
<td>The same as <code>'c'</code>.</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
The available integer presentation types are:
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th>Type</th>
|
||||
<th>Meaning</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'b'</code></td>
|
||||
<td>
|
||||
Binary format. Outputs the number in base 2. Using the <code>'#'</code>
|
||||
option with this type adds the prefix <code>"0b"</code> to the output value.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'B'</code></td>
|
||||
<td>
|
||||
Binary format. Outputs the number in base 2. Using the <code>'#'</code>
|
||||
option with this type adds the prefix <code>"0B"</code> to the output value.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'c'</code></td>
|
||||
<td>Character format. Outputs the number as a character.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'d'</code></td>
|
||||
<td>Decimal integer. Outputs the number in base 10.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'o'</code></td>
|
||||
<td>Octal format. Outputs the number in base 8.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'x'</code></td>
|
||||
<td>
|
||||
Hex format. Outputs the number in base 16, using lower-case letters for the
|
||||
digits above 9. Using the <code>'#'</code> option with this type adds the
|
||||
prefix <code>"0x"</code> to the output value.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'X'</code></td>
|
||||
<td>
|
||||
Hex format. Outputs the number in base 16, using upper-case letters for the
|
||||
digits above 9. Using the <code>'#'</code> option with this type adds the
|
||||
prefix <code>"0X"</code> to the output value.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>none</td>
|
||||
<td>The same as <code>'d'</code>.</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
Integer presentation types can also be used with character and Boolean values
|
||||
with the only exception that `'c'` cannot be used with `bool`. Boolean values
|
||||
are formatted using textual representation, either `true` or `false`, if the
|
||||
presentation type is not specified.
|
||||
|
||||
The available presentation types for floating-point values are:
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th>Type</th>
|
||||
<th>Meaning</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'a'</code></td>
|
||||
<td>
|
||||
Hexadecimal floating point format. Prints the number in base 16 with
|
||||
prefix <code>"0x"</code> and lower-case letters for digits above 9.
|
||||
Uses <code>'p'</code> to indicate the exponent.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'A'</code></td>
|
||||
<td>
|
||||
Same as <code>'a'</code> except it uses upper-case letters for the
|
||||
prefix, digits above 9 and to indicate the exponent.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'e'</code></td>
|
||||
<td>
|
||||
Exponent notation. Prints the number in scientific notation using
|
||||
the letter 'e' to indicate the exponent.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'E'</code></td>
|
||||
<td>
|
||||
Exponent notation. Same as <code>'e'</code> except it uses an
|
||||
upper-case <code>'E'</code> as the separator character.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'f'</code></td>
|
||||
<td>Fixed point. Displays the number as a fixed-point number.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'F'</code></td>
|
||||
<td>
|
||||
Fixed point. Same as <code>'f'</code>, but converts <code>nan</code>
|
||||
to <code>NAN</code> and <code>inf</code> to <code>INF</code>.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'g'</code></td>
|
||||
<td>
|
||||
<p>General format. For a given precision <code>p >= 1</code>,
|
||||
this rounds the number to <code>p</code> significant digits and then
|
||||
formats the result in either fixed-point format or in scientific
|
||||
notation, depending on its magnitude.</p>
|
||||
<p>A precision of <code>0</code> is treated as equivalent to a precision
|
||||
of <code>1</code>.</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'G'</code></td>
|
||||
<td>
|
||||
General format. Same as <code>'g'</code> except switches to
|
||||
<code>'E'</code> if the number gets too large. The representations of
|
||||
infinity and NaN are uppercased, too.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>none</td>
|
||||
<td>
|
||||
Similar to <code>'g'</code>, except that the default precision is as
|
||||
high as needed to represent the particular value.
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
The available presentation types for pointers are:
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th>Type</th>
|
||||
<th>Meaning</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'p'</code></td>
|
||||
<td>
|
||||
Pointer format. This is the default type for pointers and may be omitted.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>none</td>
|
||||
<td>The same as <code>'p'</code>.</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
## Chrono Format Specifications
|
||||
|
||||
Format specifications for chrono duration and time point types as well as
|
||||
`std::tm` have the following syntax:
|
||||
|
||||
<a id="chrono-format-spec"></a>
|
||||
<pre><code class="language-json"
|
||||
>chrono_format_spec ::= [[<a href="#format-spec">fill</a>]<a href="#format-spec"
|
||||
>align</a>][<a href="#format-spec">width</a>]["." <a href="#format-spec"
|
||||
>precision</a>][chrono_specs]
|
||||
chrono_specs ::= conversion_spec |
|
||||
chrono_specs (conversion_spec | literal_char)
|
||||
conversion_spec ::= "%" [padding_modifier] [locale_modifier] chrono_type
|
||||
literal_char ::= <a character other than '{', '}' or '%'>
|
||||
padding_modifier ::= "-" | "_" | "0"
|
||||
locale_modifier ::= "E" | "O"
|
||||
chrono_type ::= "a" | "A" | "b" | "B" | "c" | "C" | "d" | "D" | "e" |
|
||||
"F" | "g" | "G" | "h" | "H" | "I" | "j" | "m" | "M" |
|
||||
"n" | "p" | "q" | "Q" | "r" | "R" | "S" | "t" | "T" |
|
||||
"u" | "U" | "V" | "w" | "W" | "x" | "X" | "y" | "Y" |
|
||||
"z" | "Z" | "%"</code>
|
||||
</pre>
|
||||
|
||||
Literal chars are copied unchanged to the output. Precision is valid only
|
||||
for `std::chrono::duration` types with a floating-point representation type.
|
||||
|
||||
The available presentation types (*chrono_type*) are:
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th>Type</th>
|
||||
<th>Meaning</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'a'</code></td>
|
||||
<td>
|
||||
The abbreviated weekday name, e.g. "Sat". If the value does not contain a
|
||||
valid weekday, an exception of type <code>format_error</code> is thrown.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'A'</code></td>
|
||||
<td>
|
||||
The full weekday name, e.g. "Saturday". If the value does not contain a
|
||||
valid weekday, an exception of type <code>format_error</code> is thrown.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'b'</code></td>
|
||||
<td>
|
||||
The abbreviated month name, e.g. "Nov". If the value does not contain a
|
||||
valid month, an exception of type <code>format_error</code> is thrown.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'B'</code></td>
|
||||
<td>
|
||||
The full month name, e.g. "November". If the value does not contain a valid
|
||||
month, an exception of type <code>format_error</code> is thrown.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'c'</code></td>
|
||||
<td>
|
||||
The date and time representation, e.g. "Sat Nov 12 22:04:00 1955". The
|
||||
modified command <code>%Ec</code> produces the locale's alternate date and
|
||||
time representation.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'C'</code></td>
|
||||
<td>
|
||||
The year divided by 100 using floored division, e.g. "19". If the result
|
||||
is a single decimal digit, it is prefixed with 0. The modified command
|
||||
<code>%EC</code> produces the locale's alternative representation of the
|
||||
century.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'d'</code></td>
|
||||
<td>
|
||||
The day of month as a decimal number. If the result is a single decimal
|
||||
digit, it is prefixed with 0. The modified command <code>%Od</code>
|
||||
produces the locale's alternative representation.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'D'</code></td>
|
||||
<td>Equivalent to <code>%m/%d/%y</code>, e.g. "11/12/55".</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'e'</code></td>
|
||||
<td>
|
||||
The day of month as a decimal number. If the result is a single decimal
|
||||
digit, it is prefixed with a space. The modified command <code>%Oe</code>
|
||||
produces the locale's alternative representation.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'F'</code></td>
|
||||
<td>Equivalent to <code>%Y-%m-%d</code>, e.g. "1955-11-12".</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'g'</code></td>
|
||||
<td>
|
||||
The last two decimal digits of the ISO week-based year. If the result is a
|
||||
single digit it is prefixed by 0.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'G'</code></td>
|
||||
<td>
|
||||
The ISO week-based year as a decimal number. If the result is less than
|
||||
four digits it is left-padded with 0 to four digits.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'h'</code></td>
|
||||
<td>Equivalent to <code>%b</code>, e.g. "Nov".</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'H'</code></td>
|
||||
<td>
|
||||
The hour (24-hour clock) as a decimal number. If the result is a single
|
||||
digit, it is prefixed with 0. The modified command <code>%OH</code>
|
||||
produces the locale's alternative representation.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'I'</code></td>
|
||||
<td>
|
||||
The hour (12-hour clock) as a decimal number. If the result is a single
|
||||
digit, it is prefixed with 0. The modified command <code>%OI</code>
|
||||
produces the locale's alternative representation.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'j'</code></td>
|
||||
<td>
|
||||
If the type being formatted is a specialization of duration, the decimal
|
||||
number of days without padding. Otherwise, the day of the year as a decimal
|
||||
number. Jan 1 is 001. If the result is less than three digits, it is
|
||||
left-padded with 0 to three digits.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'m'</code></td>
|
||||
<td>
|
||||
The month as a decimal number. Jan is 01. If the result is a single digit,
|
||||
it is prefixed with 0. The modified command <code>%Om</code> produces the
|
||||
locale's alternative representation.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'M'</code></td>
|
||||
<td>
|
||||
The minute as a decimal number. If the result is a single digit, it
|
||||
is prefixed with 0. The modified command <code>%OM</code> produces the
|
||||
locale's alternative representation.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'n'</code></td>
|
||||
<td>A new-line character.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'p'</code></td>
|
||||
<td>The AM/PM designations associated with a 12-hour clock.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'q'</code></td>
|
||||
<td>The duration's unit suffix.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'Q'</code></td>
|
||||
<td>
|
||||
The duration's numeric value (as if extracted via <code>.count()</code>).
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'r'</code></td>
|
||||
<td>The 12-hour clock time, e.g. "10:04:00 PM".</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'R'</code></td>
|
||||
<td>Equivalent to <code>%H:%M</code>, e.g. "22:04".</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'S'</code></td>
|
||||
<td>
|
||||
Seconds as a decimal number. If the number of seconds is less than 10, the
|
||||
result is prefixed with 0. If the precision of the input cannot be exactly
|
||||
represented with seconds, then the format is a decimal floating-point number
|
||||
with a fixed format and a precision matching that of the precision of the
|
||||
input (or to a microseconds precision if the conversion to floating-point
|
||||
decimal seconds cannot be made within 18 fractional digits). The modified
|
||||
command <code>%OS</code> produces the locale's alternative representation.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'t'</code></td>
|
||||
<td>A horizontal-tab character.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'T'</code></td>
|
||||
<td>Equivalent to <code>%H:%M:%S</code>.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'u'</code></td>
|
||||
<td>
|
||||
The ISO weekday as a decimal number (1-7), where Monday is 1. The modified
|
||||
command <code>%Ou</code> produces the locale's alternative representation.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'U'</code></td>
|
||||
<td>
|
||||
The week number of the year as a decimal number. The first Sunday of the
|
||||
year is the first day of week 01. Days of the same year prior to that are
|
||||
in week 00. If the result is a single digit, it is prefixed with 0.
|
||||
The modified command <code>%OU</code> produces the locale's alternative
|
||||
representation.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'V'</code></td>
|
||||
<td>
|
||||
The ISO week-based week number as a decimal number. If the result is a
|
||||
single digit, it is prefixed with 0. The modified command <code>%OV</code>
|
||||
produces the locale's alternative representation.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'w'</code></td>
|
||||
<td>
|
||||
The weekday as a decimal number (0-6), where Sunday is 0. The modified
|
||||
command <code>%Ow</code> produces the locale's alternative representation.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'W'</code></td>
|
||||
<td>
|
||||
The week number of the year as a decimal number. The first Monday of the
|
||||
year is the first day of week 01. Days of the same year prior to that are
|
||||
in week 00. If the result is a single digit, it is prefixed with 0.
|
||||
The modified command <code>%OW</code> produces the locale's alternative
|
||||
representation.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'x'</code></td>
|
||||
<td>
|
||||
The date representation, e.g. "11/12/55". The modified command
|
||||
<code>%Ex</code> produces the locale's alternate date representation.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'X'</code></td>
|
||||
<td>
|
||||
The time representation, e.g. "10:04:00". The modified command
|
||||
<code>%EX</code> produces the locale's alternate time representation.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'y'</code></td>
|
||||
<td>
|
||||
The last two decimal digits of the year. If the result is a single digit
|
||||
it is prefixed by 0. The modified command <code>%Oy</code> produces the
|
||||
locale's alternative representation. The modified command <code>%Ey</code>
|
||||
produces the locale's alternative representation of offset from
|
||||
<code>%EC</code> (year only).
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'Y'</code></td>
|
||||
<td>
|
||||
The year as a decimal number. If the result is less than four digits it is
|
||||
left-padded with 0 to four digits. The modified command <code>%EY</code>
|
||||
produces the locale's alternative full year representation.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'z'</code></td>
|
||||
<td>
|
||||
The offset from UTC in the ISO 8601:2004 format. For example -0430 refers
|
||||
to 4 hours 30 minutes behind UTC. If the offset is zero, +0000 is used.
|
||||
The modified commands <code>%Ez</code> and <code>%Oz</code> insert a
|
||||
<code>:</code> between the hours and minutes: -04:30. If the offset
|
||||
information is not available, an exception of type
|
||||
<code>format_error</code> is thrown.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'Z'</code></td>
|
||||
<td>
|
||||
The time zone abbreviation. If the time zone abbreviation is not available,
|
||||
an exception of type <code>format_error</code> is thrown.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>'%'</code></td>
|
||||
<td>A % character.</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
Specifiers that have a calendaric component such as `'d'` (the day of month)
|
||||
are valid only for `std::tm` and time points but not durations.
|
||||
|
||||
The available padding modifiers (*padding_modifier*) are:
|
||||
|
||||
| Type | Meaning |
|
||||
|-------|-----------------------------------------|
|
||||
| `'_'` | Pad a numeric result with spaces. |
|
||||
| `'-'` | Do not pad a numeric result string. |
|
||||
| `'0'` | Pad a numeric result string with zeros. |
|
||||
|
||||
These modifiers are only supported for the `'H'`, `'I'`, `'M'`, `'S'`, `'U'`,
|
||||
`'V'`, `'W'`, `'Y'`, `'d'`, `'j'` and `'m'` presentation types.
|
||||
|
||||
## Range Format Specifications
|
||||
|
||||
Format specifications for range types have the following syntax:
|
||||
|
||||
<pre><code class="language-json"
|
||||
>range_format_spec ::= ["n"][range_type][range_underlying_spec]</code>
|
||||
</pre>
|
||||
|
||||
The `'n'` option formats the range without the opening and closing brackets.
|
||||
|
||||
The available presentation types for `range_type` are:
|
||||
|
||||
| Type | Meaning |
|
||||
|--------|------------------------------------------------------------|
|
||||
| none | Default format. |
|
||||
| `'s'` | String format. The range is formatted as a string. |
|
||||
| `'?s'` | Debug format. The range is formatted as an escaped string. |
|
||||
|
||||
If `range_type` is `'s'` or `'?s'`, the range element type must be a character
|
||||
type. The `'n'` option and `range_underlying_spec` are mutually exclusive with
|
||||
`'s'` and `'?s'`.
|
||||
|
||||
The `range_underlying_spec` is parsed based on the formatter of the range's
|
||||
element type.
|
||||
|
||||
By default, a range of characters or strings is printed escaped and quoted.
|
||||
But if any `range_underlying_spec` is provided (even if it is empty), then the
|
||||
characters or strings are printed according to the provided specification.
|
||||
|
||||
Examples:
|
||||
|
||||
```c++
|
||||
fmt::print("{}", std::vector{10, 20, 30});
|
||||
// Output: [10, 20, 30]
|
||||
fmt::print("{::#x}", std::vector{10, 20, 30});
|
||||
// Output: [0xa, 0x14, 0x1e]
|
||||
fmt::print("{}", std::vector{'h', 'e', 'l', 'l', 'o'});
|
||||
// Output: ['h', 'e', 'l', 'l', 'o']
|
||||
fmt::print("{:n}", std::vector{'h', 'e', 'l', 'l', 'o'});
|
||||
// Output: 'h', 'e', 'l', 'l', 'o'
|
||||
fmt::print("{:s}", std::vector{'h', 'e', 'l', 'l', 'o'});
|
||||
// Output: "hello"
|
||||
fmt::print("{:?s}", std::vector{'h', 'e', 'l', 'l', 'o', '\n'});
|
||||
// Output: "hello\n"
|
||||
fmt::print("{::}", std::vector{'h', 'e', 'l', 'l', 'o'});
|
||||
// Output: [h, e, l, l, o]
|
||||
fmt::print("{::d}", std::vector{'h', 'e', 'l', 'l', 'o'});
|
||||
// Output: [104, 101, 108, 108, 111]
|
||||
```
|
||||
|
||||
## Format Examples
|
||||
|
||||
This section contains examples of the format syntax and comparison with
|
||||
the printf formatting.
|
||||
|
||||
In most of the cases the syntax is similar to the printf formatting,
|
||||
with the addition of the `{}` and with `:` used instead of `%`. For
|
||||
example, `"%03.2f"` can be translated to `"{:03.2f}"`.
|
||||
|
||||
The new format syntax also supports new and different options, shown in
|
||||
the following examples.
|
||||
|
||||
Accessing arguments by position:
|
||||
|
||||
```c++
|
||||
fmt::format("{0}, {1}, {2}", 'a', 'b', 'c');
|
||||
// Result: "a, b, c"
|
||||
fmt::format("{}, {}, {}", 'a', 'b', 'c');
|
||||
// Result: "a, b, c"
|
||||
fmt::format("{2}, {1}, {0}", 'a', 'b', 'c');
|
||||
// Result: "c, b, a"
|
||||
fmt::format("{0}{1}{0}", "abra", "cad"); // arguments' indices can be repeated
|
||||
// Result: "abracadabra"
|
||||
```
|
||||
|
||||
Aligning the text and specifying a width:
|
||||
|
||||
```c++
|
||||
fmt::format("{:<30}", "left aligned");
|
||||
// Result: "left aligned "
|
||||
fmt::format("{:>30}", "right aligned");
|
||||
// Result: " right aligned"
|
||||
fmt::format("{:^30}", "centered");
|
||||
// Result: " centered "
|
||||
fmt::format("{:*^30}", "centered"); // use '*' as a fill char
|
||||
// Result: "***********centered***********"
|
||||
```
|
||||
|
||||
Dynamic width:
|
||||
|
||||
```c++
|
||||
fmt::format("{:<{}}", "left aligned", 30);
|
||||
// Result: "left aligned "
|
||||
```
|
||||
|
||||
Dynamic precision:
|
||||
|
||||
```c++
|
||||
fmt::format("{:.{}f}", 3.14, 1);
|
||||
// Result: "3.1"
|
||||
```
|
||||
|
||||
Replacing `%+f`, `%-f`, and `% f` and specifying a sign:
|
||||
|
||||
```c++
|
||||
fmt::format("{:+f}; {:+f}", 3.14, -3.14); // show it always
|
||||
// Result: "+3.140000; -3.140000"
|
||||
fmt::format("{: f}; {: f}", 3.14, -3.14); // show a space for positive numbers
|
||||
// Result: " 3.140000; -3.140000"
|
||||
fmt::format("{:-f}; {:-f}", 3.14, -3.14); // show only the minus -- same as '{:f}; {:f}'
|
||||
// Result: "3.140000; -3.140000"
|
||||
```
|
||||
|
||||
Replacing `%x` and `%o` and converting the value to different bases:
|
||||
|
||||
```c++
|
||||
fmt::format("int: {0:d}; hex: {0:x}; oct: {0:o}; bin: {0:b}", 42);
|
||||
// Result: "int: 42; hex: 2a; oct: 52; bin: 101010"
|
||||
// with 0x or 0 or 0b as prefix:
|
||||
fmt::format("int: {0:d}; hex: {0:#x}; oct: {0:#o}; bin: {0:#b}", 42);
|
||||
// Result: "int: 42; hex: 0x2a; oct: 052; bin: 0b101010"
|
||||
```
|
||||
|
||||
Padded hex byte with prefix and always prints both hex characters:
|
||||
|
||||
```c++
|
||||
fmt::format("{:#04x}", 0);
|
||||
// Result: "0x00"
|
||||
```
|
||||
|
||||
Box drawing using Unicode fill:
|
||||
|
||||
```c++
|
||||
fmt::print(
|
||||
"┌{0:─^{2}}┐\n"
|
||||
"│{1: ^{2}}│\n"
|
||||
"└{0:─^{2}}┘\n", "", "Hello, world!", 20);
|
||||
```
|
||||
|
||||
prints:
|
||||
|
||||
```
|
||||
┌────────────────────┐
|
||||
│ Hello, world! │
|
||||
└────────────────────┘
|
||||
```
|
||||
|
||||
Using type-specific formatting:
|
||||
|
||||
```c++
|
||||
#include <fmt/chrono.h>
|
||||
|
||||
auto t = tm();
|
||||
t.tm_year = 2010 - 1900;
|
||||
t.tm_mon = 7;
|
||||
t.tm_mday = 4;
|
||||
t.tm_hour = 12;
|
||||
t.tm_min = 15;
|
||||
t.tm_sec = 58;
|
||||
fmt::print("{:%Y-%m-%d %H:%M:%S}", t);
|
||||
// Prints: 2010-08-04 12:15:58
|
||||
```
|
||||
|
||||
Using the comma as a thousands separator:
|
||||
|
||||
```c++
|
||||
#include <fmt/format.h>
|
||||
|
||||
auto s = fmt::format(std::locale("en_US.UTF-8"), "{:L}", 1234567890);
|
||||
// s == "1,234,567,890"
|
||||
```
|
||||
Reference in New Issue
Block a user