mirror of
https://github.com/EQEmu/Server.git
synced 2026-05-16 22:58:34 +00:00
Update fmt lib, add recast, wip on recast pathfinder interface (broken atm)
This commit is contained in:
KimLS
@@ -11,8 +11,8 @@ namespace is usually omitted in examples.
|
||||
Format API
|
||||
==========
|
||||
|
||||
The following functions use :ref:`format string syntax <syntax>` similar
|
||||
to the one used by Python's `str.format
|
||||
The following functions defined in ``fmt/format.h`` use :ref:`format string
|
||||
syntax <syntax>` similar to the one used by Python's `str.format
|
||||
<http://docs.python.org/3/library/stdtypes.html#str.format>`_ function.
|
||||
They take *format_str* and *args* as arguments.
|
||||
|
||||
@@ -22,6 +22,11 @@ arguments in the resulting string.
|
||||
|
||||
*args* is an argument list representing arbitrary arguments.
|
||||
|
||||
The `performance of the format API
|
||||
<https://github.com/fmtlib/fmt/blob/master/README.rst#speed-tests>`_ is close
|
||||
to that of glibc's ``printf`` and better than the performance of IOStreams.
|
||||
For even better speed use the `write API`_.
|
||||
|
||||
.. _format:
|
||||
|
||||
.. doxygenfunction:: format(CStringRef, ArgList)
|
||||
@@ -40,8 +45,9 @@ arguments in the resulting string.
|
||||
Date and time formatting
|
||||
------------------------
|
||||
|
||||
The library supports `strftime <http://en.cppreference.com/w/cpp/chrono/c/strftime>`_-like
|
||||
date and time formatting::
|
||||
The library supports `strftime
|
||||
<http://en.cppreference.com/w/cpp/chrono/c/strftime>`_-like date and time
|
||||
formatting::
|
||||
|
||||
#include "fmt/time.h"
|
||||
|
||||
@@ -52,6 +58,36 @@ date and time formatting::
|
||||
The format string syntax is described in the documentation of
|
||||
`strftime <http://en.cppreference.com/w/cpp/chrono/c/strftime>`_.
|
||||
|
||||
Formatting user-defined types
|
||||
-----------------------------
|
||||
|
||||
A custom ``format_arg`` function may be implemented and used to format any
|
||||
user-defined type. That is how date and time formatting described in the
|
||||
previous section is implemented in :file:`fmt/time.h`. The following example
|
||||
shows how to implement custom formatting for a user-defined structure.
|
||||
|
||||
::
|
||||
|
||||
struct MyStruct { double a, b; };
|
||||
|
||||
void format_arg(fmt::BasicFormatter<char> &f,
|
||||
const char *&format_str, const MyStruct &s) {
|
||||
f.writer().write("[MyStruct: a={:.1f}, b={:.2f}]", s.a, s.b);
|
||||
}
|
||||
|
||||
MyStruct m = { 1, 2 };
|
||||
std::string s = fmt::format("m={}", n);
|
||||
// s == "m=[MyStruct: a=1.0, b=2.00]"
|
||||
|
||||
Note in the example above the ``format_arg`` function ignores the contents of
|
||||
``format_str`` so the type will always be formatted as specified. See
|
||||
``format_arg`` in :file:`fmt/time.h` for an advanced example of how to use
|
||||
the ``format_str`` argument to customize the formatted output.
|
||||
|
||||
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.
|
||||
|
||||
``std::ostream`` support
|
||||
------------------------
|
||||
|
||||
@@ -63,7 +99,7 @@ formatting of user-defined types that have overloaded ``operator<<``::
|
||||
class Date {
|
||||
int year_, month_, day_;
|
||||
public:
|
||||
Date(int year, int month, int day) : year_(year), month_(month), day_(day) {}
|
||||
Date(int year, int month, int day): year_(year), month_(month), day_(day) {}
|
||||
|
||||
friend std::ostream &operator<<(std::ostream &os, const Date &d) {
|
||||
return os << d.year_ << '-' << d.month_ << '-' << d.day_;
|
||||
@@ -75,8 +111,6 @@ formatting of user-defined types that have overloaded ``operator<<``::
|
||||
|
||||
.. doxygenfunction:: print(std::ostream&, CStringRef, ArgList)
|
||||
|
||||
.. doxygenfunction:: fprintf(std::ostream&, CStringRef, ArgList)
|
||||
|
||||
Argument formatters
|
||||
-------------------
|
||||
|
||||
@@ -86,7 +120,7 @@ custom argument formatter class::
|
||||
// A custom argument formatter that formats negative integers as unsigned
|
||||
// with the ``x`` format specifier.
|
||||
class CustomArgFormatter :
|
||||
public fmt::BasicArgFormatter<CustomArgFormatter, char> {
|
||||
public fmt::BasicArgFormatter<CustomArgFormatter, char> {
|
||||
public:
|
||||
CustomArgFormatter(fmt::BasicFormatter<char, CustomArgFormatter> &f,
|
||||
fmt::FormatSpec &s, const char *fmt)
|
||||
@@ -120,22 +154,43 @@ custom argument formatter class::
|
||||
.. doxygenclass:: fmt::ArgFormatter
|
||||
:members:
|
||||
|
||||
Printf formatting functions
|
||||
---------------------------
|
||||
Printf formatting
|
||||
-----------------
|
||||
|
||||
The header ``fmt/printf.h`` provides ``printf``-like formatting functionality.
|
||||
The following functions use `printf format string syntax
|
||||
<http://pubs.opengroup.org/onlinepubs/009695399/functions/fprintf.html>`_ with
|
||||
a POSIX extension for positional arguments.
|
||||
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.
|
||||
|
||||
.. doxygenfunction:: printf(CStringRef, ArgList)
|
||||
|
||||
.. doxygenfunction:: fprintf(std::FILE *, CStringRef, ArgList)
|
||||
|
||||
.. doxygenfunction:: fprintf(std::ostream&, CStringRef, ArgList)
|
||||
|
||||
.. doxygenfunction:: sprintf(CStringRef, ArgList)
|
||||
|
||||
.. doxygenclass:: fmt::PrintfFormatter
|
||||
:members:
|
||||
|
||||
.. doxygenclass:: fmt::BasicPrintfArgFormatter
|
||||
:members:
|
||||
|
||||
.. doxygenclass:: fmt::PrintfArgFormatter
|
||||
:members:
|
||||
|
||||
Write API
|
||||
=========
|
||||
|
||||
The write API provides classes for writing formatted data into character
|
||||
streams. It is usually faster than the `format API`_ but, as IOStreams,
|
||||
may result in larger compiled code size. The main writer class is
|
||||
`~fmt::BasicMemoryWriter` which stores its output in a memory buffer and
|
||||
provides direct access to it. It is possible to create custom writers that
|
||||
store output elsewhere by subclassing `~fmt::BasicWriter`.
|
||||
|
||||
.. doxygenclass:: fmt::BasicWriter
|
||||
:members:
|
||||
|
||||
@@ -145,6 +200,12 @@ Write API
|
||||
.. doxygenclass:: fmt::BasicArrayWriter
|
||||
:members:
|
||||
|
||||
.. doxygenclass:: fmt::BasicStringWriter
|
||||
:members:
|
||||
|
||||
.. doxygenclass:: fmt::BasicContainerWriter
|
||||
:members:
|
||||
|
||||
.. doxygenfunction:: bin(int)
|
||||
|
||||
.. doxygenfunction:: oct(int)
|
||||
@@ -169,6 +230,8 @@ Utilities
|
||||
.. doxygenclass:: fmt::ArgList
|
||||
:members:
|
||||
|
||||
.. doxygenfunction:: fmt::to_string(const T&)
|
||||
|
||||
.. doxygenclass:: fmt::BasicStringRef
|
||||
:members:
|
||||
|
||||
@@ -185,6 +248,8 @@ System errors
|
||||
.. doxygenclass:: fmt::SystemError
|
||||
:members:
|
||||
|
||||
.. doxygenfunction:: fmt::format_system_error
|
||||
|
||||
.. doxygenclass:: fmt::WindowsError
|
||||
:members:
|
||||
|
||||
@@ -202,7 +267,8 @@ A custom allocator class can be specified as a template argument to
|
||||
It is also possible to write a formatting function that uses a custom
|
||||
allocator::
|
||||
|
||||
typedef std::basic_string<char, std::char_traits<char>, CustomAllocator> CustomString;
|
||||
typedef std::basic_string<char, std::char_traits<char>, CustomAllocator>
|
||||
CustomString;
|
||||
|
||||
CustomString format(CustomAllocator alloc, fmt::CStringRef format_str,
|
||||
fmt::ArgList args) {
|
||||
|
||||
@@ -10,9 +10,9 @@ alternative to C++ IOStreams.
|
||||
<div class="panel panel-default">
|
||||
<div class="panel-heading">What users say:</div>
|
||||
<div class="panel-body">
|
||||
Thanks for creating this library. It’s been a hole in C++ for a long time.
|
||||
I’ve used both boost::format and loki::SPrintf, and neither felt like the
|
||||
right answer. This does.
|
||||
Thanks for creating this library. It’s been a hole in C++ for a long
|
||||
time. I’ve used both boost::format and loki::SPrintf, and neither felt
|
||||
like the right answer. This does.
|
||||
</div>
|
||||
</div>
|
||||
|
||||
@@ -24,8 +24,8 @@ Format API
|
||||
The replacement-based Format API provides a safe alternative to ``printf``,
|
||||
``sprintf`` and friends with comparable or `better performance
|
||||
<http://zverovich.net/2013/09/07/integer-to-string-conversion-in-cplusplus.html>`_.
|
||||
The `format string syntax <doc/latest/index.html#format-string-syntax>`_ is similar
|
||||
to the one used by `str.format <http://docs.python.org/2/library/stdtypes.html#str.format>`_
|
||||
The `format string syntax <syntax.html>`_ is similar to the one used by
|
||||
`str.format <http://docs.python.org/2/library/stdtypes.html#str.format>`_
|
||||
in Python:
|
||||
|
||||
.. code:: c++
|
||||
@@ -98,8 +98,8 @@ literal operators, they must be made visible with the directive
|
||||
Write API
|
||||
---------
|
||||
|
||||
The concatenation-based Write API (experimental) provides a
|
||||
`fast <http://zverovich.net/2013/09/07/integer-to-string-conversion-in-cplusplus.html>`_
|
||||
The concatenation-based Write API (experimental) provides a `fast
|
||||
<http://zverovich.net/2013/09/07/integer-to-string-conversion-in-cplusplus.html>`_
|
||||
stateless alternative to IOStreams:
|
||||
|
||||
.. code:: c++
|
||||
@@ -112,8 +112,9 @@ stateless alternative to IOStreams:
|
||||
Safety
|
||||
------
|
||||
|
||||
The library is fully type safe, automatic memory management prevents buffer overflow,
|
||||
errors in format strings are reported using exceptions. For example, the code
|
||||
The library is fully type safe, automatic memory management prevents buffer
|
||||
overflow, errors in format strings are reported using exceptions. For example,
|
||||
the code
|
||||
|
||||
.. code:: c++
|
||||
|
||||
@@ -138,19 +139,21 @@ formatted into a narrow string. You can use a wide format string instead:
|
||||
fmt::format(L"Cyrillic letter {}", L'\x42e');
|
||||
|
||||
For comparison, writing a wide character to ``std::ostream`` results in
|
||||
its numeric value being written to the stream (i.e. 1070 instead of letter 'ю' which
|
||||
is represented by ``L'\x42e'`` if we use Unicode) which is rarely what is needed.
|
||||
its numeric value being written to the stream (i.e. 1070 instead of letter 'ю'
|
||||
which is represented by ``L'\x42e'`` if we use Unicode) which is rarely what is
|
||||
needed.
|
||||
|
||||
.. _portability:
|
||||
|
||||
Portability
|
||||
-----------
|
||||
|
||||
The library is highly portable. Here is an incomplete list of operating systems and
|
||||
compilers where it has been tested and known to work:
|
||||
The library is highly portable. Here is an incomplete list of operating systems
|
||||
and compilers where it has been tested and known to work:
|
||||
|
||||
* 64-bit (amd64) GNU/Linux with GCC 4.4.3, `4.6.3 <https://travis-ci.org/fmtlib/fmt>`_,
|
||||
4.7.2, 4.8.1 and Intel C++ Compiler (ICC) 14.0.2
|
||||
* 64-bit (amd64) GNU/Linux with GCC 4.4.3,
|
||||
`4.6.3 <https://travis-ci.org/fmtlib/fmt>`_, 4.7.2, 4.8.1, and Intel C++
|
||||
Compiler (ICC) 14.0.2
|
||||
|
||||
* 32-bit (i386) GNU/Linux with GCC 4.4.3, 4.6.3
|
||||
|
||||
@@ -161,21 +164,21 @@ compilers where it has been tested and known to work:
|
||||
|
||||
* 32-bit Windows with Visual C++ 2010
|
||||
|
||||
Although the library uses C++11 features when available, it also works with older
|
||||
compilers and standard library implementations. The only thing to keep in mind
|
||||
for C++98 portability:
|
||||
Although the library uses C++11 features when available, it also works with
|
||||
older compilers and standard library implementations. The only thing to keep in
|
||||
mind for C++98 portability:
|
||||
|
||||
* Variadic templates: minimum GCC 4.4, Clang 2.9 or VS2013. This feature allows
|
||||
the Format API to accept an unlimited number of arguments. With older compilers
|
||||
the maximum is 15.
|
||||
the Format API to accept an unlimited number of arguments. With older
|
||||
compilers the maximum is 15.
|
||||
|
||||
* User-defined literals: minimum GCC 4.7, Clang 3.1 or VS2015. The suffixes
|
||||
``_format`` and ``_a`` are functionally equivalent to the functions
|
||||
* User-defined literals: minimum GCC 4.7, Clang 3.1 or VS2015. The suffixes
|
||||
``_format`` and ``_a`` are functionally equivalent to the functions
|
||||
``fmt::format`` and ``fmt::arg``.
|
||||
|
||||
The output of all formatting functions is consistent across platforms. In particular,
|
||||
formatting a floating-point infinity always gives ``inf`` while the output
|
||||
of ``printf`` is platform-dependent in this case. For example,
|
||||
The output of all formatting functions is consistent across platforms. In
|
||||
particular, formatting a floating-point infinity always gives ``inf`` while the
|
||||
output of ``printf`` is platform-dependent in this case. For example,
|
||||
|
||||
.. code::
|
||||
|
||||
@@ -188,10 +191,10 @@ always prints ``inf``.
|
||||
Ease of Use
|
||||
-----------
|
||||
|
||||
fmt has a small self-contained code base consisting of a single header file
|
||||
and a single source file and no external dependencies. A permissive BSD `license
|
||||
<https://github.com/fmtlib/fmt#license>`_ allows using the library both
|
||||
in open-source and commercial projects.
|
||||
fmt has a small self-contained code base with the core library consisting of
|
||||
a single header file and a single source file and no external dependencies.
|
||||
A permissive BSD `license <https://github.com/fmtlib/fmt#license>`_ allows
|
||||
using the library both in open-source and commercial projects.
|
||||
|
||||
.. raw:: html
|
||||
|
||||
|
||||
@@ -49,12 +49,10 @@ 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 within it.
|
||||
These nested replacement fields can contain only an argument index;
|
||||
format specifications are not allowed. Formatting is performed as if the
|
||||
replacement fields within the format_spec are substituted before the
|
||||
*format_spec* string is interpreted. This allows the formatting of a value
|
||||
to be dynamically specified.
|
||||
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 :ref:`formatexamples` section for some examples.
|
||||
|
||||
@@ -80,8 +78,8 @@ The general form of a *standard format specifier* is:
|
||||
sign: "+" | "-" | " "
|
||||
width: `integer` | "{" `arg_id` "}"
|
||||
precision: `integer` | "{" `arg_id` "}"
|
||||
type: `int_type` | "c" | "e" | "E" | "f" | "F" | "g" | "G" | "p" | "s"
|
||||
int_type: "b" | "B" | "d" | "o" | "x" | "X"
|
||||
type: `int_type` | "a" | "A" | "c" | "e" | "E" | "f" | "F" | "g" | "G" | "p" | "s"
|
||||
int_type: "b" | "B" | "d" | "n" | "o" | "x" | "X"
|
||||
|
||||
The *fill* character can be any character other than '{' or '}'. The presence
|
||||
of a fill character is signaled by the character following it, which must be
|
||||
@@ -234,7 +232,7 @@ The available presentation types for floating-point values are:
|
||||
+=========+==========================================================+
|
||||
| ``'a'`` | Hexadecimal floating point format. Prints the number in |
|
||||
| | base 16 with prefix ``"0x"`` and lower-case letters for |
|
||||
| | digits above 9. Uses 'p' to indicate the exponent. |
|
||||
| | digits above 9. Uses ``'p'`` to indicate the exponent. |
|
||||
+---------+----------------------------------------------------------+
|
||||
| ``'A'`` | Same as ``'a'`` except it uses upper-case letters for |
|
||||
| | the prefix, digits above 9 and to indicate the exponent. |
|
||||
|
||||
@@ -54,6 +54,23 @@ To build a `shared library`__ set the ``BUILD_SHARED_LIBS`` CMake variable to
|
||||
|
||||
__ http://en.wikipedia.org/wiki/Library_%28computing%29#Shared_libraries
|
||||
|
||||
Header-only usage with CMake
|
||||
============================
|
||||
|
||||
In order to add ``fmtlib`` into an existing ``CMakeLists.txt`` file, you can add the ``fmt`` library directory into your main project, which will enable the ``fmt`` library::
|
||||
|
||||
add_subdirectory(fmt)
|
||||
|
||||
If you have a project called ``foo`` that you would like to link against the fmt library in a header-only fashion, you can enable with with::
|
||||
|
||||
target_link_libraries(foo PRIVATE fmt::fmt-header-only)
|
||||
|
||||
And then to ensure that the ``fmt`` library does not always get built, you can modify the call to ``add_subdirectory`` to read ::
|
||||
|
||||
add_subdirectory(fmt EXCLUDE_FROM_ALL)
|
||||
|
||||
This will ensure that the ``fmt`` library is exluded from calls to ``make``, ``make all``, or ``cmake --build .``.
|
||||
|
||||
Building the documentation
|
||||
==========================
|
||||
|
||||
@@ -62,7 +79,11 @@ system:
|
||||
|
||||
* `Python <https://www.python.org/>`_ with pip and virtualenv
|
||||
* `Doxygen <http://www.stack.nl/~dimitri/doxygen/>`_
|
||||
* `Less <http://lesscss.org/>`_ with less-plugin-clean-css
|
||||
* `Less <http://lesscss.org/>`_ with ``less-plugin-clean-css``.
|
||||
Ubuntu doesn't package the ``clean-css`` plugin so you should use ``npm``
|
||||
instead of ``apt`` to install both ``less`` and the plugin::
|
||||
|
||||
sudo npm install -g less less-plugin-clean-css.
|
||||
|
||||
First generate makefiles or project files using CMake as described in
|
||||
the previous section. Then compile the ``doc`` target/project, for example::
|
||||
@@ -87,4 +108,4 @@ Homebrew
|
||||
|
||||
fmt can be installed on OS X using `Homebrew <http://brew.sh/>`_::
|
||||
|
||||
brew install cppformat
|
||||
brew install fmt
|
||||
|
||||
Reference in New Issue
Block a user