/usr/share/doc/libntl-dev/NTL/vector.cpp.html is in libntl-dev 6.2.1-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>/Volumes/Unix/unix-files.noindex/ntl-new/ntl-6.1.0/doc/vector.cpp.html</title>
<meta name="Generator" content="Vim/7.3">
<meta name="plugin-version" content="vim7.3_v6">
<meta name="syntax" content="cpp">
<meta name="settings" content="use_css">
<style type="text/css">
<!--
pre { font-family: monospace; color: #000000; background-color: #ffffff; }
body { font-family: monospace; color: #000000; background-color: #ffffff; }
.Statement { color: #b03060; font-weight: bold; }
.Type { color: #008b00; font-weight: bold; }
.Comment { color: #0000ee; font-style: italic; }
-->
</style>
</head>
<body>
<pre>
<span class="Comment">/*</span><span class="Comment">*************************************************************************\</span>
<span class="Comment">MODULE: vector</span>
<span class="Comment">SUMMARY:</span>
<span class="Comment">Template class for dynamic-sized vectors.</span>
<span class="Comment">The declaration</span>
<span class="Comment"> Vec<T> v;</span>
<span class="Comment">creates a zero-length vector. To grow this vector to length n,</span>
<span class="Comment">execute</span>
<span class="Comment"> v.SetLength(n)</span>
<span class="Comment">This causes space to be allocated for (at least) n elements, and also</span>
<span class="Comment">causes the delault constructor for T to be called to initialize these</span>
<span class="Comment">elements.</span>
<span class="Comment">The current length of a vector is available as v.length().</span>
<span class="Comment">The i-th vector element (counting from 0) is accessed as v[i]. If the</span>
<span class="Comment">macro NTL_RANGE_CHECK is defined, code is emitted to test if 0 <= i <</span>
<span class="Comment">v.length(). This check is not performed by default.</span>
<span class="Comment">For old-time FORTRAN programmers, the i-th vector element (counting</span>
<span class="Comment">from 1) is accessed as v(i).</span>
<span class="Comment">Let n = v.length(). Calling v.SetLength(m) with m <= n sets the</span>
<span class="Comment">current length of v to m (but does not call any destructors or free</span>
<span class="Comment">any space). Calling v.SetLength(m) with m > n will allocate space and</span>
<span class="Comment">initialize as necessary, but will leave the values of the already</span>
<span class="Comment">allocated elements unchanged (although their addresses may change).</span>
<span class="Comment">Initializations are performed using T's default constructor.</span>
<span class="Comment">v.MaxLength() is the largest value of n for which v.SetLength(n) was invoked,</span>
<span class="Comment">and is equal to the number of entries that have been initialized.</span>
<span class="Comment">v.SetMaxLength(n) will allocate space for and initialize up to n elements,</span>
<span class="Comment">without changing v.length().</span>
<span class="Comment">When v's destructor is called, all constructed elements will be</span>
<span class="Comment">destructed, and all space will be relinquished.</span>
<span class="Comment">Space is managed using malloc, realloc, and free. When a vector is</span>
<span class="Comment">grown, a bit more space may be allocated than was requested for</span>
<span class="Comment">efficiency reasons.</span>
<span class="Comment">Note that when a vector is grown, the space is reallocated using</span>
<span class="Comment">realloc, and thus the addresses of vector elements may change,</span>
<span class="Comment">possibly creating dangling references to vector elements. One has to</span>
<span class="Comment">be especially careful of this when using vectors passed as reference</span>
<span class="Comment">parameters that may alias one another.</span>
<span class="Comment">Because realloc is used to grow a vector, the objects stored</span>
<span class="Comment">in a vector should be "relocatable"---that is, they shouldn't care</span>
<span class="Comment">what their actual address is, which may change over time.</span>
<span class="Comment">Most reasonable objects satisfy this constraint.</span>
<span class="Comment">v.allocated() is the number of elements which have been allocated,</span>
<span class="Comment">which may be more than the number elements initialized.</span>
<span class="Comment">Note that if n <= v.allocated(), then v.SetLength(n) is guaranteed</span>
<span class="Comment">not to cause any memory allocation, or movement of objects.</span>
<span class="Comment">\*************************************************************************</span><span class="Comment">*/</span>
<span class="Type">template</span><<span class="Type">class</span> T>
<span class="Type">class</span> Vec {
<span class="Statement">public</span>:
Vec(); <span class="Comment">// initially length 0</span>
Vec(<span class="Type">const</span> Vec<T>& a);
<span class="Comment">// copy constructor; uses the assignment operator of T</span>
<span class="Comment">// for copying into locations that have already been initialized,</span>
<span class="Comment">// and uses the copy constructor for T for initializing new locations.</span>
Vec& <span class="Statement">operator</span>=(<span class="Type">const</span> Vec<T>& a);
<span class="Comment">// assignment; uses the assignment operator of T</span>
<span class="Comment">// for copying into locations that have already been initialized,</span>
<span class="Comment">// and uses the copy constructor for T for initializing new locations.</span>
~Vec();
<span class="Comment">// destructor: calls T's destructor for all initialized</span>
<span class="Comment">// elements in the vector, and then frees the vector itself</span>
<span class="Type">void</span> SetLength(<span class="Type">long</span> n);
<span class="Comment">// set current length to n, growing vector if necessary</span>
<span class="Comment">// new objects are initialized using the default contructor for T</span>
<span class="Type">void</span> SetLength(<span class="Type">long</span> n, <span class="Type">const</span> T& a);
<span class="Comment">// set current length to n, growing vector if necessary</span>
<span class="Comment">// new objects are initialized using the copy contructor for T</span>
<span class="Type">long</span> length() <span class="Type">const</span>;
<span class="Comment">// current length</span>
T& <span class="Statement">operator</span>[](<span class="Type">long</span> i);
<span class="Type">const</span> T& <span class="Statement">operator</span>[](<span class="Type">long</span> i) <span class="Type">const</span>;
<span class="Comment">// indexing operation, starting from 0.</span>
<span class="Comment">// The first version is applied to non-const Vec<T>,</span>
<span class="Comment">// and returns a non-const reference to a T, while the second version</span>
<span class="Comment">// is applied to a const Vec<T> and returns a const reference to a T.</span>
T& <span class="Statement">operator</span>()(<span class="Type">long</span> i);
<span class="Type">const</span> T& <span class="Statement">operator</span>()(<span class="Type">long</span> i) <span class="Type">const</span>;
<span class="Comment">// indexing operation, starting from 1</span>
<span class="Comment">// The first version is applied to non-const Vec<T>,</span>
<span class="Comment">// and returns a non-const reference to a T, while the second version</span>
<span class="Comment">// is applied to a const Vec<T> and returns a const reference to a T.</span>
T* elts();
<span class="Type">const</span> T* elts() <span class="Type">const</span>;
<span class="Comment">// returns address of first vector element (or 0 if no space has</span>
<span class="Comment">// been allocated for this vector). If a vector potentially has</span>
<span class="Comment">// length 0, it is safer to write v.elts() instead of &v[0].</span>
<span class="Comment">// The first version is applied to non-const Vec<T>,</span>
<span class="Comment">// and returns a non-const pointer to a T, while the second version</span>
<span class="Comment">// is applied to a const Vec<T> and returns a const reference to a T.</span>
<span class="Type">void</span> swap(Vec<T>& y);
<span class="Comment">// swap with y (fast: just swaps pointers)</span>
<span class="Type">void</span> append(<span class="Type">const</span> T& a);
<span class="Comment">// append a to end of vector; uses the assignment operator of T</span>
<span class="Comment">// for copying into locations that have already been initialized,</span>
<span class="Comment">// and uses the copy constructor for T for initializing new locations.</span>
<span class="Type">void</span> append(<span class="Type">const</span> Vec<T>& w);
<span class="Comment">// append w to end of vector; uses the assignment operator of T</span>
<span class="Comment">// for copying into locations that have already been initialized,</span>
<span class="Comment">// and uses the copy constructor for T for initializing new locations.</span>
<span class="Comment">// Alternative access interface </span>
<span class="Type">const</span> T& get(<span class="Type">long</span> i) <span class="Type">const</span>;
<span class="Comment">// v.get(i) returns v[i]</span>
<span class="Type">void</span> put(<span class="Type">long</span> i, <span class="Type">const</span> T& a);
<span class="Comment">// v.put(i, a) equivalent to v[i] = q</span>
<span class="Comment">// Some STL compatibility</span>
<span class="Type">typedef</span> T value_type;
<span class="Type">typedef</span> value_type& reference;
<span class="Type">typedef</span> <span class="Type">const</span> value_type& const_reference;
<span class="Type">typedef</span> value_type *iterator;
<span class="Type">typedef</span> <span class="Type">const</span> value_type *const_iterator;
T* data();
<span class="Type">const</span> T* data() <span class="Type">const</span>;
<span class="Comment">// v.data() same as v.elts()</span>
T* begin();
<span class="Type">const</span> T* begin() <span class="Type">const</span>;
<span class="Comment">// v.begin() same as v.elts()</span>
T* end();
<span class="Type">const</span> T* end() <span class="Type">const</span>;
<span class="Comment">// pointer to last element (or NULL)</span>
T& at(<span class="Type">long</span> i);
<span class="Type">const</span> T& at(<span class="Type">long</span> i) <span class="Type">const</span>;
<span class="Comment">// indexing with range checking</span>
<span class="Comment">// the remaining member functions are a bit esoteric (skip on first</span>
<span class="Comment">// reading)</span>
Vec(INIT_SIZE_TYPE, <span class="Type">long</span> n);
<span class="Comment">// Vec(INIT_SIZE, n) initializes with an intial length of n.</span>
<span class="Type">void</span> kill();
<span class="Comment">// release space and set to length 0</span>
<span class="Type">void</span> SetMaxLength(<span class="Type">long</span> n);
<span class="Comment">// allocates space and initializes up to n elements. Does not change</span>
<span class="Comment">// current length</span>
<span class="Type">void</span> FixLength(<span class="Type">long</span> n);
<span class="Comment">// sets length to n and prohibits all future length changes.</span>
<span class="Comment">// FixLength may only be invoked immediately after the default</span>
<span class="Comment">// construction or kill.</span>
<span class="Comment">// The kill operation is also subsequently prohibited, and swap is</span>
<span class="Comment">// allowed on fixed length vectors of the same length.</span>
<span class="Comment">// FixLength is provided mainly to implement Mat<T>, to enforce</span>
<span class="Comment">// the restriction that all rows have the same length.</span>
<span class="Type">long</span> fixed() <span class="Type">const</span>;
<span class="Comment">// test if length has been fixed by FixLength().</span>
<span class="Type">long</span> MaxLength() <span class="Type">const</span>;
<span class="Comment">// maximum length, i.e., number of allocated and initialized elements</span>
<span class="Type">long</span> allocated() <span class="Type">const</span>;
<span class="Comment">// the number of objects for which space has been allocated, but not</span>
<span class="Comment">// necessarily initialized; this may be larger than MaxLength().</span>
T& RawGet(<span class="Type">long</span> i);
<span class="Type">const</span> T& RawGet(<span class="Type">long</span> i) <span class="Type">const</span>;
<span class="Comment">// indexing with no range checking</span>
<span class="Type">long</span> position(<span class="Type">const</span> T& a) <span class="Type">const</span>;
<span class="Comment">// returns position of a in the vector, or -1 if it is not there.</span>
<span class="Comment">// The search is conducted from position 0 to allocated()-1 the vector, </span>
<span class="Comment">// and an error is raised if the object is found at position MaxLength()</span>
<span class="Comment">// or higher (in which case a references an uninitialized object).</span>
<span class="Comment">// Note that if NTL_CLEAN_PTR flag is set, this routine takes</span>
<span class="Comment">// linear time, and otherwise, it takes constant time.</span>
<span class="Type">long</span> position1(<span class="Type">const</span> T& a) <span class="Type">const</span>;
<span class="Comment">// returns position of a in the vector, or -1 if it is not there.</span>
<span class="Comment">// The search is conducted from position 0 to length()-1 of the vector.</span>
<span class="Comment">// Note that if NTL_CLEAN_PTR flag is set, this routine takes</span>
<span class="Comment">// linear time, and otherwise, it takes constant time.</span>
};
<span class="Comment">/*</span><span class="Comment">*************************************************************************\</span>
<span class="Comment"> Some utility routines</span>
<span class="Comment">\*************************************************************************</span><span class="Comment">*/</span>
<span class="Type">template</span><<span class="Type">class</span> T>
<span class="Type">void</span> swap(Vec<T>& x, Vec<T>& y);
<span class="Comment">// swaps x & y; same as x.swap(y)</span>
<span class="Type">template</span><<span class="Type">class</span> T>
<span class="Type">void</span> append(Vec<T>& v, <span class="Type">const</span> T& a);
<span class="Comment">// appends a to the end of v; same as v.append(a)</span>
<span class="Type">template</span><<span class="Type">class</span> T>
<span class="Type">void</span> append(Vec<T>& v, <span class="Type">const</span> Vec<T>& w);
<span class="Comment">// appends w to the end of v; same as v.append(w)</span>
<span class="Comment">/*</span><span class="Comment">*************************************************************************\</span>
<span class="Comment"> Input/Output</span>
<span class="Comment">The I/O format for a vector v with n elements is:</span>
<span class="Comment"> [v[0] v[1] ... v[n-1]]</span>
<span class="Comment">Uses corresponding I/O operators for T</span>
<span class="Comment">\*************************************************************************</span><span class="Comment">*/</span>
<span class="Type">template</span><<span class="Type">class</span> T>
istream& <span class="Statement">operator</span>>>(istream&, Vec<T>&);
<span class="Type">template</span><<span class="Type">class</span> T>
ostream& <span class="Statement">operator</span><<(ostream&, <span class="Type">const</span> Vec<T>&);
<span class="Comment">/*</span><span class="Comment">*************************************************************************\</span>
<span class="Comment"> Equality Testing</span>
<span class="Comment">\*************************************************************************</span><span class="Comment">*/</span>
<span class="Type">template</span><<span class="Type">class</span> T>
<span class="Type">long</span> <span class="Statement">operator</span>==(<span class="Type">const</span> Vec<T>& a, <span class="Type">const</span> Vec<T>& b);
<span class="Type">template</span><<span class="Type">class</span> T>
<span class="Type">long</span> <span class="Statement">operator</span>!=(<span class="Type">const</span> Vec<T>& a, <span class="Type">const</span> Vec<T>& b);
<span class="Comment">/*</span><span class="Comment">*************************************************************************\</span>
<span class="Comment"> Customized Constructors and Destructors</span>
<span class="Comment"> </span>
<span class="Comment">Esoteric: skip on first reading...also these interfaces are subject to change</span>
<span class="Comment">When new elements in a vector need to be constructed, one of the</span>
<span class="Comment">following routines is called:</span>
<span class="Comment"> void BlockConstruct(T* p, long n); </span>
<span class="Comment"> // invokes T() to initialize p[i] for i = 0..n-1</span>
<span class="Comment"> void BlockConstructFromVec(T* p, long n, const T* q);</span>
<span class="Comment"> // invokes T(q[i]) to initialize p[i] for i = 0..n-1;</span>
<span class="Comment"> // q points to elements from a Vec<T></span>
<span class="Comment"> void BlockConstructFromObj(T* p, long n, const T& q);</span>
<span class="Comment"> // invokes T(q) to initialize p[i] for i = 0..n-1</span>
<span class="Comment">When a vector is destroyed, the following routine is called:</span>
<span class="Comment"> void BlockDestroy(T* p, long n);</span>
<span class="Comment"> // invokes ~T() on p[i] for i = 0..n-1</span>
<span class="Comment">The default behavior of these routines may be modified by </span>
<span class="Comment">overloading these functions with a custom implementation.</span>
<span class="Comment"> </span>
<span class="Comment">In NTL, these routines are overridden for the ZZ_p and GF2E classes,</span>
<span class="Comment">so that many vector entries will be packed into contiguous storage</span>
<span class="Comment">locations. This reduces the number of invocations of malloc, and</span>
<span class="Comment">increases locality of reference.</span>
<span class="Comment">\*************************************************************************</span><span class="Comment">*/</span>
</pre>
</body>
</html>
|