diff options
Diffstat (limited to 'EASTL/doc/html')
| -rw-r--r-- | EASTL/doc/html/EASTL Benchmarks.html | 330 | ||||
| -rw-r--r-- | EASTL/doc/html/EASTL Best Practices.html | 1001 | ||||
| -rw-r--r-- | EASTL/doc/html/EASTL Design.html | 424 | ||||
| -rw-r--r-- | EASTL/doc/html/EASTL FAQ.html | 2385 | ||||
| -rw-r--r-- | EASTL/doc/html/EASTL Glossary.html | 490 | ||||
| -rw-r--r-- | EASTL/doc/html/EASTL Gotchas.html | 175 | ||||
| -rw-r--r-- | EASTL/doc/html/EASTL Introduction.html | 47 | ||||
| -rw-r--r-- | EASTL/doc/html/EASTL Maintenance.html | 292 | ||||
| -rw-r--r-- | EASTL/doc/html/EASTL Modules.html | 666 | ||||
| -rw-r--r-- | EASTL/doc/html/EASTLDoc.css | 86 |
10 files changed, 5896 insertions, 0 deletions
diff --git a/EASTL/doc/html/EASTL Benchmarks.html b/EASTL/doc/html/EASTL Benchmarks.html new file mode 100644 index 0000000..70ff23f --- /dev/null +++ b/EASTL/doc/html/EASTL Benchmarks.html @@ -0,0 +1,330 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> + <title>EASTL Benchmarks</title> + <meta content="text/html; charset=us-ascii" http-equiv="content-type"> + <meta content="Paul Pedriana" name="author"> + <meta content="Presentation of various benchmarks of EASTL" name="description"> + <link type="text/css" rel="stylesheet" href="EASTLDoc.css"> +</head> + + +<body> + + +<h1>EASTL Benchmarks</h1> +<h2>Introduction</h2> +<p>This document provides a number of benchmark results of EASTL. + Where possible, these benchmarks are implemented as comparisons + with equivalent functionality found in other libraries such as + compiler STL libraries or other well-known libraries. These + comparison benchmarks concentrate on highlighting the differences + between implementations rather than the similarities. In many + mundane cases -- such as accessing a vector element via operator [] + -- virtually all vector/array implementations you are likely to run + into will have identical performance.<br> + + + +<br> + + + +It's also important to note that the platform you run on can make a + significant difference in the results. On a modern 3+GHz Windows PC + many operations are fast due to large memory caches, intelligent + branch prediction, and parallel instruction execution. However, on + embedded or console systems none of these may be the case. + <br> + + + +<br> + + + +While EASTL generally outperforms std STL, there are some benchmarks + here in which EASTL is slower than std STL. There are three primary +explanations of this:</p> +<ol> + + + + <li>EASTL is making some kind of speed, memory, or design tradeoff +that results in the given speed difference. In may such cases, EASTL +goes slower on one benchmark in order to go faster on another benchmark +deemed more important. This explanation constitutes about 60% of the +cases.</li> + + + + <li>Compiler optimizations and resulting code generation is +coincidencally favoring one kind of implementation over another, often +when they are visually virtually identical. This explantation +constitutes about 30% of the cases.</li> + + + + <li>EASTL is simply not yet as optimized as it could be. This +explanation constitutes about 10% of the cases (as of this writing +there are about three such functions throughout EASTL). </li> + + + +</ol> + + + +<h2> Benchmarks</h2> +<p>Below is a table of links to detailed benchmark results derived from + the Benchmark test present in the EASTL package. The detailed results + are present below the table. Additional platforms will be added as + results become available for those platforms. Debug benchmarks are + present because (lack of) debug performance can be significant for + highly templated libraries. EASTL has specific optimizations to enhance + debug performance relative to other standard libraries; in some cases + it is 10x or more faster than alternatives (though there are exceptions where EASTL is slower). Feel free to submit results + for additional compilers/platforms.<br> + + + +</p> +<table style="text-align: left; width: 550px; margin-left: 40px;" border="1" cellpadding="2" cellspacing="2"> + + + <tbody> + + + <tr> + + + <td style="text-align: center;"><span style="font-weight: bold;">Platform</span></td> + + + <td style="text-align: center;"><span style="font-weight: bold;">Compiler</span></td> + + + <td style="font-weight: bold; text-align: center;">STL type</td> + + + <td style="font-weight: bold; text-align: center;">Build</td> + + + <td style="text-align: center;"><span style="font-weight: bold;">Results</span></td> + + + </tr> + + + + + + <tr> + + + <td>Win32</td> + + + <td>VC++ 7.1</td> + + + <td>Microsoft (Dinkumware)</td> + + + <td>Debug</td> + + + <td><a href="#Win32.VC71.MS.Debug">Detail</a></td> + + + </tr> + + + <tr> + + + <td>Win32</td> + + + <td>VC++ 7.1</td> + + + <td>Microsoft (Dinkumware)</td> + + + <td>Release</td> + + + <td><a href="#Win32.VC71.MS.Release">Detail</a></td> + + + </tr> + + + <tr> + + + <td>Win32</td> + + + <td>VC++ 7.1</td> + + + <td>STLPort</td> + + + <td>Debug</td> + + + <td><a href="#Win32.VC71.STLPort.Debug">Detail</a></td> + + + </tr> + + + <tr> + + + <td>Win32</td> + + + <td>VC++ 7.1</td> + + + <td>STLPort</td> + + + <td>Release</td> + + + <td><a href="#Win32.VC71.STLPort.Release">Detail</a></td> + + + </tr> + + + + </tbody> +</table> + + + + + + + + + + + + + +<h2> + + + + + <a name="Win32.VC71.MS.Debug"></a>Win32.VC71.MS.Debug<span style="font-weight: bold;"></span><span style="font-weight: bold;"></span></h2> +<div style="margin-left: 40px;"> +<pre>EASTL version: 0.96.00<br>Platform: Windows on X86<br>Compiler: Microsoft Visual C++ compiler, version 1310<br>Allocator: PPMalloc::GeneralAllocatorDebug. Thread safety enabled.<br>Build: Debug. Inlining disabled. STL debug features disabled.<br><br>Values are times to complete tests; smaller values are better.<br>Alarm indicates a greater than 10% difference.<br><br>Test VC++ EASTL Ratio Alarm<br>----------------------------------------------------------------------------------------<br>algorithm/adj_find/vector<TestObject> 33061345 6497757 5.09 *<br>algorithm/copy/vector<LargePOD> 5844906 4876076 1.20 *<br>algorithm/copy/vector<uint32_t> 1634346 166065 9.84 *<br>algorithm/copy_backward/vector<LargePOD> 4515974 4638892 0.97<br>algorithm/copy_backward/vector<uint32_t> 1821168 121746 14.96 *<br>algorithm/count/vector<uint64_t> 17048884 2720766 6.27 *<br>algorithm/equal_range/vector<uint64_t> 1111147812 448756888 2.48 *<br>algorithm/fill/bool[] 1728722 91936 18.80 *<br>algorithm/fill/char[]/'d' 1299200 33745 38.50 *<br>algorithm/fill/vector<char>/'d' 10205092 33796 100.00 *<br>algorithm/fill/vector<char>/0 10200748 33805 100.00 *<br>algorithm/fill/vector<uint64_t> 10416538 1399687 7.44 *<br>algorithm/fill/vector<void*> 10221837 1307700 7.82 *<br>algorithm/fill_n/bool[] 1399033 34196 40.91 *<br>algorithm/fill_n/char[] 1299225 33754 38.49 *<br>algorithm/fill_n/vector<uint64_t> 5961637 1371900 4.35 *<br>algorithm/find_end/string/end 16569373 2657372 6.24 *<br>algorithm/find_end/string/middle 16558638 20242410 0.82 *<br>algorithm/find_end/string/none 16811207 40480468 0.42 *<br>algorithm/lex_cmp/schar[] 1749674 194429 9.00 *<br>algorithm/lex_cmp/vector<TestObject> 32824195 5253587 6.25 *<br>algorithm/lex_cmp/vector<uchar> 29852034 202658 100.00 *<br>algorithm/lower_bound/vector<TestObject> 798624462 350027935 2.28 *<br>algorithm/min_element/vector<TestObject> 21675298 5314676 4.08 *<br>algorithm/rand_shuffle/vector<uint64_t> 84236190 43677506 1.93 *<br>algorithm/reverse/list<TestObject> 3007292 2105799 1.43 *<br>algorithm/reverse/vector<TestObject> 2974618 2124796 1.40 *<br>algorithm/search/string<char> 16228158 3594268 4.52 *<br>algorithm/search_n/string<char> 16926985 1522096 11.12 *<br>algorithm/unique/vector<TestObject> 54206243 9988002 5.43 *<br>algorithm/unique/vector<uint32_t> 26940079 1741991 15.47 *<br>algorithm/unique/vector<uint64_t> 47621344 5213127 9.13 *<br>algorithm/upper_bound/vector<uint32_t> 372381295 137901552 2.70 *<br><br>bitset<1500>/>>=/1 90196544 92539832 0.97<br>bitset<1500>/count 50753832 53742117 0.94<br>bitset<1500>/flip 86935875 85121117 1.02<br>bitset<1500>/reset 78153837 79922611 0.98<br>bitset<1500>/set() 79214968 79360658 1.00<br>bitset<1500>/set(i) 11300589 12199651 0.93<br>bitset<1500>/test 11282679 13186450 0.86 *<br><br>bitset<15>/>>=/1 10500577 6000559 1.75 *<br>bitset<15>/count 4000356 6399753 0.63 *<br>bitset<15>/flip 7268877 5647944 1.29 *<br>bitset<15>/reset 8564235 5800163 1.48 *<br>bitset<15>/set() 9935523 5914012 1.68 *<br>bitset<15>/set(i) 11199703 12503637 0.90 *<br>bitset<15>/test 10600623 12899592 0.82 *<br><br>bitset<35>/>>=/1 13076052 6599834 1.98 *<br>bitset<35>/count 4800384 11500330 0.42 *<br>bitset<35>/flip 7915439 5816313 1.36 *<br>bitset<35>/reset 9400049 5803180 1.62 *<br>bitset<35>/set() 10701152 5840316 1.83 *<br>bitset<35>/set(i) 11342936 12271128 0.92<br>bitset<35>/test 10670799 13099682 0.81 *<br><br>bitset<75>/>>=/1 14198834 17151088 0.83 *<br>bitset<75>/count 5795530 8576373 0.68 *<br>bitset<75>/flip 8516703 8922995 0.95<br>bitset<75>/reset 9999970 8526095 1.17 *<br>bitset<75>/set() 11124877 9009686 1.23 *<br>bitset<75>/set(i) 11300563 12531618 0.90 *<br>bitset<75>/test 11031913 13100523 0.84 *<br><br>deque<ValuePair>/erase 743801706 335646802 2.22 *<br>deque<ValuePair>/insert 742331809 341912866 2.17 *<br>deque<ValuePair>/iteration 29097030 16315827 1.78 *<br>deque<ValuePair>/operator[] 49859598 24026313 2.08 *<br>deque<ValuePair>/push_back 424807033 34497608 12.31 *<br>deque<ValuePair>/push_front 402313373 38006322 10.59 *<br>deque<ValuePair>/sort 725101017 581796551 1.25 *<br><br>hash_map<string, uint32_t>/clear 559462 961019 0.58 *<br>hash_map<string, uint32_t>/count 53377807 8091448 6.60 *<br>hash_map<string, uint32_t>/erase pos 613573 858084 0.72 *<br>hash_map<string, uint32_t>/erase range 5488748 461134 11.90 *<br>hash_map<string, uint32_t>/erase val 35760096 16379858 2.18 *<br>hash_map<string, uint32_t>/find 43490335 10324823 4.21 *<br>hash_map<string, uint32_t>/find_as/char* 49343818 8617139 5.73 *<br>hash_map<string, uint32_t>/insert 107420281 168690439 0.64 *<br>hash_map<string, uint32_t>/iteration 2456356 1255153 1.96 *<br>hash_map<string, uint32_t>/operator[] 47209502 12581624 3.75 *<br><br>hash_map<uint32_t, TestObject>/clear 533172 546449 0.98<br>hash_map<uint32_t, TestObject>/count 28667432 2899997 9.89 *<br>hash_map<uint32_t, TestObject>/erase pos 683239 538289 1.27 *<br>hash_map<uint32_t, TestObject>/erase range 9632676 253037 38.07 *<br>hash_map<uint32_t, TestObject>/erase val 25466026 7752188 3.29 *<br>hash_map<uint32_t, TestObject>/find 20048253 4678502 4.29 *<br>hash_map<uint32_t, TestObject>/insert 71085798 37686187 1.89 *<br>hash_map<uint32_t, TestObject>/iteration 1460318 1338317 1.09<br>hash_map<uint32_t, TestObject>/operator[] 23226692 7888748 2.94 *<br><br>heap (uint32_t[])/make_heap 5399966 6961305 0.78 *<br>heap (uint32_t[])/pop_heap 108060534 103511318 1.04<br>heap (uint32_t[])/push_heap 22595661 16640688 1.36 *<br>heap (uint32_t[])/sort_heap 93559424 83076731 1.13 *<br><br>heap (vector<TestObject>)/make_heap 91770743 21724870 4.22 *<br>heap (vector<TestObject>)/pop_heap 1175599317 284007398 4.14 *<br>heap (vector<TestObject>)/push_heap 207804541 45918046 4.53 *<br>heap (vector<TestObject>)/sort_heap 970394145 208321477 4.66 *<br><br>list<TestObject>/ctor(it) 805539509 760938607 1.06<br>list<TestObject>/ctor(n) 80959236 75106995 1.08<br>list<TestObject>/erase 1052543704 1044976137 1.01<br>list<TestObject>/find 97785267 75970884 1.29 *<br>list<TestObject>/insert 873895175 807051107 1.08<br>list<TestObject>/push_back 812797710 780742425 1.04<br>list<TestObject>/remove 1850600714 1436980599 1.29 *<br>list<TestObject>/reverse 180270465 80466636 2.24 *<br>list<TestObject>/size/1 440148 599642 0.73 *<br>list<TestObject>/size/10 439433 1329817 0.33 * EASTL intentionally implements list::size as O(n).<br>list<TestObject>/size/100 439595 11030060 0.04 * EASTL intentionally implements list::size as O(n).<br>list<TestObject>/splice 177106094 69383027 2.55 *<br><br>map<TestObject, uint32_t>/clear 508283 470807 1.08<br>map<TestObject, uint32_t>/count 43145354 14280357 3.02 *<br>map<TestObject, uint32_t>/equal_range 38594004 16520447 2.34 *<br>map<TestObject, uint32_t>/erase/key 33948082 16123175 2.11 *<br>map<TestObject, uint32_t>/erase/pos 578332 455201 1.27 * MS uses a code bloating implementation of erase.<br>map<TestObject, uint32_t>/erase/range 387345 284538 1.36 *<br>map<TestObject, uint32_t>/find 22897224 12766100 1.79 *<br>map<TestObject, uint32_t>/insert 61665800 47286928 1.30 *<br>map<TestObject, uint32_t>/iteration 1977202 745391 2.65 *<br>map<TestObject, uint32_t>/lower_bound 19892941 12260928 1.62 *<br>map<TestObject, uint32_t>/operator[] 24199084 15429634 1.57 *<br>map<TestObject, uint32_t>/upper_bound 19842409 12064441 1.64 *<br><br>set<uint32_t>/clear 1027625 1000901 1.03<br>set<uint32_t>/count 39730182 13329565 2.98 *<br>set<uint32_t>/equal_range 34681649 14768827 2.35 *<br>set<uint32_t>/erase range 841458 602030 1.40 *<br>set<uint32_t>/erase/pos 1380485 1084303 1.27 * MS uses a code bloating implementation of erase.<br>set<uint32_t>/erase/val 31617425 13344023 2.37 *<br>set<uint32_t>/find 19582428 10788864 1.82 *<br>set<uint32_t>/insert 61434014 48232086 1.27 *<br>set<uint32_t>/iteration 1512057 667820 2.26 *<br>set<uint32_t>/lower_bound 18394885 10402785 1.77 *<br>set<uint32_t>/upper_bound 17189083 10554425 1.63 *<br><br>sort/q_sort/TestObject[] 87088799 15037988 5.79 *<br>sort/q_sort/TestObject[]/sorted 21502892 3284299 6.55 *<br>sort/q_sort/vector<TestObject> 87962047 15004677 5.86 *<br>sort/q_sort/vector<TestObject>/sorted 21396523 3341163 6.40 *<br>sort/q_sort/vector<ValuePair> 80334589 10429161 7.70 *<br>sort/q_sort/vector<ValuePair>/sorted 22133295 3230553 6.85 *<br>sort/q_sort/vector<uint32> 72195388 5940302 12.15 *<br>sort/q_sort/vector<uint32>/sorted 19635171 995495 19.72 *<br><br>string<char16_t>/compare 523013373 534722089 0.98<br>string<char16_t>/erase/pos,n 3446597 3439492 1.00<br>string<char16_t>/find/p,pos,n 383873158 441902786 0.87 *<br>string<char16_t>/find_first_not_of/p,pos,n 174157 134131 1.30 *<br>string<char16_t>/find_first_of/p,pos,n 11715423 8520944 1.37 *<br>string<char16_t>/find_last_of/p,pos,n 1871556 1226457 1.53 *<br>string<char16_t>/insert/pos,p 3624877 3357058 1.08<br>string<char16_t>/iteration 6766787933 581916665 11.63 *<br>string<char16_t>/operator[] 4820827 2335579 2.06 *<br>string<char16_t>/push_back 59812962 6757466 8.85 *<br>string<char16_t>/replace/pos,n,p,n 4371279 4459713 0.98<br>string<char16_t>/reserve 2307530 1919386 1.20 *<br>string<char16_t>/rfind/p,pos,n 734826 372615 1.97 *<br>string<char16_t>/size 41608 28866 1.44 *<br>string<char16_t>/swap 1033932 1490994 0.69 *<br><br>string<char8_t>/compare 63086797 64194771 0.98<br>string<char8_t>/erase/pos,n 2045687 1960270 1.04<br>string<char8_t>/find/p,pos,n 123872549 471364764 0.26 *<br>string<char8_t>/find_first_not_of/p,pos,n 140013 130271 1.07<br>string<char8_t>/find_first_of/p,pos,n 8051906 8749994 0.92<br>string<char8_t>/find_last_of/p,pos,n 1318835 1230715 1.07<br>string<char8_t>/insert/pos,p 1770610 1724234 1.03<br>string<char8_t>/iteration 28112136 2544475 11.05 *<br>string<char8_t>/operator[] 4810525 2255841 2.13 *<br>string<char8_t>/push_back 54869634 6127447 8.95 *<br>string<char8_t>/replace/pos,n,p,n 2737578 2847900 0.96<br>string<char8_t>/reserve 1123395 394902 2.84 *<br>string<char8_t>/rfind/p,pos,n 737299 368518 2.00 *<br>string<char8_t>/size 42245 26801 1.58 *<br>string<char8_t>/swap 1036142 1491028 0.69 *<br><br>vector<uint64>/erase 56417135 55770251 1.01<br>vector<uint64>/insert 56617761 56100468 1.01<br>vector<uint64>/iteration 10413895 1291269 8.06 *<br>vector<uint64>/operator[] 23507193 3479390 6.76 *<br>vector<uint64>/push_back 34687939 13806627 2.51 *<br>vector<uint64>/sort 256886550 84669657 3.03 *<br><br></pre> + + + + + +</div> + + + + + +<h2> + + + + + <a name="Win32.VC71.MS.Release"></a>Win32.VC71.MS.Release<span style="font-weight: bold;"></span><span style="font-weight: bold;"></span></h2> +<div style="margin-left: 40px;"> +<pre>EASTL version: 0.96.00<br>Platform: Windows on X86<br>Compiler: Microsoft Visual C++ compiler, version 1310<br>Allocator: PPMalloc::GeneralAllocator. Thread safety enabled.<br>Build: Full optimization. Inlining enabled.<br><br>Values are times to complete tests; smaller values are better.<br>Alarm indicates a greater than 10% difference.<br><br>Test VC++ EASTL Ratio Alarm<br>----------------------------------------------------------------------------------------<br>algorithm/adj_find/vector<TestObject> 2783546 2750660 1.01<br>algorithm/copy/vector<LargePOD> 6474025 4972738 1.30 *<br>algorithm/copy/vector<uint32_t> 157267 173162 0.91<br>algorithm/copy_backward/vector<LargePOD> 4836406 4374780 1.11 *<br>algorithm/copy_backward/vector<uint32_t> 104780 120912 0.87 *<br>algorithm/count/vector<uint64_t> 1368440 1368696 1.00<br>algorithm/equal_range/vector<uint64_t> 114199387 102783938 1.11 *<br>algorithm/fill/bool[] 253215 27353 9.26 *<br>algorithm/fill/char[]/'d' 253164 27404 9.24 *<br>algorithm/fill/vector<char>/'d' 253105 27362 9.25 *<br>algorithm/fill/vector<char>/0 253275 27353 9.26 *<br>algorithm/fill/vector<uint64_t> 397001 394323 1.01<br>algorithm/fill/vector<void*> 547196 642362 0.85 *<br>algorithm/fill_n/bool[] 229177 27361 8.38 *<br>algorithm/fill_n/char[] 228845 27404 8.35 *<br>algorithm/fill_n/vector<uint64_t> 565233 1376822 0.41 *<br>algorithm/find_end/string/end 2107116 82356 25.59 *<br>algorithm/find_end/string/middle 2111672 664283 3.18 *<br>algorithm/find_end/string/none 2110423 1519596 1.39 *<br>algorithm/lex_cmp/schar[] 741021 176162 4.21 *<br>algorithm/lex_cmp/vector<TestObject> 2610494 2642183 0.99<br>algorithm/lex_cmp/vector<uchar> 697595 167866 4.16 *<br>algorithm/lower_bound/vector<TestObject> 62462233 58146664 1.07<br>algorithm/min_element/vector<TestObject> 4350385 2671227 1.63 *<br>algorithm/rand_shuffle/vector<uint64_t> 10868261 11300818 0.96<br>algorithm/reverse/list<TestObject> 483718 470024 1.03<br>algorithm/reverse/vector<TestObject> 476739 484322 0.98<br>algorithm/search/string<char> 2560387 1259496 2.03 *<br>algorithm/search_n/string<char> 2770991 458524 6.04 *<br>algorithm/unique/vector<TestObject> 4194520 4658910 0.90 *<br>algorithm/unique/vector<uint32_t> 538730 787924 0.68 *<br>algorithm/unique/vector<uint64_t> 3169829 2575636 1.23 *<br>algorithm/upper_bound/vector<uint32_t> 27495562 25321593 1.09<br><br>bitset<1500>/>>=/1 33464228 33469719 1.00<br>bitset<1500>/count 18736116 18814903 1.00<br>bitset<1500>/flip 19299309 18605438 1.04<br>bitset<1500>/reset 22200487 15262847 1.45 *<br>bitset<1500>/set() 14418193 17557319 0.82 *<br>bitset<1500>/set(i) 1599250 1599199 1.00<br>bitset<1500>/test 1599241 1599233 1.00<br><br>bitset<15>/>>=/1 2199222 2264442 0.97<br>bitset<15>/count 1399406 1399193 1.00<br>bitset<15>/flip 1266712 1199197 1.06<br>bitset<15>/reset 1399364 1399109 1.00<br>bitset<15>/set() 1199197 999201 1.20 *<br>bitset<15>/set(i) 1599258 1462952 1.09<br>bitset<15>/test 1599275 1599224 1.00<br><br>bitset<35>/>>=/1 2599266 1933376 1.34 *<br>bitset<35>/count 2599240 2592559 1.00<br>bitset<35>/flip 1693124 1199188 1.41 *<br>bitset<35>/reset 1399406 999201 1.40 *<br>bitset<35>/set() 1599403 1199205 1.33 *<br>bitset<35>/set(i) 1599241 1599190 1.00<br>bitset<35>/test 1599250 1599232 1.00<br><br>bitset<75>/>>=/1 4199332 4199213 1.00<br>bitset<75>/count 2999497 2199341 1.36 *<br>bitset<75>/flip 2399499 1830178 1.31 *<br>bitset<75>/reset 2199468 1199197 1.83 *<br>bitset<75>/set() 1999387 1199851 1.67 *<br>bitset<75>/set(i) 1599266 1599198 1.00<br>bitset<75>/test 1599241 1662651 0.96<br><br>deque<ValuePair>/erase 90444165 37113253 2.44 *<br>deque<ValuePair>/insert 93299349 36175167 2.58 *<br>deque<ValuePair>/iteration 2756414 2122076 1.30 *<br>deque<ValuePair>/operator[] 5117969 4632075 1.10<br>deque<ValuePair>/push_back 30300757 3060357 9.90 *<br>deque<ValuePair>/push_front 25498529 2808392 9.08 *<br>deque<ValuePair>/sort 142283047 111292464 1.28 *<br><br>hash_map<string, uint32_t>/clear 146769 389699 0.38 *<br>hash_map<string, uint32_t>/count 13059434 3460324 3.77 *<br>hash_map<string, uint32_t>/erase pos 184246 331925 0.56 *<br>hash_map<string, uint32_t>/erase range 382432 167237 2.29 *<br>hash_map<string, uint32_t>/erase val 6187898 3302114 1.87 *<br>hash_map<string, uint32_t>/find 11289369 3459024 3.26 *<br>hash_map<string, uint32_t>/find_as/char* 13559192 3662387 3.70 *<br>hash_map<string, uint32_t>/insert 17514012 14095176 1.24 *<br>hash_map<string, uint32_t>/iteration 801014 218450 3.67 *<br>hash_map<string, uint32_t>/operator[] 11457065 3690385 3.10 *<br><br>hash_map<uint32_t, TestObject>/clear 141865 265379 0.53 *<br>hash_map<uint32_t, TestObject>/count 1766045 703613 2.51 *<br>hash_map<uint32_t, TestObject>/erase pos 172337 218458 0.79 *<br>hash_map<uint32_t, TestObject>/erase range 537846 102340 5.26 *<br>hash_map<uint32_t, TestObject>/erase val 2220132 1441787 1.54 *<br>hash_map<uint32_t, TestObject>/find 1612994 1043953 1.55 *<br>hash_map<uint32_t, TestObject>/insert 7141547 4348056 1.64 *<br>hash_map<uint32_t, TestObject>/iteration 199512 169328 1.18 *<br>hash_map<uint32_t, TestObject>/operator[] 1831733 1519707 1.21 *<br><br>heap (uint32_t[])/make_heap 3366247 1949093 1.73 *<br>heap (uint32_t[])/pop_heap 57280514 53779440 1.07<br>heap (uint32_t[])/push_heap 9700217 7582935 1.28 *<br>heap (uint32_t[])/sort_heap 47227751 46131948 1.02<br><br>heap (vector<TestObject>)/make_heap 11458442 11510819 1.00<br>heap (vector<TestObject>)/pop_heap 122897267 119061132 1.03<br>heap (vector<TestObject>)/push_heap 21688481 21176220 1.02<br>heap (vector<TestObject>)/sort_heap 90867380 88869523 1.02<br><br>list<TestObject>/ctor(it) 74591104 69845817 1.07<br>list<TestObject>/ctor(n) 6243998 5838582 1.07<br>list<TestObject>/erase 299509298 206013676 1.45 *<br>list<TestObject>/find 40927185 14514243 2.82 *<br>list<TestObject>/insert 71277251 47234534 1.51 *<br>list<TestObject>/push_back 73780527 44116725 1.67 *<br>list<TestObject>/remove 786197776 326434612 2.41 *<br>list<TestObject>/reverse 49283128 25029678 1.97 *<br>list<TestObject>/size/1 159741 139400 1.15 *<br>list<TestObject>/size/10 159324 346579 0.46 * EASTL intentionally implements list::size as O(n).<br>list<TestObject>/size/100 159188 97235419 0.00 * EASTL intentionally implements list::size as O(n).<br>list<TestObject>/splice 63548584 19322931 3.29 *<br><br>map<TestObject, uint32_t>/clear 167408 170501 0.98<br>map<TestObject, uint32_t>/count 10213685 4748346 2.15 *<br>map<TestObject, uint32_t>/equal_range 9515053 5677558 1.68 *<br>map<TestObject, uint32_t>/erase/key 6646260 4302300 1.54 *<br>map<TestObject, uint32_t>/erase/pos 297135 327938 0.91 MS uses a code bloating implementation of erase.<br>map<TestObject, uint32_t>/erase/range 148614 163702 0.91<br>map<TestObject, uint32_t>/find 5637531 4767055 1.18 *<br>map<TestObject, uint32_t>/insert 9591128 9030349 1.06<br>map<TestObject, uint32_t>/iteration 323595 325261 0.99<br>map<TestObject, uint32_t>/lower_bound 5398239 4784089 1.13 *<br>map<TestObject, uint32_t>/operator[] 5631250 5141166 1.10<br>map<TestObject, uint32_t>/upper_bound 5436336 4762431 1.14 *<br><br>set<uint32_t>/clear 155983 156026 1.00<br>set<uint32_t>/count 9635965 4392146 2.19 *<br>set<uint32_t>/equal_range 8504157 5247832 1.62 *<br>set<uint32_t>/erase range 140488 119408 1.18 *<br>set<uint32_t>/erase/pos 260678 286697 0.91 MS uses a code bloating implementation of erase.<br>set<uint32_t>/erase/val 6008225 4012825 1.50 *<br>set<uint32_t>/find 5145432 4381945 1.17 *<br>set<uint32_t>/insert 8087129 8697251 0.93<br>set<uint32_t>/iteration 271507 304538 0.89 *<br>set<uint32_t>/lower_bound 4666228 4404250 1.06<br>set<uint32_t>/upper_bound 4623600 4402974 1.05<br><br>sort/q_sort/TestObject[] 9596169 5578652 1.72 *<br>sort/q_sort/TestObject[]/sorted 602463 1016132 0.59 *<br>sort/q_sort/vector<TestObject> 9674828 5430199 1.78 *<br>sort/q_sort/vector<TestObject>/sorted 606908 1111647 0.55 *<br>sort/q_sort/vector<ValuePair> 6284194 3423452 1.84 *<br>sort/q_sort/vector<ValuePair>/sorted 711629 569364 1.25 *<br>sort/q_sort/vector<uint32> 5453379 2916146 1.87 *<br>sort/q_sort/vector<uint32>/sorted 537047 419144 1.28 *<br><br>string<char16_t>/compare 435083295 251985824 1.73 *<br>string<char16_t>/erase/pos,n 3454842 3451858 1.00<br>string<char16_t>/find/p,pos,n 401954723 165298157 2.43 *<br>string<char16_t>/find_first_not_of/p,pos,n 131452 65374 2.01 *<br>string<char16_t>/find_first_of/p,pos,n 11657444 4144515 2.81 *<br>string<char16_t>/find_last_of/p,pos,n 1604248 567571 2.83 *<br>string<char16_t>/insert/pos,p 3398734 3355460 1.01<br>string<char16_t>/iteration 218856504 218771844 1.00<br>string<char16_t>/operator[] 714161 240023 2.98 *<br>string<char16_t>/push_back 34968235 2444897 14.30 *<br>string<char16_t>/replace/pos,n,p,n 4226693 4198498 1.01<br>string<char16_t>/reserve 1901765 390805 4.87 *<br>string<char16_t>/rfind/p,pos,n 195483 150985 1.29 *<br>string<char16_t>/size 11169 11245 0.99<br>string<char16_t>/swap 1459280 419807 3.48 *<br><br>string<char8_t>/compare 63071275 77209580 0.82 *<br>string<char8_t>/erase/pos,n 2008652 1944494 1.03<br>string<char8_t>/find/p,pos,n 123201023 167536164 0.74 *<br>string<char8_t>/find_first_not_of/p,pos,n 93372 67864 1.38 *<br>string<char8_t>/find_first_of/p,pos,n 7542492 3375758 2.23 *<br>string<char8_t>/find_last_of/p,pos,n 933972 583576 1.60 *<br>string<char8_t>/insert/pos,p 1737213 1750847 0.99<br>string<char8_t>/iteration 893834 899130 0.99<br>string<char8_t>/operator[] 817879 313437 2.61 *<br>string<char8_t>/push_back 20857734 2004410 10.41 *<br>string<char8_t>/replace/pos,n,p,n 2578696 2607655 0.99<br>string<char8_t>/reserve 915127 85289 10.73 *<br>string<char8_t>/rfind/p,pos,n 196103 148894 1.32 *<br>string<char8_t>/size 11619 11220 1.04<br>string<char8_t>/swap 1461056 419874 3.48 *<br><br>vector<uint64>/erase 55235116 55284587 1.00<br>vector<uint64>/insert 55166046 55142755 1.00<br>vector<uint64>/iteration 553954 509719 1.09<br>vector<uint64>/operator[] 1284239 798516 1.61 *<br>vector<uint64>/push_back 5399549 3867959 1.40 *<br>vector<uint64>/sort 43636314 42619952 1.02<br></pre> + + + + + +</div> + + + + + +<h2> + + <a name="Win32.VC71.STLPort.Debug"></a>Win32.VC71.STLPort.Debug<span style="font-weight: bold;"></span><span style="font-weight: bold;"></span></h2> +<div style="margin-left: 40px;"> +<pre>EASTL version: 0.96.00<br>Platform: Windows on X86<br>Compiler: Microsoft Visual C++ compiler, version 1310<br>Allocator: PPMalloc::GeneralAllocatorDebug. Thread safety enabled.<br>Build: Debug. Inlining disabled. STL debug features disabled.<br><br>Values are times to complete tests; smaller values are better.<br>Alarm indicates a greater than 10% difference.<br><br>Test STLPort EASTL Ratio Alarm<br>----------------------------------------------------------------------------------------<br>algorithm/adj_find/vector<TestObject> 5661170 5689517 1.00<br>algorithm/copy/vector<LargePOD> 5573815 5124428 1.09<br>algorithm/copy/vector<uint32_t> 148273 125782 1.18 *<br>algorithm/copy_backward/vector<LargePOD> 5429791 4834510 1.12 *<br>algorithm/copy_backward/vector<uint32_t> 156765 163038 0.96<br>algorithm/count/vector<uint64_t> 2730922 2730072 1.00<br>algorithm/equal_range/vector<uint64_t> 639366489 452896251 1.41 *<br>algorithm/fill/bool[] 1299326 27361 47.49 *<br>algorithm/fill/char[]/'d' 27378 27361 1.00<br>algorithm/fill/vector<char>/'d' 34459 27361 1.26 *<br>algorithm/fill/vector<char>/0 1299224 27361 47.48 *<br>algorithm/fill/vector<uint64_t> 1400647 1400145 1.00<br>algorithm/fill/vector<void*> 1308779 1309085 1.00<br>algorithm/fill_n/bool[] 1299156 27352 47.50 *<br>algorithm/fill_n/char[] 1299258 27369 47.47 *<br>algorithm/fill_n/vector<uint64_t> 1451162 1313632 1.10<br>algorithm/find_end/string/end 13089999 2526412 5.18 *<br>algorithm/find_end/string/middle 12627412 20190101 0.63 *<br>algorithm/find_end/string/none 12704185 40728803 0.31 *<br>algorithm/lex_cmp/schar[] 1749844 195806 8.94 *<br>algorithm/lex_cmp/vector<TestObject> 5060968 4799882 1.05<br>algorithm/lex_cmp/vector<uchar> 1668354 189490 8.80 *<br>algorithm/lower_bound/vector<TestObject> 450240945 353437573 1.27 *<br>algorithm/min_element/vector<TestObject> 5861744 5326371 1.10<br>algorithm/rand_shuffle/vector<uint64_t> 40780449 45780090 0.89 *<br>algorithm/reverse/list<TestObject> 2657678 2130627 1.25 *<br>algorithm/reverse/vector<TestObject> 2666424 2124889 1.25 *<br>algorithm/search/string<char> 3110379 3613460 0.86 *<br>algorithm/search_n/string<char> 3061665 1521261 2.01 *<br>algorithm/unique/vector<TestObject> 12423684 9485439 1.31 *<br>algorithm/unique/vector<uint32_t> 3718699 1726596 2.15 *<br>algorithm/unique/vector<uint64_t> 6205110 4591631 1.35 *<br>algorithm/upper_bound/vector<uint32_t> 185391094 139336317 1.33 *<br><br>bitset<1500>/>>=/1 120666960 92449816 1.31 * STLPort is broken, neglects wraparound check.<br>bitset<1500>/count 201709793 52874726 3.81 *<br>bitset<1500>/flip 87360297 81737071 1.07<br>bitset<1500>/reset 23950178 77390323 0.31 *<br>bitset<1500>/set() 84608107 76912011 1.10<br>bitset<1500>/set(i) 18023620 12229604 1.47 *<br>bitset<1500>/test 18006553 13276396 1.36 *<br><br>bitset<15>/>>=/1 11935904 6012695 1.99 * STLPort is broken, neglects wraparound check.<br>bitset<15>/count 9368581 6022742 1.56 *<br>bitset<15>/flip 11600706 6533635 1.78 *<br>bitset<15>/reset 5830957 5874690 0.99<br>bitset<15>/set() 11695328 5701621 2.05 *<br>bitset<15>/set(i) 16363205 12570216 1.30 *<br>bitset<15>/test 16743172 13201452 1.27 *<br><br>bitset<35>/>>=/1 22950918 6774457 3.39 * STLPort is broken, neglects wraparound check.<br>bitset<35>/count 12655309 11736256 1.08<br>bitset<35>/flip 13738575 5800042 2.37 *<br>bitset<35>/reset 15561434 5800510 2.68 *<br>bitset<35>/set() 13564283 5600709 2.42 *<br>bitset<35>/set(i) 18519689 12199973 1.52 *<br>bitset<35>/test 18000569 13103566 1.37 *<br><br>bitset<75>/>>=/1 25579525 16669664 1.53 * STLPort is broken, neglects wraparound check.<br>bitset<75>/count 18740698 8480492 2.21 *<br>bitset<75>/flip 13555630 8300335 1.63 *<br>bitset<75>/reset 15200133 8200000 1.85 *<br>bitset<75>/set() 14408112 8001959 1.80 *<br>bitset<75>/set(i) 18137741 12374257 1.47 *<br>bitset<75>/test 18422135 13100038 1.41 *<br><br>deque<ValuePair>/erase 651933790 326443043 2.00 *<br>deque<ValuePair>/insert 659786183 333304660 1.98 *<br>deque<ValuePair>/iteration 23734592 16173706 1.47 *<br>deque<ValuePair>/operator[] 59126816 23911774 2.47 *<br>deque<ValuePair>/push_back 58056988 31859266 1.82 *<br>deque<ValuePair>/push_front 57780891 31743199 1.82 *<br>deque<ValuePair>/sort 818414195 596568113 1.37 *<br><br>hash_map<string, uint32_t>/clear 3422133 2204517 1.55 *<br>hash_map<string, uint32_t>/count 9869545 8624924 1.14 *<br>hash_map<string, uint32_t>/erase pos 3256350 2069299 1.57 *<br>hash_map<string, uint32_t>/erase range 3230203 1151392 2.81 *<br>hash_map<string, uint32_t>/erase val 16860362 15939778 1.06<br>hash_map<string, uint32_t>/find 10286971 9920910 1.04<br>hash_map<string, uint32_t>/find_as/char* 118136025 9458468 12.49 *<br>hash_map<string, uint32_t>/insert 188948336 174490082 1.08<br>hash_map<string, uint32_t>/iteration 4037049 2021036 2.00 *<br>hash_map<string, uint32_t>/operator[] 11472127 12887699 0.89 *<br><br>hash_map<uint32_t, TestObject>/clear 2522264 1331848 1.89 *<br>hash_map<uint32_t, TestObject>/count 3210739 2897063 1.11 *<br>hash_map<uint32_t, TestObject>/erase pos 1862281 1304783 1.43 *<br>hash_map<uint32_t, TestObject>/erase range 698079 579606 1.20 *<br>hash_map<uint32_t, TestObject>/erase val 8806722 7041298 1.25 *<br>hash_map<uint32_t, TestObject>/find 3604875 4709645 0.77 *<br>hash_map<uint32_t, TestObject>/insert 40785711 40376342 1.01<br>hash_map<uint32_t, TestObject>/iteration 3064088 1508834 2.03 *<br>hash_map<uint32_t, TestObject>/operator[] 6053742 8176906 0.74 *<br><br>heap (uint32_t[])/make_heap 5799813 5738596 1.01<br>heap (uint32_t[])/pop_heap 113775168 102076134 1.11 *<br>heap (uint32_t[])/push_heap 21649151 16854845 1.28 *<br>heap (uint32_t[])/sort_heap 97535213 83290735 1.17 *<br><br>heap (vector<TestObject>)/make_heap 22215557 22277063 1.00<br>heap (vector<TestObject>)/pop_heap 275392171 277340039 0.99<br>heap (vector<TestObject>)/push_heap 51479442 47342577 1.09<br>heap (vector<TestObject>)/sort_heap 214474736 218497540 0.98<br><br>list<TestObject>/ctor(it) 767753795 753421427 1.02<br>list<TestObject>/ctor(n) 74185322 73386245 1.01<br>list<TestObject>/erase 1021003824 1033873589 0.99<br>list<TestObject>/find 77666072 74917622 1.04<br>list<TestObject>/insert 788071150 774188737 1.02<br>list<TestObject>/push_back 760490154 737327348 1.03<br>list<TestObject>/remove 1682511938 1434771006 1.17 *<br>list<TestObject>/reverse 87237327 80394623 1.09<br>list<TestObject>/size/1 3828111 599530 6.39 *<br>list<TestObject>/size/10 9600605 1329535 7.22 * EASTL intentionally implements list::size as O(n).<br>list<TestObject>/size/100 62952334 15022551 4.19 * EASTL intentionally implements list::size as O(n).<br>list<TestObject>/splice 96536412 60804817 1.59 *<br><br>map<TestObject, uint32_t>/clear 1142127 1099066 1.04<br>map<TestObject, uint32_t>/count 19659726 14647548 1.34 *<br>map<TestObject, uint32_t>/equal_range 36680687 18219086 2.01 *<br>map<TestObject, uint32_t>/erase/key 28892154 16037774 1.80 *<br>map<TestObject, uint32_t>/erase/pos 1209643 1185495 1.02<br>map<TestObject, uint32_t>/erase/range 715402 670539 1.07<br>map<TestObject, uint32_t>/find 21020992 13429575 1.57 *<br>map<TestObject, uint32_t>/insert 59530871 51120640 1.16 *<br>map<TestObject, uint32_t>/iteration 972825 1191946 0.82 *<br>map<TestObject, uint32_t>/lower_bound 18852651 12495034 1.51 *<br>map<TestObject, uint32_t>/operator[] 22889573 16676736 1.37 *<br>map<TestObject, uint32_t>/upper_bound 18603584 12406922 1.50 *<br><br>set<uint32_t>/clear 919555 882988 1.04<br>set<uint32_t>/count 17561110 12461084 1.41 *<br>set<uint32_t>/equal_range 31522488 15230282 2.07 *<br>set<uint32_t>/erase range 687582 564765 1.22 *<br>set<uint32_t>/erase/pos 1044352 1045355 1.00<br>set<uint32_t>/erase/val 25525304 12940774 1.97 *<br>set<uint32_t>/find 17140751 10704866 1.60 *<br>set<uint32_t>/insert 56035051 45555664 1.23 *<br>set<uint32_t>/iteration 682669 640831 1.07<br>set<uint32_t>/lower_bound 16339932 10475740 1.56 *<br>set<uint32_t>/upper_bound 17779424 10652599 1.67 *<br><br>sort/q_sort/TestObject[] 17000866 14823515 1.15 *<br>sort/q_sort/TestObject[]/sorted 6658559 3263328 2.04 *<br>sort/q_sort/vector<TestObject> 17476629 14953285 1.17 *<br>sort/q_sort/vector<TestObject>/sorted 6667034 3327435 2.00 *<br>sort/q_sort/vector<ValuePair> 15391357 10820848 1.42 *<br>sort/q_sort/vector<ValuePair>/sorted 6617122 3232949 2.05 *<br>sort/q_sort/vector<uint32> 8343906 6014846 1.39 *<br>sort/q_sort/vector<uint32>/sorted 3039430 1003127 3.03 *<br><br>string<char16_t>/compare 1489709846 532664000 2.80 *<br>string<char16_t>/erase/pos,n 3528690 3439864 1.03<br>string<char16_t>/find/p,pos,n 2521448321 443752189 5.68 *<br>string<char16_t>/find_first_not_of/p,pos,n 661206 137419 4.81 *<br>string<char16_t>/find_first_of/p,pos,n 54746434 8521335 6.42 *<br>string<char16_t>/find_last_of/p,pos,n 10607778 1212414 8.75 *<br>string<char16_t>/insert/pos,p 3445016 3360126 1.03<br>string<char16_t>/iteration 580955636 579452556 1.00<br>string<char16_t>/operator[] 2206353 1987809 1.11 *<br>string<char16_t>/push_back 22421368 6007808 3.73 *<br>string<char16_t>/replace/pos,n,p,n 5138454 4464786 1.15 *<br>string<char16_t>/reserve 4922413418 335622 100.00 *<br>string<char16_t>/rfind/p,pos,n 1440308 380578 3.78 *<br>string<char16_t>/size 25355 25398 1.00<br>string<char16_t>/swap 2122704 1490823 1.42 *<br><br>string<char8_t>/compare 77222134 77443134 1.00<br>string<char8_t>/erase/pos,n 1965344 1956521 1.00<br>string<char8_t>/find/p,pos,n 2468091951 474205522 5.20 *<br>string<char8_t>/find_first_not_of/p,pos,n 660960 130211 5.08 *<br>string<char8_t>/find_first_of/p,pos,n 55020899 9240171 5.95 *<br>string<char8_t>/find_last_of/p,pos,n 10576210 1239053 8.54 *<br>string<char8_t>/insert/pos,p 1822756 1750880 1.04<br>string<char8_t>/iteration 2617889 2540148 1.03<br>string<char8_t>/operator[] 2254794 2256443 1.00<br>string<char8_t>/push_back 12463022 5210321 2.39 *<br>string<char8_t>/replace/pos,n,p,n 3744862 2855260 1.31 *<br>string<char8_t>/reserve 1372046888 218815 100.00 *<br>string<char8_t>/rfind/p,pos,n 1446232 366902 3.94 *<br>string<char8_t>/size 26859 25431 1.06<br>string<char8_t>/swap 2123350 1490509 1.42 *<br><br>vector<uint64>/erase 55164013 56417449 0.98<br>vector<uint64>/insert 55872973 56432664 0.99<br>vector<uint64>/iteration 1329102 1324623 1.00<br>vector<uint64>/operator[] 5264738 3136746 1.68 *<br>vector<uint64>/push_back 14903245 13171175 1.13 *<br>vector<uint64>/sort 88429095 88542171 1.00<br></pre> + + + + + +</div> + + + + + +<h2> + + + + + <a name="Win32.VC71.STLPort.Release"></a>Win32.VC71.STLPort.Release<span style="font-weight: bold;"></span><span style="font-weight: bold;"></span></h2> +<div style="margin-left: 40px;"> +<pre>EASTL version: 0.96.00<br>Platform: Windows on X86<br>Compiler: Microsoft Visual C++ compiler, version 1310<br>Allocator: PPMalloc::GeneralAllocator. Thread safety enabled.<br>Build: Full optimization. Inlining enabled.<br><br>Values are times to complete tests; smaller values are better.<br>Alarm indicates a greater than 10% difference.<br><br>Test STLPort EASTL Ratio Alarm<br>----------------------------------------------------------------------------------------<br>algorithm/adj_find/vector<TestObject> 2741046 2731441 1.00<br>algorithm/copy/vector<LargePOD> 6065923 5085142 1.19 *<br>algorithm/copy/vector<uint32_t> 158304 165555 0.96<br>algorithm/copy_backward/vector<LargePOD> 4710258 4896476 0.96<br>algorithm/copy_backward/vector<uint32_t> 146030 142630 1.02<br>algorithm/count/vector<uint64_t> 1395921 1406334 0.99<br>algorithm/equal_range/vector<uint64_t> 211692764 118969493 1.78 *<br>algorithm/fill/bool[] 366078 33737 10.85 *<br>algorithm/fill/char[]/'d' 33736 33771 1.00<br>algorithm/fill/vector<char>/'d' 28466 33720 0.84 *<br>algorithm/fill/vector<char>/0 366086 33728 10.85 *<br>algorithm/fill/vector<uint64_t> 466250 401591 1.16 *<br>algorithm/fill/vector<void*> 521603 693481 0.75 *<br>algorithm/fill_n/bool[] 599709 33762 17.76 *<br>algorithm/fill_n/char[] 599573 33711 17.79 *<br>algorithm/fill_n/vector<uint64_t> 434971 1374084 0.32 *<br>algorithm/find_end/string/end 1494742 85349 17.51 *<br>algorithm/find_end/string/middle 1480700 687208 2.15 *<br>algorithm/find_end/string/none 1540540 1546431 1.00<br>algorithm/lex_cmp/schar[] 921638 178797 5.15 *<br>algorithm/lex_cmp/vector<TestObject> 2623559 2643551 0.99<br>algorithm/lex_cmp/vector<uchar> 960899 183608 5.23 *<br>algorithm/lower_bound/vector<TestObject> 60630534 56531528 1.07<br>algorithm/min_element/vector<TestObject> 4209022 2768527 1.52 *<br>algorithm/rand_shuffle/vector<uint64_t> 13762010 15969052 0.86 *<br>algorithm/reverse/list<TestObject> 673387 731825 0.92<br>algorithm/reverse/vector<TestObject> 634576 754511 0.84 *<br>algorithm/search/string<char> 1262599 1387608 0.91<br>algorithm/search_n/string<char> 1166242 458592 2.54 *<br>algorithm/unique/vector<TestObject> 4912193 5336317 0.92<br>algorithm/unique/vector<uint32_t> 809387 809081 1.00<br>algorithm/unique/vector<uint64_t> 4371814 2414255 1.81 *<br>algorithm/upper_bound/vector<uint32_t> 31899081 29555596 1.08<br><br>bitset<1500>/>>=/1 63308136 40553560 1.56 * STLPort is broken, neglects wraparound check.<br>bitset<1500>/count 62523178 22799473 2.74 *<br>bitset<1500>/flip 20302845 19919232 1.02<br>bitset<1500>/reset 18892015 15403148 1.23 *<br>bitset<1500>/set() 15803302 17322192 0.91<br>bitset<1500>/set(i) 2799271 2999310 0.93<br>bitset<1500>/test 2999293 2799262 1.07<br><br>bitset<15>/>>=/1 1199239 3199256 0.37 * STLPort is broken, neglects wraparound check.<br>bitset<15>/count 3599461 2199231 1.64 *<br>bitset<15>/flip 1199231 1199188 1.00<br>bitset<15>/reset 1199188 1199180 1.00<br>bitset<15>/set() 1199214 1199180 1.00<br>bitset<15>/set(i) 2599257 1399262 1.86 *<br>bitset<15>/test 2599274 2599283 1.00<br><br>bitset<35>/>>=/1 6643974 4599239 1.44 * STLPort is broken, neglects wraparound check.<br>bitset<35>/count 5151331 5399438 0.95<br>bitset<35>/flip 1999404 1199273 1.67 *<br>bitset<35>/reset 9805285 1399313 7.01 *<br>bitset<35>/set() 2799279 1199248 2.33 *<br>bitset<35>/set(i) 2799246 1599241 1.75 *<br>bitset<35>/test 2999234 2999251 1.00<br><br>bitset<75>/>>=/1 7002045 6999333 1.00 STLPort is broken, neglects wraparound check.<br>bitset<75>/count 5999351 3002259 2.00 *<br>bitset<75>/flip 3599334 3599163 1.00<br>bitset<75>/reset 9799344 3399218 2.88 *<br>bitset<75>/set() 3599232 3599062 1.00<br>bitset<75>/set(i) 2799228 1599284 1.75 *<br>bitset<75>/test 2999250 2799339 1.07<br><br>deque<ValuePair>/erase 127108651 115258113 1.10<br>deque<ValuePair>/insert 137727889 116552332 1.18 *<br>deque<ValuePair>/iteration 7144182 6009899 1.19 *<br>deque<ValuePair>/operator[] 34241222 20535039 1.67 *<br>deque<ValuePair>/push_back 6585800 3932126 1.67 *<br>deque<ValuePair>/push_front 6805865 3993513 1.70 *<br>deque<ValuePair>/sort 395352323 348778188 1.13 *<br><br>hash_map<string, uint32_t>/clear 426640 447015 0.95<br>hash_map<string, uint32_t>/count 4359344 3883089 1.12 *<br>hash_map<string, uint32_t>/erase pos 584392 458142 1.28 *<br>hash_map<string, uint32_t>/erase range 221034 196078 1.13 *<br>hash_map<string, uint32_t>/erase val 3539867 3790813 0.93<br>hash_map<string, uint32_t>/find 3966831 3811910 1.04<br>hash_map<string, uint32_t>/find_as/char* 11591612 4243710 2.73 *<br>hash_map<string, uint32_t>/insert 16763887 16719194 1.00<br>hash_map<string, uint32_t>/iteration 909968 478609 1.90 *<br>hash_map<string, uint32_t>/operator[] 4360041 4108313 1.06<br><br>hash_map<uint32_t, TestObject>/clear 302634 283722 1.07<br>hash_map<uint32_t, TestObject>/count 916487 907426 1.01<br>hash_map<uint32_t, TestObject>/erase pos 388042 321385 1.21 *<br>hash_map<uint32_t, TestObject>/erase range 122680 116280 1.06<br>hash_map<uint32_t, TestObject>/erase val 1710931 1729529 0.99<br>hash_map<uint32_t, TestObject>/find 1089462 1346527 0.81 *<br>hash_map<uint32_t, TestObject>/insert 4560310 5072350 0.90 *<br>hash_map<uint32_t, TestObject>/iteration 960117 495354 1.94 *<br>hash_map<uint32_t, TestObject>/operator[] 1872830 1890595 0.99<br><br>heap (uint32_t[])/make_heap 3528418 3327257 1.06<br>heap (uint32_t[])/pop_heap 63243859 61011853 1.04<br>heap (uint32_t[])/push_heap 11602424 10045869 1.15 *<br>heap (uint32_t[])/sort_heap 52965362 48744729 1.09<br><br>heap (vector<TestObject>)/make_heap 13191456 13089711 1.01<br>heap (vector<TestObject>)/pop_heap 148555656 144787742 1.03<br>heap (vector<TestObject>)/push_heap 28696689 26618830 1.08<br>heap (vector<TestObject>)/sort_heap 112473989 114018643 0.99<br><br>list<TestObject>/ctor(it) 80186731 74006287 1.08<br>list<TestObject>/ctor(n) 6232311 6128007 1.02<br>list<TestObject>/erase 344556374 212877808 1.62 *<br>list<TestObject>/find 39859075 14591347 2.73 *<br>list<TestObject>/insert 86935153 56138233 1.55 *<br>list<TestObject>/push_back 79569180 46700641 1.70 *<br>list<TestObject>/remove 785786758 324201016 2.42 *<br>list<TestObject>/reverse 45248186 24852759 1.82 *<br>list<TestObject>/size/1 219844 219496 1.00<br>list<TestObject>/size/10 519563 519579 1.00 EASTL intentionally implements list::size as O(n).<br>list<TestObject>/size/100 4567194 101230266 0.05 * EASTL intentionally implements list::size as O(n).<br>list<TestObject>/splice 68321087 23601687 2.89 *<br><br>map<TestObject, uint32_t>/clear 168011 180540 0.93<br>map<TestObject, uint32_t>/count 4830439 5139287 0.94<br>map<TestObject, uint32_t>/equal_range 8700090 6158531 1.41 *<br>map<TestObject, uint32_t>/erase/key 6696776 4617038 1.45 *<br>map<TestObject, uint32_t>/erase/pos 309273 333183 0.93<br>map<TestObject, uint32_t>/erase/range 137419 136068 1.01<br>map<TestObject, uint32_t>/find 4773498 4931352 0.97<br>map<TestObject, uint32_t>/insert 9651877 9311699 1.04<br>map<TestObject, uint32_t>/iteration 372946 416364 0.90 *<br>map<TestObject, uint32_t>/lower_bound 4784234 4915797 0.97<br>map<TestObject, uint32_t>/operator[] 5040254 5183147 0.97<br>map<TestObject, uint32_t>/upper_bound 4724292 4915984 0.96<br><br>set<uint32_t>/clear 165300 173289 0.95<br>set<uint32_t>/count 4958654 4885086 1.02<br>set<uint32_t>/equal_range 8434134 5698681 1.48 *<br>set<uint32_t>/erase range 145554 133960 1.09<br>set<uint32_t>/erase/pos 299914 324760 0.92<br>set<uint32_t>/erase/val 6506155 4335034 1.50 *<br>set<uint32_t>/find 4866879 4556043 1.07<br>set<uint32_t>/insert 8340523 8957257 0.93<br>set<uint32_t>/iteration 294465 343442 0.86 *<br>set<uint32_t>/lower_bound 4548095 4756498 0.96<br>set<uint32_t>/upper_bound 4559196 4521498 1.01<br><br>sort/q_sort/TestObject[] 7316766 7013894 1.04<br>sort/q_sort/TestObject[]/sorted 1668439 1332885 1.25 *<br>sort/q_sort/vector<TestObject> 7331530 7017260 1.04<br>sort/q_sort/vector<TestObject>/sorted 1601629 1247120 1.28 *<br>sort/q_sort/vector<ValuePair> 7071643 7067869 1.00<br>sort/q_sort/vector<ValuePair>/sorted 2136390 1703799 1.25 *<br>sort/q_sort/vector<uint32> 3292891 2943627 1.12 *<br>sort/q_sort/vector<uint32>/sorted 653693 473612 1.38 *<br><br>string<char16_t>/compare 356579259 432760228 0.82 *<br>string<char16_t>/erase/pos,n 3430422 3428645 1.00<br>string<char16_t>/find/p,pos,n 229263402 225830975 1.02<br>string<char16_t>/find_first_not_of/p,pos,n 187391 81404 2.30 *<br>string<char16_t>/find_first_of/p,pos,n 4411831 4413532 1.00<br>string<char16_t>/find_last_of/p,pos,n 731655 726155 1.01<br>string<char16_t>/insert/pos,p 3408628 3319726 1.03<br>string<char16_t>/iteration 309993861 310333547 1.00<br>string<char16_t>/operator[] 580839 579904 1.00<br>string<char16_t>/push_back 3983338 2975553 1.34 *<br>string<char16_t>/replace/pos,n,p,n 4361095 4211504 1.04<br>string<char16_t>/reserve 935141729 247010 100.00 *<br>string<char16_t>/rfind/p,pos,n 248956 223397 1.11 *<br>string<char16_t>/size 13311 13107 1.02<br>string<char16_t>/swap 519129 579445 0.90 *<br><br>string<char8_t>/compare 76695559 76828015 1.00<br>string<char8_t>/erase/pos,n 1951566 1947282 1.00<br>string<char8_t>/find/p,pos,n 185878944 185605039 1.00<br>string<char8_t>/find_first_not_of/p,pos,n 196877 81600 2.41 *<br>string<char8_t>/find_first_of/p,pos,n 4147685 4145356 1.00<br>string<char8_t>/find_last_of/p,pos,n 605897 598222 1.01<br>string<char8_t>/insert/pos,p 1781592 1768264 1.01<br>string<char8_t>/iteration 921502 921272 1.00<br>string<char8_t>/operator[] 361250 359873 1.00<br>string<char8_t>/push_back 3363288 2530493 1.33 *<br>string<char8_t>/replace/pos,n,p,n 2682600 2633130 1.02<br>string<char8_t>/reserve 672517501 78387 100.00 *<br>string<char8_t>/rfind/p,pos,n 226202 200013 1.13 *<br>string<char8_t>/size 11280 11109 1.02<br>string<char8_t>/swap 519393 559759 0.93<br><br>vector<uint64>/erase 55184856 55192217 1.00<br>vector<uint64>/insert 56764267 55682726 1.02<br>vector<uint64>/iteration 423122 424039 1.00<br>vector<uint64>/operator[] 1189397 860991 1.38 *<br>vector<uint64>/push_back 5626609 4027317 1.40 *<br>vector<uint64>/sort 49227036 49231362 1.00<br></pre> + + + + + +</div> + + + + + +<h2> + + + + + + + + +<br> + + + +<hr style="width: 100%; height: 2px;"> +End of document<br> + + + +<br> + + + +<br> + + + +<br> + + + +<br> + + + +</body> +</html> diff --git a/EASTL/doc/html/EASTL Best Practices.html b/EASTL/doc/html/EASTL Best Practices.html new file mode 100644 index 0000000..bc0792e --- /dev/null +++ b/EASTL/doc/html/EASTL Best Practices.html @@ -0,0 +1,1001 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> + <title>EASTL Best Practices</title> + <meta content="text/html; charset=us-ascii" http-equiv="content-type"> + <meta name="author" content="Paul Pedriana"> + <meta name="description" content="Best practices for EASTL usage"> + <link type="text/css" rel="stylesheet" href="EASTLDoc.css"> + <style type="text/css"> +<!-- +.style1 {font-size: 12pt} +--> + </style> +</head> +<body> +<h1>EASTL Best Practices</h1> +<p>In this document we discuss best practices for using EASTL. The primary emphasis is on performance with a secondary + emphasis on correctness and maintainability. Some best practices apply only to some situations, and these will be + pointed out as we go along. In order to be easily digestible, we present these practices as a list of items in the tone + of the Effective C++ series of books.</p> +<h2>Summary</h2> +<p>The descriptions here are intentionally terse; this is to make them easier to visually scan.</p> +<table style="text-align: left; width: 100%;" border="0" cellpadding="1" cellspacing="1"> +<tbody> +<tr> +<td style="width: 28px;">1</td> +<td><a href="#Best.1">Consider intrusive containers.</a></td> +</tr> +<tr> +<td>2</td> +<td><a href="#Best.2">Consider fixed-size containers.</a></td> +</tr> +<tr> +<td>3</td> +<td><a href="#Best.3">Consider custom allocators.</a></td> +</tr> +<tr> +<td>4</td> +<td><a href="#Best.4">Consider hash tables instead of maps.</a></td> +</tr> +<tr> +<td>5</td> +<td><a href="#Best.5">Consider a vector_map (a.k.a. sorted vector) for unchanging data.</a></td> +</tr> +<tr> +<td>6</td> +<td><a href="#Best.6">Consider slist instead of list.</a></td> +</tr> +<tr> +<td>7</td> +<td><a href="#Best.7">Avoid redundant end() and size() in loops.</a></td> +</tr> +<tr> +<td>8</td> +<td><a href="#Best.8">Iterate containers instead of using operator[].</a></td> +</tr> +<tr> +<td>9</td> +<td><a href="#Best.9">Learn to use the string class appropriately.</a></td> +</tr> +<tr> +<td>10</td> +<td><a href="#Best.10">Cache list size if you want size() to be O(1).</a></td> +</tr> +<tr> +<td>11</td> +<td><a href="#Best.11">Use empty() instead of size() when possible.</a></td> +</tr> +<tr> +<td>12</td> +<td><a href="#Best.12">Know your container efficiencies.</a></td> +</tr> +<tr> +<td>13</td> +<td><a href="#Best.13">Use vector::reserve.</a></td> +</tr> +<tr> +<td>14</td> +<td><a href="#Best.14">Use vector::set_capacity to trim memory usage.</a></td> +</tr> +<tr> +<td>15</td> +<td><a href="#Best.15">Use swap() instead of a manually implemented version.</a></td> +</tr> +<tr> +<td>16</td> +<td><a href="#Best.16">Consider storing pointers instead of objects.</a></td> +</tr> +<tr> +<td>17</td> +<td><a href="#Best.17">Consider smart pointers instead of raw pointers.</a></td> +</tr> +<tr> +<td>18</td> +<td><a href="#Best.18">Use iterator pre-increment instead of post-increment.</a></td> +</tr> +<tr> +<td>19</td> +<td><a href="#Best.19">Make temporary references so the code can be traced/debugged.</a></td> +</tr> +<tr> +<td>20</td> +<td><a href="#Best.20">Consider bitvector or bitset instead of vector<bool>.</a></td> +</tr> +<tr> +<td>21</td> +<td><a href="#Best.21">Vectors can be treated as contiguous memory.</a></td> +</tr> +<tr> +<td>22</td> +<td><a href="#Best.22">Search hash_map<string> via find_as() instead of find().</a></td> +</tr> +<tr> +<td>23</td> +<td><a href="#Best.23">Take advantage of type_traits (e.g. <small style= +"font-family: Courier New;">EASTL_DECLARE_TRIVIAL_RELOCATE</small>).</a></td> +</tr> +<tr> +<td>24</td> +<td><a href="#Best.24">Name containers to track memory usage.</a></td> +</tr> +<tr> +<td>25</td> +<td><a href="#Best.25">Learn the algorithms.</a></td> +</tr> +<tr> +<td>26</td> +<td><a href="#Best.26">Pass and return containers by reference instead of value.</a></td> +</tr> +<tr> +<td>27</td> +<td><a href="#Best.27">Consider using reset_lose_memory() for fast container teardown.</a></td> +</tr> +<tr> +<td>28</td> +<td><a href="#Best.28">Consider using fixed_substring instead of copying strings.</a></td> +</tr> +<tr> + <td>29</td> + <td><a href="#Best.29">Consider using vector::push_back(void).</a></td> +</tr> +</tbody> +</table> +<h2>Detail</h2> +<p class="faq-question"><a name="Best.1"></a>1 + Consider intrusive containers. +</p> +<p class="faq-answer">Intrusive containers (such as intrusive_list) differ from regular containers (such as list) in that they use the stored objects to manage the linked list instead of using nodes allocated from a memory heap. The result is better usage of memory. Additionally intrusive_list objects can be removed from their list without knowing what list they belong to. To make an intrusive_list of Widgets, you have Widget inherit from intrusive_list_node or simply have mpPrev/mpNext member variables.</p> +<p class="faq-answer">To create an intrusive_list container, you can use the following code:</p> +<p class="code-example">class Widget : public intrusive_list_node<br> +{ };<br> +<br> +intrusive_list<Widget> widgetList;<br> +widgetList.push_back(someWidget);</p> +<p></p> +<p class="faq-question"><a name="Best.2"></a>2 + Consider fixed-size containers. +</p> +<p class="faq-answer">Fixed-size containers (such as fixed_list) are variations of regular containers (such as list) in that they allocate from a fixed block of local memory instead of allocating from a generic heap. The result is better usage of memory due to reduced fragmentation, better cache behavior, and faster allocation/deallocation. The presence of fixed-size containers negate the most common complaint that people have about STL: that it fragments the heap or "allocates all over the place."</p> +<p class="faq-answer">EASTL fixed containers include:</p> +<ul> + <li>fixed_list</li> + <li>fixed_slist</li> + <li>fixed_vector</li> + <li>fixed_string</li> + <li>fixed_map</li> + <li>fixed_multimap</li> + <li>fixed_set</li> + <li>fixed_multiset</li> + <li>fixed_hash_map</li> + <li>fixed_hash_multimap</li> + <li>fixed_hash_set</li> + <li>fixed_hash_multiset</li> +</ul> +<p class="faq-answer">To create a fixed_set, you can use the following code:</p> +<p class="code-example">fixed_set<int, 25> intSet; // Create a set capable of holding 25 elements.<br> +intSet.push_back(37);</p> +<p></p> +<p class="faq-question"><a name="Best.3"></a>3 + Consider custom allocators. +</p> +<p class="faq-answer">While EASTL provides fixed-size containers in order to control container memory usage, EASTL lets you assign a custom allocator to any container. This lets you define your own memory pool. EASTL has a more flexible and powerful mechanism of doing this that standard STL, as EASTL understands object alignment requirements, allows for debug naming, allows for sharing allocators across containers, and allows dynamic allocator assignment.</p> +<p class="faq-answer">To create a list container that uses your custom allocator and uses block naming, you can use the following code:</p> +<p class="code-example">list<int> intList(pSomeAllocator, "graphics/intList");<br> +intList.push_back(37);</p> +<p class="faq-question"><a name="Best.4"></a>4 +Consider hash tables instead of maps.</p> +<p class="faq-answer">Hash containers (such as hash_map) provide the same interface as associative containers (such as map) but have faster lookup and use less memory. The primary disadvantage relative to associative containers is that hash containers are not sorted.</p> +<p class="faq-answer">To make a hash_map (dictionary) of integers to strings, you can use the following code:</p> +<p class="code-example">hash_map<int, const char*> stringTable;<br> +stringTable[37] = "hello";</p> +<p class="faq-question"><a name="Best.5"></a>5 + Consider a vector_map (a.k.a. sorted vector) for unchanging data. +</p> +<p class="faq-answer">You can improve speed, memory usage, and cache behavior by using a vector_map instead of a map (or vector_set instead of set, etc.). The primary disadvantage of vector_map is that insertions and removal of elements is O(n) instead of O(1). However, if your associative container is not going to be changing much or at all, you can benefit from using a vector_map. Consider calling reserve on the vector_map in order to set the desired capacity up front.</p> +<p class="faq-answer">To make a vector_set, you can use the following code:</p> +<p class="code-example">vector_set<int> intSet(16); // Create a vector_set with an initial capacity of 16.<br> +intSet.insert(37);</p> +<p class="faq-answer">Note that you can use containers other than vector to implement vector_set. Here's how you do it with deque:</p> +<p class="code-example">vector_set<int, less<int>, EASTLAllocatorType, deque<int> > intSet;<br> +intSet.insert(37);</p> +<p class="faq-question"><a name="Best.6"></a>6 + Consider slist instead of list. +</p> +<p class="faq-answer">An slist is a singly-linked list; it is much like a list except that it can only be traversed in a forward direction and not a backward direction. The benefit is that each node is 4 bytes instead of 8 bytes. This is a small improvement, but if you don't need reverse iteration then it can be an improvement. There's also intrusive_slist as an option.</p> +<p class="faq-answer">To make an slist, you can use the following code:</p> +<p class="code-example">slist<int> intSlist;<br> +intSlist.push_front(37);</p> +<p class="faq-question"><a name="Best.7"></a>7 +Avoid redundant end() and size() in loops.</p> +<p class="faq-answer">Instead of writing code like this:<br> +</p> +<div class="code-example" style="margin-left: 40px; font-family: Courier New;"><small>for(deque<int>::iterator it = d.begin(); <span style="color: rgb(204, 0, 0);">it != d.end()</span>; ++it)<br> + ...</small></div> +<span class="faq-answer">write code like this:<br> +</span> +<div class="code-example" style="margin-left: 40px; font-family: Courier New;"><small>for(deque<int>::iterator it = d.begin(), itEnd = d.end(); <span style="color: rgb(51, 204, 0);">it != itEnd</span>; ++it)<br> + ...</small></div> +<span class="faq-answer">The latter avoids a function call and return of an object (which in deque's case happens to be more than just a pointer). The above only works when the container is unchanged or for containers that have a constant end value. By "constant end value" we mean containers which can be modified but end always remains the same.</span><br> +<table style="text-align: left; width: 600px; margin-left: 40px;" border="1" cellpadding="2" cellspacing="2"> + <tbody> + <tr> + <td style="text-align: center;">Constant begin</td> + <td style="text-align: center;">Non-constant begin</td> + <td style="text-align: center;">Constant end</td> + <td style="text-align: center;">Non-constant end</td> + </tr> + <tr> + <td style="vertical-align: top;">array<sup>1</sup></td> + <td style="vertical-align: top;">string<br> + vector<br> + deque<br> + intrusive_list<br> + intrusive_slist<br> + vector_map<br> + vector_multimap<br> + vector_set<br> + vector_multiset<br> + bit_vector<br> + hash_map<br> + hash_multimap<br> + hash_set<br> + hash_multiset<br> + intrusive_hash_map<br> + intrusive_hash_multimap<br> + intrusive_hash_set<br> + intrusive_hash_multiset</td> + <td style="vertical-align: top;">array<br> + list<br> + slist<br> + intrusive_list<br> + intrusive_slist<br> + map<br> + multimap<br> + set<br> + multiset<br> + hash_map<sup>2</sup><br> + hash_multimap<sup>2</sup><br> + hash_set<sup>2</sup><br> + hash_multiset<sup>2</sup><br> + intrusive_hash_map<br> + intrusive_hash_multimap<br> + intrusive_hash_set<br> + intrusive_hash_multiset</td> + <td style="vertical-align: top;">string<br> + vector<br> + deque<br> + vector_map<br> + vector_multimap<br> + vector_set<br> + vector_multiset<br> + bit_vector<br></td> + </tr> + </tbody> +</table> +<div style="margin-left: 40px;"><sup>1</sup> Arrays can be neither resized nor reallocated.<br> + <sup>2</sup> Constant end if the hashtable can't/won't re-hash. Non-constant if it can re-hash.</div> +<p class="faq-question"> <a name="Best.8"></a>8 +Iterate containers instead of using operator[]. +</p> +<p class="faq-answer">It's faster to iterate random access containers via iterators than via operator[], though operator[] usage may look simpler.</p> +<p class="faq-answer">Instead of doing this:</p> +<p class="code-example">for(unsigned i = 0, iEnd = intVector.size(); i != iEnd; ++i)<br> + intVector[i] = 37;</p> +<p class="faq-answer">you can execute more efficiently by doing this:</p> +<p class="code-example">for(vector<int>::iterator it = intVector.begin(), itEnd = intVector.end(); it != itEnd; ++it)<br> + *it = 37;</p> +<p class="faq-question"> <a name="Best.9"></a>9 +Learn to use the string class appropriately.</p> +<p class="faq-answer">Oddly enough, the most mis-used STL container is easily the string class. The tales of string abuse could rival the 1001 Arabian Nights. Most of the abuses involve doing things in a harder way than need be. In examining the historical mis-uses of string, it is clear that many of the problems stem from the user thinking in terms of C-style string operations instead of object-oriented strings. This explains why statements such as <small><span style="font-family: Courier New;">strlen(s.c_str())</span></small> are so common, whereas the user could just use <small><span style="font-family: Courier New;">s.length()</span></small> instead and be both clearer and more efficient.<br> +<br> +Here we provide a table of actual collected examples of things done and how they could have been done instead.</p> +<table style="text-align: left; width: 90%; margin-left: 40px;" border="1" cellpadding="2" cellspacing="2"> + <tbody> + <tr> + <td style="font-weight: bold;">What was written</td> + <td style="font-weight: bold;">What could have been written</td> + </tr> + <tr> + <td class="style1" style="font-family: Courier New;"><small><br> + s = s.Left(i) + '+' + s.Right(s.length() - i - 1);<br> + <br> + </small></td> + <td class="style1" style="font-family: Courier New;"><small>s[i] = '+';</small></td> + </tr> + <tr> + <td class="style1" style="font-family: Courier New;"><small><br> + string s(""); // This is the most commonly found misuse.<br> + <br> + </small></td> + <td class="style1" style="font-family: Courier New;"><small>string s;</small></td> + </tr> + <tr> + <td class="style1" style="font-family: Courier New;"><small><br> + s = "";<br> + <br> + </small></td> + <td class="style1" style="font-family: Courier New;"><small>s.clear();</small></td> + </tr> + <tr> + <td class="style1" style="font-family: Courier New;"><small><br> + s.c_str()[0] = 'u';<br> + <br> + </small></td> + <td class="style1" style="font-family: Courier New;"><small>s[0] = 'u';</small></td> + </tr> + <tr> + <td class="style1" style="font-family: Courier New;"><small><br> + len = strlen(s.c_str());<br> + <br> + </small></td> + <td class="style1" style="font-family: Courier New;"><small>len = s.length();</small></td> + </tr> + <tr> + <td class="style1" style="font-family: Courier New;"><small><br> + s = string("u");<br> + </small></td> + <td class="style1" style="font-family: Courier New;"><small>s = "u";</small></td> + </tr> + <tr> + <td class="style1" style="font-family: Courier New;"><small><br> + puts(s + string("u"));<br> + <br> + </small></td> + <td class="style1" style="font-family: Courier New;"><small>puts(s + "u");</small></td> + </tr> + <tr> + <td class="style1" style="font-family: Courier New;"><small><br> + string s(" ");<br> + puts(s.c_str());<br> + <br> + </small></td> + <td class="style1" style="font-family: Courier New;"><small>puts(" ");</small></td> + </tr> + <tr> + <td class="style1" style="font-family: Courier New;"><small><br> + s.sprintf("u");<br> + <br> + </small></td> + <td class="style1" style="font-family: Courier New;"><small>s = "u";</small></td> + </tr> + <tr> + <td class="style1" style="font-family: Courier New;"><small><br> + char array[32];<br> + sprintf(array, "%d", 10);<br> + s = string(array);<br> + <br> + </small></td> + <td class="style1" style="font-family: Courier New;"><small>s.sprintf("%d", 10);</small></td> + </tr> + </tbody> +</table> +<p class="faq-answer"><br> +The chances are that if you want to do something with a string, there is a very basic way to do it. You don't want your code to appear in a future version of the above table.</p> +<p class="faq-question"> <a name="Best.10"></a>10 +Cache list size if you want list::size() to be O(1).</p> +<p class="faq-answer">EASTL's list, slist, intrusive_list, and intrusive_slist containers have a size() implementation which is O(n). That is, these containers don't keep a count (cache) of the current list size and when you call the size() function they iterate the list. This is by design and the reasoning behind it has been deeply debated and considered (and is discussed in the FAQ and the list header file). In summary, list doesn't cache its size because the only function that would benefit is the size function while many others would be negatively impacted and the memory footprint would be negatively impacted, yet list::size is not a very frequently called function in well-designed code. At the same time, nothing prevents the user from caching the size himself, though admittedly it adds some tedium and risk to the code writing process.<br> + <br> +Here's an example of caching the list size manually:<br> +</p> +<div class="code-example" style="margin-left: 40px;"><small><span style="font-family: Courier New;">list<int> intList;<br> + size_t n = 0;<br> + <br> + intList.push_back(37);<br> + ++n;<br> + intList.pop_front();<br> + --n;</span></small></div> +<p class="faq-question"> <a name="Best.11"></a>11 +Use empty() instead of size() when possible. +</p> +<p class="faq-answer">All conventional containers have both an empty function and a size function. For all containers empty() executes with O(1) (constant time) efficiency. However, this is not so for size(), as some containers need to calculate the size and others need to do pointer subtraction (which may involve integer division) to find the size.</p> +<p class="faq-question"><a name="Best.12"></a>12 +Know your container efficiencies.</p> +<p class="faq-answer">The above two practices lead us to this practice, which is a generalization of the above. + We present a table of basic information for the conventional EASTL containers. The values are described at the + bottom.</p> +<table style="width: 90%; margin-left: 40px;" border="1" cellpadding="1" cellspacing="1"> + <tbody> + <tr> + <td style="width: 15%; vertical-align: top; height: 13px; font-weight: bold;"><p>Container</p></td> + <td style="text-align: center;">empty() efficiency</td> + <td style="text-align: center; font-weight: bold;">size() efficiency</td> + <td style="text-align: center; font-weight: bold;">operator[] efficiency</td> + <td style="font-weight: bold; text-align: center;" height="13" valign="top" width="16%"><p>insert() efficiency</p></td> + <td style="font-weight: bold; text-align: center;" height="13" valign="top" width="16%"><p>erase() efficiency</p></td> + <td style="font-weight: bold; text-align: center;" height="13" valign="top" width="7%"><p>find() efficiency</p></td> + <td style="font-weight: bold; text-align: center;" height="13" valign="top" width="10%"><p>sort efficiency</p></td> + </tr> + <tr> + <td>slist</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">O(n)</td> + <td style="text-align: center;">-</td> + <td style="text-align: center;">O(1)</td> + <td style="text-align: center;">O(1)</td> + <td style="text-align: center;">O(n)</td> + <td style="text-align: center;">O(n+)</td> + </tr> + <tr> + <td height="13" valign="top" width="15%"><p>list</p></td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">n</td> + <td style="text-align: center;">-</td> + <td style="text-align: center;" height="13" valign="top" width="16%"><p>1</p></td> + <td style="text-align: center;" height="13" valign="top" width="16%"><p>1</p></td> + <td style="text-align: center;" height="13" valign="top" width="7%"><p>n</p></td> + <td style="text-align: center;" height="13" valign="top" width="10%"><p>n log(n)</p></td> + </tr> + <tr> + <td>intrusive_slist</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">n</td> + <td style="text-align: center;">-</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">n+</td> + </tr> + <tr> + <td>intrusive_list</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">n</td> + <td style="text-align: center;">-</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">n log(n)</td> + </tr> + <tr> + <td>array</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">-</td> + <td style="text-align: center;">-</td> + <td style="text-align: center;">n</td> + <td style="text-align: center;">n log(n)</td> + </tr> + <tr> + <td>vector</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">1<sup>a</sup></td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">1 at end, else n</td> + <td style="text-align: center;">1 at end, else n</td> + <td style="text-align: center;">n</td> + <td style="text-align: center;">n log(n)</td> + </tr> + <tr> + <td>vector_set</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">1<sup>a</sup></td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">1 at end, else n</td> + <td style="text-align: center;">1 at end, else n</td> + <td style="text-align: center;">log(n)</td> + <td style="text-align: center;">1</td> + </tr> + <tr> + <td>vector_multiset</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">1<sup>a</sup></td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">1 at end, else n</td> + <td style="text-align: center;">1 at end, else n</td> + <td style="text-align: center;">log(n)</td> + <td style="text-align: center;">1</td> + </tr> + <tr> + <td>vector_map</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">1<sup>a</sup></td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">1 at end, else n</td> + <td style="text-align: center;">1 at end, else n</td> + <td style="text-align: center;">log(n)</td> + <td style="text-align: center;">1</td> + </tr> + <tr> + <td>vector_multimap</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">1<sup>a</sup></td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">1 at end, else n</td> + <td style="text-align: center;">1 at end, else n</td> + <td style="text-align: center;">log(n)</td> + <td style="text-align: center;">1</td> + </tr> + <tr> + <td>deque</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">1<sup>a</sup></td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">1 at begin or end,<br> + else n / 2</td> + <td style="text-align: center;">1 at begin or end,<br> + else n / 2</td> + <td style="text-align: center;">n</td> + <td style="text-align: center;">n log(n)</td> + </tr> + <tr> + <td>bit_vector</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">1<sup>a</sup></td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">1 at end, else n</td> + <td style="text-align: center;">1 at end, else n</td> + <td style="text-align: center;">n</td> + <td style="text-align: center;">n log(n)</td> + </tr> + <tr> + <td>string, cow_string</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">1<sup>a</sup></td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">1 at end, else n</td> + <td style="text-align: center;">1 at end, else n</td> + <td style="text-align: center;">n</td> + <td style="text-align: center;">n log(n)</td> + </tr> + <tr> + <td>set</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">-</td> + <td style="text-align: center;">log(n)</td> + <td style="text-align: center;">log(n)</td> + <td style="text-align: center;">log(n)</td> + <td style="text-align: center;">1</td> + </tr> + <tr> + <td>multiset</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">-</td> + <td style="text-align: center;">log(n)</td> + <td style="text-align: center;">log(n)</td> + <td style="text-align: center;">log(n)</td> + <td style="text-align: center;">1</td> + </tr> + <tr> + <td>map</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">log(n)</td> + <td style="text-align: center;">log(n)</td> + <td style="text-align: center;">log(n)</td> + <td style="text-align: center;">log(n)</td> + <td style="text-align: center;">1</td> + </tr> + <tr> + <td>multimap</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">-</td> + <td style="text-align: center;">log(n)</td> + <td style="text-align: center;">log(n)</td> + <td style="text-align: center;">log(n)</td> + <td style="text-align: center;">1</td> + </tr> + <tr> + <td>hash_set</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">-</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">-</td> + </tr> + <tr> + <td>hash_multiset</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">-</td> + <td style="text-align: center;">1<br></td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">-</td> + </tr> + <tr> + <td>hash_map</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">-</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">-</td> + </tr> + <tr> + <td>hash_multimap</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">-</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">-</td> + </tr> + <tr> + <td>intrusive_hash_set</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">-</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">-</td> + </tr> + <tr> + <td>intrusive_hash_multiset</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">-</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">-</td> + </tr> + <tr> + <td>intrusive_hash_map</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">-</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">-</td> + </tr> + <tr> + <td>intrusive_hash_multimap</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">-</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">1</td> + <td style="text-align: center;">-</td> + </tr> + </tbody> +</table> +<p class="faq-answer"><br> + Notes: +</p> +<ul> + <li>- means that the operation does not exist.</li> + <li>1 means amortized constant time. Also known as O(1)</li> + <li>n means time proportional to the container size. Also known as O(n)</li> + <li>log(n) means time proportional to the natural logarithm of the container size. Also known as O(log(n))</li> + <li>n log(n) means time proportional to log(n) times the size of the container. Also known as O(n log(n))</li> + <li>n+ means that the time is at least n, and possibly higher.</li> + <li>Inserting at the end of a vector may cause the vector to be resized; resizing a vector is O(n). However, the amortized time complexity for vector insertions at the end is constant.</li> + <li>Sort assumes the usage of the best possible sort for a large container of random data. Some sort algorithms (e.g. quick_sort) require random access iterators and so the sorting of some containers requires a different sort algorithm. We do not include bucket or radix sorts, as they are always O(n).</li> + <li><sup>a</sup> vector, deque, string size is O(1) but involves pointer subtraction and thus integer division and so is not as efficient as containers that store the size directly.</li> +</ul> +<p class="faq-question"><a name="Best.13"></a>13 +Use vector::reserve.</p> +<p class="faq-answer">You can prevent vectors (and strings) from reallocating as you add items by specifying up front how many items you will be requiring. You can do this in the constructor or by calling the reserve function at any time. The capacity function returns the amount of space which is currently reserved.<br> + <br> +Here's how you could specify reserved capacity in a vector:<br> +</p> +<div class="code-example" style="margin-left: 40px; font-family: Courier New;"><small>vector<Widget> v(37); // Reserve space to hold up to 37 items.<br> + or<br> +vector<Widget> v; // This empty construction causes to memory to be allocated or reserved.<br> + v.reserve(37);<br> +</small></div> +<span class="faq-answer">The EASTL vector (and string) implementation looks like this:</span> +<span class="code-example"><small>template <typename T><br> + class vector {<br> + T* mpBegin; // Beginning of used element memory.<br> + T* mpEnd; // End of used element memory.<br> + T* mpCapacity; // End of storage capacity. Is >= mpEnd<br> + </small> <small>}</small></span><small> </small><span class="faq-answer"> +Another approach to being efficient with vector memory usage is to use fixed_vector.</span> + <p class="faq-question"><a name="Best.14"></a>14 +Use vector::set_capacity to trim memory usage.</p> +<p class="faq-answer">A commonly asked question about vectors and strings is, "How do I reduce the capacity of a vector?" The conventional solution for std STL is to use the somewhat non-obvious trick of using <small><span style= +"font-family: Courier New;">vector<Widget>(v).swap(v)</span></small>. EASTL provides the same functionality via a member function called set_capacity() which is present in both the vector and string classes. <br> + <br> +An example of reducing a vector is the following:</p> +<span class="code-example"><small>vector<Widget> v;<br> +...<br> +</small> <small>v.set_capacity();</small></span><small> </small><span class="faq-answer"> +An example of resizing to zero and completely freeing the memory of a vector is the following:<br> +</span> +<div class="code-example" style="margin-left: 40px; font-family: Courier New;"><small>vector<Widget> v;<br> + ...<br> + </small> <small>v.set_capacity(0);</small></div> +<p class="faq-question"><a name="Best.15"></a>15 Use swap() instead of a manually implemented version.</p> +<p class="faq-answer">The generic swap algorithm provides a basic version for any kind of object. However, each EASTL container provides a specialization of swap which is optimized for that container. For example, the list container implements swap by simply swapping the internal member pointers and not by moving individual elements.</p> +<p class="faq-question"> <a name="Best.16"></a>16 +Consider storing pointers instead of objects.</p> +<p class="faq-answer">There are times when storing pointers to objects is more efficient or useful than storing objects directly in containers. It can be more efficient to store pointers when the objects are big and the container may need to construct, copy, and destruct objects during sorting or resizing. Moving pointers is usually faster than moving objects. It can be useful to store pointers instead of objects when somebody else owns the objects or the objects are in another container. It might be useful for a Widget to be in a list and in a hash table at the same time.</p> +<p class="faq-question"><a name="Best.17"></a>17 + Consider smart pointers instead of raw pointers. +</p> +<p class="faq-answer">If you take the above recommendation and store objects as pointers instead of as objects, you may want to consider storing them as smart pointers instead of as regular pointers. This is particularly useful for when you want to delete the object when it is removed from the container. Smart pointers will automatically delete the pointed-to object when the smart pointer is destroyed. Otherwise, you will have to be careful about how you work with the list so that you don't generate memory leaks. Smart pointers implement a shared reference count on the stored pointer, as so any operation you do on a smart pointer container will do the right thing. Any pointer can be stored in a smart pointer, and custom new/delete mechanisms can work with smart pointers. The primary smart pointer is shared_ptr.</p> +<p class="faq-answer">Here is an example of creating and using a shared_ptr:</p> +<p class="code-example">typedef shared_ptr<Widget> WPtr;<br> + list<WPtr> wList;<br> + <br> + wList.push_back(WPtr(new Widget)); // The user may have operator new/delete overrides.<br> +wList.pop_back(); // Implicitly deletes the Widget.</p> +<p class="faq-answer">Here is an example of creating and using a shared_ptr that uses a custom allocation and deallocation mechanism:</p> +<p class="code-example">typedef shared_ptr<Widget, EASTLAllocatorType, WidgetDelete> WPtr; // WidgetDelete is a custom destroyer.<br> + list<WPtr> wList;<br> + <br> + wList.push_back(WPtr(WidgetCreate(Widget))); // WidgetCreate is a custom allocator.<br> +wList.pop_back(); // Implicitly calls WidgetDelete.</p> +<p class="faq-question"><a name="Best.18"></a>18 + Use iterator pre-increment instead of post-increment. +</p> +<p class="faq-answer">Pre-increment (e.g. ++x) of iterators is better than post-increment (x++) when the latter is not specifically needed. It is common to find code that uses post-incrementing when it could instead use pre-incrementing; presumably this is due to post-increment looking a little better visually. The problem is that the latter constructs a temporary object before doing the increment. With built-in types such as pointers and integers, the compiler will recognize that the object is a trivial built-in type and that the temporary is not needed, but the compiler cannot do this for other types, even if the compiler sees that the temporary is not used; this is because the constructor may have important side effects and the compiler would be broken if it didn't construct the temporary object.</p> +<p class="faq-answer">EASTL iterators are usually not trivial types and so it's best not to hope the compiler will do the best thing. Thus you should always play it safe an use pre-increment of iterators whenever post-increment is not required.</p> +<p class="faq-answer">Here is an example of using iterator pre-increment; for loops like this should always use pre-increment:</p> +<p class="code-example">for(set<int>::iterator it(intSet.begin()), itEnd(intSet.end()); it != itEnd; ++it)<br> + *it = 37;</p> +<p class="faq-question"> <a name="Best.19"></a>19 + Make temporary references so the code can be traced/debugged. +</p> +<p class="faq-answer">Users want to be able to inspect or modify variables which are referenced by iterators. While EASTL containers and iterators are designed to make this easier than other STL implementations, it makes things very easy if the code explicitly declares a reference to the iterated element. In addition to making the variable easier to debug, it also makes code easier to read and makes the debug (and possibly release) version of the application run more efficiently.</p> +<p class="faq-answer">Instead of doing this:</p> +<p class="code-example">for(list<Widget>::iterator it = wl.begin(), itEnd = wl.end(); it != itEnd; ++it) {<br> + (*it).x = 37;<br> + (*it).y = 38;<br> + (*it).z = 39;<br> + }</p> +<p class="faq-answer">Consider doing this:</p> +<p class="code-example">for(list<Widget>::iterator it = wl.begin(), itEnd = wl.end(); it != itEnd; ++it) {<br> + Widget& w = *it; // The user can easily inspect or modify w here.<br> + w.x = 37;<br> + w.y = 38;<br> + w.z = 39;<br> + }</p> +<p class="faq-question"><a name="Best.20"></a>20 + Consider bitvector or bitset instead of vector<bool>. </p> +<p class="faq-answer">In EASTL, a vector of bool is exactly that. It intentionally does not attempt to make a specialization which implements a packed bit array. The bitvector class is specifically designed for this purpose. There are arguments either way, but if vector<bool> were allowed to be something other than an array of bool, it would go against user expectations and prevent users from making a true array of bool. There's a mechanism for specifically getting the bit packing, and it is bitvector.</p> +<p class="faq-answer">Additionally there is bitset, which is not a conventional iterateable container but instead acts like bit flags. bitset may better suit your needs than bitvector if you need to do flag/bit operations instead of array operations. bitset does have an operator[], though.</p> +<p class="faq-question"> <a name="Best.21"></a>21 +Vectors can be treated as contiguous memory.</p> +<p class="faq-answer">EASTL vectors (and strings) guarantee that elements are present in a linear contiguous array. This means that you can use a vector as you would a C-style array by using the vector data() member function or by using &v[0].</p> +<p class="faq-answer">To use a vector as a pointer to an array, you can use the following code:</p> +<p class="code-example">struct Widget {<br> + uint32_t x;<br> + uint32_t y;<br> + };<br> + <br> + vector<Widget> v;<br> + <br> + quick_sort((uint64_t*)v.data(), (uint64_t*)(v.data() + v.size()));</p> +<p class="faq-question"><a name="Best.22"></a>22 +Search hash_map<string> via find_as() instead of find(). </p> +<p class="faq-answer">EASTL hash tables offer a bonus function called find_as when lets you search a hash table by something other than the container type. This is particularly useful for hash tables of string objects that you want to search for by string literals (e.g. "hello") or char pointers. If you search for a string via the find function, your string literal will necessarily be converted to a temporary string object, which is inefficient.</p> +<p class="faq-answer">To use find_as, you can use the following code:</p> +<p class="code-example">hash_map<string, int> hashMap;<br> + hash_map<string, int>::iterator it = hashMap.find_as("hello"); // Using default hash and compare.</p> +<p class="faq-question"> <a name="Best.23"></a>23 +Take advantage of type_traits (e.g. <small style= +"font-family: Courier New;">EASTL_DECLARE_TRIVIAL_RELOCATE</small>).</p> +<p class="faq-answer">EASTL includes a fairly serious type traits library that is on par with the one found in Boost but offers some additional performance-enhancing help as well. The type_traits library provides information about class <span style="font-style: italic;">types</span>, as opposed to class instances. For example, the is_integral type trait tells if a type is one of int, short, long, char, uint64_t, etc.<br> + <br> +There are three primary uses of type traits:</p> +<ul> + <li>Allowing for optimized operations on some data types.</li> + <li>Allowing for different logic pathways based on data types.</li> + <li>Allowing for compile-type assertions about data type expectations.</li> +</ul> +<span class="faq-answer">Most of the type traits are automatically detected and implemented by the compiler. However, EASTL allows for the user to explicitly give the compiler hints about type traits that the compiler cannot know, via the EASTL_DECLARE declarations. If the user has a class that is relocatable (i.e. can safely use memcpy to copy values), the user can use the EASTL_DECLARE_TRIVIAL_RELOCATE declaration to tell the compiler that the class can be copied via memcpy. This will automatically significantly speed up some containers and algorithms that use that class.<br> +<br> +Here is an example of using type traits to tell if a value is a floating point value or not:<br> +</span> +<div class="code-example" style="margin-left: 40px; font-family: Courier New;"><small>template <typename T><br> + DoSomething(T t) {<br> + assert(is_floating_point<T>::value);<br> + }</small></div> +<span class="faq-answer">Here is an example of declaring a class as relocatable and using it in a vector.<br> +</span> +<div class="code-example" style="margin-left: 40px; font-family: Courier New;"><small>EASTL_DECLARE_TRIVIAL_RELOCATE(Widget); // Usually you put this at the Widget class declaration.<br> + vector<Widget> wVector;<br> + wVector.erase(wVector.begin()); // This operation will be optimized via using memcpy.</small></div> +<span class="faq-answer">The following is a full list of the currently recognized type traits. Most of these are implemented as of this writing, but if there is one that is missing, feel free to contact the maintainer of this library and request that it be completed.</span> +<ul> + <li>is_void</li> + <li>is_integral</li> + <li>is_floating_point</li> + <li>is_arithmetic</li> + <li>is_fundamental</li> + <li>is_const</li> + <li>is_volatile</li> + <li>is_abstract</li> + <li>is_signed</li> + <li>is_unsigned</li> + <li>is_array</li> + <li>is_pointer</li> + <li>is_reference</li> + <li>is_member_object_pointer</li> + <li>is_member_function_pointer</li> + <li>is_member_pointer</li> + <li>is_enum</li> + <li>is_union</li> + <li>is_class</li> + <li>is_polymorphic</li> + <li>is_function</li> + <li>is_object</li> + <li>is_scalar</li> + <li>is_compound</li> + <li>is_same</li> + <li>is_convertible</li> + <li>is_base_of</li> + <li>is_empty</li> + <li>is_pod</li> + <li>is_aligned</li> + <li>has_trivial_constructor</li> + <li>has_trivial_copy</li> + <li>has_trivial_assign</li> + <li>has_trivial_destructor</li> + <li>has_trivial_relocate<sup>1</sup></li> + <li>has_nothrow_constructor</li> + <li>has_nothrow_copy</li> + <li>has_nothrow_assign</li> + <li>has_virtual_destructor</li> + <li>alignment_of</li> + <li>rank</li> + <li>extent</li> +</ul> +<span class="faq-answer"><sup>1</sup> has_trivial_relocate is not found in Boost nor the C++ standard update proposal. However, it is very useful in allowing for the generation of optimized object moving operations. It is similar to the is_pod type trait, but goes further and allows non-pod classes to be categorized as relocatable. Such categorization is something that no compiler can do, as only the user can know if it is such. Thus <small style= +"font-family: Courier New;">EASTL_DECLARE_TRIVIAL_RELOCATE</small> is provided to allow the user to give the compiler a hint.</span> +<p class="faq-question"> <a name="Best.24"></a>24 +Name containers to track memory usage. +</p> +<p class="faq-answer">All EASTL containers which allocate memory have a built-in function called set_name and have a constructor argument that lets you specify the container name. This name is used in memory tracking and allows for the categorization and measurement of memory usage. You merely need to supply a name for your container to use and it does the rest.</p> +<p class="faq-answer">Here is an example of creating a list and naming it "collision list":</p> +<p class="faq-answer"><span class="code-example">list<CollisionData> collisionList(allocator("collision list"));</span>or<br> + <span class="code-example">list<CollisionData> collisionList;<br> +collisionList.get_allocator().set_name("collision list");</span></p> +<p class="faq-answer">Note that EASTL containers do not copy the name contents but merely copy the name pointer. This is done for simplicity and efficiency. A user can get around this limitation by creating a persistently present string table. Additionally, the user can get around this by declaring static but non-const strings and modifying them at runtime.</p> +<p class="faq-question"><a name="Best.25"></a>25 +Learn the algorithms.</p> +<p><span class="faq-answer">EASTL algorithms provide a variety of optimized implementations of fundamental algorithms. Many of the EASTL algorithms are the same as the STL algorithm set, though EASTL adds additional algorithms and additional optimizations not found in STL implementations such as Microsoft's. The copy algorithm, for example, will memcpy data types that have the has_trivial_relocate type trait instead of doing an element-by-element copy.<br> + <br> + The classifications we use here are not exactly the same as found in the C++ standard; they have been modified to be a little more intuitive. Not all the functions listed here may be yet available in EASTL as you read this. If you want some function then send a request to the maintainer. Detailed documentation for each algorithm is found in algorithm.h or the otherwise corresponding header file for the algorithm.<br> + <br> + <span style="font-weight: bold;">Search</span></span></p> +<ul> + <li>find, find_if</li> + <li>find_end</li> + <li>find_first_of</li> + <li>adjacent_find</li> + <li>binary_search</li> + <li>search, search_n</li> + <li>lower_bound</li> + <li>upper_bound</li> + <li>equal_range</li> +</ul> +<p class="faq-answer" style="font-weight: bold;">Sort</p> +<ul> + <li>is_sorted</li> + <li>quick_sort</li> + <li>insertion_sort</li> + <li>shell_sort</li> + <li>heap_sort</li> + <li>merge_sort, merge_sort_buffer</li> + <li>merge</li> + <li>inplace_merge</li> + <li>partial_sort</li> + <li>stable_sort</li> + <li>partial_sort_copy</li> + <li><other sort functions found in the EASTL bonus directories></li> +</ul> +<p class="faq-answer" style="font-weight: bold;">Modifying</p> +<ul> + <li>fill, fill_n</li> + <li>generate, generate_n</li> + <li>random_shuffle</li> + <li>swap</li> + <li>iter_swap</li> + <li>swap_ranges</li> + <li>remove, remove_if</li> + <li>remove_copy, remove_copy_if</li> + <li>replace, replace_if</li> + <li>replace_copy, replace_copy_if</li> + <li>reverse</li> + <li>reverse_copy</li> + <li>rotate</li> + <li>rotate_copy</li> + <li>partition</li> + <li>stable_partition</li> + <li>transform</li> + <li>next_permutation</li> + <li>prev_permutation</li> + <li>unique</li> + <li>unique_copy</li> +</ul> +<p class="faq-answer" style="font-weight: bold;">Non-Modifying</p> +<ul> + <li>for_each</li> + <li>copy</li> + <li>copy_backward</li> + <li>count, count_if</li> + <li>equal</li> + <li>mismatch</li> + <li>min</li> + <li>max</li> + <li>min_element</li> + <li>max_element</li> + <li>lexicographical_compare</li> + <li>nth_element</li> +</ul> +<p class="faq-answer" style="font-weight: bold;">Heap</p> +<ul> + <li>is_heap</li> + <li>make_heap</li> + <li>push_heap</li> + <li>pop_heap</li> + <li>change_heap</li> + <li>sort_heap</li> + <li>remove_heap</li> +</ul> +<p class="faq-answer" style="font-weight: bold;">Set</p> +<ul> + <li>includes</li> + <li>set_difference</li> + <li>set_symmetric_difference</li> + <li>set_intersection</li> + <li>set_union</li> +</ul> +<p class="faq-question"> <a name="Best.26"></a>26 +Pass and return containers by reference instead of value.</p> +<p class="faq-answer">If you aren't paying attention you might accidentally write code like this:</p> +<p class="code-example">void DoSomething(list<Widget> widgetList) {<br> + ...<br> +}</p> +<p class="faq-answer">The problem with the above is that widgetList is passed by value and not by reference. Thus the a copy of the container is made and passed instead of a reference of the container being passed. This may seem obvious to some but this happens periodically and the compiler gives no warning and the code will often execute properly, but inefficiently. Of course there are some occasions where you really do want to pass values instead of references.</p> +<p class="faq-question"><a name="Best.27"></a>27 +Consider using reset_lose_memory() for fast container teardown.</p> +<p class="faq-answer">EASTL containers have a reset function which unilaterally resets the container to a newly constructed state. The contents of the container are forgotten; no destructors are called and no memory is freed. This is a risky but power function for the purpose of implementing very fast temporary containers. There are numerous cases in high performance programming when you want to create a temporary container out of a scratch buffer area, use the container, and then just "vaporize" it, as it would be waste of time to go through the trouble of clearing the container and destroying and freeing the objects. Such functionality is often used with hash tables or maps and with a stack allocator (a.k.a. linear allocator).</p> +<p class="faq-answer">Here's an example of usage of the reset function and a PPMalloc-like StackAllocator:</p> +<p class="code-example">pStackAllocator->push_bookmark();<br> + hash_set<Widget, less<Widget>, StackAllocator> wSet(pStackAllocator);<br> +<use wSet><br> + wSet.reset_lose_memory();<br> + pStackAllocator->pop_bookmark();</p> +<p></p> +<p class="faq-question"> <a name="Best.28"></a>28 +Consider using fixed_substring instead of copying strings. +</p> +<p class="faq-answer">EASTL provides a fixed_substring class which uses a reference to a character segment instead of allocating its own string memory. This can be a more efficient way to work with strings under some circumstances.</p> +<p class="faq-answer">Here's an example of usage of fixed_substring:</p> +<p class="code-example">basic_string<char> str("hello world");<br> + fixed_substring<char> sub(str, 6, 5); // sub == "world"</p> +<p class="faq-answer">fixed_substring can refer to any character array and not just one that derives from a string object.</p> +<p class="faq-question"><a name="Best.29" id="Best.29"></a>29 + Consider using vector::push_back(void).</p> +<p class="faq-answer">EASTL provides an alternative way to insert elements into containers that avoids copy construction and/or the creation of temporaries. Consider the following code:</p> +<p class="code-example">vector<Widget> widgetArray;<br> + widgetArray.push_back(Widget());</p> +<p class="faq-answer">The standard vector push_back function requires you to supply an object to copy from. This incurs the cost of the creation of a temporary and for some types of classes or situations this cost may be undesirable. It additionally requires that your contained class support copy-construction whereas you may not be able to support copy construction. As an alternative, EASTL provides a push_back(void) function which requires nothing to copy from but instead constructs the object in place in the container. So you can do this:</p> +<p class="code-example">vector<Widget> widgetArray;<br> + widgetArray.push_back();<br> +widgetArray.back().x = 0; // Example of how to reference the new object. </p> +<p class="faq-answer">Other containers with such copy-less functions include:</p> +<p class="code-example">vector::push_back()<br> + deque::push_back()<br> + deque::push_front()<br> + list::push_back()<br> + list::push_front()<br> + slist::push_front()<br> + map::insert(const key_type& key) <br> + multimap::insert(const key_type& key) <br> + hash_map::insert(const key_type& key) <br> + hash_multimap::insert(const key_type& key) </p> +<p class="faq-answer">Note that the map functions above allow you to insert a default value specified by key alone and not a value_type like with the other map insert functions.</p> +<hr style="width: 100%; height: 2px;"> +<p>End of document<br> +<br> +<br> +<br> +<br></p> +</body> +</html> diff --git a/EASTL/doc/html/EASTL Design.html b/EASTL/doc/html/EASTL Design.html new file mode 100644 index 0000000..479dacc --- /dev/null +++ b/EASTL/doc/html/EASTL Design.html @@ -0,0 +1,424 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> + <title>EASTL Design</title> + <meta content="text/html; charset=us-ascii" http-equiv="content-type"> + <meta name="author" content="Paul Pedriana"> + <meta name="description" content="Discusses various design aspects of EASTL."> + <link type="text/css" rel="stylesheet" href="EASTLDoc.css"> +</head> +<body> +<h1>EASTL Design</h1> +<h2> Introduction</h2> +<p>EASTL (EA Standard Template Library) is designed to be a template library which encompasses and extends the + functionality of standard C++ STL while improving it in various ways useful to game development. Much of EASTL's design + is identical to standard STL, as the large majority of the STL is well-designed for many uses. The primary areas where +EASTL deviates from standard STL implementations are essentially the following:</p> +<ul> +<li>EASTL has a simplified and more flexible custom allocation scheme.</li> +<li>EASTL has significantly easier to read code.</li> +<li>EASTL has extension containers and algorithms.</li> +<li>EASTL has optimizations designed for game development.</li> +</ul> +<p>Of the above items, the only one which is an incompatible difference with STL is the case of memory allocation. The + method for defining a custom allocator for EASTL is slightly different than that of standard STL, though they are 90% + similar. The 10% difference, however, is what makes EASTL generally easier and more powerful to work with than standard +STL. Containers without custom allocators act identically between EASTL and standard STL.</p> +<h2>Motivations</h2> +<p>Our motifications for making EASTL drive the design of EASTL. As identified in the EASTL RFC (Request for Comment), the + primary reasons for implementing a custom version of the STL are: +</p> +<ul> +<li><span class="458151900-03082005"><font><font>Some STL implementations (especially Microsoft STL) have inferior +performance characteristics that make them unsuitable for game development. EASTL is faster than all existing STL +implementations.</font></font></span></li> +<li>The STL is sometimes hard to debug, as most STL implementations use cryptic variable names and unusual data +structures.</li> +<li>STL allocators are sometimes painful to work with, as they have many requirements and cannot be modified once bound +to a container.</li> +<li>The STL includes excess functionality that can lead to larger code than desirable. It's not very easy to tell +programmers they shouldn't use that functionality.</li> +<li>The STL is implemented with very deep function calls. This results is unacceptable performance in non-optimized +builds and sometimes in optimized builds as well.</li> +<li>The STL doesn't support alignment of contained objects.</li> +<li>STL containers won't let you insert an entry into a container without supplying an entry to copy from. This can be +inefficient.</li> +<li>Useful STL extensions (e.g. slist, hash_map, shared_ptr) found in existing STL implementations such as STLPort are +not portable because they don't exist in other versions of STL or aren't consistent between STL versions.<br></li> +<li>The STL lacks useful extensions that game programmers find useful (e.g. intrusive_list) but which could be best +optimized in a portable STL environment.</li> +<li>The STL has specifications that limit our ability to use it efficiently. For example, STL vectors are not +guaranteed to use contiguous memory and so cannot be safely used as an array.</li> +<li>The STL puts an emphasis on correctness before performance, whereas sometimes you can get significant performance +gains by making things less academcially pure.</li> +<li>STL containers have private implementations that don't allow you to work with their data in a portable way, yet +sometimes this is an important thing to be able to do (e.g. node pools).</li> +<li>All existing versions of STL allocate memory in empty versions of at least some of their containers. This is not +ideal and prevents optimizations such as container memory resets that can greatly increase performance in some +situations.</li> +<li>The STL is slow to compile, as most modern STL implementations are very large.<br></li> +<li>There are legal issues that make it hard for us to freely use portable STL implementations such as STLPort.</li> +<li>We have no say in the design and implementation of the STL and so are unable to change it to work for our +needs.</li> +</ul> +<h2>Prime Directives</h2> +<p>The implementation of EASTL is guided foremost by the +following directives which are listed in order of importance.</p> +<ol> +<li>Efficiency (speed and memory usage)</li> +<li>Correctness</li> +<li>Portability</li> +<li>Readability</li> +</ol> +<p>Note that unlike commercial STL implementations which must put correctness above all, we put a higher value on + efficiency. As a result, some functionality may have some usage limitation that is not present in other similar systems +but which allows for more efficient operation, especially on the platforms of significance to us.</p> +<p>Portability is significant, but not critical. Yes, EASTL must compile and run on all platforms that we will ship games + for. But we don't take that to mean under all compilers that could be conceivably used for such platforms. For example, + Microsoft VC6 can be used to compile Windows programs, but VC6's C++ support is too weak for EASTL and so you simply +cannot use EASTL under VC6.</p> +<p>Readability is something that EASTL achieves better than many other templated libraries, particularly Microsoft STL and + STLPort. We make every attempt to make EASTL code clean and sensible. Sometimes our need to provide optimizations + (particularly related to type_traits and iterator types) results in less simple code, but efficiency happens to be our +prime directive and so it overrides all other considerations.</p> +<h2> Thread Safety</h2> +<p>It's not simple enough to simply say that EASTL is thread-safe or thread-unsafe. However, we can say that with respect +to thread safety that EASTL does the right thing.</p> +<p>Individual EASTL containers are not thread-safe. That is, access to an instance of a container from multiple + threads at the same time is unsafe if any of those accesses are modifying operations. A given container can be read + from multiple threads simultaneously as well as any other standalone data structure. If a user wants to be able to have + modifying access an instance of a container from multiple threads, it is up to the user to ensure that proper thread +synchronization occurs. This usually means using a mutex.</p> +<p>EASTL classes other than containers are the same as containers with respect to thread safety. EASTL functions (e.g. + algorithms) are inherently thread-safe as they have no instance data and operate entirely on the stack. As of this +writing, no EASTL function allocates memory and thus doesn't bring thread safety issues via that means.</p> +<p>The user may well need to be concerned about thread safety with respect to memory allocation. If the user modifies + containers from multiple threads, then allocators are going to be accessed from multiple threads. If an allocator is + shared across multiple container instances (of the same type of container or not), then mutexes (as discussed above) + the user uses to protect access to indivudual instances will not suffice to provide thread safety for allocators used + across multiple instances. The conventional solution here is to use a mutex within the allocator if it is exected to be +used by multiple threads.</p> +<p>EASTL uses neither static nor global variables and thus there are no inter-instance dependencies that would make +thread safety difficult for the user to implement.</p> +<h2> Container Design</h2> +<p>All EASTL containers follow a set of consistent conventions. Here we define the prototypical container which has the + minimal functionality that all (non-adapter) containers must have. Some containers (e.g. stack) are explicitly adapter + containers and thus wrap or inherit the properties of the wrapped container in a way that is implementation + specific.<br> +</p> +<div class="code-example" style="margin-left: 40px;"><small><span style="font-family: Courier New;">template <class T, class Allocator = +EASTLAllocator><br> +class container<br> +{<br> +public:<br> + typedef container<T, Allocator> this_type;<br> + typedef +T + value_type;<br> + typedef T* + pointer;<br> + typedef const T* + const_pointer;<br> + typedef +T& reference;<br> + + typedef const +T& const_reference;<br> + + typedef +ptrdiff_t difference_type;<br> + + typedef +impl_defined size_type;<br> + + typedef impl-defined + iterator;<br> + typedef impl-defined + const_iterator;<br> + typedef reverse_iterator<iterator> reverse_iterator;<br> + typedef reverse_iterator<const_iterator> reverse_const_iterator;<br> + typedef Allocator + allocator_type;<br> +<br> +public:<br> + container(</span></small><small><span style="font-family: Courier New;">const</span></small> +<small><span style="font-family: Courier New;">allocator_type& allocator = allocator_type());<br> + container(const</span></small> <small><span style= +"font-family: Courier New;">this_type</span></small><small><span style="font-family: Courier New;">& +x</span></small><small><span style="font-family: Courier New;">);<br> +<br> + </span></small><small><span style= +"font-family: Courier New;">this_type</span></small><small><span style="font-family: Courier New;">& +operator=(</span></small><small><span style="font-family: Courier New;">this_type</span></small><small><span style= +"font-family: Courier New;">& x);<br> + void swap(</span></small><small><span style= +"font-family: Courier New;">this_type</span></small><small><span style="font-family: Courier New;">& x);<br> + void reset();<br> +<br> + allocator_type& get_allocator();<br> + void set_allocator(allocator_type& allocator);<br> +<br> + iterator begin();<br> + const_iterator begin() const;<br> + iterator end();<br> + const_iterator end() const;<br> +<br> + bool validate() const;<br></span></small> <small><span style= +"font-family: Courier New;"> int validate_iterator(const_iterator i) +const;<br></span></small><br> +<small><span style="font-family: Courier New;">protected:<br> + allocator_type mAllocator;<br> +};<br> +<br> +template <class T,</span></small> <small><span style="font-family: Courier New;">class +Allocator</span></small><small><span style="font-family: Courier New;">><br> +bool operator==(const container<T, Allocator>& a, const container<T,</span></small> <small><span style= +"font-family: Courier New;">Allocator</span></small><small><span style="font-family: Courier New;">>& b);<br> +<br> +template <class T,</span></small> <small><span style="font-family: Courier New;">class +Allocator</span></small><small><span style="font-family: Courier New;">><br> +bool operator!=(const container<T,</span></small> <small><span style= +"font-family: Courier New;">Allocator</span></small><small><span style="font-family: Courier New;">>& a, const +container<T,</span></small> <small><span style= +"font-family: Courier New;">Allocator</span></small><small><span style="font-family: Courier New;">>& +b);</span></small></div> +<br> +Notes: +<ul> +<li>Swapped containers do not swap their allocators.</li> +<li>Newly constructed empty containers do no memory allocation. Some STL and other container libraries allocate an +initial node from the class memory allocator. EASTL containers by design never do this. If a container needs an initial +node, that node should be made part of the container itself or be a static empty node object.</li> +<li>Empty containers (new or otherwise) contain no constructed objects, including those that might be in an 'end' node. +Similarly, no user object (e.g. of type T) should be constructed unless required by the design and unless documented in +the cotainer/algorithm contract. </li> +<li>The reset function is a special extension function which unilaterally resets the container to an empty state +without freeing the memory of the contained objects. This is useful for very quickly tearing down a container built +into scratch memory. No memory is allocated by reset, and the container has no allocatedmemory after the reset is +executed.</li> +<li>The validate and validate_iterator functions provide explicit container and iterator validation. EASTL provides an option to do implicit automatic iterator and container validation, but full validation (which can be potentially extensive) has too much of a performance cost to execute implicitly, even in a debug build. So EASTL provides these explicit functions which can be called by the user at the appropriate time and in optimized builds as well as debug builds. </li> +</ul> +<h2>Allocator Design</h2> +<p>The most significant difference between EASTL and standard C++ STL is that standard STL containers are templated on an + allocator class with the interface defined in std::allocator. std::allocator is defined in the C++ standard as + this:<br> +</p> +<div class="code-example" style="margin-left: 40px;"><small><span style="font-family: Courier New;">// Standard C++ allocator<br> + <br> + template <class T><br> +class allocator</span><br style="font-family: Courier New;"> +<span style="font-family: Courier New;">{</span><br style="font-family: Courier New;"> +<span style="font-family: Courier New;">public:</span><br style="font-family: Courier New;"> +<span style="font-family: Courier New;"> typedef size_t size_type;</span><br style= +"font-family: Courier New;"> +<span style="font-family: Courier New;"> typedef ptrdiff_t difference_type;</span><br style= +"font-family: Courier New;"> +<span style="font-family: Courier New;"> typedef T* pointer;</span><br style="font-family: Courier New;"> +<span style="font-family: Courier New;"> typedef const T* const_pointer;</span><br style= +"font-family: Courier New;"> +<span style="font-family: Courier New;"> typedef T& + reference;</span><br style="font-family: Courier New;"> +<span style="font-family: Courier New;"> typedef const +T& const_reference;</span><br style="font-family: Courier New;"> +<span style="font-family: Courier New;"> typedef T value_type;</span><br style="font-family: Courier New;"> +<br style="font-family: Courier New;"> +<span style="font-family: Courier New;"> template <class U><br> + struct rebind { typedef allocator<U> other; };</span><br style="font-family: Courier New;"> +<br style="font-family: Courier New;"> +<span style="font-family: Courier New;"> allocator() throw();</span><br style= +"font-family: Courier New;"> +<span style="font-family: Courier New;"> allocator(const allocator&) throw();</span><br style= +"font-family: Courier New;"> +<span style="font-family: Courier New;"> template <class U><br> + allocator(const allocator<U>&) throw();<br> +<br style="font-family: Courier New;"> +</span> <span style="font-family: Courier New;"> ~allocator() +throw();<br> +<br style="font-family: Courier New;"> +</span> <span style="font-family: Courier New;"> pointer + address(reference x) const;</span><br style="font-family: Courier New;"> +<span style="font-family: Courier New;"> const_pointer address(const_reference x) +const;</span><br style="font-family: Courier New;"> +<span style="font-family: Courier New;"> pointer allocate(size_type, typename +allocator<void>::const_pointer hint = 0);</span><br style="font-family: Courier New;"> +<span style="font-family: Courier New;"> void deallocate(pointer p, +size_type n);</span><br style="font-family: Courier New;"> +<span style="font-family: Courier New;"> size_type max_size() const +throw();</span><br style="font-family: Courier New;"> +<span style="font-family: Courier New;"> void construct(pointer p, +const T& val);</span><br style="font-family: Courier New;"> +<span style="font-family: Courier New;"> void destroy(pointer +p);</span><br style="font-family: Courier New;"> +<span style="font-family: Courier New;">};</span></small></div> +<p> Each STL container needs to have an allocator templated on container type T associated with it. The problem with this +is that allocators for containers are defined at the class level and not the instance level. This makes it painful to +define custom allocators for containers and adds to code bloat. Also, it turns out that the containers don't actually +use allocator<T> but instead use allocator<T>::rebind<U>::other. Lastly, you cannot access this +allocator after the container is constructed. There are some good academic reasons why the C++ standard works this way, +but it results in a lot of unnecessary pain and makes concepts like memory tracking much harder to implement.</p> +<p>What EASTL does is use a more familiar memory allocation pattern whereby there is only one allocator class interface + and it is used by all containers. Additionally EASTL containers let you access their allocators and query them, name +them, change them, etc.</p> +<p>EASTL has chosen to make allocators not be copied between containers during container swap and assign operations. This + means that if container A swaps its contents with container B, both containers retain their original allocators. + Similarly, assigning container A to container B causes container B to retain its original allocator. Containers that + are equivalent should report so via operator==; EASTL will do a smart swap if allocators are equal, and a brute-force + swap otherwise.<br> +</p> +<div class="code-example" style="margin-left: 40px;"><small><span style="font-family: Courier New;">// EASTL allocator<br> +<br> +class allocator<br> +{<br> +public:<br> + allocator(const char* pName = NULL);<br> +<br> + void* allocate(size_t n, int flags = 0);<br> + void* allocate(size_t n, size_t alignment, size_t offset, int flags = 0);<br> + void deallocate(void* p, size_t n);<br> +<br> + const char* get_name() const;<br> + void set_name(const char* pName);<br> +};<br> +<br> +allocator* GetDefaultAllocator();</span></small></div> +<h2>Fixed Size Container Design</h2> +<p>EASTL supplies a set of fixed-size containers that the user can use, though the user can also implement their own + versions. So in addition to class list there is class fixed_list. The fixed_list class implements a linked list via a + fixed-size pool of contiguous memory which has no space overhead (unlike with a regular heap), doesn't cause +fragmentation, and allocates very quickly.</p> +<p>EASTL implements fixed containers via subclasses of regular containers which set the regular container's allocator to + point to themselves. Thus the implementation for fixed_list is very tiny and consists of little more + than constructor and allocator functions. This design has some advantages but has one small disadvantage. The + primary advantages are primarily that code bloat is reduced and that the implementation is simple and the user can + easily extend it. The primary disadvantage is that the parent list class ends up with a pointer to itself and thus has + 4 bytes that could arguably be saved if system was designed differently. That different design would be to make the + list class have a policy template parameter which specifies that it is a fixed pool container. EASTL chose not to + follow the policy design because it would complicate the implementation, make it harder for the user to extend the + container, and would potentially waste more memory due to code bloat than it would save due to the 4 byte savings it +achieves in container instances.</p> +<h2>Algorithm Design</h2> +<p>EASTL algorithms very much follow the philosophy of standard C++ algorithms, as this philosophy is sound and efficient. + One of the primary aspects of algorithms is that they work on iterators and not containers. You will note for example + that the find algorithm takes a first and last iterator as arguments and not a container. This has two primary + benefits: it allows the user to specify a subrange of the container to search within and it allows the user to apply +the find algorithm to sequences that aren't containers (e.g. a C array).</p> +<p>EASTL algorithms are optimized at least as well as the best STL algorithms found in commercial libraries and are + significantly optimized over the algorithms that come with the first-party STLs that come with compilers. Most significantly, EASTL algorithms take advantage of type traits of contained classes and + take advantage of iterator types to optimize code generation. For example, if you resize an array of integers (or other "pod" type), EASTL will detect that this can be done with a memcpy instead of a slow object-by-object move as would +Micrsoft STL.</p> +<p>The optimizations found in EASTL algorithms and the supporting code in EASTL type traits consistts of some fairly + tricky advanced C++ and while it is fairly easy to read, it requires a C++ expert (language lawyer, really) to + implement confidently. The result of this is that it takes more effort to develop and maintain EASTL than it would to +maintain a simpler library. However, the performance advantages have been deemed worth the tradeoff.</p> +<h2>Smart Pointer Design</h2> +<p>EASTL implements the following smart pointer types:</p> +<ul> +<li>shared_ptr</li> +<li>shared_array</li> +<li>weak_ptr</li> +<li>instrusive_ptr</li> +<li>scoped_ptr</li> +<li>scoped_array</li> +<li>linked_ptr</li> +<li>linked_array</li> +</ul> +All but linked_ptr/linked_array are well-known smart pointers from the Boost library. The behaviour of these smart +pointers is very similar to those from Boost with two exceptions: +<ul> +<li>EASTL smart pointers allow you to assign an allocator to them.</li> +<li>EASTL shared_ptr implements deletion via a templated parameter instead of a dynamically allocated virtual +member object interface.</li> +</ul> +<p>With respect to assigning an allocator, this gives EASTL more control over memory allocation and tracking, as Boost +smart pointers unilaterally use global operator new to allocate memory from the global heap.</p> +<p>With respect to shared_ptr deletion, EASTL's current design of using a templated parameter is questionable, but does + have some reason. The advantage is that EASTL avoids a heap allocation, avoids virtual function calls, and avoids + templated class proliferation. The disadvantage is that EASTL shared_ptr containers which hold void pointers can't call + the destructors of their contained objects unless the user manually specifies a custom deleter template parameter. This + is case whereby EASTL is more efficient but less safe. We can revisit this topic in the future if it becomes an + issue.</p> +<h2>list::size is O(n)</h2> +<p>As of this writing, EASTL has three linked list classes: list, slist, and intrusive_list. In each of these classes, the + size of the list is not cached in a member size variable. The result of this is that getting the size of a list is not + a fast operation, as it requires traversing the list and counting the nodes. We could make the list::size function be + fast by having a member mSize variable which tracks the size as we insert and delete items. There are reasons for + having such functionality and reasons for not having such functionality. We currently choose to not have a member mSize + variable as it would add four bytes to the class, add a tiny amount of processing to functions such as insert and + erase, and would only serve to improve the size function, but no others. In the case of intrusive_list, it would do + additional harm. The alternative argument is that the C++ standard states that std::list should be an O(1) + operation (i.e. have a member size variable), that many C++ standard library list implementations do so, that the + size is but an integer which is quick to update, and that many users expect to have a fast size function. In the final + analysis, we are developing a library for game development and performance is paramount, so we choose to not cache the +list size. The user can always implement a size cache himself.</p> +<h2>basic_string doesn't use copy-on-write</h2> +<p>The primary benefit of CoW is that it allows for the sharing of string data between two string objects. Thus if you say + this:</p> +<p class="code-example"> string a("hello");<br style= +"font-family: Courier New;"> + string b(a);</p> +<p>the "hello" will be shared between a and b. If you then say this:</p> +<p class="code-example"> a = "world";</p> +<p>then <span style="font-family: Courier New;">a</span> will release its reference to "hello" and leave b with the only + reference to it. Normally this functionality is accomplished via reference counting and with atomic operations or +mutexes.</p> +<p> The C++ standard does not say anything about basic_string and CoW. However, for a basic_string implementation to be + standards-conforming, a number of issues arise which dictate some things about how one would have to implement a CoW + string. The discussion of these issues will not be rehashed here, as you can read the references below for better + detail than can be provided in the space we have here. However, we can say that the C++ standard is sensible + and that anything we try to do here to allow for an efficient CoW implementation would result in a generally +unacceptable string interface.</p> +<p>The disadvantages of CoW strings are:</p> +<ul> +<li>A reference count needs to exist with the string, which increases string memory usage.</li> +<li>With thread safety, atomic operations and mutex locks are expensive, especially on weaker memory systems such +as console gaming platforms.</li> +<li>All non-const string accessor functions need to do a sharing check the the first such check needs to detach the +string. Similarly, all string assignments need to do a sharing check as well. If you access the string before doing an +assignment, the assignment doesn't result in a shared string, because the string has already been detached.</li> +<li>String sharing doesn't happen the large majority of the time. In some cases, the total sum of the reference +count memory can exceed any memory savings gained by the strings that share representations. </li> +</ul> +<p>The addition of a cow_string class is under consideration for EASTL. There are conceivably some systems which have + string usage patterns which would benefit from CoW sharing. Such functionality is best saved for a separate +string implementation so that the other string uses aren't penalized.</p> +<p>This is a good starting HTML reference on the topic:</p> +<blockquote> + <p> + <a href= +"http://www.gotw.ca/publications/optimizations.htm">http://www.gotw.ca/publications/optimizations.htm</a></p> +</blockquote> +<p>Here is a well-known Usenet discussion on the topic:</p> +<blockquote> + <p><a href= +"http://groups-beta.google.com/group/comp.lang.c++.moderated/browse_thread/thread/3dc6af5198d0bf7/886c8642cb06e03d">http://groups-beta.google.com/group/comp.lang.c++.moderated/browse_thread/thread/3dc6af5198d0bf7/886c8642cb06e03d</a></p> +</blockquote> +<hr style="width: 100%; height: 2px;"> +End of document<br> +<br> +<br> +<br> +<br> +<br> +<br> +<br> +<br> +<br> +<br> +<br> +<br> +<br> +<br> +<br> +<br> +<br> +<br> +<br> +<br> +<br> +<br> +<br> +<br> +<br> +<br> +</body> +</html> diff --git a/EASTL/doc/html/EASTL FAQ.html b/EASTL/doc/html/EASTL FAQ.html new file mode 100644 index 0000000..04b1578 --- /dev/null +++ b/EASTL/doc/html/EASTL FAQ.html @@ -0,0 +1,2385 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> + <title>EASTL FAQ</title> + <meta content="text/html; charset=us-ascii" http-equiv="content-type"> + <meta name="author" content="Paul Pedriana"> + <meta name="description" content="Frequently asked questions about EASTL."> + <link type="text/css" rel="stylesheet" href="EASTLDoc.css"> +<style type="text/css"> +<!-- +.style1 {font-family: "Courier New"} +.style2 {color: #339900} +.style3 {color: #FF0000} +.style4 {color: #999999} +.style5 {font-size: 10pt} +--> +</style> +</head> +<body> +<h1>EASTL FAQ</h1> +<p>We provide a FAQ (frequently asked questions) list here for a number of commonly asked questions about EASTL and STL in +general. Feel free to suggest new FAQ additions based on your own experience.</p> +<h2>Information</h2> +<table style="width: 100%;" border="0" cellpadding="0" cellspacing="0" cols="2"> +<tbody> +<tr> +<td>1</td> +<td><a href="#Info.1">What is EASTL?</a></td> +</tr> +<tr> +<td>2</td> +<td><a href="#Info.2">What uses are EASTL suitable for?</a></td> +</tr> +<tr> +<td style="width: 28px;">3<br></td> +<td style="vertical-align: top; text-align: left;"><a href="#Info.3">How does EASTL differ from standard C++ +STL?</a></td> +</tr> +<tr> +<td>4</td> +<td><a href="#Info.4">Is EASTL thread-safe?</a></td> +</tr> +<tr> +<td>5</td> +<td><a href="#Info.5">What platforms/compilers does EASTL support?</a></td> +</tr> +<tr> +<td>6</td> +<td><a href="#Info.6">Why is there EASTL when there is the STL?</a></td> +</tr> +<tr> +<td>7</td> +<td><a href="#Info.7">Can I mix EASTL with standard C++ STL?</a></td> +</tr> +<tr> +<td>8</td> +<td><a href="#Info.8">Where can I learn more about STL and EASTL?</a></td> +</tr> +<tr> +<td>9</td> +<td><a href="#Info.9">What is the legal status of EASTL?</a></td> +</tr> +<tr> +<td>10</td> +<td><a href="#Info.10">Does EASTL deal with compiler exception handling settings?</a></td> +</tr> +<tr> +<td>11</td> +<td><a href="#Info.11">What C++ language features does EASTL use (e.g. virtual functions)?</a></td> +</tr> +<tr> +<td>12</td> +<td><a href="#Info.12">What compiler warning levels does EASTL support?</a></td> +</tr> +<tr> +<td>13</td> +<td><a href="#Info.13">Is EASTL compatible with Lint?</a></td> +</tr> +<tr> +<td>14</td> +<td><a href="#Info.14">What compiler settings do I need to compile EASTL?</a></td> +</tr> +<tr> +<td>15</td> +<td><a href="#Info.15">How hard is it to incorporate EASTL into my project?</a></td> +</tr> +<tr> +<td>16</td> +<td><a href="#Info.16">Should I use EASTL instead of std STL or instead of my custom library?</a></td> +</tr> +<tr> +<td>17</td> +<td><a href="#Info.17">I think I've found a bug. What do I do?</a></td> +</tr> +<tr> +<td>18</td> +<td><a href="#Info.18">Can EASTL be used by third party EA developers?</a></td> +</tr> +</tbody> +</table> +<h2> Performance +</h2> +<table style="width: 100%;" border="0" cellpadding="0" cellspacing="0" cols="2"> +<tbody> +<tr> +<td style="width: 28px;">1</td> +<td><a href="#Perf.1">How efficient is EASTL compared to standard C++ STL implementations?</a></td> +</tr> +<tr> +<td>2</td> +<td><a href="#Perf.2">How efficient is EASTL in general?</a></td> +</tr> +<tr> +<td>3</td> +<td><a href="#Perf.3">Strings don't appear to use the "copy-on-write" optimization. Why not?</a></td> +</tr> +<tr> +<td>4</td> +<td><a href="#Perf.4">Does EASTL cause code bloat, given that it uses templates?</a></td> +</tr> +<tr> +<td>5</td> +<td><a href="#Perf.5">Don't STL and EASTL containers fragment memory?</a></td> +</tr> +<tr> +<td>6</td> +<td><a href="#Perf.6">I don't see container optimizations for equivalent scalar types such as pointer types. +Why?</a></td> +</tr> +<tr> +<td>7</td> +<td><a href="#Perf.7">I've seen some STL's provide a default quick "node allocator" as the default allocator. Why +doesn't EASTL do this?</a></td> +</tr> +<tr> +<td>8</td> +<td><a href="#Perf.8">Templates sometimes seem to take a long time to compile. Why do I do about that?</a></td> +</tr> +<tr> +<td>9</td> +<td><a href="#Cont.8">How do I assign a custom allocator to an EASTL container?</a></td> +</tr> +<tr> +<td>10</td> +<td><a href="#Perf.10">How well does EASTL inline?</a></td> +</tr> +<tr> +<td>11</td> +<td><a href="#Perf.11">How do I control function inlining?</a></td> +</tr> +<tr> +<td>12</td> +<td><a href="#Perf.12">C++ / EASTL seems to bloat my .obj files much more than C does.</a></td> +</tr> +<tr> +<td>13</td> +<td><a href="#Perf.13">What are the best compiler settings for EASTL?</a></td> +</tr> +</tbody> +</table> +<h2>Problems</h2> +<table style="width: 100%;" border="0" cellpadding="0" cellspacing="0" cols="2"> +<tbody> +<tr> +<td style="width: 28px;">1</td> +<td><a href="#Prob.1">I'm getting screwy behavior in sorting algorithms or sorted containers. What's wrong?</a></td> +</tr> +<tr> +<td>2</td> + <td><a href="#Prob.2">I am getting compiler warnings (e.g. C4244, C4242 or C4267) that make no sense. Why?</a></td> +</tr> +<tr> +<td>3</td> +<td><a href="#Prob.3">I am getting compiler warning C4530, which complains about exception handling and "unwind +semantics." What gives?</a></td> +</tr> +<tr> +<td>4</td> +<td><a href="#Prob.4">Why are tree-based containers hard to read with a debugger?</a></td> +</tr> +<tr> +<td>5</td> +<td><a href="#Prob.5">The EASTL source code is sometimes rather complicated looking. Why is that?</a></td> +</tr> +<tr> +<td>6</td> +<td><a href="#Prob.6">When I get compilation errors, they are very long and complicated looking. What do I do?</a></td> +</tr> +<tr> +<td>7</td> +<td><a href="#Prob.7">Templates sometimes seem to take a long time to compile. Why do I do about that?</a></td> +</tr> +<tr> +<td>8</td> +<td><a href="#Prob.8">I get the compiler error: <small>"template instantiation depth exceeds maximum of 17. use +-ftemplate-depth-NN to increase the maximum"</small></a></td> +</tr> +<tr> +<td>9</td> +<td><a href="#Prob.9">I'm getting errors about min and max while compiling.</a></td> +</tr> +<tr> +<td>10</td> +<td><a href="#Prob.10">C++ / EASTL seems to bloat my .obj files much more than C does.</a></td> +</tr> +<tr> +<td>11</td> +<td><a href="#Prob.11">I'm getting compiler errors regarding operator new being previously defined.</a></td> +</tr> +<tr> +<td>12</td> +<td><a href="#Prob.12">I'm getting errors related to wchar_t string functions such as wcslen.</a></td> +</tr> +<tr> +<td>13</td> +<td><a href="#Prob.13">I'm getting compiler warning C4619: there is no warning number Cxxxx (e.g. C4217).</a></td> +</tr> +<tr> +<td>14</td> +<td><a href="#Prob.14">My stack-based fixed_vector is not respecting the object alignment requirements.</a></td> +</tr> +<tr> + <td>15</td> + <td><a href="#Prob.15">I am getting compiler errors when using GCC under XCode (Macintosh/iphone).</a></td> +</tr> +<tr> + <td>16</td> + <td><a href="#Prob.16">I am getting linker errors about Vsnprintf8 or Vsnprintf16.</a></td> +</tr> +<tr> + <td>17</td> + <td><a href="#Prob.17">I am getting compiler errors about UINT64_C or UINT32_C</a>. </td> +</tr> +<tr> + <td>18</td> + <td><a href="#Prob.18">I am getting a crash with a global EASTL container. </a></td> +</tr> +<tr> + <td>19</td> + <td><a href="#Prob.19">Why doesn't EASTL support passing NULL to functions with pointer arguments? </a></td> +</tr> +</tbody> +</table> +<h2>Debug</h2> +<table style="width: 100%;" border="0" cellpadding="0" cellspacing="0" cols="2"> +<tbody> +<tr> +<td style="width: 28px;">1</td> +<td><a href="#Debug.1">How do I get VC++ mouse-overs to view templated data?</a></td> +</tr> +<tr> +<td>2</td> +<td><a href="#Debug.2">How do I view containers if the visualizer/tooltip support is not present?</a></td> +</tr> +<tr> +<td>3</td> +<td><a href="#Debug.3">The EASTL source code is sometimes rather complicated looking. Why is that?</a></td> +</tr> +<tr> +<td>4</td> +<td><a href="#Debug.4">When I get compilation errors, they are very long and complicated looking. What do I +do?</a></td> +</tr> +<tr> +<td>5</td> +<td><a href="#Debug.5">How do I measure hash table balancing?</a></td> +</tr> +</tbody> +</table> +<h2>Containers</h2> +<table style="width: 100%;" border="0" cellpadding="0" cellspacing="0" cols="2"> +<tbody> +<tr> +<td style="width: 28px;">1</td> +<td><a href="#Cont.1">Why do some containers have "fixed" versions (e.g. fixed_list) but others(e.g. deque) don't have +fixed versions?</a></td> +</tr> +<tr> +<td>2</td> +<td><a href="#Cont.2">Can I mix EASTL with standard C++ STL?</a></td> +</tr> +<tr> +<td>3</td> +<td><a href="#Cont.3">Why are there so many containers?</a></td> +</tr> +<tr> +<td>4</td> +<td><a href="#Cont.4">Don't STL and EASTL containers fragment memory?</a></td> +</tr> +<tr> +<td>5</td> +<td><a href="#Cont.5">I don't see container optimizations for equivalent scalar types such as pointer types. +Why?</a></td> +</tr> +<tr> +<td>6</td> +<td><a href="#Cont.6">What about alternative container and algorithm implementations (e.g. treaps, skip lists, avl +trees)?</a></td> +</tr> +<tr> +<td>7</td> +<td><a href="#Cont.7">Why are containers hard to read with a debugger?</a></td> +</tr> +<tr> +<td>8</td> +<td><a href="#Cont.8">How do I assign a custom allocator to an EASTL container?</a></td> +</tr> +<tr> +<td>9</td> +<td><a href="#Cont.9">How do I set the VC++ debugger to display EASTL container data with tooltips?</a></td> +</tr> +<tr> +<td>10</td> +<td><a href="#Cont.10">How do I use a memory pool with a container?</a></td> +</tr> +<tr> +<td>11</td> +<td><a href="#Cont.11">How do I write a comparison (operator<()) for a struct that contains two or more +members?</a></td> +</tr> +<tr> +<td>12</td> +<td><a href="#Cont.12">Why doesn't container X have member function Y?</a></td> +</tr> +<tr> +<td>13</td> +<td><a href="#Cont.13">How do I search a hash_map of strings via a char pointer efficiently? If I use map.find("hello") +it creates a temporary string, which is inefficient.</a></td> +</tr> +<tr> +<td>14</td> +<td><a href="#Cont.14">Why are set and hash_set iterators const (i.e. const_iterator)?</a></td> +</tr> +<tr> +<td>15</td> +<td><a href="#Cont.15">How do I prevent my hash container from re-hashing?</a></td> +</tr> +<tr> +<td>16</td> +<td><a href="#Cont.16">Which uses less memory, a map or a hash_map?</a></td> +</tr> +<tr> +<td>17</td> +<td><a href="#Cont.17">How do I write a custom hash function?</a></td> +</tr> +<tr> +<td>18</td> +<td><a href="#Cont.18">How do I write a custom compare function for a map or set?</a></td> +</tr> +<tr> +<td>19</td> +<td><a href="#Cont.19">How do I force my vector or string capacity down to the size of the container?</a></td> +</tr> +<tr> +<td>20</td> +<td><a href="#Cont.20">How do I iterate a container while (selectively) removing items from it?</a></td> +</tr> +<tr> +<td>21</td> +<td><a href="#Cont.21">How do I store a pointer in a container?</a></td> +</tr> +<tr> +<td>22</td> +<td><a href="#Cont.22">How do I make a union of two containers? difference? intersection?</a></td> +</tr> +<tr> +<td>23</td> +<td><a href="#Cont.23">How do I override the default global allocator?</a></td> +</tr> +<tr> +<td>24</td> +<td><a href="#Cont.24">How do I do trick X with the string class?</a></td> +</tr> +<tr> +<td>25</td> +<td><a href="#Cont.25">How do EASTL smart pointers compare to Boost smart pointers?</a></td> +</tr> +<tr> +<td>26</td> +<td><a href="#Cont.26">How do your forward-declare an EASTL container?</a></td> +</tr> +<tr> + <td>27</td> + <td><a href="#Cont.27">How do I make two containers share a memory pool?</a></td> +</tr> +<tr> + <td>28</td> + <td><a href="#Cont.28">Can I use a std (STL) allocator with EASTL?</a></td> +</tr> +<tr> + <td>29 </td> + <td><a href="#Cont.29">What are the requirements of classes stored in containers? </a></td> +</tr> +</tbody> +</table> +<h2>Algorithms</h2> +<table style="width: 100%;" border="0" cellpadding="0" cellspacing="0" cols="2"> +<tbody> +<tr> +<td style="width: 28px;">1</td> +<td><a href="#Algo.1">I'm getting screwy behavior in sorting algorithms or sorted containers. What's wrong?</a></td> +</tr> +<tr> +<td>2</td> +<td><a href="#Algo.2">How do I write a comparison (operator<()) for a struct that contains two or more +members?</a></td> +</tr> +<tr> +<td>3</td> +<td><a href="#Algo.3">How do I sort something in reverse order?</a></td> +</tr> +<tr> +<td>4</td> +<td><a href="#Algo.4">I'm getting errors about min and max while compiling.</a></td> +</tr> +<tr> +<td>5</td> +<td><a href="#Algo.5">Why don't algorithms take a container as an argument instead of iterators? A container would be +more convenient.</a></td> +</tr> +<tr> +<td>6</td> +<td><a href="#Algo.6">Given a container of pointers, how do I find an element by value (instead of by +pointer)?</a></td> +</tr> +<tr> +<td>7</td> +<td><a href="#Algo.7">When do stored objects need to support <small><span style="font-family: Courier New;">opertor +<</span></small> vs. when do they need to support <small><span style="font-family: Courier New;">operator +==</span></small>?</a></td> +</tr> +<tr> + <td>8</td> + <td><a href="#Algo.8">How do I sort via pointers or array indexes instead of objects directly?</a></td> +</tr> +</tbody> +</table> +<h2>Iterators</h2> +<table style="width: 100%;" border="0" cellpadding="0" cellspacing="0" cols="2"> +<tbody> +<tr> +<td style="width: 28px;">1</td> +<td><a href="#Iter.1">What's the difference between iterator, const iterator, and const_iterator?</a></td> +</tr> +<tr> +<td>2</td> +<td><a href="#Iter.2">How do I tell from an iterator what type of thing it is iterating?</a></td> +</tr> +<tr> +<td>3</td> +<td><a href="#Iter.3">How do I iterate a container while (selectively) removing items from it?</a></td> +</tr> +<tr> +<td>4</td> +<td><a href="#Iter.4">What is an insert_iterator?</a></td> +</tr> +</tbody> +</table> +<h2><br> + Information +</h2> +<p class="faq-question"><a name="Info.1"></a>Info.1 +What is EASTL?</p> +<p class="faq-answer">EASTL refers to "EA Standard Template Library." It is a C++ template library that is analogous to the template facilities of the C++ standard library, which are often referred to as the STL. EASTL consists of the following systems: </p> +<ul> + <li>Containers</li> + <li>Iterators</li> + <li>Algorithms</li> + <li>Utilities</li> + <li>Smart pointers</li> + <li>Type traits</li> +</ul> +<p class="faq-answer">EASTL provides extensions and optimizations over the equivalents in standard C++ STL.</p> +<p class="faq-answer">EASTL is a professional-level implementation which outperforms commercial implementations (where functionality overlaps) and is significantly easier to read and debug.</p> +<p class="faq-question"> <a name="Info.2"></a>Info.2 +What uses are EASTL suitable for?</p> +<p class="faq-answer">EASTL is suitable for any place where templated containers and algorithms would be appropriate. Thus any C++ tools could use it and many C++ game runtimes could use it, especially 2005+ generation game platforms. EASTL has optimizations that make it more suited to the CPUs and memory systems found on console platforms. Additionally, EASTL has some type-traits and iterator-traits-derived template optimizations that make it generally more efficient than home-brew templated containers.</p> +<p class="faq-question"><a name="Info.3"></a>Info.3 +How does EASTL differ from standard C++ STL?</p> +<p class="faq-answer">There are three kinds of ways that EASTL differs from standard STL: </p> +<ol> + <li>EASTL equivalents to STL sometimes differ.</li> + <li>EASTL implementations sometimes differ from STL implementations of the same thing.</li> + <li>EASTL has functionality that doesn't exist in STL.</li> +</ol> +<p class="faq-answer">With respect to item #1, the changes are such that they benefit game development and not the type that could silently hurt you if you were more familiar with STL interfaces.</p> +<p class="faq-answer">With respect to item #2, where EASTL implementations differ from STL implementations it is almost always due to improvements being made in the EASTL versions or tradeoffs being made which are considered better for game development.</p> +<p class="faq-answer">With respect to item #3, there are a number of facilities that EASTL has that STL doesn't have, such as intrusive_list and slist containers, smart pointers, and type traits. All of these are facilities that assist in making more efficient game code and data.</p> +<p class="faq-answer">Ways in which EASTL is better than standard STL: </p> +<ul> + <li>Has higher performance in release builds, sometimes dramatically so.</li> + <li>Has significantly higher performance in debug builds, due to less call overhead.</li> + <li>Has extended per-container functionality, particularly for game development.</li> + <li>Has additional containers that are useful for high performance game development.</li> + <li>Is easier to read, trace, and debug.</li> + <li>Memory allocation is much simpler and more controllable.</li> + <li>Has higher portability, as there is a single implementation for all platforms.</li> + <li>Has support of object alignment, whereas such functionality is not natively supported by STL.</li> + <li>We have control over it, so we can modify it as we like.</li> + <li>Has stricter standards for container design and behavior, particularly as this benefits game development.</li> +</ul> +<p class="faq-answer">Ways in which EASTL is worse than standard STL: </p> +<ul> + <li>Standard STL implementations are currently very reliable and weather-worn, whereas EASTL is less tested.</li> + <li>Standard STL is automatically available with just about every C++ compiler vendor's library.</li> + <li>Standard STL is supported by the compiler vendor and somewhat by the Internet community.</li> +</ul> +<p style="font-weight: bold;">EASTL coverage of std STL</p> +<ul style="margin-top: 0in;" type="disc"> + <li>list</li> + <li>vector</li> + <li>deque</li> + <li>string</li> + <li>set</li> + <li>multiset</li> + <li>map</li> + <li>multimap</li> + <li>bitset</li> + <li>queue</li> + <li>stack</li> + <li>priority_queue</li> + <li>memory</li> + <li>numeric</li> + <li>algorithm (all but inplace_merge, prev_permutation, next_permutation, nth_element, includes, unique_copy)</li> + <li>utility</li> + <li>functional</li> + <li>iterator</li> + <li>string_view</li> + <li>variant</li> + <li>any</li> + <li>optional</li> +</ul> +<p>EASTL additions/amendments to std STL</p> +<ul style="margin-top: 0in;" type="disc"> + <li>allocators work in a simpler way.</li> + <li>exception handling can be disabled.</li> + <li>all containers expose/declare their node size, so you can make a node allocator for them.</li> + <li>all containers have reset_lose_memory(), which unilaterally forgets their contents.</li> + <li>all containers have validate() and validate_iterator() functions.</li> + <li>all containers understand and respect object alignment requirements.</li> + <li>all containers guarantee no memory allocation upon being newly created as empty.</li> + <li>all containers and their iterators can be viewed in a debugger (no other STL does this, believe it or not).</li> + <li>linear containers guarantee linear memory.</li> + <li>vector has push_back(void).</li> + <li>vector has a data() function.</li> + <li>vector<bool> is actually a vector of type bool.</li> + <li>vector and string have set_capacity().</li> + <li>string has sprintf(), append_sprintf(), trim(), compare_i(), make_lower(), make_upper().</li> + <li>deque allows you to specify the subarray size.</li> + <li>list has a push_back(void) and push_back(void) function.</li> + <li>hash_map, hash_set, etc. have find_as().</li> +</ul> +<p><span style="font-weight: bold;">EASTL coverage of TR1</span> <font face="Arial" size="2"><span style= +"font-size: 10pt; font-family: Arial;">(tr1 refers to proposed additions for the next C++ standard library, ~2008)</span></font></p> +<ul style="margin-top: 0in;" type="disc"> + <li>array</li> + <li>type_traits (there are about 30 of these)</li> + <li>unordered_set (EASTL calls it hash_set)</li> + <li>unordered_multiset</li> + <li>unordered_map</li> + <li>unordered_multimap</li> + <li>shared_ptr, shared_array, weak_ptr, scoped_ptr, scoped_array, intrusive_ptr</li> +</ul> +<p><span style="font-weight: bold;">EASTL additional functionality</span> <font face="Arial" size="1"><span style= +"font-size: 9pt; font-family: Arial;">(not found elsewhere)</span></font></p> +<ul style="margin-top: 0in;" type="disc"> + <li>fixed_list</li> + <li>fixed_slist</li> + <li>fixed_vector</li> + <li>fixed_string</li> + <li>fixed_substring</li> + <li>fixed_set</li> + <li>fixed_multiset</li> + <li>fixed_map</li> + <li>fixed_multimap</li> + <li>fixed_hash_set</li> + <li>fixed_hash_multiset</li> + <li>fixed_hash_map</li> + <li>fixed_hash_multimap</li> + <li>fixed_function</li> + <li>vector_set</li> + <li>vector_multiset</li> + <li>vector_map</li> + <li>vector_multimap</li> + <li>intrusive_list</li> + <li>intrusive_slist</li> + <li>intrusive_sdlist</li> + <li>intrusive_hash_set</li> + <li>intrusive_hash_multiset</li> + <li>intrusive_hash_map</li> + <li>intrusive_hash_multimap</li> + <li>slist (STLPort's STL has this)</li> + <li>heap</li> + <li>linked_ptr, linked_array</li> + <li>sparse_matrix (this is not complete as of this writing)</li> + <li>ring_buffer</li> + <li>compressed_pair</li> + <li>call_traits</li> + <li>binary_search_i, change_heap, find_first_not_of, find_last_of, find_last_not_of, identical</li> + <li>comb_sort, bubble_sort, selection_sort, shaker_sort, bucket_sort</li> + <li>equal_to_2, not_equal_to_2, str_equal_to, str_equal_to_i<br> + </li> +</ul> +<p class="faq-question"> <a name="Info.4"></a>Info.4 +Is EASTL thread-safe? +</p> +<p class="faq-answer">It's not simple enough to simply say that EASTL is thread-safe or thread-unsafe. However, we can say that with respect to thread safety that EASTL does the right thing.</p> +<p class="faq-answer">Individual EASTL containers are not thread-safe. That is, access to an instance of a container from multiple threads at the same time is unsafe if any of those accesses are modifying operations. A given container can be read from multiple threads simultaneously as well as any other standalone data structure. If a user wants to be able to have modifying access an instance of a container from multiple threads, it is up to the user to ensure that proper thread synchronization occurs. This usually means using a mutex.</p> +<p class="faq-answer">EASTL classes other than containers are the same as containers with respect to thread safety. EASTL functions (e.g. algorithms) are inherently thread-safe as they have no instance data and operate entirely on the stack. As of this writing, no EASTL function allocates memory and thus doesn't bring thread safety issues via that means.</p> +<p class="faq-answer">The user may well need to be concerned about thread safety with respect to memory allocation. If the user modifies containers from multiple threads, then allocators are going to be accessed from multiple threads. If an allocator is shared across multiple container instances (of the same type of container or not), then mutexes (as discussed above) the user uses to protect access to individual instances will not suffice to provide thread safety for allocators used across multiple instances. The conventional solution here is to use a mutex within the allocator if it is expected to be used by multiple threads.</p> +<p class="faq-answer">EASTL uses neither static nor global variables and thus there are no inter-instance dependencies that would make thread safety difficult for the user to implement.</p> +<p class="faq-question"><a name="Info.5"></a>Info.5 +What platforms/compilers does EASTL support?</p> +<p class="faq-answer">EASTL's support depends entirely on the compiler and not on the platform. EASTL works on any C++ compiler that completely conforms the C++ language standard. Additionally, EASTL is 32 bit and 64 bit compatible. Since EASTL does not use the C or C++ standard library <small><span style= +"font-family: Arial Narrow;">(with a couple small exceptions)</span></small>, it doesn't matter what kind of libraries are provided (or not provided) by the compiler vendor. However, given that we need to work with some compilers that aren't 100% conforming to the language standard, it will be useful to make a list here of these that are supported and those that are not:</p> +<blockquote> + <table border="1"> + <tr> + <th scope="col">Compiler</th> + <th scope="col">Status</th> + <th scope="col">Notes</th> + </tr> + <tr> + <td>GCC 3.x+</td> + <td>Not Supported</td> + <td>Not officially supported due to migration to Clang.</td> + </tr> + <tr> + <td>MSVC 12.0+</td> + <td>Supported</td> + <td>This compiler is used by the Windows based platforms</td> + </tr> + <tr> + <td>Clang 4.0+</td> + <td>Supported</td> + <td>This compiler is used by the Linux based platforms</td> + </tr> + </table> +</blockquote> +<p class="faq-question"><a name="Info.6"></a>Info.6 +Why is there EASTL when there is the STL?</p> +<p class="faq-answer">The STL is largely a fine library for general purpose C++. However, we can improve upon it for our uses and gain other advantages as well. The primary motivations for the existence of EASTL are the following:</p> +<ul> + <li class="458151900-03082005"><font><font>Some STL implementations (especially Microsoft STL) have inferior performance characteristics that make them unsuitable for game development. EASTL is faster than all existing STL implementations.</font></font></li> + <li>The STL is sometimes hard to debug, as most STL implementations use cryptic variable names and unusual data structures.</li> + <li>STL allocators are sometimes painful to work with, as they have many requirements and cannot be modified once bound to a container.</li> + <li>The STL includes excess functionality that can lead to larger code than desirable. It's not very easy to tell programmers they shouldn't use that functionality.</li> + <li>The STL is implemented with very deep function calls. This results is unacceptable performance in non-optimized builds and sometimes in optimized builds as well.</li> + <li>The STL doesn't support alignment of contained objects.</li> + <li>STL containers won't let you insert an entry into a container without supplying an entry to copy from. This can be inefficient.</li> + <li>Useful STL extensions (e.g. slist, hash_map, shared_ptr) found in existing STL implementations such as STLPort are not portable because they don't exist in other versions of STL or aren't consistent between STL versions.<br> + </li> + <li>The STL lacks useful extensions that game programmers find useful (e.g. intrusive_list) but which could be best optimized in a portable STL environment.</li> + <li>The STL puts an emphasis on correctness before performance, whereas sometimes you can get significant performance gains by making things less academically pure.</li> + <li>STL containers have private implementations that don't allow you to work with their data in a portable way, yet sometimes this is an important thing to be able to do (e.g. node pools).</li> + <li>All existing versions of STL allocate memory in empty versions of at least some of their containers. This is not ideal and prevents optimizations such as container memory resets that can greatly increase performance in some situations.</li> + <li>The STL is slow to compile, as most modern STL implementations are very large.<br> + </li> + <li>There are legal issues that make it hard for us to freely use portable STL implementations such as STLPort.</li> + <li>We have no say in the design and implementation of the STL and so are unable to change it to work for our needs.</li> +</ul> +<p class="faq-answer">Note that there isn't actually anything in the C++ standard called "STL." STL is a term that merely refers to the templated portion of the C++ standard library.</p> +<p class="faq-question"><a name="Info.7"></a>Info.7 +Can I mix EASTL with standard C++ STL?</p> +<p class="faq-answer">This is possible to some degree, though the extent depends on the implementation of C++ STL. One of things that makes interoperability is something called iterator categories. Containers and algorithms recognize iterator types via their category and STL iterator categories are not recognized by EASTL and vice versa.<br> +<br> +Things that you definitely can do: </p> +<ul> + <li>#include both EASTL and standard STL headers from the same .cpp file.</li> + <li>Use EASTL containers to hold STL containers.</li> + <li>Construct an STL reverse_iterator from an EASTL iterator.</li> + <li>Construct an EASTL reverse_iterator from an STL iterator.</li> +</ul> +<p class="faq-answer">Things that you probably will be able to do, though a given std STL implementation may prevent it: +</p> +<ul> + <li>Use STL containers in EASTL algorithms.</li> + <li>Use EASTL containers in STL algorithms.</li> + <li>Construct or assign to an STL container via iterators into an EASTL container.</li> + <li>Construct or assign to an EASTL container via iterators into an STL container.</li> +</ul> +<p class="faq-answer">Things that you would be able to do if the given std STL implementation is bug-free: +</p> +<ul> + <li>Use STL containers to hold EASTL containers. Unfortunately, VC7.x STL has a confirmed bug that prevents this. Similarly, STLPort versions prior to v5 have a similar but.</li> +</ul> +<p class="faq-answer">Things that you definitely can't do:</p> +<ul> + <li>Use an STL allocator directly with an EASTL container (though you can use one indirectly).</li> + <li>Use an EASTL allocator directly with an STL container (though you can use one indirectly).</li> +</ul> +<p class="faq-question"> <a name="Info.8"></a>Info.8 +Where can I learn more about STL and EASTL? +</p> +<p class="faq-answer">EASTL is close enough in philosophy and functionality to standard C++ STL that most of what you read about STL applies to EASTL. This is particularly useful with respect to container specifications. It would take a lot of work to document EASTL containers and algorithms in fine detail, whereas most standard STL documentation applies as-is to EASTL. We won't cover the differences here, as that's found in another FAQ entry.</p> +<p class="faq-answer">That being said, we provide a list of sources for STL documentation that may be useful to you, especially if you are less familiar with the concepts of STL and template programming in general.</p> +<ul> + <li>The SGI STL web site. Includes a good STL reference.</li> + <li>CodeProject STL introduction.</li> + <li>Scott Meyers Effective STL book.</li> + <li>The Microsoft online STL documentation. Microsoft links go bad every couple months, so try searching for STL at the Microsoft MSDN site.</li> + <li>The Dinkumware online STL documentation. </li> + <li>The C++ standard, which is fairly readable. You can buy an electronic version for about $18 and in the meantime you can make do with draft revisions of it off the Internet by searching for "c++ draft standard".</li> + <li>STL performance tips, by Pete Isensee</li> + <li>STL algorithms vs. hand-written loops, by Scott Meyers.</li> + <li>cppreference.com</li> + <li>isocpp.org<li> +</ul> +<p class="faq-question"><a name="Info.9"></a>Info.9 +What is the legal status of EASTL?</p> +<p class="faq-answer">EASTL is usable for all uses within Electronic Arts, both for internal usage and for shipping products for all platforms. Any externally derived code would be explicitly stated as such and approved by the legal department if such code ever gets introduced. As of EASTL v1.0, the red_black_tree.cpp file contains two functions derived from the original HP STL and have received EA legal approval for usage in any product.</p> +<p class="faq-question"><a name="Info.10"></a>Info.10 +Does EASTL deal with compiler exception handling settings?</p> +<p class="faq-answer">EASTL has automatic knowledge of the compiler's enabling/disabling of exceptions. If your compiler is set to disable exceptions, EASTL automatically detects so and executes without them. Also, you can force-enable or force-disable that setting to override the automatic behavior by #defining EASTL_EXCEPTIONS_ENABLED to 0 or 1. See EASTL's config.h for more information.</p> +<p class="faq-question"> <a name="Info.11"></a>Info.11 + What C++ language features does EASTL use (e.g. virtual +functions)?</p> +<p class="faq-answer">EASTL uses the following C++ language features: </p> +<ul> + <li>Template functions, classes, member functions.</li> + <li>Multiple inheritance.</li> + <li>Namespaces.</li> + <li>Operator overloading.</li> +</ul> +<p class="faq-answer">EASTL does not use the following C++ language features: +</p> +<ul> + <li>Virtual functions / interfaces.</li> + <li>RTTI (dynamic_cast).</li> + <li>Global and static variables. There are a couple class static const variables, but they act much like enums.</li> + <li>Volatile declarations</li> + <li>Template export.</li> + <li>Virtual inheritance.</li> +</ul> +<p class="faq-answer">EASTL may use the following C++ language features: +</p> +<ul> + <li>Try/catch. This is an option that the user can enable and it defaults to whatever the compiler is set to use.</li> + <li>Floating point math. Hash containers have one floating point calculation, but otherwise floating point is not used.</li> +</ul> +<p class="faq-answer">Notes: +</p> +<ul> + <li>EASTL uses rather little of the standard C or C++ library and uses none of the C++ template library (STL) and iostream library. The memcpy family of functions is one example EASTL C++ library usage.</li> + <li>EASTL never uses global new / delete / malloc / free. All allocations are done via user-specified allocators, though a default allocator definition is available.</li> +</ul> +<p class="faq-question"><a name="Info.12"></a>Info.12 + What compiler warning levels does EASTL support? +</p> +<p class="faq-answer">For VC++ EASTL should compile without warnings on level 4, and should compile without warnings for "warnings disabled by default" except C4242, C4514, C4710, C4786, and C4820. These latter warnings are somewhat draconian and most EA projects have little choice but to leave them disabled.</p> +<p class="faq-answer">For GCC, EASTL should compile without warnings with -Wall. Extensive testing beyond that hasn't been done.</p> +<p class="faq-answer">However, due to the nature of templated code generation and due to the way compilers compile templates, unforeseen warnings may occur in user code that may or may not be addressable by modifying EASTL.</p> +<p class="faq-question"><a name="Info.13"></a>Info.13 + Is EASTL compatible with Lint? +</p> +<p class="faq-answer">As of EASTL 1.0, minimal lint testing has occurred. Testing with the November 2005 release of Lint (8.00t) demonstrated bugs in Lint that made its analysis not very useful. For example, Lint seems to get confused about the C++ typename keyword and spews many errors with code that uses it. We will work with the makers of Lint to get this resolved so that Lint can provide useful information about EASTL.</p> +<p class="faq-question"><a name="Info.14"></a>Info.14 + What compiler settings do I need to compile EASTL? +</p> +<p class="faq-answer">EASTL consists mostly of header files with templated C++ code, but there are also a few .cpp files that need to be compiled and linked in order to use some of the modules. EASTL will compile in just about any environment. As mentioned elsewhere in this FAQ, EASTL can be compiled at the highest warning level of most compilers, transparently deals with compiler exception handling settings, is savvy to most or all compilation language options (e.g. wchar_t is built-in or not, for loop variables are local or not), and has almost no platform-specific or compiler-specific code. For the most part, you can just drop it in and it will work. The primary thing that needs to be in place is that EASTL .cpp files need to be compiled with the same struct padding/alignment settings as other code in the project. This of course is the same for just about any C++ source code library.</p> +<p class="faq-answer">See the Performance section of this FAQ for a discussion of the optimal compiler settings for EASTL performance.</p> +<p class="faq-question"><a name="Info.15"></a>Info.15 +How hard is it to incorporate EASTL into my project?</p> +<p>It's probably trivial.<br> + <br> +EASTL has only one dependency: EABase. And EASTL auto-configures itself for most compiler environments and for the most typical configuration choices. Since it is fairly highly warning-free, you won't likely need to modify your compiler warning settings, even if they're pretty strict. EASTL has a few .cpp files which need to be compiled if you want to use the modules associated with those files. You can just compile those files with your regular compiler settings. Alternatively, you can use one of the EASTL project files.<br> +<br> +In its default configuration, the only thing you need to provide to make EASTL work is to define implementations of the following operator new functions:</p> +<pre class="code-example">#include <new><br> +void* operator new[](size_t size, const char* pName, int flags, unsigned debugFlags, const char* file, int line); +void* operator new[](size_t size, size_t alignment, size_t alignmentOffset, const char* pName, int flags, unsigned debugFlags, const char* file, int line);</pre> +The flags and debugFlags arguments correspond to PPMalloc/RenderWare GeneralAllocator/GeneralAllocatorDebug Malloc equivalents.<br> +<p class="faq-question"><a name="Info.16"></a>Info.16 +Should I use EASTL instead of std STL or instead of my custom library?</p> +<p class="faq-answer">There are reasons you may want to use EASTL; there are reasons you may not want to use it. Ditto for std STL or any other library. Here we present a list of reasons (+ and -) for why you might want to use one or another. However, it should be noted that while EASTL contains functionality found in std STL, it has another ~40% of functionality not found in std STL, so EASTL and std STL (and whatever other template library you may have) are not mutually exclusive.<br> +<br> +<span style="font-weight: bold;">EASTL</span><br> +</p> +<div class="faq-answer" style="margin-left: 40px;"><span style="font-family: Courier New,Courier,monospace;">+</span> Has higher performance than any commercial STL, especially on console platforms.<br> + <span style="font-family: Courier New,Courier,monospace;">+</span> Has extended functionality tailored for game development.<br> + <span style="font-family: Courier New,Courier,monospace;">+</span> Is highly configurable, and we own it so it can be amended at will. Std STL is owned by a third party committee.<br> + <span style="font-family: Courier New,Courier,monospace;">+</span> Is much easier to read and debug than other similar libraries, especially std STL.<br> + <br> + <span style="font-family: Courier New,Courier,monospace;">-</span> Is highly unit tested, but does not have the same level as std STL.<br> + <span style="font-family: Courier New,Courier,monospace;">-</span> Is more complicated than many users' lite template libraries, and may put off some beginners.<br> +<span style="font-family: Courier New,Courier,monospace;">-</span> EASTL </div> +<p> <span class="faq-answer" style="font-weight: bold;">Std STL</span> +</p> +<div class="faq-answer" style="margin-left: 40px;"><span style="font-family: Courier New,Courier,monospace;">+</span> Is highly portable; your STL code will likely compile and run anywhere.<br> + <span style="font-family: Courier New,Courier,monospace;">+</span> Works without the need to install or download any package to use it. It just works.<br> + <span style="font-family: Courier New,Courier,monospace;">+</span> Is highly reliable and supported by the compiler vendor. You can have confidence in it.<br> + <span style="font-family: Courier New,Courier,monospace;">+</span> Some std STL versions (e.g. STLPort, VC8 STL) have better runtime debug checking than EASTL.<br> + <br> + <span style="font-family: Courier New,Courier,monospace;">-</span> Has (sometimes greatly) variable implementations, behavior, and performance between implementations.<br> + <span style="font-family: Courier New,Courier,monospace;">-</span> Is usually hard to read and debug.<br> + <span style="font-family: Courier New,Courier,monospace;">-</span> Doesn't support some of the needs of game development, such as aligned allocations, named allocations, intrusive containers, etc.<br> +<span style="font-family: Courier New,Courier,monospace;">-</span> Is not as efficient as EASTL, especially on console platforms.</div> +<p> <span class="faq-answer" style="font-weight: bold;">Your own library</span> +</p> +<div class="faq-answer" style="margin-left: 40px;">(please forgive us for implying there may be weaknesses in your libraries)<br> + + <p></p> + <span style="font-family: Courier New,Courier,monospace;">+</span> You have control over it and can make it work however you want.<br> + <span style="font-family: Courier New,Courier,monospace;">+</span> You can fix bugs in it on the spot and have the fix in your codebase immediately.<br> + <span style="font-family: Courier New,Courier,monospace;">+</span> Your own library can be highly integrated into your application code or development environment.<br> + <br> + <span style="font-family: Courier New,Courier,monospace;">-</span> Many custom libraries don't have the same level of testing as libraries such as std STL or EASTL.<br> + <span style="font-family: Courier New,Courier,monospace;">-</span> Many custom libraries don't have the same breadth or depth as std STL or especially EASTL.<br> +<span style="font-family: Courier New,Courier,monospace;">-</span> Many custom libraries don't have the level of performance tuning that std STL or especially EASTL has.</div> +<p class="faq-question"><a name="Info.17"></a>Info.17 +I think I've found a bug. What do I do?</p> +<p class="faq-answer"><span style="font-weight: bold;">Verify that you indeed have a bug</span><br> +There are various levels of bugs that can occur, which include the following: </p> +<ol> + <li>Compiler warnings generated by EASTL.</li> + <li>Compiler errors generated by EASTL (failure to compile well-formed code).</li> + <li>Runtime misbehavior by EASTL (function does the wrong thing).</li> + <li>Runtime crash or data corruption by EASTL.</li> + <li>Mismatch between EASTL documentation and behavior.</li> + <li>Mismatch between EASTL behavior and user's expectations (mis-design).</li> +</ol> +<p class="faq-answer">Any of the above items can be the fault of EASTL. However, the first four can also be the fault of the user. Your primary goal in verifying a potential bug is to determine if it is an EASTL bug or a user bug. Template errors can sometimes be hard to diagnose. It's probably best if you first show the problem to somebody you know to make sure you are not missing something obvious. Creating a reproducible case may be useful in helping convince yourself, but as is mentioned below, this is not required in order to report the bug.<br> + <br> + <span style="font-weight: bold;">Report the bug</span><br> +The first place to try is the standard EA centralized tech support site. As of this writing (10/2005), that tech site is <a href="http://eatech/">http://eatech/</a>. Due to the frequent technology churn that seems to occur within Electronic Arts, the bug reporting system in place when you read this may not be the one that was in place when this FAQ entry was written. If the tech site route fails, consider directly contacting the maintainer of the EASTL package.<br> +<br> +In reporting a bug, it is nice if there is a simple reproducible case that can be presented. However, such a case requires time to create, and so you are welcome to initially simply state what you think the bug is without producing a simple reproducible case. It may be that this is a known bug or it may be possible to diagnose the bug without a reproducible case. If more information is needed then the step of trying to produce a reproducible case may be necessary.</p> +<p class="faq-question"><a name="Info.18"></a>Info.18 + Can EASTL be used by third party EA developers?</p> +<p class="faq-answer">EASTL and other core technologies authored by EA (and not licensed from other companies) can be used in source and binary form by designated 3rd parties. The primary case where there is an issue is if the library contains platform specific code for a platform that the 3rd party is not licensed for. In that case the platform-specific code would need to be removed. This doesn’t apply to EASTL, nor many of the other core tech packages. </p> +<h2><span style="font-weight: bold;">Performance</span> +</h2> + +<p class="faq-question"><a name="Perf.1"></a>Perf.1 How efficient is EASTL compared to standard C++ STL implementations?</p> +<p class="faq-answer">With respect to the functionality that is equivalent between EASTL and standard STL, the short answer to this is that EASTL is as at least as efficient as other STL implementations and in a number of aspects is more so. EASTL has functionality such as intrusive_list and linked_ptr that don't exist in standard STL but are explicitly present to provide significant optimizations over standard STL.</p> +<p class="faq-answer">The medium length answer is that EASTL is significantly more efficient than Dinkumware STL, and Microsoft Windows STL. EASTL is generally more efficient than Metrowerks STL, but Metrowerks has a few tricks up its sleeve which EASTL doesn't currently implement. EASTL is roughly equal in efficiency to STLPort and GCC 3.x+ STL, though EASTL has some optimizations that these do not.</p> +<p class="faq-answer">The long answer requires a breakdown of the functionality between various versions of the STL.</p> + +<p class="faq-question"><a name="Perf.2"></a>Perf.2 How efficient is EASTL in general?</p> +<p class="faq-answer">This question is related to the question, "How efficient are templates?" If you understand the effects of templates then you can more or less see the answer for EASTL. Templates are more efficient than the alternative when they are used appropriately, but can be less efficient than the alternative when used under circumstances that don't call for them. The strength of templates is that the compiler sees all the code and data types at compile time and can often reduce statements to smaller and faster code than with conventional non-templated code. The weakness of templates is that the sometimes produce more code and can result in what is often called "code bloat". However, it's important to note that unused template functions result in no generated nor linked code, so if you have a templated class with 100 functions but you only use one, only that one function will be compiled.</p> +<p class="faq-answer">EASTL is a rather efficient implementation of a template library and pulls many tricks of the trade in terms of squeezing optimal performance out of the compiler. The only way to beat it is to write custom code for the data types you are working with, and even then people are sometimes surprised to find that their hand-implemented algorithm works no better or even worse than the EASTL equivalent. But certainly there are ways to beat templates, especially if you resort to assembly language programming and some kinds of other non-generic tricks.</p> + +<p class="faq-question"> <a name="Perf.3"></a>Perf.3 Strings don't appear to use the "copy-on-write" (CoW) optimization. Why not?</p> +<p class="faq-answer"> +<span style="font-weight: bold;">Short answer</span><br> +CoW provides a benefit for a small percentage of uses but provides a disadvantage for the large majority of uses.<br> +<br> +<span style="font-weight: bold;">Long answer</span><br> +The primary benefit of CoW is that it allows for the sharing of string data between two string objects. Thus if you say this: +<pre class="code-example">string a("hello"); +string b(a);</pre> +the "hello" will be shared between a and b. If you then say this: +<pre class="code-example">a = "world";</pre> +then <span style="font-family: Courier New;">a</span> will release its reference to "hello" and +leave b with the only reference to it. Normally this functionality is accomplished via reference +counting and with atomic operations or mutexes.</p> + +<p class="faq-answer">The C++ standard does not say anything about basic_string and CoW. +However, for a basic_string implementation to be standards-conforming, a number of issues arise +which dictate some things about how one would have to implement a CoW string. The discussion of +these issues will not be rehashed here, as you can read the references below for better detail +than can be provided in the space we have here. However, we can say that the C++ standard +is sensible and that anything we try to do here to allow for an efficient CoW implementation +would result in a generally unacceptable string interface.</p> +<p class="faq-answer">The disadvantages of CoW strings are:</p> +<ul> + <li>A reference count needs to exist with the string, which increases string memory usage.</li> + <li>With thread safety, atomic operations and mutex locks are expensive, especially on weaker memory systems such as console gaming platforms.</li> + <li>All non-const string accessor functions need to do a sharing check and the first such check needs to detach the string. Similarly, all string assignments need to do a sharing check as well. If you access the string before doing an assignment, the assignment doesn't result in a shared string, because the string has already been detached.</li> + <li>String sharing doesn't happen the large majority of the time. In some cases, the total sum of the reference count memory can exceed any memory savings gained by the strings that share representations.</li> +</ul> +<p class="faq-answer">The addition of a cow_string class is under consideration for EASTL. There are conceivably some systems which have string usage patterns which would benefit from CoW sharing. Such functionality is best saved for a separate string implementation so that the other string uses aren't penalized.</p> +<p class="faq-answer">References</p> +<p class="faq-answer">This is a good starting HTML reference on the topic:<br> + <a href="http://www.gotw.ca/publications/optimizations.htm">http://www.gotw.ca/publications/optimizations.htm</a></p> +<p class="faq-answer">Here is a well-known Usenet discussion on the topic:<br> + <a href="http://groups-beta.google.com/group/comp.lang.c++.moderated/browse_thread/thread/3dc6af5198d0bf7/886c8642cb06e03d">http://groups-beta.google.com/group/comp.lang.c++.moderated/browse_thread/thread/3dc6af5198d0bf7/886c8642cb06e03d</a></p> + +<p class="faq-question"><a name="Perf.4"></a>Perf.4 Does EASTL cause code bloat, given that it uses templates?</p> +<p class="faq-answer"> The reason that templated functions and classes might cause an increase in code size +because each template instantiation theoretically creates a unique piece of code. For example, when you compile this +code:</p> +<pre class="code-example">template <typename T> +const T min(const T a, const T b) + { return b < a ? b : a; } + +int i = min<int>(3, 4); +double d = min<double>(3.0, 4.0);</pre> +<p class="faq-answer">the compiler treats it as if you wrote this:</p> +<pre class="code-example">int min(const int a, const int b) + { return b < a ? b : a; }<br> +double min(const double a, const double b) + { return b < a ? b : a; }</pre> +<p class="faq-answer">Imagine this same effect happening with containers such as list and map and you can see how it is that templates can cause code proliferation.</p> +<p class="faq-answer">A couple things offset the possibility of code proliferation: inlining and folding. In practice the above 'min' function would be converted to inlined functions by the compiler which occupy only a few CPU instructions. In many of the simplest cases the inlined version actually occupies less code than the code required to push parameters on the stack and execute a function call. And they will execute much faster as well.</p> +<p class="faq-answer">Code folding (a.k.a. "COMDAT folding", "duplicate stripping", "ICF" / "identical code folding") is a compiler optimization whereby the compiler realizes that two independent functions have compiled to the same code and thus can be reduced to a single function. The Microsoft VC++ compiler (Since VS2005), and GCC (v 4.5+) can do these kinds of optimizations on all platforms. This can result, for example, in all templated containers of pointers (e.g. vector<char*>, vector<Widget*>, etc.) to be linked as a single implementation. This folding occurs at a function level and so individual member functions can be folded while other member functions are not. A side effect of this optimization is that you aren't likely to gain much much declaring containers of void* instead of the pointer type actually contained.</p> +<p class="faq-answer">The above two features reduce the extent of code proliferation, but certainly don't eliminate it. What you need to think about is how much code might be generated vs. what your alternatives are. Containers like vector can often inline completely away, whereas more complicated containers such as map can only partially be inlined. In the case of map, if you need such a container for your Widgets, what alternatives do you have that would be more efficient than instantiating a map? This is up to you to answer.</p> +<p class="faq-answer">It's important to note that C++ compilers will throw away any templated functions that aren't used, including unused member functions of templated classes. However, some argue that by having many functions available to the user that users will choose to use that larger function set rather than stick with a more restricted set.</p> +<p class="faq-answer">Also, don't be confused by syntax bloat vs. code bloat. In looking at templated libraries such as EASTL you will notice that there is sometimes a lot of text in the definition of a template implementation. But the actual underlying code is what you need to be concerned about.</p> +<p class="faq-answer">There is a good Usenet discussion on this topic at: <small><a href= +"http://groups.google.com/group/comp.lang.c++.moderated/browse_frm/thread/2b00649a935997f5">http://groups.google.com/group/comp.lang.c++.moderated/browse_frm/thread/2b00649a935997f5</a></small></p> +<p class="faq-question"><a name="Perf.5"></a>Perf.5 +Don't STL and EASTL containers fragment memory?</p> +<p class="faq-answer">They only fragment memory if you use them in a way that does so. This is no different from any other type of container used in a dynamic way. There are various solutions to this problem, and EASTL provides additional help as well:</p> +<ul> + <li>For vectors, use the reserve function (or the equivalent constructor) to set aside a block of memory for the container. The container will not reallocate memory unless you try grow beyond the capacity you reserve.</li> + <li>EASTL has "fixed" variations of containers which allow you to specify a fixed block of memory which the container uses for its memory. The container will not allocate any memory with these types of containers and all memory will be cache-friendly due to its locality.</li> + <li>You can assign custom allocators to containers instead of using the default global allocator. You would typically use an allocator that has its own private pool of memory.</li> + <li>Where possible, add all a container's elements to it at once up front instead of adding them over time. This avoids memory fragmentation and increase cache coherency.</li> +</ul> + +<p class="faq-question"><a name="Perf.6"></a>Perf.6 I don't see container optimizations for equivalent scalar types such as pointer types. Why?</p> +<p class="faq-answer">Metrowerks (and no other, as of this writing) STL has some container specializations for type +T* which maps them to type void*. The idea is that a user who declares a list of Widget* and a list of Gadget* +will generate only one container: a list of void*. As a result, code generation will be smaller. Often this is +done only in optimized builds, as such containers are harder to view in debug builds due to type information being lost.<br> +<br> +The addition of this optimization is under consideration for EASTL, though it might be noted that optimizing +compilers such as VC++ are already capable of recognizing duplicate generated code and folding it automatically +as part of link-time code generation (LTCG) (a.k.a. "whole program optimization"). This has been verified +with VC++, as the following code and resulting disassembly demonstrate:</p> +<pre class="code-example">eastl::list<int*> intPtrList; +eastl::list<TestObject*> toPtrList; + +eastl_size_t n1 = intPtrList.size(); +eastl_size_t n2 = toPtrList.size(); + +0042D288 lea edx,[esp+14h] +0042D28C <span style="color: rgb(51, 51, 255);">call eastl::list<TestObject>::size (414180h)</span> +0042D291 push eax +0042D292 lea edx,[esp+24h] +0042D296 <span style="color: rgb(51, 51, 255);">call eastl::list<TestObject>::size (414180h)</span></pre> +<p class="faq-answer">Note that in the above case the compiler folded the two implementations of size() into a single implementation.</p> + +<p class="faq-question"><a name="Perf.7"></a>Perf.7 +I've seen some STL's provide a default quick "node allocator" as the default allocator. Why doesn't EASTL do this?</p> +<p class="faq-answer"><span style="font-weight: bold;">Short answer<br> +</span>This is a bad, misguided idea.</p> +<p class="faq-answer"><span style="font-weight: bold;">Long answer</span><br> +These node allocators implement a heap for all of STL with buckets for various sizes of allocations and implemented fixed-size pools for each of these buckets. These pools are attractive at first because they do well in STL comparison benchmarks, especially when thread safety is disabled. Such benchmarks make it impossible to truly compare STL implementations because you have two different allocators in use and in some cases allocator performance can dominate the benchmark. However, the real problem with these node allocators is that they badly fragment and waste memory. The technical discussion of this topic is outside the scope of this FAQ, but you can learn more about it by researching memory management on the Internet. Unfortunately, the people who implement STL libraries are generally not experts on the topic of memory management. A better approach, especially for game development, is for the user to decide when fixed-size pools are appropriate and use them via custom allocator assignment to containers.</p> +<p class="faq-question"><a name="Perf.8"></a>Perf.8 Templates sometimes seem to take a long time to compile. Why do I do about that? +</p> +<p class="faq-answer">C++ compilers are generally slower than C compilers, and C++ templates are generally slower to compile than regular C++ code. EASTL has some extra functionality (such as type_traits and algorithm specializations) that is not found in most other template libraries and significantly improves performance and usefulness but adds to the amount of code that needs to be compiled. Ironically, we have a case where more source code generates faster and smaller object code.</p> +<p class="faq-answer">The best solution to the problem is to use pre-compiled headers, which are available on all modern ~2002+) compilers, such as VC6.0+, GCC 3.2+, and Metrowerks 7.0+. In terms of platforms this means all 2002+ platforms.</p> +<p class="faq-answer">Some users have been speeding up build times by creating project files that put all the source code in one large .cpp file. This has an effect similar to pre-compiled headers. It can go even faster than pre-compiled headers but has downsides in the way of convenience and portability.</p> +<p class="faq-question"><a name="Perf.10"></a>Perf.10 +How well does EASTL inline?</p> +<p class="faq-answer">EASTL is written in such as way as to be easier to inline than typical templated libraries such as STL. How is this so? It is so because EASTL reduces the inlining depth of many functions, particularly the simple ones. In doing so it makes the implementation less "academic" but entirely correct. An example of this is the vector operator[] function, which is implemented like so with Microsoft STL:</p> +<pre class="code-example">reference operator[](size_type n) { + return *(begin() + n); +}</pre> +<span class="faq-answer">EASTL implements the function directly, like so:</span> +<pre class="code-example">reference operator[](size_type n) { + return *(mpBegin + n); +}</pre> +<span class="faq-answer">Both implementations are correct, but the EASTL implementation will run faster in debug builds, be easier to debug, and will be more likely to be inlined when the usage of this function is within a hierarchy of other functions being inlined. It is not so simple to say that the Microsoft version will always inline in an optimized build, as it could be part of a chain and cause the max depth to be exceeded.<br> +<br> +That being said, EASTL appears to inline fairly well under most circumstances, including with GCC, which is the poorest of the compilers in its ability to inline well.</span> +<p class="faq-question"><a name="Perf.11"></a>Perf.11 +How do I control function inlining?</p> +<p class="faq-answer">Inlining is an important topic for templated code, as such code often relies on the compiler being able to do good function inlining for maximum performance. GCC, VC++, and Metrowerks are discussed here. We discuss compilation-level inlining and function-level inlining here, though the latter is likely to be of more use to the user of EASTL, as it can externally control how EASTL is inlined. A related topic is GCC's template expansion depth, discussed <a href= +"file:///f:/Projects/SharedProjects/Core/EASTL/doc/EASTL%20FAQ.html#29">elsewhere</a> in this FAQ. We provide descriptions of inlining options here but don't currently have any advice on how to best use these with EASTL.</p> +<p class="faq-answer">Compilation-Level Inlining -- VC++</p> +<p class="faq-answer">VC++ has some basic functionality to control inlining, and the compiler is pretty good at doing aggressive inlining when optimizing on for all platforms.</p> +<blockquote> + <p class="faq-answer"><small><span style="font-family: Courier New;"> #pragma inline_depth( [0... 255] )</span></small></p> + <p class="faq-answer">Controls the number of times inline expansion can occur by controlling the number of times that a series of function calls can be expanded (from 0 to 255 times). This pragma controls the inlining of functions marked inline and or inlined automatically under the /Ob2 option. The inline_depth pragma controls the number of times a series of function calls can be expanded. For example, if the inline depth is 4, and if A calls B and B then calls C, all three calls will be expanded inline. However, if the closest inline expansion is 2, only A and B are expanded, and C remains as a function call.</p> + <p class="faq-answer"><small><span style="font-family: Courier New;">#pragma inline_recursion( [{on | off}] )</span></small></p> + <p class="faq-answer">Controls the inline expansion of direct or mutually recursive function calls. Use this pragma to control functions marked as inline and or functions that the compiler automatically expands under the /Ob2 option. Use of this pragma requires an /Ob compiler option setting of either 1 or 2. The default state for inline_recursion is off. The inline_recursion pragma controls how recursive functions are expanded. If inline_recursion is off, and if an inline function calls itself (either directly or indirectly), the function is expanded only once. If inline_recursion is on, the function is expanded multiple times until it reaches the value set by inline_depth, the default value of 8, or a capacity limit.</p> +</blockquote> +<p class="faq-answer">Compilation-Level Inlining -- GCC</p> +<p class="faq-answer">GCC has a large set of options to control function inlining. Some options are available only in GCC 3.0 and later and thus not present on older platforms.</p> +<blockquote> + <table style="text-align: left; width: 100%;" border="1" cellpadding="2" cellspacing="2"> + <tbody> + <tr> + <td>-fno-default-inline</td> + <td>Do not make member functions inline by default merely because they are defined inside the class scope (C++ only). Otherwise, when you specify -O, member functions defined inside class scope are compiled inline by default; i.e., you don't need to add `inline' in front of the member function name.</td> + </tr> + <tr> + <td>-fno-inline</td> + <td>Don't pay attention to the inline keyword. Normally this option is used to keep the compiler from expanding any functions inline. Note that if you are not optimizing, no functions can be expanded inline.</td> + </tr> + <tr> + <td>-finline-functions</td> + <td>Integrate all simple functions into their callers. The compiler heuristically decides which functions are simple enough to be worth integrating in this way. If all calls to a given function are integrated, and the function is declared static, then the function is normally not output as assembler code in its own right. Enabled at level -O3.</td> + </tr> + <tr> + <td>-finline-limit=n</td> + <td>By default, GCC limits the size of functions that can be inlined. This flag allows the control of this limit for functions that are explicitly marked as inline (i.e., marked with the inline keyword or defined within the class definition in c++). n is the size of functions that can be inlined in number of pseudo instructions (not counting parameter handling). pseudo-instructions are an internal representation of function size. The default value of n is 600. Increasing this value can result in more inlined code at the cost of compilation time and memory consumption. Decreasing usually makes the compilation faster and less code will be inlined (which presumably means slower programs). This option is particularly useful for programs that use inlining heavily such as those based on recursive templates with C++.<br> + <br> + Inlining is actually controlled by a number of parameters, which may be specified individually by using --param name=value. The -finline-limit=n option sets some of these parameters as follows:<br> + <br> + max-inline-insns-single<br> + is set to n/2.<br> + max-inline-insns-auto<br> + is set to n/2.<br> + min-inline-insns<br> + is set to 130 or n/4, whichever is smaller.<br> + max-inline-insns-rtl<br> + is set to n.<br> + <br> + See --param below for a documentation of the individual parameters controlling inlining.</td> + </tr> + <tr> + <td>-fkeep-inline-functions</td> + <td>Emit all inline functions into the object file, even if they are inlined where used.</td> + </tr> + <tr> + <td>--param name=value</td> + <td>In some places, GCC uses various constants to control the amount of optimization that is done. For example, GCC will not inline functions that contain more that a certain number of instructions. You can control some of these constants on the command-line using the --param option. <br> + <br> + max-inline-insns-single<br> + Several parameters control the tree inliner used in gcc. This number sets the maximum number of instructions (counted in GCC's internal representation) in a single function that the tree inliner will consider for inlining. This only affects functions declared inline and methods implemented in a class declaration (C++). The default value is 450.<br> + <br> + max-inline-insns-auto<br> + When you use -finline-functions (included in -O3), a lot of functions that would otherwise not be considered for inlining by the compiler will be investigated. To those functions, a different (more restrictive) limit compared to functions declared inline can be applied. The default value is 90.<br> + <br> + large-function-insns<br> + The limit specifying really large functions. For functions larger than this limit after inlining inlining is constrained by --param large-function-growth. This parameter is useful primarily to avoid extreme compilation time caused by non-linear algorithms used by the backend. This parameter is ignored when -funit-at-a-time is not used. The default value is 2700.<br> + <br> + large-function-growth<br> + Specifies maximal growth of large function caused by inlining in percents. This parameter is ignored when -funit-at-a-time is not used. The default value is 100 which limits large function growth to 2.0 times the original size.<br> + <br> + inline-unit-growth<br> + Specifies maximal overall growth of the compilation unit caused by inlining. This parameter is ignored when -funit-at-a-time is not used. The default value is 50 which limits unit growth to 1.5 times the original size.<br> + <br> + max-inline-insns-recursive<br> + max-inline-insns-recursive-auto<br> + Specifies maximum number of instructions out-of-line copy of self recursive inline function can grow into by performing recursive inlining. For functions declared inline --param max-inline-insns-recursive is taken into acount. For function not declared inline, recursive inlining happens only when -finline-functions (included in -O3) is enabled and --param max-inline-insns-recursive-auto is used. The default value is 450.<br> + <br> + max-inline-recursive-depth<br> + max-inline-recursive-depth-auto<br> + Specifies maximum recursion depth used by the recursive inlining. For functions declared inline --param max-inline-recursive-depth is taken into acount. For function not declared inline, recursive inlining happens only when -finline-functions (included in -O3) is enabled and --param max-inline-recursive-depth-auto is used. The default value is 450.<br> + <br> + inline-call-cost<br> + Specify cost of call instruction relative to simple arithmetics operations (having cost of 1). Increasing this cost disqualify inlining of non-leaf functions and at same time increase size of leaf function that is believed to reduce function size by being inlined. In effect it increase amount of inlining for code having large abstraction penalty (many functions that just pass the arguments to other functions) and decrease inlining for code with low abstraction penalty. Default value is 16.</td> + </tr> + <tr> + <td>-finline-limit=n </td> + <td>By default, GCC limits the size of functions that can be inlined. This flag allows the control of this limit for functions that are explicitly marked as inline (i.e., marked with the inline keyword or defined within the class definition in c++). n is the size of functions that can be inlined in number of pseudo instructions (not counting parameter handling). The default value of n is 600. Increasing this value can result in more inlined code at the cost of compilation time and memory consumption. Decreasing usually makes the compilation faster and less code will be inlined (which presumably means slower programs). This option is particularly useful for programs that use inlining heavily such as those based on recursive templates with C++. </td> + </tr> + </tbody> +</table> +</blockquote> +<p class="faq-answer">Inlining is actually controlled by a number of parameters, which may be specified individually by using <samp><span class="option">--param</span> <var>name</var><span class="option">=</span><var>value</var></samp>. The <samp><span class="option">-finline-limit=</span><var>n</var></samp> option sets some of these parameters as follows:</p> +<blockquote> + <dl> + <dl> + <dt><code>max-inline-insns-single</code></dt> + <dd>is set to <var>n</var>/2.<br> + </dd> + <dt><code>max-inline-insns-auto</code></dt> + <dd>is set to <var>n</var>/2.<br> + </dd> + <dt><code>min-inline-insns</code></dt> + <dd>is set to 130 or <var>n</var>/4, whichever is smaller.<br> + </dd> + <dt><code>max-inline-insns-rtl</code></dt> + <dd>is set to <var>n</var>.</dd> + </dl> + </dl> +</blockquote> +<p class="faq-answer">See below for a documentation of the individual parameters controlling inlining.</p> +<p class="faq-answer"><em>Note:</em> pseudo instruction represents, in this particular context, an abstract measurement of function's size. In no way, it represents a count of assembly instructions and as such its exact meaning might change from one release to an another.</p> +<p class="faq-answer">GCC additionally has the -Winline compiler warning, which emits a warning whenever a function declared as inline was not inlined.</p> +<p class="faq-answer">Compilation-Level Inlining -- Metrowerks</p> +<p class="faq-answer">Metrowerks has a number of pragmas (and corresponding compiler settings) to control inlining. These include always_inline, inline_depth, inline_max_size, and inline max_total_size.</p> +<blockquote> + <p class="faq-answer"><small><span style="font-family: Courier New;">#pragma always_inline on | off | reset</span></small></p> + <p class="faq-answer">Controls the use of inlined functions. If you enable this pragma, the compiler ignores all inlining limits and attempts to inline all functions where it is legal to do so. This pragma is deprecated. Use the inline_depth pragma instead.<br> + <br> + <small><span style="font-family: Courier New;">#pragma inline_depth(n)</span><br> + <span style="font-family: Courier New;">#pragma inline_depth(smart)</span></small></p> + <p class="faq-answer">Controls how many passes are used to expand inline function. Sets the number of passes used to expand inline function calls. The number n is an integer from 0 to 1024 or the smart specifier. It also represents the distance allowed in the call chain from the last function up. For example, if d is the total depth of a call chain, then functions below (d-n) are inlined if they do not exceed the inline_max_size and inline_max_total_size settings which are discussed directly below.<br> + <br> + <small><span style="font-family: Courier New;">#pragma inline_max_size(n);</span><br> + <span style="font-family: Courier New;">#pragma inline_max_total_size(n);</span></small></p> + <p class="faq-answer">The first pragma sets the maximum function size to be considered for inlining; the second sets the maximum size to which a function is allowed to grow after the functions it calls are inlined. Here, n is the number of statements, operands, and operators in the function, which<br> + turns out to be roughly twice the number of instructions generated by the function. However, this number can vary from function to function. For the inline_max_size pragma, the default value of n is 256; for the inline_max_total_size pragma, the default value of n is 10000. The smart specifier is the default mode, with four passes where the passes 2-4 are limited to small inline functions. All inlineable functions are expanded if inline_depth is set to 1-1024.</p> +</blockquote> +<p class="faq-answer">Function-Level Inlining -- VC++</p> +<blockquote> + <p class="faq-answer">To force inline usage under VC++, you use this:</p> + <p class="faq-answer"> <small><span style="font-family: Courier New;"> __forceinline void foo(){ ... }</span></small></p> + <p class="faq-answer">It should be noted that __forceinline has no effect if the compiler is set to disable inlining. It merely tells the compiler that when inlining is enabled that it shouldn't use its judgment to decide if the function should be inlined but instead to always inline it.<br> + <br> + To disable inline usage under VC++, you need to use this:</p> + <p class="faq-answer"><small><span style="font-family: Courier New;"> #pragma inline_depth(0) // Disable inlining.</span><br> + <span style="font-family: Courier New;"> void foo() { ... }</span><br> + <span style="font-family: Courier New;"> #pragma inline_depth() // Restore default.</span></small></p> + <p class="faq-answer">The above is essentially specifying compiler-level inlining control within the code for a specific function.</p> +</blockquote> +<p class="faq-answer"><span style="font-weight: bold;">Function-Level Inlining --</span> <span style="font-weight: bold;">GCC / Metrowerks</span></p> +<blockquote> + <p class="faq-answer">To force inline usage under GCC 3.1+, you use this:</p> + <p class="faq-answer"> <small><span style="font-family: Courier New;"> inline void foo() __attribute__((always_inline)) { ... }</span><br> + <span style="font-family: Courier New;"> </span></small> or<small><br> + <span style="font-family: Courier New;"> inline __attribute__((always_inline)) void foo() { ... }</span></small></p> + <p class="faq-answer">To disable inline usage under GCC 3+, you use this:</p> + <p class="faq-answer"><small><span style="font-family: Courier New;"> void foo() __attribute__((noinline)) { ... }</span><br> + </small> <small><span style="font-family: Courier New;"> </span></small> or<small><br> + <span style="font-family: Courier New;"> inline __attribute__((noinline)) void foo() { ... }</span></small></p> + <p class="faq-answer">EABase has some wrappers for this, such as EA_FORCE_INLINE.</p> +</blockquote> +<p class="faq-question"><a name="Perf.12"></a>Perf.12 + C++ / EASTL seems to bloat my .obj files much more than C does. +</p> +<p class="faq-answer">There is no need to worry. The way most C++ compilers compile templates, they compile all seen template code into the current .obj module, which results in larger .obj files and duplicated template code in multiple .obj files. However, the linker will (and in fact must) select only a single version of any given function for the application, and these linked functions will usually be located contiguously.</p> +<p class="faq-answer">Additionally, the debug information for template definitions is usually larger than that for non-templated C++ definitions, which itself is sometimes larger than C definitions due to name decoration.</p> +<p class="faq-question"><a name="Perf.13"></a>Perf.13 +What are the best compiler settings for EASTL?</p> +<p class="faq-answer">We will discuss various aspects of this topic here. As of this writing, more EASTL research on this topic has been done on Microsoft compiler platforms (e.g. Win32) than GCC platforms. Thus currently this discussion focuses on VC++ optimization. Some of the concepts are applicable to GCC, though. EASTL has been successfully compiled and tested (the EASTL unit test) on our major development platforms with the highest optimization settings enabled, including GCC's infamous -O3 level.<br> +<br> +<span style="font-weight: bold;">Optimization Topics</span></p> +<ul> + <li>Function inlining.</li> + <li>Optimization for speed vs. optimization for size.</li> + <li>Link-time code generation (LTCG).</li> + <li>Profile-guided optimization (PGO).</li> +</ul> +<p class="faq-answer"><span style="font-weight: bold;">Function inlining</span><br> + EASTL is a template library and inlining is important for optimal speed. Compilers have various options for enabling inlining and those options are discussed in this FAQ in detail. Most users will want to enable some form of inlining when compiling EASTL and other templated libraries. For users that are most concerned about the compiler's inlining increasing code size may want to try the 'inline only functions marked as inline' compiler option. Here is a table of normalized results from the benchmark project (Win32 platform):<br> +</p> +<table style="text-align: left; margin-left: 40px; width: 696px; height: 88px;" border="1" cellpadding="2" cellspacing= +"2"> + <tbody> + <tr> + <td style="font-weight: bold;"></td> + <td style="font-weight: bold; text-align: center;">Inlining Disabled</td> + <td style="font-weight: bold; text-align: center;">Inline only 'inline'</td> + <td style="text-align: center;">Inline any</td> + </tr> + <tr> + <td style="font-weight: bold;">Application size</td> + <td style="text-align: center;">100K</td> + <td style="text-align: center;">86K</td> + <td style="text-align: center;">86K</td> + </tr> + <tr> + <td style="font-weight: bold;">Execution time</td> + <td style="text-align: center;">100</td> + <td style="text-align: center;">75</td> + <td style="text-align: center;">75</td> + </tr> + </tbody> +</table> +<p class="faq-answer"><br> +The above execution times are highly simplified versions of the actual benchmark data but convey a sense of the general average behaviour that can be expected. In practice, simple functions such as vector::operator[] will execute much faster with inlining enabled but complex functions such as map::insert may execute no faster within inlining enabled.</p> +<p class="faq-answer"><span style="font-weight: bold;">Optimization for Speed / Size</span><br> + Optimization for speed results in the compiler inlining more code than it would otherwise. This results in the inlined code executing faster than if it was not inlined. As mentioned above, basic function inlining can result in smaller code as well as faster code, but after a certain point highly inlined code becomes greater in size than less inlined code and the performance advantages of inlining start to lessen. The EASTL Benchmark project is a medium sized application that is about 80% templated and thus acts as a decent measure of the practical tradeoff between speed and size. Here is a table of normalized results from the benchmark project (Windows platform):<br> +</p> +<table style="text-align: left; margin-left: 40px; width: 696px; height: 88px;" border="1" cellpadding="2" cellspacing= +"2"> + <tbody> + <tr> + <td style="font-weight: bold;"></td> + <td style="font-weight: bold; text-align: center;">Size</td> + <td style="font-weight: bold; text-align: center;">Speed</td> + <td style="text-align: center;">Speed + LTCG</td> + <td style="text-align: center;">Speed + LTCG + PGO</td> + </tr> + <tr> + <td style="font-weight: bold;">Application size</td> + <td style="text-align: center;">80K</td> + <td style="text-align: center;">100K</td> + <td style="text-align: center;">98K</td> + <td style="text-align: center;">98K</td> + </tr> + <tr> + <td style="font-weight: bold;">Execution time</td> + <td style="text-align: center;">100</td> + <td style="text-align: center;">90</td> + <td style="text-align: center;">83</td> + <td style="text-align: center;">75</td> + </tr> + </tbody> +</table> +<p class="faq-answer"><br> +What the above table is saying is that if you are willing to have your EASTL code be 20% larger, it will be 10% faster. Note that it doesn't mean that your app will be 20% larger, only the templated code in it like EASTL will be 20% larger.</p> +<p class="faq-answer"><span style="font-weight: bold;">Link-time code generation (LTCG)</span><br> + LTCG is a mechanism whereby the compiler compiles the application as if it was all in one big .cpp file instead of separate .cpp files that don't see each other. Enabling LTCG optimizations is done by simply setting some compiler and linker settings and results in slower link times. The benchmark results are presented above and for the EASTL Benchmark project show some worthwhile improvement.</p> +<p class="faq-answer"><span style="font-weight: bold;">Profile-guided optimization (PGO)</span><br> + PGO is a mechanism whereby the compiler uses profiling information from one or more runs to optimize the compilation and linking of an application. Enabling PGO optimizations is done by setting some linker settings and doing some test runs of the application, then linking the app with the test run results. Doing PGO optimizations is a somewhat time-consuming task but the benchmark results above demonstrate that for the EASTL Benchmark project that PGO is worth the effort. </p> +<h2> Problems</h2> +<p class="faq-question"><a name="Prob.1"></a>Prob.1 +I'm getting screwy behavior in sorting algorithms or sorted containers. What's wrong?</p> +<p class="faq-answer">It may possible that you are seeing floating point roundoff problems. Many STL algorithms require object comparisons to act consistently. However, floating point values sometimes compare differently between uses because in one situation a value might be in 32 bit form in system memory, whereas in anther situation that value might be in an FPU register with a different precision. These are difficult problems to track down and aren't the fault of EASTL or whatever similar library you might be using. There are various solutions to the problem, but the important thing is to find a way to force the comparisons to be consistent.</p> +<p class="faq-answer">The code below was an example of this happening, whereby the object pA->mPos was stored in system memory while pB->mPos was stored in a register and comparisons were inconsistent and a crash ensued.<br> +</p> +<pre class="code-example">class SortByDistance : public binary_function<WorldTreeObject*, WorldTreeObject*, bool> +{ +private: + Vector3 mOrigin; + +public: + SortByDistance(Vector3 origin) { + mOrigin = origin; + } + + bool operator()(WorldTreeObject* pA, WorldTreeObject* pB) const { +<span style="color: rgb(204, 0, 0);"> return ((WorldObject*)pA)->mPos - mOrigin).GetLength()</span> +<span style="color: rgb(204, 0, 0);"> < ((WorldObject*)pB)->mPos - mOrigin).GetLength();</span> + } +};</pre> +<p class="faq-answer">Another thing to watch out for is the following mistake:<br> +</p> +<pre class="code-example">struct ValuePair +{ + uint32_t a; + uint32_t b; +}; + +// Improve speed by casting the struct to uint64_t +bool operator<(const ValuePair& vp1, const ValuePair& vp2) + <span style="color: rgb(204, 0, 0);">{ return *(uint64_t*)&vp1 < *(uint64_t*)&vp2; }</span></pre> +<p class="faq-answer">The problem is that the ValuePair struct has 32 bit alignment but the comparison assumes 64 bit alignment. The code above has been observed to crash on the PowerPC 64-based machines. The resolution is to declare ValuePair as having 64 bit alignment.<br> + +</p> +<p class="faq-question"><a name="Prob.2"></a>Prob.2 I am getting compiler warnings (e.g. C4244, C4242 or C4267) that make no sense. Why?</p> +<span class="faq-answer">One cause of this occurs with VC++ when you have code compiled with the /Wp64 (detect 64 bit portability issues) option. This causes pointer types to have a hidden flag called __w64 attached to them by the compiler. So 'ptrdiff_t' is actually known by the compiler as '__w64 int', while 'int' is known by the compilers as simply 'int'. A problem occurs here when you use templates. For example, let's say we have this templated function</span> +<pre class="code-example">template <typename T> +T min(const T a, const T b) { + return b < a ? b : a; +}</pre> +<span class="faq-answer">If you compile this code:</span> +<pre class="code-example">ptrdiff_t a = min(ptrdiff_t(0), ptrdiff_t(1)); +int b = min((int)0, (int)1);</pre> +<span class="faq-answer">You will get the following warning for the second line, which is somewhat nonsensical:</span> +<pre class="code-example">warning C4244: 'initializing' : conversion from 'const ptrdiff_t' to 'int', possible loss of data</pre> +<p class="faq-answer"> This could probably be considered a VC++ bug, but in the meantime you have little choice but to ignore the warning or disable it.</p> + +<p class="faq-question"><a name="Prob.3"></a>Prob.3 +I am getting compiler warning C4530, which complains about exception handling and "unwind semantics." What gives?</p> +<p class="faq-answer">VC++ has a compiler option (/EHsc) that allows you to enable/disable exception handling stack unwinding but still enable try/catch. This is useful because it can save a lot in the way of code generation for your application. Disabling stack unwinding will decrease the size of your executable on at least the Win32 platform by 10-12%.<br> +<br> +If you have stack unwinding disabled, but you have try/catch statements, VC++ will generate the following warning:</p> +<pre class="code-example">warning C4530: C++ exception handler used, but unwind semantics are not enabled. Specify /EHsc</pre> +<p class="faq-answer"> As of EASTL v1.0, this warning has been disabled within EASTL for EASTL code. However, non-EASTL code such as std STL code may still cause this warning to be triggered. In this case there is not much you can do about this other than to disable the warning.</p> +<p class="faq-question"> <a name="Prob.4"></a>Prob.4 + Why are tree-based EASTL containers hard to read with a +debugger?</p> +<p class="faq-answer"><span style="font-weight: bold;">Short answer<br> +</span> Maximum performance and design mandates.</p> +<p class="faq-answer"><span style="font-weight: bold;">Long answer</span><br> +You may notice that when you have a tree-based container (e.g. set, map) in the debugger that it isn't automatically able to recognize the tree nodes as containing instances of your contained object. You can get the debugger to do what you want with casting statements in the debug watch window, but this is not an ideal solution. The reason this is happening is that node-based containers always use an anonymous node type as the base class for container nodes. This is primarily done for performance, as it allows the node manipulation code to exist as a single non-templated library of functions and it saves memory because containers will have one or two base nodes as container 'anchors' and you don't want to allocate a node of the size of the user data when you can just use a base node. See list.h for an example of this and some additional in-code documentation on this.</p> +<p class="faq-answer">Additionally, EASTL has the design mandate that an empty container constructs no user objects. This is both for performance reasons and because it doing so would skew the user's tracking of object counts and might possibly break some expectation the user has about object lifetimes.</p> +<p class="faq-answer">Currently this debug issue exists only with tree-based containers. Other node-based containers such as list and slist use a trick to get around this problem in debug builds.</p> +<p class="faq-answer">See <a href="#Debug.2">Debug.2</a> for more. +<p class="faq-question"><a name="Prob.5"></a>Prob.5 +The EASTL source code is sometimes rather complicated looking. Why is that?</p> +<p class="faq-answer"><span style="font-weight: bold;">Short answer</span><br> +Maximum performance.</p> +<p class="faq-answer"><span style="font-weight: bold;">Long answer</span><br> + EASTL uses templates, type_traits, iterator categories, redundancy reduction, and branch reduction in order to achieve optimal performance. A side effect of this is that there are sometimes a lot of template parameters and multiple levels of function calls due to template specialization. The ironic thing about this is that this makes the code (an optimized build, at least) go faster, not slower. In an optimized build the compiler will see through the calls and template parameters and generate a direct optimized inline version.</p> +<p class="faq-answer">As an example of this, take a look at the implementation of the <span style="font-style: italic;">copy</span> implementation in algorithm.h. If you are copying an array of scalar values or other trivially copyable values, the compiler will see how the code directs this to the memcpy function and will generate nothing but a memcpy in the final code. For non-memcpyable data types the compiler will automatically understand that in do the right thing.</p> +<p class="faq-answer">EASTL's primary objective is maximal performance, and it has been deemed worthwhile to make the code a little less obvious in order to achieve this goal. Every case where EASTL does something in an indirect way is by design and usually this is for the purpose of achieving the highest possible performance.</p> +<p class="faq-question"><a name="Prob.6"></a>Prob.6 +When I get compilation errors, they are very long and complicated looking. What do I do?</p> +<p class="faq-answer">Assuming the bugs are all worked out of EASTL, these errors really do indicate that you have something wrong. EASTL is intentionally very strict about types, as it tries to minimize the chance of users errors. Unfortunately, there is no simple resolution to the problem of long compiler errors other than to deal with them. On the other hand, once you've dealt with them a few times, you tend to realize that most of time they are the same kinds of errors and</p> +<p class="faq-answer">Top five approaches to dealing with long compilation errors:</p> +<ol> + <li>Look at the line where the compilation error occurred and ignore the text of the error and just look at obvious things that might be wrong.</li> + <li>Consider the most common typical causes of templated compilation errors and consider if any of these might be your problem. Usually one of them are.</li> + <li>Either read through the error (it's not as hard as it may look on the surface) or copy the error to a text file and remove the extraneous</li> + <li>Compile the code under GCC instead of MSVC, as GCC warnings and errors tend to be more helpful than MSVC's. Possibly also consider compiling an isolated version under Comeau C++'s free online compiler at www.comeaucomputing.com or the Dinkumware online compiler at http://dinkumware.com/exam/. </li> + <li>Try using an STL filter (http://www.bdsoft.com/tools/stlfilt.html) which automatically boils down template errors to simpler forms. We haven't tried this yet with EASTL. Also there is the more generic TextFilt (http://textfilt.sourceforge.net/).</li> +</ol> +<p class="faq-answer">Top five causes of EASTL compilation errors:</p> +<ol> + <li>const-correctness. Perhaps a quarter of container template errors are due to the user not specifying const correctly.</li> + <li>Missing hash function. hash_map, hash_set, etc. require that you either specify a hash function or one exists for your class. See functional.h for examples of declarations of hash functions for common data types.</li> + <li>Missing operators. Various containers and algorithms require that certain operators exist for your contained classes. For example, list requires that you can test contained objects for equivalence (i.e. operator==), while map requires that you can test contained objects for "less-ness" (operator <). If you define a Widget class and don't have a way to compare two Widgets, you will get errors when trying to put them into a map.</li> + <li>Specifying the wrong data type. For example, it is a common mistake to forget that when you insert into a map, you need to insert a pair of objects and not just your key or value type.</li> + <li>Incorrect template parameters. When declaring a template instantiation (e.g. map<int, int, less<int> >) you simply need to get the template parameters correct. Also note that when you have "<span style="font-family: Courier New;">>></span>" next to each other that you need to separate them by one space (e.g. "<span style="font-family: Courier New;">> ></span>").</li> +</ol> +<p class="faq-question"><a name="Prob.7"></a>Prob.7 + Templates sometimes seem to take a long time to compile. Why do I do about that? +</p> +<p class="faq-answer">C++ compilers are generally slower than C compilers, and C++ templates are generally slower to compile than regular C++ code. EASTL has some extra functionality (such as type_traits and algorithm specializations) that is not found in most other template libraries and significantly improves performance and usefulness but adds to the amount of code that needs to be compiled. Ironically, we have a case where more source code generates faster and smaller object code.</p> +<p class="faq-answer">The best solution to the problem is to use pre-compiled headers, which are available on all modern ~2002+) compilers, such as VC6.0+, GCC 3.2+, and Metrowerks 7.0+. In terms of platforms this means all 2002+ platforms.</p> +<p class="faq-answer">Some users have been speeding up build times by creating project files that put all the source code in one large .cpp file. This has an effect similar to pre-compiled headers. It can go even faster than pre-compiled headers but has downsides in the way of convenience and portability.</p> +<p class="faq-question"><a name="Prob.8"></a>Prob.8 +I get the compiler error: "template instantiation depth exceeds maximum of 17. use -ftemplate-depth-NN to increase the maximum". </p> +<p class="faq-answer">This is a GCC error that occurs when a templated function calls a templated function which calls a templated function, etc. past a depth of 17. You can use the GCC command line argument -ftemplate-depth-40 (or some other high number) to get around this. As note below, the syntax starting with GCC 4.5 has changed slightly. </p> +<p class="faq-answer">The primary reason you would encounter this with EASTL is type traits that are used by algorithms. The type traits library is a (necessarily) highly templated set of types and functions which adds at most about nine levels of inlining. The copy and copy_backward algorithms have optimized pathways that add about four levels of inlining. If you have just a few more layers on top of that in container or user code then the default limit of 17 can be exceeded. We are investigating ways to reduce the template depth in the type traits library, but only so much can be done, as most compilers don't support type traits natively. Metrowerks is the current exception.</p> +<p class="faq-answer">From the GCC documentation:</p> +<pre class="code-example">-ftemplate-depth-n + +Set the maximum instantiation depth for template classes to n. +A limit on the template instantiation depth is needed to detect +endless recursions during template class instantiation ANSI/ISO +C++ conforming programs must not rely on a maximum depth greater than 17. +</pre> + +<p class="faq-answer">Note that starting with GCC 4.5 the syntax is -ftemplate-depth=N instead of -ftemplate-depth-n.</p> +<p class="faq-question"><a name="Prob.9"></a>Prob.9 + I'm getting errors about min and max while compiling.</p> +<p class="faq-answer">You need to define NOMINMAX under VC++ when this occurs, as it otherwise defines min and max macros that interfere. There may be equivalent issues with other compilers. Also, VC++ has a specific <minmax.h> header file which defines min and max macros but which doesn't pay attention to NOMINMAX and so in that case there is nothing to do but not include that file or to undefine min and max. minmax.h is not a standard file and its min and max macros are not standard C or C++ macros or functions.</p> +<p class="faq-question"><a name="Prob.10"></a>Prob.10 +C++ / EASTL seems to bloat my .obj files much more than C does.</p> +<p class="faq-answer"> There is no need to worry. The way most C++ compilers compile templates, they compile all +seen template code into the current .obj module, which results in larger .obj files and duplicated template code in +multiple .obj files. However, the linker will (and must) select only a single version of any given function for the +application, and these linked functions will usually be located contiguously.</p> +<p class="faq-question"> <a name="Prob.11"></a>Prob.11 + I'm getting compiler errors regarding placement operator new +being previously defined.</p> +<p class="faq-answer">This can happen if you are attempting to define your own versions of placement new/delete. The C++ language standard does not allow the user to override these functions. Section 18.4.3 of the standard states:</p> +<p class="faq-answer"> Placement forms<br> + 1. These functions are reserved, a C++ program may not define functions that displace the versions in the Standard C++ library.</p> +<p class="faq-answer">You may find that #defining <small>__PLACEMENT_NEW_INLINE</small> seems to fix your problems under VC++, but it can fail under some circumstances and is not portable and fails with other compilers, which don't have an equivalent workaround.</p> +<p class="faq-question"> <a name="Prob.12"></a>Prob.12 +I'm getting errors related to wchar_t string functions such as wcslen().</p> +<p class="faq-answer">EASTL requires EABase-related items that the following be so. If not, then EASTL gets confused about what types it can pass to wchar_t related functions.</p> +<ul> + <li>The #define EA_WCHAR_SIZE is equal to sizeof(wchar_t).</li> + <li>If sizeof(wchar_t) == 2, then char16_t is typedef'd to wchar_t.</li> + <li>If sizeof(wchar_t) == 4, then char32_t is typedef'd to wchar_t.</li> +</ul> +<p class="faq-answer">EABase v2.08 and later automatically does this for most current generation and all next generation platforms. With GCC 2.x, the user may need to predefine EA_WCHAR_SIZE to the appropriate value, due to limitations with the GCC compiler. Note that GCC defaults to sizeof(wchar_t) ==4, but it can be changed to 2 with the -fshort_wchar compiler command line argument. If you are using EASTL without EABase, you will need to make sure the above items are correctly defined.</p> +<p class="faq-question"> <a name="Prob.13"></a>Prob.13 + I'm getting compiler warning C4619: there is no warning number Cxxxx +(e.g. C4217).</p> +<p class="faq-answer">Compiler warning C4619 is a VC++ warning which is saying that the user is attempting to enable or disable a warning which the compiler doesn't recognize. This warning only occurs if the user has the compiler set to enable warnings that are normally disabled, regardless of the warning level. The problem, however, is that there is no easy way for user code to tell what compiler warnings any given compiler version will recognize. That's why Microsoft normally disables this warning.</p> +<p class="faq-answer">The only practical solution we have for this is for the user to disable warning 4619 globally or an a case-by-case basis. EA build systems such as nant/framework 2's eaconfig will usually disable 4619. In general, global enabling of 'warnings that are disabled by default' often result in quandrys such as this.</p> +<p class="faq-question"><a name="Prob.14"></a>Prob.14 +My stack-based fixed_vector is not respecting the object alignment requirements.</p> +<p class="faq-answer">EASTL fixed_* containers rely on the compiler-supplied alignment directives, such as that implemented by EA_PREFIX_ALIGN. This is normally a good thing because it allows the memory to be local with the container. However, as documented by Microsoft at <a href="http://msdn2.microsoft.com/en-us/library/83ythb65(VS.71).aspx"> http://msdn2.microsoft.com/en-us/library/83ythb65(VS.71).aspx</a>, this doesn't work for stack variables. The two primary means of working around this are: </p> +<ul> + <li>Use something like AlignedObject<> from the EAStdC package's EAAllocator.h file. </li> + <li>Use eastl::vector with a custom allocator and have it provide aligned memory. EASTL automatically recognizes that the objects are aligned and will call the aligned version of your allocator allocate() function. You can get this aligned memory from the stack, if you need it, somewhat like how AlignedObject<> works. </li> +</ul> +<p class="faq-question"><a name="Prob.15" id="Prob.15"></a>Prob.15 I am getting compiler errors when using GCC under XCode (Macintosh/iphone).</p> +<p class="faq-answer">The XCode environment has a compiler option which causes it to evaluate include directories recursively. So if you specify /a/b/c as an include directory, it will consider all directories underneath c to also be include directories. This option is enabled by default, though many XCode users disable it, as it is a somewhat dangerous option. The result of enabling this option with EASTL is that <EASTL/string.h> is used by the compiler when you say #include <string.h>. The solution is to disable this compiler option. It's probably a good idea to disable this option anyway, as it typically causes problems for users yet provides minimal benefits. </p> +<p class="faq-question"><a name="Prob.16" id="Prob.16"></a>Prob.16 I am getting linker errors about Vsnprintf8 or Vsnprintf16.</p> +<p class="faq-answer">EASTL requires the user to provide a function called Vsnprintf8 if the string::sprintf function is used. vsnprintf is not a standard C function, but most C standard libraries provide some form of it, though in some ways their implementations differ, especially in what the return value means. Also, most implementations of vsnprintf are slow, mostly due to mutexes related to locale functionality. And you can't really use vendor vsnprintf on an SPU due to the heavy standard library size. EASTL is stuck because it doesn't want to depend on something with these problems. EAStdC provides a single consistent fast lightweight, yet standards-conforming, implementation in the form of Vsnprintf(char8_t*, ...), but EASTL can't have a dependency on EAStdC. So the user must provide an implementation, even if all it does is call EAStdC's Vsnprintf or the vendor vsnprintf for that matter.</p> +<p class="faq-answer">Example of providing Vsnprintf8 via EAStdC:</p> +<pre class="code-example">#include <EAStdC/EASprintf.h> + +int Vsnprintf8(char8_t* pDestination, size_t n, const char8_t* pFormat, va_list arguments) +{ + return EA::StdC::Vsnprintf(pDestination, n, pFormat, arguments); +} + +int Vsnprintf16(char16_t* pDestination, size_t n, const char16_t* pFormat, va_list arguments) +{ + return EA::StdC::Vsnprintf(pDestination, n, pFormat, arguments); +}</pre> +<p>Example of providing Vsnprintf8 via C libraries:</p> +<pre><span class="code-example">#include <stdio.h> + +int Vsnprintf8(char8_t* p, size_t n, const char8_t* pFormat, va_list arguments) +{ + #ifdef _MSC_VER + return vsnprintf_s(p, n, _TRUNCATE, pFormat, arguments); + #else + return vsnprintf(p, n, pFormat, arguments); + #endif +} + +int Vsnprintf16(char16_t* p, size_t n, const char16_t* pFormat, va_list arguments) +{ + #ifdef _MSC_VER + return vsnwprintf_s(p, n, _TRUNCATE, pFormat, arguments); + #else + return vsnwprintf(p, n, pFormat, arguments); <span class="code-example-comment">// Won't work on Unix because its libraries implement wchar_t as int32_t.</span> + #endif +}</span></pre> +<p class="faq-question"><a name="Prob.17" id="Prob.17"></a>Prob.17 I am getting compiler errors about UINT64_C or UINT32_C.</p> +<p class="faq-answer">This is usually an order-of-include problem that comes about due to the implementation of __STDC_CONSTANT_MACROS in C++ Standard libraries. The C++ <stdint.h> header file defineds UINT64_C only if __STDC_CONSTANT_MACROS has been defined by the user or the build system; the compiler doesn't automatically define it. The failure you are seeing occurs because user code is #including a system header before #including EABase and without defining __STDC_CONSTANT_MACROS itself or globally. EABase defines __STDC_CONSTANT_MACROS and #includes the appropriate system header. But if the system header was already previously #included and __STDC_CONSTANT_MACROS was not defined, then UINT64_C doesn't get defined by anybody. </p> +<p class="faq-answer">The real solution that the C++ compiler and standard library wants is for the app to globally define __STDC_CONSTANT_MACROS itself in the build. </p> +<p class="faq-question"><a name="Prob.18" id="Prob.18"></a>Prob.18 I am getting a crash with a global EASTL container. </p> +<p class="faq-answer">This usually due to compiler's lack of support for global (and static) C++ class instances. The crash is happening because the global variable exists but its constructor was not called on application startup and it's member data is zeroed bytes. To handle this you need to manually initialize such variables. There are two primary ways:</p> +<p class="faq-answer">Failing code:</p> +<pre class="code-example">eastl::list<int> gIntList; // Global variable. + +void DoSomething() +{ + gIntList.push_back(1); // <span class="style3">Crash</span>. gIntList was never constructed. +}</pre> +<p class="faq-answer">Declaring a pointer solution: </p> +<pre class="code-example">eastl::list<int>* gIntList = NULL; + +void DoSomething() +{ + if(!gIntList) // Or move this to an init function. + gIntList = new eastl::list<int>; + + gIntList->push_back(1); // <span class="style2">Success</span> +}</pre> +<p class="faq-answer">Manual constructor call solution: </p> +<pre class="code-example">eastl::list<int> gIntList; + +void InitSystem() +{ + new(&gIntList) eastl::list<int>; +} + +void DoSomething() +{ + gIntList.push_back(1); // <span class="style2">Success</span> +}</pre> +<p class="faq-question"><a name="Prob.19" id="Prob.19"></a>Prob.19 Why doesn't EASTL support passing NULL string functions? </p> +<p class="faq-answer"></p> +<p class="faq-answer">The primary argument is to make functions safer for use. Why crash on NULL pointer access when you can make the code safe? That's a good argument. The counter argument, which EASTL currently makes, is: </p> +<ul> + <li class="faq-answer"> It breaks consistency with the C++ STL library and C libraries, which require strings to be valid.</li> + <li class="faq-answer"> It makes the coder slower and bigger for all users, though few need NULL checks. </li> + <li class="faq-answer"> The specification for how to handle NULL is simple for some cases but not simple for others. Operator < below a case where the proper handling of it in a consistent way is not simple, as all comparison code (<, >, ==, !=, >=, <=) in EASTL must universally and consistently handle the case where either or both sides are NULL. A NULL string seems similar to an empty string, but doesn't always work out so simply.</li> + <li class="faq-answer">What about other invalid string pointers? NULL is merely one invalid value of many, with its only distinction being that sometimes it's intentionally NULL (as opposed to being NULL due to not being initialized). </li> + <li class="faq-answer"> How and where to implement the NULL checks in such a way as to do it efficiently is not always simple, given that public functions call public functions. </li> + <li class="faq-answer">It's arguable (and in fact the intent of the C++ standard library) that using pointers that are NULL is a user/app mistake. If we really want to be safe then we should be using string objects for everything. You may not entirely buy this argument in practice, but on the other hand one might ask why is the caller of EASTL using a NULL pointer in the first place? The answer of course is that somebody gave it to him. </li> +</ul> +<h2>Debug</h2> +<p class="faq-question"><a name="Debug.1"></a>Debug.1 +How do I set the VC++ debugger to display EASTL container data with tooltips?</p> +<p class="faq-answer">See <a href="#Cont.9">Cont.9</a></p> +<p class="faq-question"><a name="Debug.2"></a>Debug.2 +How do I view containers if the visualizer/tooltip support is not present?</p> + +<p class="faq-answer">Here is a table of answers about how to manually inspect containers in the debugger.</p> +<blockquote> +<table style="text-align: left; width: 100%;" border="1" cellpadding="2" cellspacing="2" id="table4"> + <tbody> + <tr> + <td style="font-weight: bold;"> Container</td> + <td style="font-weight: bold;">Approach</td> + </tr> + <tr> + <td>slist<br> + fixed_slist</td> + <td>slist is a singly-linked list. Look at the slist mNode variable. You can walk the list by looking at mNode.mpNext, etc.</td> + </tr> + <tr> + <td>list<br> + fixed_list</td> + <td>list is a doubly-linked list. Look at the list mNode variable. You can walk the list forward by looking at mNode.mpNext, etc. and backward by looking at mpPrev, etc.</td> + </tr> + <tr> + <td>intrusive_list<br> + intrusive_slist<sup>†</sup></td> + <td>Look at the list mAnchor node. This lets you walk forward and backward in the list via mpNext and mpPrev.</td> + </tr> + <tr> + <td>array</td> + <td>View the array mValue member in the debugger. It's simply a C style array.</td> + </tr> + <tr> + <td>vector<br> + fixed_vector</td> + <td>View the vector mpBegin value in the debugger. If the string is long, use ", N" to limit the view length, as with someVector.mpBegin, 32</td> + </tr> + <tr> + <td>vector_set<br> + vector_multiset<br> + vector_map<br> + vector_multimap<br></td> + <td>These are containers that are implemented as a sorted vector, deque, or array. They are searched via a standard binary search. You can view them the same way you view a vector or deque.</td> + </tr> + <tr> + <td style="vertical-align: top;">deque<br></td> + <td style="vertical-align: top;">deque is implemented as an array of arrays, where the arrays implement successive equally-sized segments of the deque. The mItBegin deque member points the deque begin() position. </td> + </tr> + <tr> + <td>bitvector</td> + <td>Look at the bitvector mContainer variable. If it's a vector, then see vector above.</td> + </tr> + <tr> + <td>bitset</td> + <td>Look at the bitset mWord variable. The bitset is nothing but one or more uint32_t mWord items.</td> + </tr> + <tr> + <td>set<br> + multiset<br> + fixed_set<br> + fixed_multiset<br></td> + <td>The set containers are implemented as a tree of elements. The set mAnchor.mpNodeParent points to the top of the tree; the mAnchor.mpNodeLeft points to the far left node of the tree (set begin()); the mAnchor.mpNodeRight points to the right of the tree (set end()).</td> + </tr> + <tr> + <td>map<br> + multimap<br> + fixed_map<br> + fixed_multimap</td> + <td>The map containers are implemented as a tree of pairs, where pair.first is the map key and pair.second is the map value. The map mAnchor.mpNodeParent points to the top of the tree; the mAnchor.mpNodeLeft points to the far left node of the tree (map begin()); the mAnchor.mpNodeRight points to the right of the tree (map end()).</td> + </tr> + <tr> + <td>hash_map<br> + hash_multimap<br> + fixed_hash_map<br> + fixed_hash_multimap</td> + <td>hash tables in EASTL are implemented as an array of singly-linked lists. The array is the mpBucketArray member. Each element in the list is a pair, where the first element of the pair is the map key and the second is the map value.</td> + </tr> + <tr> + <td>intrusive_hash_map<br> + intrusive_hash_multimap<br> + intrusive_hash_set<br> + intrusive_hash_multiset</td> + <td>intrusive hash tables in EASTL are implemented very similarly to regular hash tables. See the hash_map and hash_set entries for more info.</td> + </tr> + <tr> + <td>hash_set<br> + hash_multiset<br> + fixed_hash_set<br> + fixed_hash_map<br></td> + <td>hash tables in EASTL are implemented as an array of singly-linked lists. The array is the mpBucketArray member. </td> + </tr> + <tr> + <td>basic_string<br> + fixed_string<br> + fixed_substring</td> + <td>View the string mpBegin value in the debugger. If the string is long, use ", N" to limit the view length, as with someString.mpBegin, 32</td> + </tr> + <tr> + <td style="vertical-align: top;">heap<br></td> + <td style="vertical-align: top;">A heap is an array of data (e.g. EASTL vector) which is organized in a tree whereby the highest priority item is array[0], The next two highest priority items are array[1] and [2]. Underneath [1] in priority are items [3] and [4], and underneath item [2] in priority are items [5] and [6]. etc.</td> + </tr> + <tr> + <td style="vertical-align: top;">stack<br></td> + <td style="vertical-align: top;">View the stack member c value in the debugger. That member will typically be a list or deque. </td> + </tr> + <tr> + <td style="vertical-align: top;">queue<br></td> + <td style="vertical-align: top;">View the queue member c value in the debugger. That member will typically be a list or deque. </td> + </tr> + <tr> + <td style="vertical-align: top;">priority_queue<br></td> + <td style="vertical-align: top;">View the priority_queue member c value in the debugger. That member will typically be a vector or deque which is organized as a heap. See the heap section above for how to view a heap. </td> + </tr> + <tr> + <td>smart_ptr</td> + <td>View the mpValue member.</td> + </tr> + </tbody> +</table> +</blockquote> +<p class="faq-question"><a name="Debug.3"></a>Debug.3 +The EASTL source code is sometimes rather complicated looking. Why is that?</p> +<p class="faq-answer"><span style="font-weight: bold;">Short answer</span><br> +Maximum performance.</p> +<p class="faq-answer"><span style="font-weight: bold;">Long answer</span><br> + EASTL uses templates, type_traits, iterator categories, redundancy reduction, and branch reduction in order to achieve optimal performance. A side effect of this is that there are sometimes a lot of template parameters and multiple levels of function calls due to template specialization. The ironic thing about this is that this makes the code (an optimized build, at least) go faster, not slower. In an optimized build the compiler will see through the calls and template parameters and generate a direct optimized inline version.</p> +<p class="faq-answer">As an example of this, take a look at the implementation of the <span style="font-style: italic;">copy</span> implementation in algorithm.h. If you are copying an array of scalar values or other trivially copyable values, the compiler will see how the code directs this to the memcpy function and will generate nothing but a memcpy in the final code. For non-memcpyable data types the compiler will automatically understand that in do the right thing.</p> +<p class="faq-answer">EASTL's primary objective is maximal performance, and it has been deemed worthwhile to make the code a little less obvious in order to achieve this goal. Every case where EASTL does something in an indirect way is by design and usually this is for the purpose of achieving the highest possible performance.</p> +<p class="faq-question"><a name="Debug.4"></a>Debug.4 +When I get compilation errors, they are very long and complicated looking. What do I do?</p> +<p class="faq-answer">Assuming the bugs are all worked out of EASTL, these errors really do indicate that you have something wrong. EASTL is intentionally very strict about types, as it tries to minimize the chance of users errors. Unfortunately, there is no simple resolution to the problem of long compiler errors other than to deal with them. On the other hand, once you've dealt with them a few times, you tend to realize that most of time they are the same kinds of errors and<br> +<br> +Top five approaches to dealing with long compilation errors:</p> +<ol> + <li>Look at the line where the compilation error occurred and ignore the text of the error and just look at obvious things that might be wrong.</li> + <li>Consider the most common typical causes of templated compilation errors and consider if any of these might be your problem. Usually one of them are.</li> + <li>Either read through the error (it's not as hard as it may look on the surface) or copy the error to a text file and remove the extraneous</li> + <li>Compile the code under GCC instead of MSVC, as GCC warnings and errors tend to be more helpful than MSVC's. Possibly also consider compiling an isolated version under Comeau C++'s free online compiler at www.comeaucomputing.com or the Dinkumware online compiler at http://dinkumware.com/exam/. </li> + <li>Try using an STL filter (http://www.bdsoft.com/tools/stlfilt.html) which automatically boils down template errors to simpler forms. We haven't tried this yet with EASTL. Also there is the more generic TextFilt (http://textfilt.sourceforge.net/).</li> +</ol> +<p class="faq-answer">Top five causes of EASTL compilation errors:</p> +<ol> + <li>const-correctness. Perhaps a quarter of container template errors are due to the user not specifying const correctly.</li> + <li>Missing hash function. hash_map, hash_set, etc. require that you either specify a hash function or one exists for your class. See functional.h for examples of declarations of hash functions for common data types.</li> + <li>Missing operators. Various containers and algorithms require that certain operators exist for your contained classes. For example, list requires that you can test contained objects for equivalence (i.e. operator==), while map requires that you can test contained objects for "less-ness" (operator <). If you define a Widget class and don't have a way to compare two Widgets, you will get errors when trying to put them into a map.</li> + <li>Specifying the wrong data type. For example, it is a common mistake to forget that when you insert into a map, you need to insert a pair of objects and not just your key or value type.</li> + <li>Incorrect template parameters. When declaring a template instantiation (e.g. map<int, int, less<int> >) you simply need to get the template parameters correct. Also note that when you have "<span style="font-family: Courier New;">>></span>" next to each other that you need to separate them by one space (e.g. "<span style="font-family: Courier New;">> ></span>").</li> +</ol> +<p class="faq-question"><a name="Debug.5"></a>Debug.5 +How do I measure hash table balancing?</p> +<p class="faq-answer">The following functionality lets you spelunk hash container layout.</p> +<ul> + <li>There is the load_factor function which tells you the overall hashtable load, but doesn't tell you if a load is unevenly distributed.</li> + <li>You can control the load factor and thus the automated bucket redistribution with set_load_factor.</li> + <li>The local_iterator begin(size_type n) and local_iterator end(size_type) functions lets you iterate each bucket individually. You can use this to examine the elements in a bucket.</li> + <li>You can use the above to get the size of any bucket, but there is also simply the bucket_size(size_type n) function.</li> + <li>The bucket_count function tells you the count of buckets. So with this you can completely visualize the layout of the hash table.</li> + <li>There is also iterator find_by_hash(hash_code_t c), for what it's worth.</li> +</ul> +<p class="faq-answer">The following function draws an ASCII bar graph of the hash table for easy visualization of bucket distribution:</p> +<blockquote> + <p><font face="Courier New" size="1">#include <EASTL/hash_map.h><br> + #include <EASTL/algorithm.h><br> + #include <stdio.h><br> + <br> + template <typename HashTable><br> + void VisualizeHashTableBuckets(const HashTable& h)<br> + {<br> + eastl_size_t bucketCount = h.bucket_count();<br> + eastl_size_t largestBucketSize = 0;<br> + <br> + for(eastl_size_t i = 0; i < bucketCount; i++)<br> + largestBucketSize = eastl::max_alt(largestBucketSize, h.bucket_size(i));<br> + <br> + YourPrintFunction("\n --------------------------------------------------------------------------------\n");<br> + <br> + for(eastl_size_t i = 0; i < bucketCount; i++)<br> + {<br> + const eastl_size_t k = h.bucket_size(i) * 80 / largestBucketSize;<br> + <br> + char buffer[16];<br> + sprintf(buffer, "%3u|", (unsigned)i);<br> + YourPrintFunction(buffer);<br> + <br> + for(eastl_size_t j = 0; j < k; j++)<br> + YourPrintFunction("*");<br> + <br> + YourPrintFunction("\n");<br> + }<br> + <br> + YourPrintFunction(" --------------------------------------------------------------------------------\n");<br> + }</font></p> +</blockquote> +<p class="faq-answer"> This results in a graph that looks like the following (with one horizontal bar per bucket). This hashtable has a large number of collisions in each of its 10 buckets. +<blockquote> + <p><font face="Courier New" size="2"> ------------------------------------------------------<br> + 0|********************************************<br> + 1|************************************************<br> + 2|***************************************<br> + 3|********************************************<br> + 4|*****************************************************<br> + 5|*************************************************<br> + 6|****************************************<br> + 7|***********************************************<br> + 8|********************************************<br> + 9|**************************************<br> + 10|********************************************<br> + -----------------------------------------------------</font> +</blockquote> +<h2> Containers</h2> +<p class="faq-question"><a name="Cont.1"></a>Cont.1 +Why do some containers have "fixed" versions (e.g. fixed_list) but others(e.g. deque) don't have fixed versions?</p> +<p class="faq-answer">Recall that fixed containers are those that are implemented via a single contiguous block of memory and don't use a general purpose heap to allocate memory from. For example, fixed_list is a list container that implements its list by a user-configurable fixed block of memory. Such containers have an upper limit to how many items they can hold, but have the advantage of being more efficient with memory use and memory access coherency.</p> +<p class="faq-answer">The reason why some containers don't have fixed versions is that such functionality doesn't make sense with these containers. Containers which don't have fixed versions include:</p> +<pre class="code-example">array, deque, bitset, stack, queue, priority_queue, +intrusive_list, intrusive_hash_map, intrusive_hash_set, +intrusive_hash_multimap, intrusive_hash_multimap, +vector_map, vector_multimap, vector_set, vector_multiset.</pre> +<p class="faq-answer">Some of these containers are adapters which wrap other containers and thus there is no need for a fixed version because you can just wrap a fixed container. In the case of intrusive containers, the user is doing the allocation and so there are no memory allocations. In the case of array, the container is a primitive type which doesn't allocate memory. In the case of deque, it's primary purpose for being is to dynamically resize and thus the user would likely be better of using a fixed_vector.</p> +<p class="faq-question"> <a name="Cont.2"></a>Cont.2 +Can I mix EASTL with standard C++ STL?</p> +<p class="faq-answer">This is possible to some degree, though the extent depends on the implementation of C++ STL. One of things that makes interoperability is something called iterator categories. Containers and algorithms recognize iterator types via their category and STL iterator categories are not recognized by EASTL and vice versa.</p> +<p class="faq-answer">Things that you definitely can do:</p> +<ul> + <li>#include both EASTL and standard STL headers from the same .cpp file.</li> + <li>Use EASTL containers to hold STL containers.</li> + <li>Construct an STL reverse_iterator from an EASTL iterator.</li> + <li>Construct an EASTL reverse_iterator from an STL iterator.</li> +</ul> +<p class="faq-answer">Things that you probably will be able to do, though a given std STL implementation may prevent it: +</p> +<ul> + <li>Use STL containers in EASTL algorithms.</li> + <li>Use EASTL containers in STL algorithms.</li> + <li>Construct or assign to an STL container via iterators into an EASTL container.</li> + <li>Construct or assign to an EASTL container via iterators into an STL container.</li> +</ul> +<p class="faq-answer">Things that you would be able to do if the given std STL implementation is bug-free: +</p> +<ul> + <li>Use STL containers to hold EASTL containers. Unfortunately, VC7.x STL has a confirmed bug that prevents this. Similarly, STLPort versions prior to v5 have a similar but.</li> +</ul> +<p class="faq-answer">Things that you definitely can't do: +</p> +<ul> + <li>Use an STL allocator directly with an EASTL container (though you can use one indirectly).</li> + <li>Use an EASTL allocator directly with an STL container (though you can use one indirectly).</li> +</ul> +<p class="faq-question"> <a name="Cont.3"></a>Cont.3 +Why are there so many containers?</p> +<p class="faq-answer">EASTL has a large number of container types (e.g vector, list, set) and often has a number of variations of given types (list, slist, intrusive_list, fixed_list). The reason for this is that each container is tuned and to a specific need and there is no single container that works for all needs. The more the user is concerned about squeezing the most performance out of their system, the more the individual container variations become significant. It's important to note that having additional container types generally does not mean generating additional code or code bloat. Templates result in generated code regardless of what templated class they come from, and so for the most part you get optimal performance by choosing the optimal container for your needs.</p> +<p class="faq-question"> <a name="Cont.4"></a>Cont.4 +Don't STL and EASTL containers fragment memory?</p> +<p class="faq-answer">They only fragment memory if you use them in a way that does so. This is no different from any other type of container used in a dynamic way. There are various solutions to this problem, and EASTL provides additional help as well:</p> +<ul> + <li>For vectors, use the reserve function (or the equivalent constructor) to set aside a block of memory for the container. The container will not reallocate memory unless you try grow beyond the capacity you reserve.</li> + <li>EASTL has "fixed" variations of containers which allow you to specify a fixed block of memory which the container uses for its memory. The container will not allocate any memory with these types of containers and all memory will be cache-friendly due to its locality.</li> + <li>You can assign custom allocators to containers instead of using the default global allocator. You would typically use an allocator that has its own private pool of memory.</li> + <li>Where possible, add all a container's elements to it at once up front instead of adding them over time. This avoids memory fragmentation and increase cache coherency.</li> +</ul> +<p class="faq-question"><a name="Cont.5"></a>Cont.5 + I don't see container optimizations for equivalent scalar types such +as pointer types. Why?</p> +<p>Metrowerks (and no other, as of this writing) STL has some container specializations for type T* which maps them to type void*. The idea is that a user who declares a list of Widget* and a list of Gadget* will generate only one container: a list of void*. As a result, code generation will be smaller. Often this is done only in optimized builds, as such containers are harder to view in debug builds due to type information being lost.<br> +<br> +The addition of this optimization is under consideration for EASTL, though it might be noted that optimizing compilers such as VC++ are already capable of recognizing duplicate generated code and folding it automatically as part of link-time code generation (LTCG) (a.k.a. "whole program optimization"). This has been verified with VC++, as the following code and resulting disassembly demonstrate:</p> +<pre class="code-example">eastl::list<int*> intPtrList; +eastl::list<TestObject*> toPtrList; + +eastl_size_t n1 = intPtrList.size(); +eastl_size_t n2 = toPtrList.size(); + +0042D288 lea edx,[esp+14h] +0042D28C <span style="color: rgb(51, 51, 255);">call eastl::list<TestObject>::size (414180h)</span> +0042D291 push eax +0042D292 lea edx,[esp+24h] +0042D296 <span style="color: rgb(51, 51, 255);">call eastl::list<TestObject>::size (414180h)</span></pre> +Note that in the above case the compiler folded the two implementations of size() into a single implementation.<br> +<p class="faq-question"><a name="Cont.6"></a>Cont.6 +What about alternative container and algorithm implementations (e.g. treaps, skip lists, avl trees)?</p> +<p class="faq-answer">EASTL chooses to implement some alternative containers and algorithms and not others. It's a matter of whether or not the alternative provides truly complementary or improved functionality over existing containers. The following is a list of some implemented and non-implemented alternatives and the rationale behind each:</p> +<p class="faq-answer">Implemented:</p> +<ul> + <li>intrusive_list, etc. -- Saves memory and improves cache locality.</li> + <li>vector_map, etc. -- Saves memory and improves cache locality.</li> + <li>ring_buffer -- Useful for some types of operations and has no alternative.</li> + <li>shell_sort -- Useful sorting algorithm.</li> + <li>sparse_matrix -- Useful for some types of operations and has no alternative.</li> +</ul> +<p class="faq-answer">Not implemented: +</p> +<ul> + <li>skip lists (alternative to red-black tree) -- These use more memory and usually perform worse than rbtrees.</li> + <li>treap (alternative to red-black tree) -- These are easier and smaller than rbtrees, but perform worse.</li> + <li>avl tree (alternative to red-black tree) -- These have slightly better search performance than rbtrees, but significantly worse insert/remove performance.</li> + <li>btree (alternative to red-black tree) -- These are no better than rbtrees.</li> +</ul> +<p class="faq-answer">If you have an idea of something that should be implemented, please suggest it or even provide at least a prototypical implementation.</p> +<p class="faq-question"><a name="Cont.7"></a>Cont.7 +Why are tree-based EASTL containers hard to read with a debugger?</p> +<p class="faq-answer"><span style="font-weight: bold;">Short answer<br> +</span> Maximum performance and design mandates.</p> +<p class="faq-answer"><span style="font-weight: bold;">Long answer</span><br> +You may notice that when you have a tree-based container (e.g. set, map) in the debugger that it isn't automatically able to recognize the tree nodes as containing instances of your contained object. You can get the debugger to do what you want with casting statements in the debug watch window, but this is not an ideal solution. The reason this is happening is that node-based containers always use an anonymous node type as the base class for container nodes. This is primarily done for performance, as it allows the node manipulation code to exist as a single non-templated library of functions and it saves memory because containers will have one or two base nodes as container 'anchors' and you don't want to allocate a node of the size of the user data when you can just use a base node. See list.h for an example of this and some additional in-code documentation on this.</p> +<p class="faq-answer">Additionally, EASTL has the design mandate that an empty container constructs no user objects. This is both for performance reasons and because it doing so would skew the user's tracking of object counts and might possibly break some expectation the user has about object lifetimes.</p> +<p class="faq-answer">Currently this debug issue exists only with tree-based containers. Other node-based containers such as list and slist use a trick to get around this problem in debug builds.</p> +<p class="faq-question"><a name="Cont.8"></a>Cont.8 +How do I assign a custom allocator to an EASTL container?</p> +<p class="faq-answer">There are two ways of doing this:</p> +<ol> + <li>Use the set_allocator function that is present in each container.</li> + <li>Specify a new allocator type via the Allocator template parameter that is present in each container.</li> +</ol> +<p class="faq-answer">For item #1, EASTL expects that you provide an instance of an allocator of the type that EASTL recognizes. This is simple but has the disadvantage that all such allocators must be of the same class. The class would need to have C++ virtual functions in order to allow a given instance to act differently from another instance.</p> +<p class="faq-answer">For item #2, you specify that the container use your own allocator class. The advantage of this is that your class can be implemented any way you want and doesn't require virtual functions for differentiation from other instances. Due to the way C++ works your class would necessarily have to use the same member function names as the default allocator class type. In order to make things easier, we provide a skeleton allocator here which you can copy and fill in with your own implementation.</p> +<pre class="code-example">class custom_allocator +{ +public: + custom_allocator(const char* pName = EASTL_NAME_VAL("custom allocator")) + { + #if EASTL_NAME_ENABLED + mpName = pName ? pName : EASTL_ALLOCATOR_DEFAULT_NAME; + #endif + + // Possibly do something here. + } + + custom_allocator(const allocator& x, const char* pName = EASTL_NAME_VAL("custom allocator")); + { + #if EASTL_NAME_ENABLED + mpName = pName ? pName : EASTL_ALLOCATOR_DEFAULT_NAME; + #endif + + // Possibly copy from x here. + } + + ~custom_allocator(); + { + // Possibly do something here. + } + + custom_allocator& operator=(const custom_allocator& x) + { + // Possibly copy from x here. + return *this; + } + + void* allocate(size_t n, int flags = 0) + { + // Implement the allocation here. + } + + void* allocate(size_t n, size_t alignment, size_t offset, int flags = 0) + { + // Implement the allocation here. + } + + void deallocate(void* p, size_t n) + { + // Implement the deallocation here. + } + + const char* get_name() const + { + #if EASTL_NAME_ENABLED + return mpName; + #else + return "custom allocator"; + #endif + } + + void set_name(const char* pName) + { + #if EASTL_NAME_ENABLED + mpName = pName; + #endif + } + +protected: + // Possibly place instance data here. + + #if EASTL_NAME_ENABLED + const char* mpName; // Debug name, used to track memory. + #endif +}; + + +inline bool operator==(const allocator& a, const allocator& b) +{ + // Provide a comparison here. +} + +inline bool operator!=(const allocator& a, const allocator& b) +{ + // Provide a negative comparison here. +}</pre> +<p class="faq-answer"> Here's an example of how to use the above custom allocator:</p> +<pre class="code-example">// Declare a Widget list and have it default construct. +list<Widget, custom_allocator> widgetList; + +// Declare a Widget list and have it construct with a copy of some global allocator. +list<Widget, custom_allocator> widgetList2(gSomeGlobalAllocator); + +// Declare a Widget list and have it default construct, but assign +// an underlying implementation after construction. +list<Widget, custom_allocator> widgetList; +widgetList.get_allocator().mpIAllocator = new WidgetAllocatorImpl;</pre> + +<p class="faq-question"><a name="Cont.9"></a>Cont.9 How do I set the VC++ debugger to display EASTL container data with tooltips?</p> +<p class="faq-answer">Visual Studio supports this via the AutoExp.dat file, an example of which is <a href="AutoExp.dat">present</a> with this documentation. </p> +<p class="faq-answer">Sometimes the AutoExp.dat doesn't seem to work. Avery Lee's explanation:</p> +<blockquote> + <p class="faq-answer style5"> If I had to take a guess, the problem is most likely in the cast to the concrete node type. These are always tricky because, for some strange reason, the debugger is whitespace sensitive with regard to specifying template types. You might try manually checking one of the routines of the specific map instantiation and checking that the placement of whitespace and const within the template expression still matches exactly. In some cases the compiler uses different whitespace rules depending on the value type which makes it impossible to correctly specify a single visualizer – this was the case for eastl::list<>, for which I was forced to include sections for both cases. The downside is that you have a bunch of (error) entries either way. </p> +</blockquote> +<p class="faq-question"> <a name="Cont.10"></a>Cont.10 +How do I use a memory pool with a container?</p> +<p class="faq-answer">Using custom memory pools is a common technique for decreasing memory fragmentation and increasing memory cache locality. EASTL gives you the flexibility of defining your own memory pool systems for containers. There are two primary ways of doing this:</p> +<ul> + <li>Assign a custom allocator to a container. eastl::fixed_pool provides an implementation.</li> + <li>Use one of the EASTL fixed containers, such as fixed_list.</li> +</ul> +<p class="faq-answer"><span style="font-weight: bold;">Custom Allocator</span><br> +In the custom allocator case, you will want to create a memory pool and assign it to the container. For purely node-based containers such as list, slist, map, set, multimap, and multiset, your pool simply needs to be able to allocate list nodes. Each of these containers has a member typedef called node_type which defines the type of node allocated by the container. So if you have a memory pool that has a constructor that takes the size of pool items and the count of pool items, you would do this (assuming that MemoryPool implements the Allocator interface):</p> +<pre class="code-example">typedef list<Widget, MemoryPool> WidgetList; // Declare your WidgetList type. + +MemoryPool myPool(sizeof(WidgetList::node_type), 100); // Make a pool of 100 Widget nodes. +WidgetList myList(&myPool); // Create a list that uses the pool.</pre> +<p class="faq-answer">In the case of containers that are array-based, such as vector and basic_string, memory pools don't work very well as these containers work on a realloc-basis instead of by adding incremental nodes. What we want to do with these containers is assign a sufficient block of memory to them and reserve() the container's capacity to the size of the memory.</p> +<p class="faq-answer">In the case of mixed containers which are partly array-based and partly node-based, such as hash containers and deque, you can use a memory pool for the nodes but will need a single array block to supply for the buckets (hash containers and deque both use a bucket-like system).</p> +<p class="faq-answer">You might consider using eastl::fixed_pool as such an allocator, as it provides such functionality and allows the user to provide the actual memory used for the pool. Here is some example code:</p> +<pre class="code-example">char buffer[256]; + +list<Widget, fixed_pool> myList; +myList.get_allocator().init(buffer, 256);</pre> +<p class="faq-answer"><span style="font-weight: bold;">Fixed Container</span><br> +In the fixed container case, the container does all the work for you. To use a list which implements a private pool of memory, just declare it like so:</p> +<pre class="code-example">fixed_list<Widget, 100> fixedList; // Declare a fixed_list that can hold 100 Widgets</pre> +<p class="faq-question"><a name="Cont.11"></a>Cont.11 +How do I write a comparison (operator<()) for a struct that contains two or more members? </p> +<p class="faq-answer">See <a href="#Algo.2">Algo.2</a></p> +<p class="faq-question"> <a name="Cont.12"></a>Cont.12 +Why doesn't container X have member function Y?</p> +<p class="faq-answer">Why don't the list or vector containers have a find() function? Why doesn't the vector container have a sort() function? Why doesn't the string container have a mid() function? These are common examples of such questions.</p> +<p class="faq-answer">The answer usually boils down to two reasons:</p> +<ul> + <li>The functionality exists in a more centralized location elsewhere, such as the algorithms.</li> + <li>The functionality can be had by using other member functions.</li> +</ul> +<p class="faq-answer">In the case of find and sort functions not being part of containers, the find algorithm and sort algorithm are centralized versions that apply to <span style="font-style: italic;">any</span> container. Additionally, the algorithms allow you to specify a sub-range of the container on which to apply the algorithm. So in order to find an element in a list, you would do this:<br> +</p> +<div class="code-example">list<int>::iterator i = find(list.begin(), list.end(), 3);</div> +<p class="faq-answer">And in order to sort a vector, you would do this:<br> +</p> +<div class="code-example">quick_sort(v.begin(), v.end()); // Sort the entire array. + <br> +quick_sort(&v[3], &v[8]); // Sort the items at the indexes in the range of [3, 8).</div> +<p class="faq-answer">In the case of functionality that can be had by using other member functions, +note that EASTL follows the philosophy that duplicated functionality should not exist in a container, +with exceptions being made for cases where mistakes and unsafe practices commonly happen if the given +function isn't present. In the case of string not having a mid function, this is because there is a +string constructor that takes a sub-range of another string. So to make a string out of the middle of +another, you would do this:</p> +<pre class="code-example">string strMid(str, 3, 5); // Make a new string of the characters from the source range of [3, 3+5).</pre> +<p class="faq-answer"> It might be noted that the EASTL string class is unique among EASTL containers in that it sometimes violates the minimum functionality rule. This is so because the std C++ string class similarly does so and EASTL aims to be compatible.</p> +<p class="faq-question"><a name="Cont.13"></a>Cont.13 +How do I search a hash_map of strings via a char pointer efficiently? If I use map.find("hello") it creates a temporary string, which is inefficient.</p> +<p class="faq-answer">The problem is illustrated with this example:</p> +<pre class="code-example">map<string, Widget> swMap; + ... +map<string, Widget>::iterator it = swMap.find("blue"); // A temporary string object is created here.</pre> +<p class="faq-answer">In this example, the find function expects a string object and not a string literal and so (silently!) creates a temporary string object for the duration of the find. There are two solutions to this problem: +</p> +<ul> + <li>Make the map a map of char pointers instead of string objects. Don't forget to write a custom compare or else the default comparison function will compare pointer values instead of string contents.</li> + <li>Use the EASTL hash_map::find_as function, which allows you to find an item in a hash container via an alternative key than the one the hash table uses.</li> +</ul> +<p class="faq-question"><a name="Cont.14"></a>Cont.14 +Why are set and hash_set iterators const (i.e. const_iterator)?</p> +<p class="faq-answer">The situation is illustrated with this example:</p> +<pre class="code-example">set<int> intSet; + +intSet.insert(1); +set<int>::iterator i = intSet.begin(); +*i = 2; // Error: iterator i is const.</pre> +<p class="faq-answer">In this example, the iterator is a regular iterator and not a const_iterator, yet the compiler gives an error when trying to change the iterator value. The reason this is so is that a set is an ordered container and changing the value would make it out of order. Thus, set and multiset iterators are always const_iterators. If you need to change the value and are sure the change will not alter the container order, use const_cast or declare mutable member variables for your contained object. This resolution is the one blessed by the C++ standardization committee.</p> + +<p class="faq-question"><a name="Cont.15"></a>Cont.15 +How do I prevent my hash container from re-hashing?</p> +<p class="faq-answer">If you want to make a hashtable never re-hash (i.e. increase/reallocate its bucket count), +call set_max_load_factor with a very high value such as 100000.f.</p> +<p class="faq-answer">Similarly, you can control the bucket growth factor with the rehash_policy function. +By default, when buckets reallocate, they reallocate to about twice their previous count. +You can control that value as with the example code here:</p> +<pre class="code-example">hash_set<int> hashSet; +hashSet.rehash_policy().mfGrowthFactor = 1.5f</pre> + +<p class="faq-question"> + <a name="Cont.16"></a>Cont.16 +Which uses less memory, a map or a hash_map? +</p> +<p class="faq-answer">A hash_map will virtually always use less memory. A hash_map will use an average of two pointers per stored element, while a map uses three pointers per stored element.</p> +<p class="faq-question"> <a name="Cont.17"></a>Cont.17 +How do I write a custom hash function?</p> +<p class="faq-answer">You can look at the existing hash functions in functional.h, but we provide a couple examples here.</p> +<p class="faq-answer">To write a specific hash function for a Widget class, you would do this:</p> +<pre class="code-example">struct WidgetHash { + size_t operator()(const Widget& w) const + { return w.id; } +}; + +hash_set<Widget, WidgetHash> widgetHashSet;</pre> +<p class="faq-answer">To write a generic (templated) hash function for a set of similar classes (in this case that have an id member), you would do this:<br> +</p> +<pre class="code-example">template <typename T> +struct GeneralHash { + size_t operator()(const T& t) const + { return t.id; } +}; + +hash_set<Widget, GeneralHash<Widget> > widgetHashSet; +hash_set<Dogget, GeneralHash<Dogget> > doggetHashSet;</pre> + +<p class="faq-question"> <a name="Cont.18"></a>Cont.18 +How do I write a custom compare function for a map or set?</p> +<p class="faq-answer"> The sorted containers require that an operator< exist for the stored values or that the user provide a suitable custom comparison function. A custom can be implemented like so:<br> +</p> +<div class="code-example">struct WidgetLess { + bool operator()(const Widget& w1, const Widget& w2) const + { return w.id < w2.id; } +}; + +set<Widget, WidgetLess> wSet;</div> +<p class="faq-answer">It's important that your comparison function must be consistent in its behaviour, else the container will either be unsorted or a crash will occur. This concept is called "strict weak ordering."</p> +<p class="faq-question"><a name="Cont.19"></a>Cont.19 +How do I force my vector or string capacity down to the size of the container?</p> +<p class="faq-answer">You can simply use the set_capacity() member function which is present in both vector and string. This is a function that is not present in std STL vector and string functions.</p> +<pre class="code-example">eastl::vector<Widget> x; +x.set_capacity(); // Shrink x's capacity to be equal to its size. + +eastl::vector<Widget> x; +x.set_capacity(0); // Completely clear x.</pre> +<p> To compact your vector or string in a way that would also work with std STL you need to do the following.</p> +<p> How to shrink a vector's capacity to be equal to its size:</p> +<pre class="code-example">std::vector<Widget> x; +std::vector<Widget>(x).swap(x); // Shrink x's capacity.</pre> +How to completely clear a std::vector (size = 0, capacity = 0, no allocation):<br> +<pre class="code-example">std::vector<Widget> x; +std::vector<Widget>().swap(x); // Completely clear x. +</pre> +<p class="faq-question"> <a name="Cont.20"></a>Cont.20 +How do I iterate a container while (selectively) removing items from it?</p> +<p class="faq-answer">All EASTL containers have an erase function which takes an iterator as an argument and returns an iterator to the next item. Thus, you can erase items from a container while iterating it like so:</p> +<pre class="code-example">set<int> intSet;<br> +set<int>::iterator i = intSet.begin();<br> +while(i != intSet.end()) +{ + if(*i & 1) <span class="code-example-comment">// Erase all odd integers from the container.</span> + i = intSet.erase(i); + else + ++i; +}</pre> +<p class="faq-question"><a name="Cont.21"></a>Cont.21 +How do I store a pointer in a container?</p> +<p class="faq-answer"> The problem with storing pointers in containers is that clearing the container will not +free the pointers automatically. There are two conventional resolutions to this problem:</p> +<ul> + <li>Manually free pointers when removing them from containers. </li> + <li>Store the pointer as a smart pointer instead of a "raw"pointer.</li> +</ul> +<p class="faq-answer">The advantage of the former is that it makes the user's intent obvious and prevents the possibility of smart pointer "thrashing" with some containers. The disadvantage of the former is that it is more tedicous and error-prone.</p> +<p class="faq-answer">The advantage of the latter is that your code will be cleaner and will always be error-free. The disadvantage is that it is perhaps slightly obfuscating and with some uses of some containers it can cause smart pointer thrashing, whereby a resize of a linear container (e.g. vector) can cause shared pointers to be repeatedly incremented and decremented with no net effect.</p> +<p class="faq-answer">It's important that you use a shared smart pointer and not an unshared one such as C++ auto_ptr, as the latter will result in crashes upon linear container resizes. Here we provide an example of how to create a list of smart pointers:</p> +<pre class="code-example">list< shared_ptr<Widget> > wList; + +wList.push_back(shared_ptr<Widget>(new Widget)); +wList.pop_back(); // The Widget will be freed.</pre> +<p class="faq-question"><a name="Cont.22"></a>Cont.22 +How do I make a union of two containers? difference? intersection?</p> +<p class="faq-answer">The best way to accomplish this is to sort your container (or use a sorted container such as set) and then apply the set_union, set_difference, or set_intersection algorithms.</p> +<p class="faq-question"><a name="Cont.23"></a>Cont.23 +How do I override the default global allocator? </p> +<p class="faq-answer">There are multiple ways to accomplish this. The allocation mechanism is defined in EASTL/internal/config.h and in allocator.h/cpp. Overriding the default global allocator means overriding these files, overriding what these files refer to, or changing these files outright. Here is a list of things you can do, starting with the simplest:</p> +<ul> + <li>Simply provide the following versions of operator new (which EASTL requires, actually):<br> + <small><span style="font-family: Helvetica,Arial,sans-serif;"> void* operator new[](size_t size, const char* pName, int flags, unsigned debugFlags, const char* file, int line);</span><br style= +"font-family: Helvetica,Arial,sans-serif;"> + <span style="font-family: Helvetica,Arial,sans-serif;"> void* operator new[](size_t size, size_t alignment, size_t alignmentOffset, const char* pName, int flags, unsigned debugFlags, const char* file, int line);</span></small></li> + <li>Predefine the config.h macros for EASTLAlloc, EASTLFree, etc. See config.h for this.</li> + <li>Override config.h entirely via EASTL_USER_CONFIG_HEADER. See config.h for this.</li> + <li>Provide your own version of allocator.h/cpp</li> + <li>Provide your own version of config.h. </li> +</ul> +<p class="faq-answer">If you redefine the allocator class, you can make it work however you want.</p> +<p class="faq-answer">Note that config.h defines EASTLAllocatorDefault, which returns the default allocator instance. As documented in config.h, this is not a global allocator which implements all container allocations but is the allocator that is used when EASTL needs to allocate memory internally. There are very few cases where EASTL allocates memory internally, and in each of these it is for a sensible reason that is documented to behave as such.</p> +<p class="faq-question"> <a name="Cont.24"></a>Cont.24 +How do I do trick X with the string container?</p> +<p class="faq-answer">There seem to be many things users want to do with strings. Perhaps the most commonly requested EASTL container extensions are string class shortcut functions. While some of these requests are being considered, we provide some shortcut functions here.<br> +<br> +<span style="font-weight: bold;">find_and_replace</span></p> +<pre class="code-example">template <typename String> +void find_and_replace(String& s, const typename String::value_type* pFind, const typename String::value_type* pReplace) +{ + for(size_t i; (i = source.find(pFind)) != T::npos; ) + s.replace(i, eastl::CharStrlen(pFind), pReplace); +} + +Example:<span class="style1"> +</span> find_and_replace(s, "hello", "hola");</pre> +<p class="faq-answer"><span style="font-weight: bold;">trim front</span> (multiple chars)</p> +<pre class="code-example">template <typename String> +void trim_front(String& s, const typename String::value_type* pValues) +{ + s.erase(0, s.find_first_not_of(pValues)); +} + +Example: + trim_front(s, " \t\n\r");</pre> +<p class="faq-answer"><span style="font-weight: bold;">trim back</span> (multiple chars)</p> +<pre class="code-example">template <typename String> +void trim_front(String& s, const typename String::value_type* pValues) +{ + s.resize(s.find_last_not_of(pValues) + 1); +} + +Example: + trim_back(s, " \t\n\r");</pre> +<p class="faq-answer">prepend</p> +<pre class="code-example">template <typename String> +void prepend(String& s, const typename String::value_type* p) +{ + s.insert(0, p); +} + +Example: + prepend(s, "log: ");</pre> +<p><span class="faq-answer" style="font-weight: bold;">begins_with</span> +</p> +<pre class="code-example">template <typename String> +bool begins_with(const String& s, const typename String::value_type* p) +{ + return s.compare(0, eastl::CharStrlen(p), p) == 0; +} + +Example: + if(begins_with(s, "log: ")) ...</pre> +<p class="faq-answer">ends_with</p> +<pre class="code-example">template <typename String> +bool ends_with(const String& s, const typename String::value_type* p) +{ + const typename String::size_type n1 = s.size(); + const typename String::size_type n2 = eastl::CharStrlen(p); + return ((n1 >= n2) && s.compare(n1 - n2, n2, p) == 0); +} + +Example: + if(ends_with(s, "test.")) ...</pre> +<p class="faq-answer"><span style="font-weight: bold;">tokenize</span><br> +Here is a simple tokenization function that acts very much like the C strtok function. </p> +<pre class="code-example">template <typename String> +size_t tokenize(const String& s, const typename String::value_type* pDelimiters, + String* resultArray, size_t resultArraySize) +{ + size_t n = 0; + typename String::size_type lastPos = s.find_first_not_of(pDelimiters, 0); + typename String::size_type pos = s.find_first_of(pDelimiters, lastPos); + + while((n < resultArraySize) && (pos != String::npos) || (lastPos != String::npos)) + { + resultArray[n++].assign(s, lastPos, pos - lastPos); + lastPos = s.find_first_not_of(pDelimiters, pos); + pos = s.find_first_of(pDelimiters, lastPos); + } + + return n; +} + +Example: + string resultArray[32]; +tokenize(s, " \t", resultArray, 32));</pre> + +<p class="faq-question"><a name="Cont.25"></a>Cont.25 How do EASTL smart pointers compare to Boost smart pointers? </p> +<p class="faq-answer">EASTL's smart pointers are nearly identical to Boost (including all that crazy member template and dynamic cast functionality in shared_ptr), but are not using the Boost source code. EA legal has already stated that it is fine to have smart pointer classes with the same names and functionality as those present in Boost. EA legal specifically looked at the smart pointer classes in EASTL for this. There are two differences between EASTL smart pointers and Boost smart pointers:</p> +<ul> + <li>EASTL smart pointers don't have thread safety built-in. It was deemed that this is too much overhead and that thread safety is something best done at a higher level. By coincidence the C++ library proposal to add shared_ptr also omits the thread safety feature. FWIW, I put a thread-safe shared_ptr in EAThread, though it doesn't attempt to do all the fancy member template things that Boost shared_ptr does. Maybe I'll add that some day if people care.</li> +</ul> +<ul> + <li>EASTL shared_ptr object deletion goes through a deletion object instead of through a virtual function interface. 95% of the time this makes no difference (aside from being more efficient), but the primary case where it matters is when you have shared_ptr<void> and assign to is something like "new Widget". The problem is that shared_ptr<void> doesn't know what destructor to call and so doesn't call a destructor unless you specify a custom destructor object as part of the template specification. I don't know what to say about this one, as it is less safe, but forcing everybody to have the overhead of additional templated classes and virtual destruction functions doesn't seem to be in the spirit of high performance or lean game development.</li> +</ul> +<p class="faq-answer">There is the possibility of making a shared_ptr_boost which is completely identical to Boost shared_ptr. So perhaps that will be done some day.</p> +<p class="faq-question"><a name="Cont.26"></a>Cont.26 +How do your forward-declare an EASTL container?</p> +<p class="faq-answer">Here is are some examples of how to do this:</p> +<pre class="code-example">namespace eastl +{ + template <typename T, typename Allocator> class basic_string; + typedef basic_string<char, allocator> string8; <span class="code-example-comment">// Forward declare EASTL's string8 type.</span> + + template <typename T, typename Allocator> class vector; + typedef vector<char, allocator> CharArray; + + template <typename Value, typename Hash, typename Predicate, typename Allocator, bool bCacheHashCode> class hash_set; + + template <typename Key, typename T, typename Compare, typename Allocator> class map; +}</pre> +<p class="faq-answer">The forward declaration can be used to declare a pointer or reference to such a class. It cannot be used to declare an instance of a class or refer to class data, static or otherwise. Nevertheless, forward declarations for pointers and references are useful for reducing the number of header files a header file needs to include.</p> +<p class="faq-question"> <a name="Cont.27" id="Cont.27"></a>Cont.27 +How do I make two containers share a memory pool?</p> +<p class="faq-answer">EASTL (and std STL) allocators are specified by value semantics and not reference semantics. Value semantics is more powerful (because a value can also be a reference, but not the other way around), but is not always what people expects if they're used to writing things the other way.</p> +<p class="faq-answer">Here is some example code:</p> +<pre class="code-example">struct fixed_pool_reference<br>{<br>public:<br> fixed_pool_reference()<br> {<br> mpFixedPool = NULL;<br> }<br> <br> fixed_pool_reference(eastl::fixed_pool& fixedPool)<br> {<br> mpFixedPool = &fixedPool;<br> }<br> <br> fixed_pool_reference(const fixed_pool_reference& x)<br> {<br> mpFixedPool = x.mpFixedPool;<br> }<br> <br> fixed_pool_reference& operator=(const fixed_pool_reference& x)<br> {<br> mpFixedPool = x.mpFixedPool;<br> return *this;<br> }<br> <br> void* allocate(size_t /*n*/, int /*flags*/ = 0)<br> {<br> return mpFixedPool->allocate();<br> }<br> <br> void* allocate(size_t /*n*/, size_t /*alignment*/, size_t /*offset*/, int /*flags*/ = 0)<br> {<br> return mpFixedPool->allocate();<br> }<br> <br> void deallocate(void* p, size_t /*n*/)<br> {<br> return mpFixedPool->deallocate(p);<br> }<br> <br> const char* get_name() const<br> {<br> return "fixed_pool_reference";<br> }<br> <br> void set_name(const char* /*pName*/)<br> {<br> }<br> <br>protected:<br> friend bool operator==(const fixed_pool_reference& a, const fixed_pool_reference& b);<br> friend bool operator!=(const fixed_pool_reference& a, const fixed_pool_reference& b);<br> <br> eastl::fixed_pool* mpFixedPool;<br>}; + +inline bool operator==(const fixed_pool_reference& a, const fixed_pool_reference& b) +{ + return (a.mpFixedPool == b.mpFixedPool);<br>} + +inline bool operator!=(const fixed_pool_reference& a, const fixed_pool_reference& b) +{ + return (a.mpFixedPool != b.mpFixedPool); +}</pre> + <p class="faq-answer"> Example usage of the above:</p> +<pre class="code-example">typedef eastl::list<int, fixed_pool_reference> IntList; + +IntList::node_type buffer[2]; +eastl::fixed_pool myPool(buffer, sizeof(buffer), sizeof(Int::node_type), 2); + +IntList myList1(myPool); +IntList myList2(myPool); + +myList1.push_back(37); +myList2.push_back(39);</pre> +<p class="faq-question"><a name="Cont.28"></a>Cont.28 +Can I use a std (STL) allocator with EASTL?</p> +<p class="faq-answer">No. EASTL allocators are similar in interface to std STL allocators, but not 100% compatible. If it was possible to make them compatible with std STL allocators but also match the design of EASTL then compatibility would exist. The primary reasons for lack of compatibility are:</p> +<ul> + <li>EASTL allocators have a different allocate function signature.</li> + <li>EASTL allocators have as many as four extra required functions: ctor(name), get_name(), set_name(), allocate(size, align, offset).</li> + <li>EASTL allocators have an additional allocate function specifically for aligned allocations, as listed directly above.</li> +</ul> +<p class="faq-question"><a name="Cont.29" id="Cont.29"></a>What are the requirements of classes stored in containers?</p> +<p class="faq-answer">Class types stored in containers must have:</p> +<ul> + <li>a public copy constructor</li> + <li>a public assignment operator</li> + <li>a public destructor</li> + <li>an operator < that compares two such classes (sorted containers only).</li> + <li>an operator == that compares two such classes (hash containers only). </li> +</ul> +<p class="faq-answer">Recall that the compiler generates basic versions these functions for you when you don't implement them yourself, so you can omit any of the above if the compiler-generated version is sufficient. </p> +<p class="faq-answer">For example, the following code will act incorrectly, because the user forgot to implement an assignment operator. The compiler-generated assignment operator will assign the refCount value, which the user doesn't want, and which will be called by the vector during resizing. </p> +<pre class="code-example">struct NotAPod +{ + NotAPod(const NotAPod&) {} <span class="code-example-comment">// Intentionally don't copy the refCount </span><br> + int refCount; <span class="code-example-comment">// refCounts should not be copied between NotAPod instances.</span> +}; + +eastl::vector<NotAPod> v;</pre> +<h2>Algorithms</h2> +<p class="faq-question"> <a name="Algo.1"></a>Algo.1 + I'm getting screwy behavior in sorting algorithms or sorted +containers. What's wrong?</p> +<p class="faq-answer">It may possible that you are seeing floating point roundoff problems. Many STL algorithms require object comparisons to act consistently. However, floating point values sometimes compare differently between uses because in one situation a value might be in 32 bit form in system memory, whereas in anther situation that value might be in an FPU register with a different precision. These are difficult problems to track down and aren't the fault of EASTL or whatever similar library you might be using. There are various solutions to the problem, but the important thing is to find a way to force the comparisons to be consistent.</p> +<p class="faq-answer">The code below was an example of this happening, whereby the object pA->mPos was stored in system memory while pB->mPos was stored in a register and comparisons were inconsistent and a crash ensued.</p> +<pre class="code-example">class SortByDistance : public binary_function<WorldTreeObject*, WorldTreeObject*, bool> +{ +private: + Vector3 mOrigin; + +public: + SortByDistance(Vector3 origin) { + mOrigin = origin; + } + + bool operator()(WorldTreeObject* pA, WorldTreeObject* pB) const { + return ((WorldObject*)pA)->mPos - mOrigin).GetLength() + < ((WorldObject*)pB)->mPos - mOrigin).GetLength(); + } +};</pre> + +<p class="faq-question"><a name="Algo.2"></a>Algo.2 +How do I write a comparison (operator<()) for a struct that contains two or more members? </p> +<p class="faq-answer">For a struct with two members such as the following:</p> +<pre class="code-example">struct X { + Blah m1; + Blah m2; +};</pre> +<p class="faq-answer">You would write the comparison function like this:</p> +<pre class="code-example">bool operator<(const X& a, const X& b) { + return (a.m1 == b.m1) ? (a.m2 < b.m2) : (a.m1 < b.m1); +}</pre> +<p class="faq-answer">or, using only operator < but more instructions:</p> +<pre class="code-example">bool operator<(const X& a, const X& b) { + return (a.m1 < b.m1) || (!(b.m1 < a.m1) && (a.m2 < b.m2)); +}</pre> +<p class="faq-answer"> For a struct with three members, you would have:</p> +<pre class="code-example">bool operator<(const X& a, const X& b) { + if(a.m1 != b.m1) + return (a.m1 < b.m1); + if(a.m2 != b.m2) + return (a.m2 < b.m2); + return (a.mType < b.mType); +}</pre> +<p class="faq-answer">And a somewhat messy implementation if you wanted to use only operator <.</p> +<p class="faq-answer">Note also that you can use the above technique to implement operator < for spatial types such as vectors, points, and rectangles. You would simply treat the members of the struct as an array of values and ignore the fact that they have spatial meaning. All operator < cares about is that things order consistently.</p> +<pre class="code-example">bool operator<(const Point2D& a, const Point2D& b) { + return (a.x == b.x) ? (a.y < b.y) : (a.x < b.x); +}</pre> +<p class="faq-question"><a name="Algo.3"></a>Algo.3 +How do I sort something in reverse order?</p> +<p class="faq-answer">Normally sorting puts the lowest value items first in the sorted range. You can change this by simply reversing the comparison. For example:<br> +</p> +<div class="code-example">sort(intVector.begin(), intVector.end(), greater<int>());</div> +<p class="faq-answer"> It's important that you use operator > instead of >=. The comparison function must return false for every case where values are equal.</p> +<p class="faq-question"><a name="Algo.4"></a>Algo.4 +I'm getting errors about min and max while compiling.</p> +<p class="faq-answer">You need to define NOMINMAX under VC++ when this occurs, as it otherwise defines min and max macros that interfere. There may be equivalent issues with other compilers. Also, VC++ has a specific <minmax.h> header file which defines min and max macros but which doesn't pay attention to NOMINMAX and so in that case there is nothing to do but not include that file or to undefine min and max. minmax.h is not a standard file and its min and max macros are not standard C or C++ macros or functions.</p> +<p class="faq-question"><a name="Algo.5"></a>Algo.5 +Why don't algorithms take a container as an argument instead of iterators? A container would be more convenient.</p> +<p class="faq-answer">Having algorithms that use containers instead of algorithms would reduce reduce functionality with no increase in performance. This is because the use of iterators allows for the application of algorithms to sub-ranges of containers and allows for the application of algorithms to containers aren't formal C++ objects, such as C-style arrays.</p> +<p class="faq-answer">Providing additional algorithms that use containers would introduce redundancy with respect to the existing algorithms that use iterators.</p> +<p class="faq-question"><a name="Algo.6"></a>Algo.6 +Given a container of pointers, how do I find an element by value (instead of by pointer)?</p> +<p class="faq-answer">Functions such as find_if help you find a T element in a container of Ts. But if you have a container of pointers such as vector<Widget*>, these functions will enable you to find an element that matches a given Widget* pointer, but they don't let you find an element that matches a given Widget object.</p> +<p class="faq-answer">You can write your own iterating 'for' loop and compare values, or you can use a generic function object to do the work if this is a common task:</p> +<pre class="code-example">template<typename T> +struct dereferenced_equal +{ + const T& mValue; + + dereferenced_equal(const T& value) : mValue(value) { } + bool operator==(const T* pValue) const { return *pValue == mValue; } +}; + +... + +find_if(container.begin(), container.end(), dereferenced_equal<Widget>(someWidget));</pre> + +<p class="faq-question"><a name="Algo.7"></a>Algo.7 +When do stored objects need to support <small><span style="font-family: Courier New;">operator <</span></small> vs. when do they need to support <small><span style="font-family: Courier New;">operator ==</span></small>?</p> +<p class="faq-answer">Any object which is sorted needs to have operator < defined for it, implicitly via operator < or explicitly via a user-supplied Compare function. Sets and map containers require operator <, while sort, binary search, and min/max algorithms require operator <.</p> +<p class="faq-answer">Any object which is compared for equality needs to have operator == defined for it, implicitly via operator == or explicitly via a user-supplied BinaryPredicate function. Hash containers required operator ==, while many of the algorithms other than those mentioned above for operator < require operator ==.</p> +<p class="faq-answer">Some algorithms and containers require neither < nor ==. Interestingly, no algorithm or container requires both < and ==.</p> +<p class="faq-question"><a name="Algo.8"></a>Algo.8 How do I sort via pointers or array indexes instead of objects directly?</p> +<p class="faq-answer">Pointers </p> +<pre class="code-example"><span class="style4">vector<TestObject> toArray; +vector<TestObject*> topArray; + +for(eastl_size_t i = 0; i < 32; i++) + toArray.push_back(TestObject(rng.RandLimit(20))); +for(eastl_size_t i = 0; i < 32; i++) // This needs to be a second loop because the addresses might change in the first loop due to container resizing. + topArray.push_back(&toArray[i]); +</span> +struct TestObjectPtrCompare +{ + bool operator()(TestObject* a, TestObject* b) + { return a->mX < a->mX; } +}; + +quick_sort(topArray.begin(), topArray.end(), TestObjectPtrCompare());</pre> +<p class="faq-answer">Array indexes</p> +<pre class="code-example"><span class="style4">vector<TestObject> toArray; +vector<eastl_size_t> toiArray; + +for(eastl_size_t i = 0; i < 32; i++) +{ + toArray.push_back(TestObject(rng.RandLimit(20))); + toiArray.push_back(i); +}</span> + +struct TestObjectIndexCompare +{ + vector<TestObject>* mpArray; + + TestObjectIndexCompare(vector<TestObject>* pArray) : mpArray(pArray) { } + TestObjectIndexCompare(const TestObjectIndexCompare& x) : mpArray(x.mpArray){ } + TestObjectIndexCompare& operator=(const TestObjectIndexCompare& x) { mpArray = x.mpArray; return *this; } + + bool operator()(eastl_size_t a, eastl_size_t b) + { return (*mpArray)[a] < (*mpArray)[b]; } +}; + +quick_sort(toiArray.begin(), toiArray.end(), TestObjectIndexCompare(&toArray)); +</pre> +<p class="faq-answer">Array indexes (simpler version using toArray as a global variable) </p> +<pre class="code-example"><span class="style4">vector<TestObject> toArray; +vector<eastl_size_t> toiArray; + +for(eastl_size_t i = 0; i < 32; i++) +{ + toArray.push_back(TestObject(rng.RandLimit(20))); + toiArray.push_back(i); +}</span> + +struct TestObjectIndexCompare +{ + bool operator()(eastl_size_t a, eastl_size_t b) + { return toArray[a] < toArray[b]; } +}; + +quick_sort(toiArray.begin(), toiArray.end(), TestObjectIndexCompare(&toArray));</pre> +<h2>Iterators</h2> +<p class="faq-question"><a name="Iter.1"></a>Iter.1 +What's the difference between iterator, const iterator, and const_iterator?</p> +<p class="faq-answer">An iterator can be modified and item it points to can be modified.<br> +A const iterator cannot be modified, but the items it points to can be modified.<br> +A const_iterator can be modified, but the items it points to cannot be modified.<br> +A const const_iterator cannot be modified, nor can the items it points to.</p> +<p class="faq-answer">This situation is much like with char pointers:</p> +<div style="margin-left: 40px;"> + <table style="text-align: left; width: 400px;" border="1" cellpadding="2" cellspacing="2"> + <tbody> + <tr> + <td>Iterator type</td> + <td>Pointer equivalent</td> + </tr> + <tr> + <td>iterator</td> + <td>char*</td> + </tr> + <tr> + <td>const iterator</td> + <td>char* const</td> + </tr> + <tr> + <td>const_iterator</td> + <td>const char*</td> + </tr> + <tr> + <td>const const_iterator</td> + <td>const char* const</td> + </tr> + </tbody> + </table> +</div> +<p class="faq-question"><a name="Iter.2"></a>Iter.2 How do I tell from an iterator what type of thing it is iterating?</p> +<p class="faq-answer">Use the value_type typedef from iterator_traits, as in this example</p> +<pre class="code-example">template <typename Iterator> +void DoSomething(Iterator first, Iterator last) +{ + typedef typename iterator_traits<Iterator>::value_type; + + // use value_type +}</pre> +<p class="faq-question"><a name="Iter.3"></a>Iter.3 +How do I iterate a container while (selectively) removing items from it?</p> +<p class="faq-answer">All EASTL containers have an erase function which takes an iterator as an +argument and returns an iterator to the next item. Thus, you can erase items from a container +while iterating it like so:</p> +<pre class="code-example">set<int> intSet; +set<int>::iterator i = intSet.begin(); + +while(i != intSet.end()) +{ + if(*i & 1) // Erase all odd integers from the container. + i = intSet.erase(i); + else + ++i; +}</pre> +<p class="faq-question"><a name="Iter.4"></a>Iter.4 +What is an insert_iterator?</p> +<p class="faq-answer">An insert_iterator is a utility class which is like an iterator except that when you assign a value to it, the insert_iterator inserts the value into the container (via insert()) and increments the iterator. Similarly, there are front_insert_iterator and back_insert_iterator, which are similar to insert_iterator except that assigning a value to them causes then to call push_front and push_back, respectively, on the container. These utilities may seem a slightly abstract, but they have uses in generic programming.<br> +</p> +<hr style="width: 100%; height: 2px;"> +End of document<br> +<br> +<br> +<br> +<br> +</body> +</html> diff --git a/EASTL/doc/html/EASTL Glossary.html b/EASTL/doc/html/EASTL Glossary.html new file mode 100644 index 0000000..bd4b865 --- /dev/null +++ b/EASTL/doc/html/EASTL Glossary.html @@ -0,0 +1,490 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> + <title>EASTL Glossary</title> + <meta content="text/html; charset=us-ascii" http-equiv="content-type"> + <meta name="author" content="Paul Pedriana"> + <meta name="description" content="Definitions of common terms related to EASTL."> + <link type="text/css" rel="stylesheet" href="EASTLDoc.css"> +</head> +<body> +<h1>EASTL Glossary</h1> +<p>This document provides definitions to various terms related to EASTL. Items that are capitalized are items that are +used as template parameters.</p> +<table style="width: 100%; text-align: left;" border="1" cellpadding="2" cellspacing="2"> +<tbody> +<tr> +<td>adapter</td> +<td>An adapter is something that encapsulates a component to provide another interface, such as a C++ class which makes +a stack out of a list.</td> +</tr> +<tr> +<td style="width: 150px; vertical-align: top;">algorithm<br></td> +<td style="vertical-align: top;">Algorithms are standalone functions which manipulate data which usually but not +necessarily comes from a container. Some algorithms change the data while others don't. Examples are reverse, sort, +find, and remove.<br></td> +</tr> +<tr> +<td>associative container</td> +<td>An associative container is a variable-sized container that supports efficient retrieval of elements (values) based +on keys. It supports insertion and removal of elements, but differs from a sequence in that it does not provide a +mechanism for inserting an element at a specific position. Associative containers include map, multimap, set, multiset, +hash_map, hash_multimap, hash_set, hash_multiset.</td> +</tr> +<tr> +<td>array</td> +<td>An array is a C++ container which directly implements a C-style fixed array but which adds STL container semantics +to it.</td> +</tr> +<tr> +<td>basic_string</td> +<td>A templated string class which is usually used to store char or wchar_t strings.</td> +</tr> +<tr> +<td>begin</td> +<td>The function used by all conventional containers to return the first item in the container.</td> +</tr> +<tr> +<td>BidirectionalIterator</td> +<td>An input iterator which is like ForwardIterator except it can be read in a backward direction as well.</td> +</tr> +<tr> +<td>BinaryOperation </td> +<td>A function which takes two arguments and returns a value (which will usually be assigned to a third object).</td> +</tr> +<tr> +<td>BinaryPredicate</td> +<td>A function which takes two arguments and returns true if some criteria is met (e.g. they are equal).</td> +</tr> +<tr> +<td>binder1st, binder2nd</td> +<td>These are function objects which convert one function object into another. In particular, they implement a +binary function whereby you can specify one of the arguments.This is a somewhat abstract concept but has its uses.</td> +</tr> +<tr> +<td>bit vector</td> +<td>A specialized container that acts like vector<bool> but is implemented via one bit per entry. STL +vector<bool> is usually implemented as a bit vector but EASTL avoids this in favor of a specific bit vector +container.</td> +</tr> +<tr> +<td>bitset</td> +<td>An extensible yet efficient implementation of bit flags. Not strictly a conventional STL container and not the same +thing as vector<bool> or a bit_vector, both of which are formal iterate-able containers.</td> +</tr> +<tr> +<td>capacity</td> +<td>Refers to the amount of total storage available in an array-based container such as vector, string, and array. +Capacity is always >= container size and is > size in order to provide extra space for a container to grow +into.</td> +</tr> +<tr> +<td>const_iterator</td> +<td>An iterator whose iterated items are cannot be modified. A const_iterator is akin to a const pointer such as 'const +char*'.</td> +</tr> +<tr> +<td>container</td> +<td>A container is an object that stores other objects (its elements), and that has methods for accessing its elements. +In particular, every type that is a model of container has an associated iterator type that can be used to iterate +through the container's elements.</td> +</tr> +<tr> +<td>copy constructor</td> +<td>A constructor for a type which takes another object of that type as its argument. For a hypothetical Widget class, +the copy constructor is of the form Widget(const Widget& src);</td> +</tr> +<tr> +<td>Compare</td> +<td>A function which takes two arguments and returns the lesser of the two.</td> +</tr> +<tr> +<td>deque</td> +<td>The name deque is pronounced "deck" and stands for "double-ended queue."<br> +<br> +A deque is very much like a vector: like vector, it is a sequence that supports random access to elements, constant +time insertion and removal of elements at the end of the sequence, and linear time insertion and removal of elements in +the middle.<br> +<br> +The main way in which deque differs from vector is that deque also supports constant time insertion and removal of +elements at the beginning of the sequence. Additionally, deque does not have any member functions analogous to vector's +capacity() and reserve(), and does not provide the guarantees on iterator validity that are associated with those +member functions.</td> +</tr> +<tr> +<td>difference_type</td> +<td>The typedef'd type used by all conventional containers and iterators to define the distance between two iterators. +It is usually the same thing as the C/C++ ptrdiff_t data type.</td> +</tr> +<tr> +<td>empty</td> +<td>The function used by all conventional containers to tell if a container has a size of zero. In many cases empty is +more efficient than checking for size() == 0.</td> +</tr> +<tr> +<td>element</td> +<td>An element refers to a member of a container.</td> +</tr> +<tr> +<td>end</td> +<td>The function used by all conventional containers to return one-past the last item in the container.</td> +</tr> +<tr> +<td>equal_range</td> +<td>equal_range is a version of binary search: it attempts to find the element value in an ordered range [first, last). +The value returned by equal_range is essentially a combination of the values returned by lower_bound and upper_bound: +it returns a pair of iterators i and j such that i is the first position where value could be inserted without +violating the ordering and j is the last position where value could be inserted without violating the ordering. It +follows that every element in the range [i, j) is equivalent to value, and that [i, j) is the largest subrange of +[first, last) that has this property.</td> +</tr> +<tr> +<td>explicit instantiation</td> +<td>Explicit instantiation lets you create an instantiation of a templated class or function without actually using it +in your code. Since this is useful when you are creating library files that use templates for distribution, +uninstantiated template definitions are not put into object files. An example of the syntax for explicit +instantiation is:<br> +<small><span style="font-family: Courier New;"> </span></small> <small><span style= +"font-family: Courier New;">template class vector<char>;<br> + template void min<int>(int, int);<br> + template void min(int, int);</span></small></td> +</tr> +<tr> +<td>ForwardIterator</td> +<td>An input iterator which is like InputIterator except it can be reset back to the beginning.</td> +</tr> +<tr> +<td>Function</td> +<td>A function which takes one argument and applies some operation to the target.</td> +</tr> +<tr> +<td>function object, functor</td> +<td>A function object or functor is a class that has the function-call operator (<tt>operator()</tt>) +defined.</td> +</tr> +<tr> +<td>Generator</td> +<td>A function which takes no arguments and returns a value (which will usually be assigned to an object).</td> +</tr> +<tr> +<td>hash_map, hash_multimap, hash_set, hash_multiset</td> +<td>The hash containers are implementations of map, multimap, set, and multiset via a hashtable instead of via a tree. +Searches are O(1) (fast) but the container is not sorted.</td> +</tr> +<tr> +<td>heap</td> +<td>A heap is a data structure which is not necessarily sorted but is organized such that the highest priority item is +at the top. A heap is synonymous with a priority queue and has numerous applications in computer science.</td> +</tr> +<tr> +<td>InputIterator</td> +<td>An input iterator (iterator you read from) which allows reading each element only once and only in a forward +direction.</td> +</tr> +<tr> +<td>intrusive_list, intrusive_hash_map, etc.</td> +<td>Intrusive containers are containers which don't allocate memory but instead use their contained object to manage +the container's memory. While list allocates nodes (with mpPrev/mpNext pointers) that contain the list items, +intrusive_list doesn't allocate nodes but instead the container items have the mpPrev/mpNext pointers.</td> +</tr> +<tr> +<td>intrusive_ptr</td> +<td>intrusive_ptr is a smart pointer which doesn't allocate memory but instead uses the contained object to manage +lifetime via addref and release functions.</td> +</tr> +<tr> +<td>iterator</td> +<td>An iterator is the fundamental entity of reading and enumerating values in a container. Much like a pointer +can be used to walk through a character array, an iterator is used to walk through a linked list.</td> +</tr> +<tr> +<td>iterator category</td> +<td>An iterator category defines the functionality the iterator provides. The conventional iterator categories are +InputIterator, ForwardIterator, BidirectionalIterator, RandomAccessIterator, and OutputIterator. See the definitions of +each of these for more information.Iterator category is synonymous with <span style= +"font-style: italic;">iterator_tag</span>.</td> +</tr> +<tr> +<td>iterator_tag</td> +<td>See <span style="font-style: italic;">iterator category</span>.</td> +</tr> +<tr> +<td>key_type, Key</td> +<td>A Key or key_type is the identifier used by associative (a.k.a. dictionary) containers (e.g. map, hash_map) to +identify the type used to index the mapped_type. If you have a dictionary of strings that you access by an integer id, +the ids are the keys and the strings are the mapped types.</td> +</tr> +<tr> +<td>lexicographical compare</td> +<td>A lexicographical compare is a comparison of two containers that compares them element by element, much like the C +strcmp function compares two strings.</td> +</tr> +<tr> +<td>linked_ptr</td> +<td>A linked_ptr is a shared smart pointer which implements object lifetime via a linked list of all linked_ptrs that +are referencing the object. linked_ptr, like intrusive_ptr, is a non-memory-allocating alternative to shared_ptr.</td> +</tr> +<tr> +<td>list</td> +<td>A list is a doubly linked list. It is a sequence that supports both forward and backward traversal, and (amortized) +constant time insertion and removal of elements at the beginning or the end, or in the middle. Lists have the important +property that insertion and splicing do not invalidate iterators to list elements, and that even removal invalidates +only the iterators that point to the elements that are removed. The ordering of iterators may be changed (that is, +list<T>::iterator might have a different predecessor or successor after a list operation than it did before), but +the iterators themselves will not be invalidated or made to point to different elements unless that invalidation or +mutation is explicit.</td> +</tr> +<tr> +<td>lower_bound</td> +<td>lower_bound is a version of binary search: it attempts to find the element value in an ordered range [first, last). +Specifically, it returns the first position where value could be inserted without violating the ordering.</td> +</tr> +<tr> +<td>map</td> +<td>Map is a sorted associative container that associates objects of type Key with objects of type T. Map is a pair +associative container, meaning that its value type is pair<const Key, T>. It is also a unique associative +container, meaning that no two elements have the same key. It is implemented with a tree structure.</td> +</tr> +<tr> +<td>mapped_type</td> +<td>A mapped_type is a typedef used by associative containers to identify the container object which is accessed by a +key. If you have a dictionary of strings that you access by an integer id, the ids are the keys and the strings are the +mapped types.</td> +</tr> +<tr> +<td>member template</td> +<td>A member template is a templated function of a templated class. Thus with a member template function there are two +levels of templating -- the class and the function.</td> +</tr> +<tr> +<td>multimap, </td> +<td>Multimap is a sorted associative container that associates objects of type Key with objects of type T. +multimap is a pair associative container, meaning that its value type is pair<const Key, T>. It is also a +multiple associative container, meaning that there is no limit on the number of elements with the same key.It is +implemented with a tree structure.</td> +</tr> +<tr> +<td>multiset</td> +<td>Multiset is a sorted associative container that stores objects of type Key. Its value type, as well as its key +type, is Key. It is also a multiple associative container, meaning that two or more elements may be identical. It +is implemented with a tree structure.</td> +</tr> +<tr> +<td>node</td> +<td>A node is a little holder class used by many containers to hold the contained items. A linked-list, for example, +defines a node which has three members: mpPrev, mpNext, and T (the contained object).</td> +</tr> +<tr> +<td>npos</td> +<td>npos is used by the string class to identify a non-existent index. Some string functions return npos to indicate +that the function failed.</td> +</tr> +<tr> +<td>rel_ops</td> +<td>rel_ops refers to "relational operators" and is a set of templated functions which provide operator!= for classes +that have only operator== and provide operator > for classes that have only operator <, etc. Unfortunately, +rel_ops have a habit of polluting the global operator space and creating conflicts. They must be used with +discretion.</td> +</tr> +<tr> +<td>reverse_iterator</td> +<td>A reverse_iterator is an iterator which wraps a bidirectional or random access iterator and allows the iterator to +be read in reverse direction. The difference between using reverse_iterators and just decrementing regular iterators is +that reverse_iterators use operator++ to move backwards and thus work in any algorithm that calls ++ to move through a +container.</td> +</tr> +<tr> +<td>OutputIterator</td> +<td>An output iterator (iterator you write to) which allows writing each element only once in only in a forward +direction.</td> +</tr> +<tr> +<td>POD</td> +<td>POD means Plain Old Data. It refers to C++ classes which act like built-in types and C structs. These are useful to +distinguish because some algorithms can be made more efficient when they can detect that they are working with PODs +instead of regular classes. </td> +</tr> +<tr> +<td>Predicate</td> +<td>A function which takes one argument returns true if the argument meets some criteria.</td> +</tr> +<tr> +<td>priority_queue</td> +<td>A priority_queue is an adapter container which implements a heap via a random access container such as vector or +deque.</td> +</tr> +<tr> +<td>queue</td> +<td>A queue is an adapter container which implements a FIFO (first-in, first-out) container with which you can add +items to the back and get items from the front.</td> +</tr> +<tr> +<td>RandomAccessIterator</td> +<td>An input iterator which can be addressed like an array. It is a superset of all other input iterators.</td> +</tr> +<tr> +<td>red-black tree</td> +<td>A red-black tree is a binary tree which has the property of being always balanced. The colors red and black are +somewhat arbitrarily named monikers for nodes used to measure the balance of the tree. Red-black trees are considered +the best all-around data structure for sorted containers.</td> +</tr> +<tr> +<td>scalar</td> +<td>A scalar is a data type which is implemented via a numerical value. In C++ this means integers, floating point +values, enumerations, and pointers. </td> +</tr> +<tr> +<td>scoped_ptr</td> +<td>A scoped_ptr is a smart pointer which is the same as C++ auto_ptr except that it cannot be copied.</td> +</tr> +<tr> +<td>set</td> +<td>Set is a sorted associative container that stores objects of type Key. Its value type, as well as its key type, is +Key. It is also a unique associative container, meaning that no two elements are the same.It is implemented with a tree +structure.</td> +</tr> +<tr> +<td>sequence</td> +<td>A sequence is a variable-sized container whose elements are arranged in a strict linear (though not necessarily +contiguous) order. It supports insertion and removal of elements. Sequence containers include vector, deque, array, +list, slist.</td> +</tr> +<tr> +<td>size</td> +<td>All conventional containers have a size member function which returns the count of elements in the container. The +efficiency of the size function differs between containers.</td> +</tr> +<tr> +<td>size_type</td> +<td>The type that a container uses to define its size and counts. This is similar to the C/C++ size_t type but may be +specialized for the container. It defaults to size_t, but it is possible to force it to be 4 bytes for 64 bit machines by defining EASTL_SIZE_T_32BIT.</td> +</tr> +<tr> +<td>skip list</td> +<td>A skip-list is a type of container which is an alternative to a binary tree for finding data.</td> +</tr> +<tr> +<td>shared_ptr</td> +<td>A shared_ptr is a smart pointer which allows multiple references (via multiple shared_ptrs) to the same object. +When the last shared_ptr goes away, the pointer is freed. shared_ptr is implemented via a shared count between all +instances.</td> +</tr> +<tr> +<td>slist</td> +<td>An slist is like a list but is singly-linked instead of doubly-linked. It can only be iterated in a +forward-direction.</td> +</tr> +<tr> +<td>smart pointer</td> +<td>Smart pointer is a term that identifies a family of utility classes which store pointers and free them when the +class instance goes out of scope. Examples of smart pointers are shared_ptr, linked_ptr, intrusive_ptr, and +scoped_ptr.</td> +</tr> +<tr> +<td>splice</td> +<td>Splicing refers to the moving of a subsequence of one Sequence into another Sequence.</td> +</tr> +<tr> +<td>stack</td> +<td>A stack is a adapter container which implements LIFO (last-in, first, out) access via another container such as a +list or deque.</td> +</tr> +<tr> +<td>STL</td> +<td>Standard Template Library. </td> +</tr> +<tr> +<td>StrictWeakOrdering</td> +<td>A BinaryPredicate that compares two objects, returning true if the first precedes the second. Like Compare but has +additional requirements. Used for sorting routines.<br> +<br> +This predicate must satisfy the standard mathematical definition of a strict weak ordering. A StrictWeakOrdering has to +behave the way that "less than" behaves: if a is less than b then b is not less than a, if a is less than b and b is +less than c then a is less than c, and so on.</td> +</tr> +<tr> +<td>string</td> +<td>See basic_string.</td> +</tr> +<tr> +<td>T</td> +<td>T is the template parameter name used by most containers to identify the contained element type. </td> +</tr> +<tr> +<td>template parameter</td> +<td>A template parameter is the templated type used to define a template function or class. In the declaration +'template <typename T> class vector{ },' T is a template parameter.</td> +</tr> +<tr> +<td>template specialization</td> +<td>A template specialization is a custom version of a template which overrides the default version and provides +alternative functionality, often for the purpose of providing improved or specialized functionality.</td> +</tr> +<tr> +<td>treap</td> +<td>A tree-like structure implemented via a heap. This is an alternative to a binary tree (e.g. red-black tree), +skip-list, and sorted array as a mechanism for a fast-access sorted container.</td> +</tr> +<tr> +<td>type traits</td> +<td>Type traits are properties of types. If you have a templated type T and you want to know if it is a pointer, you +would use the is_pointer type trait. If you want to know if the type is a POD, you would use the is_pod type trait. +Type traits are very useful for allowing the implementation of optimized generic algorithms and for asserting that +types have properties expected by the function or class contract. For example, you can use type_traits to tell if a +type can be copied via memcpy instead of a slower element-by-element copy.</td> +</tr> +<tr> +<td>typename</td> +<td>Typename is a C++ keyword used in templated function implementations which identifies to the compiler that the +following expression is a type and not a value. It is used extensively in EASTL, particularly in the algorithms.</td> +</tr> +<tr> +<td>UnaryOperation</td> +<td>A function which takes one argument and returns a value (which will usually be assigned to second object).</td> +</tr> +<tr> +<td>upper_bound</td> +<td>upper_bound is a version of binary search: it attempts to find the element value in an ordered range [first, last). +Specifically, it returns the last position where value could be inserted without violating the ordering.</td> +</tr> +<tr> +<td>value_type, Value</td> +<td>A value_type is a typedef used by all containers to identify the elements they contain. In most cases value_type is +simply the same thing as the user-supplied T template parameter. The primary exception is the associative containers +whereby value_type is the pair of key_type and mapped_type.</td> +</tr> +<tr> +<td>vector</td> +<td>A vector is a Sequence that supports random access to elements, constant time insertion and removal of elements at +the end, and linear time insertion and removal of elements at the beginning or in the middle. The number of elements in +a vector may vary dynamically; memory management is automatic. Vector is the simplest of the container classes, and in +many cases the most efficient.</td> +</tr> +<tr> +<td>vector_map, vector_multimap, vector_set, vector_multiset</td> +<td>These are containers that implement the functionality of map, multimap, set, and multiset via a vector or deque +instead of a tree. They use less memory and find items faster, but are slower to modify and modification invalidates +iterators.</td> +</tr> +<tr> +<td>weak_ptr</td> +<td>A weak_ptr is an adjunct to shared_ptr which doesn't increment the reference on the contained object but can safely +tell you if the object still exists and access it if so. It has uses in preventing circular references in +shared_ptrs.</td> +</tr> +</tbody> +</table> +<br> + +<hr style="width: 100%; height: 2px;"> +End of document<br> +<br> +<br> +<br> +<br> +<br> +<br> +<br> +<br> +</body> +</html> diff --git a/EASTL/doc/html/EASTL Gotchas.html b/EASTL/doc/html/EASTL Gotchas.html new file mode 100644 index 0000000..daa8f7a --- /dev/null +++ b/EASTL/doc/html/EASTL Gotchas.html @@ -0,0 +1,175 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> + <title>EASTL Gotchas</title> + <meta content="text/html; charset=us-ascii" http-equiv="content-type"> + <meta name="author" content="Paul Pedriana"> + <meta name="description" content="Desciptions of potential pitfalls that exist in EASTL."> + <link type="text/css" rel="stylesheet" href="EASTLDoc.css"> + <style type="text/css"> +<!-- +.style1 {color: #FF0000} +.style2 {color: #009933} +--> + </style> +</head> +<body> +<h1>EASTL Gotchas</h1> +<p> There are some cases where the EASTL design results in "gotchas" or behavior that isn't necessarily what the new user + would expect. These are all situations in which this behavior may be undesirable. One might ask, "Why not change EASTL + to make these gotchas go away?" The answer is that in each case making the gotchas go away would either be impossible + or would compromise the functionality of the library.</p> +<h2>Summary</h2> +<p>The descriptions here are intentionally terse; this is to make them easier to visually scan.</p> +<table style="text-align: left; width: 100%;" border="0" cellpadding="1" cellspacing="1"> +<tbody> +<tr> +<td style="width: 28px;">1</td> +<td><a href="#Gotchas.1">map::operator[] can create elements.</a></td> +</tr> +<tr> +<td style="width: 28px;">2</td> +<td><a href="#Gotchas.2">char* converts to string silently.</a></td> +</tr> +<tr> +<td style="width: 28px;">3</td> +<td><a href="#Gotchas.3">char* is compared by ptr and not by contents.</a></td> +</tr> +<tr> +<td style="width: 28px;">4</td> +<td><a href="#Gotchas.4">Iterators can be invalidated by container mutations.</a></td> +</tr> +<tr> +<td style="width: 28px;">5</td> +<td><a href="#Gotchas.5">Vector resizing may cause ctor/dtor cascades.</a></td> +</tr> +<tr> +<td style="width: 28px;">6</td> +<td><a href="#Gotchas.6">Vector and string insert/push_back/resize can reallocate.</a></td> +</tr> +<tr> +<td style="width: 28px;">7</td> +<td><a href="#Gotchas.7">Deriving from containers may not work.</a></td> +</tr> +<tr> +<td style="width: 28px;">8</td> +<td><a href="#Gotchas.8">set::iterator is const_iterator.</a></td> +</tr> +<tr> +<td style="width: 28px;">9</td> +<td><a href="#Gotchas.9">Inserting elements means copying by value.</a></td> +</tr> +<tr> +<td style="width: 28px;">10</td> +<td><a href="#Gotchas.10">Containers of pointers can leak if you aren't careful.</a></td> +</tr> +<tr> +<td style="width: 28px;">11</td> +<td><a href="#Gotchas.11">Containers of auto_ptrs can crash.</a></td> +</tr> +<tr> +<td style="width: 28px;">12</td> +<td><a href="#Gotchas.12">Remove algorithms don't actually remove elements.</a></td> +</tr> +<tr> +<td style="width: 28px;">13</td> +<td><a href="#Gotchas.13">list::size() is O(n).</a></td> +</tr> +<tr> +<td style="width: 28px;">14</td> +<td><a href="#Gotchas.14">vector and deque::size() may incur integer division.</a></td> +</tr> +<tr> +<td style="width: 28px;">15</td> +<td><a href="#Gotchas.15">Be careful making custom Compare functions.</a></td> +</tr> +<tr> +<td style="width: 28px;">16</td> +<td><a href="#Gotchas.16">Comparisons involving floating point are dangerous.</a></td> +</tr> +<tr> + <td style="width: 28px;">17</td> + <td><a href="#Gotchas.17">Writing beyond string::size and vector::size is dangerous. </a></td> +</tr> +<tr> + <td style="width: 28px;">18</td> + <td><a href="#Gotchas.18">Container operator=() doesn't copy allocators. </a></td> +</tr> +</tbody> +</table> +<h2> Detail</h2> +<p class="faq-question"><a name="Gotchas.1"></a>1 +map::operator[] can create elements.</p> +<p class="faq-answer">By design, map operator[] creates a value for you if it isn't already present. The reason for this is that the alternative behavior would be to throw an exception, and such behavior isn't desirable. The resolution is to simply use the map::find function instead of operator[].</p> +<p class="faq-question"><a name="Gotchas.2"></a>2 +char* converts to string silently.</p> +<p class="faq-answer">The string class has a non-explicit constructor that takes char* as an argument. Thus if you pass char* to a function that takes a string object, a temporary string will be created. In some cases this is undesirable behavior but the user may not notice it right away, as the compiler gives no warnings. The reason that the string constructor from char* is not declared explicit is that doing so would prevent the user from expressions such as: string s = "hello". In this example, no temporary string object is created, but the syntax is not possible if the char* constructor is declared explicit. Thus a decision to make the string char* constructor explicit involves tradeoffs.</p> +<p class="faq-answer">There is an EASTL configuration option called EASTL_STRING_EXPLICIT which makes the string char* ctor explicit and avoids the behaviour described above.</p> +<p class="faq-question"><a name="Gotchas.3"></a>3 +char* is compared by ptr and not by contents.</p> +<p class="faq-answer">If you have a set of strings declared as set<char*>, the find function will compare via the pointer value and not the string contents. The workaround is to make a set of string objects or, better, to supply a custom string comparison function to the set. The workaround is not to declare a global operator< for type char*, as that could cause other systems to break.</p> +<p class="faq-question"><a name="Gotchas.4"></a>4 Iterators can be invalidated by container mutations</p> +<p class="faq-answer">With some containers, modifications of them may invalidate iterators into them. With other containers, modifications of them only an iterator if the modification involves the element that iterator refers to. Containers in the former category include vector, deque, basic_string (string), vector_map, vector_multimap, vector_set, and vector_multiset. Containers in the latter category include list, slist, map, multimap, multiset, all hash containers, and all intrusive containers.</p> +<p class="faq-question"><a name="Gotchas.5"></a>5 Vector resizing may cause ctor/dtor cascades.</p> +<p>If elements are inserted into a vector in middle of the sequence, the elements from the insertion point to the end will be copied upward. This will necessarily cause a series of element constructions and destructions as the elements are copied upward. Similarly, if an element is appended to a vector but the vector capacity is exhausted and needs to be reallocated, the entire vector will undergo a construction and destruction pass as the values are copied to the new storage. This issue exists for deque as well, though to a lesser degree. For vector, the resolution is to reserve enough space in your vector to prevent such reallocation. For deque the resolution is to set its subarray size to enough to prevent such reallocation. Another solution that can often be used is to take advantage of the has_trivial_relocate type trait, which can cause such moves to happen via memcpy instead of via ctor/dtor calls. If your class can be safely memcpy'd, you can use EASTL_DECLARE_TRIVIAL_RELOCATE to tell the compiler it can be memcpy'd. Note that built-in scalars (e.g. int) already are automatically memcpy'd by EASTL.</p> +<p class="faq-question"><a name="Gotchas.6"></a>6 +Vector and string insert/push_back/resize can reallocate.</p> +<p>If you create an empty vector and use push_back to insert 100 elements, the vector will reallocate itself at least three or four times during the operation. This can be an undesirable thing. The best thing to do if possible is to reserve the size you will need up front in the vector constructor or before you add any elements.</p> +<p class="faq-question"><a name="Gotchas.7"></a>7 +Deriving from containers may not work.</p> +<p>EASTL containers are not designed with the guarantee that they can be arbitrarily subclassed. This is by design and is done for performance reasons, as such guarantees would likely involve making containers use virtual functions. However, some types of subclassing can be successful and EASTL does such subclassing internally to its advantage. The primary problem with subclassing results when a parent class function calls a function that the user wants to override. The parent class cannot see the overridden function and silent unpredictable behavior will likely occur. If your derived container acts strictly as a wrapper for the container then you will likely be able to successfully subclass it.</p> +<p class="faq-question"><a name="Gotchas.8"></a>8 +set::iterator is const_iterator.</p> +<p class="faq-answer">The reason this is so is that a set is an ordered container and changing the value referred to by an iterator could make the set be out of order. Thus, set and multiset iterators are always const_iterators. If you need to change the value and are sure the change will not alter the container order, use const_cast or declare mutable member variables for your contained object. This resolution is the one blessed by the C++ standardization committee. This issue is addressed in more detail in the EASTL FAQ.</p> +<p class="faq-question"><a name="Gotchas.9"></a>9 +Inserting elements means copying by value.</p> +<p class="faq-answer">When you insert an element into a (non-intrusive) container, the container makes a copy of the element. There is no provision to take over ownership of an object from the user. The exception to this is of course when you use a container of pointers instead of a container of values. See the entry below regarding containers of pointers. Intrusive containers (e.g. intrusive_list) do in fact take over the user-provided value, and thus provide another advantage over regular containers in addition to avoiding memory allocation.</p> +<p class="faq-question"><a name="Gotchas.10"></a>10 + Containers of pointers can leak if you aren't careful.</p> +<p class="faq-answer">Containers of points don't know or care about the possibility that the pointer may have been allocated and need to be freed. Thus if you erase such elements from a container they are not freed. The resolution is to manually free the pointers when removing them or to instead use a container of smart pointers (shared smart pointers, in particular). This issue is addressed in more detail in the EASTL FAQ and the auto_ptr-related entry below.</p> +<p class="faq-question"><a name="Gotchas.11"></a>11 +Containers of auto_ptrs can crash</p> +<p class="faq-answer">We suggested above that the user can use a container of smart pointers to automatically manage contained pointers. However, you don't want to use auto_ptr, as auto_ptrs cannot be safely assigned to each other; doing so results in a stale pointer and most likely a crash.</p> +<p class="faq-question"><a name="Gotchas.12"></a>12 +Remove algorithms don't actually remove elements.</p> +<p class="faq-answer">Algorithms such as remove, remove_if, remove_heap, and unique do not erase elements from the sequences they work on. Instead, they return an iterator to the new end of the sequence and the user must call erase with that iterator in order to actually remove the elements from the container. This behavior exists because algorithms work on sequences via iterators and don't know how to work with containers. Only the container can know how to best erase its own elements. In each case, the documentation for the algorithm reminds the user of this behavior. Similarly, the copy algorithm copies elements from one sequence to another and doesn't modify the size of the destination sequence. So the destination must hold at least as many items as the source, and if it holds more items, you may want to erase the items at the end after the copy.</p> +<p class="faq-question"><a name="Gotchas.13"></a>13 +list::size() is O(n).</p> +<p class="faq-answer">By this we mean that calling size() on a list will iterate the list and add the size as it goes. Thus, getting the size of a list is not a fast operation, as it requires traversing the list and counting the nodes. We could make list::size() be fast by having a member mSize variable. There are reasons for having such functionality and reasons for not having such functionality. We currently choose to not have a member mSize variable as it would add four bytes to the class, add processing to functions such as insert and erase, and would only serve to improve the size function, but no other function. The alternative argument is that the C++ standard states that std::list should be an O(1) operation (i.e. have a member size variable), most C++ standard library list implementations do so, the size is but an integer which is quick to update, and many users expect to have a fast size function. All of this applies to slist and intrusive_list as well.</p> +<p class="faq-answer">Note that EASTL's config.h file has an option in it to cause list and slist to cache their size with an mSize variable and thus make size() O(1). This option is disabled by default.</p> +<p class="faq-question"> <a name="Gotchas.14"></a>14 + vector and deque::size() may incur integer division.</p> +<p class="faq-answer">Some containers (vector and deque in particular) calculate their size by pointer subtraction. For example, the implementation of vector::size() is 'return mpEnd - mpBegin'. This looks like a harmless subtraction, but if the size of the contained object is not an even power of two then the compiler will likely need to do an integer division to calculate the value of the subtracted pointers. One might suggest that vector use mpBegin and mnSize as member variables instead of mpBegin and mpEnd, but that would incur costs in other vector operations. The suggested workaround is to iterate a vector instead of using a for loop and operator[] and for those cases where you do use a for loop and operator[], get the size once at the beginning of the loop instead of repeatedly during the condition test.</p> +<p class="faq-question"><a name="Gotchas.15"></a>15 + Be careful making custom Compare functions. +</p> +<p class="faq-answer">A Compare function compares two values and returns true if the first is less than the second. This is easy to understand for integers and strings, but harder to get right for more complex structures. Many a time have people decided to come up with a fancy mechanism for comparing values and made mistakes. The FAQ has a couple entries related to this. See http://blogs.msdn.com/oldnewthing/archive/2003/10/23/55408.aspx for a story about how this can go wrong by being overly clever.</p> +<p class="faq-question"> <a name="Gotchas.16"></a>16 + Comparisons involving floating point are dangerous.</p> +<p class="faq-answer">Floating point comparisons between two values that are very nearly equal can result in inconsistent results. Similarly, floating point comparisons between NaN values will always generate inconsistent results, as NaNs by definition always compare as non-equal. You thus need to be careful when using comparison functions that work with floating point values. Conversions to integral values may help the problem, but not necessarily.</p> +<p class="faq-question"><a name="Gotchas.17" id="Gotchas.17"></a>17 Writing beyond string::size and vector::size is dangerous.</p> +<p>A trick that often comes to mind when working with strings is to set the string capacity to some maximum value, strcpy data into it, and then resize the string when done. This can be done with EASTL, but only if you resize the string to the maximum value and not reserve the string to the maximum value. The reason is that when you resize a string from size (n) to size (n + count), the count characters are zeroed and overwrite the characters that you strcpyd. </p> +<p class="faq-answer">The following code is broken: </p> +<p class="code-example">string mDataDir;<br> + <br> + mDataDir.<span class="style1">reserve</span>(kMaxPathLength);<br> + strcpy(&mDataDir[0], "blah/blah/blah");<br> +mDataDir.resize(strlen(&mDataDir[0])); // Overwrites your blah/... with 00000...</p> +<p class="faq-answer">This following code is OK: </p> +<p class="code-example">string mDataDir;<br> + <br> + mDataDir.<span class="style2">resize</span>(kMaxPathLength);<br> + strcpy(&mDataDir[0], "blah/blah/blah");<br> +mDataDir.resize(strlen(&mDataDir[0]));</p> +<p class="faq-question"><a name="Gotchas.18" id="Gotchas.18"></a>18 Container operator=() doesn't copy allocators. +</p> +<p class="faq-answer">EASTL container assignment (e.g. vector::operator=(const vector&)) doesn't copy the allocator. There are good and bad reasons for doing this, but that's how it acts. So you need to beware that you need to assign the allocator separately or make a container subclass which overrides opeator=() and does this. </p> +<br> +<hr style="width: 100%; height: 2px;"> +End of document<br> +<br> +<br> +<br> +<br> +</body> +</html> diff --git a/EASTL/doc/html/EASTL Introduction.html b/EASTL/doc/html/EASTL Introduction.html new file mode 100644 index 0000000..0e9b23c --- /dev/null +++ b/EASTL/doc/html/EASTL Introduction.html @@ -0,0 +1,47 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> + <title>EASTL Introduction</title> + <meta content="text/html; charset=us-ascii" http-equiv="content-type"> + <meta name="author" content="Paul Pedriana"> + <meta name="description" content="Basic introduction to EASTL."> + <link type="text/css" rel="stylesheet" href="EASTLDoc.css"> +</head> +<body> +<h1>EASTL Introduction</h1> +<p>EASTL stands for Electronic Arts Standard Template Library. It is a C++ template library of containers, algorithms, and + iterators useful for runtime and tool development across multiple platforms. It is a fairly extensive and robust + implementation of such a library and has an emphasis on high performance above all other considerations.</p> +<h2>Intended Audience</h2> +<p>This is a short document intended to provide a basic introduction to EASTL for + those new to the concept of EASTL or STL. If you are familiar with the C++ STL + or have worked with other templated container/algorithm libraries, you probably + don't need to read this. If you have no familiarity with C++ templates at all, + then you probably will need more than this document to get you up to speed. In + this case you need to understand that templates, when used properly, are powerful + vehicles for the ease of creation of optimized C++ code. A description of C++ + templates is outside the scope of this documentation, but there is plenty of such + documentation on the Internet. See the <a href="EASTL%20FAQ.html">EASTL FAQ.html</a> + document for links to information related to learning templates and STL.</p> +<h2>EASTL Modules</h2> +<p>EASTL consists primarily of containers, algorithms, and iterators. An example of a container is a linked list, while an + example of an algorithm is a sort function; iterators are the entities of traversal for containers and algorithms. + EASTL containers a fairly large number of containers and algorithms, each of which is a very clean, efficient, and + unit-tested implementation. We can say with some confidence that you are not likely to find better implementations of + these (commercial or otherwise), as these are the result of years of wisdom and diligent work. For a detailed list of + EASTL modules, see <a href="EASTL%20Modules.html">EASTL Modules.html</a>.</p> +<h2>EASTL Suitability</h2> +<p>What uses are EASTL suitable for? Essentially any situation in tools and shipping applications where the functionality + of EASTL is useful. Modern compilers are capable of producing good code with templates and many people are using them + in both current generation and future generation applications on multiple platforms from embedded systems to servers + and mainframes.</p> +<hr style="width: 100%; height: 2px;"> +End of document<br> +<br> +<br> +<br> +<br> +<br> +<br> +</body> +</html> diff --git a/EASTL/doc/html/EASTL Maintenance.html b/EASTL/doc/html/EASTL Maintenance.html new file mode 100644 index 0000000..aaca955 --- /dev/null +++ b/EASTL/doc/html/EASTL Maintenance.html @@ -0,0 +1,292 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> + <title>EASTL Maintenance</title> + <meta content="text/html; charset=us-ascii" http-equiv="content-type"> + <meta name="author" content="Paul Pedriana"> + <meta name="description" content="Information for the EASTL maintainer."> + <link type="text/css" rel="stylesheet" href="EASTLDoc.css"> +</head> +<body> + +<h1>EASTL Maintenance</h1> +<h2><span style="font-style: italic;"><a name="Introduction" id="Introduction"></a></span>Introduction</h2> +<p>The purpose of this document is to provide some necessary background for anybody who might do work on EASTL. Writing + generic templated systems like EASTL can be surprisingly tricky. There are numerous details of the C++ language that + you need to understand which don't usually come into play during the day-to-day C++ coding that many people do. It is + easy to make a change to some function that seems proper and works for your test case but either violates the design + expectations or simply breaks under other circumstances.<br> + <br> + It may be useful to start with an example. Here we provide an implementation of the count algorithm which is seems +simple enough. Except it is wrong and while it will compile in some cases it won't compile in others:</p> +<pre class="code-example">template <class InputIterator, class T> +int count(InputIterator first, InputIterator last, const T& value) +{ + int result = 0; + + for(; first < last; ++first){ + if(*first == value) + ++result; + } + + return result; + } </pre> +<p>The problem is with the comparison 'first < last'. The count algorithm takes an InputIterator and operator< is +not guaranteed to exist for any given InputIterator (and indeed while operator< exists for vector::iterator, it +doesn't exist for list::iterator). The comparison in the above algorithm must instead be implemented as 'first != +last'. If we were working with a RandomAccessIterator then 'first < last' would be valid.</p> +<p>In the following sections we cover various topics of interest regarding the development and maintentance of EASTL. + Unfortunately, this document can't cover every aspect of EASTL maintenance issues, but at least it should give you a +sense of the kinds of issues.</p> + +<h2> <a name="Language_Standard" id="Language_Standard"></a>C++ Language Standard</h2> +<p>First and foremost, you need to be familiar with the C++ standard. In particular, the sections of the standard related + to containers, algorithms, and iterators are of prime significance. We'll talk about some of this in more detail below. + Similarly, a strong understanding of the basic data types is required. What is the difference between ptrdiff_t and +intptr_t; unsigned int and size_t; char and signed char?</p> +<p>In addition to the C++ language standard, you'll want to be familiar with the C++ Defect Report. This is a continuously + updated document which lists flaws in the original C++ language specification and the current thinking as the +resolutions of those flaws. You will notice various references to the Defect Report in EASTL source code.</p> +<p>Additionally, you will want to be familiar with the C++ Technical Report 1 (as of this writing there is only one). This + document is the evolving addendum to the C++ standard based on both the Defect Report and based on desired additions to +the C++ language and standard library.</p> +<p>Additionally, you will probably want to have some familiarity with Boost. It also helps to keep an eye on + comp.std.c++ Usenet discussions. However, watch out for what people say on Usenet. They tend to defend GCC, Unix, std + STL, and C++ to a sometimes unreasonable degree. Many discussions ignore performance implications and +concentrate only on correctness and sometimes academic correctness above usability.</p> +<h2> <a name="Langauge_Use" id="Langauge_Use"></a>Language Use</h2> +<p>Macros are (almost) not allowed in EASTL. A prime directive of EASTL is to be easier to read by users and most of + the time macros are an impedence to this. So we avoid macros at all costs, even if it ends up making our development + and maintenance more difficult. That being said, you will notice that the EASTL config.h file uses macros to control + various options. This is an exception to the rule; when we talk about not using macros, we mean with the EASTL +implementation itself.</p> +<p>EASTL assumes a compliant and intelligent C++ compiler, and thus all language facilities are usable. However, we +nevertheless choose to stay away from some language functionality. The primary language features we avoid are:</p> +<ul> + <li>RTTI (run-time-type-identification) (this is deemed too costly)</li> +<li>Template export (few compilers support this)</li> +<li>Exception specifications (most compilers ignore them)</li> +</ul> +<p>Use of per-platform or per-compiler code should be avoided when possible but where there is a significant advantage to + be gained it can and indeed should be used. An example of this is the GCC __builtin_expect feature, which allows the + user to give the compiler a hint about whether an expression is true or false. This allows for the generation of code +that executes faster due to more intelligent branch prediction.</p> +<h2> <a name="Prime_Directives" id="Prime_Directives"></a>Prime Directives</h2> +<p>The +implementation of EASTL is guided foremost by the following directives which are listed in order of importance.</p> +<ol> +<li>Efficiency (speed and memory usage)</li> +<li>Correctness (doesn't have bugs)</li> +<li>Portability (works on all required platforms with minimal specialized code)</li> +<li>Readability (code is legible and comments are present and useful)</li> +</ol> +<p>Note that unlike commercial STL implementations which must put correctness above all, we put a higher value on + efficiency. As a result, some functionality may have some usage limitation that is not present in other similar systems +but which allows for more efficient operation, especially on the platforms of significance to us.</p> +<p>Portability is significant, but not critical. Yes, EASTL must compile and run on all platforms that we will ship games + for. But we don't take that to mean under all compilers that could be conceivably used for such platforms. For example, + Microsoft VC6 can be used to compile Windows programs, but VC6's C++ support is too weak for EASTL and so you simply +cannot use EASTL under VC6.</p> +<p>Readability is something that EASTL achieves better than many other templated libraries, particularly Microsoft STL and + STLPort. We make every attempt to make EASTL code clean and sensible. Sometimes our need to provide optimizations + (particularly related to type_traits and iterator types) results in less simple code, but efficiency happens to be our +prime directive and so it overrides all other considerations.</p> + +<h2> <a name="Coding_Conventions" id="Coding_Conventions"></a>Coding Conventions</h2> +<p>Here we provide a list of coding conventions to follow when maintaining or adding to EASTL, starting with the three +language use items from above:</p> +<ul> +<li>No RTTI use.</li> +<li>No use of exception specifications (e.g. appending the 'throw' declarator to a function).</li> +<li>No use of exception handling itself except where explicitly required by the implementation (e.g. vector::at).</li> +<li>Exception use needs to savvy to EASTL_EXCEPTIONS_ENABLED.</li> +<li>No use of macros (outside of config.h). Macros make things more difficult for the user.</li> +<li>No use of static or global variables.</li> +<li>No use of global new, delete, malloc, or free. All memory must be user-specifyable via an Allocator parameter +(default-specified or explicitly specified).</li> +<li>Containers use protected member data and functions as opposed to private. This is because doing so allows +subclasses to extend the container without the creation of intermediary functions. Recall from our <a href="#Prime_Directives">prime directives</a> above that performance and simplicity overrule all.</li> +<li>No use of multithreading primitives. </li> +<li>No use of the export keyword.</li> +<li>We don't have a rule about C-style casts vs. C++ static_cast<>, etc. We would always use static_cast except +that debuggers can't evaluate them and so in practice they can get in the way of debugging and tracing. However, if the +cast is one that users don't tend to need to view in a debugger, C++ casts are preferred.</li> +<li>No external library dependencies whatsoever, including standard STL. EASTL is dependent on only EABase and the +C++ compiler. </li> +<li>All code must be const-correct. This isn't just for readability -- compilation can fail unless const-ness is used +correctly everywhere. </li> +<li>Algorithms do not refer to containers; they refer only to iterators.</li> +<li>Algorithms in general do not allocate memory. If such a situation arises, there should be a version of the +algorithm which allows the user to provide the allocator.</li> +<li>No inferior implementations. No facility should be added to EASTL unless it is of professional +quality.</li> +<li>The maintainer should emulate the EASTL style of code layout, regardless of the maintainer's personal preferences. +When in Rome, do as the Romans do. EASTL uses 4 spaces for indents, which is how the large majority of code within EA +is written.</li> +<li>No major changes should be done without consulting a peer group.</li> +</ul> + +<h2><a name="Compiler_Issues" id="Compiler_Issues"></a>Compiler Issues</h2> +<p>Historically, templates are the feature of C++ that has given C++ compilers the most fits. We are still working with + compilers that don't completely and properly support templates. Luckily, most compilers are now good enough to handle +what EASTL requires. Nevertheless, there are precautions we must take.</p> +<p>It turns out that the biggest problem in writing portable EASTL code is that VC++ allows you to make illegal statements + which are not allowed by other compilers. For example, VC++ will allow you to neglect using the typename keyword in +template references, whereas GCC (especially 3.4+) requires it.</p> +<p>In order to feel comfortable that your EASTL code is C++ correct and is portable, you must do at least these two +things:</p> +<ul> +<li>Test under at least VS2005, GCC 3.4+, GCC 4.4+, EDG, and clang. </li> +<li>Test all functions that you write, as compilers will often skip the compilation of a template function if it isn't +used.</li> +</ul> +<p>The two biggest issues to watch out for are 'typename' and a concept called "dependent names". In both cases VC++ will + accept non-conforming syntax whereas most other compilers will not. Whenever you reference a templated type (and not a templated + value) in a template, you need to prefix it by 'typename'. Whenever your class function refers to a base class member (data or + function), you need to refer to it by "this->", "base_type::", or by placing a "using" statement in your class to +declare that you will be referencing the given base class member.</p> + +<h2> <a name="Iterator_Issues" id="Iterator_Issues"></a>Iterator Issues</h2> +<p>The most important thing to understand about iterators is the concept of iterator types and their designated + properties. In particular, we need to understand the difference between InputIterator, ForwardIterator, + BidirectionalIterator, RandomAccessIterator, and OutputIterator. These differences dictate both how we implement our + algorithms and how we implement our optimizations. Please read the C++ standard for a reasonably well-implemented + description of these iterator types.</p> +<p>Here's an example from EASTL/algorithm.h which demonstrates how we use iterator types to optimize the reverse algorithm +based on the kind of iterator passed to it:</p> +<pre class="code-example">template <class BidirectionalIterator> +inline void reverse_impl(BidirectionalIterator first, BidirectionalIterator last, bidirectional_iterator_tag)<br>{ + for(; (first != last) && (first != --last); ++first) <span class="code-example-comment">// We are not allowed to use operator <, <=, >, >= with</span> + iter_swap(first, last); <span class="code-example-comment">// a generic (bidirectional or otherwise) iterator.</span> +}<br> + +template <typename RandomAccessIterator> +inline void reverse_impl(RandomAccessIterator first, RandomAccessIterator last, random_access_iterator_tag) +{ + for(; first < --last; ++first) <span class="code-example-comment">// With a random access iterator, we can use operator < to more efficiently implement</span> + iter_swap(first, last); <span class="code-example-comment">// this algorithm. A generic iterator doesn't necessarily have an operator < defined.</span> +}<br><br> +template <class BidirectionalIterator> +inline void reverse(BidirectionalIterator first, BidirectionalIterator last) +{ + typedef typename iterator_traits<BidirectionalIterator>::iterator_category IC; + reverse_impl(first, last, IC()); +}</pre> + +<h2> <a name="Exception_Handling" id="Exception_Handling"></a>Exception Handling</h2> +<p>You will notice that EASTL uses try/catch in some places (particularly in containers) and uses + the EASTL_EXCEPTIONS_ENABLED define. For starters, any EASTL code that uses try/catch should always be wrapped + within #if EASTL_EXCEPTIONS_ENABLED (note: #if, not #ifdef).</p> +<p>This is simple enough, but what you may be wondering is how it is that EASTL decides to use try/catch for some sections + of code and not for others. EASTL follows the C++ standard library conventions with respect to exception handling, and + you will see similar exception handling in standard STL. The code that you need to wrap in try/catch is code that can + throw a C++ exception (not to be confused with CPU exception) and needs to have something unwound (or fixed) as a + result. The important thing is that the container be in a valid state after encountering such exceptions. In general +the kinds of things that require such try/catch are:</p> +<ul> +<li>Memory allocation failures (which throw exceptions)</li> +<li>Constructor exceptions</li> +</ul> +<p>Take a look at the cases in EASTL where try/catch is used and see what it is doing.</p> +<h2> <a name="Type_Traits" id="Type_Traits"></a>Type Traits </h2> +<p>EASTL provides a facility called type_traits which is very similar to the type_traits being proposed by the C++ TR1 + (see above). type_traits are useful because they tell you about properties of types at compile time. This allows you to + do things such as assert that a data type is scalar or that a data type is const. The way we put them to use in EASTL + is to take advantage of them to implement different pathways for functions based on types. For example, we can copy a + contiguous array of scalars much faster via memcpy than we can via a for loop, though we could not safely employ the + for loop for a non-trivial C++ class.</p> +<p>As mentioned in the GeneralOptimizations section below, EASTL should take advantage of type_traits information to the +extent possible to achive maximum effiiciency.</p> +<h2> <a name="General_Optimizations" id="General_Optimizations"></a>General +Optimizations</h2> +<p>One of the primary goals of EASTL is to achieve the highest possible efficiency. In cases where EASTL functionality + overlaps standard C++ STL functionality, standard STL implementations provided by compiler vendors are a benchmark upon + which EASTL strives to beat. Indeed EASTL is more efficient than all other current STL implementations (with some + exception in the case of some Metrowerks STL facilities). Here we list some of the things to look for when considering + optimization of EASTL code These items can be considered general optimization suggestions for any code, but this +particular list applies to EASTL:</p> +<ul> +<li>Take advantage of type_traits to the extent possible (e.g. to use memcpy to move data instead of a for loop when +possible).</li> +<li>Take advantage of iterator types to the extent possible.</li> +<li>Take advantage of the compiler's expectation that if statements are expected to evaluate as true and for loop +conditions are expected to evaluate as false.</li> +<li>Make inline-friendly code. This often means avoiding temporaries to the extent possible.</li> +<li>Minimize branching (i.e. minimize 'if' statements). Where branching is used, make it so that 'if' statements +execute as true.</li> +<li>Use EASTL_LIKELY/EASTL_UNLIKELY to give branch hints to the compiler when you are confident it will be +beneficial.</li> +<li>Use restricted pointers (EABase's EA_RESTRICT or various compiler-specific versions of __restrict).</li> +<li>Compare unsigned values to < max instead of comparing signed values to >= 0 && < max.</li> +<li>Employ power of 2 integer math instead of math with any kind of integer.</li> +<li>Use template specialization where possible to implement improved functionality.</li> +<li>Avoid function calls when the call does something trivial. This improves debug build speed (which matters) and +sometimes release build speed as well, though sometimes makes the code intent less clear. A comment next to the code +saying what call it is replacing makes the intent clear without sacrificing performance.</li> +</ul> +<h2><a name="Unit_Tests" id="Unit_Tests"></a>Unit Tests</h2> +<p>Writing robust templated containers and algorithms is difficult or impossible without a heavy unit test suite in place. + EASTL has a pretty extensive set of unit tests for all containers and algorithms. While the successful automated unit + testing of shipping application programs may be a difficult thing to pull off, unit testing of libraries such as this + is of huge importance and cannot be understated. </p> +<ul> +<li>When making a new unit test, start by copying one of the existing unit tests and follow its conventions.</li> +<li>Test containers of both scalars and classes.</li> +<li>Test algorithms on both container iterators (e.g. vector.begin()) and pointer iterators (e.g. int*).</li> +<li>Make sure that algorithm or container member functions which take iterators work with the type of iterator they +claim to (InputIterator, ForwardIterator, BidirectionalIterator, RandomAccessIterator). </li> +<li>Test for const-correctness. If a user is allowed to modify something that is supposed to be const, silent errors +can go undetected.</li> +<li>Make sure that unit tests cover all functions and all pathways of the tested code. This means that in writing the +unit test you need to look at the source code to understand all the pathways.</li> +<li>Consider using a random number generator (one is provided in the test library) to do 'monkey' testing whereby +unexpected input is given to a module being tested. When doing so, make sure you seed the generator in a way that +problems can be reproduced.</li> +<li>While we avoid macros in EASTL user code, macros to assist in unit tests aren't considered a problem. However, +consider that a number of macros could be replaced by templated functions and thus be easier to work with.</li> +<li>Unit tests don't need to be efficient; feel free to take up all the CPU power and time you need to test a module +sufficiently.</li> +<li>EASTL containers are not thread-safe, by design. Thus there is no need to do multithreading tests as long as you +stay away from the usage of static and global variables.</li> +<li>Unit tests must succeed with no memory leaks and of course no memory corruption. The heap system should be +configured to test for this, and heap validation functions are available to the unit tests while in the middle of +runs.</li> +</ul> + +<h2><a name="Things_to_Keep_in_Mind" id="Things_to_Keep_in_Mind"></a>Things to Keep in Mind</h2> +<ul> +<li>When referring to EASTL functions and types from EASTL code, make sure to preface the type with the EASTL +namespace. If you don't do this you can get collisions due to the compiler not knowing if it should use the EASTL +namespace or the namespace of the templated type for the function or type.</li> +<li>Newly constructed empty containers do no memory allocation. Some STL and other container libraries allocate an +initial node from the class memory allocator. EASTL containers by design never do this. If a container needs an +initial node, that node should be made part of the container itself or be a static empty node object.</li> +<li>Empty containers (new or otherwise) contain no constructed objects, including those that might be in an 'end' node. +Similarly, no user object (e.g. of type T) should be constructed unless required by the design and unless documented in +the cotainer/algorithm contract. </li> +<li>When creating a new container class, it's best to copy from an existing similar class to the extent possible. This +helps keep the library consistent and resolves subtle problems that can happen in the construction of containers.</li> +<li>Be very careful about tweaking the code. It's easy to think (for example) that a > could be switch to a >= +where instead it is a big deal. Just about every line of code in EASTL has been thought through and has a purpose. Unit +tests may or may not currently test every bit of EASTL, so you can't necessarily rely on them to give you 100% +confidence in changes. If you are not sure about something, contact the original author and he will tell you for +sure.</li> +<li>Algorithm templates always work with iterators and not containers. A given container may of course implement an +optimized form or an algorithm itself.</li> +<li>Make sure everything is heavily unit tested. If somebody finds a bug, fix the bug and make a unit test to make sure +the bug doesn't happen again.</li> +<li>It's easy to get iterator categories confused or forgotten while implementing algorithms and containers.</li> +<li>Watch out for the strictness of GCC 3.4+. There is a bit of syntax — especially related to templates — that other +compilers accept but GCC 3.4+ will not.</li> +<li>Don't forget to update the config.h EASTL_VERSION define before publishing.</li> +<li>The vector and string classes define iterator to be T*. We want to always leave this so — at least in release +builds — as this gives some algorithms an advantage that optimizers cannot get around.</li> +</ul> +<hr style="width: 100%; height: 2px;"> +<br> +<br> +<br> +<br> +<br> +</body> +</html> diff --git a/EASTL/doc/html/EASTL Modules.html b/EASTL/doc/html/EASTL Modules.html new file mode 100644 index 0000000..620937e --- /dev/null +++ b/EASTL/doc/html/EASTL Modules.html @@ -0,0 +1,666 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> + <title>EASTL Modules</title> + <meta content="text/html; charset=us-ascii" http-equiv="content-type"> + <meta name="author" content="Paul Pedriana"> + <meta name="description" content="Lists the top-level modules present in EASTL."> + <link type="text/css" rel="stylesheet" href="EASTLDoc.css"> + <style type="text/css"> +<!-- +.style1 {font-size: 10pt} +--> + </style> +</head> +<body> +<h1><font size="+3">EASTL Modules</font></h1> +<h2> Introduction</h2> +<p>We provide here a list of all top-level modules present or planned for future presence in EASTL. In some cases (e.g. + algorithm), the module consists of many smaller submodules which are not described in detail here. In those cases you + should consult the source code for those modules or consult the detailed documentation for those modules. This document +is a high level overview and not a detailed document.</p> +<h2>Module List</h2> +<table style="text-align: left; width: 100%;" border="1" cellpadding="2" cellspacing="2"> +<tbody> +<tr> +<td style="font-weight: bold;"> Module</td> +<td style="font-weight: bold;">Description</td> +</tr> +<tr> +<td>config</td> +<td>Configuration header. Allows for changing some compile-time options.</td> +</tr> +<tr> +<td>slist<br> +fixed_slist</td> +<td>Singly-linked list.<br> +fixed_slist is a version which is implemented via a fixed block of contiguous memory.</td> +</tr> +<tr> +<td>list<br> +fixed_list</td> +<td>Doubly-linked list.</td> +</tr> +<tr> +<td>intrusive_list<br> +intrusive_slist</td> +<td>List whereby the contained item provides the node implementation.</td> +</tr> +<tr> +<td>array</td> +<td>Wrapper for a C-style array which extends it to act like an STL container.</td> +</tr> +<tr> +<td>vector<br> +fixed_vector</td> +<td>Resizable array container.</td> +</tr> +<tr> +<td>vector_set<br> +vector_multiset<br></td> +<td>Set implemented via a vector instead of a tree. Speed and memory use is improved but resizing is slower.</td> +</tr> +<tr> +<td>vector_map<br> +vector_multimap<br></td> +<td>Map implemented via a vector instead of a tree. Speed and memory use is improved but resizing is slower.</td> +</tr> +<tr> +<td style="vertical-align: top;">deque<br></td> +<td style="vertical-align: top;">Double-ended queue, but also with random access. Acts like a vector but insertions and +removals are efficient.<br></td> +</tr> +<tr> +<td>bit_vector</td> +<td>Implements a vector of bool, but the actual storage is done with one bit per bool. Not the same thing as a +bitset.</td> +</tr> +<tr> +<td>bitset</td> +<td>Implements an efficient arbitrarily-sized bitfield. Note that this is not strictly the same thing as a vector of +bool (bit_vector), as it is optimized to act like an arbitrary set of flags and not to be a generic container which can +be iterated, inserted, removed, etc.</td> +</tr> +<tr> +<td>set<br> +multiset<br> +fixed_set<br> +fixed_multiset<br></td> +<td>A set is a sorted unique collection, multiset is sorted but non-unique collection.</td> +</tr> +<tr> +<td>map<br> +multimap<br> +fixed_map<br> +fixed_multimap</td> +<td>A map is a sorted associative collection implemented via a tree. It is also known as dictionary.</td> +</tr> +<tr> +<td>hash_map<br> +hash_multimap<br> +fixed_hash_map<br> +fixed_hash_multimap</td> +<td>Map implemented via a hash table.</td> +</tr> +<tr> +<td>intrusive_hash_map<br> +intrusive_hash_multimap<br> +intrusive_hash_set<br> +intrusive_hash_multiset</td> +<td>hash_map whereby the contained item provides the node implementation, much like intrusive_list.</td> +</tr> +<tr> +<td>hash_set<br> +hash_multiset<br> +fixed_hash_set<br> +fixed_hash_map<br></td> +<td>Set implemented via a hash table.</td> +</tr> +<tr> +<td>basic_string<br> +fixed_string<br> +fixed_substring</td> +<td>basic_string is a character string/array.<br> +fixed_substring is a string which is a reference to a range within another string or character array.<br> +cow_string is a string which implements copy-on-write.</td> +</tr> +<tr> +<td>algorithm</td> +<td>min/max, find, binary_search, random_shuffle, reverse, etc. </td> +</tr> +<tr> +<td style="vertical-align: top;">sort<br></td> +<td style="vertical-align: top;">Sorting functionality, including functionality not in STL. quick_sort, heap_sort, +merge_sort, shell_sort, insertion_sort, etc.<br></td> +</tr> +<tr> +<td>numeric</td> +<td>Numeric algorithms: accumulate, inner_product, partial_sum, adjacent_difference, etc.</td> +</tr> +<tr> +<td style="vertical-align: top;">heap<br></td> +<td style="vertical-align: top;">Heap structure functionality: make_heap, push_heap, pop_heap, sort_heap, is_heap, +remove_heap, etc.<br></td> +</tr> +<tr> +<td style="vertical-align: top;">stack<br></td> +<td style="vertical-align: top;">Adapts any container into a stack.<br></td> +</tr> +<tr> +<td style="vertical-align: top;">queue<br></td> +<td style="vertical-align: top;">Adapts any container into a queue.<br></td> +</tr> +<tr> +<td style="vertical-align: top;">priority_queue<br></td> +<td style="vertical-align: top;">Implements a conventional priority queue via a heap structure.<br></td> +</tr> +<tr> +<td>type_traits</td> +<td>Type information, useful for writing optimized and robust code. Also used for implementing optimized containers and +algorithms.</td> +</tr> +<tr> +<td style="vertical-align: top;">utility<br></td> +<td style="vertical-align: top;">pair, make_pair, rel_ops, etc.<br></td> +</tr> +<tr> +<td style="vertical-align: top;">functional<br></td> +<td style="vertical-align: top;">Function objects.<br></td> +</tr> +<tr> +<td style="vertical-align: top;">iterator<br></td> +<td style="vertical-align: top;">Iteration for containers and algorithms.<br></td> +</tr> +<tr> +<td>smart_ptr</td> +<td>Smart pointers: shared_ptr, shared_array, weak_ptr, scoped_ptr, scoped_array, linked_ptr, linked_array, +intrusive_ptr.</td> +</tr> +</tbody> +</table> +<p> </p> +<h2>Module Behaviour</h2> +<p>The overhead sizes listed here refer to an optimized release build; debug builds may add some additional overhead. Some + of the overhead sizes may be off by a little bit (usually at most 4 bytes). This is because the values reported here + are those that refer to when EASTL's container optimizations have been complete. These optimizations may not have been + completed as you are reading this.</p> +<table style="width: 100%;" border="1" cellpadding="1" cellspacing="1"> +<tbody> +<tr> +<td style="width: 15%; vertical-align: top; height: 13px; font-weight: bold;"> +<p>Container</p> +</td> +<td style="font-weight: bold; text-align: center;" height="13" valign="top" width="10%"> +<p>Stores</p> +</td> +<td style="font-weight: bold; text-align: center;">Container Overhead (32 bit)</td> +<td style="font-weight: bold; text-align: center;">Container Overhead (64 bit)</td> +<td style="font-weight: bold; text-align: center;" height="13" valign="top" width="10%"> +<p>Node Overhead (32 bit)</p> +</td> +<td style="font-weight: bold; text-align: center;">Node Overhead (64 bit)</td> +<td style="font-weight: bold; text-align: center;" height="13" valign="top" width="9%"> +<p>Iterator category</p> +</td> +<td style="text-align: center; font-weight: bold;">size() efficiency</td> +<td style="text-align: center; font-weight: bold;">operator[] efficiency</td> +<td style="font-weight: bold; text-align: center;" height="13" valign="top" width="16%"> +<p>Insert efficiency</p> +</td> +<td style="font-weight: bold; text-align: center;" height="13" valign="top" width="16%"> +<p>Erase via Iterator efficiency</p> +</td> +<td style="font-weight: bold; text-align: center;" height="13" valign="top" width="7%"> +<p>Find efficiency</p> +</td> +<td style="font-weight: bold; text-align: center;" height="13" valign="top" width="10%"> +<p>Sort efficiency</p> +</td> +</tr> +<tr> +<td>slist</td> +<td style="text-align: center;">T</td> +<td style="text-align: center;">8</td> +<td style="text-align: center;">16</td> +<td style="text-align: center;">4</td> +<td style="text-align: center;">8</td> +<td style="text-align: center;">f</td> +<td style="text-align: center;">n</td> +<td style="text-align: center;">-</td> +<td style="text-align: center;">1</td> +<td style="text-align: center;">1</td> +<td style="text-align: center;">n</td> +<td style="text-align: center;">n+</td> +</tr> +<tr> +<td height="13" valign="top" width="15%"> +<p>list</p> +</td> +<td style="text-align: center;" height="13" valign="top" width="10%"> +<p>T</p> +</td> +<td style="text-align: center;">12</td> +<td style="text-align: center;">24</td> +<td style="text-align: center;" height="13" valign="top" width="10%"> +<p>8</p> +</td> +<td style="text-align: center;">16</td> +<td style="text-align: center;" height="13" valign="top" width="9%"> +<p>b</p> +</td> +<td style="text-align: center;">n</td> +<td style="text-align: center;">-</td> +<td style="text-align: center;" height="13" valign="top" width="16%"> +<p>1</p> +</td> +<td style="text-align: center;" height="13" valign="top" width="16%"> +<p>1</p> +</td> +<td style="text-align: center;" height="13" valign="top" width="7%"> +<p>n</p> +</td> +<td style="text-align: center;" height="13" valign="top" width="10%"> +<p>n log(n)</p> +</td> +</tr> +<tr> +<td>intrusive_slist</td> +<td style="text-align: center;">T</td> +<td style="text-align: center;">4</td> +<td style="text-align: center;">8</td> +<td style="text-align: center;">4</td> +<td style="text-align: center;">8</td> +<td style="text-align: center;">f</td> +<td style="text-align: center;">n</td> +<td style="text-align: center;">-</td> +<td style="text-align: center;">1</td> +<td style="text-align: center;">1</td> +<td style="text-align: center;">n</td> +<td style="text-align: center;">n+</td> +</tr> +<tr> +<td>intrusive_list</td> +<td style="text-align: center;">T</td> +<td style="text-align: center;">8</td> +<td style="text-align: center;">16</td> +<td style="text-align: center;">8</td> +<td style="text-align: center;">16</td> +<td style="text-align: center;">b</td> +<td style="text-align: center;">n</td> +<td style="text-align: center;">-</td> +<td style="text-align: center;">1</td> +<td style="text-align: center;">1</td> +<td style="text-align: center;">n</td> +<td style="text-align: center;">n log(n)</td> +</tr> +<tr> +<td>array</td> +<td style="text-align: center;">T</td> +<td style="text-align: center;">0</td> +<td style="text-align: center;">0</td> +<td style="text-align: center;">0</td> +<td style="text-align: center;">0</td> +<td style="text-align: center;">r</td> +<td style="text-align: center;">1</td> +<td style="text-align: center;">1</td> +<td style="text-align: center;">-</td> +<td style="text-align: center;">-</td> +<td style="text-align: center;">n</td> +<td style="text-align: center;">n log(n)</td> +</tr> +<tr> +<td>vector</td> +<td style="text-align: center;">T</td> +<td style="text-align: center;">16</td> +<td style="text-align: center;">32</td> +<td style="text-align: center;">0</td> +<td style="text-align: center;">0</td> +<td style="text-align: center;">r</td> +<td style="text-align: center;">1</td> +<td style="text-align: center;">1</td> +<td style="text-align: center;">1 at end, else n</td> +<td style="text-align: center;">1 at end, else n</td> +<td style="text-align: center;">n</td> +<td style="text-align: center;">n log(n)</td> +</tr> +<tr> +<td>vector_set</td> +<td style="text-align: center;">T</td> +<td style="text-align: center;">16</td> +<td style="text-align: center;">32</td> +<td style="text-align: center;">0</td> +<td style="text-align: center;">0</td> +<td style="text-align: center;">r</td> +<td style="text-align: center;">1</td> +<td style="text-align: center;">1</td> +<td style="text-align: center;">1 at end, else n</td> +<td style="text-align: center;">1 at end, else n</td> +<td style="text-align: center;">log(n)</td> +<td style="text-align: center;">1</td> +</tr> +<tr> +<td>vector_multiset</td> +<td style="text-align: center;">T</td> +<td style="text-align: center;">16</td> +<td style="text-align: center;">32</td> +<td style="text-align: center;">0</td> +<td style="text-align: center;">0</td> +<td style="text-align: center;">r</td> +<td style="text-align: center;">1</td> +<td style="text-align: center;">1</td> +<td style="text-align: center;">1 at end, else n</td> +<td style="text-align: center;">1 at end, else n</td> +<td style="text-align: center;">log(n)</td> +<td style="text-align: center;">1</td> +</tr> +<tr> +<td>vector_map</td> +<td style="text-align: center;">Key, T</td> +<td style="text-align: center;">16</td> +<td style="text-align: center;">32</td> +<td style="text-align: center;">0</td> +<td style="text-align: center;">0</td> +<td style="text-align: center;">r</td> +<td style="text-align: center;">1</td> +<td style="text-align: center;">1</td> +<td style="text-align: center;">1 at end, else n</td> +<td style="text-align: center;">1 at end, else n</td> +<td style="text-align: center;">log(n)</td> +<td style="text-align: center;">1</td> +</tr> +<tr> +<td>vector_multimap</td> +<td style="text-align: center;">Key, T</td> +<td style="text-align: center;">16</td> +<td style="text-align: center;">32</td> +<td style="text-align: center;">0</td> +<td style="text-align: center;">0</td> +<td style="text-align: center;">r</td> +<td style="text-align: center;">1</td> +<td style="text-align: center;">1</td> +<td style="text-align: center;">1 at end, else n</td> +<td style="text-align: center;">1 at end, else n</td> +<td style="text-align: center;">log(n)</td> +<td style="text-align: center;">1</td> +</tr> +<tr> +<td>deque</td> +<td style="text-align: center;">T</td> +<td style="text-align: center;">44</td> +<td style="text-align: center;">84</td> +<td style="text-align: center;">0</td> +<td style="text-align: center;">0</td> +<td style="text-align: center;">r</td> +<td style="text-align: center;">1</td> +<td style="text-align: center;">1</td> +<td style="text-align: center;">1 at begin or end,<br> +else n / 2</td> +<td style="text-align: center;">1 at begin or end,<br> +else n / 2</td> +<td style="text-align: center;">n</td> +<td style="text-align: center;">n log(n)</td> +</tr> +<tr> +<td>bit_vector</td> +<td style="text-align: center;">bool</td> +<td style="text-align: center;">8</td> +<td style="text-align: center;">16</td> +<td style="text-align: center;">0</td> +<td style="text-align: center;">0</td> +<td style="text-align: center;">r</td> +<td style="text-align: center;">1</td> +<td style="text-align: center;">1</td> +<td style="text-align: center;">1 at end, else n</td> +<td style="text-align: center;">1 at end, else n</td> +<td style="text-align: center;">n</td> +<td style="text-align: center;">n log(n)</td> +</tr> +<tr> +<td>string (all types)</td> +<td style="text-align: center;">T</td> +<td style="text-align: center;">16</td> +<td style="text-align: center;">32</td> +<td style="text-align: center;">0</td> +<td style="text-align: center;">0</td> +<td style="text-align: center;">r</td> +<td style="text-align: center;">1</td> +<td style="text-align: center;">1</td> +<td style="text-align: center;">1 at end, else n</td> +<td style="text-align: center;">1 at end, else n</td> +<td style="text-align: center;">n</td> +<td style="text-align: center;">n log(n)</td> +</tr> +<tr> +<td>set</td> +<td style="text-align: center;">T</td> +<td style="text-align: center;">24</td> +<td style="text-align: center;">44</td> +<td style="text-align: center;">16</td> +<td style="text-align: center;">28</td> +<td style="text-align: center;">b</td> +<td style="text-align: center;">1</td> +<td style="text-align: center;">-</td> +<td style="text-align: center;">log(n)</td> +<td style="text-align: center;">log(n)</td> +<td style="text-align: center;">log(n)</td> +<td style="text-align: center;">1</td> +</tr> +<tr> +<td>multiset</td> +<td style="text-align: center;">T</td> +<td style="text-align: center;">24</td> +<td style="text-align: center;">44</td> +<td style="text-align: center;">16</td> +<td style="text-align: center;">28</td> +<td style="text-align: center;">b</td> +<td style="text-align: center;">1</td> +<td style="text-align: center;">-</td> +<td style="text-align: center;">log(n)</td> +<td style="text-align: center;">log(n)</td> +<td style="text-align: center;">log(n)</td> +<td style="text-align: center;">1</td> +</tr> +<tr> +<td>map</td> +<td style="text-align: center;">Key, T</td> +<td style="text-align: center;">24</td> +<td style="text-align: center;">44</td> +<td style="text-align: center;">16</td> +<td style="text-align: center;">28</td> +<td style="text-align: center;">b</td> +<td style="text-align: center;">1</td> +<td style="text-align: center;">log(n)</td> +<td style="text-align: center;">log(n)</td> +<td style="text-align: center;">log(n)</td> +<td style="text-align: center;">log(n)</td> +<td style="text-align: center;">1</td> +</tr> +<tr> +<td>multimap</td> +<td style="text-align: center;">Key, T</td> +<td style="text-align: center;">24</td> +<td style="text-align: center;">44</td> +<td style="text-align: center;">16</td> +<td style="text-align: center;">28</td> +<td style="text-align: center;">b</td> +<td style="text-align: center;">1</td> +<td style="text-align: center;">-</td> +<td style="text-align: center;">log(n)</td> +<td style="text-align: center;">log(n)</td> +<td style="text-align: center;">log(n)</td> +<td style="text-align: center;">1</td> +</tr> +<tr> +<td>hash_set</td> +<td style="text-align: center;">T</td> +<td style="text-align: center;">16</td> +<td style="text-align: center;">20</td> +<td style="text-align: center;">4</td> +<td style="text-align: center;">8</td> +<td style="text-align: center;">b</td> +<td style="text-align: center;">1</td> +<td style="text-align: center;">-</td> +<td style="text-align: center;">1</td> +<td style="text-align: center;">1</td> +<td style="text-align: center;">1</td> +<td style="text-align: center;">-</td> +</tr> +<tr> +<td>hash_multiset</td> +<td style="text-align: center;">T</td> +<td style="text-align: center;">16</td> +<td style="text-align: center;">20</td> +<td style="text-align: center;">4</td> +<td style="text-align: center;">8</td> +<td style="text-align: center;">b</td> +<td style="text-align: center;">1</td> +<td style="text-align: center;">-</td> +<td style="text-align: center;">1<br></td> +<td style="text-align: center;">1</td> +<td style="text-align: center;">1</td> +<td style="text-align: center;">-</td> +</tr> +<tr> +<td>hash_map</td> +<td style="text-align: center;">Key, T</td> +<td style="text-align: center;">16</td> +<td style="text-align: center;">20</td> +<td style="text-align: center;">4</td> +<td style="text-align: center;">8</td> +<td style="text-align: center;">b</td> +<td style="text-align: center;">1</td> +<td style="text-align: center;">-</td> +<td style="text-align: center;">1</td> +<td style="text-align: center;">1</td> +<td style="text-align: center;">1</td> +<td style="text-align: center;">-</td> +</tr> +<tr> +<td>hash_multimap</td> +<td style="text-align: center;">Key, T</td> +<td style="text-align: center;">16</td> +<td style="text-align: center;">20</td> +<td style="text-align: center;">4</td> +<td style="text-align: center;">8</td> +<td style="text-align: center;">b</td> +<td style="text-align: center;">1</td> +<td style="text-align: center;">-</td> +<td style="text-align: center;">1</td> +<td style="text-align: center;">1</td> +<td style="text-align: center;">1</td> +<td style="text-align: center;">-</td> +</tr> +<tr> +<td>intrusive_hash_set</td> +<td style="text-align: center;">T</td> +<td style="text-align: center;">16</td> +<td style="text-align: center;">20</td> +<td style="text-align: center;">4</td> +<td style="text-align: center;">8</td> +<td style="text-align: center;">b</td> +<td style="text-align: center;">1</td> +<td style="text-align: center;">-</td> +<td style="text-align: center;">1</td> +<td style="text-align: center;">1</td> +<td style="text-align: center;">1</td> +<td style="text-align: center;">-</td> +</tr> +<tr> +<td>intrusive_hash_multiset</td> +<td style="text-align: center;">T</td> +<td style="text-align: center;">16</td> +<td style="text-align: center;">20</td> +<td style="text-align: center;">4</td> +<td style="text-align: center;">8</td> +<td style="text-align: center;">b</td> +<td style="text-align: center;">1</td> +<td style="text-align: center;">-</td> +<td style="text-align: center;">1</td> +<td style="text-align: center;">1</td> +<td style="text-align: center;">1</td> +<td style="text-align: center;">-</td> +</tr> +<tr> +<td>intrusive_hash_map</td> +<td style="text-align: center;">T <small>(Key == T)</small></td> +<td style="text-align: center;">16</td> +<td style="text-align: center;">20</td> +<td style="text-align: center;">4</td> +<td style="text-align: center;">8</td> +<td style="text-align: center;">b</td> +<td style="text-align: center;">1</td> +<td style="text-align: center;">-</td> +<td style="text-align: center;">1</td> +<td style="text-align: center;">1</td> +<td style="text-align: center;">1</td> +<td style="text-align: center;">-</td> +</tr> +<tr> +<td>intrusive_hash_multimap</td> +<td style="text-align: center;">T <small>(Key == T) </small></td> +<td style="text-align: center;">16</td> +<td style="text-align: center;">20</td> +<td style="text-align: center;">4</td> +<td style="text-align: center;">8</td> +<td style="text-align: center;">b</td> +<td style="text-align: center;">1</td> +<td style="text-align: center;">-</td> +<td style="text-align: center;">1</td> +<td style="text-align: center;">1</td> +<td style="text-align: center;">1</td> +<td style="text-align: center;">-</td> +</tr> +</tbody> +</table> +<ul> +<li>- means that the operation does not exist.</li> +<li>1 means amortized constant time. Also known as O(1)</li> +<li>n means time proportional to the container size. Also known as O(n)</li> +<li>log(n) means time proportional to the natural logarithm of the container size. Also known as O(log(n))</li> +<li>n log(n) means time proportional to log(n) times the size of the container. Also known as O(n log(n))</li> +<li>n+ means that the time is at least n, and possibly higher.</li> +<li>Iterator meanings are: f = forward iterator; b = bidirectional iterator, r = random iterator.</li> +<li>Overhead indicates approximate per-element overhead memory required in bytes. Overhead doesn't include possible +additional overhead that may be imposed by the memory heap used to allocate nodes. General heaps tend to have between 4 +and 16 bytes of overhead per allocation, depending on the heap.</li> +<li>Some overhead values are dependent on the structure alignment characteristics in effect. The values reported here +are those that would be in effect for a system that requires pointers to be aligned on boundaries of their size and +allocations with a minimum of 4 bytes (thus one byte values get rounded up to 4).</li> +<li>Some overhead values are dependent on the size_type used by containers. size_type defaults to size_t, but it is possible to force it to be 4 bytes for 64 bit machines by defining EASTL_SIZE_T_32BIT.</li> +<li>Inserting at the end of a vector may cause the vector to be resized; resizing a vector is O(n). However, the +amortized time complexity for vector insertions at the end is constant.</li> +<li>Sort assumes the usage of the best possible sort for a large container of random data. Some sort algorithms (e.g. +quick_sort) require random access iterators and so the sorting of some containers requires a different sort algorithm. +We do not include bucket or radix sorts, as they are always O(n).</li> +<li>Some containers (e.g. deque, hash*) have unusual data structures that make per-container and per-node overhead +calculations not quite account for all memory.</li> +</ul> +<hr style="width: 100%; height: 2px;"> +End of document<br> +<br> +<br> +<br> +<br> +<br> +<br> +<br> +<br> +<br> +<br> +<br> +<br> +<br> +<br> +<br> +<br> +<br> +<br> +<br> +<br> +<br> +<br> +<br> +<br> +<br> +</body> +</html> diff --git a/EASTL/doc/html/EASTLDoc.css b/EASTL/doc/html/EASTLDoc.css new file mode 100644 index 0000000..b2656d8 --- /dev/null +++ b/EASTL/doc/html/EASTLDoc.css @@ -0,0 +1,86 @@ +body +{ + font-family: Georgia, "Times New Roman", Times, serif; + font-size: 12pt; +} + +h1 +{ + font-family: Verdana, Arial, Helvetica, sans-serif; + display: block; + background-color: #BBCCDD; + border: 2px solid #000000; + font-size: 16pt; + font-weight: bold; + padding: 6px; +} + +h2 +{ + font-size: 14pt; + font-family: Verdana; + border-bottom: 2px solid black; +} + +h3 +{ + font-family: Verdana; + font-size: 13pt; + font-weight: bold; +} + +.code-example +{ + display: block; + background-color: #D1DDE9; + margin-left: 3em; + margin-right: 3em; + margin-top: 1em; + margin-bottom: 1em; + padding: 8px; + border: 2px solid #7993C8; + font-family: "Courier New", Courier, mono; + font-size: 10pt; + white-space: pre; +} + +.code-example-span +{ + font-family: "Courier New", Courier, mono; + font-size: 10pt; + white-space: pre; +} + +.code-example-comment +{ + background-color: #e0e0f0; + padding: 0px 0px; + font-family: "Courier New", Courier, mono; + font-size: 10pt; + white-space: pre; + color: #999999; + margin: auto auto; +} + + +.faq-question +{ + background-color: #D9E2EC; + font-size: 12pt; + font-weight: bold; + margin-top: 0em; + padding-left:5px; + padding-right:8px; + padding-top:2px; + padding-bottom:3px; + margin-bottom: 0.5em; +} + +.faq-answer +{ + display: block; + margin: 4pt 1em 0.8em; +} +.indented { + margin-left: 50px; +} |