From 4f39500d47f8383cda1d67758dc1b32d1233342f Mon Sep 17 00:00:00 2001 From: Vinnie Falco Date: Sun, 22 Sep 2019 07:50:40 -0700 Subject: [PATCH] Add doc exposition and tidy --- README.md | 51 ++++++++++++++++++++++++++++++++++++--- doc/Jamfile | 4 ++-- doc/qbk/main.qbk | 62 +++++++++++++++++++++++++++++++++++++++++++----- 3 files changed, 106 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index dd3158b..09c508c 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,52 @@ Branch | Travis | Appveyor | Azure Pipelines | codecov.io | Docs | Matrix | :-------------: | ------ | -------- | --------------- | ---------- | ---- | ------ | -[`master`](https://github.com/boostorg/fixed_string/tree/master) | [![Build Status](https://travis-ci.org/boostorg/fixed_string.svg?branch=master)](https://travis-ci.org/boostorg/fixed_string) | [![Build status](https://ci.appveyor.com/api/projects/status/github/boostorg/fixed_string?branch=master&svg=true)](https://ci.appveyor.com/project/maintainer/fixed_string-xyzzy/branch/master) | [![Build Status](https://dev.azure.com/maintainer/fixed_string/_apis/build/status/pipeline?branchName=master)](https://dev.azure.com/maintainer/fixed_string/_build/latest?definitionId=6&branchName=master) | [![codecov](https://codecov.io/gh/boostorg/fixed_string/branch/master/graph/badge.svg)](https://codecov.io/gh/boostorg/fixed_string/branch/master) | [![Documentation](https://img.shields.io/badge/docs-master-brightgreen.svg)](http://www.boost.org/doc/libs/master/doc/html/fixed_string.html) | [![Matrix](https://img.shields.io/badge/matrix-master-brightgreen.svg)](http://www.boost.org/development/tests/master/developer/fixed_string.html) -[`develop`](https://github.com/boostorg/fixed_string/tree/develop) | [![Build Status](https://travis-ci.org/boostorg/fixed_string.svg?branch=develop)](https://travis-ci.org/boostorg/fixed_string) | [![Build status](https://ci.appveyor.com/api/projects/status/github/boostorg/fixed_string?branch=develop&svg=true)](https://ci.appveyor.com/project/maintainer/fixed_string-xyzzy/branch/develop) | [![Build Status](https://dev.azure.com/maintainer/fixed_string/_apis/build/status/pipeline?branchName=develop)](https://dev.azure.com/maintainer/fixed_string/_build/latest?definitionId=6&branchName=master) | [![codecov](https://codecov.io/gh/boostorg/fixed_string/branch/develop/graph/badge.svg)](https://codecov.io/gh/boostorg/fixed_string/branch/develop) | [![Documentation](https://img.shields.io/badge/docs-develop-brightgreen.svg)](http://www.boost.org/doc/libs/develop/doc/html/fixed_string.html) | [![Matrix](https://img.shields.io/badge/matrix-develop-brightgreen.svg)](http://www.boost.org/development/tests/develop/developer/fixed_string.html) +[`master`](https://github.com/vinniefalco/fixed_string/tree/master) | [![Build Status](https://travis-ci.org/vinniefalco/fixed_string.svg?branch=master)](https://travis-ci.org/vinniefalco/fixed_string) | [![Build status](https://ci.appveyor.com/api/projects/status/github/vinniefalco/fixed_string?branch=master&svg=true)](https://ci.appveyor.com/project/vinniefalco/fixed-string/branch/master) | [![Build Status](https://dev.azure.com/vinniefalco/fixed-string/_apis/build/status/pipeline?branchName=master)](https://dev.azure.com/vinniefalco/fixed-string/_build/latest?definitionId=6&branchName=master) | [![codecov](https://codecov.io/gh/vinniefalco/fixed_string/branch/master/graph/badge.svg)](https://codecov.io/gh/vinniefalco/fixed_string/branch/master) | [![Documentation](https://img.shields.io/badge/docs-master-brightgreen.svg)](http://www.boost.org/doc/libs/master/doc/html/fixed_string.html) | [![Matrix](https://img.shields.io/badge/matrix-master-brightgreen.svg)](http://www.boost.org/development/tests/master/developer/fixed_string.html) +[`develop`](https://github.com/vinniefalco/fixed_string/tree/develop) | [![Build Status](https://travis-ci.org/vinniefalco/fixed_string.svg?branch=develop)](https://travis-ci.org/vinniefalco/fixed_string) | [![Build status](https://ci.appveyor.com/api/projects/status/github/vinniefalco/fixed_string?branch=develop&svg=true)](https://ci.appveyor.com/project/vinniefalco/fixed-string/branch/develop) | [![Build Status](https://dev.azure.com/vinniefalco/fixed-string/_apis/build/status/pipeline?branchName=develop)](https://dev.azure.com/vinniefalco/fixed-string/_build/latest?definitionId=6&branchName=master) | [![codecov](https://codecov.io/gh/vinniefalco/fixed_string/branch/develop/graph/badge.svg)](https://codecov.io/gh/vinniefalco/fixed_string/branch/develop) | [![Documentation](https://img.shields.io/badge/docs-develop-brightgreen.svg)](http://www.boost.org/doc/libs/develop/doc/html/fixed_string.html) | [![Matrix](https://img.shields.io/badge/matrix-develop-brightgreen.svg)](http://www.boost.org/development/tests/develop/developer/fixed_string.html) -This is currently **NOT** an official Boost library. +## This is currently **NOT** an official Boost library. + +## Introduction + +This library provides a dynamically resizable string of characters with +compile-time fixed capacity and contiguous embedded storage in which the +characters are placed within the string object itself. Its API closely +resembles that of `std::string` + +## Motivation + +A fixed capacity string is useful when: + +* Memory allocation is not possible, e.g., embedded environments without a free + store, where only a stack and the static memory segment are available. +* Memory allocation imposes an unacceptable performance penalty. + e.g., with respect to latency. +* Allocation of objects with complex lifetimes in the static-memory + segment is required. +* A dynamically-resizable string is required within `constexpr` functions. +* The storage location of the static_vector elements is required to be + within the string object itself (e.g. to support memcopy for serialization + purposes). + +## Design + +The over-arching design goal is to resemble the interface and behavior of +`std::string` as much as possible. When any operation would exceed the +maximum allowed size of the string, `std::length_error` is thrown. All +algorithms which throw exceptions provide the strong exception safety +guarantee. + +## Iterators + +The iterator invalidation rules are different than those for `std::string`, +since: + +* Moving a string invalidates all iterators +* Swapping two strings invalidates all iterators + + +## License + +Distributed under the Boost Software License, Version 1.0. +(See accompanying file [LICENSE_1_0.txt](LICENSE_1_0.txt) or copy at +https://www.boost.org/LICENSE_1_0.txt) diff --git a/doc/Jamfile b/doc/Jamfile index 97c6d51..bb61e17 100644 --- a/doc/Jamfile +++ b/doc/Jamfile @@ -175,12 +175,12 @@ boostbook fixed_string : boost.root=../../../.. chapter.autolabel=1 - chunk.section.depth=8 # Depth to which sections should be chunked + chunk.section.depth=0 # Depth to which sections should be chunked chunk.first.sections=1 # Chunk the first top-level section? toc.section.depth=8 # How deep should recursive sections appear in the TOC? toc.max.depth=8 # How many levels should be created for each TOC? generate.section.toc.level=8 # Control depth of TOC generation in sections - generate.toc="chapter toc,title section nop reference nop" + generate.toc="" ../../../tools/boostbook/dtd : images diff --git a/doc/qbk/main.qbk b/doc/qbk/main.qbk index f8c46d4..af4ead5 100644 --- a/doc/qbk/main.qbk +++ b/doc/qbk/main.qbk @@ -30,16 +30,66 @@ [template include_file[path][^<''''''[path]''''''>]] [template issue[n] '''#'''[n]''''''] -[section:quickref Reference] +[/-----------------------------------------------------------------------------] + +[section Introduction] + +This library provides a dynamically resizable string of characters with +compile-time fixed capacity and contiguous embedded storage in which the +characters are placed within the string object itself. Its API closely +resembles that of `std::string` -[xinclude quickref.xml] [endsect] -[block'''This Page Intentionally Left Blank 1/2'''] -[section:ref This Page Intentionally Left Blank 2/2] + +[/-----------------------------------------------------------------------------] + +[section Motivation] + +A fixed capacity string is useful when: + +* Memory allocation is not possible, e.g., embedded environments without a free + store, where only a stack and the static memory segment are available. +* Memory allocation imposes an unacceptable performance penalty. + e.g., with respect to latency. +* Allocation of objects with complex lifetimes in the static-memory + segment is required. +* A dynamically-resizable string is required within `constexpr` functions. +* The storage location of the static_vector elements is required to be + within the string object itself (e.g. to support memcopy for serialization + purposes). + +[endsect] + +[/-----------------------------------------------------------------------------] + +[section Design] + +The over-arching design goal is to resemble the interface and behavior of +`std::string` as much as possible. When any operation would exceed the +maximum allowed size of the string, `std::length_error` is thrown. All +algorithms which throw exceptions provide the strong exception safety +guarantee. + +[endsect] + +[/-----------------------------------------------------------------------------] + +[section Iterators] + +The iterator invalidation rules are different than those for `std::string`, +since: + +* Moving a string invalidates all iterators +* Swapping two strings invalidates all iterators + +[endsect] + +[/-----------------------------------------------------------------------------] + +[section:ref Reference] [include reference.qbk] [endsect] -[block''''''] -This is the main file +[/-----------------------------------------------------------------------------] [xinclude index.xml]