libs/test/doc/html/boost_test/testing_tools/extended_comparison/collections.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Collections comparison</title>
   5 <link rel="stylesheet" href="../../../boostbook.css" type="text/css">
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
   7 <link rel="home" href="../../../index.html" title="Boost.Test">
   8 <link rel="up" href="../extended_comparison.html" title="Extended comparisons support">
   9 <link rel="prev" href="strings.html" title="Strings and C-strings comparison">
  10 <link rel="next" href="bitwise.html" title="Bitwise comparison">
  11 </head>
  12 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  13 <table cellpadding="2" width="100%"><tr>
  14 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
  15 <td align="center"><a href="../../../../../../../index.html">Home</a></td>
  16 <td align="center"><a href="../../../../../../../libs/libraries.htm">Libraries</a></td>
  17 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
  18 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
  19 <td align="center"><a href="../../../../../../../more/index.htm">More</a></td>
  20 </tr></table>
  21 <hr>
  22 <div class="spirit-nav">
  23 <a accesskey="p" href="strings.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../extended_comparison.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="bitwise.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
  24 </div>
  25 <div class="section">
  26 <div class="titlepage"><div><div><h4 class="title">
  27 <a name="boost_test.testing_tools.extended_comparison.collections"></a><a class="link" href="collections.html" title="Collections comparison">Collections
  28         comparison</a>
  29 </h4></div></div></div>
  30 <p>
  31           Instead of comparing a single value against another, there is often a need
  32           for comparing <span class="emphasis"><em>collections</em></span> of values. A collection
  33           and indirectly the values it contains may be considered in several ways:
  34         </p>
  35 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
  36 <li class="listitem">
  37               collection as a <span class="emphasis"><em>sequence of values</em></span>: this is the
  38               case for instance when <code class="computeroutput"><span class="identifier">N</span></code>
  39               values are stored in a container. Containers in this case are used
  40               for storing several values, and iterating over the containers yields
  41               sequences that can be compared <span class="bold"><strong>element-wise</strong></span>.
  42               The iteration should be in an order that is <span class="emphasis"><em>a priori</em></span>
  43               known <a href="#ftn.boost_test.testing_tools.extended_comparison.collections.f0" class="footnote" name="boost_test.testing_tools.extended_comparison.collections.f0"><sup class="footnote">[10]</sup></a>, for being able to compare the sequences. The values in
  44               the collection are independent each other, and subsets can be compared
  45               as well.
  46             </li>
  47 <li class="listitem">
  48               collection as an <span class="emphasis"><em>ensemble</em></span>: this is the case where
  49               the elements of the collection define an <span class="emphasis"><em>entity</em></span>,
  50               and no element can be dissociated from the others. An example would
  51               be a collection of letters for a specific word in the natural language;
  52               in this settings any of the character in the word/collection depends
  53               <span class="emphasis"><em>semantically</em></span> on the other and it is not possible
  54               to take a subset of it without breaking the meaning of the word. Another
  55               example would be a vector of size <code class="computeroutput"><span class="identifier">N</span></code>
  56               representing a point in a <code class="computeroutput"><span class="identifier">N</span></code>
  57               dimensional space, compared to another point with the relation "<code class="computeroutput"><span class="special">&lt;</span></code>": the comparison is application
  58               specific and a possible comparison would be the lexicographical ordering
  59               <a href="#ftn.boost_test.testing_tools.extended_comparison.collections.f1" class="footnote" name="boost_test.testing_tools.extended_comparison.collections.f1"><sup class="footnote">[11]</sup></a>.
  60             </li>
  61 </ul></div>
  62 <p>
  63           The following observations can be done:
  64         </p>
  65 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
  66 <li class="listitem">
  67               the methods employed for comparing collections should be chosen adequately
  68               with the meaning of the collection,
  69             </li>
  70 <li class="listitem">
  71               comparing sequences <span class="bold"><strong>element-wise</strong></span> often
  72               involves writing loops in the test body, and if a dedicated tool is
  73               already in place the test body would gain in clarity and expressiveness
  74               (including the report in case of failure),
  75             </li>
  76 <li class="listitem">
  77               some comparison methods such as the lexicographical one, have good
  78               general behavior (e.g. total ordering, defined for collections of different
  79               size), but are sometimes inappropriate.
  80             </li>
  81 </ul></div>
  82 <p>
  83           <a class="link" href="../../utf_reference/testing_tool_ref/assertion_boost_test_universal_macro.html" title="BOOST_TEST"><code class="computeroutput"><span class="identifier">BOOST_TEST</span></code></a> provides specific tools
  84           for comparing collections:
  85         </p>
  86 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
  87 <li class="listitem">
  88               using the <span class="emphasis"><em>native</em></span> <a href="#ftn.boost_test.testing_tools.extended_comparison.collections.f2" class="footnote" name="boost_test.testing_tools.extended_comparison.collections.f2"><sup class="footnote">[12]</sup></a> operator of the container of the collection, which is mentioned
  89               as the <a class="link" href="collections.html#ref_boost_test_coll_default_comp"><span class="emphasis"><em>default
  90               behavior</em></span></a>.
  91             </li>
  92 <li class="listitem">
  93               using <a class="link" href="collections.html#boost_test_coll_perelement">element-wise</a>
  94               comparison for which extended failure diagnostic is provided,
  95             </li>
  96 <li class="listitem">
  97               and using <a class="link" href="collections.html#boost_test_coll_default_lex">lexicographical</a>
  98               comparison for which extended failure diagnostic is provided,
  99             </li>
 100 </ul></div>
 101 <p>
 102           More details about the concept of <span class="emphasis"><em>collection</em></span> in the
 103           <span class="emphasis"><em>Unit Test Framework</em></span> is given <a class="link" href="collections.html#what_is_a_collection"><span class="emphasis"><em>here</em></span></a>.
 104         </p>
 105 <a name="ref_boost_test_coll_default_comp"></a><h4>
 106 <a name="boost_test.testing_tools.extended_comparison.collections.h0"></a>
 107           <span class="phrase"><a name="boost_test.testing_tools.extended_comparison.collections.default_comparison"></a></span><a class="link" href="collections.html#boost_test.testing_tools.extended_comparison.collections.default_comparison">Default
 108           comparison</a>
 109         </h4>
 110 <p>
 111           The default comparison dispatches to the existing overloaded comparison
 112           operator. The <span class="emphasis"><em>Unit Test Framework</em></span> distinguishes two
 113           use cases
 114         </p>
 115 <div class="orderedlist"><ol class="orderedlist" type="1">
 116 <li class="listitem">
 117               none of the comparison operand is a C-Array, in which case we use the
 118               <a class="link" href="collections.html#ref_boost_test_coll_default_comp_container">container
 119               default behavior</a>
 120             </li>
 121 <li class="listitem">
 122               one of the comparison operand is a C-array, in which case we <a class="link" href="collections.html#ref_boost_test_coll_c_arrays">mimic <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span></code></a>
 123               behavior
 124             </li>
 125 </ol></div>
 126 <a name="ref_boost_test_coll_default_comp_container"></a><h5>
 127 <a name="boost_test.testing_tools.extended_comparison.collections.h1"></a>
 128           <span class="phrase"><a name="boost_test.testing_tools.extended_comparison.collections.container_default_behavior"></a></span><a class="link" href="collections.html#boost_test.testing_tools.extended_comparison.collections.container_default_behavior">Container
 129           default behavior</a>
 130         </h5>
 131 <p>
 132           Given two containers <code class="computeroutput"><span class="identifier">c_a</span></code>
 133           and <code class="computeroutput"><span class="identifier">c_b</span></code> that are not C-arrays,
 134         </p>
 135 <pre class="programlisting"><span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">c_a</span> <span class="identifier">op</span> <span class="identifier">c_b</span><span class="special">)</span>
 136 </pre>
 137 <p>
 138           is equivalent, in terms of test success, to
 139         </p>
 140 <pre class="programlisting"><span class="keyword">auto</span> <span class="identifier">result</span> <span class="special">=</span> <span class="identifier">c_a</span> <span class="identifier">op</span> <span class="identifier">c_b</span><span class="special">;</span>
 141 <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">result</span><span class="special">);</span>
 142 </pre>
 143 <p>
 144           In the example below, <code class="computeroutput"><span class="keyword">operator</span><span class="special">==</span></code> is not defined for <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span></code>
 145           of different types, and the program would fail to compile if the corresponding
 146           lines were uncommented (<code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span></code>
 147           uses lexicographical comparison by default).
 148         </p>
 149 <div class="note"><table border="0" summary="Note">
 150 <tr>
 151 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../doc/src/images/note.png"></td>
 152 <th align="left">Note</th>
 153 </tr>
 154 <tr><td align="left" valign="top"><p>
 155             In the case of default comparison, there is no additional diagnostic
 156             provided by the <span class="emphasis"><em>Unit Test Framework</em></span>. See the section
 157             <a class="link" href="collections.html#ref_boost_test_coll_special_macro"><code class="computeroutput"><span class="identifier">BOOST_TEST_SPECIALIZED_COLLECTION_COMPARE</span></code></a>
 158             below.
 159           </p></td></tr>
 160 </table></div>
 161 <h6>
 162 <a name="boost_test.testing_tools.extended_comparison.collections.h2"></a>
 163           <span class="phrase"><a name="boost_test.testing_tools.extended_comparison.collections.example_descr"></a></span><a class="link" href="collections.html#boost_test.testing_tools.extended_comparison.collections.example_descr">Example:
 164           BOOST_TEST containers comparison default</a>
 165         </h6>
 166 <div class="informaltable"><table class="table">
 167 <colgroup><col></colgroup>
 168 <thead><tr><th>
 169                   <p>
 170                     Code
 171                   </p>
 172                 </th></tr></thead>
 173 <tbody><tr><td>
 174 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="preprocessor">#define</span> <span class="identifier">BOOST_TEST_MODULE</span> <span class="identifier">boost_test_sequence</span>
 175 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">test</span><span class="special">/</span><span class="identifier">included</span><span class="special">/</span><span class="identifier">unit_test</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 176 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">vector</span><span class="special">&gt;</span>
 177
 178 <span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span> <span class="identifier">test_collections_vectors</span> <span class="special">)</span>
 179 <span class="special">{</span>
 180   <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="identifier">a</span><span class="special">{</span><span class="number">1</span><span class="special">,</span><span class="number">2</span><span class="special">,</span><span class="number">3</span><span class="special">},</span> <span class="identifier">c</span><span class="special">{</span><span class="number">1</span><span class="special">,</span><span class="number">5</span><span class="special">,</span><span class="number">3</span><span class="special">,</span><span class="number">4</span><span class="special">};</span>
 181   <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">long</span><span class="special">&gt;</span> <span class="identifier">b</span><span class="special">{</span><span class="number">1</span><span class="special">,</span><span class="number">5</span><span class="special">,</span><span class="number">3</span><span class="special">};</span>
 182
 183   <span class="comment">// the following does not compile</span>
 184   <span class="comment">//BOOST_TEST(a == b);</span>
 185   <span class="comment">//BOOST_TEST(a &lt;= b);</span>
 186
 187   <span class="comment">// stl defaults to lexicographical comparison</span>
 188   <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">a</span> <span class="special">&lt;</span> <span class="identifier">c</span><span class="special">);</span>
 189   <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">a</span> <span class="special">&gt;=</span> <span class="identifier">c</span><span class="special">);</span>
 190   <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">a</span> <span class="special">!=</span> <span class="identifier">c</span><span class="special">);</span>
 191 <span class="special">}</span>
 192 </pre>
 193                 </td></tr></tbody>
 194 </table></div>
 195 <div class="informaltable"><table class="table">
 196 <colgroup><col></colgroup>
 197 <thead><tr><th>
 198                   <p>
 199                     Output
 200                   </p>
 201                 </th></tr></thead>
 202 <tbody><tr><td>
 203 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="special">&gt;</span> <span class="special">./</span><span class="identifier">boost_test_container_default</span> <span class="special">--</span><span class="identifier">log_level</span><span class="special">=</span><span class="identifier">all</span>
 204 <span class="identifier">Running</span> <span class="number">1</span> <span class="identifier">test</span> <span class="keyword">case</span><span class="special">...</span>
 205 <span class="identifier">Entering</span> <span class="identifier">test</span> <span class="identifier">module</span> <span class="string">"boost_test_sequence"</span>
 206 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">(</span><span class="number">13</span><span class="special">):</span> <span class="identifier">Entering</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"test_collections_vectors"</span>
 207 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">(</span><span class="number">23</span><span class="special">):</span> <span class="identifier">info</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">a</span> <span class="special">&lt;</span> <span class="identifier">c</span> <span class="identifier">has</span> <span class="identifier">passed</span>
 208 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">(</span><span class="number">24</span><span class="special">):</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test_collections_vectors"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">a</span> <span class="special">&gt;=</span> <span class="identifier">c</span> <span class="identifier">has</span> <span class="identifier">failed</span>
 209 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">(</span><span class="number">25</span><span class="special">):</span> <span class="identifier">info</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">a</span> <span class="special">!=</span> <span class="identifier">c</span> <span class="identifier">has</span> <span class="identifier">passed</span>
 210 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">(</span><span class="number">13</span><span class="special">):</span> <span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"test_collections_vectors"</span><span class="special">;</span> <span class="identifier">testing</span> <span class="identifier">time</span><span class="special">:</span> <span class="number">208u</span><span class="identifier">s</span>
 211 <span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="identifier">module</span> <span class="string">"boost_test_sequence"</span><span class="special">;</span> <span class="identifier">testing</span> <span class="identifier">time</span><span class="special">:</span> <span class="number">286u</span><span class="identifier">s</span>
 212
 213 <span class="special">***</span> <span class="number">1</span> <span class="identifier">failure</span> <span class="identifier">is</span> <span class="identifier">detected</span> <span class="identifier">in</span> <span class="identifier">the</span> <span class="identifier">test</span> <span class="identifier">module</span> <span class="string">"boost_test_container_default"</span>
 214 </pre>
 215                 </td></tr></tbody>
 216 </table></div>
 217 <a name="ref_boost_test_coll_c_arrays"></a><h5>
 218 <a name="boost_test.testing_tools.extended_comparison.collections.h3"></a>
 219           <span class="phrase"><a name="boost_test.testing_tools.extended_comparison.collections.c_arrays_default_behavior"></a></span><a class="link" href="collections.html#boost_test.testing_tools.extended_comparison.collections.c_arrays_default_behavior">C-arrays
 220           default behavior</a>
 221         </h5>
 222 <p>
 223           As soon as one of the operands is a C-array, there is no <span class="emphasis"><em>default
 224           behavior</em></span> the <span class="emphasis"><em>Unit Test Framework</em></span> can dispatch
 225           to. This is why in that case, the comparison mimics the <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span></code>
 226           behavior.
 227         </p>
 228 <h6>
 229 <a name="boost_test.testing_tools.extended_comparison.collections.h4"></a>
 230           <span class="phrase"><a name="boost_test.testing_tools.extended_comparison.collections.example_descr0"></a></span><a class="link" href="collections.html#boost_test.testing_tools.extended_comparison.collections.example_descr0">Example:
 231           BOOST_TEST C-arrays</a>
 232         </h6>
 233 <div class="informaltable"><table class="table">
 234 <colgroup><col></colgroup>
 235 <thead><tr><th>
 236                   <p>
 237                     Code
 238                   </p>
 239                 </th></tr></thead>
 240 <tbody><tr><td>
 241 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="preprocessor">#define</span> <span class="identifier">BOOST_TEST_MODULE</span> <span class="identifier">boost_test_containers_c_arrays</span>
 242 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">test</span><span class="special">/</span><span class="identifier">included</span><span class="special">/</span><span class="identifier">unit_test</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 243 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">vector</span><span class="special">&gt;</span>
 244
 245 <span class="keyword">namespace</span> <span class="identifier">tt</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">test_tools</span><span class="special">;</span>
 246
 247 <span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span> <span class="identifier">test_collections_on_c_arrays</span> <span class="special">)</span>
 248 <span class="special">{</span>
 249   <span class="keyword">int</span> <span class="identifier">a</span><span class="special">[]</span> <span class="special">=</span> <span class="special">{</span><span class="number">1</span><span class="special">,</span> <span class="number">2</span><span class="special">,</span> <span class="number">3</span><span class="special">};</span>
 250   <span class="keyword">int</span> <span class="identifier">b</span><span class="special">[]</span> <span class="special">=</span> <span class="special">{</span><span class="number">1</span><span class="special">,</span> <span class="number">5</span><span class="special">,</span> <span class="number">3</span><span class="special">,</span> <span class="number">4</span><span class="special">};</span>
 251   <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">long</span><span class="special">&gt;</span> <span class="identifier">c</span><span class="special">{</span><span class="number">1</span><span class="special">,</span> <span class="number">5</span><span class="special">,</span> <span class="number">3</span><span class="special">,</span> <span class="number">4</span><span class="special">};</span>
 252   <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">a</span> <span class="special">==</span> <span class="identifier">a</span><span class="special">);</span> <span class="comment">// element-wise compare</span>
 253   <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">a</span> <span class="special">==</span> <span class="identifier">b</span><span class="special">);</span> <span class="comment">// element-wise compare</span>
 254   <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">a</span> <span class="special">!=</span> <span class="identifier">b</span><span class="special">);</span>
 255   <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">a</span> <span class="special">&lt;</span> <span class="identifier">b</span><span class="special">);</span> <span class="comment">// lexicographical compare</span>
 256   <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">b</span> <span class="special">&lt;</span> <span class="identifier">c</span><span class="special">);</span> <span class="comment">// lexicographical compare</span>
 257   <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">c</span> <span class="special">&lt;</span> <span class="identifier">a</span><span class="special">);</span> <span class="comment">// lexicographical compare</span>
 258 <span class="special">}</span>
 259 </pre>
 260                 </td></tr></tbody>
 261 </table></div>
 262 <div class="informaltable"><table class="table">
 263 <colgroup><col></colgroup>
 264 <thead><tr><th>
 265                   <p>
 266                     Output
 267                   </p>
 268                 </th></tr></thead>
 269 <tbody><tr><td>
 270 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="special">&gt;</span> <span class="special">./</span><span class="identifier">boost_test_containers_c_arrays</span> <span class="special">--</span><span class="identifier">log_level</span><span class="special">=</span><span class="identifier">all</span>
 271 <span class="identifier">Running</span> <span class="number">1</span> <span class="identifier">test</span> <span class="keyword">case</span><span class="special">...</span>
 272 <span class="identifier">Entering</span> <span class="identifier">test</span> <span class="identifier">module</span> <span class="string">"boost_test_containers_c_arrays"</span>
 273 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">15</span><span class="special">:</span> <span class="identifier">Entering</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"test_collections_on_c_arrays"</span>
 274 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">20</span><span class="special">:</span> <span class="identifier">info</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">a</span> <span class="special">==</span> <span class="identifier">a</span> <span class="identifier">has</span> <span class="identifier">passed</span>
 275 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">21</span><span class="special">:</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test_collections_on_c_arrays"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">a</span> <span class="special">==</span> <span class="identifier">b</span> <span class="identifier">has</span> <span class="identifier">failed</span><span class="special">.</span>
 276 <span class="identifier">Collections</span> <span class="identifier">size</span> <span class="identifier">mismatch</span><span class="special">:</span> <span class="number">3</span> <span class="special">!=</span> <span class="number">4</span>
 277 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">22</span><span class="special">:</span> <span class="identifier">info</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">a</span> <span class="special">!=</span> <span class="identifier">b</span> <span class="identifier">has</span> <span class="identifier">passed</span>
 278 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">23</span><span class="special">:</span> <span class="identifier">info</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">a</span> <span class="special">&lt;</span> <span class="identifier">b</span> <span class="identifier">has</span> <span class="identifier">passed</span>
 279 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">24</span><span class="special">:</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test_collections_on_c_arrays"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">b</span> <span class="special">&lt;</span> <span class="identifier">c</span> <span class="identifier">has</span> <span class="identifier">failed</span><span class="special">.</span>
 280 <span class="identifier">Collections</span> <span class="identifier">appear</span> <span class="identifier">to</span> <span class="identifier">be</span> <span class="identifier">equal</span><span class="special">.</span>
 281 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">25</span><span class="special">:</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test_collections_on_c_arrays"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">c</span> <span class="special">&lt;</span> <span class="identifier">a</span> <span class="identifier">has</span> <span class="identifier">failed</span><span class="special">.</span>
 282 <span class="identifier">Failure</span> <span class="identifier">at</span> <span class="identifier">position</span> <span class="number">1</span><span class="special">:</span> <span class="number">5</span> <span class="special">&gt;=</span> <span class="number">2.</span>
 283 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">15</span><span class="special">:</span> <span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"test_collections_on_c_arrays"</span><span class="special">;</span> <span class="identifier">testing</span> <span class="identifier">time</span><span class="special">:</span> <span class="number">204u</span><span class="identifier">s</span>
 284 <span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="identifier">module</span> <span class="string">"boost_test_containers_c_arrays"</span><span class="special">;</span> <span class="identifier">testing</span> <span class="identifier">time</span><span class="special">:</span> <span class="number">240u</span><span class="identifier">s</span>
 285
 286 <span class="special">***</span> <span class="number">3</span> <span class="identifier">failures</span> <span class="identifier">are</span> <span class="identifier">detected</span> <span class="identifier">in</span> <span class="identifier">the</span> <span class="identifier">test</span> <span class="identifier">module</span> <span class="string">"boost_test_containers_c_arrays"</span>
 287 </pre>
 288                 </td></tr></tbody>
 289 </table></div>
 290 <a name="boost_test_coll_perelement"></a><h4>
 291 <a name="boost_test.testing_tools.extended_comparison.collections.h5"></a>
 292           <span class="phrase"><a name="boost_test.testing_tools.extended_comparison.collections.element_wise_comparison"></a></span><a class="link" href="collections.html#boost_test.testing_tools.extended_comparison.collections.element_wise_comparison">Element-wise
 293           comparison</a>
 294         </h4>
 295 <p>
 296           By specifying the manipulator <code class="computeroutput"><a class="link" href="../../../boost/test_tools/per_element.html" title="Struct per_element">boost::test_tools::per_element</a></code>,
 297           the comparison of the elements of the containers are performed <span class="emphasis"><em>element-wise</em></span>,
 298           in the order given by the forward iterators of the containers. This is
 299           a comparison on the <span class="emphasis"><em>sequences</em></span> of elements generated
 300           by the containers, for which the <span class="emphasis"><em>Unit Test Framework</em></span>
 301           provides advanced diagnostic.
 302         </p>
 303 <p>
 304           In more details, let <code class="computeroutput"><span class="identifier">c_a</span> <span class="special">=</span> <span class="special">(</span><span class="identifier">a_1</span><span class="special">,...</span> <span class="identifier">a_n</span><span class="special">)</span></code> and <code class="computeroutput"><span class="identifier">c_b</span>
 305           <span class="special">=</span> <span class="special">(</span><span class="identifier">b_1</span><span class="special">,...</span> <span class="identifier">b_n</span><span class="special">)</span></code>
 306           be two sequences of same length, but not necessarily of same type. Those
 307           sequences correspond to the content of the respective containers, in the
 308           order given by their iterator. Let <code class="computeroutput"><span class="identifier">op</span></code>
 309           be one of the <a class="link" href="../boost_test_universal_macro.html#boost_test_statement_overloads">binary comparison
 310           operators</a>.
 311         </p>
 312 <pre class="programlisting"><span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">c_a</span> <span class="identifier">op</span> <span class="identifier">c_b</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">test_tools</span><span class="special">::</span><span class="identifier">per_element</span><span class="special">()</span> <span class="special">);</span>
 313 </pre>
 314 <p>
 315           is equivalent to
 316         </p>
 317 <pre class="programlisting"><span class="keyword">if</span><span class="special">(</span><span class="identifier">c_a</span><span class="special">.</span><span class="identifier">size</span><span class="special">()</span> <span class="special">==</span> <span class="identifier">c_b</span><span class="special">.</span><span class="identifier">size</span><span class="special">())</span>
 318 <span class="special">{</span>
 319   <span class="keyword">for</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">i</span><span class="special">=</span><span class="number">0</span><span class="special">;</span> <span class="identifier">i</span> <span class="special">&lt;</span> <span class="identifier">c_a</span><span class="special">.</span><span class="identifier">size</span><span class="special">();</span> <span class="identifier">i</span><span class="special">++)</span>
 320   <span class="special">{</span>
 321     <a class="link" href="../../utf_reference/testout_reference/test_output_macro_context.html" title="BOOST_TEST_CONTEXT"><code class="computeroutput"><span class="identifier">BOOST_TEST_CONTEXT</span></code></a><span class="special">(</span><span class="string">"index "</span> <span class="special">&lt;&lt;</span> <span class="identifier">i</span><span class="special">)</span>
 322     <span class="special">{</span>
 323       <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">a_i</span> <span class="identifier">op</span> <span class="identifier">b_i</span><span class="special">);</span>
 324     <span class="special">}</span>
 325   <span class="special">}</span>
 326 <span class="special">}</span>
 327 <span class="keyword">else</span>
 328 <span class="special">{</span>
 329   <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">c_a</span><span class="special">.</span><span class="identifier">size</span><span class="special">()</span> <span class="special">==</span> <span class="identifier">c_b</span><span class="special">.</span><span class="identifier">size</span><span class="special">());</span>
 330 <span class="special">}</span>
 331 </pre>
 332 <div class="warning"><table border="0" summary="Warning">
 333 <tr>
 334 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../../../../../doc/src/images/warning.png"></td>
 335 <th align="left">Warning</th>
 336 </tr>
 337 <tr><td align="left" valign="top"><p>
 338             this is fundamentally different from using the containers' default comparison
 339             operators (default behavior).
 340           </p></td></tr>
 341 </table></div>
 342 <div class="warning"><table border="0" summary="Warning">
 343 <tr>
 344 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../../../../../doc/src/images/warning.png"></td>
 345 <th align="left">Warning</th>
 346 </tr>
 347 <tr><td align="left" valign="top">
 348 <p>
 349             this is not an order relationship on containers. As a side effect, it
 350             is possible to have
 351           </p>
 352 <pre class="programlisting"><span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">c_a</span> <span class="special">==</span> <span class="identifier">c_b</span><span class="special">)</span></pre>
 353 <p>
 354             and
 355           </p>
 356 <pre class="programlisting"><span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">c_a</span> <span class="special">!=</span> <span class="identifier">c_b</span><span class="special">)</span></pre>
 357 <p>
 358             failing at the same time
 359           </p>
 360 </td></tr>
 361 </table></div>
 362 <p>
 363           Sequences are compared using the specified operator <code class="computeroutput"><span class="identifier">op</span></code>,
 364           evaluated on the left and right elements of the respective sequences. The
 365           order of the compared elements is given by the iterators of the respective
 366           containers <a href="#ftn.boost_test.testing_tools.extended_comparison.collections.f3" class="footnote" name="boost_test.testing_tools.extended_comparison.collections.f3"><sup class="footnote">[13]</sup></a>. In case of failure, the indices of the elements failing <code class="computeroutput"><span class="identifier">op</span></code> are returned.
 367         </p>
 368 <h6>
 369 <a name="boost_test.testing_tools.extended_comparison.collections.h6"></a>
 370           <span class="phrase"><a name="boost_test.testing_tools.extended_comparison.collections.example_descr1"></a></span><a class="link" href="collections.html#boost_test.testing_tools.extended_comparison.collections.example_descr1">Example:
 371           BOOST_TEST sequence comparison</a>
 372         </h6>
 373 <div class="informaltable"><table class="table">
 374 <colgroup><col></colgroup>
 375 <thead><tr><th>
 376                   <p>
 377                     Code
 378                   </p>
 379                 </th></tr></thead>
 380 <tbody><tr><td>
 381 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="preprocessor">#define</span> <span class="identifier">BOOST_TEST_MODULE</span> <span class="identifier">boost_test_sequence_per_element</span>
 382 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">test</span><span class="special">/</span><span class="identifier">included</span><span class="special">/</span><span class="identifier">unit_test</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 383 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">vector</span><span class="special">&gt;</span>
 384 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">list</span><span class="special">&gt;</span>
 385 <span class="keyword">namespace</span> <span class="identifier">tt</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">test_tools</span><span class="special">;</span>
 386
 387 <span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span> <span class="identifier">test_sequence_per_element</span> <span class="special">)</span>
 388 <span class="special">{</span>
 389   <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="identifier">a</span><span class="special">{</span><span class="number">1</span><span class="special">,</span><span class="number">2</span><span class="special">,</span><span class="number">3</span><span class="special">};</span>
 390   <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">long</span><span class="special">&gt;</span> <span class="identifier">b</span><span class="special">{</span><span class="number">1</span><span class="special">,</span><span class="number">5</span><span class="special">,</span><span class="number">3</span><span class="special">};</span>
 391   <span class="identifier">std</span><span class="special">::</span><span class="identifier">list</span><span class="special">&lt;</span><span class="keyword">short</span><span class="special">&gt;</span> <span class="identifier">c</span><span class="special">{</span><span class="number">1</span><span class="special">,</span><span class="number">5</span><span class="special">,</span><span class="number">3</span><span class="special">,</span><span class="number">4</span><span class="special">};</span>
 392
 393   <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">a</span> <span class="special">==</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">tt</span><span class="special">::</span><span class="identifier">per_element</span><span class="special">());</span> <span class="comment">// nok: a[1] != b[1]</span>
 394
 395   <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">a</span> <span class="special">!=</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">tt</span><span class="special">::</span><span class="identifier">per_element</span><span class="special">());</span> <span class="comment">// nok: a[0] == b[0] ...</span>
 396   <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">a</span> <span class="special">&lt;=</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">tt</span><span class="special">::</span><span class="identifier">per_element</span><span class="special">());</span> <span class="comment">// ok</span>
 397   <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">b</span>  <span class="special">&lt;</span> <span class="identifier">c</span><span class="special">,</span> <span class="identifier">tt</span><span class="special">::</span><span class="identifier">per_element</span><span class="special">());</span> <span class="comment">// nok: size mismatch</span>
 398   <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">b</span> <span class="special">&gt;=</span> <span class="identifier">c</span><span class="special">,</span> <span class="identifier">tt</span><span class="special">::</span><span class="identifier">per_element</span><span class="special">());</span> <span class="comment">// nok: size mismatch</span>
 399   <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">b</span> <span class="special">!=</span> <span class="identifier">c</span><span class="special">,</span> <span class="identifier">tt</span><span class="special">::</span><span class="identifier">per_element</span><span class="special">());</span> <span class="comment">// nok: size mismatch</span>
 400 <span class="special">}</span>
 401
 402 <span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span> <span class="identifier">test_compare_c_arrays_element_wise</span> <span class="special">)</span>
 403 <span class="special">{</span>
 404   <span class="keyword">int</span> <span class="identifier">a</span><span class="special">[]</span> <span class="special">=</span> <span class="special">{</span><span class="number">1</span><span class="special">,</span> <span class="number">2</span><span class="special">,</span> <span class="number">3</span><span class="special">};</span>
 405   <span class="keyword">int</span> <span class="identifier">b</span><span class="special">[]</span> <span class="special">=</span> <span class="special">{</span><span class="number">1</span><span class="special">,</span> <span class="number">5</span><span class="special">,</span> <span class="number">3</span><span class="special">};</span>
 406   <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">long</span><span class="special">&gt;</span> <span class="identifier">c</span><span class="special">{</span><span class="number">1</span><span class="special">,</span> <span class="number">5</span><span class="special">,</span> <span class="number">3</span><span class="special">};</span>
 407   <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">a</span> <span class="special">==</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">test_tools</span><span class="special">::</span><span class="identifier">per_element</span><span class="special">());</span>
 408   <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">a</span> <span class="special">!=</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">test_tools</span><span class="special">::</span><span class="identifier">per_element</span><span class="special">());</span>
 409   <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">a</span> <span class="special">&lt;</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">test_tools</span><span class="special">::</span><span class="identifier">per_element</span><span class="special">());</span>
 410   <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">b</span> <span class="special">&lt;</span> <span class="identifier">c</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">test_tools</span><span class="special">::</span><span class="identifier">per_element</span><span class="special">());</span>
 411   <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">c</span> <span class="special">&lt;</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">test_tools</span><span class="special">::</span><span class="identifier">per_element</span><span class="special">());</span>
 412 <span class="special">}</span>
 413 </pre>
 414                 </td></tr></tbody>
 415 </table></div>
 416 <div class="informaltable"><table class="table">
 417 <colgroup><col></colgroup>
 418 <thead><tr><th>
 419                   <p>
 420                     Output
 421                   </p>
 422                 </th></tr></thead>
 423 <tbody><tr><td>
 424 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="special">&gt;</span> <span class="special">./</span><span class="identifier">boost_test_sequence_per_element</span>
 425 <span class="identifier">Running</span> <span class="number">2</span> <span class="identifier">test</span> <span class="identifier">cases</span><span class="special">...</span>
 426 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">21</span><span class="special">:</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test_sequence_per_element"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">a</span> <span class="special">==</span> <span class="identifier">b</span> <span class="identifier">has</span> <span class="identifier">failed</span>
 427 <span class="identifier">Mismatch</span> <span class="identifier">at</span> <span class="identifier">position</span> <span class="number">1</span><span class="special">:</span> <span class="number">2</span> <span class="special">!=</span> <span class="number">5.</span>
 428 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">23</span><span class="special">:</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test_sequence_per_element"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">a</span> <span class="special">!=</span> <span class="identifier">b</span> <span class="identifier">has</span> <span class="identifier">failed</span>
 429 <span class="identifier">Mismatch</span> <span class="identifier">at</span> <span class="identifier">position</span> <span class="number">0</span><span class="special">:</span> <span class="number">1</span> <span class="special">==</span> <span class="number">1.</span>
 430 <span class="identifier">Mismatch</span> <span class="identifier">at</span> <span class="identifier">position</span> <span class="number">2</span><span class="special">:</span> <span class="number">3</span> <span class="special">==</span> <span class="number">3.</span>
 431 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">25</span><span class="special">:</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test_sequence_per_element"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">b</span> <span class="special">&lt;</span> <span class="identifier">c</span> <span class="identifier">has</span> <span class="identifier">failed</span>
 432 <span class="identifier">Collections</span> <span class="identifier">size</span> <span class="identifier">mismatch</span><span class="special">:</span> <span class="number">3</span> <span class="special">!=</span> <span class="number">4</span>
 433 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">26</span><span class="special">:</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test_sequence_per_element"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">b</span> <span class="special">&gt;=</span> <span class="identifier">c</span> <span class="identifier">has</span> <span class="identifier">failed</span>
 434 <span class="identifier">Collections</span> <span class="identifier">size</span> <span class="identifier">mismatch</span><span class="special">:</span> <span class="number">3</span> <span class="special">!=</span> <span class="number">4</span>
 435 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">27</span><span class="special">:</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test_sequence_per_element"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">b</span> <span class="special">!=</span> <span class="identifier">c</span> <span class="identifier">has</span> <span class="identifier">failed</span>
 436 <span class="identifier">Collections</span> <span class="identifier">size</span> <span class="identifier">mismatch</span><span class="special">:</span> <span class="number">3</span> <span class="special">!=</span> <span class="number">4</span>
 437 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">35</span><span class="special">:</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test_compare_c_arrays_element_wise"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">a</span> <span class="special">==</span> <span class="identifier">b</span> <span class="identifier">has</span> <span class="identifier">failed</span>
 438 <span class="identifier">Mismatch</span> <span class="identifier">at</span> <span class="identifier">position</span> <span class="number">1</span><span class="special">:</span> <span class="number">2</span> <span class="special">!=</span> <span class="number">5.</span>
 439 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">36</span><span class="special">:</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test_compare_c_arrays_element_wise"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">a</span> <span class="special">!=</span> <span class="identifier">b</span> <span class="identifier">has</span> <span class="identifier">failed</span>
 440 <span class="identifier">Mismatch</span> <span class="identifier">at</span> <span class="identifier">position</span> <span class="number">0</span><span class="special">:</span> <span class="number">1</span> <span class="special">==</span> <span class="number">1.</span>
 441 <span class="identifier">Mismatch</span> <span class="identifier">at</span> <span class="identifier">position</span> <span class="number">2</span><span class="special">:</span> <span class="number">3</span> <span class="special">==</span> <span class="number">3.</span>
 442 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">37</span><span class="special">:</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test_compare_c_arrays_element_wise"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">a</span> <span class="special">&lt;</span> <span class="identifier">b</span> <span class="identifier">has</span> <span class="identifier">failed</span>
 443 <span class="identifier">Mismatch</span> <span class="identifier">at</span> <span class="identifier">position</span> <span class="number">0</span><span class="special">:</span> <span class="number">1</span> <span class="special">&gt;=</span> <span class="number">1.</span>
 444 <span class="identifier">Mismatch</span> <span class="identifier">at</span> <span class="identifier">position</span> <span class="number">2</span><span class="special">:</span> <span class="number">3</span> <span class="special">&gt;=</span> <span class="number">3.</span>
 445 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">38</span><span class="special">:</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test_compare_c_arrays_element_wise"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">b</span> <span class="special">&lt;</span> <span class="identifier">c</span> <span class="identifier">has</span> <span class="identifier">failed</span>
 446 <span class="identifier">Mismatch</span> <span class="identifier">at</span> <span class="identifier">position</span> <span class="number">0</span><span class="special">:</span> <span class="number">1</span> <span class="special">&gt;=</span> <span class="number">1.</span>
 447 <span class="identifier">Mismatch</span> <span class="identifier">at</span> <span class="identifier">position</span> <span class="number">1</span><span class="special">:</span> <span class="number">5</span> <span class="special">&gt;=</span> <span class="number">5.</span>
 448 <span class="identifier">Mismatch</span> <span class="identifier">at</span> <span class="identifier">position</span> <span class="number">2</span><span class="special">:</span> <span class="number">3</span> <span class="special">&gt;=</span> <span class="number">3.</span>
 449 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">39</span><span class="special">:</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test_compare_c_arrays_element_wise"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">c</span> <span class="special">&lt;</span> <span class="identifier">a</span> <span class="identifier">has</span> <span class="identifier">failed</span>
 450 <span class="identifier">Mismatch</span> <span class="identifier">at</span> <span class="identifier">position</span> <span class="number">0</span><span class="special">:</span> <span class="number">1</span> <span class="special">&gt;=</span> <span class="number">1.</span>
 451 <span class="identifier">Mismatch</span> <span class="identifier">at</span> <span class="identifier">position</span> <span class="number">1</span><span class="special">:</span> <span class="number">5</span> <span class="special">&gt;=</span> <span class="number">2.</span>
 452 <span class="identifier">Mismatch</span> <span class="identifier">at</span> <span class="identifier">position</span> <span class="number">2</span><span class="special">:</span> <span class="number">3</span> <span class="special">&gt;=</span> <span class="number">3.</span>
 453
 454 <span class="special">***</span> <span class="number">10</span> <span class="identifier">failures</span> <span class="identifier">are</span> <span class="identifier">detected</span> <span class="identifier">in</span> <span class="identifier">the</span> <span class="identifier">test</span> <span class="identifier">module</span> <span class="string">"boost_test_sequence_per_element"</span>
 455 </pre>
 456                 </td></tr></tbody>
 457 </table></div>
 458 <h5>
 459 <a name="boost_test.testing_tools.extended_comparison.collections.h7"></a>
 460           <span class="phrase"><a name="boost_test.testing_tools.extended_comparison.collections.requirements"></a></span><a class="link" href="collections.html#boost_test.testing_tools.extended_comparison.collections.requirements">Requirements</a>
 461         </h5>
 462 <p>
 463           For the sequences to be comparable element-wise, the following conditions
 464           should be met:
 465         </p>
 466 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 467 <li class="listitem">
 468               the containers should meet the <a class="link" href="collections.html#what_is_a_collection">sequence</a>
 469               definition,
 470             </li>
 471 <li class="listitem">
 472               the containers should yield the same number of elements,
 473             </li>
 474 <li class="listitem">
 475               <code class="computeroutput"><span class="identifier">op</span></code> should be one of
 476               the comparison operator <code class="computeroutput"><span class="special">==</span></code>,
 477               <code class="computeroutput"><span class="special">!=</span></code>, <code class="computeroutput"><span class="special">&lt;</span></code>,
 478               <code class="computeroutput"><span class="special">&lt;=</span></code>, <code class="computeroutput"><span class="special">&gt;</span></code>,
 479               <code class="computeroutput"><span class="special">&gt;=</span></code>
 480             </li>
 481 <li class="listitem">
 482               the <code class="computeroutput"><span class="identifier">a_i</span> <span class="identifier">op</span>
 483               <span class="identifier">b_i</span></code> should be defined, where
 484               the type of <code class="computeroutput"><span class="identifier">a_i</span></code> and
 485               <code class="computeroutput"><span class="identifier">b_i</span></code> are the type returned
 486               by the dereference operator of the respective collections.
 487             </li>
 488 </ul></div>
 489 <div class="caution"><table border="0" summary="Caution">
 490 <tr>
 491 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../../../../doc/src/images/caution.png"></td>
 492 <th align="left">Caution</th>
 493 </tr>
 494 <tr><td align="left" valign="top">
 495 <p>
 496             the resulting type of "<code class="computeroutput"><span class="identifier">c_a</span>
 497             <span class="special">==</span> <span class="identifier">c_b</span></code>"
 498             is an <code class="computeroutput"><a class="link" href="../../../boost/test_tools/assertion_result.html" title="Class assertion_result">assertion_result</a></code>:
 499             it is not possible to compose more that one comparison on the <code class="computeroutput"><span class="identifier">BOOST_TEST</span></code> statement:
 500           </p>
 501 <pre class="programlisting"><span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">c_a</span> <span class="special">==</span> <span class="identifier">c_b</span> <span class="special">==</span> <span class="number">42</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">test_tools</span><span class="special">::</span><span class="identifier">per_element</span><span class="special">()</span> <span class="special">);</span> <span class="comment">// does not compile</span>
 502 </pre>
 503 </td></tr>
 504 </table></div>
 505 <a name="boost_test_coll_default_lex"></a><h4>
 506 <a name="boost_test.testing_tools.extended_comparison.collections.h8"></a>
 507           <span class="phrase"><a name="boost_test.testing_tools.extended_comparison.collections.lexicographic_comparison"></a></span><a class="link" href="collections.html#boost_test.testing_tools.extended_comparison.collections.lexicographic_comparison">Lexicographic
 508           comparison</a>
 509         </h4>
 510 <p>
 511           By specifying the manipulator <code class="computeroutput"><a class="link" href="../../../boost/test_tools/lexicographic.html" title="Struct lexicographic">boost::test_tools::lexicographic</a></code>,
 512           the containers are compared using the <span class="emphasis"><em>lexicographical</em></span>
 513           order and for which the <span class="emphasis"><em>Unit Test Framework</em></span> provides
 514           additional diagnostic in case of failure.
 515         </p>
 516 <pre class="programlisting"><span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">c_a</span> <span class="identifier">op</span> <span class="identifier">c_b</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">test_tools</span><span class="special">::</span><span class="identifier">lexicographic</span><span class="special">()</span> <span class="special">);</span>
 517 </pre>
 518 <p>
 519           The comparison is performed in the order given by forward iterators of
 520           the containers.
 521         </p>
 522 <div class="tip"><table border="0" summary="Tip">
 523 <tr>
 524 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../../../../doc/src/images/tip.png"></td>
 525 <th align="left">Tip</th>
 526 </tr>
 527 <tr><td align="left" valign="top"><p>
 528             lexicographic comparison yields a total order on the containers: the
 529             statements <code class="computeroutput"><span class="identifier">c_a</span> <span class="special">&lt;</span>
 530             <span class="identifier">c_b</span></code> and <code class="computeroutput"><span class="identifier">c_b</span>
 531             <span class="special">&lt;=</span> <span class="identifier">c_a</span></code>
 532             are mutually exclusive.
 533           </p></td></tr>
 534 </table></div>
 535 <div class="note"><table border="0" summary="Note">
 536 <tr>
 537 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../doc/src/images/note.png"></td>
 538 <th align="left">Note</th>
 539 </tr>
 540 <tr><td align="left" valign="top"><p>
 541             The equality <code class="computeroutput"><span class="special">==</span></code> and inequality
 542             <code class="computeroutput"><span class="special">!=</span></code> are not available for
 543             this type of comparison.
 544           </p></td></tr>
 545 </table></div>
 546 <h6>
 547 <a name="boost_test.testing_tools.extended_comparison.collections.h9"></a>
 548           <span class="phrase"><a name="boost_test.testing_tools.extended_comparison.collections.example_descr2"></a></span><a class="link" href="collections.html#boost_test.testing_tools.extended_comparison.collections.example_descr2">Example:
 549           BOOST_TEST container comparison using lexicographical order</a>
 550         </h6>
 551 <div class="informaltable"><table class="table">
 552 <colgroup><col></colgroup>
 553 <thead><tr><th>
 554                   <p>
 555                     Code
 556                   </p>
 557                 </th></tr></thead>
 558 <tbody><tr><td>
 559 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="preprocessor">#define</span> <span class="identifier">BOOST_TEST_MODULE</span> <span class="identifier">boost_test_container_lex</span>
 560 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">test</span><span class="special">/</span><span class="identifier">included</span><span class="special">/</span><span class="identifier">unit_test</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 561 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">vector</span><span class="special">&gt;</span>
 562
 563 <span class="keyword">namespace</span> <span class="identifier">tt</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">test_tools</span><span class="special">;</span>
 564
 565 <span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span> <span class="identifier">test_collections_vectors_lex</span> <span class="special">)</span>
 566 <span class="special">{</span>
 567   <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="identifier">a</span><span class="special">{</span><span class="number">1</span><span class="special">,</span><span class="number">2</span><span class="special">,</span><span class="number">3</span><span class="special">},</span> <span class="identifier">b</span><span class="special">{</span><span class="number">1</span><span class="special">,</span><span class="number">2</span><span class="special">,</span><span class="number">2</span><span class="special">},</span> <span class="identifier">c</span><span class="special">{</span><span class="number">1</span><span class="special">,</span><span class="number">2</span><span class="special">,</span><span class="number">3</span><span class="special">,</span><span class="number">4</span><span class="special">};</span>
 568
 569   <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">a</span> <span class="special">&lt;</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">tt</span><span class="special">::</span><span class="identifier">lexicographic</span><span class="special">());</span>
 570   <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">a</span> <span class="special">&lt;</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">tt</span><span class="special">::</span><span class="identifier">lexicographic</span><span class="special">());</span>
 571   <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">a</span> <span class="special">&lt;</span> <span class="identifier">c</span><span class="special">,</span> <span class="identifier">tt</span><span class="special">::</span><span class="identifier">lexicographic</span><span class="special">());</span>
 572   <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">a</span> <span class="special">&gt;=</span> <span class="identifier">c</span><span class="special">,</span> <span class="identifier">tt</span><span class="special">::</span><span class="identifier">lexicographic</span><span class="special">());</span>
 573
 574   <span class="comment">//BOOST_TEST(a == c, tt::lexicographic()); // does not compile</span>
 575   <span class="comment">//BOOST_TEST(a != c, tt::lexicographic()); // does not compile</span>
 576 <span class="special">}</span>
 577
 578 <span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span> <span class="identifier">test_compare_c_arrays_lexicographic</span> <span class="special">)</span>
 579 <span class="special">{</span>
 580   <span class="keyword">int</span> <span class="identifier">a</span><span class="special">[]</span> <span class="special">=</span> <span class="special">{</span><span class="number">1</span><span class="special">,</span> <span class="number">2</span><span class="special">,</span> <span class="number">3</span><span class="special">};</span>
 581   <span class="keyword">int</span> <span class="identifier">b</span><span class="special">[]</span> <span class="special">=</span> <span class="special">{</span><span class="number">1</span><span class="special">,</span> <span class="number">5</span><span class="special">,</span> <span class="number">3</span><span class="special">};</span>
 582   <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">long</span><span class="special">&gt;</span> <span class="identifier">c</span><span class="special">{</span><span class="number">1</span><span class="special">,</span> <span class="number">5</span><span class="special">,</span> <span class="number">3</span><span class="special">};</span>
 583   <span class="comment">// BOOST_TEST(a == b, boost::test_tools::lexicographic()); // does not compile</span>
 584   <span class="comment">// BOOST_TEST(a != b, boost::test_tools::lexicographic()); // does not compile</span>
 585   <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">a</span> <span class="special">&lt;</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">test_tools</span><span class="special">::</span><span class="identifier">lexicographic</span><span class="special">());</span>
 586   <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">b</span> <span class="special">&lt;</span> <span class="identifier">c</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">test_tools</span><span class="special">::</span><span class="identifier">lexicographic</span><span class="special">());</span>
 587   <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">c</span> <span class="special">&lt;</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">test_tools</span><span class="special">::</span><span class="identifier">lexicographic</span><span class="special">());</span>
 588 <span class="special">}</span>
 589 </pre>
 590                 </td></tr></tbody>
 591 </table></div>
 592 <div class="informaltable"><table class="table">
 593 <colgroup><col></colgroup>
 594 <thead><tr><th>
 595                   <p>
 596                     Output
 597                   </p>
 598                 </th></tr></thead>
 599 <tbody><tr><td>
 600 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="special">&gt;</span> <span class="special">./</span><span class="identifier">boost_test_container_lex</span> <span class="special">--</span><span class="identifier">log_level</span><span class="special">=</span><span class="identifier">all</span>
 601 <span class="identifier">Running</span> <span class="number">2</span> <span class="identifier">test</span> <span class="identifier">cases</span><span class="special">...</span>
 602 <span class="identifier">Entering</span> <span class="identifier">test</span> <span class="identifier">module</span> <span class="string">"boost_test_container_lex"</span>
 603 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">15</span><span class="special">:</span> <span class="identifier">Entering</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"test_collections_vectors_lex"</span>
 604 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">19</span><span class="special">:</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test_collections_vectors_lex"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">a</span> <span class="special">&lt;</span> <span class="identifier">a</span> <span class="identifier">has</span> <span class="identifier">failed</span>
 605 <span class="identifier">Collections</span> <span class="identifier">appear</span> <span class="identifier">to</span> <span class="identifier">be</span> <span class="identifier">equal</span><span class="special">.</span>
 606 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">20</span><span class="special">:</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test_collections_vectors_lex"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">a</span> <span class="special">&lt;</span> <span class="identifier">b</span> <span class="identifier">has</span> <span class="identifier">failed</span>
 607 <span class="identifier">Failure</span> <span class="identifier">at</span> <span class="identifier">position</span> <span class="number">2</span><span class="special">:</span> <span class="number">3</span> <span class="special">&gt;=</span> <span class="number">2.</span>
 608 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">21</span><span class="special">:</span> <span class="identifier">info</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">a</span> <span class="special">&lt;</span> <span class="identifier">c</span> <span class="identifier">has</span> <span class="identifier">passed</span>
 609 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">22</span><span class="special">:</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test_collections_vectors_lex"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">a</span> <span class="special">&gt;=</span> <span class="identifier">c</span> <span class="identifier">has</span> <span class="identifier">failed</span>
 610 <span class="identifier">Second</span> <span class="identifier">collection</span> <span class="identifier">has</span> <span class="identifier">extra</span> <span class="identifier">trailing</span> <span class="identifier">elements</span><span class="special">.</span>
 611 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">15</span><span class="special">:</span> <span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"test_collections_vectors_lex"</span><span class="special">;</span> <span class="identifier">testing</span> <span class="identifier">time</span><span class="special">:</span> <span class="number">178u</span><span class="identifier">s</span>
 612 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">28</span><span class="special">:</span> <span class="identifier">Entering</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"test_compare_c_arrays_lexicographic"</span>
 613 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">35</span><span class="special">:</span> <span class="identifier">info</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">a</span> <span class="special">&lt;</span> <span class="identifier">b</span> <span class="identifier">has</span> <span class="identifier">passed</span>
 614 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">36</span><span class="special">:</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test_compare_c_arrays_lexicographic"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">b</span> <span class="special">&lt;</span> <span class="identifier">c</span> <span class="identifier">has</span> <span class="identifier">failed</span>
 615 <span class="identifier">Collections</span> <span class="identifier">appear</span> <span class="identifier">to</span> <span class="identifier">be</span> <span class="identifier">equal</span><span class="special">.</span>
 616 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">37</span><span class="special">:</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test_compare_c_arrays_lexicographic"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">c</span> <span class="special">&lt;</span> <span class="identifier">a</span> <span class="identifier">has</span> <span class="identifier">failed</span>
 617 <span class="identifier">Failure</span> <span class="identifier">at</span> <span class="identifier">position</span> <span class="number">1</span><span class="special">:</span> <span class="number">5</span> <span class="special">&gt;=</span> <span class="number">2.</span>
 618 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">28</span><span class="special">:</span> <span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"test_compare_c_arrays_lexicographic"</span><span class="special">;</span> <span class="identifier">testing</span> <span class="identifier">time</span><span class="special">:</span> <span class="number">88u</span><span class="identifier">s</span>
 619 <span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="identifier">module</span> <span class="string">"boost_test_container_lex"</span><span class="special">;</span> <span class="identifier">testing</span> <span class="identifier">time</span><span class="special">:</span> <span class="number">323u</span><span class="identifier">s</span>
 620
 621 <span class="special">***</span> <span class="number">5</span> <span class="identifier">failures</span> <span class="identifier">are</span> <span class="identifier">detected</span> <span class="identifier">in</span> <span class="identifier">the</span> <span class="identifier">test</span> <span class="identifier">module</span> <span class="string">"boost_test_container_lex"</span>
 622 </pre>
 623                 </td></tr></tbody>
 624 </table></div>
 625 <a name="ref_boost_test_coll_special_macro"></a><h4>
 626 <a name="boost_test.testing_tools.extended_comparison.collections.h10"></a>
 627           <span class="phrase"><a name="boost_test.testing_tools.extended_comparison.collections.extended_diagnostic_by_default_f"></a></span><a class="link" href="collections.html#boost_test.testing_tools.extended_comparison.collections.extended_diagnostic_by_default_f">Extended
 628           diagnostic by default for specific containers</a>
 629         </h4>
 630 <p>
 631           As seen above,
 632         </p>
 633 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 634 <li class="listitem">
 635               for testing equality, the <code class="computeroutput"><span class="special">==</span></code>
 636               relation is either explicit (using <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">test_tools</span><span class="special">::</span><span class="identifier">per_element</span><span class="special">()</span></code>) or implicit when the container overloads/implements
 637               this type of comparison,
 638             </li>
 639 <li class="listitem">
 640               for testing inequality, lexicographical comparison for <code class="computeroutput"><span class="special">&lt;</span></code> (and derived operations) is either
 641               explicit (using <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">test_tools</span><span class="special">::</span><span class="identifier">lexicographic</span><span class="special">()</span></code>) or implicit when the container overloads/implements
 642               uses this type of comparison.
 643             </li>
 644 </ul></div>
 645 <p>
 646           When the default is to using the container implementation, it is not possible
 647           to benefit from an extended failure diagnostic. The <span class="emphasis"><em>Unit Test
 648           Framework</em></span> provides a mechanism for performing the same comparisons
 649           through the <span class="emphasis"><em>Unit Test Framework</em></span> instead of the container
 650           operator, through the macro <code class="computeroutput"><span class="identifier">BOOST_TEST_SPECIALIZED_COLLECTION_COMPARE</span></code>
 651           that might be used as follow:
 652         </p>
 653 <h6>
 654 <a name="boost_test.testing_tools.extended_comparison.collections.h11"></a>
 655           <span class="phrase"><a name="boost_test.testing_tools.extended_comparison.collections.example_descr3"></a></span><a class="link" href="collections.html#boost_test.testing_tools.extended_comparison.collections.example_descr3">Example:
 656           Default <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span></code>
 657           to lexicographic with extended diagnostic</a>
 658         </h6>
 659 <div class="informaltable"><table class="table">
 660 <colgroup><col></colgroup>
 661 <thead><tr><th>
 662                   <p>
 663                     Code
 664                   </p>
 665                 </th></tr></thead>
 666 <tbody><tr><td>
 667 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="preprocessor">#define</span> <span class="identifier">BOOST_TEST_MODULE</span> <span class="identifier">boost_test_container_lex_default</span>
 668 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">test</span><span class="special">/</span><span class="identifier">included</span><span class="special">/</span><span class="identifier">unit_test</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 669 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">vector</span><span class="special">&gt;</span>
 670
 671 <span class="keyword">namespace</span> <span class="identifier">tt</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">test_tools</span><span class="special">;</span>
 672
 673 <span class="identifier">BOOST_TEST_SPECIALIZED_COLLECTION_COMPARE</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;)</span>
 674
 675 <span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span> <span class="identifier">test_collections_vectors_lex</span> <span class="special">)</span>
 676 <span class="special">{</span>
 677   <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="identifier">a</span><span class="special">{</span><span class="number">1</span><span class="special">,</span><span class="number">2</span><span class="special">,</span><span class="number">3</span><span class="special">},</span> <span class="identifier">b</span><span class="special">{</span><span class="number">1</span><span class="special">,</span><span class="number">2</span><span class="special">,</span><span class="number">2</span><span class="special">};</span>
 678   <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">long</span> <span class="keyword">int</span><span class="special">&gt;</span> <span class="identifier">c</span><span class="special">{</span><span class="number">1</span><span class="special">,</span><span class="number">2</span><span class="special">,</span><span class="number">3</span><span class="special">,</span><span class="number">5</span><span class="special">},</span> <span class="identifier">d</span><span class="special">{</span><span class="number">1</span><span class="special">,</span><span class="number">2</span><span class="special">,</span><span class="number">3</span><span class="special">,</span><span class="number">4</span><span class="special">};</span>
 679
 680   <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">a</span> <span class="special">&lt;</span> <span class="identifier">a</span><span class="special">);</span> <span class="comment">// lexcographic</span>
 681   <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">a</span> <span class="special">&lt;</span> <span class="identifier">b</span><span class="special">);</span> <span class="comment">// lexcographic</span>
 682   <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">a</span> <span class="special">==</span> <span class="identifier">b</span><span class="special">);</span> <span class="comment">// element-wise</span>
 683   <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">a</span> <span class="special">!=</span> <span class="identifier">b</span><span class="special">);</span> <span class="comment">// extended diagnostic</span>
 684   <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">c</span> <span class="special">&lt;</span> <span class="identifier">d</span><span class="special">);</span> <span class="comment">// no extended diagnostic</span>
 685   <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">c</span> <span class="special">==</span> <span class="identifier">d</span><span class="special">);</span> <span class="comment">// no extended diagnostic</span>
 686 <span class="special">}</span>
 687 </pre>
 688                 </td></tr></tbody>
 689 </table></div>
 690 <div class="informaltable"><table class="table">
 691 <colgroup><col></colgroup>
 692 <thead><tr><th>
 693                   <p>
 694                     Output
 695                   </p>
 696                 </th></tr></thead>
 697 <tbody><tr><td>
 698 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="special">&gt;</span> <span class="special">./</span><span class="identifier">boost_test_container_lex_default</span> <span class="special">--</span><span class="identifier">log_level</span><span class="special">=</span><span class="identifier">all</span>
 699 <span class="identifier">Running</span> <span class="number">1</span> <span class="identifier">test</span> <span class="keyword">case</span><span class="special">...</span>
 700 <span class="identifier">Entering</span> <span class="identifier">test</span> <span class="identifier">module</span> <span class="string">"boost_test_container_lex_default"</span>
 701 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">17</span><span class="special">:</span> <span class="identifier">Entering</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"test_collections_vectors_lex"</span>
 702 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">22</span><span class="special">:</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test_collections_vectors_lex"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">a</span> <span class="special">&lt;</span> <span class="identifier">a</span> <span class="identifier">has</span> <span class="identifier">failed</span><span class="special">.</span>
 703 <span class="identifier">Collections</span> <span class="identifier">appear</span> <span class="identifier">to</span> <span class="identifier">be</span> <span class="identifier">equal</span><span class="special">.</span>
 704 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">23</span><span class="special">:</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test_collections_vectors_lex"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">a</span> <span class="special">&lt;</span> <span class="identifier">b</span> <span class="identifier">has</span> <span class="identifier">failed</span><span class="special">.</span>
 705 <span class="identifier">Failure</span> <span class="identifier">at</span> <span class="identifier">position</span> <span class="number">2</span><span class="special">:</span> <span class="number">3</span> <span class="special">&gt;=</span> <span class="number">2.</span>
 706 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">24</span><span class="special">:</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test_collections_vectors_lex"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">a</span> <span class="special">==</span> <span class="identifier">b</span> <span class="identifier">has</span> <span class="identifier">failed</span><span class="special">.</span>
 707 <span class="identifier">Mismatch</span> <span class="identifier">at</span> <span class="identifier">position</span> <span class="number">2</span><span class="special">:</span> <span class="number">3</span> <span class="special">!=</span> <span class="number">2.</span>
 708 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">25</span><span class="special">:</span> <span class="identifier">info</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">a</span> <span class="special">!=</span> <span class="identifier">b</span> <span class="identifier">has</span> <span class="identifier">passed</span>
 709 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">26</span><span class="special">:</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test_collections_vectors_lex"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">c</span> <span class="special">&lt;</span> <span class="identifier">d</span> <span class="identifier">has</span> <span class="identifier">failed</span>
 710 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">27</span><span class="special">:</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test_collections_vectors_lex"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">c</span> <span class="special">==</span> <span class="identifier">d</span> <span class="identifier">has</span> <span class="identifier">failed</span>
 711 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">17</span><span class="special">:</span> <span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"test_collections_vectors_lex"</span><span class="special">;</span> <span class="identifier">testing</span> <span class="identifier">time</span><span class="special">:</span> <span class="number">155u</span><span class="identifier">s</span>
 712 <span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="identifier">module</span> <span class="string">"boost_test_container_lex_default"</span><span class="special">;</span> <span class="identifier">testing</span> <span class="identifier">time</span><span class="special">:</span> <span class="number">177u</span><span class="identifier">s</span>
 713
 714 <span class="special">***</span> <span class="number">5</span> <span class="identifier">failures</span> <span class="identifier">are</span> <span class="identifier">detected</span> <span class="identifier">in</span> <span class="identifier">the</span> <span class="identifier">test</span> <span class="identifier">module</span> <span class="string">"boost_test_container_lex_default"</span>
 715 </pre>
 716                 </td></tr></tbody>
 717 </table></div>
 718 <h5>
 719 <a name="boost_test.testing_tools.extended_comparison.collections.h12"></a>
 720           <span class="phrase"><a name="boost_test.testing_tools.extended_comparison.collections.requirements0"></a></span><a class="link" href="collections.html#boost_test.testing_tools.extended_comparison.collections.requirements0">Requirements</a>
 721         </h5>
 722 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 723 <li class="listitem">
 724               the containers should meet the <a class="link" href="collections.html#what_is_a_collection">sequence</a>
 725               definition,
 726             </li>
 727 <li class="listitem">
 728               the containers should be of the exact same type
 729             </li>
 730 <li class="listitem">
 731               <code class="computeroutput"><span class="identifier">op</span></code> should be one of
 732               the comparison operator <code class="computeroutput"><span class="special">==</span></code>,
 733               <code class="computeroutput"><span class="special">!=</span></code>, <code class="computeroutput"><span class="special">&lt;</span></code>,
 734               <code class="computeroutput"><span class="special">&lt;=</span></code>, <code class="computeroutput"><span class="special">&gt;</span></code>,
 735               <code class="computeroutput"><span class="special">&gt;=</span></code>
 736             </li>
 737 </ul></div>
 738 <div class="note"><table border="0" summary="Note">
 739 <tr>
 740 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../doc/src/images/note.png"></td>
 741 <th align="left">Note</th>
 742 </tr>
 743 <tr><td align="left" valign="top"><p>
 744             Note that the operation <code class="computeroutput"><span class="special">!=</span></code>
 745             is in this case not an element-wise comparison,
 746           </p></td></tr>
 747 </table></div>
 748 <a name="what_is_a_collection"></a><h4>
 749 <a name="boost_test.testing_tools.extended_comparison.collections.h13"></a>
 750           <span class="phrase"><a name="boost_test.testing_tools.extended_comparison.collections.what_is_a_sequence"></a></span><a class="link" href="collections.html#boost_test.testing_tools.extended_comparison.collections.what_is_a_sequence">What
 751           is a sequence?</a>
 752         </h4>
 753 <p>
 754           A <span class="emphasis"><em>sequence</em></span> is given by the iteration over a <span class="emphasis"><em>forward
 755           iterable</em></span> container. A forward iterable container is:
 756         </p>
 757 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 758 <li class="listitem">
 759               either a C-array,
 760             </li>
 761 <li class="listitem">
 762               or a <code class="computeroutput"><span class="keyword">class</span></code>/<code class="computeroutput"><span class="keyword">struct</span></code> that implements the member functions
 763               <code class="computeroutput"><span class="identifier">begin</span></code> and <code class="computeroutput"><span class="identifier">end</span></code>.
 764             </li>
 765 </ul></div>
 766 <p>
 767           For collection comparisons, both sequences are also required to be different
 768           than <code class="computeroutput"><span class="identifier">string</span></code> sequences.
 769           In that case, the sequences are dispatched to string <a class="link" href="strings.html" title="Strings and C-strings comparison">comparison
 770           instead</a>.
 771         </p>
 772 <div class="warning"><table border="0" summary="Warning">
 773 <tr>
 774 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../../../../../doc/src/images/warning.png"></td>
 775 <th align="left">Warning</th>
 776 </tr>
 777 <tr><td align="left" valign="top"><p>
 778             <code class="computeroutput"><span class="identifier">string</span></code> (or <code class="computeroutput"><span class="identifier">wstring</span></code>) meets the sequence concept
 779             by definition, but their handling with <a class="link" href="../../utf_reference/testing_tool_ref/assertion_boost_test_universal_macro.html" title="BOOST_TEST"><code class="computeroutput"><span class="identifier">BOOST_TEST</span></code></a> is done differently.
 780             See <a class="link" href="strings.html" title="Strings and C-strings comparison">Strings
 781             and C-strings comparison</a> for more details.
 782           </p></td></tr>
 783 </table></div>
 784 <div class="tip"><table border="0" summary="Tip">
 785 <tr>
 786 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../../../../doc/src/images/tip.png"></td>
 787 <th align="left">Tip</th>
 788 </tr>
 789 <tr><td align="left" valign="top"><p>
 790             If the behavior of <a class="link" href="../../utf_reference/testing_tool_ref/assertion_boost_test_universal_macro.html" title="BOOST_TEST"><code class="computeroutput"><span class="identifier">BOOST_TEST</span></code></a> is not the one you
 791             expect, you can always use raw comparison. See <a class="link" href="../boost_test_universal_macro.html#boost_test_statement_limitations">this
 792             section</a> for details.
 793           </p></td></tr>
 794 </table></div>
 795 <div class="note"><table border="0" summary="Note">
 796 <tr>
 797 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../doc/src/images/note.png"></td>
 798 <th align="left">Note</th>
 799 </tr>
 800 <tr><td align="left" valign="top"><p>
 801             Since <a class="link" href="../../change_log.html#ref_CHANGE_LOG_3_6">Boost.Test 3.6</a> (Boost
 802             1.65) the requirements for the collection concepts have been relaxed
 803             to include C-arrays as well
 804           </p></td></tr>
 805 </table></div>
 806 <div class="note"><table border="0" summary="Note">
 807 <tr>
 808 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../doc/src/images/note.png"></td>
 809 <th align="left">Note</th>
 810 </tr>
 811 <tr><td align="left" valign="top"><p>
 812             Since <a class="link" href="../../change_log.html#ref_CHANGE_LOG_3_7">Boost.Test 3.7</a> (Boost
 813             1.67) the definition of <code class="computeroutput"><span class="identifier">const_iterator</span></code>
 814             and <code class="computeroutput"><span class="identifier">value_type</span></code> in the
 815             collection type is not required anymore (for the compilers properly supporting
 816             <code class="computeroutput"><span class="keyword">decltype</span></code>).
 817           </p></td></tr>
 818 </table></div>
 819 <p>
 820           The detection of the types that meet these requirements containers is delegated
 821           to the class <code class="computeroutput"><a class="link" href="../../../boost/unit_test/is_forward_iterable.html" title="Struct template is_forward_iterable">boost::unit_test::is_forward_iterable</a></code>,
 822           which for C++11 detects the required member functions and fields. However
 823           for C++03, the types providing the sequences should be explicitly indicated
 824           to the <span class="emphasis"><em>Unit Test Framework</em></span> by a specialization of
 825           <code class="computeroutput"><a class="link" href="../../../boost/unit_test/is_forward_iterable.html" title="Struct template is_forward_iterable">boost::unit_test::is_forward_iterable</a></code>
 826           <a href="#ftn.boost_test.testing_tools.extended_comparison.collections.f4" class="footnote" name="boost_test.testing_tools.extended_comparison.collections.f4"><sup class="footnote">[14]</sup></a>.
 827         </p>
 828 <div class="footnotes">
 829 <br><hr style="width:100; text-align:left;margin-left: 0">
 830 <div id="ftn.boost_test.testing_tools.extended_comparison.collections.f0" class="footnote"><p><a href="#boost_test.testing_tools.extended_comparison.collections.f0" class="para"><sup class="para">[10] </sup></a>
 831                 this might not be the case for e.g. <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">unordered_map</span></code>,
 832                 for which the buckets might be filled differently depending on the
 833                 insertion order.
 834               </p></div>
 835 <div id="ftn.boost_test.testing_tools.extended_comparison.collections.f1" class="footnote"><p><a href="#boost_test.testing_tools.extended_comparison.collections.f1" class="para"><sup class="para">[11] </sup></a>
 836                 in this case <code class="computeroutput"><span class="identifier">v_a</span> <span class="special">&lt;</span> <span class="identifier">v_b</span></code>
 837                 means that the point <code class="computeroutput"><span class="identifier">v_a</span></code>
 838                 is inside the rectangle (origin, <code class="computeroutput"><span class="identifier">v_b</span></code>)
 839               </p></div>
 840 <div id="ftn.boost_test.testing_tools.extended_comparison.collections.f2" class="footnote"><p><a href="#boost_test.testing_tools.extended_comparison.collections.f2" class="para"><sup class="para">[12] </sup></a>
 841                 either defined by the container or by the user
 842               </p></div>
 843 <div id="ftn.boost_test.testing_tools.extended_comparison.collections.f3" class="footnote"><p><a href="#boost_test.testing_tools.extended_comparison.collections.f3" class="para"><sup class="para">[13] </sup></a>
 844             the containers should yield the same sequences for a fixed set of elements
 845             they contain
 846           </p></div>
 847 <div id="ftn.boost_test.testing_tools.extended_comparison.collections.f4" class="footnote"><p><a href="#boost_test.testing_tools.extended_comparison.collections.f4" class="para"><sup class="para">[14] </sup></a>
 848             Standard containers of the <code class="computeroutput"><span class="identifier">STL</span></code>
 849             are recognized as <span class="emphasis"><em>forward iterable</em></span> container.
 850           </p></div>
 851 </div>
 852 </div>
 853 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 854 <td align="left"></td>
 855 <td align="right"><div class="copyright-footer">Copyright &#169; 2001-2019 Boost.Test
 856       contributors<p>
 857         Distributed under the Boost Software License, Version 1.0. (See accompanying
 858         file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
 859       </p>
 860 </div></td>
 861 </tr></table>
 862 <hr>
 863 <div class="spirit-nav">
 864 <a accesskey="p" href="strings.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../extended_comparison.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="bitwise.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
 865 </div>
 866 </body>
 867 </html>