mirror of
https://github.com/EQEmu/Server.git
synced 2025-12-12 22:01:30 +00:00
297 lines
19 KiB
HTML
297 lines
19 KiB
HTML
<!DOCTYPE html>
|
||
|
||
|
||
<html lang="en">
|
||
<head>
|
||
<meta charset="utf-8">
|
||
<meta http-equiv="X-UA-Compatible" content="IE=edge">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||
|
||
|
||
<title>Overview — fmt 3.0.0 documentation</title>
|
||
|
||
<link rel="stylesheet" href="_static/basic.css" type="text/css" />
|
||
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
|
||
<link rel="stylesheet" href="_static/breathe.css" type="text/css" />
|
||
|
||
<script type="text/javascript">
|
||
var DOCUMENTATION_OPTIONS = {
|
||
URL_ROOT: './',
|
||
VERSION: '3.0.0',
|
||
COLLAPSE_INDEX: false,
|
||
FILE_SUFFIX: '.html',
|
||
HAS_SOURCE: true
|
||
};
|
||
</script>
|
||
<script type="text/javascript" src="_static/jquery.js"></script>
|
||
<script type="text/javascript" src="_static/underscore.js"></script>
|
||
<script type="text/javascript" src="_static/doctools.js"></script>
|
||
<meta name="description" content="Small, safe and fast formatting library">
|
||
<meta name="keywords" content="C++, formatting, printf, string, library">
|
||
<meta name="author" content="Victor Zverovich">
|
||
<link rel="stylesheet" href="_static/fmt.css">
|
||
|
||
<script>
|
||
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
|
||
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
|
||
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
|
||
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
|
||
ga('create', 'UA-20116650-4', 'fmtlib.net');
|
||
ga('send', 'pageview');
|
||
</script>
|
||
|
||
</head>
|
||
<body role="document">
|
||
<nav class="navbar navbar-inverse">
|
||
<div class="tb-container">
|
||
<div class="row">
|
||
<div class="navbar-content">
|
||
|
||
<div class="navbar-header">
|
||
<button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target=".navbar-collapse">
|
||
<span class="sr-only">Toggle navigation</span>
|
||
<span class="icon-bar"></span>
|
||
<span class="icon-bar"></span>
|
||
<span class="icon-bar"></span>
|
||
</button>
|
||
<a class="navbar-brand" href="index.html">{fmt}</a>
|
||
</div>
|
||
|
||
|
||
<div class="collapse navbar-collapse">
|
||
<ul class="nav navbar-nav">
|
||
<li class="dropdown">
|
||
|
||
<a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button"
|
||
aria-expanded="false">3.0.0 <span class="caret"></span></a>
|
||
<ul class="dropdown-menu" role="menu">
|
||
<li><a href="http://fmtlib.net/2.0.0/">2.0.0</a></li>
|
||
<li><a href="http://fmtlib.net/1.1.0/">1.1.0</a></li>
|
||
<li><a href="http://fmtlib.net/1.0.0/">1.0.0</a></li>
|
||
</ul>
|
||
</li>
|
||
|
||
|
||
<li><a href="contents.html">Contents</a></li>
|
||
|
||
|
||
|
||
<li><a href="usage.html">Usage</a></li>
|
||
|
||
|
||
|
||
<li><a href="api.html">API</a></li>
|
||
|
||
|
||
|
||
<li><a href="syntax.html">Syntax</a></li>
|
||
|
||
|
||
</ul>
|
||
|
||
|
||
<form class="navbar-form navbar-right" role="search" action="search.html" method="get">
|
||
<div class="form-group">
|
||
<input type="text" name="q" class="form-control" placeholder="Search" >
|
||
</div>
|
||
<input type="hidden" name="check_keywords" value="yes" />
|
||
<input type="hidden" name="area" value="default" />
|
||
|
||
</form>
|
||
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</nav>
|
||
|
||
<div class="jumbotron">
|
||
<div class="tb-container">
|
||
<h1>{fmt}</h1>
|
||
<p class="lead">Small, safe and fast formatting library</p>
|
||
<div class="btn-group" role="group">
|
||
<a class="btn btn-success"
|
||
href="https://github.com/fmtlib/fmt/releases/download/2.0.0/cppformat-2.0.0.zip">
|
||
<span class="glyphicon glyphicon-download"></span> Download
|
||
</a>
|
||
<button type="button" class="btn btn-success dropdown-toggle" data-toggle="dropdown"><span class="caret"></span></button>
|
||
<ul class="dropdown-menu">
|
||
<li><a href="https://github.com/fmtlib/fmt/releases/download/2.0.0/cppformat-2.0.0.zip">Version 2.0.0</a></li>
|
||
<li><a href="https://github.com/fmtlib/fmt/releases/download/1.1.0/cppformat-1.1.0.zip">Version 1.1.0</a></li>
|
||
<li><a href="https://github.com/fmtlib/fmt/releases/download/1.0.0/cppformat-1.0.0.zip">Version 1.0.0</a></li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
|
||
|
||
<div class="tb-container">
|
||
<div class="row">
|
||
|
||
|
||
<div class="content">
|
||
|
||
<div class="section" id="overview">
|
||
<h1>Overview<a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h1>
|
||
<p><strong>fmt</strong> (formerly cppformat) is an open-source formatting library.
|
||
It can be used as a safe alternative to printf or as a fast
|
||
alternative to C++ IOStreams.</p>
|
||
<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.
|
||
</div>
|
||
</div><div class="section" id="format-api">
|
||
<span id="id1"></span><h2>Format API<a class="headerlink" href="#format-api" title="Permalink to this headline">¶</a></h2>
|
||
<p>The replacement-based Format API provides a safe alternative to <code class="docutils literal"><span class="pre">printf</span></code>,
|
||
<code class="docutils literal"><span class="pre">sprintf</span></code> and friends with comparable or <a class="reference external" href="http://zverovich.net/2013/09/07/integer-to-string-conversion-in-cplusplus.html">better performance</a>.
|
||
The <a class="reference external" href="doc/latest/index.html#format-string-syntax">format string syntax</a> is similar
|
||
to the one used by <a class="reference external" href="http://docs.python.org/2/library/stdtypes.html#str.format">str.format</a>
|
||
in Python:</p>
|
||
<div class="code c++ highlight-c++"><div class="highlight"><pre><span></span><span class="n">fmt</span><span class="o">::</span><span class="n">format</span><span class="p">(</span><span class="s">"The answer is {}"</span><span class="p">,</span> <span class="mi">42</span><span class="p">);</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The <code class="docutils literal"><span class="pre">fmt::format</span></code> function returns a string “The answer is 42”. You can use
|
||
<code class="docutils literal"><span class="pre">fmt::MemoryWriter</span></code> to avoid constructing <code class="docutils literal"><span class="pre">std::string</span></code>:</p>
|
||
<div class="code c++ highlight-c++"><div class="highlight"><pre><span></span><span class="n">fmt</span><span class="o">::</span><span class="n">MemoryWriter</span> <span class="n">w</span><span class="p">;</span>
|
||
<span class="n">w</span><span class="p">.</span><span class="n">write</span><span class="p">(</span><span class="s">"Look, a {} string"</span><span class="p">,</span> <span class="sc">'C'</span><span class="p">);</span>
|
||
<span class="n">w</span><span class="p">.</span><span class="n">c_str</span><span class="p">();</span> <span class="c1">// returns a C string (const char*)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The <code class="docutils literal"><span class="pre">fmt::print</span></code> function performs formatting and writes the result to a file:</p>
|
||
<div class="code c++ highlight-c++"><div class="highlight"><pre><span></span><span class="n">fmt</span><span class="o">::</span><span class="n">print</span><span class="p">(</span><span class="n">stderr</span><span class="p">,</span> <span class="s">"System error code = {}</span><span class="se">\n</span><span class="s">"</span><span class="p">,</span> <span class="n">errno</span><span class="p">);</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The file argument can be omitted in which case the function prints to
|
||
<code class="docutils literal"><span class="pre">stdout</span></code>:</p>
|
||
<div class="code c++ highlight-c++"><div class="highlight"><pre><span></span><span class="n">fmt</span><span class="o">::</span><span class="n">print</span><span class="p">(</span><span class="s">"Don't {}</span><span class="se">\n</span><span class="s">"</span><span class="p">,</span> <span class="s">"panic"</span><span class="p">);</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>If your compiler supports C++11, then the formatting functions are implemented
|
||
with variadic templates. Otherwise variadic functions are emulated by generating
|
||
a set of lightweight wrappers. This ensures compatibility with older compilers
|
||
while providing a natural API.</p>
|
||
<p>The Format API also supports positional arguments useful for localization:</p>
|
||
<div class="code c++ highlight-c++"><div class="highlight"><pre><span></span><span class="n">fmt</span><span class="o">::</span><span class="n">print</span><span class="p">(</span><span class="s">"I'd rather be {1} than {0}."</span><span class="p">,</span> <span class="s">"right"</span><span class="p">,</span> <span class="s">"happy"</span><span class="p">);</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Named arguments can be created with <code class="docutils literal"><span class="pre">fmt::arg</span></code>. This makes it easier to track
|
||
what goes where when multiple values are being inserted:</p>
|
||
<div class="code c++ highlight-c++"><div class="highlight"><pre><span></span><span class="n">fmt</span><span class="o">::</span><span class="n">print</span><span class="p">(</span><span class="s">"Hello, {name}! The answer is {number}. Goodbye, {name}."</span><span class="p">,</span>
|
||
<span class="n">fmt</span><span class="o">::</span><span class="n">arg</span><span class="p">(</span><span class="s">"name"</span><span class="p">,</span> <span class="s">"World"</span><span class="p">),</span> <span class="n">fmt</span><span class="o">::</span><span class="n">arg</span><span class="p">(</span><span class="s">"number"</span><span class="p">,</span> <span class="mi">42</span><span class="p">));</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>If your compiler supports C++11 user-defined literals, the suffix <code class="docutils literal"><span class="pre">_a</span></code> offers
|
||
an alternative, slightly terser syntax for named arguments:</p>
|
||
<div class="code c++ highlight-c++"><div class="highlight"><pre><span></span><span class="n">fmt</span><span class="o">::</span><span class="n">print</span><span class="p">(</span><span class="s">"Hello, {name}! The answer is {number}. Goodbye, {name}."</span><span class="p">,</span>
|
||
<span class="s">"name"</span><span class="n">_a</span><span class="o">=</span><span class="s">"World"</span><span class="p">,</span> <span class="s">"number"</span><span class="n">_a</span><span class="o">=</span><span class="mi">42</span><span class="p">);</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The <code class="docutils literal"><span class="pre">_format</span></code> suffix may be used to format string literals similar to Python:</p>
|
||
<div class="code c++ highlight-c++"><div class="highlight"><pre><span></span><span class="n">std</span><span class="o">::</span><span class="n">string</span> <span class="n">message</span> <span class="o">=</span> <span class="s">"{0}{1}{0}"</span><span class="n">_format</span><span class="p">(</span><span class="s">"abra"</span><span class="p">,</span> <span class="s">"cad"</span><span class="p">);</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Other than the placement of the format string on the left of the operator,
|
||
<code class="docutils literal"><span class="pre">_format</span></code> is functionally identical to <code class="docutils literal"><span class="pre">fmt::format</span></code>. In order to use the
|
||
literal operators, they must be made visible with the directive
|
||
<code class="docutils literal"><span class="pre">using</span> <span class="pre">namespace</span> <span class="pre">fmt::literals;</span></code>. Note that this brings in only <code class="docutils literal"><span class="pre">_a</span></code> and
|
||
<code class="docutils literal"><span class="pre">_format</span></code> but nothing else from the <code class="docutils literal"><span class="pre">fmt</span></code> namespace.</p>
|
||
</div>
|
||
<div class="section" id="write-api">
|
||
<span id="id2"></span><h2>Write API<a class="headerlink" href="#write-api" title="Permalink to this headline">¶</a></h2>
|
||
<p>The concatenation-based Write API (experimental) provides a
|
||
<a class="reference external" href="http://zverovich.net/2013/09/07/integer-to-string-conversion-in-cplusplus.html">fast</a>
|
||
stateless alternative to IOStreams:</p>
|
||
<div class="code c++ highlight-c++"><div class="highlight"><pre><span></span><span class="n">fmt</span><span class="o">::</span><span class="n">MemoryWriter</span> <span class="n">out</span><span class="p">;</span>
|
||
<span class="n">out</span> <span class="o"><<</span> <span class="s">"The answer in hexadecimal is "</span> <span class="o"><<</span> <span class="n">hex</span><span class="p">(</span><span class="mi">42</span><span class="p">);</span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="safety">
|
||
<span id="id3"></span><h2>Safety<a class="headerlink" href="#safety" title="Permalink to this headline">¶</a></h2>
|
||
<p>The library is fully type safe, automatic memory management prevents buffer overflow,
|
||
errors in format strings are reported using exceptions. For example, the code</p>
|
||
<div class="code c++ highlight-c++"><div class="highlight"><pre><span></span><span class="n">fmt</span><span class="o">::</span><span class="n">format</span><span class="p">(</span><span class="s">"The answer is {:d}"</span><span class="p">,</span> <span class="s">"forty-two"</span><span class="p">);</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>throws a <code class="docutils literal"><span class="pre">FormatError</span></code> exception with description
|
||
“unknown format code ‘d’ for string”, because the argument
|
||
<code class="docutils literal"><span class="pre">"forty-two"</span></code> is a string while the format code <code class="docutils literal"><span class="pre">d</span></code>
|
||
only applies to integers.</p>
|
||
<p>Where possible, errors are caught at compile time. For example, the code</p>
|
||
<div class="code c++ highlight-c++"><div class="highlight"><pre><span></span>fmt::format("Cyrillic letter {}", L'\x42e');
|
||
</pre></div>
|
||
</div>
|
||
<p>produces a compile-time error because wide character <code class="docutils literal"><span class="pre">L'\x42e'</span></code> cannot be
|
||
formatted into a narrow string. You can use a wide format string instead:</p>
|
||
<div class="code c++ highlight-c++"><div class="highlight"><pre><span></span>fmt::format(L"Cyrillic letter {}", L'\x42e');
|
||
</pre></div>
|
||
</div>
|
||
<p>For comparison, writing a wide character to <code class="docutils literal"><span class="pre">std::ostream</span></code> results in
|
||
its numeric value being written to the stream (i.e. 1070 instead of letter ‘ю’ which
|
||
is represented by <code class="docutils literal"><span class="pre">L'\x42e'</span></code> if we use Unicode) which is rarely what is needed.</p>
|
||
</div>
|
||
<div class="section" id="portability">
|
||
<span id="id4"></span><h2>Portability<a class="headerlink" href="#portability" title="Permalink to this headline">¶</a></h2>
|
||
<p>The library is highly portable. Here is an incomplete list of operating systems and
|
||
compilers where it has been tested and known to work:</p>
|
||
<ul class="simple">
|
||
<li>64-bit (amd64) GNU/Linux with GCC 4.4.3, <a class="reference external" href="https://travis-ci.org/fmtlib/fmt">4.6.3</a>,
|
||
4.7.2, 4.8.1 and Intel C++ Compiler (ICC) 14.0.2</li>
|
||
<li>32-bit (i386) GNU/Linux with GCC 4.4.3, 4.6.3</li>
|
||
<li>Mac OS X with GCC 4.2.1 and Clang 4.2, 5.1.0</li>
|
||
<li>64-bit Windows with Visual C++ 2010, 2013 and
|
||
<a class="reference external" href="https://ci.appveyor.com/project/vitaut/fmt">2015</a></li>
|
||
<li>32-bit Windows with Visual C++ 2010</li>
|
||
</ul>
|
||
<p>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:</p>
|
||
<ul class="simple">
|
||
<li>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.</li>
|
||
<li>User-defined literals: minimum GCC 4.7, Clang 3.1 or VS2015. The suffixes
|
||
<code class="docutils literal"><span class="pre">_format</span></code> and <code class="docutils literal"><span class="pre">_a</span></code> are functionally equivalent to the functions
|
||
<code class="docutils literal"><span class="pre">fmt::format</span></code> and <code class="docutils literal"><span class="pre">fmt::arg</span></code>.</li>
|
||
</ul>
|
||
<p>The output of all formatting functions is consistent across platforms. In particular,
|
||
formatting a floating-point infinity always gives <code class="docutils literal"><span class="pre">inf</span></code> while the output
|
||
of <code class="docutils literal"><span class="pre">printf</span></code> is platform-dependent in this case. For example,</p>
|
||
<div class="code highlight-c++"><div class="highlight"><pre><span></span><span class="n">fmt</span><span class="o">::</span><span class="n">print</span><span class="p">(</span><span class="s">"{}"</span><span class="p">,</span> <span class="n">std</span><span class="o">::</span><span class="n">numeric_limits</span><span class="o"><</span><span class="kt">double</span><span class="o">>::</span><span class="n">infinity</span><span class="p">());</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>always prints <code class="docutils literal"><span class="pre">inf</span></code>.</p>
|
||
</div>
|
||
<div class="section" id="ease-of-use">
|
||
<span id="id7"></span><h2>Ease of Use<a class="headerlink" href="#ease-of-use" title="Permalink to this headline">¶</a></h2>
|
||
<p>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 <a class="reference external" href="https://github.com/fmtlib/fmt#license">license</a> allows using the library both
|
||
in open-source and commercial projects.</p>
|
||
<a class="btn btn-success" href="https://github.com/fmtlib/fmt">GitHub Repository</a>
|
||
|
||
<div class="section footer">
|
||
<iframe src="http://ghbtns.com/github-btn.html?user=fmtlib&repo=fmt&type=watch&count=true"
|
||
class="github-btn" width="100" height="20"></iframe>
|
||
</div></div>
|
||
</div>
|
||
|
||
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
|
||
|
||
<div class="footer" role="contentinfo">
|
||
© Copyright 2012-2015, Victor Zverovich.
|
||
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.4.1.
|
||
</div>
|
||
|
||
<script src="_static/bootstrap.min.js"></script>
|
||
|
||
</body>
|
||
</html> |