<ahref="util_2permutation_8h.html">Go to the documentation of this file.</a><divclass="fragment"><divclass="line"><aid="l00001"name="l00001"></a><spanclass="lineno"> 1</span><spanclass="comment">// Copyright 2010-2021 Google LLC</span></div>
<divclass="line"><aid="l00002"name="l00002"></a><spanclass="lineno"> 2</span><spanclass="comment">// Licensed under the Apache License, Version 2.0 (the "License");</span></div>
<divclass="line"><aid="l00003"name="l00003"></a><spanclass="lineno"> 3</span><spanclass="comment">// you may not use this file except in compliance with the License.</span></div>
<divclass="line"><aid="l00004"name="l00004"></a><spanclass="lineno"> 4</span><spanclass="comment">// You may obtain a copy of the License at</span></div>
<divclass="line"><aid="l00008"name="l00008"></a><spanclass="lineno"> 8</span><spanclass="comment">// Unless required by applicable law or agreed to in writing, software</span></div>
<divclass="line"><aid="l00009"name="l00009"></a><spanclass="lineno"> 9</span><spanclass="comment">// distributed under the License is distributed on an "AS IS" BASIS,</span></div>
<divclass="line"><aid="l00010"name="l00010"></a><spanclass="lineno"> 10</span><spanclass="comment">// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.</span></div>
<divclass="line"><aid="l00011"name="l00011"></a><spanclass="lineno"> 11</span><spanclass="comment">// See the License for the specific language governing permissions and</span></div>
<divclass="line"><aid="l00012"name="l00012"></a><spanclass="lineno"> 12</span><spanclass="comment">// limitations under the License.</span></div>
<divclass="line"><aid="l00015"name="l00015"></a><spanclass="lineno"> 15</span><spanclass="comment">// Classes for permuting indexable, ordered containers of data without</span></div>
<divclass="line"><aid="l00016"name="l00016"></a><spanclass="lineno"> 16</span><spanclass="comment">// depending on that data to be accessible in any particular way. The</span></div>
<divclass="line"><aid="l00017"name="l00017"></a><spanclass="lineno"> 17</span><spanclass="comment">// client needs to give us two things:</span></div>
<divclass="line"><aid="l00018"name="l00018"></a><spanclass="lineno"> 18</span><spanclass="comment">// 1. a permutation to apply to some container(s) of data, and</span></div>
<divclass="line"><aid="l00019"name="l00019"></a><spanclass="lineno"> 19</span><spanclass="comment">// 2. a description of how to move data around in the container(s).</span></div>
<divclass="line"><aid="l00021"name="l00021"></a><spanclass="lineno"> 21</span><spanclass="comment">// The permutation (1) comes to us in the form of an array argument to</span></div>
<divclass="line"><aid="l00022"name="l00022"></a><spanclass="lineno"> 22</span><spanclass="comment">// PermutationApplier::Apply(), along with index values that tell us</span></div>
<divclass="line"><aid="l00023"name="l00023"></a><spanclass="lineno"> 23</span><spanclass="comment">// where in that array the permutation of interest lies. Typically</span></div>
<divclass="line"><aid="l00024"name="l00024"></a><spanclass="lineno"> 24</span><spanclass="comment">// those index values will span the entire array that describes the</span></div>
<divclass="line"><aid="l00027"name="l00027"></a><spanclass="lineno"> 27</span><spanclass="comment">// Applying a permutation involves decomposing the permutation into</span></div>
<divclass="line"><aid="l00028"name="l00028"></a><spanclass="lineno"> 28</span><spanclass="comment">// disjoint cycles and walking each element of the underlying data one</span></div>
<divclass="line"><aid="l00029"name="l00029"></a><spanclass="lineno"> 29</span><spanclass="comment">// step around the unique cycle in which it participates. The</span></div>
<divclass="line"><aid="l00030"name="l00030"></a><spanclass="lineno"> 30</span><spanclass="comment">// decomposition into disjoint cycles is done implicitly on the fly as</span></div>
<divclass="line"><aid="l00031"name="l00031"></a><spanclass="lineno"> 31</span><spanclass="comment">// the code in PermutationApplier::Apply() advances through the array</span></div>
<divclass="line"><aid="l00032"name="l00032"></a><spanclass="lineno"> 32</span><spanclass="comment">// describing the permutation. As an important piece of bookkeeping to</span></div>
<divclass="line"><aid="l00033"name="l00033"></a><spanclass="lineno"> 33</span><spanclass="comment">// support the decomposition into cycles, the elements of the</span></div>
<divclass="line"><aid="l00034"name="l00034"></a><spanclass="lineno"> 34</span><spanclass="comment">// permutation array typically get modified somehow to indicate which</span></div>
<divclass="line"><aid="l00035"name="l00035"></a><spanclass="lineno"> 35</span><spanclass="comment">// ones have already been used.</span></div>
<divclass="line"><aid="l00037"name="l00037"></a><spanclass="lineno"> 37</span><spanclass="comment">// At first glance, it would seem that if the containers are</span></div>
<divclass="line"><aid="l00038"name="l00038"></a><spanclass="lineno"> 38</span><spanclass="comment">// indexable, we don't need anything more complicated than just the</span></div>
<divclass="line"><aid="l00039"name="l00039"></a><spanclass="lineno"> 39</span><spanclass="comment">// permutation and the container of data we want to permute; it would</span></div>
<divclass="line"><aid="l00040"name="l00040"></a><spanclass="lineno"> 40</span><spanclass="comment">// seem we can just use the container's operator[] to retrieve and</span></div>
<divclass="line"><aid="l00041"name="l00041"></a><spanclass="lineno"> 41</span><spanclass="comment">// assign elements within the container. Unfortunately it's not so</span></div>
<divclass="line"><aid="l00042"name="l00042"></a><spanclass="lineno"> 42</span><spanclass="comment">// simple because the containers of interest can be indexable without</span></div>
<divclass="line"><aid="l00043"name="l00043"></a><spanclass="lineno"> 43</span><spanclass="comment">// providing any consistent way of accessing their contents that</span></div>
<divclass="line"><aid="l00044"name="l00044"></a><spanclass="lineno"> 44</span><spanclass="comment">// applies to all the containers of interest. For instance, if we</span></div>
<divclass="line"><aid="l00045"name="l00045"></a><spanclass="lineno"> 45</span><spanclass="comment">// could insist that every indexable container must define an lvalue</span></div>
<divclass="line"><aid="l00046"name="l00046"></a><spanclass="lineno"> 46</span><spanclass="comment">// operator[]() we could simply use that for the assignments we need</span></div>
<divclass="line"><aid="l00047"name="l00047"></a><spanclass="lineno"> 47</span><spanclass="comment">// to do while walking around cycles of the permutation. But we cannot</span></div>
<divclass="line"><aid="l00048"name="l00048"></a><spanclass="lineno"> 48</span><spanclass="comment">// insist on any such thing. To see why, consider the PackedArray</span></div>
<divclass="line"><aid="l00049"name="l00049"></a><spanclass="lineno"> 49</span><spanclass="comment">// class template in ortools/util/packed_array.h</span></div>
<divclass="line"><aid="l00050"name="l00050"></a><spanclass="lineno"> 50</span><spanclass="comment">// where operator[] is supplied for rvalues, but because each logical</span></div>
<divclass="line"><aid="l00051"name="l00051"></a><spanclass="lineno"> 51</span><spanclass="comment">// array element is packed across potentially multiple instances of</span></div>
<divclass="line"><aid="l00052"name="l00052"></a><spanclass="lineno"> 52</span><spanclass="comment">// the underlying data type that the C++ language knows about, there</span></div>
<divclass="line"><aid="l00053"name="l00053"></a><spanclass="lineno"> 53</span><spanclass="comment">// is no way to have a C++ reference to an element of a</span></div>
<divclass="line"><aid="l00054"name="l00054"></a><spanclass="lineno"> 54</span><spanclass="comment">// PackedArray. There are other such examples besides PackedArray,</span></div>
<divclass="line"><aid="l00055"name="l00055"></a><spanclass="lineno"> 55</span><spanclass="comment">// too. This is the main reason we need a codified description (2) of</span></div>
<divclass="line"><aid="l00056"name="l00056"></a><spanclass="lineno"> 56</span><spanclass="comment">// how to move data around in the indexable container. That</span></div>
<divclass="line"><aid="l00057"name="l00057"></a><spanclass="lineno"> 57</span><spanclass="comment">// description comes to us via the PermutationApplier constructor's</span></div>
<divclass="line"><aid="l00058"name="l00058"></a><spanclass="lineno"> 58</span><spanclass="comment">// argument which is a PermutationCycleHandler instance. Such an</span></div>
<divclass="line"><aid="l00059"name="l00059"></a><spanclass="lineno"> 59</span><spanclass="comment">// object has three important methods defined: SetTempFromIndex(),</span></div>
<divclass="line"><aid="l00060"name="l00060"></a><spanclass="lineno"> 60</span><spanclass="comment">// SetIndexFromIndex(), and SetIndexFromTemp(). Those methods embody</span></div>
<divclass="line"><aid="l00061"name="l00061"></a><spanclass="lineno"> 61</span><spanclass="comment">// all we need to know about how to move data in the indexable</span></div>
<divclass="line"><aid="l00062"name="l00062"></a><spanclass="lineno"> 62</span><spanclass="comment">// container(s) underlying the PermutationCycleHandler.</span></div>
<divclass="line"><aid="l00064"name="l00064"></a><spanclass="lineno"> 64</span><spanclass="comment">// Another reason we need the description (2) of how to move elements</span></div>
<divclass="line"><aid="l00065"name="l00065"></a><spanclass="lineno"> 65</span><spanclass="comment">// around in the container(s) is that it is often important to permute</span></div>
<divclass="line"><aid="l00066"name="l00066"></a><spanclass="lineno"> 66</span><spanclass="comment">// side-by-side containers of elements according to the same</span></div>
<divclass="line"><aid="l00067"name="l00067"></a><spanclass="lineno"> 67</span><spanclass="comment">// permutation. This situation, too, is covered by defining a</span></div>
<divclass="line"><aid="l00068"name="l00068"></a><spanclass="lineno"> 68</span><spanclass="comment">// PermutationCycleHandler that knows about multiple underlying</span></div>
<divclass="line"><aid="l00071"name="l00071"></a><spanclass="lineno"> 71</span><spanclass="comment">// The above-mentioned PermutationCycleHandler methods embody</span></div>
<divclass="line"><aid="l00072"name="l00072"></a><spanclass="lineno"> 72</span><spanclass="comment">// knowledge of how to assign elements. It happens that</span></div>
<divclass="line"><aid="l00073"name="l00073"></a><spanclass="lineno"> 73</span><spanclass="comment">// PermutationCycleHandler is also a convenient place to embody the</span></div>
<divclass="line"><aid="l00074"name="l00074"></a><spanclass="lineno"> 74</span><spanclass="comment">// knowledge of how to keep track of which permutation elements have</span></div>
<divclass="line"><aid="l00075"name="l00075"></a><spanclass="lineno"> 75</span><spanclass="comment">// been consumed by the process of walking data around cycles. We</span></div>
<divclass="line"><aid="l00076"name="l00076"></a><spanclass="lineno"> 76</span><spanclass="comment">// depend on the PermutationCycleHandler instance we're given to</span></div>
<divclass="line"><aid="l00077"name="l00077"></a><spanclass="lineno"> 77</span><spanclass="comment">// define SetSeen() and Unseen() methods for that purpose.</span></div>
<divclass="line"><aid="l00079"name="l00079"></a><spanclass="lineno"> 79</span><spanclass="comment">// For the common case in which elements can be accessed using</span></div>
<divclass="line"><aid="l00080"name="l00080"></a><spanclass="lineno"> 80</span><spanclass="comment">// operator[](), we provide the class template</span></div>
<divclass="line"><aid="l00091"name="l00091"></a><spanclass="lineno"> 91</span><spanclass="comment">// Abstract base class template defining the interface needed by</span></div>
<divclass="line"><aid="l00092"name="l00092"></a><spanclass="lineno"> 92</span><spanclass="comment">// PermutationApplier to handle a single cycle of a permutation.</span></div>
<divclass="line"><aid="l00096"name="l00096"></a><spanclass="lineno"> 96</span><spanclass="comment">// Sets the internal temporary storage from the given index in the</span></div>
<divclass="line"><aid="l00100"name="l00100"></a><spanclass="lineno"> 100</span><spanclass="comment">// Moves a data element one step along its cycle.</span></div>
<divclass="line"><aid="l00104"name="l00104"></a><spanclass="lineno"> 104</span><spanclass="comment">// Sets a data element from the temporary.</span></div>
<divclass="line"><aid="l00107"name="l00107"></a><spanclass="lineno"> 107</span><spanclass="comment">// Marks an element of the permutation as handled by</span></div>
<divclass="line"><aid="l00108"name="l00108"></a><spanclass="lineno"> 108</span><spanclass="comment">// PermutationHandler::Apply(), meaning that we have read the</span></div>
<divclass="line"><aid="l00109"name="l00109"></a><spanclass="lineno"> 109</span><spanclass="comment">// corresponding value from the data to be permuted, and put that</span></div>
<divclass="line"><aid="l00110"name="l00110"></a><spanclass="lineno"> 110</span><spanclass="comment">// value somewhere (either in the temp or in its ultimate</span></div>
<divclass="line"><aid="l00111"name="l00111"></a><spanclass="lineno"> 111</span><spanclass="comment">// destination in the data.</span></div>
<divclass="line"><aid="l00113"name="l00113"></a><spanclass="lineno"> 113</span><spanclass="comment">// This method must be overridden in implementations where it is</span></div>
<divclass="line"><aid="l00114"name="l00114"></a><spanclass="lineno"> 114</span><spanclass="comment">// called. If an implementation doesn't call it, no need to</span></div>
<divclass="line"><aid="l00117"name="l00117"></a><spanclass="lineno"> 117</span><aclass="code hl_define"href="base_2logging_8h.html#accad43a85d781d53381cd53a9894b6ae">LOG</a>(<aclass="code hl_variable"href="log__severity_8h.html#acdd38e3c9f22f127d7776920e3079eda">FATAL</a>) <<<spanclass="stringliteral">"Base implementation of SetSeen() must not be called."</span>;</div>
<divclass="line"><aid="l00120"name="l00120"></a><spanclass="lineno"> 120</span><spanclass="comment">// Returns true iff the given element of the permutation is unseen,</span></div>
<divclass="line"><aid="l00121"name="l00121"></a><spanclass="lineno"> 121</span><spanclass="comment">// meaning that it has not yet been handled by</span></div>
<divclass="line"><aid="l00124"name="l00124"></a><spanclass="lineno"> 124</span><spanclass="comment">// This method must be overridden in implementations where it is</span></div>
<divclass="line"><aid="l00125"name="l00125"></a><spanclass="lineno"> 125</span><spanclass="comment">// called. If an implementation doesn't call it, no need to</span></div>
<divclass="line"><aid="l00128"name="l00128"></a><spanclass="lineno"> 128</span><aclass="code hl_define"href="base_2logging_8h.html#accad43a85d781d53381cd53a9894b6ae">LOG</a>(<aclass="code hl_variable"href="log__severity_8h.html#acdd38e3c9f22f127d7776920e3079eda">FATAL</a>) <<<spanclass="stringliteral">"Base implementation of Unseen() must not be called."</span>;</div>
<divclass="line"><aid="l00141"name="l00141"></a><spanclass="lineno"> 141</span><spanclass="comment">// A generic cycle handler class for the common case in which the</span></div>
<divclass="line"><aid="l00142"name="l00142"></a><spanclass="lineno"> 142</span><spanclass="comment">// object to be permuted is indexable with T& operator[](int), and the</span></div>
<divclass="line"><aid="l00143"name="l00143"></a><spanclass="lineno"> 143</span><spanclass="comment">// permutation is represented by a mutable array of nonnegative</span></div>
<divclass="line"><aid="l00144"name="l00144"></a><spanclass="lineno"> 144</span><spanclass="comment">// int-typed index values. To mark a permutation element as seen, we</span></div>
<divclass="line"><aid="l00145"name="l00145"></a><spanclass="lineno"> 145</span><spanclass="comment">// replace it by its ones-complement value.</span></div>
<divclass="line"><aid="l00167"name="l00167"></a><spanclass="lineno"> 167</span><spanclass="comment">// Pointer to the base of the array of data to be permuted.</span></div>
<divclass="line"><aid="l00170"name="l00170"></a><spanclass="lineno"> 170</span><spanclass="comment">// Temporary storage for the one extra element we need.</span></div>
<divclass="line"><aid="l00176"name="l00176"></a><spanclass="lineno"> 176</span><spanclass="comment">// Note that this template is not implemented in an especially</span></div>
<divclass="line"><aid="l00177"name="l00177"></a><spanclass="lineno"> 177</span><spanclass="comment">// performance-sensitive way. In particular, it makes multiple virtual</span></div>
<divclass="line"><aid="l00178"name="l00178"></a><spanclass="lineno"> 178</span><spanclass="comment">// method calls for each element of the permutation.</span></div>
<divclass="line"><aid="l00187"name="l00187"></a><spanclass="lineno"> 187</span><spanclass="keywordflow">for</span> (IndexType current = permutation_start; current < permutation_end;</div>
<divclass="line"><aid="l00204"name="l00204"></a><spanclass="lineno"> 204</span><spanclass="comment">// Set current back to the start of this cycle.</span></div>
<divclass="line"><aid="l00205"name="l00205"></a><spanclass="lineno"> 205</span> current = <aclass="code hl_variable"href="constraint__solver_8cc.html#a395f613555f398dd389670bb4c2a4599">next</a>;</div>
<divclass="ttc"id="aclassoperations__research_1_1_permutation_applier_html_ad4775eecdf6f1fcbddac8c58f4f52c4b"><divclass="ttname"><ahref="classoperations__research_1_1_permutation_applier.html#ad4775eecdf6f1fcbddac8c58f4f52c4b">operations_research::PermutationApplier::Apply</a></div><divclass="ttdeci">void Apply(IndexType permutation[], int permutation_start, int permutation_end)</div><divclass="ttdef"><b>Definition:</b><ahref="util_2permutation_8h_source.html#l00185">util/permutation.h:185</a></div></div>
<divclass="ttc"id="alog__severity_8h_html_acdd38e3c9f22f127d7776920e3079eda"><divclass="ttname"><ahref="log__severity_8h.html#acdd38e3c9f22f127d7776920e3079eda">FATAL</a></div><divclass="ttdeci">const int FATAL</div><divclass="ttdef"><b>Definition:</b><ahref="log__severity_8h_source.html#l00032">log_severity.h:32</a></div></div>
<divclass="ttc"id="anamespaceoperations__research_html"><divclass="ttname"><ahref="namespaceoperations__research.html">operations_research</a></div><divclass="ttdoc">Collection of objects used to extend the Constraint Solver library.</div><divclass="ttdef"><b>Definition:</b><ahref="dense__doubly__linked__list_8h_source.html#l00021">dense_doubly_linked_list.h:21</a></div></div>
