From 2b033ce05db9558fcb4971afc85dbc7dd6cdb42d Mon Sep 17 00:00:00 2001 From: Glen Fernandes Date: Mon, 3 Feb 2014 16:42:57 -0800 Subject: [PATCH] Improve documentation for make_shared for arrays --- make_shared_array.html | 264 +++++++++++++++++++++++++++-------------- make_unique.html | 168 +++++++++++++++----------- 2 files changed, 272 insertions(+), 160 deletions(-) diff --git a/make_shared_array.html b/make_shared_array.html index e7d80d4..76e4f20 100644 --- a/make_shared_array.html +++ b/make_shared_array.html @@ -8,13 +8,13 @@

boost.png (6897 bytes)make_shared and allocate_shared for arrays

-

Introduction
- Synopsis
+

Introduction
+ Synopsis
+ Common Requirements
Free Functions
- Examples
History
References

-

Introduction

+

Introduction

Originally the Boost function templates make_shared and allocate_shared were for efficient allocation of shared objects only. There was a need to have efficient allocation of @@ -28,24 +28,24 @@ make_shared uses the global operator new to allocate memory, whereas allocate_shared uses an user-supplied allocator, allowing finer control.

-

Synopsis

+

Synopsis

namespace boost {
     template<typename U> // U is T[]
     shared_ptr<U> make_shared(size_t size);
 
     template<typename U, typename A> // U is T[]
     shared_ptr<U> allocate_shared(const A& allocator, size_t size);
-    
+
     template<typename U> // U is T[N]
     shared_ptr<U> make_shared();
 
     template<typename U, typename A> // U is T[N]
     shared_ptr<U> allocate_shared(const A& allocator);
-   
+
     template<typename U> // U is T[]
     shared_ptr<U> make_shared(size_t size, const T& value);
 
-    template<typename U, typename A> // U is T[]
+    template<typename U, typename A>  // U is T[]
     shared_ptr<U> allocate_shared(const A& allocator, size_t size, const T& value);
 
     template<typename U> // U is T[N]
@@ -66,95 +66,183 @@
     template<typename U, typename A> // U is T[N]
     shared_ptr<U> allocate_shared_noinit(const A& allocator);
 }
-

Free Functions

- 
template<typename U> // U is T[]
-shared_ptr<U> make_shared(size_t size);
-
-template<typename U, typename A> // U is T[]
-shared_ptr<U> allocate_shared(const A& allocator, size_t size);
-
-template<typename U> // U is T[N]
-shared_ptr<U> make_shared();
-
-template<typename U, typename A> // U is T[N]
-shared_ptr<U> allocate_shared(const A& allocator);
+

Common Requirements

+ 
template<typename U>
+    shared_ptr<U> make_shared(args);
+template<typename U, typename A>
+    shared_ptr<U> allocate_shared(const A& allocator, args);
+template<typename U>
+    shared_ptr<U> make_shared_noinit(args);
+template<typename U, typename A>
+    shared_ptr<U> allocate_shared_noinit(const A& allocator, args);
-

Requires: The expression - new(pointer) T(), where pointer is a - void* pointing to storage suitable to hold an object of - type T, shall be well-formed. A shall be an - Allocator, as described in section 20.1.5 (Allocator - requirements) of the C++ Standard. The copy constructor and - destructor of A shall not throw.

-

Effects: Allocates memory suitable for an array of type - T and size size and constructs an array of - objects in it via the placement new expression new(pointer) - T(). allocate_shared uses a copy of - allocator to allocate memory. If an exception is thrown, - has no effect.

+

Requires: U is of the form T[] or + T[N]. A shall be an Allocator, as + described in section 17.6.3.5 [Allocator + requirements] of the C++ Standard. The copy constructor and + destructor of A shall not throw exceptions.

+

Effects: Allocates memory for an object of type U + (or T[size] when U is T[], + where size is determined from args + as specified by the concrete overload). The object is initialized as + specified by the concrete overload. The templates + allocate_shared and allocate_shared_noinit + use a copy of allocator to allocate memory. If an + exception is thrown, the functions have no effect.

Returns: A shared_ptr instance that stores and - owns the address of the newly constructed array of type T - and size size.

-

Postconditions: - get() != 0 && use_count() == 1.

-

Throws: bad_alloc, or an exception thrown from - A::allocate or the constructor of T.

-

Notes: This implementation allocates the memory required for - the returned shared_ptr and an array of type - T of size size in a single allocation. This - provides efficiency to equivalent to an intrusive smart pointer.

-
- 
template<typename U> // U is T[]
-shared_ptr<U> make_shared(size_t size, const T& value);
-
-template<typename U, typename A> // U is T[]
-shared_ptr<U> allocate_shared(const A& allocator, size_t size, const T& value);
-
-template<typename U> // U is T[N]
-shared_ptr<U> make_shared(const T& value);
-
-template<typename U, typename A> // U is T[N]
-shared_ptr<U> allocate_shared(const A& allocator, const T& value);
-
-

Notes: These overloads initialize array objects with the given + owns the address of the newly constructed object.

+

Postconditions: r.get() != 0 && + r.use_count() == 1, where r is the return value.

+

Throws: bad_alloc, an exception thrown from + A::allocate, or from the initialization of the + object.

- 
template<typename U> // U is T[]
-shared_ptr<U> make_shared_noinit(size_t size);
-
-template<typename U, typename A> // U is T[]
-shared_ptr<U> allocate_shared_noinit(const A& allocator, size_t size);
-
-template<typename U> // U is T[N]
-shared_ptr<U> make_shared_noinit();
-
-template<typename U, typename A> // U is T[N]
-shared_ptr<U> allocate_shared_noinit(const A& allocator);
-

Notes: These overloads do not perform value initialization of - array objects.

-
-

Examples

-

The following examples value-initialize objects.

-
- 
boost::shared_ptr<int[]>     a1  = boost::make_shared<int[]>(size);
-boost::shared_ptr<int[8]>    a2  = boost::make_shared<int[8]>();
-boost::shared_ptr<int[][2]>  a3  = boost::make_shared<int[][2]>(size);
-boost::shared_ptr<int[4][2]> a4  = boost::make_shared<int[4][2]>();
+

Remarks:

+
+

This implementation performs no more than one memory + allocation. This provides efficiency to equivalent to an intrusive + smart pointer.

+

When an object of an array type T is specified to be + initialized to a value of the same type value, this + shall be interpreted to mean that each array element of the object + is initialized to the corresponding element from + value.

+

When an object of an array type is specified to be + value-initialized, this shall be interpreted to mean that each + array element of the object is value-initialized.

+

Array elements are initialized in ascending order of their + addresses.

+

When a subobject of a non-array type T is specified to + be initialized to a value value, or to + T(list...), where list... is a list of + constructor arguments, make_shared shall perform this + initialization via the expression ::new(ptr) T(value) + or ::new(ptr) T(list...) respectively, where + ptr has type void* and points to storage + suitable to hold an object of type T.

+

When a subobject of non-array type T is specified to + be value-initialized, make_shared shall perform this + initialization via the expression ::new(ptr) T(), where + ptr has type void* and points to storage + suitable to hold an object of type T.

+

When a subobject of non-array type T is specified to + be default-initialized, make_shared_noinit and + allocate_shared_noinit shall perform this + initialization via the expression ::new(ptr) T, where + ptr has type void* and points to storage + suitable to hold an object of type T.

+

When the lifetime of the object managed by the return value ends, + or when the initialization of an array element throws an exception, + the initialized elements should be destroyed in the reverse order + of their construction.

+
-

The following examples initialize objects with a given value.

+

Free Functions

+ 
template<typename U> 
+    shared_ptr<U> make_shared(size_t size);
+template<typename U, typename A> 
+    shared_ptr<U> allocate_shared(const A& allocator, size_t size);
- 
boost::shared_ptr<int[]>     a5  = boost::make_shared<int[]>(size, 1);
-boost::shared_ptr<int[8]>    a6  = boost::make_shared<int[8]>(1);
-boost::shared_ptr<int[][2]>  a7  = boost::make_shared<int[][2]>(size, {1, 2});
-boost::shared_ptr<int[4][2]> a8  = boost::make_shared<int[4][2]>({1, 2});
+

Returns: A shared_ptr to a value-initialized + object of type T[size].

+

Remarks: These overloads shall only participate in overload + resolution when U is of the form T[].

-

The following examples default-initialize objects.

- 
boost::shared_ptr<int[]>     a9  = boost::make_shared_noinit<int[]>(size);
-boost::shared_ptr<int[8]>    a10 = boost::make_shared_noinit<int[8]>();
-boost::shared_ptr<int[][2]>  a11 = boost::make_shared_noinit<int[][2]>(size);
-boost::shared_ptr<int[4][2]> a12 = boost::make_shared_noinit<int[4][2]>();
+

Examples:

+
+ 
boost::shared_ptr<int[]> a1 = boost::make_shared<int[]>(size);
+boost::shared_ptr<int[][2]> a2 = boost::make_shared<int[][2]>(size);
+
+
+ 
template<typename U> 
+    shared_ptr<U> make_shared();
+template<typename U, typename A> 
+    shared_ptr<U> allocate_shared(const A& allocator);
+
+

Returns: A shared_ptr to a value-initialized + object of type T[N].

+

Remarks: These overloads shall only participate in overload + resolution when U is of the form T[N].

+
+
+

Examples:

+
+ 
boost::shared_ptr<int[8]> a1 = boost::make_shared<int[8]>();
+boost::shared_ptr<int[4][2]> a2 = boost::make_shared<int[4][2]>();
+
+
+ 
template<typename U> 
+    shared_ptr<U> make_shared(size_t size, const T& value);
+template<typename U, typename A> 
+    shared_ptr<U> allocate_shared(const A& allocator, size_t size, const T& value);
+
+

Returns: A shared_ptr to an object of type + T[size], where each array element of type T + is initialized to value.

+

Remarks: These overloads shall only participate in overload + resolution when U is of the form T[].

+
+
+

Examples:

+
+ 
boost::shared_ptr<int[]> a1 = boost::make_shared<int[]>(size, 1);
+boost::shared_ptr<int[][2]> a2 = boost::make_shared<int[][2]>(size, {1, 2});
+
+
+ 
template<typename U> 
+    shared_ptr<U> make_shared(const T& value);
+template<typename U, typename A> 
+    shared_ptr<U> allocate_shared(const A& allocator, const T& value);
+
+

Returns: A shared_ptr to an object of type + T[N], where each array element of type T is + initialized to value.

+

Remarks: These overloads shall only participate in overload + resolution when U is of the form T[N].

+
+
+

Examples:

+
+ 
boost::shared_ptr<int[8]> a1 = boost::make_shared<int[8]>(1);
+boost::shared_ptr<int[4][2]> a2 = boost::make_shared<int[4][2]>({1, 2});
+
+
+ 
template<typename U> 
+    shared_ptr<U> make_shared_noinit(size_t size);
+template<typename U, typename A> 
+    shared_ptr<U> allocate_shared_noinit(const A& allocator, size_t size);
+
+

Returns: A shared_ptr to a default-initialized + object of type T[size].

+

Remarks: These overloads shall only participate in overload + resolution when U is of the form T[].

+
+
+

Examples:

+
+ 
boost::shared_ptr<int[]> a1 = boost::make_shared_noinit<int[]>(size);
+boost::shared_ptr<int[][2]> a2 = boost::make_shared_noinit<int[][2]>(size);
+
+
+ 
template<typename U> 
+    shared_ptr<U> make_shared_noinit();
+template<typename U, typename A> 
+    shared_ptr<U> allocate_shared_noinit(const A& allocator);
+
+

Returns: A shared_ptr to a default-initialized + object of type T[N].

+

Remarks: These overloads shall only participate in overload + resolution when U is of the form T[N].

+
+
+

Examples:

+
+ 
boost::shared_ptr<int[8]> a1 = boost::make_shared_noinit<int[8]>();
+boost::shared_ptr<int[4][2]> a2 = boost::make_shared_noinit<int[4][2]>();
+

History

January 2014. Glen Fernandes reduced the overloads of make_shared and diff --git a/make_unique.html b/make_unique.html index 2d5544d..fc46428 100644 --- a/make_unique.html +++ b/make_unique.html @@ -7,16 +7,16 @@

boost.png (6897 bytes)make_unique

-

Introduction
- Synopsis
+

Introduction
+ Synopsis
+ Common Requirements
Free Functions
- Examples
History

-

Introduction

+

Introduction

The header file <boost/make_unique.hpp> provides overloaded function template make_unique for convenient creation of unique_ptr objects.

-

Synopsis

+

Synopsis

namespace boost {
     template<typename U> // U is not array
     unique_ptr<U> make_unique();
@@ -29,103 +29,127 @@
     template<typename U> // U is not array
     unique_ptr<U> make_unique(U&& value);
 
+    template<typename U> // U is T[]
+    unique_ptr<U> make_unique(size_t size);
+
     template<typename U> // U is not array
     unique_ptr<U> make_unique_noinit();
 
-    template<typename U> // U is T[]
-    unique_ptr<U> make_unique(size_t size);
-
     template<typename U> // U is T[]
     unique_ptr<U> make_unique_noinit(size_t size);
 }
-

Free Functions

- 
template<typename U> // U is not array
-unique_ptr<U> make_unique();
+

Common Requirements

+ 
template<typename U>
+    unique_ptr<U> make_unique(args);
+template<typename U>
+    unique_ptr<U> make_unique_noinit(args);
-

Requires: The expression new U() shall be - well-formed.

-

Effects: Constructs an object of type U via the - expression new U().

+

Effects: Allocates memory for an object of type U + (or T[size] when U is T[], + where size is determined from args as + specified by the concrete overload). The object is initialized from + args as specified by the concrete overload. If an + exception is thrown, the functions have no effect.

Returns: A unique_ptr instance that stores and owns the address of the newly constructed object.

-

Postconditions: get() != 0.

+

Postconditions: r.get() != 0, where + r is the return value.

Throws: bad_alloc, or an exception thrown from - the constructor of U.

+ the initialization of the object.

- 
template<typename U, typename... Args> // U is not array
-unique_ptr<U> make_unique(Args&&... args);
-

Requires: The expression - new U(forward<Args>(args)...) shall be - well-formed.

-

Effects: Constructs an object of type U via the - expression new U(forward<Args>(args)...).

+

Remarks:

+
+

When an object of a non-array type T is specified to + be initialized to a value value, or to + T(list...), where list... is a list of + constructor arguments, make_unique shall perform this + initialization via the expression new T(value) or + new T(list...) respectively.

+

When an object of type T is specified to be + value-initialized, make_unique shall perform this + initialization via the expression new T().

+

When an object of type T is specified to be + default-initialized, make_unique_noinit shall perform + this initialization via the expression new T.

+
- 
template<typename U> // U is not array
+    
Free Functions

+    
template<typename U, typename... Args>
+unique_ptr<U> make_unique(Args&&... args);
 
+    

+      
Returns: A unique_ptr to an object of type U, 
+        initialized to U(forward<Args>(args)...).

+      
Remarks: This overload shall only participate in overload 
+        resolution when U is not an array type.

+    

+    

+      
Examples:

+      

+        
unique_ptr<float> p1 = boost::make_unique<float>();
+unique_ptr<point> p2 = boost::make_unique<point>(x, y);

+      

+    

+    
template<typename U>
 unique_ptr<U> make_unique(U&& value);
 
     

-      
Requires: The expression new U(move(value)) shall 
-        be well-formed.
 
-      
Effects: Constructs an object of type U via the 
-        expression new U(move(value)).

+      
Returns: A unique_ptr to an object of type U, 
+        initialized to move(value).

+      
Remarks: This overload shall only participate in overload 
+        resolution when U is not an array type.

     

-    
template<typename U> // U is not array
-unique_ptr<U> make_unique_noinit();

     

-      
Requires: The expression new U shall be 
-        well-formed.

-      
Effects: Constructs an object of type U via the 
-        expression new U.

+      
Examples:

+      

+        
unique_ptr<string> p1 = boost::make_unique<string>({'a', 'b'});
+unique_ptr<point> p2 = boost::make_unique<point>({-10, 25});

+      

     

-    
template<typename U> // U is T[]
-unique_ptr<U> make_unique(size_t size);

+    
template<typename U>
+unique_ptr<U> make_unique(size_t size);
 
     

-      
Requires: The expression new T[size]() shall be 
-        well-formed.

-      
Effects: Constructs an array of objects of type 
-        U and size size via the expression 
-        new T[size]().

+      
Returns: A unique_ptr to a value-initialized object of type 
+        T[size].

+      
Remarks: This overload shall only participate in overload 
+        resolution when U is of the form T[].

     

-    
template<typename U> // U is T[]
-unique_ptr<U> make_unique_noinit(size_t size);

     

-      
Requires: The expression new T[size] shall be 
-        well-formed.

-      
Effects: Constructs an array of objects of type 
-        U and size size via the expression 
-        new T[size].

-    
    
-    
Examples

-    
For objects with value-initialization.

-    

-      
unique_ptr<float> p1 = boost::make_unique<float>();
-unique_ptr<point> p2 = boost::make_unique<point>();

+      
Examples:

+      

+        
unique_ptr<double[]> p1 = boost::make_unique<double[]>(4);
+unique_ptr<int[][2]> p2 = boost::make_unique<int[][2]>(2);

+      

     

-    
For objects with construction arguments.

+    
template<typename U>
+unique_ptr<U> make_unique_noinit();
 
     

-      
unique_ptr<float> p3 = boost::make_unique<float>(1.0f);
-unique_ptr<point> p4 = boost::make_unique<point>(x, y);

+      
Returns: A unique_ptr to a default-initialized object of 
+        type U.

+      
Remarks: This overload shall only participate in overload 
+        resolution when U is not an array type.

     

-    
For objects with given value.

     

-      
unique_ptr<string> p4 = boost::make_unique<string>({'a', 'b'});
-unique_ptr<type>   p5 = boost::make_unique<type>({3, 5, 4});

+      
Examples:

+      

+        
unique_ptr<float> p1 = boost::make_unique_noinit<float>();
+unique_ptr<point> p2 = boost::make_unique_noinit<point>();

+      

     

-    
For objects with default-initialization.

+    
template<typename U>
+unique_ptr<U> make_unique_noinit(size_t size);
 
     

-      
unique_ptr<float> p6 = boost::make_unique_noinit<float>();
-unique_ptr<point> p7 = boost::make_unique_noinit<point>();

+      
Returns: A unique_ptr to a default-initialized object of 
+        type T[size].

+      
Remarks: This overload shall only participate in overload 
+        resolution when U is of the form T[].

     

-    
For arrays with value-initialization.

     

-      
unique_ptr<double[]> a1 = boost::make_unique<double[]>();
-unique_ptr<int[][4]> a2 = boost::make_unique<int[][4]>();

+      
Examples:

+      

+        
unique_ptr<double[]> p1 = boost::make_unique_noinit<double[]>(4);
+unique_ptr<int[][2]> p2 = boost::make_unique_noinit<int[][2]>(2);

+      

     

-    
For arrays with default-initialization.

-    

-      
unique_ptr<double[]> a3 = boost::make_unique_noinit<double[]>();
-unique_ptr<int[][4]> a4 = boost::make_unique_noinit<int[][4]>();

-    
   
     
History

     
January 2014. Glen Fernandes contributed implementations of 
       make_unique for objects and arrays.