From e821380d69a549dc64900693942789d21aa4df5e Mon Sep 17 00:00:00 2001 From: Abseil Team Date: Thu, 4 Oct 2018 08:55:32 -0700 Subject: Export of internal Abseil changes. -- e09635c907d471ab46e14fb8091988c92cb4e78e by Abseil Team : Fix syntax error in documentation '}' -> ')' PiperOrigin-RevId: 215744854 -- a9e2d036850748137355f4a07083f1052d5c3766 by Abseil Team : WrapUnique's comment about avoiding explicit template specification doesn't make clear what alternative there is when this hurts readability. Add a comment about the approved alternative. PiperOrigin-RevId: 215634917 -- 596b8ff41ff70b27bff3a2369038c0fe7d13ae85 by Greg Falcon : Allow for a small amount of slop in timeout tests, as not all OSs we support give us the perfect timing behavior we're testing for here. PiperOrigin-RevId: 215615172 GitOrigin-RevId: e09635c907d471ab46e14fb8091988c92cb4e78e Change-Id: I30721294bac86510a49bb7f405149fc74c532abb --- absl/memory/memory.h | 24 +++++++++++++++++++----- 1 file changed, 19 insertions(+), 5 deletions(-) (limited to 'absl/memory') diff --git a/absl/memory/memory.h b/absl/memory/memory.h index a80aab0..1eaec0f 100644 --- a/absl/memory/memory.h +++ b/absl/memory/memory.h @@ -39,16 +39,30 @@ namespace absl { // Function Template: WrapUnique() // ----------------------------------------------------------------------------- // -// Adopts ownership from a raw pointer and transfers it to the returned -// `std::unique_ptr`, whose type is deduced. DO NOT specify the template type T -// when calling WrapUnique. +// Adopts ownership from a raw pointer and transfers it to the returned +// `std::unique_ptr`, whose type is deduced. Because of this deduction, *do not* +// specify the template type `T` when calling `WrapUnique`. // // Example: // X* NewX(int, int); // auto x = WrapUnique(NewX(1, 2)); // 'x' is std::unique_ptr. // -// `absl::WrapUnique` is useful for capturing the output of a raw pointer -// factory. However, prefer 'absl::make_unique(args...) over +// The purpose of WrapUnique is to automatically deduce the pointer type. If you +// wish to make the type explicit, for readability reasons or because you prefer +// to use a base-class pointer rather than a derived one, just use +// `std::unique_ptr` directly. +// +// Example: +// X* Factory(int, int); +// auto x = std::unique_ptr(Factory(1, 2)); +// - or - +// std::unique_ptr x(Factory(1, 2)); +// +// This has the added advantage of working whether Factory returns a raw +// pointer or a `std::unique_ptr`. +// +// While `absl::WrapUnique` is useful for capturing the output of a raw +// pointer factory, prefer 'absl::make_unique(args...)' over // 'absl::WrapUnique(new T(args...))'. // // auto x = WrapUnique(new X(1, 2)); // works, but nonideal. -- cgit v1.2.3