libs/utility/doc/compressed_pair.qbk

   1 [/
   2   Copyright 2000 Beman Dawes & John Maddock.
   3
   4   Distributed under the Boost Software License, Version 1.0.
   5
   6   See accompanying file LICENSE_1_0.txt
   7   or copy at http://boost.org/LICENSE_1_0.txt
   8 ]
   9
  10 [article Compressed_Pair
  11     [quickbook 1.5]
  12     [authors [Cleary, Steve]]
  13     [authors [Dawes, Beman]]
  14     [authors [Hinnant, Howard]]
  15     [authors [Maddock, John]]
  16     [copyright 2000 Steve Cleary, Beman Dawes, Howard Hinnant &amp; John Maddock]
  17     [license
  18         Distributed under the Boost Software License, Version 1.0.
  19         (See accompanying file LICENSE_1_0.txt or copy at
  20         [@http://www.boost.org/LICENSE_1_0.txt])
  21     ]
  22 ]
  23
  24 [section Overview]
  25
  26 All of the contents of `<boost/compressed_pair.hpp>` are defined inside
  27 `namespace boost`.
  28
  29 The class `compressed_pair` is very similar to `std::pair`, but if either of
  30 the template arguments are empty classes, then the ['empty base-class
  31 optimisation] is applied to compress the size of the pair.
  32
  33 [endsect]
  34
  35 [section Synopsis]
  36
  37     template <class T1, class T2>
  38     class compressed_pair
  39     {
  40     public:
  41         typedef T1                                                 first_type;
  42         typedef T2                                                 second_type;
  43         typedef typename call_traits<first_type>::param_type       first_param_type;
  44         typedef typename call_traits<second_type>::param_type      second_param_type;
  45         typedef typename call_traits<first_type>::reference        first_reference;
  46         typedef typename call_traits<second_type>::reference       second_reference;
  47         typedef typename call_traits<first_type>::const_reference  first_const_reference;
  48         typedef typename call_traits<second_type>::const_reference second_const_reference;
  49
  50                  compressed_pair() : base() {}
  51                  compressed_pair(first_param_type x, second_param_type y);
  52         explicit compressed_pair(first_param_type x);
  53         explicit compressed_pair(second_param_type y);
  54
  55         compressed_pair& operator=(const compressed_pair&);
  56
  57         first_reference       first();
  58         first_const_reference first() const;
  59
  60         second_reference       second();
  61         second_const_reference second() const;
  62
  63         void swap(compressed_pair& y);
  64     };
  65
  66 The two members of the pair can be accessed using the member functions
  67 `first()` and `second()`. Note that not all member functions can be
  68 instantiated for all template parameter types. In particular
  69 `compressed_pair` can be instantiated for reference and array types,
  70 however in these cases the range of constructors that can be used are
  71 limited. If types `T1` and `T2` are the same type, then there is only
  72 one version of the single-argument constructor, and this constructor
  73 initialises both values in the pair to the passed value.
  74
  75 Note that if either member is a POD type, then that member is not
  76 zero-initialized by the `compressed_pair` default constructor: it's up
  77 to you to supply an initial value for these types if you want them to have
  78 a default value.
  79
  80 Note that `compressed_pair` can not be instantiated if either of the
  81 template arguments is a union type, unless there is compiler support for
  82 `boost::is_union`, or if `boost::is_union` is specialised for the union
  83 type.
  84
  85 Finally, a word of caution for Visual C++ 6 users: if either argument is an
  86 empty type, then assigning to that member will produce memory corruption,
  87 unless the empty type has a "do nothing" assignment operator defined. This
  88 is due to a bug in the way VC6 generates implicit assignment operators.
  89
  90 [endsect]
  91
  92 [section Acknowledgments]
  93
  94 Based on contributions by Steve Cleary, Beman Dawes, Howard Hinnant and
  95 John Maddock.
  96
  97 Maintained by [@mailto:john@johnmaddock.co.uk John Maddock].
  98
  99 [endsect]