libs/core/doc/nvp.qbk

   1 [/
   2 Copyright 2019 Glen Joseph Fernandes
   3 (glenjofe@gmail.com)
   4
   5 Distributed under the Boost Software License, Version 1.0.
   6 (http://www.boost.org/LICENSE_1_0.txt)
   7 ]
   8
   9 [section:nvp nvp]
  10
  11 [section Overview]
  12
  13 The header <boost/core/nvp.hpp> provides the class template `boost::nvp` that
  14 pairs a name (`const char*`) with the address of a value (`T*`). It is the new
  15 implementation of the NVP type previously provided by the Boost Serialization
  16 library. This type now lives in the Core library so that other Boost libraries
  17 can support named value serialization without taking a dependency on the
  18 Serialization library.
  19
  20 [endsect]
  21
  22 [section Examples]
  23
  24 The following snippet shows use in a member serialize function:
  25
  26 ```
  27 template<class A>
  28 void serialize(A& archive, unsigned)
  29 {
  30     archive & boost::make_nvp("x", x_) & boost::make_nvp("y", y_);
  31 }
  32 ```
  33
  34 [endsect]
  35
  36 [section Reference]
  37
  38 ```
  39 namespace boost {
  40
  41 template<class T>
  42 class nvp {
  43 public:
  44     nvp(const char* name, T& value) noexcept;
  45
  46     const char* name() const noexcept;
  47
  48     T& value() const noexcept;
  49
  50     const T& const_value() const noexcept;
  51 };
  52
  53 template<class T>
  54 const nvp<T> make_nvp(const char* name, T& value) noexcept;
  55
  56 } /* boost */
  57
  58 #define BOOST_NVP(object) ``['see below]``
  59 ```
  60
  61 [section Constructors]
  62
  63 [variablelist
  64 [[`nvp(const char* name, T& value) noexcept;`]
  65 [Initializes the stored name pointer with `name` and the value pointer with
  66 `addressof(value)`.]]]
  67
  68 [endsect]
  69
  70 [section Members]
  71
  72 [variablelist
  73 [[`const char* name() const noexcept;`]
  74 [Returns a pointer to the name.]]
  75 [[`T& value() const noexcept;`]
  76 [Returns a reference to the value.]]
  77 [[`const T& const_value() const noexcept;`]
  78 [Returns a reference to the value.]]]
  79
  80 [endsect]
  81
  82 [section Functions]
  83
  84 [variablelist
  85 [[`template<class T> const nvp<T> make_nvp(const char* name, T& value)
  86 noexcept;`]
  87 [Returns `nvp<T>(name, value)`.]]]
  88
  89 [endsect]
  90
  91 [section Macros]
  92
  93 [variablelist
  94 [[`#define BOOST_NVP(object) see below`]
  95 [Expands to `boost::make_nvp(BOOST_STRINGIZE(object), object)`.]]]
  96
  97 [endsect]
  98
  99 [endsect]
 100
 101 [section History]
 102
 103 Robert Ramey originally implemented NVP in the Serialization library. Glen
 104 Fernandes implemented this new (but compatible) version in the Core library.
 105
 106 [endsect]
 107
 108 [endsect]