{"id":20745,"date":"2018-09-04T09:12:09","date_gmt":"2018-09-04T16:12:09","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/vcblog\/?p=20745"},"modified":"2022-06-23T18:56:25","modified_gmt":"2022-06-23T18:56:25","slug":"stdoptional-how-when-and-why","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/cppblog\/stdoptional-how-when-and-why\/","title":{"rendered":"std::optional: How, when, and why"},"content":{"rendered":"

This post is part of a regular series of posts where the C++ product team here at Microsoft and other guests answer questions we have received from customers. The questions can be about anything C++ related: MSVC toolset, the standard language and library, the C++ standards committee, isocpp.org, CppCon, etc. Today\u2019s post is by Casey Carter.<\/i><\/p>\n

C++17\u00a0adds several new\u00a0“vocabulary types”\u00a0\u2013\u00a0types intended to be used in the interfaces between components from different sources \u2013 to the standard library.\u00a0MSVC<\/a>\u00a0has been shipping implementations of std::optional<\/code>,\u00a0std::any<\/code>, and\u00a0std::variant<\/code>\u00a0since the Visual Studio 2017 release, but we haven’t provided any guidelines on how and when these vocabulary types should be used. This article on\u00a0std::optional<\/code>\u00a0is the first of a series that will examine each of the vocabulary types in turn.<\/p>\n

The need for “sometimes-a-thing”<\/h3>\n

How do you write a function that optionally accepts or returns an object? The traditional solution is to choose one of the potential values as a sentinel to indicate the\u00a0absence<\/em>\u00a0of a value:<\/p>\n

void maybe_take_an_int(int value = -1); \/\/ an argument of -1 means \"no value\"\r\nint maybe_return_an_int(); \/\/ a return value of -1 means \"no value\"\r\n<\/pre>\n
This works reasonably well when one of the representable values of the type never occurs in practice. It’s less great when there’s no obvious choice of sentinel and you want to be able to pass all representable values. If that’s the case, the typical approach is to use a separate\u00a0boolean\u00a0to indicate whether the optional parameter holds a valid value:<\/p>\n
void maybe_take_an_int(int value = -1, bool is_valid = false);\r\nvoid or_even_better(pair<int,bool> param = std::make_pair(-1, false));\r\npair<int, bool> maybe_return_an_int();\r\n<\/pre>\n
This is also feasible, but awkward. The “two distinct parameters” technique of\u00a0maybe_take_an_int<\/code>\u00a0requires the caller to pass two things instead of one to represent a single notion, and fails silently when the caller forgets the\u00a0bool<\/code>\u00a0and simply calls\u00a0maybe_take_an_int(42)<\/code>. The use of\u00a0pair<\/code>\u00a0in the other two functions avoids those problems, but it’s possible for the user of the\u00a0pair<\/code>\u00a0to forget to check the\u00a0bool<\/code>\u00a0and potentially use a garbage value in the\u00a0int<\/code>. Passing\u00a0std::make_pair(42, true)<\/code>\u00a0or\u00a0std::make_pair(whatever, false)<\/code>\u00a0is also hugely different than passing\u00a042<\/code>\u00a0or nothing \u2013 we’ve made the interface hard to use.<\/p>\n
The need for “not-yet-a-thing”<\/h3>\n
How do you write a class with a member object whose initialization is delayed, i.e., optionally contains an object? For whatever reason, you do not want to initialize this member in a constructor. The initialization may happen in a later mandatory call, or it may happen only on request. When the object is destroyed the member must be destroyed only if it has been initialized. It’s possible to achieve this by allocating raw storage for the member object, using a\u00a0bool<\/code>\u00a0to track its initialization status, and doing horrible placement\u00a0new<\/code>\u00a0tricks:<\/p>\n
using T = \/* some object type *\/;\r\n\r\nstruct S {\r\n  bool is_initialized = false;\r\n  alignas(T) unsigned char maybe_T[sizeof(T)];\r\n\r\n  void construct_the_T(int arg) {\r\n    assert(!is_initialized);\r\n    new (&maybe_T) T(arg);\r\n    is_initialized = true;\r\n  }\r\n\r\n  T& get_the_T() {\r\n    assert(is_initialized);\r\n    return reinterpret_cast<T&>(maybe_T);\r\n  }\r\n\r\n  ~S() {\r\n    if (is_initialized) {\r\n      get_the_T().~T(); \/\/ destroy the T\r\n    }\r\n  }\r\n\r\n  \/\/ ... lots of code ...\r\n};\r\n<\/pre>\n
The \"lots of code\"<\/code>\u00a0comment in the body of\u00a0S<\/code>\u00a0is where you write copy\/move constructors\/assignment operators that do the right thing depending on whether the source and target objects contain an initialized\u00a0T<\/code>. If this all seems horribly messy and fragile to you, then give yourself a pat on the back \u2013 your instincts are right. We’re walking right along the cliff’s edge where small mistakes will send us tumbling into undefined behavior.<\/p>\n
Another possible solution to many of the above problems is to dynamically allocate the “optional” value and pass it via pointer\u00a0\u2013\u00a0ideally\u00a0std::unique_ptr<\/code>. Given that we C++ programmers are accustomed to using pointers, this solution has good usability: a\u00a0null\u00a0pointer indicates the no-value condition,\u00a0*<\/code>\u00a0is used to access the value,\u00a0std::make_unique<int>(42)<\/code>\u00a0is only slightly awkward compared to\u00a0return 42<\/code>\u00a0and\u00a0unique_ptr<\/code>\u00a0handles the deallocation for us automatically.\u00a0Of course\u00a0usability is not the only concern; readers accustomed to C++’s zero-overhead abstractions will immediately pounce upon this solution and complain that dynamic allocation is orders of magnitude more expensive than simply returning an integer. We’d like to solve this class of problem without\u00a0requiring<\/em>\u00a0dynamic allocation.<\/p>\n
optional<\/code>\u00a0is\u00a0mandatory<\/h3>\n
C++17’s solution to the above problems is\u00a0std::optional<\/code>.\u00a0optional<T><\/code>\u00a0directly addresses the issues that arise when passing or storing what may-or-may-not-currently-be an object.\u00a0optional<T><\/code>\u00a0provides interfaces to determine if it contains a\u00a0T<\/code>\u00a0and to query the stored value. You can initialize an\u00a0optional<\/code> with an actual\u00a0T<\/code>\u00a0value, or default-initialize it (or initialize with\u00a0std::nullopt<\/code>) to put it in the “empty” state.\u00a0optional<T><\/code>\u00a0even extends\u00a0T<\/code>‘s ordering operations\u00a0<<\/code>,\u00a0><\/code>,\u00a0<=<\/code>,\u00a0>=<\/code>\u00a0\u2013 where an empty\u00a0optional<\/code> compares as less than any\u00a0optional<\/code>\u00a0that contains a\u00a0T<\/code>\u00a0\u2013 so you can use it in some contexts exactly as if it were a\u00a0T<\/code>.\u00a0optional<T><\/code>\u00a0stores the\u00a0T<\/code>\u00a0object internally, so dynamic allocation is not necessary and in fact explicitly forbidden by the C++ Standard.<\/p>\n
Our functions that need to optionally pass a\u00a0T<\/code>\u00a0would be declared as:<\/p>\n
void maybe_take_an_int(optional<int> potential_value = nullopt); \r\n  \/\/ or equivalently, \"potential_value = {}\"\r\noptional<int> maybe_return_an_int();\r\n<\/pre>\n
Since optional<T><\/code>\u00a0can be initialized from a\u00a0T<\/code>\u00a0value, callers of\u00a0maybe_take_an_int<\/code> need not change unless they were explicitly passing\u00a0-1<\/code>\u00a0to indicate “not-a-value.” Similarly, the implementation of\u00a0maybe_return_an_int<\/code> need only change places that are returning\u00a0-1<\/code>\u00a0for “not-a-value” to instead return\u00a0nullopt<\/code>\u00a0(or equivalently\u00a0{}<\/code>).<\/p>\n
Callers of\u00a0maybe_return_an_int<\/code>\u00a0and the implementation of\u00a0maybe_take_an_int<\/code>\u00a0require more substantial changes. You can ask explicitly if an instance of\u00a0optional<\/code>\u00a0holds a value using either the\u00a0has_value<\/code>\u00a0member or by contextual conversion to\u00a0bool<\/code>:<\/p>\n
optional<int> o = maybe_return_an_int();\r\nif (o.has_value()) { \/* ... *\/ }\r\nif (o) { \/* ... *\/ } \/\/ \"if\" converts its condition to bool\r\n<\/pre>\n
Once you know that the\u00a0optional<\/code>\u00a0contains a value, you can extract it with the\u00a0*<\/code>\u00a0operator:<\/p>\n
if (o) { cout << \"The value is: \" << *o << '\\n'; }\r\n<\/pre>\n
or you can use the\u00a0value\u00a0member function to get the stored value or a\u00a0bad_optional_access<\/code>\u00a0exception if there is none, and not bother with checking:<\/p>\n
cout << \"The value is: \" << o.value() << '\\n';\r\n<\/pre>\n
or the\u00a0value_or<\/code>\u00a0member function if you’d rather get a fallback value than an exception from an empty\u00a0optional<\/code>:<\/p>\n
cout << \"The value might be: \" << o.value_or(42) << '\\n';\r\n<\/pre>\n
All of which together means we cannot inadvertently use a garbage value as was the case for the “traditional” solutions. Attempting to access the contained value of an empty\u00a0optional<\/code>\u00a0results in an exception if accessed with the\u00a0value()<\/code>\u00a0member, or undefined behavior if accessed via the\u00a0*<\/code>\u00a0operator that can be caught by debug libraries and static analysis tools. Updating the “old” code is probably as simple as replacing validity tests like\u00a0value ==\u00a0not_a_value_sentinel<\/code>\u00a0and\u00a0if (is_valid)<\/code>\u00a0with\u00a0opt_value.has_value()<\/code>\u00a0and\u00a0if (opt_value)<\/code>\u00a0and replacing uses with\u00a0*opt_value<\/code>.<\/p>\n
Returning to the concrete example, your function that looks up a string given an integer can simply return\u00a0optional<string><\/code>. This avoids the problems of the suggested solutions; we can<\/p>\n