libs/smart_ptr/doc/smart_ptr/make_unique.adoc

   1 ////
   2 Copyright 2017 Peter Dimov
   3 Copyright 2017 Glen Joseph Fernandes (glenjofe@gmail.com)
   4
   5 Distributed under the Boost Software License, Version 1.0.
   6
   7 See accompanying file LICENSE_1_0.txt or copy at
   8 http://www.boost.org/LICENSE_1_0.txt
   9 ////
  10
  11 [#make_unique]
  12 # make_unique: Creating unique_ptr
  13 :toc:
  14 :toc-title:
  15 :idprefix: make_unique_
  16
  17 ## Description
  18
  19 The `make_unique` function templates provide convenient and safe ways to
  20 create `std::unique_ptr` objects.
  21
  22 ## Rationale
  23
  24 The {cpp}11 standard introduced `std::unique_ptr` but did not provide any
  25 `make_unique` utility like `std::make_shared` that provided the same
  26 exception safety and facility to avoid writing `new` expressions. Before it
  27 was implemented by some standard library vendors (and prior to the {cpp}14
  28 standard introducing `std::make_unique`), this library provided it due to
  29 requests from users.
  30
  31 This library also provides additional overloads of `make_unique` for
  32 default-initialization, when users do not need or want to incur the expense
  33 of value-initialization. The {cpp} standard does not yet provide this
  34 feature with `std::make_unique`.
  35
  36 ## Synopsis
  37
  38 `make_unique` is defined in `<boost/smart_ptr/make_unique.hpp>`.
  39
  40 [subs=+quotes]
  41 ```
  42 namespace boost {
  43   `// T is not an array`
  44   template<class T, class... Args>
  45     std::unique_ptr<T> make_unique(Args&&... args);
  46
  47   `// T is not an array`
  48   template<class T>
  49     std::unique_ptr<T> make_unique(type_identity_t<T>&& v);
  50
  51   `// T is an array of unknown bounds`
  52   template<class T>
  53     std::unique_ptr<T> make_unique(std::size_t n);
  54
  55   `// T is not an array`
  56   template<class T>
  57     std::unique_ptr<T> make_unique_noinit();
  58
  59   `// T is an array of unknown bounds`
  60   template<class T>
  61     std::unique_ptr<T> make_unique_noinit(std::size_t n);
  62 }
  63 ```
  64
  65 ## Free Functions
  66
  67 ```
  68 template<class T, class... Args>
  69   std::unique_ptr<T> make_unique(Args&&... args);
  70 ```
  71 [none]
  72 * {blank}
  73 +
  74 Constraints:: `T` is not an array.
  75 Returns:: `std::unique_ptr<T>(new T(std::forward<Args>(args)\...)`.
  76 Example:: `auto p = make_unique<int>();`
  77
  78 ```
  79 template<class T>
  80   std::unique_ptr<T> make_unique(type_identity_t<T>&& v);
  81 ```
  82 [none]
  83 * {blank}
  84 +
  85 Constraints:: `T` is not an array.
  86 Returns:: `std::unique_ptr<T>(new T(std::move(v))`.
  87 Example:: `auto p = make_unique<std::vector<int> >({1, 2});`
  88
  89 ```
  90 template<class T>
  91   std::unique_ptr<T> make_unique(std::size_t n);
  92 ```
  93 [none]
  94 * {blank}
  95 +
  96 Constraints:: `T` is an array of unknown bounds.
  97 Returns:: `std::unique_ptr<T>(new remove_extent_t<T>[n]())`.
  98 Example:: `auto p = make_unique<double[]>(1024);`
  99
 100 ```
 101 template<class T>
 102   std::unique_ptr<T> make_unique_noinit();
 103 ```
 104 [none]
 105 * {blank}
 106 +
 107 Constraints:: `T` is not an array.
 108 Returns:: `std::unique_ptr<T>(new T)`.
 109 Example:: `auto p = make_unique_noinit<double[1024]>();`
 110
 111 ```
 112 template<class T>
 113   std::unique_ptr<T> make_unique_noinit(std::size_t n);
 114 ```
 115 [none]
 116 * {blank}
 117 +
 118 Constraints:: `T` is an array of unknown bounds.
 119 Returns:: `std::unique_ptr<T>(new remove_extent_t<T>[n])`.
 120 Example:: `auto p = make_unique_noinit<double[]>(1024);`