From 6af3da10896ff071fd0161ce3ca37d92d35b4960 Mon Sep 17 00:00:00 2001 From: Victor Zverovich Date: Mon, 9 Mar 2015 07:37:27 -0700 Subject: [PATCH] Merge website content into docs --- doc/_static/breathe.css | 12 +++ doc/_templates/layout.html | 23 ++++++ doc/conf.py | 2 +- doc/contents.rst | 10 +++ doc/index.rst | 161 +++++++++++++++++++++++++++++++++++-- 5 files changed, 199 insertions(+), 9 deletions(-) create mode 100644 doc/contents.rst diff --git a/doc/_static/breathe.css b/doc/_static/breathe.css index 96e5a497..2a1534b0 100644 --- a/doc/_static/breathe.css +++ b/doc/_static/breathe.css @@ -14,3 +14,15 @@ .container .breathe-sectiondef { width: inherit; } + +.github-btn { + border: 0; + overflow: hidden; +} + +.jumbotron { + background-size: 100% 4px; + background-repeat: repeat-y; + color: white; + text-align: center; +} diff --git a/doc/_templates/layout.html b/doc/_templates/layout.html index 6e8372f3..079184da 100644 --- a/doc/_templates/layout.html +++ b/doc/_templates/layout.html @@ -1,5 +1,28 @@ {% extends "!layout.html" %} +{% block header %} +{% if pagename == "index" %} +
+
+

C++ Format

+

Small, safe and fast formatting library for C++

+
+ + Download + + + +
+
+
+{% endif %} +{% endblock %} + {% block footer %} {{ super() }} diff --git a/doc/conf.py b/doc/conf.py index 172299a7..cb2b4403 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -46,7 +46,7 @@ source_suffix = '.rst' #source_encoding = 'utf-8-sig' # The master toctree document. -master_doc = 'index' +#master_doc = 'contents' # General information about the project. project = u'C++ Format' diff --git a/doc/contents.rst b/doc/contents.rst new file mode 100644 index 00000000..c66257f7 --- /dev/null +++ b/doc/contents.rst @@ -0,0 +1,10 @@ +########## +C++ Format +########## + +.. toctree:: + :maxdepth: 2 + + usage + reference + syntax diff --git a/doc/index.rst b/doc/index.rst index c66257f7..72311cf8 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,10 +1,155 @@ -########## -C++ Format -########## +Overview +======== -.. toctree:: - :maxdepth: 2 +C++ Format (cppformat) is an open-source formatting library for C++. +It can be used as a safe alternative to printf or as a fast +alternative to IOStreams. - usage - reference - syntax +.. _format-api: + +Format API +---------- + +The replacement-based Format API provides a safe alternative to ``printf``, +``sprintf`` and friends with comparable or `better performance +`_. +The `format string syntax `_ is similar +to the one used by `str.format `_ +in Python: + +.. code:: c++ + + fmt::format("The answer is {}", 42); + +The ``fmt::format`` function returns a string "The answer is 42". You can use +``fmt::MemoryWriter`` to avoid constructing ``std::string``: + +.. code:: c++ + + fmt::MemoryWriter w; + w.write("Look, a {} string", 'C'); + w.c_str(); // returns a C string (const char*) + +The ``fmt::print`` function performs formatting and writes the result to a file: + +.. code:: c++ + + fmt::print(stderr, "System error code = {}\n", errno); + +The file argument can be omitted in which case the function prints to +``stdout``: + +.. code:: c++ + + fmt::print("Don't {}\n", "panic"); + +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. + +The Format API also supports positional arguments useful for localization: + +.. code:: c++ + + fmt::print("I'd rather be {1} than {0}.", "right", "happy"); + +.. _write-api: + +Write API +--------- + +The concatenation-based Write API (experimental) provides a +`fast `_ +stateless alternative to IOStreams: + +.. code:: c++ + + fmt::MemoryWriter out; + out << "The answer in hexadecimal is " << hex(42); + +.. _safety: + +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 + +.. code:: c++ + + fmt::format("The answer is {:d}", "forty-two"); + +throws a ``FormatError`` exception with description +"unknown format code 'd' for string", because the argument +``"forty-two"`` is a string while the format code ``d`` +only applies to integers. + +Where possible, errors are catched at compile time. For example, the code + +.. code:: c++ + + fmt::format("Cyrillic letter {}", L'\x42e'); + +produces a compile-time error because wide character ``L'\x42e'`` cannot be +formatted into a narrow string. You can use a wide format string instead: + +.. code:: c++ + + 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. + +.. _portability: + +Portability +----------- + +C++ Format 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 `_, + 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 + +* Mac OS X with GCC 4.2.1 and Clang 4.2, 5.1.0 + +* 64-bit Windows with Visual C++ 2010 and + `2013 `_ + +* 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 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:: + + fmt::print("{}", std::numeric_limits::infinity()); + +always prints ``inf``. + +.. _ease-of-use: + +Ease of Use +----------- + +C++ Format has small self-contained code base consisting of a single header file +and a single source file and no external dependencies. A permissive BSD `license +`_ allows using the library both +in open-source and commercial projects. + +.. raw:: html + + GitHub Repository

+ +
+ +