[Boost-commit] svn:boost r84706 - branches/release/libs/container/doc

Subject: [Boost-commit] svn:boost r84706 - branches/release/libs/container/doc
From: igaztanaga_at_[hidden]
Date: 2013-06-08 18:55:23

Author: igaztanaga
Date: 2013-06-08 18:55:23 EDT (Sat, 08 Jun 2013)
New Revision: 84706
URL: http://svn.boost.org/trac/boost/changeset/84706

Log:
Added `static_vector` to non-standard containers section.

Text files modified: 
   branches/release/libs/container/doc/container.qbk |    28 +++++++++++++++++++++++++++-            
   1 files changed, 27 insertions(+), 1 deletions(-)

Modified: branches/release/libs/container/doc/container.qbk
==============================================================================
--- branches/release/libs/container/doc/container.qbk	Sat Jun  8 18:54:27 2013	(r84705)
+++ branches/release/libs/container/doc/container.qbk	2013-06-08 18:55:23 EDT (Sat, 08 Jun 2013)	(r84706)
@@ -236,7 +236,7 @@
 
 [section:stable_vector ['stable_vector]]
 
-This useful, fully STL-compliant stable container [@http://bannalia.blogspot.com/2008/09/introducing-stablevector.html designed by by Joaqu\u00EDn M. L\u00F3pez Mu\u00F1oz]
+This useful, fully STL-compliant stable container [@http://bannalia.blogspot.com/2008/09/introducing-stablevector.html designed by Joaqu\u00EDn M. L\u00F3pez Mu\u00F1oz]
 is an hybrid between `vector` and `list`, providing most of
 the features of `vector` except [@http://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#69 element contiguity].
 
@@ -432,6 +432,32 @@
 
 [endsect]
 
+[section:static_vector ['static_vector]]
+
+`static_vector` is an hybrid between `vector` and `array`: like `vector`, it's a sequence container 
+with contiguous storage that can change in size, along with the static allocation, low overhead,
+and fixed capacity of `array`. `static_vector` is based on Adam Wulkiewicz and Andrew Hundt's
+high-performance [@https://svn.boost.org/svn/boost/sandbox/varray/doc/html/index.html varray]
+class.
+
+The number of elements in a `static_vector` may vary dynamically up to a fixed capacity 
+because elements are stored within the object itself similarly to an array. However, objects are 
+initialized as they are inserted into `static_vector` unlike C arrays or `std::array` which must construct 
+all elements on instantiation. The behavior of `static_vector` enables the use of statically allocated 
+elements in cases with complex object lifetime requirements that would otherwise not be trivially 
+possible. Some other properties:
+
+* Random access to elements
+* Constant time insertion and removal of elements at the end
+* Linear time insertion and removal of elements at the beginning or in the middle.
+ 
+`static_vector` is well suited for use in a buffer, the internal implementation of other 
+classes, or use cases where there is a fixed limit to the number of elements that must be stored.
+Embedded and realtime applications where allocation either may not be available or acceptable 
+are a particular case where `static_vector` can be beneficial. 
+
+[endsect]
+
 [endsect]
 
 [section:Cpp11_conformance C++11 Conformance]