[ { "path": ".clang-format", "content": "#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-\nLanguage : Cpp\nBasedOnStyle : Google \nStandard : Auto\n#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-\nAccessModifierOffset : -4\nAlignTrailingComments : true\nAllowAllParametersOfDeclarationOnNextLine : false\nAllowShortBlocksOnASingleLine : true\nAllowShortFunctionsOnASingleLine : true\nAllowShortIfStatementsOnASingleLine : false\nAllowShortLoopsOnASingleLine : false\nBinPackParameters : false\nBreakBeforeBraces : Allman\nBreakBeforeTernaryOperators : false\nBreakConstructorInitializersBeforeComma : true\nColumnLimit : 120 \nCpp11BracedListStyle : true\nDerivePointerAlignment : true\nDerivePointerBinding : false\nIndentWidth : 4\nKeepEmptyLinesAtTheStartOfBlocks : true\nMaxEmptyLinesToKeep : 2\nNamespaceIndentation : All \nPointerBindsToType : true\nSpacesBeforeTrailingComments : 1\nSpacesInAngles : false\nSpacesInSquareBrackets : false\nTabWidth : 4\nUseTab : ForIndentation\n#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-\n#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-\n" }, { "path": ".gitattributes", "content": "# Auto detect text files and perform LF normalization\n# http://git-scm.com/docs/gitattributes\n* text=auto\n.appveyor.yml -text eol=crlf\n.appveyor-mingw.yml -text eol=crlf\nci-*.cmd -text eol=crlf" }, { "path": ".github/workflows/c-cpp.yml", "content": "name: EASTL Build & Test Pipeline\n\non:\n push:\n branches: [ master ]\n pull_request:\n branches: [ master ]\n\njobs:\n checkout:\n name: Checkout EASTL\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n with:\n path: EASTL/\n - name: Upload checked out code\n uses: actions/upload-artifact@v4\n with:\n name: Code\n path: EASTL/\n \n build:\n needs: checkout\n \n strategy:\n fail-fast: false\n matrix:\n os: [ windows-latest, ubuntu-latest ]\n compiler: [ clang, gcc, msvc ]\n configuration: [ Debug, Release ]\n std_iter_compatibility: [ std_iter_category_disabled, std_iter_category_enabled ]\n exclude:\n - os: windows-latest\n compiler: gcc\n - os: windows-latest\n compiler: clang\n - os: ubuntu-latest\n compiler: msvc\n include: \n - os: windows-latest\n compiler: msvc\n cxxflags: '/std:c++20 /Zc:char8_t'\n - os: ubuntu-latest\n compiler: clang\n cc: 'clang-18'\n cxx: 'clang++-18'\n cxxflags: '-std=c++20'\n - os: ubuntu-latest\n compiler: gcc\n cc: 'gcc-14'\n cxx: 'g++-14'\n cxxflags: '-std=c++2a'\n\n name: Build EASTL\n runs-on: ${{ matrix.os }}\n \n steps:\n - name: Download a Build Artifact\n uses: actions/download-artifact@v4\n with:\n name: Code\n path: Code/\n\n - run: mkdir build\n - run: cd build && cmake ../Code -DEASTL_BUILD_BENCHMARK:BOOL=ON -DEASTL_BUILD_TESTS:BOOL=ON -DEASTL_STD_ITERATOR_CATEGORY_ENABLED:BOOL=${{ contains(matrix.std_iter_compatibility, 'enabled') && 'ON' || 'OFF' }}\n env:\n CXXFLAGS: ${{ matrix.cxxflags }}\n CXX: ${{ matrix.cxx }}\n CC: ${{ matrix.cc }}\n - run: cd build && cmake --build . --config ${{ matrix.configuration }}\n - name: Upload binaries\n uses: actions/upload-artifact@v4\n with:\n name: Binaries-${{ matrix.os }}-${{ matrix.compiler }}-${{ matrix.configuration }}-${{ matrix.std_iter_compatibility }}\n path: build/\n \n test:\n needs: build\n name: Run EASTL tests\n strategy:\n fail-fast: false\n matrix:\n os: [ windows-latest, ubuntu-latest ]\n compiler: [ clang, msvc, gcc ]\n configuration: [ Debug, Release ]\n std_iter_compatibility: [ std_iter_category_disabled, std_iter_category_enabled ]\n exclude:\n - os: windows-latest\n compiler: gcc\n - os: windows-latest\n compiler: clang\n - os: ubuntu-latest\n compiler: msvc\n runs-on: ${{ matrix.os }}\n \n steps:\n - name: Download a Build Artifact\n uses: actions/download-artifact@v4\n with:\n name: Binaries-${{ matrix.os }}-${{ matrix.compiler }}-${{ matrix.configuration }}-${{ matrix.std_iter_compatibility }}\n path: Binaries/\n - if: matrix.os == 'ubuntu-latest'\n run: chmod 755 ./Binaries/test/EASTLTest\n - run: cd Binaries/test && ctest -C ${{ matrix.configuration }} -V\n \n benchmark:\n needs: build\n name: Run EASTL benchmarks\n strategy:\n fail-fast: false\n matrix:\n os: [ windows-latest, ubuntu-latest ]\n compiler: [ clang, msvc, gcc ]\n configuration: [ Release ]\n exclude:\n - os: windows-latest\n compiler: gcc\n - os: windows-latest\n compiler: clang\n - os: ubuntu-latest\n compiler: msvc\n runs-on: ${{ matrix.os }}\n\n steps:\n - name: Download a Build Artifact\n uses: actions/download-artifact@v4\n with:\n name: Binaries-${{ matrix.os }}-${{ matrix.compiler }}-${{ matrix.configuration }}-std_iter_category_disabled\n path: Binaries/\n - if: matrix.os == 'ubuntu-latest'\n run: chmod 755 ./Binaries/benchmark/EASTLBenchmarks\n - run: cd Binaries/benchmark && ctest -C ${{ matrix.configuration }} -V\n" }, { "path": ".gitignore", "content": "tags\ncscope.out\n**/*.swp\n**/*.swo\n.swp\n*.swp\n.swo\n.TMP\n-.d\neastl_build_out\nbuild_bench\nbench.bat\nbuild.bat\n.p4config\n\n## CMake generated files\nCMakeCache.txt\ncmake_install.cmake\n\n## Patch files\n*.patch\n\n## For Visual Studio Generated projects\n*.sln\n**/*.vcxproj\n**/*.vcxproj.filters\n*.VC.opendb\n*.sdf\n**/*.suo\n**/*.user\n.vs/*\n**/Debug/*\nCMakeFiles/*\nEASTL.dir/**\nRelWithDebInfo/*\nRelease/*\nWin32/*\nx64/*\nMinSizeRel/*\nbuild*/*\nTesting/*\n%ALLUSERSPROFILE%/*\n\n# Buck\n/buck-out/\n/.buckd/\n/buckaroo/\n.buckconfig.local\nBUCKAROO_DEPS\n.vscode/settings.json\n" }, { "path": ".p4ignore", "content": "/.git/\ntags\n.gitignore\ncscope.out\n" }, { "path": "3RDPARTYLICENSES.TXT", "content": "Additional licenses also apply to this software package as detailed below.\n\n\n\nHP STL comes with the following license:\n\n///////////////////////////////////////////////////////////////////////////////\n// Copyright (c) 1994\n// Hewlett-Packard Company\n// \n// Permission to use, copy, modify, distribute and sell this software\n// and its documentation for any purpose is hereby granted without fee,\n// provided that the above copyright notice appear in all copies and\n// that both that copyright notice and this permission notice appear\n// in supporting documentation. Hewlett-Packard Company makes no\n// representations about the suitability of this software for any\n// purpose. It is provided \"as is\" without express or implied warranty.\n///////////////////////////////////////////////////////////////////////////////\n\n\n\nlibc++ comes with the following license:\n\n==============================================================================\nlibc++ License\n==============================================================================\n\nThe libc++ library is dual licensed under both the University of Illinois\n\"BSD-Like\" license and the MIT license. As a user of this code you may choose\nto use it under either license. As a contributor, you agree to allow your code\nto be used under both.\n\nFull text of the relevant licenses is included below.\n\n==============================================================================\n\nUniversity of Illinois/NCSA\nOpen Source License\n\nCopyright (c) 2009-2015 by the contributors listed at \nhttp://llvm.org/svn/llvm-project/libcxx/trunk/CREDITS.TXT\n\nAll rights reserved.\n\nDeveloped by:\n\n LLVM Team\n\n University of Illinois at Urbana-Champaign\n\n http://llvm.org\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of\nthis software and associated documentation files (the \"Software\"), to deal with\nthe Software without restriction, including without limitation the rights to\nuse, copy, modify, merge, publish, distribute, sublicense, and/or sell copies\nof the Software, and to permit persons to whom the Software is furnished to do\nso, subject to the following conditions:\n\n * Redistributions of source code must retain the above copyright notice,\n this list of conditions and the following disclaimers.\n\n * Redistributions in binary form must reproduce the above copyright notice,\n this list of conditions and the following disclaimers in the\n documentation and/or other materials provided with the distribution.\n\n * Neither the names of the LLVM Team, University of Illinois at\n Urbana-Champaign, nor the names of its contributors may be used to\n endorse or promote products derived from this Software without specific\n prior written permission.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS\nFOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nCONTRIBUTORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS WITH THE\nSOFTWARE.\n\n==============================================================================\n\nCopyright (c) 2009-2014 by the contributors listed at \nhttp://llvm.org/svn/llvm-project/libcxx/trunk/CREDITS.TXT\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN\nTHE SOFTWARE.\n\n==============================================================================\n \n*No express or implied license to use PlayStation®4 libraries included.\nPlayStation®4 development tools and libraries are subject to separate license\nwith Sony Interactive Entertainment LLC.\n\n==============================================================================\n\n" }, { "path": "CMakeLists.txt", "content": "#-------------------------------------------------------------------------------------------\n# Copyright (C) Electronic Arts Inc. All rights reserved.\n#-------------------------------------------------------------------------------------------\ncmake_minimum_required(VERSION 3.11)\ninclude(FetchContent)\nproject(EASTL CXX)\n\n#-------------------------------------------------------------------------------------------\n# Options\n#-------------------------------------------------------------------------------------------\noption(EASTL_BUILD_BENCHMARK \"Enable generation of build files for benchmark\" OFF)\noption(EASTL_BUILD_TESTS \"Enable generation of build files for tests\" OFF)\noption(EASTL_STD_ITERATOR_CATEGORY_ENABLED \"Enable compatibility with std:: iterator categories\" OFF)\n\n\noption(EASTL_DISABLE_APRIL_2024_DEPRECATIONS \"Enable use of API marked for removal in April 2024.\" OFF)\noption(EASTL_DISABLE_SEPT_2024_DEPRECATIONS \"Enable use of API marked for removal in September 2024.\" OFF)\noption(EASTL_DISABLE_APRIL_2025_DEPRECATIONS \"Enable use of API marked for removal in April 2025.\" OFF)\n\n#-------------------------------------------------------------------------------------------\n# Compiler Flags\n#-------------------------------------------------------------------------------------------\nset (CMAKE_MODULE_PATH \"${CMAKE_MODULE_PATH};${CMAKE_CURRENT_SOURCE_DIR}/scripts/CMake\")\ninclude(CommonCppFlags)\n\n#-------------------------------------------------------------------------------------------\n# Library definition\n#-------------------------------------------------------------------------------------------\nfile(GLOB EASTL_SOURCES \"source/*.cpp\")\nfile(GLOB_RECURSE EASTL_HEADERS \"include/EASTL/**.h\")\nadd_library(EASTL ${EASTL_SOURCES} ${EASTL_HEADERS})\ntarget_compile_features(EASTL PUBLIC cxx_std_14)\n\n# include both source and headers in the files tab in Visual Studio\nsource_group(TREE ${CMAKE_CURRENT_SOURCE_DIR} PREFIX \"Header Files\" FILES ${EASTL_HEADERS})\n\nif (MSVC)\n set(EASTL_NATVIS_DIR \"doc\")\n set(EASTL_NATVIS_FILE \"${EASTL_NATVIS_DIR}/EASTL.natvis\")\n target_sources(EASTL INTERFACE\n $\n $\n )\nendif()\n\nif(EASTL_BUILD_BENCHMARK)\n add_subdirectory(benchmark)\nendif()\n\nif(EASTL_BUILD_TESTS)\n add_subdirectory(test)\nendif()\n\n#-------------------------------------------------------------------------------------------\n# Defines\n#-------------------------------------------------------------------------------------------\nadd_definitions(-D_CHAR16T)\nadd_definitions(-D_CRT_SECURE_NO_WARNINGS)\nadd_definitions(-D_SCL_SECURE_NO_WARNINGS)\nadd_definitions(-DEASTL_OPENSOURCE=1)\nif (EASTL_STD_ITERATOR_CATEGORY_ENABLED)\n add_definitions(-DEASTL_STD_ITERATOR_CATEGORY_ENABLED=1)\nendif()\n\n#-------------------------------------------------------------------------------------------\n# Include dirs\n#-------------------------------------------------------------------------------------------\ntarget_include_directories(EASTL PUBLIC include)\n\n#-------------------------------------------------------------------------------------------\n# Dependencies\n#-------------------------------------------------------------------------------------------\nFetchContent_Declare(\n EABase\n GIT_REPOSITORY https://github.com/electronicarts/EABase.git\n GIT_TAG 0699a15efdfd20b6cecf02153bfa5663decb653c\n GIT_SUBMODULES \"\" # This should be temporary until we update the cyclic submodule dependencies in EABase.\n)\n\nFetchContent_MakeAvailable(EABase)\n\ntarget_link_libraries(EASTL EABase)\n\n#-------------------------------------------------------------------------------------------\n# Deprecations\n#-------------------------------------------------------------------------------------------\nif(EASTL_DISABLE_APRIL_2024_DEPRECATIONS)\n target_compile_definitions(EASTL PUBLIC EA_DEPRECATIONS_FOR_2024_APRIL=EA_DISABLED)\nendif()\nif(EASTL_DISABLE_SEPT_2024_DEPRECATIONS)\n target_compile_definitions(EASTL PUBLIC EA_DEPRECATIONS_FOR_2024_SEPT=EA_DISABLED)\nendif()\nif(EASTL_DISABLE_APRIL_2025_DEPRECATIONS)\n target_compile_definitions(EASTL PUBLIC EA_DEPRECATIONS_FOR_2025_APRIL=EA_DISABLED)\nendif()\n\n\n#-------------------------------------------------------------------------------------------\n# Installation\n#-------------------------------------------------------------------------------------------\ninstall(TARGETS EASTL DESTINATION lib)\ninstall(DIRECTORY include/EASTL DESTINATION include)\n\nif (MSVC)\n install(FILES ${EASTL_NATVIS_FILE} DESTINATION ${EASTL_NATVIS_DIR})\nendif()\n" }, { "path": "CONTRIBUTING.md", "content": "## Contributing\n\nBefore you can contribute, EA must have a Contributor License Agreement (CLA) on file that has been signed by each contributor.\nYou can sign here: [Go to CLA](https://electronicarts.na1.echosign.com/public/esignWidget?wid=CBFCIBAA3AAABLblqZhByHRvZqmltGtliuExmuV-WNzlaJGPhbSRg2ufuPsM3P0QmILZjLpkGslg24-UJtek*)\n\nIf you want to be recognized for your contributions to EASTL or have a project using EASTL be recognized; you can submit a pull request to the appropriate sections in [README.md](README.md).\nSome examples of what the format and information will look like is as follows.\n* John Smith - jsmith@domain.com\n* John Smith\n* Frostbite - Electronic Arts\n* My Project - [link to said project]\n\n### Pull Request Policy\n\nAll code contributions to EASTL are submitted as [Github pull requests](https://help.github.com/articles/using-pull-requests/). All pull requests will be reviewed by an EASTL maintainer according to the guidelines found in the next section.\n\nYour pull request should:\n\n* merge cleanly\n* come with tests\n\t* tests should be minimal and stable\n\t* fail before your fix is applied\n* pass the test suite\n* code formatting is encoded in clang format\n\t* limit using clang format on new code\n\t* do not deviate from style already established in the files\n\n### Getting the Repository\n\n```bash\ngit clone https://github.com/electronicarts/EASTL\n```\n\n### Running the Unit Tests\n\nEASTL uses CMake as its build system. \n\n* Create and navigate to \"your_build_folder\":\n\t* mkdir your_build_folder && cd your_build_folder\n* Generate build scripts:\n\t* cmake eastl_source_folder -DEASTL_BUILD_TESTS:BOOL=ON\n* Build unit tests for \"your_config\":\n\t* cmake --build . --config your_config\n* Run the unit tests for \"your_config\" from the test folder:\n\t* cd test && ctest -C your_config\n\nHere is an example batch file.\n```batch\nset build_folder=out\nmkdir %build_folder%\npushd %build_folder%\ncall cmake .. -DEASTL_BUILD_TESTS:BOOL=ON -DEASTL_BUILD_BENCHMARK:BOOL=OFF\ncall cmake --build . --config Release\ncall cmake --build . --config Debug\ncall cmake --build . --config RelWithDebInfo\ncall cmake --build . --config MinSizeRel\npushd test\ncall ctest -C Release\ncall ctest -C Debug\ncall ctest -C RelWithDebInfo\ncall ctest -C MinSizeRel\npopd\npopd\n```\n\nHere is an example bash file\n```bash\nbuild_folder=out\nmkdir $build_folder\npushd $build_folder\ncmake .. -DEASTL_BUILD_TESTS:BOOL=ON -DEASTL_BUILD_BENCHMARK:BOOL=OFF\ncmake --build . --config Release\ncmake --build . --config Debug\ncmake --build . --config RelWithDebInfo\ncmake --build . --config MinSizeRel\npushd test\nctest -C Release\nctest -C Debug\nctest -C RelWithDebInfo\nctest -C MinSizeRel\npopd\npopd\n```\n\nThe value of EASTL_BUILD_BENCHMARK can be toggled to `ON` in order to build projects that include the benchmark program.\n" }, { "path": "LICENSE", "content": "BSD 3-Clause License\n\nCopyright (c) 2019, Electronic Arts\nAll rights reserved.\n\nRedistribution and use in source and binary forms, with or without\nmodification, are permitted provided that the following conditions are met:\n\n1. Redistributions of source code must retain the above copyright notice, this\n list of conditions and the following disclaimer.\n\n2. Redistributions in binary form must reproduce the above copyright notice,\n this list of conditions and the following disclaimer in the documentation\n and/or other materials provided with the distribution.\n\n3. Neither the name of the copyright holder nor the names of its\n contributors may be used to endorse or promote products derived from\n this software without specific prior written permission.\n\nTHIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\"\nAND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE\nIMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE\nDISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE\nFOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL\nDAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR\nSERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER\nCAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,\nOR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE\nOF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\n" }, { "path": "README.md", "content": "# EA Standard Template Library\n\n[![Build Status](https://travis-ci.org/electronicarts/EASTL.svg?branch=master)](https://travis-ci.org/electronicarts/EASTL) \n\nEASTL 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.\n\n\n## Usage\n\nIf 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.\n\nEASTL is suitable for any 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.\n\n## Package Managers\n\nYou can download and install EASTL using the [Conan](https://github.com/conan-io/conan) package manager:\n\n conan install eastl/3.15.00@\n\nThe EASTL package in conan is kept up to date by Conan team members and community contributors. If the version is out-of-date, please [create an issue or pull request](https://github.com/conan-io/conan-center-index) on the Conan Center Index repository.\n\n\nYou can download and install EASTL using the [vcpkg](https://github.com/Microsoft/vcpkg) dependency manager:\n\n git clone https://github.com/Microsoft/vcpkg.git\n cd vcpkg\n ./bootstrap-vcpkg.sh\n ./vcpkg integrate install\n vcpkg install eastl\n\nThe EASTL port in vcpkg is kept up to date by Microsoft team members and community contributors. If the version is out of date, please [create an issue or pull request](https://github.com/Microsoft/vcpkg) on the vcpkg repository.\n\n\n## Documentation\n\nPlease see [EASTL Introduction](doc/Introduction.md).\n\n\n## Compiling sources\n\nPlease see [CONTRIBUTING.md](CONTRIBUTING.md) for details on compiling and testing the source.\n\n## Credits And Maintainers\n\nEASTL was created by Paul Pedriana and he maintained the project for roughly 10 years.\n\nEASTL was subsequently maintained by Roberto Parolin for more than 8 years.\nHe was the driver and proponent for getting EASTL opensourced.\nRob was a mentor to all members of the team and taught us everything we ever wanted to know about C++ spookyness.\n\nAfter Rob, maintenance of EASTL passed to Max Winkler for roughly a year, then to Liam Mitchell for about another year. \n\nThe current maintainers (since circa 2022) are Galo Rojo and Jonathan Hopkins.\n\nSignificant EASTL contributions were made by (in alphabetical order):\n\n* Avery Lee\n* Claire Andrews\n* Galo Rojo\n* Jonathan Hopkins\n* JP Flouret\n* Liam Mitchell\n* Matt Newport\n* Max Winkler\n* Paul Pedriana\n* Roberto Parolin\n* Simon Everett\n\n## Contributors\n\n## Projects And Products Using EASTL\n\n* Frostbite - Electronic Arts - [https://www.ea.com/frostbite]\n\n## License\n\nModified BSD License (3-Clause BSD license) see the file LICENSE in the project root.\n" }, { "path": "_config.yml", "content": "theme: jekyll-theme-minimal" }, { "path": "benchmark/CMakeLists.txt", "content": "#-------------------------------------------------------------------------------------------\n# Copyright (C) Electronic Arts Inc. All rights reserved.\n#-------------------------------------------------------------------------------------------\n\n#-------------------------------------------------------------------------------------------\n# CMake info\n#-------------------------------------------------------------------------------------------\ncmake_minimum_required(VERSION 3.1)\nproject(EASTLBenchmarks CXX)\ninclude(CTest)\n\n#-------------------------------------------------------------------------------------------\n# Defines\n#-------------------------------------------------------------------------------------------\nadd_definitions(-D_CHAR16T)\n\n#-------------------------------------------------------------------------------------------\n# Include directories\n#-------------------------------------------------------------------------------------------\ninclude_directories(source)\ninclude_directories(../test/source)\n\n#-------------------------------------------------------------------------------------------\n# Compiler Flags\n#-------------------------------------------------------------------------------------------\nset (CMAKE_MODULE_PATH \"${CMAKE_MODULE_PATH};${CMAKE_CURRENT_SOURCE_DIR}/../scripts/CMake\")\ninclude(CommonCppFlags)\n\n# Libstdc++ calls new internally, since DLLs have no weak symbols, runtime symbol resolution fails and EASTL's new is not called.\n# Linking against static libstdc++ fixes this.\n# See https://github.com/electronicarts/EASTL/issues/40 for more info.\nif (CMAKE_CXX_COMPILER_ID MATCHES \"Clang\" OR CMAKE_CXX_COMPILER_ID MATCHES \"GNU\" AND MINGW)\n set(CMAKE_EXE_LINKER_FLAGS_RELEASE \"${CMAKE_EXE_LINKER_FLAGS_RELEASE} -static-libstdc++\")\n set(CMAKE_EXE_LINKER_FLAGS_RELWITHDEBINFO \"${CMAKE_EXE_LINKER_FLAGS_RELWITHDEBINFO} -static-libstdc++\")\n set(CMAKE_EXE_LINKER_FLAGS_MINSIZEREL \"${CMAKE_EXE_LINKER_FLAGS_MINSIZEREL} -static-libstdc++\")\nendif()\n\nif (CMAKE_CXX_COMPILER_ID MATCHES \"Clang\" AND CMAKE_BUILD_TYPE MATCHES \"MinSizeRel\" AND MINGW)\n message(FATAL_ERROR \"FIXME: MinSizeRel on MingW-w64's Clang fails to link.\")\nendif()\n\n# The benchmark suite fails to compile if char8_t is enabled, so disable it.\nif (EASTL_NO_CHAR8T_FLAG)\n add_compile_options(${EASTL_NO_CHAR8T_FLAG})\nendif()\n\n#-------------------------------------------------------------------------------------------\n# Source files\n#-------------------------------------------------------------------------------------------\nfile(GLOB EASTLBENCHMARK_SOURCES \"source/*.cpp\")\nfile(GLOB EASTLTEST_SOURCES \"../test/source/EASTLTestAllocator.cpp\" \"../test/source/EASTLTest.cpp\")\nfile(GLOB EASTLBENCHMARK_HEADERS \"source/*.h\")\nset(SOURCES ${EASTLBENCHMARK_SOURCES} ${EASTLTEST_SOURCES} ${EASTLBENCHMARK_HEADERS})\n\n# include both source and headers in the files view in Visual Studio\nsource_group(TREE ${CMAKE_CURRENT_SOURCE_DIR} PREFIX \"Header Files\" FILES ${EASTLBENCHMARK_HEADERS})\n\n#-------------------------------------------------------------------------------------------\n# Defines\n#-------------------------------------------------------------------------------------------\nadd_definitions(-D_CRT_SECURE_NO_WARNINGS)\nadd_definitions(-D_SCL_SECURE_NO_WARNINGS)\nadd_definitions(-DEASTL_THREAD_SUPPORT_AVAILABLE=0)\nadd_definitions(-DEASTL_OPENSOURCE=1)\nadd_definitions(-D_SILENCE_STDEXT_HASH_DEPRECATION_WARNINGS) # silence std::hash_map deprecation warnings\nif (EASTL_STD_ITERATOR_CATEGORY_ENABLED)\n add_definitions(-DEASTL_STD_ITERATOR_CATEGORY_ENABLED=1)\nendif()\n\nif(NOT EASTL_BUILD_TESTS)\n add_subdirectory(../test/packages/EAStdC ../test/EAStdC)\n add_subdirectory(../test/packages/EAAssert ../test/EAAssert)\n add_subdirectory(../test/packages/EAThread ../test/EAThread)\n add_subdirectory(../test/packages/EATest ../test/EATest)\n add_subdirectory(../test/packages/EAMain ../test/EAMain)\nendif()\n\n#-------------------------------------------------------------------------------------------\n# Executable definition\n#-------------------------------------------------------------------------------------------\nadd_executable(EASTLBenchmarks ${SOURCES})\n\nset(THREADS_PREFER_PTHREAD_FLAG ON)\nfind_package(Threads REQUIRED)\n\nset(EASTLBenchmark_Libraries\n EABase\n EAAssert\n EAMain\n EAThread\n EAStdC\n EASTL\n EATest)\ntarget_link_libraries(EASTLBenchmarks ${EASTLBenchmark_Libraries} Threads::Threads)\n\n#-------------------------------------------------------------------------------------------\n# Run Unit tests and verify the results.\n#-------------------------------------------------------------------------------------------\nadd_test(EASTLBenchmarkRuns EASTLBenchmarks)\nset_tests_properties (EASTLBenchmarkRuns PROPERTIES PASS_REGULAR_EXPRESSION \"RETURNCODE=0\")\n\n" }, { "path": "benchmark/source/BenchmarkAlgorithm.cpp", "content": "/////////////////////////////////////////////////////////////////////////////\n// BenchmarkAlgorithm.cpp\n//\n// Copyright (c) Electronic Arts Inc. All rights reserved.\n/////////////////////////////////////////////////////////////////////////////\n\n\n#include \"EASTLBenchmark.h\"\n#include \"EASTLTest.h\"\n#include \n#include \n#include \n#include \n#include \n#include \n#include \n#include \n#include \n\nEA_DISABLE_ALL_VC_WARNINGS()\n#include \n#include \n#include \n#include \n#include \n#include \nEA_RESTORE_ALL_VC_WARNINGS()\n\n#ifdef _MSC_VER\n\t#pragma warning(disable: 4996) // Function call with parameters that may be unsafe\n#endif\n\n\nusing namespace EA;\n\n\ntypedef std::vector StdVectorUChar;\ntypedef eastl::vector EaVectorUChar;\n\ntypedef std::vector StdVectorSChar;\ntypedef eastl::vector EaVectorSChar;\n\ntypedef std::vector StdVectorUint32;\ntypedef eastl::vector EaVectorUint32;\n\ntypedef std::vector StdVectorUint64;\ntypedef eastl::vector EaVectorUint64;\n\ntypedef std::vector StdVectorTO;\ntypedef eastl::vector EaVectorTO;\n\n\n// We make a fake version of C++11 std::next, as some C++ compilers don't currently \n// provide the C++11 next algorithm in their standard libraries.\nnamespace std__\n{\n\ttemplate\n\tinline InputIterator \n\tnext(InputIterator it, typename std::iterator_traits::difference_type n = 1)\n\t{\n\t\tstd::advance(it, n);\n\t\treturn it;\n\t}\n}\n\n\nnamespace\n{\n\t// Exists for the purpose testing PODs that are larger than built-in types.\n\ttemplate \n\tstruct SizedPOD\n\t{\n\t\tchar memory[kSize];\n\t};\n\n\tvoid TestFindEndStd(EA::StdC::Stopwatch& stopwatch, const std::string& sTest, const char* pSearchStringBegin, const char* pSearchStringEnd)\n\t{\n\t\tstopwatch.Restart();\n\t\tstd::string::const_iterator it = std::find_end(sTest.begin(), sTest.end(), pSearchStringBegin, pSearchStringEnd);\n\t\tstopwatch.Stop();\n\t\tif(it != sTest.end())\n\t\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%c\", *it);\n\t}\n\n\tvoid TestFindEndEa(EA::StdC::Stopwatch& stopwatch, const eastl::string& sTest, const char* pSearchStringBegin, const char* pSearchStringEnd)\n\t{\n\t\tstopwatch.Restart();\n\t\teastl::string::const_iterator it = eastl::find_end(sTest.begin(), sTest.end(), pSearchStringBegin, pSearchStringEnd);\n\t\tstopwatch.Stop();\n\t\tif(it != sTest.end())\n\t\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%c\", *it);\n\t}\n\n\n\n\tvoid TestSearchStd(EA::StdC::Stopwatch& stopwatch, const std::string& sTest, const char* pSearchStringBegin, const char* pSearchStringEnd)\n\t{\n\t\tstopwatch.Restart();\n\t\tstd::string::const_iterator it = std::search(sTest.begin(), sTest.end(), pSearchStringBegin, pSearchStringEnd);\n\t\tstopwatch.Stop();\n\t\tif(it != sTest.end())\n\t\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%c\", *it);\n\t}\n\n\tvoid TestSearchEa(EA::StdC::Stopwatch& stopwatch, const eastl::string& sTest, const char* pSearchStringBegin, const char* pSearchStringEnd)\n\t{\n\t\tstopwatch.Restart();\n\t\teastl::string::const_iterator it = eastl::search(sTest.begin(), sTest.end(), pSearchStringBegin, pSearchStringEnd);\n\t\tstopwatch.Stop();\n\t\tif(it != sTest.end())\n\t\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%c\", *it);\n\t}\n\n\n\n\tvoid TestSearchNStd(EA::StdC::Stopwatch& stopwatch, const std::string& sTest, int n, char c)\n\t{\n\t\tstopwatch.Restart();\n\t\tstd::string::const_iterator it = std::search_n(sTest.begin(), sTest.end(), n, c);\n\t\tstopwatch.Stop();\n\t\tif(it != sTest.end())\n\t\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%c\", *it);\n\t}\n\n\tvoid TestSearchNEa(EA::StdC::Stopwatch& stopwatch, const eastl::string& sTest, int n, char c)\n\t{\n\t\tstopwatch.Restart();\n\t\teastl::string::const_iterator it = eastl::search_n(sTest.begin(), sTest.end(), n, c);\n\t\tstopwatch.Stop();\n\t\tif(it != sTest.end())\n\t\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%c\", *it);\n\t}\n\n\n\n\ttemplate \n\tvoid TestUniqueStd(EA::StdC::Stopwatch& stopwatch, Container& c)\n\t{\n\t\tstopwatch.Restart();\n\t\ttypename Container::iterator it = std::unique(c.begin(), c.end());\n\t\tstopwatch.Stop();\n\t\tc.erase(it, c.end());\n\t}\n\n\ttemplate \n\tvoid TestUniqueEa(EA::StdC::Stopwatch& stopwatch, Container& c)\n\t{\n\t\tstopwatch.Restart();\n\t\ttypename Container::iterator it = eastl::unique(c.begin(), c.end());\n\t\tstopwatch.Stop(); \n\t\tc.erase(it, c.end());\n\t}\n\n\n\n\ttemplate \n\tvoid TestMinElementStd(EA::StdC::Stopwatch& stopwatch, const Container& c)\n\t{\n\t\tstopwatch.Restart();\n\t\tconst typename Container::const_iterator it = std::min_element(c.begin(), c.end());\n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%p\", &it);\n\t}\n\n\ttemplate \n\tvoid TestMinElementEa(EA::StdC::Stopwatch& stopwatch, const Container& c)\n\t{\n\t\tstopwatch.Restart();\n\t\tconst typename Container::const_iterator it = eastl::min_element(c.begin(), c.end());\n\t\tstopwatch.Stop(); \n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%p\", &it);\n\t}\n\n\n\n\ttemplate \n\tvoid TestCountStd(EA::StdC::Stopwatch& stopwatch, const Container& c)\n\t{\n\t\tstopwatch.Restart();\n\t\tconst typename Container::difference_type n = std::count(c.begin(), c.end(), (typename Container::value_type)999999);\n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%d\", (int)n);\n\t}\n\n\ttemplate \n\tvoid TestCountEa(EA::StdC::Stopwatch& stopwatch, const Container& c)\n\t{\n\t\tstopwatch.Restart();\n\t\tconst typename Container::difference_type n = eastl::count(c.begin(), c.end(), (typename Container::value_type)999999);\n\t\tstopwatch.Stop(); \n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%d\", (int)n);\n\t}\n\n\n\n\ttemplate \n\tvoid TestAdjacentFindStd(EA::StdC::Stopwatch& stopwatch, const Container& c)\n\t{\n\t\tstopwatch.Restart();\n\t\tconst typename Container::const_iterator it = std::adjacent_find(c.begin(), c.end());\n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%p\", &it);\n\t}\n\n\ttemplate \n\tvoid TestAdjacentFindEa(EA::StdC::Stopwatch& stopwatch, const Container& c)\n\t{\n\t\tstopwatch.Restart();\n\t\tconst typename Container::const_iterator it = eastl::adjacent_find(c.begin(), c.end());\n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%p\", &it);\n\t}\n\n\n\n\ttemplate \n\tvoid TestLowerBoundStd(EA::StdC::Stopwatch& stopwatch, const Container& c, const typename Container::value_type* pBegin, const typename Container::value_type* pEnd)\n\t{\n\n\t\tstopwatch.Restart();\n\t\twhile(pBegin != pEnd)\n\t\t{\n\t\t\ttypename Container::const_iterator it = std::lower_bound(c.begin(), c.end(), *pBegin++);\n\t\t\tBenchmark::DoNothing(&it);\n\t\t}\n\t\tstopwatch.Stop();\n\t}\n\n\ttemplate \n\tvoid TestLowerBoundEa(EA::StdC::Stopwatch& stopwatch, Container& c, const typename Container::value_type* pBegin, const typename Container::value_type* pEnd)\n\t{\n\t\tstopwatch.Restart();\n\t\twhile(pBegin != pEnd)\n\t\t{\n\t\t\ttypename Container::const_iterator it = eastl::lower_bound(c.begin(), c.end(), *pBegin++);\n\t\t\tBenchmark::DoNothing(&it);\n\t\t}\n\t\tstopwatch.Stop(); \n\t}\n\n\n\n\ttemplate \n\tvoid TestUpperBoundStd(EA::StdC::Stopwatch& stopwatch, const Container& c, const typename Container::value_type* pBegin, const typename Container::value_type* pEnd)\n\t{\n\t\tstopwatch.Restart();\n\t\twhile(pBegin != pEnd)\n\t\t{\n\t\t\ttypename Container::const_iterator it = std::upper_bound(c.begin(), c.end(), *pBegin++);\n\t\t\tBenchmark::DoNothing(&it);\n\t\t}\n\t\tstopwatch.Stop();\n\t}\n\n\ttemplate \n\tvoid TestUpperBoundEa(EA::StdC::Stopwatch& stopwatch, Container& c, const typename Container::value_type* pBegin, const typename Container::value_type* pEnd)\n\t{\n\t\tstopwatch.Restart();\n\t\twhile(pBegin != pEnd)\n\t\t{\n\t\t\ttypename Container::const_iterator it = eastl::upper_bound(c.begin(), c.end(), *pBegin++);\n\t\t\tBenchmark::DoNothing(&it);\n\t\t}\n\t\tstopwatch.Stop();\n\t}\n\n\n\n\ttemplate \n\tvoid TestEqualRangeStd(EA::StdC::Stopwatch& stopwatch, const Container& c, const typename Container::value_type* pBegin, const typename Container::value_type* pEnd)\n\t{\n\t\tstopwatch.Restart();\n\t\twhile(pBegin != pEnd)\n\t\t{\n\t\t\tstd::pair itPair = std::equal_range(c.begin(), c.end(), *pBegin++);\n\n\t\t\tBenchmark::DoNothing(&itPair);\n\t\t}\n\t\tstopwatch.Stop();\n\t}\n\n\ttemplate \n\tvoid TestEqualRangeEa(EA::StdC::Stopwatch& stopwatch, Container& c, const typename Container::value_type* pBegin, const typename Container::value_type* pEnd)\n\t{\n\t\tstopwatch.Restart();\n\t\twhile(pBegin != pEnd)\n\t\t{\n\t\t\teastl::pair itPair = eastl::equal_range(c.begin(), c.end(), *pBegin++);\n\t\t\tBenchmark::DoNothing(&itPair);\n\t\t}\n\t\tstopwatch.Stop();\n\t}\n\n\n\n\ttemplate \n\tvoid TestLexicographicalCompareStd(EA::StdC::Stopwatch& stopwatch, Iterator1 first1, Iterator1 last1, Iterator2 first2, Iterator2 last2)\n\t{\n\t\tstopwatch.Restart();\n\t\tconst bool bResult = std::lexicographical_compare(first1, last1, first2, last2);\n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%d\", bResult ? (int)1 : (int)0);\n\t}\n\n\ttemplate \n\tvoid TestLexicographicalCompareEa(EA::StdC::Stopwatch& stopwatch, Iterator1 first1, Iterator1 last1, Iterator2 first2, Iterator2 last2)\n\t{\n\t\tstopwatch.Restart();\n\t\tconst bool bResult = eastl::lexicographical_compare(first1, last1, first2, last2);\n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%d\", bResult ? (int)1 : (int)0);\n\t}\n\n\n\n\ttemplate \n\tvoid TestCopyStd(EA::StdC::Stopwatch& stopwatch, Iterator first, Iterator last, OutputIterator result)\n\t{\n\t\tstopwatch.Restart();\n\t\tstd::copy(first, last, result);\n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%d\", (int)*first);\n\t}\n\n\ttemplate \n\tvoid TestCopyEa(EA::StdC::Stopwatch& stopwatch, Iterator first, Iterator last, OutputIterator result)\n\t{\n\t\tstopwatch.Restart();\n\t\teastl::copy(first, last, result);\n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%d\", (int)*first);\n\t}\n\n\n\n\ttemplate \n\tvoid TestCopyBackwardStd(EA::StdC::Stopwatch& stopwatch, Iterator first, Iterator last, OutputIterator result)\n\t{\n\t\tstopwatch.Restart();\n\t\tstd::copy_backward(first, last, result);\n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%d\", (int)*first);\n\t}\n\n\ttemplate \n\tvoid TestCopyBackwardEa(EA::StdC::Stopwatch& stopwatch, Iterator first, Iterator last, OutputIterator result)\n\t{\n\t\tstopwatch.Restart();\n\t\teastl::copy_backward(first, last, result);\n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%d\", (int)*first);\n\t}\n\n\n\n\ttemplate \n\tvoid TestFillStd(EA::StdC::Stopwatch& stopwatch, Iterator first, Iterator last, const Value& v)\n\t{\n\t\tstopwatch.Restart();\n\t\tstd::fill(first, last, v);\n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%p\", &*first);\n\t}\n\n\ttemplate \n\tvoid TestFillEa(EA::StdC::Stopwatch& stopwatch, Iterator first, Iterator last, const Value& v)\n\t{\n\t\tstopwatch.Restart();\n\t\teastl::fill(first, last, v);\n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%p\", &*first);\n\t}\n\n\n\n\ttemplate \n\tvoid TestFillNStd(EA::StdC::Stopwatch& stopwatch, Iterator first, int n, const Value& v)\n\t{\n\t\tstopwatch.Restart();\n\t\tstd::fill_n(first, n, v);\n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%p\", &*first);\n\t}\n\n\ttemplate \n\tvoid TestFillNEa(EA::StdC::Stopwatch& stopwatch, Iterator first, int n, const Value& v)\n\t{\n\t\tstopwatch.Restart();\n\t\teastl::fill_n(first, n, v);\n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%p\", &*first);\n\t}\n\n\n\n\ttemplate \n\tvoid TestReverseStd(EA::StdC::Stopwatch& stopwatch, Iterator first, Iterator last)\n\t{\n\t\tstopwatch.Restart();\n\t\tstd::reverse(first, last);\n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%p\", &*first);\n\t}\n\n\ttemplate \n\tvoid TestReverseEa(EA::StdC::Stopwatch& stopwatch, Iterator first, Iterator last)\n\t{\n\t\tstopwatch.Restart();\n\t\teastl::reverse(first, last);\n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%p\", &*first);\n\t}\n\n\n\n\ttemplate \n\tvoid TestRotateStd(EA::StdC::Stopwatch& stopwatch, Iterator first, Iterator middle, Iterator last)\n\t{\n\t\tstopwatch.Restart();\n\t\tstd::rotate(first, middle, last); // C++11 specifies that rotate has a return value, but not all std implementations return it.\n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%p\", &*first);\n\t}\n\n\ttemplate \n\tvoid TestRotateEa(EA::StdC::Stopwatch& stopwatch, Iterator first, Iterator middle, Iterator last)\n\t{\n\t\tstopwatch.Restart();\n\t\teastl::rotate(first, middle, last);\n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%p\", &*first);\n\t}\n\n\ttemplate \n\tvoid TestMergeStd(EA::StdC::Stopwatch& stopwatch, Iterator firstIn1, Iterator lastIn1, Iterator firstIn2, Iterator lastIn2, Iterator out)\n\t{\n\t\tstopwatch.Restart();\n\t\tstd::merge(firstIn1, lastIn1, firstIn2, lastIn2, out);\n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%p\", &*out);\n\t}\n\n\ttemplate \n\tvoid TestMergeEa(EA::StdC::Stopwatch& stopwatch, Iterator firstIn1, Iterator lastIn1, Iterator firstIn2, Iterator lastIn2, Iterator out)\n\t{\n\t\tstopwatch.Restart();\n\t\teastl::merge(firstIn1, lastIn1, firstIn2, lastIn2, out);\n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%p\", &*out);\n\t}\n} // namespace\n\n\n\n\nvoid BenchmarkAlgorithm1(EASTLTest_Rand& /*rng*/, EA::StdC::Stopwatch& stopwatch1, EA::StdC::Stopwatch& stopwatch2)\n{\n\t{\n\t\tstd::string sTestStd;\n\t\teastl::string sTestEa;\n\t\tconst char* pSearchString1Begin = \"AAA\";\n\t\tconst char* pSearchString1End = pSearchString1Begin + strlen(pSearchString1Begin);\n\t\tconst char* pSearchString2Begin = \"BBB\"; // This is something that doesn't exist searched string.\n\t\tconst char* pSearchString2End = pSearchString2Begin + strlen(pSearchString2Begin);\n\t\tconst char* pSearchString3Begin = \"CCC\";\n\t\tconst char* pSearchString3End = pSearchString3Begin + strlen(pSearchString3Begin);\n\n\t\tfor(int i = 0; i < 10000; i++)\n\t\t\tsTestStd += \"This is a test of the find_end algorithm. \";\n\t\tsTestEa.assign(sTestStd.data(), (eastl_size_t)sTestStd.length());\n\n\t\tfor(int i = 0; i < 2; i++)\n\t\t{\n\t\t\t///////////////////////////////\n\t\t\t// Test find_end\n\t\t\t///////////////////////////////\n\n\t\t\tsTestStd.insert(sTestStd.size() * 15 / 16, pSearchString1Begin);\n\t\t\tsTestEa.insert (sTestEa.size() * 15 / 16, pSearchString1Begin);\n\t\t\tTestFindEndStd(stopwatch1, sTestStd, pSearchString1Begin, pSearchString1End);\n\t\t\tTestFindEndEa (stopwatch2, sTestEa, pSearchString1Begin, pSearchString1End);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"algorithm/find_end/string/end\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tsTestStd.insert(sTestStd.size() / 2, pSearchString2Begin);\n\t\t\tsTestEa.insert (sTestEa.size() / 2, pSearchString2Begin);\n\t\t\tTestFindEndStd(stopwatch1, sTestStd, pSearchString2Begin, pSearchString2End);\n\t\t\tTestFindEndEa (stopwatch2, sTestEa, pSearchString2Begin, pSearchString2End);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"algorithm/find_end/string/middle\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tTestFindEndStd(stopwatch1, sTestStd, pSearchString3Begin, pSearchString3End);\n\t\t\tTestFindEndEa (stopwatch2, sTestEa, pSearchString3Begin, pSearchString3End);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"algorithm/find_end/string/none\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test search\n\t\t\t///////////////////////////////\n\t\t\tTestSearchStd(stopwatch1, sTestStd, pSearchString1Begin, pSearchString1End);\n\t\t\tTestSearchEa (stopwatch2, sTestEa, pSearchString1Begin, pSearchString1End);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"algorithm/search/string\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test search_n\n\t\t\t///////////////////////////////\n\t\t\tTestSearchNStd(stopwatch1, sTestStd, 3, 'A');\n\t\t\tTestSearchNEa (stopwatch2, sTestEa, 3, 'A');\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"algorithm/search_n/string\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test adjacent_find\n\t\t\t///////////////////////////////\n\n\t\t}\n\t}\n}\n\n\nvoid BenchmarkAlgorithm2(EASTLTest_Rand& rng, EA::StdC::Stopwatch& stopwatch1, EA::StdC::Stopwatch& stopwatch2)\n{\n\t{\n\t\tStdVectorUint32 stdVectorUint32;\n\t\tEaVectorUint32 eaVectorUint32;\n\n\t\tStdVectorUint64 stdVectorUint64;\n\t\tEaVectorUint64 eaVectorUint64;\n\n\t\tStdVectorTO stdVectorTO;\n\t\tEaVectorTO eaVectorTO;\n\n\t\tfor(int i = 0; i < 2; i++)\n\t\t{\n\t\t\tstdVectorUint32.clear();\n\t\t\teaVectorUint32.clear();\n\n\t\t\tfor(int j = 0; j < 100000; j++)\n\t\t\t{\n\t\t\t\tstdVectorUint32.push_back(j);\n\t\t\t\teaVectorUint32.push_back(j);\n\t\t\t\tstdVectorUint64.push_back(j);\n\t\t\t\teaVectorUint64.push_back(j);\n\t\t\t\tstdVectorTO.push_back(TestObject(j));\n\t\t\t\teaVectorTO.push_back(TestObject(j));\n\n\t\t\t\tif((rng() % 16) == 0)\n\t\t\t\t{\n\t\t\t\t\tstdVectorUint32.push_back(i);\n\t\t\t\t\teaVectorUint32.push_back(i);\n\t\t\t\t\tstdVectorUint64.push_back(j);\n\t\t\t\t\teaVectorUint64.push_back(j);\n\t\t\t\t\tstdVectorTO.push_back(TestObject(j));\n\t\t\t\t\teaVectorTO.push_back(TestObject(j));\n\n\t\t\t\t\tif((rng() % 16) == 0)\n\t\t\t\t\t{\n\t\t\t\t\t\tstdVectorUint32.push_back(i);\n\t\t\t\t\t\teaVectorUint32.push_back(i);\n\t\t\t\t\t\tstdVectorUint64.push_back(j);\n\t\t\t\t\t\teaVectorUint64.push_back(j);\n\t\t\t\t\t\tstdVectorTO.push_back(TestObject(j));\n\t\t\t\t\t\teaVectorTO.push_back(TestObject(j));\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test unique\n\t\t\t///////////////////////////////\n\n\t\t\tTestUniqueStd(stopwatch1, stdVectorUint32);\n\t\t\tTestUniqueEa (stopwatch2, eaVectorUint32);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"algorithm/unique/vector\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tTestUniqueStd(stopwatch1, stdVectorUint64);\n\t\t\tTestUniqueEa (stopwatch2, eaVectorUint64);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"algorithm/unique/vector\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tTestUniqueStd(stopwatch1, stdVectorTO);\n\t\t\tTestUniqueEa (stopwatch2, eaVectorTO);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"algorithm/unique/vector\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test min_element\n\t\t\t///////////////////////////////\n\n\t\t\tTestMinElementStd(stopwatch1, stdVectorTO);\n\t\t\tTestMinElementEa (stopwatch2, eaVectorTO);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"algorithm/min_element/vector\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test count\n\t\t\t///////////////////////////////\n\n\t\t\tTestCountStd(stopwatch1, stdVectorUint64);\n\t\t\tTestCountEa (stopwatch2, eaVectorUint64);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"algorithm/count/vector\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t\n\t\t\t///////////////////////////////\n\t\t\t// Test adjacent_find\n\t\t\t///////////////////////////////\n\n\t\t\t// Due to the above unique testing, the container should container unique elements. Let's change that.\n\t\t\tstdVectorTO[stdVectorTO.size() - 2] = stdVectorTO[stdVectorTO.size() - 1];\n\t\t\teaVectorTO[eaVectorTO.size() - 2] = eaVectorTO[eaVectorTO.size() - 1];\n\t\t\tTestAdjacentFindStd(stopwatch1, stdVectorTO);\n\t\t\tTestAdjacentFindEa (stopwatch2, eaVectorTO);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"algorithm/adj_find/vector\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test lower_bound\n\t\t\t///////////////////////////////\n\n\t\t\t// Sort the containers for the following tests.\n\t\t\tstd::sort(stdVectorTO.begin(), stdVectorTO.end());\n\t\t\teaVectorTO.assign(&stdVectorTO[0], &stdVectorTO[0] + stdVectorTO.size());\n\n\t\t\tTestLowerBoundStd(stopwatch1, stdVectorTO, &stdVectorTO[0], &stdVectorTO[0] + stdVectorTO.size());\n\t\t\tTestLowerBoundEa (stopwatch2, eaVectorTO, &eaVectorTO[0], &eaVectorTO[0] + eaVectorTO.size());\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"algorithm/lower_bound/vector\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test upper_bound\n\t\t\t///////////////////////////////\n\n\t\t\tstd::sort(stdVectorUint32.begin(), stdVectorUint32.end());\n\t\t\teaVectorUint32.assign(&stdVectorUint32[0], &stdVectorUint32[0] + stdVectorUint32.size());\n\n\t\t\tTestUpperBoundStd(stopwatch1, stdVectorUint32, &stdVectorUint32[0], &stdVectorUint32[0] + stdVectorUint32.size());\n\t\t\tTestUpperBoundEa (stopwatch2, eaVectorUint32, &eaVectorUint32[0], &eaVectorUint32[0] + eaVectorUint32.size());\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"algorithm/upper_bound/vector\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test equal_range\n\t\t\t///////////////////////////////\n\n\t\t\t// VS2010 (and later versions?) is extremely slow executing this in debug builds. It can take minutes for a \n\t\t\t// single TestEqualRangeStd call to complete. It's so slow that it's nearly pointless to execute.\n\t\t\t#if !defined(_MSC_VER) || (_MSC_VER < 1600) || !defined(_ITERATOR_DEBUG_LEVEL) || (_ITERATOR_DEBUG_LEVEL < 2) \n\t\t\t\tstd::sort(stdVectorUint64.begin(), stdVectorUint64.end());\n\t\t\t\teaVectorUint64.assign(&stdVectorUint64[0], &stdVectorUint64[0] + stdVectorUint64.size());\n\n\t\t\t\tTestEqualRangeStd(stopwatch1, stdVectorUint64, &stdVectorUint64[0], &stdVectorUint64[0] + stdVectorUint64.size());\n\t\t\t\tTestEqualRangeEa (stopwatch2, eaVectorUint64, &eaVectorUint64[0], &eaVectorUint64[0] + eaVectorUint64.size());\n\n\t\t\t\tif(i == 1)\n\t\t\t\t\tBenchmark::AddResult(\"algorithm/equal_range/vector\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\t\t\t#endif\n\t\t}\n\t}\n}\n\n\nvoid BenchmarkAlgorithm3(EASTLTest_Rand& /*rng*/, EA::StdC::Stopwatch& stopwatch1, EA::StdC::Stopwatch& stopwatch2)\n{\n\t{\n\t\tStdVectorUChar stdVectorUChar1(100000);\n\t\tStdVectorUChar stdVectorUChar2(100000);\n\t\tEaVectorUChar eaVectorUChar1(100000);\n\t\tEaVectorUChar eaVectorUChar2(100000);\n\n\t\tStdVectorSChar stdVectorSChar1(100000);\n\t\tStdVectorSChar stdVectorSChar2(100000);\n\t\tEaVectorSChar eaVectorSChar1(100000);\n\t\tEaVectorSChar eaVectorSChar2(100000);\n\n\t\tStdVectorTO stdVectorTO1(100000);\n\t\tStdVectorTO stdVectorTO2(100000);\n\t\tEaVectorTO eaVectorTO1(100000);\n\t\tEaVectorTO eaVectorTO2(100000);\n\n\t\t// All these containers should have values of zero in them.\n\n\t\tfor(int i = 0; i < 2; i++)\n\t\t{\n\t\t\t///////////////////////////////\n\t\t\t// Test lexicographical_compare\n\t\t\t///////////////////////////////\n\n\t\t\tTestLexicographicalCompareStd(stopwatch1, stdVectorUChar1.begin(), stdVectorUChar1.end(), stdVectorUChar2.begin(), stdVectorUChar2.end());\n\t\t\tTestLexicographicalCompareEa (stopwatch2, eaVectorUChar1.begin(), eaVectorUChar2.end(), eaVectorUChar2.begin(), eaVectorUChar2.end());\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"algorithm/lex_cmp/vector\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tTestLexicographicalCompareStd(stopwatch1, &stdVectorSChar1[0], &stdVectorSChar1[0] + stdVectorSChar1.size(), &stdVectorSChar2[0], &stdVectorSChar2[0] + stdVectorSChar2.size());\n\t\t\tTestLexicographicalCompareEa (stopwatch2, &eaVectorSChar1[0], &eaVectorSChar1[0] + eaVectorSChar1.size(), &eaVectorSChar2[0], &eaVectorSChar2[0] + eaVectorSChar2.size());\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"algorithm/lex_cmp/schar[]\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tTestLexicographicalCompareStd(stopwatch1, stdVectorTO1.begin(), stdVectorTO1.end(), stdVectorTO2.begin(), stdVectorTO2.end());\n\t\t\tTestLexicographicalCompareEa (stopwatch2, eaVectorTO1.begin(), eaVectorTO1.end(), eaVectorTO2.begin(), eaVectorTO2.end());\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"algorithm/lex_cmp/vector\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\t\t}\n\t}\n\n}\n\n\nvoid BenchmarkAlgorithm4(EASTLTest_Rand& /*rng*/, EA::StdC::Stopwatch& stopwatch1, EA::StdC::Stopwatch& stopwatch2)\n{\n\t{\n\t\tstd::vector stdVectorUint321(10000);\n\t\tstd::vector stdVectorUint322(10000);\n\t\teastl::vector eaVectorUint321(10000);\n\t\teastl::vector eaVectorUint322(10000);\n\n\t\tstd::vector stdVectorUint64(100000);\n\t\teastl::vector eaVectorUint64(100000);\n\n\n\t\tfor(int i = 0; i < 2; i++)\n\t\t{\n\t\t\t///////////////////////////////\n\t\t\t// Test copy\n\t\t\t///////////////////////////////\n\n\t\t\tTestCopyStd(stopwatch1, stdVectorUint321.begin(), stdVectorUint321.end(), stdVectorUint322.begin());\n\t\t\tTestCopyEa (stopwatch2, eaVectorUint321.begin(), eaVectorUint321.end(), eaVectorUint322.begin());\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"algorithm/copy/vector\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test copy_backward\n\t\t\t///////////////////////////////\n\n\t\t\tTestCopyBackwardStd(stopwatch1, stdVectorUint321.begin(), stdVectorUint321.end(), stdVectorUint322.end());\n\t\t\tTestCopyBackwardEa (stopwatch2, eaVectorUint321.begin(), eaVectorUint321.end(), eaVectorUint322.end());\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"algorithm/copy_backward/vector\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test fill\n\t\t\t///////////////////////////////\n\n\t\t\tTestFillStd(stopwatch1, stdVectorUint64.begin(), stdVectorUint64.end(), UINT64_C(37));\n\t\t\tTestFillEa (stopwatch2, eaVectorUint64.begin(), eaVectorUint64.end(), UINT64_C(37));\n\t\t\tTestFillStd(stopwatch1, stdVectorUint64.begin(), stdVectorUint64.end(), UINT64_C(37)); // Intentionally do this a second time, as we are finding \n\t\t\tTestFillEa (stopwatch2, eaVectorUint64.begin(), eaVectorUint64.end(), UINT64_C(37)); // the results are inconsistent otherwise.\n\t\t\tif(EA::StdC::Memcheck64(&eaVectorUint64[0], UINT64_C(37), eaVectorUint64.size()))\n\t\t\t\tEA::UnitTest::Report(\"eastl algorithm 64 bit fill failure.\");\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"algorithm/fill/vector\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test fill_n\n\t\t\t///////////////////////////////\n\n\t\t\tTestFillNStd(stopwatch1, stdVectorUint64.begin(), (int)stdVectorUint64.size(), UINT64_C(37));\n\t\t\tTestFillNEa (stopwatch2, eaVectorUint64.begin(), (int) eaVectorUint64.size(), UINT64_C(37));\n\t\t\tTestFillNStd(stopwatch1, stdVectorUint64.begin(), (int)stdVectorUint64.size(), UINT64_C(37)); // Intentionally do this a second time, as we are finding \n\t\t\tTestFillNEa (stopwatch2, eaVectorUint64.begin(), (int) eaVectorUint64.size(), UINT64_C(37)); // the results are inconsistent otherwise.\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"algorithm/fill_n/vector\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\t\t}\n\t}\n}\n\n\nvoid BenchmarkAlgorithm5(EASTLTest_Rand& /*rng*/, EA::StdC::Stopwatch& stopwatch1, EA::StdC::Stopwatch& stopwatch2)\n{\n\t{\n\t\tstd::vector stdVectorVoid(100000);\n\t\teastl::vector eaVectorVoid(100000);\n\n\t\tstd::vector stdVectorChar(100000);\n\t\teastl::vector eaVectorChar(100000);\n\n\t\tstd::vector stdVectorBool(100000);\n\t\teastl::vector eaVectorBool(100000);\n\n\t\tfor(int i = 0; i < 2; i++)\n\t\t{\n\t\t\tTestFillStd(stopwatch1, stdVectorVoid.begin(), stdVectorVoid.end(), (void*)NULL);\n\t\t\tTestFillEa (stopwatch2, eaVectorVoid.begin(), eaVectorVoid.end(), (void*)NULL);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"algorithm/fill/vector\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tTestFillStd(stopwatch1, &stdVectorChar[0], &stdVectorChar[0] + stdVectorChar.size(), 'd'); // Intentionally use ' ' and not casted to any type.\n\t\t\tTestFillEa (stopwatch2, eaVectorChar.data(), eaVectorChar.data() + eaVectorChar.size(), 'd');\n\t\t\tTestFillStd(stopwatch1, &stdVectorChar[0], &stdVectorChar[0] + stdVectorChar.size(), 'd'); // Intentionally do this a second time, as we are finding \n\t\t\tTestFillEa (stopwatch2, eaVectorChar.data(), eaVectorChar.data() + eaVectorChar.size(), 'd'); // the results are inconsistent otherwise.\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"algorithm/fill/char[]/'d'\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tTestFillStd(stopwatch1, stdVectorChar.begin(), stdVectorChar.end(), (char)'d'); \n\t\t\tTestFillEa (stopwatch2, eaVectorChar.begin(), eaVectorChar.end(), (char)'d');\n\t\t\tTestFillStd(stopwatch1, stdVectorChar.begin(), stdVectorChar.end(), (char)'d'); // Intentionally do this a second time, as we are finding \n\t\t\tTestFillEa (stopwatch2, eaVectorChar.begin(), eaVectorChar.end(), (char)'d'); // the results are inconsistent otherwise.\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"algorithm/fill/vector/'d'\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tTestFillStd(stopwatch1, stdVectorChar.begin(), stdVectorChar.end(), (char)0); \n\t\t\tTestFillEa (stopwatch2, eaVectorChar.begin(), eaVectorChar.end(), (char)0);\n\t\t\tTestFillStd(stopwatch1, stdVectorChar.begin(), stdVectorChar.end(), (char)0); // Intentionally do this a second time, as we are finding \n\t\t\tTestFillEa (stopwatch2, eaVectorChar.begin(), eaVectorChar.end(), (char)0); // the results are inconsistent otherwise.\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"algorithm/fill/vector/0\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tTestFillStd(stopwatch1, eaVectorBool.data(), eaVectorBool.data() + eaVectorBool.size(), false); // Intentionally use eaVectorBool for the array. \n\t\t\tTestFillEa (stopwatch2, eaVectorBool.data(), eaVectorBool.data() + eaVectorBool.size(), false);\n\t\t\tTestFillStd(stopwatch1, eaVectorBool.data(), eaVectorBool.data() + eaVectorBool.size(), false);\n\t\t\tTestFillEa (stopwatch2, eaVectorBool.data(), eaVectorBool.data() + eaVectorBool.size(), false);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"algorithm/fill/bool[]\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test fill_n\n\t\t\t///////////////////////////////\n\n\t\t\tTestFillNStd(stopwatch1, eaVectorChar.data(), (int) eaVectorChar.size(), 'd'); // Intentionally use eaVectorBool for the array.\n\t\t\tTestFillNEa (stopwatch2, eaVectorChar.data(), (int) eaVectorChar.size(), 'd');\n\t\t\tTestFillNStd(stopwatch1, eaVectorChar.data(), (int) eaVectorChar.size(), 'd'); // Intentionally do this a second time, as we are finding \n\t\t\tTestFillNEa (stopwatch2, eaVectorChar.data(), (int) eaVectorChar.size(), 'd'); // the results are inconsistent otherwise.\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"algorithm/fill_n/char[]\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tTestFillNStd(stopwatch1, eaVectorBool.data(), (int) eaVectorBool.size(), false); // Intentionally use eaVectorBool for the array.\n\t\t\tTestFillNEa (stopwatch2, eaVectorBool.data(), (int) eaVectorBool.size(), false);\n\t\t\tTestFillNStd(stopwatch1, eaVectorBool.data(), (int) eaVectorBool.size(), false); // Intentionally do this a second time, as we are finding \n\t\t\tTestFillNEa (stopwatch2, eaVectorBool.data(), (int) eaVectorBool.size(), false); // the results are inconsistent otherwise.\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"algorithm/fill_n/bool[]\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\t\t}\n\t}\n}\n\n\nvoid BenchmarkAlgorithm6(EASTLTest_Rand& /*rng*/, EA::StdC::Stopwatch& stopwatch1, EA::StdC::Stopwatch& stopwatch2)\n{\n\t// We allocate this on the heap because some platforms don't always have enough stack space for this.\n\tstd::vector* pstdVectorLP1 = new std::vector(100);\n\tstd::vector* pstdVectorLP2 = new std::vector(100);\n\teastl::vector* peaVectorLP1 = new eastl::vector(100);\n\teastl::vector* peaVectorLP2 = new eastl::vector(100);\n\n\t// Aliases.\n\tstd::vector& stdVectorLP1 = *pstdVectorLP1;\n\tstd::vector& stdVectorLP2 = *pstdVectorLP2;\n\teastl::vector& eaVectorLP1 = *peaVectorLP1;\n\teastl::vector& eaVectorLP2 = *peaVectorLP2;\n\n\tfor(int i = 0; i < 2; i++)\n\t{\n\t\t///////////////////////////////\n\t\t// Test copy\n\t\t///////////////////////////////\n\n\t\tTestCopyStd(stopwatch1, stdVectorLP1.begin(), stdVectorLP1.end(), stdVectorLP2.begin());\n\t\tTestCopyEa (stopwatch2, eaVectorLP1.begin(), eaVectorLP1.end(), eaVectorLP2.begin());\n\n\t\tif(i == 1)\n\t\t\tBenchmark::AddResult(\"algorithm/copy/vector\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t///////////////////////////////\n\t\t// Test copy_backward\n\t\t///////////////////////////////\n\n\t\tTestCopyBackwardStd(stopwatch1, stdVectorLP1.begin(), stdVectorLP1.end(), stdVectorLP2.end());\n\t\tTestCopyBackwardEa (stopwatch2, eaVectorLP1.begin(), eaVectorLP1.end(), eaVectorLP2.end());\n\n\t\tif(i == 1)\n\t\t\tBenchmark::AddResult(\"algorithm/copy_backward/vector\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\t}\n\n\tdelete pstdVectorLP1;\n\tdelete pstdVectorLP2;\n\tdelete peaVectorLP1;\n\tdelete peaVectorLP2;\n}\n\n\nvoid BenchmarkAlgorithm7(EASTLTest_Rand& /*rng*/, EA::StdC::Stopwatch& stopwatch1, EA::StdC::Stopwatch& stopwatch2)\n{\n\t{\n\t\tstd::list stdListTO(10000);\n\t\teastl::list eaListTO(10000);\n\n\t\tstd::vector stdVectorTO(10000);\n\t\teastl::vector eaVectorTO(10000);\n\n\t\tfor(int i = 0; i < 2; i++)\n\t\t{\n\t\t\t///////////////////////////////\n\t\t\t// Test reverse\n\t\t\t///////////////////////////////\n\n\t\t\tTestReverseStd(stopwatch1, stdListTO.begin(), stdListTO.end());\n\t\t\tTestReverseEa (stopwatch2, eaListTO.begin(), eaListTO.end());\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"algorithm/reverse/list\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tTestReverseStd(stopwatch1, stdVectorTO.begin(), stdVectorTO.end());\n\t\t\tTestReverseEa (stopwatch2, eaVectorTO.begin(), eaVectorTO.end());\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"algorithm/reverse/vector\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\t\t}\n\t}\n\n\t{\n\t\t// Create some containers and seed them with incremental values (i.e. 0, 1, 2, 3...).\n\t\teastl::slist eaSlistIntLarge(10000);\n\t\teastl::generate(eaSlistIntLarge.begin(), eaSlistIntLarge.end(), GenerateIncrementalIntegers());\n\n\n\t\tstd::vector< SizedPOD<32> > stdVectorLargePod32(10000);\n\t\tfor(std::vector< SizedPOD<32> >::iterator it = stdVectorLargePod32.begin(); it != stdVectorLargePod32.end(); ++it)\n\t\t\tmemset(&*it, 0, sizeof(SizedPOD<32>));\n\t\teastl::vector< SizedPOD<32> > eaVectorLargePod32(10000);\n\t\tfor(eastl::vector< SizedPOD<32> >::iterator it = eaVectorLargePod32.begin(); it != eaVectorLargePod32.end(); ++it)\n\t\t\tmemset(&*it, 0, sizeof(SizedPOD<32>));\n\n\t\tstd::list stdListIntLarge(10000);\n\t\teastl::generate(stdListIntLarge.begin(), stdListIntLarge.end(), GenerateIncrementalIntegers());\n\n\t\teastl::list eaListIntLarge(10000);\n\t\teastl::generate(eaListIntLarge.begin(), eaListIntLarge.end(), GenerateIncrementalIntegers());\n\n\n\t\tstd::vector stdVectorIntLarge(10000);\n\t\teastl::generate(stdVectorIntLarge.begin(), stdVectorIntLarge.end(), GenerateIncrementalIntegers());\n\n\t\teastl::vector eaVectorIntLarge(10000);\n\t\teastl::generate(eaVectorIntLarge.begin(), eaVectorIntLarge.end(), GenerateIncrementalIntegers());\n\n\n\t\tstd::list stdListIntSmall(10);\n\t\teastl::generate(stdListIntLarge.begin(), stdListIntLarge.end(), GenerateIncrementalIntegers());\n\n\t\teastl::list eaListIntSmall(10);\n\t\teastl::generate(eaListIntLarge.begin(), eaListIntLarge.end(), GenerateIncrementalIntegers());\n\n\n\t\tstd::vector stdVectorIntSmall(10);\n\t\teastl::generate(stdVectorIntLarge.begin(), stdVectorIntLarge.end(), GenerateIncrementalIntegers());\n\n\t\teastl::vector eaVectorIntSmall(10);\n\t\teastl::generate(eaVectorIntLarge.begin(), eaVectorIntLarge.end(), GenerateIncrementalIntegers());\n\n\n\n\t\tstd::list stdListTOLarge(10000);\n\t\teastl::generate(stdListTOLarge.begin(), stdListTOLarge.end(), GenerateIncrementalIntegers());\n\n\t\teastl::list eaListTOLarge(10000);\n\t\teastl::generate(eaListTOLarge.begin(), eaListTOLarge.end(), GenerateIncrementalIntegers());\n\n\n\t\tstd::vector stdVectorTOLarge(10000);\n\t\teastl::generate(stdVectorTOLarge.begin(), stdVectorTOLarge.end(), GenerateIncrementalIntegers());\n\n\t\teastl::vector eaVectorTOLarge(10000);\n\t\teastl::generate(eaVectorTOLarge.begin(), eaVectorTOLarge.end(), GenerateIncrementalIntegers());\n\n\n\t\tstd::list stdListTOSmall(10);\n\t\teastl::generate(stdListTOSmall.begin(), stdListTOSmall.end(), GenerateIncrementalIntegers());\n\n\t\teastl::list eaListTOSmall(10);\n\t\teastl::generate(eaListTOSmall.begin(), eaListTOSmall.end(), GenerateIncrementalIntegers());\n\n\n\t\tstd::vector stdVectorTOSmall(10);\n\t\teastl::generate(stdVectorTOSmall.begin(), stdVectorTOSmall.end(), GenerateIncrementalIntegers());\n\n\t\teastl::vector eaVectorTOSmall(10);\n\t\teastl::generate(eaVectorTOSmall.begin(), eaVectorTOSmall.end(), GenerateIncrementalIntegers());\n\t\t\n\n\t\tfor(int i = 0; i < 2; i++)\n\t\t{\n\t\t\t///////////////////////////////\n\t\t\t// Test reverse\n\t\t\t///////////////////////////////\n\n\t\t\t// There is no guaranteed Standard Library forward_list or slist.\n\t\t\tTestRotateEa (stopwatch2, eaSlistIntLarge.begin(), eastl::next( eaSlistIntLarge.begin(), (eaSlistIntLarge.size() / 2) - 1), eaSlistIntLarge.end());\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"algorithm/rotate/slist large\", stopwatch1.GetUnits(), 0 /* untested */, stopwatch2.GetElapsedTime());\n\n\n\n\t\t\tTestRotateStd(stopwatch1, stdVectorLargePod32.begin(), std__::next(stdVectorLargePod32.begin(), (stdVectorLargePod32.size() / 2) - 1), stdVectorLargePod32.end());\n\t\t\tTestRotateEa (stopwatch2, eaVectorLargePod32.begin(), eastl::next( eaVectorLargePod32.begin(), (eaVectorLargePod32.size() / 2) - 1), eaVectorLargePod32.end());\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"algorithm/rotate/vector> large\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\n\n\t\t\tTestRotateStd(stopwatch1, stdListIntLarge.begin(), std__::next(stdListIntLarge.begin(), (stdListIntLarge.size() / 2) - 1), stdListIntLarge.end());\n\t\t\tTestRotateEa (stopwatch2, eaListIntLarge.begin(), eastl::next( eaListIntLarge.begin(), (eaListIntLarge.size() / 2) - 1), eaListIntLarge.end());\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"algorithm/rotate/list large\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tTestRotateStd(stopwatch1, stdVectorIntLarge.begin(), std__::next(stdVectorIntLarge.begin(), (stdVectorIntLarge.size() / 2) - 1), stdVectorIntLarge.end());\n\t\t\tTestRotateEa (stopwatch2, eaVectorIntLarge.begin(), eastl::next( eaVectorIntLarge.begin(), (eaVectorIntLarge.size() / 2) - 1), eaVectorIntLarge.end());\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"algorithm/rotate/vector\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\n\t\t\tTestRotateStd(stopwatch1, stdListIntSmall.begin(), std__::next(stdListIntSmall.begin(), (stdListIntSmall.size() / 2) - 1), stdListIntSmall.end());\n\t\t\tTestRotateEa (stopwatch2, eaListIntSmall.begin(), eastl::next( eaListIntSmall.begin(), (eaListIntSmall.size() / 2) - 1), eaListIntSmall.end());\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"algorithm/rotate/list small\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tTestRotateStd(stopwatch1, stdVectorIntSmall.begin(), std__::next(stdVectorIntSmall.begin(), (stdVectorIntSmall.size() / 2) - 1), stdVectorIntSmall.end());\n\t\t\tTestRotateEa (stopwatch2, eaVectorIntSmall.begin(), eastl::next( eaVectorIntSmall.begin(), (eaVectorIntSmall.size() / 2) - 1), eaVectorIntSmall.end());\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"algorithm/rotate/vector\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\n\t\t\tTestRotateStd(stopwatch1, stdListTOLarge.begin(), std__::next(stdListTOLarge.begin(), (stdListTOLarge.size() / 2) - 1), stdListTOLarge.end());\n\t\t\tTestRotateEa (stopwatch2, eaListTOLarge.begin(), eastl::next( eaListTOLarge.begin(), (eaListTOLarge.size() / 2) - 1), eaListTOLarge.end());\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"algorithm/rotate/list\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tTestRotateStd(stopwatch1, stdVectorTOLarge.begin(), std__::next(stdVectorTOLarge.begin(), (stdVectorTOLarge.size() / 2) - 1), stdVectorTOLarge.end());\n\t\t\tTestRotateEa (stopwatch2, eaVectorTOLarge.begin(), eastl::next( eaVectorTOLarge.begin(), (eaVectorTOLarge.size() / 2) - 1), eaVectorTOLarge.end());\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"algorithm/rotate/vector\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\n\t\t\tTestRotateStd(stopwatch1, stdListTOSmall.begin(), std__::next(stdListTOSmall.begin(), (stdListTOSmall.size() / 2) - 1), stdListTOSmall.end());\n\t\t\tTestRotateEa (stopwatch2, eaListTOSmall.begin(), eastl::next( eaListTOSmall.begin(), (eaListTOSmall.size() / 2) - 1), eaListTOSmall.end());\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"algorithm/rotate/list\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tTestRotateStd(stopwatch1, stdVectorTOSmall.begin(), std__::next(stdVectorTOSmall.begin(), (stdVectorTOSmall.size() / 2) - 1), stdVectorTOSmall.end());\n\t\t\tTestRotateEa (stopwatch2, eaVectorTOSmall.begin(), eastl::next( eaVectorTOSmall.begin(), (eaVectorTOSmall.size() / 2) - 1), eaVectorTOSmall.end());\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"algorithm/rotate/vector\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\t\t}\n\t}\n}\n\nvoid BenchmarkAlgorithm8(EASTLTest_Rand& rng, EA::StdC::Stopwatch& stopwatch1, EA::StdC::Stopwatch& stopwatch2)\n{\n\tconst uint32_t ElementCount = 10000;\n\n\teastl::vector srcVecA(ElementCount);\n\teastl::vector srcVecB(ElementCount);\n\n\tstd::vector stdVecAInt(ElementCount);\n\tstd::vector stdVecBInt(ElementCount);\n\tstd::vector stdVecOutInt(2 * ElementCount);\n\tstd::vector stdVecATestObject(ElementCount);\n\tstd::vector stdVecBTestObject(ElementCount);\n\tstd::vector stdVecOutTestObject(2 * ElementCount);\n\n\teastl::vector eaVecAInt(ElementCount);\n\teastl::vector eaVecBInt(ElementCount);\n\teastl::vector eaVecOutInt(2 * ElementCount);\n\teastl::vector eaVecATestObject(ElementCount);\n\teastl::vector eaVecBTestObject(ElementCount);\n\teastl::vector eaVecOutTestObject(2 * ElementCount);\n\n\t// Note:\n\t// In some cases the compiler may generate branch free code for the loop body of merge.\n\t// In this situation the performance of merging data that has a random merge selection (i.e. the chance that the smallest\n\t// element is taken from the first or second list is essentially random) is the same as merging data where the choice of\n\t// which list has the smallest element is predictable.\n\t// However, if the compiler doesn't generate branch free code, then the performance of merge will suffer from branch\n\t// misprediction when merging random data and will benefit greatly when misprediction is rare.\n\t// This benchmark is aimed at highlighting what sort of code is being generated, and also showing the impact of\n\t// predictability of the comparisons performed during merge. The branch predictablity /can/ have a large impact\n\t// on merge sort performance.\n\n\t// 'unpred' is the case where the comparison is unpredictable\n\t// 'pred' is the case where the comparison is mostly predictable\n\tconst char* patternDescriptions[][2] =\n\t{\n\t\t{\n\t\t\t\"algorithm/merge/vector (unpred)\",\n\t\t\t\"algorithm/merge/vector (pred)\",\n\t\t},\n\t\t{\n\t\t\t\"algorithm/merge/vector (unpred)\",\n\t\t\t\"algorithm/merge/vector (pred)\",\n\t\t},\n\t};\n\n\tenum Pattern\n\t{\n\t\tP_Random,\n\t\tP_Predictable,\n\t\tP_Count\n\t};\n\n\tfor (int pattern = 0; pattern < P_Count; pattern++)\n\t{\n\t\tif (pattern == P_Random)\n\t\t{\n\t\t\teastl::generate(srcVecA.begin(), srcVecA.end(), [&]{ return int(rng()); });\n\t\t\teastl::sort(srcVecA.begin(), srcVecA.end());\n\t\t\teastl::generate(srcVecB.begin(), srcVecB.end(), [&] { return int(rng()); });\n\t\t\teastl::sort(srcVecB.begin(), srcVecB.end());\n\t\t}\n\t\telse if (pattern == P_Predictable)\n\t\t{\n\t\t\t// The data pattern means that a simple/naive algorithm will select 'runLen' values\n\t\t\t// from one list, and then 'runLen' values from the other list (alternating back and forth).\n\t\t\t// Of course, a merge algorithm that is more complicated might have a different order of\n\t\t\t// comparison.\n\t\t\tconst int runLen = 32;\n\t\t\tfor (int i = 0; i < ElementCount; i++)\n\t\t\t{\n\t\t\t\tint baseValue = ((i / runLen) * 2 * runLen) + (i % (runLen));\n\t\t\t\tsrcVecA[i] = baseValue;\n\t\t\t\tsrcVecB[i] = baseValue + runLen;\n\t\t\t}\n\t\t}\n\n\t\t///////////////////////////////\n\t\t// Test merge\n\t\t///////////////////////////////\n\t\tfor (int i = 0; i < 2; i++)\n\t\t{\n\t\t\teastl::copy(srcVecA.begin(), srcVecA.end(), stdVecAInt.begin());\n\t\t\teastl::copy(srcVecB.begin(), srcVecB.end(), stdVecBInt.begin());\n\t\t\teastl::copy(srcVecA.begin(), srcVecA.end(), eaVecAInt.begin());\n\t\t\teastl::copy(srcVecB.begin(), srcVecB.end(), eaVecBInt.begin());\n\t\t\tTestMergeStd(stopwatch1, stdVecAInt.begin(), stdVecAInt.end(), stdVecBInt.begin(), stdVecBInt.end(), stdVecOutInt.begin());\n\t\t\tTestMergeEa(stopwatch2, eaVecAInt.begin(), eaVecAInt.end(), eaVecBInt.begin(), eaVecBInt.end(), eaVecOutInt.begin());\n\n\t\t\tif (i == 1)\n\t\t\t{\n\t\t\t\tBenchmark::AddResult(patternDescriptions[0][pattern], stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\t\t\t}\n\n\t\t\tfor (int j = 0; j < ElementCount; j++)\n\t\t\t{\n\t\t\t\tstdVecATestObject[j] = TestObject(srcVecA[j]);\n\t\t\t\tstdVecBTestObject[j] = TestObject(srcVecB[j]);\n\t\t\t\teaVecATestObject[j] = TestObject(srcVecA[j]);\n\t\t\t\teaVecBTestObject[j] = TestObject(srcVecB[j]);\n\t\t\t}\n\t\t\tTestMergeStd(stopwatch1, stdVecATestObject.begin(), stdVecATestObject.end(), stdVecBTestObject.begin(), stdVecBTestObject.end(), stdVecOutTestObject.begin());\n\t\t\tTestMergeEa(stopwatch2, eaVecATestObject.begin(), eaVecATestObject.end(), eaVecBTestObject.begin(), eaVecBTestObject.end(), eaVecOutTestObject.begin());\n\n\t\t\tif (i == 1)\n\t\t\t{\n\t\t\t\tBenchmark::AddResult(patternDescriptions[1][pattern], stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\t\t\t}\n\t\t}\n\t}\n\n}\n\n\n\nvoid BenchmarkAlgorithm()\n{\n\tEASTLTest_Printf(\"Algorithm\\n\");\n\n\tEASTLTest_Rand rng(EA::UnitTest::GetRandSeed());\n\tEA::StdC::Stopwatch stopwatch1(EA::StdC::Stopwatch::kUnitsCPUCycles);\n\tEA::StdC::Stopwatch stopwatch2(EA::StdC::Stopwatch::kUnitsCPUCycles);\n\n\tBenchmarkAlgorithm1(rng, stopwatch1, stopwatch2);\n\tBenchmarkAlgorithm2(rng, stopwatch1, stopwatch2);\n\tBenchmarkAlgorithm3(rng, stopwatch1, stopwatch2);\n\tBenchmarkAlgorithm4(rng, stopwatch1, stopwatch2);\n\tBenchmarkAlgorithm5(rng, stopwatch1, stopwatch2);\n\tBenchmarkAlgorithm6(rng, stopwatch1, stopwatch2);\n\tBenchmarkAlgorithm7(rng, stopwatch1, stopwatch2);\n\tBenchmarkAlgorithm8(rng, stopwatch1, stopwatch2);\n}\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n" }, { "path": "benchmark/source/BenchmarkBitset.cpp", "content": "/////////////////////////////////////////////////////////////////////////////\n// Copyright (c) Electronic Arts Inc. All rights reserved.\n/////////////////////////////////////////////////////////////////////////////\n\n\n#ifdef _MSC_VER\n\t// Microsoft STL generates warnings.\n\t#pragma warning(disable: 4267) // 'initializing' : conversion from 'size_t' to 'const int', possible loss of data\n#endif\n\n#include \"EASTLBenchmark.h\"\n#include \"EASTLTest.h\"\n#include \n#include \n\n\nEA_DISABLE_ALL_VC_WARNINGS()\n#include \nEA_RESTORE_ALL_VC_WARNINGS()\n\n\nusing namespace EA;\n\n\nnamespace\n{\n\ttemplate \n\tvoid TestSet(EA::StdC::Stopwatch& stopwatch, Bitset& b)\n\t{\n\t\tstopwatch.Restart();\n\t\tfor(int i = 0; i < 100000; i++)\n\t\t{\n\t\t\tb.set();\n\t\t\tBenchmark::DoNothing(&b);\n\t\t}\n\t\tstopwatch.Stop();\n\t}\n\n\n\ttemplate \n\tvoid TestSetIndex(EA::StdC::Stopwatch& stopwatch, Bitset& b, size_t index)\n\t{\n\t\tstopwatch.Restart();\n\t\tfor(int i = 0; i < 100000; i++)\n\t\t{\n\t\t\tb.set(index);\n\t\t\tBenchmark::DoNothing(&b);\n\t\t}\n\t\tstopwatch.Stop();\n\t}\n\n\n\ttemplate \n\tvoid TestReset(EA::StdC::Stopwatch& stopwatch, Bitset& b)\n\t{\n\t\tstopwatch.Restart();\n\t\tfor(int i = 0; i < 100000; i++)\n\t\t{\n\t\t\tb.reset();\n\t\t\tBenchmark::DoNothing(&b);\n\t\t}\n\t\tstopwatch.Stop();\n\t}\n\n\n\ttemplate \n\tvoid TestFlip(EA::StdC::Stopwatch& stopwatch, Bitset& b)\n\t{\n\t\tstopwatch.Restart();\n\t\tfor(int i = 0; i < 100000; i++)\n\t\t{\n\t\t\tb.flip();\n\t\t\tBenchmark::DoNothing(&b);\n\t\t}\n\t\tstopwatch.Stop();\n\t}\n\n\n\ttemplate \n\tvoid TestTest(EA::StdC::Stopwatch& stopwatch, Bitset& b, unsigned nANDValue)\n\t{\n\t\tstopwatch.Restart();\n\t\tfor(unsigned i = 0; i < 100000; i++)\n\t\t\tBenchmark::DoNothing(b.test(i & nANDValue)); // We use & instead of % because the former is always fast due to forced power of 2.\n\t\tstopwatch.Stop();\n\t}\n\n\n\ttemplate \n\tvoid TestCount(EA::StdC::Stopwatch& stopwatch, Bitset& b)\n\t{\n\t\tsize_t temp = 0;\n\t\tstopwatch.Restart();\n\t\tfor(int i = 0; i < 100000; i++)\n\t\t{\n\t\t\ttemp += b.count();\n\t\t\tBenchmark::DoNothing(&temp);\n\t\t}\n\t\tstopwatch.Stop();\n\t}\n\n\n\ttemplate \n\tvoid TestRightShift(EA::StdC::Stopwatch& stopwatch, Bitset& b, size_t n)\n\t{\n\t\tsize_t temp = 0;\n\t\tstopwatch.Restart();\n\t\tfor(int i = 0; i < 100000; i++)\n\t\t{\n\t\t\tb >>= n;\n\t\t\tBenchmark::DoNothing(&temp);\n\t\t}\n\t\tstopwatch.Stop();\n\t}\n\n} // namespace\n\n\n\nvoid BenchmarkBitset()\n{\n\tEASTLTest_Printf(\"Bitset\\n\");\n\n\tEA::StdC::Stopwatch stopwatch1(EA::StdC::Stopwatch::kUnitsCPUCycles);\n\tEA::StdC::Stopwatch stopwatch2(EA::StdC::Stopwatch::kUnitsCPUCycles);\n\n\t{\n\t\tstd::bitset<15> stdBitset15;\n\t\teastl::bitset<15> eaBitset15;\n\n\t\tstd::bitset<35> stdBitset35;\n\t\teastl::bitset<35> eaBitset35;\n\n\t\tstd::bitset<75> stdBitset75;\n\t\teastl::bitset<75> eaBitset75;\n\n\t\tstd::bitset<1500> stdBitset1500;\n\t\teastl::bitset<1500> eaBitset1500;\n\n\n\t\tfor(int i = 0; i < 2; i++)\n\t\t{\n\t\t\t///////////////////////////////\n\t\t\t// Test set()\n\t\t\t///////////////////////////////\n\n\t\t\tTestSet(stopwatch1, stdBitset15);\n\t\t\tTestSet(stopwatch2, eaBitset15);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"bitset<15>/set()\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tTestSet(stopwatch1, stdBitset35);\n\t\t\tTestSet(stopwatch2, eaBitset35);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"bitset<35>/set()\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tTestSet(stopwatch1, stdBitset75);\n\t\t\tTestSet(stopwatch2, eaBitset75);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"bitset<75>/set()\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tTestSet(stopwatch1, stdBitset1500);\n\t\t\tTestSet(stopwatch2, eaBitset1500);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"bitset<1500>/set()\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test set(index)\n\t\t\t///////////////////////////////\n\n\t\t\tTestSetIndex(stopwatch1, stdBitset15, 13);\n\t\t\tTestSetIndex(stopwatch2, eaBitset15, 13);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"bitset<15>/set(i)\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tTestSetIndex(stopwatch1, stdBitset35, 33);\n\t\t\tTestSetIndex(stopwatch2, eaBitset35, 33);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"bitset<35>/set(i)\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tTestSetIndex(stopwatch1, stdBitset75, 73);\n\t\t\tTestSetIndex(stopwatch2, eaBitset75, 73);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"bitset<75>/set(i)\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tTestSetIndex(stopwatch1, stdBitset1500, 730);\n\t\t\tTestSetIndex(stopwatch2, eaBitset1500, 730);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"bitset<1500>/set(i)\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test reset()\n\t\t\t///////////////////////////////\n\n\t\t\tTestReset(stopwatch1, stdBitset15);\n\t\t\tTestReset(stopwatch2, eaBitset15);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"bitset<15>/reset\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tTestReset(stopwatch1, stdBitset35);\n\t\t\tTestReset(stopwatch2, eaBitset35);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"bitset<35>/reset\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tTestReset(stopwatch1, stdBitset75);\n\t\t\tTestReset(stopwatch2, eaBitset75);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"bitset<75>/reset\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tTestReset(stopwatch1, stdBitset1500);\n\t\t\tTestReset(stopwatch2, eaBitset1500);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"bitset<1500>/reset\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test flip\n\t\t\t///////////////////////////////\n\n\t\t\tTestFlip(stopwatch1, stdBitset15);\n\t\t\tTestFlip(stopwatch2, eaBitset15);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"bitset<15>/flip\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tTestFlip(stopwatch1, stdBitset35);\n\t\t\tTestFlip(stopwatch2, eaBitset35);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"bitset<35>/flip\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tTestFlip(stopwatch1, stdBitset75);\n\t\t\tTestFlip(stopwatch2, eaBitset75);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"bitset<75>/flip\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tTestFlip(stopwatch1, stdBitset1500);\n\t\t\tTestFlip(stopwatch2, eaBitset1500);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"bitset<1500>/flip\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test test\n\t\t\t///////////////////////////////\n\n\t\t\tTestTest(stopwatch1, stdBitset15, 7);\n\t\t\tTestTest(stopwatch2, eaBitset15, 7);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"bitset<15>/test\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tTestTest(stopwatch1, stdBitset35, 31);\n\t\t\tTestTest(stopwatch2, eaBitset35, 31);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"bitset<35>/test\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tTestTest(stopwatch1, stdBitset75, 63);\n\t\t\tTestTest(stopwatch2, eaBitset75, 63);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"bitset<75>/test\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tTestTest(stopwatch1, stdBitset1500, 1023);\n\t\t\tTestTest(stopwatch2, eaBitset1500, 1023);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"bitset<1500>/test\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test count\n\t\t\t///////////////////////////////\n\n\t\t\tTestCount(stopwatch1, stdBitset15);\n\t\t\tTestCount(stopwatch2, eaBitset15);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"bitset<15>/count\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tTestCount(stopwatch1, stdBitset35);\n\t\t\tTestCount(stopwatch2, eaBitset35);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"bitset<35>/count\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tTestCount(stopwatch1, stdBitset75);\n\t\t\tTestCount(stopwatch2, eaBitset75);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"bitset<75>/count\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tTestCount(stopwatch1, stdBitset1500);\n\t\t\tTestCount(stopwatch2, eaBitset1500);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"bitset<1500>/count\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test >>=\n\t\t\t///////////////////////////////\n\n\t\t\tTestRightShift(stopwatch1, stdBitset15, 1);\n\t\t\tTestRightShift(stopwatch2, eaBitset15, 1);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"bitset<15>/>>=/1\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime(),\n\t\t\t\t\t\t\t\t\t\tGetStdSTLType() == kSTLPort ? \"STLPort is broken, neglects wraparound check.\" : NULL);\n\n\t\t\tTestRightShift(stopwatch1, stdBitset35, 1);\n\t\t\tTestRightShift(stopwatch2, eaBitset35, 1);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"bitset<35>/>>=/1\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime(),\n\t\t\t\t\t\t\t\t\t\tGetStdSTLType() == kSTLPort ? \"STLPort is broken, neglects wraparound check.\" : NULL);\n\n\t\t\tTestRightShift(stopwatch1, stdBitset75, 1);\n\t\t\tTestRightShift(stopwatch2, eaBitset75, 1);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"bitset<75>/>>=/1\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime(),\n\t\t\t\t\t\t\t\t\t\tGetStdSTLType() == kSTLPort ? \"STLPort is broken, neglects wraparound check.\" : NULL);\n\n\t\t\tTestRightShift(stopwatch1, stdBitset1500, 1);\n\t\t\tTestRightShift(stopwatch2, eaBitset1500, 1);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"bitset<1500>/>>=/1\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime(),\n\t\t\t\t\t\t\t\t\t\tGetStdSTLType() == kSTLPort ? \"STLPort is broken, neglects wraparound check.\" : NULL);\n\t\t}\n\t}\n}\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n" }, { "path": "benchmark/source/BenchmarkDeque.cpp", "content": "/////////////////////////////////////////////////////////////////////////////\n// Copyright (c) Electronic Arts Inc. All rights reserved.\n/////////////////////////////////////////////////////////////////////////////\n\n\n#include \"EASTLBenchmark.h\"\n#include \"EASTLTest.h\"\n#include \n#include \n#include \n#include \n#include \n\n#ifdef _MSC_VER\n\t#pragma warning(push, 0)\n\t#pragma warning(disable: 4350) // behavior change: X called instead of Y\n#endif\n#include \n#include \n#include \n#include \n#include \n#ifdef _MSC_VER\n\t#pragma warning(pop)\n#endif\n\n\nusing namespace EA;\n\n\nnamespace\n{\n\tstruct ValuePair\n\t{\n\t\tuint32_t key;\n\t\tuint32_t v;\n\t};\n\n\tstruct VPCompare\n\t{\n\t\tbool operator()(const ValuePair& vp1, const ValuePair& vp2) const\n\t\t{\n\t\t\treturn (vp1.key == vp2.key) ? (vp1.v < vp2.v) : (vp1.key < vp2.key);\n\t\t}\n\t};\n\n\tbool operator<(const ValuePair& vp1, const ValuePair& vp2)\n\t{\n\t\treturn (vp1.key == vp2.key) ? (vp1.v < vp2.v) : (vp1.key < vp2.key);\n\t}\n\n\tbool operator==(const ValuePair& vp1, const ValuePair& vp2)\n\t{\n\t\treturn (vp1.key == vp2.key) && (vp1.v == vp2.v);\n\t}\n}\n\n\ntypedef std::deque StdDeque;\ntypedef eastl::deque EaDeque; // What value do we pick for the subarray size to make the comparison fair? Using the default isn't ideal because it results in this test measuring speed efficiency and ignoring memory efficiency. \n\n\n\nnamespace\n{\n\ttemplate \n\tvoid TestPushBack(EA::StdC::Stopwatch& stopwatch, Container& c, eastl::vector& intVector)\n\t{\n\t\tstopwatch.Restart();\n\t\tfor(eastl_size_t j = 0, jEnd = intVector.size(); j < jEnd; j++)\n\t\t{\n\t\t\tconst ValuePair vp = { intVector[j], intVector[j] };\n\t\t\tc.push_back(vp);\n\t\t}\n\t\tstopwatch.Stop();\n\t}\n\n\n\ttemplate \n\tvoid TestPushFront(EA::StdC::Stopwatch& stopwatch, Container& c, eastl::vector& intVector)\n\t{\n\t\tstopwatch.Restart();\n\t\tfor(eastl_size_t j = 0, jEnd = intVector.size(); j < jEnd; j++)\n\t\t{\n\t\t\tconst ValuePair vp = { intVector[j], intVector[j] };\n\t\t\tc.push_front(vp);\n\t\t}\n\t\tstopwatch.Stop();\n\t}\n\n\n\ttemplate \n\tvoid TestBracket(EA::StdC::Stopwatch& stopwatch, Container& c)\n\t{\n\t\tuint64_t temp = 0;\n\t\tstopwatch.Restart();\n\t\tfor(typename Container::size_type j = 0, jEnd = c.size(); j < jEnd; j++)\n\t\t\ttemp += c[j].key;\n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%u\", (unsigned)(temp & 0xffffffff));\n\t}\n\n\n\ttemplate \n\tvoid TestIteration(EA::StdC::Stopwatch& stopwatch, Container& c)\n\t{\n\t\ttypename Container::iterator it = c.begin(), itEnd = c.end();\n\t\tstopwatch.Restart();\n\t\twhile(it != itEnd)\n\t\t\t++it;\n\t\tstopwatch.Stop();\n\t\tif(it != c.end())\n\t\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%u\", (unsigned)(*it).key);\n\n\t\t/* Alternative way to measure:\n\t\tconst eastl_size_t n = c.size();\n\t\tstopwatch.Restart();\n\t\tfor(eastl_size_t i = 0; i < n; ++i)\n\t\t\t++it;\n\t\tstopwatch.Stop();\n\t\tif(it != c.end())\n\t\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%u\", (unsigned)(*it).key);\n\t\t*/\n\t}\n\n\n\ttemplate \n\tvoid TestFind(EA::StdC::Stopwatch& stopwatch, Container& c)\n\t{\n\t\t// Intentionally use eastl find in order to measure just \n\t\t// vector access speed and not be polluted by sort speed.\n\t\tconst ValuePair vp = { 0xffffffff, 0 };\n\t\tstopwatch.Restart();\n\t\ttypename Container::iterator it = eastl::find(c.begin(), c.end(), vp);\n\t\tstopwatch.Stop();\n\t\tif(it != c.end())\n\t\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%u\", (unsigned)(*it).key);\n\t}\n\n\n\ttemplate \n\tvoid TestSort(EA::StdC::Stopwatch& stopwatch, Container& c)\n\t{\n\t\t// Intentionally use eastl sort in order to measure just \n\t\t// vector access speed and not be polluted by sort speed.\n\t\tVPCompare vpCompare;\n\t\tstopwatch.Restart();\n\t\teastl::quick_sort(c.begin(), c.end(), vpCompare);\n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%u\", (unsigned)c[0].key);\n\t}\n\n\n\ttemplate \n\tvoid TestInsert(EA::StdC::Stopwatch& stopwatch, Container& c)\n\t{\n\t\tconst ValuePair vp = { 0xffffffff, 0 };\n\t\ttypename Container::size_type j, jEnd;\n\t\ttypename Container::iterator it;\n\n\t\tstopwatch.Restart();\n\t\tfor(j = 0, jEnd = 2000, it = c.begin(); j < jEnd; ++j)\n\t\t{\n\t\t\tit = c.insert(it, vp);\n\n\t\t\tif(it == c.end()) // Try to safely increment the iterator three times.\n\t\t\t\tit = c.begin();\n\t\t\tif(++it == c.end())\n\t\t\t\tit = c.begin();\n\t\t\tif(++it == c.end())\n\t\t\t\tit = c.begin();\n\t\t}\n\t\tstopwatch.Stop();\n\t}\n\n\n\ttemplate \n\tvoid TestErase(EA::StdC::Stopwatch& stopwatch, Container& c)\n\t{\n\t\ttypename Container::size_type j, jEnd;\n\t\ttypename Container::iterator it;\n\n\t\tstopwatch.Restart();\n\t\tfor(j = 0, jEnd = 2000, it = c.begin(); j < jEnd; ++j)\n\t\t{\n\t\t\tit = c.erase(it);\n\n\t\t\tif(it == c.end()) // Try to safely increment the iterator three times.\n\t\t\t\tit = c.begin();\n\t\t\tif(++it == c.end())\n\t\t\t\tit = c.begin();\n\t\t\tif(++it == c.end())\n\t\t\t\tit = c.begin();\n\t\t}\n\t\tstopwatch.Stop();\n\t}\n\n} // namespace\n\n\n\nvoid BenchmarkDeque()\n{\n\tEASTLTest_Printf(\"Deque\\n\");\n\n\tEA::UnitTest::RandGenT rng(EA::UnitTest::GetRandSeed());\n\tEA::StdC::Stopwatch stopwatch1(EA::StdC::Stopwatch::kUnitsCPUCycles);\n\tEA::StdC::Stopwatch stopwatch2(EA::StdC::Stopwatch::kUnitsCPUCycles);\n\n\t{ // Exercise some declarations\n\t\tint nErrorCount = 0;\n\t\tValuePair vp1 = { 0, 0 }, vp2 = { 0, 0 };\n\t\tVPCompare c1, c2;\n\n\t\tVERIFY(c1.operator()(vp1, vp2) == c2.operator()(vp1, vp2));\n\t\tVERIFY((vp1 < vp2) || (vp1 == vp2) || !(vp1 == vp2));\n\t}\n\n\t{\n\t\teastl::vector intVector(100000);\n\t\teastl::generate(intVector.begin(), intVector.end(), rng);\n\n\t\tfor(int i = 0; i < 2; i++)\n\t\t{\n\t\t\tStdDeque stdDeque;\n\t\t\tEaDeque eaDeque;\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test push_back\n\t\t\t///////////////////////////////\n\n\t\t\tTestPushBack(stopwatch1, stdDeque, intVector);\n\t\t\tTestPushBack(stopwatch2, eaDeque, intVector);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"deque/push_back\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test push_front\n\t\t\t///////////////////////////////\n\n\t\t\tTestPushFront(stopwatch1, stdDeque, intVector);\n\t\t\tTestPushFront(stopwatch2, eaDeque, intVector);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"deque/push_front\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test operator[]\n\t\t\t///////////////////////////////\n\n\t\t\tTestBracket(stopwatch1, stdDeque);\n\t\t\tTestBracket(stopwatch2, eaDeque);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"deque/operator[]\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test iteration\n\t\t\t///////////////////////////////\n\n\t\t\tTestIteration(stopwatch1, stdDeque);\n\t\t\tTestIteration(stopwatch2, eaDeque);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"deque/iteration\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test find()\n\t\t\t///////////////////////////////\n\n\t\t\tTestFind(stopwatch1, stdDeque);\n\t\t\tTestFind(stopwatch2, eaDeque);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"deque/find\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test sort\n\t\t\t///////////////////////////////\n\n\t\t\t// Currently VC++ complains about our sort function decrementing std::iterator that is already at begin(). In the strictest sense,\n\t\t\t// that's a valid complaint, but we aren't testing std STL here. We will want to revise our sort function eventually.\n\t\t\t#if !defined(_MSC_VER) || !defined(_ITERATOR_DEBUG_LEVEL) || (_ITERATOR_DEBUG_LEVEL < 2)\n\t\t\t\tTestSort(stopwatch1, stdDeque);\n\t\t\t\tTestSort(stopwatch2, eaDeque);\n\n\t\t\t\tif(i == 1)\n\t\t\t\t\tBenchmark::AddResult(\"deque/sort\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\t\t\t#endif\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test insert\n\t\t\t///////////////////////////////\n\n\t\t\tTestInsert(stopwatch1, stdDeque);\n\t\t\tTestInsert(stopwatch2, eaDeque);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"deque/insert\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test erase\n\t\t\t///////////////////////////////\n\n\t\t\tTestErase(stopwatch1, stdDeque);\n\t\t\tTestErase(stopwatch2, eaDeque);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"deque/erase\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\t\t}\n\t}\n}\n\n\n\n\n\n\n\n\n\n\n\n\n" }, { "path": "benchmark/source/BenchmarkHash.cpp", "content": "/////////////////////////////////////////////////////////////////////////////\n// Copyright (c) Electronic Arts Inc. All rights reserved.\n/////////////////////////////////////////////////////////////////////////////\n\n\n#include \"EASTLBenchmark.h\"\n#include \"EASTLTest.h\"\n#include \n#include \n#include \n#include \n#include \n\n\n\nEA_DISABLE_ALL_VC_WARNINGS()\n#include \n#include \n#include \n#include \nEA_RESTORE_ALL_VC_WARNINGS()\n\n\n\nusing namespace EA;\n\n\n// HashString8\n//\n// We define a string\n//\ntemplate \nstruct HashString8\n{\n\t// Defined for EASTL, STLPort, SGI, etc. and Metrowerks-related hash tables:\n\tsize_t operator()(const String& s) const \n\t{ \n\t\tconst uint8_t* p = (const uint8_t*) s.c_str();\n\t\tuint32_t c, stringHash = UINT32_C(2166136261);\n\t\twhile((c = *p++) != 0)\n\t\t\tstringHash = (stringHash * 16777619) ^ c;\n\t\treturn stringHash;\n\t}\n\n\t// Defined for Dinkumware-related (e.g. MS STL) hash tables:\n\tbool operator()(const String& s1, const String& s2) const\n\t{\n\t\treturn s1 < s2;\n\t}\n\n\t// Defined for Dinkumware-related (e.g. MS STL) hash tables:\n\tenum {\n\t\tbucket_size = 7,\n\t\tmin_buckets = 8\n\t};\n};\n\n\nusing StdMapUint32TO = std::unordered_map;\nusing StdMapStrUint32 = std::unordered_map>;\n\nusing EaMapUint32TO = eastl::hash_map;\nusing EaMapStrUint32 = eastl::hash_map>;\n\n\nnamespace\n{\n\ttemplate \n\tvoid TestInsert(EA::StdC::Stopwatch& stopwatch, Container& c, const Value* pArrayBegin, const Value* pArrayEnd)\n\t{\n\t\tstopwatch.Restart();\n\t\tc.insert(pArrayBegin, pArrayEnd);\n\t\tstopwatch.Stop();\n\t}\n\n\n\ttemplate \n\tvoid TestIteration(EA::StdC::Stopwatch& stopwatch, const Container& c, const Value& findValue)\n\t{\n\t\tstopwatch.Restart();\n\t\ttypename Container::const_iterator it = eastl::find(c.begin(), c.end(), findValue); // It shouldn't matter what find implementation we use here, as it merely iterates values.\n\t\tstopwatch.Stop();\n\t\tif(it != c.end())\n\t\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%p\", &*it);\n\t}\n\n\n\ttemplate \n\tvoid TestBracket(EA::StdC::Stopwatch& stopwatch, Container& c, const Value* pArrayBegin, const Value* pArrayEnd)\n\t{\n\t\tstopwatch.Restart();\n\t\twhile(pArrayBegin != pArrayEnd)\n\t\t{\n\t\t\tBenchmark::DoNothing(&c[pArrayBegin->first]);\n\t\t\t++pArrayBegin;\n\t\t}\n\t\tstopwatch.Stop();\n\t}\n\n\n\ttemplate \n\tvoid TestFind(EA::StdC::Stopwatch& stopwatch, Container& c, const Value* pArrayBegin, const Value* pArrayEnd)\n\t{\n\t\tstopwatch.Restart();\n\t\twhile(pArrayBegin != pArrayEnd)\n\t\t{\n\t\t\ttypename Container::iterator it = c.find(pArrayBegin->first);\n\t\t\tBenchmark::DoNothing(&it);\n\t\t\t++pArrayBegin;\n\t\t}\n\t\tstopwatch.Stop();\n\t}\n\n\n\ttemplate \n\tvoid TestFindAsStd(EA::StdC::Stopwatch& stopwatch, Container& c, const Value* pArrayBegin, const Value* pArrayEnd)\n\t{\n\t\tstopwatch.Restart();\n\t\twhile(pArrayBegin != pArrayEnd)\n\t\t{\n\t\t\ttypename Container::iterator it = c.find(pArrayBegin->first.c_str());\n\t\t\tBenchmark::DoNothing(&it);\n\t\t\t++pArrayBegin;\n\t\t}\n\t\tstopwatch.Stop();\n\t}\n\n\n\ttemplate \n\tvoid TestFindAsEa(EA::StdC::Stopwatch& stopwatch, Container& c, const Value* pArrayBegin, const Value* pArrayEnd)\n\t{\n\t\tstopwatch.Restart();\n\t\twhile(pArrayBegin != pArrayEnd)\n\t\t{\n\t\t\ttypename Container::iterator it = c.find_as(pArrayBegin->first.c_str());\n\t\t\tBenchmark::DoNothing(&it);\n\t\t\t++pArrayBegin;\n\t\t}\n\t\tstopwatch.Stop();\n\t}\n\n\n\ttemplate \n\tvoid TestCount(EA::StdC::Stopwatch& stopwatch, Container& c, const Value* pArrayBegin, const Value* pArrayEnd)\n\t{\n\t\ttypename Container::size_type temp = 0;\n\t\tstopwatch.Restart();\n\t\twhile(pArrayBegin != pArrayEnd)\n\t\t{\n\t\t\ttemp += c.count(pArrayBegin->first);\n\t\t\t++pArrayBegin;\n\t\t}\n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%u\", (unsigned)temp);\n\t}\n\n\n\ttemplate \n\tvoid TestEraseValue(EA::StdC::Stopwatch& stopwatch, Container& c, const Value* pArrayBegin, const Value* pArrayEnd)\n\t{\n\t\tstopwatch.Restart();\n\t\twhile(pArrayBegin != pArrayEnd)\n\t\t{\n\t\t\tc.erase(pArrayBegin->first);\n\t\t\t++pArrayBegin;\n\t\t}\n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%u\", (unsigned)c.size());\n\t}\n\n\n\ttemplate \n\tvoid TestErasePosition(EA::StdC::Stopwatch& stopwatch, Container& c)\n\t{\n\t\ttypename Container::size_type j, jEnd;\n\t\ttypename Container::iterator it;\n\n\t\tstopwatch.Restart();\n\t\tfor(j = 0, jEnd = c.size() / 3, it = c.begin(); j < jEnd; ++j)\n\t\t{\n\t\t\t// The erase fucntion is supposed to return an iterator, but the C++ standard was \n\t\t\t// not initially clear about it and some STL implementations don't do it correctly.\n\t\t\t#if (defined(_MSC_VER) || defined(_CPPLIB_VER)) // _CPPLIB_VER is something defined by Dinkumware STL.\n\t\t\t\tit = c.erase(it);\n\t\t\t#else\n\t\t\t\t// This pathway may execute at a slightly different speed than the \n\t\t\t\t// standard behaviour, but that's fine for the benchmark because the\n\t\t\t\t// benchmark is measuring the speed of erasing while iterating, and \n\t\t\t\t// however it needs to get done by the given STL is how it is measured.\n\t\t\t\tconst typename Container::iterator itErase(it++);\n\t\t\t\tc.erase(itErase);\n\t\t\t#endif\n\n\t\t\t++it;\n\t\t\t++it;\n\t\t}\n\n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%p %p\", &c, &it);\n\t}\n\n\n\ttemplate \n\tvoid TestEraseRange(EA::StdC::Stopwatch& stopwatch, Container& c)\n\t{\n\t\ttypename Container::size_type j, jEnd;\n\t\ttypename Container::iterator it1 = c.begin();\n\t\ttypename Container::iterator it2 = c.begin();\n\n\t\tfor(j = 0, jEnd = c.size() / 3; j < jEnd; ++j)\n\t\t\t++it2;\n\n\t\tstopwatch.Restart();\n\t\tc.erase(it1, it2);\n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%p %p %p\", &c, &it1, &it2);\n\t}\n\n\n\ttemplate \n\tvoid TestClear(EA::StdC::Stopwatch& stopwatch, Container& c)\n\t{\n\t\tstopwatch.Restart();\n\t\tc.clear();\n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%u\", (unsigned)c.size());\n\t}\n\n\n} // namespace\n\n\n\nvoid BenchmarkHash()\n{\n\tEASTLTest_Printf(\"HashMap\\n\");\n\n\tEA::UnitTest::Rand rng(EA::UnitTest::GetRandSeed());\n\tEA::StdC::Stopwatch stopwatch1(EA::StdC::Stopwatch::kUnitsCPUCycles);\n\tEA::StdC::Stopwatch stopwatch2(EA::StdC::Stopwatch::kUnitsCPUCycles);\n\n\t{\n\t\teastl::vector< std::pair > stdVectorUT(10000);\n\t\teastl::vector< eastl::pair > eaVectorUT(10000);\n\n\t\teastl::vector< std::pair< std::string, uint32_t> > stdVectorSU(10000);\n\t\teastl::vector< eastl::pair > eaVectorSU(10000);\n\n\t\tfor(eastl_size_t i = 0, iEnd = stdVectorUT.size(); i < iEnd; i++)\n\t\t{\n\t\t\tconst uint32_t n1 = rng.RandLimit((uint32_t)(iEnd / 2));\n\t\t\tconst uint32_t n2 = rng.RandValue();\n\n\t\t\tstdVectorUT[i] = std::pair(n1, TestObject(n2));\n\t\t\teaVectorUT[i] = eastl::pair(n1, TestObject(n2));\n\n\t\t\tchar str_n1[32];\n\t\t\tsprintf(str_n1, \"%u\", (unsigned)n1);\n\n\t\t\tstdVectorSU[i] = std::pair< std::string, uint32_t>( std::string(str_n1), n2);\n\t\t\teaVectorSU[i] = eastl::pair(eastl::string(str_n1), n2);\n\t\t}\n\n\t\tfor(int i = 0; i < 2; i++)\n\t\t{\n\t\t\tStdMapUint32TO stdMapUint32TO;\n\t\t\tEaMapUint32TO eaMapUint32TO;\n\n\t\t\tStdMapStrUint32 stdMapStrUint32;\n\t\t\tEaMapStrUint32 eaMapStrUint32;\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test insert(const value_type&)\n\t\t\t///////////////////////////////\n\n\t\t\tTestInsert(stopwatch1, stdMapUint32TO, stdVectorUT.data(), stdVectorUT.data() + stdVectorUT.size());\n\t\t\tTestInsert(stopwatch2, eaMapUint32TO, eaVectorUT.data(), eaVectorUT.data() + eaVectorUT.size());\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"hash_map/insert\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tTestInsert(stopwatch1, stdMapStrUint32, stdVectorSU.data(), stdVectorSU.data() + stdVectorSU.size());\n\t\t\tTestInsert(stopwatch2, eaMapStrUint32, eaVectorSU.data(), eaVectorSU.data() + eaVectorSU.size());\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"hash_map/insert\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test iteration\n\t\t\t///////////////////////////////\n\n\t\t\tTestIteration(stopwatch1, stdMapUint32TO, StdMapUint32TO::value_type(9999999, TestObject(9999999)));\n\t\t\tTestIteration(stopwatch2, eaMapUint32TO, EaMapUint32TO::value_type(9999999, TestObject(9999999)));\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"hash_map/iteration\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tTestIteration(stopwatch1, stdMapStrUint32, StdMapStrUint32::value_type( std::string(\"9999999\"), 9999999));\n\t\t\tTestIteration(stopwatch2, eaMapStrUint32, EaMapStrUint32::value_type(eastl::string(\"9999999\"), 9999999));\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"hash_map/iteration\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test operator[]\n\t\t\t///////////////////////////////\n\n\t\t\tTestBracket(stopwatch1, stdMapUint32TO, stdVectorUT.data(), stdVectorUT.data() + stdVectorUT.size());\n\t\t\tTestBracket(stopwatch2, eaMapUint32TO, eaVectorUT.data(), eaVectorUT.data() + eaVectorUT.size());\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"hash_map/operator[]\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tTestBracket(stopwatch1, stdMapStrUint32, stdVectorSU.data(), stdVectorSU.data() + stdVectorSU.size());\n\t\t\tTestBracket(stopwatch2, eaMapStrUint32, eaVectorSU.data(), eaVectorSU.data() + eaVectorSU.size());\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"hash_map/operator[]\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test find\n\t\t\t///////////////////////////////\n\n\t\t\tTestFind(stopwatch1, stdMapUint32TO, stdVectorUT.data(), stdVectorUT.data() + stdVectorUT.size());\n\t\t\tTestFind(stopwatch2, eaMapUint32TO, eaVectorUT.data(), eaVectorUT.data() + eaVectorUT.size());\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"hash_map/find\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tTestFind(stopwatch1, stdMapStrUint32, stdVectorSU.data(), stdVectorSU.data() + stdVectorSU.size());\n\t\t\tTestFind(stopwatch2, eaMapStrUint32, eaVectorSU.data(), eaVectorSU.data() + eaVectorSU.size());\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"hash_map/find\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test find_as\n\t\t\t///////////////////////////////\n\n\t\t\tTestFindAsStd(stopwatch1, stdMapStrUint32, stdVectorSU.data(), stdVectorSU.data() + stdVectorSU.size());\n\t\t\tTestFindAsEa(stopwatch2, eaMapStrUint32, eaVectorSU.data(), eaVectorSU.data() + eaVectorSU.size());\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"hash_map/find_as/char*\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test count\n\t\t\t///////////////////////////////\n\n\t\t\tTestCount(stopwatch1, stdMapUint32TO, stdVectorUT.data(), stdVectorUT.data() + stdVectorUT.size());\n\t\t\tTestCount(stopwatch2, eaMapUint32TO, eaVectorUT.data(), eaVectorUT.data() + eaVectorUT.size());\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"hash_map/count\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tTestCount(stopwatch1, stdMapStrUint32, stdVectorSU.data(), stdVectorSU.data() + stdVectorSU.size());\n\t\t\tTestCount(stopwatch2, eaMapStrUint32, eaVectorSU.data(), eaVectorSU.data() + eaVectorSU.size());\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"hash_map/count\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test erase(const key_type& key)\n\t\t\t///////////////////////////////\n\n\t\t\tTestEraseValue(stopwatch1, stdMapUint32TO, stdVectorUT.data(), stdVectorUT.data() + (stdVectorUT.size() / 2));\n\t\t\tTestEraseValue(stopwatch2, eaMapUint32TO, eaVectorUT.data(), eaVectorUT.data() + (eaVectorUT.size() / 2));\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"hash_map/erase val\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tTestEraseValue(stopwatch1, stdMapStrUint32, stdVectorSU.data(), stdVectorSU.data() + (stdVectorSU.size() / 2));\n\t\t\tTestEraseValue(stopwatch2, eaMapStrUint32, eaVectorSU.data(), eaVectorSU.data() + (eaVectorSU.size() / 2));\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"hash_map/erase val\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test erase(iterator position)\n\t\t\t///////////////////////////////\n\n\t\t\tTestErasePosition(stopwatch1, stdMapUint32TO);\n\t\t\tTestErasePosition(stopwatch2, eaMapUint32TO);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"hash_map/erase pos\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tTestErasePosition(stopwatch1, stdMapStrUint32);\n\t\t\tTestErasePosition(stopwatch2, eaMapStrUint32);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"hash_map/erase pos\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test erase(iterator first, iterator last)\n\t\t\t///////////////////////////////\n\n\t\t\tTestEraseRange(stopwatch1, stdMapUint32TO);\n\t\t\tTestEraseRange(stopwatch2, eaMapUint32TO);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"hash_map/erase range\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tTestEraseRange(stopwatch1, stdMapStrUint32);\n\t\t\tTestEraseRange(stopwatch2, eaMapStrUint32);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"hash_map/erase range\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test clear()\n\t\t\t///////////////////////////////\n\n\t\t\t// Clear the containers of whatever they happen to have. We want the containers to have full data.\n\t\t\tTestClear(stopwatch1, stdMapUint32TO);\n\t\t\tTestClear(stopwatch2, eaMapUint32TO);\n\t\t\tTestClear(stopwatch1, stdMapStrUint32);\n\t\t\tTestClear(stopwatch2, eaMapStrUint32);\n\n\t\t\t// Re-set the containers with full data.\n\t\t\tTestInsert(stopwatch1, stdMapUint32TO, stdVectorUT.data(), stdVectorUT.data() + stdVectorUT.size());\n\t\t\tTestInsert(stopwatch2, eaMapUint32TO, eaVectorUT.data(), eaVectorUT.data() + eaVectorUT.size());\n\t\t\tTestInsert(stopwatch1, stdMapStrUint32, stdVectorSU.data(), stdVectorSU.data() + stdVectorSU.size());\n\t\t\tTestInsert(stopwatch2, eaMapStrUint32, eaVectorSU.data(), eaVectorSU.data() + eaVectorSU.size());\n\n\t\t\t// Now clear the data again, this time measuring it.\n\t\t\tTestClear(stopwatch1, stdMapUint32TO);\n\t\t\tTestClear(stopwatch2, eaMapUint32TO);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"hash_map/clear\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tTestClear(stopwatch1, stdMapStrUint32);\n\t\t\tTestClear(stopwatch2, eaMapStrUint32);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"hash_map/clear\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t}\n\t}\n}\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n" }, { "path": "benchmark/source/BenchmarkHeap.cpp", "content": "/////////////////////////////////////////////////////////////////////////////\n// Copyright (c) Electronic Arts Inc. All rights reserved.\n/////////////////////////////////////////////////////////////////////////////\n\n\n#include \"EASTLBenchmark.h\"\n#include \"EASTLTest.h\"\n#include \n#include \n#include \n#include \n\n#ifdef _MSC_VER\n\t#pragma warning(push, 0)\n\t#pragma warning(disable: 4350) // behavior change: X called instead of Y\n#endif\n#include \n#include \n#ifdef _MSC_VER\n\t#pragma warning(pop)\n#endif\n\n\nusing namespace EA;\n\n\nnamespace\n{\n\ttemplate \n\tvoid TestMakeHeapStd(EA::StdC::Stopwatch& stopwatch, Iterator first, Iterator last)\n\t{\n\t\tstopwatch.Restart();\n\t\tstd::make_heap(first, last);\n\t\tstopwatch.Stop();\n\t}\n\n\ttemplate \n\tvoid TestMakeHeapEa(EA::StdC::Stopwatch& stopwatch, Iterator first, Iterator last)\n\t{\n\t\tstopwatch.Restart();\n\t\teastl::make_heap(first, last);\n\t\tstopwatch.Stop();\n\t}\n\n\n\n\ttemplate \n\tvoid TestPushHeapStd(EA::StdC::Stopwatch& stopwatch, Iterator1 first1, Iterator1 last1, Iterator2 first2, Iterator2 last2)\n\t{\n\t\tstopwatch.Restart();\n\t\twhile(first2 != last2)\n\t\t{\n\t\t\t*last1++ = *first2++;\n\t\t\tstd::push_heap(first1, last1);\n\t\t}\n\t\tstopwatch.Stop();\n\t}\n\n\ttemplate \n\tvoid TestPushHeapEa(EA::StdC::Stopwatch& stopwatch, Iterator1 first1, Iterator1 last1, Iterator2 first2, Iterator2 last2)\n\t{\n\t\tstopwatch.Restart();\n\t\twhile(first2 != last2)\n\t\t{\n\t\t\t*last1++ = *first2++;\n\t\t\teastl::push_heap(first1, last1);\n\t\t}\n\t\tstopwatch.Stop();\n\t}\n\n\n\n\ttemplate \n\tvoid TestPopHeapStd(EA::StdC::Stopwatch& stopwatch, Iterator first, Iterator last, Iterator popEnd)\n\t{\n\t\tstopwatch.Restart();\n\t\twhile(last != popEnd)\n\t\t\tstd::pop_heap(first, last--);\n\t\tstopwatch.Stop();\n\t}\n\n\ttemplate \n\tvoid TestPopHeapEa(EA::StdC::Stopwatch& stopwatch, Iterator first, Iterator last, Iterator popEnd)\n\t{\n\t\tstopwatch.Restart();\n\t\twhile(last != popEnd)\n\t\t\teastl::pop_heap(first, last--);\n\t\tstopwatch.Stop();\n\t}\n\n\n\n\ttemplate \n\tvoid TestSortHeapStd(EA::StdC::Stopwatch& stopwatch, Iterator first, Iterator last)\n\t{\n\t\tstopwatch.Restart();\n\t\tstd::sort_heap(first, last);\n\t\tstopwatch.Stop();\n\t}\n\n\ttemplate \n\tvoid TestSortHeapEa(EA::StdC::Stopwatch& stopwatch, Iterator first, Iterator last)\n\t{\n\t\tstopwatch.Restart();\n\t\teastl::sort_heap(first, last);\n\t\tstopwatch.Stop();\n\t}\n\n} // namespace\n\n\n\nvoid BenchmarkHeap()\n{\n\tEASTLTest_Printf(\"Heap (Priority Queue)\\n\");\n\n\tEA::UnitTest::RandGenT rng(EA::UnitTest::GetRandSeed());\n\tEA::StdC::Stopwatch stopwatch1(EA::StdC::Stopwatch::kUnitsCPUCycles);\n\tEA::StdC::Stopwatch stopwatch2(EA::StdC::Stopwatch::kUnitsCPUCycles);\n\n\t{\n\t\tconst int kArraySize = 100000;\n\n\t\t// uint32[]\n\t\tuint32_t* const pIntArrayS = new uint32_t[kArraySize * 2]; // * 2 because we will be adding more items via push_heap.\n\t\tuint32_t* const pIntArrayE = new uint32_t[kArraySize * 2]; // S means Std; E means EA.\n\t\tuint32_t* const pIntArray2 = new uint32_t[kArraySize]; // This will be used for pop_heap.\n\n\t\teastl::generate(pIntArrayS, pIntArrayS + kArraySize, rng);\n\t\teastl::copy(pIntArrayS, pIntArrayS + kArraySize, pIntArrayE);\n\t\teastl::copy(pIntArrayS, pIntArrayS + kArraySize, pIntArray2);\n\n\n\t\t// vector\n\t\tstd::vector stdVectorTO(kArraySize * 2);\n\t\tstd::vector stdVectorTO2(kArraySize);\n\t\teastl::vector eaVectorTO(kArraySize * 2);\n\t\teastl::vector eaVectorTO2(kArraySize);\n\n\t\tfor(int k = 0; k < kArraySize; k++)\n\t\t{\n\t\t\tstdVectorTO[k] = TestObject(pIntArrayS[k]);\n\t\t\tstdVectorTO2[k] = TestObject(pIntArrayS[k]);\n\t\t\teaVectorTO[k] = TestObject(pIntArrayS[k]);\n\t\t\teaVectorTO2[k] = TestObject(pIntArrayS[k]);\n\t\t}\n\n\n\t\tfor(int i = 0; i < 2; i++)\n\t\t{\n\t\t\t///////////////////////////////\n\t\t\t// Test make_heap\n\t\t\t///////////////////////////////\n\n\t\t\tTestMakeHeapStd(stopwatch1, pIntArrayS, pIntArrayS + kArraySize);\n\t\t\tTestMakeHeapEa (stopwatch2, pIntArrayE, pIntArrayE + kArraySize);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"heap (uint32_t[])/make_heap\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tTestMakeHeapStd(stopwatch1, stdVectorTO.begin(), stdVectorTO.begin() + kArraySize);\n\t\t\tTestMakeHeapEa (stopwatch2, eaVectorTO.begin(), eaVectorTO.begin() + kArraySize);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"heap (vector)/make_heap\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test push_heap\n\t\t\t///////////////////////////////\n\n\t\t\tTestPushHeapStd(stopwatch1, pIntArrayS, pIntArrayS + kArraySize, pIntArray2, pIntArray2 + kArraySize);\n\t\t\tTestPushHeapEa (stopwatch2, pIntArrayE, pIntArrayE + kArraySize, pIntArray2, pIntArray2 + kArraySize);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"heap (uint32_t[])/push_heap\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tTestPushHeapStd(stopwatch1, stdVectorTO.begin(), stdVectorTO.begin() + kArraySize, stdVectorTO2.begin(), stdVectorTO2.begin() + kArraySize);\n\t\t\tTestPushHeapEa (stopwatch2, eaVectorTO.begin(), eaVectorTO.begin() + kArraySize, eaVectorTO2.begin(), eaVectorTO2.begin() + kArraySize);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"heap (vector)/push_heap\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test pop_heap\n\t\t\t///////////////////////////////\n\n\t\t\tTestPopHeapStd(stopwatch1, pIntArrayS, pIntArrayS + (kArraySize * 2), pIntArrayS + kArraySize); // * 2 because we used push_heap above to add more items.\n\t\t\tTestPopHeapEa (stopwatch2, pIntArrayE, pIntArrayE + (kArraySize * 2), pIntArrayE + kArraySize);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"heap (uint32_t[])/pop_heap\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tTestPopHeapStd(stopwatch1, stdVectorTO.begin(), stdVectorTO.begin() + (kArraySize * 2), stdVectorTO.begin() + kArraySize); // * 2 because we used push_heap above to add more items.\n\t\t\tTestPopHeapEa (stopwatch2, eaVectorTO.begin(), eaVectorTO.begin() + (kArraySize * 2), eaVectorTO.begin() + kArraySize);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"heap (vector)/pop_heap\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test sort_heap\n\t\t\t///////////////////////////////\n\n\t\t\tTestSortHeapStd(stopwatch1, pIntArrayS, pIntArrayS + kArraySize);\n\t\t\tTestSortHeapEa (stopwatch2, pIntArrayE, pIntArrayE + kArraySize);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"heap (uint32_t[])/sort_heap\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tTestSortHeapStd(stopwatch1, stdVectorTO.begin(), stdVectorTO.begin() + kArraySize);\n\t\t\tTestSortHeapEa (stopwatch2, eaVectorTO.begin(), eaVectorTO.begin() + kArraySize);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"heap (vector)/sort_heap\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\t\t}\n\n\t\tdelete[] pIntArrayS;\n\t\tdelete[] pIntArrayE;\n\t\tdelete[] pIntArray2;\n\t}\n}\n\n\n\n\n\n\n\n\n\n\n\n\n" }, { "path": "benchmark/source/BenchmarkList.cpp", "content": "/////////////////////////////////////////////////////////////////////////////\n// Copyright (c) Electronic Arts Inc. All rights reserved.\n/////////////////////////////////////////////////////////////////////////////\n\n\n#include \"EASTLBenchmark.h\"\n#include \"EASTLTest.h\"\n#include \n#include \n#include \n#include \n#include \n\n#ifdef _MSC_VER\n\t#pragma warning(push, 0)\n\t#pragma warning(disable: 4555) // expression has no effect; expected expression with side-effect\n\t#pragma warning(disable: 4350) // behavior change: X called instead of Y\n#endif\n#include \n#ifdef _MSC_VER\n\t#pragma warning(pop)\n#endif\n\n\nusing namespace EA;\nusing namespace eastl;\n\n\n\ntypedef std::list StdListTO;\ntypedef eastl::list EaListTO;\n\n\n\nnamespace\n{\n\tvoid DoNothing(void*)\n\t{\n\t\t// Empty\n\t}\n\n\n\ttemplate \n\tvoid TestCtorIterator(EA::StdC::Stopwatch& stopwatch, const ContainerSource& cs, Container*) // Dummy Container argument because of GCC 2.X limitations.\n\t{\n\t\tstopwatch.Restart();\n\t\tContainer c(cs.begin(), cs.end());\n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%u\", (unsigned)c.back().mX);\n\t}\n\n\n\ttemplate \n\tvoid TestCtorN(EA::StdC::Stopwatch& stopwatch, Container*) // Dummy Container argument because of GCC 2.X limitations.\n\t{\n\t\tstopwatch.Restart();\n\t\tContainer c(10000);\n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%u\", (unsigned)c.back().mX);\n\t}\n\n\n\ttemplate \n\tvoid TestPushBack(EA::StdC::Stopwatch& stopwatch, Container& c, const TestObject* pTOBegin, const TestObject* const pTOEnd)\n\t{\n\t\tstopwatch.Restart();\n\t\twhile(pTOBegin != pTOEnd)\n\t\t\tc.push_back(*pTOBegin++);\n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%u\", (unsigned)c.back().mX);\n\t}\n\n\n\ttemplate \n\tvoid TestInsert(EA::StdC::Stopwatch& stopwatch, Container& c, const TestObject* pTOBegin, const TestObject* const pTOEnd)\n\t{\n\t\ttypename Container::iterator it = c.begin();\n\t\tstopwatch.Restart();\n\t\twhile(pTOBegin != pTOEnd)\n\t\t{\n\t\t\tit = c.insert(it, *pTOBegin++);\n\n\t\t\tif(++it == c.end()) // Try to safely increment the iterator a couple times\n\t\t\t\tit = c.begin();\n\t\t\tif(++it == c.end())\n\t\t\t\tit = c.begin();\n\t\t}\n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%u\", (unsigned)c.back().mX);\n\t}\n\n\n\ttemplate \n\tvoid TestSize(EA::StdC::Stopwatch& stopwatch, Container& c, void (*pFunction)(...))\n\t{\n\t\tstopwatch.Restart();\n\t\tfor(int i = 0; (i < 10000) && c.size(); i++)\n\t\t\t(*pFunction)(&c);\n\t\tstopwatch.Stop();\n\t}\n\n\n\ttemplate \n\tvoid TestFind(EA::StdC::Stopwatch& stopwatch, Container& c, const TestObject& to)\n\t{\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%u\", (unsigned)c.size());\n\t\tstopwatch.Restart();\n\t\ttypename Container::iterator it = eastl::find(c.begin(), c.end(), to);\n\t\tstopwatch.Stop();\n\t\tif(it != c.end())\n\t\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%d\", (*it).mX);\n\t}\n\n\n\ttemplate \n\tvoid TestReverse(EA::StdC::Stopwatch& stopwatch, Container& c)\n\t{\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%u\", (unsigned)c.size());\n\t\tstopwatch.Restart();\n\t\tc.reverse();\n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%u\", (unsigned)c.back().mX);\n\t}\n\n\n\ttemplate \n\tvoid TestRemove(EA::StdC::Stopwatch& stopwatch, Container& c, const TestObject* pTOBegin, const TestObject* const pTOEnd)\n\t{\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%u\", (unsigned)c.size());\n\t\tstopwatch.Restart();\n\t\twhile(pTOBegin != pTOEnd)\n\t\t\tc.remove(*pTOBegin++);\n\t\tstopwatch.Stop();\n\t\tif(!c.empty())\n\t\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%u\", (unsigned)c.back().mX);\n\t}\n\n\n\ttemplate \n\tvoid TestSplice(EA::StdC::Stopwatch& stopwatch, Container& c, Container& cSource)\n\t{\n\t\ttypename Container::iterator it = c.begin();\n\t\tint i = 0, iEnd = (int)cSource.size() - 5;\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%u\", (unsigned)c.size());\n\t\tstopwatch.Restart();\n\t\twhile(i++ != iEnd)\n\t\t\tc.splice(it, cSource, cSource.begin());\n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%u\", (unsigned)c.back().mX);\n\t}\n\n\n\ttemplate \n\tvoid TestErase(EA::StdC::Stopwatch& stopwatch, Container& c)\n\t{\n\t\ttypename Container::iterator it = c.begin();\n\t\tint i = 0, iEnd = (int)c.size() - 5;\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%u\", (unsigned)c.size());\n\t\tstopwatch.Restart();\n\t\twhile(i++ != iEnd)\n\t\t{\n\t\t\tit = c.erase(it);\n\n\t\t\tif(it == c.end()) // Try to safely increment the iterator a couple times\n\t\t\t\tit = c.begin();\n\t\t\tif(++it == c.end())\n\t\t\t\tit = c.begin();\n\t\t}\n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%u\", (unsigned)c.back().mX);\n\t}\n\n} // namespace\n\n\n\n\nvoid BenchmarkList()\n{\n\tEASTLTest_Printf(\"List\\n\");\n\n\tEASTLTest_Rand rng(EA::UnitTest::GetRandSeed());\n\tEA::StdC::Stopwatch stopwatch1(EA::StdC::Stopwatch::kUnitsCPUCycles);\n\tEA::StdC::Stopwatch stopwatch2(EA::StdC::Stopwatch::kUnitsCPUCycles);\n\n\tEaListTO eaListTO_1(1);\n\tEaListTO eaListTO_10(10);\n\tEaListTO eaListTO_100(100);\n\tStdListTO stdListTO_1(1);\n\tStdListTO stdListTO_10(10);\n\tStdListTO stdListTO_100(100);\n\n\t{\n\t\tchar buffer[32];\n\t\tsprintf(buffer, \"%p\", &DoNothing);\n\t}\n\n\t{\n\t\teastl::vector toVector(100000);\n\t\tfor(eastl_size_t i = 0, iEnd = toVector.size(); i < iEnd; ++i)\n\t\t\ttoVector[i] = TestObject((int)i);\n\t\trandom_shuffle(toVector.begin(), toVector.end(), rng);\n\n\n\t\tfor(int i = 0; i < 2; i++)\n\t\t{\n\t\t\tStdListTO stdListTO;\n\t\t\tEaListTO eaListTO;\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test list(InputIterator first, InputIterator last)\n\t\t\t///////////////////////////////\n\n\t\t\tTestCtorIterator(stopwatch1, toVector, &stdListTO);\n\t\t\tTestCtorIterator(stopwatch2, toVector, &eaListTO);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"list/ctor(it)\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test list(size_type n)\n\t\t\t///////////////////////////////\n\n\t\t\tTestCtorN(stopwatch1, &stdListTO);\n\t\t\tTestCtorN(stopwatch2, &eaListTO);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"list/ctor(n)\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test push_back()\n\t\t\t///////////////////////////////\n\n\t\t\tTestPushBack(stopwatch1, stdListTO, toVector.data(), toVector.data() + toVector.size());\n\t\t\tTestPushBack(stopwatch2, eaListTO, toVector.data(), toVector.data() + toVector.size());\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"list/push_back\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test insert()\n\t\t\t///////////////////////////////\n\n\t\t\tTestInsert(stopwatch1, stdListTO, toVector.data(), toVector.data() + toVector.size());\n\t\t\tTestInsert(stopwatch2, eaListTO, toVector.data(), toVector.data() + toVector.size());\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"list/insert\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test size()\n\t\t\t///////////////////////////////\n\n\t\t\tTestSize(stopwatch1, stdListTO_1, Benchmark::DoNothing);\n\t\t\tTestSize(stopwatch2, eaListTO_1, Benchmark::DoNothing);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"list/size/1\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tTestSize(stopwatch1, stdListTO_10, Benchmark::DoNothing);\n\t\t\tTestSize(stopwatch2, eaListTO_10, Benchmark::DoNothing);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"list/size/10\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime()\n\t\t\t\t\t\t\t\t\t#if !EASTL_LIST_SIZE_CACHE\n\t\t\t\t\t\t\t\t\t\t, \"EASTL is configured to not cache the list size.\"\n\t\t\t\t\t\t\t\t\t#endif\n\t\t\t\t\t\t\t\t\t);\n\n\t\t\tTestSize(stopwatch1, stdListTO_100, Benchmark::DoNothing);\n\t\t\tTestSize(stopwatch2, eaListTO_100, Benchmark::DoNothing);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"list/size/100\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime()\n\t\t\t\t\t\t\t\t\t#if !EASTL_LIST_SIZE_CACHE\n\t\t\t\t\t\t\t\t\t\t, \"EASTL is configured to not cache the list size.\"\n\t\t\t\t\t\t\t\t\t#endif\n\t\t\t\t\t\t\t\t\t);\n\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test find()\n\t\t\t///////////////////////////////\n\n\t\t\tTestFind(stopwatch1, stdListTO, TestObject(99999999));\n\t\t\tTestFind(stopwatch2, eaListTO, TestObject(99999999));\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"list/find\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test reverse()\n\t\t\t///////////////////////////////\n\n\t\t\tTestReverse(stopwatch1, stdListTO);\n\t\t\tTestReverse(stopwatch2, eaListTO);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"list/reverse\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test remove()\n\t\t\t///////////////////////////////\n\n\t\t\trandom_shuffle(toVector.begin(), toVector.end(), rng);\n\t\t\tTestRemove(stopwatch1, stdListTO, &toVector[0], &toVector[20]);\n\t\t\tTestRemove(stopwatch2, eaListTO, &toVector[0], &toVector[20]);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"list/remove\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test splice()\n\t\t\t///////////////////////////////\n\t\t\tStdListTO listCopyStd(stdListTO);\n\t\t\tEaListTO listCopyEa(eaListTO);\n\n\t\t\tTestSplice(stopwatch1, stdListTO, listCopyStd);\n\t\t\tTestSplice(stopwatch2, eaListTO, listCopyEa);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"list/splice\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test erase()\n\t\t\t///////////////////////////////\n\n\t\t\tTestErase(stopwatch1, stdListTO);\n\t\t\tTestErase(stopwatch2, eaListTO);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"list/erase\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\t\t}\n\t}\n}\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n" }, { "path": "benchmark/source/BenchmarkMap.cpp", "content": "/////////////////////////////////////////////////////////////////////////////\n// Copyright (c) Electronic Arts Inc. All rights reserved.\n/////////////////////////////////////////////////////////////////////////////\n\n\n#include \"EASTLBenchmark.h\"\n#include \"EASTLTest.h\"\n#include \n#include \n#include \n#include \n\nEA_DISABLE_ALL_VC_WARNINGS()\n#include \n#include \nEA_RESTORE_ALL_VC_WARNINGS()\n\n\nusing namespace EA;\n\n\ntypedef std::map StdMapTOUint32;\ntypedef eastl::map EaMapTOUint32;\n\n\nnamespace\n{\n\ttemplate \n\tvoid TestInsert(EA::StdC::Stopwatch& stopwatch, Container& c, const Value* pArrayBegin, const Value* pArrayEnd, const Value& highValue)\n\t{\n\t\tstopwatch.Restart();\n\t\tc.insert(pArrayBegin, pArrayEnd);\n\t\tstopwatch.Stop();\n\t\tc.insert(highValue);\n\t}\n\n\n\ttemplate \n\tvoid TestIteration(EA::StdC::Stopwatch& stopwatch, const Container& c, const Value& findValue)\n\t{\n\t\tstopwatch.Restart();\n\t\ttypename Container::const_iterator it = eastl::find(c.begin(), c.end(), findValue); // It shouldn't matter what find implementation we use here, as it merely iterates values.\n\t\tstopwatch.Stop();\n\t\tif(it != c.end())\n\t\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%p\", &*it);\n\t}\n\n\n\ttemplate \n\tvoid TestBracket(EA::StdC::Stopwatch& stopwatch, Container& c, const Value* pArrayBegin, const Value* pArrayEnd)\n\t{\n\t\tstopwatch.Restart();\n\t\twhile(pArrayBegin != pArrayEnd)\n\t\t{\n\t\t\tBenchmark::DoNothing(c[pArrayBegin->first]);\n\t\t\t++pArrayBegin;\n\t\t}\n\t\tstopwatch.Stop();\n\t}\n\n\n\ttemplate \n\tvoid TestFind(EA::StdC::Stopwatch& stopwatch, Container& c, const Value* pArrayBegin, const Value* pArrayEnd)\n\t{\n\t\tstopwatch.Restart();\n\t\twhile(pArrayBegin != pArrayEnd)\n\t\t{\n\t\t\tBenchmark::DoNothing(c.find(pArrayBegin->first)->second);\n\t\t\t++pArrayBegin;\n\t\t}\n\t\tstopwatch.Stop();\n\t}\n\n\n\ttemplate \n\tvoid TestCount(EA::StdC::Stopwatch& stopwatch, Container& c, const Value* pArrayBegin, const Value* pArrayEnd)\n\t{\n\t\ttypename Container::size_type temp = 0;\n\t\tstopwatch.Restart();\n\t\twhile(pArrayBegin != pArrayEnd)\n\t\t{\n\t\t\ttemp += c.count(pArrayBegin->first);\n\t\t\t++pArrayBegin;\n\t\t}\n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%u\", (unsigned)temp);\n\t}\n\n\n\ttemplate \n\tvoid TestLowerBound(EA::StdC::Stopwatch& stopwatch, Container& c, const Value* pArrayBegin, const Value* pArrayEnd)\n\t{\n\t\tstopwatch.Restart();\n\t\twhile(pArrayBegin != pArrayEnd)\n\t\t{\n\t\t\tBenchmark::DoNothing(c.lower_bound(pArrayBegin->first)->second);\n\t\t\t++pArrayBegin;\n\t\t}\n\t\tstopwatch.Stop();\n\t}\n\n\n\ttemplate \n\tvoid TestUpperBound(EA::StdC::Stopwatch& stopwatch, Container& c, const Value* pArrayBegin, const Value* pArrayEnd)\n\t{\n\t\tstopwatch.Restart();\n\t\twhile(pArrayBegin != pArrayEnd)\n\t\t{\n\t\t\tBenchmark::DoNothing(c.upper_bound(pArrayBegin->first)->second);\n\t\t\t++pArrayBegin;\n\t\t}\n\t\tstopwatch.Stop();\n\t}\n\n\n\ttemplate \n\tvoid TestEqualRange(EA::StdC::Stopwatch& stopwatch, Container& c, const Value* pArrayBegin, const Value* pArrayEnd)\n\t{\n\t\tstopwatch.Restart();\n\t\twhile(pArrayBegin != pArrayEnd)\n\t\t{\n\t\t\tBenchmark::DoNothing(c.equal_range(pArrayBegin->first).second->second);\n\t\t\t++pArrayBegin;\n\t\t}\n\t\tstopwatch.Stop();\n\t}\n\n\n\ttemplate \n\tvoid TestEraseValue(EA::StdC::Stopwatch& stopwatch, Container& c, const Value* pArrayBegin, const Value* pArrayEnd)\n\t{\n\t\tstopwatch.Restart();\n\t\twhile(pArrayBegin != pArrayEnd)\n\t\t{\n\t\t\tc.erase(pArrayBegin->first);\n\t\t\t++pArrayBegin;\n\t\t}\n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%u\", (unsigned)c.size());\n\t}\n\n\n\ttemplate \n\tvoid TestErasePosition(EA::StdC::Stopwatch& stopwatch, Container& c)\n\t{\n\t\ttypename Container::size_type j, jEnd;\n\t\ttypename Container::iterator it;\n\n\t\tstopwatch.Restart();\n\t\tfor(j = 0, jEnd = c.size() / 3, it = c.begin(); j < jEnd; ++j)\n\t\t{\n\t\t\t// The erase fucntion is supposed to return an iterator, but the C++ standard was \n\t\t\t// not initially clear about it and some STL implementations don't do it correctly.\n\t\t\t#if (((defined(_MSC_VER) || defined(_CPPLIB_VER)) && !defined(_HAS_STRICT_CONFORMANCE))) // _CPPLIB_VER is something defined by Dinkumware STL.\n\t\t\t\tit = c.erase(it); // Standard behavior.\n\t\t\t#else\n\t\t\t\t// This pathway may execute at a slightly different speed than the \n\t\t\t\t// standard behaviour, but that's fine for the benchmark because the\n\t\t\t\t// benchmark is measuring the speed of erasing while iterating, and \n\t\t\t\t// however it needs to get done by the given STL is how it is measured.\n\t\t\t\tconst typename Container::iterator itErase(it++);\n\t\t\t\tc.erase(itErase);\n\t\t\t#endif\n\n\t\t\t++it;\n\t\t\t++it;\n\t\t}\n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%p %p\", &c, &it);\n\t}\n\n\n\ttemplate \n\tvoid TestEraseRange(EA::StdC::Stopwatch& stopwatch, Container& c)\n\t{\n\t\ttypename Container::size_type j, jEnd;\n\t\ttypename Container::iterator it1 = c.begin();\n\t\ttypename Container::iterator it2 = c.begin();\n\n\t\tfor(j = 0, jEnd = c.size() / 3; j < jEnd; ++j)\n\t\t\t++it2;\n\n\t\tstopwatch.Restart();\n\t\tc.erase(it1, it2);\n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%p %p %p\", &c, &it1, &it2);\n\t}\n\n\n\ttemplate \n\tvoid TestClear(EA::StdC::Stopwatch& stopwatch, Container& c)\n\t{\n\t\tstopwatch.Restart();\n\t\tc.clear();\n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%u\", (unsigned)c.size());\n\t}\n\n\n} // namespace\n\n\n\nvoid BenchmarkMap()\n{\n\tEASTLTest_Printf(\"Map\\n\");\n\n\tEA::UnitTest::Rand rng(EA::UnitTest::GetRandSeed());\n\tEA::StdC::Stopwatch stopwatch1(EA::StdC::Stopwatch::kUnitsCPUCycles);\n\tEA::StdC::Stopwatch stopwatch2(EA::StdC::Stopwatch::kUnitsCPUCycles);\n\n\t{\n\t\teastl::vector< std::pair > stdVector(10000);\n\t\teastl::vector< eastl::pair > eaVector(10000);\n\n\t\tfor(eastl_size_t i = 0, iEnd = stdVector.size(); i < iEnd; i++)\n\t\t{\n\t\t\tconst uint32_t n1 = rng.RandLimit(((uint32_t)iEnd / 2));\n\t\t\tconst uint32_t n2 = rng.RandValue();\n\n\t\t\tstdVector[i] = std::pair(TestObject(n1), n2);\n\t\t\teaVector[i] = eastl::pair(TestObject(n1), n2);\n\t\t}\n\n\t\tfor(int i = 0; i < 2; i++)\n\t\t{\n\t\t\tStdMapTOUint32 stdMapTOUint32;\n\t\t\tEaMapTOUint32 eaMapTOUint32;\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test insert(const value_type&)\n\t\t\t///////////////////////////////\n\t\t\tconst std::pair stdHighValue(TestObject(0x7fffffff), 0x7fffffff);\n\t\t\tconst eastl::pair eaHighValue(TestObject(0x7fffffff), 0x7fffffff);\n\n\t\t\tTestInsert(stopwatch1, stdMapTOUint32, stdVector.data(), stdVector.data() + stdVector.size(), stdHighValue);\n\t\t\tTestInsert(stopwatch2, eaMapTOUint32, eaVector.data(), eaVector.data() + eaVector.size(), eaHighValue);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"map/insert\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test iteration\n\t\t\t///////////////////////////////\n\n\t\t\tTestIteration(stopwatch1, stdMapTOUint32, StdMapTOUint32::value_type(TestObject(9999999), 9999999));\n\t\t\tTestIteration(stopwatch2, eaMapTOUint32, EaMapTOUint32::value_type(TestObject(9999999), 9999999));\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"map/iteration\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test operator[]\n\t\t\t///////////////////////////////\n\n\t\t\tTestBracket(stopwatch1, stdMapTOUint32, stdVector.data(), stdVector.data() + stdVector.size());\n\t\t\tTestBracket(stopwatch2, eaMapTOUint32, eaVector.data(), eaVector.data() + eaVector.size());\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"map/operator[]\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test find\n\t\t\t///////////////////////////////\n\n\t\t\tTestFind(stopwatch1, stdMapTOUint32, stdVector.data(), stdVector.data() + stdVector.size());\n\t\t\tTestFind(stopwatch2, eaMapTOUint32, eaVector.data(), eaVector.data() + eaVector.size());\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"map/find\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test count\n\t\t\t///////////////////////////////\n\n\t\t\tTestCount(stopwatch1, stdMapTOUint32, stdVector.data(), stdVector.data() + stdVector.size());\n\t\t\tTestCount(stopwatch2, eaMapTOUint32, eaVector.data(), eaVector.data() + eaVector.size());\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"map/count\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test lower_bound\n\t\t\t///////////////////////////////\n\n\t\t\tTestLowerBound(stopwatch1, stdMapTOUint32, stdVector.data(), stdVector.data() + stdVector.size());\n\t\t\tTestLowerBound(stopwatch2, eaMapTOUint32, eaVector.data(), eaVector.data() + eaVector.size());\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"map/lower_bound\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test upper_bound\n\t\t\t///////////////////////////////\n\n\t\t\tTestUpperBound(stopwatch1, stdMapTOUint32, stdVector.data(), stdVector.data() + stdVector.size());\n\t\t\tTestUpperBound(stopwatch2, eaMapTOUint32, eaVector.data(), eaVector.data() + eaVector.size());\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"map/upper_bound\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test equal_range\n\t\t\t///////////////////////////////\n\n\t\t\tTestEqualRange(stopwatch1, stdMapTOUint32, stdVector.data(), stdVector.data() + stdVector.size());\n\t\t\tTestEqualRange(stopwatch2, eaMapTOUint32, eaVector.data(), eaVector.data() + eaVector.size());\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"map/equal_range\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test erase(const key_type& key)\n\t\t\t///////////////////////////////\n\n\t\t\tTestEraseValue(stopwatch1, stdMapTOUint32, stdVector.data(), stdVector.data() + (stdVector.size() / 2));\n\t\t\tTestEraseValue(stopwatch2, eaMapTOUint32, eaVector.data(), eaVector.data() + (eaVector.size() / 2));\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"map/erase/key\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test erase(iterator position)\n\t\t\t///////////////////////////////\n\n\t\t\tTestErasePosition(stopwatch1, stdMapTOUint32);\n\t\t\tTestErasePosition(stopwatch2, eaMapTOUint32);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"map/erase/pos\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime(),\n\t\t\t\t\t\t\t\t\t\tGetStdSTLType() == kSTLMS ? \"MS uses a code bloating implementation of erase.\" : NULL);\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test erase(iterator first, iterator last)\n\t\t\t///////////////////////////////\n\n\t\t\tTestEraseRange(stopwatch1, stdMapTOUint32);\n\t\t\tTestEraseRange(stopwatch2, eaMapTOUint32);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"map/erase/range\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test clear()\n\t\t\t///////////////////////////////\n\n\t\t\tTestClear(stopwatch1, stdMapTOUint32);\n\t\t\tTestClear(stopwatch2, eaMapTOUint32);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"map/clear\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t}\n\t}\n}\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n" }, { "path": "benchmark/source/BenchmarkSet.cpp", "content": "/////////////////////////////////////////////////////////////////////////////\n// Copyright (c) Electronic Arts Inc. All rights reserved.\n/////////////////////////////////////////////////////////////////////////////\n\n\n#include \"EASTLBenchmark.h\"\n#include \"EASTLTest.h\"\n#include \n#include \n#include \n#include \n\nEA_DISABLE_ALL_VC_WARNINGS()\n#include \n#include \nEA_RESTORE_ALL_VC_WARNINGS()\n\n\nusing namespace EA;\n\n\ntypedef std::set StdSetUint32;\ntypedef eastl::set EaSetUint32;\n\n\nnamespace\n{\n\ttemplate \n\tvoid TestInsert(EA::StdC::Stopwatch& stopwatch, Container& c, const uint32_t* pArrayBegin, const uint32_t* pArrayEnd)\n\t{\n\t\tstopwatch.Restart();\n\t\tc.insert(pArrayBegin, pArrayEnd);\n\t\tstopwatch.Stop();\n\n\t\t// Intentionally push back a high uint32_t value. We do this so that \n\t\t// later upper_bound, lower_bound and equal_range never return end().\n\t\tc.insert(0xffffffff);\n\t}\n\n\n\ttemplate \n\tvoid TestIteration(EA::StdC::Stopwatch& stopwatch, const Container& c)\n\t{\n\t\tstopwatch.Restart();\n\t\ttypename Container::const_iterator it = eastl::find(c.begin(), c.end(), uint32_t(9999999));\n\t\tstopwatch.Stop();\n\t\tif(it != c.end())\n\t\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%u\", (unsigned)*it);\n\t}\n\n\n\ttemplate \n\tvoid TestFind(EA::StdC::Stopwatch& stopwatch, Container& c, const uint32_t* pArrayBegin, const uint32_t* pArrayEnd)\n\t{\n\t\tuint32_t temp = 0;\n\t\ttypename Container::iterator it;\n\t\tstopwatch.Restart();\n\t\twhile(pArrayBegin != pArrayEnd)\n\t\t{\n\t\t\tit = c.find(*pArrayBegin++);\n\t\t\ttemp += *it;\n\t\t}\n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%u\", (unsigned)temp);\n\t}\n\n\n\ttemplate \n\tvoid TestCount(EA::StdC::Stopwatch& stopwatch, Container& c, const uint32_t* pArrayBegin, const uint32_t* pArrayEnd)\n\t{\n\t\ttypename Container::size_type temp = 0;\n\t\tstopwatch.Restart();\n\t\twhile(pArrayBegin != pArrayEnd)\n\t\t\ttemp += c.count(*pArrayBegin++);\n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%u\", (unsigned)temp);\n\t}\n\n\n\ttemplate \n\tvoid TestLowerBound(EA::StdC::Stopwatch& stopwatch, Container& c, const uint32_t* pArrayBegin, const uint32_t* pArrayEnd)\n\t{\n\t\tuint32_t temp = 0;\n\t\ttypename Container::iterator it;\n\t\tstopwatch.Restart();\n\t\twhile(pArrayBegin != pArrayEnd)\n\t\t{\n\t\t\tit = c.lower_bound(*pArrayBegin++);\n\t\t\ttemp += *it; // We know that it != end because earlier we inserted 0xffffffff.\n\t\t}\n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%u\", (unsigned)temp);\n\t}\n\n\n\ttemplate \n\tvoid TestUpperBound(EA::StdC::Stopwatch& stopwatch, Container& c, const uint32_t* pArrayBegin, const uint32_t* pArrayEnd)\n\t{\n\t\tuint32_t temp = 0;\n\t\ttypename Container::iterator it;\n\t\tstopwatch.Restart();\n\t\twhile(pArrayBegin != pArrayEnd)\n\t\t{\n\t\t\tit = c.upper_bound(*pArrayBegin++);\n\t\t\ttemp += *it; // We know that it != end because earlier we inserted 0xffffffff.\n\t\t}\n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%u\", (unsigned)temp);\n\t}\n\n\n\ttemplate \n\tvoid TestEqualRange(EA::StdC::Stopwatch& stopwatch, Container& c, const uint32_t* pArrayBegin, const uint32_t* pArrayEnd)\n\t{\n\t\tuint32_t temp = 0;\n\t\tstopwatch.Restart();\n\t\twhile(pArrayBegin != pArrayEnd)\n\t\t{\n\t\t\ttemp += *(c.equal_range(*pArrayBegin++).first); // We know that it != end because earlier we inserted 0xffffffff.\n\t\t}\n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%u\", (unsigned)temp);\n\t}\n\n\n\ttemplate \n\tvoid TestEraseValue(EA::StdC::Stopwatch& stopwatch, Container& c, const uint32_t* pArrayBegin, const uint32_t* pArrayEnd)\n\t{\n\t\tstopwatch.Restart();\n\t\twhile(pArrayBegin != pArrayEnd)\n\t\t\tc.erase(*pArrayBegin++);\n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%u\", (unsigned)c.size());\n\t}\n\n\n\ttemplate \n\tvoid TestErasePosition(EA::StdC::Stopwatch& stopwatch, Container& c)\n\t{\n\t\ttypename Container::size_type j, jEnd;\n\t\ttypename Container::iterator it;\n\n\t\tstopwatch.Restart();\n\t\tfor(j = 0, jEnd = c.size() / 3, it = c.begin(); j < jEnd; ++j)\n\t\t{\n\t\t\t// The erase fucntion is supposed to return an iterator, but the C++ standard was \n\t\t\t// not initially clear about it and some STL implementations don't do it correctly.\n\t\t\t#if (((defined(_MSC_VER) || defined(_CPPLIB_VER)) && !defined(_HAS_STRICT_CONFORMANCE))) // _CPPLIB_VER is something defined by Dinkumware STL.\n\t\t\t\tit = c.erase(it);\n\t\t\t#else\n\t\t\t\t// This pathway may execute at a slightly different speed than the \n\t\t\t\t// standard behaviour, but that's fine for the benchmark because the\n\t\t\t\t// benchmark is measuring the speed of erasing while iterating, and \n\t\t\t\t// however it needs to get done by the given STL is how it is measured.\n\t\t\t\tconst typename Container::iterator itErase(it++);\n\t\t\t\tc.erase(itErase);\n\t\t\t#endif\n\n\t\t\t++it;\n\t\t\t++it;\n\t\t}\n\t\tstopwatch.Stop();\n\t}\n\n\n\ttemplate \n\tvoid TestEraseRange(EA::StdC::Stopwatch& stopwatch, Container& c)\n\t{\n\t\ttypename Container::size_type j, jEnd;\n\t\ttypename Container::iterator it1 = c.begin();\n\t\ttypename Container::iterator it2 = c.begin();\n\n\t\tfor(j = 0, jEnd = c.size() / 3; j < jEnd; ++j)\n\t\t\t++it2;\n\n\t\tstopwatch.Restart();\n\t\tc.erase(it1, it2);\n\t\tstopwatch.Stop();\n\t}\n\n\n\ttemplate \n\tvoid TestClear(EA::StdC::Stopwatch& stopwatch, Container& c)\n\t{\n\t\tstopwatch.Restart();\n\t\tc.clear();\n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%u\", (unsigned)c.size());\n\t}\n\n\n} // namespace\n\n\n\nvoid BenchmarkSet()\n{\n\tEASTLTest_Printf(\"Set\\n\");\n\n\tEA::UnitTest::Rand rng(EA::UnitTest::GetRandSeed());\n\tEA::StdC::Stopwatch stopwatch1(EA::StdC::Stopwatch::kUnitsCPUCycles);\n\tEA::StdC::Stopwatch stopwatch2(EA::StdC::Stopwatch::kUnitsCPUCycles);\n\n\t{\n\t\teastl::vector intVector(10000);\n\t\tfor(eastl_size_t i = 0, iEnd = intVector.size(); i < iEnd; i++)\n\t\t\tintVector[i] = (uint32_t)rng.RandLimit(((uint32_t)iEnd / 2)); // This will result in duplicates and even a few triplicates.\n\n\t\tfor(int i = 0; i < 2; i++)\n\t\t{\n\t\t\tStdSetUint32 stdSetUint32;\n\t\t\tEaSetUint32 eaSetUint32;\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test insert(const value_type&)\n\t\t\t///////////////////////////////\n\n\t\t\tTestInsert(stopwatch1, stdSetUint32, intVector.data(), intVector.data() + intVector.size());\n\t\t\tTestInsert(stopwatch2, eaSetUint32, intVector.data(), intVector.data() + intVector.size());\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"set/insert\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test iteration\n\t\t\t///////////////////////////////\n\n\t\t\tTestIteration(stopwatch1, stdSetUint32);\n\t\t\tTestIteration(stopwatch2, eaSetUint32);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"set/iteration\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test find\n\t\t\t///////////////////////////////\n\n\t\t\tTestFind(stopwatch1, stdSetUint32, intVector.data(), intVector.data() + intVector.size());\n\t\t\tTestFind(stopwatch2, eaSetUint32, intVector.data(), intVector.data() + intVector.size());\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"set/find\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test count\n\t\t\t///////////////////////////////\n\n\t\t\tTestCount(stopwatch1, stdSetUint32, intVector.data(), intVector.data() + intVector.size());\n\t\t\tTestCount(stopwatch2, eaSetUint32, intVector.data(), intVector.data() + intVector.size());\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"set/count\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test lower_bound\n\t\t\t///////////////////////////////\n\n\t\t\tTestLowerBound(stopwatch1, stdSetUint32, intVector.data(), intVector.data() + intVector.size());\n\t\t\tTestLowerBound(stopwatch2, eaSetUint32, intVector.data(), intVector.data() + intVector.size());\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"set/lower_bound\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test upper_bound\n\t\t\t///////////////////////////////\n\n\t\t\tTestUpperBound(stopwatch1, stdSetUint32, intVector.data(), intVector.data() + intVector.size());\n\t\t\tTestUpperBound(stopwatch2, eaSetUint32, intVector.data(), intVector.data() + intVector.size());\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"set/upper_bound\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test equal_range\n\t\t\t///////////////////////////////\n\n\t\t\tTestEqualRange(stopwatch1, stdSetUint32, intVector.data(), intVector.data() + intVector.size());\n\t\t\tTestEqualRange(stopwatch2, eaSetUint32, intVector.data(), intVector.data() + intVector.size());\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"set/equal_range\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test erase(const key_type& key)\n\t\t\t///////////////////////////////\n\n\t\t\tTestEraseValue(stopwatch1, stdSetUint32, &intVector[0], &intVector[intVector.size() / 2]);\n\t\t\tTestEraseValue(stopwatch2, eaSetUint32, &intVector[0], &intVector[intVector.size() / 2]);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"set/erase/val\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test erase(iterator position)\n\t\t\t///////////////////////////////\n\n\t\t\tTestErasePosition(stopwatch1, stdSetUint32);\n\t\t\tTestErasePosition(stopwatch2, eaSetUint32);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"set/erase/pos\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime(),\n\t\t\t\t\t\t\t\t\t\tGetStdSTLType() == kSTLMS ? \"MS uses a code bloating implementation of erase.\" : NULL);\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test erase(iterator first, iterator last)\n\t\t\t///////////////////////////////\n\n\t\t\tTestEraseRange(stopwatch1, stdSetUint32);\n\t\t\tTestEraseRange(stopwatch2, eaSetUint32);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"set/erase range\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test clear()\n\t\t\t///////////////////////////////\n\n\t\t\tTestClear(stopwatch1, stdSetUint32);\n\t\t\tTestClear(stopwatch2, eaSetUint32);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"set/clear\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t}\n\t}\n}\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n" }, { "path": "benchmark/source/BenchmarkSort.cpp", "content": "/////////////////////////////////////////////////////////////////////////////\n// Copyright (c) Electronic Arts Inc. All rights reserved.\n/////////////////////////////////////////////////////////////////////////////\n\n\n#include \n#include \n#include \n#include \n#include \"EASTLBenchmark.h\"\n#include \"EASTLTest.h\"\n\nEA_DISABLE_ALL_VC_WARNINGS()\n#include \n#include \n#include \n#include \nEA_RESTORE_ALL_VC_WARNINGS()\n\n\nusing namespace EA;\n\n\nnamespace\n{\n\tstruct ValuePair\n\t{\n\t\tuint32_t key;\n\t\tuint32_t v;\n\t};\n\n\tstruct VPCompare\n\t{\n\t\tbool operator()(const ValuePair& vp1, const ValuePair& vp2) const\n\t\t{\n\t\t\t// return *(const uint64_t*)&vp1 < *(const uint64_t*)&vp2;\n\t\t\treturn (vp1.key == vp2.key) ? (vp1.v < vp2.v) : (vp1.key < vp2.key);\n\t\t}\n\t};\n\n\tbool operator<(const ValuePair& vp1, const ValuePair& vp2)\n\t{\n\t\t// return *(const uint64_t*)&vp1 < *(const uint64_t*)&vp2;\n\t\treturn (vp1.key == vp2.key) ? (vp1.v < vp2.v) : (vp1.key < vp2.key);\n\t}\n\n\tbool operator==(const ValuePair& vp1, const ValuePair& vp2)\n\t{\n\t\t// return *(const uint64_t*)&vp1 == *(const uint64_t*)&vp2;\n\t\treturn (vp1.key == vp2.key) && (vp1.v == vp2.v);\n\t}\n}\n\n// VPCompareC\n// Useful for testing the the C qsort function.\nint VPCompareC(const void* elem1, const void* elem2)\n{\n\treturn (int)(*(const uint64_t*)elem1 - *(const uint64_t*)elem2);\n}\n\n\ntypedef std::vector StdVectorVP;\ntypedef eastl::vector EaVectorVP;\n\ntypedef std::vector StdVectorInt;\ntypedef eastl::vector EaVectorInt;\n\ntypedef std::vector StdVectorTO;\ntypedef eastl::vector EaVectorTO;\n\n\nnamespace\n{\n\t#ifndef EA_PREFIX_NO_INLINE\n\t\t#ifdef _MSC_VER\n\t\t\t#define EA_PREFIX_NO_INLINE EA_NO_INLINE\n\t\t\t#define EA_POSTFIX_NO_INLINE\n\t\t#else\n\t\t\t#define EA_PREFIX_NO_INLINE\n\t\t\t#define EA_POSTFIX_NO_INLINE EA_NO_INLINE\n\t\t#endif\n\t#endif\n\n\tEA_PREFIX_NO_INLINE void TestQuickSortStdVP (EA::StdC::Stopwatch& stopwatch, StdVectorVP& stdVectorVP) EA_POSTFIX_NO_INLINE;\n\tEA_PREFIX_NO_INLINE void TestQuickSortEaVP (EA::StdC::Stopwatch& stopwatch, EaVectorVP& eaVectorVP) EA_POSTFIX_NO_INLINE;\n\tEA_PREFIX_NO_INLINE void TestQuickSortStdInt(EA::StdC::Stopwatch& stopwatch, StdVectorInt& stdVectorInt) EA_POSTFIX_NO_INLINE;\n\tEA_PREFIX_NO_INLINE void TestQuickSortEaInt (EA::StdC::Stopwatch& stopwatch, EaVectorInt& eaVectorInt) EA_POSTFIX_NO_INLINE;\n\tEA_PREFIX_NO_INLINE void TestQuickSortStdTO (EA::StdC::Stopwatch& stopwatch, StdVectorTO& stdVectorTO) EA_POSTFIX_NO_INLINE;\n\tEA_PREFIX_NO_INLINE void TestQuickSortEaTO (EA::StdC::Stopwatch& stopwatch, EaVectorTO& eaVectorTO) EA_POSTFIX_NO_INLINE;\n\n\n\n\tvoid TestQuickSortStdVP(EA::StdC::Stopwatch& stopwatch, StdVectorVP& stdVectorVP)\n\t{\n\t\tstopwatch.Restart();\n\t\tstd::sort(stdVectorVP.begin(), stdVectorVP.end());\n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%u\", (unsigned)stdVectorVP[0].key);\n\t}\n\n\n\tvoid TestQuickSortEaVP(EA::StdC::Stopwatch& stopwatch, EaVectorVP& eaVectorVP)\n\t{\n\t\tstopwatch.Restart();\n\t\teastl::quick_sort(eaVectorVP.begin(), eaVectorVP.end());\n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%u\", (unsigned)eaVectorVP[0].key);\n\t}\n\n\n\tvoid TestQuickSortStdInt(EA::StdC::Stopwatch& stopwatch, StdVectorInt& stdVectorInt)\n\t{\n\t\tstopwatch.Restart();\n\t\tstd::sort(stdVectorInt.begin(), stdVectorInt.end());\n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%u\", (unsigned)stdVectorInt[0]);\n\t}\n\n\n\tvoid TestQuickSortEaInt(EA::StdC::Stopwatch& stopwatch, EaVectorInt& eaVectorInt)\n\t{\n\t\tstopwatch.Restart();\n\t\teastl::quick_sort(eaVectorInt.begin(), eaVectorInt.end());\n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%u\", (unsigned)eaVectorInt[0]);\n\t}\n\n\n\tvoid TestQuickSortStdTO(EA::StdC::Stopwatch& stopwatch, StdVectorTO& stdVectorTO)\n\t{\n\t\tstopwatch.Restart();\n\t\tstd::sort(stdVectorTO.begin(), stdVectorTO.end());\n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%u\", (unsigned)stdVectorTO[0].mX);\n\t}\n\n\n\tvoid TestQuickSortEaTO(EA::StdC::Stopwatch& stopwatch, EaVectorTO& eaVectorTO)\n\t{\n\t\tstopwatch.Restart();\n\t\teastl::quick_sort(eaVectorTO.begin(), eaVectorTO.end());\n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%u\", (unsigned)eaVectorTO[0].mX);\n\t}\n\n} // namespace\n\n\nnamespace\n{\n\tenum SortFunctionType\n\t{\n\t\tsf_qsort, // C qsort\n\t\tsf_shell_sort, // eastl::shell_sort.\n\t\tsf_heap_sort, // eastl::heap_sort\n\t\tsf_merge_sort, // eastl::merge_sort\n\t\tsf_merge_sort_buffer, // eastl::merge_sort_buffer\n\t\tsf_comb_sort, // eastl::comb_sort\n\t\tsf_bubble_sort, // eastl::bubble_sort\n\t\tsf_selection_sort, // eastl::selection_sort\n\t\tsf_shaker_sort, // eastl::shaker_sort\n\t\tsf_quick_sort, // eastl::quick_sort\n\t\tsf_tim_sort, // eastl::tim_sort\n\t\tsf_insertion_sort, // eastl::insertion_sort\n\t\tsf_std_sort, // std::sort\n\t\tsf_std_stable_sort, // std::stable_sort\n\t\tsf_radix_sort, // eastl::radix_sort (unconventional sort)\n\t\tsf_count //\n\t};\n\n\tconst char* GetSortFunctionName(int sortFunctionType)\n\t{\n\t\tswitch (sortFunctionType)\n\t\t{\n\t\t\tcase sf_quick_sort:\n\t\t\t\treturn \"eastl::sort\";\n\n\t\t\tcase sf_tim_sort:\n\t\t\t\treturn \"eastl::tim_sort\";\n\n\t\t\tcase sf_insertion_sort:\n\t\t\t\treturn \"eastl::insertion_sort\";\n\n\t\t\tcase sf_shell_sort:\n\t\t\t\treturn \"eastl::shell_sort\";\n\n\t\t\tcase sf_heap_sort:\n\t\t\t\treturn \"eastl::heap_sort\";\n\n\t\t\tcase sf_merge_sort:\n\t\t\t\treturn \"eastl::merge_sort\";\n\n\t\t\tcase sf_merge_sort_buffer:\n\t\t\t\treturn \"eastl::merge_sort_buffer\";\n\n\t\t\tcase sf_comb_sort:\n\t\t\t\treturn \"eastl::comb_sort\";\n\n\t\t\tcase sf_bubble_sort:\n\t\t\t\treturn \"eastl::bubble_sort\";\n\n\t\t\tcase sf_selection_sort:\n\t\t\t\treturn \"eastl::selection_sort\";\n\n\t\t\tcase sf_shaker_sort:\n\t\t\t\treturn \"eastl::shaker_sort\";\n\n\t\t\tcase sf_radix_sort:\n\t\t\t\treturn \"eastl::radix_sort\";\n\n\t\t\tcase sf_qsort:\n\t\t\t\treturn \"qsort\";\n\n\t\t\tcase sf_std_sort:\n\t\t\t\treturn \"std::sort\";\n\n\t\t\tcase sf_std_stable_sort:\n\t\t\t\treturn \"std::stable_sort\";\n\n\t\t\tdefault:\n\t\t\t\treturn \"unknown\";\n\t\t}\n\t}\n\n\n\tenum RandomizationType\n\t{\n\t\tkRandom, // Completely random data.\n\t\tkRandomSorted, // Random values already sorted.\n\t\tkOrdered, // Already sorted.\n\t\tkMostlyOrdered, // Partly sorted already.\n\t\tkRandomizationTypeCount\n\t};\n\n\tconst char* GetRandomizationTypeName(int randomizationType)\n\t{\n\t\tswitch (randomizationType)\n\t\t{\n\t\t\tcase kRandom:\n\t\t\t\treturn \"random\";\n\n\t\t\tcase kRandomSorted:\n\t\t\t\treturn \"random sorted\";\n\n\t\t\tcase kOrdered:\n\t\t\t\treturn \"ordered\";\n\n\t\t\tcase kMostlyOrdered:\n\t\t\t\treturn \"mostly ordered\";\n\n\t\t\tdefault:\n\t\t\t\treturn \"unknown\";\n\t\t}\n\t}\n\n\ttemplate \n\tvoid Randomize(eastl::vector& v, EA::UnitTest::RandGenT& rng, RandomizationType type)\n\t{\n\t\ttypedef RandomType value_type;\n\n\t\tswitch (type)\n\t\t{\n\t\t\tdefault:\n\t\t\tcase kRandomizationTypeCount: // We specify this only to avoid a compiler warning about not testing for it.\n\t\t\tcase kRandom:\n\t\t\t{\n\t\t\t\teastl::generate(v.begin(), v.end(), rng);\n\t\t\t\tbreak;\n\t\t\t}\n\n\t\t\tcase kRandomSorted:\n\t\t\t{\n\t\t\t\t// This randomization type differs from kOrdered because the set of values is random (but sorted), in the kOrdered\n\t\t\t\t// case the set of values is contiguous (i.e. 0, 1, ..., n) which can have different performance characteristics.\n\t\t\t\t// For example, radix_sort performs poorly for kOrdered.\n\t\t\t\teastl::generate(v.begin(), v.end(), rng);\n\t\t\t\teastl::sort(v.begin(), v.end());\n\t\t\t\tbreak;\n\t\t\t}\n\n\t\t\tcase kOrdered:\n\t\t\t{\n\t\t\t\tfor(eastl_size_t i = 0; i < v.size(); ++i)\n\t\t\t\t\tv[i] = value_type((value_type)i); // Note that value_type may be a struct and not an integer. Thus the casting and construction here.\n\t\t\t\tbreak;\n\t\t\t}\n\n\t\t\tcase kMostlyOrdered:\n\t\t\t{\n\t\t\t\tfor(eastl_size_t i = 0; i < v.size(); ++i)\n\t\t\t\t\tv[i] = value_type((value_type)i); // Note that value_type may be a struct and not an integer. Thus the casting and construction here.\n\n\t\t\t\t// We order random segments.\n\t\t\t\t// The algorithm below in practice will make slightly more than kPercentOrdered be ordered.\n\t\t\t\tconst eastl_size_t kPercentOrdered = 80; // In actuality, due to statistics, the actual ordered percent will be about 82-85%.\n\n\t\t\t\tfor(eastl_size_t n = 0, s = v.size(), nEnd = ((s < (100 - kPercentOrdered)) ? 1 : (s / (100 - kPercentOrdered))); n < nEnd; n++)\n\t\t\t\t{\n\t\t\t\t\teastl_size_t i = rng.mRand.RandLimit((uint32_t)s);\n\t\t\t\t\teastl_size_t j = rng.mRand.RandLimit((uint32_t)s);\n\n\t\t\t\t\teastl::swap(v[i], v[j]);\n\t\t\t\t}\n\n\t\t\t\tbreak;\n\t\t\t}\n\t\t}\n\t}\n\n\n\tchar gSlowAssignBuffer1[256] = {0, 0, 0, 0, 0, 0, 0, 0, 0, 0 /* ... */};\n\tchar gSlowAssignBuffer2[256] = {0, 0, 0, 0, 0, 0, 0, 0, 0, 0 /* ... */};\n\n\n\t// SlowAssign\n\t// Implements an object which has slow assign performance.\n\ttemplate \n\tstruct SlowAssign\n\t{\n\t\ttypedef T key_type;\n\t\tT x;\n\n\t\tstatic int nAssignCount;\n\n\t\tSlowAssign()\n\t\t\t{ x = 0; memcpy(gSlowAssignBuffer1, gSlowAssignBuffer2, sizeof(gSlowAssignBuffer1)); }\n\n\t\tSlowAssign(const SlowAssign& sa)\n\t\t\t{ ++nAssignCount; x = sa.x; memcpy(gSlowAssignBuffer1, gSlowAssignBuffer2, sizeof(gSlowAssignBuffer1)); }\n\n\t\tSlowAssign& operator=(const SlowAssign& sa)\n\t\t\t{ ++nAssignCount; x = sa.x; memcpy(gSlowAssignBuffer1, gSlowAssignBuffer2, sizeof(gSlowAssignBuffer1)); return *this; }\n\n\t\tSlowAssign& operator=(int a)\n\t\t\t{ x = (T)a; return *this; }\n\n\t\tstatic void Reset()\n\t\t\t{ nAssignCount = 0; }\n\t};\n\n\ttemplate<> int SlowAssign::nAssignCount = 0;\n\n\ttemplate \n\tbool operator <(const SlowAssign& a, const SlowAssign& b)\n\t\t{ return a.x < b.x; }\n\n\n\t// SlowCompare\n\t// Implements a compare which is N time slower than a simple integer compare.\n\ttemplate \n\tstruct SlowCompare\n\t{\n\t\tstatic int nCompareCount;\n\n\t\tbool operator()(T a, T b)\n\t\t{\n\t\t\t++nCompareCount;\n\n\t\t\treturn (a < b) && // It happens that gSlowAssignBuffer1 is always zeroed.\n\t\t\t (gSlowAssignBuffer1[0] == 0) && (gSlowAssignBuffer1[1] == 0) && (gSlowAssignBuffer1[1] == 0) &&\n\t\t\t (gSlowAssignBuffer1[2] == 0) && (gSlowAssignBuffer1[4] == 0) && (gSlowAssignBuffer1[5] == 0);\n\t\t}\n\n\t\tstatic void Reset() { nCompareCount = 0; }\n\t};\n\n\ttemplate <>\n\tint SlowCompare::nCompareCount = 0;\n\n\n\t// qsort callback functions\n\t// qsort compare function returns negative if b > a and positive if a > b.\n\ttemplate \n\tint CompareInteger(const void* a, const void* b)\n\t{\n\t\t// Even though you see the following in Internet example code, it doesn't work!\n\t\t// The reason is that it works only if a and b are both >= 0, otherwise large\n\t\t// values can cause integer register wraparound. A similar kind of problem happens\n\t\t// if you try to do the same thing with floating point value compares.\n\t\t// See http://www.akalin.cx/2006/06/23/on-the-qsort-comparison-function/\n\t\t// Internet exmaple code:\n\t\t// return *(const int32_t*)a - *(const int32_t*)b;\n\n\t\t// This double comparison might seem like it's crippling qsort against the\n\t\t// STL-based sorts which do a single compare. But consider that the returning\n\t\t// of -1, 0, +1 gives qsort more information, and its logic takes advantage\n\t\t// of that.\n\t\tif (*(const T*)a < *(const T*)b)\n\t\t\treturn -1;\n\t\tif (*(const T*)a > *(const T*)b)\n\t\t\treturn +1;\n\t\treturn 0;\n\t}\n\n\n\tint SlowCompareInt32(const void* a, const void* b)\n\t{\n\t\t++SlowCompare::nCompareCount;\n\n\t\t// This code is similar in performance to the C++ SlowCompare template functor above.\n\t\tif((gSlowAssignBuffer1[0] == 0) && (gSlowAssignBuffer1[1] == 0) &&\n\t\t (gSlowAssignBuffer1[1] == 0) && (gSlowAssignBuffer1[2] == 0) &&\n\t\t (gSlowAssignBuffer1[4] == 0) && (gSlowAssignBuffer1[5] == 0))\n\t\t{\n\t\t\tif (*(const int32_t*)a < *(const int32_t*)b)\n\t\t\t\treturn -1;\n\t\t\tif (*(const int32_t*)a > *(const int32_t*)b)\n\t\t\t\treturn +1;\n\t\t}\n\n\t\treturn 0;\n\t}\n\n\ttemplate \n\tstruct slow_assign_extract_radix_key\n\t{\n\t\ttypedef typename slow_assign_type::key_type radix_type;\n\n\t\tconst radix_type operator()(const slow_assign_type& obj) const\n\t\t{\n\t\t\treturn obj.x;\n\t\t}\n\t};\n\t\n\ttemplate \n\tstruct identity_extract_radix_key\n\t{\n\t\ttypedef integer_type radix_type;\n\n\t\tconst radix_type operator()(const integer_type& x) const\n\t\t{\n\t\t\treturn x;\n\t\t}\n\t};\n} // namespace\n\n\nstruct BenchmarkResult\n{\n\tuint64_t mTime;\n\tuint64_t mCompareCount;\n\tuint64_t mAssignCount;\n\n\tBenchmarkResult() : mTime(0), mCompareCount(0), mAssignCount(0) {}\n};\n\n\nint CompareSortPerformance()\n{\n\t// Sizes of arrays to be sorted.\n\tconst eastl_size_t kSizes[] = { 10, 100, 1000, 10000 };\n\tconst eastl_size_t kSizesCount = EAArrayCount(kSizes);\n\tstatic BenchmarkResult sResults[kRandomizationTypeCount][kSizesCount][sf_count];\n\tint nErrorCount = 0;\n\n\tEA::UnitTest::ReportVerbosity(2, \"Sort comparison\\n\");\n\tEA::UnitTest::ReportVerbosity(2, \"Random seed = %u\\n\", (unsigned)EA::UnitTest::GetRandSeed());\n\n\tEA::UnitTest::RandGenT rng(EA::UnitTest::GetRandSeed());\n\tEA::StdC::Stopwatch stopwatch(EA::StdC::Stopwatch::kUnitsCPUCycles);\n\tEA::StdC::Stopwatch stopwatchGlobal(EA::StdC::Stopwatch::kUnitsSeconds);\n\tconst eastl_size_t kArraySizeMax = *eastl::max_element(eastl::begin(kSizes), eastl::end(kSizes));\n\tconst int kRunCount = 4;\n\n\t#if !defined(EA_DEBUG)\n\t\tEA::UnitTest::SetHighThreadPriority();\n\t#endif\n\n\teastl::vector allSortFunctions;\n\tfor (int i = 0; i < sf_count; i++)\n\t{\n\t\tallSortFunctions.push_back(SortFunctionType(i));\n\t}\n\n\t{\n\t\tauto& sortFunctions = allSortFunctions;\n\n\t\t// Regular speed test.\n\t\t// In this case we test the sorting of integral values.\n\t\t// This is probably the most common type of comparison.\n\t\tEA::UnitTest::ReportVerbosity(2, \"Sort comparison: Regular speed test\\n\");\n\n\t\ttypedef uint32_t ElementType;\n\t\ttypedef eastl::less CompareFunction;\n\n\t\teastl::string sOutput;\n\t\tsOutput.set_capacity(100000);\n\t\tElementType* pBuffer = new ElementType[kArraySizeMax];\n\n\t\tmemset(sResults, 0, sizeof(sResults));\n\n\t\tstopwatchGlobal.Restart();\n\n\t\tfor (int c = 0; c < kRunCount; c++)\n\t\t{\n\t\t\tfor (int i = 0; i < kRandomizationTypeCount; i++)\n\t\t\t{\n\t\t\t\tfor (size_t sizeType = 0; sizeType < EAArrayCount(kSizes); sizeType++)\n\t\t\t\t{\n\t\t\t\t\tconst eastl_size_t size = kSizes[sizeType];\n\n\t\t\t\t\tfor (SortFunctionType sortFunction : sortFunctions)\n\t\t\t\t\t{\n\t\t\t\t\t\teastl::vector v(size);\n\n\t\t\t\t\t\trng.SetSeed(EA::UnitTest::GetRandSeed());\n\t\t\t\t\t\tRandomize(v, rng, (RandomizationType)i);\n\n\t\t\t\t\t\tswitch (sortFunction)\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\tcase sf_quick_sort:\n\t\t\t\t\t\t\t\tstopwatch.Restart();\n\t\t\t\t\t\t\t\teastl::quick_sort(v.begin(), v.end(), CompareFunction());\n\t\t\t\t\t\t\t\tstopwatch.Stop();\n\t\t\t\t\t\t\t\tbreak;\n\n\t\t\t\t\t\t\tcase sf_tim_sort:\n\t\t\t\t\t\t\t\tstopwatch.Restart();\n\t\t\t\t\t\t\t\teastl::tim_sort_buffer(v.begin(), v.end(), pBuffer, CompareFunction());\n\t\t\t\t\t\t\t\tstopwatch.Stop();\n\t\t\t\t\t\t\t\tbreak;\n\n\t\t\t\t\t\t\tcase sf_insertion_sort:\n\t\t\t\t\t\t\t\tstopwatch.Restart();\n\t\t\t\t\t\t\t\teastl::insertion_sort(v.begin(), v.end(), CompareFunction());\n\t\t\t\t\t\t\t\tstopwatch.Stop();\n\t\t\t\t\t\t\t\tbreak;\n\n\t\t\t\t\t\t\tcase sf_shell_sort:\n\t\t\t\t\t\t\t\tstopwatch.Restart();\n\t\t\t\t\t\t\t\teastl::shell_sort(v.begin(), v.end(), CompareFunction());\n\t\t\t\t\t\t\t\tstopwatch.Stop();\n\t\t\t\t\t\t\t\tbreak;\n\n\t\t\t\t\t\t\tcase sf_heap_sort:\n\t\t\t\t\t\t\t\tstopwatch.Restart();\n\t\t\t\t\t\t\t\teastl::heap_sort(v.begin(), v.end(), CompareFunction());\n\t\t\t\t\t\t\t\tstopwatch.Stop();\n\t\t\t\t\t\t\t\tbreak;\n\n\t\t\t\t\t\t\tcase sf_merge_sort:\n\t\t\t\t\t\t\t\tstopwatch.Restart();\n\t\t\t\t\t\t\t\teastl::merge_sort(v.begin(), v.end(), *get_default_allocator((EASTLAllocatorType*)NULL), CompareFunction());\n\t\t\t\t\t\t\t\tstopwatch.Stop();\n\t\t\t\t\t\t\t\tbreak;\n\n\t\t\t\t\t\t\tcase sf_merge_sort_buffer:\n\t\t\t\t\t\t\t\tstopwatch.Restart();\n\t\t\t\t\t\t\t\teastl::merge_sort_buffer(v.begin(), v.end(), pBuffer, CompareFunction());\n\t\t\t\t\t\t\t\tstopwatch.Stop();\n\t\t\t\t\t\t\t\tbreak;\n\n\t\t\t\t\t\t\tcase sf_comb_sort:\n\t\t\t\t\t\t\t\tstopwatch.Restart();\n\t\t\t\t\t\t\t\teastl::comb_sort(v.begin(), v.end(), CompareFunction());\n\t\t\t\t\t\t\t\tstopwatch.Stop();\n\t\t\t\t\t\t\t\tbreak;\n\n\t\t\t\t\t\t\tcase sf_bubble_sort:\n\t\t\t\t\t\t\t\tstopwatch.Restart();\n\t\t\t\t\t\t\t\teastl::bubble_sort(v.begin(), v.end(), CompareFunction());\n\t\t\t\t\t\t\t\tstopwatch.Stop();\n\t\t\t\t\t\t\t\tbreak;\n\n\t\t\t\t\t\t\tcase sf_selection_sort:\n\t\t\t\t\t\t\t\tstopwatch.Restart();\n\t\t\t\t\t\t\t\teastl::selection_sort(v.begin(), v.end(), CompareFunction());\n\t\t\t\t\t\t\t\tstopwatch.Stop();\n\t\t\t\t\t\t\t\tbreak;\n\n\t\t\t\t\t\t\tcase sf_shaker_sort:\n\t\t\t\t\t\t\t\tstopwatch.Restart();\n\t\t\t\t\t\t\t\teastl::shaker_sort(v.begin(), v.end(), CompareFunction());\n\t\t\t\t\t\t\t\tstopwatch.Stop();\n\t\t\t\t\t\t\t\tbreak;\n\n\t\t\t\t\t\t\tcase sf_radix_sort:\n\t\t\t\t\t\t\t\tstopwatch.Restart();\n\t\t\t\t\t\t\t\teastl::radix_sort>(v.begin(), v.end(), pBuffer);\n\t\t\t\t\t\t\t\tstopwatch.Stop();\n\t\t\t\t\t\t\t\tbreak;\n\n\t\t\t\t\t\t\tcase sf_qsort:\n\t\t\t\t\t\t\t\tstopwatch.Restart();\n\t\t\t\t\t\t\t\tqsort(&v[0], (size_t)v.size(), sizeof(ElementType), CompareInteger);\n\t\t\t\t\t\t\t\tstopwatch.Stop();\n\t\t\t\t\t\t\t\tbreak;\n\n\t\t\t\t\t\t\tcase sf_std_sort:\n\t\t\t\t\t\t\t\tstopwatch.Restart();\n\t\t\t\t\t\t\t\tstd::sort(v.data(), v.data() + v.size(), std::less());\n\t\t\t\t\t\t\t\tstopwatch.Stop();\n\t\t\t\t\t\t\t\tbreak;\n\n\t\t\t\t\t\t\tcase sf_std_stable_sort:\n\t\t\t\t\t\t\t\tstopwatch.Restart();\n\t\t\t\t\t\t\t\tstd::stable_sort(v.data(), v.data() + v.size(), std::less());\n\t\t\t\t\t\t\t\tstopwatch.Stop();\n\t\t\t\t\t\t\t\tbreak;\n\n\t\t\t\t\t\t\tcase sf_count:\n\t\t\t\t\t\t\tdefault:\n\t\t\t\t\t\t\t\t// unsupported\n\t\t\t\t\t\t\t\tbreak;\n\t\t\t\t\t\t}\n\n\t\t\t\t\t\tconst uint64_t elapsedTime = (uint64_t)stopwatch.GetElapsedTime();\n\n\t\t\t\t\t\t// If this result was faster than a previously fastest result, record this one instead.\n\t\t\t\t\t\tif ((c == 0) || (elapsedTime < sResults[i][sizeType][sortFunction].mTime))\n\t\t\t\t\t\t\tsResults[i][sizeType][sortFunction].mTime = elapsedTime;\n\n\t\t\t\t\t\tVERIFY(eastl::is_sorted(v.begin(), v.end()));\n\n\t\t\t\t\t} // for each sort function...\n\n\t\t\t\t} // for each size type...\n\n\t\t\t} // for each randomization type...\n\n\t\t} // for each run\n\n\t\tEA::UnitTest::ReportVerbosity(2, \"Total time: %.2f s\\n\", stopwatchGlobal.GetElapsedTimeFloat());\n\n\t\tdelete[] pBuffer;\n\n\t\t// Now print the results.\n\t\tfor (int i = 0; i < kRandomizationTypeCount; i++)\n\t\t{\n\t\t\tfor (size_t sizeType = 0; sizeType < EAArrayCount(kSizes); sizeType++)\n\t\t\t{\n\t\t\t\tconst eastl_size_t size = kSizes[sizeType];\n\n\t\t\t\tfor (SortFunctionType sortFunction : sortFunctions)\n\t\t\t\t{\n\t\t\t\t\tsOutput.append_sprintf(\"%25s, %14s, Size: %8u, Time: %14\" PRIu64 \" ticks %0.2f ticks/elem\\n\",\n\t\t\t\t\t GetSortFunctionName(sortFunction), GetRandomizationTypeName(i),\n\t\t\t\t\t (unsigned)size, sResults[i][sizeType][sortFunction].mTime,\n\t\t\t\t\t float(sResults[i][sizeType][sortFunction].mTime)/float(size));\n\t\t\t\t}\n\t\t\t\tsOutput.append(\"\\n\");\n\t\t\t}\n\t\t}\n\n\t\tEA::UnitTest::ReportVerbosity(2, \"%s\\n\\n\", sOutput.c_str());\n\t}\n\n\t{\n\t\t// Do a speed test for the case of slow compares.\n\t\t// By this we mean to compare sorting speeds when the comparison of elements is slow.\n\t\t// Sort functions use element comparison to tell where elements go and use element\n\t\t// movement to get them there. But some sorting functions accomplish sorting performance by\n\t\t// minimizing the amount of movement, some minimize the amount of comparisons, and the\n\t\t// best do a good job of minimizing both.\n\t\tauto sortFunctions = allSortFunctions;\n\t\t// We can't test this radix_sort because what we need isn't exposed.\n\t\tsortFunctions.erase(eastl::remove(sortFunctions.begin(), sortFunctions.end(), sf_radix_sort), sortFunctions.end());\n\t\tEA::UnitTest::ReportVerbosity(2, \"Sort comparison: Slow compare speed test\\n\");\n\n\t\ttypedef int32_t ElementType;\n\t\ttypedef SlowCompare CompareFunction;\n\n\t\teastl::string sOutput;\n\t\tsOutput.set_capacity(100000);\n\t\tElementType* pBuffer = new ElementType[kArraySizeMax];\n\n\t\tmemset(sResults, 0, sizeof(sResults));\n\n\t\tstopwatchGlobal.Restart();\n\n\t\tfor (int c = 0; c < kRunCount; c++)\n\t\t{\n\t\t\tfor (int i = 0; i < kRandomizationTypeCount; i++)\n\t\t\t{\n\t\t\t\tfor (size_t sizeType = 0; sizeType < EAArrayCount(kSizes); sizeType++)\n\t\t\t\t{\n\t\t\t\t\tconst eastl_size_t size = kSizes[sizeType];\n\n\t\t\t\t\tfor (SortFunctionType sortFunction : sortFunctions)\n\t\t\t\t\t{\n\t\t\t\t\t\teastl::vector v(size);\n\n\t\t\t\t\t\trng.SetSeed(EA::UnitTest::GetRandSeed());\n\t\t\t\t\t\tRandomize(v, rng, (RandomizationType)i);\n\t\t\t\t\t\tCompareFunction::Reset();\n\n\t\t\t\t\t\tswitch (sortFunction)\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\tcase sf_quick_sort:\n\t\t\t\t\t\t\t\tstopwatch.Restart();\n\t\t\t\t\t\t\t\teastl::quick_sort(v.begin(), v.end(), CompareFunction());\n\t\t\t\t\t\t\t\tstopwatch.Stop();\n\t\t\t\t\t\t\t\tbreak;\n\n\t\t\t\t\t\t\tcase sf_tim_sort:\n\t\t\t\t\t\t\t\tstopwatch.Restart();\n\t\t\t\t\t\t\t\teastl::tim_sort_buffer(v.begin(), v.end(), pBuffer, CompareFunction());\n\t\t\t\t\t\t\t\tstopwatch.Stop();\n\t\t\t\t\t\t\t\tbreak;\n\n\t\t\t\t\t\t\tcase sf_insertion_sort:\n\t\t\t\t\t\t\t\tstopwatch.Restart();\n\t\t\t\t\t\t\t\teastl::insertion_sort(v.begin(), v.end(), CompareFunction());\n\t\t\t\t\t\t\t\tstopwatch.Stop();\n\t\t\t\t\t\t\t\tbreak;\n\n\t\t\t\t\t\t\tcase sf_shell_sort:\n\t\t\t\t\t\t\t\tstopwatch.Restart();\n\t\t\t\t\t\t\t\teastl::shell_sort(v.begin(), v.end(), CompareFunction());\n\t\t\t\t\t\t\t\tstopwatch.Stop();\n\t\t\t\t\t\t\t\tbreak;\n\n\t\t\t\t\t\t\tcase sf_heap_sort:\n\t\t\t\t\t\t\t\tstopwatch.Restart();\n\t\t\t\t\t\t\t\teastl::heap_sort(v.begin(), v.end(), CompareFunction());\n\t\t\t\t\t\t\t\tstopwatch.Stop();\n\t\t\t\t\t\t\t\tbreak;\n\n\t\t\t\t\t\t\tcase sf_merge_sort:\n\t\t\t\t\t\t\t\tstopwatch.Restart();\n\t\t\t\t\t\t\t\teastl::merge_sort(v.begin(), v.end(), *get_default_allocator((EASTLAllocatorType*)NULL), CompareFunction());\n\t\t\t\t\t\t\t\tstopwatch.Stop();\n\t\t\t\t\t\t\t\tbreak;\n\n\t\t\t\t\t\t\tcase sf_merge_sort_buffer:\n\t\t\t\t\t\t\t\tstopwatch.Restart();\n\t\t\t\t\t\t\t\teastl::merge_sort_buffer(v.begin(), v.end(), pBuffer, CompareFunction());\n\t\t\t\t\t\t\t\tstopwatch.Stop();\n\t\t\t\t\t\t\t\tbreak;\n\n\t\t\t\t\t\t\tcase sf_comb_sort:\n\t\t\t\t\t\t\t\tstopwatch.Restart();\n\t\t\t\t\t\t\t\teastl::comb_sort(v.begin(), v.end(), CompareFunction());\n\t\t\t\t\t\t\t\tstopwatch.Stop();\n\t\t\t\t\t\t\t\tbreak;\n\n\t\t\t\t\t\t\tcase sf_bubble_sort:\n\t\t\t\t\t\t\t\tstopwatch.Restart();\n\t\t\t\t\t\t\t\teastl::bubble_sort(v.begin(), v.end(), CompareFunction());\n\t\t\t\t\t\t\t\tstopwatch.Stop();\n\t\t\t\t\t\t\t\tbreak;\n\n\t\t\t\t\t\t\tcase sf_selection_sort:\n\t\t\t\t\t\t\t\tstopwatch.Restart();\n\t\t\t\t\t\t\t\teastl::selection_sort(v.begin(), v.end(), CompareFunction());\n\t\t\t\t\t\t\t\tstopwatch.Stop();\n\t\t\t\t\t\t\t\tbreak;\n\n\t\t\t\t\t\t\tcase sf_shaker_sort:\n\t\t\t\t\t\t\t\tstopwatch.Restart();\n\t\t\t\t\t\t\t\teastl::shaker_sort(v.begin(), v.end(), CompareFunction());\n\t\t\t\t\t\t\t\tstopwatch.Stop();\n\t\t\t\t\t\t\t\tbreak;\n\n\t\t\t\t\t\t\tcase sf_qsort:\n\t\t\t\t\t\t\t\tstopwatch.Restart();\n\t\t\t\t\t\t\t\tqsort(&v[0], (size_t)v.size(), sizeof(ElementType), SlowCompareInt32);\n\t\t\t\t\t\t\t\tstopwatch.Stop();\n\t\t\t\t\t\t\t\tbreak;\n\n\t\t\t\t\t\t\tcase sf_std_sort:\n\t\t\t\t\t\t\t\tstopwatch.Restart();\n\t\t\t\t\t\t\t\tstd::sort(v.begin(), v.end(), CompareFunction());\n\t\t\t\t\t\t\t\tstopwatch.Stop();\n\t\t\t\t\t\t\t\tbreak;\n\n\t\t\t\t\t\t\tcase sf_std_stable_sort:\n\t\t\t\t\t\t\t\tstopwatch.Restart();\n\t\t\t\t\t\t\t\tstd::stable_sort(v.begin(), v.end(), CompareFunction());\n\t\t\t\t\t\t\t\tstopwatch.Stop();\n\t\t\t\t\t\t\t\tbreak;\n\n\t\t\t\t\t\t\tcase sf_radix_sort:\n\t\t\t\t\t\t\tcase sf_count:\n\t\t\t\t\t\t\tdefault:\n\t\t\t\t\t\t\t\t// unsupported\n\t\t\t\t\t\t\t\tbreak;\n\t\t\t\t\t\t}\n\n\t\t\t\t\t\tconst uint64_t elapsedTime = (uint64_t)stopwatch.GetElapsedTime();\n\n\t\t\t\t\t\t// If this result was faster than a previously fastest result, record this one instead.\n\t\t\t\t\t\tif ((c == 0) || (elapsedTime < sResults[i][sizeType][sortFunction].mTime))\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\tsResults[i][sizeType][sortFunction].mTime = elapsedTime;\n\t\t\t\t\t\t\tsResults[i][sizeType][sortFunction].mCompareCount = (uint64_t)CompareFunction::nCompareCount;\n\t\t\t\t\t\t}\n\n\t\t\t\t\t\tVERIFY(eastl::is_sorted(v.begin(), v.end()));\n\t\t\t\t\t} // for each sort function...\n\n\t\t\t\t} // for each size type...\n\n\t\t\t} // for each randomization type...\n\n\t\t} // for each run\n\n\t\tEA::UnitTest::ReportVerbosity(2, \"Total time: %.2f s\\n\", stopwatchGlobal.GetElapsedTimeFloat());\n\n\t\tdelete[] pBuffer;\n\n\t\t// Now print the results.\n\t\tfor (int i = 0; i < kRandomizationTypeCount; i++)\n\t\t{\n\t\t\tfor (size_t sizeType = 0; sizeType < EAArrayCount(kSizes); sizeType++)\n\t\t\t{\n\t\t\t\tconst eastl_size_t size = kSizes[sizeType];\n\n\t\t\t\tfor (SortFunctionType sortFunction : sortFunctions)\n\t\t\t\t{\n\t\t\t\t\tsOutput.append_sprintf(\"%25s, %14s, Size: %6u, Time: %11\" PRIu64 \" ticks, Compares: %11\" PRIu64 \"\\n\",\n\t\t\t\t\t GetSortFunctionName(sortFunction), GetRandomizationTypeName(i),\n\t\t\t\t\t (unsigned)size, sResults[i][sizeType][sortFunction].mTime,\n\t\t\t\t\t sResults[i][sizeType][sortFunction].mCompareCount);\n\t\t\t\t}\n\n\t\t\t\tsOutput.append(\"\\n\");\n\t\t\t}\n\t\t}\n\n\t\tEA::UnitTest::ReportVerbosity(2, \"%s\\n\\n\", sOutput.c_str());\n\t}\n\n\t{\n\t\t// Do a speed test for the case of slow assignment.\n\t\t// By this we mean to compare sorting speeds when the movement of elements is slow.\n\t\t// Sort functions use element comparison to tell where elements go and use element\n\t\t// movement to get them there. But some sorting functions accomplish sorting performance by\n\t\t// minimizing the amount of movement, some minimize the amount of comparisons, and the\n\t\t// best do a good job of minimizing both.\n\t\tauto sortFunctions = allSortFunctions;\n\t\t// Can't implement this for qsort because the C standard library doesn't expose it.\n\t\t// We could implement it by copying and modifying the source code.\n\t\tsortFunctions.erase(eastl::remove(sortFunctions.begin(), sortFunctions.end(), sf_qsort), sortFunctions.end());\n\n\t\tEA::UnitTest::ReportVerbosity(2, \"Sort comparison: Slow assignment speed test\\n\");\n\n\t\ttypedef SlowAssign ElementType;\n\t\ttypedef eastl::less CompareFunction;\n\n\t\teastl::string sOutput;\n\t\tsOutput.set_capacity(100000);\n\t\tElementType* pBuffer = new ElementType[kArraySizeMax];\n\n\t\tmemset(sResults, 0, sizeof(sResults));\n\n\t\tstopwatchGlobal.Restart();\n\n\t\tfor (int c = 0; c < kRunCount; c++)\n\t\t{\n\t\t\tfor (int i = 0; i < kRandomizationTypeCount; i++)\n\t\t\t{\n\t\t\t\tfor (size_t sizeType = 0; sizeType < EAArrayCount(kSizes); sizeType++)\n\t\t\t\t{\n\t\t\t\t\tconst eastl_size_t size = kSizes[sizeType];\n\n\t\t\t\t\tfor (SortFunctionType sortFunction : sortFunctions)\n\t\t\t\t\t{\n\t\t\t\t\t\teastl::vector v(size);\n\n\t\t\t\t\t\tRandomize(v, rng, (RandomizationType)i);\n\t\t\t\t\t\tElementType::Reset();\n\n\t\t\t\t\t\tswitch (sortFunction)\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\tcase sf_quick_sort:\n\t\t\t\t\t\t\t\tstopwatch.Restart();\n\t\t\t\t\t\t\t\teastl::quick_sort(v.begin(), v.end(), CompareFunction());\n\t\t\t\t\t\t\t\tstopwatch.Stop();\n\t\t\t\t\t\t\t\tbreak;\n\n\t\t\t\t\t\t\tcase sf_tim_sort:\n\t\t\t\t\t\t\t\tstopwatch.Restart();\n\t\t\t\t\t\t\t\teastl::tim_sort_buffer(v.begin(), v.end(), pBuffer, CompareFunction());\n\t\t\t\t\t\t\t\tstopwatch.Stop();\n\t\t\t\t\t\t\t\tbreak;\n\n\t\t\t\t\t\t\tcase sf_insertion_sort:\n\t\t\t\t\t\t\t\tstopwatch.Restart();\n\t\t\t\t\t\t\t\teastl::insertion_sort(v.begin(), v.end(), CompareFunction());\n\t\t\t\t\t\t\t\tstopwatch.Stop();\n\t\t\t\t\t\t\t\tbreak;\n\n\t\t\t\t\t\t\tcase sf_shell_sort:\n\t\t\t\t\t\t\t\tstopwatch.Restart();\n\t\t\t\t\t\t\t\teastl::shell_sort(v.begin(), v.end(), CompareFunction());\n\t\t\t\t\t\t\t\tstopwatch.Stop();\n\t\t\t\t\t\t\t\tbreak;\n\n\t\t\t\t\t\t\tcase sf_heap_sort:\n\t\t\t\t\t\t\t\tstopwatch.Restart();\n\t\t\t\t\t\t\t\teastl::heap_sort(v.begin(), v.end(), CompareFunction());\n\t\t\t\t\t\t\t\tstopwatch.Stop();\n\t\t\t\t\t\t\t\tbreak;\n\n\t\t\t\t\t\t\tcase sf_merge_sort:\n\t\t\t\t\t\t\t\tstopwatch.Restart();\n\t\t\t\t\t\t\t\teastl::merge_sort(v.begin(), v.end(), *get_default_allocator((EASTLAllocatorType*)NULL), CompareFunction());\n\t\t\t\t\t\t\t\tstopwatch.Stop();\n\t\t\t\t\t\t\t\tbreak;\n\n\t\t\t\t\t\t\tcase sf_merge_sort_buffer:\n\t\t\t\t\t\t\t\tstopwatch.Restart();\n\t\t\t\t\t\t\t\teastl::merge_sort_buffer(v.begin(), v.end(), pBuffer, CompareFunction());\n\t\t\t\t\t\t\t\tstopwatch.Stop();\n\t\t\t\t\t\t\t\tbreak;\n\n\t\t\t\t\t\t\tcase sf_comb_sort:\n\t\t\t\t\t\t\t\tstopwatch.Restart();\n\t\t\t\t\t\t\t\teastl::comb_sort(v.begin(), v.end(), CompareFunction());\n\t\t\t\t\t\t\t\tstopwatch.Stop();\n\t\t\t\t\t\t\t\tbreak;\n\n\t\t\t\t\t\t\tcase sf_bubble_sort:\n\t\t\t\t\t\t\t\tstopwatch.Restart();\n\t\t\t\t\t\t\t\teastl::bubble_sort(v.begin(), v.end(), CompareFunction());\n\t\t\t\t\t\t\t\tstopwatch.Stop();\n\t\t\t\t\t\t\t\tbreak;\n\n\t\t\t\t\t\t\tcase sf_selection_sort:\n\t\t\t\t\t\t\t\tstopwatch.Restart();\n\t\t\t\t\t\t\t\teastl::selection_sort(v.begin(), v.end(), CompareFunction());\n\t\t\t\t\t\t\t\tstopwatch.Stop();\n\t\t\t\t\t\t\t\tbreak;\n\n\t\t\t\t\t\t\tcase sf_shaker_sort:\n\t\t\t\t\t\t\t\tstopwatch.Restart();\n\t\t\t\t\t\t\t\teastl::shaker_sort(v.begin(), v.end(), CompareFunction());\n\t\t\t\t\t\t\t\tstopwatch.Stop();\n\t\t\t\t\t\t\t\tbreak;\n\n\t\t\t\t\t\t\tcase sf_radix_sort:\n\t\t\t\t\t\t\t\tstopwatch.Restart();\n\t\t\t\t\t\t\t\teastl::radix_sort>(v.begin(), v.end(), pBuffer);\n\t\t\t\t\t\t\t\tstopwatch.Stop();\n\t\t\t\t\t\t\t\tbreak;\n\n\t\t\t\t\t\t\tcase sf_std_sort:\n\t\t\t\t\t\t\t\tstopwatch.Restart();\n\t\t\t\t\t\t\t\tstd::sort(v.begin(), v.end(), std::less());\n\t\t\t\t\t\t\t\tstopwatch.Stop();\n\t\t\t\t\t\t\t\tbreak;\n\n\t\t\t\t\t\t\tcase sf_std_stable_sort:\n\t\t\t\t\t\t\t\tstopwatch.Restart();\n\t\t\t\t\t\t\t\tstd::stable_sort(v.begin(), v.end(), std::less());\n\t\t\t\t\t\t\t\tstopwatch.Stop();\n\t\t\t\t\t\t\t\tbreak;\n\n\t\t\t\t\t\t\tcase sf_qsort:\n\t\t\t\t\t\t\tcase sf_count:\n\t\t\t\t\t\t\tdefault:\n\t\t\t\t\t\t\t\t// unsupported\n\t\t\t\t\t\t\t\tbreak;\n\t\t\t\t\t\t}\n\n\t\t\t\t\t\tconst uint64_t elapsedTime = (uint64_t)stopwatch.GetElapsedTime();\n\n\t\t\t\t\t\t// If this result was faster than a previously fastest result, record this one instead.\n\t\t\t\t\t\tif ((c == 0) || (elapsedTime < sResults[i][sizeType][sortFunction].mTime))\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\tsResults[i][sizeType][sortFunction].mTime = elapsedTime;\n\t\t\t\t\t\t\tsResults[i][sizeType][sortFunction].mAssignCount = (uint64_t)ElementType::nAssignCount;\n\t\t\t\t\t\t}\n\n\t\t\t\t\t\tVERIFY(eastl::is_sorted(v.begin(), v.end()));\n\n\t\t\t\t\t} // for each sort function...\n\n\t\t\t\t} // for each size type...\n\n\t\t\t} // for each randomization type...\n\n\t\t} // for each run\n\n\t\tEA::UnitTest::ReportVerbosity(2, \"Total time: %.2f s\\n\", stopwatchGlobal.GetElapsedTimeFloat());\n\n\t\tdelete[] pBuffer;\n\n\t\t// Now print the results.\n\t\tfor (int i = 0; i < kRandomizationTypeCount; i++)\n\t\t{\n\t\t\tfor (size_t sizeType = 0; sizeType < EAArrayCount(kSizes); sizeType++)\n\t\t\t{\n\t\t\t\tconst eastl_size_t size = kSizes[sizeType];\n\n\t\t\t\tfor (SortFunctionType sortFunction : sortFunctions)\n\t\t\t\t{\n\t\t\t\t\tsOutput.append_sprintf(\"%25s, %14s, Size: %6u, Time: %11\" PRIu64 \" ticks, Assignments: %11\" PRIu64 \"\\n\",\n\t\t\t\t\t GetSortFunctionName(sortFunction), GetRandomizationTypeName(i),\n\t\t\t\t\t (unsigned)size, sResults[i][sizeType][sortFunction].mTime,\n\t\t\t\t\t sResults[i][sizeType][sortFunction].mAssignCount);\n\t\t\t\t}\n\n\t\t\t\tsOutput.append(\"\\n\");\n\t\t\t}\n\t\t}\n\t\tEA::UnitTest::ReportVerbosity(2, \"%s\\n\", sOutput.c_str());\n\t}\n\n\t#if !defined(EA_DEBUG)\n\t\tEA::UnitTest::SetNormalThreadPriority();\n\t#endif\n\n\treturn nErrorCount;\n}\n\ntypedef eastl::function OutputResultCallback;\ntypedef eastl::function PostExecuteCallback;\ntypedef eastl::function PreExecuteCallback;\n\n\ntemplate\nstatic int CompareSmallInputSortPerformanceHelper(eastl::vector &arraySizes, eastl::vector &sortFunctions, const PreExecuteCallback &preExecuteCallback, const PostExecuteCallback &postExecuteCallback, const OutputResultCallback &outputResultCallback)\n{\n\tint nErrorCount = 0;\n\n\tEA::UnitTest::RandGenT rng(EA::UnitTest::GetRandSeed());\n\tEA::StdC::Stopwatch stopwatch(EA::StdC::Stopwatch::kUnitsCPUCycles);\n\tEA::StdC::Stopwatch stopwatchGlobal(EA::StdC::Stopwatch::kUnitsSeconds);\n\tconst eastl_size_t kArraySizeMax = *eastl::max_element(eastl::begin(arraySizes), eastl::end(arraySizes));\n\tconst int kRunCount = 4;\n\tconst int numSubArrays = 128;\n\n\teastl::string sOutput;\n\tsOutput.set_capacity(100000);\n\tElementType* pBuffer = new ElementType[kArraySizeMax];\n\n\tstopwatchGlobal.Restart();\n\n\tfor (int i = 0; i < kRandomizationTypeCount; i++)\n\t{\n\t\tfor (size_t size : arraySizes)\n\t\t{\n\t\t\tfor (SortFunctionType sortFunction : sortFunctions)\n\t\t\t{\n\t\t\t\tBenchmarkResult bestResult{};\n\n\t\t\t\tfor (int c = 0; c < kRunCount; c++)\n\t\t\t\t{\n\t\t\t\t\teastl::vector v(size * numSubArrays);\n\n\t\t\t\t\trng.SetSeed(EA::UnitTest::GetRandSeed());\n\t\t\t\t\tRandomize(v, rng, (RandomizationType)i);\n\t\t\t\t\tpreExecuteCallback();\n\n\t\t\t\t\tswitch (sortFunction)\n\t\t\t\t\t{\n\t\t\t\t\t\tcase sf_quick_sort:\n\t\t\t\t\t\t\tstopwatch.Restart();\n\t\t\t\t\t\t\tfor (auto begin = v.begin(); begin != v.end(); begin += size)\n\t\t\t\t\t\t\t{\n\t\t\t\t\t\t\t\teastl::quick_sort(begin, begin + size, CompareFunction());\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\tstopwatch.Stop();\n\t\t\t\t\t\t\tbreak;\n\n\t\t\t\t\t\tcase sf_tim_sort:\n\t\t\t\t\t\t\tstopwatch.Restart();\n\t\t\t\t\t\t\tfor (auto begin = v.begin(); begin != v.end(); begin += size)\n\t\t\t\t\t\t\t{\n\t\t\t\t\t\t\t\teastl::tim_sort_buffer(begin, begin + size, pBuffer, CompareFunction());\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\tstopwatch.Stop();\n\t\t\t\t\t\t\tbreak;\n\n\t\t\t\t\t\tcase sf_insertion_sort:\n\t\t\t\t\t\t\tstopwatch.Restart();\n\t\t\t\t\t\t\tfor (auto begin = v.begin(); begin != v.end(); begin += size)\n\t\t\t\t\t\t\t{\n\t\t\t\t\t\t\t\teastl::insertion_sort(begin, begin + size, CompareFunction());\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\tstopwatch.Stop();\n\t\t\t\t\t\t\tbreak;\n\n\t\t\t\t\t\tcase sf_shell_sort:\n\t\t\t\t\t\t\tstopwatch.Restart();\n\t\t\t\t\t\t\tfor (auto begin = v.begin(); begin != v.end(); begin += size)\n\t\t\t\t\t\t\t{\n\t\t\t\t\t\t\t\teastl::shell_sort(begin, begin + size, CompareFunction());\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\tstopwatch.Stop();\n\t\t\t\t\t\t\tbreak;\n\n\t\t\t\t\t\tcase sf_heap_sort:\n\t\t\t\t\t\t\tstopwatch.Restart();\n\t\t\t\t\t\t\tfor (auto begin = v.begin(); begin != v.end(); begin += size)\n\t\t\t\t\t\t\t{\n\t\t\t\t\t\t\t\teastl::heap_sort(begin, begin + size, CompareFunction());\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\tstopwatch.Stop();\n\t\t\t\t\t\t\tbreak;\n\n\t\t\t\t\t\tcase sf_merge_sort:\n\t\t\t\t\t\t\tstopwatch.Restart();\n\t\t\t\t\t\t\tfor (auto begin = v.begin(); begin != v.end(); begin += size)\n\t\t\t\t\t\t\t{\n\t\t\t\t\t\t\t\teastl::merge_sort(begin, begin + size, *get_default_allocator((EASTLAllocatorType*)NULL), CompareFunction());\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\tstopwatch.Stop();\n\t\t\t\t\t\t\tbreak;\n\n\t\t\t\t\t\tcase sf_merge_sort_buffer:\n\t\t\t\t\t\t\tstopwatch.Restart();\n\t\t\t\t\t\t\tfor (auto begin = v.begin(); begin != v.end(); begin += size)\n\t\t\t\t\t\t\t{\n\t\t\t\t\t\t\t\teastl::merge_sort_buffer(begin, begin + size, pBuffer, CompareFunction());\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\tstopwatch.Stop();\n\t\t\t\t\t\t\tbreak;\n\n\t\t\t\t\t\tcase sf_comb_sort:\n\t\t\t\t\t\t\tstopwatch.Restart();\n\t\t\t\t\t\t\tfor (auto begin = v.begin(); begin != v.end(); begin += size)\n\t\t\t\t\t\t\t{\n\t\t\t\t\t\t\t\teastl::comb_sort(begin, begin + size, CompareFunction());\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\tstopwatch.Stop();\n\t\t\t\t\t\t\tbreak;\n\n\t\t\t\t\t\tcase sf_bubble_sort:\n\t\t\t\t\t\t\tstopwatch.Restart();\n\t\t\t\t\t\t\tfor (auto begin = v.begin(); begin != v.end(); begin += size)\n\t\t\t\t\t\t\t{\n\t\t\t\t\t\t\t\teastl::bubble_sort(begin, begin + size, CompareFunction());\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\tstopwatch.Stop();\n\t\t\t\t\t\t\tbreak;\n\n\t\t\t\t\t\tcase sf_selection_sort:\n\t\t\t\t\t\t\tstopwatch.Restart();\n\t\t\t\t\t\t\tfor (auto begin = v.begin(); begin != v.end(); begin += size)\n\t\t\t\t\t\t\t{\n\t\t\t\t\t\t\t\teastl::selection_sort(begin, begin + size, CompareFunction());\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\tstopwatch.Stop();\n\t\t\t\t\t\t\tbreak;\n\n\t\t\t\t\t\tcase sf_shaker_sort:\n\t\t\t\t\t\t\tstopwatch.Restart();\n\t\t\t\t\t\t\tfor (auto begin = v.begin(); begin != v.end(); begin += size)\n\t\t\t\t\t\t\t{\n\t\t\t\t\t\t\t\teastl::shaker_sort(begin, begin + size, CompareFunction());\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\tstopwatch.Stop();\n\t\t\t\t\t\t\tbreak;\n\n\t\t\t\t\t\tcase sf_std_sort:\n\t\t\t\t\t\t\tstopwatch.Restart();\n\t\t\t\t\t\t\tfor (auto begin = v.begin(); begin != v.end(); begin += size)\n\t\t\t\t\t\t\t{\n\t\t\t\t\t\t\t\tstd::sort(begin, begin + size, CompareFunction());\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\tstopwatch.Stop();\n\t\t\t\t\t\t\tbreak;\n\n\t\t\t\t\t\tcase sf_std_stable_sort:\n\t\t\t\t\t\t\tstopwatch.Restart();\n\t\t\t\t\t\t\tfor (auto begin = v.begin(); begin != v.end(); begin += size)\n\t\t\t\t\t\t\t{\n\t\t\t\t\t\t\t\tstd::stable_sort(begin, begin + size, CompareFunction());\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\tstopwatch.Stop();\n\t\t\t\t\t\t\tbreak;\n\n\t\t\t\t\t\tcase sf_qsort:\n\t\t\t\t\t\tcase sf_radix_sort:\n\t\t\t\t\t\tcase sf_count:\n\t\t\t\t\t\tdefault:\n\t\t\t\t\t\t\tEATEST_VERIFY_F(false, \"Missing case statement for sort function %s.\", GetSortFunctionName(sortFunction));\n\t\t\t\t\t\t\tbreak;\n\t\t\t\t\t}\n\n\t\t\t\t\tBenchmarkResult result {};\n\t\t\t\t\tresult.mTime = (uint64_t)stopwatch.GetElapsedTime();\n\t\t\t\t\tpostExecuteCallback(result);\n\n\t\t\t\t\t// If this result was faster than a previously fastest result, record this one instead.\n\t\t\t\t\tif ((c == 0) || (result.mTime < bestResult.mTime))\n\t\t\t\t\t\tbestResult = result;\n\n\t\t\t\t\tfor (auto begin = v.begin(); begin != v.end(); begin += size)\n\t\t\t\t\t{\n\t\t\t\t\t\tVERIFY(eastl::is_sorted(begin, begin + size));\n\t\t\t\t\t}\n\t\t\t\t} // for each run\n\n\t\t\t\toutputResultCallback(sOutput, GetSortFunctionName(sortFunction), GetRandomizationTypeName(i), size, numSubArrays, bestResult);\n\n\t\t\t} // for each sort function...\n\t\t\tsOutput.append(\"\\n\");\n\n\t\t} // for each size type...\n\n\t} // for each randomization type...\n\n\tEA::UnitTest::ReportVerbosity(2, \"Total time: %.2f s\\n\", stopwatchGlobal.GetElapsedTimeFloat());\n\tEA::UnitTest::ReportVerbosity(2, \"%s\\n\", sOutput.c_str());\n\n\tdelete[] pBuffer;\n\treturn nErrorCount;\n}\n\nstatic int CompareSmallInputSortPerformance()\n{\n\tint nErrorCount = 0;\n\teastl::vector arraySizes{1, 2, 3, 4, 7, 8, 15, 16, 31, 32, 64, 128, 256};\n\t// Test quick sort and merge sort to provide a \"base line\" for performance. The other sort algorithms are mostly\n\t// O(n^2) and they are benchmarked to determine what sorts are ideal for sorting small arrays or sub-arrays. (i.e.\n\t// this is useful to determine good algorithms to choose as a base case for some of the recursive sorts).\n\teastl::vector sortFunctions{sf_quick_sort, sf_merge_sort_buffer, sf_bubble_sort, sf_comb_sort,\n\t sf_insertion_sort, sf_selection_sort, sf_shell_sort, sf_shaker_sort};\n\n\tEA::UnitTest::ReportVerbosity(2, \"Small Sub-array Sort comparison: Regular speed test\\n\");\n\tnErrorCount += CompareSmallInputSortPerformanceHelper>(\n\t arraySizes, sortFunctions, PreExecuteCallback([]() {}), PostExecuteCallback([](BenchmarkResult&) {}),\n\t OutputResultCallback([](eastl::string& output, const char* sortFunction, const char* randomizationType,\n\t size_t size, size_t numSubArrays, const BenchmarkResult& result) {\n\t\t output.append_sprintf(\"%25s, %14s, Size: %8u, Time: %0.1f ticks %0.2f ticks/elem\\n\", sortFunction,\n\t\t randomizationType, (unsigned)size, float(result.mTime) / float(numSubArrays),\n\t\t float(result.mTime) / float(size * numSubArrays));\n\t }));\n\n\tEA::UnitTest::ReportVerbosity(2, \"Small Sub-array Sort comparison: Slow compare speed test\\n\");\n\tnErrorCount += CompareSmallInputSortPerformanceHelper>(\n\t arraySizes, sortFunctions, PreExecuteCallback([]() { SlowCompare::Reset(); }),\n\t PostExecuteCallback(\n\t [](BenchmarkResult& result) { result.mCompareCount = (uint64_t)SlowCompare::nCompareCount; }),\n\t OutputResultCallback([](eastl::string& output, const char* sortFunction, const char* randomizationType,\n\t size_t size, size_t numSubArrays, const BenchmarkResult& result) {\n\t\t output.append_sprintf(\"%25s, %14s, Size: %6u, Time: %0.2f ticks, Compares: %0.2f\\n\", sortFunction,\n\t\t randomizationType, (unsigned)size, float(result.mTime) / float(numSubArrays),\n\t\t float(result.mCompareCount) / float(numSubArrays));\n\t }));\n\n\tEA::UnitTest::ReportVerbosity(2, \"Small Sub-array Sort comparison: Slow assignment speed test\\n\");\n\tnErrorCount += CompareSmallInputSortPerformanceHelper, eastl::less>>(\n\t arraySizes, sortFunctions, PreExecuteCallback([]() { SlowAssign::Reset(); }),\n\t PostExecuteCallback([](BenchmarkResult& result) {\n\t\t result.mCompareCount = (uint64_t)SlowCompare::nCompareCount;\n\t\t result.mAssignCount = (uint64_t)SlowAssign::nAssignCount;\n\t }),\n\t OutputResultCallback([](eastl::string& output, const char* sortFunction, const char* randomizationType,\n\t size_t size, size_t numSubArrays, const BenchmarkResult& result) {\n\t\t output.append_sprintf(\"%25s, %14s, Size: %6u, Time: %0.2f ticks, Assignments: %0.2f\\n\", sortFunction,\n\t\t randomizationType, (unsigned)size, float(result.mTime) / float(numSubArrays),\n\t\t float(result.mAssignCount) / float(numSubArrays));\n\t }));\n\n\treturn nErrorCount;\n}\n\n\nvoid BenchmarkSort()\n{\n\tEASTLTest_Printf(\"Sort\\n\");\n\n\tEA::UnitTest::RandGenT rng(12345678); // For debugging sort code we should use 12345678, for normal testing use EA::UnitTest::GetRandSeed().\n\tEA::StdC::Stopwatch stopwatch1(EA::StdC::Stopwatch::kUnitsCPUCycles);\n\tEA::StdC::Stopwatch stopwatch2(EA::StdC::Stopwatch::kUnitsCPUCycles);\n\n\tif (EA::UnitTest::GetVerbosity() >= 3)\n\t{\n\t\tCompareSortPerformance();\n\t\tCompareSmallInputSortPerformance();\n\t}\n\n\t{ // Exercise some declarations\n\t\tint nErrorCount = 0;\n\n\t\tValuePair vp1 = {0, 0}, vp2 = {0, 0};\n\t\tVPCompare c1, c2;\n\n\t\tVERIFY(c1.operator()(vp1, vp2) == c2.operator()(vp1, vp2));\n\t\tVERIFY((vp1 < vp2) || (vp1 == vp2) || !(vp1 == vp2));\n\t}\n\n\t{\n\t\teastl::vector intVector(10000);\n\t\teastl::generate(intVector.begin(), intVector.end(), rng);\n\n\t\tfor (int i = 0; i < 2; i++)\n\t\t{\n\t\t\t///////////////////////////////\n\t\t\t// Test quick_sort/vector/ValuePair\n\t\t\t///////////////////////////////\n\n\t\t\tStdVectorVP stdVectorVP(intVector.size());\n\t\t\tEaVectorVP eaVectorVP(intVector.size());\n\n\t\t\tfor (eastl_size_t j = 0, jEnd = intVector.size(); j < jEnd; j++)\n\t\t\t{\n\t\t\t\tconst ValuePair vp = {intVector[j], intVector[j]};\n\t\t\t\tstdVectorVP[j] = vp;\n\t\t\t\teaVectorVP[j] = vp;\n\t\t\t}\n\n\t\t\tTestQuickSortStdVP(stopwatch1, stdVectorVP);\n\t\t\tTestQuickSortEaVP (stopwatch2, eaVectorVP);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"sort/q_sort/vector\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\t// Benchmark the sorting of something that is already sorted.\n\t\t\tTestQuickSortStdVP(stopwatch1, stdVectorVP);\n\t\t\tTestQuickSortEaVP (stopwatch2, eaVectorVP);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"sort/q_sort/vector/sorted\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test quick_sort/vector/Int\n\t\t\t///////////////////////////////\n\n\t\t\tStdVectorInt stdVectorInt(intVector.size());\n\t\t\tEaVectorInt eaVectorInt (intVector.size());\n\n\t\t\tfor(eastl_size_t j = 0, jEnd = intVector.size(); j < jEnd; j++)\n\t\t\t{\n\t\t\t\tstdVectorInt[j] = intVector[j];\n\t\t\t\teaVectorInt[j] = intVector[j];\n\t\t\t}\n\n\t\t\tTestQuickSortStdInt(stopwatch1, stdVectorInt);\n\t\t\tTestQuickSortEaInt (stopwatch2, eaVectorInt);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"sort/q_sort/vector\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\t// Benchmark the sorting of something that is already sorted.\n\t\t\tTestQuickSortStdInt(stopwatch1, stdVectorInt);\n\t\t\tTestQuickSortEaInt (stopwatch2, eaVectorInt);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"sort/q_sort/vector/sorted\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test quick_sort/vector/TestObject\n\t\t\t///////////////////////////////\n\n\t\t\tStdVectorTO stdVectorTO(intVector.size());\n\t\t\tEaVectorTO eaVectorTO(intVector.size());\n\n\t\t\tfor (eastl_size_t j = 0, jEnd = intVector.size(); j < jEnd; j++)\n\t\t\t{\n\t\t\t\tstdVectorTO[j] = TestObject(intVector[j]);\n\t\t\t\teaVectorTO[j] = TestObject(intVector[j]);\n\t\t\t}\n\n\t\t\tTestQuickSortStdTO(stopwatch1, stdVectorTO);\n\t\t\tTestQuickSortEaTO(stopwatch2, eaVectorTO);\n\n\t\t\tif (i == 1)\n\t\t\t\tBenchmark::AddResult(\"sort/q_sort/vector\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\t// Benchmark the sorting of something that is already sorted.\n\t\t\tTestQuickSortStdTO(stopwatch1, stdVectorTO);\n\t\t\tTestQuickSortEaTO(stopwatch2, eaVectorTO);\n\n\t\t\tif (i == 1)\n\t\t\t\tBenchmark::AddResult(\"sort/q_sort/vector/sorted\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test quick_sort/TestObject[]\n\t\t\t///////////////////////////////\n\n\t\t\t// Reset the values back to the unsorted state.\n\t\t\tfor(eastl_size_t j = 0, jEnd = intVector.size(); j < jEnd; j++)\n\t\t\t{\n\t\t\t\tstdVectorTO[j] = TestObject(intVector[j]);\n\t\t\t\teaVectorTO[j] = TestObject(intVector[j]);\n\t\t\t}\n\n\t\t\tTestQuickSortStdTO(stopwatch1, stdVectorTO);\n\t\t\tTestQuickSortEaTO (stopwatch2, eaVectorTO);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"sort/q_sort/TestObject[]\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\t// Benchmark the sorting of something that is already sorted.\n\t\t\tTestQuickSortStdTO(stopwatch1, stdVectorTO);\n\t\t\tTestQuickSortEaTO (stopwatch2, eaVectorTO);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"sort/q_sort/TestObject[]/sorted\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\t\t}\n\t}\n}\n\n\n\n\n\n" }, { "path": "benchmark/source/BenchmarkString.cpp", "content": "/////////////////////////////////////////////////////////////////////////////\n// Copyright (c) Electronic Arts Inc. All rights reserved.\n/////////////////////////////////////////////////////////////////////////////\n\n\n#include \"EASTLBenchmark.h\"\n#include \"EASTLTest.h\"\n#include \n#include \n#include \n#include \n\nEA_DISABLE_ALL_VC_WARNINGS()\n#include \n#include \n#include \n#include \nEA_RESTORE_ALL_VC_WARNINGS()\n\n\nusing namespace EA;\n\n\nnamespace\n{\n\ttemplate \n\tvoid TestPushBack(EA::StdC::Stopwatch& stopwatch, Container& c)\n\t{\n\t\tstopwatch.Restart();\n\t\tfor(int i = 0; i < 100000; i++)\n\t\t\tc.push_back((typename Container::value_type)(i & ((typename Container::value_type)~0)));\n\t\tstopwatch.Stop();\n\t}\n\n\n\ttemplate \n\tvoid TestInsert1(EA::StdC::Stopwatch& stopwatch, Container& c, T* p)\n\t{\n\t\tconst typename Container::size_type s = c.size();\n\t\tstopwatch.Restart();\n\t\tfor(int i = 0; i < 100; i++)\n\t\t\tc.insert(s - (typename Container::size_type)(i * 317), p);\n\t\tstopwatch.Stop();\n\t}\n\n\n\ttemplate \n\tvoid TestErase1(EA::StdC::Stopwatch& stopwatch, Container& c)\n\t{\n\t\tconst typename Container::size_type s = c.size();\n\t\tstopwatch.Restart();\n\t\tfor(int i = 0; i < 100; i++)\n\t\t\tc.erase(s - (typename Container::size_type)(i * 339), 7);\n\t\tstopwatch.Stop();\n\t}\n\n\n\ttemplate \n\tvoid TestReplace1(EA::StdC::Stopwatch& stopwatch, Container& c, T* p, int n)\n\t{\n\t\tconst typename Container::size_type s = c.size();\n\t\tstopwatch.Restart();\n\t\tfor(int i = 0; i < 1000; i++)\n\t\t\tc.replace(s - (typename Container::size_type)(i * 5), ((n - 2) + (i & 3)), p, n); // The second argument rotates through n-2, n-1, n, n+1, n-2, etc.\n\t\tstopwatch.Stop();\n\t}\n\n\n\ttemplate \n\tvoid TestReserve(EA::StdC::Stopwatch& stopwatch, Container& c)\n\t{\n\t\tconst typename Container::size_type s = c.capacity();\n\t\tstopwatch.Restart();\n\t\tfor(int i = 0; i < 1000; i++)\n\t\t\tc.reserve((s - 2) + (i & 3)); // The second argument rotates through n-2, n-1, n, n+1, n-2, etc.\n\t\tstopwatch.Stop();\n\t}\n\n\n\ttemplate \n\tvoid TestSize(EA::StdC::Stopwatch& stopwatch, Container& c)\n\t{\n\t\tstopwatch.Restart();\n\t\tfor(int i = 0; i < 1000; i++)\n\t\t\tBenchmark::DoNothing(&c, c.size()); \n\t\tstopwatch.Stop();\n\t}\n\n\n\ttemplate \n\tvoid TestBracket(EA::StdC::Stopwatch& stopwatch, Container& c)\n\t{\n\t\tint32_t temp = 0;\n\t\tstopwatch.Restart();\n\t\tfor(typename Container::size_type j = 0, jEnd = c.size(); j < jEnd; j++)\n\t\t\ttemp += c[j];\n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%u\", (unsigned)temp);\n\t}\n\n\n\ttemplate \n\tvoid TestFind(EA::StdC::Stopwatch& stopwatch, Container& c)\n\t{\n\t\tstopwatch.Restart();\n\t\tfor(int i = 0; i < 1000; i++)\n\t\t\tBenchmark::DoNothing(&c, *eastl::find(c.begin(), c.end(), (typename Container::value_type)~0));\n\t\tstopwatch.Stop();\n\t}\n\n\n\ttemplate \n\tvoid TestFind1(EA::StdC::Stopwatch& stopwatch, Container& c, T* p, int pos, int n)\n\t{\n\t\tstopwatch.Restart();\n\t\tfor(int i = 0; i < 1000; i++)\n\t\t\tBenchmark::DoNothing(&c, c.find(p, (typename Container::size_type)pos, (typename Container::size_type)n));\n\t\tstopwatch.Stop();\n\t}\n\n\n\ttemplate \n\tvoid TestRfind1(EA::StdC::Stopwatch& stopwatch, Container& c, T* p, int pos, int n)\n\t{\n\t\tstopwatch.Restart();\n\t\tfor(int i = 0; i < 1000; i++)\n\t\t\tBenchmark::DoNothing(&c, c.rfind(p, (typename Container::size_type)pos, (typename Container::size_type)n));\n\t\tstopwatch.Stop();\n\t}\n\n\ttemplate \n\tvoid TestFirstOf1(EA::StdC::Stopwatch& stopwatch, Container& c, T* p, int pos, int n)\n\t{\n\t\tstopwatch.Restart();\n\t\tfor(int i = 0; i < 1000; i++)\n\t\t\tBenchmark::DoNothing(&c, c.find_first_of(p, (typename Container::size_type)pos, (typename Container::size_type)n));\n\t\tstopwatch.Stop();\n\t}\n\n\ttemplate \n\tvoid TestLastOf1(EA::StdC::Stopwatch& stopwatch, Container& c, T* p, int pos, int n)\n\t{\n\t\tstopwatch.Restart();\n\t\tfor(int i = 0; i < 1000; i++)\n\t\t\tBenchmark::DoNothing(&c, c.find_last_of(p, (typename Container::size_type)pos, (typename Container::size_type)n));\n\t\tstopwatch.Stop();\n\t}\n\n\ttemplate \n\tvoid TestFirstNotOf1(EA::StdC::Stopwatch& stopwatch, Container& c, T* p, int pos, int n)\n\t{\n\t\tstopwatch.Restart();\n\t\tfor(int i = 0; i < 1000; i++)\n\t\t\tBenchmark::DoNothing(&c, c.find_first_not_of(p, (typename Container::size_type)pos, (typename Container::size_type)n));\n\t\tstopwatch.Stop();\n\t}\n\n\ttemplate \n\tvoid TestLastNotOf1(EA::StdC::Stopwatch& stopwatch, Container& c, T* p, int pos, int n)\n\t{\n\t\tstopwatch.Restart();\n\t\tfor(int i = 0; i < 1000; i++)\n\t\t\tBenchmark::DoNothing(&c, c.find_last_not_of(p, (typename Container::size_type)pos, (typename Container::size_type)n));\n\t\tstopwatch.Stop();\n\t}\n\n\n\ttemplate \n\tvoid TestCompare(EA::StdC::Stopwatch& stopwatch, Container& c1, Container& c2) // size()\n\t{\n\t\tstopwatch.Restart();\n\t\tfor(int i = 0; i < 500; i++)\n\t\t\tBenchmark::DoNothing(&c1, c1.compare(c2));\n\t\tstopwatch.Stop();\n\t}\n\n\n\ttemplate \n\tvoid TestSwap(EA::StdC::Stopwatch& stopwatch, Container& c1, Container& c2) // size()\n\t{\n\t\tstopwatch.Restart();\n\t\tfor(int i = 0; i < 10000; i++) // Make sure this is an even count so that when done things haven't changed.\n\t\t{\n\t\t\tc1.swap(c2);\n\t\t\tBenchmark::DoNothing(&c1);\n\t\t} \n\t\tstopwatch.Stop();\n\t}\n\n} // namespace\n\n\n\n\nvoid BenchmarkString()\n{\n\tEASTLTest_Printf(\"String\\n\");\n\n\tEA::StdC::Stopwatch stopwatch1(EA::StdC::Stopwatch::kUnitsCPUCycles);\n\tEA::StdC::Stopwatch stopwatch2(EA::StdC::Stopwatch::kUnitsCPUCycles);\n\n\t{\n\t\tfor(int i = 0; i < 2; i++)\n\t\t{\n\t\t\tstd::basic_string ss8(16, 0); // We initialize to size of 16 because different implementations may make\n\t\t\teastl::basic_string es8(16, 0); // different tradeoffs related to startup size. Initial operations are faster\n\t\t\t\t\t\t\t\t\t\t\t\t\t\t// when strings start with a higher reserve, but they use more memory. \n\t\t\tstd::basic_string ss16(16, 0); // We try to nullify this tradeoff for the tests below by starting all at \n\t\t\teastl::basic_string es16(16, 0); // the same baseline allocation.\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test push_back\n\t\t\t///////////////////////////////\n\n\t\t\tTestPushBack(stopwatch1, ss8);\n\t\t\tTestPushBack(stopwatch2, es8);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"string/push_back\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tTestPushBack(stopwatch1, ss16);\n\t\t\tTestPushBack(stopwatch2, es16);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"string/push_back\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test insert(size_type position, const value_type* p)\n\t\t\t///////////////////////////////\n\n\t\t\tconst char8_t pInsert1_8[] = { 'a', 0 };\n\t\t\tTestInsert1(stopwatch1, ss8, pInsert1_8);\n\t\t\tTestInsert1(stopwatch2, es8, pInsert1_8);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"string/insert/pos,p\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tconst char16_t pInsert1_16[] = { 'a', 0 };\n\t\t\tTestInsert1(stopwatch1, ss16, pInsert1_16);\n\t\t\tTestInsert1(stopwatch2, es16, pInsert1_16);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"string/insert/pos,p\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test erase(size_type position, size_type n)\n\t\t\t///////////////////////////////\n\n\t\t\tTestErase1(stopwatch1, ss8);\n\t\t\tTestErase1(stopwatch2, es8);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"string/erase/pos,n\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tTestErase1(stopwatch1, ss16);\n\t\t\tTestErase1(stopwatch2, es16);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"string/erase/pos,n\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t/////////////////////////////// \n\t\t\t// Test replace(size_type position, size_type n1, const value_type* p, size_type n2)\n\t\t\t///////////////////////////////\n\n\t\t\tconst int kReplace1Size = 8;\n\t\t\tconst char8_t pReplace1_8[kReplace1Size] = { 'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h' };\n\n\t\t\tTestReplace1(stopwatch1, ss8, pReplace1_8, kReplace1Size);\n\t\t\tTestReplace1(stopwatch2, es8, pReplace1_8, kReplace1Size);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"string/replace/pos,n,p,n\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tconst char16_t pReplace1_16[kReplace1Size] = { 'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h' };\n\n\t\t\tTestReplace1(stopwatch1, ss16, pReplace1_16, kReplace1Size);\n\t\t\tTestReplace1(stopwatch2, es16, pReplace1_16, kReplace1Size);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"string/replace/pos,n,p,n\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test reserve(size_type)\n\t\t\t///////////////////////////////\n\n\t\t\tTestReserve(stopwatch1, ss8);\n\t\t\tTestReserve(stopwatch2, es8);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"string/reserve\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tTestReserve(stopwatch1, ss16);\n\t\t\tTestReserve(stopwatch2, es16);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"string/reserve\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test size()\n\t\t\t///////////////////////////////\n\n\t\t\tTestSize(stopwatch1, ss8);\n\t\t\tTestSize(stopwatch2, es8);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"string/size\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tTestSize(stopwatch1, ss16);\n\t\t\tTestSize(stopwatch2, es16);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"string/size\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test operator[].\n\t\t\t///////////////////////////////\n\n\t\t\tTestBracket(stopwatch1, ss8);\n\t\t\tTestBracket(stopwatch2, es8);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"string/operator[]\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tTestBracket(stopwatch1, ss16);\n\t\t\tTestBracket(stopwatch2, es16);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"string/operator[]\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test iteration via find().\n\t\t\t///////////////////////////////\n\n\t\t\tTestFind(stopwatch1, ss8);\n\t\t\tTestFind(stopwatch2, es8);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"string/iteration\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tTestFind(stopwatch1, ss16);\n\t\t\tTestFind(stopwatch2, es16);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"string/iteration\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test find(const value_type* p, size_type position, size_type n)\n\t\t\t///////////////////////////////\n\n\t\t\tconst int kFind1Size = 7;\n\t\t\tconst char8_t pFind1_8[kFind1Size] = { 'p', 'a', 't', 't', 'e', 'r', 'n' };\n\n\t\t\tss8.insert(ss8.size() / 2, pFind1_8);\n\t\t\tes8.insert(es8.size() / 2, pFind1_8);\n\n\t\t\tTestFind1(stopwatch1, ss8, pFind1_8, 15, kFind1Size);\n\t\t\tTestFind1(stopwatch2, es8, pFind1_8, 15, kFind1Size);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"string/find/p,pos,n\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tconst char16_t pFind1_16[kFind1Size] = { 'p', 'a', 't', 't', 'e', 'r', 'n' };\n\n\t\t\t#if !defined(EA_PLATFORM_IPHONE) && (!defined(EA_COMPILER_CLANG) && defined(EA_PLATFORM_MINGW)) // Crashes on iPhone.\n\t\t\t ss16.insert(ss8.size() / 2, pFind1_16);\n\t\t\t#endif\n\t\t\tes16.insert(es8.size() / 2, pFind1_16);\n\n\t\t\tTestFind1(stopwatch1, ss16, pFind1_16, 15, kFind1Size);\n\t\t\tTestFind1(stopwatch2, es16, pFind1_16, 15, kFind1Size);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"string/find/p,pos,n\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test rfind(const value_type* p, size_type position, size_type n)\n\t\t\t///////////////////////////////\n\n\t\t\tTestRfind1(stopwatch1, ss8, pFind1_8, 15, kFind1Size);\n\t\t\tTestRfind1(stopwatch2, es8, pFind1_8, 15, kFind1Size);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"string/rfind/p,pos,n\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tTestRfind1(stopwatch1, ss16, pFind1_16, 15, kFind1Size);\n\t\t\tTestRfind1(stopwatch2, es16, pFind1_16, 15, kFind1Size);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"string/rfind/p,pos,n\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t//NOTICE (RASHIN):\n\t\t\t//FindFirstOf variants are incredibly slow on palm pixi debug builds.\n\t\t\t//Disabling for now...\n\t\t#if !defined(EA_DEBUG)\n\t\t\t///////////////////////////////\n\t\t\t// Test find_first_of(const value_type* p, size_type position, size_type n\n\t\t\t///////////////////////////////\n\n\t\t\tconst int kFindOf1Size = 7;\n\t\t\tconst char8_t pFindOf1_8[kFindOf1Size] = { '~', '~', '~', '~', '~', '~', '~' };\n\n\t\t\tTestFirstOf1(stopwatch1, ss8, pFindOf1_8, 15, kFindOf1Size);\n\t\t\tTestFirstOf1(stopwatch2, es8, pFindOf1_8, 15, kFindOf1Size);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"string/find_first_of/p,pos,n\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tconst char16_t pFindOf1_16[kFindOf1Size] = { '~', '~', '~', '~', '~', '~', '~' };\n\n\t\t\tTestFirstOf1(stopwatch1, ss16, pFindOf1_16, 15, kFindOf1Size);\n\t\t\tTestFirstOf1(stopwatch2, es16, pFindOf1_16, 15, kFindOf1Size);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"string/find_first_of/p,pos,n\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test find_last_of(const value_type* p, size_type position, size_type n\n\t\t\t///////////////////////////////\n\n\t\t\tTestLastOf1(stopwatch1, ss8, pFindOf1_8, 15, kFindOf1Size);\n\t\t\tTestLastOf1(stopwatch2, es8, pFindOf1_8, 15, kFindOf1Size);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"string/find_last_of/p,pos,n\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tTestLastOf1(stopwatch1, ss16, pFindOf1_16, 15, kFindOf1Size);\n\t\t\tTestLastOf1(stopwatch2, es16, pFindOf1_16, 15, kFindOf1Size);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"string/find_last_of/p,pos,n\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test find_first_not_of(const value_type* p, size_type position, size_type n\n\t\t\t///////////////////////////////\n\n\t\t\tTestFirstNotOf1(stopwatch1, ss8, pFind1_8, 15, kFind1Size);\n\t\t\tTestFirstNotOf1(stopwatch2, es8, pFind1_8, 15, kFind1Size);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"string/find_first_not_of/p,pos,n\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tTestFirstNotOf1(stopwatch1, ss16, pFind1_16, 15, kFind1Size);\n\t\t\tTestFirstNotOf1(stopwatch2, es16, pFind1_16, 15, kFind1Size);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"string/find_first_not_of/p,pos,n\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test find_last_of(const value_type* p, size_type position, size_type n\n\t\t\t///////////////////////////////\n\n\t\t\tTestLastNotOf1(stopwatch1, ss8, pFind1_8, 15, kFind1Size);\n\t\t\tTestLastNotOf1(stopwatch2, es8, pFind1_8, 15, kFind1Size);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"string/find_last_of/p,pos,n\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tTestLastNotOf1(stopwatch1, ss16, pFind1_16, 15, kFind1Size);\n\t\t\tTestLastNotOf1(stopwatch2, es16, pFind1_16, 15, kFind1Size);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"string/find_last_of/p,pos,n\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t#endif\n\n\t\t\t///////////////////////////////\n\t\t\t// Test compare()\n\t\t\t///////////////////////////////\n\n\t\t\tstd::basic_string ss8X(ss8);\n\t\t\teastl::basic_string es8X(es8);\n\t\t\tstd::basic_string ss16X(ss16);\n\t\t\teastl::basic_string es16X(es16);\n\n\t\t\tTestCompare(stopwatch1, ss8, ss8X);\n\t\t\tTestCompare(stopwatch2, es8, es8X);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"string/compare\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tTestCompare(stopwatch1, ss16, ss16X);\n\t\t\tTestCompare(stopwatch2, es16, es16X);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"string/compare\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test swap()\n\t\t\t///////////////////////////////\n\n\t\t\tTestSwap(stopwatch1, ss8, ss8X);\n\t\t\tTestSwap(stopwatch2, es8, es8X);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"string/swap\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\tTestSwap(stopwatch1, ss16, ss16X);\n\t\t\tTestSwap(stopwatch2, es16, es16X);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"string/swap\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t}\n\t}\n\n}\n\n\n\n\n\n\n\n\n\n" }, { "path": "benchmark/source/BenchmarkTupleVector.cpp", "content": "/////////////////////////////////////////////////////////////////////////////\n// Copyright (c) Electronic Arts Inc. All rights reserved.\n/////////////////////////////////////////////////////////////////////////////\n\n\n#include \"EASTLBenchmark.h\"\n#include \"EASTLTest.h\"\n#include \n#include \n#include \n#include \n\n#ifdef _MSC_VER\n\t#pragma warning(push, 0)\n\t#pragma warning(disable: 4350)\n#endif\n#include \n#include \n#include \n#include \n#ifdef _MSC_VER\n\t#pragma warning(pop)\n#endif\n\n\nusing namespace EA;\n\n\ntypedef std::vector StdVectorUint64;\ntypedef eastl::tuple_vector EaTupleVectorUint64;\n\n struct PaddingStruct\n{\n\tchar padding[56] = { 0 };\n};\nstatic const PaddingStruct DefaultPadding;\ntypedef eastl::tuple PaddedTuple;\ntypedef std::vector StdVectorUint64Padded;\ntypedef eastl::tuple_vector EaTupleVectorUint64Padded;\n\nnamespace\n{\n\n\n\t//////////////////////////////////////////////////////////////////////////////\n\t// MovableType\n\t// \n\tstruct MovableType\n\t{\n\t\tint8_t* mpData;\n\t\tenum { kDataSize = 128 };\n\n\t\tMovableType() : mpData(new int8_t[kDataSize])\n\t\t\t{ memset(mpData, 0, kDataSize); }\n\n\t\tMovableType(const MovableType& x) : mpData(new int8_t[kDataSize])\n\t\t\t{ memcpy(mpData, x.mpData, kDataSize); }\n\n\t\tMovableType& operator=(const MovableType& x)\n\t\t{\n\t\t\tif(!mpData)\n\t\t\t\tmpData = new int8_t[kDataSize];\n\t\t\tmemcpy(mpData, x.mpData, kDataSize);\n\t\t\treturn *this;\n\t\t}\n\n\t\t#if EASTL_MOVE_SEMANTICS_ENABLED\n\t\t\tMovableType(MovableType&& x) EA_NOEXCEPT : mpData(x.mpData)\n\t\t\t\t{ x.mpData = NULL; }\n\n\t\t\tMovableType& operator=(MovableType&& x)\n\t\t\t{\n\t\t\t\teastl::swap(mpData, x.mpData); // In practice it may not be right to do a swap, depending on the case.\n\t\t\t\treturn *this;\n\t\t\t}\n\t\t#endif\n\n\t ~MovableType()\n\t\t\t{ delete[] mpData; }\n\t};\n\n\n\t//////////////////////////////////////////////////////////////////////////////\n\t// AutoRefCount\n\t// \n\t// Basic ref-counted object.\n\t//\n\ttemplate \n\tclass AutoRefCount\n\t{\n\tpublic:\n\t\tT* mpObject;\n\n\tpublic:\n\t\tAutoRefCount() EA_NOEXCEPT : mpObject(NULL) \n\t\t\t{}\n\n\t\tAutoRefCount(T* pObject) EA_NOEXCEPT : mpObject(pObject) \n\t\t{ \n\t\t\tif(mpObject)\n\t\t\t\tmpObject->AddRef();\n\t\t} \n\n\t\tAutoRefCount(T* pObject, int) EA_NOEXCEPT : mpObject(pObject) \n\t\t{\n\t\t\t// Inherit the existing refcount.\n\t\t} \n\n\t\tAutoRefCount(const AutoRefCount& x) EA_NOEXCEPT : mpObject(x.mpObject) \n\t\t{ \n\t\t\tif(mpObject)\n\t\t\t\tmpObject->AddRef();\n\t\t}\n\n\t\tAutoRefCount& operator=(const AutoRefCount& x) \n\t\t{ \n\t\t\treturn operator=(x.mpObject);\n\t\t}\n\n\t\tAutoRefCount& operator=(T* pObject)\n\t\t{ \n\t\t\tif(pObject != mpObject)\n\t\t\t{\n\t\t\t\tT* const pTemp = mpObject; // Create temporary to prevent possible problems with re-entrancy.\n\t\t\t\tif(pObject)\n\t\t\t\t\tpObject->AddRef();\n\t\t\t\tmpObject = pObject;\n\t\t\t\tif(pTemp)\n\t\t\t\t\tpTemp->Release();\n\t\t\t}\n\t\t\treturn *this;\n\t\t}\n\n\t\t#if EASTL_MOVE_SEMANTICS_ENABLED\n\t\t\tAutoRefCount(AutoRefCount&& x) EA_NOEXCEPT : mpObject(x.mpObject) \n\t\t\t{ \n\t\t\t\tx.mpObject = NULL;\n\t\t\t}\n\n\t\t\tAutoRefCount& operator=(AutoRefCount&& x)\n\t\t\t{\n\t\t\t\tif(mpObject)\n\t\t\t\t\tmpObject->Release();\n\t\t\t\tmpObject = x.mpObject;\n\t\t\t\tx.mpObject = NULL;\n\t\t\t\treturn *this;\n\t\t\t}\n\t\t#endif\n\n\t\t~AutoRefCount() \n\t\t{\n\t\t\tif(mpObject)\n\t\t\t\tmpObject->Release();\n\t\t}\n\n\t\tT& operator *() const EA_NOEXCEPT\n\t\t\t{ return *mpObject; }\n\n\t\tT* operator ->() const EA_NOEXCEPT\n\t\t\t{ return mpObject; }\n\n\t\toperator T*() const EA_NOEXCEPT\n\t\t\t{ return mpObject; }\n\n\t}; // class AutoRefCount\n\n\n\tstruct RefCounted\n\t{\n\t\tint mRefCount;\n\t\tstatic int msAddRefCount;\n\t\tstatic int msReleaseCount;\n\n\t\tRefCounted() : mRefCount(1) {}\n\n\t\tint AddRef()\n\t\t\t{ ++msAddRefCount; return ++mRefCount; }\n\n\t\tint Release()\n\t\t{\n\t\t\t++msReleaseCount;\n\t\t\tif(mRefCount > 1)\n\t\t\t\treturn --mRefCount;\n\t\t\tdelete this;\n\t\t\treturn 0;\n\t\t}\n\t};\n\n\tint RefCounted::msAddRefCount = 0;\n\tint RefCounted::msReleaseCount = 0;\n\n} // namespace \n\n\nnamespace \n{\n\ttemplate \n\tvoid TestPushBack(EA::StdC::Stopwatch& stopwatch, Container& c, eastl::vector& intVector)\n\t{\n\t\tstopwatch.Restart();\n\t\tfor(eastl_size_t j = 0, jEnd = intVector.size(); j < jEnd; j++)\n\t\t\tc.push_back((uint64_t)intVector[j]);\n\t\tstopwatch.Stop();\n\t}\n\n\n\ttemplate \n\tvoid TestBracket(EA::StdC::Stopwatch& stopwatch, Container& c)\n\t{\n\t\tuint64_t temp = 0;\n\t\tstopwatch.Restart();\n\t\tfor(typename Container::size_type j = 0, jEnd = c.size(); j < jEnd; j++)\n\t\t\ttemp += c[j];\n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%u\", (unsigned)(temp & 0xffffffff));\n\t}\n\n\tvoid TestBracket(EA::StdC::Stopwatch& stopwatch, EaTupleVectorUint64& c)\n\t{\n\t\tuint64_t temp = 0;\n\t\tstopwatch.Restart();\n\t\tfor (typename EaTupleVectorUint64::size_type j = 0, jEnd = c.size(); j < jEnd; j++)\n\t\t\ttemp += eastl::get<0>(c[j]);\n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%u\", (unsigned)(temp & 0xffffffff));\n\t}\n\n\ttemplate \n\tvoid TestFind(EA::StdC::Stopwatch& stopwatch, Container& c)\n\t{\n\t\tstopwatch.Restart();\n\t\ttypedef typename Container::iterator iterator_t; // This typedef is required to get this code to compile on RVCT\n\t\titerator_t it = eastl::find(c.begin(), c.end(), UINT64_C(0xffffffffffff));\n\t\tstopwatch.Stop();\n\t\tif(it != c.end())\n\t\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%u\", (unsigned)*it);\n\t}\n\n\tvoid TestFind(EA::StdC::Stopwatch& stopwatch, EaTupleVectorUint64& c)\n\t{\n\t\teastl::tuple val(0xffffffffffff);\n\t\tstopwatch.Restart();\n\t\tEaTupleVectorUint64::iterator it = eastl::find(c.begin(), c.end(), val);\n\t\tstopwatch.Stop();\n\t\tif (it != c.end())\n\t\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%u\", (unsigned)eastl::get<0>(*it));\n\t}\n\n\ttemplate \n\tvoid TestSort(EA::StdC::Stopwatch& stopwatch, Container& c)\n\t{\n\t\t// Intentionally use eastl sort in order to measure just \n\t\t// vector access speed and not be polluted by sort speed.\n\t\tstopwatch.Restart();\n\t\teastl::quick_sort(c.begin(), c.end()); \n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%u\", (unsigned)(c[0] & 0xffffffff));\n\t}\n\n\tvoid TestSort(EA::StdC::Stopwatch& stopwatch, EaTupleVectorUint64& c)\n\t{\n\t\t// Intentionally use eastl sort in order to measure just\n\t\t// vector access speed and not be polluted by sort speed.\n\t\tstopwatch.Restart();\n\t\teastl::quick_sort(c.begin(), c.end());\n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%u\", (unsigned)(eastl::get<0>(c[0]) & 0xffffffff));\n\t}\n\n\n\ttemplate \n\tvoid TestInsert(EA::StdC::Stopwatch& stopwatch, Container& c)\n\t{\n\t\ttypename Container::size_type j, jEnd;\n\t\ttypename Container::iterator it;\n\n\t\tstopwatch.Restart();\n\t\tfor(j = 0, jEnd = 100, it = c.begin(); j < jEnd; ++j)\n\t\t{\n\t\t\tit = c.insert(it, UINT64_C(0xffffffffffff));\n\n\t\t\tif(it == c.end()) // Try to safely increment the iterator three times.\n\t\t\t\tit = c.begin();\n\t\t\tif(++it == c.end())\n\t\t\t\tit = c.begin();\n\t\t\tif(++it == c.end())\n\t\t\t\tit = c.begin();\n\t\t}\n\t\tstopwatch.Stop();\n\t}\n\n\n\ttemplate \n\tvoid TestErase(EA::StdC::Stopwatch& stopwatch, Container& c)\n\t{\n\t\ttypename Container::size_type j, jEnd;\n\t\ttypename Container::iterator it;\n\n\t\tstopwatch.Restart();\n\t\tfor(j = 0, jEnd = 100, it = c.begin(); j < jEnd; ++j)\n\t\t{\n\t\t\tit = c.erase(it);\n\n\t\t\tif(it == c.end()) // Try to safely increment the iterator three times.\n\t\t\t\tit = c.begin();\n\t\t\tif(++it == c.end())\n\t\t\t\tit = c.begin();\n\t\t\tif(++it == c.end())\n\t\t\t\tit = c.begin();\n\t\t}\n\t\tstopwatch.Stop();\n\t}\n\n\n\ttemplate \n\tvoid TestMoveReallocate(EA::StdC::Stopwatch& stopwatch, Container& c)\n\t{\n\t\tstopwatch.Restart();\n\t\twhile(c.size() < 8192)\n\t\t\tc.resize(c.capacity() + 1);\n\t\tstopwatch.Stop();\n\t}\n\n\n\ttemplate \n\tvoid TestMoveErase(EA::StdC::Stopwatch& stopwatch, Container& c)\n\t{\n\t\tstopwatch.Restart();\n\t\twhile(!c.empty())\n\t\t\tc.erase(c.begin());\n\t\tstopwatch.Stop();\n\t}\n\n\t//////////////////////////////////////////////////////////////////////////\n\t// Variations of test functions for the Padded structures\n\ttemplate \n\tvoid TestTuplePushBack(EA::StdC::Stopwatch& stopwatch, Container& c, eastl::vector& intVector)\n\t{\n\t\tstopwatch.Restart();\n\t\tfor (eastl_size_t j = 0, jEnd = intVector.size(); j < jEnd; j++)\n\t\t{\n\t\t\tPaddedTuple tup((uint64_t)intVector[j], DefaultPadding);\n\t\t\tc.push_back(tup);\n\t\t}\n\t\tstopwatch.Stop();\n\t}\n\n\t\n\ttemplate \n\tvoid TestTupleBracket(EA::StdC::Stopwatch& stopwatch, Container& c)\n\t{\n\t\tuint64_t temp = 0;\n\t\tstopwatch.Restart();\n\t\tfor (typename Container::size_type j = 0, jEnd = c.size(); j < jEnd; j++)\n\t\t\ttemp += eastl::get<0>(c[j]);\n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%u\", (unsigned)(temp & 0xffffffff));\n\t}\n\n\n\ttemplate \n\tvoid TestTupleFind(EA::StdC::Stopwatch& stopwatch, Container& c)\n\t{\n\t\tstopwatch.Restart();\n\t\ttypedef typename Container::iterator iterator_t; // This typedef is required to get this code to compile on RVCT\n\t\titerator_t it = eastl::find_if(c.begin(), c.end(), [](auto tup) { return eastl::get<0>(tup) == 0xFFFFFFFF; });\n\t\tstopwatch.Stop();\n\t\tif (it != c.end())\n\t\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%u\", (unsigned)eastl::get<0>(*it));\n\t}\n\n\ttemplate \n\tvoid TestTupleSort(EA::StdC::Stopwatch& stopwatch, Container& c)\n\t{\n\t\t// Intentionally use eastl sort in order to measure just\n\t\t// vector access speed and not be polluted by sort speed.\n\t\tstopwatch.Restart();\n\t\teastl::quick_sort(c.begin(), c.end(), [](auto a, auto b) { return eastl::get<0>(a) < eastl::get<0>(b); });\n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%u\", (unsigned)(eastl::get<0>(c[0]) & 0xffffffff));\n\t}\n\n\ttemplate \n\tvoid TestTupleInsert(EA::StdC::Stopwatch& stopwatch, Container& c)\n\t{\n\t\ttypename Container::size_type j, jEnd;\n\t\ttypename Container::iterator it;\n\t\tPaddedTuple tup(0xFFFFFFFF, DefaultPadding);\n\n\t\tstopwatch.Restart();\n\t\tfor (j = 0, jEnd = 100, it = c.begin(); j < jEnd; ++j)\n\t\t{\n\t\t\tit = c.insert(it, tup);\n\n\t\t\tif (it == c.end()) // Try to safely increment the iterator three times.\n\t\t\t\tit = c.begin();\n\t\t\tif (++it == c.end())\n\t\t\t\tit = c.begin();\n\t\t\tif (++it == c.end())\n\t\t\t\tit = c.begin();\n\t\t}\n\t\tstopwatch.Stop();\n\t}\n\n\ttemplate \n\tvoid TestTupleErase(EA::StdC::Stopwatch& stopwatch, Container& c)\n\t{\n\t\ttypename Container::size_type j, jEnd;\n\t\ttypename Container::iterator it;\n\n\t\tstopwatch.Restart();\n\t\tfor (j = 0, jEnd = 100, it = c.begin(); j < jEnd; ++j)\n\t\t{\n\t\t\tit = c.erase(it);\n\n\t\t\tif (it == c.end()) // Try to safely increment the iterator three times.\n\t\t\t\tit = c.begin();\n\t\t\tif (++it == c.end())\n\t\t\t\tit = c.begin();\n\t\t\tif (++it == c.end())\n\t\t\t\tit = c.begin();\n\t\t}\n\t\tstopwatch.Stop();\n\t}\n\n} // namespace\n\n\n\n\n\nvoid BenchmarkTupleVector()\n{\n\tEASTLTest_Printf(\"TupleVector\\n\");\n\n\tEA::UnitTest::RandGenT rng(EA::UnitTest::GetRandSeed());\n\tEA::StdC::Stopwatch stopwatch1(EA::StdC::Stopwatch::kUnitsCPUCycles);\n\tEA::StdC::Stopwatch stopwatch2(EA::StdC::Stopwatch::kUnitsCPUCycles);\n\n\t{\n\t\teastl::vector intVector(100000);\n\t\teastl::generate(intVector.begin(), intVector.end(), rng);\n\n\t\tfor(int i = 0; i < 2; i++)\n\t\t{\n\t\t\tStdVectorUint64 stdVectorUint64;\n\t\t\tEaTupleVectorUint64 eaTupleVectorUint64;\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test push_back\n\t\t\t///////////////////////////////\n\n\t\t\tTestPushBack(stopwatch1, stdVectorUint64, intVector);\n\t\t\tTestPushBack(stopwatch2, eaTupleVectorUint64, intVector);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"tuple_vector/push_back\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test operator[].\n\t\t\t///////////////////////////////\n\n\t\t\tTestBracket(stopwatch1, stdVectorUint64);\n\t\t\tTestBracket(stopwatch2, eaTupleVectorUint64);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"tuple_vector/operator[]\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test iteration via find().\n\t\t\t///////////////////////////////\n\n\t\t\tTestFind(stopwatch1, stdVectorUint64);\n\t\t\tTestFind(stopwatch2, eaTupleVectorUint64);\n\t\t\tTestFind(stopwatch1, stdVectorUint64);\n\t\t\tTestFind(stopwatch2, eaTupleVectorUint64);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"tuple_vector/iteration\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test sort\n\t\t\t///////////////////////////////\n\n\t\t\t// Currently VC++ complains about our sort function decrementing std::iterator that is already at begin(). In the strictest sense,\n\t\t\t// that's a valid complaint, but we aren't testing std STL here. We will want to revise our sort function eventually.\n\t\t\t#if !defined(_MSC_VER) || !defined(_ITERATOR_DEBUG_LEVEL) || (_ITERATOR_DEBUG_LEVEL < 2)\n\t\t\tTestSort(stopwatch1, stdVectorUint64);\n\t\t\tTestSort(stopwatch2, eaTupleVectorUint64);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"tuple_vector/sort\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\t\t\t#endif\n\n\t\t\t///////////////////////////////\n\t\t\t// Test insert\n\t\t\t///////////////////////////////\n\n\t\t\tTestInsert(stopwatch1, stdVectorUint64);\n\t\t\tTestInsert(stopwatch2, eaTupleVectorUint64);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"tuple_vector/insert\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test erase\n\t\t\t///////////////////////////////\n\n\t\t\tTestErase(stopwatch1, stdVectorUint64);\n\t\t\tTestErase(stopwatch2, eaTupleVectorUint64);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"tuple_vector/erase\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////////////////\n\t\t\t// Test move of MovableType\n\t\t\t// Should be much faster with C++11 move.\n\t\t\t///////////////////////////////////////////\n\n\t\t\tstd::vector stdVectorMovableType;\n\t\t\teastl::tuple_vector eaTupleVectorMovableType;\n\n\t\t\tTestMoveReallocate(stopwatch1, stdVectorMovableType);\n\t\t\tTestMoveReallocate(stopwatch2, eaTupleVectorMovableType);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"tuple_vector/reallocate\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\tTestMoveErase(stopwatch1, stdVectorMovableType);\n\t\t\tTestMoveErase(stopwatch2, eaTupleVectorMovableType);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"tuple_vector/erase\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////////////////\n\t\t\t// Test move of AutoRefCount\n\t\t\t// Should be much faster with C++11 move.\n\t\t\t///////////////////////////////////////////\n\n\t\t\tstd::vector > stdVectorAutoRefCount;\n\t\t\teastl::tuple_vector > eaTupleVectorAutoRefCount;\n\n\t\t\tfor(size_t a = 0; a < 2048; a++)\n\t\t\t{\n\t\t\t\tstdVectorAutoRefCount.push_back(AutoRefCount(new RefCounted));\n\t\t\t\teaTupleVectorAutoRefCount.push_back(AutoRefCount(new RefCounted));\n\t\t\t}\n\n\t\t\tRefCounted::msAddRefCount = 0;\n\t\t\tRefCounted::msReleaseCount = 0;\n\t\t\tTestMoveErase(stopwatch1, stdVectorAutoRefCount);\n\t\t\t//EASTLTest_Printf(\"tuple_vector/erase std counts: %d %d\\n\", RefCounted::msAddRefCount, RefCounted::msReleaseCount);\n\n\t\t\tRefCounted::msAddRefCount = 0;\n\t\t\tRefCounted::msReleaseCount = 0;\n\t\t\tTestMoveErase(stopwatch2, eaTupleVectorAutoRefCount);\n\t\t\t//EASTLTest_Printf(\"tuple_vector/erase EA counts: %d %d\\n\", RefCounted::msAddRefCount, RefCounted::msReleaseCount);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"tuple_vector/erase\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\t\t\t\n\t\t\t//////////////////////////////////////////////////////////////////////////\n\t\t\t// Test various operations with \"padded\" data, to demonstrate access/modification of sparse data\n\n\t\t\tStdVectorUint64Padded stdVectorUint64Padded;\n\t\t\tEaTupleVectorUint64Padded eaTupleVectorUint64Padded;\n\n\t\t\t///////////////////////////////\n\t\t\t// Test push_back\n\t\t\t///////////////////////////////\n\n\t\t\tTestTuplePushBack(stopwatch1, stdVectorUint64Padded, intVector);\n\t\t\tTestTuplePushBack(stopwatch2, eaTupleVectorUint64Padded, intVector);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"tuple_vector/push_back\", stopwatch1.GetUnits(),\n\t\t\t\t\t\t\t\t\t stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test operator[].\n\t\t\t///////////////////////////////\n\n\t\t\tTestTupleBracket(stopwatch1, stdVectorUint64Padded);\n\t\t\tTestTupleBracket(stopwatch2, eaTupleVectorUint64Padded);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"tuple_vector/operator[]\", stopwatch1.GetUnits(),\n\t\t\t\t\t\t\t\t\t stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\t\t\t\n\n\t\t\t///////////////////////////////\n\t\t\t// Test iteration via find().\n\t\t\t///////////////////////////////\n\n\t\t\tTestTupleFind(stopwatch1, stdVectorUint64Padded);\n\t\t\tTestTupleFind(stopwatch2, eaTupleVectorUint64Padded);\n\t\t\tTestTupleFind(stopwatch1, stdVectorUint64Padded);\n\t\t\tTestTupleFind(stopwatch2, eaTupleVectorUint64Padded);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"tuple_vector/iteration\", stopwatch1.GetUnits(),\n\t\t\t\t\t\t\t\t\t stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test sort\n\t\t\t///////////////////////////////\n\n\t\t\t// Currently VC++ complains about our sort function decrementing std::iterator that is already at\n\t\t\t// begin(). In the strictest sense, that's a valid complaint, but we aren't testing std STL here. We\n\t\t\t// will want to revise our sort function eventually.\n\t\t\t#if !defined(_MSC_VER) || !defined(_ITERATOR_DEBUG_LEVEL) || (_ITERATOR_DEBUG_LEVEL < 2)\n\t\t\tTestTupleSort(stopwatch1, stdVectorUint64Padded);\n\t\t\tTestTupleSort(stopwatch2, eaTupleVectorUint64Padded);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"tuple_vector/sort\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(),\n\t\t\t\t\t\t\t\t\t stopwatch2.GetElapsedTime());\n\t\t\t#endif\n\n\t\t\t///////////////////////////////\n\t\t\t// Test insert\n\t\t\t///////////////////////////////\n\n\t\t\tTestTupleInsert(stopwatch1, stdVectorUint64Padded);\n\t\t\tTestTupleInsert(stopwatch2, eaTupleVectorUint64Padded);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"tuple_vector/insert\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(),\n\t\t\t\t\t\t\t\t\t stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test erase\n\t\t\t///////////////////////////////\n\n\t\t\tTestTupleErase(stopwatch1, stdVectorUint64Padded);\n\t\t\tTestTupleErase(stopwatch2, eaTupleVectorUint64Padded);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"tuple_vector/erase\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(),\n\t\t\t\t\t\t\t\t\t stopwatch2.GetElapsedTime());\n\t\t}\n\t}\n}\n\n\n\n\n\n\n\n\n\n\n\n\n" }, { "path": "benchmark/source/BenchmarkVector.cpp", "content": "/////////////////////////////////////////////////////////////////////////////\n// Copyright (c) Electronic Arts Inc. All rights reserved.\n/////////////////////////////////////////////////////////////////////////////\n\n\n#include \"EASTLBenchmark.h\"\n#include \"EASTLTest.h\"\n#include \n#include \n#include \n#include \n\n#ifdef _MSC_VER\n\t#pragma warning(push, 0)\n\t#pragma warning(disable: 4350)\n#endif\n#include \n#include \n#include \n#include \n#ifdef _MSC_VER\n\t#pragma warning(pop)\n#endif\n\n\nusing namespace EA;\n\n\ntypedef std::vector StdVectorUint64;\ntypedef eastl::vector EaVectorUint64;\n\n\nnamespace\n{\n\n\n\t//////////////////////////////////////////////////////////////////////////////\n\t// MovableType\n\t// \n\tstruct MovableType\n\t{\n\t\tint8_t* mpData;\n\t\tenum { kDataSize = 128 };\n\n\t\tMovableType() : mpData(new int8_t[kDataSize])\n\t\t\t{ memset(mpData, 0, kDataSize); }\n\n\t\tMovableType(const MovableType& x) : mpData(new int8_t[kDataSize])\n\t\t\t{ memcpy(mpData, x.mpData, kDataSize); }\n\n\t\tMovableType& operator=(const MovableType& x)\n\t\t{\n\t\t\tif(!mpData)\n\t\t\t\tmpData = new int8_t[kDataSize];\n\t\t\tmemcpy(mpData, x.mpData, kDataSize);\n\t\t\treturn *this;\n\t\t}\n\n\t\tMovableType(MovableType&& x) EA_NOEXCEPT : mpData(x.mpData)\n\t\t\t{ x.mpData = NULL; }\n\n\t\tMovableType& operator=(MovableType&& x)\n\t\t{\n\t\t\teastl::swap(mpData, x.mpData); // In practice it may not be right to do a swap, depending on the case.\n\t\t\treturn *this;\n\t\t}\n\n\t ~MovableType()\n\t\t\t{ delete[] mpData; }\n\t};\n\n\n\t//////////////////////////////////////////////////////////////////////////////\n\t// AutoRefCount\n\t// \n\t// Basic ref-counted object.\n\t//\n\ttemplate \n\tclass AutoRefCount\n\t{\n\tpublic:\n\t\tT* mpObject;\n\n\tpublic:\n\t\tAutoRefCount() EA_NOEXCEPT : mpObject(NULL) \n\t\t\t{}\n\n\t\tAutoRefCount(T* pObject) EA_NOEXCEPT : mpObject(pObject) \n\t\t{ \n\t\t\tif(mpObject)\n\t\t\t\tmpObject->AddRef();\n\t\t} \n\n\t\tAutoRefCount(T* pObject, int) EA_NOEXCEPT : mpObject(pObject) \n\t\t{\n\t\t\t// Inherit the existing refcount.\n\t\t} \n\n\t\tAutoRefCount(const AutoRefCount& x) EA_NOEXCEPT : mpObject(x.mpObject) \n\t\t{ \n\t\t\tif(mpObject)\n\t\t\t\tmpObject->AddRef();\n\t\t}\n\n\t\tAutoRefCount& operator=(const AutoRefCount& x) \n\t\t{ \n\t\t\treturn operator=(x.mpObject);\n\t\t}\n\n\t\tAutoRefCount& operator=(T* pObject)\n\t\t{ \n\t\t\tif(pObject != mpObject)\n\t\t\t{\n\t\t\t\tT* const pTemp = mpObject; // Create temporary to prevent possible problems with re-entrancy.\n\t\t\t\tif(pObject)\n\t\t\t\t\tpObject->AddRef();\n\t\t\t\tmpObject = pObject;\n\t\t\t\tif(pTemp)\n\t\t\t\t\tpTemp->Release();\n\t\t\t}\n\t\t\treturn *this;\n\t\t}\n\n\t\tAutoRefCount(AutoRefCount&& x) EA_NOEXCEPT : mpObject(x.mpObject) \n\t\t{ \n\t\t\tx.mpObject = NULL;\n\t\t}\n\n\t\tAutoRefCount& operator=(AutoRefCount&& x)\n\t\t{\n\t\t\tif(mpObject)\n\t\t\t\tmpObject->Release();\n\t\t\tmpObject = x.mpObject;\n\t\t\tx.mpObject = NULL;\n\t\t\treturn *this;\n\t\t}\n\n\t\t~AutoRefCount() \n\t\t{\n\t\t\tif(mpObject)\n\t\t\t\tmpObject->Release();\n\t\t}\n\n\t\tT& operator *() const EA_NOEXCEPT\n\t\t\t{ return *mpObject; }\n\n\t\tT* operator ->() const EA_NOEXCEPT\n\t\t\t{ return mpObject; }\n\n\t\toperator T*() const EA_NOEXCEPT\n\t\t\t{ return mpObject; }\n\n\t}; // class AutoRefCount\n\n\n\tstruct RefCounted\n\t{\n\t\tint mRefCount;\n\t\tstatic int msAddRefCount;\n\t\tstatic int msReleaseCount;\n\n\t\tRefCounted() : mRefCount(1) {}\n\n\t\tint AddRef()\n\t\t\t{ ++msAddRefCount; return ++mRefCount; }\n\n\t\tint Release()\n\t\t{\n\t\t\t++msReleaseCount;\n\t\t\tif(mRefCount > 1)\n\t\t\t\treturn --mRefCount;\n\t\t\tdelete this;\n\t\t\treturn 0;\n\t\t}\n\t};\n\n\tint RefCounted::msAddRefCount = 0;\n\tint RefCounted::msReleaseCount = 0;\n\n} // namespace \n\n\nnamespace \n{\n\ttemplate \n\tvoid TestPushBack(EA::StdC::Stopwatch& stopwatch, Container& c, eastl::vector& intVector)\n\t{\n\t\tstopwatch.Restart();\n\t\tfor(eastl_size_t j = 0, jEnd = intVector.size(); j < jEnd; j++)\n\t\t\tc.push_back((uint64_t)intVector[j]);\n\t\tstopwatch.Stop();\n\t}\n\n\n\ttemplate \n\tvoid TestBracket(EA::StdC::Stopwatch& stopwatch, Container& c)\n\t{\n\t\tuint64_t temp = 0;\n\t\tstopwatch.Restart();\n\t\tfor(typename Container::size_type j = 0, jEnd = c.size(); j < jEnd; j++)\n\t\t\ttemp += c[j];\n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%u\", (unsigned)(temp & 0xffffffff));\n\t}\n\n\n\ttemplate \n\tvoid TestFind(EA::StdC::Stopwatch& stopwatch, Container& c)\n\t{\n\t\tstopwatch.Restart();\n\t\ttypedef typename Container::iterator iterator_t; // This typedef is required to get this code to compile on RVCT\n\t\titerator_t it = eastl::find(c.begin(), c.end(), UINT64_C(0xffffffffffff));\n\t\tstopwatch.Stop();\n\t\tif(it != c.end())\n\t\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%u\", (unsigned)*it);\n\t}\n\n\n\ttemplate \n\tvoid TestSort(EA::StdC::Stopwatch& stopwatch, Container& c)\n\t{\n\t\t// Intentionally use eastl sort in order to measure just \n\t\t// vector access speed and not be polluted by sort speed.\n\t\tstopwatch.Restart();\n\t\teastl::quick_sort(c.begin(), c.end()); \n\t\tstopwatch.Stop();\n\t\tEA::StdC::Snprintf(Benchmark::gScratchBuffer, Benchmark::kScratchBufferSize, \"%u\", (unsigned)(c[0] & 0xffffffff));\n\t}\n\n\n\ttemplate \n\tvoid TestInsert(EA::StdC::Stopwatch& stopwatch, Container& c)\n\t{\n\t\ttypename Container::size_type j, jEnd;\n\t\ttypename Container::iterator it;\n\n\t\tstopwatch.Restart();\n\t\tfor(j = 0, jEnd = 100, it = c.begin(); j < jEnd; ++j)\n\t\t{\n\t\t\tit = c.insert(it, UINT64_C(0xffffffffffff));\n\n\t\t\tif(it == c.end()) // Try to safely increment the iterator three times.\n\t\t\t\tit = c.begin();\n\t\t\tif(++it == c.end())\n\t\t\t\tit = c.begin();\n\t\t\tif(++it == c.end())\n\t\t\t\tit = c.begin();\n\t\t}\n\t\tstopwatch.Stop();\n\t}\n\n\n\ttemplate \n\tvoid TestErase(EA::StdC::Stopwatch& stopwatch, Container& c)\n\t{\n\t\ttypename Container::size_type j, jEnd;\n\t\ttypename Container::iterator it;\n\n\t\tstopwatch.Restart();\n\t\tfor(j = 0, jEnd = 100, it = c.begin(); j < jEnd; ++j)\n\t\t{\n\t\t\tit = c.erase(it);\n\n\t\t\tif(it == c.end()) // Try to safely increment the iterator three times.\n\t\t\t\tit = c.begin();\n\t\t\tif(++it == c.end())\n\t\t\t\tit = c.begin();\n\t\t\tif(++it == c.end())\n\t\t\t\tit = c.begin();\n\t\t}\n\t\tstopwatch.Stop();\n\t}\n\n\n\ttemplate \n\tvoid TestMoveReallocate(EA::StdC::Stopwatch& stopwatch, Container& c)\n\t{\n\t\tstopwatch.Restart();\n\t\twhile(c.size() < 8192)\n\t\t\tc.resize(c.capacity() + 1);\n\t\tstopwatch.Stop();\n\t}\n\n\n\ttemplate \n\tvoid TestMoveErase(EA::StdC::Stopwatch& stopwatch, Container& c)\n\t{\n\t\tstopwatch.Restart();\n\t\twhile(!c.empty())\n\t\t\tc.erase(c.begin());\n\t\tstopwatch.Stop();\n\t}\n\n\n} // namespace\n\n\n\n\n\nvoid BenchmarkVector()\n{\n\tEASTLTest_Printf(\"Vector\\n\");\n\n\tEA::UnitTest::RandGenT rng(EA::UnitTest::GetRandSeed());\n\tEA::StdC::Stopwatch stopwatch1(EA::StdC::Stopwatch::kUnitsCPUCycles);\n\tEA::StdC::Stopwatch stopwatch2(EA::StdC::Stopwatch::kUnitsCPUCycles);\n\n\t{\n\t\teastl::vector intVector(100000);\n\t\teastl::generate(intVector.begin(), intVector.end(), rng);\n\n\t\tfor(int i = 0; i < 2; i++)\n\t\t{\n\t\t\tStdVectorUint64 stdVectorUint64;\n\t\t\tEaVectorUint64 eaVectorUint64;\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test push_back\n\t\t\t///////////////////////////////\n\n\t\t\tTestPushBack(stopwatch1, stdVectorUint64, intVector);\n\t\t\tTestPushBack(stopwatch2, eaVectorUint64, intVector);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"vector/push_back\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test operator[].\n\t\t\t///////////////////////////////\n\n\t\t\tTestBracket(stopwatch1, stdVectorUint64);\n\t\t\tTestBracket(stopwatch2, eaVectorUint64);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"vector/operator[]\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test iteration via find().\n\t\t\t///////////////////////////////\n\n\t\t\tTestFind(stopwatch1, stdVectorUint64);\n\t\t\tTestFind(stopwatch2, eaVectorUint64);\n\t\t\tTestFind(stopwatch1, stdVectorUint64);\n\t\t\tTestFind(stopwatch2, eaVectorUint64);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"vector/iteration\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test sort\n\t\t\t///////////////////////////////\n\n\t\t\t// Currently VC++ complains about our sort function decrementing std::iterator that is already at begin(). In the strictest sense,\n\t\t\t// that's a valid complaint, but we aren't testing std STL here. We will want to revise our sort function eventually.\n\t\t\t#if !defined(_MSC_VER) || !defined(_ITERATOR_DEBUG_LEVEL) || (_ITERATOR_DEBUG_LEVEL < 2)\n\t\t\t\tTestSort(stopwatch1, stdVectorUint64);\n\t\t\t\tTestSort(stopwatch2, eaVectorUint64);\n\n\t\t\t\tif(i == 1)\n\t\t\t\t\tBenchmark::AddResult(\"vector/sort\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\t\t\t#endif\n\n\t\t\t///////////////////////////////\n\t\t\t// Test insert\n\t\t\t///////////////////////////////\n\n\t\t\tTestInsert(stopwatch1, stdVectorUint64);\n\t\t\tTestInsert(stopwatch2, eaVectorUint64);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"vector/insert\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////\n\t\t\t// Test erase\n\t\t\t///////////////////////////////\n\n\t\t\tTestErase(stopwatch1, stdVectorUint64);\n\t\t\tTestErase(stopwatch2, eaVectorUint64);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"vector/erase\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////////////////\n\t\t\t// Test move of MovableType\n\t\t\t// Should be much faster with C++11 move.\n\t\t\t///////////////////////////////////////////\n\n\t\t\tstd::vector stdVectorMovableType;\n\t\t\teastl::vector eaVectorMovableType;\n\n\t\t\tTestMoveReallocate(stopwatch1, stdVectorMovableType);\n\t\t\tTestMoveReallocate(stopwatch2, eaVectorMovableType);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"vector/reallocate\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\tTestMoveErase(stopwatch1, stdVectorMovableType);\n\t\t\tTestMoveErase(stopwatch2, eaVectorMovableType);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"vector/erase\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\n\n\t\t\t///////////////////////////////////////////\n\t\t\t// Test move of AutoRefCount\n\t\t\t// Should be much faster with C++11 move.\n\t\t\t///////////////////////////////////////////\n\n\t\t\tstd::vector > stdVectorAutoRefCount;\n\t\t\teastl::vector > eaVectorAutoRefCount;\n\n\t\t\tfor(size_t a = 0; a < 2048; a++)\n\t\t\t{\n\t\t\t\tstdVectorAutoRefCount.push_back(AutoRefCount(new RefCounted));\n\t\t\t\teaVectorAutoRefCount.push_back(AutoRefCount(new RefCounted));\n\t\t\t}\n\n\t\t\tRefCounted::msAddRefCount = 0;\n\t\t\tRefCounted::msReleaseCount = 0;\n\t\t\tTestMoveErase(stopwatch1, stdVectorAutoRefCount);\n\t\t\tEASTLTest_Printf(\"vector/erase std counts: %d %d\\n\", RefCounted::msAddRefCount, RefCounted::msReleaseCount);\n\n\t\t\tRefCounted::msAddRefCount = 0;\n\t\t\tRefCounted::msReleaseCount = 0;\n\t\t\tTestMoveErase(stopwatch2, eaVectorAutoRefCount);\n\t\t\tEASTLTest_Printf(\"vector/erase EA counts: %d %d\\n\", RefCounted::msAddRefCount, RefCounted::msReleaseCount);\n\n\t\t\tif(i == 1)\n\t\t\t\tBenchmark::AddResult(\"vector/erase\", stopwatch1.GetUnits(), stopwatch1.GetElapsedTime(), stopwatch2.GetElapsedTime());\n\t\t}\n\t}\n}\n\n\n\n\n\n\n\n\n\n\n\n\n" }, { "path": "benchmark/source/EASTLBenchmark.cpp", "content": "/////////////////////////////////////////////////////////////////////////////\n// Copyright (c) Electronic Arts Inc. All rights reserved.\n/////////////////////////////////////////////////////////////////////////////\n\n\n#include \"EASTLBenchmark.h\"\n#include \"EASTLTest.h\"\n#include \n#include \n\n#ifdef _MSC_VER\n\t#pragma warning(push, 0)\n#endif\n#include \n#include \n#include \n#ifdef _MSC_VER\n\t#pragma warning(pop)\n#endif\n\n\n\nnamespace Benchmark\n{\n\tstatic int64_t ConvertStopwatchUnits(EA::StdC::Stopwatch::Units unitsSource, int64_t valueSource, EA::StdC::Stopwatch::Units unitsDest)\n\t{\n\t\tusing namespace EA::StdC;\n\n\t\tint64_t valueDest = valueSource;\n\n\t\tif(unitsSource != unitsDest)\n\t\t{\n\t\t\tdouble sourceMultiplier;\n\n\t\t\tswitch (unitsSource)\n\t\t\t{\n\t\t\t\tcase Stopwatch::kUnitsCPUCycles:\n\t\t\t\t\tsourceMultiplier = Stopwatch::GetUnitsPerCPUCycle(unitsDest); // This will typically be a number less than 1.\n\t\t\t\t\tvalueDest = (int64_t)(valueSource * sourceMultiplier);\n\t\t\t\t\tbreak;\n\n\t\t\t\tcase Stopwatch::kUnitsCycles:\n\t\t\t\t\tsourceMultiplier = Stopwatch::GetUnitsPerStopwatchCycle(unitsDest); // This will typically be a number less than 1.\n\t\t\t\t\tvalueDest = (int64_t)(valueSource * sourceMultiplier);\n\t\t\t\t\tbreak;\n\n\t\t\t\tcase Stopwatch::kUnitsNanoseconds:\n\t\t\t\tcase Stopwatch::kUnitsMicroseconds:\n\t\t\t\tcase Stopwatch::kUnitsMilliseconds:\n\t\t\t\tcase Stopwatch::kUnitsSeconds:\n\t\t\t\tcase Stopwatch::kUnitsMinutes:\n\t\t\t\tcase Stopwatch::kUnitsUserDefined:\n\t\t\t\t\t// To do. Also, handle the case of unitsDest being Cycles or CPUCycles and unitsSource being a time.\n\t\t\t\t\tbreak;\n\t\t\t}\n\t\t}\n\n\t\treturn valueDest;\n\t}\n\n\tvoid WriteTime(int64_t timeNS, eastl::string& sTime)\n\t{\n\t\tif(timeNS > 1000000000)\n\t\t\tsTime.sprintf(\" %6.2f s\", (double)timeNS / 1000000000);\n\t\telse if(timeNS > 1000000)\n\t\t\tsTime.sprintf(\"%6.1f ms\", (double)timeNS / 1000000);\n\t\telse if(timeNS > 1000)\n\t\t\tsTime.sprintf(\"%6.1f us\", (double)timeNS / 1000);\n\t\telse\n\t\t\tsTime.sprintf(\"%6.1f ns\", (double)timeNS / 1);\n\t}\n\n\n\n\tEnvironment gEnvironment;\n\n\tEnvironment& GetEnvironment()\n\t{\n\t\treturn gEnvironment;\n\t}\n\n\n\n\tResultSet gResultSet;\n\n\tResultSet& GetResultSet()\n\t{\n\t\treturn gResultSet;\n\t}\n\n\n\n\t// Scratch sprintf buffer\n\tchar gScratchBuffer[kScratchBufferSize];\n\n\n\tvoid DoNothing(...)\n\t{\n\t\t// Intentionally nothing.\n\t}\n\n\n\tvoid AddResult(const char* pName, int units, int64_t nTime1, int64_t nTime2, const char* pNotes)\n\t{\n\t\tResult result;\n\n\t\tresult.msName = pName;\n\t\tresult.mUnits = units;\n\t\tresult.mTime1 = nTime1;\n\t\tresult.mTime1NS = ConvertStopwatchUnits((EA::StdC::Stopwatch::Units)units, nTime1, EA::StdC::Stopwatch::kUnitsNanoseconds);\n\t\tresult.mTime2 = nTime2;\n\t\tresult.mTime2NS = ConvertStopwatchUnits((EA::StdC::Stopwatch::Units)units, nTime2, EA::StdC::Stopwatch::kUnitsNanoseconds);\n\n\t\tif(pNotes)\n\t\t\tresult.msNotes = pNotes;\n\n\t\tgResultSet.insert(result);\n\t}\n\n\n\tvoid PrintResultLine(const Result& result)\n\t{\n\t\tconst double fRatio = (double)result.mTime1 / (double)result.mTime2;\n\t\tconst double fRatioPrinted = (fRatio > 100) ? 100 : fRatio;\n\t\tconst double fPercentChange = fabs(((double)result.mTime1 - (double)result.mTime2) / (((double)result.mTime1 + (double)result.mTime2) / 2));\n\t\tconst bool bDifference = (result.mTime1 > 10) && (result.mTime2 > 10) && (fPercentChange > 0.25);\n\t\tconst char* pDifference = (bDifference ? (result.mTime1 < result.mTime2 ? \"-\" : \"+\") : \"\");\n\n\t\teastl::string sClockTime1, sClockTime2;\n\n\t\tWriteTime(result.mTime1NS, sClockTime1); // This converts an integer in nanoseconds (e.g. 23400000) to a string (e.g. \"23.4 ms\")\n\t\tWriteTime(result.mTime2NS, sClockTime2);\n\n\t\tEA::UnitTest::Report(\"%-43s | %13\" PRIu64 \" %s | %13\" PRIu64 \" %s | %10.2f%10s\", result.msName.c_str(), result.mTime1, sClockTime1.c_str(), result.mTime2, sClockTime2.c_str(), fRatioPrinted, pDifference);\n\n\t\tif(result.msNotes.length()) // If there are any notes...\n\t\t\tEA::UnitTest::Report(\" %s\", result.msNotes.c_str());\n\t\tEA::UnitTest::Report(\"\\n\");\n\t}\n\n\n\t#if defined(EASTL_BENCHMARK_WRITE_FILE) && EASTL_BENCHMARK_WRITE_FILE\n\n\t\t#if !defined(EASTL_BENCHMARK_WRITE_FILE_PATH)\n\t\t\t#define EASTL_BENCHMARK_WRITE_FILE_PATH \"BenchmarkResults.txt\"\n\t\t#endif\n\n\t\tstruct FileWriter\n\t\t{\n\t\t\tFILE* mpReportFile;\n\t\t\tEA::EAMain::ReportFunction mpSavedReportFunction;\n\t\t\tstatic FileWriter* gpFileWriter;\n\n\t\t\tstatic void StaticPrintfReportFunction(const char8_t* pText)\n\t\t\t{\n\t\t\t\tif(gpFileWriter)\n\t\t\t\t\tgpFileWriter->PrintfReportFunction(pText);\n\t\t\t}\n\n\t\t\tvoid PrintfReportFunction(const char8_t* pText)\n\t\t\t{\n\t\t\t\tfwrite(pText, strlen(pText), 1, mpReportFile);\n\t\t\t\tEA::EAMain::ReportFunction gpReportFunction = EA::EAMain::GetDefaultReportFunction();\n\t\t\t\tgpReportFunction(pText);\n\t\t\t}\n\n\t\t\tFileWriter() : mpReportFile(NULL), mpSavedReportFunction(NULL)\n\t\t\t{\n\t\t\t\tmpReportFile = fopen(EASTL_BENCHMARK_WRITE_FILE_PATH, \"w+\");\n\n\t\t\t\tif(mpReportFile)\n\t\t\t\t{\n\t\t\t\t\tgpFileWriter = this;\n\t\t\t\t\tmpSavedReportFunction = EA::EAMain::GetDefaultReportFunction();\n\t\t\t\t\tEA::EAMain::SetReportFunction(StaticPrintfReportFunction);\n\t\t\t\t}\n\t\t\t}\n\n\t\t ~FileWriter()\n\t\t\t{\n\t\t\t\tif(mpReportFile)\n\t\t\t\t{\n\t\t\t\t\tgpFileWriter = NULL;\n\t\t\t\t\tEA::EAMain::SetReportFunction(mpSavedReportFunction);\n\t\t\t\t\tfclose(mpReportFile);\n\t\t\t\t}\n\t\t\t}\n\t\t};\n\n\t\tFileWriter* FileWriter::gpFileWriter = NULL;\n\t#endif\n\n\n\tvoid PrintResults()\n\t{\n\t\t#if defined(EASTL_BENCHMARK_WRITE_FILE) && EASTL_BENCHMARK_WRITE_FILE\n\t\t\tFileWriter fileWriter; // This will auto-execute.\n\t\t#endif\n\n\t\t// Print the results\n\t\tEA::UnitTest::Report(\"\\n\");\n\t\tEA::UnitTest::Report(\"****************************************************************************************\\n\");\n\t\tEA::UnitTest::Report(\"EASTL Benchmark test results\\n\");\n\t\tEA::UnitTest::Report(\"****************************************************************************************\\n\");\n\t\tEA::UnitTest::Report(\"\\n\");\n\t\tEA::UnitTest::Report(\"EASTL version: %s\\n\", EASTL_VERSION);\n\t\tEA::UnitTest::Report(\"Platform: %s\\n\", gEnvironment.msPlatform.c_str());\n\t\tEA::UnitTest::Report(\"Compiler: %s\\n\", EA_COMPILER_STRING);\n\t\t#if defined(EA_DEBUG) || defined(_DEBUG)\n\t\tEA::UnitTest::Report(\"Allocator: PPMalloc::GeneralAllocatorDebug. Thread safety enabled.\\n\");\n\t\tEA::UnitTest::Report(\"Build: Debug. Inlining disabled. STL debug features disabled.\\n\");\n\t\t#else\n\t\tEA::UnitTest::Report(\"Allocator: PPMalloc::GeneralAllocator. Thread safety enabled.\\n\");\n\t\tEA::UnitTest::Report(\"Build: Full optimization. Inlining enabled.\\n\");\n\t\t#endif\n\t\tEA::UnitTest::Report(\"\\n\");\n\t\tEA::UnitTest::Report(\"Values are ticks and time to complete tests; smaller values are better.\\n\");\n\t\tEA::UnitTest::Report(\"\\n\");\n\t\tEA::UnitTest::Report(\"%-43s%26s%26s%13s%13s\\n\", \"Test\", gEnvironment.msSTLName1.c_str(), gEnvironment.msSTLName2.c_str(), \"Ratio\", \"Difference?\");\n\t\tEA::UnitTest::Report(\"---------------------------------------------------------------------------------------------------------------------\\n\");\n\n\t\teastl::string sTestTypeLast;\n\t\teastl::string sTestTypeTemp;\n\n\t\tfor(ResultSet::iterator it = gResultSet.begin(); it != gResultSet.end(); ++it)\n\t\t{\n\t\t\tconst Result& result = *it;\n\n\t\t\teastl_size_t n = result.msName.find('/');\n\t\t\tif(n == eastl::string::npos)\n\t\t\t\tn = result.msName.length();\n\t\t\tsTestTypeTemp.assign(result.msName, 0, n);\n\n\t\t\tif(sTestTypeTemp != sTestTypeLast) // If it looks like we are changing to a new test type... add an empty line to help readability.\n\t\t\t{\n\t\t\t\tif(it != gResultSet.begin())\n\t\t\t\t\tEA::UnitTest::Report(\"\\n\");\n\t\t\t\tsTestTypeLast = sTestTypeTemp;\n\t\t\t}\n\n\t\t\tPrintResultLine(result);\n\t\t}\n\n\t\t// We will print out a final line that has the sum of the rows printed above.\n\t\tResult resultSum;\n\t\tresultSum.msName = \"sum\";\n\n\t\tfor(ResultSet::iterator its = gResultSet.begin(); its != gResultSet.end(); ++its)\n\t\t{\n\t\t\tconst Result& resultTemp = *its;\n\n\t\t\tEASTL_ASSERT(resultTemp.mUnits == EA::StdC::Stopwatch::kUnitsCPUCycles); // Our ConvertStopwatchUnits call below assumes that every measured time is CPUCycles.\n\t\t\tresultSum.mTime1 += resultTemp.mTime1;\n\t\t\tresultSum.mTime2 += resultTemp.mTime2;\n\t\t}\n\n\t\t// We do this convert as a final step instead of the loop in order to avoid loss of precision.\n\t\tresultSum.mTime1NS = ConvertStopwatchUnits(EA::StdC::Stopwatch::kUnitsCPUCycles, resultSum.mTime1, EA::StdC::Stopwatch::kUnitsNanoseconds);\n\t\tresultSum.mTime2NS = ConvertStopwatchUnits(EA::StdC::Stopwatch::kUnitsCPUCycles, resultSum.mTime2, EA::StdC::Stopwatch::kUnitsNanoseconds);\n\t\tEA::UnitTest::Report(\"\\n\");\n\t\tPrintResultLine(resultSum);\n\n\t\tEA::UnitTest::Report(\"\\n\");\n\t\tEA::UnitTest::Report(\"****************************************************************************************\\n\");\n\t\tEA::UnitTest::Report(\"\\n\");\n\n\t\t// Clear the results\n\t\tgResultSet.clear();\n\t\tgEnvironment.clear();\n\t}\n\n} // namespace Benchmark\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n" }, { "path": "benchmark/source/EASTLBenchmark.h", "content": "/////////////////////////////////////////////////////////////////////////////\n// Copyright (c) Electronic Arts Inc. All rights reserved.\n/////////////////////////////////////////////////////////////////////////////\n\n\n#ifndef EASTLBENCHMARK_H\n#define EASTLBENCHMARK_H\n\n\n// Intrinsic control\n//\n// Our benchmark results are being skewed by inconsistent decisions by the \n// VC++ compiler to use intrinsic functions. Additionally, many of our \n// benchmarks work on large blocks of elements, whereas intrinsics often\n// are an improvement only over small blocks of elements. As a result, \n// enabling of intrinsics is often resulting in poor benchmark results for\n// code that gets an intrinsic enabled for it, even though it will often\n// happen in real code to be the opposite case. The disabling of intrinsics\n// here often results in EASTL performance being lower than it would be in\n// real-world situations.\n//\n#include \n#ifdef _MSC_VER\n\t#pragma function(strlen, strcmp, strcpy, strcat, memcpy, memcmp, memset)\n#endif\n\n\n#include \n#include \n#include \n#include \n#include \n#include \n\n\nvoid BenchmarkSort();\nvoid BenchmarkList();\nvoid BenchmarkString();\nvoid BenchmarkVector();\nvoid BenchmarkDeque();\nvoid BenchmarkSet();\nvoid BenchmarkMap();\nvoid BenchmarkHash();\nvoid BenchmarkAlgorithm();\nvoid BenchmarkHeap();\nvoid BenchmarkBitset();\nvoid BenchmarkTupleVector();\n\n\nnamespace Benchmark\n{\n\n\t// Environment\n\t//\n\t// The environment for this benchmark test.\n\t//\n\tstruct Environment\n\t{\n\t\teastl::string8 msPlatform; // Name of test platform (e.g. \"Windows\")\n\t\teastl::string8 msSTLName1; // Name of competitor #1 (e.g. \"EASTL\").\n\t\teastl::string8 msSTLName2; // Name of competitor #2 (e.g. \"MS STL\").\n\n\t\tvoid clear() { msPlatform.set_capacity(0); msSTLName1.set_capacity(0); msSTLName2.set_capacity(0); }\n\t};\n\n\tEnvironment& GetEnvironment();\n\n\n\t// Result\n\t//\n\t// An individual benchmark result.\n\t//\n\tstruct Result\n\t{\n\t\teastl::string8 msName; // Test name (e.g. \"vector/insert\").\n\t\tint mUnits; // Timing units (e.g. EA::StdC::Stopwatch::kUnitsSeconds).\n\t\tint64_t mTime1; // Time of competitor #1.\n\t\tuint64_t mTime1NS; // Nanoseconds.\n\t\tint64_t mTime2; // Time of competitor #2.\n\t\tint64_t mTime2NS; // Nanoseconds.\n\t\teastl::string8 msNotes; // Any comments to attach to this result.\n\n\t\tResult() : msName(), mUnits(EA::StdC::Stopwatch::kUnitsCPUCycles), \n\t\t\t\t\tmTime1(0), mTime1NS(0), mTime2(0), mTime2NS(0), msNotes() { }\n\t};\n\n\tinline bool operator<(const Result& r1, const Result& r2)\n\t\t{ return r1.msName < r2.msName; } \n\n\ttypedef eastl::set ResultSet;\n\n\tResultSet& GetResultSet();\n\n\n\t// Scratch sprintf buffer\n\tconst int kScratchBufferSize = 1024;\n\textern char gScratchBuffer[kScratchBufferSize];\n\n\n\n\t// Utility functions\n\t//\n\tvoid DoNothing(...);\n\tvoid AddResult(const char* pName, int units, int64_t nTime1, int64_t nTime2, const char* pNotes = NULL);\n\tvoid PrintResults();\n\tvoid WriteTime(int64_t timeNS, eastl::string& sTime);\n\t\n\n} // namespace Benchmark\n\n\n\n\n///////////////////////////////////////////////////////////////////////////////\n/// LargePOD\n///\n/// Implements a structure which is essentially a largish POD. Useful for testing\n/// containers and algorithms for their ability to efficiently work with PODs.\n/// This class isn't strictly a POD by the definition of the C++ standard, \n/// but it suffices for our interests.\n///\nstruct LargeObject\n{\n\tint32_t mData[2048];\n};\n\nstruct LargePOD\n{\n\tLargeObject mLargeObject1;\n\tLargeObject mLargeObject2;\n\tconst char* mpName1;\n\tconst char* mpName2;\n\n\texplicit LargePOD(int32_t x = 0) // A true POD doesn't have a non-trivial constructor.\n\t{\n\t\tmemset(mLargeObject1.mData, 0, sizeof(mLargeObject1.mData));\n\t\tmemset(mLargeObject2.mData, 0, sizeof(mLargeObject2.mData));\n\t\tmLargeObject1.mData[0] = x;\n\n\t\tmpName1 = \"LargePOD1\";\n\t\tmpName2 = \"LargePOD2\";\n\t}\n\n\tLargePOD(const LargePOD& largePOD) // A true POD doesn't have a non-trivial copy-constructor.\n\t\t: mLargeObject1(largePOD.mLargeObject1), \n\t\t mLargeObject2(largePOD.mLargeObject2), \n\t\t mpName1(largePOD.mpName1),\n\t\t mpName2(largePOD.mpName2)\n\t{\n\t}\n\n\tvirtual ~LargePOD() { }\n\n\tLargePOD& operator=(const LargePOD& largePOD) // A true POD doesn't have a non-trivial assignment operator.\n\t{\n\t\tif(&largePOD != this)\n\t\t{\n\t\t\tmLargeObject1 = largePOD.mLargeObject1; \n\t\t\tmLargeObject2 = largePOD.mLargeObject2; \n\t\t\tmpName1 = largePOD.mpName1;\n\t\t\tmpName2 = largePOD.mpName2;\n\t\t}\n\t\treturn *this;\n\t}\n\n\tvirtual void DoSomething() // Note that by declaring this virtual, this class is not truly a POD.\n\t{ // But it acts like a POD for the purposes of EASTL algorithms.\n\t\tmLargeObject1.mData[1]++;\n\t}\n\n\toperator int()\n\t{\n\t\treturn (int)mLargeObject1.mData[0];\n\t}\n};\n\n//EASTL_DECLARE_POD(LargePOD);\n//EASTL_DECLARE_TRIVIAL_CONSTRUCTOR(LargePOD);\n//EASTL_DECLARE_TRIVIAL_COPY(LargePOD);\n//EASTL_DECLARE_TRIVIAL_ASSIGN(LargePOD);\n//EASTL_DECLARE_TRIVIAL_DESTRUCTOR(LargePOD);\n//EASTL_DECLARE_TRIVIAL_RELOCATE(LargePOD);\n\n// Operators\n// We specifically define only == and <, in order to verify that \n// our containers and algorithms are not mistakenly expecting other \n// operators for the contained and manipulated classes.\ninline bool operator==(const LargePOD& t1, const LargePOD& t2)\n{\n\treturn (memcmp(&t1.mLargeObject1, &t2.mLargeObject1, sizeof(t1.mLargeObject1)) == 0) &&\n\t\t (memcmp(&t1.mLargeObject2, &t2.mLargeObject2, sizeof(t1.mLargeObject2)) == 0) &&\n\t\t (strcmp(t1.mpName1, t2.mpName1) == 0) &&\n\t\t (strcmp(t1.mpName2, t2.mpName2) == 0);\n}\n\ninline bool operator<(const LargePOD& t1, const LargePOD& t2)\n{\n\treturn (memcmp(&t1.mLargeObject1, &t2.mLargeObject1, sizeof(t1.mLargeObject1)) < 0) &&\n\t\t (memcmp(&t1.mLargeObject2, &t2.mLargeObject2, sizeof(t1.mLargeObject2)) < 0) &&\n\t\t (strcmp(t1.mpName1, t2.mpName1) < 0) &&\n\t\t (strcmp(t1.mpName2, t2.mpName2) < 0);\n}\n\n\n\n\n\n#endif // Header sentry\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n" }, { "path": "benchmark/source/main.cpp", "content": "///////////////////////////////////////////////////////////////////////////////\n// Copyright (c) Electronic Arts Inc. All rights reserved.\n///////////////////////////////////////////////////////////////////////////////\n\n\n#include \"EASTLBenchmark.h\"\n#include \"EASTLTest.h\"\n#if !EASTL_OPENSOURCE\n #include \n#endif\n#include \n#include \n#include \n#include \n#include \n#include \nEA_DISABLE_VC_WARNING(4946)\n#include \"EAMain/EAEntryPointMain.inl\"\n#include \"EASTLTestAllocator.h\"\n\n\n///////////////////////////////////////////////////////////////////////////////\n// gpEAGeneralAllocator / gpEAGeneralAllocatorDebug\n//\n#if !EASTL_OPENSOURCE\nnamespace EA\n{\n\tnamespace Allocator\n\t{\n\t\t#ifdef EA_DEBUG\n\t\t\textern GeneralAllocatorDebug gGeneralAllocator;\n\t\t\textern PPM_API GeneralAllocatorDebug* gpEAGeneralAllocatorDebug;\n\t\t#else\n\t\t\textern GeneralAllocator gGeneralAllocator;\n\t\t\textern PPM_API GeneralAllocator* gpEAGeneralAllocator;\n\t\t#endif\n\t}\n}\n#endif\n\n\n///////////////////////////////////////////////////////////////////////////////\n// Required by EASTL.\n//\n#if !defined(EASTL_EASTDC_VSNPRINTF) || !EASTL_EASTDC_VSNPRINTF\n\tint Vsnprintf8(char8_t* pDestination, size_t n, const char8_t* pFormat, va_list arguments)\n\t{\n\t\treturn EA::StdC::Vsnprintf(pDestination, n, pFormat, arguments);\n\t}\n\n\tint Vsnprintf16(char16_t* pDestination, size_t n, const char16_t* pFormat, va_list arguments)\n\t{\n\t\treturn EA::StdC::Vsnprintf(pDestination, n, pFormat, arguments);\n\t}\n\n\t#if (EASTDC_VERSION_N >= 10600)\n\t\tint Vsnprintf32(char32_t* pDestination, size_t n, const char32_t* pFormat, va_list arguments)\n\t\t{\n\t\t\treturn EA::StdC::Vsnprintf(pDestination, n, pFormat, arguments);\n\t\t}\n\t#endif\n#endif\n\n\n///////////////////////////////////////////////////////////////////////////////\n// main\n//\nint EAMain(int argc, char* argv[])\n{\n\tbool bWaitAtEnd = false;\n\tbool bPrintHelp = false;\n\tint nOptionCount = 0;\n\tint nErrorCount = 0;\n\n\tEA::EAMain::PlatformStartup();\n\tEA::EAMain::SetVerbosity(2); // Default value.\n\n\t// Set up debug parameters.\n\t#ifdef EA_DEBUG\n\t // Only enable this temporarily to help find any problems you might find.\n\t // EA::Allocator::gpEAGeneralAllocatorDebug->SetAutoHeapValidation(EA::Allocator::GeneralAllocator::kHeapValidationLevelBasic, 16);\n\t#endif\n\n\t// Parse command line arguments\n\tfor(int i = 1; i < argc; i++)\n\t{\n\t\tif(strstr(argv[i], \"-w\") == argv[i])\n\t\t{\n\t\t\tbWaitAtEnd = true;\n\t\t\tnOptionCount++;\n\t\t}\n\t\telse if(strstr(argv[i], \"-v\") == argv[i])\n\t\t{\n\t\t\tuint32_t verbosity = EA::StdC::AtoU32(argv[i] + 3);\n\t\t\tEA::EAMain::SetVerbosity(verbosity);\n\t\t\tnOptionCount++;\n\t\t}\n\t\telse if(strstr(argv[i], \"-l:\") == argv[i])\n\t\t{\n\t\t\tgEASTL_TestLevel = atoi(argv[i] + 3);\n\t\t\tif(gEASTL_TestLevel < kEASTL_TestLevelLow)\n\t\t\t\tgEASTL_TestLevel = kEASTL_TestLevelLow;\n\t\t\telse if(gEASTL_TestLevel > kEASTL_TestLevelHigh)\n\t\t\t\tgEASTL_TestLevel = kEASTL_TestLevelHigh;\n\t\t\tnOptionCount++;\n\t\t}\n\t\telse if(strstr(argv[i], \"-s:\") == argv[i])\n\t\t{\n\t\t\tuint32_t seed = (eastl_size_t)atoi(argv[i] + 3);\n\t\t\tEA::UnitTest::SetRandSeed(seed);\n\t\t\tnOptionCount++;\n\t\t}\n\t\telse if((strstr(argv[i], \"-?\") == argv[i]) || (strstr(argv[i], \"-h\") == argv[i]))\n\t\t{\n\t\t\tbPrintHelp = true;\n\t\t\tnOptionCount++;\n\t\t}\n\t}\n\n\t// Print user help.\n\tif(!bPrintHelp)\n\t\tbPrintHelp = (nOptionCount == 0);\n\n\tif(bPrintHelp)\n\t{\n\t\tEASTLTest_Printf(\"Options\\n\");\n\t\tEASTLTest_Printf(\" -w Wait at end.\\n\");\n\t\tEASTLTest_Printf(\" -l:N Test level in range of [1, 10]. 10 means maximum testing.\\n\");\n\t\tEASTLTest_Printf(\" -s:N Specify a randomization seed. 0 is default and means use clock.\\n\");\n\t\tEASTLTest_Printf(\" -? Show help.\\n\");\n\t}\n\n\n\t// Set up test information\n\tBenchmark::Environment& environment = Benchmark::GetEnvironment();\n\tenvironment.msPlatform = EA_PLATFORM_DESCRIPTION;\n\tenvironment.msSTLName1 = GetStdSTLName();\n\tenvironment.msSTLName2 = \"EASTL\";\n\n\n\t// Run tests\n\t#ifndef EA_DEBUG\n\t\tEA::UnitTest::SetHighThreadPriority();\n\t#endif\n\n\tEA::StdC::Stopwatch stopwatch(EA::StdC::Stopwatch::kUnitsSeconds, true); // Measure seconds, start the counting immediately.\n\n\tBenchmarkAlgorithm();\n\tBenchmarkList();\n\tBenchmarkString();\n\tBenchmarkVector();\n\tBenchmarkDeque();\n\tBenchmarkSet();\n\tBenchmarkMap();\n\tBenchmarkHash();\n\tBenchmarkHeap();\n\tBenchmarkBitset();\n\tBenchmarkSort();\n\tBenchmarkTupleVector();\n\n\tstopwatch.Stop();\n\n\t#ifndef EA_DEBUG\n\t\tEA::UnitTest::SetNormalThreadPriority();\n\t#endif\n\n\tBenchmark::PrintResults();\n\n\teastl::string sClockTime;\n\tBenchmark::WriteTime(stopwatch.GetElapsedTime(), sClockTime);\n\n\tEASTLTest_Printf(\"Time to complete all tests: %s.\\n\", sClockTime.c_str());\n\n\t// Done\n\tif(bWaitAtEnd)\n\t{\n\t\tEASTLTest_Printf(\"\\nPress any key to exit.\\n\");\n\t\tgetchar(); // Wait for the user and shutdown\n\t}\n\n\tEA::EAMain::PlatformShutdown(nErrorCount);\n\n\treturn 0;\n}\n\n\n\n\n\n\n\n\n\n\n" }, { "path": "doc/Benchmarks.md", "content": "# EASTL Benchmarks\n\n## Introduction\n\nThis 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.\n\nIt'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.\n\nWhile 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:\n\n1. 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.\n2. 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.\n3. 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).\n\n## Benchmarks\n\nBelow 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.\n\n| Platform | Compiler | STL type | Build | Results |\n|------|------|------|------|------|\n| Win32 | VC++ 7.1 | Microsoft (Dinkumware) | Debug | [Detail]() |\n| Win32 | VC++ 7.1 | Microsoft (Dinkumware) | Release | [Detail]() |\n| Win32 | VC++ 7.1 | STLPort | Debug | [Detail]() |\n| Win32 | VC++ 7.1 | STLPort | Release | [Detail]() |\n\n### Win32.VC71.MS.Debug\n\n```\nEASTL version: 0.96.00\nPlatform: Windows on X86\nCompiler: Microsoft Visual C++ compiler, version 1310\nAllocator: PPMalloc::GeneralAllocatorDebug. Thread safety enabled.\nBuild: Debug. Inlining disabled. STL debug features disabled.\n\nValues are times to complete tests; smaller values are better.\nAlarm indicates a greater than 10% difference.\n\nTest VC++ EASTL Ratio Alarm\n----------------------------------------------------------------------------------------\nalgorithm/adj_find/vector 33061345 6497757 5.09 *\nalgorithm/copy/vector 5844906 4876076 1.20 *\nalgorithm/copy/vector 1634346 166065 9.84 *\nalgorithm/copy_backward/vector 4515974 4638892 0.97\nalgorithm/copy_backward/vector 1821168 121746 14.96 *\nalgorithm/count/vector 17048884 2720766 6.27 *\nalgorithm/equal_range/vector 1111147812 448756888 2.48 *\nalgorithm/fill/bool[] 1728722 91936 18.80 *\nalgorithm/fill/char[]/'d' 1299200 33745 38.50 *\nalgorithm/fill/vector/'d' 10205092 33796 100.00 *\nalgorithm/fill/vector/0 10200748 33805 100.00 *\nalgorithm/fill/vector 10416538 1399687 7.44 *\nalgorithm/fill/vector 10221837 1307700 7.82 *\nalgorithm/fill_n/bool[] 1399033 34196 40.91 *\nalgorithm/fill_n/char[] 1299225 33754 38.49 *\nalgorithm/fill_n/vector 5961637 1371900 4.35 *\nalgorithm/find_end/string/end 16569373 2657372 6.24 *\nalgorithm/find_end/string/middle 16558638 20242410 0.82 *\nalgorithm/find_end/string/none 16811207 40480468 0.42 *\nalgorithm/lex_cmp/schar[] 1749674 194429 9.00 *\nalgorithm/lex_cmp/vector 32824195 5253587 6.25 *\nalgorithm/lex_cmp/vector 29852034 202658 100.00 *\nalgorithm/lower_bound/vector 798624462 350027935 2.28 *\nalgorithm/min_element/vector 21675298 5314676 4.08 *\nalgorithm/rand_shuffle/vector 84236190 43677506 1.93 *\nalgorithm/reverse/list 3007292 2105799 1.43 *\nalgorithm/reverse/vector 2974618 2124796 1.40 *\nalgorithm/search/string 16228158 3594268 4.52 *\nalgorithm/search_n/string 16926985 1522096 11.12 *\nalgorithm/unique/vector 54206243 9988002 5.43 *\nalgorithm/unique/vector 26940079 1741991 15.47 *\nalgorithm/unique/vector 47621344 5213127 9.13 *\nalgorithm/upper_bound/vector 372381295 137901552 2.70 *\n\nbitset<1500>/>>=/1 90196544 92539832 0.97\nbitset<1500>/count 50753832 53742117 0.94\nbitset<1500>/flip 86935875 85121117 1.02\nbitset<1500>/reset 78153837 79922611 0.98\nbitset<1500>/set() 79214968 79360658 1.00\nbitset<1500>/set(i) 11300589 12199651 0.93\nbitset<1500>/test 11282679 13186450 0.86 *\n\nbitset<15>/>>=/1 10500577 6000559 1.75 *\nbitset<15>/count 4000356 6399753 0.63 *\nbitset<15>/flip 7268877 5647944 1.29 *\nbitset<15>/reset 8564235 5800163 1.48 *\nbitset<15>/set() 9935523 5914012 1.68 *\nbitset<15>/set(i) 11199703 12503637 0.90 *\nbitset<15>/test 10600623 12899592 0.82 *\n\nbitset<35>/>>=/1 13076052 6599834 1.98 *\nbitset<35>/count 4800384 11500330 0.42 *\nbitset<35>/flip 7915439 5816313 1.36 *\nbitset<35>/reset 9400049 5803180 1.62 *\nbitset<35>/set() 10701152 5840316 1.83 *\nbitset<35>/set(i) 11342936 12271128 0.92\nbitset<35>/test 10670799 13099682 0.81 *\n\nbitset<75>/>>=/1 14198834 17151088 0.83 *\nbitset<75>/count 5795530 8576373 0.68 *\nbitset<75>/flip 8516703 8922995 0.95\nbitset<75>/reset 9999970 8526095 1.17 *\nbitset<75>/set() 11124877 9009686 1.23 *\nbitset<75>/set(i) 11300563 12531618 0.90 *\nbitset<75>/test 11031913 13100523 0.84 *\n\ndeque/erase 743801706 335646802 2.22 *\ndeque/insert 742331809 341912866 2.17 *\ndeque/iteration 29097030 16315827 1.78 *\ndeque/operator[] 49859598 24026313 2.08 *\ndeque/push_back 424807033 34497608 12.31 *\ndeque/push_front 402313373 38006322 10.59 *\ndeque/sort 725101017 581796551 1.25 *\n\nhash_map/clear 559462 961019 0.58 *\nhash_map/count 53377807 8091448 6.60 *\nhash_map/erase pos 613573 858084 0.72 *\nhash_map/erase range 5488748 461134 11.90 *\nhash_map/erase val 35760096 16379858 2.18 *\nhash_map/find 43490335 10324823 4.21 *\nhash_map/find_as/char* 49343818 8617139 5.73 *\nhash_map/insert 107420281 168690439 0.64 *\nhash_map/iteration 2456356 1255153 1.96 *\nhash_map/operator[] 47209502 12581624 3.75 *\n\nhash_map/clear 533172 546449 0.98\nhash_map/count 28667432 2899997 9.89 *\nhash_map/erase pos 683239 538289 1.27 *\nhash_map/erase range 9632676 253037 38.07 *\nhash_map/erase val 25466026 7752188 3.29 *\nhash_map/find 20048253 4678502 4.29 *\nhash_map/insert 71085798 37686187 1.89 *\nhash_map/iteration 1460318 1338317 1.09\nhash_map/operator[] 23226692 7888748 2.94 *\n\nheap (uint32_t[])/make_heap 5399966 6961305 0.78 *\nheap (uint32_t[])/pop_heap 108060534 103511318 1.04\nheap (uint32_t[])/push_heap 22595661 16640688 1.36 *\nheap (uint32_t[])/sort_heap 93559424 83076731 1.13 *\n\nheap (vector)/make_heap 91770743 21724870 4.22 *\nheap (vector)/pop_heap 1175599317 284007398 4.14 *\nheap (vector)/push_heap 207804541 45918046 4.53 *\nheap (vector)/sort_heap 970394145 208321477 4.66 *\n\nlist/ctor(it) 805539509 760938607 1.06\nlist/ctor(n) 80959236 75106995 1.08\nlist/erase 1052543704 1044976137 1.01\nlist/find 97785267 75970884 1.29 *\nlist/insert 873895175 807051107 1.08\nlist/push_back 812797710 780742425 1.04\nlist/remove 1850600714 1436980599 1.29 *\nlist/reverse 180270465 80466636 2.24 *\nlist/size/1 440148 599642 0.73 *\nlist/size/10 439433 1329817 0.33 * EASTL intentionally implements list::size as O(n).\nlist/size/100 439595 11030060 0.04 * EASTL intentionally implements list::size as O(n).\nlist/splice 177106094 69383027 2.55 *\n\nmap/clear 508283 470807 1.08\nmap/count 43145354 14280357 3.02 *\nmap/equal_range 38594004 16520447 2.34 *\nmap/erase/key 33948082 16123175 2.11 *\nmap/erase/pos 578332 455201 1.27 * MS uses a code bloating implementation of erase.\nmap/erase/range 387345 284538 1.36 *\nmap/find 22897224 12766100 1.79 *\nmap/insert 61665800 47286928 1.30 *\nmap/iteration 1977202 745391 2.65 *\nmap/lower_bound 19892941 12260928 1.62 *\nmap/operator[] 24199084 15429634 1.57 *\nmap/upper_bound 19842409 12064441 1.64 *\n\nset/clear 1027625 1000901 1.03\nset/count 39730182 13329565 2.98 *\nset/equal_range 34681649 14768827 2.35 *\nset/erase range 841458 602030 1.40 *\nset/erase/pos 1380485 1084303 1.27 * MS uses a code bloating implementation of erase.\nset/erase/val 31617425 13344023 2.37 *\nset/find 19582428 10788864 1.82 *\nset/insert 61434014 48232086 1.27 *\nset/iteration 1512057 667820 2.26 *\nset/lower_bound 18394885 10402785 1.77 *\nset/upper_bound 17189083 10554425 1.63 *\n\nsort/q_sort/TestObject[] 87088799 15037988 5.79 *\nsort/q_sort/TestObject[]/sorted 21502892 3284299 6.55 *\nsort/q_sort/vector 87962047 15004677 5.86 *\nsort/q_sort/vector/sorted 21396523 3341163 6.40 *\nsort/q_sort/vector 80334589 10429161 7.70 *\nsort/q_sort/vector/sorted 22133295 3230553 6.85 *\nsort/q_sort/vector 72195388 5940302 12.15 *\nsort/q_sort/vector/sorted 19635171 995495 19.72 *\n\nstring/compare 523013373 534722089 0.98\nstring/erase/pos,n 3446597 3439492 1.00\nstring/find/p,pos,n 383873158 441902786 0.87 *\nstring/find_first_not_of/p,pos,n 174157 134131 1.30 *\nstring/find_first_of/p,pos,n 11715423 8520944 1.37 *\nstring/find_last_of/p,pos,n 1871556 1226457 1.53 *\nstring/insert/pos,p 3624877 3357058 1.08\nstring/iteration 6766787933 581916665 11.63 *\nstring/operator[] 4820827 2335579 2.06 *\nstring/push_back 59812962 6757466 8.85 *\nstring/replace/pos,n,p,n 4371279 4459713 0.98\nstring/reserve 2307530 1919386 1.20 *\nstring/rfind/p,pos,n 734826 372615 1.97 *\nstring/size 41608 28866 1.44 *\nstring/swap 1033932 1490994 0.69 *\n\nstring/compare 63086797 64194771 0.98\nstring/erase/pos,n 2045687 1960270 1.04\nstring/find/p,pos,n 123872549 471364764 0.26 *\nstring/find_first_not_of/p,pos,n 140013 130271 1.07\nstring/find_first_of/p,pos,n 8051906 8749994 0.92\nstring/find_last_of/p,pos,n 1318835 1230715 1.07\nstring/insert/pos,p 1770610 1724234 1.03\nstring/iteration 28112136 2544475 11.05 *\nstring/operator[] 4810525 2255841 2.13 *\nstring/push_back 54869634 6127447 8.95 *\nstring/replace/pos,n,p,n 2737578 2847900 0.96\nstring/reserve 1123395 394902 2.84 *\nstring/rfind/p,pos,n 737299 368518 2.00 *\nstring/size 42245 26801 1.58 *\nstring/swap 1036142 1491028 0.69 *\n\nvector/erase 56417135 55770251 1.01\nvector/insert 56617761 56100468 1.01\nvector/iteration 10413895 1291269 8.06 *\nvector/operator[] 23507193 3479390 6.76 *\nvector/push_back 34687939 13806627 2.51 *\nvector/sort 256886550 84669657 3.03 *\n```\n\n### Win32.VC71.MS.Release\n\n```\nEASTL version: 0.96.00\nPlatform: Windows on X86\nCompiler: Microsoft Visual C++ compiler, version 1310\nAllocator: PPMalloc::GeneralAllocator. Thread safety enabled.\nBuild: Full optimization. Inlining enabled.\n\nValues are times to complete tests; smaller values are better.\nAlarm indicates a greater than 10% difference.\n\nTest VC++ EASTL Ratio Alarm\n----------------------------------------------------------------------------------------\nalgorithm/adj_find/vector 2783546 2750660 1.01\nalgorithm/copy/vector 6474025 4972738 1.30 *\nalgorithm/copy/vector 157267 173162 0.91\nalgorithm/copy_backward/vector 4836406 4374780 1.11 *\nalgorithm/copy_backward/vector 104780 120912 0.87 *\nalgorithm/count/vector 1368440 1368696 1.00\nalgorithm/equal_range/vector 114199387 102783938 1.11 *\nalgorithm/fill/bool[] 253215 27353 9.26 *\nalgorithm/fill/char[]/'d' 253164 27404 9.24 *\nalgorithm/fill/vector/'d' 253105 27362 9.25 *\nalgorithm/fill/vector/0 253275 27353 9.26 *\nalgorithm/fill/vector 397001 394323 1.01\nalgorithm/fill/vector 547196 642362 0.85 *\nalgorithm/fill_n/bool[] 229177 27361 8.38 *\nalgorithm/fill_n/char[] 228845 27404 8.35 *\nalgorithm/fill_n/vector 565233 1376822 0.41 *\nalgorithm/find_end/string/end 2107116 82356 25.59 *\nalgorithm/find_end/string/middle 2111672 664283 3.18 *\nalgorithm/find_end/string/none 2110423 1519596 1.39 *\nalgorithm/lex_cmp/schar[] 741021 176162 4.21 *\nalgorithm/lex_cmp/vector 2610494 2642183 0.99\nalgorithm/lex_cmp/vector 697595 167866 4.16 *\nalgorithm/lower_bound/vector 62462233 58146664 1.07\nalgorithm/min_element/vector 4350385 2671227 1.63 *\nalgorithm/rand_shuffle/vector 10868261 11300818 0.96\nalgorithm/reverse/list 483718 470024 1.03\nalgorithm/reverse/vector 476739 484322 0.98\nalgorithm/search/string 2560387 1259496 2.03 *\nalgorithm/search_n/string 2770991 458524 6.04 *\nalgorithm/unique/vector 4194520 4658910 0.90 *\nalgorithm/unique/vector 538730 787924 0.68 *\nalgorithm/unique/vector 3169829 2575636 1.23 *\nalgorithm/upper_bound/vector 27495562 25321593 1.09\n\nbitset<1500>/>>=/1 33464228 33469719 1.00\nbitset<1500>/count 18736116 18814903 1.00\nbitset<1500>/flip 19299309 18605438 1.04\nbitset<1500>/reset 22200487 15262847 1.45 *\nbitset<1500>/set() 14418193 17557319 0.82 *\nbitset<1500>/set(i) 1599250 1599199 1.00\nbitset<1500>/test 1599241 1599233 1.00\n\nbitset<15>/>>=/1 2199222 2264442 0.97\nbitset<15>/count 1399406 1399193 1.00\nbitset<15>/flip 1266712 1199197 1.06\nbitset<15>/reset 1399364 1399109 1.00\nbitset<15>/set() 1199197 999201 1.20 *\nbitset<15>/set(i) 1599258 1462952 1.09\nbitset<15>/test 1599275 1599224 1.00\n\nbitset<35>/>>=/1 2599266 1933376 1.34 *\nbitset<35>/count 2599240 2592559 1.00\nbitset<35>/flip 1693124 1199188 1.41 *\nbitset<35>/reset 1399406 999201 1.40 *\nbitset<35>/set() 1599403 1199205 1.33 *\nbitset<35>/set(i) 1599241 1599190 1.00\nbitset<35>/test 1599250 1599232 1.00\n\nbitset<75>/>>=/1 4199332 4199213 1.00\nbitset<75>/count 2999497 2199341 1.36 *\nbitset<75>/flip 2399499 1830178 1.31 *\nbitset<75>/reset 2199468 1199197 1.83 *\nbitset<75>/set() 1999387 1199851 1.67 *\nbitset<75>/set(i) 1599266 1599198 1.00\nbitset<75>/test 1599241 1662651 0.96\n\ndeque/erase 90444165 37113253 2.44 *\ndeque/insert 93299349 36175167 2.58 *\ndeque/iteration 2756414 2122076 1.30 *\ndeque/operator[] 5117969 4632075 1.10\ndeque/push_back 30300757 3060357 9.90 *\ndeque/push_front 25498529 2808392 9.08 *\ndeque/sort 142283047 111292464 1.28 *\n\nhash_map/clear 146769 389699 0.38 *\nhash_map/count 13059434 3460324 3.77 *\nhash_map/erase pos 184246 331925 0.56 *\nhash_map/erase range 382432 167237 2.29 *\nhash_map/erase val 6187898 3302114 1.87 *\nhash_map/find 11289369 3459024 3.26 *\nhash_map/find_as/char* 13559192 3662387 3.70 *\nhash_map/insert 17514012 14095176 1.24 *\nhash_map/iteration 801014 218450 3.67 *\nhash_map/operator[] 11457065 3690385 3.10 *\n\nhash_map/clear 141865 265379 0.53 *\nhash_map/count 1766045 703613 2.51 *\nhash_map/erase pos 172337 218458 0.79 *\nhash_map/erase range 537846 102340 5.26 *\nhash_map/erase val 2220132 1441787 1.54 *\nhash_map/find 1612994 1043953 1.55 *\nhash_map/insert 7141547 4348056 1.64 *\nhash_map/iteration 199512 169328 1.18 *\nhash_map/operator[] 1831733 1519707 1.21 *\n\nheap (uint32_t[])/make_heap 3366247 1949093 1.73 *\nheap (uint32_t[])/pop_heap 57280514 53779440 1.07\nheap (uint32_t[])/push_heap 9700217 7582935 1.28 *\nheap (uint32_t[])/sort_heap 47227751 46131948 1.02\n\nheap (vector)/make_heap 11458442 11510819 1.00\nheap (vector)/pop_heap 122897267 119061132 1.03\nheap (vector)/push_heap 21688481 21176220 1.02\nheap (vector)/sort_heap 90867380 88869523 1.02\n\nlist/ctor(it) 74591104 69845817 1.07\nlist/ctor(n) 6243998 5838582 1.07\nlist/erase 299509298 206013676 1.45 *\nlist/find 40927185 14514243 2.82 *\nlist/insert 71277251 47234534 1.51 *\nlist/push_back 73780527 44116725 1.67 *\nlist/remove 786197776 326434612 2.41 *\nlist/reverse 49283128 25029678 1.97 *\nlist/size/1 159741 139400 1.15 *\nlist/size/10 159324 346579 0.46 * EASTL intentionally implements list::size as O(n).\nlist/size/100 159188 97235419 0.00 * EASTL intentionally implements list::size as O(n).\nlist/splice 63548584 19322931 3.29 *\n\nmap/clear 167408 170501 0.98\nmap/count 10213685 4748346 2.15 *\nmap/equal_range 9515053 5677558 1.68 *\nmap/erase/key 6646260 4302300 1.54 *\nmap/erase/pos 297135 327938 0.91 MS uses a code bloating implementation of erase.\nmap/erase/range 148614 163702 0.91\nmap/find 5637531 4767055 1.18 *\nmap/insert 9591128 9030349 1.06\nmap/iteration 323595 325261 0.99\nmap/lower_bound 5398239 4784089 1.13 *\nmap/operator[] 5631250 5141166 1.10\nmap/upper_bound 5436336 4762431 1.14 *\n\nset/clear 155983 156026 1.00\nset/count 9635965 4392146 2.19 *\nset/equal_range 8504157 5247832 1.62 *\nset/erase range 140488 119408 1.18 *\nset/erase/pos 260678 286697 0.91 MS uses a code bloating implementation of erase.\nset/erase/val 6008225 4012825 1.50 *\nset/find 5145432 4381945 1.17 *\nset/insert 8087129 8697251 0.93\nset/iteration 271507 304538 0.89 *\nset/lower_bound 4666228 4404250 1.06\nset/upper_bound 4623600 4402974 1.05\n\nsort/q_sort/TestObject[] 9596169 5578652 1.72 *\nsort/q_sort/TestObject[]/sorted 602463 1016132 0.59 *\nsort/q_sort/vector 9674828 5430199 1.78 *\nsort/q_sort/vector/sorted 606908 1111647 0.55 *\nsort/q_sort/vector 6284194 3423452 1.84 *\nsort/q_sort/vector/sorted 711629 569364 1.25 *\nsort/q_sort/vector 5453379 2916146 1.87 *\nsort/q_sort/vector/sorted 537047 419144 1.28 *\n\nstring/compare 435083295 251985824 1.73 *\nstring/erase/pos,n 3454842 3451858 1.00\nstring/find/p,pos,n 401954723 165298157 2.43 *\nstring/find_first_not_of/p,pos,n 131452 65374 2.01 *\nstring/find_first_of/p,pos,n 11657444 4144515 2.81 *\nstring/find_last_of/p,pos,n 1604248 567571 2.83 *\nstring/insert/pos,p 3398734 3355460 1.01\nstring/iteration 218856504 218771844 1.00\nstring/operator[] 714161 240023 2.98 *\nstring/push_back 34968235 2444897 14.30 *\nstring/replace/pos,n,p,n 4226693 4198498 1.01\nstring/reserve 1901765 390805 4.87 *\nstring/rfind/p,pos,n 195483 150985 1.29 *\nstring/size 11169 11245 0.99\nstring/swap 1459280 419807 3.48 *\n\nstring/compare 63071275 77209580 0.82 *\nstring/erase/pos,n 2008652 1944494 1.03\nstring/find/p,pos,n 123201023 167536164 0.74 *\nstring/find_first_not_of/p,pos,n 93372 67864 1.38 *\nstring/find_first_of/p,pos,n 7542492 3375758 2.23 *\nstring/find_last_of/p,pos,n 933972 583576 1.60 *\nstring/insert/pos,p 1737213 1750847 0.99\nstring/iteration 893834 899130 0.99\nstring/operator[] 817879 313437 2.61 *\nstring/push_back 20857734 2004410 10.41 *\nstring/replace/pos,n,p,n 2578696 2607655 0.99\nstring/reserve 915127 85289 10.73 *\nstring/rfind/p,pos,n 196103 148894 1.32 *\nstring/size 11619 11220 1.04\nstring/swap 1461056 419874 3.48 *\n\nvector/erase 55235116 55284587 1.00\nvector/insert 55166046 55142755 1.00\nvector/iteration 553954 509719 1.09\nvector/operator[] 1284239 798516 1.61 *\nvector/push_back 5399549 3867959 1.40 *\nvector/sort 43636314 42619952 1.02\n```\n\n### Win32.VC71.STLPort.Debug\n\n```\nEASTL version: 0.96.00\nPlatform: Windows on X86\nCompiler: Microsoft Visual C++ compiler, version 1310\nAllocator: PPMalloc::GeneralAllocatorDebug. Thread safety enabled.\nBuild: Debug. Inlining disabled. STL debug features disabled.\n\nValues are times to complete tests; smaller values are better.\nAlarm indicates a greater than 10% difference.\n\nTest STLPort EASTL Ratio Alarm\n----------------------------------------------------------------------------------------\nalgorithm/adj_find/vector 5661170 5689517 1.00\nalgorithm/copy/vector 5573815 5124428 1.09\nalgorithm/copy/vector 148273 125782 1.18 *\nalgorithm/copy_backward/vector 5429791 4834510 1.12 *\nalgorithm/copy_backward/vector 156765 163038 0.96\nalgorithm/count/vector 2730922 2730072 1.00\nalgorithm/equal_range/vector 639366489 452896251 1.41 *\nalgorithm/fill/bool[] 1299326 27361 47.49 *\nalgorithm/fill/char[]/'d' 27378 27361 1.00\nalgorithm/fill/vector/'d' 34459 27361 1.26 *\nalgorithm/fill/vector/0 1299224 27361 47.48 *\nalgorithm/fill/vector 1400647 1400145 1.00\nalgorithm/fill/vector 1308779 1309085 1.00\nalgorithm/fill_n/bool[] 1299156 27352 47.50 *\nalgorithm/fill_n/char[] 1299258 27369 47.47 *\nalgorithm/fill_n/vector 1451162 1313632 1.10\nalgorithm/find_end/string/end 13089999 2526412 5.18 *\nalgorithm/find_end/string/middle 12627412 20190101 0.63 *\nalgorithm/find_end/string/none 12704185 40728803 0.31 *\nalgorithm/lex_cmp/schar[] 1749844 195806 8.94 *\nalgorithm/lex_cmp/vector 5060968 4799882 1.05\nalgorithm/lex_cmp/vector 1668354 189490 8.80 *\nalgorithm/lower_bound/vector 450240945 353437573 1.27 *\nalgorithm/min_element/vector 5861744 5326371 1.10\nalgorithm/rand_shuffle/vector 40780449 45780090 0.89 *\nalgorithm/reverse/list 2657678 2130627 1.25 *\nalgorithm/reverse/vector 2666424 2124889 1.25 *\nalgorithm/search/string 3110379 3613460 0.86 *\nalgorithm/search_n/string 3061665 1521261 2.01 *\nalgorithm/unique/vector 12423684 9485439 1.31 *\nalgorithm/unique/vector 3718699 1726596 2.15 *\nalgorithm/unique/vector 6205110 4591631 1.35 *\nalgorithm/upper_bound/vector 185391094 139336317 1.33 *\n\nbitset<1500>/>>=/1 120666960 92449816 1.31 * STLPort is broken, neglects wraparound check.\nbitset<1500>/count 201709793 52874726 3.81 *\nbitset<1500>/flip 87360297 81737071 1.07\nbitset<1500>/reset 23950178 77390323 0.31 *\nbitset<1500>/set() 84608107 76912011 1.10\nbitset<1500>/set(i) 18023620 12229604 1.47 *\nbitset<1500>/test 18006553 13276396 1.36 *\n\nbitset<15>/>>=/1 11935904 6012695 1.99 * STLPort is broken, neglects wraparound check.\nbitset<15>/count 9368581 6022742 1.56 *\nbitset<15>/flip 11600706 6533635 1.78 *\nbitset<15>/reset 5830957 5874690 0.99\nbitset<15>/set() 11695328 5701621 2.05 *\nbitset<15>/set(i) 16363205 12570216 1.30 *\nbitset<15>/test 16743172 13201452 1.27 *\n\nbitset<35>/>>=/1 22950918 6774457 3.39 * STLPort is broken, neglects wraparound check.\nbitset<35>/count 12655309 11736256 1.08\nbitset<35>/flip 13738575 5800042 2.37 *\nbitset<35>/reset 15561434 5800510 2.68 *\nbitset<35>/set() 13564283 5600709 2.42 *\nbitset<35>/set(i) 18519689 12199973 1.52 *\nbitset<35>/test 18000569 13103566 1.37 *\n\nbitset<75>/>>=/1 25579525 16669664 1.53 * STLPort is broken, neglects wraparound check.\nbitset<75>/count 18740698 8480492 2.21 *\nbitset<75>/flip 13555630 8300335 1.63 *\nbitset<75>/reset 15200133 8200000 1.85 *\nbitset<75>/set() 14408112 8001959 1.80 *\nbitset<75>/set(i) 18137741 12374257 1.47 *\nbitset<75>/test 18422135 13100038 1.41 *\n\ndeque/erase 651933790 326443043 2.00 *\ndeque/insert 659786183 333304660 1.98 *\ndeque/iteration 23734592 16173706 1.47 *\ndeque/operator[] 59126816 23911774 2.47 *\ndeque/push_back 58056988 31859266 1.82 *\ndeque/push_front 57780891 31743199 1.82 *\ndeque/sort 818414195 596568113 1.37 *\n\nhash_map/clear 3422133 2204517 1.55 *\nhash_map/count 9869545 8624924 1.14 *\nhash_map/erase pos 3256350 2069299 1.57 *\nhash_map/erase range 3230203 1151392 2.81 *\nhash_map/erase val 16860362 15939778 1.06\nhash_map/find 10286971 9920910 1.04\nhash_map/find_as/char* 118136025 9458468 12.49 *\nhash_map/insert 188948336 174490082 1.08\nhash_map/iteration 4037049 2021036 2.00 *\nhash_map/operator[] 11472127 12887699 0.89 *\n\nhash_map/clear 2522264 1331848 1.89 *\nhash_map/count 3210739 2897063 1.11 *\nhash_map/erase pos 1862281 1304783 1.43 *\nhash_map/erase range 698079 579606 1.20 *\nhash_map/erase val 8806722 7041298 1.25 *\nhash_map/find 3604875 4709645 0.77 *\nhash_map/insert 40785711 40376342 1.01\nhash_map/iteration 3064088 1508834 2.03 *\nhash_map/operator[] 6053742 8176906 0.74 *\n\nheap (uint32_t[])/make_heap 5799813 5738596 1.01\nheap (uint32_t[])/pop_heap 113775168 102076134 1.11 *\nheap (uint32_t[])/push_heap 21649151 16854845 1.28 *\nheap (uint32_t[])/sort_heap 97535213 83290735 1.17 *\n\nheap (vector)/make_heap 22215557 22277063 1.00\nheap (vector)/pop_heap 275392171 277340039 0.99\nheap (vector)/push_heap 51479442 47342577 1.09\nheap (vector)/sort_heap 214474736 218497540 0.98\n\nlist/ctor(it) 767753795 753421427 1.02\nlist/ctor(n) 74185322 73386245 1.01\nlist/erase 1021003824 1033873589 0.99\nlist/find 77666072 74917622 1.04\nlist/insert 788071150 774188737 1.02\nlist/push_back 760490154 737327348 1.03\nlist/remove 1682511938 1434771006 1.17 *\nlist/reverse 87237327 80394623 1.09\nlist/size/1 3828111 599530 6.39 *\nlist/size/10 9600605 1329535 7.22 * EASTL intentionally implements list::size as O(n).\nlist/size/100 62952334 15022551 4.19 * EASTL intentionally implements list::size as O(n).\nlist/splice 96536412 60804817 1.59 *\n\nmap/clear 1142127 1099066 1.04\nmap/count 19659726 14647548 1.34 *\nmap/equal_range 36680687 18219086 2.01 *\nmap/erase/key 28892154 16037774 1.80 *\nmap/erase/pos 1209643 1185495 1.02\nmap/erase/range 715402 670539 1.07\nmap/find 21020992 13429575 1.57 *\nmap/insert 59530871 51120640 1.16 *\nmap/iteration 972825 1191946 0.82 *\nmap/lower_bound 18852651 12495034 1.51 *\nmap/operator[] 22889573 16676736 1.37 *\nmap/upper_bound 18603584 12406922 1.50 *\n\nset/clear 919555 882988 1.04\nset/count 17561110 12461084 1.41 *\nset/equal_range 31522488 15230282 2.07 *\nset/erase range 687582 564765 1.22 *\nset/erase/pos 1044352 1045355 1.00\nset/erase/val 25525304 12940774 1.97 *\nset/find 17140751 10704866 1.60 *\nset/insert 56035051 45555664 1.23 *\nset/iteration 682669 640831 1.07\nset/lower_bound 16339932 10475740 1.56 *\nset/upper_bound 17779424 10652599 1.67 *\n\nsort/q_sort/TestObject[] 17000866 14823515 1.15 *\nsort/q_sort/TestObject[]/sorted 6658559 3263328 2.04 *\nsort/q_sort/vector 17476629 14953285 1.17 *\nsort/q_sort/vector/sorted 6667034 3327435 2.00 *\nsort/q_sort/vector 15391357 10820848 1.42 *\nsort/q_sort/vector/sorted 6617122 3232949 2.05 *\nsort/q_sort/vector 8343906 6014846 1.39 *\nsort/q_sort/vector/sorted 3039430 1003127 3.03 *\n\nstring/compare 1489709846 532664000 2.80 *\nstring/erase/pos,n 3528690 3439864 1.03\nstring/find/p,pos,n 2521448321 443752189 5.68 *\nstring/find_first_not_of/p,pos,n 661206 137419 4.81 *\nstring/find_first_of/p,pos,n 54746434 8521335 6.42 *\nstring/find_last_of/p,pos,n 10607778 1212414 8.75 *\nstring/insert/pos,p 3445016 3360126 1.03\nstring/iteration 580955636 579452556 1.00\nstring/operator[] 2206353 1987809 1.11 *\nstring/push_back 22421368 6007808 3.73 *\nstring/replace/pos,n,p,n 5138454 4464786 1.15 *\nstring/reserve 4922413418 335622 100.00 *\nstring/rfind/p,pos,n 1440308 380578 3.78 *\nstring/size 25355 25398 1.00\nstring/swap 2122704 1490823 1.42 *\n\nstring/compare 77222134 77443134 1.00\nstring/erase/pos,n 1965344 1956521 1.00\nstring/find/p,pos,n 2468091951 474205522 5.20 *\nstring/find_first_not_of/p,pos,n 660960 130211 5.08 *\nstring/find_first_of/p,pos,n 55020899 9240171 5.95 *\nstring/find_last_of/p,pos,n 10576210 1239053 8.54 *\nstring/insert/pos,p 1822756 1750880 1.04\nstring/iteration 2617889 2540148 1.03\nstring/operator[] 2254794 2256443 1.00\nstring/push_back 12463022 5210321 2.39 *\nstring/replace/pos,n,p,n 3744862 2855260 1.31 *\nstring/reserve 1372046888 218815 100.00 *\nstring/rfind/p,pos,n 1446232 366902 3.94 *\nstring/size 26859 25431 1.06\nstring/swap 2123350 1490509 1.42 *\n\nvector/erase 55164013 56417449 0.98\nvector/insert 55872973 56432664 0.99\nvector/iteration 1329102 1324623 1.00\nvector/operator[] 5264738 3136746 1.68 *\nvector/push_back 14903245 13171175 1.13 *\nvector/sort 88429095 88542171 1.00\n```\n\n### Win32.VC71.STLPort.Release\n\n```\nEASTL version: 0.96.00\nPlatform: Windows on X86\nCompiler: Microsoft Visual C++ compiler, version 1310\nAllocator: PPMalloc::GeneralAllocator. Thread safety enabled.\nBuild: Full optimization. Inlining enabled.\n\nValues are times to complete tests; smaller values are better.\nAlarm indicates a greater than 10% difference.\n\nTest STLPort EASTL Ratio Alarm\n----------------------------------------------------------------------------------------\nalgorithm/adj_find/vector 2741046 2731441 1.00\nalgorithm/copy/vector 6065923 5085142 1.19 *\nalgorithm/copy/vector 158304 165555 0.96\nalgorithm/copy_backward/vector 4710258 4896476 0.96\nalgorithm/copy_backward/vector 146030 142630 1.02\nalgorithm/count/vector 1395921 1406334 0.99\nalgorithm/equal_range/vector 211692764 118969493 1.78 *\nalgorithm/fill/bool[] 366078 33737 10.85 *\nalgorithm/fill/char[]/'d' 33736 33771 1.00\nalgorithm/fill/vector/'d' 28466 33720 0.84 *\nalgorithm/fill/vector/0 366086 33728 10.85 *\nalgorithm/fill/vector 466250 401591 1.16 *\nalgorithm/fill/vector 521603 693481 0.75 *\nalgorithm/fill_n/bool[] 599709 33762 17.76 *\nalgorithm/fill_n/char[] 599573 33711 17.79 *\nalgorithm/fill_n/vector 434971 1374084 0.32 *\nalgorithm/find_end/string/end 1494742 85349 17.51 *\nalgorithm/find_end/string/middle 1480700 687208 2.15 *\nalgorithm/find_end/string/none 1540540 1546431 1.00\nalgorithm/lex_cmp/schar[] 921638 178797 5.15 *\nalgorithm/lex_cmp/vector 2623559 2643551 0.99\nalgorithm/lex_cmp/vector 960899 183608 5.23 *\nalgorithm/lower_bound/vector 60630534 56531528 1.07\nalgorithm/min_element/vector 4209022 2768527 1.52 *\nalgorithm/rand_shuffle/vector 13762010 15969052 0.86 *\nalgorithm/reverse/list 673387 731825 0.92\nalgorithm/reverse/vector 634576 754511 0.84 *\nalgorithm/search/string 1262599 1387608 0.91\nalgorithm/search_n/string 1166242 458592 2.54 *\nalgorithm/unique/vector 4912193 5336317 0.92\nalgorithm/unique/vector 809387 809081 1.00\nalgorithm/unique/vector 4371814 2414255 1.81 *\nalgorithm/upper_bound/vector 31899081 29555596 1.08\n\nbitset<1500>/>>=/1 63308136 40553560 1.56 * STLPort is broken, neglects wraparound check.\nbitset<1500>/count 62523178 22799473 2.74 *\nbitset<1500>/flip 20302845 19919232 1.02\nbitset<1500>/reset 18892015 15403148 1.23 *\nbitset<1500>/set() 15803302 17322192 0.91\nbitset<1500>/set(i) 2799271 2999310 0.93\nbitset<1500>/test 2999293 2799262 1.07\n\nbitset<15>/>>=/1 1199239 3199256 0.37 * STLPort is broken, neglects wraparound check.\nbitset<15>/count 3599461 2199231 1.64 *\nbitset<15>/flip 1199231 1199188 1.00\nbitset<15>/reset 1199188 1199180 1.00\nbitset<15>/set() 1199214 1199180 1.00\nbitset<15>/set(i) 2599257 1399262 1.86 *\nbitset<15>/test 2599274 2599283 1.00\n\nbitset<35>/>>=/1 6643974 4599239 1.44 * STLPort is broken, neglects wraparound check.\nbitset<35>/count 5151331 5399438 0.95\nbitset<35>/flip 1999404 1199273 1.67 *\nbitset<35>/reset 9805285 1399313 7.01 *\nbitset<35>/set() 2799279 1199248 2.33 *\nbitset<35>/set(i) 2799246 1599241 1.75 *\nbitset<35>/test 2999234 2999251 1.00\n\nbitset<75>/>>=/1 7002045 6999333 1.00 STLPort is broken, neglects wraparound check.\nbitset<75>/count 5999351 3002259 2.00 *\nbitset<75>/flip 3599334 3599163 1.00\nbitset<75>/reset 9799344 3399218 2.88 *\nbitset<75>/set() 3599232 3599062 1.00\nbitset<75>/set(i) 2799228 1599284 1.75 *\nbitset<75>/test 2999250 2799339 1.07\n\ndeque/erase 127108651 115258113 1.10\ndeque/insert 137727889 116552332 1.18 *\ndeque/iteration 7144182 6009899 1.19 *\ndeque/operator[] 34241222 20535039 1.67 *\ndeque/push_back 6585800 3932126 1.67 *\ndeque/push_front 6805865 3993513 1.70 *\ndeque/sort 395352323 348778188 1.13 *\n\nhash_map/clear 426640 447015 0.95\nhash_map/count 4359344 3883089 1.12 *\nhash_map/erase pos 584392 458142 1.28 *\nhash_map/erase range 221034 196078 1.13 *\nhash_map/erase val 3539867 3790813 0.93\nhash_map/find 3966831 3811910 1.04\nhash_map/find_as/char* 11591612 4243710 2.73 *\nhash_map/insert 16763887 16719194 1.00\nhash_map/iteration 909968 478609 1.90 *\nhash_map/operator[] 4360041 4108313 1.06\n\nhash_map/clear 302634 283722 1.07\nhash_map/count 916487 907426 1.01\nhash_map/erase pos 388042 321385 1.21 *\nhash_map/erase range 122680 116280 1.06\nhash_map/erase val 1710931 1729529 0.99\nhash_map/find 1089462 1346527 0.81 *\nhash_map/insert 4560310 5072350 0.90 *\nhash_map/iteration 960117 495354 1.94 *\nhash_map/operator[] 1872830 1890595 0.99\n\nheap (uint32_t[])/make_heap 3528418 3327257 1.06\nheap (uint32_t[])/pop_heap 63243859 61011853 1.04\nheap (uint32_t[])/push_heap 11602424 10045869 1.15 *\nheap (uint32_t[])/sort_heap 52965362 48744729 1.09\n\nheap (vector)/make_heap 13191456 13089711 1.01\nheap (vector)/pop_heap 148555656 144787742 1.03\nheap (vector)/push_heap 28696689 26618830 1.08\nheap (vector)/sort_heap 112473989 114018643 0.99\n\nlist/ctor(it) 80186731 74006287 1.08\nlist/ctor(n) 6232311 6128007 1.02\nlist/erase 344556374 212877808 1.62 *\nlist/find 39859075 14591347 2.73 *\nlist/insert 86935153 56138233 1.55 *\nlist/push_back 79569180 46700641 1.70 *\nlist/remove 785786758 324201016 2.42 *\nlist/reverse 45248186 24852759 1.82 *\nlist/size/1 219844 219496 1.00\nlist/size/10 519563 519579 1.00 EASTL intentionally implements list::size as O(n).\nlist/size/100 4567194 101230266 0.05 * EASTL intentionally implements list::size as O(n).\nlist/splice 68321087 23601687 2.89 *\n\nmap/clear 168011 180540 0.93\nmap/count 4830439 5139287 0.94\nmap/equal_range 8700090 6158531 1.41 *\nmap/erase/key 6696776 4617038 1.45 *\nmap/erase/pos 309273 333183 0.93\nmap/erase/range 137419 136068 1.01\nmap/find 4773498 4931352 0.97\nmap/insert 9651877 9311699 1.04\nmap/iteration 372946 416364 0.90 *\nmap/lower_bound 4784234 4915797 0.97\nmap/operator[] 5040254 5183147 0.97\nmap/upper_bound 4724292 4915984 0.96\n\nset/clear 165300 173289 0.95\nset/count 4958654 4885086 1.02\nset/equal_range 8434134 5698681 1.48 *\nset/erase range 145554 133960 1.09\nset/erase/pos 299914 324760 0.92\nset/erase/val 6506155 4335034 1.50 *\nset/find 4866879 4556043 1.07\nset/insert 8340523 8957257 0.93\nset/iteration 294465 343442 0.86 *\nset/lower_bound 4548095 4756498 0.96\nset/upper_bound 4559196 4521498 1.01\n\nsort/q_sort/TestObject[] 7316766 7013894 1.04\nsort/q_sort/TestObject[]/sorted 1668439 1332885 1.25 *\nsort/q_sort/vector 7331530 7017260 1.04\nsort/q_sort/vector/sorted 1601629 1247120 1.28 *\nsort/q_sort/vector 7071643 7067869 1.00\nsort/q_sort/vector/sorted 2136390 1703799 1.25 *\nsort/q_sort/vector 3292891 2943627 1.12 *\nsort/q_sort/vector/sorted 653693 473612 1.38 *\n\nstring/compare 356579259 432760228 0.82 *\nstring/erase/pos,n 3430422 3428645 1.00\nstring/find/p,pos,n 229263402 225830975 1.02\nstring/find_first_not_of/p,pos,n 187391 81404 2.30 *\nstring/find_first_of/p,pos,n 4411831 4413532 1.00\nstring/find_last_of/p,pos,n 731655 726155 1.01\nstring/insert/pos,p 3408628 3319726 1.03\nstring/iteration 309993861 310333547 1.00\nstring/operator[] 580839 579904 1.00\nstring/push_back 3983338 2975553 1.34 *\nstring/replace/pos,n,p,n 4361095 4211504 1.04\nstring/reserve 935141729 247010 100.00 *\nstring/rfind/p,pos,n 248956 223397 1.11 *\nstring/size 13311 13107 1.02\nstring/swap 519129 579445 0.90 *\n\nstring/compare 76695559 76828015 1.00\nstring/erase/pos,n 1951566 1947282 1.00\nstring/find/p,pos,n 185878944 185605039 1.00\nstring/find_first_not_of/p,pos,n 196877 81600 2.41 *\nstring/find_first_of/p,pos,n 4147685 4145356 1.00\nstring/find_last_of/p,pos,n 605897 598222 1.01\nstring/insert/pos,p 1781592 1768264 1.01\nstring/iteration 921502 921272 1.00\nstring/operator[] 361250 359873 1.00\nstring/push_back 3363288 2530493 1.33 *\nstring/replace/pos,n,p,n 2682600 2633130 1.02\nstring/reserve 672517501 78387 100.00 *\nstring/rfind/p,pos,n 226202 200013 1.13 *\nstring/size 11280 11109 1.02\nstring/swap 519393 559759 0.93\n\nvector/erase 55184856 55192217 1.00\nvector/insert 56764267 55682726 1.02\nvector/iteration 423122 424039 1.00\nvector/operator[] 1189397 860991 1.38 *\nvector/push_back 5626609 4027317 1.40 *\nvector/sort 49227036 49231362 1.00\n```\n\n----------------------------------------------\nEnd of document\n" }, { "path": "doc/BestPractices.md", "content": "# EASTL Best Practices\n\nIn 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.\n\n## Summary\n\nThe descriptions here are intentionally terse; this is to make them easier to visually scan.\n\n1. [Consider intrusive containers.](#consider-intrusive-containers)\n2. [Consider fixed-size containers.](#consider-fixed-size-containers)\n3. [Consider custom allocators.](#consider-custom-allocators)\n4. [Consider hash tables instead of maps.](#consider-hash-tables-instead-of-maps)\n5. [Consider a vector_map (a.k.a. sorted vector) for unchanging data.](#consider-a-vector_map-aka-sorted-vector-for-unchanging-data)\n6. [Consider slist instead of list.](#consider-slist-instead-of-list)\n7. [Avoid redundant end() and size() in loops.](#avoid-redundant-end-and-size-in-loops)\n8. [Iterate containers instead of using operator\\[\\].](#iterate-containers-instead-of-using-operator)\n9. [Learn to use the string class appropriately.](#learn-to-use-the-string-class-appropriately)\n10. [Cache list size if you want size() to be O(1).](#cache-list-size-if-you-want-listsize-to-be-o1)\n11. [Use empty() instead of size() when possible.](#use-empty-instead-of-size-when-possible)\n12. [Know your container efficiencies.](#know-your-container-efficiencies)\n13. [Use vector::reserve.](#use-vectorreserve)\n14. [Use vector::set_capacity to trim memory usage.](#use-vectorset_capacity-to-trim-memory-usage)\n15. [Use swap() instead of a manually implemented version.](#use-swap-instead-of-a-manually-implemented-version)\n16. [Consider storing pointers instead of objects.](#consider-storing-pointers-instead-of-objects)\n17. [Consider smart pointers instead of raw pointers.](#consider-smart-pointers-instead-of-raw-pointers)\n18. [Use iterator pre-increment instead of post-increment.](#use-iterator-pre-increment-instead-of-post-increment)\n19. [Make temporary references so the code can be traced/debugged.](#make-temporary-references-so-the-code-can-be-traceddebugged)\n20. [Consider bitvector or bitset instead of vector\\.](#consider-bitvector-or-bitset-instead-of-vector)\n21. [Vectors can be treated as contiguous memory.](#vectors-can-be-treated-as-contiguous-memory)\n22. [Search hash_map\\ using heterogeneous lookup.](#search-hash_mapstring-using-heterogeneous-lookup)\n23. [Take advantage of type_traits.](#take-advantage-of-type_traits)\n24. [Name containers to track memory usage.](#name-containers-to-track-memory-usage)\n25. [Learn the algorithms.](#learn-the-algorithms)\n26. [Pass and return containers by reference instead of value.](#pass-and-return-containers-by-reference-instead-of-value)\n27. [Consider using reset_lose_memory() for fast container teardown.](#consider-using-reset_lose_memory-for-fast-container-teardown)\n28. [Consider using fixed_substring instead of copying strings.](#consider-using-fixed_substring-instead-of-copying-strings)\n29. [Consider using vector::push_back(void).](#consider-using-vectorpush_backvoid)\n\n## Detail\n\n### Consider intrusive containers.\n\nIntrusive 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.\n\nTo create an intrusive_list container, you can use the following code:\n\n```cpp\nclass Widget : public intrusive_list_node\n\n{ };\n\n\n\nintrusive_list widgetList;\n\nwidgetList.push_back(someWidget);\n```\n\n### Consider fixed-size containers.\n\nFixed-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.\"\n\nEASTL fixed containers include:\n\n* fixed_list\n* fixed_slist\n* fixed_vector\n* fixed_string\n* fixed_map\n* fixed_multimap\n* fixed_set\n* fixed_multiset\n* fixed_hash_map\n* fixed_hash_multimap\n* fixed_hash_set\n* fixed_hash_multiset\n\nTo create a fixed_set, you can use the following code:\n\n```cpp\nfixed_set intSet; // Create a set capable of holding 25 elements.\n\nintSet.push_back(37);\n```\n\n### Consider custom allocators.\n\nWhile 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.\n\nTo create a list container that uses your custom allocator and uses block naming, you can use the following code:\n\n```cpp\nlist intList(pSomeAllocator, \"graphics/intList\");\n\nintList.push_back(37);\n```\n\n### Consider hash tables instead of maps.\n\nHash 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.\n\nTo make a hash_map (dictionary) of integers to strings, you can use the following code:\n```cpp\nhash_map stringTable;\n\nstringTable[37] = \"hello\";\n```\n\n### Consider a vector_map (a.k.a. sorted vector) for unchanging data.\n\nYou 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.\n\nTo make a vector_set, you can use the following code:\n\n```cpp\nvector_set intSet(16); // Create a vector_set with an initial capacity of 16.\n\nintSet.insert(37);\n```\n\nNote that you can use containers other than vector to implement vector_set. Here's how you do it with deque:\n\n```cpp\nvector_set, EASTLAllocatorType, deque > intSet;\n\nintSet.insert(37);\n```\n\n### Consider slist instead of list.\n\nAn 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.\n\nTo make an slist, you can use the following code:\n\n```cpp\nslist intSlist;\n\nintSlist.push_front(37);\n```\n\n### Avoid redundant end() and size() in loops.\n\nInstead of writing code like this:\n\n```cpp\nfor(deque::iterator it = d.begin(); it != d.end(); ++it)\n\n ...\n```\n\nwrite code like this:\n\n```cpp\nfor(deque::iterator it = d.begin(), itEnd = d.end(); it != itEnd; ++it)\n\n ...\n```\n\nThe 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. But \"constant end value\" we mean containers which can be modified but end always remains the same.\n\n| Constant begin | Non-constant begin | Constant end | Non-constant end |\n|------|------|------|------|\n| array1 | string
vector
deque
intrusive_list
intrusive_slist
vector_map
vector_multimap
vector_set
vector_multiset
bit_vector
hash_map
hash_multimap
hash_set
hash_multiset
intrusive_hash_map
intrusive_hash_multimap
intrusive_hash_set
intrusive_hash_multiset | array
list
slist
intrusive_list
intrusive_slist
map
multimap
set
multiset
hash_map2
hash_multimap2
hash_set2
hash_multiset2
intrusive_hash_map
intrusive_hash_multimap
intrusive_hash_set
intrusive_hash_multiset | string
vector
deque
vector_map
vector_multimap
vector_set
vector_multiset
bit_vector |\n\n* 1 Arrays can be neither resized nor reallocated.\n* 2 Constant end if the hashtable can't/won't re-hash. Non-constant if it can re-hash.\n\n### Iterate containers instead of using operator[].\n\nIt's faster to iterate random access containers via iterators than via operator[], though operator[] usage may look simpler.\n\nInstead of doing this:\n\n```cpp\nfor(unsigned i = 0, iEnd = intVector.size(); i != iEnd; ++i)\n\n intVector[i] = 37;\n```\n\nyou can execute more efficiently by doing this:\n\n```cpp\nfor(vector::iterator it = intVector.begin(), itEnd = intVector.end(); it != itEnd; ++it)\n\n *it = 37;\n```\n\n### Learn to use the string class appropriately.\n\nOddly 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 strlen(s.c_str()) are so common, whereas the user could just use s.length() instead and be both clearer and more efficient.\n\nHere we provide a table of actual collected examples of things done and how they could have been done instead.\n\n| What was written | What could have been written |\n|------|------|\n| `s = s.Left(i) + '+' + s.Right(s.length() - i - 1);` | `s[i] = '+';` |\n| `string s(\"\"); // This is the most commonly found misuse.` | `string s;` |\n| `s = \"\";` | `s.clear();` |\n| `s.c_str()[0] = 'u';` | `s[0] = 'u';` |\n| `len = strlen(s.c_str());` | `len = s.length();` |\n| `s = string(\"u\");` | `s = \"u\";` |\n| `puts(s + string(\"u\"));` | `puts(s + \"u\");` |\n| `string s(\" \");`
`puts(s.c_str());` | `puts(\" \");` |\n| `s.sprintf(\"u\");` | s = \"u\";` |\n| `char array[32];`
`sprintf(array, \"%d\", 10);`
`s = string(array);` | `s.sprintf(\"%d\", 10);` |\n\nThe 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.\n\n### Cache list size if you want list::size() to be O(1).\n\nEASTL'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.\n\nHere's an example of caching the list size manually:\n\n```cpp\nlist intList;\n\n size_t n = 0;\n\n\n\n intList.push_back(37);\n\n ++n;\n\n intList.pop_front();\n\n --n;\n```\n\n### Use empty() instead of size() when possible.\n\nAll 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.\n\n### Know your container efficiencies.\n\nThe 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.\n\n| Container | empty() efficiency | size() efficiency | operator[] efficiency | insert() efficiency | erase() efficiency | find() efficiency | sort efficiency |\n|------|------|------|------|------|------|------|------|\n| slist | 1 | O(n) | - | O(1) | O(1) | O(n) | O(n+) |\n| list | 1 | n | - | 1 | 1 | n | n log(n) |\n| intrusive_slist | 1 | n | - | 1 | 1 | 1 | n+ |\n| intrusive_list | 1 | n | - | 1 | 1 | 1 | n log(n) |\n| array | 1 | 1 | 1 | - | - | n | n log(n) |\n| vector | 1 | 1a | 1 | \t1 at end, else n | 1 at end, else n | n | n log(n) |\n| vector_set | 1 | 1a | 1 | 1 at end, else n | 1 at end, else n | log(n) | 1 |\n| vector_multiset | 1 | 1a | 1 | 1 at end, else n | 1 at end, else n | log(n) | 1 |\n| vector_map | 1 | 1a | 1 | 1 at end, else n | 1 at end, else n | log(n) | 1 |\n| vector_multimap | 1 | 1a | 1 | 1 at end, else n | 1 at end, else n | log(n) | 1 |\n| deque | 1 | 1a | 1 | 1 at begin or end, else n / 2 | 1 at begin or end, else n / 2 | n | n log(n) |\n| bit_vector | 1 | 1a | 1 | 1 at end, else n | 1 at end, else n | n | n log(n) |\n| string, cow_string | 1 | 1a | 1 | 1 at end, else n | 1 at end, else n | n | n log(n) |\n| set | 1 | 1 | - | log(n) | log(n) | log(n) | 1 |\n| multiset | 1 | 1 | - | log(n) | log(n) | log(n) | 1 |\n| map | 1 | 1 | log(n) | log(n) | log(n) | log(n) | 1 |\n| multimap | 1 | 1 | - | log(n) | log(n) | log(n) | 1 |\n| hash_set | 1 | 1 | - | 1 | 1 | 1 | - |\n| hash_multiset | 1 | 1 | - | 1 | 1 | 1 | - |\n| hash_map | 1 | 1 | - | 1 | 1 | 1 | - |\n| hash_multimap | 1 | 1 | - | 1 | 1 | 1 | - |\n| intrusive_hash_set | 1 | 1 | - | 1 | 1 | 1 | - |\n| intrusive_hash_multiset | 1 | 1 | - | 1 | 1 | 1 | - |\n| intrusive_hash_map | 1 | 1 | - | 1 | 1 | 1 | - |\n| intrusive_hash_multimap | 1 | 1 | - | 1 | 1 | 1 | - |\n\nNotes:\n\n* \\- means that the operation does not exist.\n* 1 means amortized constant time. Also known as O(1)\n* n means time proportional to the container size. Also known as O(n)\n* log(n) means time proportional to the natural logarithm of the container size. Also known as O(log(n))\n* n log(n) means time proportional to log(n) times the size of the container. Also known as O(n log(n))\n* n+ means that the time is at least n, and possibly higher.\n* 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.\n* 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).\n* a 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.\n\n### Use vector::reserve.\n\nYou 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.\n\nHere's how you could specify reserved capacity in a vector:\n\n```cpp\nvector v(37); // Reserve space to hold up to 37 items.\n\n or\n\nvector v; // This empty construction causes to memory to be allocated or reserved.\n\n v.reserve(37);\n```\n\nThe EASTL vector (and string) implementation looks like this:\n\n```cpp\ntemplate \n\n class vector {\n\n T* mpBegin; // Beginning of used element memory.\n\n T* mpEnd; // End of used element memory.\n\n T* mpCapacity; // End of storage capacity. Is >= mpEnd\n\n }\n```\n\nAnother approach to being efficient with vector memory usage is to use fixed_vector.\n\n### Use vector::set_capacity to trim memory usage.\n\nA 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 vector(v).swap(v). EASTL provides the same functionality via a member function called set_capacity() which is present in both the vector and string classes.\n\nAn example of reducing a vector is the following:\n\n```cpp\nvector v;\n\n...\n\n v.set_capacity();\n```\n\nAn example of resizing to zero and completely freeing the memory of a vector is the following:\n\n```cpp\nvector v;\n\n ...\n\n v.set_capacity(0);\n```\n\n### Use swap() instead of a manually implemented version.\n\nThe 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.\n\n### Consider storing pointers instead of objects.\n\nThere 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.\n\n### Consider smart pointers instead of raw pointers.\n\nIf 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.\n\nHere is an example of creating and using a shared_ptr:\n\n```cpp\ntypedef shared_ptr WPtr;\n\n list wList;\n\n\n\n wList.push_back(WPtr(new Widget)); // The user may have operator new/delete overrides.\n\nwList.pop_back(); // Implicitly deletes the Widget.\n```\n\nHere is an example of creating and using a shared_ptr that uses a custom allocation and deallocation mechanism:\n\n```cpp\ntypedef shared_ptr WPtr; // WidgetDelete is a custom destroyer.\n\n list wList;\n\n\n\n wList.push_back(WPtr(WidgetCreate(Widget))); // WidgetCreate is a custom allocator.\n\nwList.pop_back(); // Implicitly calls WidgetDelete.\n```\n\n### Use iterator pre-increment instead of post-increment.\n\nPre-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.\n\nEASTL 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.\n\nHere is an example of using iterator pre-increment; for loops like this should always use pre-increment:\n\n```cpp\nfor(set::iterator it(intSet.begin()), itEnd(intSet.end()); it != itEnd; ++it)\n\n *it = 37;\n```\n\n### Make temporary references so the code can be traced/debugged.\n\nUsers 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.\n\nInstead of doing this:\n\n```cpp\nfor(list::iterator it = wl.begin(), itEnd = wl.end(); it != itEnd; ++it) {\n\n (*it).x = 37;\n\n (*it).y = 38;\n\n (*it).z = 39;\n\n }\n```\n\nConsider doing this:\n\n```cpp\nfor(list::iterator it = wl.begin(), itEnd = wl.end(); it != itEnd; ++it) {\n\n Widget& w = *it; // The user can easily inspect or modify w here.\n\n w.x = 37;\n\n w.y = 38;\n\n w.z = 39;\n\n }\n```\n\n### Consider bitvector or bitset instead of vector.\n\nIn 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 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.\n\nAdditionally 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.\n\n### Vectors can be treated as contiguous memory.\n\nEASTL 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].\n\nTo use a vector as a pointer to an array, you can use the following code:\n\n```cpp\nstruct Widget {\n\n uint32_t x;\n\n uint32_t y;\n\n };\n\n\n\n vector v;\n\n\n\n quick_sort((uint64_t*)v.data(), (uint64_t*)(v.data() + v.size()));\n```\n\n### Search hash_map\\ using heterogeneous lookup\n\nWhen using a hash map (or any associative container) 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 because string allocates.\n\nYou can avoid creating these temporary objects declare the container type with [transparent comparison types](https://en.cppreference.com/w/cpp/utility/functional#Transparent_function_objects) (eg. [`equal_to`](https://en.cppreference.com/w/cpp/utility/functional/less_void)). eg.\n```cpp\neastl::hash_map> hashMap;\n ...\nauto it = hashMap.find(\"hello\"); // No string object created. Uses heterogeneous lookup, which calls transparent_string_hash::operator()(const string&) and equal_to::operator()(const string&, const char*).\n```\nEASTL containers support this optimization for additional member functions that take a `key_type` parameter, ie. heterogeneous lookup, insertion and erasure.\n\nEASTL also has a member function called `find_as` which lets you search a hash table by something other than the container comparison type. Note that the comparison semantics must be equivalent to the container's comparison object, otherwise the behaviour is undefined.\n\nTo use `find_as`, you can use the following code:\n\n```cpp\nhash_map hashMap;\n...\nauto it = hashMap.find_as(\"hello\", /* a hash object */, /* an equality comparison object */);\n```\n\nUsing transparent comparison types should be preferred due to the support for additional member functions and additional safety.\n\n### Take advantage of type_traits.\n\nEASTL 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 *types*, 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.\n\nThere are three primary uses of type traits:\n\n* Allowing for optimized operations on some data types.\n* Allowing for different logic pathways based on data types.\n* Allowing for compile-type assertions about data type expectations.\n\nHere is an example of using type traits to tell if a value is a floating point value or not:\n\n```cpp\ntemplate \n\n DoSomething(T t) {\n\n assert(is_floating_point::value);\n\n }\n```\n\nHere is an example of declaring a class that is trivially copyable and using it in a vector.\n\n```cpp\n class Widget { ... }; // Anything conforming to the trivially copyable rules: https://en.cppreference.com/w/cpp/language/classes#Trivially_copyable_class\n\n vector wVector{ ... some elements ... };\n\n wVector.erase(wVector.begin()); // This operation will be optimized to memcpy the elements into place.\n```\n\n### Name containers to track memory usage.\n\nAll 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 containers to use and it does the rest.\n\nHere is an example of creating a list and naming it \"collision list\":\n\n`list collisionList(allocator(\"collision list\"));`\n\nor\n\n```cpp\nlist collisionList;\n\ncollisionList.get_allocator().set_name(\"collision list\");\n```\n\nNote 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.\n\n### Learn the algorithms.\n\nEASTL 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.\n\nThe 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.\n\n**Search**\n\n* find, find_if\n* find_end\n* find_first_of\n* adjacent_find\n* binary_search\n* search, search_n\n* lower_bound\n* upper_bound\n* equal_range\n\n**Sort**\n\n* is_sorted\n* quick_sort\n* insertion_sort\n* shell_sort\n* heap_sort\n* merge_sort, merge_sort_buffer\n* merge\n* inplace_merge\n* partial_sort\n* stable_sort\n* partial_sort_copy\n* \n\n**Modifying**\n\n* fill, fill_n\n* generate, generate_n\n* random_shuffle\n* swap\n* iter_swap\n* swap_ranges\n* remove, remove_if\n* remove_copy, remove_copy_if\n* replace, replace_if\n* replace_copy, replace_copy_if\n* reverse\n* reverse_copy\n* rotate\n* rotate_copy\n* partition\n* stable_partition\n* transform\n* next_permutation\n* prev_permutation\n* unique\n* unique_copy\n\n**Non-Modifying**\n\n* for_each\n* copy\n* copy_backward\n* count, count_if\n* equal\n* mismatch\n* min\n* max\n* min_element\n* max_element\n* lexicographical_compare\n* nth_element\n\n**Heap**\n\n* is_heap\n* make_heap\n* push_heap\n* pop_heap\n* change_heap\n* sort_heap\n* remove_heap\n\n**Set**\n\n* includes\n* set_difference\n* set_symmetric_difference\n* set_intersection\n* set_union\n\n### Pass and return containers by reference instead of value.\n\nIf you aren't paying attention you might accidentally write code like this:\n\n```cpp\nvoid DoSomething(list widgetList) {\n\n ...\n\n}\n```\n\nThe 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.\n\n### Consider using reset_lose_memory() for fast container teardown.\n\nEASTL containers have a reset_lose_memory 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 powerful 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).\n\nHere's an example of usage of the reset function and a PPMalloc-like StackAllocator:\n\n```cpp\n pStackAllocator->push_bookmark();\n\n hash_set, StackAllocator> wSet(pStackAllocator);\n\n \n\n wSet.reset_lose_memory();\n\n pStackAllocator->pop_bookmark();\n```\n\n### Consider using fixed_substring instead of copying strings.\n\nEASTL 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.\n\nHere's an example of usage of fixed_substring:\n\n```cpp\nbasic_string str(\"hello world\");\n\n fixed_substring sub(str, 6, 5); // sub == \"world\"\n\nfixed_substring can refer to any character array and not just one that derives from a string object.\n```\n\n### Consider using vector::push_back(void).\n\nEASTL provides an alternative way to insert elements into containers that avoids copy construction and/or the creation of temporaries. Consider the following code:\n\n```cpp\nvector widgetArray;\n\n widgetArray.push_back(Widget());\n```\n\nThe 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:\n\n```cpp\nvector widgetArray;\n\n widgetArray.push_back();\n\nwidgetArray.back().x = 0; // Example of how to reference the new object.\n```\n\nOther containers with such copy-less functions include:\n\n```cpp\nvector::push_back()\n\n deque::push_back()\n\n deque::push_front()\n\n list::push_back()\n\n list::push_front()\n\n slist::push_front()\n\n map::insert(const key_type& key)\n\n multimap::insert(const key_type& key)\n\n hash_map::insert(const key_type& key)\n\n hash_multimap::insert(const key_type& key)\n```\n\nNote 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.\n\n----------------------------------------------\nEnd of document\n" }, { "path": "doc/Bonus/tuple_vector_readme.md", "content": "## Introduction to tuple_vector\n\n`tuple_vector` is a data container that is designed to abstract and simplify\nthe handling of a \"structure of arrays\" layout of data in memory. In\nparticular, it mimics the interface of `vector`, including functionality to do\ninserts, erases, push_backs, and random-access. It also provides a\n`RandomAccessIterator` and corresponding functionality, making it compatible\nwith most STL (and STL-esque) algorithms such as ranged-for loops, `find_if`,\n`remove_if`, or `sort`.\n\nWhen used or applied properly, this container can improve performance of\nsome algorithms through cache-coherent data accesses or allowing for\nsensible SIMD programming, while keeping the structure of a single\ncontainer, to permit a developer to continue to use existing algorithms in\nSTL and the like.\n\n## Review of \"Structure of arrays\" data layouts\n\nWhen trying to improve the performance of some code, it can sometimes be\ndesirable to transform how some data is stored in memory to be laid out not as\nan \"array of structures\", but as a \"structure of arrays\". That is, instead of\nstoring a series of objects as a single contiguous chunk of memory, one or \nmore data members are instead stored as separate chunks of memory that are \nhandled and accessed in parallel to each other.\n\nThis can be beneficial in two primary respects:\n\n1) To improve the cache coherency of the data accesses, e.g. by utilizing more\ndata that is loaded per cache line loaded from memory, and thereby reducing \nthe amount of time waiting on memory accesses from off-CPU memory.\nThis presentation from Mike Acton touches on this, among other things:\nhttps://www.youtube.com/watch?v=rX0ItVEVjHc\n\n2) To allow the data to be more easily loaded and utilized by SIMD kernels, \nby being able to load memory directly into a SIMD register.\nThis is touched on in this presentation from Andreas Fredriksson for writing\ncode with SIMD intrinsics:\nhttp://www.gdcvault.com/play/1022249/SIMD-at-Insomniac-Games-How\n...and as well in this guide for writing performant ISPC kernels:\nhttps://ispc.github.io/perfguide.html\n\n## How TupleVecImpl works\n\n`tuple_vector` inherits from `TupleVecImpl`, which\nprovides the bulk of the functionality for those data containers. It manages\nthe memory allocated, marshals data members to each array of memory, generates\nthe necessary iterators, and so on. \n\nWhen a `tuple_vector` is declared, it is alongside a list of types, or \"tuple\nelements\", indicating what data to store in the container, similar to how `tuple`\noperates. `TupleVecImpl` uses this list of tuple elements to then inherit from a series of\n`TupleVecLeaf` structures, which each have their own pointer to an array of their\ncorresponding type in memory. When dereferencing the container, either to fetch a\ntuple of references or just fetching pointers to the memory, it is these pointers\nthat are utilized or fetched. \n\nWhile each `TupleVecLeaf` contains a pointer to its own block of memory, they\nare not individual memory allocations. When `TupleVecImpl` needs to grow its\ncapacity, it calculates the total size needed for a single allocation, taking\ninto account the number of objects for the container, the size of each tuple\nelement's type, and the alignment requirements for each type. Pointers into the\nallocation for each tuple element are also determined at the same time, which\nare passed to each `TupleVecLeaf`. From there, many of the interactions with\n`TupleVecImpl`, to modify or access members of the container, then reference\neach `TupleVecLeaf`'s data pointer in series, using parameter packs to repeat\neach operation for each parent `TupleVecLeaf`.\n\n## How tuple_vector's iterator works\n\n`TupleVecImpl` provides a definition to an iterator type, `TupleVecIter`.\nAs mentioned above, `TupleVecIter` provides all of the functionality to operate\nas a `RandomAccessIterator`. When it is dereferenced, it provides a tuple of\nreferences, similar to `at()` or `operator[]` on `TupleVecImpl`, as opposed to\na reference of some other type. As well, a customization of `move_iterator` for\n`TupleVecIter` is provided, which will return a tuple of rvalue-references.\n\nThe way that `TupleVecIter` operates internally is to track an index into the\ncontainer, as well as a copy of all of the `TupleVecImpl`'s `TupleVecLeaf`\npointers at the time of the iterator's construction. As a result, modifying the\niterator involves just changing the index, and dereferencing the iterator into\nthe tuple of references involves dereferencing each pointer with an offset\nspecified by that index.\n\nOf the various ways of handling the multitude of references, this tended to\nprovide the best code-generation. For example, having a tuple of pointers that\nare collectively modified with each iterator modification resulted in the compiler\nnot being able to accurately determine which pointers were relevant to the final\noutput of some function, creating many redundant operations. Similarly, having\nthe iterator refer to the source `TupleVecImpl` for the series of pointers\noften resulted in extra, unnecessary, data hops to the `TupleVecImpl` to repeatedly\nfetch data that was not practically mutable, but theoretically mutable. While this\nsolution is the heaviest in terms of storage, the resulted assembly tends to be\ncompetitive with traditional structure-of-arrays setups.\n\n## How to work with tuple_vector, and where to use it\n\t\nPut simply, `tuple_vector` can be used as a replacement for `vector`. For example,\ninstead of declaring a structure and vector as:\n\n```\nstruct Entity\n{\n\tbool active;\n\tfloat lifetime;\n\tVec3 position;\n}\nvector entityVec;\n```\n\n...the `tuple_vector` equivalent of this can be defined as:\n\n```\ntuple_vector entityVec;\n```\n\nIn terms of how `tuple_vector` is modified and accessed, it has a similar\nfeatureset as `vector`, except where `vector` would accept or return a single\nvalue, it instead accepts or returns a tuple of values or unstructured series\nof equivalent arguments.\n\nFor example, the following functions can be used to access the data, either by\nfetching a tuple of references to a series of specific values, or the data\npointers to the tuple elements:\n\n```\ntuple operator[](size_type)\ntuple at(size_type)\ntuple iterator::operator*()\ntuple move_iterator::operator*()\ntuple data()\n\n// extract the Ith tuple element pointer from the tuple_vector\ntemplate\nT* get()\n// e.g. bool* get<0>(), float* get<1>(), and Vec3* get<2>()\n\n// extract the tuple element pointer of type T from the tuple_vector\n// note that this function can only be used if there is one instance\n// of type T in the tuple_vector's elements\ntemplate\nT* get()\n// e.g. bool* get(), float* get(), and Vec3* get()\n```\n\nAnd `push_back(...)` has the following overloads, accepting either values or tuples as needed.\n\n```\ntuple push_back()\npush_back(const bool&, const float&, const Vec3&)\npush_back(tuple)\npush_back(bool&&, float&&, Vec3&&)\npush_back(tuple)\t\t\n```\n...and so on, and so forth, for others like the constructor, `insert(...)`,\n`emplace(...)`, `emplace_back(...)`, `assign(...)`, and `resize(...)`.\n\nAs well, note that the tuple types that are accepted or returned for \n`tuple_vector` have typedefs available in the case of not wanting to use\nautomatic type deduction:\n```\ntypedef eastl::tuple value_tuple;\ntypedef eastl::tuple reference_tuple;\ntypedef eastl::tuple const_reference_tuple;\ntypedef eastl::tuple ptr_tuple;\ntypedef eastl::tuple const_ptr_tuple;\ntypedef eastl::tuple rvalue_tuple;\n```\nWith this, and the fact that the iterator type satisfies\nthe `RandomAccessIterator` requirements, it is possible to use `tuple_vector` in\nmost ways and manners that `vector` was previously used, with few structural\ndifferences.\n\nHowever, even if not using it strictly as a replacement for `vector`, it is\nstill useful as a tool for simplifying management of a traditional structure of\narrays. That is, it is possible to use `tuple_vector` to just perform a single\nlarge memory allocation instead of a series of smaller memory allocations,\nby sizing the `tuple_vector` as needed, fetching the necessary pointers with\n`data()` or `get<...>()`, and carrying on normally.\n\nOne example where this can be utilized is with ISPC integration. Given the\nfollowing ISPC function definition:\n\n\texport void simple(uniform float vin[], uniform float vfactors[], uniform float vout[], uniform int size);\n\n...which generates the following function prototype for C/C++ usage:\n\n\textern void simple(float* vin, float* vfactors, float* vout, int32_t size);\n\t\t\n...this can be utilized with some raw float arrays:\n```\nfloat* vin = new float[NumElements];\nfloat* vfactors = new float[NumElements];\nfloat* vout = new float[NumElements];\n\n// Initialize input buffer\nfor (int i = 0; i < NumElements; ++i)\n{\n\tvin[i] = (float)i;\n\tvfactors[i] = (float)i / 2.0f;\n}\n\n// Call simple() function from simple.ispc file\nsimple(vin, vfactors, vout, NumElements);\n\ndelete vin;\ndelete vfactors;\ndelete vout;\n```\nor, with `tuple_vector`:\n\n```\ntuple_vector simpleData(NumElements);\nfloat* vin = simpleData.get<0>();\nfloat* vfactors = simpleData.get<1>();\nfloat* vout = simpleData.get<2>();\n\n// Initialize input buffer\nfor (int i = 0; i < NumElements; ++i)\n{\n\tvin[i] = (float)i;\n\tvfactors[i] = (float)i / 2.0f;\n}\n\n// Call simple() function from simple.ispc file\nsimple(vin, vfactors, vout, NumElements);\n```\n\t\t\n`simpleData` here only has a single memory allocation during its construction,\ninstead of the three in the first example, and also automatically releases the\nmemory when it falls out of scope.\n\nIt is possible to also skip a memory allocation entirely, in some circumstances.\nEASTL provides \"fixed\" counterparts of many data containers which allows for a \ndata container to have an inlined buffer of memory. For example, \n`eastl::vector` has the following counterpart:\n\n\teastl::fixed_vector\n\nThis buffer allows for enough space to hold a `nodeCount` number of `T` objects,\nskipping any memory allocation at all, until the requested size becomes\ngreater than `nodeCount` - assuming `enableOverflow` is True.\n\nThere is a similar counterpart to `eastl::tuple_vector` available as well:\n\n\teastl::fixed_tuple_vector\n\nThis does the similar legwork in creating an inlined buffer, and all of the\nfunctionality of `tuple_vector` otherwise is supported. Note the slight\ndifference in declaration, though: `nodeCount` and `enableOverflow` are defined\nfirst, and `enableOverflow` is not a default parameter. This change arises out\nof restrictions surrounding variadic templates, in that they must be declared\nlast, and cannot be mixed with default template parameters.\n\nLastly, `eastl::vector` and other EASTL data containers support custom Memory Allocator\ntypes, through their template parameters. For example, `eastl::vector`'s full declaration\nis actually:\n\n\teastl::vector\n\nHowever, because such a default template parameter cannot be used with\nvariadic templates, a separate type for `tuple_vector` is required for such a\ndefinition:\n\n\teastl::tuple_vector_alloc\n\nNote that `tuple_vector` uses EASTLAllocatorType as the allocator.\n\n## Performance comparisons/discussion\n\nA small benchmark suite for `tuple_vector` is included when running the\nEASTLBenchmarks project. It provides the following output on a Core i7 3770k\n(Skylake) at 3.5GHz, with DDR3-1600 memory.\n\nThe `tuple_vector` benchmark cases compare total execution time of similar\nalgorithms run against `eastl::tuple_vector` and `std::vector`, such as\nerasing or inserting elements, iterating through the array to find a specific\nelement, sum all of the elements together via operator[] access, or just\nrunning `eastl::sort` on the data containers. More information about the\nEASTLBenchmarks suite can be found in EASTL/doc/EASTL Benchmarks.html\n\t\nBenchmark | STD execution time | EASTL execution time | Ratio\n--------- | -------- | ---------- | -----\n`tuple_vector/erase ` | 1.7 ms | 1.7 ms | 1.00 \n`tuple_vector/erase ` | 104.6 ms | 106.3 ms | 0.98 \n`tuple_vector/reallocate ` | 1.3 ms | 1.7 ms | 0.77 -\n | | | \n`tuple_vector/erase ` | 3.4 ms | 3.5 ms | 0.98 \n`tuple_vector/insert ` | 3.4 ms | 3.4 ms | 0.99 \n`tuple_vector/iteration ` | 56.3 us | 81.4 us | 0.69 -\n`tuple_vector/operator[] ` | 67.4 us | 61.8 us | 1.09 \n`tuple_vector/push_back ` | 1.3 ms | 818.3 us | 1.53 +\n`tuple_vector/sort ` | 5.8 ms | 7.3 ms | 0.80 \n | | | \n`tuple_vector/erase ` | 34.7 ms | 32.9 ms | 1.05 \n`tuple_vector/insert ` | 41.0 ms | 32.6 ms | 1.26 \n`tuple_vector/iteration ` | 247.1 us | 80.5 us | 3.07 +\n`tuple_vector/operator[]` | 695.7 us | 81.1 us | 8.58 +\n`tuple_vector/push_back ` | 10.0 ms | 6.0 ms | 1.67 +\n`tuple_vector/sort ` | 8.2 ms | 10.1 ms | 0.81 \n | | | \n`vector/erase ` | 1.3 ms | 1.2 ms | 1.05 \n`vector/erase ` | 104.4 ms | 109.4 ms | 0.95 \n`vector/reallocate ` | 1.5 ms | 1.5 ms | 0.95 \n | | | \n`vector/erase ` | 4.3 ms | 3.6 ms | 1.20 \n`vector/insert ` | 4.8 ms | 4.8 ms | 1.01 \n`vector/iteration ` | 71.5 us | 77.3 us | 0.92 \n`vector/operator[] ` | 90.7 us | 87.2 us | 1.04 \n`vector/push_back ` | 1.6 ms | 1.2 ms | 1.38 +\n`vector/sort ` | 7.7 ms | 8.2 ms | 0.93 \n\t\t\nFirst off, `tuple_vector`'s performance versus `std::vector` is\ncomparable, as expected, as the `tuple_vector`'s management for one type\nbecomes very similar to just a regular vector. The major notable exception is\nthe iteration case, which runs `eastl::find_if`. This\nperformance differences is a consequence of the iterator design, and how\nit works with indices, not a direct pointer, so the code generation suffers slightly\nin this compute-bound scenario. This is worth noting as a demonstration of a\ncase where falling back to pointer-based iteration by fetching the `begin` and\n`end` pointers of that tuple element may be preferable, instead of using the\niterator constructs.\n\nThe set of `tuple_vector` tests are more interesting. \nThis is a comparison between a single `std::vector` with a\nstructure containing a `uint64` and 56 bytes of padding, and a `tuple_vector` with\ntwo elements: one for `uint64` and one for 56 bytes of padding. The erase,\ninsert, push_back, and sort cases all perform at a similar relative rate as\nthey did in the `tuple_vector` tests - demonstrating that operations\nthat have to touch all of elements do not have a significant change in\nperformance.\n\nHowever, iteration and operator[] are very different, because\nthose only access the `uint64` member of both `vector` and `tuple_vector` to run\nsome operation. The iteration test now runs 3x faster whereas before it ran\n0.7x as fast, and operator[] runs 8.5x faster, instead of 1.1x. This\ndemonstrates some of the utility of `tuple_vector`, in that these algorithms end\nup being limited by the CPU's compute capabilities, as opposed to being\nlimited by how fast they can load memory in from DRAM. \n\t\t\nIn a series of other tests, generally speaking, `tuple_vector` tends to perform\non par with manual management of multiple arrays in many algorithms and\noperations, often even generating the same code. It should be noted that\nsignificant degrees of inlining and optimization are required to get the most out\nof `tuple_vector`. Compared to accessing a series of arrays or vectors,\n`tuple_vector` does perform a multitude of extra trivial function calls internally\nin order to manage the various elements, or interact with `eastl::tuple` through\nits interface, so running in debug configurations can run significantly slower\nin some cases, e.g. sometimes running at 0.2x the speed compared to vector.\n\t\t\n## The problem of referencing tuple elements\n\nThis will be experienced shortly after using `tuple_vector` in most capacities,\nbut it should be noted that the most significant drawback is that there is no\nway to **symbolically** reference each tuple element of the `tuple_vector` - much\nin the same way as `tuple`. For example, if translating a struct such as...\n\n```\nstruct Entity\n{\n\tfloat x, y, z;\n\tfloat lifetime;\n};\n```\n...to `tuple_vector`, it will exist as:\n\n```\ntuple_vector entityVec;\n```\n\n...and can only be accessed in a manner like `entityVec.get<3>()` to refer to\nthe `lifetime` member. With existing tools, the only good alternatives are to\nencapsulate each float as a separate struct to give it unique typenames...\n\n```\nstruct entityX { float val; };\nstruct entityY { float val; };\nstruct entityZ { float val; };\nstruct entityLifetime { float val; };\n\ntuple_vector entityVec;\n```\n...and then access each tuple element by typename like\n`entityVec.get()`; or, creating an enumerated value to replace\nthe indices...\n\n```\nenum EntityTypeEnum\n{\n\tentityX = 0,\n\tentityY = 1,\n\tentityZ = 2,\n\tentityLifetime = 3\n};\n\ntuple_vector entityVec;\n```\n\n...and then access each tuple element by the enumerated value:\n`entityVec.get()`.\n\nEither way, there is a fairly significant maintenance and readability issue\naround this. This is arguably more severe than with `tuple` on its own\nbecause that is generally not intended for structures with long lifetime.\n\nIdeally, if the language could be mutated to accommodate such a thing, it would\nbe good to have some combination of typenames and symbolic names in the\ndeclaration, e.g. something like\n\n```\ntuple_vector entityVec;\n```\nand be able to reference the tuple elements not just by typename or index, but\nthrough their corresponding symbol, like `entityVec.get()`. Or, it may\nbe interesting if the necessary `get` functions could be even automatically\ngenerated through a reflection system, e.g. `entityVec.get_lifetime()`.\nAll of this remains a pipe dream for now.\n" }, { "path": "doc/CMake/EASTL_Project_Integration.md", "content": "## Using EASTL in your own projects\n\nThis page describes the steps needed to use EASTL in your own projects\n\n## Setting up your project\n\n### Using CMake\n\nAdd to your CMakeLists.txt:\n\n```cmake\nset(EASTL_ROOT_DIR C:/EASTL)\ninclude_directories (${EASTL_ROOT_DIR}/include)\ninclude_directories (${EASTL_ROOT_DIR}/test/packages/EAAssert/include)\ninclude_directories (${EASTL_ROOT_DIR}/test/packages/EABase/include/Common)\ninclude_directories (${EASTL_ROOT_DIR}/test/packages/EAMain/include)\ninclude_directories (${EASTL_ROOT_DIR}/test/packages/EAStdC/include)\ninclude_directories (${EASTL_ROOT_DIR}/test/packages/EATest/include)\ninclude_directories (${EASTL_ROOT_DIR}/test/packages/EAThread/include)\nset(EASTL_LIBRARY debug ${EASTL_ROOT_DIR}/build/Debug/EASTL.lib optimized ${EASTL_ROOT_DIR}/build/Release/EASTL.lib)\nadd_custom_target(NatVis SOURCES ${EASTL_ROOT_DIR}/doc/EASTL.natvis)\n```\n\nAnd then add the library into the linker \n\n```\ntarget_link_libraries(... ${EASTL_LIBRARY})\n```\n\n### Using Visual Studio\n\nUsing Visual Studio projecs directly you will need do the following steps:\n- Add the include paths\n- Add the library path\n- Add the library dependency\n- Add natvis (optional)\n\n> Note that in the examples below ${EASTL_ROOT_DIR} is the folder in which you stored EASTL. You could create an environment variable for this.\n\n#### Add the include paths\n\nAdd the following paths to your C/C++ -> General -> Additional include directories:\n```\n${EASTL_ROOT_DIR}/include\n${EASTL_ROOT_DIR}/test/packages/EAAssert/include\n${EASTL_ROOT_DIR}/test/packages/EABase/include/Common\n${EASTL_ROOT_DIR}/test/packages/EAMain/include)\n${EASTL_ROOT_DIR}/test/packages/EAStdC/include)\n${EASTL_ROOT_DIR}/test/packages/EATest/include)\n${EASTL_ROOT_DIR}/test/packages/EAThread/include)\n```\n\n#### Add the library path\n\nAdd the following library path to your Linker -> General -> Additional Library Directories:\n```\n${EASTL_ROOT_DIR}/build/$(Configuration)\n```\n\n#### Add the library dependency\n\nEither add the following library to your Linker -> Input -> Additional Dependencies\n```\nEASTL.lib\n```\nOr in code use the following:\n```\n#pragma comment(lib, \"EASTL.lib\")\n```\n\n#### Add natvis (optional)\n\n> Adding the natvis file to your project allows the debugger to use custom visualizers for the eastl data types. This greatly enhances the debugging experience.\n\nAdd the natvis file anywhere in your solution:\n\n```\nRight-click your project: Add -> Existing item and then add the following file:\n${EASTL_ROOT_DIR}/doc/EASTL.natvis\n```\n\n## Setting up your code\n\n### Overloading operator new[]\n\nEASTL requires you to have an overload for the operator new[], here is an example that just forwards to global new[]:\n\n```c\nvoid* __cdecl operator new[](size_t size, const char* name, int flags, unsigned debugFlags, const char* file, int line)\n{\n\treturn new uint8_t[size];\n}\n```\n" }, { "path": "doc/Design.md", "content": "# EASTL Design\n\n## Introduction\n\nEASTL (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:\n\n* EASTL has a simplified and more flexible custom allocation scheme.\n* EASTL has significantly easier to read code.\n* EASTL has extension containers and algorithms.\n* EASTL has optimizations designed for game development.\n\nOf 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.\n\n## Motivations\n\nOur 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:\n\n* 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.\n* The STL is sometimes hard to debug, as most STL implementations use cryptic variable names and unusual data structures.\n* STL allocators are sometimes painful to work with, as they have many requirements and cannot be modified once bound to a container.\n* 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.\n* 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.\n* The STL doesn't support alignment of contained objects.\n* STL containers won't let you insert an entry into a container without supplying an entry to copy from. This can be inefficient.\n* 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. \n\n* 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.\n* 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.\n* The STL puts an emphasis on correctness before performance, whereas sometimes you can get significant performance gains by making things less academcially pure.\n* 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).\n* 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.\n* The STL is slow to compile, as most modern STL implementations are very large. \n\n* There are legal issues that make it hard for us to freely use portable STL implementations such as STLPort.\n* We have no say in the design and implementation of the STL and so are unable to change it to work for our needs.\n\n## Prime Directives\n\nThe implementation of EASTL is guided foremost by the following directives which are listed in order of importance.\n\n1. Efficiency (speed and memory usage)\n2. Correctness\n3. Portability\n4. Readability\n\nNote 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.\n\nPortability 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.\n\nReadability 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.\n\n## Thread Safety\n\nIt'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.\n\nIndividual 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.\n\nEASTL 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.\n\nThe 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.\n\nEASTL 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.\n\n## Container Design\n\nAll 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. \n\n```cpp\ntemplate \n\nclass container\n\n{\n\npublic:\n\n typedef container this_type;\n\n typedef\nT \n value_type;\n\n typedef T* \n pointer;\n\n typedef const T* \n const_pointer;\n\n typedef\nT& reference;\n\n\n typedef const\nT& const_reference;\n\n\n typedef\nptrdiff_t difference_type;\n\n\n typedef\nimpl_defined size_type;\n\n\n typedef impl-defined \n iterator;\n\n typedef impl-defined \n const_iterator;\n\n typedef reverse_iterator reverse_iterator;\n\n typedef reverse_iterator reverse_const_iterator;\n\n typedef Allocator \n allocator_type;\n\n\n\npublic:\n\n container(const\nallocator_type& allocator = allocator_type());\n\n container(const this_type&\nx);\n\n\n\n this_type&\noperator=(this_type& x);\n\n void swap(this_type& x);\n\n void reset();\n\n\n\n allocator_type& get_allocator();\n\n void set_allocator(allocator_type& allocator);\n\n\n\n iterator begin();\n\n const_iterator begin() const;\n\n iterator end();\n\n const_iterator end() const;\n\n\n\n bool validate() const;\n int validate_iterator(const_iterator i)\nconst;\n\n\nprotected:\n\n allocator_type mAllocator;\n\n};\n\n\n\ntemplate \n\nbool operator==(const container& a, const container& b);\n\n\n\ntemplate \n\nbool operator!=(const container& a, const\ncontainer&\nb);\n```\n\nNotes:\n\n* Swapped containers do not swap their allocators.\n* 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.\n* 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. \n* 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.\n* 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.\n\n## Allocator Design\n\nThe 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: \n\n```cpp\n// Standard C++ allocator\n\n\n\n template \n\nclass allocator\n\n{\n\npublic:\n\n typedef size_t size_type;\n\n typedef ptrdiff_t difference_type;\n\n typedef T* pointer;\n\n typedef const T* const_pointer;\n\n typedef T& \n reference;\n\n typedef const\nT& const_reference;\n\n typedef T value_type;\n\n\n\n template \n\n struct rebind { typedef allocator other; };\n\n\n\n allocator() throw();\n\n allocator(const allocator&) throw();\n\n template \n\n allocator(const allocator&) throw();\n\n\n\n ~allocator()\nthrow();\n\n\n\n pointer \n address(reference x) const;\n\n const_pointer address(const_reference x)\nconst;\n\n pointer allocate(size_type, typename\nallocator::const_pointer hint = 0);\n\n void deallocate(pointer p,\nsize_type n);\n\n size_type max_size() const\nthrow();\n\n void construct(pointer p,\nconst T& val);\n\n void destroy(pointer\np);\n\n};\n```\n\nEach 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 but instead use allocator\\::rebind\\::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.\n\nWhat 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.\n\nEASTL 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. \n\n```cpp\n// EASTL allocator \n\nclass allocator \n{ \npublic: \n    allocator(const char* pName = NULL); \n\n    void* allocate(size_t n, int flags = 0); \n    void* allocate(size_t n, size_t alignment, size_t offset, int flags = 0); \n    void  deallocate(void* p, size_t n); \n\n    const char* get_name() const; \n    void        set_name(const char* pName); \n}; \n\nallocator* GetDefaultAllocator();\n```\n\n## Fixed Size Container Design\n\nEASTL 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.\n\nEASTL 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.\n\n## Algorithm Design\n\nEASTL 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).\n\nEASTL 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.\n\nThe 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.\n\n## Smart Pointer Design\n\nEASTL implements the following smart pointer types:\n\n* shared_ptr\n* shared_array\n* weak_ptr\n* instrusive_ptr\n* scoped_ptr\n* scoped_array\n* linked_ptr\n* linked_array\n\nAll 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:\n\n* EASTL smart pointers allow you to assign an allocator to them.\n* EASTL shared_ptr implements deletion via a templated parameter instead of a dynamically allocated virtual member object interface.\n\nWith 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.\n\nWith 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.\n\n## list::size is O(n)\n\nAs 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.\n\n## basic_string doesn't use copy-on-write\n\nThe primary benefit of CoW is that it allows for the sharing of string data between two string objects. Thus if you say this:\n\n```cpp\nstring a(\"hello\"); \nstring b(a);\n```\n\nthe \"hello\" will be shared between a and b. If you then say this:\n\n```cpp\na = \"world\";\n```\n\nthen `a` 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.\n\nThe 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.\n\nThe disadvantages of CoW strings are:\n\n* A reference count needs to exist with the string, which increases string memory usage.\n* With thread safety, atomic operations and mutex locks are expensive, especially on weaker memory systems such as console gaming platforms.\n* 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.\n* 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. \n\nThe 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.\n\nThis is a good starting HTML reference on the topic:\n\n> [http://www.gotw.ca/publications/optimizations.htm](http://www.gotw.ca/publications/optimizations.htm)\n\nHere is a well-known Usenet discussion on the topic:\n\n> [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)\n\n----------------------------------------------\nEnd of document\n" }, { "path": "doc/EASTL.natvis", "content": "\n\n\n\n\n\n\n\t({(void*)mPair.mFirst} = {*mPair.mFirst})\n\t({nullptr})\n\t\n\t\t(void*)mPair.mFirst\n\t\t*mPair.mFirst\n\t\n\n\n\n\t({(void*)mpValue} = {*mpValue})\n\t({nullptr})\n\t\n\t\t(void*)mpValue\n\t\t*mpValue\n\t\tmpRefCount->mRefCount\n\t\tmpRefCount->mWeakRefCount\n\t\n\n\n\n\t{((mpRefCount && mpRefCount->mRefCount) ? mpValue : nullptr)}\n\t\n\t\tmpRefCount && mpRefCount->mRefCount ? mpValue : nullptr\n\t\n\n\n\n\t[{$T2}] {{}}\n\t[{$T2}] {{ {*mValue} }}\n\t[{$T2}] {{ {*mValue}, {*(mValue+1)} }}\n\t[{$T2}] {{ {*mValue}, {*(mValue+1)}, {*(mValue+2)} }}\n\t[{$T2}] {{ {*mValue}, {*(mValue+1)}, {*(mValue+2)}, {*(mValue+3)} }}\n\t[{$T2}] {{ {*mValue}, {*(mValue+1)}, {*(mValue+2)}, {*(mValue+3)}, {*(mValue+4)} }}\n\t[{$T2}] {{ {*mValue}, {*(mValue+1)}, {*(mValue+2)}, {*(mValue+3)}, {*(mValue+4)}, {*(mValue+5)} }}\n\t[{$T2}] {{ {*mValue}, {*(mValue+1)}, {*(mValue+2)}, {*(mValue+3)}, {*(mValue+4)}, {*(mValue+5)}, ... }}\n\t\n $T2\n \n $T2\n mValue\n \n \n\n\n\n\t\"{mPair.mFirst.heap.mpBegin,sb}\"\n\t\"{mPair.mFirst.sso.mData,sb}\"\n\t\n\t\tmPair.mFirst.heap.mnSize\n\t\t(mPair.mFirst.heap.mnCapacity & ~kHeapMask)\n\t\tmPair.mFirst.heap.mpBegin,sb\n\n\t\t(SSOLayout::SSO_CAPACITY - mPair.mFirst.sso.mRemainingSizeField.mnRemainingSize)\n\t\tSSOLayout::SSO_CAPACITY\n\t\tmPair.mFirst.sso.mData,sb\n\n\t\t!!(mPair.mFirst.sso.mRemainingSizeField.mnRemainingSize & kSSOMask)\n\t\n\n\n \n\n\t{mPair.mFirst.heap.mpBegin,su}\n\t{mPair.mFirst.sso.mData,su}\n\t\n\t\tmPair.mFirst.heap.mnSize\n\t\t(mPair.mFirst.heap.mnCapacity & ~kHeapMask)\n\t\tmPair.mFirst.heap.mpBegin,su\n\n\t\t(SSOLayout::SSO_CAPACITY - mPair.mFirst.sso.mRemainingSizeField.mnRemainingSize)\n\t\tSSOLayout::SSO_CAPACITY\n\t\tmPair.mFirst.sso.mData,su\n\n\t\t!!(mPair.mFirst.sso.mRemainingSizeField.mnRemainingSize & kSSOMask)\n\t\n\n\n\n\t({first}, {second})\n \n first\n second\n \n\n\n\n\t[{mStorage.mnSize}] {{}}\n\t[{mStorage.mnSize}] {{ {*mStorage.mpData} }}\n\t[{mStorage.mnSize}] {{ {*mStorage.mpData}, {*(mStorage.mpData+1)} }}\n\t[{mStorage.mnSize}] {{ {*mStorage.mpData}, {*(mStorage.mpData+1)}, {*(mStorage.mpData+2)} }}\n\t[{mStorage.mnSize}] {{ {*mStorage.mpData}, {*(mStorage.mpData+1)}, {*(mStorage.mpData+2)}, {*(mStorage.mpData+3)} }}\n\t[{mStorage.mnSize}] {{ {*mStorage.mpData}, {*(mStorage.mpData+1)}, {*(mStorage.mpData+2)}, {*(mStorage.mpData+3)}, {*(mStorage.mpData+4)} }}\n\t[{mStorage.mnSize}] {{ {*mStorage.mpData}, {*(mStorage.mpData+1)}, {*(mStorage.mpData+2)}, {*(mStorage.mpData+3)}, {*(mStorage.mpData+4)}, {*(mStorage.mpData+5)} }}\n\t[{mStorage.mnSize}] {{ {*mStorage.mpData}, {*(mStorage.mpData+1)}, {*(mStorage.mpData+2)}, {*(mStorage.mpData+3)}, {*(mStorage.mpData+4)}, {*(mStorage.mpData+5)}, ... }}\n\t\n\t\t\n\t\t\tDynamicSize\n\t\t\n\t\tmStorage.mnSize\n\t\t\n\t\t\tmStorage.mnSize\n\t\t\tmStorage.mpData\n\t\t\n\t\n\n\n\n\t[{$T2}] {{}}\n\t[{$T2}] {{ {*mStorage.mpData} }}\n\t[{$T2}] {{ {*mStorage.mpData}, {*(mStorage.mpData+1)} }}\n\t[{$T2}] {{ {*mStorage.mpData}, {*(mStorage.mpData+1)}, {*(mStorage.mpData+2)} }}\n\t[{$T2}] {{ {*mStorage.mpData}, {*(mStorage.mpData+1)}, {*(mStorage.mpData+2)}, {*(mStorage.mpData+3)} }}\n\t[{$T2}] {{ {*mStorage.mpData}, {*(mStorage.mpData+1)}, {*(mStorage.mpData+2)}, {*(mStorage.mpData+3)}, {*(mStorage.mpData+4)} }}\n\t[{$T2}] {{ {*mStorage.mpData}, {*(mStorage.mpData+1)}, {*(mStorage.mpData+2)}, {*(mStorage.mpData+3)}, {*(mStorage.mpData+4)}, {*(mStorage.mpData+5)} }}\n\t[{$T2}] {{ {*mStorage.mpData}, {*(mStorage.mpData+1)}, {*(mStorage.mpData+2)}, {*(mStorage.mpData+3)}, {*(mStorage.mpData+4)}, {*(mStorage.mpData+5)}, ... }}\n\t\n\t\t\n\t\t\tConstantSize\n\t\t\n\t\t$T2\n\t\t\n\t\t\t$T2\n\t\t\tmStorage.mpData\n\t\t\n\t\n\n\n\n\t[{mpEnd - mpBegin}] {{}}\n\t[{mpEnd - mpBegin}] {{ {*mpBegin} }}\n\t[{mpEnd - mpBegin}] {{ {*mpBegin}, {*(mpBegin+1)} }}\n\t[{mpEnd - mpBegin}] {{ {*mpBegin}, {*(mpBegin+1)}, {*(mpBegin+2)} }}\n\t[{mpEnd - mpBegin}] {{ {*mpBegin}, {*(mpBegin+1)}, {*(mpBegin+2)}, {*(mpBegin+3)} }}\n\t[{mpEnd - mpBegin}] {{ {*mpBegin}, {*(mpBegin+1)}, {*(mpBegin+2)}, {*(mpBegin+3)}, {*(mpBegin+4)} }}\n\t[{mpEnd - mpBegin}] {{ {*mpBegin}, {*(mpBegin+1)}, {*(mpBegin+2)}, {*(mpBegin+3)}, {*(mpBegin+4)}, {*(mpBegin+5)} }}\n\t[{mpEnd - mpBegin}] {{ {*mpBegin}, {*(mpBegin+1)}, {*(mpBegin+2)}, {*(mpBegin+3)}, {*(mpBegin+4)}, {*(mpBegin+5)}, ... }}\n \n mpEnd - mpBegin\n mCapacityAllocator.mFirst - mpBegin\n \n mpEnd - mpBegin\n mpBegin\n \n \n\n\n\n\t\n\t\t[0] {{}}\n\t\n\t\n\t\t[1] {{ {*mItBegin.mpCurrent} }}\n\t\n\t\n\t\t[{(mItEnd.mpCurrentArrayPtr - mItBegin.mpCurrentArrayPtr) * $T3 + (mItEnd.mpCurrent-mItEnd.mpBegin) - (mItBegin.mpCurrent-mItBegin.mpBegin)}] \n\t\t{{ \n\t\t\t{*mItBegin.mpCurrent}, \n\t\t\t... \n\t\t}}\n\t\n\t\n\t\t(mItEnd.mpCurrentArrayPtr - mItBegin.mpCurrentArrayPtr) * $T3 + (mItEnd.mpCurrent-mItEnd.mpBegin) - (mItBegin.mpCurrent-mItBegin.mpBegin)\n\t\t\n (mItEnd.mpCurrentArrayPtr - mItBegin.mpCurrentArrayPtr) * $T3 + (mItEnd.mpCurrent-mItEnd.mpBegin) - (mItBegin.mpCurrent-mItBegin.mpBegin)\n mItBegin.mpCurrentArrayPtr[(mItBegin.mpCurrent-mItBegin.mpBegin + $i) / $T3][(mItBegin.mpCurrent-mItBegin.mpBegin + $i) % $T3]\n \n\t\n\n\n\n\t{*mpCurrent}\n\t\n\t\t*mpCurrent\n\t\t*(*(mpCurrentArrayPtr-1) + (mpEnd-mpBegin) - 1)\n\t\t*(mpCurrent-1)\n\t\t**(mpCurrentArrayPtr+1)\n\t\t*(mpCurrent+1)\n\t\tmpCurrent == mpBegin\n\t\tmpCurrent+1 == mpEnd\n\t\n\n\n\n\t\n\t\n\t{c}\n\t\n\t\tc\n\t\n\n\n\n\t\n\t\t[0] {{}}\n\t\n \n\t\t[1] {{ {((eastl::ListNode<$T1>*)mNodeAllocator.mFirst.mpNext)->mValue} }}\n\t\n\t\n\t\t[2] \n\t\t{{ \n\t\t\t{((eastl::ListNode<$T1>*)mNodeAllocator.mFirst.mpNext)->mValue}, \n\t\t\t{((eastl::ListNode<$T1>*)mNodeAllocator.mFirst.mpNext->mpNext)->mValue} \n\t\t}}\n\t\n\t\n\t\t[?] \n\t\t{{ \n\t\t\t{((eastl::ListNode<$T1>*)mNodeAllocator.mFirst.mpNext)->mValue}, \n\t\t\t{((eastl::ListNode<$T1>*)mNodeAllocator.mFirst.mpNext->mpNext)->mValue}, \n\t\t\t...\n\t\t}}\n\t\n\t\n\t\t\n\t\t Content of lists will repeat indefinitely. Keep that in mind! \n\t\t \n \n mNodeAllocator.mFirst.mpNext\n mpNext\n ((eastl::ListNode<$T1>*)this)->mValue\n \n \n\n\n\n\t{mValue}\n\t\n\t\tmValue\n\t\t*(eastl::ListNode<$T1>*)mpNext\n\t\t*(eastl::ListNode<$T1>*)mpPrev\n\t\t\n\t\t Content of lists will repeat indefinitely. Keep that in mind! \n\t\t \n\t\t\n\t\t The rest of the list follows: \n\t\t\n \n (eastl::ListNode<$T1>*)mpNext->mpNext\n (eastl::ListNode<$T1>*)mpNext\n mValue\n \n\t\n\n\n\n\t{*mpNode}\n\t\n\t\t*(eastl::ListNode<$T1>*)mpNode\n\t\n\n\n\n\t\n\t\t[0] {{}}\n\t\n \n\t\t[1] \n\t\t{{ \n\t\t\t{((eastl::SListNode<$T1>*)mNode.mpNext)->mValue} \n\t\t}}\n\t\n\t\n\t\t[2] \n\t\t{{ \n\t\t\t{((eastl::SListNode<$T1>*)mNode.mpNext)->mValue}, \n\t\t\t{((eastl::SListNode<$T1>*)mNode.mpNext->mpNext)->mValue} \n\t\t}}\n\t\n\t\n\t\t[?] \n\t\t{{ \n\t\t\t{((eastl::SListNode<$T1>*)mNode.mpNext)->mValue}, \n\t\t\t{((eastl::SListNode<$T1>*)mNode.mpNext->mpNext)->mValue},\n\t\t\t...\n\t\t}}\n\t\n\t\n \n mNode.mpNext\n mpNext\n ((eastl::SListNode<$T1>*)this)->mValue\n \n \n\n\n\n\t{mValue}\n\t\n\t\tmValue\n\t\t*(eastl::SListNode<$T1>*)mpNext\n\t\t\n\t\t The rest of the list follows: \n\t\t\n\t\t\n mpNext == nullptr ? nullptr : (eastl::SListNode<$T1>*)mpNext->mpNext\n (eastl::SListNode<$T1>*)mpNext\n mValue\n \n\t\n\n\n\n\t{*mpNode}\n\t\n\t\t*(eastl::SListNode<$T1>*)mpNode\n\t\n\n\n\n\t[0] {{}}\n [1] {{ {mAnchor.mpNext} }}\n\t[?] {{ {mAnchor.mpNext}, ... }}\n\t\n\t\t\n\t\t Content of intrusive lists will repeat indefinitely. Keep that in mind! \n\t\t \n \n mAnchor.mpNext\n mpNext\n *this\n \n \n\n\n\n\t[0] {{}}\n\t[1] {{ {mAnchor.mpNext} }}\n\t[?] {{ {mAnchor.mpNext}, ... }}\n\t\n\t\t\n\t\t\tContent of intrusive lists will repeat indefinitely. Keep that in mind!\n\t\t\n\t\t\n\t\t\tmAnchor.mpNext\n\t\t\tmpNext\n\t\t\t*(($T1*)this)\n\t\t\n\t\n\n\n\n\t{*($T1*)mpNode}\n\t\n\t\t*($T1*)mpNode\n\t\n\n\n\n\t\n \n\t\t[0] {{}}\n\t\n\t\n\t\t[1] \n\t\t{{ \n\t\t\t{((eastl::rbtree_node<$T1>*)mAnchor.mpNodeLeft)->mValue} \n\t\t}}\n\t\n\t\n\t\t[{mnSize}] \n\t\t{{ \n\t\t\t{((eastl::rbtree_node<$T1>*)mAnchor.mpNodeLeft)->mValue}, \n\t\t\t...\n\t\t}}\n\t\n \n\t\tmnSize\n \n mnSize\n mAnchor.mpNodeParent\n mpNodeLeft\n mpNodeRight\n ((eastl::rbtree_node<$T1>*)this)->mValue\n \n \n\n\n\n\t\n\t\t[0] {{}}\n\t\n\t\n\t\t[1] \n\t\t{{ \n\t\t\t{((eastl::rbtree_node<$T2>*)mAnchor.mpNodeLeft)->mValue} \n\t\t}}\n\t\n\t\n\t\t[{mnSize}] \n\t\t{{ \n\t\t\t{((eastl::rbtree_node<$T2>*)mAnchor.mpNodeLeft)->mValue}, \n\t\t\t...\n\t\t}}\n\t\n \n\t\tmnSize\n \n mnSize\n mAnchor.mpNodeParent\n mpNodeLeft\n mpNodeRight\n ((eastl::rbtree_node<$T2>*)this)->mValue\n \n \n\n\n\n\t{mValue}\n\t\n\t\tmValue\n\t\t\n\t\t It is possible to expand parents that do not exist. \n\t\t\n\t\t*(eastl::rbtree_node<$T1>*)mpNodeParent\n\t\t*(eastl::rbtree_node<$T1>*)mpNodeLeft\n\t\t*(eastl::rbtree_node<$T1>*)mpNodeRight\n\t\n\n\n\n\t{*(eastl::rbtree_node<$T1>*)mpNode}\n\t\n\t\t*(eastl::rbtree_node<$T1>*)mpNode\n\t\n\n\n\n\n [{mnElementCount}] {{}}\n [{mnElementCount}] {{ ... }}\n \n \n mnBucketCount\n mpBucketArray\n \n \n \n \n \n entry->mValue\n \n entry = entry->mpNext\n \n \n bucketIndex++\n \n entry = mpBucketArray[bucketIndex]\n \n \n \n \n\n\n\n\n [{mnElementCount}] {{}}\n [{mnElementCount}] {{ ... }}\n \n \n \n \n \n mValue.first}]\" Condition=\"entry != nullptr\">entry->mValue.second\n \n entry = entry->mpNext\n \n \n bucketIndex++\n \n entry = mpBucketArray[bucketIndex]\n \n \n \n \n\n\n\n\t {mValue}, {*mpNext}\n\t {mValue}\n\t\n\t\n\t\t\n this\n mpNext\n mValue\n \n\t\n\n\n\n\t{mpNode->mValue}\n\t\n\t\tmpNode->mValue\n\t\n\n\n\n\t{*(mIterator-1)}\n\t\n\t\tmIterator-1\n\t\n\n\n\n {{count = {kSize}}}\n \n kSize\n \n \n \n \n\n kSize\n\n \n bBitValue = ((mWord[iWord] >> iBitInWord) % 2) != 0 ? true : false\n bBitValue\n iBitInWord++\n \n iWord++\n iBitInWord = 0\n \n \n \n \n\n\n\n {c}\n \n c\n \n\n\n\n\t{mpBegin,[mnCount]}\n\tmpBegin,[mnCount]\n\n\n\n\t({mFirst}, {mSecond})\n\t({mSecond})\n\t({mFirst})\n\t(empty)\n\t(empty)\n\t({mFirst}, {mSecond})\n\n\n\n\t\n\tnullopt\n\t{value()}\n\t\n\t\tvalue()\n\t\n\n\n\n\t{mError} (Error)\n\t{mValue}\n \n mError\n mValue\n mHasValue\n \n\n\n \n\tvoid\n\t{mError} (Error)\n \n mError\n mHasValue\n \n\n\n\n\t{$T1} to {$T2}}\n\n\n\n\n\t{mRep} nanoseconds\n\n\n\n\t{mRep} microseconds\n\n\n\n\t{mRep} milliseconds\n\n\n\n\t{mRep} seconds\n\n\n\n\t{mRep} minutes\n\n\n\n\t{mRep} hours\n\n\n\n\t{mRep} duration with ratio = [{$T2} : {$T3}] \n\n\n\n\n\n\tempty\n\t{mInvokeFuncPtr}\n\n\n\n\n\t{*val}\n\n\n\n\n\tempty\n\t{m_storage.external_storage}\n\n\n\n\n\t{mAtomic}\n\t\n\t\tmAtomic\n\t\n\n\n\n\t{mFlag.mAtomic}\n\n\n\n\t\n\t[valueless_by_exception]\n\t{{ index=0, value={($T1*)mBuffer.mCharData}}\n\t{{ index=1, value={($T2*)mBuffer.mCharData}}\n\t{{ index=2, value={($T3*)mBuffer.mCharData}}\n\t{{ index=3, value={($T4*)mBuffer.mCharData}}\n\t{{ index=4, value={($T5*)mBuffer.mCharData}}\n\t{{ index=5, value={($T6*)mBuffer.mCharData}}\n\t{{ index=6, value={($T7*)mBuffer.mCharData}}\n\t{{ index=7, value={($T8*)mBuffer.mCharData}}\n\t{{ index=8, value={($T9*)mBuffer.mCharData}}\n\t{{ index=9, value={($T10*)mBuffer.mCharData}}\n\t{{ index=10, value={($T11*)mBuffer.mCharData}}\n\t{{ index=11, value={($T12*)mBuffer.mCharData}}\n\t{{ index=12, value={($T13*)mBuffer.mCharData}}\n\t{{ index=13, value={($T14*)mBuffer.mCharData}}\n\t{{ index=14, value={($T15*)mBuffer.mCharData}}\n\t{{ index=15, value={($T16*)mBuffer.mCharData}}\n\t{{ index=16, value={($T17*)mBuffer.mCharData}}\n\t{{ index=17, value={($T18*)mBuffer.mCharData}}\n\t{{ index=18, value={($T19*)mBuffer.mCharData}}\n\t{{ index=19, value={($T20*)mBuffer.mCharData}}\n\t{{ index=20, value={($T21*)mBuffer.mCharData}}\n\t{{ index=21, value={($T22*)mBuffer.mCharData}}\n\t{{ index=22, value={($T23*)mBuffer.mCharData}}\n\t{{ index=23, value={($T24*)mBuffer.mCharData}}\n\t{{ index=24, value={($T25*)mBuffer.mCharData}}\n\t{{ index=25, value={($T26*)mBuffer.mCharData}}\n\t{{ index=26, value={($T27*)mBuffer.mCharData}}\n\t{{ index=27, value={($T28*)mBuffer.mCharData}}\n\t{{ index=28, value={($T29*)mBuffer.mCharData}}\n\t{{ index=29, value={($T30*)mBuffer.mCharData}}\n\t{{ index=30, value={($T31*)mBuffer.mCharData}}\n\t\n\t\tindex()\n\t\t($T1*)mBuffer.mCharData\n\t\t($T2*)mBuffer.mCharData\n\t\t($T3*)mBuffer.mCharData\n\t\t($T4*)mBuffer.mCharData\n\t\t($T5*)mBuffer.mCharData\n\t\t($T6*)mBuffer.mCharData\n\t\t($T7*)mBuffer.mCharData\n\t\t($T8*)mBuffer.mCharData\n\t\t($T9*)mBuffer.mCharData\n\t\t($T10*)mBuffer.mCharData\n\t\t($T11*)mBuffer.mCharData\n\t\t($T12*)mBuffer.mCharData\n\t\t($T13*)mBuffer.mCharData\n\t\t($T14*)mBuffer.mCharData\n\t\t($T15*)mBuffer.mCharData\n\t\t($T16*)mBuffer.mCharData\n\t\t($T17*)mBuffer.mCharData\n\t\t($T18*)mBuffer.mCharData\n\t\t($T19*)mBuffer.mCharData\n\t\t($T20*)mBuffer.mCharData\n\t\t($T21*)mBuffer.mCharData\n\t\t($T22*)mBuffer.mCharData\n\t\t($T23*)mBuffer.mCharData\n\t\t($T24*)mBuffer.mCharData\n\t\t($T25*)mBuffer.mCharData\n\t\t($T26*)mBuffer.mCharData\n\t\t($T27*)mBuffer.mCharData\n\t\t($T28*)mBuffer.mCharData\n\t\t($T29*)mBuffer.mCharData\n\t\t($T30*)mBuffer.mCharData\n\t\t($T31*)mBuffer.mCharData\n\t\n\n\n\n\n \n ({*this,view(noparens)})\n \n\n\n\n {(*((eastl::Internal::TupleLeaf<0,$T1,0>*)&mImpl)).mValue}\n ({*this,view(noparens)})\n \n (*((eastl::Internal::TupleLeaf<0,$T1,0>*)&mImpl)).mValue\n \n\n\n\n {(*((eastl::Internal::TupleLeaf<0,$T1,0>*)&mImpl)).mValue}, {(*((eastl::Internal::TupleLeaf<1,$T2,0>*)&mImpl)).mValue}\n ({*this,view(noparens)})\n \n (*((eastl::Internal::TupleLeaf<0,$T1,0>*)&mImpl)).mValue\n (*((eastl::Internal::TupleLeaf<1,$T2,0>*)&mImpl)).mValue\n \n\n\n\n {(*((eastl::Internal::TupleLeaf<0,$T1,0>*)&mImpl)).mValue}, {(*((eastl::Internal::TupleLeaf<1,$T2,0>*)&mImpl)).mValue}, {(*((eastl::Internal::TupleLeaf<2,$T3,0>*)&mImpl)).mValue}\n ({*this,view(noparens)})\n \n (*((eastl::Internal::TupleLeaf<0,$T1,0>*)&mImpl)).mValue\n (*((eastl::Internal::TupleLeaf<1,$T2,0>*)&mImpl)).mValue\n (*((eastl::Internal::TupleLeaf<2,$T3,0>*)&mImpl)).mValue\n \n\n\n\n {(*((eastl::Internal::TupleLeaf<0,$T1,0>*)&mImpl)).mValue}, {(*((eastl::Internal::TupleLeaf<1,$T2,0>*)&mImpl)).mValue}, {(*((eastl::Internal::TupleLeaf<2,$T3,0>*)&mImpl)).mValue}, {(*((eastl::Internal::TupleLeaf<3,$T4,0>*)&mImpl)).mValue}\n ({*this,view(noparens)})\n \n (*((eastl::Internal::TupleLeaf<0,$T1,0>*)&mImpl)).mValue\n (*((eastl::Internal::TupleLeaf<1,$T2,0>*)&mImpl)).mValue\n (*((eastl::Internal::TupleLeaf<2,$T3,0>*)&mImpl)).mValue\n (*((eastl::Internal::TupleLeaf<3,$T4,0>*)&mImpl)).mValue\n \n\n\n\n {(*((eastl::Internal::TupleLeaf<0,$T1,0>*)&mImpl)).mValue}, {(*((eastl::Internal::TupleLeaf<1,$T2,0>*)&mImpl)).mValue}, {(*((eastl::Internal::TupleLeaf<2,$T3,0>*)&mImpl)).mValue}, {(*((eastl::Internal::TupleLeaf<3,$T4,0>*)&mImpl)).mValue}, {(*((eastl::Internal::TupleLeaf<4,$T5,0>*)&mImpl)).mValue}\n ({*this,view(noparens)})\n \n (*((eastl::Internal::TupleLeaf<0,$T1,0>*)&mImpl)).mValue\n (*((eastl::Internal::TupleLeaf<1,$T2,0>*)&mImpl)).mValue\n (*((eastl::Internal::TupleLeaf<2,$T3,0>*)&mImpl)).mValue\n (*((eastl::Internal::TupleLeaf<3,$T4,0>*)&mImpl)).mValue\n (*((eastl::Internal::TupleLeaf<4,$T5,0>*)&mImpl)).mValue\n \n\n\n\n {(*((eastl::Internal::TupleLeaf<0,$T1,0>*)&mImpl)).mValue}, {(*((eastl::Internal::TupleLeaf<1,$T2,0>*)&mImpl)).mValue}, {(*((eastl::Internal::TupleLeaf<2,$T3,0>*)&mImpl)).mValue}, {(*((eastl::Internal::TupleLeaf<3,$T4,0>*)&mImpl)).mValue}, {(*((eastl::Internal::TupleLeaf<4,$T5,0>*)&mImpl)).mValue}, {(*((eastl::Internal::TupleLeaf<5,$T6,0>*)&mImpl)).mValue}\n ({*this,view(noparens)})\n \n (*((eastl::Internal::TupleLeaf<0,$T1,0>*)&mImpl)).mValue\n (*((eastl::Internal::TupleLeaf<1,$T2,0>*)&mImpl)).mValue\n (*((eastl::Internal::TupleLeaf<2,$T3,0>*)&mImpl)).mValue\n (*((eastl::Internal::TupleLeaf<3,$T4,0>*)&mImpl)).mValue\n (*((eastl::Internal::TupleLeaf<4,$T5,0>*)&mImpl)).mValue\n (*((eastl::Internal::TupleLeaf<5,$T6,0>*)&mImpl)).mValue\n \n\n\n\n {(*((eastl::Internal::TupleLeaf<0,$T1,0>*)&mImpl)).mValue}, {(*((eastl::Internal::TupleLeaf<1,$T2,0>*)&mImpl)).mValue}, {(*((eastl::Internal::TupleLeaf<2,$T3,0>*)&mImpl)).mValue}, {(*((eastl::Internal::TupleLeaf<3,$T4,0>*)&mImpl)).mValue}, {(*((eastl::Internal::TupleLeaf<4,$T5,0>*)&mImpl)).mValue}, {(*((eastl::Internal::TupleLeaf<5,$T6,0>*)&mImpl)).mValue}, {(*((eastl::Internal::TupleLeaf<6,$T7,0>*)&mImpl)).mValue}\n ({*this,view(noparens)})\n \n (*((eastl::Internal::TupleLeaf<0,$T1,0>*)&mImpl)).mValue\n (*((eastl::Internal::TupleLeaf<1,$T2,0>*)&mImpl)).mValue\n (*((eastl::Internal::TupleLeaf<2,$T3,0>*)&mImpl)).mValue\n (*((eastl::Internal::TupleLeaf<3,$T4,0>*)&mImpl)).mValue\n (*((eastl::Internal::TupleLeaf<4,$T5,0>*)&mImpl)).mValue\n (*((eastl::Internal::TupleLeaf<5,$T6,0>*)&mImpl)).mValue\n (*((eastl::Internal::TupleLeaf<6,$T7,0>*)&mImpl)).mValue\n \n\n\n\n\t(nothing)\n\t{static_cast<flag_type>(m_mask),en}\n\t\n\t\tm_mask,bb\n\t\t(flag_type)(1 << 0),en\n\t\t(flag_type)(1 << 1),en\n\t\t(flag_type)(1 << 2),en\n\t\t(flag_type)(1 << 3),en\n\t\t(flag_type)(1 << 4),en\n\t\t(flag_type)(1 << 5),en\n\t\t(flag_type)(1 << 6),en\n\t\t(flag_type)(1 << 7),en\n\n\t\t(flag_type)(1 << 8),en\n\t\t(flag_type)(1 << 9),en\n\t\t(flag_type)(1 << 10),en\n\t\t(flag_type)(1 << 11),en\n\t\t(flag_type)(1 << 12),en\n\t\t(flag_type)(1 << 13),en\n\t\t(flag_type)(1 << 14),en\n\t\t(flag_type)(1 << 15),en\n\n\t\t(flag_type)(1 << 16),en\n\t\t(flag_type)(1 << 17),en\n\t\t(flag_type)(1 << 18),en\n\t\t(flag_type)(1 << 19),en\n\t\t(flag_type)(1 << 20),en\n\t\t(flag_type)(1 << 21),en\n\t\t(flag_type)(1 << 22),en\n\t\t(flag_type)(1 << 23),en\n\n\t\t(flag_type)(1 << 24),en\n\t\t(flag_type)(1 << 25),en\n\t\t(flag_type)(1 << 26),en\n\t\t(flag_type)(1 << 27),en\n\t\t(flag_type)(1 << 28),en\n\t\t(flag_type)(1 << 29),en\n\t\t(flag_type)(1 << 30),en\n\t\t(flag_type)(1 << 31),en\n\t\n\n\n\n\t\n\t{static_cast<flag_type>(__log2(m_mask)),en}\n\t\n\t(multiple values)\n\t\n\t(nothing)\n\n\t\n\t\tm_mask,bb\n\t\t(flag_type)(0),en\n\t\t(flag_type)(1),en\n\t\t(flag_type)(2),en\n\t\t(flag_type)(3),en\n\t\t(flag_type)(4),en\n\t\t(flag_type)(5),en\n\t\t(flag_type)(6),en\n\t\t(flag_type)(7),en\n\t\t\n\t\t(flag_type)(8),en\n\t\t(flag_type)(9),en\n\t\t(flag_type)(10),en\n\t\t(flag_type)(11),en\n\t\t(flag_type)(12),en\n\t\t(flag_type)(13),en\n\t\t(flag_type)(14),en\n\t\t(flag_type)(15),en\n\t\t\n\t\t(flag_type)(16),en\n\t\t(flag_type)(17),en\n\t\t(flag_type)(18),en\n\t\t(flag_type)(19),en\n\t\t(flag_type)(20),en\n\t\t(flag_type)(21),en\n\t\t(flag_type)(22),en\n\t\t(flag_type)(23),en\n\t\t\n\t\t(flag_type)(24),en\n\t\t(flag_type)(25),en\n\t\t(flag_type)(26),en\n\t\t(flag_type)(27),en\n\t\t(flag_type)(28),en\n\t\t(flag_type)(29),en\n\t\t(flag_type)(30),en\n\t\t(flag_type)(31),en\n\t\n\n\n" }, { "path": "doc/FAQ.md", "content": "# EASTL FAQ\n\nWe 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.\n\n## Information\n\n1. [What is EASTL?](#info1-what-is-eastl)\n2. [What uses are EASTL suitable for?](#info2-what-uses-are-eastl-suitable-for)\n3. [How does EASTL differ from standard C++ STL?](#info3-how-does-eastl-differ-from-standard-c-stl)\n4. [Is EASTL thread-safe?](#info4-is-eastl-thread-safe)\n5. [What platforms/compilers does EASTL support?](#info5-what-platformscompilers-does-eastl-support)\n6. [Why is there EASTL when there is the STL?](#info6-why-is-there-eastl-when-there-is-the-stl)\n7. [Can I mix EASTL with standard C++ STL?](#info7-can-i-mix-eastl-with-standard-c-stl)\n8. [Where can I learn more about STL and EASTL?](#info8-where-can-i-learn-more-about-stl-and-eastl)\n9. [What is the legal status of EASTL?](#info9-what-is-the-legal-status-of-eastl)\n10. [Does EASTL deal with compiler exception handling settings?](#info10-does-eastl-deal-with-compiler-exception-handling-settings)\n11. [What C++ language features does EASTL use (e.g. virtual functions)?](#info11-what-c-language-features-does-eastl-use-eg-virtual-functions)\n12. [What compiler warning levels does EASTL support?](#info12-what-compiler-warning-levels-does-eastl-support)\n13. [Is EASTL compatible with Lint?](#info13-is-eastl-compatible-with-lint)\n14. [What compiler settings do I need to compile EASTL?](#info14-what-compiler-settings-do-i-need-to-compile-eastl)\n15. [How hard is it to incorporate EASTL into my project?](#info15-how-hard-is-it-to-incorporate-eastl-into-my-project)\n16. [Should I use EASTL instead of std STL or instead of my custom library?](#info16-should-i-use-eastl-instead-of-std-stl-or-instead-of-my-custom-library)\n17. [I think I've found a bug. What do I do?](#info17-i-think-ive-found-a-bug-what-do-i-do)\n18. [Can EASTL be used by third party EA developers?](#info18-can-eastl-be-used-by-third-party-ea-developers)\n\n## Performance\n\n1. [How efficient is EASTL compared to standard C++ STL implementations?](#perf1-how-efficient-is-eastl-compared-to-standard-c-stl-implementations)\n2. [How efficient is EASTL in general?](#perf2-how-efficient-is-eastl-in-general)\n3. [Strings don't appear to use the \"copy-on-write\" optimization. Why not?](#perf3-strings-dont-appear-to-use-the-copy-on-write-cow-optimization-why-not)\n4. [Does EASTL cause code bloat, given that it uses templates?](#perf4-does-eastl-cause-code-bloat-given-that-it-uses-templates)\n5. [Don't STL and EASTL containers fragment memory?](#perf5-dont-stl-and-eastl-containers-fragment-memory)\n6. [I don't see container optimizations for equivalent scalar types such as pointer types. Why?](#perf6-i-dont-see-container-optimizations-for-equivalent-scalar-types-such-as-pointer-types-why)\n7. [I've seen some STL's provide a default quick \"node allocator\" as the default allocator. Why doesn't EASTL do this?](#perf7-ive-seen-some-stls-provide-a-default-quick-node-allocator-as-the-default-allocator-why-doesnt-eastl-do-this)\n8. [Templates sometimes seem to take a long time to compile. Why do I do about that?](#perf8-templates-sometimes-seem-to-take-a-long-time-to-compile-why-do-i-do-about-that)\n9. [How do I assign a custom allocator to an EASTL container?](#cont8-how-do-i-assign-a-custom-allocator-to-an-eastl-container)\n10. [How well does EASTL inline?](#perf10-how-well-does-eastl-inline)\n11. [How do I control function inlining?](#perf11-how-do-i-control-function-inlining)\n12. [C++ / EASTL seems to bloat my .obj files much more than C does.](#perf12-c--eastl-seems-to-bloat-my-obj-files-much-more-than-c-does)\n13. [What are the best compiler settings for EASTL?](#perf13-what-are-the-best-compiler-settings-for-eastl)\n\n## Problems\n\n1. [I'm getting screwy behavior in sorting algorithms or sorted containers. What's wrong?](#prob1-im-getting-screwy-behavior-in-sorting-algorithms-or-sorted-containers-whats-wrong)\n2. [I am getting compiler warnings (e.g. C4244, C4242 or C4267) that make no sense. Why?](#prob2-i-am-getting-compiler-warnings-eg-c4244-c4242-or-c4267-that-make-no-sense-why)\n3. [I am getting compiler warning C4530, which complains about exception handling and \"unwind semantics.\" What gives?](#prob3-i-am-getting-compiler-warning-c4530-which-complains-about-exception-handling-and-unwind-semantics-what-gives)\n4. [Why are tree-based containers hard to read with a debugger?](#prob4-why-are-tree-based-eastl-containers-hard-to-read-with-a-debugger)\n5. [The EASTL source code is sometimes rather complicated looking. Why is that?](#prob5-the-eastl-source-code-is-sometimes-rather-complicated-looking-why-is-that)\n6. [When I get compilation errors, they are very long and complicated looking. What do I do?](#prob6-when-i-get-compilation-errors-they-are-very-long-and-complicated-looking-what-do-i-do)\n7. [Templates sometimes seem to take a long time to compile. Why do I do about that?](#prob7-templates-sometimes-seem-to-take-a-long-time-to-compile-why-do-i-do-about-that)\n8. [I get the compiler error: \"template instantiation depth exceeds maximum of 17. use -ftemplate-depth-NN to increase the maximum\"](#prob8-i-get-the-compiler-error-template-instantiation-depth-exceeds-maximum-of-17-use--ftemplate-depth-nn-to-increase-the-maximum)\n9. [I'm getting errors about min and max while compiling.](#prob9-im-getting-errors-about-min-and-max-while-compiling)\n10. [C++ / EASTL seems to bloat my .obj files much more than C does.](#prob10-c--eastl-seems-to-bloat-my-obj-files-much-more-than-c-does)\n11. [I'm getting compiler errors regarding operator new being previously defined.](#prob11-im-getting-compiler-errors-regarding-placement-operator-new-being-previously-defined)\n12. [I'm getting errors related to wchar_t string functions such as wcslen().](#prob12-im-getting-errors-related-to-wchar_t-string--functions-such-as-wcslen)\n13. [I'm getting compiler warning C4619: there is no warning number Cxxxx (e.g. C4217).](#prob13-im-getting-compiler-warning-c4619-there-is-no-warning-number-cxxxx-eg-c4217)\n14. [My stack-based fixed_vector is not respecting the object alignment requirements.](#prob14-my-stack-based-fixed_vector-is-not-respecting-the-object-alignment-requirements)\n15. [I am getting compiler errors when using GCC under XCode (Macintosh/iphone).](#prob15-i-am-getting-compiler-errors-when-using-gcc-under-xcode-macintoshiphone)\n16. [I am getting linker errors about Vsnprintf8 or Vsnprintf16.](#prob16-i-am-getting-linker-errors-about-vsnprintf8-or-vsnprintf16)\n17. [I am getting compiler errors about UINT64_C or UINT32_C.](#prob17-i-am-getting-compiler-errors-about-uint64_c-or-uint32_c)\n18. [I am getting a crash with a global EASTL container.](#prob18-i-am-getting-a-crash-with-a-global-eastl-container)\n19. [Why doesn't EASTL support passing NULL to functions with pointer arguments?](#prob19-why-doesnt-eastl-support-passing-null-string-functions)\n\n## Debug\n\n1. [How do I get VC++ mouse-overs to view templated data?](#debug1-how-do-i-set-the-vc-debugger-to-display-eastl-container-data-with-tooltips)\n2. [How do I view containers if the visualizer/tooltip support is not present?](#debug2-how-do-i-view-containers-if-the-visualizertooltip-support-is-not-present)\n3. [The EASTL source code is sometimes rather complicated looking. Why is that?](#debug3-the-eastl-source-code-is-sometimes-rather-complicated-looking-why-is-that)\n4. [When I get compilation errors, they are very long and complicated looking. What do I do?](#debug4-when-i-get-compilation-errors-they-are-very-long-and-complicated-looking-what-do-i-do)\n5. [How do I measure hash table balancing?](#debug5-how-do-i-measure-hash-table-balancing)\n\n## Containers\n\n1. [Why do some containers have \"fixed\" versions (e.g. fixed_list) but others(e.g. deque) don't have fixed versions?](#cont1-why-do-some-containers-have-fixed-versions-eg-fixed_list-but-otherseg-deque-dont-have-fixed-versions)\n2. [Can I mix EASTL with standard C++ STL?](#cont2-can-i-mix-eastl-with-standard-c-stl)\n3. [Why are there so many containers?](#cont3-why-are-there-so-many-containers)\n4. [Don't STL and EASTL containers fragment memory?](#cont4-dont-stl-and-eastl-containers-fragment-memory)\n5. [I don't see container optimizations for equivalent scalar types such as pointer types. Why?](#cont5-i-dont-see-container-optimizations-for-equivalent-scalar-types-such-as-pointer-types-why)\n6. [What about alternative container and algorithm implementations (e.g. treaps, skip lists, avl trees)?](#cont6-what-about-alternative-container-and-algorithm-implementations-eg-treaps-skip-lists-avl-trees)\n7. [Why are containers hard to read with a debugger?](#cont7-why-are-tree-based-eastl-containers-hard-to-read-with-a-debugger)\n8. [How do I assign a custom allocator to an EASTL container?](#cont8-how-do-i-assign-a-custom-allocator-to-an-eastl-container)\n9. [How do I set the VC++ debugger to display EASTL container data with tooltips?](#cont9-how-do-i-set-the-vc-debugger-to-display-eastl-container-data-with-tooltips)\n10. [How do I use a memory pool with a container?](#cont10-how-do-i-use-a-memory-pool-with-a-container)\n11. [How do I write a comparison (operator<()) for a struct that contains two or more members?](#cont11-how-do-i-write-a-comparison-operator-for-a-struct-that-contains-two-or-more-members)\n12. [Why doesn't container X have member function Y?](#cont12-why-doesnt-container-x-have-member-function-y)\n13. [How do I search a map of strings via a char pointer efficiently? If I use map.find(\"hello\") it creates a temporary string, which is inefficient.](#cont13-how-do-i-search-a-map-of-strings-via-a-char-pointer-efficiently-if-i-use-mapfindhello-it-creates-a-temporary-string-which-is-inefficient)\n14. [Why are set and hash_set iterators const (i.e. const_iterator)?](#cont14-why-are-set-and-hash_set-iterators-const-ie-const_iterator)\n15. [How do I prevent my hash container from re-hashing?](#cont15-how-do-i-prevent-my-hash-container-from-re-hashing)\n16. [Which uses less memory, a map or a hash_map?](#cont16-which-uses-less-memory-a-map-or-a-hash_map)\n17. [How do I write a custom hash function?](#cont17-how-do-i-write-a-custom-hash-function)\n18. [How do I write a custom compare function for a map or set?](#cont18-how-do-i-write-a-custom-compare-function-for-a-map-or-set)\n19. [How do I force my vector or string capacity down to the size of the container?](#cont19-how-do-i-force-my-vector-or-string-capacity-down-to-the-size-of-the-container)\n20. [How do I iterate a container while (selectively) removing items from it?](#cont20-how-do-i-iterate-a-container-while-selectively-removing-items-from-it)\n21. [How do I store a pointer in a container?](#cont21-how-do-i-store-a-pointer-in-a-container)\n22. [How do I make a union of two containers? difference? intersection?](#cont22-how-do-i-make-a-union-of-two-containers-difference-intersection)\n23. [How do I override the default global allocator?](#cont23-how-do-i-override-the-default-global-allocator)\n24. [How do I do trick X with the string container?](#cont24-how-do-i-do-trick-x-with-the-string-container)\n25. [How do EASTL smart pointers compare to Boost smart pointers?](#cont25-how-do-eastl-smart-pointers-compare-to-boost-smart-pointers)\n26. [How do your forward-declare an EASTL container?](#cont26-how-do-your-forward-declare-an-eastl-container)\n27. [How do I make two containers share a memory pool?](#cont27-how-do-i-make-two-containers-share-a-memory-pool)\n28. [Can I use a std (STL) allocator with EASTL?](#cont28-can-i-use-a-std-stl-allocator-with-eastl)\n29. [What are the requirements of classes stored in containers?](#what-are-the-requirements-of-classes-stored-in-containers)\n\n## Algorithms\n\n1. [I'm getting screwy behavior in sorting algorithms or sorted containers. What's wrong?](#algo1-im-getting-screwy-behavior-in-sorting-algorithms-or-sorted-containers-whats-wrong)\n2. [How do I write a comparison (operator<()) for a struct that contains two or more members?](#algo2-how-do-i-write-a-comparison-operator-for-a-struct-that-contains-two-or-more-members)\n3. [How do I sort something in reverse order?](#algo3-how-do-i-sort-something-in-reverse-order)\n4. [I'm getting errors about min and max while compiling.](#algo4-im-getting-errors-about-min-and-max-while-compiling)\n5. [Why don't algorithms take a container as an argument instead of iterators? A container would be more convenient.](#algo5-why-dont-algorithms-take-a-container-as-an-argument-instead-of-iterators-a-container-would-be-more-convenient)\n6. [Given a container of pointers, how do I find an element by value (instead of by pointer)?](#algo6-given-a-container-of-pointers-how-do-i-find-an-element-by-value-instead-of-by-pointer)\n7. [When do stored objects need to support opertor < vs. when do they need to support operator ==?](#algo7-when-do-stored-objects-need-to-support-operator--vs-when-do-they-need-to-support-operator-)\n8. [How do I sort via pointers or array indexes instead of objects directly?](#algo8-how-do-i-sort-via-pointers-or-array-indexes-instead-of-objects-directly)\n\n## Iterators\n\n1. [What's the difference between iterator, const iterator, and const_iterator?](#iter1-whats-the-difference-between-iterator-const-iterator-and-const_iterator)\n2. [How do I tell from an iterator what type of thing it is iterating?](#iter2-how-do-i-tell-from-an-iterator-what-type-of-thing-it-is-iterating)\n3. [How do I iterate a container while (selectively) removing items from it?](#iter3-how-do-i-iterate-a-container-while-selectively-removing-items-from-it)\n4. [What is an insert_iterator?](#iter4-what-is-an-insert_iterator)\n\n## Information\n\n### Info.1 What is EASTL?\n\nEASTL 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:\n\n* Containers\n* Iterators\n* Algorithms\n* Utilities\n* Smart pointers\n* Type traits\n\nOf these, the last two (smart pointers and type traits) do not have analogs in standard C++. With respect to the other items, EASTL provides extensions and optimizations over the equivalents in standard C++ STL.\n\nEASTL is a professional-level implementation which outperforms commercial implementations (where functionality overlaps) and is significantly easier to read and debug.\n\n### Info.2 What uses are EASTL suitable for?\n\nEASTL 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.\n\n### Info.3 How does EASTL differ from standard C++ STL?\n\nThere are three kinds of ways that EASTL differs from standard STL:\n\n* EASTL equivalents to STL sometimes differ.\n* EASTL implementations sometimes differ from STL implementations of the same thing.\n* EASTL has functionality that doesn't exist in STL.\n\nWith respect to item #1, the changes are such that they benefit game development and and not the type that could silently hurt you if you were more familiar with STL interfaces.\n\nWith 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.\n\nWith 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.\n\nWays in which EASTL is better than standard STL:\n\n* Has higher performance in release builds, sometimes dramatically so.\n* Has significantly higher performance in debug builds, due to less call overhead.\n* Has extended per-container functionality, particularly for game development.\n* Has additional containers that are useful for high performance game development.\n* Is easier to read, trace, and debug.\n* Memory allocation is much simpler and more controllable.\n* Has higher portability, as there is a single implementation for all platforms.\n* Has support of object alignment, whereas such functionality is not natively supported by STL.\n* We have control over it, so we can modify it as we like.\n* Has stricter standards for container design and behavior, particularly as this benefits game development.\n\nWays in which EASTL is worse than standard STL:\n\n* Standard STL implementations are currently very reliable and weather-worn, whereas EASTL is less tested.\n* Standard STL is automatically available with just about every C++ compiler vendor's library.\n* Standard STL is supported by the compiler vendor and somewhat by the Internet community.\n\n#### EASTL coverage of std STL\n\n* list\n* vector\n* deque\n* string\n* set\n* multiset\n* map\n* multimap\n* bitset\n* queue\n* stack\n* priority_queue\n* memory\n* numeric\n* algorithm (all but inplace_merge, prev_permutation, next_permutation, nth_element, includes, unique_copy)\n* utility\n* functional\n* iterator\n\nEASTL additions/amendments to std STL\n\n* allocators work in a simpler way.\n* exception handling can be disabled.\n* all containers expose/declare their node size, so you can make a node allocator for them.\n* all containers have reset(), which unilaterally forgets their contents.\n* all containers have validate() and validate_iterator() functions.\n* all containers understand and respect object alignment requirements.\n* all containers guarantee no memory allocation upon being newly created as empty.\n* all containers and their iterators can be viewed in a debugger (no other STL does this, believe it or not).\n* linear containers guarantee linear memory.\n* vector has push_back(void).\n* vector has a data() function.\n* vector is actually a vector of type bool.\n* vector and string have set_capacity().\n* string has sprintf(), append_sprintf(), trim(), compare_i(), make_lower(), make_upper().\n* deque allows you to specify the subarray size.\n* list has a push_back(void) and push_back(void) function.\n* hash_map, hash_set, etc. have find_as().\n\nEASTL coverage of TR1 (tr1 refers to proposed additions for the next C++ standard library, ~2008)\n\n* array\n* type_traits (there are about 30 of these)\n* unordered_set (EASTL calls it hash_set)\n* unordered_multiset\n* unordered_map\n* unordered_multimap\n* shared_ptr, shared_array, weak_ptr, scoped_ptr, scoped_array, intrusive_ptr\n\nEASTL additional functionality (not found elsewhere)\n\n* fixed_list\n* fixed_slist\n* fixed_vector\n* fixed_string\n* fixed_substring\n* fixed_set\n* fixed_multiset\n* fixed_map\n* fixed_multimap\n* fixed_hash_set\n* fixed_hash_multiset\n* fixed_hash_map\n* fixed_hash_multimap\n* vector_set\n* vector_multiset\n* vector_map\n* vector_multimap\n* intrusive_list\n* intrusive_slist\n* intrusive_sdlist\n* intrusive_hash_set\n* intrusive_hash_multiset\n* intrusive_hash_map\n* intrusive_hash_multimap\n* slist (STLPort's STL has this)\n* heap\n* linked_ptr, linked_array\n* sparse_matrix (this is not complete as of this writing)\n* ring_buffer\n* compressed_pair\n* call_traits\n* binary_search_i, change_heap, find_first_not_of, find_last_of, find_last_not_of, identical\n* comb_sort, bubble_sort, selection_sort, shaker_sort, bucket_sort\n* equal_to_2, not_equal_to_2, str_equal_to, str_equal_to_i\n\n### Info.4 Is EASTL thread-safe?\n\nIt'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.\n\nIndividual 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.\n\nEASTL 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.\n\nThe 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.\n\nEASTL 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.\n\n### Info.5 What platforms/compilers does EASTL support?\n\nEASTL'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 (with a couple small exceptions), 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:\n\n| Compiler | Status | Notes |\n|---------|--------|-------|\n| GCC 2.9x | Supported | However, GCC 2.9x has some issues that you may run into that cause you to use EASTL facilities differently than a fully compliant compiler would allow. |\n| GCC 3.x+ | Supported | This compiler is used by the Mac OSX, and Linux platforms. |\n| MSVC 6.0 | Not supported | This compiler is too weak in the area of template and namespace support. |\n| MSVC 7.0+ | Supported | This compiler is used by the PC and Win CE platforms |\n| Borland 5.5+ | Not supported | Borland can successfully compile many parts of EASTL, but not all parts. |\n| EDG | Supported | This is the compiler front end to some other compilers, such as Intel, and Comeau C++. |\n| IBM XL 5.0+ | Supported | This compiler is sometimes used by PowerPC platforms such as Mac OSX and possibly future console platforms. |\n\n### Info.6 Why is there EASTL when there is the STL?\n\nThe 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:\n\n* 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.\n* The STL is sometimes hard to debug, as most STL implementations use cryptic variable names and unusual data structures.\n* STL allocators are sometimes painful to work with, as they have many requirements and cannot be modified once bound to a container.\n* 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.\n* 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.\n* The STL doesn't support alignment of contained objects.\n* STL containers won't let you insert an entry into a container without supplying an entry to copy from. This can be inefficient.\n* 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.\n* 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.\n* 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.\n* The STL puts an emphasis on correctness before performance, whereas sometimes you can get significant performance gains by making things less academcially pure.\n* 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).\n* 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.\n* The STL is slow to compile, as most modern STL implementations are very large.\n* There are legal issues that make it hard for us to freely use portable STL implementations such as STLPort.\n* We have no say in the design and implementation of the STL and so are unable to change it to work for our needs.\n* 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.\n\n### Info.7 Can I mix EASTL with standard C++ STL?\n\nThis 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.\n\nThings that you definitely can do:\n\n* #include both EASTL and standard STL headers from the same .cpp file.\n* Use EASTL containers to hold STL containers.\n* Construct an STL reverse_iterator from an EASTL iterator.\n* Construct an EASTL reverse_iterator from an STL iterator.\n\nThings that you probably will be able to do, though a given std STL implementation may prevent it:\n\n* Use STL containers in EASTL algorithms.\n* Use EASTL containers in STL algorithms.\n* Construct or assign to an STL container via iterators into an EASTL container.\n* Construct or assign to an EASTL container via iterators into an STL container.\n*\nThings that you would be able to do if the given std STL implementation is bug-free:\n\n* 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.\n\nThings that you definitely can't do:\n\n* Use an STL allocator directly with an EASTL container (though you can use one indirectly).\n* Use an EASTL allocator directly with an STL container (though you can use one indirectly).\n\n### Info.8 Where can I learn more about STL and EASTL?\n\nEASTL 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.\n\nThat 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.\n\n* The SGI STL web site. Includes a good STL reference.\n* CodeProject STL introduction.\n* Scott Meyers Effective STL book.\n* The Microsoft online STL documentation. Microsoft links go bad every couple months, so try searching for STL at the * Microsoft MSDN site.\n* The Dinkumware online STL documentation.\n* 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\".\n* STL performance tips, by Pete Isensee\n* STL algorithms vs. hand-written loops, by Scott Meyers.\n\n### Info.9 What is the legal status of EASTL?\n\nEASTL is usable for all uses within Electronic Arts, both for internal usage and for shipping products for all platforms. All source code was written by a single EA engineer. 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.\n\n### Info.10 Does EASTL deal with compiler exception handling settings?\n\nEASTL 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.\n\n### Info.11 What C++ language features does EASTL use (e.g. virtual functions)?\n\nEASTL uses the following C++ language features:\n\n* Template functions, classes, member functions.\n* Multiple inheritance.\n* Namespaces.\n* Operator overloading.\n\nEASTL does not use the following C++ language features:\n\n* Virtual functions / interfaces.\n* RTTI (dynamic_cast).\n* Global and static variables. There are a couple class static const variables, but they act much like enums.\n* Volatile declarations\n* Template export.\n* Virtual inheritance.\n\nEASTL may use the following C++ language features:\n\n* Try/catch. This is an option that the user can enable and it defaults to whatever the compiler is set to use.\n* Floating point math. Hash containers have one floating point calculation, but otherwise floating point is not used.\n\nNotes:\n\n* 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.\n* EASTL never uses global new / delete / malloc / free. All allocations are done via user-specified allocators, though a default allocator definition is available.\n\n\n### Info.12 What compiler warning levels does EASTL support?\n\nFor 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.\n\nFor GCC, EASTL should compile without warnings with -Wall. Extensive testing beyond that hasn't been done.\n\nHowever, 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 addressible by modifying EASTL.\n\n### Info.13 Is EASTL compatible with Lint?\n\nAs 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 analysisnot 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.\n\n### Info.14 What compiler settings do I need to compile EASTL?\n\nEASTL 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.\n\nSee the Performance section of this FAQ for a discussion of the optimal compiler settings for EASTL performance.\n\n### Info.15 How hard is it to incorporate EASTL into my project?\n\nIt's probably trivial.\n\nEASTL 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 stict. 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.\n\nIn its default configuration, the only thing you need to provide to make EASTL work is to define implementations of the following operator new functions:\n\n```cpp\n#include \n\nvoid* operator new[](size_t size, const char* pName, int flags, unsigned debugFlags, const char* file, int line);\nvoid* operator new[](size_t size, size_t alignment, size_t alignmentOffset, const char* pName, int flags, unsigned debugFlags, const char* file, int line);\n```\nThe flags and debugFlags arguments correspond to PPMalloc/RenderWare GeneralAllocator/GeneralAllocatorDebug Malloc equivalents.\n\n### Info.16 Should I use EASTL instead of std STL or instead of my custom library?\n\nThere 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.\n\n**EASTL**\n* \\+ Has higher performance than any commercial STL, especially on console platforms.\n* \\+ Has extended functionality tailored for game development.\n* \\+ Is highly configurable, and we own it so it can be amended at will. Std STL is owned by a third party committee.\n* \\+ Is much easier to read and debug than other similar libraries, especiallly std STL.\n\n\n* \\- Is highly unit tested, but does not have the same level as std STL.\n* \\- Is more complicated than many users' lite template libraries, and may put off some beginners.\n* \\- EASTL \n\n**Std STL**\n\n* \\+ Is highly portable; your STL code will likely compile and run anywhere.\n* \\+ Works without the need to install or download any package to use it. It just works.\n* \\+ Is highly reliable and supported by the compiler vendor. You can have confidence in it.\n* \\+ Some std STL versions (e.g. STLPort, VC8 STL) have better runtime debug checking than EASTL.\n\n\n* \\- Has (sometimes greatly) variable implementations, behavior, and performance between implementations.\n* \\- Is usually hard to read and debug.\n* \\- Doesn't support some of the needs of game development, such as aligned allocations, named allocations, intrusive containers, etc.\n* \\- Is not as efficient as EASTL, especially on console platforms.\n\n**Your own library**\n(please forgive us for implying there may be weaknesses in your libraries)\n\n* \\+ You have control over it and can make it work however you want.\n* \\+ You can fix bugs in it on the spot and have the fix in your codebase immediately.\n* \\+ Your own library can be highly integrated into your application code or development environment.\n\n\n* \\- Many custom libraries don't have the same level of testing as libraries such as std STL or EASTL.\n* \\- Many custom libraries don't have the same breadth or depth as std STL or especially EASTL.\n* \\- Many custom libraries don't have the level of performance tuning that std STL or especially EASTL has.\n\n### Info.17 I think I've found a bug. What do I do?\n\n**Verify that you indeed have a bug**\n\nThere are various levels of bugs that can occur, which include the following:\n\n* Compiler warnings generated by EASTL.\n* Compiler errors generated by EASTL (failure to compile well-formed code).\n* Runtime misbehavior by EASTL (function does the wrong thing).\n* Runtime crash or data corruption by EASTL.\n* Mismatch between EASTL documentation and behavior.\n* Mismatch between EASTL behavior and user's expections (mis-design).\n\nAny 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.\n\n**Report the bug**\n\nThe first place to try is the standard EA centralized tech support site. As of this writing (10/2005), that tech site is http://eatech/. 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.\n\nIn 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.\n\n### Info.18 Can EASTL be used by third party EA developers?\n\nEASTL 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.\n\n## Performance\n\n### Perf.1 How efficient is EASTL compared to standard C++ STL implementations?\n\nWith 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 othe 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.\n\nThe 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.\n\nThe long answer requires a breakdown of the functionality between various versions of the STL.\n\n### Perf.2 How efficient is EASTL in general?\n\nThis 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.\n\nEASTL 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.\n\n### Perf.3 Strings don't appear to use the \"copy-on-write\" (CoW) optimization. Why not?\n\n**Short answer**\nCoW provides a benefit for a small percentage of uses but provides a disadvantage for the large majority of uses.\n\n**Long answer**\nThe primary benefit of CoW is that it allows for the sharing of string data between two string objects. Thus if you say this:\n\n```cpp\nstring a(\"hello\");\nstring b(a);\n```\n\nthe \"hello\" will be shared between a and b. If you then say this:\n\n```cpp\na = \"world\";\n```\n\nthen *a* 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.\n\nThe 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.\n\nThe disadvantages of CoW strings are:\n\n* A reference count needs to exist with the string, which increases string memory usage.\n* With thread safety, atomic operations and mutex locks are expensive, especially on weaker memory systems such as console gaming platforms.\n* 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.\n* 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.\n\nThe 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.\n\nReferences\n\nThis is a good starting HTML reference on the topic:\n http://www.gotw.ca/publications/optimizations.htm\n\nHere is a well-known Usenet discussion on the topic:\n http://groups-beta.google.com/group/comp.lang.c++.moderated/browse_thread/thread/3dc6af5198d0bf7/886c8642cb06e03d\n\n### Perf.4 Does EASTL cause code bloat, given that it uses templates?\n\nThe 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:\n\n```cpp\ntemplate \nconst T min(const T a, const T b)\n { return b < a ? b : a; }\n\nint i = min(3, 4);\ndouble d = min(3.0, 4.0);\n```\n\nthe compiler treats it as if you wrote this:\n\n```cpp\nint min(const int a, const int b)\n { return b < a ? b : a; }\n\ndouble min(const double a, const double b)\n { return b < a ? b : a; }\n```\n\nImagine this same effect happening with containers such as list and map and you can see how it is that templates can cause code proliferation.\n\nA 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.\n\nCode 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, vector, 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.\n\nThe 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 an 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.\n\nIt'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.\n\nAlso, 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.\n\nThere is a good Usenet discussion on this topic at: http://groups.google.com/group/comp.lang.c++.moderated/browse_frm/thread/2b00649a935997f5\n\n### Perf.5 Don't STL and EASTL containers fragment memory?\n\nThey 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:\n\n* 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.\n* 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.\n* 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.\n* 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.\n\n### Perf.6 I don't see container optimizations for equivalent scalar types such as pointer types. Why?\n\nMetrowerks (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.\n\nThe 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:\n\n```cpp\neastl::list intPtrList;\neastl::list toPtrList;\n\neastl_size_t n1 = intPtrList.size();\neastl_size_t n2 = toPtrList.size();\n\n0042D288 lea edx,[esp+14h]\n0042D28C call eastl::list::size (414180h)\n0042D291 push eax\n0042D292 lea edx,[esp+24h]\n0042D296 call eastl::list::size (414180h)\n```\n\nNote that in the above case the compiler folded the two implementations of size() into a single implementation.\n\n### Perf.7 I've seen some STL's provide a default quick \"node allocator\" as the default allocator. Why doesn't EASTL do this?\n\n**Short answer**\n\nThis is a bad, misguided idea.\n\n**Long answer**\n\nThese 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.\n\n### Perf.8 Templates sometimes seem to take a long time to compile. Why do I do about that?\n\nC++ 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.\n\nThe 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.\n\nSome 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.\n\n### Perf.10 How well does EASTL inline?\n\nEASTL 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:\n\n```cpp\nreference operator[](size_type n) {\n return *(begin() + n);\n}\n```\n\nEASTL implements the function directly, like so:\n\n```cpp\nreference operator[](size_type n) {\n return *(mpBegin + n);\n}\n```\n\nBoth implementations are correct, but hte 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.\n\nThat 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.\n\n### Perf.11 How do I control function inlining?\n\nInlining 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 inling 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 elsewhere 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.\n\nCompilation-Level Inlining -- VC++\n\nVC++ has some basic functionality to control inlining, and the compiler is pretty good at doing aggressive inlining when optimizing on for all platforms.\n\n> **#pragma inline_depth( [0... 255] )**\n>\n> 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.\n\n> **#pragma inline_recursion( [{on | off}] )**\n>\n> 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.\n\nCompilation-Level Inlining -- GCC\n\nGCC 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.\n\n\n> **-fno-default-inline**\n>\n> 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.\n>\n> **-fno-inline**\n>\n> 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.\n>\n> **-finline-functions**\n>\n> 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.\n>\n> **-finline-limit=n**\n>\n> 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++.\n>\n> 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:\n>\n> ```\n> max-inline-insns-single\n> is set to n/2.\n> max-inline-insns-auto\n> is set to n/2.\n> min-inline-insns\n> is set to 130 or n/4, whichever is smaller.\n> max-inline-insns-rtl\n> is set to n.\n> ```\n>\n> See --param below for a documentation of the individual parameters controlling inlining.\n>\n> **-fkeep-inline-functions**\n>\n> Emit all inline functions into the object file, even if they are inlined where used.\n>\n> **--param name=value**\n>\n> 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.\n>\n> max-inline-insns-single\n> 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.\n>\n> max-inline-insns-auto\n> 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.\n>\n>large-function-insns\n> 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.\n>\n> large-function-growth\n> 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.\n>\n> inline-unit-growth\n> 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.\n>\n> max-inline-insns-recursive\n> max-inline-insns-recursive-auto\n> 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.\n>\n> max-inline-recursive-depth\n> max-inline-recursive-depth-auto\n> 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.\n>\n> inline-call-cost\n> Specify cost of call instruction relative to simple arithmetics operations (having cost of 1). Increasing this cost disqualify inlinining 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 argumetns to other functions) and decrease inlining for code with low abstraction penalty. Default value is 16.\n>\n> **-finline-limit=n**\n>\n> 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++.\n\nInlining 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:\n\n```\nmax-inline-insns-single\n is set to n/2.\nmax-inline-insns-auto\n is set to n/2.\nmin-inline-insns\n is set to 130 or n/4, whichever is smaller.\nmax-inline-insns-rtl\n is set to n.\n```\n\nSee below for a documentation of the individual parameters controlling inlining.\n\nNote: 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.\n\nGCC additionally has the -Winline compiler warning, which emits a warning whenever a function declared as inline was not inlined.\n\nCompilation-Level Inlining -- Metrowerks\n\nMetrowerks 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.\n\n> ```\n> #pragma always_inline on | off | reset\n> ```\n>\n> 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.\n>\n> ```\n> #pragma inline_depth(n)\n> #pragma inline_depth(smart)\n> ```\n>\n> 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.\n>\n> ```\n> #pragma inline_max_size(n);\n> #pragma inline_max_total_size(n);\n> ```\n>\n> 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 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.\n\nFunction-Level Inlining -- VC++\n\n> To force inline usage under VC++, you use this:\n>\n> ```\n> __forceinline void foo(){ ... }\n> ```\n>\n> 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.\n>\n> To disable inline usage under VC++, you need to use this:\n>\n> ```\n> #pragma inline_depth(0) // Disable inlining.\n> void foo() { ... }\n> #pragma inline_depth() // Restore default.\n> ```\n>\n> The above is essentially specifying compiler-level inlining control within the code for a specific function.\n\n**Function-Level Inlining -- GCC / Metrowerks**\n\n> To force inline usage under GCC 3.1+, you use this:\n>\n> `inline void foo() __attribute__((always_inline)) { ... }`\n>\n> or\n>\n> `inline __attribute__((always_inline)) void foo() { ... }`\n>\n> To disable inline usage under GCC 3+, you use this:\n>\n> `void foo() __attribute__((noinline)) { ... }`\n>\n> or\n>\n> `inline __attribute__((noinline)) void foo() { ... }`\n\nEABase has some wrappers for this, such as EA_FORCE_INLINE.\n\n### Perf.12 C++ / EASTL seems to bloat my .obj files much more than C does.\n\nThere 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.\n\nAdditionally, the debug information for template definitions is usually larger than that for non-templated C++ definitions, which itself is sometimes larger than C defintions due to name decoration.\n\n### Perf.13 What are the best compiler settings for EASTL?\n\nWe 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 sucessfully compiled and tested (the EASTL unit test) on our major development platforms with the highest optimization settings enabled, including GCC's infamous -O3 level.\n\n**Optimization Topics**\n\n* Function inlining.\n* Optimization for speed vs. optimization for size.\n* Link-time code generation (LTCG).\n* Profile-guided optimization (PGO).\n\n**Function inlining**\n\nEASTL 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):\n| Inlining Disabled | Inline only 'inline' | Inline any |\n|------|------|------|------|\n| **Application size** | 100K | 86K | 86K |\n| **Execution time** | 100 | 75 | 75 |\n\nThe 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.\n\n**Optimization for Speed / Size**\n\nOptimization 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):\n| Size | Speed | Speed + LTCG | Speed + LTCG + PGO |\n|------|------|------|------|\n| **Application size** | 80K | 100K | 98K | 98K |\n| **Execution time** | 100 | 90 | 83 | 75 |\n\nWhat 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.\n\n**Link-time code generation (LTCG)**\n\nLTCG 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.\n\n**Profile-guided optimization (PGO)**\n\nPGO 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.\n\n## Problems\n\n### Prob.1 I'm getting screwy behavior in sorting algorithms or sorted containers. What's wrong?\n\nIt 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.\n\nThe 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.\n\n```cpp\nclass SortByDistance : public binary_function\n{\nprivate:\n Vector3 mOrigin;\n\npublic:\n SortByDistance(Vector3 origin) {\n mOrigin = origin;\n }\n\n bool operator()(WorldTreeObject* pA, WorldTreeObject* pB) const {\n return ((WorldObject*)pA)->mPos - mOrigin).GetLength()\n < ((WorldObject*)pB)->mPos - mOrigin).GetLength();\n }\n};\n```\n\nAnother thing to watch out for is the following mistake:\n\n```cpp\nstruct ValuePair\n{\n uint32_t a;\n uint32_t b;\n};\n\n// Improve speed by casting the struct to uint64_t\nbool operator<(const ValuePair& vp1, const ValuePair& vp2)\n { return *(uint64_t*)&vp1 < *(uint64_t*)&vp2; }\n```\n\nThe 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.\n\n### Prob.2 I am getting compiler warnings (e.g. C4244, C4242 or C4267) that make no sense. Why?\n\nOne 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\n\n``` cpp\ntemplate \nT min(const T a, const T b) {\n return b < a ? b : a;\n}\n```\n\nIf you compile this code:\n\n```cpp\nptrdiff_t a = min(ptrdiff_t(0), ptrdiff_t(1));\nint b = min((int)0, (int)1);\n```\n\nYou will get the following warning for the second line, which is somewhat nonsensical:\n\n`warning C4244: 'initializing' : conversion from 'const ptrdiff_t' to 'int', possible loss of data`\n\nThis could probably be considered a VC++ bug, but in the meantime you have little choice but to ignore the warning or disable it.\n\n### Prob.3 I am getting compiler warning C4530, which complains about exception handling and \"unwind semantics.\" What gives?\n\nVC++ 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%.\n\nIf you have stack unwinding disabled, but you have try/catch statements, VC++ will generate the following warning:\n\n`warning C4530: C++ exception handler used, but unwind semantics are not enabled. Specify /EHsc`\n\nAs 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.\n\n### Prob.4 Why are tree-based EASTL containers hard to read with a debugger?\n\n**Short answer**\n\nMaximum performance and design mandates.\n\n**Long answer**\n\nYou 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.\n\nAdditionally, 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.\n\nCurrently 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.\n\nSee [Debug.2](#debug2-how-do-i-view-containers-if-the-visualizertooltip-support-is-not-present) for more.\n\n### Prob.5 The EASTL source code is sometimes rather complicated looking. Why is that?\n\n**Short answer**\n\nMaximum performance.\n\n**Long answer**\nEASTL 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.\n\nAs an example of this, take a look at the implementation of the copy 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.\n\nEASTL'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.\n\n### Prob.6 When I get compilation errors, they are very long and complicated looking. What do I do?\n\nAssuming 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\n\nTop five approaches to dealing with long compilation errors:\n\n1. 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.\n2. 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.\n3. 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\n4. 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/.\n5. 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/).\n\nTop five causes of EASTL compilation errors:\n\n1. const-correctness. Perhaps a quarter of container template errors are due to the user not specifying const correctly.\n2. 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.\n3. 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.\n4. 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.\n5. Incorrect template parameters. When declaring a template instantiation (e.g. map >) you simply need to get the template parameters correct. Also note that when you have \">>\" next to each other that you need to separate them by one space (e.g. \"> >\").\n\n### Prob.7 Templates sometimes seem to take a long time to compile. Why do I do about that?\n\nC++ 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.\n\nThe 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.\n\nSome 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.\n\n### Prob.8 I get the compiler error: \"template instantiation depth exceeds maximum of 17. use -ftemplate-depth-NN to increase the maximum\".\n\nThis 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.\n\nThe 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.\n\nFrom the GCC documentation:\n\n```\n-ftemplate-depth-n\n\nSet the maximum instantiation depth for template classes to n.\nA limit on the template instantiation depth is needed to detect\nendless recursions during template class instantiation ANSI/ISO\nC++ conforming programs must not rely on a maximum depth greater than 17.\nNote that starting with GCC 4.5 the syntax is -ftemplate-depth=N instead of -ftemplate-depth-n.\n```\n\n### Prob.9 I'm getting errors about min and max while compiling.\n\nYou 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 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.\n\n### Prob.10 C++ / EASTL seems to bloat my .obj files much more than C does.\n\nThere 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.\n\n### Prob.11 I'm getting compiler errors regarding placement operator new being previously defined.\n\nThis 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:\n\n> Placement forms\n> 1. These functions are reserved, a C++ program may not define functions that displace the versions in the Standard C++ library.\n\nYou may find that #defining __PLACEMENT_NEW_INLINE 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.\n\n### Prob.12 I'm getting errors related to wchar_t string functions such as wcslen().\n\nEASTL 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.\n\n* The #define EA_WCHAR_SIZE is equal to sizeof(wchar_t).\n* If sizeof(wchar_t) == 2, then char16_t is typedef'd to wchar_t.\n* If sizeof(wchar_t) == 4, then char32_t is typedef'd to wchar_t.\n\nEABase 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.\n\n### Prob.13 I'm getting compiler warning C4619: there is no warning number Cxxxx (e.g. C4217).\n\nCompiler 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.\n\nThe 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.\n\n### Prob.14 My stack-based fixed_vector is not respecting the object alignment requirements.\n\nEASTL 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 http://msdn2.microsoft.com/en-us/library/83ythb65(VS.71).aspx, this doesn't work for stack variables. The two primary means of working around this are:\n\n* Use something like AlignedObject<> from the EAStdC package's EAAllocator.h file.\n* 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.\n\n### Prob.15 I am getting compiler errors when using GCC under XCode (Macintosh/iphone).\n\nThe 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 is used by the compiler when you say #include . 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.\n\n### Prob.16 I am getting linker errors about Vsnprintf8 or Vsnprintf16.\n\nEASTL 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.\n\nExample of providing Vsnprintf8 via EAStdC:\n\n```cpp\n#include \n\nint Vsnprintf8(char8_t* pDestination, size_t n, const char8_t* pFormat, va_list arguments)\n{\n return EA::StdC::Vsnprintf(pDestination, n, pFormat, arguments);\n}\n\nint Vsnprintf16(char16_t* pDestination, size_t n, const char16_t* pFormat, va_list arguments)\n{\n return EA::StdC::Vsnprintf(pDestination, n, pFormat, arguments);\n}\n```\n\nExample of providing Vsnprintf8 via C libraries:\n\n```cpp\n#include \n\nint Vsnprintf8(char8_t* p, size_t n, const char8_t* pFormat, va_list arguments)\n{\n #ifdef _MSC_VER\n return vsnprintf_s(p, n, _TRUNCATE, pFormat, arguments);\n #else\n return vsnprintf(p, n, pFormat, arguments);\n #endif\n}\n\nint Vsnprintf16(char16_t* p, size_t n, const char16_t* pFormat, va_list arguments)\n{\n #ifdef _MSC_VER\n return vsnwprintf_s(p, n, _TRUNCATE, pFormat, arguments);\n #else\n return vsnwprintf(p, n, pFormat, arguments); // Won't work on Unix because its libraries implement wchar_t as int32_t.\n #endif\n}\n```\n\n### Prob.17 I am getting compiler errors about UINT64_C or UINT32_C.\n\nThis is usually an order-of-include problem that comes about due to the implementation of __STDC_CONSTANT_MACROS in C++ Standard libraries. The C++ 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.\n\nThe real solution that the C++ compiler and standard library wants is for the app to globally define __STDC_CONSTANT_MACROS itself in the build.\n\n### Prob.18 I am getting a crash with a global EASTL container.\n\nThis 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:\n\nFailing code:\n\n```cpp\neastl::list gIntList; // Global variable.\n\nvoid DoSomething()\n{\n gIntList.push_back(1); // Crash. gIntList was never constructed.\n}\n```\n\nDeclaring a pointer solution:\n\n```cpp\neastl::list* gIntList = NULL;\n\nvoid DoSomething()\n{\n if(!gIntList) // Or move this to an init function.\n gIntList = new eastl::list;\n\n gIntList->push_back(1); // Success\n}\n```\n\nManual constructor call solution:\n\n```cpp\neastl::list gIntList;\n\nvoid InitSystem()\n{\n new(&gIntList) eastl::list;\n}\n\nvoid DoSomething()\n{\n gIntList.push_back(1); // Success\n}\n```\n\n### Prob.19 Why doesn't EASTL support passing NULL string functions?\n\nThe 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:\n\n> It breaks consistency with the C++ STL library and C libraries, which require strings to be valid.\n>\n> It makes the coder slower and bigger for all users, though few need NULL checks.\nThe 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.\n>\n> 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).\nHow 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.\n>\n> It's arguable (and in fact the 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.\n\n## Debug\n\n### Debug.1 How do I set the VC++ debugger to display EASTL container data with tooltips?\n\nSee [Cont.9](#cont9-how-do-i-set-the-vc-debugger-to-display-eastl-container-data-with-tooltips)\n\n### Debug.2 How do I view containers if the visualizer/tooltip support is not present?\n\nHere is a table of answers about how to manually inspect containers in the debugger.\n\n| Container | Approach |\n|------|------|\n| slist
fixed_slist | slist is a singly-linked list. Look at the slist mNode variable. You can walk the list by looking at mNode.mpNext, etc. |\n| list
fixed_list | 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. |\n| intrusive_list
intrusive_slist† | Look at the list mAnchor node. This lets you walk forward and backward in the list via mpNext and mpPrev. |\n| array | View the array mValue member in the debugger. It's simply a C style array. |\n| vector
fixed_vector | 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 |\n| vector_set
vector_multiset
vector_map
vector_multimap | 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. |\n| deque | 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. |\n| bitvector | Look at the bitvector mContainer variable. If it's a vector, then see vector above. |\n| bitset | Look at the bitset mWord variable. The bitset is nothing but one or more uint32_t mWord items. |\n| set
multiset
fixed_set
fixed_multiset | 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()). |\n| map
multimap
fixed_map
fixed_multimap | 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()). |\n| hash_map
hash_multimap
fixed_hash_map
fixed_hash_multimap | 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. |\n| intrusive_hash_map
intrusive_hash_multimap
intrusive_hash_set
intrusive_hash_multiset | intrusive hash tables in EASTL are implemented very similarly to regular hash tables. See the hash_map and hash_set entries for more info. |\n| hash_set
hash_multiset
fixed_hash_set
fixed_hash_map | hash tables in EASTL are implemented as an array of singly-linked lists. The array is the mpBucketArray member. |\n| basic_string
fixed_string
fixed_substring | 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 |\n| heap | 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. |\n| stack | View the stack member c value in the debugger. That member will typically be a list or deque. |\n| queue | View the queue member c value in the debugger. That member will typically be a list or deque. |\n| priority_queue | 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. |\n| smart_ptr | View the mpValue member. |\n\n### Debug.3 The EASTL source code is sometimes rather complicated looking. Why is that?\n\n**Short answer**\n\nMaximum performance.\n\n**Long answer**\n\nEASTL 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.\n\nAs an example of this, take a look at the implementation of the copy 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.\n\nEASTL'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.\n\n### Debug.4 When I get compilation errors, they are very long and complicated looking. What do I do?\n\nAssuming 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\n\nTop five approaches to dealing with long compilation errors:\n\n1.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.\n2. 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.\n3. 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\n4. 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/.\n5. 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/).\n\nTop five causes of EASTL compilation errors:\n\n1. const-correctness. Perhaps a quarter of container template errors are due to the user not specifying const correctly.\n2. 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.\n3. 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.\n4. 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.\n5. Incorrect template parameters. When declaring a template instantiation (e.g. map >) you simply need to get the template parameters correct. Also note that when you have \">>\" next to each other that you need to separate them by one space (e.g. \"> >\").\n\n### Debug.5 How do I measure hash table balancing?\n\nThe following functionality lets you spelunk hash container layout.\n\n* There is the load_factor function which tells you the overall hashtable load, but doesn't tell you if a load is unevenly distributed.\n* You can control the load factor and thus the automated bucket redistribution with set_load_factor.\n* 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.\n* You can use the above to get the size of any bucket, but there is also simply the bucket_size(size_type n) function.\n* The bucket_count function tells you the count of buckets. So with this you can completely visualize the layout of the hash table.\n* There is also iterator find_by_hash(hash_code_t c), for what it's worth.\n\nThe following function draws an ASCII bar graph of the hash table for easy visualization of bucket distribution:\n\n```cpp\n#include \n#include \n#include \n\ntemplate \nvoid VisualizeHashTableBuckets(const HashTable& h)\n{\n eastl_size_t bucketCount = h.bucket_count();\n eastl_size_t largestBucketSize = 0;\n\n for(eastl_size_t i = 0; i < bucketCount; i++)\n largestBucketSize = eastl::max_alt(largestBucketSize, h.bucket_size(i));\n\n YourPrintFunction(\"\\n --------------------------------------------------------------------------------\\n\");\n\n for(eastl_size_t i = 0; i < bucketCount; i++)\n {\n const eastl_size_t k = h.bucket_size(i) * 80 / largestBucketSize;\n\n char buffer[16];\n sprintf(buffer, \"%3u|\", (unsigned)i);\n YourPrintFunction(buffer);\n\n for(eastl_size_t j = 0; j < k; j++)\n YourPrintFunction(\"*\");\n\n YourPrintFunction(\"\\n\");\n }\n\n YourPrintFunction(\" --------------------------------------------------------------------------------\\n\");\n}\n```\n\nThis 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.\n\n```\n ------------------------------------------------------\n 0|********************************************\n 1|************************************************\n 2|***************************************\n 3|********************************************\n 4|*****************************************************\n 5|*************************************************\n 6|****************************************\n 7|***********************************************\n 8|********************************************\n 9|**************************************\n10|********************************************\n -----------------------------------------------------\n```\n\n## Containers\n\n### Cont.1 Why do some containers have \"fixed\" versions (e.g. fixed_list) but others(e.g. deque) don't have fixed versions?\n\nRecall 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.\n\nThe 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:\n\n```\narray, deque, bitset, stack, queue, priority_queue,\nintrusive_list, intrusive_hash_map, intrusive_hash_set,\nintrusive_hash_multimap, intrusive_hash_multimap,\nvector_map, vector_multimap, vector_set, vector_multiset.\n```\n\nSome 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.\n\n### Cont.2 Can I mix EASTL with standard C++ STL?\n\nThis 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.\n\nThings that you definitely can do:\n\n* #include both EASTL and standard STL headers from the same .cpp file.\n* Use EASTL containers to hold STL containers.\n* Construct an STL reverse_iterator from an EASTL iterator.\n* Construct an EASTL reverse_iterator from an STL iterator.\n\nThings that you probably will be able to do, though a given std STL implementation may prevent it:\n\n* Use STL containers in EASTL algorithms.\n* Use EASTL containers in STL algorithms.\n* Construct or assign to an STL container via iterators into an EASTL container.\n* Construct or assign to an EASTL container via iterators into an STL container.\n\nThings that you would be able to do if the given std STL implementation is bug-free:\n\n* 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.\n\nThings that you definitely can't do:\n\n* Use an STL allocator directly with an EASTL container (though you can use one indirectly).\n* Use an EASTL allocator directly with an STL container (though you can use one indirectly).\n\n### Cont.3 Why are there so many containers?\n\nEASTL 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.\n\n### Cont.4 Don't STL and EASTL containers fragment memory?\n\nThey 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:\n\nFor 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.\nEASTL 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.\nYou 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.\nWhere 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.\n\n### Cont.5 I don't see container optimizations for equivalent scalar types such as pointer types. Why?\n\nMetrowerks (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.\n\nThe 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:\n\n```cpp\neastl::list intPtrList;\neastl::list toPtrList;\n\neastl_size_t n1 = intPtrList.size();\neastl_size_t n2 = toPtrList.size();\n\n0042D288 lea edx,[esp+14h]\n0042D28C call eastl::list::size (414180h)\n0042D291 push eax\n0042D292 lea edx,[esp+24h]\n0042D296 call eastl::list::size (414180h)\n```\n\nNote that in the above case the compiler folded the two implementations of size() into a single implementation.\n\n### Cont.6 What about alternative container and algorithm implementations (e.g. treaps, skip lists, avl trees)?\n\nEASTL 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:\n\nImplemented:\n\n* intrusive_list, etc. -- Saves memory and improves cache locality.\n* vector_map, etc. -- Saves memory and improves cache locality.\n* ring_buffer -- Useful for some types of operations and has no alternative.\n* shell_sort -- Useful sorting algorithm.\n* sparse_matrix -- Useful for some types of operations and has no alternative.\n\nNot implemented:\n\n* skip lists (alternative to red-black tree) -- These use more memory and usually perform worse than rbtrees.\n* treap (alternative to red-black tree) -- These are easier and smaller than rbtrees, but perform worse.\n* avl tree (alternative to red-black tree) -- These have slightly better search performance than rbtrees, but significantly worse * * insert/remove performance.\n* btree (alternative to red-black tree) -- These are no better than rbtrees.\n\nIf you have an idea of something that should be implemented, please suggest it or even provide at least a prototypical implementation.\n\n### Cont.7 Why are tree-based EASTL containers hard to read with a debugger?\n\n**Short answer**\n\nMaximum performance and design mandates.\n\n**Long answer**\n\nYou 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.\n\nAdditionally, 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.\n\nCurrently 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.\n\n### Cont.8 How do I assign a custom allocator to an EASTL container?\n\nThere are two ways of doing this:\n\n1. Use the set_allocator function that is present in each container.\n2. Specify a new allocator type via the Allocator template parameter that is present in each container.\n\nFor 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.\n\nFor 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.\n\n```cpp\nclass custom_allocator\n{\npublic:\n custom_allocator(const char* pName = EASTL_NAME_VAL(\"custom allocator\"))\n {\n #if EASTL_NAME_ENABLED\n mpName = pName ? pName : EASTL_ALLOCATOR_DEFAULT_NAME;\n #endif\n\n // Possibly do something here.\n }\n\n custom_allocator(const allocator& x, const char* pName = EASTL_NAME_VAL(\"custom allocator\"));\n {\n #if EASTL_NAME_ENABLED\n mpName = pName ? pName : EASTL_ALLOCATOR_DEFAULT_NAME;\n #endif\n\n // Possibly copy from x here.\n }\n\n ~custom_allocator();\n {\n // Possibly do something here.\n }\n\n custom_allocator& operator=(const custom_allocator& x)\n {\n // Possibly copy from x here.\n return *this;\n }\n\n void* allocate(size_t n, int flags = 0)\n {\n // Implement the allocation here.\n }\n\n void* allocate(size_t n, size_t alignment, size_t offset, int flags = 0)\n {\n // Implement the allocation here.\n }\n\n void deallocate(void* p, size_t n)\n {\n // Implement the deallocation here.\n }\n\n const char* get_name() const\n {\n #if EASTL_NAME_ENABLED\n return mpName;\n #else\n return \"custom allocator\";\n #endif\n }\n\n void set_name(const char* pName)\n {\n #if EASTL_NAME_ENABLED\n mpName = pName;\n #endif\n }\n\nprotected:\n // Possibly place instance data here.\n\n #if EASTL_NAME_ENABLED\n const char* mpName; // Debug name, used to track memory.\n #endif\n};\n\n\ninline bool operator==(const allocator& a, const allocator& b)\n{\n // Provide a comparison here.\n}\n\ninline bool operator!=(const allocator& a, const allocator& b)\n{\n // Provide a negative comparison here.\n}\n```\n\nHere's an example of how to use the above custom allocator:\n\n```cpp\n// Declare a Widget list and have it default construct.\nlist widgetList;\n\n// Declare a Widget list and have it construct with a copy of some global allocator.\nlist widgetList2(gSomeGlobalAllocator);\n\n// Declare a Widget list and have it default construct, but assign\n// an underlying implementation after construction.\nlist widgetList;\nwidgetList.get_allocator().mpIAllocator = new WidgetAllocatorImpl;\n```\n\n### Cont.9 How do I set the VC++ debugger to display EASTL container data with tooltips?\n\nVisual Studio supports this via the AutoExp.dat file, an example of which is [present](./html/AutoExp.dat) with this documentation.\n\nSometimes the AutoExp.dat doesn't seem to work. Avery Lee's explanation:\n\n> 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.\n\n### Cont.10 How do I use a memory pool with a container?\n\nUsing 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:\n\n* Assign a custom allocator to a container. eastl::fixed_pool provides an implementation.\n* Use one of the EASTL fixed containers, such as fixed_list.\n\n**Custom Allocator**\n\nIn 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):\n\n```cpp\ntypedef list WidgetList; // Declare your WidgetList type.\n\nMemoryPool myPool(sizeof(WidgetList::node_type), 100); // Make a pool of 100 Widget nodes.\nWidgetList myList(&myPool); // Create a list that uses the pool.\n```\n\nIn 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 what 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.\n\nIn 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).\n\nYou 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:\n\n```cpp\nchar buffer[256];\n\nlist myList;\nmyList.get_allocator().init(buffer, 256);\nFixed Container\nIn 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:\n\nfixed_list fixedList; // Declare a fixed_list that can hold 100 Widgets\n```\n\n### Cont.11 How do I write a comparison (operator<()) for a struct that contains two or more members?\n\nSee [Algo.2](#algo2-how-do-i-write-a-comparison-operator-for-a-struct-that-contains-two-or-more-members).\n\n### Cont.12 Why doesn't container X have member function Y?\n\nWhy 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.\n\nThe answer usually boils down to two reasons:\n\n* The functionality exists in a more centralized location elsewhere, such as the algorithms.\n* The functionality can be had by using other member functions.\n\nIn the case of find and sort functions not being part of containers, the find algorithm and sort algorithm are centralized versions that apply to any 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:\n\n`list::iterator i = find(list.begin(), list.end(), 3);`\n\nAnd in order to sort a vector, you would do this:\n\n```cpp\nquick_sort(v.begin(), v.end()); // Sort the entire array.\n\nquick_sort(&v[3], &v[8]); // Sort the items at the indexes in the range of [3, 8).\n```\n\nIn 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:\n\n`string strMid(str, 3, 5); // Make a new string of the characters from the source range of [3, 3+5).`\n\nIt 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.\n\n### Cont.13 How do I search a map of strings via a char pointer efficiently? If I use map.find(\"hello\") it creates a temporary string, which is inefficient.\n\nThe problem is illustrated with this example:\n\n```cpp\nmap swMap;\n ...\nauto it = swMap.find(\"blue\"); // A temporary string object is created here, which allocates.\n```\n\nIn this example, the find function expects a string object and not a string literal and so the compiler uses the string conversion operator to (silently!) construct a temporary string object. There are several solutions to this problem:\n\n* 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.\n* Declare the map type with a [transparent comparison type](https://en.cppreference.com/w/cpp/utility/functional#Transparent_function_objects) (eg. [`less`](https://en.cppreference.com/w/cpp/utility/functional/less_void)). The above example becomes:\n```cpp\nmap> swMap;\n ...\nauto it = swMap.find(\"blue\"); // No string object created. Uses heterogeneous lookup, which calls less::operator()(const char*).\n```\nThis is advantageous over `find_as` because eastl containers support this optimization for additional member functions that take a `key_type` parameter, ie. heterogeneous lookup, insertion and erasure.\n* Use the EASTL `find_as` function, which allows you to find an item in a container via an alternative key than the one the container uses. Using a [transparent comparison type](https://en.cppreference.com/w/cpp/utility/functional#Transparent_function_objects) with the container is safer than using `find_as` because the latter requires the user specify a comparison object which must have the same semantics as the container's comparison object, otherwise the behaviour is undefined.\n\n### Cont.14 Why are set and hash_set iterators const (i.e. const_iterator)?\n\nThe situation is illustrated with this example:\n\n```cpp\nset intSet;\n\nintSet.insert(1);\nset::iterator i = intSet.begin();\n*i = 2; // Error: iterator i is const.\n```\n\nIn 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.\n\n### Cont.15 How do I prevent my hash container from re-hashing?\n\nIf 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.\n\nSimilarly, 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:\n\n```cpp\nhash_set hashSet;\nhashSet.rehash_policy().mfGrowthFactor = 1.5f\n```\n\n### Cont.16 Which uses less memory, a map or a hash_map?\n\nA 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.\n\n### Cont.17 How do I write a custom hash function?\n\nYou can look at the existing hash functions in functional.h, but we provide a couple examples here.\n\nTo write a specific hash function for a Widget class, you would do this:\n\n```cpp\nstruct WidgetHash {\n size_t operator()(const Widget& w) const\n { return w.id; }\n};\n\nhash_set widgetHashSet;\n```\n\nTo write a generic (templated) hash function for a set of similar classes (in this case that have an id member), you would do this:\n\n```cpp\ntemplate \nstruct GeneralHash {\n size_t operator()(const T& t) const\n { return t.id; }\n};\n\nhash_set > widgetHashSet;\nhash_set > doggetHashSet;\n```\n\n### Cont.18 How do I write a custom compare function for a map or set?\n\nThe 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:\n\n```cpp\nstruct WidgetLess {\n bool operator()(const Widget& w1, const Widget& w2) const\n { return w.id < w2.id; }\n};\n\nset wSet;\n```\n\nIt'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.\"\n\n### Cont.19 How do I force my vector or string capacity down to the size of the container?\n\nYou 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.\n\n```cpp\neastl::vector x;\nx.set_capacity(); // Shrink x's capacity to be equal to its size.\n\neastl::vector x;\nx.set_capacity(0); // Completely clear x.\n```\n\nTo compact your vector or string in a way that would also work with std STL you need to do the following.\n\nHow to shrink a vector's capacity to be equal to its size:\n\n```cpp\nstd::vector x;\nstd::vector(x).swap(x); // Shrink x's capacity.\n```\n\nHow to completely clear a std::vector (size = 0, capacity = 0, no allocation):\n\n```cpp\nstd::vector x;\nstd::vector().swap(x); // Completely clear x.\n```\n\n### Cont.20 How do I iterate a container while (selectively) removing items from it?\n\nAll 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:\n\n```cpp\nset intSet;\n\nset::iterator i = intSet.begin();\n\nwhile(i != intSet.end())\n{\n if(*i & 1) // Erase all odd integers from the container.\n i = intSet.erase(i);\n else\n ++i;\n}\n```\n\n### Cont.21 How do I store a pointer in a container?\n\nThe 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:\n\nManually free pointers when removing them from containers.\nStore the pointer as a smart pointer instead of a \"raw\"pointer.\nThe 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.\n\nThe 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.\n\nIt'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:\n\n```cpp\nlist< shared_ptr > wList;\n\nwList.push_back(shared_ptr(new Widget));\nwList.pop_back(); // The Widget will be freed.\n```\n\n### Cont.22 How do I make a union of two containers? difference? intersection?\n\nThe 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.\n\n### Cont.23 How do I override the default global allocator?\n\nThere 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:\n\n* Simply provide the following versions of operator new (which EASTL requires, actually):\n```cpp\nvoid* operator new[](size_t size, const char* pName, int flags, unsigned debugFlags, const char* file, int line);\nvoid* operator new[](size_t size, size_t alignment, size_t alignmentOffset, const char* pName, int flags, unsigned debugFlags, const char* file, int line);\n```\n* Predefine the config.h macros for EASTLAlloc, EASTLFree, etc. See config.h for this.\n* Override config.h entirely via EASTL_USER_CONFIG_HEADER. See config.h for this.\n* Provide your own version of allocator.h/cpp\n* Provide your own version of config.h.\n\nIf you redefine the allocator class, you can make it work however you want.\n\nNote 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.\n\n### Cont.24 How do I do trick X with the string container?\n\nThere 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.\n\n**find_and_replace**\n\n```cpp\ntemplate \nvoid find_and_replace(String& s, const typename String::value_type* pFind, const typename String::value_type* pReplace) \n{\n for(size_t i; (i = source.find(pFind)) != T::npos; )\n s.replace(i, eastl::CharStrlen(pFind), pReplace);\n}\n\nExample:\n find_and_replace(s, \"hello\", \"hola\");\n```\n\n**trim front (multiple chars)**\n\n```cpp\ntemplate \nvoid trim_front(String& s, const typename String::value_type* pValues)\n{\n s.erase(0, s.find_first_not_of(pValues));\n}\n\nExample:\n trim_front(s, \" \\t\\n\\r\");\n```\n\n**trim back (multiple chars)**\n\n```cpp\ntemplate \nvoid trim_front(String& s, const typename String::value_type* pValues)\n{\n s.resize(s.find_last_not_of(pValues) + 1);\n}\n\nExample:\n trim_back(s, \" \\t\\n\\r\");\n```\n\n**prepend**\n\n```cpp\ntemplate \nvoid prepend(String& s, const typename String::value_type* p)\n{\n s.insert(0, p);\n}\n\nExample:\n prepend(s, \"log: \");\n```\n\n**begins_with**\n\n```cpp\ntemplate \nbool begins_with(const String& s, const typename String::value_type* p)\n{\n return s.compare(0, eastl::CharStrlen(p), p) == 0;\n}\n\nExample:\n if(begins_with(s, \"log: \")) ...\n```\n\n**ends_with**\n\n```cpp\ntemplate \nbool ends_with(const String& s, const typename String::value_type* p)\n{\n const typename String::size_type n1 = s.size();\n const typename String::size_type n2 = eastl::CharStrlen(p);\n return ((n1 >= n2) && s.compare(n1 - n2, n2, p) == 0);\n}\n\nExample:\n if(ends_with(s, \"test.\")) ...\n```\n\n**tokenize**\n\nHere is a simple tokenization function that acts very much like the C strtok function.\n\n```cpp\ntemplate \nsize_t tokenize(const String& s, const typename String::value_type* pDelimiters,\n String* resultArray, size_t resultArraySize)\n{\n size_t n = 0;\n typename String::size_type lastPos = s.find_first_not_of(pDelimiters, 0);\n typename String::size_type pos = s.find_first_of(pDelimiters, lastPos);\n\n while((n < resultArraySize) && (pos != String::npos) || (lastPos != String::npos))\n {\n resultArray[n++].assign(s, lastPos, pos - lastPos);\n lastPos = s.find_first_not_of(pDelimiters, pos);\n pos = s.find_first_of(pDelimiters, lastPos);\n }\n\n return n;\n}\n\nExample:\n string resultArray[32];\ntokenize(s, \" \\t\", resultArray, 32));\n```\n\n### Cont.25 How do EASTL smart pointers compare to Boost smart pointers?\n\nEASTL'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:\n\n* 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.\n* 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 and assign to is something like \"new Widget\". The problem is that shared_ptr 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.\n\nThere 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.\n\n### Cont.26 How do your forward-declare an EASTL container?\n\nHere is are some examples of how to do this:\n\n```cpp\nnamespace eastl\n{\n template class basic_string;\n typedef basic_string string8; // Forward declare EASTL's string8 type.\n\n template class vector;\n typedef vector CharArray;\n\n template class hash_set;\n\n template class map;\n}\n```\n\nThe 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.\n\n### Cont.27 How do I make two containers share a memory pool?\n\nEASTL (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.\n\nHere is some example code:\n\n```cpp\nstruct fixed_pool_reference\n{\npublic:\n fixed_pool_reference()\n {\n mpFixedPool = NULL;\n }\n\n fixed_pool_reference(eastl::fixed_pool& fixedPool)\n {\n mpFixedPool = &fixedPool;\n }\n\n fixed_pool_reference(const fixed_pool_reference& x)\n {\n mpFixedPool = x.mpFixedPool;\n }\n\n fixed_pool_reference& operator=(const fixed_pool_reference& x)\n {\n mpFixedPool = x.mpFixedPool;\n return *this;\n }\n\n void* allocate(size_t /*n*/, int /*flags*/ = 0)\n {\n return mpFixedPool->allocate();\n }\n\n void* allocate(size_t /*n*/, size_t /*alignment*/, size_t /*offset*/, int /*flags*/ = 0)\n {\n return mpFixedPool->allocate();\n }\n\n void deallocate(void* p, size_t /*n*/)\n {\n return mpFixedPool->deallocate(p);\n }\n\n const char* get_name() const\n {\n return \"fixed_pool_reference\";\n }\n\n void set_name(const char* /*pName*/)\n {\n }\n\nprotected:\n friend bool operator==(const fixed_pool_reference& a, const fixed_pool_reference& b);\n friend bool operator!=(const fixed_pool_reference& a, const fixed_pool_reference& b);\n\n eastl::fixed_pool* mpFixedPool;\n};\n\ninline bool operator==(const fixed_pool_reference& a, const fixed_pool_reference& b)\n{\n return (a.mpFixedPool == b.mpFixedPool);\n}\n\ninline bool operator!=(const fixed_pool_reference& a, const fixed_pool_reference& b)\n{\n return (a.mpFixedPool != b.mpFixedPool);\n}\n```\n\nExample usage of the above:\n\n```cpp\ntypedef eastl::list IntList;\n\nIntList::node_type buffer[2];\neastl::fixed_pool myPool(buffer, sizeof(buffer), sizeof(Int::node_type), 2);\n\nIntList myList1(myPool);\nIntList myList2(myPool);\n\nmyList1.push_back(37);\nmyList2.push_back(39);\n```\n\n### Cont.28 Can I use a std (STL) allocator with EASTL?\n\nNo. 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:\n\n* EASTL allocators have a different allocate function signature.\n* EASTL allocators have as many as four extra required functions: ctor(name), get_name(), set_name(), allocate(size, align, offset).\n* EASTL allocators have an additional allocate function specifically for aligned allocations, as listed directly above.\n\n### What are the requirements of classes stored in containers?\n\nClass types stored in containers must have:\n\n* a public copy constructor\n* a public assignment operator\n* a public destructor\n* an operator < that compares two such classes (sorted containers only).\n* an operator == that compares two such classes (hash containers only).\n\nRecall 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.\n\nFor 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.\n\n```cpp\nstruct NotAPod\n{\n NotAPod(const NotAPod&) {} // Intentionally don't copy the refCount\n\n int refCount; // refCounts should not be copied between NotAPod instances.\n};\n\neastl::vector v;\n```\n\n## Algorithms\n\n### Algo.1 I'm getting screwy behavior in sorting algorithms or sorted containers. What's wrong?\n\nIt 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.\n\nThe 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.\n\n```cpp\nclass SortByDistance : public binary_function\n{\nprivate:\n Vector3 mOrigin;\n\npublic:\n SortByDistance(Vector3 origin) {\n mOrigin = origin;\n }\n\n bool operator()(WorldTreeObject* pA, WorldTreeObject* pB) const {\n return ((WorldObject*)pA)->mPos - mOrigin).GetLength()\n < ((WorldObject*)pB)->mPos - mOrigin).GetLength();\n }\n};\n```\n\n### Algo.2 How do I write a comparison (operator<()) for a struct that contains two or more members?\n\nFor a struct with two members such as the following:\n\n```cpp\nstruct X {\n Blah m1;\n Blah m2;\n};\n```\n\nYou would write the comparison function like this:\n\n```cpp\nbool operator<(const X& a, const X& b) {\n return (a.m1 == b.m1) ? (a.m2 < b.m2) : (a.m1 < b.m1);\n}\n```\n\nor, using only operator < but more instructions:\n\n```cpp\nbool operator<(const X& a, const X& b) {\n return (a.m1 < b.m1) || (!(b.m1 < a.m1) && (a.m2 < b.m2));\n}\n```\n\nFor a struct with three members, you would have:\n\n```cpp\nbool operator<(const X& a, const X& b) {\n if(a.m1 != b.m1)\n return (a.m1 < b.m1);\n if(a.m2 != b.m2)\n return (a.m2 < b.m2);\n return (a.mType < b.mType);\n}\n```\n\nAnd a somewhat messy implementation if you wanted to use only operator <.\n\nNote 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 stuct as an array of values and ignore the fact that they have spatial meaning. All operator < cares about is that things order consistently.\n\n```cpp\nbool operator<(const Point2D& a, const Point2D& b) {\n return (a.x == b.x) ? (a.y < b.y) : (a.x < b.x);\n}\n```\n\n### Algo.3 How do I sort something in reverse order?\n\nNormally sorting puts the lowest value items first in the sorted range. You can change this by simply reversing the comparison. For example:\n\n`sort(intVector.begin(), intVector.end(), greater());`\n\nIt's important that you use operator > instead of >=. The comparison function must return false for every case where values are equal.\n\n### Algo.4 I'm getting errors about min and max while compiling.\n\nYou 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 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.\n\n### Algo.5 Why don't algorithms take a container as an argument instead of iterators? A container would be more convenient.\n\nHaving 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.\n\nProviding additional algorithms that use containers would introduce redundancy with respect to the existing algorithms that use iterators.\n\n### Algo.6 Given a container of pointers, how do I find an element by value (instead of by pointer)?\n\nFunctions 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, 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.\n\nYou 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:\n\n```cpp\ntemplate\nstruct dereferenced_equal\n{\n const T& mValue;\n\n dereferenced_equal(const T& value) : mValue(value) { } \n bool operator==(const T* pValue) const { return *pValue == mValue; }\n};\n\n...\n\nfind_if(container.begin(), container.end(), dereferenced_equal(someWidget));\n```\n\n### Algo.7 When do stored objects need to support operator < vs. when do they need to support operator ==?\n\nAny 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 <.\n\nAny object which is compareed 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 ==.\n\nSome algorithms and containers require neither < nor ==. Interestingly, no algorithm or container requires both < and ==.\n\n### Algo.8 How do I sort via pointers or array indexes instead of objects directly?\n\nPointers\n\n```cpp\nvector toArray;\nvector topArray;\n\nfor(eastl_size_t i = 0; i < 32; i++)\n toArray.push_back(TestObject(rng.RandLimit(20)));\nfor(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.\n topArray.push_back(&toArray[i]);\n\nstruct TestObjectPtrCompare\n{\n bool operator()(TestObject* a, TestObject* b)\n { return a->mX < a->mX; }\n};\n\nquick_sort(topArray.begin(), topArray.end(), TestObjectPtrCompare());\n```\n\nArray indexes\n\n```cpp\nvector toArray;\nvector toiArray;\n\nfor(eastl_size_t i = 0; i < 32; i++)\n{\n toArray.push_back(TestObject(rng.RandLimit(20)));\n toiArray.push_back(i);\n}\n\nstruct TestObjectIndexCompare\n{\n vector* mpArray;\n\n TestObjectIndexCompare(vector* pArray) : mpArray(pArray) { }\n TestObjectIndexCompare(const TestObjectIndexCompare& x) : mpArray(x.mpArray){ }\n TestObjectIndexCompare& operator=(const TestObjectIndexCompare& x) { mpArray = x.mpArray; return *this; }\n\n bool operator()(eastl_size_t a, eastl_size_t b)\n { return (*mpArray)[a] < (*mpArray)[b]; }\n};\n\nquick_sort(toiArray.begin(), toiArray.end(), TestObjectIndexCompare(&toArray));\n```\n\nArray indexes (simpler version using toArray as a global variable)\n\n```cpp\nvector toArray;\nvector toiArray;\n\nfor(eastl_size_t i = 0; i < 32; i++)\n{\n toArray.push_back(TestObject(rng.RandLimit(20)));\n toiArray.push_back(i);\n}\n\nstruct TestObjectIndexCompare\n{\n bool operator()(eastl_size_t a, eastl_size_t b)\n { return toArray[a] < toArray[b]; }\n};\n\nquick_sort(toiArray.begin(), toiArray.end(), TestObjectIndexCompare(&toArray));\n```\n\n## Iterators\n\n### Iter.1 What's the difference between iterator, const iterator, and const_iterator?\n\nAn iterator can be modified and item it points to can be modified.\nA const iterator cannot be modified, but the items it points to can be modified.\nA const_iterator can be modified, but the items it points to cannot be modified.\nA const const_iterator cannot be modified, nor can the items it points to.\n\nThis situation is much like with char pointers:\n\n| Iterator type | Pointer equivalent |\n|------|------|\n| iterator | char* |\n| const iterator | char* const |\n| const_iterator | const char* |\n| const const_iterator | const char* const |\n\n### Iter.2 How do I tell from an iterator what type of thing it is iterating?\n\nUse the value_type typedef from iterator_traits, as in this example\n\n```cpp\ntemplate \nvoid DoSomething(Iterator first, Iterator last)\n{\n typedef typename iterator_traits::value_type;\n\n // use value_type\n}\n```\n\n### Iter.3 How do I iterate a container while (selectively) removing items from it?\n\nAll 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:\n\n```cpp\nset intSet;\nset::iterator i = intSet.begin();\n\nwhile(i != intSet.end())\n{\n if(*i & 1) // Erase all odd integers from the container.\n i = intSet.erase(i);\n else\n ++i;\n}\n```\n\n### Iter.4 What is an insert_iterator?\n\nAn 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.\n\n----------------------------------------------\nEnd of document\n" }, { "path": "doc/Glossary.md", "content": "# EASTL Glossary\n\nThis document provides definitions to various terms related to EASTL. Items that are capitalized are items that are used as template parameters.\n\n| | |\n|------|------|\n| adapter | 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. |\n| algorithm | 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. |\n| associative container | 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. |\n| array | An array is a C++ container which directly implements a C-style fixed array but which adds STL container semantics to it. |\n| basic_string | A templated string class which is usually used to store char or wchar_t strings. |\n| begin | The function used by all conventional containers to return the first item in the container. |\n| BidirectionalIterator | An input iterator which is like ForwardIterator except it can be read in a backward direction as well. |\n| BinaryOperation  | A function which takes two arguments and returns a value (which will usually be assigned to a third object). |\n| BinaryPredicate | A function which takes two arguments and returns true if some criteria is met (e.g. they are equal). |\n| binder1st, binder2nd | 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. |\n| bit vector | A specialized container that acts like vector but is implemented via one bit per entry. STL vector is usually implemented as a bit vector but EASTL avoids this in favor of a specific bit vector container. |\n| bitset | An extensible yet efficient implementation of bit flags. Not strictly a conventional STL container and not the same thing as vector or a bit_vector, both of which are formal iterate-able containers. |\n| capacity | 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. |\n| const_iterator | An iterator whose iterated items are cannot be modified. A const_iterator is akin to a const pointer such as 'const char*'. |\n| container | 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. |\n| copy constructor | 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); |\n| Compare | A function which takes two arguments and returns the lesser of the two. |\n| deque | The name deque is pronounced \"deck\" and stands for \"double-ended queue.\"

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.

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. |\n| difference_type | 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. |\n| empty | 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. |\n| element | An element refers to a member of a container. |\n| end | The function used by all conventional containers to return one-past the last item in the container. |\n| equal_range | 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. |\n| explicit instantiation | 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:
`template class vector;`
`template void min(int, int);`
`template void min(int, int);` |\n| ForwardIterator | An input iterator which is like InputIterator except it can be reset back to the beginning. |\n| Function | A function which takes one argument and applies some operation to the target. |\n| function object, functor | A function object or functor is a class that has the function-call operator (operator()) defined. |\n| Generator | A function which takes no arguments and returns a value (which will usually be assigned to an object). |\n| hash_map, hash_multimap, hash_set, hash_multiset | 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. |\n| heap | 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. |\n| InputIterator | An input iterator (iterator you read from) which allows reading each element only once and only in a forward direction. |\n| intrusive_list, intrusive_hash_map, etc. | 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. |\n| intrusive_ptr | 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. |\n| iterator | 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. |\n| iterator category | 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 iterator_tag. |\n| iterator_tag | See iterator category. |\n| key_type, Key | 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. |\n| lexicographical compare | A lexicographical compare is a comparison of two containers that compares them element by element, much like the C strcmp function compares two strings. |\n| linked_ptr | 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. |\n| list | 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::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. |\n| lower_bound | 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. |\n| map | 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. It is also a unique associative container, meaning that no two elements have the same key. It is implemented with a tree structure. |\n| mapped_type | 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. |\n| member template | 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. |\n| multimap,  | 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. 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. |\n| multiset | 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. |\n| node | 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). |\n| npos | npos is used by the string class to identify a non-existent index. Some string functions return npos to indicate that the function failed. |\n| rel_ops | 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. |\n| reverse_iterator | 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. |\n| OutputIterator | An output iterator (iterator you write to) which allows writing each element only once in only in a forward direction. |\n| POD | 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.  |\n| Predicate | A function which takes one argument returns true if the argument meets some criteria. |\n| priority_queue | A priority_queue is an adapter container which implements a heap via a random access container such as vector or deque. |\n| queue | 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. |\n| RandomAccessIterator | An input iterator which can be addressed like an array. It is a superset of all other input iterators. |\n| red-black tree | 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. |\n| scalar | A scalar is a data type which is implemented via a numerical value. In C++ this means integers, floating point values, enumerations, and pointers.  |\n| scoped_ptr | A scoped_ptr is a smart pointer which is the same as C++ auto_ptr except that it cannot be copied. |\n| set | 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. |\n| sequence | 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. |\n| size | 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. |\n| size_type | 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. |\n| skip list | A skip-list is a type of container which is an alternative to a binary tree for finding data. |\n| shared_ptr | 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. |\n| slist | An slist is like a list but is singly-linked instead of doubly-linked. It can only be iterated in a forward-direction. |\n| smart pointer | 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. |\n| splice | Splicing refers to the moving of a subsequence of one Sequence into another Sequence. |\n| stack | A stack is a adapter container which implements LIFO (last-in, first, out) access via another container such as a list or deque. |\n| STL | Standard Template Library.  |\n| StrictWeakOrdering | A BinaryPredicate that compares two objects, returning true if the first precedes the second. Like Compare but has additional requirements. Used for sorting routines.

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. |\n| string | See basic_string. |\n| T | T is the template parameter name used by most containers to identify the contained element type.  |\n| template parameter | A template parameter is the templated type used to define a template function or class. In the declaration 'template class vector{ },'  T is a template parameter. |\n| template specialization | 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. |\n| treap | 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. |\n| type traits | 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. |\n| typename | 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. |\n| UnaryOperation | A function which takes one argument and returns a value (which will usually be assigned to second object). |\n| upper_bound | 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. |\n| value_type, Value | 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. |\n| vector | 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. |\n| vector_map, vector_multimap, vector_set, vector_multiset | 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. |\n| weak_ptr | 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. |\n\n----------------------------------------------\nEnd of document\n" }, { "path": "doc/Gotchas.md", "content": "# EASTL Gotchas\n\nThere 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.\n\n## Summary\n\nThe descriptions here are intentionally terse; this is to make them easier to visually scan.\n\n1. [map::operator[] can create elements.](#mapoperator-can-create-elements)\n2. [char* converts to string silently.](#char-converts-to-string-silently)\n3. [char* is compared by ptr and not by contents.](#char-is-compared-by-ptr-and-not-by-contents)\n4. [Iterators can be invalidated by container mutations.](#iterators-can-be-invalidated-by-container-mutations)\n5. [Vector resizing may cause ctor/dtor cascades.](#vector-resizing-may-cause-ctordtor-cascades)\n6. [Vector and string insert/push_back/resize can reallocate.](#vector-and-string-insertpush_backresize-can-reallocate)\n7. [Deriving from containers may not work.](#deriving-from-containers-may-not-work)\n8. [set::iterator is const_iterator.](#setiterator-is-const_iterator)\n9. [Inserting elements means copying by value.](#inserting-elements-means-copying-by-value)\n10. [Containers of pointers can leak if you aren't careful.](#containers-of-pointers-can-leak-if-you-arent-careful)\n11. [Containers of auto_ptrs can crash.](#containers-of-auto_ptrs-can-crash)\n12. [Remove algorithms don't actually remove elements.](#remove-algorithms-dont-actually-remove-elements)\n13. [list::size() is O(n).](#listsize-is-on)\n14. [vector and deque::size() may incur integer division.](#vector-and-dequesize-may-incur-integer-division)\n15. [Be careful making custom Compare functions.](#be-careful-making-custom-compare-functions)\n16. [Comparisons involving floating point are dangerous.](#comparisons-involving-floating-point-are-dangerous)\n17. [Writing beyond string::size and vector::size is dangerous.](#writing-beyond-stringsize-and-vectorsize-is-dangerous)\n18. [Container operator=() doesn't copy allocators.](#container-operator-doesnt-copy-allocators)\n\n## Detail\n\n### map::operator[] can create elements.\n\nBy 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[].\n\n### char* converts to string silently.\n\nThe 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.\n\nThere is an EASTL configuration option called EASTL_STRING_EXPLICIT which makes the string char* ctor explicit and avoids the behaviour described above.\n\n### char* is compared by ptr and not by contents.\n\nIf you have a set of strings declared as set, 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.\n\n### Iterators can be invalidated by container mutations\n\nWith 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.\n\n### Vector resizing may cause ctor/dtor cascades.\n\nIf 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 design your element type to be trivially copyable. A good way to communicate this requirement/optimization is to static assert is_trivially_copyable. eastl optimizes such types to a memcpy/memmove, eliding a call to the copy constructor.\n\n### Vector and string insert/push_back/resize can reallocate.\n\nIf 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.\n\n### Deriving from containers may not work.\n\nEASTL 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.\n\n### set::iterator is const_iterator.\n\nThe 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.\n\n### Inserting elements means copying by value.\n\nWhen 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.\n\n### Containers of pointers can leak if you aren't careful.\n\nContainers 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.\n\n### Containers of auto_ptrs can crash\n\nWe 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.\n\n### Remove algorithms don't actually remove elements.\n\nAlgorithms 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.\n\n### list::size() is O(n).\n\nBy 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.\n\nNote 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.\n\n### vector and deque::size() may incur integer division.\n\nSome 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.\n\n### Be careful making custom Compare functions.\n\nA 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 [\"Writing a sort comparison function\"](https://devblogs.microsoft.com/oldnewthing/20031023-00/?p=42063) for a story about how this can go wrong by being overly clever. All comparisons in std STL and eastl, including user defined comparisons, must have strict weak ordering. See the [Compare](https://en.cppreference.com/w/cpp/named_req/Compare) named requirement for more info.\n\n### Comparisons involving floating point are dangerous.\n\nFloating 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.\n\n### Writing beyond string::size and vector::size is dangerous.\n\nA 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.\n\nThe following code is broken:\n\n```cpp\nstring mDataDir;\n\n\n mDataDir.reserve(kMaxPathLength); // reserve\n strcpy(&mDataDir[0], \"blah/blah/blah\");\n\nmDataDir.resize(strlen(&mDataDir[0])); // Overwrites your blah/... with 00000...\n```\n\nThis following code is OK:\n\n```cpp\nstring mDataDir;\n\n\n mDataDir.resize(kMaxPathLength); // resize\n strcpy(&mDataDir[0], \"blah/blah/blah\");\n \nmDataDir.resize(strlen(&mDataDir[0]));\n```\n\n### Container operator=() doesn't copy allocators.\n\nEASTL 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.\n\n----------------------------------------------\nEnd of document\n\n\n\n" }, { "path": "doc/Introduction.md", "content": "# EASTL Introduction\n\nEASTL 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.\n\n## Intended Audience\n\nThis 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 EASTL FAQ.html document for links to information related to learning templates and STL.\n\n## EASTL Modules\n\nEASTL 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 EASTL Modules.html.\n\n## EASTL Suitability\n\nWhat 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.\n\n----------------------------------------------\nEnd of document" }, { "path": "doc/Maintenance.md", "content": "# EASTL Maintenance\n\n## Introduction\n\nThe 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.\n\nIt 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:\n\n```cpp\nint count(InputIterator first, InputIterator last, const T& value)\n{\n     int result = 0;\n\n     for(; first < last; ++first){\n         if(*first == value)\n             ++result;\n     }\n\n     return result;\n }\n ```\n\nThe 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.\n\nIn 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.\n\n## C++ Language Standard\n\nFirst 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?\n\nIn 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.\n\nAdditionally, 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.\n\nAdditionally, 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.\n\n## Language Use\n\nMacros 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.\n\nEASTL 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:\n\n* RTTI (run-time-type-identification) (this is deemed too costly)\n* Template export (few compilers support this)\n* Exception specifications (most compilers ignore them)\n\nUse 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.\n\n## Prime Directives\n\nThe implementation of EASTL is guided foremost by the following directives which are listed in order of importance.\n\n1. Efficiency (speed and memory usage)\n2. Correctness (doesn't have bugs)\n3. Portability (works on all required platforms with minimal specialized code)\n4. Readability (code is legible and comments are present and useful)\n\nNote 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.\n\nPortability 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.\n\nReadability 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.\n\n## Coding Conventions\n\nHere we provide a list of coding conventions to follow when maintaining or adding to EASTL, starting with the three language use items from above:\n\n* No RTTI use.\n* No use of exception specifications (e.g. appending the 'throw' declarator to a function).\n* No use of exception handling itself except where explicitly required by the implementation (e.g. vector::at).\n* Exception use needs to savvy to EASTL_EXCEPTIONS_ENABLED.\n* No use of macros (outside of config.h). Macros make things more difficult for the user.\n* No use of static or global variables.\n* No use of global new, delete, malloc, or free. All memory must be user-specifyable via an Allocator parameter (default-specified or explicitly specified).\n* 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 [prime directives](#Prime_Directives) above that performance and simplicity overrule all.\n* No use of multithreading primitives. \n* No use of the export keyword.\n* 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.\n* No external library dependencies whatsoever, including standard STL. EASTL is dependent on only EABase and the C++ compiler. \n* All code must be const-correct. This isn't just for readability -- compilation can fail unless const-ness is used correctly everywhere. \n* Algorithms do not refer to containers; they refer only to iterators.\n* 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.\n* No inferior implementations. No facility should be added to EASTL unless it is of professional quality.\n* 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.\n* No major changes should be done without consulting a peer group.\n\n## Compiler Issues\n\nHistorically, 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.\n\nIt 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.\n\nIn order to feel comfortable that your EASTL code is C++ correct and is portable, you must do at least these two things:\n\n* Test under at least VS2005, GCC 3.4+, GCC 4.4+, EDG, and clang.\n* Test all functions that you write, as compilers will often skip the compilation of a template function if it isn't used.\n\nThe 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.\n\n## Iterator Issues\n\nThe 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.\n\nHere'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:\n\n```cpp\ntemplate \ninline void reverse_impl(BidirectionalIterator first, BidirectionalIterator last, bidirectional_iterator_tag)\n{\n for(; (first != last) && (first != --last); ++first) // We are not allowed to use operator <, <=, >, >= with\n iter_swap(first, last); // a generic (bidirectional or otherwise) iterator.\n}\n\n\ntemplate \ninline void reverse_impl(RandomAccessIterator first, RandomAccessIterator last, random_access_iterator_tag)\n{\n for(; first < --last; ++first) // With a random access iterator, we can use operator < to more efficiently implement\n iter_swap(first, last); // this algorithm. A generic iterator doesn't necessarily have an operator < defined.\n}\n\n\ntemplate \ninline void reverse(BidirectionalIterator first, BidirectionalIterator last)\n{\n typedef typename iterator_traits::iterator_category IC;\n reverse_impl(first, last, IC());\n}\n```\n\n## Exception Handling\n\nYou 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).\n\nThis 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:\n\n* Memory allocation failures (which throw exceptions)\n* Constructor exceptions\n\nTake a look at the cases in EASTL where try/catch is used and see what it is doing.\n\n## Type Traits\n\nEASTL 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.\n\nAs mentioned in the GeneralOptimizations section below, EASTL should take advantage of type_traits information to the extent possible to achive maximum effiiciency.\n\n## General Optimizations\n\nOne 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:\n\n* Take advantage of type_traits to the extent possible (e.g. to use memcpy to move data instead of a for loop when possible).\n* Take advantage of iterator types to the extent possible.\n* 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.\n* Make inline-friendly code. This often means avoiding temporaries to the extent possible.\n* Minimize branching (i.e. minimize 'if' statements). Where branching is used, make it so that 'if' statements execute as true.\n* Use EASTL_LIKELY/EASTL_UNLIKELY to give branch hints to the compiler when you are confident it will be beneficial.\n* Use restricted pointers (EABase's EA_RESTRICT or various compiler-specific versions of __restrict).\n* Compare unsigned values to < max instead of comparing signed values to >= 0 && < max.\n* Employ power of 2 integer math instead of math with any kind of integer.\n* Use template specialization where possible to implement improved functionality.\n* 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.\n\n## Unit Tests\n\nWriting 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.\n\n* When making a new unit test, start by copying one of the existing unit tests and follow its conventions.\n* Test containers of both scalars and classes.\n* Test algorithms on both container iterators (e.g. vector.begin()) and pointer iterators (e.g. int*).\n* Make sure that algorithm or container member functions which take iterators work with the type of iterator they claim to (InputIterator, ForwardIterator, BidirectionalIterator, RandomAccessIterator). \n* Test for const-correctness. If a user is allowed to modify something that is supposed to be const, silent errors can go undetected.\n* 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.\n* 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.\n* 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.\n* 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.\n* 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.\n* 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.\n\n## Things to Keep in Mind\n\n* 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.\n* 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.\n* 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. \n* 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.\n* 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.\n* Algorithm templates always work with iterators and not containers. A given container may of course implement an optimized form or an algorithm itself.\n* 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.\n* It's easy to get iterator categories confused or forgotten while implementing algorithms and containers.\n* 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.\n* Don't forget to update the config.h EASTL_VERSION define before publishing.\n* 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.\n\n----------------------------------------------\nEnd of document\n" }, { "path": "doc/Modules.md", "content": "# EASTL Modules\n\n## Introduction\n\nWe 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.\n\n## Module List\n\n| Module | Description |\n|------|------|\n| config | Configuration header. Allows for changing some compile-time options. |\n| slist
fixed_slist | Singly-linked list.
fixed_slist is a version which is implemented via a fixed block of contiguous memory.|\n| list
fixed_list | Doubly-linked list. |\n| intrusive_list
intrusive_slist | List whereby the contained item provides the node implementation. |\n| array | Wrapper for a C-style array which extends it to act like an STL container. |\n| vector
fixed_vector | Resizable array container.\n| vector_set
vector_multiset | Set implemented via a vector instead of a tree. Speed and memory use is improved but resizing is slower. |\n| vector_map
vector_multimap | Map implemented via a vector instead of a tree. Speed and memory use is improved but resizing is slower. |\n| deque | Double-ended queue, but also with random access. Acts like a vector but insertions and removals are efficient. |\n| bit_vector | Implements a vector of bool, but the actual storage is done with one bit per bool. Not the same thing as a bitset. |\n| bitset | 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. |\n| set
multiset
fixed_set
fixed_multiset | A set is a sorted unique collection, multiset is sorted but non-unique collection. |\n| map
multimap
fixed_map
fixed_multimap | A map is a sorted associative collection implemented via a tree. It is also known as dictionary. |\n| hash_map
hash_multimap
fixed_hash_map
fixed_hash_multimap | Map implemented via a hash table. |\n| intrusive_hash_map
intrusive_hash_multimap
intrusive_hash_set
intrusive_hash_multiset | hash_map whereby the contained item provides the node implementation, much like intrusive_list. |\n| hash_set
hash_multiset
fixed_hash_set
fixed_hash_map | Set implemented via a hash table.\n| basic_string
fixed_string
fixed_substring | basic_string is a character string/array.
fixed_substring is a string which is a reference to a range within another string or character array.
cow_string is a string which implements copy-on-write. |\n| algorithm | min/max, find, binary_search, random_shuffle, reverse, etc. |\n| sort | Sorting functionality, including functionality not in STL. quick_sort, heap_sort, merge_sort, shell_sort, insertion_sort, etc. |\n| numeric | Numeric algorithms: accumulate, inner_product, partial_sum, adjacent_difference, etc. |\n| heap | Heap structure functionality: make_heap, push_heap, pop_heap, sort_heap, is_heap, remove_heap, etc. |\n| stack | Adapts any container into a stack. |\n| queue | Adapts any container into a queue. |\n| priority_queue | Implements a conventional priority queue via a heap structure. |\n| type_traits | Type information, useful for writing optimized and robust code. Also used for implementing optimized containers and algorithms. |\n| utility | pair, make_pair, rel_ops, etc. |\n| functional | Function objects. |\n| iterator | Iteration for containers and algorithms. |\n| smart_ptr | Smart pointers: shared_ptr, shared_array, weak_ptr, scoped_ptr, scoped_array, linked_ptr, linked_array, intrusive_ptr. |\n \n\n## Module Behaviour\n\nThe 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.\n\n| Container |Stores | Container Overhead (32 bit) | Container Overhead (64 bit) | Node Overhead (32 bit) | Node Overhead (64 bit) | Iterator category | size() efficiency | operator[] efficiency | Insert efficiency | Erase via Iterator efficiency | Find efficiency | Sort efficiency |\n|------|------|------|------|------|------|------|------|------|------|------|------|------|\n| slist | T | 8 | 16 | 4 | 8 | f | n | - | 1 | 1 | n | n+ |\n| list | T | 12 | 24 | 8 | 16 | b | n | - | 1 | 1 | n | n log(n) |\n| intrusive_slist | T | 4 | 8 | 4 | 8 | f | n | - | 1 | 1 | 1 | n+ |\n| intrusive_list | T | 8 | 16 | 8 | 16 | b | n | - | 1 | 1 | 1 | n log(n) |\n| array | T | 0 | 0 | 0 | 0 | r | 1 | 1 | - | - | n | n log(n) |\n| vector | T | 16 | 32 | 0 | 0 | r | 1 | 1 | 1 at end, else n | 1 at end, else n | n | n log(n) |\n| vector_set | T | 16 | 32 | 0 | 0 | r | 1 | 1 | 1 at end, else n | 1 at end, else n | log(n) | 1 |\n| vector_multiset | T | 16 | 32 | 0 | 0 | r | 1 | 1 | 1 at end, else n | 1 at end, else n | log(n) | 1 |\n| vector_map | Key, T | 16 | 32 | 0 | 0 | r | 1 | 1 | 1 at end, else n | 1 at end, else n | log(n) | 1 |\n| vector_multimap | Key, T | 16 | 32 | 0 | 0 | r | 1 | 1 | 1 at end, else n | 1 at end, else n | log(n) | 1 |\n| deque | T | 44 | 84 | 0 | 0 | r | 1 | 1 | 1 at begin or end, else n / 2 | 1 at begin or end, else n / 2 | n | n log(n) |\n| bit_vector | bool | 8 | 16 | 0 | 0 | r | 1 | 1 | 1 at end, else n | 1 at end, else n | n | n log(n) |\n| string (all types) | T | 16 | 32 | 0 | 0 | r | 1 | 1 | 1 at end, else n | 1 at end, else n | n | n log(n) |\n| set | T | 24 | 44 | 16 | 28 | b | 1 | - | log(n) | log(n) | log(n) | 1 |\n| multiset | T | 24 | 44 | 16 | 28 | b | 1 | - | log(n) | log(n) | log(n) | 1 |\n| map | Key, T | 24 | 44 | 16 | 28 | b | 1 | log(n) | log(n) | log(n) | log(n) | 1 |\n| multimap | Key, T | 24 | 44 | 16 | 28 | b | 1 | - | log(n) | log(n) | log(n) | 1 |\n| hash_set | T | 16 | 20 | 4 | 8 | b | 1 | - | 1 | 1 | 1 | - |\n| hash_multiset | T | 16 | 20 | 4 | 8 | b | 1 | - | 1 | 1 | 1 | - |\n| hash_map | Key, T | 16 | 20 | 4 | 8 | b | 1 | - | 1 | 1 | 1 | - |\n| hash_multimap | Key, T | 16 | 20 | 4 | 8 | b | 1 | - | 1 | 1 | 1 | - |\n| intrusive_hash_set | T | 16 | 20 | 4 | 8 | b | 1 | - | 1 | 1 | 1 | - |\n| intrusive_hash_multiset | T | 16 | 20 | 4 | 8 | b | 1 | - | 1 | 1 | 1 | - |\n| intrusive_hash_map | T (Key == T) | 16 | 20 | 4 | 8 | b | 1 | - | 1 | 1 | 1 | - |\n| intrusive_hash_multimap | T (Key == T)  | 16 | 20 | 4 | 8 | b | 1 | - | 1 | 1 | 1 | - |\n\n* \\- means that the operation does not exist.\n* 1 means amortized constant time. Also known as O(1)\n* n means time proportional to the container size. Also known as O(n)\n* log(n) means time proportional to the natural logarithm of the container size. Also known as O(log(n))\n* n log(n) means time proportional to log(n) times the size of the container. Also known as O(n log(n))\n* n+ means that the time is at least n, and possibly higher.\n* Iterator meanings are: f = forward iterator; b = bidirectional iterator, r = random iterator.\n* 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.\n* 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).\n* Some overhead values are dependent on the size_type used by containers. We assume a size_type of 4 bytes, even for 64 bit machines, as this is the EASTL default.\n* 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.\n* 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).\n* 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.\n\n----------------------------------------------\nEnd of document\n" }, { "path": "doc/html/EASTL Benchmarks.html", "content": "\n\n\n EASTL Benchmarks\n \n \n \t\n \n\n\n\n\n\n\n

EASTL Benchmarks

\n

Introduction

\n

This document provides a number of benchmark results of EASTL.\n Where possible, these benchmarks are implemented as comparisons\n with equivalent functionality found in other libraries such as\n compiler STL libraries or other well-known libraries. These\n comparison benchmarks concentrate on highlighting the differences\n between implementations rather than the similarities. In many\n mundane cases -- such as accessing a vector element via operator []\n -- virtually all vector/array implementations you are likely to run\n into will have identical performance.
\n \n\n \n
\n \n\n \nIt's also important to note that the platform you run on can make a\n significant difference in the results. On a modern 3+GHz Windows PC\n many operations are fast due to large memory caches, intelligent\n branch prediction, and parallel instruction execution. However, on\n embedded or console systems none of these may be the case. \n
\n \n\n \n
\n \n\n \nWhile EASTL generally outperforms std STL, there are some benchmarks\n here in which EASTL is slower than std STL. There are three primary\nexplanations of this:

\n
    \n\n\n\n
  1. EASTL is making some kind of speed, memory, or design tradeoff\nthat results in the given speed difference. In may such cases, EASTL\ngoes slower on one benchmark in order to go faster on another benchmark\ndeemed more important. This explanation constitutes about 60% of the\ncases.
    2. \n\n\n\n
  2. Compiler optimizations and resulting code generation is\ncoincidencally favoring one kind of implementation over another, often\nwhen they are visually virtually identical. This explantation\nconstitutes about 30% of the cases.
    3. \n\n\n\n
  3. EASTL is simply not yet as optimized as it could be. This\nexplanation constitutes about 10% of the cases (as of this writing\nthere are about three such functions throughout EASTL).
    4. \n\n\n\n
\n\n\n\n

Benchmarks

\n

Below is a table of links to detailed benchmark results derived from\n the Benchmark test present in the EASTL package. The detailed results\n are present below the table. Additional platforms will be added as\n results become available for those platforms. Debug benchmarks are\n present because (lack of) debug performance can be significant for\n highly templated libraries. EASTL has specific optimizations to enhance\n debug performance relative to other standard libraries; in some cases\n it is 10x or more faster than alternatives (though there are exceptions where EASTL is slower). Feel free to submit results\n for additional compilers/platforms.
\n \n\n \n

\n\n\n\n \n\n\n \n\n\n \n\n\n \n\n\n \n\n\n \n\n\n \n\n\n \n\n\n\n\n\n \n\n\n \n\n\n \n\n\n \n\n\n \n\n\n \n\n\n \n\n\n \n\n\n \n\n\n \n\n\n \n\n\n \n\n\n \n\n\n \n\n\n \n\n\n \n\n\n \n\n\n \n\n\n \n\n\n \n\n\n \n\n\n \n\n\n \n\n\n \n\n\n \n\n\n \n\n\n \n\n\n \n\n \n \n \n
PlatformCompilerSTL typeBuildResults
Win32VC++ 7.1Microsoft (Dinkumware)DebugDetail
Win32VC++ 7.1Microsoft (Dinkumware)ReleaseDetail
Win32VC++ 7.1STLPortDebugDetail
Win32VC++ 7.1STLPortReleaseDetail
\n\n\n\n\n\n\n\n\n\n\n\n\n\n

\n \n\n \n\n Win32.VC71.MS.Debug

\n
\n
EASTL version: 0.96.00
Platform: Windows on X86
Compiler: Microsoft Visual C++ compiler, version 1310
Allocator: PPMalloc::GeneralAllocatorDebug. Thread safety enabled.
Build: Debug. Inlining disabled. STL debug features disabled.

Values are times to complete tests; smaller values are better.
Alarm indicates a greater than 10% difference.

Test                                               VC++        EASTL     Ratio     Alarm
----------------------------------------------------------------------------------------
algorithm/adj_find/vector<TestObject>          33061345      6497757      5.09         *
algorithm/copy/vector<LargePOD>                 5844906      4876076      1.20         *
algorithm/copy/vector<uint32_t>                 1634346       166065      9.84         *
algorithm/copy_backward/vector<LargePOD>        4515974      4638892      0.97
algorithm/copy_backward/vector<uint32_t>        1821168       121746     14.96         *
algorithm/count/vector<uint64_t>               17048884      2720766      6.27         *
algorithm/equal_range/vector<uint64_t>       1111147812    448756888      2.48         *
algorithm/fill/bool[]                           1728722        91936     18.80         *
algorithm/fill/char[]/'d'                       1299200        33745     38.50         *
algorithm/fill/vector<char>/'d'                10205092        33796    100.00         *
algorithm/fill/vector<char>/0                  10200748        33805    100.00         *
algorithm/fill/vector<uint64_t>                10416538      1399687      7.44         *
algorithm/fill/vector<void*>                   10221837      1307700      7.82         *
algorithm/fill_n/bool[]                         1399033        34196     40.91         *
algorithm/fill_n/char[]                         1299225        33754     38.49         *
algorithm/fill_n/vector<uint64_t>               5961637      1371900      4.35         *
algorithm/find_end/string/end                  16569373      2657372      6.24         *
algorithm/find_end/string/middle               16558638     20242410      0.82         *
algorithm/find_end/string/none                 16811207     40480468      0.42         *
algorithm/lex_cmp/schar[]                       1749674       194429      9.00         *
algorithm/lex_cmp/vector<TestObject>           32824195      5253587      6.25         *
algorithm/lex_cmp/vector<uchar>                29852034       202658    100.00         *
algorithm/lower_bound/vector<TestObject>      798624462    350027935      2.28         *
algorithm/min_element/vector<TestObject>       21675298      5314676      4.08         *
algorithm/rand_shuffle/vector<uint64_t>        84236190     43677506      1.93         *
algorithm/reverse/list<TestObject>              3007292      2105799      1.43         *
algorithm/reverse/vector<TestObject>            2974618      2124796      1.40         *
algorithm/search/string<char>                  16228158      3594268      4.52         *
algorithm/search_n/string<char>                16926985      1522096     11.12         *
algorithm/unique/vector<TestObject>            54206243      9988002      5.43         *
algorithm/unique/vector<uint32_t>              26940079      1741991     15.47         *
algorithm/unique/vector<uint64_t>              47621344      5213127      9.13         *
algorithm/upper_bound/vector<uint32_t>        372381295    137901552      2.70         *

bitset<1500>/>>=/1                             90196544     92539832      0.97
bitset<1500>/count                             50753832     53742117      0.94
bitset<1500>/flip                              86935875     85121117      1.02
bitset<1500>/reset                             78153837     79922611      0.98
bitset<1500>/set()                             79214968     79360658      1.00
bitset<1500>/set(i)                            11300589     12199651      0.93
bitset<1500>/test                              11282679     13186450      0.86         *

bitset<15>/>>=/1                               10500577      6000559      1.75         *
bitset<15>/count                                4000356      6399753      0.63         *
bitset<15>/flip                                 7268877      5647944      1.29         *
bitset<15>/reset                                8564235      5800163      1.48         *
bitset<15>/set()                                9935523      5914012      1.68         *
bitset<15>/set(i)                              11199703     12503637      0.90         *
bitset<15>/test                                10600623     12899592      0.82         *

bitset<35>/>>=/1                               13076052      6599834      1.98         *
bitset<35>/count                                4800384     11500330      0.42         *
bitset<35>/flip                                 7915439      5816313      1.36         *
bitset<35>/reset                                9400049      5803180      1.62         *
bitset<35>/set()                               10701152      5840316      1.83         *
bitset<35>/set(i)                              11342936     12271128      0.92
bitset<35>/test                                10670799     13099682      0.81         *

bitset<75>/>>=/1                               14198834     17151088      0.83         *
bitset<75>/count                                5795530      8576373      0.68         *
bitset<75>/flip                                 8516703      8922995      0.95
bitset<75>/reset                                9999970      8526095      1.17         *
bitset<75>/set()                               11124877      9009686      1.23         *
bitset<75>/set(i)                              11300563     12531618      0.90         *
bitset<75>/test                                11031913     13100523      0.84         *

deque<ValuePair>/erase                        743801706    335646802      2.22         *
deque<ValuePair>/insert                       742331809    341912866      2.17         *
deque<ValuePair>/iteration                     29097030     16315827      1.78         *
deque<ValuePair>/operator[]                    49859598     24026313      2.08         *
deque<ValuePair>/push_back                    424807033     34497608     12.31         *
deque<ValuePair>/push_front                   402313373     38006322     10.59         *
deque<ValuePair>/sort                         725101017    581796551      1.25         *

hash_map<string, uint32_t>/clear                 559462       961019      0.58         *
hash_map<string, uint32_t>/count               53377807      8091448      6.60         *
hash_map<string, uint32_t>/erase pos             613573       858084      0.72         *
hash_map<string, uint32_t>/erase range          5488748       461134     11.90         *
hash_map<string, uint32_t>/erase val           35760096     16379858      2.18         *
hash_map<string, uint32_t>/find                43490335     10324823      4.21         *
hash_map<string, uint32_t>/find_as/char*       49343818      8617139      5.73         *
hash_map<string, uint32_t>/insert             107420281    168690439      0.64         *
hash_map<string, uint32_t>/iteration            2456356      1255153      1.96         *
hash_map<string, uint32_t>/operator[]          47209502     12581624      3.75         *

hash_map<uint32_t, TestObject>/clear             533172       546449      0.98
hash_map<uint32_t, TestObject>/count           28667432      2899997      9.89         *
hash_map<uint32_t, TestObject>/erase pos         683239       538289      1.27         *
hash_map<uint32_t, TestObject>/erase range      9632676       253037     38.07         *
hash_map<uint32_t, TestObject>/erase val       25466026      7752188      3.29         *
hash_map<uint32_t, TestObject>/find            20048253      4678502      4.29         *
hash_map<uint32_t, TestObject>/insert          71085798     37686187      1.89         *
hash_map<uint32_t, TestObject>/iteration        1460318      1338317      1.09
hash_map<uint32_t, TestObject>/operator[]      23226692      7888748      2.94         *

heap (uint32_t[])/make_heap                     5399966      6961305      0.78         *
heap (uint32_t[])/pop_heap                    108060534    103511318      1.04
heap (uint32_t[])/push_heap                    22595661     16640688      1.36         *
heap (uint32_t[])/sort_heap                    93559424     83076731      1.13         *

heap (vector<TestObject>)/make_heap            91770743     21724870      4.22         *
heap (vector<TestObject>)/pop_heap           1175599317    284007398      4.14         *
heap (vector<TestObject>)/push_heap           207804541     45918046      4.53         *
heap (vector<TestObject>)/sort_heap           970394145    208321477      4.66         *

list<TestObject>/ctor(it)                     805539509    760938607      1.06
list<TestObject>/ctor(n)                       80959236     75106995      1.08
list<TestObject>/erase                       1052543704   1044976137      1.01
list<TestObject>/find                          97785267     75970884      1.29         *
list<TestObject>/insert                       873895175    807051107      1.08
list<TestObject>/push_back                    812797710    780742425      1.04
list<TestObject>/remove                      1850600714   1436980599      1.29         *
list<TestObject>/reverse                      180270465     80466636      2.24         *
list<TestObject>/size/1                          440148       599642      0.73         *
list<TestObject>/size/10                         439433      1329817      0.33         *   EASTL intentionally implements list::size as O(n).
list<TestObject>/size/100                        439595     11030060      0.04         *   EASTL intentionally implements list::size as O(n).
list<TestObject>/splice                       177106094     69383027      2.55         *

map<TestObject, uint32_t>/clear                  508283       470807      1.08
map<TestObject, uint32_t>/count                43145354     14280357      3.02         *
map<TestObject, uint32_t>/equal_range          38594004     16520447      2.34         *
map<TestObject, uint32_t>/erase/key            33948082     16123175      2.11         *
map<TestObject, uint32_t>/erase/pos              578332       455201      1.27         *   MS uses a code bloating implementation of erase.
map<TestObject, uint32_t>/erase/range            387345       284538      1.36         *
map<TestObject, uint32_t>/find                 22897224     12766100      1.79         *
map<TestObject, uint32_t>/insert               61665800     47286928      1.30         *
map<TestObject, uint32_t>/iteration             1977202       745391      2.65         *
map<TestObject, uint32_t>/lower_bound          19892941     12260928      1.62         *
map<TestObject, uint32_t>/operator[]           24199084     15429634      1.57         *
map<TestObject, uint32_t>/upper_bound          19842409     12064441      1.64         *

set<uint32_t>/clear                             1027625      1000901      1.03
set<uint32_t>/count                            39730182     13329565      2.98         *
set<uint32_t>/equal_range                      34681649     14768827      2.35         *
set<uint32_t>/erase range                        841458       602030      1.40         *
set<uint32_t>/erase/pos                         1380485      1084303      1.27         *   MS uses a code bloating implementation of erase.
set<uint32_t>/erase/val                        31617425     13344023      2.37         *
set<uint32_t>/find                             19582428     10788864      1.82         *
set<uint32_t>/insert                           61434014     48232086      1.27         *
set<uint32_t>/iteration                         1512057       667820      2.26         *
set<uint32_t>/lower_bound                      18394885     10402785      1.77         *
set<uint32_t>/upper_bound                      17189083     10554425      1.63         *

sort/q_sort/TestObject[]                       87088799     15037988      5.79         *
sort/q_sort/TestObject[]/sorted                21502892      3284299      6.55         *
sort/q_sort/vector<TestObject>                 87962047     15004677      5.86         *
sort/q_sort/vector<TestObject>/sorted          21396523      3341163      6.40         *
sort/q_sort/vector<ValuePair>                  80334589     10429161      7.70         *
sort/q_sort/vector<ValuePair>/sorted           22133295      3230553      6.85         *
sort/q_sort/vector<uint32>                     72195388      5940302     12.15         *
sort/q_sort/vector<uint32>/sorted              19635171       995495     19.72         *

string<char16_t>/compare                      523013373    534722089      0.98
string<char16_t>/erase/pos,n                    3446597      3439492      1.00
string<char16_t>/find/p,pos,n                 383873158    441902786      0.87         *
string<char16_t>/find_first_not_of/p,pos,n       174157       134131      1.30         *
string<char16_t>/find_first_of/p,pos,n         11715423      8520944      1.37         *
string<char16_t>/find_last_of/p,pos,n           1871556      1226457      1.53         *
string<char16_t>/insert/pos,p                   3624877      3357058      1.08
string<char16_t>/iteration                   6766787933    581916665     11.63         *
string<char16_t>/operator[]                     4820827      2335579      2.06         *
string<char16_t>/push_back                     59812962      6757466      8.85         *
string<char16_t>/replace/pos,n,p,n              4371279      4459713      0.98
string<char16_t>/reserve                        2307530      1919386      1.20         *
string<char16_t>/rfind/p,pos,n                   734826       372615      1.97         *
string<char16_t>/size                             41608        28866      1.44         *
string<char16_t>/swap                           1033932      1490994      0.69         *

string<char8_t>/compare                        63086797     64194771      0.98
string<char8_t>/erase/pos,n                     2045687      1960270      1.04
string<char8_t>/find/p,pos,n                  123872549    471364764      0.26         *
string<char8_t>/find_first_not_of/p,pos,n        140013       130271      1.07
string<char8_t>/find_first_of/p,pos,n           8051906      8749994      0.92
string<char8_t>/find_last_of/p,pos,n            1318835      1230715      1.07
string<char8_t>/insert/pos,p                    1770610      1724234      1.03
string<char8_t>/iteration                      28112136      2544475     11.05         *
string<char8_t>/operator[]                      4810525      2255841      2.13         *
string<char8_t>/push_back                      54869634      6127447      8.95         *
string<char8_t>/replace/pos,n,p,n               2737578      2847900      0.96
string<char8_t>/reserve                         1123395       394902      2.84         *
string<char8_t>/rfind/p,pos,n                    737299       368518      2.00         *
string<char8_t>/size                              42245        26801      1.58         *
string<char8_t>/swap                            1036142      1491028      0.69         *

vector<uint64>/erase                           56417135     55770251      1.01
vector<uint64>/insert                          56617761     56100468      1.01
vector<uint64>/iteration                       10413895      1291269      8.06         *
vector<uint64>/operator[]                      23507193      3479390      6.76         *
vector<uint64>/push_back                       34687939     13806627      2.51         *
vector<uint64>/sort                           256886550     84669657      3.03         *

\n\n\n\n\n\n
\n\n\n\n\n\n

\n\n\n\n\n Win32.VC71.MS.Release

\n
\n
EASTL version: 0.96.00
Platform: Windows on X86
Compiler: Microsoft Visual C++ compiler, version 1310
Allocator: PPMalloc::GeneralAllocator. Thread safety enabled.
Build: Full optimization. Inlining enabled.

Values are times to complete tests; smaller values are better.
Alarm indicates a greater than 10% difference.

Test                                               VC++        EASTL     Ratio     Alarm
----------------------------------------------------------------------------------------
algorithm/adj_find/vector<TestObject>           2783546      2750660      1.01
algorithm/copy/vector<LargePOD>                 6474025      4972738      1.30         *
algorithm/copy/vector<uint32_t>                  157267       173162      0.91
algorithm/copy_backward/vector<LargePOD>        4836406      4374780      1.11         *
algorithm/copy_backward/vector<uint32_t>         104780       120912      0.87         *
algorithm/count/vector<uint64_t>                1368440      1368696      1.00
algorithm/equal_range/vector<uint64_t>        114199387    102783938      1.11         *
algorithm/fill/bool[]                            253215        27353      9.26         *
algorithm/fill/char[]/'d'                        253164        27404      9.24         *
algorithm/fill/vector<char>/'d'                  253105        27362      9.25         *
algorithm/fill/vector<char>/0                    253275        27353      9.26         *
algorithm/fill/vector<uint64_t>                  397001       394323      1.01
algorithm/fill/vector<void*>                     547196       642362      0.85         *
algorithm/fill_n/bool[]                          229177        27361      8.38         *
algorithm/fill_n/char[]                          228845        27404      8.35         *
algorithm/fill_n/vector<uint64_t>                565233      1376822      0.41         *
algorithm/find_end/string/end                   2107116        82356     25.59         *
algorithm/find_end/string/middle                2111672       664283      3.18         *
algorithm/find_end/string/none                  2110423      1519596      1.39         *
algorithm/lex_cmp/schar[]                        741021       176162      4.21         *
algorithm/lex_cmp/vector<TestObject>            2610494      2642183      0.99
algorithm/lex_cmp/vector<uchar>                  697595       167866      4.16         *
algorithm/lower_bound/vector<TestObject>       62462233     58146664      1.07
algorithm/min_element/vector<TestObject>        4350385      2671227      1.63         *
algorithm/rand_shuffle/vector<uint64_t>        10868261     11300818      0.96
algorithm/reverse/list<TestObject>               483718       470024      1.03
algorithm/reverse/vector<TestObject>             476739       484322      0.98
algorithm/search/string<char>                   2560387      1259496      2.03         *
algorithm/search_n/string<char>                 2770991       458524      6.04         *
algorithm/unique/vector<TestObject>             4194520      4658910      0.90         *
algorithm/unique/vector<uint32_t>                538730       787924      0.68         *
algorithm/unique/vector<uint64_t>               3169829      2575636      1.23         *
algorithm/upper_bound/vector<uint32_t>         27495562     25321593      1.09

bitset<1500>/>>=/1                             33464228     33469719      1.00
bitset<1500>/count                             18736116     18814903      1.00
bitset<1500>/flip                              19299309     18605438      1.04
bitset<1500>/reset                             22200487     15262847      1.45         *
bitset<1500>/set()                             14418193     17557319      0.82         *
bitset<1500>/set(i)                             1599250      1599199      1.00
bitset<1500>/test                               1599241      1599233      1.00

bitset<15>/>>=/1                                2199222      2264442      0.97
bitset<15>/count                                1399406      1399193      1.00
bitset<15>/flip                                 1266712      1199197      1.06
bitset<15>/reset                                1399364      1399109      1.00
bitset<15>/set()                                1199197       999201      1.20         *
bitset<15>/set(i)                               1599258      1462952      1.09
bitset<15>/test                                 1599275      1599224      1.00

bitset<35>/>>=/1                                2599266      1933376      1.34         *
bitset<35>/count                                2599240      2592559      1.00
bitset<35>/flip                                 1693124      1199188      1.41         *
bitset<35>/reset                                1399406       999201      1.40         *
bitset<35>/set()                                1599403      1199205      1.33         *
bitset<35>/set(i)                               1599241      1599190      1.00
bitset<35>/test                                 1599250      1599232      1.00

bitset<75>/>>=/1                                4199332      4199213      1.00
bitset<75>/count                                2999497      2199341      1.36         *
bitset<75>/flip                                 2399499      1830178      1.31         *
bitset<75>/reset                                2199468      1199197      1.83         *
bitset<75>/set()                                1999387      1199851      1.67         *
bitset<75>/set(i)                               1599266      1599198      1.00
bitset<75>/test                                 1599241      1662651      0.96

deque<ValuePair>/erase                         90444165     37113253      2.44         *
deque<ValuePair>/insert                        93299349     36175167      2.58         *
deque<ValuePair>/iteration                      2756414      2122076      1.30         *
deque<ValuePair>/operator[]                     5117969      4632075      1.10
deque<ValuePair>/push_back                     30300757      3060357      9.90         *
deque<ValuePair>/push_front                    25498529      2808392      9.08         *
deque<ValuePair>/sort                         142283047    111292464      1.28         *

hash_map<string, uint32_t>/clear                 146769       389699      0.38         *
hash_map<string, uint32_t>/count               13059434      3460324      3.77         *
hash_map<string, uint32_t>/erase pos             184246       331925      0.56         *
hash_map<string, uint32_t>/erase range           382432       167237      2.29         *
hash_map<string, uint32_t>/erase val            6187898      3302114      1.87         *
hash_map<string, uint32_t>/find                11289369      3459024      3.26         *
hash_map<string, uint32_t>/find_as/char*       13559192      3662387      3.70         *
hash_map<string, uint32_t>/insert              17514012     14095176      1.24         *
hash_map<string, uint32_t>/iteration             801014       218450      3.67         *
hash_map<string, uint32_t>/operator[]          11457065      3690385      3.10         *

hash_map<uint32_t, TestObject>/clear             141865       265379      0.53         *
hash_map<uint32_t, TestObject>/count            1766045       703613      2.51         *
hash_map<uint32_t, TestObject>/erase pos         172337       218458      0.79         *
hash_map<uint32_t, TestObject>/erase range       537846       102340      5.26         *
hash_map<uint32_t, TestObject>/erase val        2220132      1441787      1.54         *
hash_map<uint32_t, TestObject>/find             1612994      1043953      1.55         *
hash_map<uint32_t, TestObject>/insert           7141547      4348056      1.64         *
hash_map<uint32_t, TestObject>/iteration         199512       169328      1.18         *
hash_map<uint32_t, TestObject>/operator[]       1831733      1519707      1.21         *

heap (uint32_t[])/make_heap                     3366247      1949093      1.73         *
heap (uint32_t[])/pop_heap                     57280514     53779440      1.07
heap (uint32_t[])/push_heap                     9700217      7582935      1.28         *
heap (uint32_t[])/sort_heap                    47227751     46131948      1.02

heap (vector<TestObject>)/make_heap            11458442     11510819      1.00
heap (vector<TestObject>)/pop_heap            122897267    119061132      1.03
heap (vector<TestObject>)/push_heap            21688481     21176220      1.02
heap (vector<TestObject>)/sort_heap            90867380     88869523      1.02

list<TestObject>/ctor(it)                      74591104     69845817      1.07
list<TestObject>/ctor(n)                        6243998      5838582      1.07
list<TestObject>/erase                        299509298    206013676      1.45         *
list<TestObject>/find                          40927185     14514243      2.82         *
list<TestObject>/insert                        71277251     47234534      1.51         *
list<TestObject>/push_back                     73780527     44116725      1.67         *
list<TestObject>/remove                       786197776    326434612      2.41         *
list<TestObject>/reverse                       49283128     25029678      1.97         *
list<TestObject>/size/1                          159741       139400      1.15         *
list<TestObject>/size/10                         159324       346579      0.46         *   EASTL intentionally implements list::size as O(n).
list<TestObject>/size/100                        159188     97235419      0.00         *   EASTL intentionally implements list::size as O(n).
list<TestObject>/splice                        63548584     19322931      3.29         *

map<TestObject, uint32_t>/clear                  167408       170501      0.98
map<TestObject, uint32_t>/count                10213685      4748346      2.15         *
map<TestObject, uint32_t>/equal_range           9515053      5677558      1.68         *
map<TestObject, uint32_t>/erase/key             6646260      4302300      1.54         *
map<TestObject, uint32_t>/erase/pos              297135       327938      0.91             MS uses a code bloating implementation of erase.
map<TestObject, uint32_t>/erase/range            148614       163702      0.91
map<TestObject, uint32_t>/find                  5637531      4767055      1.18         *
map<TestObject, uint32_t>/insert                9591128      9030349      1.06
map<TestObject, uint32_t>/iteration              323595       325261      0.99
map<TestObject, uint32_t>/lower_bound           5398239      4784089      1.13         *
map<TestObject, uint32_t>/operator[]            5631250      5141166      1.10
map<TestObject, uint32_t>/upper_bound           5436336      4762431      1.14         *

set<uint32_t>/clear                              155983       156026      1.00
set<uint32_t>/count                             9635965      4392146      2.19         *
set<uint32_t>/equal_range                       8504157      5247832      1.62         *
set<uint32_t>/erase range                        140488       119408      1.18         *
set<uint32_t>/erase/pos                          260678       286697      0.91             MS uses a code bloating implementation of erase.
set<uint32_t>/erase/val                         6008225      4012825      1.50         *
set<uint32_t>/find                              5145432      4381945      1.17         *
set<uint32_t>/insert                            8087129      8697251      0.93
set<uint32_t>/iteration                          271507       304538      0.89         *
set<uint32_t>/lower_bound                       4666228      4404250      1.06
set<uint32_t>/upper_bound                       4623600      4402974      1.05

sort/q_sort/TestObject[]                        9596169      5578652      1.72         *
sort/q_sort/TestObject[]/sorted                  602463      1016132      0.59         *
sort/q_sort/vector<TestObject>                  9674828      5430199      1.78         *
sort/q_sort/vector<TestObject>/sorted            606908      1111647      0.55         *
sort/q_sort/vector<ValuePair>                   6284194      3423452      1.84         *
sort/q_sort/vector<ValuePair>/sorted             711629       569364      1.25         *
sort/q_sort/vector<uint32>                      5453379      2916146      1.87         *
sort/q_sort/vector<uint32>/sorted                537047       419144      1.28         *

string<char16_t>/compare                      435083295    251985824      1.73         *
string<char16_t>/erase/pos,n                    3454842      3451858      1.00
string<char16_t>/find/p,pos,n                 401954723    165298157      2.43         *
string<char16_t>/find_first_not_of/p,pos,n       131452        65374      2.01         *
string<char16_t>/find_first_of/p,pos,n         11657444      4144515      2.81         *
string<char16_t>/find_last_of/p,pos,n           1604248       567571      2.83         *
string<char16_t>/insert/pos,p                   3398734      3355460      1.01
string<char16_t>/iteration                    218856504    218771844      1.00
string<char16_t>/operator[]                      714161       240023      2.98         *
string<char16_t>/push_back                     34968235      2444897     14.30         *
string<char16_t>/replace/pos,n,p,n              4226693      4198498      1.01
string<char16_t>/reserve                        1901765       390805      4.87         *
string<char16_t>/rfind/p,pos,n                   195483       150985      1.29         *
string<char16_t>/size                             11169        11245      0.99
string<char16_t>/swap                           1459280       419807      3.48         *

string<char8_t>/compare                        63071275     77209580      0.82         *
string<char8_t>/erase/pos,n                     2008652      1944494      1.03
string<char8_t>/find/p,pos,n                  123201023    167536164      0.74         *
string<char8_t>/find_first_not_of/p,pos,n         93372        67864      1.38         *
string<char8_t>/find_first_of/p,pos,n           7542492      3375758      2.23         *
string<char8_t>/find_last_of/p,pos,n             933972       583576      1.60         *
string<char8_t>/insert/pos,p                    1737213      1750847      0.99
string<char8_t>/iteration                        893834       899130      0.99
string<char8_t>/operator[]                       817879       313437      2.61         *
string<char8_t>/push_back                      20857734      2004410     10.41         *
string<char8_t>/replace/pos,n,p,n               2578696      2607655      0.99
string<char8_t>/reserve                          915127        85289     10.73         *
string<char8_t>/rfind/p,pos,n                    196103       148894      1.32         *
string<char8_t>/size                              11619        11220      1.04
string<char8_t>/swap                            1461056       419874      3.48         *

vector<uint64>/erase                           55235116     55284587      1.00
vector<uint64>/insert                          55166046     55142755      1.00
vector<uint64>/iteration                         553954       509719      1.09
vector<uint64>/operator[]                       1284239       798516      1.61         *
vector<uint64>/push_back                        5399549      3867959      1.40         *
vector<uint64>/sort                            43636314     42619952      1.02
\n\n\n\n\n\n
\n\n\n\n\n\n

\n \n Win32.VC71.STLPort.Debug

\n
\n
EASTL version: 0.96.00
Platform: Windows on X86
Compiler: Microsoft Visual C++ compiler, version 1310
Allocator: PPMalloc::GeneralAllocatorDebug. Thread safety enabled.
Build: Debug. Inlining disabled. STL debug features disabled.

Values are times to complete tests; smaller values are better.
Alarm indicates a greater than 10% difference.

Test                                            STLPort        EASTL     Ratio     Alarm
----------------------------------------------------------------------------------------
algorithm/adj_find/vector<TestObject>           5661170      5689517      1.00
algorithm/copy/vector<LargePOD>                 5573815      5124428      1.09
algorithm/copy/vector<uint32_t>                  148273       125782      1.18         *
algorithm/copy_backward/vector<LargePOD>        5429791      4834510      1.12         *
algorithm/copy_backward/vector<uint32_t>         156765       163038      0.96
algorithm/count/vector<uint64_t>                2730922      2730072      1.00
algorithm/equal_range/vector<uint64_t>        639366489    452896251      1.41         *
algorithm/fill/bool[]                           1299326        27361     47.49         *
algorithm/fill/char[]/'d'                         27378        27361      1.00
algorithm/fill/vector<char>/'d'                   34459        27361      1.26         *
algorithm/fill/vector<char>/0                   1299224        27361     47.48         *
algorithm/fill/vector<uint64_t>                 1400647      1400145      1.00
algorithm/fill/vector<void*>                    1308779      1309085      1.00
algorithm/fill_n/bool[]                         1299156        27352     47.50         *
algorithm/fill_n/char[]                         1299258        27369     47.47         *
algorithm/fill_n/vector<uint64_t>               1451162      1313632      1.10
algorithm/find_end/string/end                  13089999      2526412      5.18         *
algorithm/find_end/string/middle               12627412     20190101      0.63         *
algorithm/find_end/string/none                 12704185     40728803      0.31         *
algorithm/lex_cmp/schar[]                       1749844       195806      8.94         *
algorithm/lex_cmp/vector<TestObject>            5060968      4799882      1.05
algorithm/lex_cmp/vector<uchar>                 1668354       189490      8.80         *
algorithm/lower_bound/vector<TestObject>      450240945    353437573      1.27         *
algorithm/min_element/vector<TestObject>        5861744      5326371      1.10
algorithm/rand_shuffle/vector<uint64_t>        40780449     45780090      0.89         *
algorithm/reverse/list<TestObject>              2657678      2130627      1.25         *
algorithm/reverse/vector<TestObject>            2666424      2124889      1.25         *
algorithm/search/string<char>                   3110379      3613460      0.86         *
algorithm/search_n/string<char>                 3061665      1521261      2.01         *
algorithm/unique/vector<TestObject>            12423684      9485439      1.31         *
algorithm/unique/vector<uint32_t>               3718699      1726596      2.15         *
algorithm/unique/vector<uint64_t>               6205110      4591631      1.35         *
algorithm/upper_bound/vector<uint32_t>        185391094    139336317      1.33         *

bitset<1500>/>>=/1                            120666960     92449816      1.31         *   STLPort is broken, neglects wraparound check.
bitset<1500>/count                            201709793     52874726      3.81         *
bitset<1500>/flip                              87360297     81737071      1.07
bitset<1500>/reset                             23950178     77390323      0.31         *
bitset<1500>/set()                             84608107     76912011      1.10
bitset<1500>/set(i)                            18023620     12229604      1.47         *
bitset<1500>/test                              18006553     13276396      1.36         *

bitset<15>/>>=/1                               11935904      6012695      1.99         *   STLPort is broken, neglects wraparound check.
bitset<15>/count                                9368581      6022742      1.56         *
bitset<15>/flip                                11600706      6533635      1.78         *
bitset<15>/reset                                5830957      5874690      0.99
bitset<15>/set()                               11695328      5701621      2.05         *
bitset<15>/set(i)                              16363205     12570216      1.30         *
bitset<15>/test                                16743172     13201452      1.27         *

bitset<35>/>>=/1                               22950918      6774457      3.39         *   STLPort is broken, neglects wraparound check.
bitset<35>/count                               12655309     11736256      1.08
bitset<35>/flip                                13738575      5800042      2.37         *
bitset<35>/reset                               15561434      5800510      2.68         *
bitset<35>/set()                               13564283      5600709      2.42         *
bitset<35>/set(i)                              18519689     12199973      1.52         *
bitset<35>/test                                18000569     13103566      1.37         *

bitset<75>/>>=/1                               25579525     16669664      1.53         *   STLPort is broken, neglects wraparound check.
bitset<75>/count                               18740698      8480492      2.21         *
bitset<75>/flip                                13555630      8300335      1.63         *
bitset<75>/reset                               15200133      8200000      1.85         *
bitset<75>/set()                               14408112      8001959      1.80         *
bitset<75>/set(i)                              18137741     12374257      1.47         *
bitset<75>/test                                18422135     13100038      1.41         *

deque<ValuePair>/erase                        651933790    326443043      2.00         *
deque<ValuePair>/insert                       659786183    333304660      1.98         *
deque<ValuePair>/iteration                     23734592     16173706      1.47         *
deque<ValuePair>/operator[]                    59126816     23911774      2.47         *
deque<ValuePair>/push_back                     58056988     31859266      1.82         *
deque<ValuePair>/push_front                    57780891     31743199      1.82         *
deque<ValuePair>/sort                         818414195    596568113      1.37         *

hash_map<string, uint32_t>/clear                3422133      2204517      1.55         *
hash_map<string, uint32_t>/count                9869545      8624924      1.14         *
hash_map<string, uint32_t>/erase pos            3256350      2069299      1.57         *
hash_map<string, uint32_t>/erase range          3230203      1151392      2.81         *
hash_map<string, uint32_t>/erase val           16860362     15939778      1.06
hash_map<string, uint32_t>/find                10286971      9920910      1.04
hash_map<string, uint32_t>/find_as/char*      118136025      9458468     12.49         *
hash_map<string, uint32_t>/insert             188948336    174490082      1.08
hash_map<string, uint32_t>/iteration            4037049      2021036      2.00         *
hash_map<string, uint32_t>/operator[]          11472127     12887699      0.89         *

hash_map<uint32_t, TestObject>/clear            2522264      1331848      1.89         *
hash_map<uint32_t, TestObject>/count            3210739      2897063      1.11         *
hash_map<uint32_t, TestObject>/erase pos        1862281      1304783      1.43         *
hash_map<uint32_t, TestObject>/erase range       698079       579606      1.20         *
hash_map<uint32_t, TestObject>/erase val        8806722      7041298      1.25         *
hash_map<uint32_t, TestObject>/find             3604875      4709645      0.77         *
hash_map<uint32_t, TestObject>/insert          40785711     40376342      1.01
hash_map<uint32_t, TestObject>/iteration        3064088      1508834      2.03         *
hash_map<uint32_t, TestObject>/operator[]       6053742      8176906      0.74         *

heap (uint32_t[])/make_heap                     5799813      5738596      1.01
heap (uint32_t[])/pop_heap                    113775168    102076134      1.11         *
heap (uint32_t[])/push_heap                    21649151     16854845      1.28         *
heap (uint32_t[])/sort_heap                    97535213     83290735      1.17         *

heap (vector<TestObject>)/make_heap            22215557     22277063      1.00
heap (vector<TestObject>)/pop_heap            275392171    277340039      0.99
heap (vector<TestObject>)/push_heap            51479442     47342577      1.09
heap (vector<TestObject>)/sort_heap           214474736    218497540      0.98

list<TestObject>/ctor(it)                     767753795    753421427      1.02
list<TestObject>/ctor(n)                       74185322     73386245      1.01
list<TestObject>/erase                       1021003824   1033873589      0.99
list<TestObject>/find                          77666072     74917622      1.04
list<TestObject>/insert                       788071150    774188737      1.02
list<TestObject>/push_back                    760490154    737327348      1.03
list<TestObject>/remove                      1682511938   1434771006      1.17         *
list<TestObject>/reverse                       87237327     80394623      1.09
list<TestObject>/size/1                         3828111       599530      6.39         *
list<TestObject>/size/10                        9600605      1329535      7.22         *   EASTL intentionally implements list::size as O(n).
list<TestObject>/size/100                      62952334     15022551      4.19         *   EASTL intentionally implements list::size as O(n).
list<TestObject>/splice                        96536412     60804817      1.59         *

map<TestObject, uint32_t>/clear                 1142127      1099066      1.04
map<TestObject, uint32_t>/count                19659726     14647548      1.34         *
map<TestObject, uint32_t>/equal_range          36680687     18219086      2.01         *
map<TestObject, uint32_t>/erase/key            28892154     16037774      1.80         *
map<TestObject, uint32_t>/erase/pos             1209643      1185495      1.02
map<TestObject, uint32_t>/erase/range            715402       670539      1.07
map<TestObject, uint32_t>/find                 21020992     13429575      1.57         *
map<TestObject, uint32_t>/insert               59530871     51120640      1.16         *
map<TestObject, uint32_t>/iteration              972825      1191946      0.82         *
map<TestObject, uint32_t>/lower_bound          18852651     12495034      1.51         *
map<TestObject, uint32_t>/operator[]           22889573     16676736      1.37         *
map<TestObject, uint32_t>/upper_bound          18603584     12406922      1.50         *

set<uint32_t>/clear                              919555       882988      1.04
set<uint32_t>/count                            17561110     12461084      1.41         *
set<uint32_t>/equal_range                      31522488     15230282      2.07         *
set<uint32_t>/erase range                        687582       564765      1.22         *
set<uint32_t>/erase/pos                         1044352      1045355      1.00
set<uint32_t>/erase/val                        25525304     12940774      1.97         *
set<uint32_t>/find                             17140751     10704866      1.60         *
set<uint32_t>/insert                           56035051     45555664      1.23         *
set<uint32_t>/iteration                          682669       640831      1.07
set<uint32_t>/lower_bound                      16339932     10475740      1.56         *
set<uint32_t>/upper_bound                      17779424     10652599      1.67         *

sort/q_sort/TestObject[]                       17000866     14823515      1.15         *
sort/q_sort/TestObject[]/sorted                 6658559      3263328      2.04         *
sort/q_sort/vector<TestObject>                 17476629     14953285      1.17         *
sort/q_sort/vector<TestObject>/sorted           6667034      3327435      2.00         *
sort/q_sort/vector<ValuePair>                  15391357     10820848      1.42         *
sort/q_sort/vector<ValuePair>/sorted            6617122      3232949      2.05         *
sort/q_sort/vector<uint32>                      8343906      6014846      1.39         *
sort/q_sort/vector<uint32>/sorted               3039430      1003127      3.03         *

string<char16_t>/compare                     1489709846    532664000      2.80         *
string<char16_t>/erase/pos,n                    3528690      3439864      1.03
string<char16_t>/find/p,pos,n                2521448321    443752189      5.68         *
string<char16_t>/find_first_not_of/p,pos,n       661206       137419      4.81         *
string<char16_t>/find_first_of/p,pos,n         54746434      8521335      6.42         *
string<char16_t>/find_last_of/p,pos,n          10607778      1212414      8.75         *
string<char16_t>/insert/pos,p                   3445016      3360126      1.03
string<char16_t>/iteration                    580955636    579452556      1.00
string<char16_t>/operator[]                     2206353      1987809      1.11         *
string<char16_t>/push_back                     22421368      6007808      3.73         *
string<char16_t>/replace/pos,n,p,n              5138454      4464786      1.15         *
string<char16_t>/reserve                     4922413418       335622    100.00         *
string<char16_t>/rfind/p,pos,n                  1440308       380578      3.78         *
string<char16_t>/size                             25355        25398      1.00
string<char16_t>/swap                           2122704      1490823      1.42         *

string<char8_t>/compare                        77222134     77443134      1.00
string<char8_t>/erase/pos,n                     1965344      1956521      1.00
string<char8_t>/find/p,pos,n                 2468091951    474205522      5.20         *
string<char8_t>/find_first_not_of/p,pos,n        660960       130211      5.08         *
string<char8_t>/find_first_of/p,pos,n          55020899      9240171      5.95         *
string<char8_t>/find_last_of/p,pos,n           10576210      1239053      8.54         *
string<char8_t>/insert/pos,p                    1822756      1750880      1.04
string<char8_t>/iteration                       2617889      2540148      1.03
string<char8_t>/operator[]                      2254794      2256443      1.00
string<char8_t>/push_back                      12463022      5210321      2.39         *
string<char8_t>/replace/pos,n,p,n               3744862      2855260      1.31         *
string<char8_t>/reserve                      1372046888       218815    100.00         *
string<char8_t>/rfind/p,pos,n                   1446232       366902      3.94         *
string<char8_t>/size                              26859        25431      1.06
string<char8_t>/swap                            2123350      1490509      1.42         *

vector<uint64>/erase                           55164013     56417449      0.98
vector<uint64>/insert                          55872973     56432664      0.99
vector<uint64>/iteration                        1329102      1324623      1.00
vector<uint64>/operator[]                       5264738      3136746      1.68         *
vector<uint64>/push_back                       14903245     13171175      1.13         *
vector<uint64>/sort                            88429095     88542171      1.00
\n\n\n\n\n\n
\n\n\n\n\n\n

\n\n\n\n\n Win32.VC71.STLPort.Release

\n
\n
EASTL version: 0.96.00
Platform: Windows on X86
Compiler: Microsoft Visual C++ compiler, version 1310
Allocator: PPMalloc::GeneralAllocator. Thread safety enabled.
Build: Full optimization. Inlining enabled.

Values are times to complete tests; smaller values are better.
Alarm indicates a greater than 10% difference.

Test                                            STLPort        EASTL     Ratio     Alarm
----------------------------------------------------------------------------------------
algorithm/adj_find/vector<TestObject>           2741046      2731441      1.00
algorithm/copy/vector<LargePOD>                 6065923      5085142      1.19         *
algorithm/copy/vector<uint32_t>                  158304       165555      0.96
algorithm/copy_backward/vector<LargePOD>        4710258      4896476      0.96
algorithm/copy_backward/vector<uint32_t>         146030       142630      1.02
algorithm/count/vector<uint64_t>                1395921      1406334      0.99
algorithm/equal_range/vector<uint64_t>        211692764    118969493      1.78         *
algorithm/fill/bool[]                            366078        33737     10.85         *
algorithm/fill/char[]/'d'                         33736        33771      1.00
algorithm/fill/vector<char>/'d'                   28466        33720      0.84         *
algorithm/fill/vector<char>/0                    366086        33728     10.85         *
algorithm/fill/vector<uint64_t>                  466250       401591      1.16         *
algorithm/fill/vector<void*>                     521603       693481      0.75         *
algorithm/fill_n/bool[]                          599709        33762     17.76         *
algorithm/fill_n/char[]                          599573        33711     17.79         *
algorithm/fill_n/vector<uint64_t>                434971      1374084      0.32         *
algorithm/find_end/string/end                   1494742        85349     17.51         *
algorithm/find_end/string/middle                1480700       687208      2.15         *
algorithm/find_end/string/none                  1540540      1546431      1.00
algorithm/lex_cmp/schar[]                        921638       178797      5.15         *
algorithm/lex_cmp/vector<TestObject>            2623559      2643551      0.99
algorithm/lex_cmp/vector<uchar>                  960899       183608      5.23         *
algorithm/lower_bound/vector<TestObject>       60630534     56531528      1.07
algorithm/min_element/vector<TestObject>        4209022      2768527      1.52         *
algorithm/rand_shuffle/vector<uint64_t>        13762010     15969052      0.86         *
algorithm/reverse/list<TestObject>               673387       731825      0.92
algorithm/reverse/vector<TestObject>             634576       754511      0.84         *
algorithm/search/string<char>                   1262599      1387608      0.91
algorithm/search_n/string<char>                 1166242       458592      2.54         *
algorithm/unique/vector<TestObject>             4912193      5336317      0.92
algorithm/unique/vector<uint32_t>                809387       809081      1.00
algorithm/unique/vector<uint64_t>               4371814      2414255      1.81         *
algorithm/upper_bound/vector<uint32_t>         31899081     29555596      1.08

bitset<1500>/>>=/1                             63308136     40553560      1.56         *   STLPort is broken, neglects wraparound check.
bitset<1500>/count                             62523178     22799473      2.74         *
bitset<1500>/flip                              20302845     19919232      1.02
bitset<1500>/reset                             18892015     15403148      1.23         *
bitset<1500>/set()                             15803302     17322192      0.91
bitset<1500>/set(i)                             2799271      2999310      0.93
bitset<1500>/test                               2999293      2799262      1.07

bitset<15>/>>=/1                                1199239      3199256      0.37         *   STLPort is broken, neglects wraparound check.
bitset<15>/count                                3599461      2199231      1.64         *
bitset<15>/flip                                 1199231      1199188      1.00
bitset<15>/reset                                1199188      1199180      1.00
bitset<15>/set()                                1199214      1199180      1.00
bitset<15>/set(i)                               2599257      1399262      1.86         *
bitset<15>/test                                 2599274      2599283      1.00

bitset<35>/>>=/1                                6643974      4599239      1.44         *   STLPort is broken, neglects wraparound check.
bitset<35>/count                                5151331      5399438      0.95
bitset<35>/flip                                 1999404      1199273      1.67         *
bitset<35>/reset                                9805285      1399313      7.01         *
bitset<35>/set()                                2799279      1199248      2.33         *
bitset<35>/set(i)                               2799246      1599241      1.75         *
bitset<35>/test                                 2999234      2999251      1.00

bitset<75>/>>=/1                                7002045      6999333      1.00             STLPort is broken, neglects wraparound check.
bitset<75>/count                                5999351      3002259      2.00         *
bitset<75>/flip                                 3599334      3599163      1.00
bitset<75>/reset                                9799344      3399218      2.88         *
bitset<75>/set()                                3599232      3599062      1.00
bitset<75>/set(i)                               2799228      1599284      1.75         *
bitset<75>/test                                 2999250      2799339      1.07

deque<ValuePair>/erase                        127108651    115258113      1.10
deque<ValuePair>/insert                       137727889    116552332      1.18         *
deque<ValuePair>/iteration                      7144182      6009899      1.19         *
deque<ValuePair>/operator[]                    34241222     20535039      1.67         *
deque<ValuePair>/push_back                      6585800      3932126      1.67         *
deque<ValuePair>/push_front                     6805865      3993513      1.70         *
deque<ValuePair>/sort                         395352323    348778188      1.13         *

hash_map<string, uint32_t>/clear                 426640       447015      0.95
hash_map<string, uint32_t>/count                4359344      3883089      1.12         *
hash_map<string, uint32_t>/erase pos             584392       458142      1.28         *
hash_map<string, uint32_t>/erase range           221034       196078      1.13         *
hash_map<string, uint32_t>/erase val            3539867      3790813      0.93
hash_map<string, uint32_t>/find                 3966831      3811910      1.04
hash_map<string, uint32_t>/find_as/char*       11591612      4243710      2.73         *
hash_map<string, uint32_t>/insert              16763887     16719194      1.00
hash_map<string, uint32_t>/iteration             909968       478609      1.90         *
hash_map<string, uint32_t>/operator[]           4360041      4108313      1.06

hash_map<uint32_t, TestObject>/clear             302634       283722      1.07
hash_map<uint32_t, TestObject>/count             916487       907426      1.01
hash_map<uint32_t, TestObject>/erase pos         388042       321385      1.21         *
hash_map<uint32_t, TestObject>/erase range       122680       116280      1.06
hash_map<uint32_t, TestObject>/erase val        1710931      1729529      0.99
hash_map<uint32_t, TestObject>/find             1089462      1346527      0.81         *
hash_map<uint32_t, TestObject>/insert           4560310      5072350      0.90         *
hash_map<uint32_t, TestObject>/iteration         960117       495354      1.94         *
hash_map<uint32_t, TestObject>/operator[]       1872830      1890595      0.99

heap (uint32_t[])/make_heap                     3528418      3327257      1.06
heap (uint32_t[])/pop_heap                     63243859     61011853      1.04
heap (uint32_t[])/push_heap                    11602424     10045869      1.15         *
heap (uint32_t[])/sort_heap                    52965362     48744729      1.09

heap (vector<TestObject>)/make_heap            13191456     13089711      1.01
heap (vector<TestObject>)/pop_heap            148555656    144787742      1.03
heap (vector<TestObject>)/push_heap            28696689     26618830      1.08
heap (vector<TestObject>)/sort_heap           112473989    114018643      0.99

list<TestObject>/ctor(it)                      80186731     74006287      1.08
list<TestObject>/ctor(n)                        6232311      6128007      1.02
list<TestObject>/erase                        344556374    212877808      1.62         *
list<TestObject>/find                          39859075     14591347      2.73         *
list<TestObject>/insert                        86935153     56138233      1.55         *
list<TestObject>/push_back                     79569180     46700641      1.70         *
list<TestObject>/remove                       785786758    324201016      2.42         *
list<TestObject>/reverse                       45248186     24852759      1.82         *
list<TestObject>/size/1                          219844       219496      1.00
list<TestObject>/size/10                         519563       519579      1.00             EASTL intentionally implements list::size as O(n).
list<TestObject>/size/100                       4567194    101230266      0.05         *   EASTL intentionally implements list::size as O(n).
list<TestObject>/splice                        68321087     23601687      2.89         *

map<TestObject, uint32_t>/clear                  168011       180540      0.93
map<TestObject, uint32_t>/count                 4830439      5139287      0.94
map<TestObject, uint32_t>/equal_range           8700090      6158531      1.41         *
map<TestObject, uint32_t>/erase/key             6696776      4617038      1.45         *
map<TestObject, uint32_t>/erase/pos              309273       333183      0.93
map<TestObject, uint32_t>/erase/range            137419       136068      1.01
map<TestObject, uint32_t>/find                  4773498      4931352      0.97
map<TestObject, uint32_t>/insert                9651877      9311699      1.04
map<TestObject, uint32_t>/iteration              372946       416364      0.90         *
map<TestObject, uint32_t>/lower_bound           4784234      4915797      0.97
map<TestObject, uint32_t>/operator[]            5040254      5183147      0.97
map<TestObject, uint32_t>/upper_bound           4724292      4915984      0.96

set<uint32_t>/clear                              165300       173289      0.95
set<uint32_t>/count                             4958654      4885086      1.02
set<uint32_t>/equal_range                       8434134      5698681      1.48         *
set<uint32_t>/erase range                        145554       133960      1.09
set<uint32_t>/erase/pos                          299914       324760      0.92
set<uint32_t>/erase/val                         6506155      4335034      1.50         *
set<uint32_t>/find                              4866879      4556043      1.07
set<uint32_t>/insert                            8340523      8957257      0.93
set<uint32_t>/iteration                          294465       343442      0.86         *
set<uint32_t>/lower_bound                       4548095      4756498      0.96
set<uint32_t>/upper_bound                       4559196      4521498      1.01

sort/q_sort/TestObject[]                        7316766      7013894      1.04
sort/q_sort/TestObject[]/sorted                 1668439      1332885      1.25         *
sort/q_sort/vector<TestObject>                  7331530      7017260      1.04
sort/q_sort/vector<TestObject>/sorted           1601629      1247120      1.28         *
sort/q_sort/vector<ValuePair>                   7071643      7067869      1.00
sort/q_sort/vector<ValuePair>/sorted            2136390      1703799      1.25         *
sort/q_sort/vector<uint32>                      3292891      2943627      1.12         *
sort/q_sort/vector<uint32>/sorted                653693       473612      1.38         *

string<char16_t>/compare                      356579259    432760228      0.82         *
string<char16_t>/erase/pos,n                    3430422      3428645      1.00
string<char16_t>/find/p,pos,n                 229263402    225830975      1.02
string<char16_t>/find_first_not_of/p,pos,n       187391        81404      2.30         *
string<char16_t>/find_first_of/p,pos,n          4411831      4413532      1.00
string<char16_t>/find_last_of/p,pos,n            731655       726155      1.01
string<char16_t>/insert/pos,p                   3408628      3319726      1.03
string<char16_t>/iteration                    309993861    310333547      1.00
string<char16_t>/operator[]                      580839       579904      1.00
string<char16_t>/push_back                      3983338      2975553      1.34         *
string<char16_t>/replace/pos,n,p,n              4361095      4211504      1.04
string<char16_t>/reserve                      935141729       247010    100.00         *
string<char16_t>/rfind/p,pos,n                   248956       223397      1.11         *
string<char16_t>/size                             13311        13107      1.02
string<char16_t>/swap                            519129       579445      0.90         *

string<char8_t>/compare                        76695559     76828015      1.00
string<char8_t>/erase/pos,n                     1951566      1947282      1.00
string<char8_t>/find/p,pos,n                  185878944    185605039      1.00
string<char8_t>/find_first_not_of/p,pos,n        196877        81600      2.41         *
string<char8_t>/find_first_of/p,pos,n           4147685      4145356      1.00
string<char8_t>/find_last_of/p,pos,n             605897       598222      1.01
string<char8_t>/insert/pos,p                    1781592      1768264      1.01
string<char8_t>/iteration                        921502       921272      1.00
string<char8_t>/operator[]                       361250       359873      1.00
string<char8_t>/push_back                       3363288      2530493      1.33         *
string<char8_t>/replace/pos,n,p,n               2682600      2633130      1.02
string<char8_t>/reserve                       672517501        78387    100.00         *
string<char8_t>/rfind/p,pos,n                    226202       200013      1.13         *
string<char8_t>/size                              11280        11109      1.02
string<char8_t>/swap                             519393       559759      0.93

vector<uint64>/erase                           55184856     55192217      1.00
vector<uint64>/insert                          56764267     55682726      1.02
vector<uint64>/iteration                         423122       424039      1.00
vector<uint64>/operator[]                       1189397       860991      1.38         *
vector<uint64>/push_back                        5626609      4027317      1.40         *
vector<uint64>/sort                            49227036     49231362      1.00
\n\n\n\n\n\n
\n\n\n\n\n\n

\n\n\n\n\n\n\n\n\n
\n\n\n\n
\nEnd of document
\n\n\n\n
\n\n\n\n
\n\n\n\n
\n\n\n\n
\n\n\n\n\n\n" }, { "path": "doc/html/EASTL Best Practices.html", "content": "\n\n\n EASTL Best Practices\n\t\n\t\n\t\n \n \n\n\n

EASTL Best Practices

\n

In this document we discuss best practices for using EASTL. The primary emphasis is on performance with a secondary\n emphasis on correctness and maintainability. Some best practices apply only to some situations, and these will be\n pointed out as we go along. In order to be easily digestible, we present these practices as a list of items in the tone\n of the Effective C++ series of books.

\n

Summary

\n

The descriptions here are intentionally terse; this is to make them easier to visually scan.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n \n \n\n\n
1Consider intrusive containers.
2Consider fixed-size containers.
3Consider custom allocators.
4Consider hash tables instead of maps.
5Consider a vector_map (a.k.a. sorted vector) for unchanging data.
6Consider slist instead of list.
7Avoid redundant end() and size() in loops.
8Iterate containers instead of using operator[].
9Learn to use the string class appropriately.
10Cache list size if you want size() to be O(1).
11Use empty() instead of size() when possible.
12Know your container efficiencies.
13Use vector::reserve.
14Use vector::set_capacity to trim memory usage.
15Use swap() instead of a manually implemented version.
16Consider storing pointers instead of objects.
17Consider smart pointers instead of raw pointers.
18Use iterator pre-increment instead of post-increment.
19Make temporary references so the code can be traced/debugged.
20Consider bitvector or bitset instead of vector<bool>.
21Vectors can be treated as contiguous memory.
22Search hash_map<string> via find_as() instead of find().
23Take advantage of type_traits (e.g. EASTL_DECLARE_TRIVIAL_RELOCATE).
24Name containers to track memory usage.
25Learn the algorithms.
26Pass and return containers by reference instead of value.
27Consider using reset_lose_memory() for fast container teardown.
28Consider using fixed_substring instead of copying strings.
29Consider using vector::push_back(void).
\n

Detail

\n

1\n Consider intrusive containers.\n

\n

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.

\n

To create an intrusive_list container, you can use the following code:

\n

class Widget : public intrusive_list_node
\n{ };
\n
\nintrusive_list<Widget> widgetList;
\nwidgetList.push_back(someWidget);

\n

\n

2\n Consider fixed-size containers.\n

\n

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."

\n

EASTL fixed containers include:

\n
    \n
  • fixed_list
    • \n
  • fixed_slist
    • \n
  • fixed_vector
    • \n
  • fixed_string
    • \n
  • fixed_map
    • \n
  • fixed_multimap
    • \n
  • fixed_set
    • \n
  • fixed_multiset
    • \n
  • fixed_hash_map
    • \n
  • fixed_hash_multimap
    • \n
  • fixed_hash_set
    • \n
  • fixed_hash_multiset
    • \n
\n

To create a fixed_set, you can use the following code:

\n

fixed_set<int, 25> intSet; // Create a set capable of holding 25 elements.
\nintSet.push_back(37);

\n

\n

3\n Consider custom allocators.\n

\n

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.

\n

To create a list container that uses your custom allocator and uses block naming, you can use the following code:

\n

list<int> intList(pSomeAllocator, "graphics/intList");
\nintList.push_back(37);

\n

4\nConsider hash tables instead of maps.

\n

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.

\n

To make a hash_map (dictionary) of integers to strings, you can use the following code:

\n

hash_map<int, const char*> stringTable;
\nstringTable[37] = "hello";

\n

5\n Consider a vector_map (a.k.a. sorted vector) for unchanging data.\n

\n

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.

\n

To make a vector_set, you can use the following code:

\n

vector_set<int> intSet(16); // Create a vector_set with an initial capacity of 16.
\nintSet.insert(37);

\n

Note that you can use containers other than vector to implement vector_set. Here's how you do it with deque:

\n

vector_set<int, less<int>, EASTLAllocatorType, deque<int> > intSet;
\nintSet.insert(37);

\n

6\n Consider slist instead of list.\n

\n

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.

\n

To make an slist, you can use the following code:

\n

slist<int> intSlist;
\nintSlist.push_front(37);

\n

7\nAvoid redundant end() and size() in loops.

\n

Instead of writing code like this:
\n

\n
for(deque<int>::iterator it = d.begin(); it != d.end(); ++it)
\n    ...
\nwrite code like this:
\n\n
for(deque<int>::iterator it = d.begin(), itEnd = d.end(); it != itEnd; ++it)
\n    ...
\nThe 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.
\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
Constant beginNon-constant beginConstant endNon-constant end
array1string
\n vector
\n deque
\n intrusive_list
\n intrusive_slist
\n vector_map
\n vector_multimap
\n vector_set
\n vector_multiset
\n bit_vector
\n hash_map
\n hash_multimap
\n hash_set
\n hash_multiset
\n intrusive_hash_map
\n intrusive_hash_multimap
\n intrusive_hash_set
\n intrusive_hash_multiset		array
\n list
\n slist
\n intrusive_list
\n intrusive_slist
\n map
\n multimap
\n set
\n multiset
\n hash_map2
\n hash_multimap2
\n hash_set2
\n hash_multiset2
\n intrusive_hash_map
\n intrusive_hash_multimap
\n intrusive_hash_set
\n intrusive_hash_multiset		string
\n vector
\n deque
\n vector_map
\n vector_multimap
\n vector_set
\n vector_multiset
\n bit_vector
\n
1 Arrays can be neither resized nor reallocated.
\n 2 Constant end if the hashtable can't/won't re-hash. Non-constant if it can re-hash.
\n

8\nIterate containers instead of using operator[].\n

\n

It's faster to iterate random access containers via iterators than via operator[], though operator[] usage may look simpler.

\n

Instead of doing this:

\n

for(unsigned i = 0, iEnd = intVector.size(); i != iEnd; ++i)
\n    intVector[i] = 37;

\n

you can execute more efficiently by doing this:

\n

for(vector<int>::iterator it = intVector.begin(), itEnd = intVector.end(); it != itEnd; ++it)
\n    *it = 37;

\n

9\nLearn to use the string class appropriately.

\n

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 strlen(s.c_str()) are so common, whereas the user could just use s.length() instead and be both clearer and more efficient.
\n
\nHere we provide a table of actual collected examples of things done and how they could have been done instead.

\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
What was writtenWhat could have been written

\n s = s.Left(i) + '+' + s.Right(s.length() - i - 1);
\n
\n 		s[i] = '+';

\n string s(\"\"); // This is the most commonly found misuse.
\n
\n 		string s;

\n s = \"\";
\n
\n 		s.clear();

\n s.c_str()[0] = 'u';
\n
\n 		s[0] = 'u';

\n len = strlen(s.c_str());
\n
\n 		len = s.length();

\n s = string(\"u\");
\n 		s = \"u\";

\n puts(s + string(\"u\"));
\n
\n 		puts(s + \"u\");

\n string s(\" \");
\n puts(s.c_str());
\n
\n 		puts(\" \");

\n s.sprintf(\"u\");
\n
\n 		s = \"u\";

\n char array[32];
\n sprintf(array, \"%d\", 10);
\n s = string(array);
\n
\n 		s.sprintf(\"%d\", 10);
\n


\nThe 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.

\n

10\nCache list size if you want list::size() to be O(1).

\n

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.
\n
\nHere's an example of caching the list size manually:
\n

\n
list<int> intList;
\n size_t    n = 0;
\n
\n intList.push_back(37);
\n ++n;
\n intList.pop_front();
\n --n;
\n

11\nUse empty() instead of size() when possible.\n

\n

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.

\n

12\nKnow your container efficiencies.

\n

The above two practices lead us to this practice, which is a generalization of the above.\n We present a table of basic information for the conventional EASTL containers. The values are described at the\n bottom.

\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n

Container

empty() efficiencysize() efficiencyoperator[] efficiency

insert() efficiency

erase() efficiency

find() efficiency

sort efficiency

slist1O(n)-O(1)O(1)O(n)O(n+)

list

1n-

1

1

n

n log(n)

intrusive_slist1n-111n+
intrusive_list1n-111n log(n)
array111--nn log(n)
vector11a11 at end, else n1 at end, else nnn log(n)
vector_set11a11 at end, else n1 at end, else nlog(n)1
vector_multiset11a11 at end, else n1 at end, else nlog(n)1
vector_map11a11 at end, else n1 at end, else nlog(n)1
vector_multimap11a11 at end, else n1 at end, else nlog(n)1
deque11a11 at begin or end,
\n else n / 2		1 at begin or end,
\n else n / 2		nn log(n)
bit_vector11a11 at end, else n1 at end, else nnn log(n)
string, cow_string11a11 at end, else n1 at end, else nnn log(n)
set11-log(n)log(n)log(n)1
multiset11-log(n)log(n)log(n)1
map11log(n)log(n)log(n)log(n)1
multimap11-log(n)log(n)log(n)1
hash_set11-111-
hash_multiset11-1
11-
hash_map11-111-
hash_multimap11-111-
intrusive_hash_set11-111-
intrusive_hash_multiset11-111-
intrusive_hash_map11-111-
intrusive_hash_multimap11-111-
\n


\n Notes:\n

\n
    \n
  • - means that the operation does not exist.
    • \n
  • 1 means amortized constant time. Also known as O(1)
    • \n
  • n means time proportional to the container size. Also known as O(n)
    • \n
  • log(n) means time proportional to the natural logarithm of the container size. Also known as O(log(n))
    • \n
  • n log(n) means time proportional to log(n) times the size of the container. Also known as O(n log(n))
    • \n
  • n+ means that the time is at least n, and possibly higher.
    • \n
  • 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.
    • \n
  • 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).
    • \n
  • a 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.
    • \n
\n

13\nUse vector::reserve.

\n

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.
\n
\nHere's how you could specify reserved capacity in a vector:
\n

\n
vector<Widget> v(37);   // Reserve space to hold up to 37 items.
\n    or
\nvector<Widget> v;       // This empty construction causes to memory to be allocated or reserved.
\n v.reserve(37);
\n
\nThe EASTL vector (and string) implementation looks like this:\ntemplate <typename T>
\n class vector {
\n    T* mpBegin;     // Beginning of used element memory.
\n    T* mpEnd;       // End of used element memory.
\n    T* mpCapacity;  // End of storage capacity. Is >= mpEnd
\n } \nAnother approach to being efficient with vector memory usage is to use fixed_vector.\n

14\nUse vector::set_capacity to trim memory usage.

\n

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 vector<Widget>(v).swap(v). EASTL provides the same functionality via a member function called set_capacity() which is present in both the vector and string classes. 
\n
\nAn example of reducing a vector is the following:

\nvector<Widget> v;
\n...
\n v.set_capacity(); \nAn example of resizing to zero and completely freeing the memory of a vector is the following:
\n\n
vector<Widget> v;
\n ...
\n v.set_capacity(0);
\n

15 Use swap() instead of a manually implemented version.

\n

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.

\n

16\nConsider storing pointers instead of objects.

\n

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.

\n

17\n Consider smart pointers instead of raw pointers.\n

\n

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.

\n

Here is an example of creating and using a shared_ptr:

\n

typedef shared_ptr<Widget> WPtr;
\n list<WPtr> wList;
\n
\n wList.push_back(WPtr(new Widget)); // The user may have operator new/delete overrides.
\nwList.pop_back();                  // Implicitly deletes the Widget.

\n

Here is an example of creating and using a shared_ptr that uses a custom allocation and deallocation mechanism:

\n

typedef shared_ptr<Widget, EASTLAllocatorType, WidgetDelete> WPtr; // WidgetDelete is a custom destroyer.
\n list<WPtr> wList;
\n
\n wList.push_back(WPtr(WidgetCreate(Widget))); // WidgetCreate is a custom allocator.
\nwList.pop_back();                            // Implicitly calls WidgetDelete.

\n

18\n Use iterator pre-increment instead of post-increment.\n

\n

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.

\n

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.

\n

Here is an example of using iterator pre-increment; for loops like this should always use pre-increment:

\n

for(set<int>::iterator it(intSet.begin()), itEnd(intSet.end()); it != itEnd; ++it)
\n     *it = 37;

\n

19\n Make temporary references so the code can be traced/debugged.\n

\n

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.

\n

Instead of doing this:

\n

for(list<Widget>::iterator it = wl.begin(), itEnd = wl.end(); it != itEnd; ++it) {
\n     (*it).x = 37;
\n     (*it).y = 38;
\n     (*it).z = 39;
\n }

\n

Consider doing this:

\n

for(list<Widget>::iterator it = wl.begin(), itEnd = wl.end(); it != itEnd; ++it) {
\n     Widget& w = *it; // The user can easily inspect or modify w here.
\n     w.x = 37;
\n     w.y = 38;
\n     w.z = 39;
\n }

\n

20\n Consider bitvector or bitset instead of vector<bool>.

\n

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.

\n

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.

\n

21\nVectors can be treated as contiguous memory.

\n

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].

\n

To use a vector as a pointer to an array, you can use the following code:

\n

struct Widget {
\n     uint32_t x;
\n     uint32_t y;
\n };
\n
\n vector<Widget> v;
\n
\n quick_sort((uint64_t*)v.data(), (uint64_t*)(v.data() + v.size()));

\n

22\nSearch hash_map<string> via find_as() instead of find().

\n

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.

\n

To use find_as, you can use the following code:

\n

hash_map<string, int> hashMap;
\n hash_map<string, int>::iterator it = hashMap.find_as("hello"); // Using default hash and compare.

\n

23\nTake advantage of type_traits (e.g. EASTL_DECLARE_TRIVIAL_RELOCATE).

\n

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 types, 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.
\n
\nThere are three primary uses of type traits:

\n
    \n
  • Allowing for optimized operations on some data types.
    • \n
  • Allowing for different logic pathways based on data types.
    • \n
  • Allowing for compile-type assertions about data type expectations.
    • \n
\nMost 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.
\n
\nHere is an example of using type traits to tell if a value is a floating point value or not:
\n\n
template <typename T>
\n DoSomething(T t) {
\n    assert(is_floating_point<T>::value);
\n }
\nHere is an example of declaring a class as relocatable and using it in a vector.
\n\n
EASTL_DECLARE_TRIVIAL_RELOCATE(Widget); // Usually you put this at the Widget class declaration.
\n vector<Widget> wVector;
\n wVector.erase(wVector.begin());         // This operation will be optimized via using memcpy.
\nThe 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.\n
    \n
  • is_void
    • \n
  • is_integral
    • \n
  • is_floating_point
    • \n
  • is_arithmetic
    • \n
  • is_fundamental
    • \n
  • is_const
    • \n
  • is_volatile
    • \n
  • is_abstract
    • \n
  • is_signed
    • \n
  • is_unsigned
    • \n
  • is_array
    • \n
  • is_pointer
    • \n
  • is_reference
    • \n
  • is_member_object_pointer
    • \n
  • is_member_function_pointer
    • \n
  • is_member_pointer
    • \n
  • is_enum
    • \n
  • is_union
    • \n
  • is_class
    • \n
  • is_polymorphic
    • \n
  • is_function
    • \n
  • is_object
    • \n
  • is_scalar
    • \n
  • is_compound
    • \n
  • is_same
    • \n
  • is_convertible
    • \n
  • is_base_of
    • \n
  • is_empty
    • \n
  • is_pod
    • \n
  • is_aligned
    • \n
  • has_trivial_constructor
    • \n
  • has_trivial_copy
    • \n
  • has_trivial_assign
    • \n
  • has_trivial_destructor
    • \n
  • has_trivial_relocate1
    • \n
  • has_nothrow_constructor
    • \n
  • has_nothrow_copy
    • \n
  • has_nothrow_assign
    • \n
  • has_virtual_destructor
    • \n
  • alignment_of
    • \n
  • rank
    • \n
  • extent
    • \n
\n1 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 EASTL_DECLARE_TRIVIAL_RELOCATE  is provided to allow the user to give the compiler a hint.\n

24\nName containers to track memory usage.\n

\n

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.

\n

Here is an example of creating a list and naming it "collision list":

\n

list<CollisionData> collisionList(allocator("collision list"));or
\n list<CollisionData> collisionList;
\ncollisionList.get_allocator().set_name("collision list");

\n

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.

\n

25\nLearn the algorithms.

\n

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.
\n
\n 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.
\n
\n Search

\n
    \n
  • find, find_if
    • \n
  • find_end
    • \n
  • find_first_of
    • \n
  • adjacent_find
    • \n
  • binary_search
    • \n
  • search, search_n
    • \n
  • lower_bound
    • \n
  • upper_bound
    • \n
  • equal_range
    • \n
\n

Sort

\n
    \n
  • is_sorted
    • \n
  • quick_sort
    • \n
  • insertion_sort
    • \n
  • shell_sort
    • \n
  • heap_sort
    • \n
  • merge_sort, merge_sort_buffer
    • \n
  • merge
    • \n
  • inplace_merge
    • \n
  • partial_sort
    • \n
  • stable_sort
    • \n
  • partial_sort_copy
    • \n
  • <other sort functions found in the EASTL bonus directories>
    • \n
\n

Modifying

\n
    \n
  • fill, fill_n
    • \n
  • generate, generate_n
    • \n
  • random_shuffle
    • \n
  • swap
    • \n
  • iter_swap
    • \n
  • swap_ranges
    • \n
  • remove, remove_if
    • \n
  • remove_copy, remove_copy_if
    • \n
  • replace, replace_if
    • \n
  • replace_copy, replace_copy_if
    • \n
  • reverse
    • \n
  • reverse_copy
    • \n
  • rotate
    • \n
  • rotate_copy
    • \n
  • partition
    • \n
  • stable_partition
    • \n
  • transform
    • \n
  • next_permutation
    • \n
  • prev_permutation
    • \n
  • unique
    • \n
  • unique_copy
    • \n
\n

Non-Modifying

\n
    \n
  • for_each
    • \n
  • copy
    • \n
  • copy_backward
    • \n
  • count, count_if
    • \n
  • equal
    • \n
  • mismatch
    • \n
  • min
    • \n
  • max
    • \n
  • min_element
    • \n
  • max_element
    • \n
  • lexicographical_compare
    • \n
  • nth_element
    • \n
\n

Heap

\n
    \n
  • is_heap
    • \n
  • make_heap
    • \n
  • push_heap
    • \n
  • pop_heap
    • \n
  • change_heap
    • \n
  • sort_heap
    • \n
  • remove_heap
    • \n
\n

Set

\n
    \n
  • includes
    • \n
  • set_difference
    • \n
  • set_symmetric_difference
    • \n
  • set_intersection
    • \n
  • set_union
    • \n
\n

26\nPass and return containers by reference instead of value.

\n

If you aren't paying attention you might accidentally write code like this:

\n

void DoSomething(list<Widget> widgetList) {
\n     ...
\n}

\n

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.

\n

27\nConsider using reset_lose_memory() for fast container teardown.

\n

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).

\n

Here's an example of usage of the reset function and a PPMalloc-like StackAllocator:

\n

pStackAllocator->push_bookmark();
\n hash_set<Widget, less<Widget>, StackAllocator> wSet(pStackAllocator);
\n<use wSet>
\n wSet.reset_lose_memory();
\n pStackAllocator->pop_bookmark();

\n

\n

28\nConsider using fixed_substring instead of copying strings.\n

\n

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.

\n

Here's an example of usage of fixed_substring:

\n

basic_string<char> str("hello world");
\n fixed_substring<char> sub(str, 6, 5); // sub == "world"

\n

fixed_substring can refer to any character array and not just one that derives from a string object.

\n

29\n Consider using vector::push_back(void).

\n

EASTL provides an alternative way to insert elements into containers that avoids copy construction and/or the creation of temporaries. Consider the following code:

\n

vector<Widget> widgetArray;
\n widgetArray.push_back(Widget());

\n

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:

\n

vector<Widget> widgetArray;
\n widgetArray.push_back();
\nwidgetArray.back().x = 0; // Example of how to reference the new object.

\n

Other containers with such copy-less functions include:

\n

vector::push_back()
\n deque::push_back()
\n deque::push_front()
\n list::push_back()
\n list::push_front()
\n slist::push_front()
\n map::insert(const key_type& key)
\n multimap::insert(const key_type& key)
\n hash_map::insert(const key_type& key)
\n hash_multimap::insert(const key_type& key)

\n

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.

\n
\n

End of document
\n
\n
\n
\n

\n\n\n" }, { "path": "doc/html/EASTL Design.html", "content": "\n\n\n\tEASTL Design\n\t\n\t\n\t\n \n\n\n

EASTL Design

\n

Introduction

\n

EASTL (EA Standard Template Library) is designed to be a template library which encompasses and extends the\n functionality of standard C++ STL while improving it in various ways useful to game development. Much of EASTL's design\n is identical to standard STL, as the large majority of the STL is well-designed for many uses. The primary areas where\nEASTL deviates from standard STL implementations are essentially the following:

\n
    \n
  • EASTL has a simplified and more flexible custom allocation scheme.
    • \n
  • EASTL has significantly easier to read code.
    • \n
  • EASTL has extension containers and algorithms.
    • \n
  • EASTL has optimizations designed for game development.
    • \n
\n

Of the above items, the only one which is an incompatible difference with STL is the case of memory allocation. The\n method for defining a custom allocator for EASTL is slightly different than that of standard STL, though they are 90%\n similar. The 10% difference, however, is what makes EASTL generally easier and more powerful to work with than standard\nSTL. Containers without custom allocators act identically between EASTL and standard STL.

\n

Motivations

\n

Our motifications for making EASTL drive the design of EASTL. As identified in the EASTL RFC (Request for Comment), the\n primary reasons for implementing a custom version of the STL are:\n

\n
    \n
  • Some STL implementations (especially Microsoft STL) have inferior\nperformance characteristics that make them unsuitable for game development. EASTL is faster than all existing STL\nimplementations.
    • \n
  • The STL is sometimes hard to debug, as most STL implementations use cryptic variable names and unusual data\nstructures.
    • \n
  • STL allocators are sometimes painful to work with, as they have many requirements and cannot be modified once bound\nto a container.
    • \n
  • The STL includes excess functionality that can lead to larger code than desirable. It's not very easy to tell\nprogrammers they shouldn't use that functionality.
    • \n
  • The STL is implemented with very deep function calls. This results is unacceptable performance in non-optimized\nbuilds and sometimes in optimized builds as well.
    • \n
  • The STL doesn't support alignment of contained objects.
    • \n
  • STL containers won't let you insert an entry into a container without supplying an entry to copy from. This can be\ninefficient.
    • \n
  • Useful STL extensions (e.g. slist, hash_map, shared_ptr) found in existing STL implementations such as STLPort are\nnot portable because they don't exist in other versions of STL or aren't consistent between STL versions.
    • \n
  • The STL lacks useful extensions that game programmers find useful (e.g. intrusive_list) but which could be best\noptimized in a portable STL environment.
    • \n
  • The STL has specifications that limit our ability to use it efficiently. For example, STL vectors are not\nguaranteed to use contiguous memory and so cannot be safely used as an array.
    • \n
  • The STL puts an emphasis on correctness before performance, whereas sometimes you can get significant performance\ngains by making things less academcially pure.
    • \n
  • STL containers have private implementations that don't allow you to work with their data in a portable way, yet\nsometimes this is an important thing to be able to do (e.g. node pools).
    • \n
  • All existing versions of STL allocate memory in empty versions of at least some of their containers. This is not\nideal and prevents optimizations such as container memory resets that can greatly increase performance in some\nsituations.
    • \n
  • The STL is slow to compile, as most modern STL implementations are very large.
    • \n
  • There are legal issues that make it hard for us to freely use portable STL implementations such as STLPort.
    • \n
  • We have no say in the design and implementation of the STL and so are unable to change it to work for our\nneeds.
    • \n
\n

Prime Directives

\n

The implementation of EASTL is guided foremost by the\nfollowing directives which are listed in order of importance.

\n
    \n
  1. Efficiency (speed and memory usage)
    2. \n
  2. Correctness
    3. \n
  3. Portability
    4. \n
  4. Readability
    5. \n
\n

Note that unlike commercial STL implementations which must put correctness above all, we put a higher value on\n efficiency. As a result, some functionality may have some usage limitation that is not present in other similar systems\nbut which allows for more efficient operation, especially on the platforms of significance to us.

\n

Portability is significant, but not critical. Yes, EASTL must compile and run on all platforms that we will ship games\n for. But we don't take that to mean under all compilers that could be conceivably used for such platforms. For example,\n Microsoft VC6 can be used to compile Windows programs, but VC6's C++ support is too weak for EASTL and so you simply\ncannot use EASTL under VC6.

\n

Readability is something that EASTL achieves better than many other templated libraries, particularly Microsoft STL and\n STLPort. We make every attempt to make EASTL code clean and sensible. Sometimes our need to provide optimizations\n (particularly related to type_traits and iterator types) results in less simple code, but efficiency happens to be our\nprime directive and so it overrides all other considerations.

\n

Thread Safety

\n

It's not simple enough to simply say that EASTL is thread-safe or thread-unsafe. However, we can say that with respect\nto thread safety that EASTL does the right thing.

\n

Individual EASTL containers are not thread-safe. That is, access to an instance of a container from multiple\n threads at the same time is unsafe if any of those accesses are modifying operations. A given container can be read\n from multiple threads simultaneously as well as any other standalone data structure. If a user wants to be able to have\n modifying access an instance of a container from multiple threads, it is up to the user to ensure that proper thread\nsynchronization occurs. This usually means using a mutex.

\n

EASTL classes other than containers are the same as containers with respect to thread safety. EASTL functions (e.g.\n algorithms) are inherently thread-safe as they have no instance data and operate entirely on the stack. As of this\nwriting, no EASTL function allocates memory and thus doesn't bring thread safety issues via that means.

\n

The user may well need to be concerned about thread safety with respect to memory allocation. If the user modifies\n containers from multiple threads, then allocators are going to be accessed from multiple threads. If an allocator is\n shared across multiple container instances (of the same type of container or not), then mutexes (as discussed above)\n the user uses to protect access to indivudual instances will not suffice to provide thread safety for allocators used\n across multiple instances. The conventional solution here is to use a mutex within the allocator if it is exected to be\nused by multiple threads.

\n

EASTL uses neither static nor global variables and thus there are no inter-instance dependencies that would make\nthread safety difficult for the user to implement.

\n

Container Design

\n

All EASTL containers follow a set of consistent conventions. Here we define the prototypical container which has the\n minimal functionality that all (non-adapter) containers must have. Some containers (e.g. stack) are explicitly adapter\n containers and thus wrap or inherit the properties of the wrapped container in a way that is implementation\n specific.
\n

\n
template <class T, class Allocator =\nEASTLAllocator>
\nclass container
\n{
\npublic:
\n    typedef container<T, Allocator>            this_type;
\n    typedef\nT                     \n            value_type;
\n    typedef T*                   \n             pointer;
\n    typedef const T*                       \n   const_pointer;
\n    typedef\nT&                                 reference;
\n\n    typedef const\nT&                           const_reference;
\n\n    typedef\nptrdiff_t                          difference_type;
\n\n    typedef\nimpl_defined                       size_type;
\n\n    typedef impl-defined                  \n    iterator;
\n    typedef impl-defined                  \n    const_iterator;
\n    typedef reverse_iterator<iterator>         reverse_iterator;
\n    typedef reverse_iterator<const_iterator>   reverse_const_iterator;
\n    typedef Allocator                 \n        allocator_type;
\n
\npublic:
\n    container(const\nallocator_type& allocator = allocator_type());
\n    container(const this_type&\nx);
\n
\n    this_type&\noperator=(this_type& x);
\n    void swap(this_type& x);
\n    void reset();
\n
\n    allocator_type& get_allocator();
\n    void            set_allocator(allocator_type& allocator);
\n
\n    iterator       begin();
\n    const_iterator begin() const;
\n    iterator       end();
\n    const_iterator end() const;
\n
\n    bool validate() const;
     int  validate_iterator(const_iterator i)\nconst;

\nprotected:
\n    allocator_type mAllocator;
\n};
\n
\ntemplate <class T, class\nAllocator>
\nbool operator==(const container<T, Allocator>& a, const container<T, Allocator>& b);
\n
\ntemplate <class T, class\nAllocator>
\nbool operator!=(const container<T, Allocator>& a, const\ncontainer<T, Allocator>&\nb);
\n
\nNotes:\n
    \n
  • Swapped containers do not swap their allocators.
    • \n
  • Newly constructed empty containers do no memory allocation. Some STL and other container libraries allocate an\ninitial node from the class memory allocator. EASTL containers by design never do this. If a container needs an initial\nnode, that node should be made part of the container itself or be a static empty node object.
    • \n
  • Empty containers (new or otherwise) contain no constructed objects, including those that might be in an 'end' node.\nSimilarly, no user object (e.g. of type T) should be constructed unless required by the design and unless documented in\nthe cotainer/algorithm contract. 
    • \n
  • The reset function is a special extension function which unilaterally resets the container to an empty state\nwithout freeing the memory of the contained objects. This is useful for very quickly tearing down a container built\ninto scratch memory. No memory is allocated by reset, and the container has no allocatedmemory after the reset is\nexecuted.
    • \n
  • 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.
    • \n
\n

Allocator Design

\n

The most significant difference between EASTL and standard C++ STL is that standard STL containers are templated on an\n allocator class with the interface defined in std::allocator. std::allocator is defined in the C++ standard as\n this:
\n

\n
// Standard C++ allocator
\n
\n template <class T>
\nclass allocator
\n{
\npublic:
\n    typedef size_t    size_type;
\n    typedef ptrdiff_t difference_type;
\n    typedef T*        pointer;
\n    typedef const T*  const_pointer;
\n    typedef T&      \n reference;
\n    typedef const\nT&  const_reference;
\n    typedef T         value_type;
\n
\n    template <class U>
\n    struct rebind { typedef allocator<U> other; };
\n
\n    allocator() throw();
\n    allocator(const allocator&) throw();
\n    template <class U>
\n    allocator(const allocator<U>&) throw();
\n
\n    ~allocator()\nthrow();
\n
\n     pointer  \n    address(reference x) const;
\n    const_pointer address(const_reference x)\nconst;
\n    pointer       allocate(size_type, typename\nallocator<void>::const_pointer hint = 0);
\n    void          deallocate(pointer p,\nsize_type n);
\n    size_type     max_size() const\nthrow();
\n    void          construct(pointer p,\nconst T& val);
\n    void          destroy(pointer\np);
\n};
\n

Each STL container needs to have an allocator templated on container type T associated with it. The problem with this\nis that allocators for containers are defined at the class level and not the instance level. This makes it painful to\ndefine custom allocators for containers and adds to code bloat. Also, it turns out that the containers don't actually\nuse allocator<T> but instead use allocator<T>::rebind<U>::other. Lastly, you cannot access this\nallocator after the container is constructed. There are some good academic reasons why the C++ standard works this way,\nbut it results in a lot of unnecessary pain and makes concepts like memory tracking much harder to implement.

\n

What EASTL does is use a more familiar memory allocation pattern whereby there is only one allocator class interface\n and it is used by all containers. Additionally EASTL containers let you access their allocators and query them, name\nthem, change them, etc.

\n

EASTL has chosen to make allocators not be copied between containers during container swap and assign operations. This\n means that if container A swaps its contents with container B, both containers retain their original allocators.\n Similarly, assigning container A to container B causes container B to retain its original allocator. Containers that\n are equivalent should report so via operator==; EASTL will do a smart swap if allocators are equal, and a brute-force\n swap otherwise.
\n

\n
// EASTL allocator
\n
\nclass allocator
\n{
\npublic:
\n    allocator(const char* pName = NULL);
\n
\n    void* allocate(size_t n, int flags = 0);
\n    void* allocate(size_t n, size_t alignment, size_t offset, int flags = 0);
\n    void  deallocate(void* p, size_t n);
\n
\n    const char* get_name() const;
\n    void        set_name(const char* pName);
\n};
\n
\nallocator* GetDefaultAllocator();
\n

Fixed Size Container Design

\n

EASTL supplies a set of fixed-size containers that the user can use, though the user can also implement their own\n versions. So in addition to class list there is class fixed_list. The fixed_list class implements a linked list via a\n fixed-size pool of contiguous memory which has no space overhead (unlike with a regular heap), doesn't cause\nfragmentation, and allocates very quickly.

\n

EASTL implements fixed containers via subclasses of regular containers which set the regular container's allocator to\n point to themselves. Thus the implementation for fixed_list is very tiny and consists of little more\n than constructor and allocator functions. This design has some advantages but has one small disadvantage. The\n primary advantages are primarily that code bloat is reduced and that the implementation is simple and the user can\n easily extend it. The primary disadvantage is that the parent list class ends up with a pointer to itself and thus has\n 4 bytes that could arguably be saved if system was designed differently. That different design would be to make the\n list class have a policy template parameter which specifies that it is a fixed pool container. EASTL chose not to\n follow the policy design because it would complicate the implementation, make it harder for the user to extend the\n container, and would potentially waste more memory due to code bloat than it would save due to the 4 byte savings it\nachieves in container instances.

\n

Algorithm Design

\n

EASTL algorithms very much follow the philosophy of standard C++ algorithms, as this philosophy is sound and efficient.\n One of the primary aspects of algorithms is that they work on iterators and not containers. You will note for example\n that the find algorithm takes a first and last iterator as arguments and not a container. This has two primary\n benefits: it allows the user to specify a subrange of the container to search within and it allows the user to apply\nthe find algorithm to sequences that aren't containers (e.g. a C array).

\n

EASTL algorithms are optimized at least as well as the best STL algorithms found in commercial libraries and are\n 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\n 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\nMicrsoft STL.

\n

The optimizations found in EASTL algorithms and the supporting code in EASTL type traits consistts of some fairly\n tricky advanced C++ and while it is fairly easy to read, it requires a C++ expert (language lawyer, really) to\n implement confidently. The result of this is that it takes more effort to develop and maintain EASTL than it would to\nmaintain a simpler library. However, the performance advantages have been deemed worth the tradeoff.

\n

Smart Pointer Design

\n

EASTL implements the following smart pointer types:

\n
    \n
  • shared_ptr
    • \n
  • shared_array
    • \n
  • weak_ptr
    • \n
  • instrusive_ptr
    • \n
  • scoped_ptr
    • \n
  • scoped_array
    • \n
  • linked_ptr
    • \n
  • linked_array
    • \n
\nAll but linked_ptr/linked_array are well-known smart pointers from the Boost library. The behaviour of these smart\npointers is very similar to those from Boost with two exceptions:\n
    \n
  • EASTL smart pointers allow you to assign an allocator to them.
    • \n
  • EASTL shared_ptr implements deletion via a templated parameter instead of a dynamically allocated virtual\nmember object interface.
    • \n
\n

With respect to assigning an allocator, this gives EASTL more control over memory allocation and tracking, as Boost\nsmart pointers unilaterally use global operator new to allocate memory from the global heap.

\n

With respect to shared_ptr deletion, EASTL's current design of using a templated parameter is questionable, but does\n have some reason. The advantage is that EASTL avoids a heap allocation, avoids virtual function calls, and avoids\n templated class proliferation. The disadvantage is that EASTL shared_ptr containers which hold void pointers can't call\n the destructors of their contained objects unless the user manually specifies a custom deleter template parameter. This\n is case whereby EASTL is more efficient but less safe. We can revisit this topic in the future if it becomes an\n issue.

\n

list::size is O(n)

\n

As of this writing, EASTL has three linked list classes: list, slist, and intrusive_list. In each of these classes, the\n 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\n a fast operation, as it requires traversing the list and counting the nodes. We could make the list::size function be\n fast by having a member mSize variable which tracks the size as we insert and delete items. There are reasons for\n having such functionality and reasons for not having such functionality. We currently choose to not have a member mSize\n variable as it would add four bytes to the class, add a tiny amount of processing to functions such as insert and\n erase, and would only serve to improve the size function, but no others. In the case of intrusive_list, it would do\n additional harm. The alternative argument is that the C++ standard states that std::list should be an O(1)\n operation (i.e. have a member size variable), that many C++ standard library list implementations do so, that the\n size is but an integer which is quick to update, and that many users expect to have a fast size function. In the final\n analysis, we are developing a library for game development and performance is paramount, so we choose to not cache the\nlist size. The user can always implement a size cache himself.

\n

basic_string doesn't use copy-on-write

\n

The primary benefit of CoW is that it allows for the sharing of string data between two string objects. Thus if you say\n this:

\n

string a(\"hello\");
\n string b(a);

\n

the \"hello\" will be shared between a and b. If you then say this:

\n

a = \"world\";

\n

then a will release its reference to \"hello\" and leave b with the only\n reference to it. Normally this functionality is accomplished via reference counting and with atomic operations or\nmutexes.

\n

The C++ standard does not say anything about basic_string and CoW. However, for a basic_string implementation to be\n standards-conforming, a number of issues arise which dictate some things about how one would have to implement a CoW\n string. The discussion of these issues will not be rehashed here, as you can read the references below for better\n detail than can be provided in the space we have here. However, we can say that the C++ standard is sensible\n and that anything we try to do here to allow for an efficient CoW implementation would result in a generally\nunacceptable string interface.

\n

The disadvantages of CoW strings are:

\n
    \n
  • A reference count needs to exist with the string, which increases string memory usage.
    • \n
  • With thread safety, atomic operations and mutex locks are expensive, especially on weaker memory systems such\nas console gaming platforms.
    • \n
  • All non-const string accessor functions need to do a sharing check the the first such check needs to detach the\nstring. Similarly, all string assignments need to do a sharing check as well. If you access the string before doing an\nassignment, the assignment doesn't result in a shared string, because the string has already been detached.
    • \n
  • String sharing doesn't happen the large majority of the time. In some cases, the total sum of the reference\ncount memory can exceed any memory savings gained by the strings that share representations. 
    • \n
\n

The addition of a cow_string class is under consideration for EASTL. There are conceivably some systems which have\n string usage patterns which would benefit from CoW sharing. Such functionality is best saved for a separate\nstring implementation so that the other string uses aren't penalized.

\n

This is a good starting HTML reference on the topic:

\n
\n

\t\n http://www.gotw.ca/publications/optimizations.htm

\n
\n

Here is a well-known Usenet discussion on the topic:

\n
\n

http://groups-beta.google.com/group/comp.lang.c++.moderated/browse_thread/thread/3dc6af5198d0bf7/886c8642cb06e03d

\n
\n
\nEnd of document
\n
\n
\n
\n
\n
\n
\n
\n
\n
\n
\n
\n
\n
\n
\n
\n
\n
\n
\n
\n
\n
\n
\n
\n
\n
\n
\n\n\n" }, { "path": "doc/html/EASTL FAQ.html", "content": "\n\n\n\tEASTL FAQ\n\t\n\t\n\t\n \n\n\n\n

EASTL FAQ

\n

We provide a FAQ (frequently asked questions) list here for a number of commonly asked questions about EASTL and STL in\ngeneral. Feel free to suggest new FAQ additions based on your own experience.

\n

Information

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
1What is EASTL?
2What uses are EASTL suitable for?
3
How does EASTL differ from standard C++\nSTL?
4Is EASTL thread-safe?
5What platforms/compilers does EASTL support?
6Why is there EASTL when there is the STL?
7Can I mix EASTL with standard C++ STL?
8Where can I learn more about STL and EASTL?
9What is the legal status of EASTL?
10Does EASTL deal with compiler exception handling settings?
11What C++ language features does EASTL use (e.g. virtual functions)?
12What compiler warning levels does EASTL support?
13Is EASTL compatible with Lint?
14What compiler settings do I need to compile EASTL?
15How hard is it to incorporate EASTL into my project?
16Should I use EASTL instead of std STL or instead of my custom library?
17I think I've found a bug. What do I do?
18Can EASTL be used by third party EA developers?
\n

Performance\n

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
1How efficient is EASTL compared to standard C++ STL implementations?
2How efficient is EASTL in general?
3Strings don't appear to use the \"copy-on-write\" optimization. Why not?
4Does EASTL cause code bloat, given that it uses templates?
5Don't STL and EASTL containers fragment memory?
6I don't see container optimizations for equivalent scalar types such as pointer types.\nWhy?
7I've seen some STL's provide a default quick \"node allocator\" as the default allocator. Why\ndoesn't EASTL do this?
8Templates sometimes seem to take a long time to compile. Why do I do about that?
9How do I assign a custom allocator to an EASTL container?
10How well does EASTL inline?
11How do I control function inlining?
12C++ / EASTL seems to bloat my .obj files much more than C does.
13What are the best compiler settings for EASTL?
\n

Problems

\n\n\n\n\n\n\n\n\n \n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n \n \n\n\n \n \n\n\n \n \n\n\n \n \n\n\n \n \n\n\n
1I'm getting screwy behavior in sorting algorithms or sorted containers. What's wrong?
2I am getting compiler warnings (e.g. C4244, C4242 or C4267) that make no sense. Why?
3I am getting compiler warning C4530, which complains about exception handling and \"unwind\nsemantics.\" What gives?
4Why are tree-based containers hard to read with a debugger?
5The EASTL source code is sometimes rather complicated looking. Why is that?
6When I get compilation errors, they are very long and complicated looking. What do I do?
7Templates sometimes seem to take a long time to compile. Why do I do about that?
8I get the compiler error: \"template instantiation depth exceeds maximum of 17. use\n-ftemplate-depth-NN to increase the maximum\"
9I'm getting errors about min and max while compiling.
10C++ / EASTL seems to bloat my .obj files much more than C does.
11I'm getting compiler errors regarding operator new being previously defined.
12I'm getting errors related to wchar_t string  functions such as wcslen.
13I'm getting compiler warning C4619: there is no warning number Cxxxx (e.g. C4217).
14My stack-based fixed_vector is not respecting the object alignment requirements.
15I am getting compiler errors when using GCC under XCode (Macintosh/iphone).
16I am getting linker errors about Vsnprintf8 or Vsnprintf16.
17I am getting compiler errors about UINT64_C or UINT32_C.
18I am getting a crash with a global EASTL container.
19Why doesn't EASTL support passing NULL to functions with pointer arguments?
\n

Debug

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
1How do I get VC++ mouse-overs to view templated data?
2How do I view containers if the visualizer/tooltip support is not present?
3The EASTL source code is sometimes rather complicated looking. Why is that?
4When I get compilation errors, they are very long and complicated looking. What do I\ndo?
5How do I measure hash table balancing?
\n

Containers

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n \n \n\n\n \n \n\n\n \n \n\n\n
1Why do some containers have \"fixed\" versions (e.g. fixed_list) but others(e.g. deque) don't have\nfixed versions?
2Can I mix EASTL with standard C++ STL?
3Why are there so many containers?
4Don't STL and EASTL containers fragment memory?
5I don't see container optimizations for equivalent scalar types such as pointer types.\nWhy?
6What about alternative container and algorithm implementations (e.g. treaps, skip lists, avl\ntrees)?
7Why are containers hard to read with a debugger?
8How do I assign a custom allocator to an EASTL container?
9How do I set the VC++ debugger to display EASTL container data with tooltips?
10How do I use a memory pool with a container?
11How do I write a comparison (operator<()) for a struct that contains two or more\nmembers?
12Why doesn't container X have member function Y?
13How do I search a hash_map of strings via a char pointer efficiently? If I use map.find(\"hello\")\nit creates a temporary string, which is inefficient.
14Why are set and hash_set iterators const (i.e. const_iterator)?
15How do I prevent my hash container from re-hashing?
16Which uses less memory, a map or a hash_map?
17How do I write a custom hash function?
18How do I write a custom compare function for a map or set?
19How do I force my vector or string capacity down to the size of the container?
20How do I iterate a container while (selectively) removing items from it?
21How do I store a pointer in a container?
22How do I make a union of two containers? difference? intersection?
23How do I override the default global allocator?
24How do I do trick X with the string class?
25How do EASTL smart pointers compare to Boost smart pointers?
26How do your forward-declare an EASTL container?
27How do I make two containers share a memory pool?
28Can I use a std (STL) allocator with EASTL?
29 What are the requirements of classes stored in containers?
\n

Algorithms

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n \n \n\n\n
1I'm getting screwy behavior in sorting algorithms or sorted containers. What's wrong?
2How do I write a comparison (operator<()) for a struct that contains two or more\nmembers?
3How do I sort something in reverse order?
4I'm getting errors about min and max while compiling.
5Why don't algorithms take a container as an argument instead of iterators? A container would be\nmore convenient.
6Given a container of pointers, how do I find an element by value (instead of by\npointer)?
7When do stored objects need to support opertor\n< vs. when do they need to support operator\n==?
8How do I sort via pointers or array indexes instead of objects directly?
\n

Iterators

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
1What's the difference between iterator, const iterator, and const_iterator?
2How do I tell from an iterator what type of thing it is iterating?
3How do I iterate a container while (selectively) removing items from it?
4What is an insert_iterator?
\n


\n Information\n

\n

Info.1\nWhat is EASTL?

\n

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:

\n
    \n
  • Containers
    • \n
  • Iterators
    • \n
  • Algorithms
    • \n
  • Utilities
    • \n
  • Smart pointers
    • \n
  • Type traits
    • \n
\n

EASTL provides extensions and optimizations over the equivalents in standard C++ STL.

\n

EASTL is a professional-level implementation which outperforms commercial implementations (where functionality overlaps) and is significantly easier to read and debug.

\n

Info.2\nWhat uses are EASTL suitable for?

\n

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.

\n

Info.3\nHow does EASTL differ from standard C++ STL?

\n

There are three kinds of ways that EASTL differs from standard STL:

\n
    \n
  1. EASTL equivalents to STL sometimes differ.
    2. \n
  2. EASTL implementations sometimes differ from STL implementations of the same thing.
    3. \n
  3. EASTL has functionality that doesn't exist in STL.
    4. \n
\n

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.

\n

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.

\n

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.

\n

Ways in which EASTL is better than standard STL:

\n
    \n
  • Has higher performance in release builds, sometimes dramatically so.
    • \n
  • Has significantly higher performance in debug builds, due to less call overhead.
    • \n
  • Has extended per-container functionality, particularly for game development.
    • \n
  • Has additional containers that are useful for high performance game development.
    • \n
  • Is easier to read, trace, and debug.
    • \n
  • Memory allocation is much simpler and more controllable.
    • \n
  • Has higher portability, as there is a single implementation for all platforms.
    • \n
  • Has support of object alignment, whereas such functionality is not natively supported by STL.
    • \n
  • We have control over it, so we can modify it as we like.
    • \n
  • Has stricter standards for container design and behavior, particularly as this benefits game development.
    • \n
\n

Ways in which EASTL is worse than standard STL:

\n
    \n
  • Standard STL implementations are currently very reliable and weather-worn, whereas EASTL is less tested.
    • \n
  • Standard STL is automatically available with just about every C++ compiler vendor's library.
    • \n
  • Standard STL is supported by the compiler vendor and somewhat by the Internet community.
    • \n
\n

EASTL coverage of std STL

\n
    \n
  • list
    • \n
  • vector
    • \n
  • deque
    • \n
  • string
    • \n
  • set
    • \n
  • multiset
    • \n
  • map
    • \n
  • multimap
    • \n
  • bitset
    • \n
  • queue
    • \n
  • stack
    • \n
  • priority_queue
    • \n
  • memory
    • \n
  • numeric
    • \n
  • algorithm (all but inplace_merge, prev_permutation, next_permutation, nth_element, includes, unique_copy)
    • \n
  • utility
    • \n
  • functional
    • \n
  • iterator
    • \n
  • string_view
    • \n
  • variant
    • \n
  • any
    • \n
  • optional
    • \n
\n

EASTL additions/amendments to std STL

\n
    \n
  • allocators work in a simpler way.
    • \n
  • exception handling can be disabled.
    • \n
  • all containers expose/declare their node size, so you can make a node allocator for them.
    • \n
  • all containers have reset_lose_memory(), which unilaterally forgets their contents.
    • \n
  • all containers have validate() and validate_iterator() functions.
    • \n
  • all containers understand and respect object alignment requirements.
    • \n
  • all containers guarantee no memory allocation upon being newly created as empty.
    • \n
  • all containers and their iterators can be viewed in a debugger (no other STL does this, believe it or not).
    • \n
  • linear containers guarantee linear memory.
    • \n
  • vector has push_back(void).
    • \n
  • vector has a data() function.
    • \n
  • vector<bool> is actually a vector of type bool.
    • \n
  • vector and string have set_capacity().
    • \n
  • string has sprintf(), append_sprintf(), trim(), compare_i(), make_lower(), make_upper().
    • \n
  • deque allows you to specify the subarray size.
    • \n
  • list has a push_back(void) and push_back(void) function.
    • \n
  • hash_map, hash_set, etc. have find_as().
    • \n
\n

EASTL coverage of TR1 (tr1 refers to proposed additions for the next C++ standard library, ~2008)

\n
    \n
  • array
    • \n
  • type_traits (there are about 30 of these)
    • \n
  • unordered_set (EASTL calls it hash_set)
    • \n
  • unordered_multiset
    • \n
  • unordered_map
    • \n
  • unordered_multimap
    • \n
  • shared_ptr, shared_array, weak_ptr, scoped_ptr, scoped_array, intrusive_ptr
    • \n
\n

EASTL additional functionality (not found elsewhere)

\n
    \n
  • fixed_list
    • \n
  • fixed_slist
    • \n
  • fixed_vector
    • \n
  • fixed_string
    • \n
  • fixed_substring
    • \n
  • fixed_set
    • \n
  • fixed_multiset
    • \n
  • fixed_map
    • \n
  • fixed_multimap
    • \n
  • fixed_hash_set
    • \n
  • fixed_hash_multiset
    • \n
  • fixed_hash_map
    • \n
  • fixed_hash_multimap
    • \n
  • fixed_function
    • \n
  • vector_set
    • \n
  • vector_multiset
    • \n
  • vector_map
    • \n
  • vector_multimap
    • \n
  • intrusive_list
    • \n
  • intrusive_slist
    • \n
  • intrusive_sdlist
    • \n
  • intrusive_hash_set
    • \n
  • intrusive_hash_multiset
    • \n
  • intrusive_hash_map
    • \n
  • intrusive_hash_multimap
    • \n
  • slist (STLPort's STL has this)
    • \n
  • heap
    • \n
  • linked_ptr, linked_array
    • \n
  • sparse_matrix (this is not complete as of this writing)
    • \n
  • ring_buffer
    • \n
  • compressed_pair
    • \n
  • call_traits
    • \n
  • binary_search_i, change_heap, find_first_not_of, find_last_of, find_last_not_of, identical
    • \n
  • comb_sort, bubble_sort, selection_sort, shaker_sort, bucket_sort
    • \n
  • equal_to_2, not_equal_to_2, str_equal_to, str_equal_to_i
    \n
    • \n
\n

Info.4\nIs EASTL thread-safe?\n

\n

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.

\n

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.

\n

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.

\n

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.

\n

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.

\n

Info.5\nWhat platforms/compilers does EASTL support?

\n

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 (with a couple small exceptions), 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:

\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
CompilerStatusNotes
GCC 3.x+Not SupportedNot officially supported due to migration to Clang.
MSVC 12.0+SupportedThis compiler is used by the Windows based platforms
Clang 4.0+SupportedThis compiler is used by the Linux based platforms
\n
\n

Info.6\nWhy is there EASTL when there is the STL?

\n

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:

\n
    \n
  • 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.
    • \n
  • The STL is sometimes hard to debug, as most STL implementations use cryptic variable names and unusual data structures.
    • \n
  • STL allocators are sometimes painful to work with, as they have many requirements and cannot be modified once bound to a container.
    • \n
  • 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.
    • \n
  • 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.
    • \n
  • The STL doesn't support alignment of contained objects.
    • \n
  • STL containers won't let you insert an entry into a container without supplying an entry to copy from. This can be inefficient.
    • \n
  • 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.
    \n
    • \n
  • 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.
    • \n
  • The STL puts an emphasis on correctness before performance, whereas sometimes you can get significant performance gains by making things less academically pure.
    • \n
  • 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).
    • \n
  • 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.
    • \n
  • The STL is slow to compile, as most modern STL implementations are very large.
    \n
    • \n
  • There are legal issues that make it hard for us to freely use portable STL implementations such as STLPort.
    • \n
  • We have no say in the design and implementation of the STL and so are unable to change it to work for our needs.
    • \n
\n

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.

\n

Info.7\nCan I mix EASTL with standard C++ STL?

\n

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.
\n
\nThings that you definitely can do:

\n
    \n
  • #include both EASTL and standard STL headers from the same .cpp file.
    • \n
  • Use EASTL containers to hold STL containers.
    • \n
  • Construct an STL reverse_iterator from an EASTL iterator.
    • \n
  • Construct an EASTL reverse_iterator from an STL iterator.
    • \n
\n

Things that you probably will be able to do, though a given std STL implementation may prevent it:\n

\n
    \n
  • Use STL containers in EASTL algorithms.
    • \n
  • Use EASTL containers in STL algorithms.
    • \n
  • Construct or assign to an STL container via iterators into an EASTL container.
    • \n
  • Construct or assign to an EASTL container via iterators into an STL container.
    • \n
\n

Things that you would be able to do if the given std STL implementation is bug-free:\n

\n
    \n
  • 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.
    • \n
\n

Things that you definitely can't do:

\n
    \n
  • Use an STL allocator directly with an EASTL container (though you can use one indirectly).
    • \n
  • Use an EASTL allocator directly with an STL container (though you can use one indirectly).
    • \n
\n

Info.8\nWhere can I learn more about STL and EASTL?\n

\n

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.

\n

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.

\n
    \n
  • The SGI STL web site. Includes a good STL reference.
    • \n
  • CodeProject STL introduction.
    • \n
  • Scott Meyers Effective STL book.
    • \n
  • The Microsoft online STL documentation. Microsoft links go bad every couple months, so try searching for STL at the Microsoft MSDN site.
    • \n
  • The Dinkumware online STL documentation. 
    • \n
  • 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".
    • \n
  • STL performance tips, by Pete Isensee
    • \n
  • STL algorithms vs. hand-written loops, by Scott Meyers.
    • \n
  • cppreference.com
    • \n
  • isocpp.org
  • \n
\n

Info.9\nWhat is the legal status of EASTL?

\n

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.

\n

Info.10\nDoes EASTL deal with compiler exception handling settings?

\n

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.

\n

Info.11\n What C++ language features does EASTL use (e.g. virtual\nfunctions)?

\n

EASTL uses the following C++ language features:

\n
    \n
  • Template functions, classes, member functions.
    • \n
  • Multiple inheritance.
    • \n
  • Namespaces.
    • \n
  • Operator overloading.
    • \n
\n

EASTL does not use the following C++ language features:\n

\n
    \n
  • Virtual functions / interfaces.
    • \n
  • RTTI (dynamic_cast).
    • \n
  • Global and static variables. There are a couple class static const variables, but they act much like enums.
    • \n
  • Volatile declarations
    • \n
  • Template export.
    • \n
  • Virtual inheritance.
    • \n
\n

EASTL may use the following C++ language features:\n

\n
    \n
  • Try/catch. This is an option that the user can enable and it defaults to whatever the compiler is set to use.
    • \n
  • Floating point math. Hash containers have one floating point calculation, but otherwise floating point is not used.
    • \n
\n

Notes:\n

\n
    \n
  • 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.
    • \n
  • EASTL never uses global new / delete / malloc / free. All allocations are done via user-specified allocators, though a default allocator definition is available.
    • \n
\n

Info.12\n What compiler warning levels does EASTL support?\n

\n

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.

\n

For GCC, EASTL should compile without warnings with -Wall. Extensive testing beyond that hasn't been done.

\n

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.

\n

Info.13\n Is EASTL compatible with Lint?\n

\n

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.

\n

Info.14\n What compiler settings do I need to compile EASTL?\n

\n

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.

\n

See the Performance section of this FAQ for a discussion of the optimal compiler settings for EASTL performance.

\n

Info.15\nHow hard is it to incorporate EASTL into my project?

\n

It's probably trivial.
\n
\nEASTL 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.
\n
\nIn its default configuration, the only thing you need to provide to make EASTL work is to define implementations of the following operator new functions:

\n
#include <new>
\nvoid* operator new[](size_t size, const char* pName, int flags, unsigned debugFlags, const char* file, int line);\nvoid* operator new[](size_t size, size_t alignment, size_t alignmentOffset, const char* pName, int flags, unsigned debugFlags, const char* file, int line);
\nThe flags and debugFlags arguments correspond to PPMalloc/RenderWare GeneralAllocator/GeneralAllocatorDebug Malloc equivalents.
\n

Info.16\nShould I use EASTL instead of std STL or instead of my custom library?

\n

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.
\n
\nEASTL
\n

\n
+ Has higher performance than any commercial STL, especially on console platforms.
\n + Has extended functionality tailored for game development.
\n + Is highly configurable, and we own it so it can be amended at will. Std STL is owned by a third party committee.
\n + Is much easier to read and debug than other similar libraries, especially std STL.
\n
\n - Is highly unit tested, but does not have the same level as std STL.
\n - Is more complicated than many users' lite template libraries, and may put off some beginners.
\n- EASTL  
\n

Std STL\n

\n
+ Is highly portable; your STL code will likely compile and run anywhere.
\n + Works without the need to install or download any package to use it. It just works.
\n + Is highly reliable and supported by the compiler vendor. You can have confidence in it.
\n + Some std STL versions (e.g. STLPort, VC8 STL) have better runtime debug checking than EASTL.
\n
\n - Has (sometimes greatly) variable implementations, behavior, and performance between implementations.
\n - Is usually hard to read and debug.
\n - Doesn't support some of the needs of game development, such as aligned allocations, named allocations, intrusive containers, etc.
\n- Is not as efficient as EASTL, especially on console platforms.
\n

Your own library\n

\n
(please forgive us for implying there may be weaknesses in your libraries)
\n\n

\n + You have control over it and can make it work however you want.
\n + You can fix bugs in it on the spot and have the fix in your codebase immediately.
\n + Your own library can be highly integrated into your application code or development environment.
\n
\n - Many custom libraries don't have the same level of testing as libraries such as std STL or EASTL.
\n - Many custom libraries don't have the same breadth or depth as std STL or especially EASTL.
\n- Many custom libraries don't have the level of performance tuning that std STL or especially EASTL has.
\n

Info.17\nI think I've found a bug. What do I do?

\n

Verify that you indeed have a bug
\nThere are various levels of bugs that can occur, which include the following:

\n
    \n
  1. Compiler warnings generated by EASTL.
    2. \n
  2. Compiler errors generated by EASTL (failure to compile well-formed code).
    3. \n
  3. Runtime misbehavior by EASTL (function does the wrong thing).
    4. \n
  4. Runtime crash or data corruption by EASTL.
    5. \n
  5. Mismatch between EASTL documentation and behavior.
    6. \n
  6. Mismatch between EASTL behavior and user's expectations (mis-design).
    7. \n
\n

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.
\n
\n Report the bug
\nThe first place to try is the standard EA centralized tech support site. As of this writing (10/2005), that tech site is http://eatech/. 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.
\n
\nIn 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.

\n

Info.18\n Can EASTL be used by third party EA developers?

\n

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.

\n

Performance\n

\n\n

Perf.1 How efficient is EASTL compared to standard C++ STL implementations?

\n

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.

\n

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.

\n

The long answer requires a breakdown of the functionality between various versions of the STL.

\n\n

Perf.2 How efficient is EASTL in general?

\n

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.

\n

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.

\n\n

Perf.3 Strings don't appear to use the \"copy-on-write\" (CoW) optimization. Why not?

\n

\nShort answer
\nCoW provides a benefit for a small percentage of uses but provides a disadvantage for the large majority of uses.
\n
\nLong answer
\nThe primary benefit of CoW is that it allows for the sharing of string data between two string objects. Thus if you say this:\n

string a(\"hello\");\nstring b(a);
\nthe \"hello\" will be shared between a and b. If you then say this:\n
a = \"world\";
\nthen a will release its reference to \"hello\" and \nleave b with the only reference to it. Normally this functionality is accomplished via reference \ncounting and with atomic operations or mutexes.

\n\n

The C++ standard does not say anything about basic_string and CoW. \nHowever, for a basic_string implementation to be standards-conforming, a number of issues arise \nwhich dictate some things about how one would have to implement a CoW string. The discussion of \nthese issues will not be rehashed here, as you can read the references below for better detail \nthan can be provided in the space we have here. However, we can say that the C++ standard \nis sensible and that anything we try to do here to allow for an efficient CoW implementation \nwould result in a generally unacceptable string interface.

\n

The disadvantages of CoW strings are:

\n
    \n
  • A reference count needs to exist with the string, which increases string memory usage.
    • \n
  • With thread safety, atomic operations and mutex locks are expensive, especially on weaker memory systems such as console gaming platforms.
    • \n
  • 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.
    • \n
  • 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.
    • \n
\n

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.

\n

References

\n

This is a good starting HTML reference on the topic:
\n    http://www.gotw.ca/publications/optimizations.htm

\n

Here is a well-known Usenet discussion on the topic:
\n    http://groups-beta.google.com/group/comp.lang.c++.moderated/browse_thread/thread/3dc6af5198d0bf7/886c8642cb06e03d

\n\n

Perf.4 Does EASTL cause code bloat, given that it uses templates?

\n

The reason that templated functions and classes might cause an increase in code size\nbecause each template instantiation theoretically creates a unique piece of code. For example, when you compile this\ncode:

\n
template <typename T>\nconst T min(const T a, const T b)\n    { return b < a ? b : a; }\n\nint    i = min<int>(3, 4);\ndouble d = min<double>(3.0, 4.0);
\n

the compiler treats it as if you wrote this:

\n
int min(const int a, const int b)\n    { return b < a ? b : a; }
\ndouble min(const double a, const double b)\n    { return b < a ? b : a; }
\n

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.

\n

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.

\n

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.

\n

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.

\n

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.

\n

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.

\n

There is a good Usenet discussion on this topic at: http://groups.google.com/group/comp.lang.c++.moderated/browse_frm/thread/2b00649a935997f5

\n

Perf.5\nDon't STL and EASTL containers fragment memory?

\n

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:

\n
    \n
  • 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.
    • \n
  • 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.
    • \n
  • 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.
    • \n
  • 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.
    • \n
\n\n

Perf.6 I don't see container optimizations for equivalent scalar types such as pointer types. Why?

\n

Metrowerks (and no other, as of this writing) STL has some container specializations for type \nT* which maps them to type void*. The idea is that a user who declares a list of Widget* and a list of Gadget* \nwill generate only one container: a list of void*. As a result, code generation will be smaller. Often this is \ndone only in optimized builds, as such containers are harder to view in debug builds due to type information being lost.
\n
\nThe addition of this optimization is under consideration for EASTL, though it might be noted that optimizing \ncompilers such as VC++ are already capable of recognizing duplicate generated code and folding it automatically \nas part of link-time code generation (LTCG) (a.k.a. \"whole program optimization\"). This has been verified \nwith VC++, as the following code and resulting disassembly demonstrate:

\n
eastl::list<int*>        intPtrList;\neastl::list<TestObject*> toPtrList;\n\neastl_size_t n1 = intPtrList.size();\neastl_size_t n2 = toPtrList.size();\n\n0042D288  lea         edx,[esp+14h]\n0042D28C  call        eastl::list<TestObject>::size (414180h)\n0042D291  push        eax \n0042D292  lea         edx,[esp+24h]\n0042D296  call        eastl::list<TestObject>::size (414180h)
\n

Note that in the above case the compiler folded the two implementations of size() into a single implementation.

\n\n

Perf.7\nI've seen some STL's provide a default quick \"node allocator\" as the default allocator. Why doesn't EASTL do this?

\n

Short answer
\nThis is a bad, misguided idea.

\n

Long answer
\nThese 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.

\n

Perf.8 Templates sometimes seem to take a long time to compile. Why do I do about that?\n

\n

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.

\n

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.

\n

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.

\n

Perf.10\nHow well does EASTL inline?

\n

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:

\n
reference operator[](size_type n) {\n   return *(begin() + n);\n}
\nEASTL implements the function directly, like so:\n
reference operator[](size_type n) {\n    return *(mpBegin + n);\n}
\nBoth 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.
\n
\nThat 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.\n

Perf.11\nHow do I control function inlining?

\n

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 elsewhere 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.

\n

Compilation-Level Inlining -- VC++

\n

VC++ has some basic functionality to control inlining, and the compiler is pretty good at doing aggressive inlining when optimizing on for all platforms.

\n
\n

#pragma inline_depth( [0... 255] )

\n

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.

\n

#pragma inline_recursion( [{on | off}] )

\n

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.

\n
\n

Compilation-Level Inlining -- GCC

\n

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.

\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
-fno-default-inlineDo 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.
-fno-inlineDon'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.
-finline-functionsIntegrate 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.
-finline-limit=nBy 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++.
\n
\n 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:
\n
\n max-inline-insns-single
\n    is set to n/2.
\n max-inline-insns-auto
\n    is set to n/2.
\n min-inline-insns
\n    is set to 130 or n/4, whichever is smaller.
\n max-inline-insns-rtl
\n    is set to n.
\n
\n See --param below for a documentation of the individual parameters controlling inlining.
-fkeep-inline-functionsEmit all inline functions into the object file, even if they are inlined where used.
--param name=valueIn 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. 
\n
\n max-inline-insns-single
\n 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.
\n
\n max-inline-insns-auto
\n 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.
\n
\n large-function-insns
\n 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.
\n
\n large-function-growth
\n 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.
\n
\n inline-unit-growth
\n 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.
\n
\n max-inline-insns-recursive
\n max-inline-insns-recursive-auto
\n 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.
\n
\n max-inline-recursive-depth
\n max-inline-recursive-depth-auto
\n 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.
\n
\n inline-call-cost
\n 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.
-finline-limit=n 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++.
\n
\n

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:

\n
\n
\n
\n
max-inline-insns-single
\n
is set to n/2.
\n
\n
max-inline-insns-auto
\n
is set to n/2.
\n
\n
min-inline-insns
\n
is set to 130 or n/4, whichever is smaller.
\n
\n
max-inline-insns-rtl
\n
is set to n.
\n
\n
\n
\n

See below for a documentation of the individual parameters controlling inlining.

\n

Note: 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.

\n

GCC additionally has the -Winline compiler warning, which emits a warning whenever a function declared as inline was not inlined.

\n

Compilation-Level Inlining -- Metrowerks

\n

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.

\n
\n

#pragma always_inline on | off | reset

\n

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.
\n
\n #pragma inline_depth(n)
\n #pragma inline_depth(smart)

\n

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.
\n
\n #pragma inline_max_size(n);
\n #pragma inline_max_total_size(n);

\n

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
\n 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.

\n
\n

Function-Level Inlining -- VC++

\n
\n

To force inline usage under VC++, you use this:

\n

    __forceinline void foo(){ ... }

\n

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.
\n
\n To disable inline usage under VC++, you need to use this:

\n

    #pragma inline_depth(0) // Disable inlining.
\n     void foo() { ... }
\n     #pragma inline_depth()  // Restore default.

\n

The above is essentially specifying compiler-level inlining control within the code for a specific function.

\n
\n

Function-Level Inlining -- GCC / Metrowerks

\n
\n

To force inline usage under GCC 3.1+, you use this:

\n

    inline void foo() __attribute__((always_inline)) { ... }
\n         or
\n     inline __attribute__((always_inline)) void foo() { ... }

\n

To disable inline usage under GCC 3+, you use this:

\n

    void foo() __attribute__((noinline)) { ... }
\n         or
\n     inline __attribute__((noinline)) void foo() { ... }

\n

EABase has some wrappers for this, such as EA_FORCE_INLINE.

\n
\n

Perf.12\n C++ / EASTL seems to bloat my .obj files much more than C does.\n

\n

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.

\n

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.

\n

Perf.13\nWhat are the best compiler settings for EASTL?

\n

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.
\n
\nOptimization Topics

\n
    \n
  • Function inlining.
    • \n
  • Optimization for speed vs. optimization for size.
    • \n
  • Link-time code generation (LTCG).
    • \n
  • Profile-guided optimization (PGO).
    • \n
\n

Function inlining
\n 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):
\n

\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
Inlining DisabledInline only 'inline'Inline any
Application size100K86K86K
Execution time1007575
\n


\nThe 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.

\n

Optimization for Speed / Size
\n 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):
\n

\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
SizeSpeedSpeed + LTCGSpeed + LTCG + PGO
Application size80K100K98K98K
Execution time100908375
\n


\nWhat 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.

\n

Link-time code generation (LTCG)
\n 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.

\n

Profile-guided optimization (PGO)
\n 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.

\n

Problems

\n

Prob.1 \nI'm getting screwy behavior in sorting algorithms or sorted containers. What's wrong?

\n

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.

\n

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.
\n

\n
class SortByDistance : public binary_function<WorldTreeObject*, WorldTreeObject*, bool>\n{\nprivate:\n    Vector3 mOrigin;\n\npublic:\n    SortByDistance(Vector3 origin) {\n        mOrigin = origin;\n    }\n\n    bool operator()(WorldTreeObject* pA, WorldTreeObject* pB) const {\n         return ((WorldObject*)pA)->mPos - mOrigin).GetLength()\n              < ((WorldObject*)pB)->mPos - mOrigin).GetLength();\n    }\n};
\n

Another thing to watch out for is the following mistake:
\n

\n
struct ValuePair\n{\n    uint32_t a;\n    uint32_t b;\n};\n\n// Improve speed by casting the struct to uint64_t\nbool operator<(const ValuePair& vp1, const ValuePair& vp2)\n    { return *(uint64_t*)&vp1 < *(uint64_t*)&vp2; }
\n

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.
\n \n

\n

Prob.2 I am getting compiler warnings (e.g. C4244, C4242 or C4267) that make no sense. Why?

\nOne 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\n
template <typename T>\nT min(const T a, const T b) {\n    return b < a ? b : a;\n}
\nIf you compile this code:\n
ptrdiff_t a = min(ptrdiff_t(0), ptrdiff_t(1));\nint       b = min((int)0, (int)1);
\nYou will get the following warning for the second line, which is somewhat nonsensical:\n
warning C4244: 'initializing' : conversion from 'const ptrdiff_t' to 'int', possible loss of data
\n

This could probably be considered a VC++ bug, but in the meantime you have little choice but to ignore the warning or disable it.

\n\n

Prob.3\nI am getting compiler warning C4530, which complains about exception handling and \"unwind semantics.\" What gives?

\n

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%.
\n
\nIf you have stack unwinding disabled, but you have try/catch statements, VC++ will generate the following warning:

\n
warning C4530: C++ exception handler used, but unwind semantics are not enabled. Specify /EHsc
\n

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.

\n

Prob.4\n Why are tree-based EASTL containers hard to read with a\ndebugger?

\n

Short answer
\n Maximum performance and design mandates.

\n

Long answer
\nYou 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.

\n

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.

\n

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.

\n

See Debug.2 for more.\n

Prob.5\nThe EASTL source code is sometimes rather complicated looking. Why is that?

\n

Short answer
\nMaximum performance.

\n

Long answer
\n 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.

\n

As an example of this, take a look at the implementation of the copy 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.

\n

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.

\n

Prob.6\nWhen I get compilation errors, they are very long and complicated looking. What do I do?

\n

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

\n

Top five approaches to dealing with long compilation errors:

\n
    \n
  1. 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.
    2. \n
  2. 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.
    3. \n
  3. 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
    4. \n
  4. 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/. 
    5. \n
  5. 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/).
    6. \n
\n

Top five causes of EASTL compilation errors:

\n
    \n
  1. const-correctness. Perhaps a quarter of container template errors are due to the user not specifying const correctly.
    2. \n
  2. 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.
    3. \n
  3. 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.
    4. \n
  4. 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.
    5. \n
  5. 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 \">>\" next to each other that you need to separate them by one space (e.g. \"> >\").
    6. \n
\n

Prob.7\n Templates sometimes seem to take a long time to compile. Why do I do about that?\n

\n

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.

\n

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.

\n

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.

\n

Prob.8\nI get the compiler error: \"template instantiation depth exceeds maximum of 17. use -ftemplate-depth-NN to increase the maximum\". 

\n

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.

\n

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.

\n

From the GCC documentation:

\n
-ftemplate-depth-n\n\nSet the maximum instantiation depth for template classes to n. \nA limit on the template instantiation depth is needed to detect \nendless recursions during template class instantiation ANSI/ISO \nC++ conforming programs must not rely on a maximum depth greater than 17.\n
\n\n

Note that starting with GCC 4.5 the syntax is -ftemplate-depth=N instead of -ftemplate-depth-n.

\n

Prob.9\n I'm getting errors about min and max while compiling.

\n

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.

\n

Prob.10\nC++ / EASTL seems to bloat my .obj files much more than C does.

\n

There is no need to worry. The way most C++ compilers compile templates, they compile all\nseen template code into the current .obj module, which results in larger .obj files and duplicated template code in\nmultiple .obj files. However, the linker will (and must) select only a single version of any given function for the\napplication, and these linked functions will usually be located contiguously.

\n

Prob.11 \n I'm getting compiler errors regarding placement operator new\nbeing previously defined.

\n

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:

\n

     Placement forms
\n     1. These functions are reserved, a C++ program may not define functions that displace the versions in the Standard C++ library.

\n

You may find that #defining __PLACEMENT_NEW_INLINE 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.

\n

Prob.12\nI'm getting errors related to wchar_t string  functions such as wcslen().

\n

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.

\n
    \n
  • The #define EA_WCHAR_SIZE is equal to sizeof(wchar_t).
    • \n
  • If sizeof(wchar_t) == 2, then char16_t is typedef'd to wchar_t.
    • \n
  • If sizeof(wchar_t) == 4, then char32_t is typedef'd to wchar_t.
    • \n
\n

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.

\n

Prob.13\n I'm getting compiler warning C4619: there is no warning number Cxxxx\n(e.g. C4217).

\n

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.

\n

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.

\n

Prob.14\nMy stack-based fixed_vector is not respecting the object alignment requirements.

\n

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 http://msdn2.microsoft.com/en-us/library/83ythb65(VS.71).aspx, this doesn't work for stack variables. The two primary means of working around this are:

\n
    \n
  • Use something like AlignedObject<> from the EAStdC package's EAAllocator.h file.
    • \n
  • 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.
    • \n
\n

Prob.15 I am getting compiler errors when using GCC under XCode (Macintosh/iphone).

\n

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.

\n

Prob.16 I am getting linker errors about Vsnprintf8 or Vsnprintf16.

\n

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.

\n

Example of providing Vsnprintf8 via EAStdC:

\n
#include <EAStdC/EASprintf.h>\n   \nint Vsnprintf8(char8_t* pDestination, size_t n, const char8_t* pFormat, va_list arguments)\n{\n    return EA::StdC::Vsnprintf(pDestination, n, pFormat, arguments);\n}\n\nint Vsnprintf16(char16_t* pDestination, size_t n, const char16_t* pFormat, va_list arguments)\n{\n    return EA::StdC::Vsnprintf(pDestination, n, pFormat, arguments);\n}
\n

Example of providing Vsnprintf8 via C libraries:

\n
#include <stdio.h>\n   \nint Vsnprintf8(char8_t* p, size_t n, const char8_t* pFormat, va_list arguments)\n{\n    #ifdef _MSC_VER\n        return vsnprintf_s(p, n, _TRUNCATE, pFormat, arguments);\n    #else\n        return vsnprintf(p, n, pFormat, arguments);\n    #endif\n}\n\nint Vsnprintf16(char16_t* p, size_t n, const char16_t* pFormat, va_list arguments)\n{\n    #ifdef _MSC_VER\n        return vsnwprintf_s(p, n, _TRUNCATE, pFormat, arguments);\n    #else\n        return vsnwprintf(p, n, pFormat, arguments); // Won't work on Unix because its libraries implement wchar_t as int32_t.\n    #endif\n}
\n

Prob.17 I am getting compiler errors about UINT64_C or UINT32_C.

\n

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.

\n

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.

\n

Prob.18 I am getting a crash with a global EASTL container.

\n

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:

\n

Failing code:

\n
eastl::list<int> gIntList; // Global variable.\n   \nvoid DoSomething()\n{\n    gIntList.push_back(1); // Crash. gIntList was never constructed.\n}
\n

Declaring a pointer solution:

\n
eastl::list<int>* gIntList = NULL;\n   \nvoid DoSomething()\n{\n    if(!gIntList) // Or move this to an init function.\n        gIntList = new eastl::list<int>;\n\n    gIntList->push_back(1); // Success\n}
\n

Manual constructor call solution:

\n
eastl::list<int> gIntList;\n   \nvoid InitSystem()\n{\n    new(&gIntList) eastl::list<int>;\n}\n\nvoid DoSomething()\n{\n    gIntList.push_back(1); // Success\n}
\n

Prob.19 Why doesn't EASTL support passing NULL string functions?

\n

\n

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:

\n
    \n
  • It breaks consistency with the C++ STL library and C libraries, which require strings to be valid.
    • \n
  • It makes the coder slower and bigger for all users, though few need NULL checks.
    • \n
  • 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.
    • \n
  • 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).
    • \n
  • 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.
    • \n
  • 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.
    • \n
\n

Debug

\n

Debug.1\nHow do I set the VC++ debugger to display EASTL container data with tooltips?

\n

See Cont.9

\n

Debug.2\nHow do I view containers if the visualizer/tooltip support is not present?

\n\n

Here is a table of answers about how to manually inspect containers in the debugger.

\n
\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
 ContainerApproach
slist
\n fixed_slist		slist is a singly-linked list. Look at the slist mNode variable. You can walk the list by looking at mNode.mpNext, etc.
list
\n fixed_list		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.
intrusive_list
\n intrusive_slist†		Look at the list mAnchor node. This lets you walk forward and backward in the list via mpNext and mpPrev.
arrayView the array mValue member in the debugger. It's simply a C style array.
vector
\n fixed_vector		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
vector_set
\n vector_multiset
\n vector_map
\n vector_multimap
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.
deque
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.
bitvectorLook at the bitvector mContainer variable. If it's a vector, then see vector above.
bitsetLook at the bitset mWord variable. The bitset is nothing but one or more uint32_t mWord items.
set
\n multiset
\n fixed_set
\n fixed_multiset
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()).
map
\n multimap
\n fixed_map
\n fixed_multimap		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()).
hash_map
\n hash_multimap
\n fixed_hash_map
\n fixed_hash_multimap		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.
intrusive_hash_map
\n intrusive_hash_multimap
\n intrusive_hash_set
\n intrusive_hash_multiset		intrusive hash tables in EASTL are implemented very similarly to regular hash tables. See the hash_map and hash_set entries for more info.
hash_set
\n hash_multiset
\n fixed_hash_set
\n fixed_hash_map
hash tables in EASTL are implemented as an array of singly-linked lists. The array is the mpBucketArray member.
basic_string
\n fixed_string
\n fixed_substring		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
heap
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.
stack
View the stack member c value in the debugger. That member will typically be a list or deque.
queue
View the queue member c value in the debugger. That member will typically be a list or deque.
priority_queue
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.
smart_ptrView the mpValue member.
\n
\n

Debug.3\nThe EASTL source code is sometimes rather complicated looking. Why is that?

\n

Short answer
\nMaximum performance.

\n

Long answer
\n 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.

\n

As an example of this, take a look at the implementation of the copy 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.

\n

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.

\n

Debug.4\nWhen I get compilation errors, they are very long and complicated looking. What do I do?

\n

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
\n
\nTop five approaches to dealing with long compilation errors:

\n
    \n
  1. 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.
    2. \n
  2. 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.
    3. \n
  3. 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
    4. \n
  4. 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/. 
    5. \n
  5. 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/).
    6. \n
\n

Top five causes of EASTL compilation errors:

\n
    \n
  1. const-correctness. Perhaps a quarter of container template errors are due to the user not specifying const correctly.
    2. \n
  2. 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.
    3. \n
  3. 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.
    4. \n
  4. 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.
    5. \n
  5. 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 \">>\" next to each other that you need to separate them by one space (e.g. \"> >\").
    6. \n
\n

Debug.5\nHow do I measure hash table balancing?

\n

The following functionality lets you spelunk hash container layout.

\n
    \n
  • There is the load_factor function which tells you the overall hashtable load, but doesn't tell you if a load is unevenly distributed.
    • \n
  • You can control the load factor and thus the automated bucket redistribution with set_load_factor.
    • \n
  • 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.
    • \n
  • You can use the above to get the size of any bucket, but there is also simply the bucket_size(size_type n) function.
    • \n
  • The bucket_count function tells you the count of buckets. So with this you can completely visualize the layout of the hash table.
    • \n
  • There is also iterator find_by_hash(hash_code_t c), for what it's worth.
    • \n
\n

The following function draws an ASCII bar graph of the hash table for easy visualization of bucket distribution:

\n
\n

#include <EASTL/hash_map.h>
\n #include <EASTL/algorithm.h>
\n #include <stdio.h>
\n
\n template <typename HashTable>
\n void VisualizeHashTableBuckets(const HashTable& h)
\n {
\n    eastl_size_t bucketCount       = h.bucket_count();
\n    eastl_size_t largestBucketSize = 0;
\n
\n    for(eastl_size_t i = 0; i < bucketCount; i++)
\n        largestBucketSize = eastl::max_alt(largestBucketSize, h.bucket_size(i));
\n
\n    YourPrintFunction("\\n --------------------------------------------------------------------------------\\n");
\n
\n    for(eastl_size_t i = 0; i < bucketCount; i++)
\n    {
\n        const eastl_size_t k = h.bucket_size(i) * 80 / largestBucketSize;
\n
\n        char buffer[16];
\n        sprintf(buffer, "%3u|", (unsigned)i);
\n        YourPrintFunction(buffer);
\n
\n        for(eastl_size_t j = 0; j < k; j++)
\n            YourPrintFunction("*");
\n
\n        YourPrintFunction("\\n");
\n    }
\n
\n    YourPrintFunction(" --------------------------------------------------------------------------------\\n");
\n }

\n
\n

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.\n

\n

   ------------------------------------------------------
\n 0|********************************************
\n 1|************************************************
\n 2|***************************************
\n 3|********************************************
\n 4|*****************************************************
\n 5|*************************************************
\n 6|****************************************
\n 7|***********************************************
\n 8|********************************************
\n 9|**************************************
\n 10|********************************************
\n   -----------------------------------------------------\n

\n

Containers

\n

Cont.1\nWhy do some containers have \"fixed\" versions (e.g. fixed_list) but others(e.g. deque) don't have fixed versions?

\n

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.

\n

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:

\n
array, deque, bitset, stack, queue, priority_queue,\nintrusive_list, intrusive_hash_map, intrusive_hash_set,\nintrusive_hash_multimap, intrusive_hash_multimap,\nvector_map, vector_multimap, vector_set, vector_multiset.
\n

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.

\n

Cont.2\nCan I mix EASTL with standard C++ STL?

\n

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.

\n

Things that you definitely can do:

\n
    \n
  • #include both EASTL and standard STL headers from the same .cpp file.
    • \n
  • Use EASTL containers to hold STL containers.
    • \n
  • Construct an STL reverse_iterator from an EASTL iterator.
    • \n
  • Construct an EASTL reverse_iterator from an STL iterator.
    • \n
\n

Things that you probably will be able to do, though a given std STL implementation may prevent it:\n

\n
    \n
  • Use STL containers in EASTL algorithms.
    • \n
  • Use EASTL containers in STL algorithms.
    • \n
  • Construct or assign to an STL container via iterators into an EASTL container.
    • \n
  • Construct or assign to an EASTL container via iterators into an STL container.
    • \n
\n

Things that you would be able to do if the given std STL implementation is bug-free:\n

\n
    \n
  • 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.
    • \n
\n

Things that you definitely can't do:\n

\n
    \n
  • Use an STL allocator directly with an EASTL container (though you can use one indirectly).
    • \n
  • Use an EASTL allocator directly with an STL container (though you can use one indirectly).
    • \n
\n

Cont.3\nWhy are there so many containers?

\n

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.

\n

Cont.4\nDon't STL and EASTL containers fragment memory?

\n

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:

\n
    \n
  • 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.
    • \n
  • 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.
    • \n
  • 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.
    • \n
  • 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.
    • \n
\n

Cont.5\n I don't see container optimizations for equivalent scalar types such\nas pointer types. Why?

\n

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.
\n
\nThe 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:

\n
eastl::list<int*>        intPtrList;\neastl::list<TestObject*> toPtrList;\n\neastl_size_t n1 = intPtrList.size();\neastl_size_t n2 = toPtrList.size();\n\n0042D288  lea         edx,[esp+14h]\n0042D28C  call        eastl::list<TestObject>::size (414180h)\n0042D291  push        eax \n0042D292  lea         edx,[esp+24h]\n0042D296  call        eastl::list<TestObject>::size (414180h)
\nNote that in the above case the compiler folded the two implementations of size() into a single implementation.
\n

Cont.6\nWhat about alternative container and algorithm implementations (e.g. treaps, skip lists, avl trees)?

\n

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:

\n

Implemented:

\n
    \n
  • intrusive_list, etc. -- Saves memory and improves cache locality.
    • \n
  • vector_map, etc. -- Saves memory and improves cache locality.
    • \n
  • ring_buffer -- Useful for some types of operations and has no alternative.
    • \n
  • shell_sort -- Useful sorting algorithm.
    • \n
  • sparse_matrix -- Useful for some types of operations and has no alternative.
    • \n
\n

Not implemented:\n

\n
    \n
  • skip lists (alternative to red-black tree) -- These use more memory and usually perform worse than rbtrees.
    • \n
  • treap (alternative to red-black tree) -- These are easier and smaller than rbtrees, but perform worse.
    • \n
  • avl tree (alternative to red-black tree) -- These have slightly better search performance than rbtrees, but significantly worse insert/remove performance.
    • \n
  • btree (alternative to red-black tree) --  These are no better than rbtrees.
    • \n
\n

If you have an idea of something that should be implemented, please suggest it or even provide at least a prototypical implementation.

\n

Cont.7\nWhy are tree-based EASTL containers hard to read with a debugger?

\n

Short answer
\n Maximum performance and design mandates.

\n

Long answer
\nYou 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.

\n

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.

\n

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.

\n

Cont.8\nHow do I assign a custom allocator to an EASTL container?

\n

There are two ways of doing this:

\n
    \n
  1. Use the set_allocator function that is present in each container.
    2. \n
  2. Specify a new allocator type via the Allocator template parameter that is present in each container.
    3. \n
\n

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.

\n

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.

\n
class custom_allocator\n{\npublic:\n    custom_allocator(const char* pName = EASTL_NAME_VAL(\"custom allocator\"))\n    {\n        #if EASTL_NAME_ENABLED\n            mpName = pName ? pName : EASTL_ALLOCATOR_DEFAULT_NAME;\n        #endif\n\n        // Possibly do something here.\n    }\n\n    custom_allocator(const allocator& x, const char* pName = EASTL_NAME_VAL(\"custom allocator\"));\n    {\n        #if EASTL_NAME_ENABLED\n            mpName = pName ? pName : EASTL_ALLOCATOR_DEFAULT_NAME;\n        #endif\n\n        // Possibly copy from x here.\n    }\n\n    ~custom_allocator();\n    {\n        // Possibly do something here.\n    }\n\n    custom_allocator& operator=(const custom_allocator& x)\n    {\n        // Possibly copy from x here.\n        return *this;\n    }\n\n    void* allocate(size_t n, int flags = 0)\n    {\n        // Implement the allocation here.\n    }\n\n    void* allocate(size_t n, size_t alignment, size_t offset, int flags = 0)\n    {\n        // Implement the allocation here.\n    }\n\n    void deallocate(void* p, size_t n)\n    {\n        // Implement the deallocation here.\n    }\n\n    const char* get_name() const\n    {\n        #if EASTL_NAME_ENABLED\n            return mpName;\n        #else\n            return \"custom allocator\";\n        #endif\n    }\n\n    void set_name(const char* pName)\n    {\n        #if EASTL_NAME_ENABLED\n            mpName = pName;\n        #endif\n    }\n\nprotected:\n    // Possibly place instance data here.\n\n    #if EASTL_NAME_ENABLED\n        const char* mpName; // Debug name, used to track memory.\n    #endif\n};\n\n\ninline bool operator==(const allocator& a, const allocator& b)\n{\n    // Provide a comparison here.\n}\n\ninline bool operator!=(const allocator& a, const allocator& b)\n{\n    // Provide a negative comparison here.\n}
\n

Here's an example of how to use the above custom allocator:

\n
// Declare a Widget list and have it default construct.\nlist<Widget, custom_allocator> widgetList;\n\n// Declare a Widget list and have it construct with a copy of some global allocator.\nlist<Widget, custom_allocator> widgetList2(gSomeGlobalAllocator);\n\n// Declare a Widget list and have it default construct, but assign\n// an underlying implementation after construction.\nlist<Widget, custom_allocator> widgetList;\nwidgetList.get_allocator().mpIAllocator = new WidgetAllocatorImpl;
\n\n

Cont.9 How do I set the VC++ debugger to display EASTL container data with tooltips?

\n

Visual Studio supports this via the AutoExp.dat file, an example of which is present with this documentation.

\n

Sometimes the AutoExp.dat doesn't seem to work. Avery Lee's explanation:

\n
\n

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.

\n
\n

Cont.10\nHow do I use a memory pool with a container?

\n

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:

\n
    \n
  • Assign a custom allocator to a container. eastl::fixed_pool provides an implementation.
    • \n
  • Use one of the EASTL fixed containers, such as fixed_list.
    • \n
\n

Custom Allocator
\nIn 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):

\n
typedef list<Widget, MemoryPool> WidgetList;           // Declare your WidgetList type.\n\nMemoryPool myPool(sizeof(WidgetList::node_type), 100); // Make a pool of 100 Widget nodes.\nWidgetList myList(&myPool);                            // Create a list that uses the pool.
\n

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.

\n

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).

\n

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:

\n
char buffer[256];\n\nlist<Widget, fixed_pool> myList;\nmyList.get_allocator().init(buffer, 256);
\n

Fixed Container
\nIn 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:

\n
fixed_list<Widget, 100> fixedList; // Declare a fixed_list that can hold 100 Widgets
\n

Cont.11\nHow do I write a comparison (operator<()) for a struct that contains two or more members? 

\n

See Algo.2

\n

Cont.12\nWhy doesn't container X have member function Y?

\n

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.

\n

The answer usually boils down to two reasons:

\n
    \n
  • The functionality exists in a more centralized location elsewhere, such as the algorithms.
    • \n
  • The functionality can be had by using other member functions.
    • \n
\n

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 any 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:
\n

\n
list<int>::iterator i = find(list.begin(), list.end(), 3);
\n

And in order to sort a vector, you would do this:
\n

\n
quick_sort(v.begin(), v.end());   // Sort the entire array.\n
\nquick_sort(&v[3], &v[8]);         // Sort the items at the indexes in the range of [3, 8).
\n

In the case of functionality that can be had by using other member functions, \nnote that EASTL follows the philosophy that duplicated functionality should not exist in a container, \nwith exceptions being made for cases where mistakes and unsafe practices commonly happen if the given \nfunction isn't present. In the case of string not having a mid function, this is because there is a \nstring constructor that takes a sub-range of another string. So to make a string out of the middle of \nanother, you would do this:

\n
string strMid(str, 3, 5); // Make a new string of the characters from the source range of [3, 3+5).
\n

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.

\n

Cont.13\nHow 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.

\n

The problem is illustrated with this example:

\n
map<string, Widget> swMap;\n  ...\nmap<string, Widget>::iterator it = swMap.find(\"blue\"); // A temporary string object is created here.
\n

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:\n

\n
    \n
  • 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.
    • \n
  • 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.
    • \n
\n

Cont.14\nWhy are set and hash_set iterators const (i.e. const_iterator)?

\n

The situation is illustrated with this example:

\n
set<int> intSet;\n\nintSet.insert(1);\nset<int>::iterator i = intSet.begin();\n*i = 2; // Error: iterator i is const.
\n

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.

\n\n

Cont.15\nHow do I prevent my hash container from re-hashing?

\n

If you want to make a hashtable never re-hash (i.e. increase/reallocate its bucket count), \ncall set_max_load_factor with a very high value such as 100000.f.

\n

Similarly, you can control the bucket growth factor with the rehash_policy function. \nBy default, when buckets reallocate, they reallocate to about twice their previous count. \nYou can control that value as with the example code here:

\n
hash_set<int> hashSet;\nhashSet.rehash_policy().mfGrowthFactor = 1.5f
\n\n

\n Cont.16\nWhich uses less memory, a map or a hash_map?\n

\n

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.

\n

Cont.17\nHow do I write a custom hash function?

\n

You can look at the existing hash functions in functional.h, but we provide a couple examples here.

\n

To write a specific hash function for a Widget class, you would do this:

\n
struct WidgetHash {\n    size_t operator()(const Widget& w) const\n        { return w.id; }\n};\n\nhash_set<Widget, WidgetHash> widgetHashSet;
\n

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:
\n

\n
template <typename T>\nstruct GeneralHash {\n    size_t operator()(const T& t) const\n        { return t.id; }\n};\n\nhash_set<Widget, GeneralHash<Widget> > widgetHashSet;\nhash_set<Dogget, GeneralHash<Dogget> > doggetHashSet;
\n\n

Cont.18\nHow do I write a custom compare function for a map or set?

\n

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:
\n

\n
struct WidgetLess {\n    bool operator()(const Widget& w1, const Widget& w2) const\n        { return w.id < w2.id; }\n};\n\nset<Widget, WidgetLess> wSet;
\n

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.\"

\n

Cont.19\nHow do I force my vector or string capacity down to the size of the container?

\n

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.

\n
eastl::vector<Widget> x;\nx.set_capacity();   // Shrink x's capacity to be equal to its size.\n\neastl::vector<Widget> x;\nx.set_capacity(0);  // Completely clear x.
\n

To compact your vector or string in a way that would also work with std STL you need to do the following.

\n

How to shrink a vector's capacity to be equal to its size:

\n
std::vector<Widget> x;\nstd::vector<Widget>(x).swap(x); // Shrink x's capacity.
\nHow to completely clear a std::vector (size = 0, capacity = 0, no allocation):
\n
std::vector<Widget> x;\nstd::vector<Widget>().swap(x); // Completely clear x.\n
\n

Cont.20\nHow do I iterate a container while (selectively) removing items from it?

\n

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:

\n
set<int> intSet;
\nset<int>::iterator i = intSet.begin();
\nwhile(i != intSet.end())\n{\n    if(*i & 1)  // Erase all odd integers from the container.\n        i = intSet.erase(i);\n    else\n        ++i;\n}
\n

Cont.21\nHow do I store a pointer in a container?

\n

The problem with storing pointers in containers is that clearing the container will not\nfree the pointers automatically. There are two conventional resolutions to this problem:

\n
    \n
  • Manually free pointers when removing them from containers. 
    • \n
  • Store the pointer as a smart pointer instead of a \"raw\"pointer.
    • \n
\n

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.

\n

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.

\n

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:

\n
list< shared_ptr<Widget> > wList;\n\nwList.push_back(shared_ptr<Widget>(new Widget));\nwList.pop_back(); // The Widget will be freed.
\n

Cont.22\nHow do I make a union of two containers? difference? intersection?

\n

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.

\n

Cont.23\nHow do I override the default global allocator? 

\n

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:

\n
    \n
  • Simply provide the following versions of operator new (which EASTL requires, actually):
    \n     void* operator new[](size_t size, const char* pName, int flags, unsigned debugFlags, const char* file, int line);
    \n     void* operator new[](size_t size, size_t alignment, size_t alignmentOffset, const char* pName, int flags, unsigned debugFlags, const char* file, int line);
    • \n
  • Predefine the config.h macros for EASTLAlloc, EASTLFree, etc. See config.h for this.
    • \n
  • Override config.h entirely via EASTL_USER_CONFIG_HEADER. See config.h for this.
    • \n
  • Provide your own version of allocator.h/cpp
    • \n
  • Provide your own version of config.h. 
    • \n
\n

If you redefine the allocator class, you can make it work however you want.

\n

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.

\n

Cont.24\nHow do I do trick X with the string container?

\n

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.
\n
\nfind_and_replace

\n
template <typename String>\nvoid find_and_replace(String& s, const typename String::value_type* pFind, const typename String::value_type* pReplace)    \n{\n    for(size_t i; (i = source.find(pFind)) != T::npos; )\n        s.replace(i, eastl::CharStrlen(pFind), pReplace);\n}\n\nExample:\n    find_and_replace(s, \"hello\", \"hola\");
\n

trim front (multiple chars)

\n
template <typename String>\nvoid trim_front(String& s, const typename String::value_type* pValues)\n{\n    s.erase(0, s.find_first_not_of(pValues));\n}\n\nExample:\n    trim_front(s, \" \\t\\n\\r\");
\n

trim back (multiple chars)

\n
template <typename String>\nvoid trim_front(String& s, const typename String::value_type* pValues)\n{\n    s.resize(s.find_last_not_of(pValues) + 1);\n}\n\nExample:\n    trim_back(s, \" \\t\\n\\r\");
\n

prepend

\n
template <typename String>\nvoid prepend(String& s, const typename String::value_type* p)\n{\n    s.insert(0, p);\n}\n\nExample:\n    prepend(s, \"log: \");
\n

begins_with\n

\n
template <typename String>\nbool begins_with(const String& s, const typename String::value_type* p)\n{\n    return s.compare(0, eastl::CharStrlen(p), p) == 0;\n}\n\nExample:\n    if(begins_with(s, \"log: \")) ...
\n

ends_with

\n
template <typename String>\nbool ends_with(const String& s, const typename String::value_type* p)\n{\n    const typename String::size_type n1 = s.size();\n    const typename String::size_type n2 = eastl::CharStrlen(p);\n    return ((n1 >= n2) && s.compare(n1 - n2, n2, p) == 0);\n}\n\nExample:\n    if(ends_with(s, \"test.\")) ...
\n

tokenize
\nHere is a simple tokenization function that acts very much like the C strtok function. 

\n
template <typename String>\nsize_t tokenize(const String& s, const typename String::value_type* pDelimiters,\n                String* resultArray, size_t resultArraySize)\n{\n    size_t n = 0;\n    typename String::size_type lastPos = s.find_first_not_of(pDelimiters, 0);\n    typename String::size_type pos     = s.find_first_of(pDelimiters, lastPos);\n\n    while((n < resultArraySize) && (pos != String::npos) || (lastPos != String::npos))\n    {\n        resultArray[n++].assign(s, lastPos, pos - lastPos);\n        lastPos = s.find_first_not_of(pDelimiters, pos);\n        pos     = s.find_first_of(pDelimiters, lastPos);\n    }\n\n    return n;\n}\n\nExample:\n   string resultArray[32];\ntokenize(s, \" \\t\", resultArray, 32));
\n \n

Cont.25 How do EASTL smart pointers compare to Boost smart pointers? 

\n

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:

\n
    \n
  • 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.
    • \n
\n
    \n
  • 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.
    • \n
\n

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.

\n

Cont.26\nHow do your forward-declare an EASTL container?

\n

Here is are some examples of how to do this:

\n
namespace eastl\n{\n    template <typename T, typename Allocator> class basic_string;\n    typedef basic_string<char, allocator> string8;   // Forward declare EASTL's string8 type.\n\n    template <typename T, typename Allocator> class vector;\n    typedef vector<char, allocator> CharArray;\n\n    template <typename Value, typename Hash, typename Predicate, typename Allocator, bool bCacheHashCode> class hash_set;\n\n    template <typename Key, typename T, typename Compare, typename Allocator> class map;\n}
\n

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.

\n

Cont.27\nHow do I make two containers share a memory pool?

\n

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.

\n

Here is some example code:

\n
struct fixed_pool_reference
{
public:
    fixed_pool_reference()
    {
        mpFixedPool = NULL;
    }
 
    fixed_pool_reference(eastl::fixed_pool& fixedPool)
    {
        mpFixedPool = &fixedPool;
    }
 
    fixed_pool_reference(const fixed_pool_reference& x)
    {
        mpFixedPool = x.mpFixedPool;
    }
 
    fixed_pool_reference& operator=(const fixed_pool_reference& x)
    {
        mpFixedPool = x.mpFixedPool;
        return *this;
    }
 
    void* allocate(size_t /*n*/, int /*flags*/ = 0)
    {
        return mpFixedPool->allocate();
    }
 
    void* allocate(size_t /*n*/, size_t /*alignment*/, size_t /*offset*/, int /*flags*/ = 0)
    {
        return mpFixedPool->allocate();
    }
 
    void deallocate(void* p, size_t /*n*/)
    {
        return mpFixedPool->deallocate(p);
    }
 
    const char* get_name() const
    {
        return "fixed_pool_reference";
    }
 
    void set_name(const char* /*pName*/)
    {
    }
 
protected:
    friend bool operator==(const fixed_pool_reference& a, const fixed_pool_reference& b);
    friend bool operator!=(const fixed_pool_reference& a, const fixed_pool_reference& b);
 
    eastl::fixed_pool* mpFixedPool;
};\n\ninline bool operator==(const fixed_pool_reference& a, const fixed_pool_reference& b)\n{\n    return (a.mpFixedPool == b.mpFixedPool);
}\n\ninline bool operator!=(const fixed_pool_reference& a, const fixed_pool_reference& b)\n{\n    return (a.mpFixedPool != b.mpFixedPool);\n}
\n

Example usage of the above:

\n
typedef eastl::list<int, fixed_pool_reference> IntList;\n\nIntList::node_type buffer[2];\neastl::fixed_pool  myPool(buffer, sizeof(buffer), sizeof(Int::node_type), 2);\n\nIntList myList1(myPool);\nIntList myList2(myPool);\n           \nmyList1.push_back(37);\nmyList2.push_back(39);
\n

Cont.28\nCan I use a std (STL) allocator with EASTL?

\n

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:

\n
    \n
  • EASTL allocators have a different allocate function signature.
    • \n
  • EASTL allocators have as many as four extra required functions: ctor(name), get_name(), set_name(), allocate(size, align, offset).
    • \n
  • EASTL allocators have an additional allocate function specifically for aligned allocations, as listed directly above.
    • \n
\n

What are the requirements of classes stored in containers?

\n

Class types stored in containers must have:

\n
    \n
  • a public copy constructor
    • \n
  • a public assignment operator
    • \n
  • a public destructor
    • \n
  • an operator < that compares two such classes (sorted containers only).
    • \n
  • an operator == that compares two such classes (hash containers only).
    • \n
\n

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.

\n

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.

\n
struct NotAPod\n{\n   NotAPod(const NotAPod&) {} // Intentionally don't copy the refCount 
\n   int refCount; // refCounts should not be copied between NotAPod instances. \n}; \n \neastl::vector<NotAPod> v;
\n

Algorithms

\n

Algo.1\n I'm getting screwy behavior in sorting algorithms or sorted\ncontainers. What's wrong?

\n

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.

\n

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.

\n
class SortByDistance : public binary_function<WorldTreeObject*, WorldTreeObject*, bool>\n{\nprivate:\n    Vector3 mOrigin;\n\npublic:\n    SortByDistance(Vector3 origin) {\n        mOrigin = origin;\n    }\n\n    bool operator()(WorldTreeObject* pA, WorldTreeObject* pB) const {\n        return ((WorldObject*)pA)->mPos - mOrigin).GetLength()\n             < ((WorldObject*)pB)->mPos - mOrigin).GetLength();\n    }\n};
\n\n

Algo.2\nHow do I write a comparison (operator<()) for a struct that contains two or more members? 

\n

For a struct with two members such as the following:

\n
struct X {\n    Blah m1;\n    Blah m2;\n};
\n

You would write the comparison function like this:

\n
bool operator<(const X& a, const X& b) {\n    return (a.m1 == b.m1) ? (a.m2 < b.m2) : (a.m1 < b.m1);\n}
\n

or, using only operator < but more instructions:

\n
bool operator<(const X& a, const X& b) {\n    return (a.m1 < b.m1) || (!(b.m1 < a.m1) && (a.m2 < b.m2));\n}
\n

For a struct with three members, you would have:

\n
bool operator<(const X& a, const X& b) {\n    if(a.m1 != b.m1)\n        return (a.m1 < b.m1);\n    if(a.m2 != b.m2)\n        return (a.m2 < b.m2);\n    return (a.mType < b.mType);\n}
\n

And a somewhat messy implementation if you wanted to use only operator <.

\n

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.

\n
bool operator<(const Point2D& a, const Point2D& b) {\n    return (a.x == b.x) ? (a.y < b.y) : (a.x < b.x);\n}
\n

Algo.3\nHow do I sort something in reverse order?

\n

Normally sorting puts the lowest value items first in the sorted range. You can change this by simply reversing the comparison. For example:
\n

\n
sort(intVector.begin(), intVector.end(), greater<int>());
\n

It's important that you use operator > instead of >=. The comparison function must return false for every case where values are equal.

\n

Algo.4\nI'm getting errors about min and max while compiling.

\n

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.

\n

Algo.5\nWhy don't algorithms take a container as an argument instead of iterators? A container would be more convenient.

\n

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.

\n

Providing additional algorithms that use containers would introduce redundancy with respect to the existing algorithms that use iterators.

\n

Algo.6\nGiven a container of pointers, how do I find an element by value (instead of by pointer)?

\n

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.

\n

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:

\n
template<typename T>\nstruct dereferenced_equal\n{\n    const T& mValue;\n\n    dereferenced_equal(const T& value) : mValue(value) { }     \n    bool operator==(const T* pValue) const { return *pValue == mValue; }\n};\n\n...\n\nfind_if(container.begin(), container.end(), dereferenced_equal<Widget>(someWidget));
\n\n

Algo.7\nWhen do stored objects need to support operator < vs. when do they need to support operator ==?

\n

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 <.

\n

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 ==.

\n

Some algorithms and containers require neither < nor ==. Interestingly, no algorithm or container requires both < and ==.

\n

Algo.8 How do I sort via pointers or array indexes instead of objects directly?

\n

Pointers

\n
vector<TestObject>  toArray;\nvector<TestObject*> topArray;\n\nfor(eastl_size_t i = 0; i < 32; i++)\n   toArray.push_back(TestObject(rng.RandLimit(20)));\nfor(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.\n   topArray.push_back(&toArray[i]);\n\nstruct TestObjectPtrCompare\n{\n    bool operator()(TestObject* a, TestObject* b)\n        { return a->mX < a->mX; }\n};\n\nquick_sort(topArray.begin(), topArray.end(), TestObjectPtrCompare());
\n

Array indexes

\n
vector<TestObject>   toArray;\nvector<eastl_size_t> toiArray;\n\nfor(eastl_size_t i = 0; i < 32; i++)\n{\n    toArray.push_back(TestObject(rng.RandLimit(20)));\n    toiArray.push_back(i);\n}\n\nstruct TestObjectIndexCompare\n{\n    vector* mpArray;\n\n    TestObjectIndexCompare(vector<TestObject>* pArray) : mpArray(pArray) { }\n    TestObjectIndexCompare(const TestObjectIndexCompare& x) : mpArray(x.mpArray){ }\n    TestObjectIndexCompare& operator=(const TestObjectIndexCompare& x) { mpArray = x.mpArray; return *this; }\n\n    bool operator()(eastl_size_t a, eastl_size_t b)\n       { return (*mpArray)[a] < (*mpArray)[b]; }\n};\n\nquick_sort(toiArray.begin(), toiArray.end(), TestObjectIndexCompare(&toArray));\n
\n

Array indexes (simpler version using toArray as a global variable)

\n
vector<TestObject>   toArray;\nvector<eastl_size_t> toiArray;\n\nfor(eastl_size_t i = 0; i < 32; i++)\n{\n    toArray.push_back(TestObject(rng.RandLimit(20)));\n    toiArray.push_back(i);\n}\n\nstruct TestObjectIndexCompare\n{\n    bool operator()(eastl_size_t a, eastl_size_t b)\n       { return toArray[a] < toArray[b]; }\n};\n\nquick_sort(toiArray.begin(), toiArray.end(), TestObjectIndexCompare(&toArray));
\n

Iterators

\n

Iter.1\nWhat's the difference between iterator, const iterator, and const_iterator?

\n

An iterator can be modified and item it points to can be modified.
\nA const iterator cannot be modified, but the items it points to can be modified.
\nA const_iterator can be modified, but the items it points to cannot be modified.
\nA const const_iterator cannot be modified, nor can the items it points to.

\n

This situation is much like with char pointers:

\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
Iterator typePointer equivalent
iteratorchar*
const iteratorchar* const
const_iteratorconst char*
const const_iteratorconst char* const
\n
\n

Iter.2 How do I tell from an iterator what type of thing it is iterating?

\n

Use the value_type typedef from iterator_traits, as in this example

\n
template <typename Iterator>\nvoid DoSomething(Iterator first, Iterator last)\n{\n    typedef typename iterator_traits<Iterator>::value_type;\n\n    // use value_type\n}
\n

Iter.3\nHow do I iterate a container while (selectively) removing items from it?

\n

All EASTL containers have an erase function which takes an iterator as an \nargument and returns an iterator to the next item. Thus, you can erase items from a container \nwhile iterating it like so:

\n
set<int> intSet;\nset<int>::iterator i = intSet.begin();\n\nwhile(i != intSet.end())\n{\n    if(*i & 1) // Erase all odd integers from the container.\n        i = intSet.erase(i);\n    else\n        ++i;\n}
\n

Iter.4\nWhat is an insert_iterator?

\n

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.
\n

\n
\nEnd of document
\n
\n
\n
\n
\n\n\n" }, { "path": "doc/html/EASTL Glossary.html", "content": "\n\n\n\tEASTL Glossary\n\t\n\t\n\t\n \n\n\n

EASTL Glossary

\n

This document provides definitions to various terms related to EASTL. Items that are capitalized are items that are\nused as template parameters.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
adapterAn adapter is something that encapsulates a component to provide another interface, such as a C++ class which makes\na stack out of a list.
algorithm
Algorithms are standalone functions which manipulate data which usually but not\nnecessarily comes from a container. Some algorithms change the data while others don't. Examples are reverse, sort,\nfind, and remove.
associative containerAn associative container is a variable-sized container that supports efficient retrieval of elements (values) based\non keys. It supports insertion and removal of elements, but differs from a sequence in that it does not provide a\nmechanism for inserting an element at a specific position. Associative containers include map, multimap, set, multiset,\nhash_map, hash_multimap, hash_set, hash_multiset.
arrayAn array is a C++ container which directly implements a C-style fixed array but which adds STL container semantics\nto it.
basic_stringA templated string class which is usually used to store char or wchar_t strings.
beginThe function used by all conventional containers to return the first item in the container.
BidirectionalIteratorAn input iterator which is like ForwardIterator except it can be read in a backward direction as well.
BinaryOperation A function which takes two arguments and returns a value (which will usually be assigned to a third object).
BinaryPredicateA function which takes two arguments and returns true if some criteria is met (e.g. they are equal).
binder1st, binder2ndThese are function objects which convert one function object into another.  In particular, they implement a\nbinary function whereby you can specify one of the arguments.This is a somewhat abstract concept but has its uses.
bit vectorA specialized container that acts like vector<bool> but is implemented via one bit per entry. STL\nvector<bool> is usually implemented as a bit vector but EASTL avoids this in favor of a specific bit vector\ncontainer.
bitsetAn extensible yet efficient implementation of bit flags. Not strictly a conventional STL container and not the same\nthing as vector<bool> or a bit_vector, both of which are formal iterate-able containers.
capacityRefers to the amount of total storage available in an array-based container such as vector, string, and array.\nCapacity is always >= container size and is > size in order to provide extra space for a container to grow\ninto.
const_iteratorAn iterator whose iterated items are cannot be modified. A const_iterator is akin to a const pointer such as 'const\nchar*'.
containerA container is an object that stores other objects (its elements), and that has methods for accessing its elements.\nIn particular, every type that is a model of container has an associated iterator type that can be used to iterate\nthrough the container's elements.
copy constructorA constructor for a type which takes another object of that type as its argument. For a hypothetical Widget class,\nthe copy constructor is of the form Widget(const Widget& src);
CompareA function which takes two arguments and returns the lesser of the two.
dequeThe name deque is pronounced \"deck\" and stands for \"double-ended queue.\"
\n
\nA deque is very much like a vector: like vector, it is a sequence that supports random access to elements, constant\ntime insertion and removal of elements at the end of the sequence, and linear time insertion and removal of elements in\nthe middle.
\n
\nThe main way in which deque differs from vector is that deque also supports constant time insertion and removal of\nelements at the beginning of the sequence. Additionally, deque does not have any member functions analogous to vector's\ncapacity() and reserve(), and does not provide the guarantees on iterator validity that are associated with those\nmember functions.
difference_typeThe typedef'd type used by all conventional containers and iterators to define the distance between two iterators.\nIt is usually the same thing as the C/C++ ptrdiff_t data type.
emptyThe function used by all conventional containers to tell if a container has a size of zero. In many cases empty is\nmore efficient than checking for size() == 0.
elementAn element refers to a member of a container.
endThe function used by all conventional containers to return one-past the last item in the container.
equal_rangeequal_range is a version of binary search: it attempts to find the element value in an ordered range [first, last).\nThe value returned by equal_range is essentially a combination of the values returned by lower_bound and upper_bound:\nit returns a pair of iterators i and j such that i is the first position where value could be inserted without\nviolating the ordering and j is the last position where value could be inserted without violating the ordering. It\nfollows that every element in the range [i, j) is equivalent to value, and that [i, j) is the largest subrange of\n[first, last) that has this property.
explicit instantiationExplicit instantiation lets you create an instantiation of a templated class or function without actually using it\nin your code. Since this is useful when you are creating library files that use templates for distribution,\nuninstantiated template definitions are not put into object files. An example of the syntax for explicit\ninstantiation is:
\n    template class vector<char>;
\n    template void min<int>(int, int);
\n    template void min(int, int);
ForwardIteratorAn input iterator which is like InputIterator except it can be reset back to the beginning.
FunctionA function which takes one argument and applies some operation to the target.
function object, functorA function object or functor is a class that has the function-call operator (operator())\ndefined.
GeneratorA function which takes no arguments and returns a value (which will usually be assigned to an object).
hash_map, hash_multimap, hash_set, hash_multisetThe hash containers are implementations of map, multimap, set, and multiset via a hashtable instead of via a tree.\nSearches are O(1) (fast) but the container is not sorted.
heapA heap is a data structure which is not necessarily sorted but is organized such that the highest priority item is\nat the top. A heap is synonymous with a priority queue and has numerous applications in computer science.
InputIteratorAn input iterator (iterator you read from) which allows reading each element only once and only in a forward\ndirection.
intrusive_list, intrusive_hash_map, etc.Intrusive containers are containers which don't allocate memory but instead use their contained object to manage\nthe container's memory. While list allocates nodes (with mpPrev/mpNext pointers) that contain the list items,\nintrusive_list doesn't allocate nodes but instead the container items have the mpPrev/mpNext pointers.
intrusive_ptrintrusive_ptr is a smart pointer which doesn't allocate memory but instead uses the contained object to manage\nlifetime via addref and release functions.
iteratorAn iterator is the fundamental entity of reading and enumerating values in a container. Much like a pointer\ncan be used to walk through a character array, an iterator is used to walk through a linked list.
iterator categoryAn iterator category defines the functionality the iterator provides. The conventional iterator categories are\nInputIterator, ForwardIterator, BidirectionalIterator, RandomAccessIterator, and OutputIterator. See the definitions of\neach of these for more information.Iterator category is synonymous with iterator_tag.
iterator_tagSee iterator category.
key_type, KeyA Key or key_type is the identifier used by associative (a.k.a. dictionary) containers (e.g. map, hash_map) to\nidentify the type used to index the mapped_type. If you have a dictionary of strings that you access by an integer id,\nthe ids are the keys and the strings are the mapped types.
lexicographical compareA lexicographical compare is a comparison of two containers that compares them element by element, much like the C\nstrcmp function compares two strings.
linked_ptrA linked_ptr is a shared smart pointer which implements object lifetime via a linked list of all linked_ptrs that\nare referencing the object. linked_ptr, like intrusive_ptr, is a non-memory-allocating alternative to shared_ptr.
listA list is a doubly linked list. It is a sequence that supports both forward and backward traversal, and (amortized)\nconstant time insertion and removal of elements at the beginning or the end, or in the middle. Lists have the important\nproperty that insertion and splicing do not invalidate iterators to list elements, and that even removal invalidates\nonly the iterators that point to the elements that are removed. The ordering of iterators may be changed (that is,\nlist<T>::iterator might have a different predecessor or successor after a list operation than it did before), but\nthe iterators themselves will not be invalidated or made to point to different elements unless that invalidation or\nmutation is explicit.
lower_boundlower_bound is a version of binary search: it attempts to find the element value in an ordered range [first, last).\nSpecifically, it returns the first position where value could be inserted without violating the ordering.
mapMap is a sorted associative container that associates objects of type Key with objects of type T. Map is a pair\nassociative container, meaning that its value type is pair<const Key, T>. It is also a unique associative\ncontainer, meaning that no two elements have the same key. It is implemented with a tree structure.
mapped_typeA mapped_type is a typedef used by associative containers to identify the container object which is accessed by a\nkey. If you have a dictionary of strings that you access by an integer id, the ids are the keys and the strings are the\nmapped types.
member templateA member template is a templated function of a templated class. Thus with a member template function there are two\nlevels of templating -- the class and the function.
multimap, Multimap is a sorted associative container that associates objects of type Key with objects of type T.\nmultimap is a pair associative container, meaning that its value type is pair<const Key, T>. It is also a\nmultiple associative container, meaning that there is no limit on the number of elements with the same key.It is\nimplemented with a tree structure.
multisetMultiset is a sorted associative container that stores objects of type Key. Its value type, as well as its key\ntype, is Key. It is also a multiple associative container, meaning that two or more elements may be identical. It\nis implemented with a tree structure.
nodeA node is a little holder class used by many containers to hold the contained items. A linked-list, for example,\ndefines a node which has three members: mpPrev, mpNext, and T (the contained object).
nposnpos is used by the string class to identify a non-existent index. Some string functions return npos to indicate\nthat the function failed.
rel_opsrel_ops refers to \"relational operators\" and is a set of templated functions which provide operator!= for classes\nthat  have only operator== and provide operator > for classes that have only operator <, etc. Unfortunately,\nrel_ops have a habit of polluting the global operator space and creating conflicts. They must be used with\ndiscretion.
reverse_iteratorA reverse_iterator is an iterator which wraps a bidirectional or random access iterator and allows the iterator to\nbe read in reverse direction. The difference between using reverse_iterators and just decrementing regular iterators is\nthat reverse_iterators use operator++ to move backwards and thus work in any algorithm that calls ++ to move through a\ncontainer.
OutputIteratorAn output iterator (iterator you write to) which allows writing each element only once in only in a forward\ndirection.
PODPOD means Plain Old Data. It refers to C++ classes which act like built-in types and C structs. These are useful to\ndistinguish because some algorithms can be made more efficient when they can detect that they are working with PODs\ninstead of regular classes. 
PredicateA function which takes one argument returns true if the argument meets some criteria.
priority_queueA priority_queue is an adapter container which implements a heap via a random access container such as vector or\ndeque.
queueA queue is an adapter container which implements a FIFO (first-in, first-out) container with which you can add\nitems to the back and get items from the front.
RandomAccessIteratorAn input iterator which can be addressed like an array. It is a superset of all other input iterators.
red-black treeA red-black tree is a binary tree which has the property of being always balanced. The colors red and black are\nsomewhat arbitrarily named monikers for nodes used to measure the balance of the tree. Red-black trees are considered\nthe best all-around data structure for sorted containers.
scalarA scalar is a data type which is implemented via a numerical value. In C++ this means integers, floating point\nvalues, enumerations, and pointers. 
scoped_ptrA scoped_ptr is a smart pointer which is the same as C++ auto_ptr except that it cannot be copied.
setSet is a sorted associative container that stores objects of type Key. Its value type, as well as its key type, is\nKey. It is also a unique associative container, meaning that no two elements are the same.It is implemented with a tree\nstructure.
sequenceA sequence is a variable-sized container whose elements are arranged in a strict linear (though not necessarily\ncontiguous) order. It supports insertion and removal of elements. Sequence containers include vector, deque, array,\nlist, slist.
sizeAll conventional containers have a size member function which returns the count of elements in the container. The\nefficiency of the size function differs between containers.
size_typeThe type that a container uses to define its size and counts. This is similar to the C/C++ size_t type but may be\nspecialized 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.
skip listA skip-list is a type of container which is an alternative to a binary tree for finding data.
shared_ptrA shared_ptr is a smart pointer which allows multiple references (via multiple shared_ptrs) to the same object.\nWhen the last shared_ptr goes away, the pointer is freed. shared_ptr is implemented via a shared count between all\ninstances.
slistAn slist is like a list but is singly-linked instead of doubly-linked. It can only be iterated in a\nforward-direction.
smart pointerSmart pointer is a term that identifies a family of utility classes which store pointers and free them when the\nclass instance goes out of scope. Examples of smart pointers are shared_ptr, linked_ptr, intrusive_ptr, and\nscoped_ptr.
spliceSplicing refers to the moving of a subsequence of one Sequence into another Sequence.
stackA stack is a adapter container which implements LIFO (last-in, first, out) access via another container such as a\nlist or deque.
STLStandard Template Library. 
StrictWeakOrderingA BinaryPredicate that compares two objects, returning true if the first precedes the second. Like Compare but has\nadditional requirements. Used for sorting routines.
\n
\nThis predicate must satisfy the standard mathematical definition of a strict weak ordering. A StrictWeakOrdering has to\nbehave 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\nless than c then a is less than c, and so on.
stringSee basic_string.
TT is the template parameter name used by most containers to identify the contained element type. 
template parameterA template parameter is the templated type used to define a template function or class. In the declaration\n'template <typename T> class vector{ },'  T is a template parameter.
template specializationA template specialization is a custom version of a template which overrides the default version and provides\nalternative functionality, often for the purpose of providing improved or specialized functionality.
treapA tree-like structure implemented via a heap. This is an alternative to a binary tree (e.g. red-black tree),\nskip-list, and sorted array as a mechanism for a fast-access sorted container.
type traitsType traits are properties of types. If you have a templated type T and you want to know if it is a pointer, you\nwould 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.\nType traits are very useful for allowing the implementation of optimized generic algorithms and for asserting that\ntypes have properties expected by the function or class contract. For example, you can use type_traits to tell if a\ntype can be copied via memcpy instead of a slower element-by-element copy.
typenameTypename is a C++ keyword used in templated function implementations which identifies to the compiler that the\nfollowing expression is a type and not a value. It is used extensively in EASTL, particularly in the algorithms.
UnaryOperationA function which takes one argument and returns a value (which will usually be assigned to second object).
upper_boundupper_bound is a version of binary search: it attempts to find the element value in an ordered range [first, last).\nSpecifically, it returns the last position where value could be inserted without violating the ordering.
value_type, ValueA value_type is a typedef used by all containers to identify the elements they contain. In most cases value_type is\nsimply the same thing as the user-supplied T template parameter. The primary exception is the associative containers\nwhereby value_type is the pair of key_type and mapped_type.
vectorA vector is a Sequence that supports random access to elements, constant time insertion and removal of elements at\nthe end, and linear time insertion and removal of elements at the beginning or in the middle. The number of elements in\na vector may vary dynamically; memory management is automatic. Vector is the simplest of the container classes, and in\nmany cases the most efficient.
vector_map, vector_multimap, vector_set, vector_multisetThese are containers that implement the functionality of map, multimap, set, and multiset via a vector or deque\ninstead of a tree. They use less memory and find items faster, but are slower to modify and modification invalidates\niterators.
weak_ptrA weak_ptr is an adjunct to shared_ptr which doesn't increment the reference on the contained object but can safely\ntell you if the object still exists and access it if so. It has uses in preventing circular references in\nshared_ptrs.
\n
\n\n
\nEnd of document
\n
\n
\n
\n
\n
\n
\n
\n
\n\n\n" }, { "path": "doc/html/EASTL Gotchas.html", "content": "\n\n\n\tEASTL Gotchas\n\t\n\t\n\t\n \n \n\n\n

EASTL Gotchas

\n

There are some cases where the EASTL design results in \"gotchas\" or behavior that isn't necessarily what the new user\n would expect. These are all situations in which this behavior may be undesirable. One might ask, \"Why not change EASTL\n to make these gotchas go away?\" The answer is that in each case making the gotchas go away would either be impossible\n or would compromise the functionality of the library.

\n

Summary

\n

The descriptions here are intentionally terse; this is to make them easier to visually scan.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n \n \n\n\n \n \n\n\n
1map::operator[] can create elements.
2char* converts to string silently.
3char* is compared by ptr and not by contents.
4Iterators can be invalidated by container mutations.
5Vector resizing may cause ctor/dtor cascades.
6Vector and string insert/push_back/resize can reallocate.
7Deriving from containers may not work.
8set::iterator is const_iterator.
9Inserting elements means copying by value.
10Containers of pointers can leak if you aren't careful.
11Containers of auto_ptrs can crash.
12Remove algorithms don't actually remove elements.
13list::size() is O(n).
14vector and deque::size() may incur integer division.
15Be careful making custom Compare functions.
16Comparisons involving floating point are dangerous.
17Writing beyond string::size and vector::size is dangerous.
18Container operator=() doesn't copy allocators.
\n

Detail

\n

1\nmap::operator[] can create elements.

\n

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[].

\n

2\nchar* converts to string silently.

\n

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.

\n

There is an EASTL configuration option called EASTL_STRING_EXPLICIT which makes the string char* ctor explicit and avoids the behaviour described above.

\n

3\nchar* is compared by ptr and not by contents.

\n

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.

\n

4 Iterators can be invalidated by container mutations

\n

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.

\n

5 Vector resizing may cause ctor/dtor cascades.

\n

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.

\n

6\nVector and string insert/push_back/resize can reallocate.

\n

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.

\n

7\nDeriving from containers may not work.

\n

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.

\n

8 \nset::iterator is const_iterator.

\n

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.

\n

9\nInserting elements means copying by value.

\n

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.

\n

10\n Containers of pointers can leak if you aren't careful.

\n

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.

\n

11\nContainers of auto_ptrs can crash

\n

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.

\n

12\nRemove algorithms don't actually remove elements.

\n

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.

\n

13 \nlist::size() is O(n).

\n

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.

\n

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.

\n

14 \n vector and deque::size() may incur integer division.

\n

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.

\n

15\n Be careful making custom Compare functions.\n

\n

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.

\n

16 \n Comparisons involving floating point are dangerous.

\n

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.

\n

17 Writing beyond string::size and vector::size is dangerous.

\n

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.

\n

The following code is broken:

\n

string mDataDir;
\n
\n mDataDir.reserve(kMaxPathLength);
\n strcpy(&mDataDir[0], "blah/blah/blah");
\nmDataDir.resize(strlen(&mDataDir[0])); // Overwrites your blah/... with 00000...

\n

This following code is OK:

\n

string mDataDir;
\n
\n mDataDir.resize(kMaxPathLength);
\n strcpy(&mDataDir[0], "blah/blah/blah");
\nmDataDir.resize(strlen(&mDataDir[0]));

\n

18 Container operator=() doesn't copy allocators.\n

\n

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.

\n
\n
\nEnd of document
\n
\n
\n
\n
\n\n\n" }, { "path": "doc/html/EASTL Introduction.html", "content": "\n\n\n\tEASTL Introduction\n\t\n\t\n\t\n \n\n\n

EASTL Introduction

\n

EASTL stands for Electronic Arts Standard Template Library. It is a C++ template library of containers, algorithms, and\n iterators useful for runtime and tool development across multiple platforms. It is a fairly extensive and robust\n implementation of such a library and has an emphasis on high performance above all other considerations.

\n

Intended Audience

\n

This is a short document intended to provide a basic introduction to EASTL for \n those new to the concept of EASTL or STL. If you are familiar with the C++ STL \n or have worked with other templated container/algorithm libraries, you probably \n don't need to read this. If you have no familiarity with C++ templates at all, \n then you probably will need more than this document to get you up to speed. In \n this case you need to understand that templates, when used properly, are powerful \n vehicles for the ease of creation of optimized C++ code. A description of C++ \n templates is outside the scope of this documentation, but there is plenty of such \n documentation on the Internet. See the EASTL FAQ.html \n document for links to information related to learning templates and STL.

\n

EASTL Modules

\n

EASTL consists primarily of containers, algorithms, and iterators. An example of a container is a linked list, while an\n example of an algorithm is a sort function; iterators are the entities of traversal for containers and algorithms.\n EASTL containers a fairly large number of containers and algorithms, each of which is a very clean, efficient, and\n unit-tested implementation. We can say with some confidence that you are not likely to find better implementations of\n these (commercial or otherwise), as these are the result of years of wisdom and diligent work. For a detailed list of\n EASTL modules, see EASTL Modules.html.

\n

EASTL Suitability

\n

What uses are EASTL suitable for? Essentially any situation in tools and shipping applications where the functionality\n of EASTL is useful. Modern compilers are capable of producing good code with templates and many people are using them\n in both current generation and future generation applications on multiple platforms from embedded systems to servers\n and mainframes.

\n
\nEnd of document
\n
\n
\n
\n
\n
\n
\n\n\n" }, { "path": "doc/html/EASTL Maintenance.html", "content": "\n\n\n\tEASTL Maintenance\n\t\n\t\n\t\n \n\n\n\n

EASTL Maintenance

\n

Introduction

\n

The purpose of this document is to provide some necessary background for anybody who might do work on EASTL. Writing\n generic templated systems like EASTL can be surprisingly tricky. There are numerous details of the C++ language that\n you need to understand which don't usually come into play during the day-to-day C++ coding that many people do. It is\n easy to make a change to some function that seems proper and works for your test case but either violates the design\n expectations or simply breaks under other circumstances.
\n
\n It may be useful to start with an example. Here we provide an implementation of the count algorithm which is seems\nsimple enough. Except it is wrong and while it will compile in some cases it won't compile in others:

\n
template <class InputIterator, class T>\nint count(InputIterator first, InputIterator last, const T& value)\n{\n     int result = 0;\n \n     for(; first < last; ++first){\n         if(*first == value)\n             ++result;\n     }\n \n     return result;\n }
\n

The problem is with the comparison 'first < last'. The count algorithm takes an InputIterator and operator< is\nnot guaranteed to exist for any given InputIterator (and indeed while operator< exists for vector::iterator, it\ndoesn't exist for list::iterator). The comparison in the above algorithm must instead be implemented as 'first !=\nlast'. If we were working with a RandomAccessIterator then 'first < last' would be valid.

\n

In the following sections we cover various topics of interest regarding the development and maintentance of EASTL.\n Unfortunately, this document can't cover every aspect of EASTL maintenance issues, but at least it should give you a\nsense of the kinds of issues.

\n\n

C++ Language Standard

\n

First and foremost, you need to be familiar with the C++ standard. In particular, the sections of the standard related\n to containers, algorithms, and iterators are of prime significance. We'll talk about some of this in more detail below.\n Similarly, a strong understanding of the basic data types is required. What is the difference between ptrdiff_t and\nintptr_t; unsigned int and size_t; char and signed char?

\n

In addition to the C++ language standard, you'll want to be familiar with the C++ Defect Report. This is a continuously\n updated document which lists flaws in the original C++ language specification and the current thinking as the\nresolutions of those flaws. You will notice various references to the Defect Report in EASTL source code.

\n

Additionally, you will want to be familiar with the C++ Technical Report 1 (as of this writing there is only one). This\n document is the evolving addendum to the C++ standard based on both the Defect Report and based on desired additions to\nthe C++ language and standard library.

\n

Additionally, you will probably want to have some familiarity with Boost. It also helps to keep an eye on\n comp.std.c++ Usenet discussions. However, watch out for what people say on Usenet. They tend to defend GCC, Unix, std\n STL, and C++ to a sometimes unreasonable degree. Many discussions ignore performance implications and\nconcentrate only on correctness and sometimes academic correctness above usability.

\n

Language Use

\n

Macros are (almost) not allowed in EASTL. A prime directive of EASTL is to be easier to read by users and most of\n the time macros are an impedence to this. So we avoid macros at all costs, even if it ends up making our development\n and maintenance more difficult. That being said, you will notice that the EASTL config.h file uses macros to control\n various options. This is an exception to the rule; when we talk about not using macros, we mean with the EASTL\nimplementation itself.

\n

EASTL assumes a compliant and intelligent C++ compiler, and thus all language facilities are usable. However, we\nnevertheless choose to stay away from some language functionality. The primary language features we avoid are:

\n
    \n
  • RTTI (run-time-type-identification) (this is deemed too costly)
    • \n
  • Template export (few compilers support this)
    • \n
  • Exception specifications (most compilers ignore them)
    • \n
\n

Use of per-platform or per-compiler code should be avoided when possible but where there is a significant advantage to\n be gained it can and indeed should be used. An example of this is the GCC __builtin_expect feature, which allows the\n user to give the compiler a hint about whether an expression is true or false. This allows for the generation of code\nthat executes faster due to more intelligent branch prediction.

\n

Prime Directives

\n

The\nimplementation of EASTL is guided foremost by the following directives which are listed in order of importance.

\n
    \n
  1. Efficiency (speed and memory usage)
    2. \n
  2. Correctness (doesn't have bugs)
    3. \n
  3. Portability (works on all required platforms with minimal specialized code)
    4. \n
  4. Readability (code is legible and comments are present and useful)
    5. \n
\n

Note that unlike commercial STL implementations which must put correctness above all, we put a higher value on\n efficiency. As a result, some functionality may have some usage limitation that is not present in other similar systems\nbut which allows for more efficient operation, especially on the platforms of significance to us.

\n

Portability is significant, but not critical. Yes, EASTL must compile and run on all platforms that we will ship games\n for. But we don't take that to mean under all compilers that could be conceivably used for such platforms. For example,\n Microsoft VC6 can be used to compile Windows programs, but VC6's C++ support is too weak for EASTL and so you simply\ncannot use EASTL under VC6.

\n

Readability is something that EASTL achieves better than many other templated libraries, particularly Microsoft STL and\n STLPort. We make every attempt to make EASTL code clean and sensible. Sometimes our need to provide optimizations\n (particularly related to type_traits and iterator types) results in less simple code, but efficiency happens to be our\nprime directive and so it overrides all other considerations.

\n\n

Coding Conventions

\n

Here we provide a list of coding conventions to follow when maintaining or adding to EASTL, starting with the three\nlanguage use items from above:

\n
    \n
  • No RTTI use.
    • \n
  • No use of exception specifications (e.g. appending the 'throw' declarator to a function).
    • \n
  • No use of exception handling itself except where explicitly required by the implementation (e.g. vector::at).
    • \n
  • Exception use needs to savvy to EASTL_EXCEPTIONS_ENABLED.
    • \n
  • No use of macros (outside of config.h). Macros make things more difficult for the user.
    • \n
  • No use of static or global variables.
    • \n
  • No use of global new, delete, malloc, or free. All memory must be user-specifyable via an Allocator parameter\n(default-specified or explicitly specified).
    • \n
  • Containers use protected member data and functions as opposed to private. This is because doing so allows\nsubclasses to extend the container without the creation of intermediary functions. Recall from our prime directives above that performance and simplicity overrule all.
    • \n
  • No use of multithreading primitives. 
    • \n
  • No use of the export keyword.
    • \n
  • We don't have a rule about C-style casts vs. C++ static_cast<>, etc. We would always use static_cast except\nthat debuggers can't evaluate them and so in practice they can get in the way of debugging and tracing. However, if the\ncast is one that users don't tend to need to view in a debugger, C++ casts are preferred.
    • \n
  • No external library dependencies whatsoever, including standard STL. EASTL is dependent on only EABase and the\nC++ compiler. 
    • \n
  • All code must be const-correct. This isn't just for readability -- compilation can fail unless const-ness is used\ncorrectly everywhere. 
    • \n
  • Algorithms do not refer to containers; they refer only to iterators.
    • \n
  • Algorithms in general do not allocate memory. If such a situation arises, there should be a version of the\nalgorithm which allows the user to provide the allocator.
    • \n
  • No inferior implementations. No facility should be added to EASTL unless it is of professional\nquality.
    • \n
  • The maintainer should emulate the EASTL style of code layout, regardless of the maintainer's personal preferences.\nWhen in Rome, do as the Romans do. EASTL uses 4 spaces for indents, which is how the large majority of code within EA\nis written.
    • \n
  • No major changes should be done without consulting a peer group.
    • \n
\n\n

Compiler Issues

\n

Historically, templates are the feature of C++ that has given C++ compilers the most fits. We are still working with\n compilers that don't completely and properly support templates. Luckily, most compilers are now good enough to handle\nwhat EASTL requires. Nevertheless, there are precautions we must take.

\n

It turns out that the biggest problem in writing portable EASTL code is that VC++ allows you to make illegal statements\n which are not allowed by other compilers. For example, VC++ will allow you to neglect using the typename keyword in\ntemplate references, whereas GCC (especially 3.4+) requires it.

\n

In order to feel comfortable that your EASTL code is C++ correct and is portable, you must do at least these two\nthings:

\n
    \n
  • Test under at least VS2005, GCC 3.4+, GCC 4.4+, EDG, and clang.
    • \n
  • Test all functions that you write, as compilers will often skip the compilation of a template function if it isn't\nused.
    • \n
\n

The two biggest issues to watch out for are 'typename' and a concept called \"dependent names\". In both cases VC++ will\n accept non-conforming syntax whereas most other compilers will not. Whenever you reference a templated type (and not a templated\n value) in a template, you need to prefix it by 'typename'. Whenever your class function refers to a base class member (data or\n function), you need to refer to it by \"this->\", \"base_type::\", or by placing a \"using\" statement in your class to\ndeclare that you will be referencing the given base class member.

\n\n

Iterator Issues

\n

The most important thing to understand about iterators is the concept of iterator types and their designated\n properties. In particular, we need to understand the difference between InputIterator, ForwardIterator,\n BidirectionalIterator, RandomAccessIterator, and OutputIterator. These differences dictate both how we implement our\n algorithms and how we implement our optimizations. Please read the C++ standard for a reasonably well-implemented\n description of these iterator types.

\n

Here's an example from EASTL/algorithm.h which demonstrates how we use iterator types to optimize the reverse algorithm\nbased on the kind of iterator passed to it:

\n
template <class BidirectionalIterator>\ninline void reverse_impl(BidirectionalIterator first, BidirectionalIterator last, bidirectional_iterator_tag)
{\n    for(; (first != last) && (first != --last); ++first) // We are not allowed to use operator <, <=, >, >= with\n        iter_swap(first, last);                          // a generic (bidirectional or otherwise) iterator.\n}
\n\ntemplate <typename RandomAccessIterator>\ninline void reverse_impl(RandomAccessIterator first, RandomAccessIterator last, random_access_iterator_tag)\n{\n    for(; first < --last; ++first) // With a random access iterator, we can use operator < to more efficiently implement\n        iter_swap(first, last);    // this algorithm. A generic iterator doesn't necessarily have an operator < defined.\n}

\ntemplate <class BidirectionalIterator>\ninline void reverse(BidirectionalIterator first, BidirectionalIterator last)\n{\n    typedef typename iterator_traits<BidirectionalIterator>::iterator_category IC;\n    reverse_impl(first, last, IC());\n}
\n\n

Exception Handling

\n

You will notice that EASTL uses try/catch in some places (particularly in containers) and uses\n the EASTL_EXCEPTIONS_ENABLED define. For starters, any EASTL code that uses try/catch should always be wrapped\n within #if EASTL_EXCEPTIONS_ENABLED (note: #if, not #ifdef).

\n

This is simple enough, but what you may be wondering is how it is that EASTL decides to use try/catch for some sections\n of code and not for others. EASTL follows the C++ standard library conventions with respect to exception handling, and\n you will see similar exception handling in standard STL. The code that you need to wrap in try/catch is code that can\n throw a C++ exception (not to be confused with CPU exception) and needs to have something unwound (or fixed) as a\n result. The important thing is that the container be in a valid state after encountering such exceptions. In general\nthe kinds of things that require such try/catch are:

\n
    \n
  • Memory allocation failures (which throw exceptions)
    • \n
  • Constructor exceptions
    • \n
\n

Take a look at the cases in EASTL where try/catch is used and see what it is doing.

\n

Type Traits

\n

EASTL provides a facility called type_traits which is very similar to the type_traits being proposed by the C++ TR1\n (see above). type_traits are useful because they tell you about properties of types at compile time. This allows you to\n 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\n is to take advantage of them to implement different pathways for functions based on types. For example, we can copy a\n contiguous array of scalars much faster via memcpy than we can via a for loop, though we could not safely employ the\n for loop for a non-trivial C++ class.

\n

As mentioned in the GeneralOptimizations section below, EASTL should take advantage of type_traits information to the\nextent possible to achive maximum effiiciency.

\n

General\nOptimizations

\n

One of the primary goals of EASTL is to achieve the highest possible efficiency. In cases where EASTL functionality\n overlaps standard C++ STL functionality, standard STL implementations provided by compiler vendors are a benchmark upon\n which EASTL strives to beat. Indeed EASTL is more efficient than all other current STL implementations (with some\n exception in the case of some Metrowerks STL facilities). Here we list some of the things to look for when considering\n optimization of EASTL code These items can be considered general optimization suggestions for any code, but this\nparticular list applies to EASTL:

\n
    \n
  • Take advantage of type_traits to the extent possible (e.g. to use memcpy to move data instead of a for loop when\npossible).
    • \n
  • Take advantage of iterator types to the extent possible.
    • \n
  • Take advantage of the compiler's expectation that if statements are expected to evaluate as true and for loop\nconditions are expected to evaluate as false.
    • \n
  • Make inline-friendly code. This often means avoiding temporaries to the extent possible.
    • \n
  • Minimize branching (i.e. minimize 'if' statements). Where branching is used, make it so that 'if' statements\nexecute as true.
    • \n
  • Use EASTL_LIKELY/EASTL_UNLIKELY to give branch hints to the compiler when you are confident it will be\nbeneficial.
    • \n
  • Use restricted pointers (EABase's EA_RESTRICT or various compiler-specific versions of __restrict).
    • \n
  • Compare unsigned values to < max instead of comparing signed values to >= 0 && < max.
    • \n
  • Employ power of 2 integer math instead of math with any kind of integer.
    • \n
  • Use template specialization where possible to implement improved functionality.
    • \n
  • Avoid function calls when the call does something trivial. This improves debug build speed (which matters) and\nsometimes release build speed as well, though sometimes makes the code intent less clear. A comment next to the code\nsaying what call it is replacing makes the intent clear without sacrificing performance.
    • \n
\n

Unit Tests

\n

Writing robust templated containers and algorithms is difficult or impossible without a heavy unit test suite in place.\n EASTL has a pretty extensive set of unit tests for all containers and algorithms. While the successful automated unit\n testing of shipping application programs may be a difficult thing to pull off, unit testing of libraries such as this\n is of huge importance and cannot be understated.

\n
    \n
  • When making a new unit test, start by copying one of the existing unit tests and follow its conventions.
    • \n
  • Test containers of both scalars and classes.
    • \n
  • Test algorithms on both container iterators (e.g. vector.begin()) and pointer iterators (e.g. int*).
    • \n
  • Make sure that algorithm or container member functions which take iterators work with the type of iterator they\nclaim to (InputIterator, ForwardIterator, BidirectionalIterator, RandomAccessIterator). 
    • \n
  • Test for const-correctness. If a user is allowed to modify something that is supposed to be const, silent errors\ncan go undetected.
    • \n
  • Make sure that unit tests cover all functions and all pathways of the tested code. This means that in writing the\nunit test you need to look at the source code to understand all the pathways.
    • \n
  • Consider using a random number generator (one is provided in the test library) to do 'monkey' testing whereby\nunexpected input is given to a module being tested. When doing so, make sure you seed the generator in a way that\nproblems can be reproduced.
    • \n
  • While we avoid macros in EASTL user code, macros to assist in unit tests aren't considered a problem. However,\nconsider that a number of macros could be replaced by templated functions and thus be easier to work with.
    • \n
  • 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\nsufficiently.
    • \n
  • EASTL containers are not thread-safe, by design. Thus there is no need to do multithreading tests as long as you\nstay away from the usage of static and global variables.
    • \n
  • Unit tests must succeed with no memory leaks and of course no memory corruption. The heap system should be\nconfigured to test for this, and heap validation functions are available to the unit tests while in the middle of\nruns.
    • \n
\n\n

Things to Keep in Mind

\n
    \n
  • When referring to EASTL functions and types from EASTL code, make sure to preface the type with the EASTL\nnamespace. If you don't do this you can get collisions due to the compiler not knowing if it should use the EASTL\nnamespace or the namespace of the templated type for the function or type.
    • \n
  • Newly constructed empty containers do no memory allocation. Some STL and other container libraries allocate an\ninitial node from the class memory allocator. EASTL containers by design never do this. If a container needs an\ninitial node, that node should be made part of the container itself or be a static empty node object.
    • \n
  • Empty containers (new or otherwise) contain no constructed objects, including those that might be in an 'end' node.\nSimilarly, no user object (e.g. of type T) should be constructed unless required by the design and unless documented in\nthe cotainer/algorithm contract. 
    • \n
  • When creating a new container class, it's best to copy from an existing similar class to the extent possible. This\nhelps keep the library consistent and resolves subtle problems that can happen in the construction of containers.
    • \n
  • Be very careful about tweaking the code. It's easy to think (for example) that a > could be switch to a >=\nwhere instead it is a big deal. Just about every line of code in EASTL has been thought through and has a purpose. Unit\ntests may or may not currently test every bit of EASTL, so you can't necessarily rely on them to give you 100%\nconfidence in changes. If you are not sure about something, contact the original author and he will tell you for\nsure.
    • \n
  • Algorithm templates always work with iterators and not containers. A given container may of course implement an\noptimized form or an algorithm itself.
    • \n
  • Make sure everything is heavily unit tested. If somebody finds a bug, fix the bug and make a unit test to make sure\nthe bug doesn't happen again.
    • \n
  • It's easy to get iterator categories confused or forgotten while implementing algorithms and containers.
    • \n
  • Watch out for the strictness of GCC 3.4+. There is a bit of syntax — especially related to templates — that other\ncompilers accept but GCC 3.4+ will not.
    • \n
  • Don't forget to update the config.h EASTL_VERSION define before publishing.
    • \n
  • The vector and string classes define iterator to be T*. We want to always leave this so — at least in release\nbuilds — as this gives some algorithms an advantage that optimizers cannot get around.
    • \n
\n
\n
\n
\n
\n
\n
\n\n\n" }, { "path": "doc/html/EASTL Modules.html", "content": "\n\n\n\tEASTL Modules\n\t\n\t\n\t\n \n \n\n\n

EASTL Modules

\n

Introduction

\n

We provide here a list of all top-level modules present or planned for future presence in EASTL. In some cases (e.g.\n algorithm), the module consists of many smaller submodules which are not described in detail here. In those cases you\n should consult the source code for those modules or consult the detailed documentation for those modules. This document\nis a high level overview and not a detailed document.

\n

Module List

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
 ModuleDescription
configConfiguration header. Allows for changing some compile-time options.
slist
\nfixed_slist		Singly-linked list.
\nfixed_slist is a version which is implemented via a fixed block of contiguous memory.
list
\nfixed_list		Doubly-linked list.
intrusive_list
\nintrusive_slist		List whereby the contained item provides the node implementation.
arrayWrapper for a C-style array which extends it to act like an STL container.
vector
\nfixed_vector		Resizable array container.
vector_set
\nvector_multiset
Set implemented via a vector instead of a tree. Speed and memory use is improved but resizing is slower.
vector_map
\nvector_multimap
Map implemented via a vector instead of a tree. Speed and memory use is improved but resizing is slower.
deque
Double-ended queue, but also with random access. Acts like a vector but insertions and\nremovals are efficient.
bit_vectorImplements a vector of bool, but the actual storage is done with one bit per bool. Not the same thing as a\nbitset.
bitsetImplements an efficient arbitrarily-sized bitfield. Note that this is not strictly the same thing as a vector of\nbool (bit_vector), as it is optimized to act like an arbitrary set of flags and not to be a generic container which can\nbe iterated, inserted, removed, etc.
set
\nmultiset
\nfixed_set
\nfixed_multiset
A set is a sorted unique collection, multiset is sorted but non-unique collection.
map
\nmultimap
\nfixed_map
\nfixed_multimap		A map is a sorted associative collection implemented via a tree. It is also known as dictionary.
hash_map
\nhash_multimap
\nfixed_hash_map
\nfixed_hash_multimap		Map implemented via a hash table.
intrusive_hash_map
\nintrusive_hash_multimap
\nintrusive_hash_set
\nintrusive_hash_multiset		hash_map whereby the contained item provides the node implementation, much like intrusive_list.
hash_set
\nhash_multiset
\nfixed_hash_set
\nfixed_hash_map
Set implemented via a hash table.
basic_string
\nfixed_string
\nfixed_substring		basic_string is a character string/array.
\nfixed_substring is a string which is a reference to a range within another string or character array.
\ncow_string is a string which implements copy-on-write.
algorithmmin/max, find, binary_search, random_shuffle, reverse, etc. 
sort
Sorting functionality, including functionality not in STL. quick_sort, heap_sort,\nmerge_sort, shell_sort, insertion_sort, etc.
numericNumeric algorithms: accumulate, inner_product, partial_sum, adjacent_difference, etc.
heap
Heap structure functionality: make_heap, push_heap, pop_heap, sort_heap, is_heap,\nremove_heap, etc.
stack
Adapts any container into a stack.
queue
Adapts any container into a queue.
priority_queue
Implements a conventional priority queue via a heap structure.
type_traitsType information, useful for writing optimized and robust code. Also used for implementing optimized containers and\nalgorithms.
utility
pair, make_pair, rel_ops, etc.
functional
Function objects.
iterator
Iteration for containers and algorithms.
smart_ptrSmart pointers: shared_ptr, shared_array, weak_ptr, scoped_ptr, scoped_array, linked_ptr, linked_array,\nintrusive_ptr.
\n

 

\n

Module Behaviour

\n

The overhead sizes listed here refer to an optimized release build; debug builds may add some additional overhead. Some\n of the overhead sizes may be off by a little bit (usually at most 4 bytes). This is because the values reported here\n are those that refer to when EASTL's container optimizations have been complete. These optimizations may not have been\n completed as you are reading this.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
\n

Container

\n		\n

Stores

\n		Container Overhead (32 bit)Container Overhead (64 bit)\n

Node Overhead (32 bit)

\n		Node Overhead (64 bit)\n

Iterator category

\n		size() efficiencyoperator[] efficiency\n

Insert efficiency

\n		\n

Erase via Iterator efficiency

\n		\n

Find efficiency

\n		\n

Sort efficiency

\n
slistT81648fn-11nn+
\n

list

\n		\n

T

\n		1224\n

8

\n		16\n

b

\n		n-\n

1

\n		\n

1

\n		\n

n

\n		\n

n log(n)

\n
intrusive_slistT4848fn-11nn+
intrusive_listT816816bn-11nn log(n)
arrayT0000r11--nn log(n)
vectorT163200r111 at end, else n1 at end, else nnn log(n)
vector_setT163200r111 at end, else n1 at end, else nlog(n)1
vector_multisetT163200r111 at end, else n1 at end, else nlog(n)1
vector_mapKey, T163200r111 at end, else n1 at end, else nlog(n)1
vector_multimapKey, T163200r111 at end, else n1 at end, else nlog(n)1
dequeT448400r111 at begin or end,
\nelse n / 2		1 at begin or end,
\nelse n / 2		nn log(n)
bit_vectorbool81600r111 at end, else n1 at end, else nnn log(n)
string (all types)T163200r111 at end, else n1 at end, else nnn log(n)
setT24441628b1-log(n)log(n)log(n)1
multisetT24441628b1-log(n)log(n)log(n)1
mapKey, T24441628b1log(n)log(n)log(n)log(n)1
multimapKey, T24441628b1-log(n)log(n)log(n)1
hash_setT162048b1-111-
hash_multisetT162048b1-1
11-
hash_mapKey, T162048b1-111-
hash_multimapKey, T162048b1-111-
intrusive_hash_setT162048b1-111-
intrusive_hash_multisetT162048b1-111-
intrusive_hash_mapT (Key == T)162048b1-111-
intrusive_hash_multimapT (Key == T) 162048b1-111-
\n
    \n
  • - means that the operation does not exist.
    • \n
  • 1 means amortized constant time. Also known as O(1)
    • \n
  • n means time proportional to the container size. Also known as O(n)
    • \n
  • log(n) means time proportional to the natural logarithm of the container size. Also known as O(log(n))
    • \n
  • n log(n) means time proportional to log(n) times the size of the container. Also known as O(n log(n))
    • \n
  • n+ means that the time is at least n, and possibly higher.
    • \n
  • Iterator meanings are: f = forward iterator; b = bidirectional iterator, r = random iterator.
    • \n
  • Overhead indicates approximate per-element overhead memory required in bytes. Overhead doesn't include possible\nadditional overhead that may be imposed by the memory heap used to allocate nodes. General heaps tend to have between 4\nand 16 bytes of overhead per allocation, depending on the heap.
    • \n
  • Some overhead values are dependent on the structure alignment characteristics in effect. The values reported here\nare those that would be in effect for a system that requires pointers to be aligned on boundaries of their size and\nallocations with a minimum of 4 bytes (thus one byte values get rounded up to 4).
    • \n
  • 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.
    • \n
  • Inserting at the end of a vector may cause the vector to be resized; resizing a vector is O(n). However, the\namortized time complexity for vector insertions at the end is constant.
    • \n
  • Sort assumes the usage of the best possible sort for a large container of random data. Some sort algorithms (e.g.\nquick_sort) require random access iterators and so the sorting of some containers requires a different sort algorithm.\nWe do not include bucket or radix sorts, as they are always O(n).
    • \n
  • Some containers (e.g. deque, hash*) have unusual data structures that make per-container and per-node overhead\ncalculations not quite account for all memory.
    • \n
\n
\nEnd of document
\n
\n
\n
\n
\n
\n
\n
\n
\n
\n
\n
\n
\n
\n
\n
\n
\n
\n
\n
\n
\n
\n
\n
\n
\n
\n\n\n" }, { "path": "doc/html/EASTLDoc.css", "content": "body \n{\n\tfont-family: Georgia, \"Times New Roman\", Times, serif;\n\tfont-size: 12pt;\n}\n\nh1\n{\n\tfont-family: Verdana, Arial, Helvetica, sans-serif;\n\tdisplay: block;\n\tbackground-color: #BBCCDD;\n\tborder: 2px solid #000000;\n\tfont-size: 16pt;\n\tfont-weight: bold;\n\tpadding: 6px;\n}\n\nh2 \n{\n\tfont-size: 14pt;\n\tfont-family: Verdana;\n\tborder-bottom: 2px solid black;\n}\n\nh3\n{\n\tfont-family: Verdana;\n\tfont-size: 13pt;\n\tfont-weight: bold;\n}\n\n.code-example \n{\n\tdisplay: block;\n\tbackground-color: #D1DDE9;\n\tmargin-left: 3em;\n\tmargin-right: 3em;\n\tmargin-top: 1em;\n\tmargin-bottom: 1em;\n\tpadding: 8px;\n\tborder: 2px solid #7993C8;\n\tfont-family: \"Courier New\", Courier, mono;\n\tfont-size: 10pt;\n\twhite-space: pre;\n}\n\n.code-example-span \n{\n\tfont-family: \"Courier New\", Courier, mono;\n\tfont-size: 10pt;\n\twhite-space: pre;\n}\n\n.code-example-comment\n{\n\tbackground-color: #e0e0f0; \n\tpadding: 0px 0px; \n\tfont-family: \"Courier New\", Courier, mono; \n\tfont-size: 10pt; \n\twhite-space: pre; \n\tcolor: #999999; \n\tmargin: auto auto; \n}\n\n\n.faq-question\n{\n\tbackground-color: #D9E2EC;\n\tfont-size: 12pt;\n\tfont-weight: bold;\n\tmargin-top: 0em;\n\tpadding-left:5px;\n\tpadding-right:8px;\n\tpadding-top:2px;\n\tpadding-bottom:3px;\n\tmargin-bottom: 0.5em;\n}\n\n.faq-answer\n{\n\tdisplay: block;\n\tmargin: 4pt 1em 0.8em;\n}\n.indented {\n\tmargin-left: 50px;\n}\n" }, { "path": "include/EASTL/algorithm.h", "content": "/////////////////////////////////////////////////////////////////////////////\n// Copyright (c) Electronic Arts Inc. All rights reserved.\n/////////////////////////////////////////////////////////////////////////////\n\n///////////////////////////////////////////////////////////////////////////////\n// This file implements some of the primary algorithms from the C++ STL\n// algorithm library. These versions are just like that STL versions and so\n// are redundant. They are provided solely for the purpose of projects that\n// either cannot use standard C++ STL or want algorithms that have guaranteed\n// identical behaviour across platforms.\n///////////////////////////////////////////////////////////////////////////////\n\n\n///////////////////////////////////////////////////////////////////////////////\n// Definitions\n//\n// You will notice that we are very particular about the templated typenames\n// we use here. You will notice that we follow the C++ standard closely in\n// these respects. Each of these typenames have a specific meaning;\n// this is why we don't just label templated arguments with just letters\n// such as T, U, V, A, B. Here we provide a quick reference for the typenames\n// we use. See the C++ standard, section 25-8 for more details.\n// --------------------------------------------------------------\n// typename Meaning\n// --------------------------------------------------------------\n// T The value type.\n// Compare A function which takes two arguments and returns the lesser of the two.\n// Predicate A function which takes one argument returns true if the argument meets some criteria.\n// BinaryPredicate A function which takes two arguments and returns true if some criteria is met (e.g. they are equal).\n// StrickWeakOrdering A BinaryPredicate that compares two objects, returning true if the first precedes the second. Like Compare but has additional requirements. Used for sorting routines.\n// Function A function which takes one argument and applies some operation to the target.\n// Size A count or size.\n// Generator A function which takes no arguments and returns a value (which will usually be assigned to an object).\n// UnaryOperation A function which takes one argument and returns a value (which will usually be assigned to second object).\n// BinaryOperation A function which takes two arguments and returns a value (which will usually be assigned to a third object).\n// InputIterator An input iterator (iterator you read from) which allows reading each element only once and only in a forward direction.\n// ForwardIterator An input iterator which is like InputIterator except it can be reset back to the beginning.\n// BidirectionalIterator An input iterator which is like ForwardIterator except it can be read in a backward direction as well.\n// RandomAccessIterator An input iterator which can be addressed like an array. It is a superset of all other input iterators.\n// OutputIterator An output iterator (iterator you write to) which allows writing each element only once in only in a forward direction.\n//\n// Note that with iterators that a function which takes an InputIterator will\n// also work with a ForwardIterator, BidirectionalIterator, or RandomAccessIterator.\n// The given iterator type is merely the -minimum- supported functionality the\n// iterator must support.\n///////////////////////////////////////////////////////////////////////////////\n\n\n///////////////////////////////////////////////////////////////////////////////\n// Optimizations\n//\n// There are a number of opportunities for optimizations that we take here\n// in this library. The most obvious kinds are those that subsitute memcpy\n// in the place of a conventional loop for data types with which this is\n// possible. The algorithms here are optimized to a higher level than currently\n// available C++ STL algorithms from vendors such as Microsoft. This is especially\n// so for game programming on console devices, as we do things such as reduce\n// branching relative to other STL algorithm implementations. However, the\n// proper implementation of these algorithm optimizations is a fairly tricky\n// thing.\n//\n// The various things we look to take advantage of in order to implement\n// optimizations include:\n// - Taking advantage of random access iterators.\n// - Taking advantage of trivially copyable data types (types for which it is safe to memcpy or memmove).\n// - Taking advantage of type_traits in general.\n// - Reducing branching and taking advantage of likely branch predictions.\n// - Taking advantage of issues related to pointer and reference aliasing.\n// - Improving cache coherency during memory accesses.\n// - Making code more likely to be inlinable by the compiler.\n//\n///////////////////////////////////////////////////////////////////////////////\n\n\n///////////////////////////////////////////////////////////////////////////////\n// Supported Algorithms\n//\n// Algorithms that we implement are listed here. Note that these items are not\n// all within this header file, as we split up the header files in order to\n// improve compilation performance. Items marked with '+' are items that are\n// extensions which don't exist in the C++ standard.\n//\n// -------------------------------------------------------------------------------\n// Algorithm Notes\n// -------------------------------------------------------------------------------\n// adjacent_find\n// adjacent_find\n// all_of C++11\n// any_of C++11\n// none_of C++11\n// binary_search\n// binary_search\n// +binary_search_i\n// +binary_search_i\n// +change_heap Found in heap.h\n// +change_heap Found in heap.h\n// clamp\n// copy\n// copy_if C++11\n// copy_n C++11\n// copy_backward\n// count\n// count_if\n// equal\n// equal\n// equal_range\n// equal_range\n// fill\n// fill_n\n// find\n// find_end\n// find_end\n// find_first_of\n// find_first_of\n// +find_first_not_of\n// +find_first_not_of\n// +find_last_of\n// +find_last_of\n// +find_last_not_of\n// +find_last_not_of\n// find_if\n// find_if_not\n// for_each\n// generate\n// generate_n\n// +identical\n// +identical\n// iter_swap\n// lexicographical_compare\n// lexicographical_compare\n// lexicographical_compare_three_way\n// lower_bound\n// lower_bound\n// make_heap Found in heap.h\n// make_heap Found in heap.h\n// min\n// min\n// max\n// max\n// +min_alt Exists to work around the problem of conflicts with min/max #defines on some systems.\n// +min_alt\n// +max_alt\n// +max_alt\n// +median\n// +median\n// merge Found in sort.h\n// merge Found in sort.h\n// min_element\n// min_element\n// max_element\n// max_element\n// mismatch\n// mismatch\n// move\n// move_backward\n// nth_element Found in sort.h\n// nth_element Found in sort.h\n// partial_sort Found in sort.h\n// partial_sort Found in sort.h\n// push_heap Found in heap.h\n// push_heap Found in heap.h\n// pop_heap Found in heap.h\n// pop_heap Found in heap.h\n// random_shuffle\n// remove\n// remove_if\n// +apply_and_remove\n// +apply_and_remove_if\n// remove_copy\n// remove_copy_if\n// +remove_heap Found in heap.h\n// +remove_heap Found in heap.h\n// replace\n// replace_if\n// replace_copy\n// replace_copy_if\n// reverse_copy\n// reverse\n// random_shuffle\n// rotate\n// rotate_copy\n// search\n// search\n// search_n\n// set_difference\n// set_difference\n// set_difference_2\n// set_difference_2\n// set_decomposition\n// set_decomposition\n// set_intersection\n// set_intersection\n// set_symmetric_difference\n// set_symmetric_difference\n// set_union\n// set_union\n// sort Found in sort.h\n// sort Found in sort.h\n// sort_heap Found in heap.h\n// sort_heap Found in heap.h\n// stable_sort Found in sort.h\n// stable_sort Found in sort.h\n// partition Found in sort.h\n// stable_partition Found in sort.h\n// swap\n// swap_ranges\n// transform\n// transform\n// unique\n// unique\n// upper_bound\n// upper_bound\n// includes\n// includes\n// is_permutation\n// is_permutation\n// next_permutation\n// next_permutation\n// is_partitioned\n// partition_point\n//\n// Algorithms from the C++ standard that we don't implement are listed here.\n// Most of these items are absent because they aren't used very often.\n// They also happen to be the more complicated than other algorithms.\n// However, we can implement any of these functions for users that might\n// need them.\n// inplace_merge\n// inplace_merge\n// partial_sort_copy\n// partial_sort_copy\n// prev_permutation\n// prev_permutation\n// search_n\n// unique_copy\n// unique_copy\n//\n///////////////////////////////////////////////////////////////////////////////\n\n\n#ifndef EASTL_ALGORITHM_H\n#define EASTL_ALGORITHM_H\n\n\n#include \n#include \n#include \n#include \n#include \n#include \n#include \n#include \n#include \n#include \n#include \n\nEA_DISABLE_ALL_VC_WARNINGS();\n\n\t#if defined(EA_COMPILER_MSVC) && (defined(EA_PROCESSOR_X86) || defined(EA_PROCESSOR_X86_64))\n\t\t#include \n\t#endif\n\n\t#include \n\t#include // memcpy, memcmp, memmove\n\nEA_RESTORE_ALL_VC_WARNINGS();\n\n#if defined(EA_PRAGMA_ONCE_SUPPORTED)\n\t#pragma once // Some compilers (e.g. VC++) benefit significantly from using this. We've measured 3-4% build speed improvements in apps as a result.\n#endif\n\n\n\n///////////////////////////////////////////////////////////////////////////////\n// min/max workaround\n//\n// MSVC++ has #defines for min/max which collide with the min/max algorithm\n// declarations. The following may still not completely resolve some kinds of\n// problems with MSVC++ #defines, though it deals with most cases in production\n// game code.\n//\n#if EASTL_NOMINMAX\n\t#ifdef min\n\t\t#undef min\n\t#endif\n\t#ifdef max\n\t\t#undef max\n\t#endif\n#endif\n\n\n\n\nnamespace eastl\n{\n\t/// min_element\n\t///\n\t/// min_element finds the smallest element in the range [first, last).\n\t/// It returns the first iterator i in [first, last) such that no other\n\t/// iterator in [first, last) points to a value smaller than *i.\n\t/// The return value is last if and only if [first, last) is an empty range.\n\t///\n\t/// Returns: The first iterator i in the range [first, last) such that\n\t/// for any iterator j in the range [first, last) the following corresponding\n\t/// condition holds: !(*j < *i).\n\t///\n\t/// Complexity: Exactly 'max((last - first) - 1, 0)' applications of the\n\t/// corresponding comparisons.\n\t///\n\ttemplate \n\tForwardIterator min_element(ForwardIterator first, ForwardIterator last)\n\t{\n\t\tif(first != last)\n\t\t{\n\t\t\tForwardIterator currentMin = first;\n\n\t\t\twhile(++first != last)\n\t\t\t{\n\t\t\t\tif(*first < *currentMin)\n\t\t\t\t\tcurrentMin = first;\n\t\t\t}\n\t\t\treturn currentMin;\n\t\t}\n\t\treturn first;\n\t}\n\n\n\t/// min_element\n\t///\n\t/// min_element finds the smallest element in the range [first, last).\n\t/// It returns the first iterator i in [first, last) such that no other\n\t/// iterator in [first, last) points to a value smaller than *i.\n\t/// The return value is last if and only if [first, last) is an empty range.\n\t///\n\t/// Returns: The first iterator i in the range [first, last) such that\n\t/// for any iterator j in the range [first, last) the following corresponding\n\t/// conditions hold: compare(*j, *i) == false.\n\t///\n\t/// Complexity: Exactly 'max((last - first) - 1, 0)' applications of the\n\t/// corresponding comparisons.\n\t///\n\ttemplate \n\tForwardIterator min_element(ForwardIterator first, ForwardIterator last, Compare compare)\n\t{\n\t\tif(first != last)\n\t\t{\n\t\t\tForwardIterator currentMin = first;\n\n\t\t\twhile(++first != last)\n\t\t\t{\n\t\t\t\tif(compare(*first, *currentMin))\n\t\t\t\t\tcurrentMin = first;\n\t\t\t}\n\t\t\treturn currentMin;\n\t\t}\n\t\treturn first;\n\t}\n\n\n\t/// max_element\n\t///\n\t/// max_element finds the largest element in the range [first, last).\n\t/// It returns the first iterator i in [first, last) such that no other\n\t/// iterator in [first, last) points to a value greater than *i.\n\t/// The return value is last if and only if [first, last) is an empty range.\n\t///\n\t/// Returns: The first iterator i in the range [first, last) such that\n\t/// for any iterator j in the range [first, last) the following corresponding\n\t/// condition holds: !(*i < *j).\n\t///\n\t/// Complexity: Exactly 'max((last - first) - 1, 0)' applications of the\n\t/// corresponding comparisons.\n\t///\n\ttemplate \n\tForwardIterator max_element(ForwardIterator first, ForwardIterator last)\n\t{\n\t\tif(first != last)\n\t\t{\n\t\t\tForwardIterator currentMax = first;\n\n\t\t\twhile(++first != last)\n\t\t\t{\n\t\t\t\tif(*currentMax < *first)\n\t\t\t\t\tcurrentMax = first;\n\t\t\t}\n\t\t\treturn currentMax;\n\t\t}\n\t\treturn first;\n\t}\n\n\n\t/// max_element\n\t///\n\t/// max_element finds the largest element in the range [first, last).\n\t/// It returns the first iterator i in [first, last) such that no other\n\t/// iterator in [first, last) points to a value greater than *i.\n\t/// The return value is last if and only if [first, last) is an empty range.\n\t///\n\t/// Returns: The first iterator i in the range [first, last) such that\n\t/// for any iterator j in the range [first, last) the following corresponding\n\t/// condition holds: compare(*i, *j) == false.\n\t///\n\t/// Complexity: Exactly 'max((last - first) - 1, 0)' applications of the\n\t/// corresponding comparisons.\n\t///\n\ttemplate \n\tForwardIterator max_element(ForwardIterator first, ForwardIterator last, Compare compare)\n\t{\n\t\tif(first != last)\n\t\t{\n\t\t\tForwardIterator currentMax = first;\n\n\t\t\twhile(++first != last)\n\t\t\t{\n\t\t\t\tif(compare(*currentMax, *first))\n\t\t\t\t\tcurrentMax = first;\n\t\t\t}\n\t\t\treturn currentMax;\n\t\t}\n\t\treturn first;\n\t}\n\n\n\t#if EASTL_MINMAX_ENABLED\n\n\t\t/// min\n\t\t///\n\t\t/// Min returns the lesser of its two arguments; it returns the first\n\t\t/// argument if neither is less than the other. The two arguments are\n\t\t/// compared with operator <.\n\t\t///\n\t\t/// This min and our other min implementations are defined as returning:\n\t\t/// b < a ? b : a\n\t\t/// which for example may in practice result in something different than:\n\t\t/// b <= a ? b : a\n\t\t/// in the case where b is different from a (though they compare as equal).\n\t\t/// We choose the specific ordering here because that's the ordering\n\t\t/// done by other STL implementations.\n\t\t///\n\t\t/// Some compilers (e.g. VS20003 - VS2013) generate poor code for the case of\n\t\t/// scalars returned by reference, so we provide a specialization for those cases.\n\t\t/// The specialization returns T by value instead of reference, which is\n\t\t/// not that the Standard specifies. The Standard allows you to use\n\t\t/// an expression like &max(x, y), which would be impossible in this case.\n\t\t/// However, we have found no actual code that uses min or max like this and\n\t\t/// this specialization causes no problems in practice. Microsoft has acknowledged\n\t\t/// the problem and may fix it for a future VS version.\n\t\t///\n\t\ttemplate \n\t\tinline EA_CONSTEXPR typename eastl::enable_if::value, T>::type\n\t\tmin(T a, T b)\n\t\t{\n\t\t\treturn b < a ? b : a;\n\t\t}\n\n\t\ttemplate \n\t\tinline EA_CONSTEXPR typename eastl::enable_if::value, const T&>::type\n\t\tmin(const T& a, const T& b)\n\t\t{\n\t\t\treturn b < a ? b : a;\n\t\t}\n\n\t\tinline EA_CONSTEXPR float min(float a, float b) { return b < a ? b : a; }\n\t\tinline EA_CONSTEXPR double min(double a, double b) { return b < a ? b : a; }\n\t\tinline EA_CONSTEXPR long double min(long double a, long double b) { return b < a ? b : a; }\n\n\t#endif // EASTL_MINMAX_ENABLED\n\n\n\t/// min_alt\n\t///\n\t/// This is an alternative version of min that avoids any possible\n\t/// collisions with Microsoft #defines of min and max.\n\t///\n\t/// See min(a, b) for detailed specifications.\n\t///\n\ttemplate \n\tinline EA_CONSTEXPR typename eastl::enable_if::value, T>::type\n\tmin_alt(T a, T b)\n\t{\n\t\treturn b < a ? b : a;\n\t}\n\n\ttemplate \n\tinline typename eastl::enable_if::value, const T&>::type\n\tmin_alt(const T& a, const T& b)\n\t{\n\t\treturn b < a ? b : a;\n\t}\n\n\tinline EA_CONSTEXPR float min_alt(float a, float b) { return b < a ? b : a; }\n\tinline EA_CONSTEXPR double min_alt(double a, double b) { return b < a ? b : a; }\n\tinline EA_CONSTEXPR long double min_alt(long double a, long double b) { return b < a ? b : a; }\n\n\n\t#if EASTL_MINMAX_ENABLED\n\n\t\t/// min\n\t\t///\n\t\t/// Min returns the lesser of its two arguments; it returns the first\n\t\t/// argument if neither is less than the other. The two arguments are\n\t\t/// compared with the Compare function (or function object), which\n\t\t/// takes two arguments and returns true if the first is less than\n\t\t/// the second.\n\t\t///\n\t\t/// See min(a, b) for detailed specifications.\n\t\t///\n\t\t/// Example usage:\n\t\t/// struct A{ int a; };\n\t\t/// struct Struct{ bool operator()(const A& a1, const A& a2){ return a1.a < a2.a; } };\n\t\t///\n\t\t/// A a1, a2, a3;\n\t\t/// a3 = min(a1, a2, Struct());\n\t\t///\n\t\t/// Example usage:\n\t\t/// struct B{ int b; };\n\t\t/// inline bool Function(const B& b1, const B& b2){ return b1.b < b2.b; }\n\t\t///\n\t\t/// B b1, b2, b3;\n\t\t/// b3 = min(b1, b2, Function);\n\t\t///\n\t\ttemplate \n\t\tinline const T&\n\t\tmin(const T& a, const T& b, Compare compare)\n\t\t{\n\t\t\treturn compare(b, a) ? b : a;\n\t\t}\n\n\t#endif // EASTL_MINMAX_ENABLED\n\n\n\t/// min_alt\n\t///\n\t/// This is an alternative version of min that avoids any possible\n\t/// collisions with Microsoft #defines of min and max.\n\t///\n\t/// See min(a, b) for detailed specifications.\n\t///\n\ttemplate \n\tinline const T&\n\tmin_alt(const T& a, const T& b, Compare compare)\n\t{\n\t\treturn compare(b, a) ? b : a;\n\t}\n\n\n\t#if EASTL_MINMAX_ENABLED\n\n\t\t/// max\n\t\t///\n\t\t/// Max returns the greater of its two arguments; it returns the first\n\t\t/// argument if neither is greater than the other. The two arguments are\n\t\t/// compared with operator < (and not operator >).\n\t\t///\n\t\t/// This min and our other min implementations are defined as returning:\n\t\t/// a < b ? b : a\n\t\t/// which for example may in practice result in something different than:\n\t\t/// a <= b ? b : a\n\t\t/// in the case where b is different from a (though they compare as equal).\n\t\t/// We choose the specific ordering here because that's the ordering\n\t\t/// done by other STL implementations.\n\t\t///\n\t\ttemplate \n\t\tinline EA_CONSTEXPR typename eastl::enable_if::value, T>::type\n\t\tmax(T a, T b)\n\t\t{\n\t\t\treturn a < b ? b : a;\n\t\t}\n\n\t\ttemplate \n\t\tinline EA_CONSTEXPR typename eastl::enable_if::value, const T&>::type\n\t\tmax(const T& a, const T& b)\n\t\t{\n\t\t\treturn a < b ? b : a;\n\t\t}\n\n\t\tinline EA_CONSTEXPR float max(float a, float b) { return a < b ? b : a; }\n\t\tinline EA_CONSTEXPR double max(double a, double b) { return a < b ? b : a; }\n\t\tinline EA_CONSTEXPR long double max(long double a, long double b) { return a < b ? b : a; }\n\n\t#endif // EASTL_MINMAX_ENABLED\n\n\n\t/// max_alt\n\t///\n\t/// This is an alternative version of max that avoids any possible\n\t/// collisions with Microsoft #defines of min and max.\n\t///\n\ttemplate \n\tinline EA_CONSTEXPR typename eastl::enable_if::value, T>::type\n\tmax_alt(T a, T b)\n\t{\n\t\treturn a < b ? b : a;\n\t}\n\n\ttemplate \n\tinline EA_CONSTEXPR typename eastl::enable_if::value, const T&>::type\n\tmax_alt(const T& a, const T& b)\n\t{\n\t\treturn a < b ? b : a;\n\t}\n\n\tinline EA_CONSTEXPR float max_alt(float a, float b) { return a < b ? b : a; }\n\tinline EA_CONSTEXPR double max_alt(double a, double b) { return a < b ? b : a; }\n\tinline EA_CONSTEXPR long double max_alt(long double a, long double b) { return a < b ? b : a; }\n\n\n\t#if EASTL_MINMAX_ENABLED\n\t\t/// max\n\t\t///\n\t\t/// Min returns the lesser of its two arguments; it returns the first\n\t\t/// argument if neither is less than the other. The two arguments are\n\t\t/// compared with the Compare function (or function object), which\n\t\t/// takes two arguments and returns true if the first is less than\n\t\t/// the second.\n\t\t///\n\t\ttemplate \n\t\tinline const T&\n\t\tmax(const T& a, const T& b, Compare compare)\n\t\t{\n\t\t\treturn compare(a, b) ? b : a;\n\t\t}\n\t#endif\n\n\n\t/// max_alt\n\t///\n\t/// This is an alternative version of max that avoids any possible\n\t/// collisions with Microsoft #defines of min and max.\n\t///\n\ttemplate \n\tinline const T&\n\tmax_alt(const T& a, const T& b, Compare compare)\n\t{\n\t\treturn compare(a, b) ? b : a;\n\t}\n\n\n\t/// min(std::initializer_list)\n\t///\n\ttemplate \n\tT min(std::initializer_list ilist)\n\t{\n\t\treturn *eastl::min_element(ilist.begin(), ilist.end());\n\t}\n\n\t/// min(std::initializer_list, Compare)\n\t///\n\ttemplate \n\tT min(std::initializer_list ilist, Compare compare)\n\t{\n\t\treturn *eastl::min_element(ilist.begin(), ilist.end(), compare);\n\t}\n\n\n\t/// max(std::initializer_list)\n\t///\n\ttemplate \n\tT max(std::initializer_list ilist)\n\t{\n\t\treturn *eastl::max_element(ilist.begin(), ilist.end());\n\t}\n\n\t/// max(std::initializer_list, Compare)\n\t///\n\ttemplate \n\tT max(std::initializer_list ilist, Compare compare)\n\t{\n\t\treturn *eastl::max_element(ilist.begin(), ilist.end(), compare);\n\t}\n\n\n\t/// minmax_element\n\t///\n\t/// Returns: make_pair(first, first) if [first, last) is empty, otherwise make_pair(m, M),\n\t/// where m is the first iterator in [first,last) such that no iterator in the range\n\t/// refers to a smaller element, and where M is the last iterator in [first,last) such\n\t/// that no iterator in the range refers to a larger element.\n\t///\n\t/// Complexity: At most max([(3/2)*(N - 1)], 0) applications of the corresponding predicate,\n\t/// where N is distance(first, last).\n\t///\n\ttemplate \n\teastl::pair\n\tminmax_element(ForwardIterator first, ForwardIterator last, Compare compare)\n\t{\n\t\teastl::pair result(first, first);\n\n\t\tif(!(first == last) && !(++first == last))\n\t\t{\n\t\t\tif(compare(*first, *result.first))\n\t\t\t{\n\t\t\t\tresult.second = result.first;\n\t\t\t\tresult.first = first;\n\t\t\t}\n\t\t\telse\n\t\t\t\tresult.second = first;\n\n\t\t\twhile(++first != last)\n\t\t\t{\n\t\t\t\tForwardIterator i = first;\n\n\t\t\t\tif(++first == last)\n\t\t\t\t{\n\t\t\t\t\tif(compare(*i, *result.first))\n\t\t\t\t\t\tresult.first = i;\n\t\t\t\t\telse if(!compare(*i, *result.second))\n\t\t\t\t\t\tresult.second = i;\n\t\t\t\t\tbreak;\n\t\t\t\t}\n\t\t\t\telse\n\t\t\t\t{\n\t\t\t\t\tif(compare(*first, *i))\n\t\t\t\t\t{\n\t\t\t\t\t\tif(compare(*first, *result.first))\n\t\t\t\t\t\t\tresult.first = first;\n\n\t\t\t\t\t\tif(!compare(*i, *result.second))\n\t\t\t\t\t\t\tresult.second = i;\n\t\t\t\t\t}\n\t\t\t\t\telse\n\t\t\t\t\t{\n\t\t\t\t\t\tif(compare(*i, *result.first))\n\t\t\t\t\t\t\tresult.first = i;\n\n\t\t\t\t\t\tif(!compare(*first, *result.second))\n\t\t\t\t\t\t\tresult.second = first;\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\treturn result;\n\t}\n\n\n\ttemplate \n\teastl::pair\n\tminmax_element(ForwardIterator first, ForwardIterator last)\n\t{\n\t\ttypedef typename eastl::iterator_traits::value_type value_type;\n\n\t\treturn eastl::minmax_element(first, last, eastl::less());\n\t}\n\n\n\n\t/// minmax\n\t///\n\t/// Requires: Type T shall be LessThanComparable.\n\t/// Returns: pair(b, a) if b is smaller than a, and pair(a, b) otherwise.\n\t/// Remarks: Returns pair(a, b) when the arguments are equivalent.\n\t/// Complexity: Exactly one comparison.\n\t///\n\n\t// The following optimization is a problem because it changes the return value in a way that would break\n\t// users unless they used auto (e.g. auto result = minmax(17, 33); )\n\t//\n\t// template \n\t// inline EA_CONSTEXPR typename eastl::enable_if::value, eastl::pair >::type\n\t// minmax(T a, T b)\n\t// {\n\t// return (b < a) ? eastl::make_pair(b, a) : eastl::make_pair(a, b);\n\t// }\n\t//\n\t// template \n\t// inline typename eastl::enable_if::value, eastl::pair >::type\n\t// minmax(const T& a, const T& b)\n\t// {\n\t// return (b < a) ? eastl::make_pair(b, a) : eastl::make_pair(a, b);\n\t// }\n\n\t// It turns out that the following conforming definition of minmax generates a warning when used with VC++ up\n\t// to at least VS2012. The VS2012 version of minmax is a broken and non-conforming definition, and we don't\n\t// want to do that. We could do it for scalars alone, though we'd have to decide if we are going to do that\n\t// for all compilers, because it changes the return value from a pair of references to a pair of values.\n\ttemplate \n\tinline eastl::pair\n\tminmax(const T& a, const T& b)\n\t{\n\t\treturn (b < a) ? eastl::make_pair(b, a) : eastl::make_pair(a, b);\n\t}\n\n\n\ttemplate \n\teastl::pair\n\tminmax(const T& a, const T& b, Compare compare)\n\t{\n\t\treturn compare(b, a) ? eastl::make_pair(b, a) : eastl::make_pair(a, b);\n\t}\n\n\n\n\ttemplate \n\teastl::pair\n\tminmax(std::initializer_list ilist)\n\t{\n\t\ttypedef typename std::initializer_list::iterator iterator_type;\n\t\teastl::pair iteratorPair = eastl::minmax_element(ilist.begin(), ilist.end());\n\t\treturn eastl::make_pair(*iteratorPair.first, *iteratorPair.second);\n\t}\n\n\ttemplate \n\teastl::pair\n\tminmax(std::initializer_list ilist, Compare compare)\n\t{\n\t\ttypedef typename std::initializer_list::iterator iterator_type;\n\t\teastl::pair iteratorPair = eastl::minmax_element(ilist.begin(), ilist.end(), compare);\n\t\treturn eastl::make_pair(*iteratorPair.first, *iteratorPair.second);\n\t}\n\n\ttemplate \n\tinline T&& median_impl(T&& a, T&& b, T&& c)\n\t{\n\t\tif(a < b)\n\t\t{\n\t\t\tif(b < c)\n\t\t\t\treturn eastl::forward(b);\n\t\t\telse if(a < c)\n\t\t\t\treturn eastl::forward(c);\n\t\t\telse\n\t\t\t\treturn eastl::forward(a);\n\t\t}\n\t\telse if(a < c)\n\t\t\treturn eastl::forward(a);\n\t\telse if(b < c)\n\t\t\treturn eastl::forward(c);\n\t\treturn eastl::forward(b);\n\t}\n\n\t/// median\n\t///\n\t/// median finds which element of three (a, b, d) is in-between the other two.\n\t/// If two or more elements are equal, the first (e.g. a before b) is chosen.\n\t///\n\t/// Complexity: Either two or three comparisons will be required, depending\n\t/// on the values.\n\t///\n\ttemplate \n\tinline const T& median(const T& a, const T& b, const T& c)\n\t{\n\t\treturn median_impl(a, b, c);\n\t}\n\n\t/// median\n\t///\n\t/// median finds which element of three (a, b, d) is in-between the other two.\n\t/// If two or more elements are equal, the first (e.g. a before b) is chosen.\n\t///\n\t/// Complexity: Either two or three comparisons will be required, depending\n\t/// on the values.\n\t///\n\ttemplate \n\tinline T&& median(T&& a, T&& b, T&& c)\n\t{\n\t\treturn eastl::forward(median_impl(eastl::forward(a), eastl::forward(b), eastl::forward(c)));\n\t}\n\n\n\ttemplate \n\tinline T&& median_impl(T&& a, T&& b, T&& c, Compare compare)\n\t{\n\t\tif(compare(a, b))\n\t\t{\n\t\t\tif(compare(b, c))\n\t\t\t\treturn eastl::forward(b);\n\t\t\telse if(compare(a, c))\n\t\t\t\treturn eastl::forward(c);\n\t\t\telse\n\t\t\t\treturn eastl::forward(a);\n\t\t}\n\t\telse if(compare(a, c))\n\t\t\treturn eastl::forward(a);\n\t\telse if(compare(b, c))\n\t\t\treturn eastl::forward(c);\n\t\treturn eastl::forward(b);\n\t}\n\n\n\t/// median\n\t///\n\t/// median finds which element of three (a, b, d) is in-between the other two.\n\t/// If two or more elements are equal, the first (e.g. a before b) is chosen.\n\t///\n\t/// Complexity: Either two or three comparisons will be required, depending\n\t/// on the values.\n\t///\n\ttemplate \n\tinline const T& median(const T& a, const T& b, const T& c, Compare compare)\n\t{\n\t\treturn median_impl(a, b, c, compare);\n\t}\n\n\t/// median\n\t///\n\t/// median finds which element of three (a, b, d) is in-between the other two.\n\t/// If two or more elements are equal, the first (e.g. a before b) is chosen.\n\t///\n\t/// Complexity: Either two or three comparisons will be required, depending\n\t/// on the values.\n\t///\n\ttemplate \n\tinline T&& median(T&& a, T&& b, T&& c, Compare compare)\n\t{\n\t\treturn eastl::forward(median_impl(eastl::forward(a), eastl::forward(b), eastl::forward(c), compare));\n\t}\n\n\n\n\n\t/// all_of\n\t///\n\t/// Returns: true if the unary predicate p returns true for all elements in the range [first, last)\n\t///\n\ttemplate \n\tinline bool all_of(InputIterator first, InputIterator last, Predicate p)\n\t{\n\t\tfor(; first != last; ++first)\n\t\t{\n\t\t\tif(!p(*first))\n\t\t\t\treturn false;\n\t\t}\n\t\treturn true;\n\t}\n\n\n\t/// any_of\n\t///\n\t/// Returns: true if the unary predicate p returns true for any of the elements in the range [first, last)\n\t///\n\ttemplate \n\tinline bool any_of(InputIterator first, InputIterator last, Predicate p)\n\t{\n\t\tfor(; first != last; ++first)\n\t\t{\n\t\t\tif(p(*first))\n\t\t\t\treturn true;\n\t\t}\n\t\treturn false;\n\t}\n\n\n\t/// none_of\n\t///\n\t/// Returns: true if the unary predicate p returns true for none of the elements in the range [first, last)\n\t///\n\ttemplate \n\tinline bool none_of(InputIterator first, InputIterator last, Predicate p)\n\t{\n\t\tfor(; first != last; ++first)\n\t\t{\n\t\t\tif(p(*first))\n\t\t\t\treturn false;\n\t\t}\n\t\treturn true;\n\t}\n\n\n\t/// adjacent_find\n\t///\n\t/// Returns: The first iterator i such that both i and i + 1 are in the range\n\t/// [first, last) for which the following corresponding conditions hold: *i == *(i + 1).\n\t/// Returns last if no such iterator is found.\n\t///\n\t/// Complexity: Exactly 'find(first, last, value) - first' applications of the corresponding predicate.\n\t///\n\ttemplate \n\tinline ForwardIterator\n\tadjacent_find(ForwardIterator first, ForwardIterator last)\n\t{\n\t\tif(first != last)\n\t\t{\n\t\t\tForwardIterator i = first;\n\n\t\t\tfor(++i; i != last; ++i)\n\t\t\t{\n\t\t\t\tif(*first == *i)\n\t\t\t\t\treturn first;\n\t\t\t\tfirst = i;\n\t\t\t}\n\t\t}\n\t\treturn last;\n\t}\n\n\n\n\t/// adjacent_find\n\t///\n\t/// Returns: The first iterator i such that both i and i + 1 are in the range\n\t/// [first, last) for which the following corresponding conditions hold: predicate(*i, *(i + 1)) != false.\n\t/// Returns last if no such iterator is found.\n\t///\n\t/// Complexity: Exactly 'find(first, last, value) - first' applications of the corresponding predicate.\n\t///\n\ttemplate \n\tinline ForwardIterator\n\tadjacent_find(ForwardIterator first, ForwardIterator last, BinaryPredicate predicate)\n\t{\n\t\tif(first != last)\n\t\t{\n\t\t\tForwardIterator i = first;\n\n\t\t\tfor(++i; i != last; ++i)\n\t\t\t{\n\t\t\t\tif(predicate(*first, *i))\n\t\t\t\t\treturn first;\n\t\t\t\tfirst = i;\n\t\t\t}\n\t\t}\n\t\treturn last;\n\t}\n\n\n\t/// shuffle\n\t///\n\t/// New for C++11\n\t/// Randomizes a sequence of values via a user-supplied UniformRandomNumberGenerator.\n\t/// The difference between this and the original random_shuffle function is that this uses the more\n\t/// advanced and flexible UniformRandomNumberGenerator interface as opposed to the more\n\t/// limited RandomNumberGenerator interface of random_shuffle.\n\t///\n\t/// Effects: Shuffles the elements in the range [first, last) with uniform distribution.\n\t///\n\t/// Complexity: Exactly '(last - first) - 1' swaps.\n\t///\n\t/// Example usage:\n\t/// struct Rand{ eastl_size_t operator()(eastl_size_t n) { return (eastl_size_t)(rand() % n); } }; // Note: The C rand function is poor and slow.\n\t/// Rand randInstance;\n\t/// shuffle(pArrayBegin, pArrayEnd, randInstance);\n\t///\n\t// See the C++11 Standard, 26.5.1.3, Uniform random number generator requirements.\n\t// Also http://en.cppreference.com/w/cpp/numeric/random/uniform_int_distribution\n\n\ttemplate \n\tvoid shuffle(RandomAccessIterator first, RandomAccessIterator last, UniformRandomNumberGenerator&& urng)\n\t{\n\t\tif(first != last)\n\t\t{\n\t\t\ttypedef typename eastl::iterator_traits::difference_type difference_type;\n\t\t\ttypedef typename eastl::make_unsigned::type unsigned_difference_type;\n\t\t\ttypedef typename eastl::uniform_int_distribution uniform_int_distribution;\n\t\t\ttypedef typename uniform_int_distribution::param_type uniform_int_distribution_param_type;\n\n\t\t\tuniform_int_distribution uid;\n\n\t\t\tfor(RandomAccessIterator i = first + 1; i != last; ++i)\n\t\t\t\titer_swap(i, first + uid(urng, uniform_int_distribution_param_type(0, i - first)));\n\t\t}\n\t}\n\n\n\t/// random_shuffle\n\t///\n\t/// Randomizes a sequence of values.\n\t///\n\t/// Effects: Shuffles the elements in the range [first, last) with uniform distribution.\n\t///\n\t/// Complexity: Exactly '(last - first) - 1' swaps.\n\t///\n\t/// Example usage:\n\t/// eastl_size_t Rand(eastl_size_t n) { return (eastl_size_t)(rand() % n); } // Note: The C rand function is poor and slow.\n\t/// random_shuffle(pArrayBegin, pArrayEnd, Rand);\n\t///\n\t/// Example usage:\n\t/// struct Rand{ eastl_size_t operator()(eastl_size_t n) { return (eastl_size_t)(rand() % n); } }; // Note: The C rand function is poor and slow.\n\t/// Rand randInstance;\n\t/// random_shuffle(pArrayBegin, pArrayEnd, randInstance);\n\t///\n\ttemplate \n\tinline void random_shuffle(RandomAccessIterator first, RandomAccessIterator last, RandomNumberGenerator&& rng)\n\t{\n\t\ttypedef typename eastl::iterator_traits::difference_type difference_type;\n\n\t\t// We must do 'rand((i - first) + 1)' here and cannot do 'rand(last - first)',\n\t\t// as it turns out that the latter results in unequal distribution probabilities.\n\t\t// http://www.cigital.com/papers/download/developer_gambling.php\n\n\t\tconst difference_type swapMax = eastl::distance(first, last);\n\n\t\t// deliberately start at 1.\n\t\tfor (difference_type swapIter = 1; swapIter < swapMax; ++swapIter)\n\t\t{\n\t\t\tRandomAccessIterator i = first + swapIter;\n\t\t\titer_swap(i, first + (difference_type)rng((eastl_size_t)((i - first) + 1)));\n\t\t}\n\t}\n\n\n\t/// random_shuffle\n\t///\n\t/// Randomizes a sequence of values.\n\t///\n\t/// Effects: Shuffles the elements in the range [first, last) with uniform distribution.\n\t///\n\t/// Complexity: Exactly '(last - first) - 1' swaps.\n\t///\n\t/// Example usage:\n\t/// random_shuffle(pArrayBegin, pArrayEnd);\n\t///\n\t/// *** Disabled until we decide if we want to get into the business of writing random number generators. ***\n\t///\n\t/// template \n\t/// inline void random_shuffle(RandomAccessIterator first, RandomAccessIterator last)\n\t/// {\n\t/// for(RandomAccessIterator i = first + 1; i < last; ++i)\n\t/// iter_swap(i, first + SomeRangedRandomNumberGenerator((i - first) + 1));\n\t/// }\n\n\n\n\n\n\n\t/// move_n\n\t///\n\t/// Same as move(InputIterator, InputIterator, OutputIterator) except based on count instead of iterator range.\n\t///\n\ttemplate \n\tinline OutputIterator\n\tmove_n_impl(InputIterator first, Size n, OutputIterator result, eastl::input_iterator_tag)\n\t{\n\t\tfor(; n > 0; --n)\n\t\t\t*result++ = eastl::move(*first++);\n\t\treturn result;\n\t}\n\n\ttemplate \n\tinline OutputIterator\n\tmove_n_impl(RandomAccessIterator first, Size n, OutputIterator result, eastl::random_access_iterator_tag)\n\t{\n\t\treturn eastl::move(first, first + n, result); // Take advantage of the optimizations present in the move algorithm.\n\t}\n\n\n\ttemplate \n\tinline OutputIterator\n\tmove_n(InputIterator first, Size n, OutputIterator result)\n\t{\n\t\ttypedef typename eastl::iterator_traits::iterator_category IC;\n\t\treturn eastl::move_n_impl(first, n, result, IC());\n\t}\n\n\n\n\t/// copy_n\n\t///\n\t/// Same as copy(InputIterator, InputIterator, OutputIterator) except based on count instead of iterator range.\n\t/// Effects: Copies exactly count values from the range beginning at first to the range beginning at result, if count > 0. Does nothing otherwise.\n\t/// Returns: Iterator in the destination range, pointing past the last element copied if count>0 or first otherwise.\n\t/// Complexity: Exactly count assignments, if count > 0.\n\t///\n\ttemplate \n\tinline OutputIterator\n\tcopy_n_impl(InputIterator first, Size n, OutputIterator result, eastl::input_iterator_tag)\n\t{\n\t\tfor(; n > 0; --n)\n\t\t\t*result++ = *first++;\n\t\treturn result;\n\t}\n\n\ttemplate \n\tinline OutputIterator\n\tcopy_n_impl(RandomAccessIterator first, Size n, OutputIterator result, eastl::random_access_iterator_tag)\n\t{\n\t\treturn eastl::copy(first, first + n, result); // Take advantage of the optimizations present in the copy algorithm.\n\t}\n\n\n\ttemplate \n\tinline OutputIterator\n\tcopy_n(InputIterator first, Size n, OutputIterator result)\n\t{\n\t\ttypedef typename eastl::iterator_traits::iterator_category IC;\n\t\treturn eastl::copy_n_impl(first, n, result, IC());\n\t}\n\n\n\t/// copy_if\n\t///\n\t/// Effects: Assigns to the result iterator only if the predicate is true.\n\t///\n\ttemplate \n\tinline OutputIterator\n\tcopy_if(InputIterator first, InputIterator last, OutputIterator result, Predicate predicate)\n\t{\n\t\t// This implementation's performance could be improved by taking a more complicated approach like with the copy algorithm.\n\t\tfor(; first != last; ++first)\n\t\t{\n\t\t\tif(predicate(*first))\n\t\t\t\t*result++ = *first;\n\t\t}\n\n\t\treturn result;\n\t}\n\n\n\n\n\t// Implementation moving copying both trivial and non-trivial data via a lesser iterator than random-access.\n\ttemplate \n\tstruct move_and_copy_backward_helper\n\t{\n\t\ttemplate \n\t\tstatic BidirectionalIterator2 move_or_copy_backward(BidirectionalIterator1 first, BidirectionalIterator1 last, BidirectionalIterator2 resultEnd)\n\t\t{\n\t\t\twhile(first != last)\n\t\t\t\t*--resultEnd = *--last;\n\t\t\treturn resultEnd; // resultEnd now points to the beginning of the destination sequence instead of the end.\n\t\t}\n\t};\n\n\t// Specialization for moving non-trivial data via a lesser iterator than random-access.\n\ttemplate \n\tstruct move_and_copy_backward_helper\n\t{\n\t\ttemplate \n\t\tstatic BidirectionalIterator2 move_or_copy_backward(BidirectionalIterator1 first, BidirectionalIterator1 last, BidirectionalIterator2 resultEnd)\n\t\t{\n\t\t\twhile(first != last)\n\t\t\t\t*--resultEnd = eastl::move(*--last);\n\t\t\treturn resultEnd; // resultEnd now points to the beginning of the destination sequence instead of the end.\n\t\t}\n\t};\n\n\t// Specialization for moving non-trivial data via a random-access iterator. It's theoretically faster because the compiler can see the count when its a compile-time const.\n\ttemplate<>\n\tstruct move_and_copy_backward_helper\n\t{\n\t\ttemplate\n\t\tstatic BidirectionalIterator2 move_or_copy_backward(BidirectionalIterator1 first, BidirectionalIterator1 last, BidirectionalIterator2 resultEnd)\n\t\t{\n\t\t\ttypedef typename eastl::iterator_traits::difference_type difference_type;\n\n\t\t\tfor(difference_type n = (last - first); n > 0; --n)\n\t\t\t\t*--resultEnd = eastl::move(*--last);\n\t\t\treturn resultEnd; // resultEnd now points to the beginning of the destination sequence instead of the end.\n\t\t}\n\t};\n\n\t// Specialization for copying non-trivial data via a random-access iterator. It's theoretically faster because the compiler can see the count when its a compile-time const.\n\t// This specialization converts the random access BidirectionalIterator1 last-first to an integral type. There's simple way for us to take advantage of a random access output iterator,\n\t// as the range is specified by the input instead of the output, and distance(first, last) for a non-random-access iterator is potentially slow.\n\ttemplate <>\n\tstruct move_and_copy_backward_helper\n\t{\n\t\ttemplate \n\t\tstatic BidirectionalIterator2 move_or_copy_backward(BidirectionalIterator1 first, BidirectionalIterator1 last, BidirectionalIterator2 resultEnd)\n\t\t{\n\t\t\ttypedef typename eastl::iterator_traits::difference_type difference_type;\n\n\t\t\tfor(difference_type n = (last - first); n > 0; --n)\n\t\t\t\t*--resultEnd = *--last;\n\t\t\treturn resultEnd; // resultEnd now points to the beginning of the destination sequence instead of the end.\n\t\t}\n\t};\n\n\t// Specialization for when we can use memmove/memcpy. See the notes above for what conditions allow this.\n\ttemplate \n\tstruct move_and_copy_backward_helper\n\t{\n\t\ttemplate \n\t\tstatic T* move_or_copy_backward(const T* first, const T* last, T* resultEnd)\n\t\t{\n\t\t\tconst size_t n = (size_t)((uintptr_t)last - (uintptr_t)first);\n\t\t\t// We could use memcpy here if there's no range overlap, but memcpy is rarely much faster than memmove.\n\t\t\tif (n > 0)\n\t\t\t\treturn (T*)memmove(resultEnd - (last - first), first, n);\n\t\t\telse\n\t\t\t\treturn resultEnd;\n\t\t}\n\t};\n\n\ttemplate \n\tinline BidirectionalIterator2 move_and_copy_backward_chooser(BidirectionalIterator1 first, BidirectionalIterator1 last, BidirectionalIterator2 resultEnd)\n\t{\n\t\ttypedef typename eastl::iterator_traits::iterator_category IIC;\n\n\t\tconst bool canBeMemmoved = internal::can_be_memmoved_helper::value;\n\n\t\treturn eastl::move_and_copy_backward_helper::move_or_copy_backward(first, last, resultEnd); // Need to chose based on the input iterator tag and not the output iterator tag, because containers accept input ranges of iterator types different than self.\n\t}\n\n\n\ttemplate \n\tEASTL_REMOVE_AT_2024_SEPT inline BidirectionalIterator2 move_and_copy_backward_unwrapper(BidirectionalIterator1 first, BidirectionalIterator1 last, BidirectionalIterator2 resultEnd)\n\t{\n\t\tEASTL_INTERNAL_DISABLE_DEPRECATED() // 'unwrap_iterator': was declared deprecated\n\t\treturn BidirectionalIterator2(eastl::move_and_copy_backward_chooser(eastl::unwrap_iterator(first), eastl::unwrap_iterator(last), eastl::unwrap_iterator(resultEnd))); // Have to convert to BidirectionalIterator2 because result.base() could be a T*\n\t\tEASTL_INTERNAL_RESTORE_DEPRECATED()\n\t}\n\n\n\t/// move_backward\n\t///\n\t/// The elements are moved in reverse order (the last element is moved first), but their relative order is preserved.\n\t/// After this operation the elements in the moved-from range will still contain valid values of the\n\t/// appropriate type, but not necessarily the same values as before the move.\n\t/// Returns the beginning of the result range.\n\t/// Note: When moving between containers, the dest range must be valid; this function doesn't resize containers.\n\t/// Note: If result is within [first, last), move must be used instead of move_backward.\n\t///\n\t/// Example usage:\n\t/// eastl::move_backward(myArray.begin(), myArray.end(), myDestArray.end());\n\t///\n\t/// Reference implementation:\n\t/// template \n\t/// BidirectionalIterator2 move_backward(BidirectionalIterator1 first, BidirectionalIterator1 last, BidirectionalIterator2 resultEnd)\n\t/// {\n\t/// while(last != first)\n\t/// *--resultEnd = eastl::move(*--last);\n\t/// return resultEnd;\n\t/// }\n\t///\n\ttemplate \n\tinline BidirectionalIterator2 move_backward(BidirectionalIterator1 first, BidirectionalIterator1 last, BidirectionalIterator2 resultEnd)\n\t{\n\t\treturn eastl::move_and_copy_backward_chooser(first, last, resultEnd);\n\t}\n\n\n\t/// copy_backward\n\t///\n\t/// copies memory in the range of [first, last) to the range *ending* with result.\n\t///\n\t/// Effects: Copies elements in the range [first, last) into the range\n\t/// [result - (last - first), result) starting from last 1 and proceeding to first.\n\t/// For each positive integer n <= (last - first), performs *(result n) = *(last - n).\n\t///\n\t/// Requires: result shall not be in the range [first, last).\n\t///\n\t/// Returns: result - (last - first). That is, returns the beginning of the result range.\n\t///\n\t/// Complexity: Exactly 'last - first' assignments.\n\t///\n\ttemplate \n\tinline BidirectionalIterator2 copy_backward(BidirectionalIterator1 first, BidirectionalIterator1 last, BidirectionalIterator2 resultEnd)\n\t{\n\t\treturn eastl::move_and_copy_backward_chooser(first, last, resultEnd);\n\t}\n\n\n\t/// count\n\t///\n\t/// Counts the number of items in the range of [first, last) which equal the input value.\n\t///\n\t/// Effects: Returns the number of iterators i in the range [first, last) for which the\n\t/// following corresponding conditions hold: *i == value.\n\t///\n\t/// Complexity: At most 'last - first' applications of the corresponding predicate.\n\t///\n\t/// Note: The predicate version of count is count_if and not another variation of count.\n\t/// This is because both versions would have three parameters and there could be ambiguity.\n\t///\n\ttemplate \n\tinline typename eastl::iterator_traits::difference_type\n\tcount(InputIterator first, InputIterator last, const T& value)\n\t{\n\t\ttypename eastl::iterator_traits::difference_type result = 0;\n\n\t\tfor(; first != last; ++first)\n\t\t{\n\t\t\tif(*first == value)\n\t\t\t\t++result;\n\t\t}\n\t\treturn result;\n\t}\n\n\n\t// C++ doesn't define a count with predicate, as it can effectively be synthesized via count_if\n\t// with an appropriate predicate. However, it's often simpler to just have count with a predicate.\n\ttemplate \n\tinline typename eastl::iterator_traits::difference_type\n\tcount(InputIterator first, InputIterator last, const T& value, Predicate predicate)\n\t{\n\t\ttypename eastl::iterator_traits::difference_type result = 0;\n\n\t\tfor(; first != last; ++first)\n\t\t{\n\t\t\tif(predicate(*first, value))\n\t\t\t\t++result;\n\t\t}\n\t\treturn result;\n\t}\n\n\n\t/// count_if\n\t///\n\t/// Counts the number of items in the range of [first, last) which match\n\t/// the input value as defined by the input predicate function.\n\t///\n\t/// Effects: Returns the number of iterators i in the range [first, last) for which the\n\t/// following corresponding conditions hold: predicate(*i) != false.\n\t///\n\t/// Complexity: At most 'last - first' applications of the corresponding predicate.\n\t///\n\t/// Note: The non-predicate version of count_if is count and not another variation of count_if.\n\t/// This is because both versions would have three parameters and there could be ambiguity.\n\t///\n\ttemplate \n\tinline typename eastl::iterator_traits::difference_type\n\tcount_if(InputIterator first, InputIterator last, Predicate predicate)\n\t{\n\t\ttypename eastl::iterator_traits::difference_type result = 0;\n\n\t\tfor(; first != last; ++first)\n\t\t{\n\t\t\tif(predicate(*first))\n\t\t\t\t++result;\n\t\t}\n\t\treturn result;\n\t}\n\n\n\t/// find\n\t///\n\t/// finds the value within the unsorted range of [first, last).\n\t///\n\t/// Returns: The first iterator i in the range [first, last) for which\n\t/// the following corresponding conditions hold: *i == value.\n\t/// Returns last if no such iterator is found.\n\t///\n\t/// Complexity: At most 'last - first' applications of the corresponding predicate.\n\t/// This is a linear search and not a binary one.\n\t///\n\t/// Note: The predicate version of find is find_if and not another variation of find.\n\t/// This is because both versions would have three parameters and there could be ambiguity.\n\t///\n\ttemplate \n\tinline InputIterator\n\tfind(InputIterator first, InputIterator last, const T& value)\n\t{\n\t\twhile((first != last) && !(*first == value)) // Note that we always express value comparisons in terms of < or ==.\n\t\t\t++first;\n\t\treturn first;\n\t}\n\n\n\t// C++ doesn't define a find with predicate, as it can effectively be synthesized via find_if\n\t// with an appropriate predicate. However, it's often simpler to just have find with a predicate.\n\ttemplate \n\tinline InputIterator\n\tfind(InputIterator first, InputIterator last, const T& value, Predicate predicate)\n\t{\n\t\twhile((first != last) && !predicate(*first, value))\n\t\t\t++first;\n\t\treturn first;\n\t}\n\n\n\n\t/// find_if\n\t///\n\t/// finds the value within the unsorted range of [first, last).\n\t///\n\t/// Returns: The first iterator i in the range [first, last) for which\n\t/// the following corresponding conditions hold: pred(*i) != false.\n\t/// Returns last if no such iterator is found.\n\t/// If the sequence of elements to search for (i.e. first2 - last2) is empty,\n\t/// the find always fails and last1 will be returned.\n\t///\n\t/// Complexity: At most 'last - first' applications of the corresponding predicate.\n\t///\n\t/// Note: The non-predicate version of find_if is find and not another variation of find_if.\n\t/// This is because both versions would have three parameters and there could be ambiguity.\n\t///\n\ttemplate \n\tinline InputIterator\n\tfind_if(InputIterator first, InputIterator last, Predicate predicate)\n\t{\n\t\twhile((first != last) && !predicate(*first))\n\t\t\t++first;\n\t\treturn first;\n\t}\n\n\n\n\t/// find_if_not\n\t///\n\t/// find_if_not works the same as find_if except it tests for if the predicate\n\t/// returns false for the elements instead of true.\n\t///\n\ttemplate \n\tinline InputIterator\n\tfind_if_not(InputIterator first, InputIterator last, Predicate predicate)\n\t{\n\t\tfor(; first != last; ++first)\n\t\t{\n\t\t\tif(!predicate(*first))\n\t\t\t\treturn first;\n\t\t}\n\t\treturn last;\n\t}\n\n\n\n\n\t/// find_first_of\n\t///\n\t/// find_first_of is similar to find in that it performs linear search through\n\t/// a range of ForwardIterators. The difference is that while find searches\n\t/// for one particular value, find_first_of searches for any of several values.\n\t/// Specifically, find_first_of searches for the first occurrance in the\n\t/// range [first1, last1) of any of the elements in [first2, last2).\n\t/// This function is thus similar to the strpbrk standard C string function.\n\t/// If the sequence of elements to search for (i.e. first2-last2) is empty,\n\t/// the find always fails and last1 will be returned.\n\t///\n\t/// Effects: Finds an element that matches one of a set of values.\n\t///\n\t/// Returns: The first iterator i in the range [first1, last1) such that for some\n\t/// integer j in the range [first2, last2) the following conditions hold: *i == *j.\n\t/// Returns last1 if no such iterator is found.\n\t///\n\t/// Complexity: At most '(last1 - first1) * (last2 - first2)' applications of the\n\t/// corresponding predicate.\n\t///\n\ttemplate \n\tForwardIterator1\n\tfind_first_of(ForwardIterator1 first1, ForwardIterator1 last1,\n\t\t\t\t ForwardIterator2 first2, ForwardIterator2 last2)\n\t{\n\t\tfor(; first1 != last1; ++first1)\n\t\t{\n\t\t\tfor(ForwardIterator2 i = first2; i != last2; ++i)\n\t\t\t{\n\t\t\t\tif(*first1 == *i)\n\t\t\t\t\treturn first1;\n\t\t\t}\n\t\t}\n\t\treturn last1;\n\t}\n\n\n\t/// find_first_of\n\t///\n\t/// find_first_of is similar to find in that it performs linear search through\n\t/// a range of ForwardIterators. The difference is that while find searches\n\t/// for one particular value, find_first_of searches for any of several values.\n\t/// Specifically, find_first_of searches for the first occurrance in the\n\t/// range [first1, last1) of any of the elements in [first2, last2).\n\t/// This function is thus similar to the strpbrk standard C string function.\n\t///\n\t/// Effects: Finds an element that matches one of a set of values.\n\t///\n\t/// Returns: The first iterator i in the range [first1, last1) such that for some\n\t/// integer j in the range [first2, last2) the following conditions hold: pred(*i, *j) != false.\n\t/// Returns last1 if no such iterator is found.\n\t///\n\t/// Complexity: At most '(last1 - first1) * (last2 - first2)' applications of the\n\t/// corresponding predicate.\n\t///\n\ttemplate \n\tForwardIterator1\n\tfind_first_of(ForwardIterator1 first1, ForwardIterator1 last1,\n\t\t\t\t ForwardIterator2 first2, ForwardIterator2 last2,\n\t\t\t\t BinaryPredicate predicate)\n\t{\n\t\tfor(; first1 != last1; ++first1)\n\t\t{\n\t\t\tfor(ForwardIterator2 i = first2; i != last2; ++i)\n\t\t\t{\n\t\t\t\tif(predicate(*first1, *i))\n\t\t\t\t\treturn first1;\n\t\t\t}\n\t\t}\n\t\treturn last1;\n\t}\n\n\n\t/// find_first_not_of\n\t///\n\t/// Searches through first range for the first element that does not belong the second input range.\n\t/// This is very much like the C++ string find_first_not_of function.\n\t///\n\t/// Returns: The first iterator i in the range [first1, last1) such that for some\n\t/// integer j in the range [first2, last2) the following conditions hold: !(*i == *j).\n\t/// Returns last1 if no such iterator is found.\n\t///\n\t/// Complexity: At most '(last1 - first1) * (last2 - first2)' applications of the\n\t/// corresponding predicate.\n\t///\n\ttemplate \n\tForwardIterator1\n\tfind_first_not_of(ForwardIterator1 first1, ForwardIterator1 last1,\n\t\t\t\t\t ForwardIterator2 first2, ForwardIterator2 last2)\n\t{\n\t\tfor(; first1 != last1; ++first1)\n\t\t{\n\t\t\tif(eastl::find(first2, last2, *first1) == last2)\n\t\t\t\tbreak;\n\t\t}\n\n\t\treturn first1;\n\t}\n\n\n\n\t/// find_first_not_of\n\t///\n\t/// Searches through first range for the first element that does not belong the second input range.\n\t/// This is very much like the C++ string find_first_not_of function.\n\t///\n\t/// Returns: The first iterator i in the range [first1, last1) such that for some\n\t/// integer j in the range [first2, last2) the following conditions hold: pred(*i, *j) == false.\n\t/// Returns last1 if no such iterator is found.\n\t///\n\t/// Complexity: At most '(last1 - first1) * (last2 - first2)' applications of the\n\t/// corresponding predicate.\n\t///\n\ttemplate \n\tinline ForwardIterator1\n\tfind_first_not_of(ForwardIterator1 first1, ForwardIterator1 last1,\n\t\t\t\t\t ForwardIterator2 first2, ForwardIterator2 last2,\n\t\t\t\t\t BinaryPredicate predicate)\n\t{\n\t\ttypedef typename eastl::iterator_traits::value_type value_type;\n\n\t\tfor(; first1 != last1; ++first1)\n\t\t{\n\t\t\tif(eastl::find_if(first2, last2, [&predicate, first1](value_type& rhs) { return predicate(*first1, rhs); }) == last2)\n\t\t\t\tbreak;\n\t\t}\n\n\t\treturn first1;\n\t}\n\n\n\ttemplate \n\tinline BidirectionalIterator1\n\tfind_last_of(BidirectionalIterator1 first1, BidirectionalIterator1 last1,\n\t\t\t\t ForwardIterator2 first2, ForwardIterator2 last2)\n\t{\n\t\tif((first1 != last1) && (first2 != last2))\n\t\t{\n\t\t\tBidirectionalIterator1 it1(last1);\n\n\t\t\twhile((--it1 != first1) && (eastl::find(first2, last2, *it1) == last2))\n\t\t\t\t; // Do nothing\n\n\t\t\tif((it1 != first1) || (eastl::find(first2, last2, *it1) != last2))\n\t\t\t\treturn it1;\n\t\t}\n\n\t\treturn last1;\n\t}\n\n\n\ttemplate \n\tBidirectionalIterator1\n\tfind_last_of(BidirectionalIterator1 first1, BidirectionalIterator1 last1,\n\t\t\t\t ForwardIterator2 first2, ForwardIterator2 last2,\n\t\t\t\t BinaryPredicate predicate)\n\t{\n\t\ttypedef typename eastl::iterator_traits::value_type value_type;\n\n\t\tif((first1 != last1) && (first2 != last2))\n\t\t{\n\t\t\tBidirectionalIterator1 it1(last1);\n\n\t\t\twhile((--it1 != first1) && (eastl::find_if(first2, last2, [&predicate, it1](value_type& rhs) { return predicate(*it1, rhs); }) == last2))\n\t\t\t\t; // Do nothing\n\n\t\t\tif((it1 != first1) || (eastl::find_if(first2, last2, [&predicate, it1](value_type& rhs) { return predicate(*it1, rhs); }) != last2))\n\t\t\t\treturn it1;\n\t\t}\n\n\t\treturn last1;\n\t}\n\n\n\ttemplate \n\tinline BidirectionalIterator1\n\tfind_last_not_of(BidirectionalIterator1 first1, BidirectionalIterator1 last1,\n\t\t\t\t\t ForwardIterator2 first2, ForwardIterator2 last2)\n\t{\n\t\tif((first1 != last1) && (first2 != last2))\n\t\t{\n\t\t\tBidirectionalIterator1 it1(last1);\n\n\t\t\twhile((--it1 != first1) && (eastl::find(first2, last2, *it1) != last2))\n\t\t\t\t; // Do nothing\n\n\t\t\tif((it1 != first1) || (eastl::find( first2, last2, *it1) == last2))\n\t\t\t\treturn it1;\n\t\t}\n\n\t\treturn last1;\n\t}\n\n\n\ttemplate \n\tinline BidirectionalIterator1\n\tfind_last_not_of(BidirectionalIterator1 first1, BidirectionalIterator1 last1,\n\t\t\t\t\t ForwardIterator2 first2, ForwardIterator2 last2,\n\t\t\t\t\t BinaryPredicate predicate)\n\t{\n\t\ttypedef typename eastl::iterator_traits::value_type value_type;\n\n\t\tif((first1 != last1) && (first2 != last2))\n\t\t{\n\t\t\tBidirectionalIterator1 it1(last1);\n\n\t\t\twhile((--it1 != first1) && (eastl::find_if(first2, last2, [&predicate, it1](value_type& rhs) { return predicate(*it1, rhs); }) != last2))\n\t\t\t\t; // Do nothing\n\n\t\t\tif((it1 != first1) || (eastl::find_if(first2, last2, [&predicate, it1](value_type& rhs) { return predicate(*it1, rhs); })) != last2)\n\t\t\t\treturn it1;\n\t\t}\n\n\t\treturn last1;\n\t}\n\n\n\n\n\t/// for_each\n\t///\n\t/// Calls the Function function for each value in the range [first, last).\n\t/// Function takes a single parameter: the current value.\n\t///\n\t/// Effects: Applies function to the result of dereferencing every iterator in\n\t/// the range [first, last), starting from first and proceeding to last 1.\n\t///\n\t/// Returns: function.\n\t///\n\t/// Complexity: Applies function exactly 'last - first' times.\n\t///\n\t/// Note: If function returns a result, the result is ignored.\n\t///\n\ttemplate \n\tinline Function\n\tfor_each(InputIterator first, InputIterator last, Function function)\n\t{\n\t\tfor(; first != last; ++first)\n\t\t\tfunction(*first);\n\t\treturn function;\n\t}\n\n\t/// for_each_n\n\t///\n\t/// Calls the Function function for each value in the range [first, first + n).\n\t/// Function takes a single parameter: the current value.\n\t///\n\t/// Effects: Applies function to the result of dereferencing every iterator in\n\t/// the range [first, first + n), starting from first and proceeding to last 1.\n\t///\n\t/// Returns: first + n.\n\t///\n\t/// Complexity: Applies function exactly 'first + n' times.\n\t///\n\t/// Note:\n\t//// * If function returns a result, the result is ignored.\n\t//// * If n < 0, behaviour is undefined.\n\t///\n\ttemplate \n\tEA_CPP14_CONSTEXPR inline InputIterator\n\tfor_each_n(InputIterator first, Size n, Function function)\n\t{\n\t\tfor (Size i = 0; i < n; ++first, i++)\n\t\t\tfunction(*first);\n\t\treturn first;\n\t}\n\n\n\t/// generate\n\t///\n\t/// Iterates the range of [first, last) and assigns to each element the\n\t/// result of the function generator. Generator is a function which takes\n\t/// no arguments.\n\t///\n\t/// Complexity: Exactly 'last - first' invocations of generator and assignments.\n\t///\n\ttemplate \n\tinline void\n\tgenerate(ForwardIterator first, ForwardIterator last, Generator generator)\n\t{\n\t\tfor(; first != last; ++first) // We cannot call generate_n(first, last-first, generator)\n\t\t\t*first = generator(); // because the 'last-first' might not be supported by the\n\t} // given iterator.\n\n\n\t/// generate_n\n\t///\n\t/// Iterates an interator n times and assigns the result of generator\n\t/// to each succeeding element. Generator is a function which takes\n\t/// no arguments.\n\t///\n\t/// Complexity: Exactly n invocations of generator and assignments.\n\t///\n\ttemplate \n\tinline OutputIterator\n\tgenerate_n(OutputIterator first, Size n, Generator generator)\n\t{\n\t\tfor(; n > 0; --n, ++first)\n\t\t\t*first = generator();\n\t\treturn first;\n\t}\n\n\n\t/// transform\n\t///\n\t/// Iterates the input range of [first, last) and the output iterator result\n\t/// and assigns the result of unaryOperation(input) to result.\n\t///\n\t/// Effects: Assigns through every iterator i in the range [result, result + (last1 - first1))\n\t/// a new corresponding value equal to unaryOperation(*(first1 + (i - result)).\n\t///\n\t/// Requires: op shall not have any side effects.\n\t///\n\t/// Returns: result + (last1 - first1). That is, returns the end of the output range.\n\t///\n\t/// Complexity: Exactly 'last1 - first1' applications of unaryOperation.\n\t///\n\t/// Note: result may be equal to first.\n\t///\n\ttemplate \n\tinline OutputIterator\n\ttransform(InputIterator first, InputIterator last, OutputIterator result, UnaryOperation unaryOperation)\n\t{\n\t\tfor(; first != last; ++first, ++result)\n\t\t\t*result = unaryOperation(*first);\n\t\treturn result;\n\t}\n\n\n\t/// transform\n\t///\n\t/// Iterates the input range of [first, last) and the output iterator result\n\t/// and assigns the result of binaryOperation(input1, input2) to result.\n\t///\n\t/// Effects: Assigns through every iterator i in the range [result, result + (last1 - first1))\n\t/// a new corresponding value equal to binaryOperation(*(first1 + (i - result), *(first2 + (i - result))).\n\t///\n\t/// Requires: binaryOperation shall not have any side effects.\n\t///\n\t/// Returns: result + (last1 - first1). That is, returns the end of the output range.\n\t///\n\t/// Complexity: Exactly 'last1 - first1' applications of binaryOperation.\n\t///\n\t/// Note: result may be equal to first1 or first2.\n\t///\n\ttemplate \n\tinline OutputIterator\n\ttransform(InputIterator1 first1, InputIterator1 last1, InputIterator2 first2, OutputIterator result, BinaryOperation binaryOperation)\n\t{\n\t\tfor(; first1 != last1; ++first1, ++first2, ++result)\n\t\t\t*result = binaryOperation(*first1, *first2);\n\t\treturn result;\n\t}\n\n\n\t/// equal\n\t///\n\t/// Returns: true if for every iterator i in the range [first1, last1) the\n\t/// following corresponding conditions hold: predicate(*i, *(first2 + (i - first1))) != false.\n\t/// Otherwise, returns false.\n\t///\n\t/// Complexity: At most last1 first1 applications of the corresponding predicate.\n\t///\n\t/// To consider: Make specializations of this for scalar types and random access\n\t/// iterators that uses memcmp or some trick memory comparison function.\n\t/// We should verify that such a thing results in an improvement.\n\t///\n\ttemplate \n\tEA_CPP14_CONSTEXPR inline bool equal(InputIterator1 first1, InputIterator1 last1, InputIterator2 first2)\n\t{\n\t\tfor(; first1 != last1; ++first1, ++first2)\n\t\t{\n\t\t\tif(!(*first1 == *first2)) // Note that we always express value comparisons in terms of < or ==.\n\t\t\t\treturn false;\n\t\t}\n\t\treturn true;\n\t}\n\n\t/* Enable the following if there was shown to be some benefit. A glance and Microsoft VC++ memcmp\n\t\tshows that it is not optimized in any way, much less one that would benefit us here.\n\n\tinline bool equal(const bool* first1, const bool* last1, const bool* first2)\n\t\t{ return (memcmp(first1, first2, (size_t)((uintptr_t)last1 - (uintptr_t)first1)) == 0); }\n\n\tinline bool equal(const char* first1, const char* last1, const char* first2)\n\t\t{ return (memcmp(first1, first2, (size_t)((uintptr_t)last1 - (uintptr_t)first1)) == 0); }\n\n\tinline bool equal(const unsigned char* first1, const unsigned char* last1, const unsigned char* first2)\n\t\t{ return (memcmp(first1, first2, (size_t)((uintptr_t)last1 - (uintptr_t)first1)) == 0); }\n\n\tinline bool equal(const signed char* first1, const signed char* last1, const signed char* first2)\n\t\t{ return (memcmp(first1, first2, (size_t)((uintptr_t)last1 - (uintptr_t)first1)) == 0); }\n\n\t#ifndef EA_WCHAR_T_NON_NATIVE\n\t\tinline bool equal(const wchar_t* first1, const wchar_t* last1, const wchar_t* first2)\n\t\t\t{ return (memcmp(first1, first2, (size_t)((uintptr_t)last1 - (uintptr_t)first1)) == 0); }\n\t#endif\n\n\tinline bool equal(const int16_t* first1, const int16_t* last1, const int16_t* first2)\n\t\t{ return (memcmp(first1, first2, (size_t)((uintptr_t)last1 - (uintptr_t)first1)) == 0); }\n\n\tinline bool equal(const uint16_t* first1, const uint16_t* last1, const uint16_t* first2)\n\t\t{ return (memcmp(first1, first2, (size_t)((uintptr_t)last1 - (uintptr_t)first1)) == 0); }\n\n\tinline bool equal(const int32_t* first1, const int32_t* last1, const int32_t* first2)\n\t\t{ return (memcmp(first1, first2, (size_t)((uintptr_t)last1 - (uintptr_t)first1)) == 0); }\n\n\tinline bool equal(const uint32_t* first1, const uint32_t* last1, const uint32_t* first2)\n\t\t{ return (memcmp(first1, first2, (size_t)((uintptr_t)last1 - (uintptr_t)first1)) == 0); }\n\n\tinline bool equal(const int64_t* first1, const int64_t* last1, const int64_t* first2)\n\t\t{ return (memcmp(first1, first2, (size_t)((uintptr_t)last1 - (uintptr_t)first1)) == 0); }\n\n\tinline bool equal(const uint64_t* first1, const uint64_t* last1, const uint64_t* first2)\n\t\t{ return (memcmp(first1, first2, (size_t)((uintptr_t)last1 - (uintptr_t)first1)) == 0); }\n\t*/\n\n\n\n\t/// equal\n\t///\n\t/// Returns: true if for every iterator i in the range [first1, last1) the\n\t/// following corresponding conditions hold: pred(*i, *(first2 + (i first1))) != false.\n\t/// Otherwise, returns false.\n\t///\n\t/// Complexity: At most last1 first1 applications of the corresponding predicate.\n\t///\n\ttemplate \n\tinline bool\n\tequal(InputIterator1 first1, InputIterator1 last1, InputIterator2 first2, BinaryPredicate predicate)\n\t{\n\t\tfor(; first1 != last1; ++first1, ++first2)\n\t\t{\n\t\t\tif(!predicate(*first1, *first2))\n\t\t\t\treturn false;\n\t\t}\n\t\treturn true;\n\t}\n\n\n\n\t/// identical\n\t///\n\t/// Returns true if the two input ranges are equivalent.\n\t/// There is a subtle difference between this algorithm and\n\t/// the 'equal' algorithm. The equal algorithm assumes the\n\t/// two ranges are of equal length. This algorithm efficiently\n\t/// compares two ranges for both length equality and for\n\t/// element equality. There is no other standard algorithm\n\t/// that can do this.\n\t///\n\t/// Returns: true if the sequence of elements defined by the range\n\t/// [first1, last1) is of the same length as the sequence of\n\t/// elements defined by the range of [first2, last2) and if\n\t/// the elements in these ranges are equal as per the\n\t/// equal algorithm.\n\t///\n\t/// Complexity: At most 'min((last1 - first1), (last2 - first2))' applications\n\t/// of the corresponding comparison.\n\t///\n\ttemplate \n\tbool identical(InputIterator1 first1, InputIterator1 last1,\n\t\t\t\t InputIterator2 first2, InputIterator2 last2)\n\t{\n\t\twhile((first1 != last1) && (first2 != last2) && (*first1 == *first2))\n\t\t{\n\t\t\t++first1;\n\t\t\t++first2;\n\t\t}\n\t\treturn (first1 == last1) && (first2 == last2);\n\t}\n\n\n\t/// identical\n\t///\n\ttemplate \n\tbool identical(InputIterator1 first1, InputIterator1 last1,\n\t\t\t\t InputIterator2 first2, InputIterator2 last2, BinaryPredicate predicate)\n\t{\n\t\twhile((first1 != last1) && (first2 != last2) && predicate(*first1, *first2))\n\t\t{\n\t\t\t++first1;\n\t\t\t++first2;\n\t\t}\n\t\treturn (first1 == last1) && (first2 == last2);\n\t}\n\n\n\n\t/// lexicographical_compare\n\t///\n\t/// Returns: true if the sequence of elements defined by the range\n\t/// [first1, last1) is lexicographically less than the sequence of\n\t/// elements defined by the range [first2, last2). Returns false otherwise.\n\t///\n\t/// Complexity: At most 'min((last1 - first1), (last2 - first2))' applications\n\t/// of the corresponding comparison.\n\t///\n\t/// Note: If two sequences have the same number of elements and their\n\t/// corresponding elements are equivalent, then neither sequence is\n\t/// lexicographically less than the other. If one sequence is a prefix\n\t/// of the other, then the shorter sequence is lexicographically less\n\t/// than the longer sequence. Otherwise, the lexicographical comparison\n\t/// of the sequences yields the same result as the comparison of the first\n\t/// corresponding pair of elements that are not equivalent.\n\t///\n\ttemplate \n\tinline bool\n\tlexicographical_compare(InputIterator1 first1, InputIterator1 last1, InputIterator2 first2, InputIterator2 last2)\n\t{\n\t\tfor(; (first1 != last1) && (first2 != last2); ++first1, ++first2)\n\t\t{\n\t\t\tif(*first1 < *first2)\n\t\t\t\treturn true;\n\t\t\tif(*first2 < *first1)\n\t\t\t\treturn false;\n\t\t}\n\t\treturn (first1 == last1) && (first2 != last2);\n\t}\n\n\tinline bool // Specialization for const char*.\n\tlexicographical_compare(const char* first1, const char* last1, const char* first2, const char* last2)\n\t{\n\t\tconst ptrdiff_t n1(last1 - first1), n2(last2 - first2);\n\t\tconst size_t n = (size_t)eastl::min_alt(n1, n2);\n\t\tif (n == 0) // don't call memcmp with n == 0\n\t\t\treturn false;\n\t\tconst int result = memcmp(first1, first2, n);\n\t\treturn result ? (result < 0) : (n1 < n2);\n\t}\n\n\tinline bool // Specialization for char*.\n\tlexicographical_compare(char* first1, char* last1, char* first2, char* last2)\n\t{\n\t\tconst ptrdiff_t n1(last1 - first1), n2(last2 - first2);\n\t\tconst size_t n = (size_t)eastl::min_alt(n1, n2);\n\t\tif (n == 0) // don't call memcmp with n == 0\n\t\t\treturn false;\n\t\tconst int result = memcmp(first1, first2, n);\n\t\treturn result ? (result < 0) : (n1 < n2);\n\t}\n\n\tinline bool // Specialization for const unsigned char*.\n\tlexicographical_compare(const unsigned char* first1, const unsigned char* last1, const unsigned char* first2, const unsigned char* last2)\n\t{\n\t\tconst ptrdiff_t n1(last1 - first1), n2(last2 - first2);\n\t\tconst size_t n = (size_t)eastl::min_alt(n1, n2);\n\t\tif (n == 0) // don't call memcmp with n == 0\n\t\t\treturn false;\n\t\tconst int result = memcmp(first1, first2, n);\n\t\treturn result ? (result < 0) : (n1 < n2);\n\t}\n\n\tinline bool // Specialization for unsigned char*.\n\tlexicographical_compare(unsigned char* first1, unsigned char* last1, unsigned char* first2, unsigned char* last2)\n\t{\n\t\tconst ptrdiff_t n1(last1 - first1), n2(last2 - first2);\n\t\tconst size_t n = (size_t)eastl::min_alt(n1, n2);\n\t\tif (n == 0) // don't call memcmp with n == 0\n\t\t\treturn false;\n\t\tconst int result = memcmp(first1, first2, n);\n\t\treturn result ? (result < 0) : (n1 < n2);\n\t}\n\n\tinline bool // Specialization for const signed char*.\n\tlexicographical_compare(const signed char* first1, const signed char* last1, const signed char* first2, const signed char* last2)\n\t{\n\t\tconst ptrdiff_t n1(last1 - first1), n2(last2 - first2);\n\t\tconst size_t n = (size_t)eastl::min_alt(n1, n2);\n\t\tif (n == 0) // don't call memcmp with n == 0\n\t\t\treturn false;\n\t\tconst int result = memcmp(first1, first2, n);\n\t\treturn result ? (result < 0) : (n1 < n2);\n\t}\n\n\tinline bool // Specialization for signed char*.\n\tlexicographical_compare(signed char* first1, signed char* last1, signed char* first2, signed char* last2)\n\t{\n\t\tconst ptrdiff_t n1(last1 - first1), n2(last2 - first2);\n\t\tconst size_t n = (size_t)eastl::min_alt(n1, n2);\n\t\tif (n == 0) // don't call memcmp with n == 0\n\t\t\treturn false;\n\t\tconst int result = memcmp(first1, first2, n);\n\t\treturn result ? (result < 0) : (n1 < n2);\n\t}\n\n\t#if defined(_MSC_VER) // If using the VC++ compiler (and thus bool is known to be a single byte)...\n\t\t//Not sure if this is a good idea.\n\t\t//inline bool // Specialization for const bool*.\n\t\t//lexicographical_compare(const bool* first1, const bool* last1, const bool* first2, const bool* last2)\n\t\t//{\n\t\t// const ptrdiff_t n1(last1 - first1), n2(last2 - first2);\n\t\t// const int result = memcmp(first1, first2, (size_t)eastl::min_alt(n1, n2));\n\t\t// return result ? (result < 0) : (n1 < n2);\n\t\t//}\n\t\t//\n\t\t//inline bool // Specialization for bool*.\n\t\t//lexicographical_compare(bool* first1, bool* last1, bool* first2, bool* last2)\n\t\t//{\n\t\t// const ptrdiff_t n1(last1 - first1), n2(last2 - first2);\n\t\t// const int result = memcmp(first1, first2, (size_t)eastl::min_alt(n1, n2));\n\t\t// return result ? (result < 0) : (n1 < n2);\n\t\t//}\n\t#endif\n\n\n\n\t/// lexicographical_compare\n\t///\n\t/// Returns: true if the sequence of elements defined by the range\n\t/// [first1, last1) is lexicographically less than the sequence of\n\t/// elements defined by the range [first2, last2). Returns false otherwise.\n\t///\n\t/// Complexity: At most 'min((last1 -first1), (last2 - first2))' applications\n\t/// of the corresponding comparison.\n\t///\n\t/// Note: If two sequences have the same number of elements and their\n\t/// corresponding elements are equivalent, then neither sequence is\n\t/// lexicographically less than the other. If one sequence is a prefix\n\t/// of the other, then the shorter sequence is lexicographically less\n\t/// than the longer sequence. Otherwise, the lexicographical comparison\n\t/// of the sequences yields the same result as the comparison of the first\n\t/// corresponding pair of elements that are not equivalent.\n\t///\n\t/// Note: False is always returned if range 1 is exhausted before range 2.\n\t/// The result of this is that you can't do a successful reverse compare\n\t/// (e.g. use greater<> as the comparison instead of less<>) unless the\n\t/// two sequences are of identical length. What you want to do is reverse\n\t/// the order of the arguments in order to get the desired effect.\n\t///\n\ttemplate \n\tinline bool\n\tlexicographical_compare(InputIterator1 first1, InputIterator1 last1,\n\t\t\t\t\t\t\tInputIterator2 first2, InputIterator2 last2, Compare compare)\n\t{\n\t\tfor(; (first1 != last1) && (first2 != last2); ++first1, ++first2)\n\t\t{\n\t\t\tif(compare(*first1, *first2))\n\t\t\t\treturn true;\n\t\t\tif(compare(*first2, *first1))\n\t\t\t\treturn false;\n\t\t}\n\t\treturn (first1 == last1) && (first2 != last2);\n\t}\n\n\n#if defined(EA_COMPILER_HAS_THREE_WAY_COMPARISON)\n\n\t/// lexicographical_compare_three_way\n\t///\n\t/// Returns: The comparison category ordering between both ranges. For the first non-equivalent pair in the ranges,\n\t/// the comparison will be returned. Else if the first range is a subset (superset) of the second range, then the\n\t/// less (greater) ordering will be returned.\n\t///\n\t/// Complexity: At most N iterations, where N = min(last1-first1, last2-first2) of the applications\n\t/// of the corresponding comparison.\n\t///\n\t/// Note: If two sequences have the same number of elements and their\n\t/// corresponding elements are equivalent, then neither sequence is\n\t/// lexicographically less than the other. If one sequence is a prefix\n\t/// of the other, then the shorter sequence is lexicographically less\n\t/// than the longer sequence. Otherwise, the lexicographical comparison\n\t/// of the sequences yields the same result as the comparison of the first\n\t/// corresponding pair of elements that are not equivalent.\n\t///\n\ttemplate \n\tconstexpr auto lexicographical_compare_three_way(InputIterator1 first1, InputIterator1 last1,\n\t InputIterator2 first2, InputIterator2 last2,\n\t Compare compare) -> decltype(compare(*first1, *first2))\n\t{\n\t\tfor (; (first1 != last1) && (first2 != last2); ++first1, ++first2)\n\t\t{\n\t\t\tif (auto c = compare(*first1, *first2); c != 0)\n\t\t\t\treturn c;\n\t\t}\n\n\t\treturn (first1 != last1) ? std::strong_ordering::greater :\n\t\t (first2 != last2) ? std::strong_ordering::less :\n\t\t\t\tstd::strong_ordering::equal;\n\t}\n#endif\n\n\t/// mismatch\n\t///\n\t/// Finds the first position where the two ranges [first1, last1) and\n\t/// [first2, first2 + (last1 - first1)) differ. The two versions of\n\t/// mismatch use different tests for whether elements differ.\n\t///\n\t/// Returns: A pair of iterators i and j such that j == first2 + (i - first1)\n\t/// and i is the first iterator in the range [first1, last1) for which the\n\t/// following corresponding condition holds: !(*i == *(first2 + (i - first1))).\n\t/// Returns the pair last1 and first2 + (last1 - first1) if such an iterator\n\t/// i is not found.\n\t///\n\t/// Complexity: At most last1 first1 applications of the corresponding predicate.\n\t///\n\ttemplate \n\tinline eastl::pair\n\tmismatch(InputIterator1 first1, InputIterator1 last1,\n\t\t\t InputIterator2 first2) // , InputIterator2 last2)\n\t{\n\t\twhile((first1 != last1) && (*first1 == *first2)) // && (first2 != last2) <- C++ standard mismatch function doesn't check first2/last2.\n\t\t{\n\t\t\t++first1;\n\t\t\t++first2;\n\t\t}\n\n\t\treturn eastl::pair(first1, first2);\n\t}\n\n\n\t/// mismatch\n\t///\n\t/// Finds the first position where the two ranges [first1, last1) and\n\t/// [first2, first2 + (last1 - first1)) differ. The two versions of\n\t/// mismatch use different tests for whether elements differ.\n\t///\n\t/// Returns: A pair of iterators i and j such that j == first2 + (i - first1)\n\t/// and i is the first iterator in the range [first1, last1) for which the\n\t/// following corresponding condition holds: pred(*i, *(first2 + (i - first1))) == false.\n\t/// Returns the pair last1 and first2 + (last1 - first1) if such an iterator\n\t/// i is not found.\n\t///\n\t/// Complexity: At most last1 first1 applications of the corresponding predicate.\n\t///\n\ttemplate \n\tinline eastl::pair\n\tmismatch(InputIterator1 first1, InputIterator1 last1,\n\t\t\t InputIterator2 first2, // InputIterator2 last2,\n\t\t\t BinaryPredicate predicate)\n\t{\n\t\twhile((first1 != last1) && predicate(*first1, *first2)) // && (first2 != last2) <- C++ standard mismatch function doesn't check first2/last2.\n\t\t{\n\t\t\t++first1;\n\t\t\t++first2;\n\t\t}\n\n\t\treturn eastl::pair(first1, first2);\n\t}\n\n\n\t/// lower_bound\n\t///\n\t/// Finds the position of the first element in a sorted range that has a value\n\t/// greater than or equivalent to a specified value.\n\t///\n\t/// Effects: Finds the first position into which value can be inserted without\n\t/// violating the ordering.\n\t///\n\t/// Returns: The furthermost iterator i in the range [first, last) such that\n\t/// for any iterator j in the range [first, i) the following corresponding\n\t/// condition holds: *j < value.\n\t///\n\t/// Complexity: At most 'log(last - first) + 1' comparisons.\n\t///\n\t/// Optimizations: We have no need to specialize this implementation for random\n\t/// access iterators (e.g. contiguous array), as the code below will already\n\t/// take advantage of them.\n\t///\n\ttemplate \n\tForwardIterator\n\tlower_bound(ForwardIterator first, ForwardIterator last, const T& value)\n\t{\n\t\ttypedef typename eastl::iterator_traits::difference_type DifferenceType;\n\n\t\tDifferenceType d = eastl::distance(first, last); // This will be efficient for a random access iterator such as an array.\n\n\t\twhile(d > 0)\n\t\t{\n\t\t\tForwardIterator i = first;\n\t\t\tDifferenceType d2 = d >> 1; // We use '>>1' here instead of '/2' because MSVC++ for some reason generates significantly worse code for '/2'. Go figure.\n\n\t\t\teastl::advance(i, d2); // This will be efficient for a random access iterator such as an array.\n\n\t\t\tif(*i < value)\n\t\t\t{\n\t\t\t\t// Disabled because std::lower_bound doesn't specify (23.3.3.3, p3) this can be done: EASTL_VALIDATE_COMPARE(!(value < *i)); // Validate that the compare function is sane.\n\t\t\t\tfirst = ++i;\n\t\t\t\td -= d2 + 1;\n\t\t\t}\n\t\t\telse\n\t\t\t\td = d2;\n\t\t}\n\t\treturn first;\n\t}\n\n\n\t/// lower_bound\n\t///\n\t/// Finds the position of the first element in a sorted range that has a value\n\t/// greater than or equivalent to a specified value. The input Compare function\n\t/// takes two arguments and returns true if the first argument is less than\n\t/// the second argument.\n\t///\n\t/// Effects: Finds the first position into which value can be inserted without\n\t/// violating the ordering.\n\t///\n\t/// Returns: The furthermost iterator i in the range [first, last) such that\n\t/// for any iterator j in the range [first, i) the following corresponding\n\t/// condition holds: compare(*j, value) != false.\n\t///\n\t/// Complexity: At most 'log(last - first) + 1' comparisons.\n\t///\n\t/// Optimizations: We have no need to specialize this implementation for random\n\t/// access iterators (e.g. contiguous array), as the code below will already\n\t/// take advantage of them.\n\t///\n\ttemplate \n\tForwardIterator\n\tlower_bound(ForwardIterator first, ForwardIterator last, const T& value, Compare compare)\n\t{\n\t\ttypedef typename eastl::iterator_traits::difference_type DifferenceType;\n\n\t\tDifferenceType d = eastl::distance(first, last); // This will be efficient for a random access iterator such as an array.\n\n\t\twhile(d > 0)\n\t\t{\n\t\t\tForwardIterator i = first;\n\t\t\tDifferenceType d2 = d >> 1; // We use '>>1' here instead of '/2' because MSVC++ for some reason generates significantly worse code for '/2'. Go figure.\n\n\t\t\teastl::advance(i, d2); // This will be efficient for a random access iterator such as an array.\n\n\t\t\tif(compare(*i, value))\n\t\t\t{\n\t\t\t\t// Disabled because std::lower_bound doesn't specify (23.3.3.1, p3) this can be done: EASTL_VALIDATE_COMPARE(!compare(value, *i)); // Validate that the compare function is sane.\n\t\t\t\tfirst = ++i;\n\t\t\t\td -= d2 + 1;\n\t\t\t}\n\t\t\telse\n\t\t\t\td = d2;\n\t\t}\n\t\treturn first;\n\t}\n\n\n\n\t/// upper_bound\n\t///\n\t/// Finds the position of the first element in a sorted range that has a\n\t/// value that is greater than a specified value.\n\t///\n\t/// Effects: Finds the furthermost position into which value can be inserted\n\t/// without violating the ordering.\n\t///\n\t/// Returns: The furthermost iterator i in the range [first, last) such that\n\t/// for any iterator j in the range [first, i) the following corresponding\n\t/// condition holds: !(value < *j).\n\t///\n\t/// Complexity: At most 'log(last - first) + 1' comparisons.\n\t///\n\ttemplate \n\tForwardIterator\n\tupper_bound(ForwardIterator first, ForwardIterator last, const T& value)\n\t{\n\t\ttypedef typename eastl::iterator_traits::difference_type DifferenceType;\n\n\t\tDifferenceType len = eastl::distance(first, last);\n\n\t\twhile(len > 0)\n\t\t{\n\t\t\tForwardIterator i = first;\n\t\t\tDifferenceType len2 = len >> 1; // We use '>>1' here instead of '/2' because MSVC++ for some reason generates significantly worse code for '/2'. Go figure.\n\n\t\t\teastl::advance(i, len2);\n\n\t\t\tif(!(value < *i)) // Note that we always express value comparisons in terms of < or ==.\n\t\t\t{\n\t\t\t\tfirst = ++i;\n\t\t\t\tlen -= len2 + 1;\n\t\t\t}\n\t\t\telse\n\t\t\t{\n\t\t\t\t// Disabled because std::upper_bound doesn't specify (23.3.3.2, p3) this can be done: EASTL_VALIDATE_COMPARE(!(*i < value)); // Validate that the compare function is sane.\n\t\t\t\tlen = len2;\n\t\t\t}\n\t\t}\n\t\treturn first;\n\t}\n\n\n\t/// upper_bound\n\t///\n\t/// Finds the position of the first element in a sorted range that has a\n\t/// value that is greater than a specified value. The input Compare function\n\t/// takes two arguments and returns true if the first argument is less than\n\t/// the second argument.\n\t///\n\t/// Effects: Finds the furthermost position into which value can be inserted\n\t/// without violating the ordering.\n\t///\n\t/// Returns: The furthermost iterator i in the range [first, last) such that\n\t/// for any iterator j in the range [first, i) the following corresponding\n\t/// condition holds: compare(value, *j) == false.\n\t///\n\t/// Complexity: At most 'log(last - first) + 1' comparisons.\n\t///\n\ttemplate \n\tForwardIterator\n\tupper_bound(ForwardIterator first, ForwardIterator last, const T& value, Compare compare)\n\t{\n\t\ttypedef typename eastl::iterator_traits::difference_type DifferenceType;\n\n\t\tDifferenceType len = eastl::distance(first, last);\n\n\t\twhile(len > 0)\n\t\t{\n\t\t\tForwardIterator i = first;\n\t\t\tDifferenceType len2 = len >> 1; // We use '>>1' here instead of '/2' because MSVC++ for some reason generates significantly worse code for '/2'. Go figure.\n\n\t\t\teastl::advance(i, len2);\n\n\t\t\tif(!compare(value, *i))\n\t\t\t{\n\t\t\t\tfirst = ++i;\n\t\t\t\tlen -= len2 + 1;\n\t\t\t}\n\t\t\telse\n\t\t\t{\n\t\t\t\t// Disabled because std::upper_bound doesn't specify (23.3.3.2, p3) this can be done: EASTL_VALIDATE_COMPARE(!compare(*i, value)); // Validate that the compare function is sane.\n\t\t\t\tlen = len2;\n\t\t\t}\n\t\t}\n\t\treturn first;\n\t}\n\n\n\t/// equal_range\n\t///\n\t/// Effects: Finds the largest subrange [i, j) such that the value can be inserted\n\t/// at any iterator k in it without violating the ordering. k satisfies the\n\t/// corresponding conditions: !(*k < value) && !(value < *k).\n\t///\n\t/// Complexity: At most '2 * log(last - first) + 1' comparisons.\n\t///\n\ttemplate \n\tpair\n\tequal_range(ForwardIterator first, ForwardIterator last, const T& value)\n\t{\n\t\treturn equal_range(first, last, value, eastl::less<>{});\n\t}\n\n\n\t/// equal_range\n\t///\n\t/// Effects: Finds the largest subrange [i, j) such that the value can be inserted\n\t/// at any iterator k in it without violating the ordering. k satisfies the\n\t/// corresponding conditions: compare(*k, value) == false && compare(value, *k) == false.\n\t///\n\t/// Complexity: At most '2 * log(last - first) + 1' comparisons.\n\t///\n\ttemplate \n\tpair\n\tequal_range(ForwardIterator first, ForwardIterator last, const T& value, Compare compare)\n\t{\n\t\ttypedef pair ResultType;\n\t\ttypedef typename eastl::iterator_traits::difference_type DifferenceType;\n\n\t\tDifferenceType d = eastl::distance(first, last);\n\n\t\twhile(d > 0)\n\t\t{\n\t\t\tForwardIterator i(first);\n\t\t\tDifferenceType d2 = d >> 1; // We use '>>1' here instead of '/2' because MSVC++ for some reason generates significantly worse code for '/2'. Go figure.\n\n\t\t\teastl::advance(i, d2);\n\n\t\t\tif(compare(*i, value))\n\t\t\t{\n\t\t\t\tEASTL_VALIDATE_COMPARE(!compare(value, *i)); // Validate that the compare function is sane.\n\t\t\t\tfirst = ++i;\n\t\t\t\td -= d2 + 1;\n\t\t\t}\n\t\t\telse if(compare(value, *i))\n\t\t\t{\n\t\t\t\tEASTL_VALIDATE_COMPARE(!compare(*i, value)); // Validate that the compare function is sane.\n\t\t\t\td = d2;\n\t\t\t\tlast = i;\n\t\t\t}\n\t\t\telse\n\t\t\t{\n\t\t\t\tForwardIterator j(i);\n\n\t\t\t\treturn ResultType(eastl::lower_bound(first, i, value, compare),\n\t\t\t\t\t\t\t\t eastl::upper_bound(++j, last, value, compare));\n\t\t\t}\n\t\t}\n\t\treturn ResultType(first, first);\n\t}\n\n\n\t/// replace\n\t///\n\t/// Effects: Substitutes elements referred by the iterator i in the range [first, last)\n\t/// with new_value, when the following corresponding conditions hold: *i == old_value.\n\t///\n\t/// Complexity: Exactly 'last - first' applications of the corresponding predicate.\n\t///\n\t/// Note: The predicate version of replace is replace_if and not another variation of replace.\n\t/// This is because both versions would have the same parameter count and there could be ambiguity.\n\t///\n\ttemplate \n\tinline void\n\treplace(ForwardIterator first, ForwardIterator last, const T& old_value, const T& new_value)\n\t{\n\t\tfor(; first != last; ++first)\n\t\t{\n\t\t\tif(*first == old_value)\n\t\t\t\t*first = new_value;\n\t\t}\n\t}\n\n\n\t/// replace_if\n\t///\n\t/// Effects: Substitutes elements referred by the iterator i in the range [first, last)\n\t/// with new_value, when the following corresponding conditions hold: predicate(*i) != false.\n\t///\n\t/// Complexity: Exactly 'last - first' applications of the corresponding predicate.\n\t///\n\t/// Note: The predicate version of replace_if is replace and not another variation of replace_if.\n\t/// This is because both versions would have the same parameter count and there could be ambiguity.\n\t///\n\ttemplate \n\tinline void\n\treplace_if(ForwardIterator first, ForwardIterator last, Predicate predicate, const T& new_value)\n\t{\n\t\tfor(; first != last; ++first)\n\t\t{\n\t\t\tif(predicate(*first))\n\t\t\t\t*first = new_value;\n\t\t}\n\t}\n\n\t/// remove_copy\n\t///\n\t/// Effects: Copies all the elements referred to by the iterator i in the range\n\t/// [first, last) for which the following corresponding condition does not hold:\n\t/// *i == value.\n\t///\n\t/// Requires: The ranges [first, last) and [result, result + (last - first)) shall not overlap.\n\t///\n\t/// Returns: The end of the resulting range.\n\t///\n\t/// Complexity: Exactly 'last - first' applications of the corresponding predicate.\n\t///\n\ttemplate \n\tinline OutputIterator\n\tremove_copy(InputIterator first, InputIterator last, OutputIterator result, const T& value)\n\t{\n\t\tfor(; first != last; ++first)\n\t\t{\n\t\t\tif(!(*first == value)) // Note that we always express value comparisons in terms of < or ==.\n\t\t\t{\n\t\t\t\t*result = *first;\n\t\t\t\t++result;\n\t\t\t}\n\t\t}\n\t\treturn result;\n\t}\n\n\t/// remove_copy_if\n\t///\n\t/// Effects: Copies all the elements referred to by the iterator i in the range\n\t/// [first, last) for which the following corresponding condition does not hold:\n\t/// predicate(*i) != false.\n\t///\n\t/// Requires: The ranges [first, last) and [result, result + (last - first)) shall not overlap.\n\t///\n\t/// Returns: The end of the resulting range.\n\t///\n\t/// Complexity: Exactly 'last - first' applications of the corresponding predicate.\n\t///\n\ttemplate \n\tinline OutputIterator\n\tremove_copy_if(InputIterator first, InputIterator last, OutputIterator result, Predicate predicate)\n\t{\n\t\tfor(; first != last; ++first)\n\t\t{\n\t\t\tif(!predicate(*first))\n\t\t\t{\n\t\t\t\t*result = *first;\n\t\t\t\t++result;\n\t\t\t}\n\t\t}\n\t\treturn result;\n\t}\n\n\n\t/// remove\n\t///\n\t/// Effects: Eliminates all the elements referred to by iterator i in the\n\t/// range [first, last) for which the following corresponding condition\n\t/// holds: *i == value.\n\t///\n\t/// Returns: The end of the resulting range.\n\t///\n\t/// Complexity: Exactly 'last - first' applications of the corresponding predicate.\n\t///\n\t/// Note: The predicate version of remove is remove_if and not another variation of remove.\n\t/// This is because both versions would have the same parameter count and there could be ambiguity.\n\t///\n\t/// Note: Since this function moves the element to the back of the heap and\n\t/// doesn't actually remove it from the given container, the user must call\n\t/// the container erase function if the user wants to erase the element\n\t/// from the container.\n\t///\n\t/// Example usage:\n\t/// vector intArray;\n\t/// ...\n\t/// intArray.erase(remove(intArray.begin(), intArray.end(), 4), intArray.end()); // Erase all elements of value 4.\n\t///\n\ttemplate \n\tinline ForwardIterator\n\tremove(ForwardIterator first, ForwardIterator last, const T& value)\n\t{\n\t\tfirst = eastl::find(first, last, value);\n\t\tif(first != last)\n\t\t{\n\t\t\tfor (ForwardIterator i = first; ++i != last;)\n\t\t\t{\n\t\t\t\tif (!(*i == value))\n\t\t\t\t{\n\t\t\t\t\t*first++ = eastl::move(*i);\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t\treturn first;\n\t}\n\n\t/// remove_if\n\t///\n\t/// Effects: Eliminates all the elements referred to by iterator i in the\n\t/// range [first, last) for which the following corresponding condition\n\t/// holds: predicate(*i) != false.\n\t///\n\t/// Returns: The end of the resulting range.\n\t///\n\t/// Complexity: Exactly 'last - first' applications of the corresponding predicate.\n\t///\n\t/// Note: The predicate version of remove_if is remove and not another variation of remove_if.\n\t/// This is because both versions would have the same parameter count and there could be ambiguity.\n\t///\n\t/// Note: Since this function moves the element to the back of the heap and\n\t/// doesn't actually remove it from the given container, the user must call\n\t/// the container erase function if the user wants to erase the element\n\t/// from the container.\n\t///\n\t/// Example usage:\n\t/// vector intArray;\n\t/// ...\n\t/// intArray.erase(remove(intArray.begin(), intArray.end(), bind(less(), (int)3)), intArray.end()); // Erase all elements less than 3.\n\t///\n\ttemplate \n\tinline ForwardIterator\n\tremove_if(ForwardIterator first, ForwardIterator last, Predicate predicate)\n\t{\n\t\tfirst = eastl::find_if(first, last, predicate);\n\t\tif(first != last)\n\t\t{\n\t\t\tfor (ForwardIterator i = first; ++i != last;)\n\t\t\t{\n\t\t\t\tif (!predicate(*i))\n\t\t\t\t{\n\t\t\t\t\t*first++ = eastl::move(*i);\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t\treturn first;\n\t}\n\n\t/// apply_and_remove_if\n\t///\n\t/// Calls the Function function for all elements referred to my iterator i in the range\n\t/// [first, last) for which the following corresponding condition holds:\n\t/// predicate(*i) == true\n\t/// and then left shift moves potential non-matching elements over it.\n\t///\n\t/// Returns: a past-the-end iterator for the new end of the range.\n\t///\n\t/// Complexity: Exactly 'last - first' applications of the corresponding predicate + applies\n\t/// function once for every time the condition holds.\n\t///\n\t/// Note: Since removing is done by shifting (by means of copy move assignment) the elements\n\t/// in the range in such a way that the elements that are not to be removed appear in the\n\t/// beginning of the range doesn't actually remove it from the given container, the user must call\n\t/// the container erase function if the user wants to erase the element\n\t/// from the container. I.e. in the same they as for remove_if the excess elements\n\t/// are left in a valid but possibly moved from state.\n\t///\n\ttemplate \n\tinline ForwardIterator apply_and_remove_if(ForwardIterator first,\n\t ForwardIterator last,\n\t Function function,\n\t Predicate predicate)\n\t{\n\t\tfirst = eastl::find_if(first, last, predicate);\n\t\tif (first != last)\n\t\t{\n\t\t\tfunction(*first);\n\t\t\tfor (auto i = next(first); i != last; ++i)\n\t\t\t{\n\t\t\t\tif (predicate(*i))\n\t\t\t\t{\n\t\t\t\t\tfunction(*i);\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\t*first = eastl::move(*i);\n\t\t\t\t++first;\n\t\t\t}\n\t\t}\n\t\treturn first;\n\t}\n\n\n\t/// apply_and_remove\n\t///\n\t/// Calls the Function function for all elements referred to my iterator i in the range\n\t/// [first, last) for which the following corresponding condition holds:\n\t/// value == *i\n\t/// and then left shift moves potential non-matching elements over it.\n\t///\n\t/// Returns: a past-the-end iterator for the new end of the range.\n\t///\n\t/// Complexity: Exactly 'last - first' applications of the corresponding equality test\n\t/// + applies function once for every time the condition holds.\n\t///\n\t/// Note: Since removing is done by shifting (by means of copy move assignment) the elements\n\t/// in the range in such a way that the elements that are not to be removed appear in the\n\t/// beginning of the range doesn't actually remove it from the given container, the user must call\n\t/// the container erase function if the user wants to erase the element\n\t/// from the container. I.e. in the same they as for remove_if the excess elements\n\t/// are left in a valid but possibly moved from state.\n\t///\n\ttemplate \n\tinline ForwardIterator apply_and_remove(ForwardIterator first,\n\t ForwardIterator last,\n\t Function function,\n\t const T& value)\n\t{\n\t\tfirst = eastl::find(first, last, value);\n\t\tif (first != last)\n\t\t{\n\t\t\tfunction(*first);\n\t\t\tfor (auto i = next(first); i != last; ++i)\n\t\t\t{\n\t\t\t\tif (value == *i)\n\t\t\t\t{\n\t\t\t\t\tfunction(*i);\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\t*first = eastl::move(*i);\n\t\t\t\t++first;\n\t\t\t}\n\t\t}\n\t\treturn first;\n\t}\n\n\n\t/// replace_copy\n\t///\n\t/// Effects: Assigns to every iterator i in the range [result, result + (last - first))\n\t/// either new_value or *(first + (i - result)) depending on whether the following\n\t/// corresponding conditions hold: *(first + (i - result)) == old_value.\n\t///\n\t/// Requires: The ranges [first, last) and [result, result + (last - first)) shall not overlap.\n\t///\n\t/// Returns: result + (last - first).\n\t///\n\t/// Complexity: Exactly 'last - first' applications of the corresponding predicate.\n\t///\n\t/// Note: The predicate version of replace_copy is replace_copy_if and not another variation of replace_copy.\n\t/// This is because both versions would have the same parameter count and there could be ambiguity.\n\t///\n\ttemplate \n\tinline OutputIterator\n\treplace_copy(InputIterator first, InputIterator last, OutputIterator result, const T& old_value, const T& new_value)\n\t{\n\t\tfor(; first != last; ++first, ++result)\n\t\t\t*result = (*first == old_value) ? new_value : *first;\n\t\treturn result;\n\t}\n\n\n\t/// replace_copy_if\n\t///\n\t/// Effects: Assigns to every iterator i in the range [result, result + (last - first))\n\t/// either new_value or *(first + (i - result)) depending on whether the following\n\t/// corresponding conditions hold: predicate(*(first + (i - result))) != false.\n\t///\n\t/// Requires: The ranges [first, last) and [result, result+(lastfirst)) shall not overlap.\n\t///\n\t/// Returns: result + (last - first).\n\t///\n\t/// Complexity: Exactly 'last - first' applications of the corresponding predicate.\n\t///\n\t/// Note: The predicate version of replace_copy_if is replace_copy and not another variation of replace_copy_if.\n\t/// This is because both versions would have the same parameter count and there could be ambiguity.\n\t///\n\ttemplate \n\tinline OutputIterator\n\treplace_copy_if(InputIterator first, InputIterator last, OutputIterator result, Predicate predicate, const T& new_value)\n\t{\n\t\tfor(; first != last; ++first, ++result)\n\t\t\t*result = predicate(*first) ? new_value : *first;\n\t\treturn result;\n\t}\n\n\n\n\n\t// reverse\n\t//\n\t// We provide helper functions which allow reverse to be implemented more\n\t// efficiently for some types of iterators and types.\n\t//\n\ttemplate \n\tinline void reverse_impl(BidirectionalIterator first, BidirectionalIterator last, eastl::bidirectional_iterator_tag)\n\t{\n\t\tfor(; (first != last) && (first != --last); ++first) // We are not allowed to use operator <, <=, >, >= with a\n\t\t\teastl::iter_swap(first, last); // generic (bidirectional or otherwise) iterator.\n\t}\n\n\ttemplate \n\tinline void reverse_impl(RandomAccessIterator first, RandomAccessIterator last, eastl::random_access_iterator_tag)\n\t{\n\t\tif(first != last)\n\t\t{\n\t\t\tfor(; first < --last; ++first) // With a random access iterator, we can use operator < to more efficiently implement\n\t\t\t\teastl::iter_swap(first, last); // this algorithm. A generic iterator doesn't necessarily have an operator < defined.\n\t\t}\n\t}\n\n\t/// reverse\n\t///\n\t/// Reverses the values within the range [first, last).\n\t///\n\t/// Effects: For each nonnegative integer i <= (last - first) / 2,\n\t/// applies swap to all pairs of iterators first + i, (last i) - 1.\n\t///\n\t/// Complexity: Exactly '(last - first) / 2' swaps.\n\t///\n\ttemplate \n\tinline void reverse(BidirectionalIterator first, BidirectionalIterator last)\n\t{\n\t\ttypedef typename eastl::iterator_traits::iterator_category IC;\n\t\teastl::reverse_impl(first, last, IC());\n\t}\n\n\n\n\t/// reverse_copy\n\t///\n\t/// Copies the range [first, last) in reverse order to the result.\n\t///\n\t/// Effects: Copies the range [first, last) to the range\n\t/// [result, result + (last - first)) such that for any nonnegative\n\t/// integer i < (last - first) the following assignment takes place:\n\t/// *(result + (last - first) - i) = *(first + i)\n\t///\n\t/// Requires: The ranges [first, last) and [result, result + (last - first))\n\t/// shall not overlap.\n\t///\n\t/// Returns: result + (last - first). That is, returns the end of the output range.\n\t///\n\t/// Complexity: Exactly 'last - first' assignments.\n\t///\n\ttemplate \n\tinline OutputIterator\n\treverse_copy(BidirectionalIterator first, BidirectionalIterator last, OutputIterator result)\n\t{\n\t\tfor(; first != last; ++result)\n\t\t\t*result = *--last;\n\t\treturn result;\n\t}\n\n\n\n\t/// search\n\t///\n\t/// Search finds a subsequence within the range [first1, last1) that is identical to [first2, last2)\n\t/// when compared element-by-element. It returns an iterator pointing to the beginning of that\n\t/// subsequence, or else last1 if no such subsequence exists. As such, it is very much like\n\t/// the C strstr function, with the primary difference being that strstr uses 0-terminated strings\n\t/// whereas search uses an end iterator to specify the end of a string.\n\t///\n\t/// Returns: The first iterator i in the range [first1, last1 - (last2 - first2)) such that for\n\t/// any nonnegative integer n less than 'last2 - first2' the following corresponding condition holds:\n\t/// *(i + n) == *(first2 + n). Returns last1 if no such iterator is found.\n\t///\n\t/// Complexity: At most (last1 first1) * (last2 first2) applications of the corresponding predicate.\n\t///\n\ttemplate \n\tForwardIterator1\n\tsearch(ForwardIterator1 first1, ForwardIterator1 last1,\n\t\t ForwardIterator2 first2, ForwardIterator2 last2)\n\t{\n\t\tif(first2 != last2) // If there is anything to search for...\n\t\t{\n\t\t\t// We need to make a special case for a pattern of one element,\n\t\t\t// as the logic below prevents one element patterns from working.\n\t\t\tForwardIterator2 temp2(first2);\n\t\t\t++temp2;\n\n\t\t\tif(temp2 != last2) // If what we are searching for has a length > 1...\n\t\t\t{\n\t\t\t\tForwardIterator1 cur1(first1);\n\t\t\t\tForwardIterator2 p2;\n\n\t\t\t\twhile(first1 != last1)\n\t\t\t\t{\n\t\t\t\t\t// The following loop is the equivalent of eastl::find(first1, last1, *first2)\n\t\t\t\t\twhile((first1 != last1) && !(*first1 == *first2))\n\t\t\t\t\t\t++first1;\n\n\t\t\t\t\tif(first1 != last1)\n\t\t\t\t\t{\n\t\t\t\t\t\tp2 = temp2;\n\t\t\t\t\t\tcur1 = first1;\n\n\t\t\t\t\t\tif(++cur1 != last1)\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\twhile(*cur1 == *p2)\n\t\t\t\t\t\t\t{\n\t\t\t\t\t\t\t\tif(++p2 == last2)\n\t\t\t\t\t\t\t\t\treturn first1;\n\n\t\t\t\t\t\t\t\tif(++cur1 == last1)\n\t\t\t\t\t\t\t\t\treturn last1;\n\t\t\t\t\t\t\t}\n\n\t\t\t\t\t\t\t++first1;\n\t\t\t\t\t\t\tcontinue;\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t\treturn last1;\n\t\t\t\t}\n\n\t\t\t\t// Fall through to the end.\n\t\t\t}\n\t\t\telse\n\t\t\t\treturn eastl::find(first1, last1, *first2);\n\t\t}\n\n\t\treturn first1;\n\n\n\t\t#if 0\n\t\t/* Another implementation which is a little more simpler but executes a little slower on average.\n\t\t\ttypedef typename eastl::iterator_traits::difference_type difference_type_1;\n\t\t\ttypedef typename eastl::iterator_traits::difference_type difference_type_2;\n\n\t\t\tconst difference_type_2 d2 = eastl::distance(first2, last2);\n\n\t\t\tfor(difference_type_1 d1 = eastl::distance(first1, last1); d1 >= d2; ++first1, --d1)\n\t\t\t{\n\t\t\t\tForwardIterator1 temp1 = first1;\n\n\t\t\t\tfor(ForwardIterator2 temp2 = first2; ; ++temp1, ++temp2)\n\t\t\t\t{\n\t\t\t\t\tif(temp2 == last2)\n\t\t\t\t\t\treturn first1;\n\t\t\t\t\tif(!(*temp1 == *temp2))\n\t\t\t\t\t\tbreak;\n\t\t\t\t}\n\t\t\t}\n\n\t\t\treturn last1;\n\t\t*/\n\t\t#endif\n\t}\n\n\n\t/// search\n\t///\n\t/// Search finds a subsequence within the range [first1, last1) that is identical to [first2, last2)\n\t/// when compared element-by-element. It returns an iterator pointing to the beginning of that\n\t/// subsequence, or else last1 if no such subsequence exists. As such, it is very much like\n\t/// the C strstr function, with the only difference being that strstr uses 0-terminated strings\n\t/// whereas search uses an end iterator to specify the end of a string.\n\t///\n\t/// Returns: The first iterator i in the range [first1, last1 - (last2 - first2)) such that for\n\t/// any nonnegative integer n less than 'last2 - first2' the following corresponding condition holds:\n\t/// predicate(*(i + n), *(first2 + n)) != false. Returns last1 if no such iterator is found.\n\t///\n\t/// Complexity: At most (last1 first1) * (last2 first2) applications of the corresponding predicate.\n\t///\n\ttemplate \n\tForwardIterator1\n\tsearch(ForwardIterator1 first1, ForwardIterator1 last1,\n\t\t ForwardIterator2 first2, ForwardIterator2 last2,\n\t\t BinaryPredicate predicate)\n\t{\n\t\ttypedef typename eastl::iterator_traits::difference_type difference_type_1;\n\t\ttypedef typename eastl::iterator_traits::difference_type difference_type_2;\n\n\t\tdifference_type_2 d2 = eastl::distance(first2, last2);\n\n\t\tif(d2 != 0)\n\t\t{\n\t\t\tForwardIterator1 i(first1);\n\t\t\teastl::advance(i, d2);\n\n\t\t\tfor(difference_type_1 d1 = eastl::distance(first1, last1); d1 >= d2; --d1)\n\t\t\t{\n\t\t\t\tif(eastl::equal(first1, i, first2, predicate))\n\t\t\t\t\treturn first1;\n\t\t\t\tif(d1 > d2) // To do: Find a way to make the algorithm more elegant.\n\t\t\t\t{\n\t\t\t\t\t++first1;\n\t\t\t\t\t++i;\n\t\t\t\t}\n\t\t\t}\n\t\t\treturn last1;\n\t\t}\n\t\treturn first1; // Just like with strstr, we return first1 if the match string is empty.\n\t}\n\n\n\n\t// search_n helper functions\n\t//\n\ttemplate \n\tForwardIterator // Generic implementation.\n\tsearch_n_impl(ForwardIterator first, ForwardIterator last, Size count, const T& value, eastl::forward_iterator_tag)\n\t{\n\t\tif(count <= 0)\n\t\t\treturn first;\n\n\t\tSize d1 = (Size)eastl::distance(first, last); // Should d1 be of type Size, ptrdiff_t, or iterator_traits::difference_type?\n\t\t\t\t\t\t\t\t\t\t\t\t\t // The problem with using iterator_traits::difference_type is that\n\t\tif(count > d1) // ForwardIterator may not be a true iterator but instead something like a pointer.\n\t\t\treturn last;\n\n\t\tfor(; d1 >= count; ++first, --d1)\n\t\t{\n\t\t\tForwardIterator i(first);\n\n\t\t\tfor(Size n = 0; n < count; ++n, ++i, --d1)\n\t\t\t{\n\t\t\t\tif(!(*i == value)) // Note that we always express value comparisons in terms of < or ==.\n\t\t\t\t\tgoto not_found;\n\t\t\t}\n\t\t\treturn first;\n\n\t\t\tnot_found:\n\t\t\tfirst = i;\n\t\t}\n\t\treturn last;\n\t}\n\n\ttemplate inline\n\tRandomAccessIterator // Random access iterator implementation. Much faster than generic implementation.\n\tsearch_n_impl(RandomAccessIterator first, RandomAccessIterator last, Size count, const T& value, eastl::random_access_iterator_tag)\n\t{\n\t\tif(count <= 0)\n\t\t\treturn first;\n\t\telse if(count == 1)\n\t\t\treturn eastl::find(first, last, value);\n\t\telse if(last > first)\n\t\t{\n\t\t\tRandomAccessIterator lookAhead;\n\t\t\tRandomAccessIterator backTrack;\n\n\t\t\tSize skipOffset = (count - 1);\n\t\t\tSize tailSize = (Size)(last - first);\n\t\t\tSize remainder;\n\t\t\tSize prevRemainder;\n\n\t\t\tfor(lookAhead = first + skipOffset; tailSize >= count; lookAhead += count)\n\t\t\t{\n\t\t\t\ttailSize -= count;\n\n\t\t\t\tif(*lookAhead == value)\n\t\t\t\t{\n\t\t\t\t\tremainder = skipOffset;\n\n\t\t\t\t\tfor(backTrack = lookAhead - 1; *backTrack == value; --backTrack)\n\t\t\t\t\t{\n\t\t\t\t\t\tif(--remainder == 0)\n\t\t\t\t\t\t\treturn (lookAhead - skipOffset); // success\n\t\t\t\t\t}\n\n\t\t\t\t\tif(remainder <= tailSize)\n\t\t\t\t\t{\n\t\t\t\t\t\tprevRemainder = remainder;\n\n\t\t\t\t\t\twhile(*(++lookAhead) == value)\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\tif(--remainder == 0)\n\t\t\t\t\t\t\t\treturn (backTrack + 1); // success\n\t\t\t\t\t\t}\n\t\t\t\t\t\ttailSize -= (prevRemainder - remainder);\n\t\t\t\t\t}\n\t\t\t\t\telse\n\t\t\t\t\t\treturn last; // failure\n\t\t\t\t}\n\n\t\t\t\t// lookAhead here is always pointing to the element of the last mismatch.\n\t\t\t}\n\t\t}\n\n\t\treturn last; // failure\n\t}\n\n\n\t/// search_n\n\t///\n\t/// Returns: The first iterator i in the range [first, last count) such that\n\t/// for any nonnegative integer n less than count the following corresponding\n\t/// conditions hold: *(i + n) == value, pred(*(i + n),value) != false.\n\t/// Returns last if no such iterator is found.\n\t///\n\t/// Complexity: At most '(last1 - first1) * count' applications of the corresponding predicate.\n\t///\n\ttemplate \n\tForwardIterator\n\tsearch_n(ForwardIterator first, ForwardIterator last, Size count, const T& value)\n\t{\n\t\ttypedef typename eastl::iterator_traits::iterator_category IC;\n\t\treturn eastl::search_n_impl(first, last, count, value, IC());\n\t}\n\n\n\t/// binary_search\n\t///\n\t/// Returns: true if there is an iterator i in the range [first last) that\n\t/// satisfies the corresponding conditions: !(*i < value) && !(value < *i).\n\t///\n\t/// Complexity: At most 'log(last - first) + 2' comparisons.\n\t///\n\t/// Note: The reason binary_search returns bool instead of an iterator is\n\t/// that search_n, lower_bound, or equal_range already return an iterator.\n\t/// However, there are arguments that binary_search should return an iterator.\n\t/// Note that we provide binary_search_i (STL extension) to return an iterator.\n\t///\n\t/// To use search_n to find an item, do this:\n\t/// iterator i = search_n(begin, end, 1, value);\n\t/// To use lower_bound to find an item, do this:\n\t/// iterator i = lower_bound(begin, end, value);\n\t/// if((i != last) && !(value < *i))\n\t/// \n\t/// It turns out that the above lower_bound method is as fast as binary_search\n\t/// would be if it returned an iterator.\n\t///\n\ttemplate \n\tinline bool\n\tbinary_search(ForwardIterator first, ForwardIterator last, const T& value)\n\t{\n\t\t// To do: This can be made slightly faster by not using lower_bound.\n\t\tForwardIterator i(eastl::lower_bound(first, last, value));\n\t\treturn ((i != last) && !(value < *i)); // Note that we always express value comparisons in terms of < or ==.\n\t}\n\n\n\t/// binary_search\n\t///\n\t/// Returns: true if there is an iterator i in the range [first last) that\n\t/// satisfies the corresponding conditions: compare(*i, value) == false &&\n\t/// compare(value, *i) == false.\n\t///\n\t/// Complexity: At most 'log(last - first) + 2' comparisons.\n\t///\n\t/// Note: See comments above regarding the bool return value of binary_search.\n\t///\n\ttemplate \n\tinline bool\n\tbinary_search(ForwardIterator first, ForwardIterator last, const T& value, Compare compare)\n\t{\n\t\t// To do: This can be made slightly faster by not using lower_bound.\n\t\tForwardIterator i(eastl::lower_bound(first, last, value, compare));\n\t\treturn ((i != last) && !compare(value, *i));\n\t}\n\n\n\t/// binary_search_i\n\t///\n\t/// Returns: iterator if there is an iterator i in the range [first last) that\n\t/// satisfies the corresponding conditions: !(*i < value) && !(value < *i).\n\t/// Returns last if the value is not found.\n\t///\n\t/// Complexity: At most 'log(last - first) + 2' comparisons.\n\t///\n\ttemplate \n\tinline ForwardIterator\n\tbinary_search_i(ForwardIterator first, ForwardIterator last, const T& value)\n\t{\n\t\t// To do: This can be made slightly faster by not using lower_bound.\n\t\tForwardIterator i(eastl::lower_bound(first, last, value));\n\t\tif((i != last) && !(value < *i)) // Note that we always express value comparisons in terms of < or ==.\n\t\t\treturn i;\n\t\treturn last;\n\t}\n\n\n\t/// binary_search_i\n\t///\n\t/// Returns: iterator if there is an iterator i in the range [first last) that\n\t/// satisfies the corresponding conditions: !(*i < value) && !(value < *i).\n\t/// Returns last if the value is not found.\n\t///\n\t/// Complexity: At most 'log(last - first) + 2' comparisons.\n\t///\n\ttemplate \n\tinline ForwardIterator\n\tbinary_search_i(ForwardIterator first, ForwardIterator last, const T& value, Compare compare)\n\t{\n\t\t// To do: This can be made slightly faster by not using lower_bound.\n\t\tForwardIterator i(eastl::lower_bound(first, last, value, compare));\n\t\tif((i != last) && !compare(value, *i))\n\t\t\treturn i;\n\t\treturn last;\n\t}\n\n\n\t/// unique\n\t///\n\t/// Given a sorted range, this function removes duplicated items.\n\t/// Note that if you have a container then you will probably want\n\t/// to call erase on the container with the return value if your\n\t/// goal is to remove the duplicated items from the container.\n\t///\n\t/// Effects: Eliminates all but the first element from every consecutive\n\t/// group of equal elements referred to by the iterator i in the range\n\t/// [first, last) for which the following corresponding condition holds:\n\t/// *i == *(i - 1).\n\t///\n\t/// Returns: The end of the resulting range.\n\t///\n\t/// Complexity: If the range (last - first) is not empty, exactly (last - first)\n\t/// applications of the corresponding predicate, otherwise no applications of the predicate.\n\t///\n\t/// Example usage:\n\t/// vector intArray;\n\t/// ...\n\t/// intArray.erase(unique(intArray.begin(), intArray.end()), intArray.end());\n\t///\n\ttemplate \n\tForwardIterator unique(ForwardIterator first, ForwardIterator last)\n\t{\n\t\tfirst = eastl::adjacent_find(first, last);\n\n\t\tif(first != last) // We expect that there are duplicated items, else the user wouldn't be calling this function.\n\t\t{\n\t\t\tForwardIterator dest(first);\n\n\t\t\tfor(++first; first != last; ++first)\n\t\t\t{\n\t\t\t\tif(!(*dest == *first)) // Note that we always express value comparisons in terms of < or ==.\n\t\t\t\t\t*++dest = *first;\n\t\t\t}\n\t\t\treturn ++dest;\n\t\t}\n\t\treturn last;\n\t}\n\n\n\t/// unique\n\t///\n\t/// Given a sorted range, this function removes duplicated items.\n\t/// Note that if you have a container then you will probably want\n\t/// to call erase on the container with the return value if your\n\t/// goal is to remove the duplicated items from the container.\n\t///\n\t/// Effects: Eliminates all but the first element from every consecutive\n\t/// group of equal elements referred to by the iterator i in the range\n\t/// [first, last) for which the following corresponding condition holds:\n\t/// predicate(*i, *(i - 1)) != false.\n\t///\n\t/// Returns: The end of the resulting range.\n\t///\n\t/// Complexity: If the range (last - first) is not empty, exactly (last - first)\n\t/// applications of the corresponding predicate, otherwise no applications of the predicate.\n\t///\n\ttemplate \n\tForwardIterator unique(ForwardIterator first, ForwardIterator last, BinaryPredicate predicate)\n\t{\n\t\tfirst = eastl::adjacent_find(first, last, predicate);\n\n\t\tif(first != last) // We expect that there are duplicated items, else the user wouldn't be calling this function.\n\t\t{\n\t\t\tForwardIterator dest(first);\n\n\t\t\tfor(++first; first != last; ++first)\n\t\t\t{\n\t\t\t\tif(!predicate(*dest, *first))\n\t\t\t\t\t*++dest = *first;\n\t\t\t}\n\t\t\treturn ++dest;\n\t\t}\n\t\treturn last;\n\t}\n\n\n\n\t// find_end\n\t//\n\t// We provide two versions here, one for a bidirectional iterators and one for\n\t// regular forward iterators. Given that we are searching backward, it's a bit\n\t// more efficient if we can use backwards iteration to implement our search,\n\t// though this requires an iterator that can be reversed.\n\t//\n\ttemplate \n\tForwardIterator1\n\tfind_end_impl(ForwardIterator1 first1, ForwardIterator1 last1,\n\t\t\t\t ForwardIterator2 first2, ForwardIterator2 last2,\n\t\t\t\t eastl::forward_iterator_tag, eastl::forward_iterator_tag)\n\t{\n\t\tif(first2 != last2) // We have to do this check because the search algorithm below will return first1 (and not last1) if the first2/last2 range is empty.\n\t\t{\n\t\t\tfor(ForwardIterator1 result(last1); ; )\n\t\t\t{\n\t\t\t\tconst ForwardIterator1 resultNext(eastl::search(first1, last1, first2, last2));\n\n\t\t\t\tif(resultNext != last1) // If another sequence was found...\n\t\t\t\t{\n\t\t\t\t\tfirst1 = result = resultNext;\n\t\t\t\t\t++first1;\n\t\t\t\t}\n\t\t\t\telse\n\t\t\t\t\treturn result;\n\t\t\t}\n\t\t}\n\t\treturn last1;\n\t}\n\n\ttemplate \n\tBidirectionalIterator1\n\tfind_end_impl(BidirectionalIterator1 first1, BidirectionalIterator1 last1,\n\t\t\t\t BidirectionalIterator2 first2, BidirectionalIterator2 last2,\n\t\t\t\t eastl::bidirectional_iterator_tag, eastl::bidirectional_iterator_tag)\n\t{\n\t\ttypedef eastl::reverse_iterator reverse_iterator1;\n\t\ttypedef eastl::reverse_iterator reverse_iterator2;\n\n\t\treverse_iterator1 rresult(eastl::search(reverse_iterator1(last1), reverse_iterator1(first1),\n\t\t\t\t\t\t\t\t\t\t\t\treverse_iterator2(last2), reverse_iterator2(first2)));\n\t\tif(rresult.base() != first1) // If we found something...\n\t\t{\n\t\t\tBidirectionalIterator1 result(rresult.base());\n\n\t\t\teastl::advance(result, -eastl::distance(first2, last2)); // We have an opportunity to optimize this, as the\n\t\t\treturn result; // search function already calculates this distance.\n\t\t}\n\t\treturn last1;\n\t}\n\n\t/// find_end\n\t///\n\t/// Finds the last occurrence of the second sequence in the first sequence.\n\t/// As such, this function is much like the C string function strrstr and it\n\t/// is also the same as a reversed version of 'search'. It is called find_end\n\t/// instead of the possibly more consistent search_end simply because the C++\n\t/// standard algorithms have such naming.\n\t///\n\t/// Returns an iterator between first1 and last1 if the sequence is found.\n\t/// returns last1 (the end of the first seqence) if the sequence is not found.\n\t///\n\ttemplate \n\tinline ForwardIterator1\n\tfind_end(ForwardIterator1 first1, ForwardIterator1 last1,\n\t\t\t ForwardIterator2 first2, ForwardIterator2 last2)\n\t{\n\t\ttypedef typename eastl::iterator_traits::iterator_category IC1;\n\t\ttypedef typename eastl::iterator_traits::iterator_category IC2;\n\n\t\treturn eastl::find_end_impl(first1, last1, first2, last2, IC1(), IC2());\n\t}\n\n\n\n\n\t// To consider: Fold the predicate and non-predicate versions of\n\t// this algorithm into a single function.\n\ttemplate \n\tForwardIterator1\n\tfind_end_impl(ForwardIterator1 first1, ForwardIterator1 last1,\n\t\t\t\t ForwardIterator2 first2, ForwardIterator2 last2,\n\t\t\t\t BinaryPredicate predicate,\n\t\t\t\t eastl::forward_iterator_tag, eastl::forward_iterator_tag)\n\t{\n\t\tif(first2 != last2) // We have to do this check because the search algorithm below will return first1 (and not last1) if the first2/last2 range is empty.\n\t\t{\n\t\t\tfor(ForwardIterator1 result = last1; ; )\n\t\t\t{\n\t\t\t\tconst ForwardIterator1 resultNext(eastl::search(first1, last1, first2, last2, predicate));\n\n\t\t\t\tif(resultNext != last1) // If another sequence was found...\n\t\t\t\t{\n\t\t\t\t\tfirst1 = result = resultNext;\n\t\t\t\t\t++first1;\n\t\t\t\t}\n\t\t\t\telse\n\t\t\t\t\treturn result;\n\t\t\t}\n\t\t}\n\t\treturn last1;\n\t}\n\n\ttemplate \n\tBidirectionalIterator1\n\tfind_end_impl(BidirectionalIterator1 first1, BidirectionalIterator1 last1,\n\t\t\t\t BidirectionalIterator2 first2, BidirectionalIterator2 last2,\n\t\t\t\t BinaryPredicate predicate,\n\t\t\t\t eastl::bidirectional_iterator_tag, eastl::bidirectional_iterator_tag)\n\t{\n\t\ttypedef eastl::reverse_iterator reverse_iterator1;\n\t\ttypedef eastl::reverse_iterator reverse_iterator2;\n\n\t\treverse_iterator1 rresult(eastl::search\n\t\t\t\t\t\t\t\t\t\t\t (reverse_iterator1(last1), reverse_iterator1(first1),\n\t\t\t\t\t\t\t\t\t\t\t\treverse_iterator2(last2), reverse_iterator2(first2),\n\t\t\t\t\t\t\t\t\t\t\t\tpredicate));\n\t\tif(rresult.base() != first1) // If we found something...\n\t\t{\n\t\t\tBidirectionalIterator1 result(rresult.base());\n\t\t\teastl::advance(result, -eastl::distance(first2, last2));\n\t\t\treturn result;\n\t\t}\n\t\treturn last1;\n\t}\n\n\n\t/// find_end\n\t///\n\t/// Effects: Finds a subsequence of equal values in a sequence.\n\t///\n\t/// Returns: The last iterator i in the range [first1, last1 - (last2 - first2))\n\t/// such that for any nonnegative integer n < (last2 - first2), the following\n\t/// corresponding conditions hold: pred(*(i+n),*(first2+n)) != false. Returns\n\t/// last1 if no such iterator is found.\n\t///\n\t/// Complexity: At most (last2 - first2) * (last1 - first1 - (last2 - first2) + 1)\n\t/// applications of the corresponding predicate.\n\t///\n\ttemplate \n\tinline ForwardIterator1\n\tfind_end(ForwardIterator1 first1, ForwardIterator1 last1,\n\t\t\t ForwardIterator2 first2, ForwardIterator2 last2,\n\t\t\t BinaryPredicate predicate)\n\t{\n\t\ttypedef typename eastl::iterator_traits::iterator_category IC1;\n\t\ttypedef typename eastl::iterator_traits::iterator_category IC2;\n\n\t\treturn eastl::find_end_impl\n\t\t\t\t\t\t\t\t (first1, last1, first2, last2, predicate, IC1(), IC2());\n\t}\n\n\n\t/// set_difference\n\t///\n\t/// set_difference iterates over both input ranges and copies elements present\n\t/// in the first range but not the second to the output range.\n\t///\n\t/// Effects: Copies the elements of the range [first1, last1) which are not\n\t/// present in the range [first2, last2) to the range beginning at result.\n\t/// The elements in the constructed range are sorted.\n\t///\n\t/// Requires: The input ranges must be sorted.\n\t/// Requires: The output range shall not overlap with either of the original ranges.\n\t///\n\t/// Returns: The end of the output range.\n\t///\n\t/// Complexity: At most (2 * ((last1 - first1) + (last2 - first2)) - 1) comparisons.\n\t///\n\ttemplate \n\tOutputIterator set_difference(InputIterator1 first1, InputIterator1 last1,\n\t\t\t\t\t\t\t\t InputIterator2 first2, InputIterator2 last2,\n\t\t\t\t\t\t\t\t OutputIterator result)\n\t{\n\t\twhile((first1 != last1) && (first2 != last2))\n\t\t{\n\t\t\tif(*first1 < *first2)\n\t\t\t{\n\t\t\t\t*result = *first1;\n\t\t\t\t++first1;\n\t\t\t\t++result;\n\t\t\t}\n\t\t\telse if(*first2 < *first1)\n\t\t\t\t++first2;\n\t\t\telse\n\t\t\t{\n\t\t\t\t++first1;\n\t\t\t\t++first2;\n\t\t\t}\n\t\t}\n\n\t\treturn eastl::copy(first1, last1, result);\n\t}\n\n\n\ttemplate \n\tOutputIterator set_difference(InputIterator1 first1, InputIterator1 last1,\n\t\t\t\t\t\t\t\t InputIterator2 first2, InputIterator2 last2,\n\t\t\t\t\t\t\t\t OutputIterator result, Compare compare)\n\t{\n\t\twhile((first1 != last1) && (first2 != last2))\n\t\t{\n\t\t\tif(compare(*first1, *first2))\n\t\t\t{\n\t\t\t\tEASTL_VALIDATE_COMPARE(!compare(*first2, *first1)); // Validate that the compare function is sane.\n\t\t\t\t*result = *first1;\n\t\t\t\t++first1;\n\t\t\t\t++result;\n\t\t\t}\n\t\t\telse if(compare(*first2, *first1))\n\t\t\t{\n\t\t\t\tEASTL_VALIDATE_COMPARE(!compare(*first1, *first2)); // Validate that the compare function is sane.\n\t\t\t\t++first2;\n\t\t\t}\n\t\t\telse\n\t\t\t{\n\t\t\t\t++first1;\n\t\t\t\t++first2;\n\t\t\t}\n\t\t}\n\n\t\treturn eastl::copy(first1, last1, result);\n\t}\n\n\n\t/// set_difference_2\n\t///\n\t/// set_difference_2 iterates over both input ranges and copies elements present\n\t/// in the first range but not the second to the first output range and copies\n\t/// elements present in the second range but not in the first to the second output\n\t/// range.\n\t///\n\t/// Effects: Copies the elements of the range [first1, last1) which are not\n\t/// present in the range [first2, last2) to the first output range beginning at\n\t/// result1 AND copies the element of range [first2, last2) which are not present\n\t/// in the range [first1, last) to the second output range beginning at result2.\n\t/// The elements in the constructed range are sorted.\n\t///\n\t/// Requires: The input ranges must be sorted.\n\t/// Requires: The output ranges shall not overlap with either of the original ranges.\n\t///\n\t/// Returns: Nothing.\n\t///\n\t/// Complexity: At most (2 * ((last1 - first1) + (last2 - first2)) - 1) comparisons.\n\t///\n\ttemplate \n\tvoid set_difference_2(InputIterator1 first1, InputIterator1 last1,\n\t InputIterator2 first2, InputIterator2 last2,\n\t OutputIterator result1, OutputIterator result2, Compare compare)\n\t{\n\t\twhile ((first1 != last1) && (first2 != last2))\n\t\t{\n\t\t\tif (compare(*first1, *first2))\n\t\t\t{\n\t\t\t\tEASTL_VALIDATE_COMPARE(!compare(*first2, *first1)); // Validate that the compare function is sane.\n\t\t\t\t*result1++ = *first1++;\n\t\t\t}\n\t\t\telse if (compare(*first2, *first1))\n\t\t\t{\n\t\t\t\tEASTL_VALIDATE_COMPARE(!compare(*first1, *first2)); // Validate that the compare function is sane.\n\t\t\t\t*result2++ = *first2++;\n\t\t\t}\n\t\t\telse\n\t\t\t{\n\t\t\t\t++first1;\n\t\t\t\t++first2;\n\t\t\t}\n\t\t}\n\n\t\teastl::copy(first2, last2, result2);\n\t\teastl::copy(first1, last1, result1);\n\t}\n\n\t/// set_difference_2\n\t///\n\t/// set_difference_2 with the default comparison object is eastl::less<>.\n\t///\n\ttemplate \n\tvoid set_difference_2(InputIterator1 first1, InputIterator1 last1,\n\t InputIterator2 first2, InputIterator2 last2,\n\t OutputIterator result1, OutputIterator result2)\n\t{\n\t\teastl::set_difference_2(first1, last1, first2, last2, result1, result2, eastl::less<>{});\n\t}\n\n\n\t/// set_symmetric_difference\n\t///\n\t/// set_difference iterates over both input ranges and copies elements present\n\t/// in the either range but not the other to the output range.\n\t///\n\t/// Effects: Copies the elements of the range [first1, last1) which are not\n\t/// present in the range [first2, last2), and the elements of the range [first2, last2)\n\t/// which are not present in the range [first1, last1) to the range beginning at result.\n\t/// The elements in the constructed range are sorted.\n\t///\n\t/// Requires: The input ranges must be sorted.\n\t/// Requires: The resulting range shall not overlap with either of the original ranges.\n\t///\n\t/// Returns: The end of the constructed range.\n\t///\n\t/// Complexity: At most (2 * ((last1 - first1) + (last2 - first2)) - 1) comparisons.\n\t///\n\ttemplate \n\tOutputIterator set_symmetric_difference(InputIterator1 first1, InputIterator1 last1,\n\t\t\t\t\t\t\t\t\t\t\tInputIterator2 first2, InputIterator2 last2,\n\t\t\t\t\t\t\t\t\t\t\tOutputIterator result)\n\t{\n\t\twhile((first1 != last1) && (first2 != last2))\n\t\t{\n\t\t\tif(*first1 < *first2)\n\t\t\t{\n\t\t\t\t*result = *first1;\n\t\t\t\t++first1;\n\t\t\t\t++result;\n\t\t\t}\n\t\t\telse if(*first2 < *first1)\n\t\t\t{\n\t\t\t\t*result = *first2;\n\t\t\t\t++first2;\n\t\t\t\t++result;\n\t\t\t}\n\t\t\telse\n\t\t\t{\n\t\t\t\t++first1;\n\t\t\t\t++first2;\n\t\t\t}\n\t\t}\n\n\t\treturn eastl::copy(first2, last2, eastl::copy(first1, last1, result));\n\t}\n\n\n\ttemplate \n\tOutputIterator set_symmetric_difference(InputIterator1 first1, InputIterator1 last1,\n\t\t\t\t\t\t\t\t\t\t\tInputIterator2 first2, InputIterator2 last2,\n\t\t\t\t\t\t\t\t\t\t\tOutputIterator result, Compare compare)\n\t{\n\t\twhile((first1 != last1) && (first2 != last2))\n\t\t{\n\t\t\tif(compare(*first1, *first2))\n\t\t\t{\n\t\t\t\tEASTL_VALIDATE_COMPARE(!compare(*first2, *first1)); // Validate that the compare function is sane.\n\t\t\t\t*result = *first1;\n\t\t\t\t++first1;\n\t\t\t\t++result;\n\t\t\t}\n\t\t\telse if(compare(*first2, *first1))\n\t\t\t{\n\t\t\t\tEASTL_VALIDATE_COMPARE(!compare(*first1, *first2)); // Validate that the compare function is sane.\n\t\t\t\t*result = *first2;\n\t\t\t\t++first2;\n\t\t\t\t++result;\n\t\t\t}\n\t\t\telse\n\t\t\t{\n\t\t\t\t++first1;\n\t\t\t\t++first2;\n\t\t\t}\n\t\t}\n\n\t\treturn eastl::copy(first2, last2, eastl::copy(first1, last1, result));\n\t}\n\n\n\t/// set_intersection\n\t///\n\t/// set_intersection over both ranges and copies elements present in\n\t/// both ranges to the output range.\n\t///\n\t/// Effects: Constructs a sorted intersection of the elements from the\n\t/// two ranges; that is, the set of elements that are present in both of the ranges.\n\t///\n\t/// Requires: The input ranges must be sorted.\n\t/// Requires: The resulting range shall not overlap with either of the original ranges.\n\t///\n\t/// Returns: The end of the constructed range.\n\t///\n\t/// Complexity: At most 2 * ((last1 - first1) + (last2 - first2)) - 1) comparisons.\n\t///\n\t/// Note: The copying operation is stable; if an element is present in both ranges,\n\t/// the one from the first range is copied.\n\t///\n\ttemplate \n\tOutputIterator set_intersection(InputIterator1 first1, InputIterator1 last1,\n\t\t\t\t\t\t\t\t\tInputIterator2 first2, InputIterator2 last2,\n\t\t\t\t\t\t\t\t\tOutputIterator result)\n\t{\n\t\twhile((first1 != last1) && (first2 != last2))\n\t\t{\n\t\t\tif(*first1 < *first2)\n\t\t\t\t++first1;\n\t\t\telse if(*first2 < *first1)\n\t\t\t\t++first2;\n\t\t\telse\n\t\t\t{\n\t\t\t\t*result = *first1;\n\t\t\t\t++first1;\n\t\t\t\t++first2;\n\t\t\t\t++result;\n\t\t\t}\n\t\t}\n\n\t\treturn result;\n\t}\n\n\n\ttemplate \n\tOutputIterator set_intersection(InputIterator1 first1, InputIterator1 last1,\n\t\t\t\t\t\t\t\t\tInputIterator2 first2, InputIterator2 last2,\n\t\t\t\t\t\t\t\t\tOutputIterator result, Compare compare)\n\t{\n\t\twhile((first1 != last1) && (first2 != last2))\n\t\t{\n\t\t\tif(compare(*first1, *first2))\n\t\t\t{\n\t\t\t\tEASTL_VALIDATE_COMPARE(!compare(*first2, *first1)); // Validate that the compare function is sane.\n\t\t\t\t++first1;\n\t\t\t}\n\t\t\telse if(compare(*first2, *first1))\n\t\t\t{\n\t\t\t\tEASTL_VALIDATE_COMPARE(!compare(*first1, *first2)); // Validate that the compare function is sane.\n\t\t\t\t++first2;\n\t\t\t}\n\t\t\telse\n\t\t\t{\n\t\t\t\t*result = *first1;\n\t\t\t\t++first1;\n\t\t\t\t++first2;\n\t\t\t\t++result;\n\t\t\t}\n\t\t}\n\n\t\treturn result;\n\t}\n\n\n\n\t/// set_union\n\t///\n\t/// set_union iterates over both ranges and copies elements present in\n\t/// both ranges to the output range.\n\t///\n\t/// Effects: Constructs a sorted union of the elements from the two ranges;\n\t/// that is, the set of elements that are present in one or both of the ranges.\n\t///\n\t/// Requires: The input ranges must be sorted.\n\t/// Requires: The resulting range shall not overlap with either of the original ranges.\n\t///\n\t/// Returns: The end of the constructed range.\n\t///\n\t/// Complexity: At most (2 * ((last1 - first1) + (last2 - first2)) - 1) comparisons.\n\t///\n\t/// Note: The copying operation is stable; if an element is present in both ranges,\n\t/// the one from the first range is copied.\n\t///\n\ttemplate \n\tOutputIterator set_union(InputIterator1 first1, InputIterator1 last1,\n\t\t\t\t\t\t\t InputIterator2 first2, InputIterator2 last2,\n\t\t\t\t\t\t\t OutputIterator result)\n\t{\n\t\twhile((first1 != last1) && (first2 != last2))\n\t\t{\n\t\t\tif(*first1 < *first2)\n\t\t\t{\n\t\t\t\t*result = *first1;\n\t\t\t\t++first1;\n\t\t\t}\n\t\t\telse if(*first2 < *first1)\n\t\t\t{\n\t\t\t\t*result = *first2;\n\t\t\t\t++first2;\n\t\t\t}\n\t\t\telse\n\t\t\t{\n\t\t\t\t*result = *first1;\n\t\t\t\t++first1;\n\t\t\t\t++first2;\n\t\t\t}\n\t\t\t++result;\n\t\t}\n\n\t\treturn eastl::copy(first2, last2, eastl::copy(first1, last1, result));\n\t}\n\n\n\ttemplate \n\tOutputIterator set_union(InputIterator1 first1, InputIterator1 last1,\n\t\t\t\t\t\t\t InputIterator2 first2, InputIterator2 last2,\n\t\t\t\t\t\t\t OutputIterator result, Compare compare)\n\t{\n\t\twhile((first1 != last1) && (first2 != last2))\n\t\t{\n\t\t\tif(compare(*first1, *first2))\n\t\t\t{\n\t\t\t\tEASTL_VALIDATE_COMPARE(!compare(*first2, *first1)); // Validate that the compare function is sane.\n\t\t\t\t*result = *first1;\n\t\t\t\t++first1;\n\t\t\t}\n\t\t\telse if(compare(*first2, *first1))\n\t\t\t{\n\t\t\t\tEASTL_VALIDATE_COMPARE(!compare(*first1, *first2)); // Validate that the compare function is sane.\n\t\t\t\t*result = *first2;\n\t\t\t\t++first2;\n\t\t\t}\n\t\t\telse\n\t\t\t{\n\t\t\t\t*result = *first1;\n\t\t\t\t++first1;\n\t\t\t\t++first2;\n\t\t\t}\n\t\t\t++result;\n\t\t}\n\n\t\treturn eastl::copy(first2, last2, eastl::copy(first1, last1, result));\n\t}\n\n\n\t/// set_decomposition\n\t///\n\t/// set_decomposition iterates over both ranges and copies elements to one of the three\n\t/// categories of output ranges.\n\t///\n\t/// Effects: Constructs three sorted containers of the elements from the two ranges.\n\t/// * OutputIterator1 is elements only in Container1.\n\t/// * OutputIterator2 is elements only in Container2.\n\t/// * OutputIterator3 is elements that are in both Container1 and Container2.\n\t///\n\t/// Requires: The input ranges must be sorted.\n\t/// Requires: The resulting ranges shall not overlap with either of the original ranges.\n\t///\n\t/// Returns: The end of the constructed range of elements in both Container1 and Container2.\n\t///\n\t/// Complexity: At most (2 * ((last1 - first1) + (last2 - first2)) - 1) comparisons.\n\t///\n\ttemplate \n\tOutputIterator3 set_decomposition(InputIterator1 first1, InputIterator1 last1,\n\t InputIterator2 first2, InputIterator2 last2,\n\t OutputIterator1 result1, OutputIterator2 result2, OutputIterator3 result3, Compare compare)\n\t{\n\t\twhile ((first1 != last1) && (first2 != last2))\n\t\t{\n\t\t\tif (compare(*first1, *first2))\n\t\t\t{\n\t\t\t\tEASTL_VALIDATE_COMPARE(!compare(*first2, *first1)); // Validate that the compare function is sane.\n\t\t\t\t*result1++ = *first1++;\n\t\t\t}\n\t\t\telse if (compare(*first2, *first1))\n\t\t\t{\n\t\t\t\tEASTL_VALIDATE_COMPARE(!compare(*first1, *first2)); // Validate that the compare function is sane.\n\t\t\t\t*result2++ = *first2++;\n\t\t\t}\n\t\t\telse\n\t\t\t{\n\t\t\t\t*result3++ = *first1++;\n\t\t\t\t++first2;\n\t\t\t}\n\t\t}\n\n\t\teastl::copy(first1, last1, result1);\n\t\teastl::copy(first2, last2, result2);\n\n\t\treturn result3;\n\t}\n\n\t/// set_decomposition\n\t///\n\t/// set_decomposition with the default comparison object is eastl::less<>.\n\t///\n\ttemplate \n\tOutputIterator3 set_decomposition(InputIterator1 first1, InputIterator1 last1, InputIterator2 first2, InputIterator2 last2,\n\t\t\t\t\t\t\t OutputIterator1 result1, OutputIterator2 result2, OutputIterator3 result3)\n\t{\n\t\treturn eastl::set_decomposition(first1, last1, first2, last2, result1, result2, result3, eastl::less<>{});\n\t}\n\n\t/// includes\n\t///\n\t/// Returns true if the sorted range [first2, last2) is a subsequence of the sorted range [first1, last1).\n\t/// Note: a subsequence need not be contiguous!.\n\t/// If [first1, last1) or [first2, last2) is not sorted with respect to comp, the behavior is undefined.\n\ttemplate\n\tbool includes(InputIt1 first1, InputIt1 last1,\n\t\t\t\t InputIt2 first2, InputIt2 last2, Compare comp)\n\t{\n\t\tfor (; first2 != last2; ++first1)\n\t\t{\n\t\t\tif (first1 == last1 || comp(*first2, *first1))\n\t\t\t{\n\t\t\t\treturn false;\n\t\t\t}\n\t\t\tif (!comp(*first1, *first2))\n\t\t\t{\n\t\t\t\t++first2;\n\t\t\t}\n\t\t}\n\t\treturn true;\n\t}\n\n\t/// includes\n\t///\n\t/// Returns true if the sorted range [first2, last2) is a subsequence of the sorted range [first1, last1).\n\t/// Note: a subsequence need not be contiguous!.\n\t/// If [first1, last1) or [first2, last2) is not sorted with respect to eastl::less, the behavior is undefined.\n\ttemplate\n\tbool includes(InputIt1 first1, InputIt1 last1,\n\t\t\t\t InputIt2 first2, InputIt2 last2)\n\t{\n\t\treturn eastl::includes(first1, last1, first2, last2, eastl::less<>{});\n\t}\n\n\t/// is_permutation\n\t///\n\ttemplate\n\tbool is_permutation(ForwardIterator1 first1, ForwardIterator1 last1, ForwardIterator2 first2)\n\t{\n\t\ttypedef typename eastl::iterator_traits::difference_type difference_type;\n\n\t\t// Skip past any equivalent initial elements.\n\t\twhile((first1 != last1) && (*first1 == *first2))\n\t\t{\n\t\t\t++first1;\n\t\t\t++first2;\n\t\t}\n\n\t\tif(first1 != last1)\n\t\t{\n\t\t\tconst difference_type first1Size = eastl::distance(first1, last1);\n\t\t\tForwardIterator2 last2 = first2;\n\t\t\teastl::advance(last2, first1Size);\n\n\t\t\tfor(ForwardIterator1 i = first1; i != last1; ++i)\n\t\t\t{\n\t\t\t\tif(i == eastl::find(first1, i, *i))\n\t\t\t\t{\n\t\t\t\t\tconst difference_type c = eastl::count(first2, last2, *i);\n\n\t\t\t\t\tif((c == 0) || (c != eastl::count(i, last1, *i)))\n\t\t\t\t\t\treturn false;\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\treturn true;\n\t}\n\n\t/// is_permutation\n\t///\n\ttemplate\n\tbool is_permutation(ForwardIterator1 first1, ForwardIterator1 last1, ForwardIterator2 first2, BinaryPredicate predicate)\n\t{\n\t\ttypedef typename eastl::iterator_traits::difference_type difference_type;\n\n\t\t// Skip past any equivalent initial elements.\n\t\twhile((first1 != last1) && predicate(*first1, *first2))\n\t\t{\n\t\t\t++first1;\n\t\t\t++first2;\n\t\t}\n\n\t\tif(first1 != last1)\n\t\t{\n\t\t\tconst difference_type first1Size = eastl::distance(first1, last1);\n\t\t\tForwardIterator2 last2 = first2;\n\t\t\teastl::advance(last2, first1Size);\n\n\t\t\tfor(ForwardIterator1 i = first1; i != last1; ++i)\n\t\t\t{\n\t\t\t\tif(i == eastl::find(first1, i, *i, predicate))\n\t\t\t\t{\n\t\t\t\t\tconst difference_type c = eastl::count(first2, last2, *i, predicate);\n\n\t\t\t\t\tif((c == 0) || (c != eastl::count(i, last1, *i, predicate)))\n\t\t\t\t\t\treturn false;\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\treturn true;\n\t}\n\n\n\t/// next_permutation\n\t///\n\t/// mutates the range [first, last) to the next permutation. Returns true if the\n\t/// new range is not the final permutation (sorted like the starting permutation).\n\t/// Permutations start with a sorted range, and false is returned when next_permutation\n\t/// results in the initial sorted range, or if the range has <= 1 element.\n\t/// Note that elements are compared by operator < (as usual) and that elements deemed\n\t/// equal via this are not rearranged.\n\t///\n\t/// http://marknelson.us/2002/03/01/next-permutation/\n\t/// Basically we start with an ordered range and reverse it's order one specifically\n\t/// chosen swap and reverse at a time. It happens that this require going through every\n\t/// permutation of the range. We use the same variable names as the document above.\n\t///\n\t/// To consider: Significantly improved permutation/combination functionality:\n\t/// http://home.roadrunner.com/~hinnant/combinations.html\n\t///\n\t/// Example usage:\n\t/// vector intArray;\n\t/// // \n\t/// sort(intArray.begin(), intArray.end());\n\t/// do {\n\t/// // \n\t/// } while(next_permutation(intArray.begin(), intArray.end()));\n\t///\n\n\ttemplate\n\tbool next_permutation(BidirectionalIterator first, BidirectionalIterator last, Compare compare)\n\t{\n\t\tif(first != last) // If there is anything in the range...\n\t\t{\n\t\t\tBidirectionalIterator i = last;\n\n\t\t\tif(first != --i) // If the range has more than one item...\n\t\t\t{\n\t\t\t\tfor(;;)\n\t\t\t\t{\n\t\t\t\t\tBidirectionalIterator ii(i), j;\n\n\t\t\t\t\tif(compare(*--i, *ii)) // Find two consecutive values where the first is less than the second.\n\t\t\t\t\t{\n\t\t\t\t\t\tj = last;\n\t\t\t\t\t\twhile(!compare(*i, *--j)) // Find the final value that's greater than the first (it may be equal to the second).\n\t\t\t\t\t\t\t{}\n\t\t\t\t\t\teastl::iter_swap(i, j); // Swap the first and the final.\n\t\t\t\t\t\teastl::reverse(ii, last); // Reverse the ranget from second to last.\n\t\t\t\t\t\treturn true;\n\t\t\t\t\t}\n\n\t\t\t\t\tif(i == first) // There are no two consecutive values where the first is less than the second, meaning the range is in reverse order. The reverse ordered range is always the last permutation.\n\t\t\t\t\t{\n\t\t\t\t\t\teastl::reverse(first, last);\n\t\t\t\t\t\tbreak; // We are done.\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\treturn false;\n\t}\n\n\ttemplate\n\tbool next_permutation(BidirectionalIterator first, BidirectionalIterator last)\n\t{\n\t\ttypedef typename eastl::iterator_traits::value_type value_type;\n\n\t\treturn eastl::next_permutation(first, last, eastl::less());\n\t}\n\n\n\n\t/// rotate\n\t///\n\t/// Effects: For each non-negative integer i < (last - first), places the element from the\n\t/// position first + i into position first + (i + (last - middle)) % (last - first).\n\t///\n\t/// Returns: first + (last - middle). That is, returns where first went to.\n\t///\n\t/// Remarks: This is a left rotate.\n\t///\n\t/// Requires: [first,middle) and [middle,last) shall be valid ranges. ForwardIterator shall\n\t/// satisfy the requirements of ValueSwappable (17.6.3.2). The type of *first shall satisfy\n\t/// the requirements of MoveConstructible (Table 20) and the requirements of MoveAssignable.\n\t///\n\t/// Complexity: At most last - first swaps.\n\t///\n\t/// Note: While rotate works on ForwardIterators (e.g. slist) and BidirectionalIterators (e.g. list),\n\t/// you can get much better performance (O(1) instead of O(n)) with slist and list rotation by\n\t/// doing splice operations on those lists instead of calling this rotate function.\n\t///\n\t/// http://www.cs.bell-labs.com/cm/cs/pearls/s02b.pdf / http://books.google.com/books?id=kse_7qbWbjsC&pg=PA14&lpg=PA14&dq=Programming+Pearls+flipping+hands\n\t/// http://books.google.com/books?id=tjOlkl7ecVQC&pg=PA189&lpg=PA189&dq=stepanov+Elements+of+Programming+rotate\n\t/// http://stackoverflow.com/questions/21160875/why-is-stdrotate-so-fast\n\t///\n\t/// Strategy:\n\t/// - We handle the special case of (middle == first) and (middle == last) no-ops\n\t/// up front in the main rotate entry point.\n\t/// - There's a basic ForwardIterator implementation (rotate_general_impl) which is\n\t/// a fallback implementation that's not as fast as others but works for all cases.\n\t/// - There's a slightly better BidirectionalIterator implementation.\n\t/// - We have specialized versions for rotating elements that are trivially copyable.\n\t/// These versions will use memmove for when we have a RandomAccessIterator.\n\t/// - We have a specialized version for rotating by only a single position, as that allows us\n\t/// (with any iterator type) to avoid a lot of logic involved with algorithms like \"flipping hands\"\n\t/// and achieve near optimal O(n) behavior. it turns out that rotate-by-one is a common use\n\t/// case in practice.\n\t///\n\tnamespace Internal\n\t{\n\t\ttemplate\n\t\tForwardIterator rotate_general_impl(ForwardIterator first, ForwardIterator middle, ForwardIterator last)\n\t\t{\n\t\t\tusing eastl::swap;\n\n\t\t\tForwardIterator current = middle;\n\n\t\t\tdo {\n\t\t\t\tswap(*first++, *current++);\n\n\t\t\t\tif(first == middle)\n\t\t\t\t\tmiddle = current;\n\t\t\t} while(current != last);\n\n\t\t\tForwardIterator result = first;\n\t\t\tcurrent = middle;\n\n\t\t\twhile(current != last)\n\t\t\t{\n\t\t\t\tswap(*first++, *current++);\n\n\t\t\t\tif(first == middle)\n\t\t\t\t\tmiddle = current;\n\t\t\t\telse if(current == last)\n\t\t\t\t\tcurrent = middle;\n\t\t\t}\n\n\t\t\treturn result; // result points to first + (last - middle).\n\t\t}\n\n\n\t\ttemplate \n\t\tForwardIterator move_rotate_left_by_one(ForwardIterator first, ForwardIterator last)\n\t\t{\n\t\t\ttypedef typename eastl::iterator_traits::value_type value_type;\n\n\t\t\tvalue_type temp(eastl::move(*first));\n\t\t\tForwardIterator result = eastl::move(eastl::next(first), last, first); // Note that while our template type is BidirectionalIterator, if the actual\n\t\t\t*result = eastl::move(temp); // iterator is a RandomAccessIterator then this move will be a memmove for trivially copyable types.\n\n\t\t\treturn result; // result points to the final element in the range.\n\t\t}\n\n\n\t\ttemplate \n\t\tBidirectionalIterator move_rotate_right_by_one(BidirectionalIterator first, BidirectionalIterator last)\n\t\t{\n\t\t\ttypedef typename eastl::iterator_traits::value_type value_type;\n\n\t\t\tBidirectionalIterator beforeLast = eastl::prev(last);\n\t\t\tvalue_type temp(eastl::move(*beforeLast));\n\t\t\tBidirectionalIterator result = eastl::move_backward(first, beforeLast, last); // Note that while our template type is BidirectionalIterator, if the actual\n\t\t\t*first = eastl::move(temp); // iterator is a RandomAccessIterator then this move will be a memmove for trivially copyable types.\n\n\t\t\treturn result; // result points to the first element in the range.\n\t\t}\n\n\t\ttemplate \n\t\tstruct rotate_helper\n\t\t{\n\t\t\ttemplate \n\t\t\tstatic ForwardIterator rotate_impl(ForwardIterator first, ForwardIterator middle, ForwardIterator last)\n\t\t\t\t{ return Internal::rotate_general_impl(first, middle, last); }\n\t\t};\n\n\t\ttemplate <>\n\t\tstruct rotate_helper\n\t\t{\n\t\t\ttemplate \n\t\t\tstatic ForwardIterator rotate_impl(ForwardIterator first, ForwardIterator middle, ForwardIterator last)\n\t\t\t{\n\t\t\t\tif(eastl::next(first) == middle) // If moving trivial types by a single element, memcpy is fast for that case.\n\t\t\t\t\treturn Internal::move_rotate_left_by_one(first, last);\n\t\t\t\treturn Internal::rotate_general_impl(first, middle, last);\n\t\t\t}\n\t\t};\n\n\t\ttemplate <>\n\t\tstruct rotate_helper\n\t\t{\n\t\t\ttemplate \n\t\t\tstatic BidirectionalIterator rotate_impl(BidirectionalIterator first, BidirectionalIterator middle, BidirectionalIterator last)\n\t\t\t\t{ return Internal::rotate_general_impl(first, middle, last); } // rotate_general_impl outperforms the flipping hands algorithm.\n\n\t\t\t/*\n\t\t\t// Simplest \"flipping hands\" implementation. Disabled because it's slower on average than rotate_general_impl.\n\t\t\ttemplate \n\t\t\tstatic BidirectionalIterator rotate_impl(BidirectionalIterator first, BidirectionalIterator middle, BidirectionalIterator last)\n\t\t\t{\n\t\t\t\teastl::reverse(first, middle);\n\t\t\t\teastl::reverse(middle, last);\n\t\t\t\teastl::reverse(first, last);\n\t\t\t\treturn first + (last - middle); // This can be slow for large ranges because operator + and - are O(n).\n\t\t\t}\n\n\t\t\t// Smarter \"flipping hands\" implementation, but still disabled because benchmarks are showing it to be slower than rotate_general_impl.\n\t\t\ttemplate \n\t\t\tstatic BidirectionalIterator rotate_impl(BidirectionalIterator first, BidirectionalIterator middle, BidirectionalIterator last)\n\t\t\t{\n\t\t\t\t// This is the \"flipping hands\" algorithm.\n\t\t\t\teastl::reverse_impl(first, middle, eastl::bidirectional_iterator_tag()); // Reverse the left side.\n\t\t\t\teastl::reverse_impl(middle, last, eastl::bidirectional_iterator_tag()); // Reverse the right side.\n\n\t\t\t\t// Reverse the entire range.\n\t\t\t\twhile((first != middle) && (middle != last))\n\t\t\t\t{\n\t\t\t\t\teastl::iter_swap(first, --last);\n\t\t\t\t\t++first;\n\t\t\t\t}\n\n\t\t\t\tif(first == middle) // Finish reversing the entire range.\n\t\t\t\t{\n\t\t\t\t\teastl::reverse_impl(middle, last, bidirectional_iterator_tag());\n\t\t\t\t\treturn last;\n\t\t\t\t}\n\t\t\t\telse\n\t\t\t\t{\n\t\t\t\t\teastl::reverse_impl(first, middle, bidirectional_iterator_tag());\n\t\t\t\t\treturn first;\n\t\t\t\t}\n\t\t\t}\n\t\t\t*/\n\t\t};\n\n\t\ttemplate <>\n\t\tstruct rotate_helper\n\t\t{\n\t\t\ttemplate \n\t\t\tstatic BidirectionalIterator rotate_impl(BidirectionalIterator first, BidirectionalIterator middle, BidirectionalIterator last)\n\t\t\t{\n\t\t\t\tif(eastl::next(first) == middle) // If moving trivial types by a single element, memcpy is fast for that case.\n\t\t\t\t\treturn Internal::move_rotate_left_by_one(first, last);\n\t\t\t\tif(eastl::next(middle) == last)\n\t\t\t\t\treturn Internal::move_rotate_right_by_one(first, last);\n\t\t\t\treturn Internal::rotate_general_impl(first, middle, last);\n\t\t\t}\n\t\t};\n\n\t\ttemplate \n\t\tinline Integer greatest_common_divisor(Integer x, Integer y)\n\t\t{\n\t\t\tdo {\n\t\t\t\tInteger t = (x % y);\n\t\t\t\tx = y;\n\t\t\t\ty = t;\n\t\t\t} while(y);\n\n\t\t\treturn x;\n\t\t}\n\n\t\ttemplate <>\n\t\tstruct rotate_helper\n\t\t{\n\t\t\t// This is the juggling algorithm, using move operations.\n\t\t\t// In practice this implementation is about 25% faster than rotate_general_impl. We may want to\n\t\t\t// consider sticking with just rotate_general_impl and avoid the code generation of this function.\n\t\t\ttemplate \n\t\t\tstatic RandomAccessIterator rotate_impl(RandomAccessIterator first, RandomAccessIterator middle, RandomAccessIterator last)\n\t\t\t{\n\t\t\t\ttypedef typename iterator_traits::difference_type difference_type;\n\t\t\t\ttypedef typename iterator_traits::value_type value_type;\n\n\t\t\t\tconst difference_type m1 = (middle - first);\n\t\t\t\tconst difference_type m2 = (last - middle);\n\t\t\t\tconst difference_type g = Internal::greatest_common_divisor(m1, m2);\n\t\t\t\tvalue_type temp;\n\n\t\t\t\tfor(RandomAccessIterator p = first + g; p != first;)\n\t\t\t\t{\n\t\t\t\t\ttemp = eastl::move(*--p);\n\t\t\t\t\tRandomAccessIterator p1 = p;\n\t\t\t\t\tRandomAccessIterator p2 = p + m1;\n\t\t\t\t\tdo\n\t\t\t\t\t{\n\t\t\t\t\t\t*p1 = eastl::move(*p2);\n\t\t\t\t\t\tp1 = p2;\n\t\t\t\t\t\tconst difference_type d = (last - p2);\n\n\t\t\t\t\t\tif(m1 < d)\n\t\t\t\t\t\t\tp2 += m1;\n\t\t\t\t\t\telse\n\t\t\t\t\t\t\tp2 = first + (m1 - d);\n\t\t\t\t\t} while(p2 != p);\n\n\t\t\t\t\t*p1 = eastl::move(temp);\n\t\t\t\t}\n\n\t\t\t\treturn first + m2;\n\t\t\t}\n\t\t};\n\n\t\ttemplate <>\n\t\tstruct rotate_helper\n\t\t{\n\t\t\t// Experiments were done which tested the performance of using an intermediate buffer\n\t\t\t// to do memcpy's to as opposed to executing a swapping algorithm. It turns out this is\n\t\t\t// actually slower than even rotate_general_impl, partly because the average case involves\n\t\t\t// memcpy'ing a quarter of the element range twice. Experiments were done with various kinds\n\t\t\t// of PODs with various element counts.\n\n\t\t\ttemplate \n\t\t\tstatic RandomAccessIterator rotate_impl(RandomAccessIterator first, RandomAccessIterator middle, RandomAccessIterator last)\n\t\t\t{\n\t\t\t\tif(eastl::next(first) == middle) // If moving trivial types by a single element, memcpy is fast for that case.\n\t\t\t\t\treturn Internal::move_rotate_left_by_one(first, last);\n\t\t\t\tif(eastl::next(middle) == last)\n\t\t\t\t\treturn Internal::move_rotate_right_by_one(first, last);\n\t\t\t\tif((last - first) < 32) // For small ranges rotate_general_impl is faster.\n\t\t\t\t\treturn Internal::rotate_general_impl(first, middle, last);\n\t\t\t\treturn Internal::rotate_helper::rotate_impl(first, middle, last);\n\t\t\t}\n\t\t};\n\n\t} // namespace Internal\n\n\n\ttemplate \n\tForwardIterator rotate(ForwardIterator first, ForwardIterator middle, ForwardIterator last)\n\t{\n\t\tif(middle != first)\n\t\t{\n\t\t\tif(middle != last)\n\t\t\t{\n\t\t\t\ttypedef typename eastl::iterator_traits::iterator_category IC;\n\t\t\t\ttypedef typename eastl::iterator_traits::value_type value_type;\n\n\t\t\t\t// the implementations for is_trivially_copyable types simply check whether we have a single element to rotate and if so,\n\t\t\t\t// defer to either move_rotate_left_by_one or move_rotate_right_by_one, which are optimized for trivially copyable types.\n\t\t\t\t// otherwise, use the same implementation as non-trivially copyable types.\n\t\t\t\treturn Internal::rotate_helper::value>::rotate_impl(first, middle, last);\n\t\t\t}\n\n\t\t\treturn first;\n\t\t}\n\n\t\treturn last;\n\t}\n\n\n\n\t/// rotate_copy\n\t///\n\t/// Similar to rotate except writes the output to the OutputIterator and\n\t/// returns an OutputIterator to the element past the last element copied\n\t/// (i.e. result + (last - first))\n\t///\n\ttemplate \n\tOutputIterator rotate_copy(ForwardIterator first, ForwardIterator middle, ForwardIterator last, OutputIterator result)\n\t{\n\t\treturn eastl::copy(first, middle, eastl::copy(middle, last, result));\n\t}\n\n\n\n\t/// clamp\n\t///\n\t/// Returns a reference to a clamped value within the range of [lo, hi].\n\t///\n\t/// http://en.cppreference.com/w/cpp/algorithm/clamp\n\t///\n\ttemplate \n\tEA_CONSTEXPR const T& clamp(const T& v, const T& lo, const T& hi, Compare comp)\n\t{\n\t\tEASTL_ASSERT(!comp(hi, lo));\n\t\treturn comp(v, lo) ? lo : comp(hi, v) ? hi : v;\n\t}\n\n\ttemplate \n\tEA_CONSTEXPR const T& clamp(const T& v, const T& lo, const T& hi)\n\t{\n\t\treturn eastl::clamp(v, lo, hi, eastl::less<>());\n\t}\n\n\n\t/// is_partitioned\n\t///\n\t/// Returns true if all the elements in the range [first, last) is empty, or is\n\t/// partitioned by predicate. Being partitioned means that all elements v for which\n\t/// predicate(v) evaluates to true appear before any elements for which predicate(v)\n\t/// is false.\n\t///\n\ttemplate \n\tEA_CONSTEXPR bool is_partitioned(InputIterator first, InputIterator last, UnaryPredicate predicate)\n\t{\n\t\tfor (; first != last; ++first)\n\t\t{\n\t\t\tif (!predicate(*first))\n\t\t\t{\n\t\t\t\t// advance the iterator, we don't need to call the predicate on this item\n\t\t\t\t// again in the \"false\" loop below.\n\t\t\t\t++first;\n\t\t\t\tbreak;\n\t\t\t}\n\t\t}\n\t\tfor (; first != last; ++first)\n\t\t{\n\t\t\tif (predicate(*first))\n\t\t\t{\n\t\t\t\treturn false;\n\t\t\t}\n\t\t}\n\t\treturn true;\n\t}\n\n\t/// partition_point\n\t///\n\t/// Precondition: for this function to work correctly the input range [first, last)\n\t/// must be partitioned by the predicate. i.e. all values for which predicate(v) is\n\t/// true should precede any value in the range for which predicate(v) is false.\n\t///\n\t/// Returns: the iterator past the end of the first partition within [first, last) or\n\t/// last if all elements satisfy the predicate.\n\t///\n\t/// Note: this is a more general version of lower_bound.\n\ttemplate \n\tEA_CONSTEXPR ForwardIterator partition_point(ForwardIterator first, ForwardIterator last, UnaryPredicate predicate)\n\t{\n\t\t// Just binary chop our way to the first one where predicate(x) is false\n\t\tfor (auto length = eastl::distance(first, last); 0 < length;)\n\t\t{\n\t\t\tconst auto half = length / 2;\n\t\t\tconst auto middle = eastl::next(first, half);\n\t\t\tif (predicate(*middle))\n\t\t\t{\n\t\t\t\tfirst = eastl::next(middle);\n\t\t\t\tlength -= (half + 1);\n\t\t\t}\n\t\t\telse\n\t\t\t{\n\t\t\t\tlength = half;\n\t\t\t}\n\t\t}\n\n\t\treturn first;\n\t}\n\n} // namespace eastl\n\n\n#endif // Header include guard\n" }, { "path": "include/EASTL/allocator.h", "content": "/////////////////////////////////////////////////////////////////////////////\n// Copyright (c) Electronic Arts Inc. All rights reserved.\n/////////////////////////////////////////////////////////////////////////////\n\n\n#ifndef EASTL_ALLOCATOR_H\n#define EASTL_ALLOCATOR_H\n\n\n#include \n#include \n#include \n\n\n#if defined(EA_PRAGMA_ONCE_SUPPORTED)\n\t#pragma once // Some compilers (e.g. VC++) benefit significantly from using this. We've measured 3-4% build speed improvements in apps as a result.\n#endif\n\n\n\nnamespace eastl\n{\n\n\t/// alloc_flags\n\t///\n\t/// Defines allocation flags.\n\t///\n\tenum alloc_flags \n\t{\n\t\tMEM_TEMP = 0, // Low memory, not necessarily actually temporary.\n\t\tMEM_PERM = 1 // High memory, for things that won't be unloaded.\n\t};\n\n\n\t/// allocator\n\t///\n\t/// In this allocator class, note that it is not templated on any type and\n\t/// instead it simply allocates blocks of memory much like the C malloc and\n\t/// free functions. It can be thought of as similar to C++ std::allocator.\n\t/// The flags parameter has meaning that is specific to the allocation \n\t///\n\t/// C++11's std::allocator (20.6.9) doesn't have a move constructor or assignment \n\t/// operator. This is possibly because std::allocators are associated with types\n\t/// instead of as instances. The potential non-equivalance of C++ std::allocator\n\t/// instances has been a source of some acknowledged design problems.\n\t/// We don't implement support for move construction or assignment in eastl::allocator,\n\t/// but users can define their own allocators which do have move functions and \n\t/// the eastl containers are compatible with such allocators (i.e. nothing unexpected\n\t/// will happen).\n\t///\n\tclass EASTL_API allocator\n\t{\n\tpublic:\n\t\tEASTL_ALLOCATOR_EXPLICIT allocator(const char* pName = EASTL_NAME_VAL(EASTL_ALLOCATOR_DEFAULT_NAME));\n\t\tallocator(const allocator& x);\n\t\tallocator(const allocator& x, const char* pName);\n\n\t\tallocator& operator=(const allocator& x);\n\n\t\tvoid* allocate(size_t n, int flags = 0);\n\t\tvoid* allocate(size_t n, size_t alignment, size_t offset, int flags = 0);\n\t\tvoid deallocate(void* p, size_t n);\n\n\t\tconst char* get_name() const;\n\t\tvoid set_name(const char* pName);\n\n\tprotected:\n\t\t#if EASTL_NAME_ENABLED\n\t\t\tconst char* mpName; // Debug name, used to track memory.\n\t\t#endif\n\t};\n\n\tbool operator==(const allocator& a, const allocator& b);\n#if !defined(EA_COMPILER_HAS_THREE_WAY_COMPARISON)\n\tbool operator!=(const allocator& a, const allocator& b);\n#endif\n\n\n\t/// dummy_allocator\n\t///\n\t/// Defines an allocator which does nothing. It returns NULL from allocate calls.\n\t///\n\tclass EASTL_API dummy_allocator\n\t{\n\tpublic:\n\t\tEASTL_ALLOCATOR_EXPLICIT dummy_allocator(const char* = NULL) { }\n\t\tdummy_allocator(const dummy_allocator&) { }\n\t\tdummy_allocator(const dummy_allocator&, const char*) { }\n\n\t\tdummy_allocator& operator=(const dummy_allocator&) { return *this; }\n\n\t\tvoid* allocate(size_t, int = 0) { return NULL; }\n\t\tvoid* allocate(size_t, size_t, size_t, int = 0) { return NULL; }\n\t\tvoid deallocate(void*, size_t) { }\n\n\t\tconst char* get_name() const { return \"\"; }\n\t\tvoid set_name(const char*) { }\n\t};\n\n\tinline bool operator==(const dummy_allocator&, const dummy_allocator&) { return true; }\n#if !defined(EA_COMPILER_HAS_THREE_WAY_COMPARISON)\n\tinline bool operator!=(const dummy_allocator&, const dummy_allocator&) { return false; }\n#endif\n\n\n\t/// Defines a static default allocator which is constant across all types.\n\t/// This is different from get_default_allocator, which is is bound at\n\t/// compile-time and expected to differ per allocator type.\n\t/// Currently this Default Allocator applies only to CoreAllocatorAdapter.\n\t/// To consider: This naming of this function is too similar to get_default_allocator\n\t/// and instead should be named something like GetStaticDefaultAllocator.\n\tEASTL_API allocator* GetDefaultAllocator();\n\tEASTL_API allocator* SetDefaultAllocator(allocator* pAllocator);\n\n\n\t/// get_default_allocator\n\t///\n\t/// This templated function allows the user to implement a default allocator\n\t/// retrieval function that any part of EASTL can use. EASTL containers take\n\t/// an Allocator parameter which identifies an Allocator class to use. But \n\t/// different kinds of allocators have different mechanisms for retrieving \n\t/// a default allocator instance, and some don't even intrinsically support\n\t/// such functionality. The user can override this get_default_allocator \n\t/// function in order to provide the glue between EASTL and whatever their\n\t/// system's default allocator happens to be.\n\t///\n\t/// Example usage:\n\t/// MyAllocatorType* gpSystemAllocator;\n\t/// \n\t/// MyAllocatorType* get_default_allocator(const MyAllocatorType*)\n\t/// { return gpSystemAllocator; }\n\t///\n\ttemplate \n\tAllocator* get_default_allocator(const Allocator*);\n\n\tEASTLAllocatorType* get_default_allocator(const EASTLAllocatorType*);\n\n\n\t/// default_allocfreemethod\n\t///\n\t/// Implements a default allocfreemethod which uses the default global allocator.\n\t/// This version supports only default alignment.\n\t///\n\tvoid* default_allocfreemethod(size_t n, void* pBuffer, void* /*pContext*/);\n\n\n\t/// allocate_memory\n\t///\n\t/// This is a memory allocation dispatching function.\n\t/// To do: Make aligned and unaligned specializations.\n\t/// Note that to do this we will need to use a class with a static\n\t/// function instead of a standalone function like below.\n\t///\n\ttemplate \n\tvoid* allocate_memory(Allocator& a, size_t n, size_t alignment, size_t alignmentOffset);\n\n\n} // namespace eastl\n\n\n\n\n\n\n#ifndef EASTL_USER_DEFINED_ALLOCATOR // If the user hasn't declared that he has defined a different allocator implementation elsewhere...\n\n\tEA_DISABLE_ALL_VC_WARNINGS()\n\t#include \n\tEA_RESTORE_ALL_VC_WARNINGS()\n\n\t#if !EASTL_DLL // If building a regular library and not building EASTL as a DLL...\n\t\t// It is expected that the application define the following\n\t\t// versions of operator new for the application. Either that or the\n\t\t// user needs to override the implementation of the allocator class.\n\t\tvoid* operator new[](size_t size, const char* pName, int flags, unsigned debugFlags, const char* file, int line);\n\t\tvoid* operator new[](size_t size, size_t alignment, size_t alignmentOffset, const char* pName, int flags, unsigned debugFlags, const char* file, int line);\n\t#endif\n\n\tnamespace eastl\n\t{\n\t\tinline allocator::allocator(const char* EASTL_NAME(pName))\n\t\t{\n\t\t\t#if EASTL_NAME_ENABLED\n\t\t\t\tmpName = pName ? pName : EASTL_ALLOCATOR_DEFAULT_NAME;\n\t\t\t#endif\n\t\t}\n\n\n\t\tinline allocator::allocator(const allocator& EASTL_NAME(alloc))\n\t\t{\n\t\t\t#if EASTL_NAME_ENABLED\n\t\t\t\tmpName = alloc.mpName;\n\t\t\t#endif\n\t\t}\n\n\n\t\tinline allocator::allocator(const allocator&, const char* EASTL_NAME(pName))\n\t\t{\n\t\t\t#if EASTL_NAME_ENABLED\n\t\t\t\tmpName = pName ? pName : EASTL_ALLOCATOR_DEFAULT_NAME;\n\t\t\t#endif\n\t\t}\n\n\n\t\tinline allocator& allocator::operator=(const allocator& EASTL_NAME(alloc))\n\t\t{\n\t\t\t#if EASTL_NAME_ENABLED\n\t\t\t\tmpName = alloc.mpName;\n\t\t\t#endif\n\t\t\treturn *this;\n\t\t}\n\n\n\t\tinline const char* allocator::get_name() const\n\t\t{\n\t\t\t#if EASTL_NAME_ENABLED\n\t\t\t\treturn mpName;\n\t\t\t#else\n\t\t\t\treturn EASTL_ALLOCATOR_DEFAULT_NAME;\n\t\t\t#endif\n\t\t}\n\n\n\t\tinline void allocator::set_name(const char* EASTL_NAME(pName))\n\t\t{\n\t\t\t#if EASTL_NAME_ENABLED\n\t\t\t\tmpName = pName;\n\t\t\t#endif\n\t\t}\n\n\n\t\tinline void* allocator::allocate(size_t n, int flags)\n\t\t{\n\t\t\t#if EASTL_NAME_ENABLED\n\t\t\t\t#define pName mpName\n\t\t\t#else\n\t\t\t\t#define pName EASTL_ALLOCATOR_DEFAULT_NAME\n\t\t\t#endif\n\n\t\t\t#if EASTL_DLL\n\t\t\t\treturn allocate(n, EASTL_SYSTEM_ALLOCATOR_MIN_ALIGNMENT, 0, flags);\n\t\t\t#elif (EASTL_DEBUGPARAMS_LEVEL <= 0)\n\t\t\t\treturn ::new((char*)0, flags, 0, (char*)0, 0) char[n];\n\t\t\t#elif (EASTL_DEBUGPARAMS_LEVEL == 1)\n\t\t\t\treturn ::new( pName, flags, 0, (char*)0, 0) char[n];\n\t\t\t#else\n\t\t\t\treturn ::new( pName, flags, 0, __FILE__, __LINE__) char[n];\n\t\t\t#endif\n\t\t}\n\n\n\t\tinline void* allocator::allocate(size_t n, size_t alignment, size_t offset, int flags)\n\t\t{\n\t\t\t#if EASTL_DLL\n\t\t\t\t// We currently have no support for implementing flags when \n\t\t\t\t// using the C runtime library operator new function. The user \n\t\t\t\t// can use SetDefaultAllocator to override the default allocator.\n\t\t\t\tEA_UNUSED(offset); EA_UNUSED(flags);\n\n\t\t\t\tsize_t adjustedAlignment = (alignment > EA_PLATFORM_PTR_SIZE) ? alignment : EA_PLATFORM_PTR_SIZE;\n\n\t\t\t\tvoid* p = new char[n + adjustedAlignment + EA_PLATFORM_PTR_SIZE];\n\t\t\t\tvoid* pPlusPointerSize = (void*)((uintptr_t)p + EA_PLATFORM_PTR_SIZE);\n\t\t\t\tvoid* pAligned = (void*)(((uintptr_t)pPlusPointerSize + adjustedAlignment - 1) & ~(adjustedAlignment - 1));\n\n\t\t\t\tvoid** pStoredPtr = (void**)pAligned - 1;\n\t\t\t\tEASTL_ASSERT(pStoredPtr >= p);\n\t\t\t\t*(pStoredPtr) = p;\n\n\t\t\t\tEASTL_ASSERT(((size_t)pAligned & ~(alignment - 1)) == (size_t)pAligned);\n\n\t\t\t\treturn pAligned;\n\t\t\t#elif (EASTL_DEBUGPARAMS_LEVEL <= 0)\n\t\t\t\treturn ::new(alignment, offset, (char*)0, flags, 0, (char*)0, 0) char[n];\n\t\t\t#elif (EASTL_DEBUGPARAMS_LEVEL == 1)\n\t\t\t\treturn ::new(alignment, offset, pName, flags, 0, (char*)0, 0) char[n];\n\t\t\t#else\n\t\t\t\treturn ::new(alignment, offset, pName, flags, 0, __FILE__, __LINE__) char[n];\n\t\t\t#endif\n\n\t\t\t#undef pName // See above for the definition of this.\n\t\t}\n\n\n\t\tinline void allocator::deallocate(void* p, size_t)\n\t\t{\n\t\t\t#if EASTL_DLL\n\t\t\t\tif (p != nullptr)\n\t\t\t\t{\n\t\t\t\t\tvoid* pOriginalAllocation = *((void**)p - 1);\n\t\t\t\t\tdelete[](char*)pOriginalAllocation;\n\t\t\t\t}\n\t\t\t#else\n\t\t\t\tdelete[](char*)p;\n\t\t\t#endif\n\t\t}\n\n\n\t\tinline bool operator==(const allocator&, const allocator&)\n\t\t{\n\t\t\treturn true; // All allocators are considered equal, as they merely use global new/delete.\n\t\t}\n\n#if !defined(EA_COMPILER_HAS_THREE_WAY_COMPARISON)\n\t\tinline bool operator!=(const allocator&, const allocator&)\n\t\t{\n\t\t\treturn false; // All allocators are considered equal, as they merely use global new/delete.\n\t\t}\n#endif\n\n\t} // namespace eastl\n\n\n#endif // EASTL_USER_DEFINED_ALLOCATOR\n\n\n\nnamespace eastl\n{\n\n\ttemplate \n\tinline Allocator* get_default_allocator(const Allocator*)\n\t{\n\t\treturn NULL; // By default we return NULL; the user must make specialization of this function in order to provide their own implementation.\n\t}\n\n\n\tinline EASTLAllocatorType* get_default_allocator(const EASTLAllocatorType*)\n\t{\n\t\treturn EASTLAllocatorDefault(); // For the built-in allocator EASTLAllocatorType, we happen to already have a function for returning the default allocator instance, so we provide it.\n\t}\n\n\n\tinline void* default_allocfreemethod(size_t n, void* pBuffer, void* /*pContext*/)\n\t{\n\t\tEASTLAllocatorType* const pAllocator = EASTLAllocatorDefault();\n\n\t\tif(pBuffer) // If freeing...\n\t\t{\n\t\t\tEASTLFree(*pAllocator, pBuffer, n);\n\t\t\treturn NULL; // The return value is meaningless for the free.\n\t\t}\n\t\telse // allocating\n\t\t\treturn EASTLAlloc(*pAllocator, n);\n\t}\n\n\n\t/// allocate_memory\n\t///\n\t/// This is a memory allocation dispatching function.\n\t/// To do: Make aligned and unaligned specializations.\n\t/// Note that to do this we will need to use a class with a static\n\t/// function instead of a standalone function like below.\n\t///\n\ttemplate \n\tinline void* allocate_memory(Allocator& a, size_t n, size_t alignment, size_t alignmentOffset)\n\t{\n\t\tvoid *result;\n\t\tif (alignment <= EASTL_ALLOCATOR_MIN_ALIGNMENT)\n\t\t{\n\t\t\tresult = EASTLAlloc(a, n);\n\t\t\t// Ensure the result is correctly aligned. An assertion likely indicates a mismatch between EASTL_ALLOCATOR_MIN_ALIGNMENT and the minimum alignment\n\t\t\t// of EASTLAlloc. If there is a mismatch it may be necessary to define EASTL_ALLOCATOR_MIN_ALIGNMENT to be the minimum alignment of EASTLAlloc, or\n\t\t\t// to increase the alignment of EASTLAlloc to match EASTL_ALLOCATOR_MIN_ALIGNMENT.\n\t\t\tEASTL_ASSERT((reinterpret_cast(result)& ~(alignment - 1)) == reinterpret_cast(result));\n\t\t}\n\t\telse\n\t\t{\n\t\t\tresult = EASTLAllocAligned(a, n, alignment, alignmentOffset);\n\t\t\t// Ensure the result is correctly aligned. An assertion here may indicate a bug in the allocator.\n\t\t\tauto resultMinusOffset = (char*)result - alignmentOffset;\n\t\t\tEA_UNUSED(resultMinusOffset);\n\t\t\tEASTL_ASSERT((reinterpret_cast(resultMinusOffset)& ~(alignment - 1)) == reinterpret_cast(resultMinusOffset));\n\t\t}\n\t\treturn result;\n\t}\n\n}\n\n\n#endif // Header include guard\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n" }, { "path": "include/EASTL/allocator_malloc.h", "content": "/////////////////////////////////////////////////////////////////////////////\n// Copyright (c) Electronic Arts Inc. All rights reserved.\n/////////////////////////////////////////////////////////////////////////////\n\n\n#ifndef EASTL_ALLOCATOR_MALLOC_H\n#define EASTL_ALLOCATOR_MALLOC_H\n\n\n#include \n#include \n#include \n\n\n// EASTL_ALIGNED_MALLOC_AVAILABLE\n//\n// Identifies if the standard library provides a built-in aligned version of malloc.\n// Defined as 0 or 1, depending on the standard library or platform availability.\n// None of the viable C functions provides for an aligned malloc with offset, so we \n// don't consider that supported in any case.\n//\n// Options for aligned allocations:\n// C11 aligned_alloc http://linux.die.net/man/3/aligned_alloc\n// glibc memalign http://linux.die.net/man/3/posix_memalign\n// Posix posix_memalign http://pubs.opengroup.org/onlinepubs/000095399/functions/posix_memalign.html\n// VC++ _aligned_malloc http://msdn.microsoft.com/en-us/library/8z34s9c6%28VS.80%29.aspx This is not suitable, since it has a limitation that you need to free via _aligned_free.\n//\n#if !defined EASTL_ALIGNED_MALLOC_AVAILABLE\n\t#if defined(EA_PLATFORM_POSIX) && !defined(EA_PLATFORM_APPLE)\n\t\t// memalign is more consistently available than posix_memalign, though its location isn't consistent across \n\t\t// platforms and compiler libraries. Typically it's declared in one of three headers: stdlib.h, malloc.h, or malloc/malloc.h\n\t\t#include // memalign, posix_memalign. \n\t\t#define EASTL_ALIGNED_MALLOC_AVAILABLE 1\n\n\t\t#if EA_HAS_INCLUDE_AVAILABLE\n\t\t\t#if EA_HAS_INCLUDE()\n\t\t\t\t#include \n\t\t\t#elif EA_HAS_INCLUDE()\n\t\t\t\t#include \n\t\t\t#endif\n\t\t#elif defined(EA_PLATFORM_BSD)\n\t\t\t#include \n\t\t#elif defined(__clang__)\n\t\t\t#if __has_include()\n\t\t\t\t#include \n\t\t\t#elif __has_include()\n\t\t\t\t#include \n\t\t\t#endif\n\t\t#else\n\t\t\t#include \n\t\t#endif\n\t#else\n\t\t#define EASTL_ALIGNED_MALLOC_AVAILABLE 0\n\t#endif\n#endif\n\n\nnamespace eastl\n{\n\n\t///////////////////////////////////////////////////////////////////////////////\n\t// allocator_malloc\n\t//\n\t// Implements an EASTL allocator that uses malloc/free as opposed to \n\t// new/delete or PPMalloc Malloc/Free. \n\t//\n\t// Example usage:\n\t// vector intVector;\n\t// \n\tclass allocator_malloc\n\t{\n\tpublic:\n\t\tallocator_malloc(const char* = NULL)\n\t\t\t{ }\n\n\t\tallocator_malloc(const allocator_malloc&)\n\t\t\t{ }\n\n\t\tallocator_malloc(const allocator_malloc&, const char*)\n\t\t\t{ }\n\n\t\tallocator_malloc& operator=(const allocator_malloc&)\n\t\t\t{ return *this; }\n\n\t\tbool operator==(const allocator_malloc&)\n\t\t\t{ return true; }\n\n\t\tbool operator!=(const allocator_malloc&)\n\t\t\t{ return false; }\n\n\t\tvoid* allocate(size_t n, int /*flags*/ = 0)\n\t\t\t{ return malloc(n); }\n\n\t\tvoid* allocate(size_t n, size_t alignment, size_t alignmentOffset, int /*flags*/ = 0)\n\t\t{ \n\t\t\t#if EASTL_ALIGNED_MALLOC_AVAILABLE\n\t\t\t\tif((alignmentOffset % alignment) == 0) // We check for (offset % alignmnent == 0) instead of (offset == 0) because any block which is aligned on e.g. 64 also is aligned at an offset of 64 by definition. \n\t\t\t\t\treturn memalign(alignment, n); // memalign is more consistently available than posix_memalign.\n\t\t\t#else\n\t\t\t\tif((alignment <= EASTL_SYSTEM_ALLOCATOR_MIN_ALIGNMENT) && ((alignmentOffset % alignment) == 0))\n\t\t\t\t\treturn malloc(n);\n\t\t\t#endif\n\t\t\treturn NULL;\n\t\t}\n\n\t\tvoid deallocate(void* p, size_t /*n*/)\n\t\t\t{ free(p); }\n\n\t\tconst char* get_name() const\n\t\t\t{ return \"allocator_malloc\"; }\n\n\t\tvoid set_name(const char*)\n\t\t\t{ }\n\t};\n\n\n} // namespace eastl\n\n\n\n#endif // Header include guard\n\n\n\n\n\n\n\n\n\n" }, { "path": "include/EASTL/any.h", "content": "/////////////////////////////////////////////////////////////////////////////\n// Copyright (c) Electronic Arts Inc. All rights reserved.\n/////////////////////////////////////////////////////////////////////////////\n\n\n///////////////////////////////////////////////////////////////////////////////\n// This file implements the eastl::any which is part of the C++ standard STL\n// library specification. \n//\n// eastl::any is a type-safe container for single values of any type. Our\n// implementation makes use of the \"small local buffer\" optimization to avoid\n// unnecessary dynamic memory allocation if the specified type is eligible to\n// be stored in its local buffer. The user type must satisfy the size\n// requirements and must be no-throw move-constructible to qualify for the local\n// buffer optimization.\n//\n// To consider: Implement a fixed_any variant to allow users to customize\n// the size of the \"small local buffer\" optimization.\n//\n// http://en.cppreference.com/w/cpp/utility/any\n///////////////////////////////////////////////////////////////////////////////\n\n\n#ifndef EASTL_ANY_H\n#define EASTL_ANY_H\n\n#if defined(EA_PRAGMA_ONCE_SUPPORTED)\n\t#pragma once // Some compilers (e.g. VC++) benefit significantly from using this. We've measured 3-4% build speed improvements in apps as a result.\n#endif\n\n#include \n#include \n#if EASTL_RTTI_ENABLED\n\t#include \n#endif\n#if EASTL_EXCEPTIONS_ENABLED\n\t#include \n#endif\n\n\nnamespace eastl\n{\n\t///////////////////////////////////////////////////////////////////////////////\n\t// bad_any_cast\n\t// \n\t// The type thrown by any_cast on failure.\n\t//\n\t// http://en.cppreference.com/w/cpp/utility/any/bad_any_cast\n\t//\n\t#if EASTL_EXCEPTIONS_ENABLED\n\tstruct bad_cast : std::exception\n\t{\n\t\tconst char* what() const EA_NOEXCEPT EA_OVERRIDE\n\t\t\t{ return \"bad cast\"; }\n\t};\n\n\tstruct bad_any_cast : public bad_cast \n\t{\n\t\tconst char* what() const EA_NOEXCEPT EA_OVERRIDE\n\t\t\t{ return \"bad_any_cast\"; }\n\t};\n #endif\n\n\tnamespace Internal\n\t{\n\t\t// utility to switch between exceptions and asserts\n\t\tinline void DoBadAnyCast()\n\t\t{\n\t\t\t#if EASTL_EXCEPTIONS_ENABLED\n\t\t\t\tthrow bad_any_cast();\n\t\t\t#else\n\t\t\t\tEASTL_ASSERT_MSG(false, \"bad_any_cast\\n\");\n\n\t\t\t\t// NOTE(rparolin): CRASH!\n\t\t\t\t// You crashed here because you requested a type that was not contained in the object.\n\t\t\t\t// We choose to intentionally crash here instead of returning invalid data to the calling \n\t\t\t\t// code which could cause hard to track down bugs. \n\t\t\t\t*((volatile int*)0) = 0xDEADC0DE;\n\t\t\t#endif\n\t\t}\n\n\t\ttemplate\n\t\tvoid* DefaultConstruct(Args&&... args)\n\t\t{\n\t\t\tauto* pMem = EASTLAllocatorDefault()->allocate(sizeof(T), alignof(T), 0);\n\n\t\t\treturn ::new(pMem) T(eastl::forward(args)...);\n\t\t}\n\n\t\ttemplate\n\t\tvoid DefaultDestroy(T* p)\n\t\t{\n\t\t\tp->~T();\n\n\t\t\tEASTLAllocatorDefault()->deallocate(static_cast(p), sizeof(T));\n\t\t}\n\t}\n\n\n\t///////////////////////////////////////////////////////////////////////////////\n\t// 20.7.3, class any\n\t//\n\tclass any\n\t{\n\t\t//////////////////////////////////////////////////////////////////////////////////////////\n\t\t// storage_operation \n\t\t//\n\t\t// operations supported by the storage handler \n\t\t//\n\t\tenum class storage_operation\n\t\t{\n\t\t\tGET,\n\t\t\tDESTROY,\n\t\t\tCOPY,\n\t\t\tMOVE,\n\t\t\tTYPE_INFO\n\t\t};\n\n\n\t\t//////////////////////////////////////////////////////////////////////////////////////////\n\t\t// storage \n\t\t//\n\t\t// the underlying storage type which enables the switching between objects stored in\n\t\t// the heap and objects stored within the any type.\n\t\t//\n\t\tunion storage\n\t\t{\n\t\t\ttypedef aligned_storage_t<4 * sizeof(void*), alignment_of::value> internal_storage_t;\n\n\t\t\tvoid* external_storage = nullptr;\n\t\t\tinternal_storage_t internal_storage;\n\t\t};\n\n\n\t\t//////////////////////////////////////////////////////////////////////////////////////////\n\t\t// use_internal_storage \n\t\t//\n\t\t// determines when the \"local buffer optimization\" is used \n\t\t//\n\t\ttemplate \n\t\tusing use_internal_storage = bool_constant\n\t\t<\n\t\t\tis_nothrow_move_constructible::value \n\t\t\t&& (sizeof(T) <= sizeof(storage)) &&\n\t\t\t(alignment_of::value % alignment_of::value == 0) \n\t\t>;\n\n\n\t\t//////////////////////////////////////////////////////////////////////////////////////////\n\t\t// non-member friend functions\t\n\t\t//\n \ttemplate friend const ValueType* any_cast(const any* pAny) EA_NOEXCEPT;\n\t\ttemplate friend ValueType* any_cast(any* pAny) EA_NOEXCEPT; \n\t\ttemplate friend ValueType any_cast(const any& operand);\n\t\ttemplate friend ValueType any_cast(any& operand);\n\t\ttemplate friend ValueType any_cast(any&& operand);\n\n\t\t//Adding Unsafe any cast operations\n\t\ttemplate friend const ValueType* unsafe_any_cast(const any* pAny) EA_NOEXCEPT;\n\t\ttemplate friend ValueType* unsafe_any_cast(any* pAny) EA_NOEXCEPT;\n\n\n\t\t//////////////////////////////////////////////////////////////////////////////////////////\n\t\t// internal storage handler\n\t\t//\n\t\ttemplate \n\t\tstruct storage_handler_internal\n\t\t{\n\t\t\ttemplate \n\t\t\tstatic void construct(storage& s, V&& v)\n\t\t\t{\n\t\t\t\t::new(&s.internal_storage) T(eastl::forward(v));\n\t\t\t}\n\n\t\t\ttemplate \n\t\t\tstatic void construct_inplace(storage& s, Args... args)\n\t\t\t{\n\t\t\t\t::new(&s.internal_storage) T(eastl::forward(args)...);\n\t\t\t}\n\n\t\t\ttemplate \n\t\t\tstatic void construct_inplace(storage& s, std::initializer_list il, Args&&... args)\n\t\t\t{\n\t\t\t\t::new(&s.internal_storage) NT(il, eastl::forward(args)...);\n\t\t\t}\n\n\t\t\tstatic inline void destroy(any& refAny)\n\t\t\t{\n\t\t\t\tT& t = *static_cast(static_cast(&refAny.m_storage.internal_storage));\n\t\t\t\tEA_UNUSED(t);\n\t\t\t\tt.~T();\n\n\t\t\t\trefAny.m_handler = nullptr;\n\t\t\t}\n\n\t\t\tstatic void* get(const any* pThis)\n\t\t\t{\n\t\t\t\tEASTL_ASSERT(pThis);\n\t\t\t\treturn (void*)(&pThis->m_storage.internal_storage);\n\t\t\t}\n\n\t\t\tstatic void* handler_func(storage_operation op, const any* pThis, any* pOther)\n\t\t\t{\n\t\t\t\tswitch (op)\n\t\t\t\t{\n\t\t\t\t\tcase storage_operation::GET:\n\t\t\t\t\t{\n\t\t\t\t\t\treturn get(pThis);\n\t\t\t\t\t}\n\t\t\t\t\tbreak;\n\n\t\t\t\t\tcase storage_operation::DESTROY:\n\t\t\t\t\t{\n\t\t\t\t\t\tEASTL_ASSERT(pThis);\n\t\t\t\t\t\tdestroy(const_cast(*pThis));\n\t\t\t\t\t}\n\t\t\t\t\tbreak;\n\n\t\t\t\t\tcase storage_operation::COPY:\n\t\t\t\t\t{\n\t\t\t\t\t\tEASTL_ASSERT(pThis);\n\t\t\t\t\t\tEASTL_ASSERT(pOther);\n\t\t\t\t\t\tconstruct(pOther->m_storage, *(T*)(&pThis->m_storage.internal_storage));\n\t\t\t\t\t}\n\t\t\t\t\tbreak;\n\n\t\t\t\t\tcase storage_operation::MOVE:\n\t\t\t\t\t{\n\t\t\t\t\t\tEASTL_ASSERT(pThis);\n\t\t\t\t\t\tEASTL_ASSERT(pOther);\n\t\t\t\t\t\tconstruct(pOther->m_storage, eastl::move(*(T*)(&pThis->m_storage.internal_storage)));\n\t\t\t\t\t\tdestroy(const_cast(*pThis));\n\t\t\t\t\t}\n\t\t\t\t\tbreak;\n\n\t\t\t\t\tcase storage_operation::TYPE_INFO:\n\t\t\t\t\t{\n\t\t\t\t\t#if EASTL_RTTI_ENABLED\n\t\t\t\t\t\treturn (void*)&typeid(T);\n\t\t\t\t\t#endif\n\t\t\t\t\t}\n\t\t\t\t\tbreak;\n\n\t\t\t\t\tdefault:\n\t\t\t\t\t{\n\t\t\t\t\t\tEASTL_ASSERT_MSG(false, \"unknown storage operation\\n\");\n\t\t\t\t\t}\n\t\t\t\t\tbreak;\n\t\t\t\t};\n\n\t\t\t\treturn nullptr;\n\t\t\t}\n\t\t};\n\n\n\n\t\t//////////////////////////////////////////////////////////////////////////////////////////\n\t\t// external storage handler\n\t\t//\n\t\ttemplate \n\t\tstruct storage_handler_external\n\t\t{\n\t\t\ttemplate \n\t\t\tstatic inline void construct(storage& s, V&& v) \n\t\t\t{\n\t\t\t\ts.external_storage = Internal::DefaultConstruct(eastl::forward(v));\n\t\t\t}\n\n\t\t\ttemplate \n\t\t\tstatic inline void construct_inplace(storage& s, Args... args)\n\t\t\t{\n\t\t\t\ts.external_storage = Internal::DefaultConstruct(eastl::forward(args)...);\n\t\t\t}\n\n\t\t\ttemplate \n\t\t\tstatic inline void construct_inplace(storage& s, std::initializer_list il, Args&&... args)\n\t\t\t{\n\t\t\t\ts.external_storage = Internal::DefaultConstruct(il, eastl::forward(args)...);\n\t\t\t}\n\n\t\t\tstatic inline void destroy(any& refAny)\n\t\t\t{\n\t\t\t\tInternal::DefaultDestroy(static_cast(refAny.m_storage.external_storage));\n\n\t\t\t\trefAny.m_handler = nullptr;\n\t\t\t}\n\n\t\t\tstatic void* get(const any* pThis)\n\t\t\t{\n\t\t\t\tEASTL_ASSERT(pThis);\n\t\t\t\tEASTL_ASSERT(pThis->m_storage.external_storage);\n\t\t\t\treturn static_cast(pThis->m_storage.external_storage);\n\t\t\t}\n\n\t\t\tstatic void* handler_func(storage_operation op, const any* pThis, any* pOther)\n\t\t\t{\n\t\t\t\tswitch (op)\n\t\t\t\t{\n\t\t\t\t\tcase storage_operation::GET:\n\t\t\t\t\t{\n\t\t\t\t\t\treturn get(pThis);\n\t\t\t\t\t}\n\t\t\t\t\tbreak;\n\n\t\t\t\t\tcase storage_operation::DESTROY:\n\t\t\t\t\t{\n\t\t\t\t\t\tEASTL_ASSERT(pThis);\n\t\t\t\t\t\tdestroy(*const_cast(pThis));\n\t\t\t\t\t}\n\t\t\t\t\tbreak;\n\n\t\t\t\t\tcase storage_operation::COPY:\n\t\t\t\t\t{\n\t\t\t\t\t\tEASTL_ASSERT(pThis);\n\t\t\t\t\t\tEASTL_ASSERT(pOther);\n\t\t\t\t\t\tconstruct(pOther->m_storage, *static_cast(pThis->m_storage.external_storage));\n\t\t\t\t\t}\n\t\t\t\t\tbreak;\n\n\t\t\t\t\tcase storage_operation::MOVE:\n\t\t\t\t\t{\n\t\t\t\t\t\tEASTL_ASSERT(pThis);\n\t\t\t\t\t\tEASTL_ASSERT(pOther);\n\t\t\t\t\t\tconstruct(pOther->m_storage, eastl::move(*(T*)(pThis->m_storage.external_storage)));\n\t\t\t\t\t\tdestroy(const_cast(*pThis));\n\t\t\t\t\t}\n\t\t\t\t\tbreak;\n\n\t\t\t\t\tcase storage_operation::TYPE_INFO:\n\t\t\t\t\t{\n\t\t\t\t\t#if EASTL_RTTI_ENABLED\n\t\t\t\t\t\treturn (void*)&typeid(T);\n\t\t\t\t\t#endif\n\t\t\t\t\t}\n\t\t\t\t\tbreak;\n\n\t\t\t\t\tdefault:\n\t\t\t\t\t{\n\t\t\t\t\t\tEASTL_ASSERT_MSG(false, \"unknown storage operation\\n\");\n\t\t\t\t\t}\n\t\t\t\t\tbreak;\n\t\t\t\t};\n\n\t\t\t\treturn nullptr;\n\t\t\t}\n\t\t};\n\n\n\t\t//////////////////////////////////////////////////////////////////////////////////////////\n\t\t// storage_handler_ptr \n\t\t//\n\t\t// defines the function signature of the storage handler that both the internal and\n\t\t// external storage handlers must implement to retrieve the underlying type of the any\n\t\t// object.\n\t\t//\n\t\tusing storage_handler_ptr = void* (*)(storage_operation, const any*, any*);\n\n\n\t\t//////////////////////////////////////////////////////////////////////////////////////////\n\t\t// storage_handler \n\t\t//\n\t\t// based on the specified type T we select the appropriate underlying storage handler\n\t\t// based on the 'use_internal_storage' trait.\n\t\t//\n\t\ttemplate \n\t\tusing storage_handler = typename conditional::value,\n\t\t storage_handler_internal,\n\t\t storage_handler_external>::type;\n\n\n\t\t//////////////////////////////////////////////////////////////////////////////////////////\n\t\t// data layout\n\t\t//\n\t\tstorage m_storage;\n\t\tstorage_handler_ptr m_handler;\n\n\tpublic:\n\t\t\t#ifndef EA_COMPILER_GNUC\n\t\t\t\t// TODO(rparolin): renable constexpr for GCC\n\t\t\t\tEA_CONSTEXPR \n\t\t\t#endif\n\t\t\tany() EA_NOEXCEPT \n\t\t\t: m_storage(), m_handler(nullptr) {}\n\n\t\tany(const any& other) : m_handler(nullptr)\n\t\t{\n\t\t\tif (other.m_handler)\n\t\t\t{\n\t\t\t\t// NOTE(rparolin): You can not simply copy the underlying\n\t\t\t\t// storage because it could hold a pointer to an object on the\n\t\t\t\t// heap which breaks the copy semantics of the language. \n\t\t\t\tother.m_handler(storage_operation::COPY, &other, this);\n\t\t\t\tm_handler = other.m_handler;\n\t\t\t}\n\t\t}\n\n\t\tany(any&& other) EA_NOEXCEPT : m_handler(nullptr)\n\t\t{ \n\t\t\tif(other.m_handler)\n\t\t\t{\n\t\t\t\t// NOTE(rparolin): You can not simply move the underlying\n\t\t\t\t// storage because because the storage class has effectively\n\t\t\t\t// type erased user type so we have to defer to the handler\n\t\t\t\t// function to get the type back and pass on the move request.\n\t\t\t\tm_handler = eastl::move(other.m_handler);\n\t\t\t\tother.m_handler(storage_operation::MOVE, &other, this);\n\t\t\t}\n\t\t}\n\n\t\t~any() { reset(); }\n\n\t\ttemplate \n\t\tany(ValueType&& value,\n\t\t typename eastl::enable_if::type, any>::value>::type* = 0)\n\t\t{\n\t\t\ttypedef decay_t DecayedValueType;\n\t\t\tstatic_assert(is_copy_constructible::value, \"ValueType must be copy-constructible\");\n\t\t\tstorage_handler::construct(m_storage, eastl::forward(value));\n\t\t\tm_handler = &storage_handler::handler_func;\n\t\t}\n\n\t\ttemplate \n\t\texplicit any(in_place_type_t, Args&&... args) \n\t\t{\n\t\t\ttypedef storage_handler> StorageHandlerT;\n\t\t\tstatic_assert(eastl::is_constructible::value, \"T must be constructible with Args...\");\n\n\t\t\tStorageHandlerT::construct_inplace(m_storage, eastl::forward(args)...);\n\t\t\tm_handler = &StorageHandlerT::handler_func;\n\t\t}\n\n\t\ttemplate \n\t\texplicit any(in_place_type_t,\n\t\t std::initializer_list il,\n\t\t Args&&... args,\n\t\t typename eastl::enable_if&, Args...>::value,\n\t\t void>::type* = 0)\n\t\t{\n\t\t\ttypedef storage_handler> StorageHandlerT;\n\n\t\t\tStorageHandlerT::construct_inplace(m_storage, il, eastl::forward(args)...);\n\t\t\tm_handler = &StorageHandlerT::handler_func;\n\t\t}\n\n\t\t// 20.7.3.2, assignments\n\t\ttemplate \n\t\tany& operator=(ValueType&& value)\n\t\t{\n\t\t\tstatic_assert(is_copy_constructible>::value, \"ValueType must be copy-constructible\");\n\t\t\tany(eastl::forward(value)).swap(*this);\n\t\t\treturn *this;\n\t\t}\n\n\t\tany& operator=(const any& other) \n\t\t{ \n\t\t\tany(other).swap(*this);\n\t\t\treturn *this; \n\t\t}\n\n\t\tany& operator=(any&& other) EA_NOEXCEPT \n\t\t{ \n\t\t\tany(eastl::move(other)).swap(*this);\n\t\t\treturn *this; \n\t\t}\n\n // 20.7.3.3, modifiers\n\t\t#if EASTL_VARIADIC_TEMPLATES_ENABLED\n\t\t\ttemplate \n\t\t\ttypename eastl::enable_if, Args...> && eastl::is_copy_constructible_v>, eastl::decay_t&>::type\n\t\t\templace(Args&&... args)\n\t\t\t{\n\t\t\t typedef storage_handler> StorageHandlerT;\n\n\t\t\t reset();\n\t\t\t\tStorageHandlerT::construct_inplace(m_storage, eastl::forward(args)...);\n\t\t\t\tm_handler = &StorageHandlerT::handler_func;\n\t\t\t\treturn *static_cast*>(StorageHandlerT::get(this));\n\t\t\t}\n\n\t\t\ttemplate \n\t\t typename eastl::enable_if, std::initializer_list&, Args...> && eastl::is_copy_constructible_v>, eastl::decay_t&>::type\n\t\t\templace(std::initializer_list il, Args&&... args)\n\t\t\t{\n\t\t\t typedef storage_handler> StorageHandlerT;\n\n\t\t\t\treset();\n\t\t\t\tStorageHandlerT::construct_inplace(m_storage, il, eastl::forward(args)...);\n\t\t\t\tm_handler = &StorageHandlerT::handler_func;\n\t\t\t\treturn *static_cast*>(StorageHandlerT::get(this));\n\t\t\t}\n #endif\n\n\t\tvoid reset() EA_NOEXCEPT \n\t\t{\n\t\t\tif(m_handler)\n\t\t\t\tm_handler(storage_operation::DESTROY, this, nullptr);\n\t\t}\n\n\t\tvoid swap(any& other) EA_NOEXCEPT \n\t\t{\n\t\t\tif(this == &other)\n\t\t\t\treturn;\n\n\t\t\tif(m_handler && other.m_handler)\n\t\t\t{\n\t\t\t\tany tmp;\n\t\t\t\ttmp.m_handler = other.m_handler;\n\t\t\t\tother.m_handler(storage_operation::MOVE, &other, &tmp);\n\n\t\t\t\tother.m_handler = m_handler;\n\t\t\t\tm_handler(storage_operation::MOVE, this, &other);\n\n\t\t\t\tm_handler = tmp.m_handler;\n\t\t\t\ttmp.m_handler(storage_operation::MOVE, &tmp, this);\n\t\t\t}\n\t\t\telse if (m_handler == nullptr && other.m_handler)\n\t\t\t{\n\t\t\t\teastl::swap(m_handler, other.m_handler);\n\t\t\t\tm_handler(storage_operation::MOVE, &other, this);\n\t\t\t}\n\t\t\telse if(m_handler && other.m_handler == nullptr)\n\t\t\t{\n\t\t\t\teastl::swap(m_handler, other.m_handler);\n\t\t\t\tother.m_handler(storage_operation::MOVE, this, &other);\n\t\t\t}\n\t\t\t//else if (m_handler == nullptr && other.m_handler == nullptr)\n\t\t\t//{\n\t\t\t// // nothing to swap \n\t\t\t//}\n\t\t}\n\n\t // 20.7.3.4, observers\n\t\tbool has_value() const EA_NOEXCEPT { return m_handler != nullptr; }\n\n #if EASTL_RTTI_ENABLED\n\t\t\tinline const std::type_info& type() const EA_NOEXCEPT \n\t\t\t{\n\t\t\t\tif(m_handler)\n\t\t\t\t{\n\t\t\t\t\tauto* pTypeInfo = m_handler(storage_operation::TYPE_INFO, this, nullptr);\n\t\t\t\t\treturn *static_cast(pTypeInfo);\n\t\t\t\t}\n\t\t\t\telse\n\t\t\t\t{\n\t\t\t\t\treturn typeid(void);\n\t\t\t\t}\n\t\t\t}\n\t\t#endif\n\t};\n\n\n\n\t//////////////////////////////////////////////////////////////////////////////////////////\n\t// 20.7.4, non-member functions\n\t//\n\tinline void swap(any& rhs, any& lhs) EA_NOEXCEPT { rhs.swap(lhs); }\n\n\n\t//////////////////////////////////////////////////////////////////////////////////////////\n\t// 20.7.4, The non-member any_cast functions provide type-safe access to the contained object.\n\t//\n\ttemplate \n\tinline ValueType any_cast(const any& operand)\n\t{\n\t\tstatic_assert(eastl::is_reference::value || eastl::is_copy_constructible::value,\n\t\t \"ValueType must be a reference or copy constructible\");\n\n\t\tauto* p = any_cast::type>::type>(&operand);\n\n\t\tif(p == nullptr)\n\t\t\tInternal::DoBadAnyCast();\n\n\t\treturn *p;\n\t}\n\n\ttemplate \n inline ValueType any_cast(any& operand)\n {\n\t\tstatic_assert(eastl::is_reference::value || eastl::is_copy_constructible::value,\n\t\t \"ValueType must be a reference or copy constructible\");\n\n\t\tauto* p = any_cast::type>(&operand);\n\n\t\tif(p == nullptr)\n\t\t\tInternal::DoBadAnyCast();\n\n\t\treturn *p;\n }\n\n\ttemplate \n\tinline ValueType any_cast(any&& operand)\n\t{\n\t\tstatic_assert(eastl::is_reference::value || eastl::is_copy_constructible::value,\n\t\t \"ValueType must be a reference or copy constructible\");\n\n\t\tauto* p = any_cast::type>(&operand);\n\n\t\tif (p == nullptr)\n\t\t\tInternal::DoBadAnyCast();\n\n\t\treturn *p;\n\t}\n\n\t// NOTE(rparolin): The runtime type check was commented out because in DLL builds the templated function pointer\n\t// value will be different -- completely breaking the validation mechanism. Due to the fact that eastl::any uses\n\t// type erasure we can't refresh (on copy/move) the cached function pointer to the internal handler function because\n\t// we don't statically know the type.\n\ttemplate \n\tinline const ValueType* any_cast(const any* pAny) EA_NOEXCEPT\n\t{\n\t\treturn (pAny && pAny->m_handler EASTL_IF_NOT_DLL(== &any::storage_handler>::handler_func)\n\t\t\t\t#if EASTL_RTTI_ENABLED\n\t\t\t\t\t&& pAny->type() == typeid(typename remove_reference::type)\n\t\t\t\t#endif\n\t\t\t\t) ?\n\t\t static_cast(pAny->m_handler(any::storage_operation::GET, pAny, nullptr)) :\n\t\t nullptr;\n\t}\n\n\ttemplate \n\tinline ValueType* any_cast(any* pAny) EA_NOEXCEPT\n\t{\n\t\treturn (pAny && pAny->m_handler EASTL_IF_NOT_DLL(== &any::storage_handler>::handler_func)\n\t\t\t\t#if EASTL_RTTI_ENABLED\n\t\t\t\t\t&& pAny->type() == typeid(typename remove_reference::type)\n\t\t\t\t#endif\n\t\t\t\t) ?\n\t\t static_cast(pAny->m_handler(any::storage_operation::GET, pAny, nullptr)) :\n\t\t nullptr;\n\t}\n\n\t//Unsafe operations - use with caution\n\ttemplate \n\tinline const ValueType* unsafe_any_cast(const any* pAny) EA_NOEXCEPT\n\t{\n\t\treturn unsafe_any_cast(const_cast(pAny));\n\t}\n\n\ttemplate \n\tinline ValueType* unsafe_any_cast(any* pAny) EA_NOEXCEPT\n\t{\n\t\treturn static_cast(pAny->m_handler(any::storage_operation::GET, pAny, nullptr));\n\t}\n\n\t//////////////////////////////////////////////////////////////////////////////////////////\n\t// make_any\n\t//\n\t#if EASTL_VARIADIC_TEMPLATES_ENABLED\n\t\ttemplate \n\t\tinline any make_any(Args&&... args)\n\t\t{\n\t\t\treturn any(eastl::in_place_type, eastl::forward(args)...);\n\t\t}\n\n\t\ttemplate \n\t\tinline any make_any(std::initializer_list il, Args&&... args)\n\t\t{\n\t\t\treturn any(eastl::in_place_type, il, eastl::forward(args)...);\n\t\t}\n #endif\n\n} // namespace eastl\n\n#endif // EASTL_ANY_H\n" }, { "path": "include/EASTL/array.h", "content": "/////////////////////////////////////////////////////////////////////////////\n// Copyright (c) Electronic Arts Inc. All rights reserved.\n/////////////////////////////////////////////////////////////////////////////\n\n\n///////////////////////////////////////////////////////////////////////////////\n// Implements a templated array class as per the C++ standard TR1 (technical\n// report 1, which is a list of proposed C++ library amendments).\n// The primary distinctions between this array and TR1 array are:\n// - array::size_type is defined as eastl_size_t instead of size_t in order\n// to save memory and run faster on 64 bit systems.\n///////////////////////////////////////////////////////////////////////////////\n\n\n#ifndef EASTL_ARRAY_H\n#define EASTL_ARRAY_H\n\n\n#include \n#include \n#include \n#include \n#include \n#include \n\n#if EASTL_EXCEPTIONS_ENABLED\n\tEA_DISABLE_ALL_VC_WARNINGS()\n\t#include // std::out_of_range, std::length_error.\n\tEA_RESTORE_ALL_VC_WARNINGS()\n#endif\n\n// 4512/4626 - 'class' : assignment operator could not be generated. // This disabling would best be put elsewhere.\nEA_DISABLE_VC_WARNING(4512 4626);\n\n#if defined(EA_PRAGMA_ONCE_SUPPORTED)\n\t#pragma once // Some compilers (e.g. VC++) benefit significantly from using this. We've measured 3-4% build speed improvements in apps as a result.\n#endif\n\n\n\nnamespace eastl\n{\n\n\t///////////////////////////////////////////////////////////////////////\n\t/// array\n\t///\n\t/// Implements a templated array class as per the C++ standard TR1.\n\t/// This class allows you to use a built-in C style array like an STL vector.\n\t/// It does not let you change its size, as it is just like a C built-in array.\n\t/// Our implementation here strives to remove function call nesting, as that\n\t/// makes it hard for us to profile debug builds due to function call overhead.\n\t/// Note that this is intentionally a struct with public data, as per the\n\t/// C++ standard update proposal requirements.\n\t///\n\t/// Example usage:\n\t/// array a = { { 0, 1, 2, 3, 4 } }; // Strict compilers such as GCC require the double brackets.\n\t/// a[2] = 4;\n\t/// for(array::iterator i = a.begin(); i < a.end(); ++i)\n\t/// *i = 0;\n\t///\n#if EA_IS_ENABLED(EA_DEPRECATIONS_FOR_2025_OCT)\n\ttemplate \n#else\n\ttemplate \n#endif\n\tstruct array\n\t{\n\tpublic:\n\t\ttypedef array this_type;\n\t\ttypedef T value_type;\n\t\ttypedef value_type& reference;\n\t\ttypedef const value_type& const_reference;\n\t\ttypedef value_type* iterator;\n\t\ttypedef const value_type* const_iterator;\n\t\ttypedef eastl::reverse_iterator reverse_iterator;\n\t\ttypedef eastl::reverse_iterator const_reverse_iterator;\n\t\ttypedef eastl_size_t size_type; // See config.h for the definition of eastl_size_t, which defaults to size_t.\n\t\ttypedef ptrdiff_t difference_type;\n\n\t\t// Note that the member data is intentionally public.\n\t\t// This allows for aggregate initialization of the\n\t\t// object (e.g. array a = { 0, 3, 2, 4 }; )\n\t\t// do not use this member directly (use data() instead).\n\t\tvalue_type mValue[N];\n\n\t\t// We intentionally provide no constructor, destructor, or assignment operator.\n\n\t\tvoid fill(const value_type& value);\n\n\t\t// Unlike the swap function for other containers, array::swap takes linear time,\n\t\t// may exit via an exception, and does not cause iterators to become associated with the other container.\n\t\tvoid swap(this_type& x) EA_NOEXCEPT_IF(eastl::is_nothrow_swappable::value);\n\n\t\tEA_CPP14_CONSTEXPR iterator begin() EA_NOEXCEPT;\n\t\tEA_CPP14_CONSTEXPR const_iterator begin() const EA_NOEXCEPT;\n\t\tEA_CPP14_CONSTEXPR const_iterator cbegin() const EA_NOEXCEPT;\n\n\t\tEA_CPP14_CONSTEXPR iterator end() EA_NOEXCEPT;\n\t\tEA_CPP14_CONSTEXPR const_iterator end() const EA_NOEXCEPT;\n\t\tEA_CPP14_CONSTEXPR const_iterator cend() const EA_NOEXCEPT;\n\n\t\tEA_CPP14_CONSTEXPR reverse_iterator rbegin() EA_NOEXCEPT;\n\t\tEA_CPP14_CONSTEXPR const_reverse_iterator rbegin() const EA_NOEXCEPT;\n\t\tEA_CPP14_CONSTEXPR const_reverse_iterator crbegin() const EA_NOEXCEPT;\n\n\t\tEA_CPP14_CONSTEXPR reverse_iterator rend() EA_NOEXCEPT;\n\t\tEA_CPP14_CONSTEXPR const_reverse_iterator rend() const EA_NOEXCEPT;\n\t\tEA_CPP14_CONSTEXPR const_reverse_iterator crend() const EA_NOEXCEPT;\n\n\t\tEA_CPP14_CONSTEXPR bool empty() const EA_NOEXCEPT;\n\t\tEA_CPP14_CONSTEXPR size_type size() const EA_NOEXCEPT;\n\t\tEA_CPP14_CONSTEXPR size_type max_size() const EA_NOEXCEPT;\n\n\t\tEA_CPP14_CONSTEXPR T* data() EA_NOEXCEPT;\n\t\tEA_CPP14_CONSTEXPR const T* data() const EA_NOEXCEPT;\n\n\t\tEA_CPP14_CONSTEXPR reference operator[](size_type i);\n\t\tEA_CPP14_CONSTEXPR const_reference operator[](size_type i) const;\n\t\tEA_CPP14_CONSTEXPR const_reference at(size_type i) const;\n\t\tEA_CPP14_CONSTEXPR reference at(size_type i);\n\n\t\tEA_CPP14_CONSTEXPR reference front();\n\t\tEA_CPP14_CONSTEXPR const_reference front() const;\n\n\t\tEA_CPP14_CONSTEXPR reference back();\n\t\tEA_CPP14_CONSTEXPR const_reference back() const;\n\n\t\tbool validate() const;\n\t\tint validate_iterator(const_iterator i) const;\n\n\t}; // class array\n\n\t// declaring a C-style array of size 0 is not valid C++.\n\t// thus, we have to declare this partial specialization:\n\ttemplate \n\tstruct array\n\t{\n\tpublic:\n\t\ttypedef array this_type;\n\t\ttypedef T value_type;\n\t\ttypedef value_type& reference;\n\t\ttypedef const value_type& const_reference;\n\t\ttypedef value_type* iterator;\n\t\ttypedef const value_type* const_iterator;\n\t\ttypedef eastl::reverse_iterator reverse_iterator;\n\t\ttypedef eastl::reverse_iterator const_reverse_iterator;\n\t\ttypedef eastl_size_t size_type; // See config.h for the definition of eastl_size_t, which defaults to size_t.\n\t\ttypedef ptrdiff_t difference_type;\n\n\t\t// We intentionally provide no constructor, destructor, or assignment operator.\n\n\t\tvoid fill(const value_type&) {}\n\n\t\t// Unlike the swap function for other containers, array::swap takes linear time,\n\t\t// may exit via an exception, and does not cause iterators to become associated with the other container.\n\t\tvoid swap(this_type&) EA_NOEXCEPT {}\n\n\t\tEA_CPP14_CONSTEXPR iterator begin() EA_NOEXCEPT { return nullptr; }\n\t\tEA_CPP14_CONSTEXPR const_iterator begin() const EA_NOEXCEPT { return nullptr; }\n\t\tEA_CPP14_CONSTEXPR const_iterator cbegin() const EA_NOEXCEPT { return nullptr; }\n\n\t\tEA_CPP14_CONSTEXPR iterator end() EA_NOEXCEPT { return nullptr; }\n\t\tEA_CPP14_CONSTEXPR const_iterator end() const EA_NOEXCEPT { return nullptr; }\n\t\tEA_CPP14_CONSTEXPR const_iterator cend() const EA_NOEXCEPT { return nullptr; }\n\n\t\tEA_CPP14_CONSTEXPR reverse_iterator rbegin() EA_NOEXCEPT { return reverse_iterator(nullptr); }\n\t\tEA_CPP14_CONSTEXPR const_reverse_iterator rbegin() const EA_NOEXCEPT { return const_reverse_iterator(nullptr); }\n\t\tEA_CPP14_CONSTEXPR const_reverse_iterator crbegin() const EA_NOEXCEPT { return const_reverse_iterator(nullptr); }\n\n\t\tEA_CPP14_CONSTEXPR reverse_iterator rend() EA_NOEXCEPT { return reverse_iterator(nullptr); }\n\t\tEA_CPP14_CONSTEXPR const_reverse_iterator rend() const EA_NOEXCEPT { return const_reverse_iterator(nullptr); }\n\t\tEA_CPP14_CONSTEXPR const_reverse_iterator crend() const EA_NOEXCEPT { return const_reverse_iterator(nullptr); }\n\n\t\tEA_CPP14_CONSTEXPR bool empty() const EA_NOEXCEPT { return true; }\n\t\tEA_CPP14_CONSTEXPR size_type size() const EA_NOEXCEPT { return 0; }\n\t\tEA_CPP14_CONSTEXPR size_type max_size() const EA_NOEXCEPT { return 0; }\n\n\t\tEA_CPP14_CONSTEXPR T* data() EA_NOEXCEPT { return nullptr; }\n\t\tEA_CPP14_CONSTEXPR const T* data() const EA_NOEXCEPT { return nullptr; }\n\n\t\tEA_CPP14_CONSTEXPR reference operator[](size_type) { return *data(); }\n\t\tEA_CPP14_CONSTEXPR const_reference operator[](size_type) const { return *data(); }\n\n\t\tEA_DISABLE_VC_WARNING(4702); // unreachable code\n\t\tEA_CPP14_CONSTEXPR const_reference at(size_type) const\n\t\t{\n#if EASTL_EXCEPTIONS_ENABLED\n\t\t\tthrow std::out_of_range(\"array::at -- out of range\");\n#elif EASTL_ASSERT_ENABLED\n\t\t\tEASTL_FAIL_MSG(\"array::at -- out of range\");\n#endif\n\t\t\treturn *data();\n\t\t}\n\t\tEA_RESTORE_VC_WARNING();\n\n\t\tEA_DISABLE_VC_WARNING(4702); // unreachable code\n\t\tEA_CPP14_CONSTEXPR reference at(size_type)\n\t\t{\n#if EASTL_EXCEPTIONS_ENABLED\n\t\t\tthrow std::out_of_range(\"array::at -- out of range\");\n#elif EASTL_ASSERT_ENABLED\n\t\t\tEASTL_FAIL_MSG(\"array::at -- out of range\");\n#endif\n\t\t\treturn *data();\n\t\t}\n\t\tEA_RESTORE_VC_WARNING();\n\n\t\tEA_CPP14_CONSTEXPR reference front() { return *data(); }\n\t\tEA_CPP14_CONSTEXPR const_reference front() const { return *data(); }\n\n\t\tEA_CPP14_CONSTEXPR reference back() { return *data(); }\n\t\tEA_CPP14_CONSTEXPR const_reference back() const { return *data(); }\n\n\t\tbool validate() const { return true; }\n\t\tint validate_iterator(const_iterator) const { return isf_none; }\n\n\t}; // class array\n\n\n\n\t///////////////////////////////////////////////////////////////////////////\n\t// template deduction guides\n\t///////////////////////////////////////////////////////////////////////////\n\t#ifdef __cpp_deduction_guides\n\t\ttemplate array(T, U...) -> array;\n\t#endif\n\n\n\t///////////////////////////////////////////////////////////////////////\n\t// array\n\t///////////////////////////////////////////////////////////////////////\n\n\n\ttemplate \n\tinline void array::fill(const value_type& value)\n\t{\n\t\teastl::fill_n(&mValue[0], N, value);\n\t}\n\n\n\ttemplate \n\tinline void array::swap(this_type& x) EA_NOEXCEPT_IF(eastl::is_nothrow_swappable::value)\n\t{\n\t\teastl::swap_ranges(&mValue[0], &mValue[N], &x.mValue[0]);\n\t}\n\n\n\ttemplate \n\tEA_CPP14_CONSTEXPR inline typename array::iterator\n\tarray::begin() EA_NOEXCEPT\n\t{\n\t\treturn &mValue[0];\n\t}\n\n\n\ttemplate \n\tEA_CPP14_CONSTEXPR inline typename array::const_iterator\n\tarray::begin() const EA_NOEXCEPT\n\t{\n\t\treturn &mValue[0];\n\t}\n\n\n\ttemplate \n\tEA_CPP14_CONSTEXPR inline typename array::const_iterator\n\tarray::cbegin() const EA_NOEXCEPT\n\t{\n\t\treturn &mValue[0];\n\t}\n\n\n\ttemplate \n\tEA_CPP14_CONSTEXPR inline typename array::iterator\n\tarray::end() EA_NOEXCEPT\n\t{\n\t\treturn &mValue[N];\n\t}\n\n\n\ttemplate \n\tEA_CPP14_CONSTEXPR inline typename array::const_iterator\n\tarray::end() const EA_NOEXCEPT\n\t{\n\t\treturn &mValue[N];\n\t}\n\n\n\ttemplate \n\tEA_CPP14_CONSTEXPR inline typename array::const_iterator\n\tarray::cend() const EA_NOEXCEPT\n\t{\n\t\treturn &mValue[N];\n\t}\n\n\n\ttemplate \n\tEA_CPP14_CONSTEXPR inline typename array::reverse_iterator\n\tarray::rbegin() EA_NOEXCEPT\n\t{\n\t\treturn reverse_iterator(&mValue[N]);\n\t}\n\n\n\ttemplate \n\tEA_CPP14_CONSTEXPR inline typename array::const_reverse_iterator\n\tarray::rbegin() const EA_NOEXCEPT\n\t{\n\t\treturn const_reverse_iterator(&mValue[N]);\n\t}\n\n\n\ttemplate \n\tEA_CPP14_CONSTEXPR inline typename array::const_reverse_iterator\n\tarray::crbegin() const EA_NOEXCEPT\n\t{\n\t\treturn const_reverse_iterator(&mValue[N]);\n\t}\n\n\n\ttemplate \n\tEA_CPP14_CONSTEXPR inline typename array::reverse_iterator\n\tarray::rend() EA_NOEXCEPT\n\t{\n\t\treturn reverse_iterator(&mValue[0]);\n\t}\n\n\n\ttemplate \n\tEA_CPP14_CONSTEXPR inline typename array::const_reverse_iterator\n\tarray::rend() const EA_NOEXCEPT\n\t{\n\t\treturn const_reverse_iterator(static_cast(&mValue[0]));\n\t}\n\n\n\ttemplate \n\tEA_CPP14_CONSTEXPR inline typename array::const_reverse_iterator\n\tarray::crend() const EA_NOEXCEPT\n\t{\n\t\treturn const_reverse_iterator(static_cast(&mValue[0]));\n\t}\n\n\n\ttemplate \n\tEA_CPP14_CONSTEXPR inline typename array::size_type\n\tarray::size() const EA_NOEXCEPT\n\t{\n\t\treturn (size_type)N;\n\t}\n\n\n\ttemplate \n\tEA_CPP14_CONSTEXPR inline typename array::size_type\n\tarray::max_size() const EA_NOEXCEPT\n\t{\n\t\treturn (size_type)N;\n\t}\n\n\n\ttemplate \n\tEA_CPP14_CONSTEXPR inline bool array::empty() const EA_NOEXCEPT\n\t{\n\t\treturn (N == 0);\n\t}\n\n\n\ttemplate \n\tEA_CPP14_CONSTEXPR inline typename array::reference\n\tarray::operator[](size_type i)\n\t{\n\t\t#if EASTL_ASSERT_ENABLED && EASTL_EMPTY_REFERENCE_ASSERT_ENABLED\n\t\t\tif (EASTL_UNLIKELY(i >= N))\n\t\t\t\tEASTL_FAIL_MSG(\"array::operator[] -- out of range\");\n\t\t#elif EASTL_ASSERT_ENABLED\n\t\t\t// We allow taking a reference to arr[0]\n\t\t\tif (EASTL_UNLIKELY((i != 0) && i >= N))\n\t\t\t\tEASTL_FAIL_MSG(\"array::operator[] -- out of range\");\n\t\t#endif\n\n\t\treturn mValue[i];\n\t}\n\n\n\ttemplate \n\tEA_CPP14_CONSTEXPR inline typename array::const_reference\n\tarray::operator[](size_type i) const\n\t{\n\t\t#if EASTL_ASSERT_ENABLED && EASTL_EMPTY_REFERENCE_ASSERT_ENABLED\n\t\t\tif (EASTL_UNLIKELY(i >= N))\n\t\t\t\tEASTL_FAIL_MSG(\"array::operator[] -- out of range\");\n\t\t#elif EASTL_ASSERT_ENABLED\n\t\t\t// We allow taking a reference to arr[0]\n\t\t\tif (EASTL_UNLIKELY((i != 0) && i >= N))\n\t\t\t\tEASTL_FAIL_MSG(\"array::operator[] -- out of range\");\n\t\t#endif\n\n\t\treturn mValue[i];\n\t}\n\n\n\ttemplate \n\tEA_CPP14_CONSTEXPR inline typename array::reference\n\tarray::front()\n\t{\n\t\treturn mValue[0];\n\t}\n\n\n\ttemplate \n\tEA_CPP14_CONSTEXPR inline typename array::const_reference\n\tarray::front() const\n\t{\n\t\treturn mValue[0];\n\t}\n\n\n\ttemplate \n\tEA_CPP14_CONSTEXPR inline typename array::reference\n\tarray::back()\n\t{\n\t\treturn mValue[N - 1];\n\t}\n\n\n\ttemplate \n\tEA_CPP14_CONSTEXPR inline typename array::const_reference\n\tarray::back() const\n\t{\n\t\treturn mValue[N - 1];\n\t}\n\n\n\ttemplate \n\tEA_CPP14_CONSTEXPR inline T* array::data() EA_NOEXCEPT\n\t{\n\t\treturn mValue;\n\t}\n\n\n\ttemplate \n\tEA_CPP14_CONSTEXPR inline const T* array::data() const EA_NOEXCEPT\n\t{\n\t\treturn mValue;\n\t}\n\n\n\ttemplate \n\tEA_CPP14_CONSTEXPR inline typename array::const_reference array::at(size_type i) const\n\t{\n\t\t#if EASTL_EXCEPTIONS_ENABLED\n\t\t\tif(EASTL_UNLIKELY(i >= N))\n\t\t\t\tthrow std::out_of_range(\"array::at -- out of range\");\n\t\t#elif EASTL_ASSERT_ENABLED\n\t\t\tif(EASTL_UNLIKELY(i >= N))\n\t\t\t\tEASTL_FAIL_MSG(\"array::at -- out of range\");\n\t\t#endif\n\n\t\treturn static_cast(mValue[i]);\n\t}\n\n\n\ttemplate \n\tEA_CPP14_CONSTEXPR inline typename array::reference array::at(size_type i)\n\t{\n\t\t#if EASTL_EXCEPTIONS_ENABLED\n\t\t\tif(EASTL_UNLIKELY(i >= N))\n\t\t\t\tthrow std::out_of_range(\"array::at -- out of range\");\n\t\t#elif EASTL_ASSERT_ENABLED\n\t\t\tif(EASTL_UNLIKELY(i >= N))\n\t\t\t\tEASTL_FAIL_MSG(\"array::at -- out of range\");\n\t\t#endif\n\n\t\treturn static_cast(mValue[i]);\n\t}\n\n\n\ttemplate \n\tinline bool array::validate() const\n\t{\n\t\treturn true; // There is nothing to do.\n\t}\n\n\n\ttemplate \n\tinline int array::validate_iterator(const_iterator i) const\n\t{\n\t\tif(i >= mValue)\n\t\t{\n\t\t\tif(i < (mValue + N))\n\t\t\t\treturn (isf_valid | isf_current | isf_can_dereference);\n\n\t\t\tif(i <= (mValue + N))\n\t\t\t\treturn (isf_valid | isf_current);\n\t\t}\n\n\t\treturn isf_none;\n\t}\n\n\n\n\t///////////////////////////////////////////////////////////////////////\n\t// global operators\n\t///////////////////////////////////////////////////////////////////////\n\n\ttemplate \n\tEA_CPP14_CONSTEXPR inline bool operator==(const array& a, const array& b)\n\t{\n\t\treturn eastl::equal(&a.mValue[0], &a.mValue[N], &b.mValue[0]);\n\t}\n\n#if defined(EA_COMPILER_HAS_THREE_WAY_COMPARISON)\n\ttemplate \n\tinline synth_three_way_result operator<=>(const array& a, const array& b)\n\t{\n\t return eastl::lexicographical_compare_three_way(&a.mValue[0], &a.mValue[N], &b.mValue[0], &b.mValue[N], synth_three_way{});\n\t}\n#else\n\n\ttemplate \n\tEA_CPP14_CONSTEXPR inline bool operator<(const array& a, const array& b)\n\t{\n\t\treturn eastl::lexicographical_compare(&a.mValue[0], &a.mValue[N], &b.mValue[0], &b.mValue[N]);\n\t}\n\n\n\ttemplate \n\tEA_CPP14_CONSTEXPR inline bool operator!=(const array& a, const array& b)\n\t{\n\t\treturn !eastl::equal(&a.mValue[0], &a.mValue[N], &b.mValue[0]);\n\t}\n\n\n\ttemplate \n\tEA_CPP14_CONSTEXPR inline bool operator>(const array& a, const array& b)\n\t{\n\t\treturn eastl::lexicographical_compare(&b.mValue[0], &b.mValue[N], &a.mValue[0], &a.mValue[N]);\n\t}\n\n\n\ttemplate \n\tEA_CPP14_CONSTEXPR inline bool operator<=(const array& a, const array& b)\n\t{\n\t\treturn !eastl::lexicographical_compare(&b.mValue[0], &b.mValue[N], &a.mValue[0], &a.mValue[N]);\n\t}\n\n\n\ttemplate \n\tEA_CPP14_CONSTEXPR inline bool operator>=(const array& a, const array& b)\n\t{\n\t\treturn !eastl::lexicographical_compare(&a.mValue[0], &a.mValue[N], &b.mValue[0], &b.mValue[N]);\n\t}\n#endif\n\n\t///////////////////////////////////////////////////////////////////////\n\t// non-member functions\n\t///////////////////////////////////////////////////////////////////////\n\n\ttemplate\n\tEA_NODISCARD EA_CONSTEXPR T& get(array& value) EA_NOEXCEPT\n\t{\n\t\tstatic_assert(I < N, \"array index out of bounds\");\n\t\treturn value.mValue[I];\n\t}\n\n\ttemplate\n\tEA_NODISCARD EA_CONSTEXPR T&& get(array&& value) EA_NOEXCEPT\n\t{\n\t\tstatic_assert(I < N, \"array index out of bounds\");\n\t\treturn move(value.mValue[I]);\n\t}\n\n\ttemplate\n\tEA_NODISCARD EA_CONSTEXPR const T& get(const array& value) EA_NOEXCEPT\n\t{\n\t\tstatic_assert(I < N, \"array index out of bounds\");\n\t\treturn value.mValue[I];\n\t}\n\n\ttemplate\n\tEA_NODISCARD EA_CONSTEXPR const T&& get(const array&& value) EA_NOEXCEPT\n\t{\n\t\tstatic_assert(I < N, \"array index out of bounds\");\n\t\treturn move(value.mValue[I]);\n\t}\n\n\ttemplate \n\tinline void swap(array& a, array& b)\n\t{\n\t\teastl::swap_ranges(&a.mValue[0], &a.mValue[N], &b.mValue[0]);\n\t}\n\n\n\t///////////////////////////////////////////////////////////////////////\n\t// to_array\n\t///////////////////////////////////////////////////////////////////////\n\tnamespace internal\n\t{\n\t\ttemplate\n\t\tEA_CONSTEXPR auto to_array(T (&a)[N], index_sequence)\n\t\t{\n\t\t\treturn eastl::array, N>{{a[I]...}};\n\t\t}\n\n\t\ttemplate\n\t\tEA_CONSTEXPR auto to_array(T (&&a)[N], index_sequence)\n\t\t{\n\t\t\treturn eastl::array, N>{{eastl::move(a[I])...}};\n\t\t}\n\t}\n\n\ttemplate\n\tEA_CONSTEXPR eastl::array, N> to_array(T (&a)[N])\n\t{\n\t\tstatic_assert(eastl::is_constructible_v, \"element type T must be copy-initializable\");\n\t\tstatic_assert(!eastl::is_array_v, \"passing multidimensional arrays to to_array is ill-formed\");\n\t\treturn internal::to_array(a, eastl::make_index_sequence{});\n\t}\n\n\ttemplate\n\tEA_CONSTEXPR eastl::array, N> to_array(T (&&a)[N])\n\t{\n\t\tstatic_assert(eastl::is_move_constructible_v, \"element type T must be move-constructible\");\n\t\tstatic_assert(!eastl::is_array_v, \"passing multidimensional arrays to to_array is ill-formed\");\n\t\treturn internal::to_array(eastl::move(a), eastl::make_index_sequence{});\n\t}\n\n#if EASTL_TUPLE_ENABLED\n\n\t///////////////////////////////////////////////////////////////////////\n\t// helper classes\n\t///////////////////////////////////////////////////////////////////////\n\n\ttemplate\n\tstruct tuple_size> : public eastl::integral_constant {};\n\n\tnamespace internal {\n\ttemplate\n\tstruct tuple_element {};\n\n\ttemplate\n\tstruct tuple_element> {\n\t\tusing type = T;\n\t};\n\t}\n\n\ttemplate\n\tstruct tuple_element> : internal::tuple_element {};\n\n#endif // EASTL_TUPLE_ENABLED\n} // namespace eastl\n\n///////////////////////////////////////////////////////////////////////\n// C++17 structured bindings support for eastl::array\n///////////////////////////////////////////////////////////////////////\n\n#ifndef EA_COMPILER_NO_STRUCTURED_BINDING\n// we can't forward declare tuple_size and tuple_element because some std implementations\n// don't declare it in the std namespace, but instead alias it.\n#include \n\nnamespace std\n{\n\ntemplate\nstruct tuple_size> : public eastl::integral_constant {};\n\ntemplate\nstruct tuple_element> : public eastl::tuple_element> {};\n}\n#endif\n\n\nEA_RESTORE_VC_WARNING();\n\n#endif // Header include guard\n\n\n\n\n\n\n\n\n\n\n" }, { "path": "include/EASTL/atomic.h", "content": "/////////////////////////////////////////////////////////////////////////////////\n// Copyright (c) Electronic Arts Inc. All rights reserved.\n/////////////////////////////////////////////////////////////////////////////////\n\n\n#ifndef EASTL_ATOMIC_H\n#define EASTL_ATOMIC_H\n\n#if defined(EA_PRAGMA_ONCE_SUPPORTED)\n\t#pragma once\n#endif\n\n\n/////////////////////////////////////////////////////////////////////////////////\n//\n// Below is the documentation of the API of the eastl::atomic library.\n// This includes class and free functions.\n// Anything marked with a '+' in front of the name is an extension to the std API.\n//\n\n\n/////////////////////////////////////////////////////////////////////////////////\n//\n// eastl::atomic memory_order API\n//\n// See below for full explanations on the memory orders and their guarantees.\n//\n// - eastl::memory_order_relaxed\n// - eastl::memory_order_acquire\n// - eastl::memory_order_release\n// - eastl::memory_order_acq_rel\n// - eastl::memory_order_seq_cst\n// - +eastl::memory_order_read_depends\n//\n\n\n/////////////////////////////////////////////////////////////////////////////////\n//\n// eastl::atomic class API\n//\n// All jargon and prerequisite knowledge is explained below.\n//\n// Unless otherwise specified all orders except read_depends is a valid order\n// on the given operation.\n// Unless otherwise specified all operations are valid on all types T.\n// If no order is provided, seq_cst memory ordering is used for the operation.\n//\n// - atomic() : Value-initializes the underlying object as T{}.\n//\n// - atomic(T) : Initializes the underlying object with a copy of T.\n//\n// - T operator=(T) : Atomically assigns T as store(T, seq_cst).\n//\n// - is_lock_free() : true if the operations are lockfree. Always true for eastl.\n//\n// - store(T, order) : Atomically stores T affecting memory according to order.\n// : Valid orders are relaxed, release, and seq_cst.\n//\n// - T load(order) : Atomically loads T affecting memory according to order.\n// : Valid orders are relaxed, acquire, and seq_cst.\n// : If T is a pointer type, read_depends is another valid order.\n//\n// - operator T() : Atomically loads T as load(T, seq_cst).\n//\n// - T exchange(T, order) : Atomically performs a RMW that replaces the current value with T.\n// : Memory is affected according to order.\n// : Returns the previous value stored before the RMW operation.\n//\n// - bool compare_exchange_weak(T&, T, successOrder, failOrder)\n// : Atomically compares the value stored with that of T& and if equal replaces it with T.\n// : This is a RMW operation.\n// : If the comparison fails, loads the observed value into T&. This is a load operation.\n// : Memory is affected in the RMW operation according to successOrder.\n// : Memory is affected in the load operation according to failOrder.\n// : failOrder cannot be a stronger order than successOrder.\n// : Returns true or false if the comparison succeeded and T was stored into the atomic object.\n// :\n// : The weak variant may fail even if the observed value of the atomic object equals T&.\n// : This can yield performance gains on platforms with ld/str exclusive pair instructions especially\n// : when the compare_exchange operation is done in a loop.\n// : Only the bool return value can be used to determine if the operation was successful.\n//\n// - bool compare_exchange_weak(T&, T, order)\n// : Same as the above except that order is used for both the RMW and the load operation.\n// : If order == acq_rel then the order of the load operation equals acquire.\n// : If order == release then the order of the load operation equals relaxed.\n//\n// - bool compare_exchange_strong(T&, T, successOrder, failOrder)\n// - bool compare_exchange_strong(T&, T, order)\n// : This operation is the same as the above weak variants\n// : expect that it will not fail spuriously if the value stored equals T&.\n//\n// The below operations are only valid for Integral types.\n//\n// - T fetch_add(T, order)\n// : Atomically performs a RMW that increments the value stored with T.\n// : Returns the previous value stored before the RMW operation.\n// - T fetch_sub(T, order)\n// : Atomically performs a RMW that decrements the value stored with T.\n// : Returns the previous value stored before the RMW operation.\n// - T fetch_and(T, order)\n// : Atomically performs a RMW that bit-wise and's the value stored with T.\n// : Returns the previous value stored before the RMW operation.\n// - T fetch_or(T, order)\n// : Atomically performs a RMW that bit-wise or's the value stored with T.\n// : Returns the previous value stored before the RMW operation.\n// - T fetch_xor(T, order)\n// : Atomically performs a RMW that bit-wise xor's the value stored with T.\n// : Returns the previous value stored before the RMW operation.\n//\n// - +T add_fetch(T, order)\n// : Atomically performs a RMW that increments the value stored with T.\n// : Returns the new updated value after the operation.\n// - +T sub_fetch(T, order)\n// : Atomically performs a RMW that decrements the value stored with T.\n// : Returns the new updated value after the operation.\n// - +T and_fetch(T, order)\n// : Atomically performs a RMW that bit-wise and's the value stored with T.\n// : Returns the new updated value after the operation.\n// - +T or_fetch(T, order)\n// : Atomically performs a RMW that bit-wise or's the value stored with T.\n// : Returns the new updated value after the operation.\n// - +T xor_fetch(T, order)\n// : Atomically performs a RMW that bit-wise xor's the value stored with T.\n// : Returns the new updated value after the operation.\n//\n// - T operator++/--()\n// : Atomically increments or decrements the atomic value by one.\n// : Returns the previous value stored before the RMW operation.\n// : Memory is affected according to seq_cst ordering.\n//\n// - T ++/--operator()\n// : Atomically increments or decrements the atomic value by one.\n// : Returns the new updated value after the RMW operation.\n// : Memory is affected according to seq_cst ordering.\n//\n// - T operator+=/-=/&=/|=/^=(T)\n// : Atomically adds, subtracts, bitwise and/or/xor the atomic object with T.\n// : Returns the new updated value after the operation.\n// : Memory is affected according to seq_cst ordering.\n//\n//\n// The below operations are only valid for Pointer types\n//\n// - T* fetch_add(ptrdiff_t val, order)\n// : Atomically performs a RMW that increments the value store with sizeof(T) * val\n// : Returns the previous value stored before the RMW operation.\n// - T* fetch_sub(ptrdiff_t val, order)\n// : Atomically performs a RMW that decrements the value store with sizeof(T) * val\n// : Returns the previous value stored before the RMW operation.\n//\n// - +T* add_fetch(ptrdiff_t val, order)\n// : Atomically performs a RMW that increments the value store with sizeof(T) * val\n// : Returns the new updated value after the operation.\n// - +T* sub_fetch(ptrdiff_t val, order)\n// : Atomically performs a RMW that decrements the value store with sizeof(T) * val\n// : Returns the new updated value after the operation.\n//\n// - T* operator++/--()\n// : Atomically increments or decrements the atomic value by sizeof(T) * 1.\n// : Returns the previous value stored before the RMW operation.\n// : Memory is affected according to seq_cst ordering.\n//\n// - T* ++/--operator()\n// : Atomically increments or decrements the atomic value by sizeof(T) * 1.\n// : Returns the new updated value after the RMW operation.\n// : Memory is affected according to seq_cst ordering.\n//\n//\n// - +EASTL_ATOMIC_HAS_[len]BIT Macro Definitions\n// These macros provide the ability to compile-time switch on the availability of support for the specific\n// bit width of an atomic object.\n// Example:\n//\n// #if defined(EASTL_ATOMIC_HAS_128BIT)\n// #endif\n//\n// Indicates the support for 128-bit atomic operations on an eastl::atomic object.\n//\n\n\n/////////////////////////////////////////////////////////////////////////////////\n//\n// eastl::atomic_flag class API\n//\n// Unless otherwise specified all orders except read_depends is a valid order\n// on the given operation.\n//\n// - atomic_flag() : Initializes the flag to false.\n//\n// - clear(order)\n// : Atomically stores the value false to the flag.\n// : Valid orders are relaxed, release, and seq_cst.\n//\n// - bool test_and_set(order)\n// : Atomically exchanges flag with true and returns the previous value that was held.\n//\n// - bool test(order)\n// : Atomically loads the flag value.\n// : Valid orders are relaxed, acquire, and seq_cst.\n//\n\n\n/////////////////////////////////////////////////////////////////////////////////\n//\n// eastl::atomic standalone free function API\n//\n// All class methods have a standalone free function that takes a pointer to the\n// atomic object as the first argument. These functions just call the correct method\n// on the atomic object for the given operation.\n// These functions come in two variants, a non-explicit and an explicit variant\n// that take on the form atomic_op() and atomic_op_explicit() respectively.\n// The non-explicit variants take no order arguments and thus are all seq_cst.\n// The explicit variants take an order argument.\n// Only the standalone functions that do not have a class method equivalent pair will be\n// documented here which includes all new extensions to the std API.\n//\n// - +compiler_barrier()\n// : Read-Write Compiler Barrier.\n// - +compiler_barrier_data_dependency(const T&)\n// : Read-Write Compiler Barrier.\n// : Applies a fake input dependency on const T& so the compiler believes said variable is used.\n// : Useful for example when writing benchmark or testing code with local variables that must not get dead-store eliminated.\n// - +cpu_pause()\n// : Prevents speculative memory order violations in spin-wait loops.\n// : Allows giving up core resources, execution units, to other threads while in spin-wait loops.\n// - atomic_thread_fence(order)\n// : Read docs below.\n// - atomic_signal_fence(order)\n// : Prevents reordering with a signal handler.\n// - +atomic_load_cond(const eastl::atomic*, Predicate)\n// : continuously loads the atomic object until Predicate is true\n// : will properly ensure the spin-wait loop is optimal\n// : very useful when needing to spin-wait for some condition to be true which is common is many lock-free algorithms\n// : Memory is affected according to seq_cst ordering.\n// - +atomic_load_cond_explicit(const eastl::atomic*, Predicate, Order)\n// : Same as above but takes an order for how memory is affected\n//\n\n\n/////////////////////////////////////////////////////////////////////////////////\n//\n// Deviations from the standard. This does not include new features added:\n//\n// 1.\n// Description: Atomics are always lock free\n// Reasoning : We don't want people to fall into performance traps where implicit locking\n// is done. If your user defined type is large enough to not support atomic\n// instructions then your user code should do the locking.\n//\n// 2.\n// Description: Atomic objects can not be volatile\n// Reasoning : Volatile objects do not make sense in the context of eastl::atomic.\n// Use the given memory orders to get the ordering you need.\n// Atomic objects have to become visible on the bus. See below for details.\n//\n// 3.\n// Description: Consume memory order is not supported\n// Reasoning : See below for the reasoning.\n//\n// 4.\n// Description: ATOMIC_INIT() macros and the ATOMIC_LOCK_FREE macros are not implemented\n// Reasoning : Use the is_lock_free() method instead of the macros.\n// ATOMIC_INIT() macros aren't needed since the default constructor value initializes.\n//\n// 5.\n// Description: compare_exchange failure memory order cannot be stronger than success memory order\n// Reasoning : Besides the argument that it ideologically does not make sense that a failure\n// of the atomic operation shouldn't have a stricter ordering guarantee than the\n// success of it; if that is required then just make the whole operation stronger.\n// This ability was added and allowed in C++17 only which makes supporting multiple\n// C++ versions harder when using the compiler provided intrinsics since their behaviour\n// is reliant on the C++ version being compiled. Also makes it harder to reason about code\n// using these atomic ops since C++ versions vary the behaviour. We have also noticed\n// that versions of compilers that say they support C++17 do not properly adhere to this\n// new requirement in their intrinsics. Thus we will not support this.\n//\n// 6.\n// Description: All memory orders are distinct types instead of enum values\n// Reasoning : This will not affect how the API is used in user code.\n// It allows us to statically assert on invalid memory orders since they are compile-time types\n// instead of potentially runtime enum values.\n// Allows for more efficient code gen without the use of switch statements or if-else conditionals\n// on the memory order enum values on compilers that do not provide intrinsics that take in a\n// memory order, such as MSVC, especially in debug and debug-opt builds.\n//\n\n\n/////////////////////////////////////////////////////////////////////////////////\n//\n// ******** DISCLAIMER ********\n//\n// This documentation is not meant to provide rigorous proofs on the memory models\n// of specific architectures or the C++ memory model introduced in C++11. It is not\n// meant to provide formal mathematical definitions and logic that shows that a given\n// implementation adheres to the C++ memory model. This isn't meant to be some infallible\n// oracle on memory models, barriers, observers, and architecture implementation details.\n// What I do hope a reader gets out of this is the following. An understanding of the C++\n// memory model and how that relates to implementations on various architectures. Various\n// phenomena and ways that compilers and architectures can steer away from a sequentially\n// consistent system. To provide examples on how to use this library with common patterns\n// that will be seen in many code bases. Lastly I would like to provide insight and\n// further readings into the lesser known topics that aren't shared outside people\n// who live in this space and why certain things are done the way they are\n// such as cumulativity of memory barriers as one example. Sometimes specifying barriers\n// as LDLD/LDST/STST/STLD doesn't actually cut it, and finer grain semantics are needed\n// to describe cumulativity of memory barriers.\n//\n// ******** Layout of the Documentation ********\n//\n// This document will first go through a variety of different hardware architectures with examples of the various kinds of\n// reordering that is allowed by these architectures. We will use the memory barriers provided by the hardware to \"fix\" these\n// examples.\n// Then we will introduce the C++ memory model and revisit the examples using the platform agnostic abstract memory model to \"fix\"\n// them.\n// The hope here is that we get a sense of the various types of architectures and weak memory consistency provided by them and thus\n// an appreciation for the design of the C++ abstract memory model.\n//\n// ******** REFERENCES ********\n// [1] Dekker's mutual exclusion algorithm made RW-safe\n// [2] Handling Memory Ordering in Multithreaded Applications with Oracle Solaris\n// [3] Evaluating the Cost of Atomic Operations on Modern Architectures\n// [4] A Tutorial Introduction to the ARM and POWER Relaxed Memory Models\n// [5] Memory Barriers: a Hardware View for Software Hackers\n// [6] Memory Model = Instruction Reordering + Store Atomicity\n// [7] ArMOR: Defending Against Memory Consistency Model Mismatches in Heterogeneous Architectures\n// [8] Weak Memory Models: Balancing Definitional Simplicity and Implementation Flexibility\n// [9] Repairing Sequential Consistency in C/C++11\n// [10] A high-level operational semantics for hardware weak memory models\n// [11] x86-TSO: A Rigorous and Usable Programmer's Model for x86 Multiprocessors\n// [12] Simplifying ARM Concurrency: Multicopy-Atomic Axiomatic and Operational Models for ARMv8\n// [13] Mixed-size Concurrency: ARM, POWER, C/C++11, and SC\n// [14] P0668R4: Revising the C++ memory model\n// [15] Constructing a Weak Memory Model\n// [16] The Superfluous Load Queue\n// [17] P0190R1: Proposal for New memory_order_consume Definition\n//\n// ******** What does it mean to be Atomic? ********\n//\n// The word atomic has been overloaded and can mean a lot of different things depending on the context,\n// so let's digest it.\n//\n// The first attribute for something to be atomic is that concurrent stores and loads\n// must not tear or shear. This means if two threads write 0x01 and 0x02 at the same time\n// then the only values that should ever be observed is 0x01 or 0x02. We can only see\n// the whole write of 0x01 or 0x02, not 0x03 as an example. Many algorithms rely on\n// this property; only very few such a Dekker's algorithm for mutual exclusion don't.\n// Well actually a recent paper, [1], showed that Dekker's isn't safe without atomic\n// loads and stores so this property is pretty fundamental and also hard to prove that\n// your algorithm is safe without this property on loads and stores.\n//\n// We need to ensure the compiler emits a single load instruction.\n// If we are doing 64-bit loads on a 32-bit platform, we need to ensure the load is one\n// instruction instead of 2 32-bit loads into two registers.\n// Another example is if we have this struct, struct { int32_t i; int32_t k; }, even on\n// a 64-bit system we have to ensure the compiler does one 64-bit load and not two\n// 32-bit loads for each individual member.\n//\n// We also need to ensure the correct instruction is emitted. A general load instruction\n// to do a 64-bit load on a 32-bit platform may perform a 64-bit load but it may not\n// be atomic, it may be turned into two 32-bit loads behind the scenes in the cpu.\n// For example on ARMv7 we would have to use ldrexd not ldrd for 64-bit loads\n// on a 32-bit ARMv7 core.\n//\n// An operation may be considered atomic if multiple sub-operations are done as one\n// transactional unit. This is commonly known as a Read-Modify-Write, RMW, operation.\n// Take a simple add operation; it is actually a load from memory into a register,\n// a modification of said register and then a store back to memory. If two threads\n// concurrently execute this add operation on the same memory location; any interleaving\n// of the 3 sub-operations is possible. It is possible that if the initial value is 0,\n// the result may be 1 because each thread executed in lockstep both loading 0, adding 1\n// and then storing 1. A RMW operation may be considered atomic if the whole sequence of\n// sub-operations are serialized as one transactional unit.\n//\n// Atomicity may also refer to the order in which memory operations are observed and the\n// dependencies between memory operations to different memory locations. As a quick example\n// into the very thing we will be deep diving into that is not very intuitive. If I do, [STORE(A, 2); STORE(B, 1);],\n// in one thread and another thread does, [r0 = LOAD(B); r1 = LOAD(A);]; if r0 == 1, thus we observed\n// the store to B, will we observe r1 == 2. Our intuition tells us that well A was stored\n// first and then B, so if I read the new value of B then I must also read the new value\n// of A since the store to A happened before B so if I can see B then I must be able to\n// see everything before B which includes A.\n// This highlights the ordering of memory operations and why memory barriers and memory\n// models are so heavily attached to atomic operations because one could classify something\n// is atomic if the dependency highlighted in the above example is allowed to be maintained.\n//\n// This is what people mean when you hear that volatile does NOT mean atomicity of the operation.\n// Usually people imply a lot of implicit assumptions when they mark a variable as volatile.\n// All volatile gives us is the ability to tell the compiler it may not assume anything\n// about the state of that memory location. This means the compiler must always emit a load\n// or store instruction, cannot perform constant folding, dead-store elimination, or\n// do any sort of code movement on volatile variables.\n//\n// ******** Preliminary Basics ********\n//\n// It is expected that the reader understands what a cache is, how it is organized and how data\n// is chunked into cachelines. It is helpful if the reader understands basic cache coherency\n// protocols such as MSI or MESI.\n// It is expected the reader understands alignment, especially natural alignment\n// of the processor and why alignment is important for data access.\n// The reader should have some understanding of how a processor executes instructions,\n// basics of what Out-of-Order execution means and basics of what speculative execution means.\n// It is expected that the reader has an understanding of threading, multi-threaded programming\n// and the use of concurrency primitives such as mutexes.\n// Memory Barrier, Barrier, Memory Fence and Fence are all interchangeable synonyms.\n//\n// Independent memory operations can be performed or observed, depending on your perspective,\n// in any order as long as the local cpu thinks its execution is happening in program order.\n// This can be a problem for inter-cpu communications and thus we need some way to enforce\n// that the compiler does not reorder instructions and that the cpu also does not reorder\n// instructions. This is what a barrier is, it is an enforcement of ordering on memory instructions,\n// so as the name suggests a barrier. Barriers can be one-sided or both-sided which means\n// the barrier enforces a partial order above or below or on both sides of said barrier.\n//\n// Processors will use tricks such as out-of-order execution, memory instruction buffering and\n// combining, speculative loads and speculative execution, branch prediction and many types of caching even\n// in various interconnects from the cpu to the memory itself. One key thing to note is that cpus\n// do not physically reorder the instruction stream. Instructions are dispatched and retired\n// in-order but executed out-of-order. Memory barriers will prevent these tricks from happening\n// by controlling the interaction of multiple cpus.\n//\n// Compilers will morph your code and physically move instructions around as long as the program\n// has the same observed behaviour. This is becoming increasingly true with more optimization techniques\n// such as Link Time Optimization becoming the norm where once people assumed compilers couldn't assume\n// something outside the given TU and now because they have the whole program view they know everything.\n// This means the compiler does indeed alter the instruction stream\n// and compiler barriers are a way to tell them to not move any memory instructions across the barrier.\n// This does not prevent a compiler from doing optimizations such as constant folding, merging of\n// overlapping loads, or even dead store elimination. Compiler barriers are also very cheap and\n// have zero impact on anything that the compiler knows isn't visible in memory such as local variables\n// whose addresses do not escape the function even if their address is taken. You can think of it\n// in terms of a sequence point as used with \"volatile\" qualified variables to denote a place in code where\n// things must be stable and the compiler doesn't cache any variables in registers or do any reordering.\n//\n// Memory Barriers come in many flavours that instill a partial or full ordering on memory operations.\n// Some memory operations themselves have implicit ordering guarantees already, for example\n// Total-Store Order, TSO, architectures like x86 guarantee that a store operation cannot be reordered with a\n// previous store operation thus a memory barrier that only orders stores is not needed\n// on this architecture other than ensuring the compiler doesn't do any shenanigans.\n// Considering we have 4 permutations of memory operations; a common way to describe an ordering\n// is via Load-Load/LDLD, Load-Store/LDST, Store-Store/STST or Store-Load/STLD notation. You read this\n// notation as follows; STLD memory barrier means a load cannot be reordered with a previous store.\n// For example, on TSO architecture we can say all stores provide a STST memory barrier,\n// since a store cannot be reordered with a previous store.\n//\n// Memory Barriers in itself are not a magic bullet, they come with caveats that must be known.\n// Each cpu architecture also has its own flavours and guarantees provided by said memory barriers.\n// There is no guarantee that memory instructions specified before a memory barrier will complete,\n// be written to memory or fully propagated throughout the rest of the system, when the memory barrier\n// instruction completes. The memory barrier creates a point in that local cpus queue of memory instructions\n// whereby they must not cross. There is no guarantee that using a memory barrier on one cpu will have\n// any effect at all on another remote cpu's observed view of memory. This also implies that executing\n// a memory barrier does not hinder, incur, stall or enforce any other cpus to serialize with each other cpu.\n// In order for a remote cpu to observe the correct effects it must also use a matching memory barrier.\n// This means code communicating in 2 threads through memory must both be employing the use of memory barriers.\n// For example, a store memory barrier that only orders stores, STST, in one thread must be paired with a load memory barrier\n// that only orders loads, LDLD, in the other thread trying to observe those stores in the correct order.\n//\n// ******** Memory Types && Devices ********\n//\n// eastl::atomic and accompanying memory barriers ONLY ORDER MEMORY to cpu-to-cpu communication through whatever the\n// processor designates as normal cacheable memory. It does not order memory to devices. It does not provide any DMA ordering guarantees.\n// It does not order memory with other memory types such as Write Combining. It strictly orders memory only to shared memory that is used\n// to communicate between cpus only.\n//\n// ******** Sequentially Consistent Machine ********\n//\n// The most intuitive as well as the model people naturally expect a concurrent system to have is Sequential Consistency.\n// You may have or definitely have heard this term if you dealt with any type of distributed system. Lamport's definition\n// articulates this consistency model the best.\n// Leslie Lamport: \"the result of any execution is the same as if the operations of all the processors were executed in some\n// sequential order, and the operations of each individual processor appear in this sequence in the order\n// specified by its program\".\n//\n// A Sequentially Consistent machine is modelled as follows:\n//\n// ------------ ------------\n// | Thread 0 | ... | Thread N |\n// ------------ ------------\n// | | | |\n// | | | |\n// ----------------------------------------\n// | |\n// | Shared Memory |\n// | |\n// ----------------------------------------\n//\n// This is a sequentially consistent machine. Each thread is executing instructions in program order which does loads and stores\n// that are serialized in some order to the shared memory. This means all communication is done through the shared memory with one cpu\n// doing one access at a time. This system has a couple key properties.\n//\n// 1. There is no local cpu memory reordering. Each cpu executes instructions in program order and all loads and stores must complete,\n// be visible in the shared memory or be visible in a register before starting the next instruction.\n// 2. Each memory operation becomes visible to all cpus at the same time. If a store hits the shared memory, then all subsequent loads\n// from every other cpu will always see the latest store.\n//\n// A Sequentially Consistent machine has, Single-Copy Store Atomicity: All stores must become visible to all cores in the system at the same time.\n//\n// ******** Adding Caches ********\n//\n// Caches by nature implicitly add the potential for memory reordering. A centralized shared snoopy bus that we all learned in school\n// makes it easy to implement sequential consistency with caches. Writes and reads are all serialized in a total order via the cache bus transaction\n// ordering. Every modern day bus is not inorder, and most certainly not a shared centralized bus. Cache coherency guarantees that all memory operations\n// will be propagated eventually to all parties, but it doesn't guarantee in what order or in what time frame. Once you add\n// caches, various levels of caching and various interconnects between remote cpus, you inevitably run into the issue where\n// some cpus observe the effects of a store before other cpus. Obviously we have weakly-ordered and strongly-ordered cpus with\n// caches so why is that? The short answer is, where is the onus put, is it on the programmer or the hardware. Does the hardware\n// have dependency tracking, is it able to determine when a memory order violation occurs such as rolling back its speculative execution\n// and also how far along the chain of interconnects does the hardware wait before it determines that the memory operation has\n// been acknowledged or is considered to satisfy its memory ordering guarantees. Again this is a very high level view of the system\n// as a whole, but the takeaway is yes; caches do add the potential for reordering but other supporting hardware determines whether\n// that is observable by the programmer. There is also some debate whether weakly-ordered processors are actually more performant\n// than strongly-ordered cpus eluding to the fact that the hardware has a better picture of what is a violation versus the programmer\n// having to emit far more barriers on weakly-ordered architectures in multi-threaded code which may actually not be needed because the\n// hardware didn't commit a violation but it may have and we as the programmer cannot rely on may haves.\n//\n// ******** Store Buffers ********\n//\n// Obviously having all stores serialize results in unnecessary stalls. Store buffers alleviate this issue.\n// Store buffers are simple fixed size structures that sit between the cpu and the memory hierarchy. This allows\n// each cpu to record its write in the store buffer and then move onto the next instruction. The store buffer will\n// eventually be flushed to the resulting memory hierarchy in FIFO order. How and when this flushing occurs is irrelevant to the\n// understanding of a store buffer. A read from an address will grab the most recent write to the same address in the store buffer.\n//\n// The introduction of a store buffer is our first dive into weaker memory consistency. The addition of this hardware turns the consistency model weaker,\n// into one that is commonly known as TSO, Total-Store Order. This is the exact model used by x86 cpus and we will see what this means\n// and what new effects are observed with the addition of the store buffer. Below is a diagram of how the machine may now look.\n// This type of store buffer is known as a FIFO store buffer, FIFO write buffer, or Load/Store Queue in some literature. This type of\n// store buffer introduces STLD reordering but still prevents STST reordering. We will take a look at another type of store buffer later.\n// Even with this store buffer, stores to the same address can still be merged so that only the latest store is written to the cache assuming\n// no other intermediary stores happen. x86 cpus do write merging even for consecutive stores, i.e. storing to A and A+1 can be merged into one two-byte store.\n//\n// ------------ ------------\n// | Thread 0 | ... | Thread N |\n// ------------ ------------\n// | | | |\n// | | | |\n// | Store | | Store |\n// | Buffer | | Buffer |\n// | | | |\n// ----------------------------------------\n// | |\n// | Shared Memory |\n// | |\n// ----------------------------------------\n//\n// ---- Store-Buffering / Dekker's Example ----\n// This is a very common litmus test that showcases the introduction of STLD reordering. It is called Store-Buffering example because it is the only weaker\n// behaviour observed under TSO and also called Dekker's Example as it famously breaks Dekker's mutual exclusion algorithm.\n//\n// ---------------------------\n// Initial State:\n// x = 0; y = 0;\n// ---------------------------\n// Thread 0 | Thread 1\n// ---------------------------\n// STORE(x, 1) | STORE(y, 1)\n// r0 = LOAD(y) | r1 = LOAD(x)\n// ---------------------------\n// Observed: r0 = 0 && r1 = 0\n// ---------------------------\n//\n// We would normally assume that any interleaving of the two threads cannot possibly end up with both loads reading 0. We assume that the observed outcome\n// of r0 = 0 && r1 = 0 to be impossible, clearly that is not the case. Let's start by understanding the example with no reordering possible. Both threads\n// run and their first instruction is to write the value 1 into either x or y, the next instruction then loads from the opposite variable. This means no\n// matter the interleaving, one of the loads always executes after the other thread's store to that variable.\n// We could observe r0 = 1 && r1 = 1 if both threads execute in lockstep.\n// We could observe r0 = 0 && r1 = 1 if thread 0 executes and then thread 1 executes.\n// We could observe r0 = 1 && r1 = 0 if thread 1 executes and then thread 0 executes.\n// Since the stores always execute before that load in the other thread, one thread must always at least observe a store, so let's see why store buffers break this.\n//\n// What will happen is that STORE(x, 1) is stored to the store buffer but not made globally visible yet.\n// STORE(y, 1) is written to the store buffer and also is not made globally visible yet.\n// Both loads now read the initial state of x and y which is 0. We got the r0 = 0 && r1 = 0 outcome and just observed a Store-Load reordering.\n// It has appeared as if the loads have been reordered with the previous stores and thus executed before the stores.\n// Notice even if we execute the instructions in order, a series of other hardware side effects made it appear as if the instructions have been reordered.\n// We can solve this by placing a Store-Load barrier after the store and before the load as follows.\n//\n// ---------------------------\n// Thread 0 | Thread 1\n// ---------------------------\n// STORE(x, 1) | STORE(y, 1)\n// STLD BARRIER | STLD BARRIER\n// r0 = LOAD(y) | r1 = LOAD(x)\n// ---------------------------\n//\n// This STLD barrier effectively will flush the store buffer into the memory hierarchy ensuring all stores in the buffer are visible to all other cpus at the same time\n// before executing the load instruction. Again nothing prevents a potential hardware from speculatively executing the load even with the STLD barrier, the hardware will have to do\n// a proper rollback if it detected a memory order violation otherwise it can continue on with its speculative load. The barrier just delimits a stability point.\n//\n// Most hardware does not provide granular barrier semantics such as STLD. Most provide a write memory barrier which only orders stores, STST, a read memory barrier\n// which only orders loads, LDLD, and then a full memory barrier which is all 4 permutations. So on x86 we will have to use the mfence, memory fence, instruction\n// which is a full memory barrier to get our desired STLD requirements.\n//\n// TSO also has the property that we call, Multi-Copy Store Atomicity. This means a cpu sees its own stores before they become visible to other cpus,\n// by forwarding them from the store buffer, but a store becomes visible to all other cpus at the same time when flushed from the store buffer.\n//\n//\n// Let's look at a non-FIFO store buffer now as seen in ARM cpus as an example and we will use a standard Message Passing example to see how it manifests in even weaker consistency.\n// A store buffer on ARM as an example allows write merging even with adjacent stores, is not a FIFO queue, any stores in the small hardware hash table may be ejected at any point\n// due to a collision eviction or the availability of cachelines in the cache hierarchy meaning that stores may bypass the buffer entirely if that cacheline is already owned by that cpu.\n// There is no guarantee that stores will be completed in order as in the FIFO case.\n//\n// ---------------------------\n// Initial State:\n// x = 0; y = 0;\n// ---------------------------\n// Thread 0 | Thread 1\n// ---------------------------\n// STORE(x, 1) | while(LOAD(y) == 0);\n// STORE(y, 1) | r0 = LOAD(x)\n// ---------------------------\n// Observed: r0 = 0\n// ---------------------------\n//\n// This is a classic Message Passing example that is very commonly used in production code. We store some values and then set a flag, STORE(y, 1) in this case.\n// The other thread waits until the flag is observed and then reads the value out of x. If we observed the flag then we should obviously see all stores before the flag was set.\n// Given our familiarity with TSO consistency above we know this definitely works on TSO and it is impossible to observe the load of x returning 0 under that consistency model.\n// Let's see how this breaks with a non-FIFO store buffer.\n//\n// Thread 0 executes the STORE(x, 1) but the cacheline for x is not in thread 0's cache so we write to the store buffer and wait for the cacheline.\n// Thread 1 executes the LOAD(y) and it also does not have y in its cacheline so it waits before completing the load.\n// Thread 0 moves on to STORE(y, 1). It owns this cacheline, hypothetically, so it may bypass the store buffer and store directly to the cache.\n// Thread 0 receives a message that Thread 1 needs y's cacheline, so it transfers the now modified cacheline to Thread 1.\n// Thread 1 completes the load with the updated value of y = 1 and branches out of the while loop since we saw the new value of y.\n// Thread 1 executes LOAD(x) which will return 0 since Thread 0 still hasn't flushed its store buffer waiting for x's cacheline.\n// Thread 0 receives x's cacheline and now flushes x = 1 to the cache. Thread 1 will also have invalidated its cacheline for x that it brought in via the previous load.\n//\n// We have now fallen victim to STST reordering, allowing Thread 1 to observe a load of x returning 0. Not only does this store buffer allow STLD reordering due to the nature of\n// buffering stores, but it also allows another reordering; that of Store-Store reordering. It was observed as if Thread 0 executed STORE(y, 1) before STORE(x, 1) which completely\n// broke our simple message passing scenario.\n//\n// ---------------------------\n// Thread 0 | Thread 1\n// ---------------------------\n// STORE(x, 1) | while(LOAD(y) == 0);\n// STST BARRIER |\n// STORE(y, 1) | r0 = LOAD(x)\n// ---------------------------\n//\n// The STST memory barrier effectively ensures that the cpu will flush its store buffer before executing any subsequent stores. That is not entirely true, the cpu is still allowed\n// to continue and execute stores to the store buffer as long as it doesn't flush them to the cache before the previous stores are flushed to the cache. If nothing becomes\n// globally visible out of order then we are good.\n// The example above will change how the processor executes due to the STST memory barrier. Thread 0 will execute STORE(y, 1), write to the store buffer and mark all current entries. Even though it owns the cacheline\n// it cannot write the store to the cache until all marked entries, which are all the previous stores, are flushed to the cache. We have now fixed the message passing code by adding\n// a STST or write memory barrier and thus it is no longer possible to observe the load of x returning 0.\n//\n// ******** Invalidation Queues ********\n//\n// Due to the cache coherency protocol in play, a write to a cacheline will have to send invalidation messages to all other cpus that may have that cacheline as well.\n// Immediately executing and responding to invalidation messages can cause quite a stall especially if the cache is busy at the moment with other requests.\n// The longer we wait to invalidate the cacheline, the longer the remote cpu doing the write is stalled waiting on us. We don't like this very much.\n// Invalidation Queues are just that, we queue up the action of actually invalidating the cacheline but immediately respond to the request saying we did it anyway.\n// Now the remote cpu thinks we invalidated said cacheline but actually it may very well still be in our cache ready to be read from. We just got weaker again, let's\n// see how this manifests in code by starting from the end of our previous example.\n//\n// ---------------------------\n// Initial State:\n// x = 0; y = 0;\n// ---------------------------\n// Thread 0 | Thread 1\n// ---------------------------\n// STORE(x, 1) | while(LOAD(y) == 0);\n// STST BARRIER |\n// STORE(y, 1) | r0 = LOAD(x)\n// ---------------------------\n// Observed: r0 = 0\n// ---------------------------\n//\n// Thread 1 receives the invalidate x's cacheline message and queues it because it is busy.\n// Thread 1 receives the invalidate y's cacheline message, but we don't have that cacheline so acknowledge immediately.\n// Thread 1 executes LOAD(y), loads in y's cacheline and branches out of the loop.\n// Thread 1 executes LOAD(x), and loads from the cache the old value of x because the invalidation message is still sitting in the invalidation queue.\n//\n// We have just again observed the load of x returning 0 but from a different type of reordering now on the reader side.\n// This is a form of LDLD, Load-Load, reordering as it appears as if LOAD(x) was executed before LOAD(y). This can be fixed as follows.\n//\n// ---------------------------\n// Thread 0 | Thread 1\n// ---------------------------\n// STORE(x, 1) | while(LOAD(y) == 0);\n// STST BARRIER | LDLD BARRIER\n// STORE(y, 1) | r0 = LOAD(x)\n// ---------------------------\n//\n// The LDLD memory barrier essentially marks all entries currently in the invalidation queue. Any subsequent load must wait until all the marked entries have been\n// processed. This ensures once we observe y = 1, we process all entries that came before y and that way we observe all the stores that happened before y.\n// The insertion of the read memory barrier creates the required memory barrier pairing as discussed above and ensures that now our code executes as expected.\n//\n// It must be made clear that these are not the only hardware structure additions or ways that can relax STST, STLD and LDLD orderings. These are merely\n// 2 structures that are common and ones that I choose to use as examples of how hardware can reduce ordering guarantees. Knowing how the hardware does this\n// isn't always entirely clear but having a model that tells us what operations can be reordered is all we need to be able to reason about our code when executing on that hardware.\n//\n// ******** Load Buffering ********\n//\n// The analog of the Store Buffering example, this litmus test has two threads read from two different locations and then write to the other locations.\n// The outcome of having LDST reordering is allowed and observable on many processors such as ARM.\n//\n// ---------------------------\n// Initial State:\n// x = 0; y = 0;\n// ---------------------------\n// Thread 0 | Thread 1\n// ---------------------------\n// r0 = LOAD(x) | r1 = LOAD(y)\n// STORE(y, 1) | STORE(x, 1)\n// ---------------------------\n// Observed: r0 = 1 && r1 = 1\n// ---------------------------\n//\n// This is possible because the processor does not have to wait for the other cpu's cacheline to arrive before storing into the cache.\n// Assume Thread 0 owns y's cacheline and Thread 1 owns x's cacheline.\n// The processor may execute the load and thus buffer the load waiting for the cacheline to arrive.\n// The processor may continue onto the store and since each cpu owns their respective cacheline, store the result into the cache.\n// The cpus now receive the cachelines for x and y with the now modified value.\n// We have just observed the loads returning 1 and thus observed LDST reordering.\n//\n// To forbid such outcome it suffices to add any full memory barrier to both threads or a local Read-After-Write/Read-To-Write dependency or a control dependency.\n//\n// -------------------------------\n// Thread 0 | Thread 1\n// -------------------------------\n// r0 = LOAD(x) | r1 = LOAD(y)\n// if (r0 == 1) | if (r1 == 1)\n// STORE(y, 1) | STORE(x, 1)\n// -------------------------------\n//\n// -----------------------------------------------------\n// Thread 0 | Thread 1\n// -----------------------------------------------------\n// r0 = LOAD(x) | r1 = LOAD(y)\n// STORE(&(y + r0 - r1), 1) | STORE(&(x + r1 - r1), 1)\n// -----------------------------------------------------\n//\n// Both fixes above ensure that both writes cannot be committed, made globally visible, until their program source code order preceding reads have been fully satisfied.\n//\n// ******** Compiler Barriers ********\n//\n// Compiler barriers are both-sided barriers that prevent loads and stores from moving down past the compiler barrier and\n// loads and stores from moving up above the compiler barrier. Here we will see the various ways our code may be subject\n// to compiler optimizations and why compiler barriers are needed. Note as stated above, compiler barriers may not\n// prevent all compiler optimizations or transformations. Compiler barriers are usually implemented by reloading all\n// variables that are currently cached in registers and flushing all stores in registers back to memory.\n// This list isn't exhaustive but will hopefully try to outline what compiler barriers protect against and what they don't.\n//\n// Compiler may reorder loads.\n// LOAD A; LOAD B; -> LOAD B; LOAD A;\n// LOAD A; operation on A; LOAD B; operation on B; -> LOAD A; LOAD B; operation on A; operation on B\n//\n// Insert a compiler barrier in between the two loads to guarantee that they are kept in order.\n// LOAD A; COMPILER_BARRIER; LOAD B;\n// LOAD A; operation on A; COMPILER_BARRIER; LOAD B; operation on B;\n//\n// The same with stores.\n// STORE(A, 1); STORE(B, 1); -> STORE(B, 1); STORE(A, 1);\n// operations and STORE result into A; operations and STORE result int B; -> all operations; STORE result into B; STORE result into A;\n//\n// Insert a compiler barrier in between the two stores to guarantee that they are kept in order.\n// It is not required that the multiple stores to A before the barrier are not merged into one final store.\n// It is not required that the store to B after the barrier be written to memory, it may be cached in a register for some indeterminate\n// amount of time as an example.\n// STORE(A, 1); COMPILER_BARRIER; STORE(B, 1);\n//\n// The compiler is allowed to merge overlapping loads and stores.\n// Inserting a compiler barrier here will not prevent the compiler from doing this optimization as doing one wider load/store is\n// technically still abiding by the guarantee that the loads/stores are not reordered with each other.\n// LOAD A[0]; LOAD A[1]; -> A single wider LOAD instruction\n// STORE(A[0], 1); STORE(A[1], 2); -> A single wider STORE instruction\n//\n// Compilers do not have to reload the values pointers point to. This is especially common with RISC architectures with lots\n// of general purpose registers or even compiler optimizations such as inlining or Link-Time Optimization.\n// int i = *ptr; Do bunch of operations; if (*ptr) { do more; }\n// It is entirely possible the compiler may remove the last if statement because it can keep the *ptr in a register\n// and it may infer from the operations done on i that i is never 0.\n//\n// int i = *ptr; Do bunch of operations; COMPILER_BARRIER; if (*ptr) { do more; }\n// Inserting a compiler barrier at that location will cause the compiler to have reload *ptr thus keeping the if statement assuming\n// no other optimizations take place, such as the compiler knowing that *ptr is always greater than 0.\n//\n// The compiler is within its rights to also merge and reload loads as much as it pleases.\n//\n// while (int tmp = LOAD(A))\n// process_tmp(tmp)\n//\n// Will be merged and transformed to\n//\n// if (int tmp = LOAD(A))\n// for (;;) process_tmp(tmp)\n//\n// Inserting a compiler barrier will ensure that LOAD(A) is always reloaded and thus the unwanted transformation is avoided.\n//\n// while (int tmp = LOAD(A))\n// {\n// process_tmp(tmp)\n// COMPILER_BARRIER\n// }\n//\n// Under heavy register pressure scenarios, say the loop body was larger, the compiler may reload A as follows.\n// Compiler barriers cannot prevent this from happening, even if we put it after process_tmp as above;\n// the compiler still kept those loads above the barrier so it satisfied its contract even though it reloaded\n// from A more than once.\n//\n// while (int tmp = LOAD(A))\n// process_tmp(LOAD(A))\n//\n// In the above transformation it is possible that another cpu stores 0 into A. When we reload A for process_tmp, we pass 0\n// to process_tmp() which it would actually never expect to observe. Because if we observed 0, the while loop condition\n// would never be satisfied. If the compiler under register pressure instead stored and loaded tmp from its stack slot, that is fine\n// because we are just storing and loading the original observed value from A. Obviously that is slower than just reloading from\n// A again so an optimizing compiler may not do the stack slot store. This is an unwanted transformation which eastl::atomic prevents\n// even on relaxed loads.\n//\n// The compiler is allowed to do dead-store elimination if it knows that value has already been stored, or that only the last store\n// needs to be stored. The compiler does not assume or know that these variables are shared variables.\n//\n// STORE(A, 1); STORE(A, 1);\n// OPERATIONS; -> OPERATIONS;\n// STORE(A, 1);\n//\n// The compiler is well within its rights to omit the second store to A. Assuming we are doing some fancy lockfree communication\n// with another cpu and the last store is meant to ensure the ending value is 1 even if another cpu changed A in between; that\n// assumption will not be satisfied. A compiler barrier will not prevent the last store from being dead-store removed.\n//\n// STORE(A, 1);\n// OPERATIONS;\n// STORE(A, 2);\n//\n// Assuming these stores are meant to denote some state changes to communicate with a remote cpu. The compiler is allowed to\n// transform this as follows without a compiler barrier. Insert a compiler barrier between the two stores to prevent the transformation.\n// Something like this will also require memory barriers, but that is not the point of this section.\n//\n// STORE(A, 2);\n// OPERATIONS;\n//\n// The compiler is also allowed to invent stores as it may please.\n// First on many RISC architectures storing an immediate value either involves loading the immediate from the .data section\n// or combing a variety of load upper immediate and add or or immediate instructions to get our constant in a register and then\n// doing a single 32-bit store instruction from said register. Some ISAs have 16-bit stores with immediate value so that a store\n// may be broken into 2 16-bit store immediate values causing shearing. To reduce instruction dependencies it may also decide\n// to do two add immediates and then two 16-bit stores again causing shearing.\n//\n// lui $t0, 1 # t0 == 0x00010000\n// ori $a0, $t0, 8 # t0 == 0x00010008\n// strw $t0, 0($a1) # store t0 into address at a1\n// ->\n// ori $a0, $t0, 1 # t0 == 0x00000001\n// ori $a0, $t1, 8 # t0 == 0x00000008\n// strhw $t0, 0($a1) # store t0 lower half at a1\n// strhw $t1, 2($a1) # store t1 upper half at a1\n//\n// The above shows a potential transformation that a compiler barrier cannot solve for us.\n//\n// A compiler may also introduce stores to save on branching. Let's see.\n//\n// if (a)\n// STORE(X, 10);\n// else\n// STORE(X, 20);\n//\n// STORE(X, 20);\n// if (a)\n// STORE(X, 10);\n//\n// This is a very common optimization as it saves a potentially more expensive branch instruction but breaks multi-threaded code.\n// This is also another case where a compiler barrier doesn't give us the granularity we need.\n// The branches may even be completely removed with the compiler instead choosing to use conditional move operations which would\n// actually be compliant since there would be one store only done, an extra store wouldn't have been added.\n//\n// You are now probably thinking that compiler barriers are useful and are definitely needed to tell the compiler to calm down\n// and guarantee our hardware guarantees are valid because the code we wrote is the instructions that were emitted.\n// But there are definitely lots of caveats where compiler barriers do not at all provide the guarantees we still need.\n// This where eastl::atomic comes into play, and under the relaxed memory ordering section it will be explained\n// what the standard guarantees and how we achieve those guarantees, like ensuring the compiler never does dead-store elimination or reloads.\n//\n// ******** Control Dependencies ********\n//\n// Control dependencies are implicit local cpu ordering of memory instructions due to branching instructions, specifically\n// only conditional branches. The problem is compilers do not understand control dependencies, and control dependencies\n// are incredibly hard to understand. This is meant to make the reader aware they exist and to never use them\n// because they shouldn't be needed at all with eastl::atomic. Also control dependencies are categorized as LDLD or LDST,\n// store control dependencies inherently do not make sense since the conditional branch loads and compares two values.\n//\n// A LDLD control dependency is an anti-pattern since it is not guaranteed that any architecture will detect the memory-order violation.\n// r0 = LOAD(A);\n// if (r0)\n// r1 = LOAD(B)\n//\n// Given those sequence of instructions, it is entirely possible that a cpu attempts to speculatively predict and load the value of B\n// before the branch instruction has finished executing. It is entirely allowed that the cpu loads from B, assume B is in cache and A\n// is not in cache, before A. It is allowed, that even if the cpu was correct in it's prediction that it doesn't reload B and change the\n// fact that it speculatively got lucky.\n//\n// This is also what the x86 pause instruction inserted into spin wait loops is meant to solve.\n// LOOP:\n// r0 = LOAD(A);\n// if (!r0) pause; goto LOOP;\n//\n// In the above spin loop, after a couple of iterations the processor will fill the pipeline with speculated cmp and load instructions.\n// x86 will catch a memory order violation if it sees that an external store was done to A and thus must flush the entire\n// pipeline of all the speculated load A. Pause instruction tells the cpu to not do speculative loads so that the pipeline is not\n// filled with all said speculative load instructions. This ensures we do not incur the costly pipeline flushes from memory order\n// violations which are likely to occur in tight spin wait loops. This also allows other threads on the same physical core to use the\n// core's resources better since our speculative nature won't be hogging it all.\n//\n// A LDST control dependency is a true dependency in which the cpu cannot make a store visible to the system and other cpus until it\n// knows its prediction is correct. Thus a LDST ordering is guaranteed and can be always relied upon as in the following example.\n//\n// r0 = LOAD(A);\n// if (r0)\n// STORE(B, 1);\n//\n// The fun part comes in with how does the compiler actually break all of this.\n// First is that if the compiler can ensure that the value of A in the LDST example is always not zero, then it is always within its\n// rights to completely remove the if statement which would lend us with no control dependency.\n//\n// Things get more fun when we deal with conditionals with else and else if statements where the compiler might be able to employ\n// invariant code motion optimizations. Take this example.\n//\n// r0 = LOAD(A);\n// r1 = LOAD(B);\n// if (r0)\n// STORE(B, 1);\n// /* MORE CODE */\n// else if (r1)\n// STORE(B, 1);\n// /* MORE CODE */\n// else\n// STORE(B, 1);\n// /* MORE CODE */\n//\n// If we were trying to be smart and entirely rely on the control dependency to ensure order, ya well just don't the compiler\n// is always smarter. The compiler is well within its rights to move all the STORE(B, 1) up and above all the conditionals breaking\n// our reliance on the LDST control dependency.\n//\n// Things can get even more complicated especially in C++ when values may come from constexpr, inline, inline constexpr, static const, etc,\n// variables and thus the compiler will do all sorts of transformations to reduce, remove, augment and change all your conditional code since\n// it knows the values of the expressions or even parts of it at compile time. Even more aggressive optimizations like LTO might break code that was being cautious.\n// Even adding simple short circuiting logic or your classic likely/unlikely macros can alter conditionals in ways you didn't expect.\n// In short know enough about control dependencies to know not to ever use them.\n//\n// ******** Multi-Copy Store Atomicity && Barrier Cumulativity ********\n//\n// Single-Copy Store Atomicity: All stores must become visible to all cores in the system at the same time.\n//\n// Multi-Copy Store Atomicity : This means a cpu sees its own stores before they become visible to other cpus, by forwarding them from the store buffer,\n// but a store becomes visible to all other cpus at the same time when flushed from the store buffer.\n//\n// Non-Atomic Store Atomicity : A store becomes visible to different cpus at different times.\n//\n// Those are the above variations of Store Atomicity. Most processors have Non-Atomic Store Atomicity and thus you must program to that lowest common denominator.\n// We can use barriers, with some caveats, to restore Multi-Copy Store Atomicity to a Non-Atomic system though we need to define a new granular definition for\n// memory barriers to define this behaviour. Simple LDLD/LDST/STST/STLD definition is not enough to categorize memory barriers at this level. Let's start off\n// with a simple example that breaks under a Non-Atomic Store Atomicity system and what potential hardware features allow this behaviour to be observed.\n//\n// NOTE: For all the below examples we assume no compile reordering and that the processor also executes the instructions with no local reorderings to make the examples simpler,\n// to only show off the effects of Multi-Copy Store Atomicity. This is why we don't add any address dependencies, or mark explicit LDLD/LDST memory barriers.\n// Thus you may assume all LDLD and LDST pairs have an address dependency between them, so that they are not reordered by the compiler or the local cpu.\n//\n// ---------------------------------------------------------------------------------------------------------\n// Write-To-Read Causality, WRC, Litmus Test\n// ---------------------------------------------------------------------------------------------------------\n// Initial State:\n// X = 0; Y = 0;\n// ---------------------------------------------------------------------------------------------------------\n// Thread 0 | Thread 1 | Thread 2\n// ---------------------------------------------------------------------------------------------------------\n// STORE(X, 1) | r0 = LOAD(X) | r1 = LOAD(Y)\n// | STORE(Y, r0) | r2 = LOAD(X)\n// ---------------------------------------------------------------------------------------------------------\n// Observed: r0 = 1 && r1 = 1 && r2 = 0\n// ---------------------------------------------------------------------------------------------------------\n//\n// Let's go over this example in detail and whether the outcome shown above can be observed. In this example Thread 0 stores 1 into X. If Thread 1 observes the write to X,\n// it stores the observed value into Y. Thread 2 loads from Y then X. This means if the load from Y returns 1, then we intuitively know the global store order\n// was 1 to X and then 1 to Y. So is it possible then that the load from X in Thread 2 can return 0 in that case? Under a Multi-Copy Store Atomicity system, that would be\n// impossible because once 1 was stored to X all cpus see that store so if Thread 2 saw the store to Y which can only happen after the store to X was observed, then\n// Thread 2 must also have observed the store to X and return 1. As you may well have figured out, it is possible under a Non-Atomic Store Atomicity system to still\n// observe the load from X returning 0 even if the above load from Y returned 1 in Thread 2. This completely breaks our intuition of causality. Let's now understand what hardware may cause this.\n//\n// This is possible on cpus that have Simultaneous Multi-Threading, SMT or HyperThreading in Intel parlance, which share resources such as store buffers or L1 cache.\n// We are accustomed to the x86 way of SMT where each logical core shares Execution Units on the physical core but each logical core has their own statically partitioned\n// cache and store buffer that is not visible to the other cpus. It is possible on cpus like ARMv7 or POWER, POWER9 supports 4 and even 8 threads per physical core, so\n// to save on die space though yet enable this large number of threads per physical core it is common for these logical cores to all use the same store buffer or L1 cache\n// per physical core on these processors. Let's take the above example and rerun it with this knowledge to get the observed behaviour outlined above.\n//\n// Assume Thread 0, Thread 1, and Thread 2 run on cpu 0, cpu 1, and cpu 2 respectively. Assume that cpu 0 and cpu 1 are two logical cores on the same physical core so this processor\n// has an SMT value of 2. Thread 0 will store 1 into X. This store may be in the store buffer or in the L1 cache that cpu 1 also shares with cpu 0, thus cpu 1 has early access to cpu 0's stores.\n// Thread 1 loads X which it observed as 1 early and then stores 1 into Y. Thread 2 may see the load from Y returning 1 but now the load from X returning 0 all because cpu 1 got early\n// access to cpu 0 store due to sharing a L1 cache or store buffer.\n// We will come back on how to fix this example with the proper memory barriers for the Non-Atomic Store Atomicity systems, but we need to detour first.\n//\n// We need to take a deeper dive into memory barriers to understand how to restore Multi-Copy Store Atomicity from a Non-Atomic Store Atomicity system.\n// Let's start with a motivating example and we will be using the POWER architecture throughout this example because it encompasses all the possible observable behaviour.\n// ARMv7 technically allows Non-Atomic Store Atomicity behaviour but no consumer ARMv7 chip actually observes this behaviour.\n// ARMv8 reworked its model to specifically say it is a Multi-Copy Store Atomicity system.\n// POWER is one of the last few popular consumer architectures that are guaranteed to have Non-Atomic Store Atomicity observable behaviour, thus we will be using it for the following examples.\n//\n// To preface, POWER has two types of memory barriers called lwsync and sync. The following table lists the guarantees provided by TSO, x86, and the lwsync instruction.\n// The table gives a hint as to why using our previous definition of LDLD/LDST/STST/STLD isn't granular enough to categorize memory barrier instructions.\n//\n// TSO: | POWER lwsync memory barrier:\n// LDLD : YES | LDLD : YES\n// LDST : YES | LDST : YES\n// STST : YES | STST : YES\n// STLD : NO | STLD : NO\n// A cumulative : YES | A cumulative : YES\n// B cumulative : YES | B cumulative : YES\n// IRIW : YES | IRIW : NO\n//\n// The TSO memory model provided by x86 seems to be exactly the same as POWER if we add lwsync memory barrier instructions in between each of the memory instructions.\n// This provides us the exact same ordering guarantees as the TSO memory model. If we just looked at the 4 permutations of reorderings we would be inclined to assume that\n// TSO has the exact same ordering as sprinkling lwsync in our code in between every pair of memory instructions. That is not the case because memory barrier causality and cumulativity differ in subtle ways.\n// In this case they differ by the implicit guarantees from the TSO memory model versus those provided by the POWER lwsync memory barrier.\n// So the lwsync memory barrier prevents reordering with instructions that have causality but does not prevent reordering with instructions that are completely independent.\n// Let's dive into these concepts a bit more.\n//\n// Non-Atomic Store Atomicity architectures are prone to behaviours such as the non-causal outcome of the WRC test above. Architectures such as POWER defines memory barriers to enforce\n// ordering with respect to memory accesses in remote cpus other than the cpu actually issuing the memory barrier. This is known as memory barrier cumulativity.\n// How does the memory barrier issued on my cpu affect the view of memory accesses done by remote cpuss.\n//\n// Cumulative memory barriers are defined as follows - Take your time this part is very non-trivial:\n// A-Cumulative: We denote group A as the set of memory instructions in this cpu or other cpus that are ordered before the memory barrier in this cpu.\n// A-Cumulativity requires that memory instructions from any cpu that have performed prior to a memory load before the memory barrier on this cpu are also members of group A.\n// B-Cumulative: We denote group B as the set of memory instructions in this cpu or other cpus that are ordered after the memory barrier in this cpu.\n// B-Cumulativity requires that memory instructions from any cpu that perform after a load and including the load in that cpu that returns the value of a store in group B are\n// also members of group B.\n// IRIW : enforces a global ordering even for memory instructions that have no causality. The memory instructions are completely independent.\n//\n// ---------------------------------------------------------------------------------------------------------\n// WRC Litmus Test\n// ---------------------------------------------------------------------------------------------------------\n// Thread 0 | Thread 1 | Thread 2\n// ---------------------------------------------------------------------------------------------------------\n// {i} : STORE(X, 1) | {ii} : r0 = LOAD(X) | {v} : r1 = LOAD(Y)\n// | {iii} : lwsync |\n// | {iv} : STORE(Y, r0) | {vi} : r2 = LOAD(X)\n// ---------------------------------------------------------------------------------------------------------\n// Outcome: r0 = 1 && r1 = 1 && r2 = 1\n//\n// Group A of {iii} : {i} && {ii}\n//\n// Group B of {iii} : {iv} && {v} && {vi}\n// ---------------------------------------------------------------------------------------------------------\n//\n// Using the WRC test again and inserting a POWER lwsync, don't concern yourself with why the memory barrier was inserted at that spot right now, we now see the distinctions of group A and group B.\n// It demonstrates the A and B Cumulative nature of the lwsync instruction, {iii}. First group A, initially consists of {ii} and group B initially consists of {iv} from the local cpu that issued the lwsync.\n// Since {ii} reads from {i} and assume {i} happens before {ii}, by definition of A-Cumulativity {i} is included in group A.\n// Similarly {v} reads from {iv} and assume {iv} happens before {v}, then {v} is included in group B by definition of B-Cumulativity.\n// {vi} is also included in group B since it happens after {v} by definition of B-Cumulativity.\n//\n// WRC litmus test represents a scenario where only a A-Cumulative memory barrier is needed. The lwsync not only provides the needed local LDST memory barrier for the local thread but also ensures\n// that any write Thread 1 has read from before the memory barrier is kept in order with any write Thread 1 does after the memory barrier as far as any other thread observes.\n// In other words it ensures that any write that has propagated to Thread 1 before the memory barrier is propagated to any other thread before the second store after the memory barrier in Thread 1\n// can propagate to other threads in the system. This is exactly the definition of A-Cumulativity and what we need to ensure that causality is maintained in the WRC Litmus Test example.\n// With that lwsync in place it is now impossible to observe r0 = 1 && r1 = 1 && r2 = 0. The lwsync has restored causal ordering. Let's look at an example that requires B-Cumulativity.\n//\n// ---------------------------------------------------------------------------------------------------------\n// Example 2 from POWER manual\n// ---------------------------------------------------------------------------------------------------------\n// Initial State:\n// X = 0; Y = 0; Z = 0\n// ---------------------------------------------------------------------------------------------------------\n// Thread 0 | Thread 1 | Thread 2\n// ---------------------------------------------------------------------------------------------------------\n// STORE(X, 1) | r0 = LOAD(Y) | r1 = LOAD(Z)\n// STORE(Y, 1) | STORE(Z, r0) | r2 = LOAD(X)\n// ---------------------------------------------------------------------------------------------------------\n// Observed: r0 = 1 && r1 = 1 && r2 = 0\n// ---------------------------------------------------------------------------------------------------------\n//\n// This example is very similar to WRC except that we kinda extended the Message Passing through an additional shared variable instead.\n// Think of this as Thread 0 writing some data into X, setting flag Y, Thread 1 waiting for flag Y then writing flag Z, and finally Thread 2 waiting for flag Z before reading the data.\n// Take a minute to digest the above example and think about where a memory barrier, lwsync, should be placed. Don't peek at the solution below.\n//\n// ---------------------------------------------------------------------------------------------------------\n// Example 2 from POWER manual\n// ---------------------------------------------------------------------------------------------------------\n// Thread 0 | Thread 1 | Thread 2\n// ---------------------------------------------------------------------------------------------------------\n// STORE(X, 1) | r0 = LOAD(Y) | r1 = LOAD(Z)\n// lwsync | |\n// STORE(Y, 1) | STORE(Z, r0) | r2 = LOAD(X)\n// ---------------------------------------------------------------------------------------------------------\n//\n// First the lwsync provides the needed local STST memory barrier for the local thread, thus the lwsync here ensures that the store to X propagates to Thread 1 before the store to Y.\n// B-Cumulativity applied to all operations after the memory barrier ensure that the store to X is\n// kept in order with respect to the store to Z as far as all other threads participating in the dependency chain are concerned. This is the exact definition of B-Cumulativity.\n// With this one lwsync the outcome outlined above is impossible to observe. If r0 = 1 && r1 = 1 then r2 must be properly observed to be 1.\n//\n// We know that lwsync only provides A-Cumulativity and B-Cumulativity. Now we will look at examples that have no causality constraints thus we need to grab heavier memory barriers\n// that ensures in short we will say makes a store become visible to all processors, even those not on the dependency chains. Let's get to the first example.\n//\n// ---------------------------------------------------------------------------------------------------------\n// Independent Reads of Independent Writes, IRIW, coined by Doug Lea\n// ---------------------------------------------------------------------------------------------------------\n// Initial State:\n// X = 0; Y = 0;\n// ---------------------------------------------------------------------------------------------------------\n// Thread 0 | Thread 1 | Thread 2 | Thread 3\n// ---------------------------------------------------------------------------------------------------------\n// STORE(X, 1) | r0 = LOAD(X) | STORE(Y, 1) | r2 = LOAD(Y)\n// | r1 = LOAD(Y) | | r3 = LOAD(X)\n// ---------------------------------------------------------------------------------------------------------\n// Observed: r0 = 1 && r1 = 0 && r2 = 1 && r3 = 0\n// ---------------------------------------------------------------------------------------------------------\n//\n// The IRIW example above clearly shows that writes can be propagated to different cpus in completely different orders.\n// Thread 1 sees the store to X but not the store to Y while Thread 3 sees the store to Y but not the store to X, the complete opposite.\n// Also to the keen eye you may have noticed this example is a slight modification of the Store Buffer example so try to guess where the memory barriers would go.\n//\n// ---------------------------------------------------------------------------------------------------------\n// Independent Reads of Independent Writes, IRIW, coined by Doug Lea\n// ---------------------------------------------------------------------------------------------------------\n// Thread 0 | Thread 1 | Thread 2 | Thread 3\n// ---------------------------------------------------------------------------------------------------------\n// STORE(X, 1) | r0 = LOAD(X) | STORE(Y, 1) | r2 = LOAD(Y)\n// | sync | | sync\n// | r1 = LOAD(Y) | | r3 = LOAD(X)\n// ---------------------------------------------------------------------------------------------------------\n//\n// To ensure that the above observation is forbidden we need to add a full sync memory barrier on both the reading threads. Think of sync as restoring sequential consistency.\n// The sync memory barrier ensures that any writes that Thread 1 has read from before the memory barrier are fully propagated to all threads before the reads are satisfied after the memory barrier.\n// The same can be said for Thread 3. This is why the sync memory barrier is needed because there is no partial causal ordering here or anything that can be considered for our A and B Cumulativity definitions.\n// We must ensure that all writes have been propagated to all cpus before proceeding. This gives way to the difference between sync and lwsync with regards to visibility of writes and cumulativity.\n// sync guarantees that all program-order previous stores must have been propagated to all other cpus before the memory instructions after the memory barrier.\n// lwsync does not ensure that stores before the memory barrier have actually propagated to any other cpu before memory instructions after the memory barrier, but it will keep stores before and after the\n// lwsync in order as far as other cpus are concerned that are within the dependency chain.\n//\n// Fun fact while ARMv7 claims to be Non-Atomic Store Atomicity no mainstream ARM implementation that I have seen has shown cases of Non-Atomic Store Atomicity.\n// It's allowed by the ARMv7 memory model and thus you have to program to that. ARMv8 changes this and states that it has Multi-Copy Store Atomicity.\n//\n// ******** Release-Acquire Semantics ********\n//\n// The most useful and common cases where Release-Acquire Semantics are used in every day code is in message passing and mutexes. Let's get onto some examples and the C++ definition of Release-Acquire.\n//\n// ACQUIRE:\n// An Acquire operation is a one-way memory barrier whereby all loads and stores after the acquire operation cannot move up and above the acquire operation.\n// Loads and stores before the acquire operation can move down past the acquire operation. An acquire operation should always be paired with a Release operation on the SAME atomic object.\n//\n// RELEASE:\n// A Release operation is a one-way memory barrier whereby all loads and stores before the release operation cannot move down and below the release operation.\n// Loads and stores after the release operation can move up and above the release operation. A release operation should always be paired with an Acquire operation on the SAME atomic object.\n//\n// Release-Acquire pair does not create a full memory barrier but it guarantees that all memory instructions before a Release operation on an atomic object M are visible after an Acquire\n// operation on that same atomic object M. Thus these semantics usually are enough to preclude the need for any other memory barriers.\n// The synchronization is established only between the threads Releasing and Acquiring the same atomic object M.\n//\n// ---------------------------------------------------\n// Critical Section\n// ---------------------------------------------------\n// Thread 0 | Thread 1\n// ---------------------------------------------------\n// mtx.lock() - Acquire | mtx.lock() - Acquire\n// STORE(X, 1) | r0 = LOAD(X)\n// mtx.unlock() - Release | mtx.unlock() - Release\n// ---------------------------------------------------\n//\n// A mutex only requires Release-Acquire semantics to protect the critical section. We do not care if operations above the lock leak into the critical section or that operations below the unlock leak into the\n// critical section because they are outside the protected region of the lock()/unlock() pair. Release-Acquire semantics does guarantee that everything inside the critical section cannot leak out.\n// Thus all accesses of all previous critical sections for the mutex are guaranteed to have completed and be visible when the mutex is handed off to the next party due to the Release-Acquire chaining.\n// This also means that mutexes do not provide or restore Multi-Copy Store Atomicity to any memory instructions outside the mutex, like the IRIW example since it does not emit full memory barriers.\n//\n// ------------------------------------------------------\n// Message Passing\n// ------------------------------------------------------\n// Thread 0 | Thread 1\n// ------------------------------------------------------\n// STORE(DATA, 1) | while (!LOAD_ACQUIRE(FLAG))\n// |\n// STORE_RELEASE(FLAG, 1) | r0 = LOAD(DATA)\n// ------------------------------------------------------\n//\n// This is a common message passing idiom that also shows the use of Release-Acquire semantics. It should be obvious by the definitions outlined above why this works.\n// An Acquire operation attached to a load needs to provide a LDLD and LDST memory barrier according to our definition of acquire. This is provided by default on x86 TSO thus no memory barrier is emitted.\n// A Release operation attached to a store needs to provide a STST and LDST memory barrier according to our definition of release. This is provided by default on x86 TSO thus no memory barrier is emitted.\n//\n// A couple of things of note here. One is that by attaching the semantics of a memory model directly to the memory instruction/operation itself we can take advantage of the fact the some processors\n// already provide guarantees between memory instructions and thus we do not have to emit memory barriers. Another thing of note is that the memory model is directly attached to the operation,\n// so you must do the Release-Acquire pairing on the SAME object which in this case is the FLAG variable. Doing an Acquire or Release on a separate object has no guarantee to observe an Acquire or Release on a different object.\n// This better encapsulates the meaning of the code and also allows the processor to potentially do more optimizations since a stand alone memory barrier will order all memory instructions of a given type before and after the barrier.\n// Where as the memory ordering attached to the load or store tells the processor that it only has to order memory instructions in relation to that specific load or store with the given memory order.\n//\n//\n// ---------------------------------------------------------------------------------------------------------\n// Release Attached to a Store VS. Standalone Fence\n// ---------------------------------------------------------------------------------------------------------\n// STORE(DATA, 1) | STORE(DATA, 1)\n// | ATOMIC_THREAD_FENCE_RELEASE()\n// STORE_RELEASE(FLAG, 1) | STORE_RELAXED(FLAG, 1)\n// STORE_RELAXED(VAR, 2) | STORE_RELAXED(VAR, 2)\n// ---------------------------------------------------------------------------------------------------------\n// ARMv8 Assembly\n// ---------------------------------------------------------------------------------------------------------\n// str 1, DATA | str 1, DATA\n// | dmb ish\n// stlr 1, FLAG | str 1, FLAG\n// str 2, VAR | str 2, VAR\n// ---------------------------------------------------------------------------------------------------------\n//\n// In the above example the release is attached to the FLAG variable, thus synchronization only needs to be guaranteed for that atomic variable.\n// It is entirely possible for the VAR relaxed store to be reordered above the release store.\n// In the fence version, since the fence is standalone, there is no notion where the release is meant to be attached to thus the fence must prevent all subsequent relaxed stores\n// from being reordered above the fence. The fence provides a stronger guarantee whereby now the VAR relaxed store cannot be moved up and above the release operation.\n// Also notice the ARMv8 assembly is different, the release fence must use the stronger dmb ish barrier instead of the dedicated release store instruction.\n// We dive more into fences provided by eastl::atomic below.\n//\n// Release-Acquire semantics also have the property that it must chain through multiple dependencies which is where our knowledge from the previous section comes into play.\n// Everything on the Release-Acquire dependency chain must be visible to the next hop in the chain.\n//\n// ---------------------------------------------------------------------------------------------------------\n// Example 2 from POWER manual\n// ---------------------------------------------------------------------------------------------------------\n// Thread 0 | Thread 1 | Thread 2\n// ---------------------------------------------------------------------------------------------------------\n// STORE(X, 1) | r0 = LOAD_ACQUIRE(Y) | r1 = LOAD_ACQUIRE(Z)\n// STORE_RELEASE(Y, 1) | STORE_RELEASE(Z, r0) | r2 = LOAD(X)\n// ---------------------------------------------------------------------------------------------------------\n//\n// ---------------------------------------------------------------------------------------------------------\n// Write-To-Read Causality, WRC, Litmus Test\n// ---------------------------------------------------------------------------------------------------------\n// Thread 0 | Thread 1 | Thread 2\n// ---------------------------------------------------------------------------------------------------------\n// STORE(X, 1) | r0 = LOAD(X) | r1 = LOAD_ACQUIRE(Y)\n// | STORE_RELEASE(Y, r0) | r2 = LOAD(X)\n// ---------------------------------------------------------------------------------------------------------\n//\n// You may notice both of these examples from the previous section. We replaced the standalone POWER memory barrier instructions with Release-Acquire semantics attached directly to the operations where we want causality preserved.\n// We have transformed those examples to use the eastl::atomic memory model.\n// Take a moment to digest these examples in relation to the definition of Release-Acquire semantics.\n//\n// The Acquire chain can be satisfied by reading the value from the store release or any later stored headed by that release operation. The following examples will make this clearer.\n//\n// ------------------------------------------------------\n// Release Sequence Headed\n// ------------------------------------------------------\n// Initial State:\n// DATA = 0; FLAG = 0;\n// ------------------------------------------------------\n// Thread 0 | Thread 1\n// ------------------------------------------------------\n// STORE(DATA, 1) | r0 = LOAD_ACQUIRE(FLAG)\n// |\n// STORE_RELEASE(FLAG, 1) | r1 = LOAD(DATA)\n// STORE_RELAXED(FLAG, 3) |\n// ------------------------------------------------------\n// Observed: r0 = 3 && r1 = 0\n// ------------------------------------------------------\n//\n// In the above example we may read the value 3 from FLAG which was not the release store, but it was headed by that release store. Thus we observed a later store and therefore it is still valid to then observe r1 = 1.\n// The stores to FLAG from the STORE_RELEASE up to but not including the next STORE_RELEASE operation make up the release sequence headed by the first release store operation. Any store on that sequence can be used to enforce\n// causality on the load acquire.\n//\n// ******** Consume is currently not useful ********\n//\n// Consume is a weaker form of an acquire barrier and creates the Release-Consume barrier pairing.\n// Consume states that a load operation on an atomic object M cannot allow any loads or stores dependent on the value loaded by the operation to be reordered before the operation.\n// To understand consume we must first understand dependent loads.\n// You might encounter this being called a data dependency or an address dependency in some literature.\n//\n// --------------------------------------------------------------\n// Address Dependency\n// --------------------------------------------------------------\n// Initial State:\n// DATA = 0; PTR = nullptr;\n// --------------------------------------------------------------\n// Thread 0 | Thread 1\n// --------------------------------------------------------------\n// STORE(DATA, 1) | r0 = LOAD(PTR) - typeof(r0) = int*\n// |\n// STORE(PTR, &DATA) | r1 = LOAD(r0) - typeof(r1) = int\n// --------------------------------------------------------------\n//\n// There is a clear dependency here where we cannot load from *int until we actually read the int* from memory.\n// Now it is possible for Thread 1's load from *ptr to be observed before the store to DATA, therefore it can lead to r0 = &DATA && r1 = 0.\n// While this is a failure of causality, it is allowed by some cpus such as the DEC Alpha and I believe Blackfin as well.\n// Thus a data dependency memory barrier must be inserted between the data dependent loads in Thread 1. Note that this would equate to a nop on any processor other than the DEC Alpha.\n//\n// This can occur for a variety of hardware reasons. We learned about invalidation queues. It is possible that the invalidation for DATA gets buffered in Thread 1. DEC Alpha allows the Thread 1\n// load from PTR to continue without marking the entries in its invalidation queue. Thus the subsequent load is allowed to return the old cached value of DATA instead of waiting for the\n// marked entries in the invalidation queue to be processed. It is a design decision of the processor not to do proper dependency tracking here and instead relying on the programmer to insert memory barriers.\n//\n// This data dependent ordering guarantee is useful because in places where we were using an Acquire memory barrier we can reduce it to this Consume memory barrier without any hardware barriers actually emitted on every modern processor.\n// Let's take the above example, translate it to Acquire and Consume memory barriers and then translate it to the ARMv7 assembly and see the difference.\n//\n// --------------------------------------------------------------- ---------------------------------------------------------------\n// Address Dependency - Release-Acquire Address Dependency - Release-Acquire - ARMv7 Assembly\n// --------------------------------------------------------------- ---------------------------------------------------------------\n// Thread 0 | Thread 1 Thread 0 | Thread 1\n// --------------------------------------------------------------- ---------------------------------------------------------------\n// STORE(DATA, 1) | r0 = LOAD_ACQUIRE(PTR) STORE(DATA, 1) | r0 = LOAD(PTR)\n// | dmb ish | dmb ish\n// STORE_RELEASE(PTR, &DATA) | r1 = LOAD(r0) STORE(PTR, &DATA) | r1 = LOAD(r0)\n// --------------------------------------------------------------- ---------------------------------------------------------------\n//\n// To get Release-Acquire semantics on ARMv7 we need to emit dmb ish; memory barriers.\n//\n// --------------------------------------------------------------- ---------------------------------------------------------------\n// Address Dependency - Release-Consume Address Dependency - Release-Consume - ARMv7 Assembly\n// --------------------------------------------------------------- ---------------------------------------------------------------\n// Thread 0 | Thread 1 Thread 0 | Thread 1\n// --------------------------------------------------------------- ---------------------------------------------------------------\n// STORE(DATA, 1) | r0 = LOAD_CONSUME(PTR) STORE(DATA, 1) | r0 = LOAD(PTR)\n// | dmb ish |\n// STORE_RELEASE(PTR, &DATA) | r1 = LOAD(r0) STORE(PTR, &DATA) | r1 = LOAD(r0)\n// --------------------------------------------------------------- ---------------------------------------------------------------\n//\n// Data Dependencies can not only be created by read-after-write/RAW on registers, but also by RAW on memory locations too. Let's look at some more elaborate examples.\n//\n// --------------------------------------------------------------- ---------------------------------------------------------------\n// Address Dependency on Registers - Release-Consume - ARMv7 Address Dependency on Memory - Release-Consume - ARMv7\n// --------------------------------------------------------------- ---------------------------------------------------------------\n// Thread 0 | Thread 1 Thread 0 | Thread 1\n// --------------------------------------------------------------- ---------------------------------------------------------------\n// STORE(DATA, 1) | r0 = LOAD(PTR) STORE(DATA, 1) | r0 = LOAD(PTR)\n// | r1 = r0 + 0 | STORE(TEMP, r0)\n// dmb ish | r2 = r1 - 0 dmb ish | r1 = LOAD(TEMP)\n// STORE(PTR, &DATA) | r3 = LOAD(r2) STORE(PTR, &DATA) | r2 = LOAD(r1)\n// --------------------------------------------------------------- ---------------------------------------------------------------\n//\n// The above shows a more elaborate example of how data dependent dependencies flow through RAW chains either through memory or through registers.\n//\n// Notice by identifying that this is a data dependent operation and asking for a consume ordering, we can completely eliminate the memory barrier on Thread 1 since we know ARMv7 does not reorder data dependent loads. Neat.\n// Unfortunately every major compiler upgrades a consume to an acquire ordering, because the consume ordering in the standard has a stronger guarantee and requires the compiler to do complicated dependency tracking.\n// Dependency chains in source code must be mapped to dependency chains at the machine instruction level until a std::kill_dependency in the source code.\n//\n// ----------------------------------------------------------------\n// Non-Address Dependency && Multiple Chains\n// ----------------------------------------------------------------\n// Initial State:\n// std::atomic FLAG; int DATA[1] = 0;\n// ----------------------------------------------------------------\n// Thread 0 | Thread 1\n// ----------------------------------------------------------------\n// STORE(DATA[0], 1) | int f = LOAD_CONSUME(FLAG)\n// | int x = f\n// | if (x) return Func(x);\n// |\n// STORE_RELEASE(FLAG, 1) | Func(int y) return DATA[y - y]\n// ----------------------------------------------------------------\n//\n// This example is really concise but there is a lot going on. Let's digest it.\n// First is that the standard allows consume ordering even on what we will call not true machine level dependencies like a ptr load and then a load from that ptr as shown in the previous examples.\n// Here the dependency is between two ints, and the dependency chain on Thread 1 is as follows. f -> x -> y -> DATA[y - y]. The standard requires that source code dependencies on the loaded value\n// from consume flow thru assignments and even thru function calls. Also notice we added a dependency on the dereference of DATA with the value loaded from consume which while it does nothing actually abides by the standard\n// by enforcing a source code data dependent load on the consume operation. You may see this referred to as artificial data dependencies in other texts.\n// If we assume the compiler is able to track all these dependencies, the question is how do we enforce these dependencies at the machine instruction level. Let's go back to our ptr dependent load example.\n//\n// ----------------------------------------------------------------\n// addi r0, pc, offset;\n// ldr r1, 0(r0);\n// ldr r2, 0(r1);\n// ----------------------------------------------------------------\n//\n// The above pseudo assembly does a pc relative calculation to find the address of ptr. We then load ptr and then continue the dependency chain by loading the int from the loaded ptr.\n// Thus r0 has type of int**, which we use to load r1 an int* which we use to load our final value of r2 which is the int.\n// The key observation here is that most instructions provided by most architectures only allow moving from a base register + offset into a destination register.\n// This allows for trivial capturing of data dependent loads through pointers. But how do we capture the data dependency of DATA[y - y]. We would need something like this.\n//\n// ----------------------------------------------------------------\n// sub r1, r0, r0; // Assume r0 holds y from the Consume Operation\n// add r3, r1, r2; // Assume r2 holds the address of DATA[0]\n// ldr r4, 0(r3);\n// ----------------------------------------------------------------\n//\n// We cannot use two registers as both arguments to the load instruction. Thus to accomplish this you noticed we had to add indirect data dependencies through registers to compute the final address from the consume\n// load of y and then load from the final computed address. The compiler would have to recognize all these dependencies and enforce that they be maintained in the generated assembly.\n// The compiler must ensure the entire syntactic, source code, data-dependency chain is enforced in the generated assembly, no matter how long such chain may be.\n// Because of this and other issues, every major compiler unilaterally promotes consume to an acquire operation across the board. Read reference [15] for more information.\n// This completely removes the actual usefulness of consume for the pointer dependent case which is used quite heavily in concurrent read heavy data structures where updates are published via pointer swaps.\n//\n// ******** read_depends use case - Release-ReadDepends Semantics ********\n//\n// eastl::atomic provides a weaker read_depends operation that only encapsulates the pointer dependency case above. Loading from a pointer and then loading the value from the loaded pointer.\n// The read_depends operation can be used on loads from only an eastl::atomic type. The return pointer of the load must and can only be used to then further load values. And that is it.\n// If you are unsure, upgrade this load to an acquire operation.\n//\n// MyStruct* ptr = gAtomicPtr.load(memory_order_read_depends);\n// int a = ptr->a;\n// int b = ptr->b;\n// return a + b;\n//\n// The loads from ptr after the gAtomicPtr load ensure that the correct values of a and b are observed. This pairs with a Release operation on the writer side by releasing gAtomicPtr.\n//\n//\n// As said above the returned pointer from a .load(memory_order_read_depends) can only be used to then further load values.\n// Dereferencing(*) and Arrow Dereferencing(->) are valid operations on return values from .load(memory_order_read_depends).\n//\n// MyStruct* ptr = gAtomicPtr.load(memory_order_read_depends);\n// int a = ptr->a; - VALID\n// int a = *ptr; - VALID\n//\n// Since dereferencing is just indexing via some offset from some base address, this also means addition and subtraction of constants is ok.\n//\n// int* ptr = gAtomicPtr.load(memory_order_read_depends);\n// int a = *(ptr + 1) - VALID\n// int a = *(ptr - 1) - VALID\n//\n// Casts also work correctly since casting is just offsetting a pointer depending on the inheritance hierarchy or if using intrusive containers.\n//\n// ReadDependsIntrusive** intrusivePtr = gAtomicPtr.load(memory_order_read_depends);\n// ReadDependsIntrusive* ptr = ((ReadDependsIntrusive*)(((char*)intrusivePtr) - offsetof(ReadDependsIntrusive, next)));\n//\n// Base* basePtr = gAtomicPtr.load(memory_order_read_depends);\n// Dervied* derivedPtr = static_cast(basePtr);\n//\n// Both of the above castings from the result of the load are valid for this memory order.\n//\n// You can reinterpret_cast the returned pointer value to a uintptr_t to set bits, clear bits, or xor bits but the pointer must be casted back before doing anything else.\n//\n// int* ptr = gAtomicPtr.load(memory_order_read_depends);\n// ptr = reinterpret_cast(reinterpret_cast(ptr) & ~3);\n//\n// Do not use any equality or relational operator (==, !=, >, <, >=, <=) results in the computation of offsets before dereferencing.\n// As we learned above in the Control Dependencies section, CPUs will not order Load-Load Control Dependencies. Relational and equality operators are often compiled using branches.\n// It doesn't have to be compiled to branched, condition instructions could be used. Or some architectures provide comparison instructions such as set less than which do not need\n// branches when using the result of the relational operator in arithmetic statements. Then again short circuiting may need to introduct branches since C++ guarantees the\n// rest of the expression must not be evaluated.\n// The following odd code is forbidden.\n//\n// int* ptr = gAtomicPtr.load(memory_order_read_depends);\n// int* ptr2 = ptr + (ptr >= 0);\n// int a = *ptr2;\n//\n// Only equality comparisons against nullptr are allowed. This is becase the compiler cannot assume that the address of the loaded value is some known address and substitute our loaded value.\n// int* ptr = gAtomicPtr.load(memory_order_read_depends);\n// if (ptr == nullptr); - VALID\n// if (ptr != nullptr); - VALID\n//\n// Thus the above sentence that states:\n// The return pointer of the load must and can only be used to then further load values. And that is it.\n// must be respected by the programmer. This memory order is an optimization added for efficient read heavy pointer swapping data structures. IF you are unsure, use memory_order_acquire.\n//\n// ******** Relaxed && eastl::atomic guarantees ********\n//\n// We saw various ways that compiler barriers do not help us and that we need something more granular to make sure accesses are not mangled by the compiler to be considered atomic.\n// Ensuring these guarantees like preventing dead-store elimination or the splitting of stores into smaller sub stores is where the C/C++11\n// standard comes into play to define what it means to operate on an atomic object.\n// These basic guarantees are provided via new compiler intrinsics on gcc/clang that provide explicit indication to the compiler.\n// Or on msvc by casting the underlying atomic T to a volatile T*, providing stronger compiler guarantees than the standard requires.\n// Essentially volatile turns off all possible optimizations on that variable access and ensures all volatile variables cannot be\n// reordered across sequence points. Again we are not using volatile here to guarantee atomicity, we are using it in its very intended purpose\n// to tell the compiler it cannot assume anything about the contents of that variable. Now let's dive into the base guarantees of eastl::atomic.\n//\n// The standard defines the following for all operations on an atomic object M.\n//\n// Write-Write Coherence:\n// If an operation A modifies an atomic object M(store), happens before an operation B that modifies M(store), then A shall be earlier than B in the modification order of M.\n//\n// Read-Read Coherence:\n// If a value computation A on an atomic object M(load), happens before a value computation B on M(load), and A takes its value from a side effect X on M(from a previous store to M), then the value\n// computed by B shall either be the value stored by X or some later side effect Y on M, where Y follows X in the modification order of M.\n//\n// Read-Write Coherence:\n// If a value computation A on an atomic object M(load), happens before an operation B that modifies M(store), then A shall take its value from a side effect X on M, where X precedes B in the modification\n// order of M.\n//\n// Write-Read Coherence:\n// If a side effect X on an atomic object M(store), happens before a value computation B on M(load), then the evaluation of B must take its value from X or from some side effect Y that follows X in the\n// modification order of M.\n//\n// What does all this mean. This is just a pedantic way of saying that the preceding coherence requirements disallow compiler reordering of atomic operations to a single atomic object.\n// This means all operations must be emitted by the compiler. Stores cannot be dead-store eliminated even if they are the only stores.\n// Loads cannot have common subexpression elimination performed on them even if they are the only loads.\n// Loads and Stores to the same atomic object cannot be reordered by the compiler.\n// Compiler cannot introduce extra loads or stores to the atomic object.\n// Compiler also cannot reload from an atomic object, it must save and store to a stack slot.\n// Essentially this provides all the necessary guarantees needed when treating an object as atomic from the compilers point of view.\n//\n// ******** Same Address LoadLoad Reordering ********\n//\n// It is expected that same address operations cannot and are not reordered with each other. It is expected that operations to the same address have sequential consistency because\n// they are to the same address. If you picture a cpu executing instructions, how is it possible to reorder instructions to the same address and yet keep program behaviour the same.\n// Same Address LoadLoad Reordering is one weakening that is possible to do and keep observed program behaviour for a single-threaded program.\n// More formally, A and B are two memory instructions onto the same address P, where A is program ordered before B. If A and B are both loads then their order need not be ordered.\n// If B is a store then it cannot retire the store before A instruction completes. If A is a store and B is a load, then B must get its value forwarded from the store buffer or observe a later store\n// from the cache. Thus Same Address LDST, STST, STLD cannot be reordered but Same Address LDLD can be reordered.\n// Intel Itanium and SPARC RMO cpus allow and do Same Address LoadLoad Reordering.\n// Let's look at an example.\n//\n// ---------------------------\n// Same Address LoadLoad\n// ---------------------------\n// Initial State:\n// x = 0;\n// ---------------------------\n// Thread 0 | Thread 1\n// ---------------------------\n// STORE(x, 1) | r0 = LOAD(x)\n// | r1 = LOAD(x)\n// ---------------------------\n// Observed: r0 = 1 && r0 = 0\n// ---------------------------\n//\n// Notice in the above example it has appeared as if the two loads from the same address have been reordered. If we first observed the new store of 1, then the next load should not observe a value in the past.\n// Many programmers, expect same address sequential consistency, all accesses to a single address appear to execute in a sequential order.\n// Notice this violates the Read-Read Coherence for all atomic objects defined by the std and thus provided by eastl::atomic.\n//\n// All operations on eastl::atomic irrelevant of the memory ordering of the operation provides Same Address Sequential Consistency since it must abide by the coherence rules above.\n//\n// ******** eastl::atomic_thread_fence ********\n//\n// eastl::atomic_thread_fence(relaxed) : Provides no ordering guarantees\n// eastl::atomic_thread_fence(acquire) : Prevents all prior loads from being reordered with all later loads and stores, LDLD && LDST memory barrier\n// eastl::atomic_thread_fence(release) : Prevents all prior loads and stores from being reordered with all later stores, STST && LDST memory barrier\n// eastl::atomic_thread_fence(acq_rel) : Union of acquire and release, LDLD && STST && LDST memory barrier\n// eastl::atomic_thread_fence(seq_cst) : Full memory barrier that provides a single total order\n//\n// See Reference [9] and Fence-Fence, Atomic-Fence, Fence-Atomic Synchronization, Atomics Order and Consistency in the C++ std.\n//\n// ******** Atomic && Fence Synchronization ********\n//\n// ---------------------------\n// Fence-Fence Synchronization\n// ---------------------------\n// A release fence A synchronizes-with an acquire fence B if there exist operations X and Y on the same atomic object M, such that fence A is sequenced-before operation X and X modifies M,\n// operation Y is sequenced-before B and Y reads the value written by X.\n// In this case all non-atomic and relaxed atomic stores that are sequenced-before fence A will happen-before all non-atomic and relaxed atomic loads after fence B.\n//\n// ----------------------------\n// Atomic-Fence Synchronization\n// ----------------------------\n// An atomic release operation A on atomic object M synchronizes-with an acquire fence B if there exists some atomic operation X on atomic object M, such that X is sequenced-before B and reads\n// the value written by A.\n// In this case all non-atomic and relaxed atomic stores that are sequenced-before atomic release operation A will happen-before all non-atomic and relaxed atomic loads after fence B.\n//\n// ----------------------------\n// Fence-Atomic Synchronization\n// ----------------------------\n// A release fence A synchronizes-with an atomic acquire operation B on an atomic object M if there exists an atomic operation X such that A is sequenced-before X, X modifies M and B reads the\n// value written by X.\n// In this case all non-atomic and relaxed atomic stores that are sequenced-before fence A will happen-before all non-atomic and relaxed atomic loads after atomic acquire operation B.\n//\n// This can be used to add synchronization to a series of several relaxed atomic operations, as in the following trivial example.\n//\n// ----------------------------------------------------------------------------------------\n// Initial State:\n// x = 0;\n// eastl::atomic y = 0;\n// z = 0;\n// eastl::atomic w = 0;\n// ----------------------------------------------------------------------------------------\n// Thread 0 | Thread 1\n// ----------------------------------------------------------------------------------------\n// x = 2 | r0 = y.load(memory_order_relaxed);\n// z = 2 | r1 = w.load(memory_order_relaxed);\n// atomic_thread_fence(memory_order_release); | atomic_thread_fence(memory_order_acquire);\n// y.store(1, memory_order_relaxed); | r2 = x\n// w.store(1, memory_order_relaxed); | r3 = z\n// ----------------------------------------------------------------------------------------\n// Observed: r0 = 1 && r1 = 1 && r2 = 0 && r3 = 0\n// ----------------------------------------------------------------------------------------\n//\n// ******** Atomic vs Standalone Fence ********\n//\n// A sequentially consistent fence is stronger than a sequentially consistent operation because it is not tied to a specific atomic object.\n// An atomic fence must provide synchronization with ANY atomic object whereas the ordering on the atomic object itself must only provide\n// that ordering on that SAME atomic object. Thus this can provide cheaper guarantees on architectures with dependency tracking hardware.\n// Let's look at a concrete example that will make this all clear.\n//\n// ----------------------------------------------------------------------------------------\n// Initial State:\n// eastl::atomic y = 0;\n// eastl::atomic z = 0;\n// ----------------------------------------------------------------------------------------\n// Thread 0 | Thread 1\n// ----------------------------------------------------------------------------------------\n// z.store(2, memory_order_relaxed); | r0 = y.load(memory_order_relaxed);\n// atomic_thread_fence(memory_order_seq_cst); | atomic_thread_fence(memory_order_seq_cst);\n// y.store(1, memory_order_relaxed); | r1 = z.load(memory_order_relaxed);\n// ----------------------------------------------------------------------------------------\n// Observed: r0 = 1 && r1 = 0\n// ----------------------------------------------------------------------------------------\n//\n// Here the two sequentially consistent fences synchronize-with each other thus ensuring that if we observe r0 = 1 then we also observe that r1 = 2.\n// In the above example if we observe r0 = 1 it is impossible to observe r1 = 0.\n//\n// ----------------------------------------------------------------------------------------\n// Initial State:\n// eastl::atomic x = 0;\n// eastl::atomic y = 0;\n// eastl::atomic z = 0;\n// ----------------------------------------------------------------------------------------\n// Thread 0 | Thread 1\n// ----------------------------------------------------------------------------------------\n// z.store(2, memory_order_relaxed); | r0 = y.load(memory_order_relaxed);\n// x.fetch_add(1, memory_order_seq_cst); | x.fetch_add(1, memory_order_seq_cst);\n// y.store(1, memory_order_relaxed); | r1 = z.load(memory_order_relaxed);\n// ----------------------------------------------------------------------------------------\n// Observed: r0 = 1 && r1 = 0\n// ----------------------------------------------------------------------------------------\n//\n// Here the two fetch_add sequentially consistent operations on x synchronize-with each other ensuring that if we observe r0 = 1 then we cannot observer r1 = 0;\n// The thing to take note here is that we synchronized on the SAME atomic object, that being the atomic object x.\n// Note that replacing the x.fetch_add() in Thread 1 with a sequentially consistent operation on another atomic object or a sequentially consistent fence can lead to\n// observing r1 = 0 even if we observe r0 = 1. For example the following code may fail.\n//\n// ----------------------------------------------------------------------------------------\n// Initial State:\n// eastl::atomic x = 0;\n// eastl::atomic y = 0;\n// eastl::atomic z = 0;\n// ----------------------------------------------------------------------------------------\n// Thread 0 | Thread 1\n// ----------------------------------------------------------------------------------------\n// z.store(2, memory_order_relaxed); | r0 = y.load(memory_order_relaxed);\n// | x.fetch_add(1, memory_order_seq_cst);\n// y.fetch_add(1, memory_order_seq_cst); | r1 = z.load(memory_order_relaxed);\n// ----------------------------------------------------------------------------------------\n// Observed: r0 = 1 && r1 = 0\n// ----------------------------------------------------------------------------------------\n//\n// ----------------------------------------------------------------------------------------\n// Initial State:\n// eastl::atomic x = 0;\n// eastl::atomic y = 0;\n// eastl::atomic z = 0;\n// ----------------------------------------------------------------------------------------\n// Thread 0 | Thread 1\n// ----------------------------------------------------------------------------------------\n// z.store(2, memory_order_relaxed); | r0 = y.load(memory_order_relaxed);\n// x.fetch_add(1, memory_order_seq_cst); | atomic_thread_fence(memory_order_seq_cst);\n// y.store(1, memory_order_relaxed); | r1 = z.load(memory_order_relaxed);\n// ----------------------------------------------------------------------------------------\n// Observed: r0 = 1 && r1 = 0\n// ----------------------------------------------------------------------------------------\n//\n// In this example it is entirely possible that we observe r0 = 1 && r1 = 0 even though we have source code causality and sequentially consistent operations.\n// Observability is tied to the atomic object on which the operation was performed and the thread fence doesn't synchronize-with the fetch_add because\n// there is no load above the fence that reads the value from the fetch_add.\n//\n// ******** Sequential Consistency Semantics ********\n//\n// See section, Order and consistency, in the C++ std and Reference [9].\n//\n// A load with memory_order_seq_cst performs an acquire operation\n// A store with memory_order_seq_cst performs a release operation\n// A RMW with memory_order_seq_cst performs both an acquire and a release operation\n//\n// All memory_order_seq_cst operations exhibit the below single total order in which all threads observe all modifications in the same order\n//\n// Paraphrasing, there is a single total order on all memory_order_seq_cst operations, S, such that each sequentially consistent operation B that loads a value from\n// atomic object M observes either the result of the last sequentially consistent modification A on M, or some modification on M that isn't memory_order_seq_cst.\n// For atomic modifications A and B on an atomic object M, B occurs after A in the total order of M if:\n// there is a memory_order_seq_cst fence X whereby A is sequenced before X, and X precedes B,\n// there is a memory_order_seq_cst fence Y whereby Y is sequenced before B, and A precedes Y,\n// there are memory_order_seq_cst fences X and Y such that A is sequenced before X, Y is sequenced before B, and X precedes Y.\n//\n// Let's look at some examples using memory_order_seq_cst.\n//\n// ------------------------------------------------------------\n// Store-Buffer\n// ------------------------------------------------------------\n// Initial State:\n// x = 0; y = 0;\n// ------------------------------------------------------------\n// Thread 0 | Thread 1\n// ------------------------------------------------------------\n// STORE_RELAXED(x, 1) | STORE_RELAXED(y, 1)\n// ATOMIC_THREAD_FENCE(SEQ_CST) | ATOMIC_THREAD_FENCE(SEQ_CST)\n// r0 = LOAD_RELAXED(y) | r1 = LOAD_RELAXED(x)\n// ------------------------------------------------------------\n// Observed: r0 = 0 && r1 = 0\n// ------------------------------------------------------------\n//\n// ------------------------------------------------------------\n// Store-Buffer\n// ------------------------------------------------------------\n// Initial State:\n// x = 0; y = 0;\n// ------------------------------------------------------------\n// Thread 0 | Thread 1\n// ------------------------------------------------------------\n// STORE_SEQ_CST(x, 1) | STORE_SEQ_CST(y, 1)\n// r0 = LOAD_SEQ_CST(y) | r1 = LOAD_SEQ_CST(x)\n// ------------------------------------------------------------\n// Observed: r0 = 0 && r1 = 0\n// ------------------------------------------------------------\n//\n// Both solutions above are correct to ensure that the end results cannot lead to both r0 and r1 returning 0. Notice that the second one requires memory_order_seq_cst on both\n// operations to ensure they are in the total order, S, for all memory_order_seq_cst operations. The other example uses the stronger guarantee provided by a sequentially consistent fence.\n//\n// ------------------------------------------------------------------------------------------------\n// Read-To-Write Causality\n// ------------------------------------------------------------------------------------------------\n// Initial State:\n// x = 0; y = 0;\n// ------------------------------------------------------------------------------------------------\n// Thread 0 | Thread 1 | Thread 2\n// ------------------------------------------------------------------------------------------------\n// STORE_SEQ_CST(x, 1) | r0 = LOAD_RELAXED(x) | STORE_RELAXED(y, 1)\n// | ATOMIC_THREAD_FENCE(SEQ_CST) | ATOMIC_THREAD_FENCE(SEQ_CST)\n// | r1 = LOAD_RELAXED(y) | r2 = LOAD_RELAXED(x)\n// ------------------------------------------------------------------------------------------------\n// Observed: r0 = 1 && r1 = 0 && r2 = 0\n// ------------------------------------------------------------------------------------------------\n//\n// You'll notice this example is an in between example of the Store-Buffer and IRIW examples we have seen earlier. The store in Thread 0 needs to be sequentially consistent so it synchronizes with the\n// thread fence in Thread 1. C++20 due to Reference [9], increased the strength of sequentially consistent fences has been increased to allow for the following.\n//\n// ------------------------------------------------------------------------------------------------\n// Read-To-Write Causality - C++20\n// ------------------------------------------------------------------------------------------------\n// Initial State:\n// x = 0; y = 0;\n// ------------------------------------------------------------------------------------------------\n// Thread 0 | Thread 1 | Thread 2\n// ------------------------------------------------------------------------------------------------\n// STORE_RELAXED(x, 1) | r0 = LOAD_RELAXED(x) | STORE_RELAXED(y, 1)\n// | ATOMIC_THREAD_FENCE(SEQ_CST) | ATOMIC_THREAD_FENCE(SEQ_CST)\n// | r1 = LOAD_RELAXED(y) | r2 = LOAD_RELAXED(x)\n// ------------------------------------------------------------------------------------------------\n// Observed: r0 = 1 && r1 = 0 && r2 = 0\n// ------------------------------------------------------------------------------------------------\n//\n// Notice we were able to turn the store in Thread 0 into a relaxed store and still properly observe either r1 or r2 returning 1.\n// Note that all implementations of the C++11 standard for every architecture even now allows the C++20 behaviour.\n// The C++20 standard memory model was brought up to recognize that all current implementations are able to implement them stronger.\n//\n// ******** False Sharing ********\n//\n// As we know operations work on the granularity of a cacheline. A RMW operation obviously must have some help from the cache to ensure the entire operation\n// is seen as one whole unit. Conceptually we can think of this as the cpu's cache taking a lock on the cacheline, the cpu doing the read-modify-write operation on the\n// locked cacheline, and then releasing the lock on the cacheline. This means during that time any other cpu needing that cacheline must wait for the lock to be released.\n//\n// If we have two atomic objects doing RMW operations and they are within the same cacheline, they are unintentionally contending and serializing with each other even\n// though they are two completely separate objects. This gives us the common name to this phenomona called false sharing.\n// You can cacheline align your structure or the eastl::atomic object to prevent false sharing.\n//\n// ******** union of eastl::atomic ********\n//\n// union { eastl::atomic atomic8; eastl::atomic atomic32; };\n//\n// While we know that operations operate at the granularity of a processor's cacheline size and so we may expect that storing and loading\n// from different width atomic variables at the same address to not cause weird observable behaviour but it may.\n// Store Buffers allow smaller stores to replace parts of larger loads that are forwarded from a store buffer.\n// This means if there is 2 bytes of modified data in the store buffer that overlaps with a 4 byte load, the 2 bytes will be forwarded\n// from the store buffer. This is even documented behaviour of the x86 store buffer in the x86 architecture manual.\n// This behaviour can cause processors to observe values that have never and will never be visible on the bus to other processors.\n// The use of a union with eastl::atomic is not wrong but your code must be able to withstand these effects.\n//\n// Assume everything starts out initially as zero.\n//\n// -------------------------------------------------------------------------------------------------------\n// Thread 0 | Thread 1 | Thread 2\n// --------------------------------------------------------------------------------------------------------\n// cmpxchg 0 -> 0x11111111 | cmpxchg 0x11111111 -> 0x22222222 | mov byte 0x33; mov 4 bytes into register;\n// ---------------------------------------------------------------------------------------------------------\n//\n// After all operations complete, the value in memory at that location is, 0x22222233.\n// It is possible that the 4 byte load in thread 2 actually returns 0x11111133.\n// Now 0x11111133 is an observed value that no other cpu could observe because it was never globally visible on the data bus.\n//\n// If the value in memory is 0x22222233 then the first cmpxchg succeeded, then the second cmpxchg succeeded and finally our\n// byte to memory was stored, yet our load returned 0x11111133. This is because store buffer contents can be forwarded to overlapping loads.\n// It is possible that the byte store got put in the store buffer. Our load happened after the first cmpxchg with the byte forwarded.\n// This behaviour is fine as long as your algorithm is able to cope with this kind of store buffer forwarding effects.\n//\n// Reference [13] is a great read on more about this topic of mixed-size concurrency.\n//\n\n\n/////////////////////////////////////////////////////////////////////////////////\n\n\n#include \n#include \n#include \n#include \n\n\n#endif /* EASTL_ATOMIC_H */\n" }, { "path": "include/EASTL/atomic_raw.h", "content": "/////////////////////////////////////////////////////////////////////////////////\n// Copyright (c) Electronic Arts Inc. All rights reserved.\n/////////////////////////////////////////////////////////////////////////////////\n\n#pragma once\n\n\n#include \n\n// This header provides extension functions for atomically operating on non-atomic types with\n// specific memory order semantics. These functions should be used as a last resort when using\n// the standard atomic types is impossible (for example due to having to cross established API\n// boundaries which can't change).\n//\n// The reason the atomic template should be preferred is that all operations on that type\n// are atomic by design, using the functions provided by this header and mixing atomic and\n// non-atomic accesses leads to potential data races unless done with extreme care. However, as\n// mentioned above sometimes there are circumstances where using atomic is\n// unfeasible. Whenever this API is used, it is recommended to verify that your data access\n// assumptions are consistent and correct by using tools like TSAN (thread sanitizer).\n//\n// For every member function of the form atomic::foo(...) where T is bool, an integral type,\n// or a pointer type, we provide an equivalent free function atomic_raw_foo(T* ptr, ...) which\n// operates on the T pointed to by ptr. Specifically:\n//\n// For bool we provide:\n// - bool atomic_raw_load(bool*, mem_order)\n// - void atomic_raw_store(bool*, bool, mem_order)\n// - bool atomic_raw_exchange(bool*, bool, mem_order)\n// - bool atomic_raw_compare_exchange_weak/strong(bool*, bool&, bool, mem_ord(, mem_ord))\n//\n// For integral T we provide:\n// - T atomic_raw_load(T*, mem_order)\n// - void atomic_raw_store(T*, T, mem_order)\n// - T atomic_raw_exchange(T*, T, mem_order)\n// - bool atomic_raw_compare_exchange_weak/strong(T*, T&, T, mem_ord(, mem_ord))\n// - T atomic_raw_fetch_add/atomic_raw_add_fetch(T*, T, mem_ord)\n// - T atomic_raw_fetch_sub/atomic_raw_sub_fetch(T*, T, mem_ord)\n// - T atomic_raw_fetch_and/atomic_raw_and_fetch(T*, T, mem_ord)\n// - T atomic_raw_fetch_or / atomic_raw_or_fetch(T*, T, mem_ord)\n// - T atomic_raw_fetch_xor/atomic_raw_xor_fetch(T*, T, mem_ord)\n//\n// For any T we provide:\n// - T* atomic_raw_load(T**, mem_order)\n// - void atomic_raw_store(T**, T*, mem_order)\n// - T* atomic_raw_exchange(T**, T*, mem_order)\n// - bool atomic_raw_compare_exchange_weak/strong(T**, T*&, T*, mem_ord(, mem_ord))\n// - T* atomic_raw_fetch_add/atomic_raw_add_fetch(T**, T*, mem_ord)\n// - T* atomic_raw_fetch_sub/atomic_raw_sub_fetch(T**, T*, mem_ord)\n\n// For pointer types, the fetch operations which look like:\n// T* fetch_add(T** p, ptrdiff_t arg, memory_order)\n// T* add_fetch(T** p, ptrdiff_t arg, memory_order)\n// The supported operations for pointer types are: add, sub.\n\n#define EASTL_ATOMIC_RAW_OPERATION_IMPL(Operation, OpAlias, p, MemOrderMacro, BitCount) \\\n\tEA_PREPROCESSOR_JOIN(EA_PREPROCESSOR_JOIN(EASTL_ATOMIC_, Operation), FUNC_WITH_PTR_IMPL) \\\n\t(EASTL_ATOMIC_BASE_OP_JOIN(OpAlias, MemOrderMacro), BitCount, ptr);\n\n#define EASTL_ATOMIC_RAW_SIZE_DEPENDANT_OPERATION_WITH_ALIAS_IMPL(Operation, OpAlias, MemOrderMacro) \\\n\tstatic_assert(sizeof(T) <= 8, \"Atomic functions only support up to 64bit types\"); \\\n\tstatic_assert(eastl::is_integral_v || eastl::is_pointer_v, \\\n\t \"We only support these for integral and pointer types\"); \\\n\tif constexpr (sizeof(T) == 1) \\\n\t{ \\\n\t\tEASTL_ATOMIC_RAW_OPERATION_IMPL(Operation, OpAlias, ptr, MemOrderMacro, 8) \\\n\t} \\\n\telse if constexpr (sizeof(T) == 2) \\\n\t{ \\\n\t\tEASTL_ATOMIC_RAW_OPERATION_IMPL(Operation, OpAlias, ptr, MemOrderMacro, 16) \\\n\t} \\\n\telse if constexpr (sizeof(T) == 4) \\\n\t{ \\\n\t\tEASTL_ATOMIC_RAW_OPERATION_IMPL(Operation, OpAlias, ptr, MemOrderMacro, 32) \\\n\t} \\\n\telse if constexpr (sizeof(T) == 8) \\\n\t{ \\\n\t\tEASTL_ATOMIC_RAW_OPERATION_IMPL(Operation, OpAlias, ptr, MemOrderMacro, 64) \\\n\t}\n\n#define EASTL_ATOMIC_RAW_SIZE_DEPENDANT_OPERATION_IMPL(Operation, MemOrderMacro) \\\n\tEASTL_ATOMIC_RAW_SIZE_DEPENDANT_OPERATION_WITH_ALIAS_IMPL(Operation, Operation, MemOrderMacro)\n\n#define EASTL_ATOMIC_RAW_LOAD_TMPL(MemOrderType, MemOrderMacro) \\\n\ttemplate \\\n\tT atomic_raw_load(T* ptr, MemOrderType) \\\n\t{ \\\n\t\tEASTL_ATOMIC_RAW_SIZE_DEPENDANT_OPERATION_IMPL(LOAD_, MemOrderMacro) \\\n\t}\n\n// Special memory order only provided for pointers\n#define EASTL_ATOMIC_RAW_POINTER_READ_DEPENDS_LOAD_TMPL() \\\n\ttemplate \\\n\tT* atomic_raw_load(T** p, internal::memory_order_read_depends_s) \\\n\t{ \\\n\t\tstatic_assert(sizeof(T*) == 8 || sizeof(T*) == 4, \"Invalid pointer size\"); \\\n\t\tif constexpr (sizeof(T*) == 4) \\\n\t\t{ \\\n\t\t\tEASTL_ATOMIC_POINTER_READ_DEPENDS_LOAD_IMPL(32, p) \\\n\t\t} \\\n\t\tif constexpr (sizeof(T*) == 8) \\\n\t\t{ \\\n\t\t\tEASTL_ATOMIC_POINTER_READ_DEPENDS_LOAD_IMPL(64, p) \\\n\t\t} \\\n\t}\n\n#define EASTL_ATOMIC_RAW_STORE_TMPL(MemOrderType, MemOrderMacro) \\\n\ttemplate \\\n\tvoid atomic_raw_store(T* ptr, T desired, MemOrderType) \\\n\t{ \\\n\t\tEASTL_ATOMIC_RAW_SIZE_DEPENDANT_OPERATION_IMPL(STORE_, MemOrderMacro) \\\n\t}\n\n#define EASTL_ATOMIC_RAW_EXCHANGE_TMPL(MemOrderType, MemOrderMacro) \\\n\ttemplate \\\n\tT atomic_raw_exchange(T* ptr, T desired, MemOrderType) \\\n\t{ \\\n\t\tEASTL_ATOMIC_RAW_SIZE_DEPENDANT_OPERATION_IMPL(EXCHANGE_, MemOrderMacro) \\\n\t}\n\n#define EASTL_ATOMIC_RAW_CMPXCHG1_TMPL(MemOrderType, MemOrderMacro) \\\n\ttemplate \\\n\tbool atomic_raw_compare_exchange_weak(T* ptr, T& expected, T desired, MemOrderType) \\\n\t{ \\\n\t\tEASTL_ATOMIC_RAW_SIZE_DEPENDANT_OPERATION_WITH_ALIAS_IMPL(CMPXCHG_, CMPXCHG_WEAK_, MemOrderMacro) \\\n\t} \\\n\ttemplate \\\n\tbool atomic_raw_compare_exchange_strong(T* ptr, T& expected, T desired, MemOrderType) \\\n\t{ \\\n\t\tEASTL_ATOMIC_RAW_SIZE_DEPENDANT_OPERATION_WITH_ALIAS_IMPL(CMPXCHG_, CMPXCHG_STRONG_, MemOrderMacro) \\\n\t}\n\n#define EASTL_ATOMIC_RAW_CMPXCHG2_TMPL(MemOrderType1, MemOrderType2, MemOrderMacro) \\\n\ttemplate \\\n\tbool atomic_raw_compare_exchange_weak(T* ptr, T& expected, T desired, MemOrderType1, MemOrderType2) \\\n\t{ \\\n\t\tEASTL_ATOMIC_RAW_SIZE_DEPENDANT_OPERATION_WITH_ALIAS_IMPL(CMPXCHG_, CMPXCHG_WEAK_, MemOrderMacro) \\\n\t} \\\n\ttemplate \\\n\tbool atomic_raw_compare_exchange_strong(T* ptr, T& expected, T desired, MemOrderType1, MemOrderType2) \\\n\t{ \\\n\t\tEASTL_ATOMIC_RAW_SIZE_DEPENDANT_OPERATION_WITH_ALIAS_IMPL(CMPXCHG_, CMPXCHG_STRONG_, MemOrderMacro) \\\n\t}\n\n#define EASTL_ATOMIC_RAW_INTEGRAL_FETCH_ORDER_TMPL(FuncName, MacroFnName, MemOrderType, MemOrderMacro) \\\n\ttemplate \\\n\tT EA_PREPROCESSOR_JOIN(atomic_raw_, FuncName)(T * p, T arg, MemOrderType) \\\n\t{ \\\n\t\tstatic_assert(eastl::is_integral_v && !eastl::is_same_v, \\\n\t\t \"This API is only enabled for integral non boolean types.\"); \\\n\t\tif constexpr (sizeof(T) == 1) \\\n\t\t{ \\\n\t\t\tEASTL_ATOMIC_INTEGRAL_FUNC_IMPL(EASTL_ATOMIC_INTEGRAL_FETCH_OP_JOIN(MacroFnName, MemOrderMacro), 8, p, T); \\\n\t\t} \\\n\t\telse if constexpr (sizeof(T) == 2) \\\n\t\t{ \\\n\t\t\tEASTL_ATOMIC_INTEGRAL_FUNC_IMPL(EASTL_ATOMIC_INTEGRAL_FETCH_OP_JOIN(MacroFnName, MemOrderMacro), 16, p, \\\n\t\t\t T); \\\n\t\t} \\\n\t\telse if constexpr (sizeof(T) == 4) \\\n\t\t{ \\\n\t\t\tEASTL_ATOMIC_INTEGRAL_FUNC_IMPL(EASTL_ATOMIC_INTEGRAL_FETCH_OP_JOIN(MacroFnName, MemOrderMacro), 32, p, \\\n\t\t\t T); \\\n\t\t} \\\n\t\telse if constexpr (sizeof(T) == 8) \\\n\t\t{ \\\n\t\t\tEASTL_ATOMIC_INTEGRAL_FUNC_IMPL(EASTL_ATOMIC_INTEGRAL_FETCH_OP_JOIN(MacroFnName, MemOrderMacro), 64, p, \\\n\t\t\t T); \\\n\t\t} \\\n\t}\n\n#define EASTL_ATOMIC_RAW_INTEGRAL_FETCH_FUNC_TMPL(FuncName, MacroFnName) \\\n\tEASTL_ATOMIC_RAW_INTEGRAL_FETCH_ORDER_TMPL(FuncName, MacroFnName, internal::memory_order_relaxed_s, RELAXED_) \\\n\tEASTL_ATOMIC_RAW_INTEGRAL_FETCH_ORDER_TMPL(FuncName, MacroFnName, internal::memory_order_acquire_s, ACQUIRE_) \\\n\tEASTL_ATOMIC_RAW_INTEGRAL_FETCH_ORDER_TMPL(FuncName, MacroFnName, internal::memory_order_release_s, RELEASE_) \\\n\tEASTL_ATOMIC_RAW_INTEGRAL_FETCH_ORDER_TMPL(FuncName, MacroFnName, internal::memory_order_acq_rel_s, ACQ_REL_) \\\n\tEASTL_ATOMIC_RAW_INTEGRAL_FETCH_ORDER_TMPL(FuncName, MacroFnName, internal::memory_order_seq_cst_s, SEQ_CST_)\n\n// Ptr version of the fetch functions.\n#define EASTL_ATOMIC_RAW_POINTER_FETCH_FUNC_IMPL(FetchOp, BitCount, ptr) \\\n\tusing ptr_integral_type = EA_PREPROCESSOR_JOIN(EA_PREPROCESSOR_JOIN(int, BitCount), _t); \\\n\tEASTL_ATOMIC_STATIC_ASSERT_TYPE_IS_OBJECT(T); \\\n\tEASTL_ATOMIC_POINTER_FUNC_IMPL(FetchOp, BitCount, ptr);\n\n#define EASTL_ATOMIC_RAW_PTR_FETCH_ORDER_TMPL(FuncName, MacroFnName, MemOrderType, MemOrderMacro) \\\n\ttemplate \\\n\tT* EA_PREPROCESSOR_JOIN(atomic_raw_, FuncName)(T * *p, ptrdiff_t arg, MemOrderType) \\\n\t{ \\\n\t\tif constexpr (sizeof(T*) == 4) \\\n\t\t{ \\\n\t\t\tEASTL_ATOMIC_RAW_POINTER_FETCH_FUNC_IMPL(EASTL_ATOMIC_POINTER_FETCH_OP_JOIN(MacroFnName, MemOrderMacro), \\\n\t\t\t 32, p) \\\n\t\t} \\\n\t\telse if constexpr (sizeof(T*) == 8) \\\n\t\t{ \\\n\t\t\tEASTL_ATOMIC_RAW_POINTER_FETCH_FUNC_IMPL(EASTL_ATOMIC_POINTER_FETCH_OP_JOIN(MacroFnName, MemOrderMacro), \\\n\t\t\t 64, p) \\\n\t\t} \\\n\t}\n\n#define EASTL_ATOMIC_RAW_PTR_FETCH_FUNC_TMPL(FuncName, MacroFnName) \\\n\tEASTL_ATOMIC_RAW_PTR_FETCH_ORDER_TMPL(FuncName, MacroFnName, internal::memory_order_relaxed_s, RELAXED_) \\\n\tEASTL_ATOMIC_RAW_PTR_FETCH_ORDER_TMPL(FuncName, MacroFnName, internal::memory_order_acquire_s, ACQUIRE_) \\\n\tEASTL_ATOMIC_RAW_PTR_FETCH_ORDER_TMPL(FuncName, MacroFnName, internal::memory_order_release_s, RELEASE_) \\\n\tEASTL_ATOMIC_RAW_PTR_FETCH_ORDER_TMPL(FuncName, MacroFnName, internal::memory_order_acq_rel_s, ACQ_REL_) \\\n\tEASTL_ATOMIC_RAW_PTR_FETCH_ORDER_TMPL(FuncName, MacroFnName, internal::memory_order_seq_cst_s, SEQ_CST_)\n\nnamespace eastl\n{\n\tEASTL_ATOMIC_RAW_LOAD_TMPL(internal::memory_order_relaxed_s, RELAXED_)\n\tEASTL_ATOMIC_RAW_LOAD_TMPL(internal::memory_order_acquire_s, ACQUIRE_)\n\tEASTL_ATOMIC_RAW_LOAD_TMPL(internal::memory_order_seq_cst_s, SEQ_CST_)\n\n\t// Special memory order for pointers\n\tEASTL_ATOMIC_RAW_POINTER_READ_DEPENDS_LOAD_TMPL()\n\n\tEASTL_ATOMIC_RAW_STORE_TMPL(internal::memory_order_relaxed_s, RELAXED_)\n\tEASTL_ATOMIC_RAW_STORE_TMPL(internal::memory_order_release_s, RELEASE_)\n\tEASTL_ATOMIC_RAW_STORE_TMPL(internal::memory_order_seq_cst_s, SEQ_CST_)\n\n\tEASTL_ATOMIC_RAW_EXCHANGE_TMPL(internal::memory_order_relaxed_s, RELAXED_)\n\tEASTL_ATOMIC_RAW_EXCHANGE_TMPL(internal::memory_order_acquire_s, ACQUIRE_)\n\tEASTL_ATOMIC_RAW_EXCHANGE_TMPL(internal::memory_order_release_s, RELEASE_)\n\tEASTL_ATOMIC_RAW_EXCHANGE_TMPL(internal::memory_order_acq_rel_s, ACQ_REL_)\n\tEASTL_ATOMIC_RAW_EXCHANGE_TMPL(internal::memory_order_seq_cst_s, SEQ_CST_)\n\n\tEASTL_ATOMIC_RAW_CMPXCHG1_TMPL(internal::memory_order_relaxed_s, RELAXED_)\n\tEASTL_ATOMIC_RAW_CMPXCHG1_TMPL(internal::memory_order_acquire_s, ACQUIRE_)\n\tEASTL_ATOMIC_RAW_CMPXCHG1_TMPL(internal::memory_order_release_s, RELEASE_)\n\tEASTL_ATOMIC_RAW_CMPXCHG1_TMPL(internal::memory_order_acq_rel_s, ACQ_REL_)\n\tEASTL_ATOMIC_RAW_CMPXCHG1_TMPL(internal::memory_order_seq_cst_s, SEQ_CST_)\n\n\tEASTL_ATOMIC_RAW_CMPXCHG2_TMPL(internal::memory_order_relaxed_s, internal::memory_order_relaxed_s, RELAXED_RELAXED_)\n\tEASTL_ATOMIC_RAW_CMPXCHG2_TMPL(internal::memory_order_acquire_s, internal::memory_order_relaxed_s, ACQUIRE_RELAXED_)\n\tEASTL_ATOMIC_RAW_CMPXCHG2_TMPL(internal::memory_order_acquire_s, internal::memory_order_acquire_s, ACQUIRE_ACQUIRE_)\n\tEASTL_ATOMIC_RAW_CMPXCHG2_TMPL(internal::memory_order_release_s, internal::memory_order_relaxed_s, RELEASE_RELAXED_)\n\tEASTL_ATOMIC_RAW_CMPXCHG2_TMPL(internal::memory_order_acq_rel_s, internal::memory_order_relaxed_s, ACQ_REL_RELAXED_)\n\tEASTL_ATOMIC_RAW_CMPXCHG2_TMPL(internal::memory_order_acq_rel_s, internal::memory_order_acquire_s, ACQ_REL_ACQUIRE_)\n\tEASTL_ATOMIC_RAW_CMPXCHG2_TMPL(internal::memory_order_seq_cst_s, internal::memory_order_relaxed_s, SEQ_CST_RELAXED_)\n\tEASTL_ATOMIC_RAW_CMPXCHG2_TMPL(internal::memory_order_seq_cst_s, internal::memory_order_acquire_s, SEQ_CST_ACQUIRE_)\n\tEASTL_ATOMIC_RAW_CMPXCHG2_TMPL(internal::memory_order_seq_cst_s, internal::memory_order_seq_cst_s, SEQ_CST_SEQ_CST_)\n\n\tEASTL_ATOMIC_RAW_INTEGRAL_FETCH_FUNC_TMPL(fetch_add, FETCH_ADD_)\n\tEASTL_ATOMIC_RAW_INTEGRAL_FETCH_FUNC_TMPL(add_fetch, ADD_FETCH_)\n\tEASTL_ATOMIC_RAW_INTEGRAL_FETCH_FUNC_TMPL(fetch_sub, FETCH_SUB_)\n\tEASTL_ATOMIC_RAW_INTEGRAL_FETCH_FUNC_TMPL(sub_fetch, SUB_FETCH_)\n\tEASTL_ATOMIC_RAW_INTEGRAL_FETCH_FUNC_TMPL(fetch_and, FETCH_AND_)\n\tEASTL_ATOMIC_RAW_INTEGRAL_FETCH_FUNC_TMPL(and_fetch, AND_FETCH_)\n\tEASTL_ATOMIC_RAW_INTEGRAL_FETCH_FUNC_TMPL(fetch_or, FETCH_OR_)\n\tEASTL_ATOMIC_RAW_INTEGRAL_FETCH_FUNC_TMPL(or_fetch, OR_FETCH_)\n\tEASTL_ATOMIC_RAW_INTEGRAL_FETCH_FUNC_TMPL(fetch_xor, FETCH_XOR_)\n\tEASTL_ATOMIC_RAW_INTEGRAL_FETCH_FUNC_TMPL(xor_fetch, XOR_FETCH_)\n\n\tEASTL_ATOMIC_RAW_PTR_FETCH_FUNC_TMPL(fetch_add, FETCH_ADD_)\n\tEASTL_ATOMIC_RAW_PTR_FETCH_FUNC_TMPL(add_fetch, ADD_FETCH_)\n\tEASTL_ATOMIC_RAW_PTR_FETCH_FUNC_TMPL(fetch_sub, FETCH_SUB_)\n\tEASTL_ATOMIC_RAW_PTR_FETCH_FUNC_TMPL(sub_fetch, SUB_FETCH_)\n} // namespace eastl\n" }, { "path": "include/EASTL/bit.h", "content": "/////////////////////////////////////////////////////////////////////////////\n// Copyright (c) Electronic Arts Inc. All rights reserved.\n/////////////////////////////////////////////////////////////////////////////\n\n#ifndef EASTL_BIT_H\n#define EASTL_BIT_H\n\n#include \n\n#if defined(EA_PRAGMA_ONCE_SUPPORTED)\n\t#pragma once\n#endif\n\n#include \n#include \n#include \n#include // memcpy\n\n#if defined(EA_COMPILER_MSVC) && !defined(__clang__)\n#include \n#endif\n\nnamespace eastl\n{\n\t// eastl::bit_cast\n\t// Obtains a value of type To by reinterpreting the object representation of 'from'.\n\t// Every bit in the value representation of the returned To object is equal to the\n\t// corresponding bit in the object representation of 'from'.\n\t//\n\t// In order for bit_cast to be constexpr, the compiler needs to explicitly support\n\t// it by providing the __builtin_bit_cast builtin. If that builtin is not available,\n\t// then we memcpy into aligned storage at runtime and return that instead.\n\t//\n\t// Both types To and From must be equal in size, and must be trivially copyable.\n\n\t#if defined(EASTL_CONSTEXPR_BIT_CAST_SUPPORTED) && EASTL_CONSTEXPR_BIT_CAST_SUPPORTED\n\n\t\ttemplate::value\n\t\t\t\t&& eastl::is_trivially_copyable::value\n\t\t\t>\n\t\t>\n\t\tconstexpr To bit_cast(const From& from) noexcept\n\t\t{\n\t\t\treturn __builtin_bit_cast(To, from);\n\t\t}\n\n\t#else\n\n\t\ttemplate::value\n\t\t\t\t&& eastl::is_trivially_copyable::value\n\t\t\t>\n\t\t>\n\t\tinline To bit_cast(const From& from) noexcept\n\t\t{\n\t\t\ttypename eastl::aligned_storage::type to;\n\t\t\t::memcpy(eastl::addressof(to), eastl::addressof(from), sizeof(To));\n\t\t\treturn reinterpret_cast(to);\n\t\t}\n\n\t#endif // EASTL_CONSTEXPR_BIT_CAST_SUPPORTED\n\nnamespace internal\n{\n\nconstexpr int countl_zero64(uint64_t x) noexcept\n{\n\tif (x)\n\t{\n\t\tint n = 0;\n\t\tif (x & UINT64_C(0xFFFFFFFF00000000))\n\t\t{\n\t\t\tn += 32;\n\t\t\tx >>= 32;\n\t\t}\n\t\tif (x & 0xFFFF0000)\n\t\t{\n\t\t\tn += 16;\n\t\t\tx >>= 16;\n\t\t}\n\t\tif (x & 0xFFFFFF00)\n\t\t{\n\t\t\tn += 8;\n\t\t\tx >>= 8;\n\t\t}\n\t\tif (x & 0xFFFFFFF0)\n\t\t{\n\t\t\tn += 4;\n\t\t\tx >>= 4;\n\t\t}\n\t\tif (x & 0xFFFFFFFC)\n\t\t{\n\t\t\tn += 2;\n\t\t\tx >>= 2;\n\t\t}\n\t\tif (x & 0xFFFFFFFE)\n\t\t{\n\t\t\tn += 1;\n\t\t}\n\t\treturn 63 - n;\n\t}\n\treturn 64;\n}\n\n// Count leading zeroes in an integer.\n//\n// todo: consolidate with EA::StdC::CountLeading0Bits() and bitset's GetLastBit() + 1.\n// this implementation has these improvements:\n// - has overloads for all unsigned integral types. CountLeading0Bits() may not compile with ambiguous overloads because it doesn't match all unsigned integral types.\n// - supports 128 bit types.\n// - is noexcept.\n// - is constexpr, if available.\n#if defined(EA_COMPILER_MSVC) && !defined(__clang__)\n\n// MSVC overloads are not constexpr because _BitScanReverse is not constexpr.\ninline int countl_zero(unsigned char x) noexcept\n{\n\tunsigned long index;\n\treturn _BitScanReverse(&index, static_cast(x)) ? (sizeof(unsigned char) * CHAR_BIT - 1 - index) : (sizeof(unsigned char) * CHAR_BIT);\n}\n\ninline int countl_zero(unsigned short x) noexcept\n{\n\tunsigned long index;\n\treturn _BitScanReverse(&index, static_cast(x)) ? (sizeof(unsigned short) * CHAR_BIT - 1 - index) : (sizeof(unsigned short) * CHAR_BIT);\n}\n\ninline int countl_zero(unsigned int x) noexcept\n{\n\tunsigned long index;\n\treturn _BitScanReverse(&index, static_cast(x)) ? (sizeof(unsigned int) * CHAR_BIT - 1 - index) : (sizeof(unsigned int) * CHAR_BIT);\n}\n\ninline int countl_zero(unsigned long x) noexcept\n{\n\tunsigned long index;\n\treturn _BitScanReverse(&index, x) ? (sizeof(unsigned long) * CHAR_BIT - 1 - index) : (sizeof(unsigned long) * CHAR_BIT);\n}\n\n#if (EA_PLATFORM_PTR_SIZE == 8)\ninline int countl_zero(unsigned long long x) noexcept\n{\n\tunsigned long index;\n\treturn _BitScanReverse64(&index, x) ? (sizeof(unsigned long long) * CHAR_BIT - 1 - index) : (sizeof(unsigned long long) * CHAR_BIT);\n}\n#else\ninline int countl_zero(unsigned long long x) noexcept\n{\n\treturn countl_zero64(static_cast(x));\n}\n#endif\n\n#elif defined(__GNUC__) || defined(__clang__)\n// __builtin_clz\nconstexpr inline int countl_zero(unsigned char x) noexcept\n{\n\tconstexpr auto diff = eastl::numeric_limits::digits - eastl::numeric_limits::digits;\n\treturn x ? (__builtin_clz(static_cast(x)) - diff) : (sizeof(unsigned char) * CHAR_BIT);\n}\nconstexpr inline int countl_zero(unsigned short x) noexcept\n{\n\tconstexpr auto diff = eastl::numeric_limits::digits - eastl::numeric_limits::digits;\n\treturn x ? (__builtin_clz(static_cast(x)) - diff) : (sizeof(unsigned short) * CHAR_BIT);\n}\nconstexpr inline int countl_zero(unsigned int x) noexcept\n{\n\treturn x ? __builtin_clz(x) : (sizeof(unsigned int) * CHAR_BIT);\n}\n\n// __builtin_clzl\nconstexpr inline int countl_zero(unsigned long x) noexcept\n{\n\treturn x ? __builtin_clzl(x) : (sizeof(unsigned long) * CHAR_BIT);\n}\n\n// __builtin_clzll\n#if (EA_PLATFORM_PTR_SIZE == 8)\nconstexpr inline int countl_zero(unsigned long long x) noexcept\n{\n\treturn x ? __builtin_clzll(x) : (sizeof(unsigned long long) * CHAR_BIT);\n}\n#else\nconstexpr inline int countl_zero(unsigned long long x) noexcept\n{\n\treturn countl_zero64(static_cast(x));\n}\n#endif\n\n#if EASTL_INT128_SUPPORTED\n// todo: once we are using Clang 19.1.0 and GCC ??? use __builtin_clzg(x)\nconstexpr inline int countl_zero(eastl_uint128_t x) noexcept\n{\n\tconst int first64bits = countl_zero(static_cast(x >> 64));\n\treturn first64bits == 64 ? (64 + countl_zero(static_cast(x))) : first64bits;\n}\n#endif\n\n#else // not MSVC, clang or GCC\n\ntemplate && sizeof(T) < 4, bool > = true>\nconstexpr int countl_zero(const T num) noexcept\n{\n\tconstexpr auto diff = 32 - eastl::numeric_limits::digits;\n\treturn countl_zero(static_cast(num)) - diff;\n}\n\ntemplate && sizeof(T) == 4, bool> = true>\nconstexpr int countl_zero(T x) noexcept\n{\n\tif (x)\n\t{\n\t\tint n = 0;\n\t\tif (x <= 0x0000FFFF)\n\t\t{\n\t\t\tn += 16;\n\t\t\tx <<= 16;\n\t\t}\n\t\tif (x <= 0x00FFFFFF)\n\t\t{\n\t\t\tn += 8;\n\t\t\tx <<= 8;\n\t\t}\n\t\tif (x <= 0x0FFFFFFF)\n\t\t{\n\t\t\tn += 4;\n\t\t\tx <<= 4;\n\t\t}\n\t\tif (x <= 0x3FFFFFFF)\n\t\t{\n\t\t\tn += 2;\n\t\t\tx <<= 2;\n\t\t}\n\t\tif (x <= 0x7FFFFFFF)\n\t\t{\n\t\t\tn += 1;\n\t\t}\n\t\treturn n;\n\t}\n\treturn 32;\n}\n\ntemplate && sizeof(T) == 8, bool> = true>\nconstexpr int countl_zero(T x) noexcept\n{\n\treturn countl_zero64(static_cast(x));\n}\n\n#if EASTL_INT128_SUPPORTED\nconstexpr inline int countl_zero(eastl_uint128_t x) noexcept\n{\n\tif (x)\n\t{\n\t\tint n = 0;\n\t\tif (x & (~eastl_uint128_t(0) << 64))\n\t\t{\n\t\t\tn += 64;\n\t\t\tx >>= 64;\n\t\t}\n\t\tif (x & UINT64_C(0xFFFFFFFF00000000))\n\t\t{\n\t\t\tn += 32;\n\t\t\tx >>= 32;\n\t\t}\n\t\tif (x & 0xFFFF0000)\n\t\t{\n\t\t\tn += 16;\n\t\t\tx >>= 16;\n\t\t}\n\t\tif (x & 0xFFFFFF00)\n\t\t{\n\t\t\tn += 8;\n\t\t\tx >>= 8;\n\t\t}\n\t\tif (x & 0xFFFFFFF0)\n\t\t{\n\t\t\tn += 4;\n\t\t\tx >>= 4;\n\t\t}\n\t\tif (x & 0xFFFFFFFC)\n\t\t{\n\t\t\tn += 2;\n\t\t\tx >>= 2;\n\t\t}\n\t\tif (x & 0xFFFFFFFE)\n\t\t{\n\t\t\tn += 1;\n\t\t}\n\t\treturn 127 - n;\n\t}\n\treturn 128;\n}\n#endif\n\n#endif\n\n} // namespace internal\n\n\ttemplate >>\n\tconstexpr int countl_zero(T x) noexcept { return internal::countl_zero(x); }\n\n\ttemplate >>\n\tconstexpr bool has_single_bit(const T num) noexcept\n\t{\n\t\treturn num != 0 && (num & (num - 1)) == 0;\n\t}\n\n\ttemplate >>\n\tconstexpr T bit_ceil(const T num) noexcept\n\t{\n\t\tif (num <= 1U)\n\t\t{\n\t\t\treturn T(1);\n\t\t}\n\n\t\tconst auto shift = eastl::numeric_limits::digits - eastl::countl_zero(static_cast(num - 1));\n\t\treturn static_cast(T(1) << shift);\n\t}\n\n\ttemplate >>\n\tconstexpr T bit_floor(const T num) noexcept\n\t{\n\t\tif (num == 0)\n\t\t{\n\t\t\treturn T(0);\n\t\t}\n\n\t\tconst auto shift = eastl::numeric_limits::digits - eastl::countl_zero(num) - 1;\n\t\treturn static_cast(T(1) << shift);\n\t}\n\n\ttemplate >>\n\tconstexpr int bit_width(const T num) noexcept\n\t{\n\t\treturn eastl::numeric_limits::digits - eastl::countl_zero(num);\n\t}\n\nnamespace internal\n{\n\nconst static char kBitsPerUint16[16] = { 0, 1, 1, 2, 1, 2, 2, 3, 1, 2, 2, 3, 2, 3, 3, 4 };\n\ntemplate \nconstexpr int popcount_non_intrinsic(T num) noexcept\n{\n\tint n = 0;\n\tfor (T w = num; w; w >>= 4)\n\t\tn += kBitsPerUint16[w & 0xF];\n\treturn n;\n}\n\n#if defined(EA_COMPILER_MSVC) && !defined(__clang__)\n\n// __popcnt is not constexpr\n\n// __popcnt16\ninline int popcount(unsigned char num) noexcept { return __popcnt16(static_cast(num)); }\ninline int popcount(unsigned short num) noexcept { return __popcnt16(num); }\n\n// __popcnt\ninline int popcount(unsigned int num) noexcept { return __popcnt(num); }\n\n#if defined(EA_PROCESSOR_X86_64)\n// __popcnt64\ninline int popcount(unsigned long num) noexcept { return static_cast(__popcnt64(num)); }\ninline int popcount(unsigned long long num) noexcept { return static_cast(__popcnt64(num)); }\n#else\n// todo: is it better to use __popcnt() or the fallback implementation?\ninline int popcount(unsigned long num) noexcept { return popcount_non_intrinsic(num); }\ninline int popcount(unsigned long long num) noexcept { return popcount_non_intrinsic(num); }\n#endif\n#elif defined(__GNUC__) || defined(__clang__)\n// __builtin_popcount\nconstexpr inline int popcount(unsigned char num) noexcept { return __builtin_popcount(num); }\nconstexpr inline int popcount(unsigned short num) noexcept { return __builtin_popcount(num); }\nconstexpr inline int popcount(unsigned int num) noexcept { return __builtin_popcount(num); }\n\n// __builtin_popcountl\nconstexpr inline int popcount(unsigned long num) noexcept { return __builtin_popcountl(num); }\n\n// __builtin_popcountll\nconstexpr inline int popcount(unsigned long long num) noexcept { return __builtin_popcountll(num); }\n#endif\n\n#if EASTL_INT128_SUPPORTED\n// todo: once we are using Clang 19.1.0 and GCC ??? use __builtin_popcountg(num)\nconstexpr inline int popcount(eastl_uint128_t num) noexcept\n{\n\treturn popcount(static_cast(num >> 64)) + popcount(static_cast(num));\n}\n#endif\n\n} // namespace internal\n\n\ttemplate >>\n\tconstexpr int popcount(T x) noexcept { return internal::popcount(x); }\n\n} // namespace eastl\n\n#endif // EASTL_BIT_H\n" }, { "path": "include/EASTL/bitset.h", "content": "/////////////////////////////////////////////////////////////////////////////\n// Copyright (c) Electronic Arts Inc. All rights reserved.\n/////////////////////////////////////////////////////////////////////////////\n\n///////////////////////////////////////////////////////////////////////////////\n// This file implements a bitset much like the C++ std::bitset class. \n// The primary distinctions between this bitset and std::bitset are:\n// - bitset is more efficient than some other std::bitset implementations,\n// notably the bitset that comes with Microsoft and other 1st party platforms.\n// - bitset is savvy to an environment that doesn't have exception handling,\n// as is sometimes the case with console or embedded environments.\n// - bitset is savvy to environments in which 'unsigned long' is not the \n// most efficient integral data type. std::bitset implementations use\n// unsigned long, even if it is an inefficient integer type.\n// - bitset removes as much function calls as practical, in order to allow\n// debug builds to run closer in speed and code footprint to release builds.\n// - bitset doesn't support string functionality. We can add this if \n// it is deemed useful.\n//\n///////////////////////////////////////////////////////////////////////////////\n\n\n#ifndef EASTL_BITSET_H\n#define EASTL_BITSET_H\n\n\n#include \n#include \n#include \n\nEA_DISABLE_ALL_VC_WARNINGS();\n\n#include \n#include \n\nEA_RESTORE_ALL_VC_WARNINGS();\n\n#if EASTL_EXCEPTIONS_ENABLED\n\tEA_DISABLE_ALL_VC_WARNINGS();\n\n\t#include // std::out_of_range, std::length_error.\n\n\tEA_RESTORE_ALL_VC_WARNINGS();\n#endif\n\nEA_DISABLE_VC_WARNING(4127); // Conditional expression is constant\n\n#if defined(EA_PRAGMA_ONCE_SUPPORTED)\n\t#pragma once // Some compilers (e.g. VC++) benefit significantly from using this. We've measured 3-4% build speed improvements in apps as a result.\n#endif\n\n\n\nnamespace eastl\n{\n\t// To consider: Enable this for backwards compatibility with any user code that might be using BitsetWordType:\n\t// #define BitsetWordType EASTL_BITSET_WORD_TYPE_DEFAULT\n\n\n\t/// BITSET_WORD_COUNT\n\t///\n\t/// Defines the number of words we use, based on the number of bits.\n\t/// nBitCount refers to the number of bits in a bitset.\n\t/// WordType refers to the type of integer word which stores bitet data. By default it is BitsetWordType.\n\t///\n\t/// Note: for nBitCount == 0, returns 1!\n\t#if !defined(__GNUC__) || (__GNUC__ >= 3) // GCC 2.x can't handle the simpler declaration below.\n\t\t#define BITSET_WORD_COUNT(nBitCount, WordType) (nBitCount == 0 ? 1 : ((nBitCount - 1) / (8 * sizeof(WordType)) + 1))\n\t#else\n\t\t#define BITSET_WORD_COUNT(nBitCount, WordType) ((nBitCount - 1) / (8 * sizeof(WordType)) + 1)\n\t#endif\n\n\n\t/// EASTL_DISABLE_BITSET_ARRAYBOUNDS_WARNING\n\t/// Before GCC 4.7 the '-Warray-bounds' buggy and was very likely to issue false positives for loops that are\n\t/// difficult to evaluate.\n\t/// https://gcc.gnu.org/bugzilla/show_bug.cgi?id=45978\n\t///\n\t#if defined(__GNUC__) && (EA_COMPILER_VERSION > 4007) && defined(EA_PLATFORM_ANDROID) // Earlier than GCC 4.7 \n\t\t#define EASTL_DISABLE_BITSET_ARRAYBOUNDS_WARNING 1\n\t#else\n\t\t#define EASTL_DISABLE_BITSET_ARRAYBOUNDS_WARNING 0\n\t#endif\n\n\ttemplate \n\tclass bitset;\n\n\tnamespace detail\n\t{\n\t\ttemplate\n\t\tstruct is_word_type : bool_constant && !is_volatile_v && !is_same_v && is_integral_v && is_unsigned_v> {};\n\n\t\ttemplate\n\t\tconstexpr bool is_word_type_v = is_word_type::value;\n\n\t\t// slices the min(N, UInt) lowest significant bits from value.\n\t\ttemplate\n\t\teastl::enable_if_t> from_unsigned_integral(bitset& bs, UInt value)\n\t\t{\n\t\t\tconstexpr size_t numWords = (N > 0) ? ((N - 1) / (CHAR_BIT * sizeof(WordType)) + 1) : 0; // BITSET_WORD_COUNT(N, WordType) but 0 for N == 0\n\n\t\t\tWordType* data = bs.data();\n\n\t\t\tEA_CONSTEXPR_IF (numWords > 0)\n\t\t\t{\n\t\t\t\t// copy everything from value into our word array:\n\t\t\t\tconstexpr size_t bytes_to_copy = eastl::min_alt(numWords * sizeof(WordType), sizeof(UInt));\n\t\t\t\tmemcpy(data, &value, bytes_to_copy);\n\n\t\t\t\t// zero any remaining elements in our array:\n\t\t\t\tmemset(reinterpret_cast(data) + bytes_to_copy, 0, numWords * sizeof(WordType) - bytes_to_copy);\n\n\t\t\t\t// we may have copied bits into the final element that are unusable (ie. bit positions > N).\n\t\t\t\t// zero these bits out, as this is an invariant for our implementation.\n\t\t\t\tEA_CONSTEXPR_IF (N % (CHAR_BIT * sizeof(WordType)) != 0)\n\t\t\t\t{\n\t\t\t\t\tconstexpr WordType lastElemUsedBitsMask = (WordType(1) << (N % (CHAR_BIT * sizeof(WordType)))) - 1;\n\t\t\t\t\tdata[numWords - 1] &= lastElemUsedBitsMask;\n\t\t\t\t}\n\t\t\t}\n\t\t\telse\n\t\t\t{\n\t\t\t\tdata[0] = 0; // our bitset implementation has a single element even when N == 0.\n\t\t\t}\n\t\t}\n\n\t\t// This is here to work around the lack of `if constexpr` in C++14, so that calling\n\t\t// (WordType(1) << (CHAR_BIT * sizeof(UInt))) doesn't trigger warnings/errors when\n\t\t// sizeof(UInt) >= sizeof(WordType)\n\t\ttemplate\n\t\tstruct to_unsigned_integral_helper\n\t\t{};\n\n\t\ttemplate\n\t\tstruct to_unsigned_integral_helper\n\t\t{\n\t\t\tstatic size_t copyWords(const WordType* data, UInt* result)\n\t\t\t{\n\t\t\t\tconstexpr size_t bytes_to_copy = sizeof(UInt);\n\t\t\t\tmemcpy(result, data, bytes_to_copy);\n\n\t\t\t\t// check remaining uncopied bits from the first word are zero:\n\t\t\t\tconstexpr WordType lastElemOverflowBitsMask = static_cast(~((WordType(1) << (CHAR_BIT * sizeof(UInt))) - 1));\n\t\t\t\tif ((data[0] & lastElemOverflowBitsMask) != 0)\n\t\t\t\t{\n#if EASTL_EXCEPTIONS_ENABLED\n\t\t\t\t\tthrow std::overflow_error(\"target type cannot represent the full bitset.\");\n#elif EASTL_ASSERT_ENABLED\n\t\t\t\t\tEA_CONSTEXPR_IF(bAssertOnOverflow)\n\t\t\t\t\t\tEASTL_FAIL_MSG(\"overflow_error\");\n#endif\n\t\t\t\t}\n\t\t\t\treturn 1;\n\t\t\t}\n\t\t};\n\n\t\ttemplate\n\t\tstruct to_unsigned_integral_helper\n\t\t{\n\t\t\tstatic size_t copyWords(const WordType* data, UInt* result)\n\t\t\t{\n\t\t\t\tconstexpr size_t bytes_to_copy = eastl::min_alt(NumWords * sizeof(WordType), sizeof(UInt));\n\t\t\t\tmemcpy(result, data, bytes_to_copy);\n\n\t\t\t\treturn bytes_to_copy / sizeof(WordType);\n\t\t\t}\n\t\t};\n\n\n\n\t\ttemplate\n\t\teastl::enable_if_t, UInt> to_unsigned_integral(const bitset& bs)\n\t\t{\n\t\t\tconstexpr size_t kNumWords = (N > 0) ? ((N - 1) / (CHAR_BIT * sizeof(WordType)) + 1) : 0; // BITSET_WORD_COUNT(N, WordType) but 0 for N == 0\n\n\t\t\tEA_CONSTEXPR_IF (kNumWords > 0)\n\t\t\t{\n\t\t\t\tconst WordType* data = bs.data();\n\n\t\t\t\tUInt result = 0;\n\n\t\t\t\tconst size_t numWordsCopied = to_unsigned_integral_helper::copyWords(data, &result);\n\n\t\t\t\t// check any remaining uncopied words are zero (don't contain any useful information).\n\t\t\t\tfor (size_t wordIndex = numWordsCopied; wordIndex < kNumWords; ++wordIndex)\n\t\t\t\t{\n\t\t\t\t\tif (data[wordIndex] != 0)\n\t\t\t\t\t{\n#if EASTL_EXCEPTIONS_ENABLED\n\t\t\t\t\t\tthrow std::overflow_error(\"target type cannot represent the full bitset.\");\n#elif EASTL_ASSERT_ENABLED\n\t\t\t\t\t\tEA_CONSTEXPR_IF (bAssertOnOverflow)\n\t\t\t\t\t\t\tEASTL_FAIL_MSG(\"overflow_error\");\n#endif\n\t\t\t\t\t}\n\t\t\t\t}\n\n\t\t\t\treturn result;\n\t\t\t}\n\t\t\telse\n\t\t\t{\n\t\t\t\treturn 0;\n\t\t\t}\n\t\t}\n\t} // namespace detail\n\n\t/// BitsetBase\n\t///\n\t/// This is a default implementation that works for any number of words.\n\t///\n\ttemplate // Templated on the number of words used to hold the bitset and the word type.\n\tstruct BitsetBase\n\t{\n\t\ttypedef WordType word_type;\n\t\ttypedef BitsetBase this_type;\n\t #if EASTL_BITSET_SIZE_T\n\t\ttypedef size_t size_type;\n\t #else\n\t\ttypedef eastl_size_t size_type;\n\t #endif\n\n\t\tenum {\n\t\t\tkBitsPerWord = (8 * sizeof(word_type)),\n\t\t\tkBitsPerWordMask = (kBitsPerWord - 1),\n\t\t\tkBitsPerWordShift = ((kBitsPerWord == 8) ? 3 : ((kBitsPerWord == 16) ? 4 : ((kBitsPerWord == 32) ? 5 : (((kBitsPerWord == 64) ? 6 : 7)))))\n\t\t};\n\n\tpublic:\n\t\t// invariant: we keep any high bits in the last word that are unneeded set to 0\n\t\t// so that our to_ulong() conversion can simply copy the words into the target type.\n\t\tword_type mWord[NW];\n\n\tpublic:\n\t\tvoid operator&=(const this_type& x);\n\t\tvoid operator|=(const this_type& x);\n\t\tvoid operator^=(const this_type& x);\n\n\t\tvoid operator<<=(size_type n);\n\t\tvoid operator>>=(size_type n);\n\n\t\tvoid flip();\n\t\tvoid set();\n\t\tvoid set(size_type i, bool value);\n\t\tvoid reset();\n\n\t\tbool operator==(const this_type& x) const;\n\n\t\tbool any() const;\n\t\tsize_type count() const;\n\n\t\tword_type& DoGetWord(size_type i);\n\t\tword_type DoGetWord(size_type i) const;\n\n\t\tsize_type DoFindFirst() const;\n\t\tsize_type DoFindNext(size_type last_find) const;\n\n\t\tsize_type DoFindLast() const; // Returns NW * kBitsPerWord (the bit count) if no bits are set.\n\t\tsize_type DoFindPrev(size_type last_find) const; // Returns NW * kBitsPerWord (the bit count) if no bits are set.\n\n\t}; // class BitsetBase\n\n\n\n\t/// BitsetBase<1, WordType>\n\t/// \n\t/// This is a specialization for a bitset that fits within one word.\n\t///\n\ttemplate \n\tstruct BitsetBase<1, WordType>\n\t{\n\t\ttypedef WordType word_type;\n\t\ttypedef BitsetBase<1, WordType> this_type;\n\t #if EASTL_BITSET_SIZE_T\n\t\ttypedef size_t size_type;\n\t #else\n\t\ttypedef eastl_size_t size_type;\n\t #endif\n\n\t\tenum {\n\t\t\tkBitsPerWord = (8 * sizeof(word_type)),\n\t\t\tkBitsPerWordMask = (kBitsPerWord - 1),\n\t\t\tkBitsPerWordShift = ((kBitsPerWord == 8) ? 3 : ((kBitsPerWord == 16) ? 4 : ((kBitsPerWord == 32) ? 5 : (((kBitsPerWord == 64) ? 6 : 7)))))\n\t\t};\n\n\tpublic:\n\t\tword_type mWord[1]; // Defined as an array of 1 so that bitset can treat this BitsetBase like others.\n\n\tpublic:\n\t\tvoid operator&=(const this_type& x);\n\t\tvoid operator|=(const this_type& x);\n\t\tvoid operator^=(const this_type& x);\n\n\t\tvoid operator<<=(size_type n);\n\t\tvoid operator>>=(size_type n);\n\n\t\tvoid flip();\n\t\tvoid set();\n\t\tvoid set(size_type i, bool value);\n\t\tvoid reset();\n\n\t\tbool operator==(const this_type& x) const;\n\n\t\tbool any() const;\n\t\tsize_type count() const;\n\n\t\tword_type& DoGetWord(size_type);\n\t\tword_type DoGetWord(size_type) const;\n\n\t\tsize_type DoFindFirst() const;\n\t\tsize_type DoFindNext(size_type last_find) const;\n\n\t\tsize_type DoFindLast() const; // Returns 1 * kBitsPerWord (the bit count) if no bits are set.\n\t\tsize_type DoFindPrev(size_type last_find) const; // Returns 1 * kBitsPerWord (the bit count) if no bits are set.\n\n\t}; // BitsetBase<1, WordType>\n\n\n\n\t/// BitsetBase<2, WordType>\n\t/// \n\t/// This is a specialization for a bitset that fits within two words.\n\t/// The difference here is that we avoid branching (ifs and loops).\n\t///\n\ttemplate \n\tstruct BitsetBase<2, WordType>\n\t{\n\t\ttypedef WordType word_type;\n\t\ttypedef BitsetBase<2, WordType> this_type;\n\t #if EASTL_BITSET_SIZE_T\n\t\ttypedef size_t size_type;\n\t #else\n\t\ttypedef eastl_size_t size_type;\n\t #endif\n\n\t\tenum {\n\t\t\tkBitsPerWord = (8 * sizeof(word_type)),\n\t\t\tkBitsPerWordMask = (kBitsPerWord - 1),\n\t\t\tkBitsPerWordShift = ((kBitsPerWord == 8) ? 3 : ((kBitsPerWord == 16) ? 4 : ((kBitsPerWord == 32) ? 5 : (((kBitsPerWord == 64) ? 6 : 7)))))\n\t\t};\n\n\tpublic:\n\t\tword_type mWord[2];\n\n\tpublic:\n\t\tvoid operator&=(const this_type& x);\n\t\tvoid operator|=(const this_type& x);\n\t\tvoid operator^=(const this_type& x);\n\n\t\tvoid operator<<=(size_type n);\n\t\tvoid operator>>=(size_type n);\n\n\t\tvoid flip();\n\t\tvoid set();\n\t\tvoid set(size_type i, bool value);\n\t\tvoid reset();\n\n\t\tbool operator==(const this_type& x) const;\n\n\t\tbool any() const;\n\t\tsize_type count() const;\n\n\t\tword_type& DoGetWord(size_type);\n\t\tword_type DoGetWord(size_type) const;\n\n\t\tsize_type DoFindFirst() const;\n\t\tsize_type DoFindNext(size_type last_find) const;\n\n\t\tsize_type DoFindLast() const; // Returns 2 * kBitsPerWord (the bit count) if no bits are set.\n\t\tsize_type DoFindPrev(size_type last_find) const; // Returns 2 * kBitsPerWord (the bit count) if no bits are set.\n\n\t}; // BitsetBase<2, WordType>\n\n\n\n\n\t/// bitset\n\t///\n\t/// Implements a bitset much like the C++ std::bitset.\n\t///\n\t/// As of this writing we don't implement a specialization of bitset<0>,\n\t/// as it is deemed an academic exercise that nobody would actually\n\t/// use and it would increase code space and provide little practical\n\t/// benefit. Note that this doesn't mean bitset<0> isn't supported; \n\t/// it means that our version of it isn't as efficient as it would be \n\t/// if a specialization was made for it.\n\t///\n\t/// - N can be any unsigned (non-zero) value, though memory usage is \n\t/// linear with respect to N, so large values of N use large amounts of memory.\n\t/// - WordType must be a non-cv qualified unsigned integral other than bool.\n\t/// By default the WordType is the largest native register type that the\n\t/// target platform supports.\n\t///\n\ttemplate \n\tclass bitset : private BitsetBase\n\t{\n\tpublic:\n\t\tstatic_assert(detail::is_word_type_v, \"Word type must be a non-cv qualified, unsigned integral other than bool.\");\n\n\t\ttypedef BitsetBase base_type;\n\t\ttypedef bitset this_type;\n\t\ttypedef WordType word_type;\n\t\ttypedef typename base_type::size_type size_type;\n\n\t\tenum\n\t\t{\n\t\t\tkBitsPerWord = (8 * sizeof(word_type)),\n\t\t\tkBitsPerWordMask = (kBitsPerWord - 1),\n\t\t\tkBitsPerWordShift = ((kBitsPerWord == 8) ? 3 : ((kBitsPerWord == 16) ? 4 : ((kBitsPerWord == 32) ? 5 : (((kBitsPerWord == 64) ? 6 : 7))))),\n\t\t\tkSize = N, // The number of bits the bitset holds\n\t\t\tkWordSize = sizeof(word_type), // The size of individual words the bitset uses to hold the bits.\n\t\t\tkWordCount = BITSET_WORD_COUNT(N, WordType) // The number of words the bitset uses to hold the bits. sizeof(bitset) == kWordSize * kWordCount.\n\t\t};\n\n\t\t// internal implementation details. do not use.\n\t\tusing base_type::mWord;\n\t\tusing base_type::DoGetWord;\n\t\tusing base_type::DoFindFirst;\n\t\tusing base_type::DoFindNext;\n\t\tusing base_type::DoFindLast;\n\t\tusing base_type::DoFindPrev;\n\n\t\tusing base_type::count;\n\t\tusing base_type::any;\n\n\tpublic:\n\t\t/// reference\n\t\t///\n\t\t/// A reference is a reference to a specific bit in the bitset.\n\t\t/// The C++ standard specifies that this be a nested class, \n\t\t/// though it is not clear if a non-nested reference implementation\n\t\t/// would be non-conforming.\n\t\t///\n\t\tclass reference\n\t\t{\n\t\tprotected:\n\t\t\tfriend class bitset;\n\n\t\t\tword_type* mpBitWord;\n\t\t\tsize_type mnBitIndex;\n\t\t\n\t\t\treference(){} // The C++ standard specifies that this is private.\n\t\n\t\tpublic:\n\t\t\treference(const bitset& x, size_type i);\n\n\t\t\treference& operator=(bool value);\n\t\t\treference& operator=(const reference& x);\n\n\t\t\tbool operator~() const;\n\t\t\toperator bool() const // Defined inline because CodeWarrior fails to be able to compile it outside.\n\t\t\t { return (*mpBitWord & (static_cast(1) << (mnBitIndex & kBitsPerWordMask))) != 0; }\n\n\t\t\treference& flip();\n\t\t};\n\n\tpublic:\n\t\tfriend class reference;\n\n\t\tbitset();\n\n#if EA_IS_ENABLED(EASTL_DEPRECATIONS_FOR_2024_SEPT)\n\t\t// note: this constructor will only copy the minimum of N or unsigned long long's size least significant bits.\n\t\tbitset(unsigned long long value);\n#else\n\t\tbitset(uint32_t value);\n#endif\n\n\t\t// We don't define copy constructor and operator= because \n\t\t// the compiler-generated versions will suffice.\n\n\t\tthis_type& operator&=(const this_type& x);\n\t\tthis_type& operator|=(const this_type& x);\n\t\tthis_type& operator^=(const this_type& x);\n\n\t\tthis_type& operator<<=(size_type n);\n\t\tthis_type& operator>>=(size_type n);\n\n\t\tthis_type& set();\n\t\tthis_type& set(size_type i, bool value = true);\n\n\t\tthis_type& reset();\n\t\tthis_type& reset(size_type i);\n\t\t\t\n\t\tthis_type& flip();\n\t\tthis_type& flip(size_type i);\n\t\tthis_type operator~() const;\n\n\t\treference operator[](size_type i);\n\t\tbool operator[](size_type i) const;\n\n\t\tconst word_type* data() const;\n\t\tword_type* data();\n\n\t\t// Deprecated: use the bitset(unsigned long long) constructor instead.\n\t\t// this was a workaround for when our constructor was defined as bitset(uint32_t) and could cause a narrowing conversion.\n\t\tEASTL_REMOVE_AT_2024_SEPT void from_uint32(uint32_t value);\n\t\tEASTL_REMOVE_AT_2024_SEPT void from_uint64(uint64_t value);\n\n\t\t/// to_xxx()\n\t\t/// \n\t\t/// Not recommended: Use one of\n\t\t/// as_xxx() which is a compile time error if the target type cannot represent the entire bitset, or\n\t\t/// to_xxx_assert_convertible() which is the standard conformant version of this function, or\n\t\t/// to_xxx_no_assert_convertible() which has the same behaviour, explicit naming\n\t\t/// \n\t\t/// Different from the standard:\n\t\t/// Does *NOT* assert that the bitset can be represented as the target integer type (has bits set outside the target type).\n\t\t/// However, if exceptions are enabled, it does throw an exception if the bitset cannot be represented as the target integer type.\n\t\tunsigned long to_ulong() const;\n\t\tuint32_t to_uint32() const;\n\t\tuint64_t to_uint64() const;\n\n\t\t/// to_xxx_assert_convertible()\n\t\t///\n\t\t/// Equivalent to the standard library's to_ulong() / to_ullong().\n\t\t/// Asserts / throws an exception if the bitset cannot be represented as the target integer type.\n\t\tuint32_t\t\t\tto_uint32_assert_convertible() const { return detail::to_unsigned_integral(*this); }\n\t\tuint64_t\t\t\tto_uint64_assert_convertible() const { return detail::to_unsigned_integral(*this); }\n\t\tunsigned long\t\tto_ulong_assert_convertible() const { return detail::to_unsigned_integral(*this); }\n\t\tunsigned long long\tto_ullong_assert_convertible() const { return detail::to_unsigned_integral(*this); }\n\n\t\t/// to_xxx_no_assert_convertible()\n\t\t///\n\t\t/// Prefer to_xxx_assert_convertible() instead of these functions.\n\t\t/// \n\t\t/// Different from the standard:\n\t\t/// Does *NOT* assert that the bitset can be represented as the target integer type (has bits set outside the target type).\n\t\t/// However, if exceptions are enabled, it does throw an exception if the bitset cannot be represented as the target integer type.\n\t\tuint32_t\t\t\tto_uint32_no_assert_convertible() const { return detail::to_unsigned_integral(*this); }\n\t\tuint64_t\t\t\tto_uint64_no_assert_convertible() const { return detail::to_unsigned_integral(*this); }\n\t\tunsigned long\t\tto_ulong_no_assert_convertible() const { return detail::to_unsigned_integral(*this); }\n\t\tunsigned long long\tto_ullong_no_assert_convertible() const { return detail::to_unsigned_integral(*this); }\n\n\t\t/// as_uint() / as_xxx()\n\t\t/// \n\t\t/// Extension to the standard: Cast to a unsigned integral that can represent the entire bitset.\n\t\t/// If the target type cannot represent the entire bitset, then issue a compile error (overload does not exist).\n\t\t/// Never throws / asserts.\n\t\ttemplate\n\t\teastl::enable_if_t && N <= (CHAR_BIT * sizeof(UInt)), UInt>\tas_uint() const noexcept { return detail::to_unsigned_integral(*this); }\n\n\t\ttemplate\n\t\teastl::enable_if_t\t\t\t\t\t\tas_uint32() const noexcept { return to_uint32_assert_convertible(); }\n\t\ttemplate\n\t\teastl::enable_if_t\t\t\t\t\t\tas_uint64() const noexcept { return to_uint64_assert_convertible(); }\n\t\ttemplate\n\t\teastl::enable_if_t\t\t\tas_ulong() const noexcept { return to_ulong_assert_convertible(); }\n\t\ttemplate\n\t\teastl::enable_if_t\tas_ullong() const noexcept { return to_ullong_assert_convertible(); }\n\n\t //size_type count() const; // We inherit this from the base class.\n\t\tsize_type size() const;\n\n\t\tbool operator==(const this_type& x) const;\n#if !defined(EA_COMPILER_HAS_THREE_WAY_COMPARISON)\n\t\tbool operator!=(const this_type& x) const;\n#endif\n\n\t\tbool test(size_type i) const;\n\t //bool any() const; // We inherit this from the base class.\n\t\tbool all() const;\n\t\tbool none() const;\n\n\t\tthis_type operator<<(size_type n) const;\n\t\tthis_type operator>>(size_type n) const;\n\n\t\t// Finds the index of the first \"on\" bit, returns kSize if none are set.\n\t\tsize_type find_first() const;\n\n\t\t// Finds the index of the next \"on\" bit after last_find, returns kSize if none are set.\n\t\tsize_type find_next(size_type last_find) const;\n\n\t\t// Finds the index of the last \"on\" bit, returns kSize if none are set.\n\t\tsize_type find_last() const;\n\n\t\t// Finds the index of the last \"on\" bit before last_find, returns kSize if none are set.\n\t\tsize_type find_prev(size_type last_find) const;\n\n\t}; // bitset\n\n\n\n\n\n\n\n\t/// BitsetCountBits\n\t///\n\t/// This is a fast trick way to count bits without branches nor memory accesses.\n\t///\n\t/// todo: Use bit.h's popcount instead?\n\ttemplate\n\teastl::enable_if_t && sizeof(UInt64) == 8, uint32_t> BitsetCountBits(UInt64 x)\n\t{\n\t\t// GCC 3.x's implementation of UINT64_C is broken and fails to deal with \n\t\t// the code below correctly. So we make a workaround for it. Earlier and \n\t\t// later versions of GCC don't have this bug.\n\n\t\t#if defined(__GNUC__) && (__GNUC__ == 3)\n\t\t\tx = x - ((x >> 1) & 0x5555555555555555ULL);\n\t\t\tx = (x & 0x3333333333333333ULL) + ((x >> 2) & 0x3333333333333333ULL);\n\t\t\tx = (x + (x >> 4)) & 0x0F0F0F0F0F0F0F0FULL;\n\t\t\treturn (uint32_t)((x * 0x0101010101010101ULL) >> 56);\n\t\t#else\n\t\t\tx = x - ((x >> 1) & UINT64_C(0x5555555555555555));\n\t\t\tx = (x & UINT64_C(0x3333333333333333)) + ((x >> 2) & UINT64_C(0x3333333333333333));\n\t\t\tx = (x + (x >> 4)) & UINT64_C(0x0F0F0F0F0F0F0F0F);\n\t\t\treturn (uint32_t)((x * UINT64_C(0x0101010101010101)) >> 56);\n\t\t#endif\n\t}\n\n\ttemplate\n\teastl::enable_if_t && sizeof(UInt32) == 4, uint32_t> BitsetCountBits(UInt32 x)\n\t{\n\t\tx = x - ((x >> 1) & 0x55555555);\n\t\tx = (x & 0x33333333) + ((x >> 2) & 0x33333333);\n\t\tx = (x + (x >> 4)) & 0x0F0F0F0F;\n\t\treturn (uint32_t)((x * 0x01010101) >> 24);\n\t}\n\n\ttemplate\n\teastl::enable_if_t< detail::is_word_type_v && sizeof(SmallUInt) < 4, uint32_t> BitsetCountBits(SmallUInt x)\n\t{\n\t\treturn BitsetCountBits((uint32_t)x);\n\t}\n\n\n\t// const static char kBitsPerUint16[16] = { 0, 1, 1, 2, 1, 2, 2, 3, 1, 2, 2, 3, 2, 3, 3, 4 };\n\t#define EASTL_BITSET_COUNT_STRING \"\\0\\1\\1\\2\\1\\2\\2\\3\\1\\2\\2\\3\\2\\3\\3\\4\"\n\n\n\ttemplate\n\teastl::enable_if_t && sizeof(UInt8) == 1, uint32_t> GetFirstBit(UInt8 x)\n\t{\n\t\tif(x)\n\t\t{\n\t\t\tuint32_t n = 1;\n\n\t\t\tif((x & 0x0000000F) == 0) { n += 4; x >>= 4; }\n\t\t\tif((x & 0x00000003) == 0) { n += 2; x >>= 2; }\n\n\t\t\treturn (uint32_t)(n - (x & 1));\n\t\t}\n\n\t\treturn 8;\n\t}\n\n\t// To do: Update this to use VC++ _BitScanForward, _BitScanForward64;\n\t// GCC __builtin_ctz, __builtin_ctzl.\n\t// VC++ __lzcnt16, __lzcnt, __lzcnt64 requires recent CPUs (2013+) and probably can't be used.\n\t// http://en.wikipedia.org/wiki/Haswell_%28microarchitecture%29#New_features\n\ttemplate\n\teastl::enable_if_t && sizeof(UInt16) == 2, uint32_t> GetFirstBit(UInt16 x)\n\t{\n\t\tif(x)\n\t\t{\n\t\t\tuint32_t n = 1;\n\n\t\t\tif((x & 0x000000FF) == 0) { n += 8; x >>= 8; }\n\t\t\tif((x & 0x0000000F) == 0) { n += 4; x >>= 4; }\n\t\t\tif((x & 0x00000003) == 0) { n += 2; x >>= 2; }\n\n\t\t\treturn (uint32_t)(n - (x & 1));\n\t\t}\n\n\t\treturn 16;\n\t}\n\n\ttemplate\n\teastl::enable_if_t && sizeof(UInt32) == 4, uint32_t> GetFirstBit(UInt32 x)\n\t{\n#if defined(EA_COMPILER_MSVC) && (defined(EA_PROCESSOR_X86) || defined(EA_PROCESSOR_X86_64))\n\t\t// This has been benchmarked as significantly faster than the generic code below.\n\t\tunsigned char isNonZero;\n\t\tunsigned long index;\n\t\tisNonZero = _BitScanForward(&index, x);\n\t\treturn isNonZero ? (int)index : 32;\n#elif (defined(EA_COMPILER_GNUC) || defined(EA_COMPILER_CLANG)) && !defined(EA_COMPILER_EDG)\n\t\tif (x)\n\t\t\treturn __builtin_ctz(x);\n\t\treturn 32;\n#else\n\t\tif(x)\n\t\t{\n\t\t\tuint32_t n = 1;\n\n\t\t\tif((x & 0x0000FFFF) == 0) { n += 16; x >>= 16; }\n\t\t\tif((x & 0x000000FF) == 0) { n += 8; x >>= 8; }\n\t\t\tif((x & 0x0000000F) == 0) { n += 4; x >>= 4; }\n\t\t\tif((x & 0x00000003) == 0) { n += 2; x >>= 2; }\n\n\t\t\treturn (n - (x & 1));\n\t\t}\n\n\t\treturn 32;\n#endif\n\t}\n\n\ttemplate\n\teastl::enable_if_t && sizeof(UInt64) == 8, uint32_t> GetFirstBit(UInt64 x)\n\t{\n#if defined(EA_COMPILER_MSVC) && defined(EA_PROCESSOR_X86_64)\n\t\t// This has been benchmarked as significantly faster than the generic code below.\n\t\tunsigned char isNonZero;\n\t\tunsigned long index;\n\t\tisNonZero = _BitScanForward64(&index, x);\n\t\treturn isNonZero ? (int)index : 64;\n#elif (defined(EA_COMPILER_GNUC) || defined(EA_COMPILER_CLANG)) && !defined(EA_COMPILER_EDG)\n\t\tif (x)\n\t\t\treturn __builtin_ctzll(x);\n\t\treturn 64;\n#else\n\t\tif(x)\n\t\t{\n\t\t\tuint32_t n = 1;\n\n\t\t\tif((x & 0xFFFFFFFF) == 0) { n += 32; x >>= 32; }\n\t\t\tif((x & 0x0000FFFF) == 0) { n += 16; x >>= 16; }\n\t\t\tif((x & 0x000000FF) == 0) { n += 8; x >>= 8; }\n\t\t\tif((x & 0x0000000F) == 0) { n += 4; x >>= 4; }\n\t\t\tif((x & 0x00000003) == 0) { n += 2; x >>= 2; }\n\n\t\t\treturn (n - ((uint32_t)x & 1));\n\t\t}\n\n\t\treturn 64;\n#endif\n\t}\n\n\n\t#if EASTL_INT128_SUPPORTED\n\t\tinline uint32_t GetFirstBit(eastl_uint128_t x)\n\t\t{\n\t\t\tif(x)\n\t\t\t{\n\t\t\t\tuint32_t n = 1;\n\n\t\t\t\tif((x & UINT64_C(0xFFFFFFFFFFFFFFFF)) == 0) { n += 64; x >>= 64; }\n\t\t\t\tif((x & 0xFFFFFFFF) == 0) { n += 32; x >>= 32; }\n\t\t\t\tif((x & 0x0000FFFF) == 0) { n += 16; x >>= 16; }\n\t\t\t\tif((x & 0x000000FF) == 0) { n += 8; x >>= 8; }\n\t\t\t\tif((x & 0x0000000F) == 0) { n += 4; x >>= 4; }\n\t\t\t\tif((x & 0x00000003) == 0) { n += 2; x >>= 2; }\n\n\t\t\t\treturn (n - ((uint32_t)x & 1));\n\t\t\t}\n\n\t\t\treturn 128;\n\t\t}\n\t#endif\n\n\ttemplate\n\teastl::enable_if_t && sizeof(UInt8) == 1, uint32_t> GetLastBit(UInt8 x)\n\t{\n\t\tif(x)\n\t\t{\n\t\t\tuint32_t n = 0;\n\n\t\t\tif(x & 0xFFF0) { n += 4; x >>= 4; }\n\t\t\tif(x & 0xFFFC) { n += 2; x >>= 2; }\n\t\t\tif(x & 0xFFFE) { n += 1; }\n\n\t\t\treturn n;\n\t\t}\n\n\t\treturn 8;\n\t}\n\n\ttemplate\n\teastl::enable_if_t && sizeof(UInt16) == 2, uint32_t> GetLastBit(UInt16 x)\n\t{\n\t\tif(x)\n\t\t{\n\t\t\tuint32_t n = 0;\n\n\t\t\tif(x & 0xFF00) { n += 8; x >>= 8; }\n\t\t\tif(x & 0xFFF0) { n += 4; x >>= 4; }\n\t\t\tif(x & 0xFFFC) { n += 2; x >>= 2; }\n\t\t\tif(x & 0xFFFE) { n += 1; }\n\n\t\t\treturn n;\n\t\t}\n\n\t\treturn 16;\n\t}\n\n\ttemplate\n\teastl::enable_if_t && sizeof(UInt32) == 4, uint32_t> GetLastBit(UInt32 x)\n\t{\n#if defined(EA_COMPILER_MSVC) && (defined(EA_PROCESSOR_X86) || defined(EA_PROCESSOR_X86_64))\n\t\t// This has been benchmarked as significantly faster than the generic code below.\n\t\tunsigned char isNonZero;\n\t\tunsigned long index;\n\t\tisNonZero = _BitScanReverse(&index, x);\n\t\treturn isNonZero ? (int)index : 32;\n#elif (defined(EA_COMPILER_GNUC) || defined(EA_COMPILER_CLANG)) && !defined(EA_COMPILER_EDG)\n\t\tif (x)\n\t\t\treturn 31 - __builtin_clz(x);\n\t\treturn 32;\n#else\n\t\tif(x)\n\t\t{\n\t\t\tuint32_t n = 0;\n\n\t\t\tif(x & 0xFFFF0000) { n += 16; x >>= 16; }\n\t\t\tif(x & 0xFFFFFF00) { n += 8; x >>= 8; }\n\t\t\tif(x & 0xFFFFFFF0) { n += 4; x >>= 4; }\n\t\t\tif(x & 0xFFFFFFFC) { n += 2; x >>= 2; }\n\t\t\tif(x & 0xFFFFFFFE) { n += 1; }\n\n\t\t\treturn n;\n\t\t}\n\n\t\treturn 32;\n#endif\n\t}\n\n\ttemplate\n\teastl::enable_if_t && sizeof(UInt64) == 8, uint32_t> GetLastBit(UInt64 x)\n\t{\n#if defined(EA_COMPILER_MSVC) && defined(EA_PROCESSOR_X86_64)\n\t\t// This has been benchmarked as significantly faster than the generic code below.\n\t\tunsigned char isNonZero;\n\t\tunsigned long index;\n\t\tisNonZero = _BitScanReverse64(&index, x);\n\t\treturn isNonZero ? (int)index : 64;\n#elif (defined(EA_COMPILER_GNUC) || defined(EA_COMPILER_CLANG)) && !defined(EA_COMPILER_EDG)\n\t\tif (x)\n\t\t\treturn 63 - __builtin_clzll(x);\n\t\treturn 64;\n#else\n\t\tif(x)\n\t\t{\n\t\t\tuint32_t n = 0;\n\n\t\t\tif(x & UINT64_C(0xFFFFFFFF00000000)) { n += 32; x >>= 32; }\n\t\t\tif(x & 0xFFFF0000) { n += 16; x >>= 16; }\n\t\t\tif(x & 0xFFFFFF00) { n += 8; x >>= 8; }\n\t\t\tif(x & 0xFFFFFFF0) { n += 4; x >>= 4; }\n\t\t\tif(x & 0xFFFFFFFC) { n += 2; x >>= 2; }\n\t\t\tif(x & 0xFFFFFFFE) { n += 1; }\n\n\t\t\treturn n;\n\t\t}\n\n\t\treturn 64;\n#endif\n\t}\n\n\t#if EASTL_INT128_SUPPORTED\n\t\tinline uint32_t GetLastBit(eastl_uint128_t x)\n\t\t{\n\t\t\tif(x)\n\t\t\t{\n\t\t\t\tuint32_t n = 0;\n\t\t\t\t\n\t\t\t\teastl_uint128_t mask(UINT64_C(0xFFFFFFFFFFFFFFFF)); // There doesn't seem to exist compiler support for INT128_C() by any compiler. EAStdC's int128_t supports it though.\n\t\t\t\tmask <<= 64;\n\n\t\t\t\tif(x & mask) { n += 64; x >>= 64; }\n\t\t\t\tif(x & UINT64_C(0xFFFFFFFF00000000)) { n += 32; x >>= 32; }\n\t\t\t\tif(x & UINT64_C(0x00000000FFFF0000)) { n += 16; x >>= 16; }\n\t\t\t\tif(x & UINT64_C(0x00000000FFFFFF00)) { n += 8; x >>= 8; }\n\t\t\t\tif(x & UINT64_C(0x00000000FFFFFFF0)) { n += 4; x >>= 4; }\n\t\t\t\tif(x & UINT64_C(0x00000000FFFFFFFC)) { n += 2; x >>= 2; }\n\t\t\t\tif(x & UINT64_C(0x00000000FFFFFFFE)) { n += 1; }\n\n\t\t\t\treturn n;\n\t\t\t}\n\n\t\t\treturn 128;\n\t\t}\n\t#endif\n\n\n\n\n\t///////////////////////////////////////////////////////////////////////////\n\t// BitsetBase\n\t//\n\t// We tried two forms of array access here:\n\t// for(word_type *pWord(mWord), *pWordEnd(mWord + NW); pWord < pWordEnd; ++pWord)\n\t// *pWord = ...\n\t// and\n\t// for(size_t i = 0; i < NW; i++)\n\t// mWord[i] = ...\n\t//\n\t// For our tests (~NW < 16), the latter (using []) access resulted in faster code. \n\t///////////////////////////////////////////////////////////////////////////\n\n\n\ttemplate \n\tinline void BitsetBase::operator&=(const this_type& x)\n\t{\n\t\tfor(size_t i = 0; i < NW; i++)\n\t\t\tmWord[i] &= x.mWord[i];\n\t}\n\n\n\ttemplate \n\tinline void BitsetBase::operator|=(const this_type& x)\n\t{\n\t\tfor(size_t i = 0; i < NW; i++)\n\t\t\tmWord[i] |= x.mWord[i];\n\t}\n\n\n\ttemplate \n\tinline void BitsetBase::operator^=(const this_type& x)\n\t{\n\t\tfor(size_t i = 0; i < NW; i++)\n\t\t\tmWord[i] ^= x.mWord[i];\n\t}\n\n\n\ttemplate \n\tinline void BitsetBase::operator<<=(size_type n)\n\t{\n\t\tconst size_type nWordShift = (size_type)(n >> kBitsPerWordShift);\n\n\t\tif(nWordShift)\n\t\t{\n\t\t\tfor(int i = (int)(NW - 1); i >= 0; --i)\n\t\t\t\tmWord[i] = (nWordShift <= (size_type)i) ? mWord[i - nWordShift] : (word_type)0;\n\t\t}\n\n\t\tif(n &= kBitsPerWordMask)\n\t\t{\n\t\t\tfor(size_t i = (NW - 1); i > 0; --i)\n\t\t\t\tmWord[i] = (word_type)((mWord[i] << n) | (mWord[i - 1] >> (kBitsPerWord - n)));\n\t\t\tmWord[0] <<= n;\n\t\t}\n\n\t\t// We let the parent class turn off any upper bits.\n\t}\n\n\n\ttemplate \n\tinline void BitsetBase::operator>>=(size_type n)\n\t{\n\t\tconst size_type nWordShift = (size_type)(n >> kBitsPerWordShift);\n\n\t\tif(nWordShift)\n\t\t{\n\t\t\tfor(size_t i = 0; i < NW; ++i)\n\t\t\t\tmWord[i] = ((nWordShift < (NW - i)) ? mWord[i + nWordShift] : (word_type)0);\n\t\t}\n\n\t\tif(n &= kBitsPerWordMask)\n\t\t{\n\t\t\tfor(size_t i = 0; i < (NW - 1); ++i)\n\t\t\t\tmWord[i] = (word_type)((mWord[i] >> n) | (mWord[i + 1] << (kBitsPerWord - n)));\n\t\t\tmWord[NW - 1] >>= n;\n\t\t}\n\t}\n\n\n\ttemplate \n\tinline void BitsetBase::flip()\n\t{\n\t\tfor(size_t i = 0; i < NW; i++)\n\t\t\tmWord[i] = ~mWord[i];\n\t\t// We let the parent class turn off any upper bits.\n\t}\n\n\n\ttemplate \n\tinline void BitsetBase::set()\n\t{\n\t\tfor(size_t i = 0; i < NW; i++)\n\t\t\tmWord[i] = static_cast(~static_cast(0));\n\t\t// We let the parent class turn off any upper bits.\n\t}\n\n\n\ttemplate \n\tinline void BitsetBase::set(size_type i, bool value)\n\t{\n\t\tif(value)\n\t\t\tmWord[i >> kBitsPerWordShift] |= (static_cast(1) << (i & kBitsPerWordMask));\n\t\telse\n\t\t\tmWord[i >> kBitsPerWordShift] &= ~(static_cast(1) << (i & kBitsPerWordMask));\n\t}\n\n\n\ttemplate \n\tinline void BitsetBase::reset()\n\t{\n\t\tif(NW > 16) // This is a constant expression and should be optimized away.\n\t\t{\n\t\t\t// This will be fastest if compiler intrinsic function optimizations are enabled.\n\t\t\tmemset(mWord, 0, sizeof(mWord));\n\t\t}\n\t\telse\n\t\t{\n\t\t\tfor(size_t i = 0; i < NW; i++)\n\t\t\t\tmWord[i] = 0;\n\t\t}\n\t}\n\n\n\ttemplate \n\tinline bool BitsetBase::operator==(const this_type& x) const\n\t{\n\t\tfor(size_t i = 0; i < NW; i++)\n\t\t{\n\t\t\tif(mWord[i] != x.mWord[i])\n\t\t\t\treturn false;\n\t\t}\n\t\treturn true;\n\t}\n\n\n\ttemplate \n\tinline bool BitsetBase::any() const\n\t{\n\t\tfor(size_t i = 0; i < NW; i++)\n\t\t{\n\t\t\tif(mWord[i])\n\t\t\t\treturn true;\n\t\t}\n\t\treturn false;\n\t}\n\n\n\ttemplate \n\tinline typename BitsetBase::size_type\n\tBitsetBase::count() const\n\t{\n\t\tsize_type n = 0;\n\t\tfor(size_t i = 0; i < NW; i++)\n\t\t\tn += popcount(mWord[i]);\n\t\treturn n;\n\t}\n\n\n\ttemplate \n\tinline typename BitsetBase::word_type&\n\tBitsetBase::DoGetWord(size_type i)\n\t{\n\t\treturn mWord[i >> kBitsPerWordShift];\n\t}\n\n\n\ttemplate \n\tinline typename BitsetBase::word_type\n\tBitsetBase::DoGetWord(size_type i) const\n\t{\n\t\treturn mWord[i >> kBitsPerWordShift];\n\t}\n\n\n\ttemplate \n\tinline typename BitsetBase::size_type \n\tBitsetBase::DoFindFirst() const\n\t{\n\t\tfor(size_type word_index = 0; word_index < NW; ++word_index)\n\t\t{\n\t\t\tconst size_type fbiw = GetFirstBit(mWord[word_index]);\n\n\t\t\tif(fbiw != kBitsPerWord)\n\t\t\t\treturn (word_index * kBitsPerWord) + fbiw;\n\t\t}\n\n\t\treturn (size_type)NW * kBitsPerWord;\n\t}\n\n\n#if EASTL_DISABLE_BITSET_ARRAYBOUNDS_WARNING\nEA_DISABLE_GCC_WARNING(-Warray-bounds)\n#endif\n\n\ttemplate \n\tinline typename BitsetBase::size_type \n\tBitsetBase::DoFindNext(size_type last_find) const\n\t{\n\t\t// Start looking from the next bit.\n\t\t++last_find;\n\n\t\t// Set initial state based on last find.\n\t\tsize_type word_index = static_cast(last_find >> kBitsPerWordShift);\n\t\tsize_type bit_index = static_cast(last_find & kBitsPerWordMask);\n\n\t\t// To do: There probably is a more elegant way to write looping below.\n\t\tif(word_index < NW)\n\t\t{\n\t\t\t// Mask off previous bits of the word so our search becomes a \"find first\".\n\t\t\tword_type this_word = mWord[word_index] & (static_cast(~0) << bit_index);\n\n\t\t\tfor(;;)\n\t\t\t{\n\t\t\t\tconst size_type fbiw = GetFirstBit(this_word);\n\n\t\t\t\tif(fbiw != kBitsPerWord)\n\t\t\t\t\treturn (word_index * kBitsPerWord) + fbiw;\n\n\t\t\t\tif(++word_index < NW)\n\t\t\t\t\tthis_word = mWord[word_index];\n\t\t\t\telse\n\t\t\t\t\tbreak;\n\t\t\t}\n\t\t}\n\n\t\treturn (size_type)NW * kBitsPerWord;\n\t}\n\n#if EASTL_DISABLE_BITSET_ARRAYBOUNDS_WARNING\nEA_RESTORE_GCC_WARNING()\n#endif\n\n\n\n\ttemplate \n\tinline typename BitsetBase::size_type \n\tBitsetBase::DoFindLast() const\n\t{\n\t\tfor(size_type word_index = (size_type)NW; word_index > 0; --word_index)\n\t\t{\n\t\t\tconst size_type lbiw = GetLastBit(mWord[word_index - 1]);\n\n\t\t\tif(lbiw != kBitsPerWord)\n\t\t\t\treturn ((word_index - 1) * kBitsPerWord) + lbiw;\n\t\t}\n\n\t\treturn (size_type)NW * kBitsPerWord;\n\t}\n\n\n\ttemplate \n\tinline typename BitsetBase::size_type \n\tBitsetBase::DoFindPrev(size_type last_find) const\n\t{\n\t\tif(last_find > 0)\n\t\t{\n\t\t\t// Set initial state based on last find.\n\t\t\tsize_type word_index = static_cast(last_find >> kBitsPerWordShift);\n\t\t\tsize_type bit_index = static_cast(last_find & kBitsPerWordMask);\n\n\t\t\t// Mask off subsequent bits of the word so our search becomes a \"find last\".\n\t\t\t// We do two shifts here because it's undefined behaviour to right shift greater than or equal to the number of bits in the integer.\n\t\t\t// \n\t\t\t// Note: operator~() is an arithmetic operator and performs integral promotions, ie. small integrals are promoted to an int.\n\t\t\t// Because the promotion is before applying operator~() we need to cast back to our word type otherwise we end up with extraneous set bits.\n\t\t\tword_type mask = (static_cast(~static_cast(0)) >> (kBitsPerWord - 1 - bit_index)) >> 1;\n\t\t\tword_type this_word = mWord[word_index] & mask;\n\n\t\t\tfor(;;)\n\t\t\t{\n\t\t\t\tconst size_type lbiw = GetLastBit(this_word);\n\n\t\t\t\tif(lbiw != kBitsPerWord)\n\t\t\t\t\treturn (word_index * kBitsPerWord) + lbiw;\n\n\t\t\t\tif(word_index > 0)\n\t\t\t\t\tthis_word = mWord[--word_index];\n\t\t\t\telse\n\t\t\t\t\tbreak;\n\t\t\t}\n\t\t}\n\n\t\treturn (size_type)NW * kBitsPerWord;\n\t}\n\n\n\n\t///////////////////////////////////////////////////////////////////////////\n\t// BitsetBase<1, WordType>\n\t///////////////////////////////////////////////////////////////////////////\n\n\n\ttemplate \n\tinline void BitsetBase<1, WordType>::operator&=(const this_type& x)\n\t{\n\t\tmWord[0] &= x.mWord[0];\n\t}\n\n\n\ttemplate \n\tinline void BitsetBase<1, WordType>::operator|=(const this_type& x)\n\t{\n\t\tmWord[0] |= x.mWord[0];\n\t}\n\n\n\ttemplate \n\tinline void BitsetBase<1, WordType>::operator^=(const this_type& x)\n\t{\n\t\tmWord[0] ^= x.mWord[0];\n\t}\n\n\n\ttemplate \n\tinline void BitsetBase<1, WordType>::operator<<=(size_type n)\n\t{\n\t\tmWord[0] <<= n;\n\t\t// We let the parent class turn off any upper bits.\n\t}\n\n\n\ttemplate \n\tinline void BitsetBase<1, WordType>::operator>>=(size_type n)\n\t{\n\t\tmWord[0] >>= n;\n\t}\n\n\n\ttemplate \n\tinline void BitsetBase<1, WordType>::flip()\n\t{\n\t\tmWord[0] = ~mWord[0];\n\t\t// We let the parent class turn off any upper bits.\n\t}\n\n\n\ttemplate \n\tinline void BitsetBase<1, WordType>::set()\n\t{\n\t\tmWord[0] = static_cast(~static_cast(0));\n\t\t// We let the parent class turn off any upper bits.\n\t}\n\n\n\ttemplate \n\tinline void BitsetBase<1, WordType>::set(size_type i, bool value)\n\t{\n\t\tif(value)\n\t\t\tmWord[0] |= (static_cast(1) << i);\n\t\telse\n\t\t\tmWord[0] &= ~(static_cast(1) << i);\n\t}\n\n\n\ttemplate \n\tinline void BitsetBase<1, WordType>::reset()\n\t{\n\t\tmWord[0] = 0;\n\t}\n\n\n\ttemplate \n\tinline bool BitsetBase<1, WordType>::operator==(const this_type& x) const\n\t{\n\t\treturn mWord[0] == x.mWord[0];\n\t}\n\n\n\ttemplate \n\tinline bool BitsetBase<1, WordType>::any() const\n\t{\n\t\treturn mWord[0] != 0;\n\t}\n\n\n\ttemplate \n\tinline typename BitsetBase<1, WordType>::size_type\n\tBitsetBase<1, WordType>::count() const\n\t{\n\t\treturn popcount(mWord[0]);\n\t}\n\n\n\ttemplate \n\tinline typename BitsetBase<1, WordType>::word_type&\n\tBitsetBase<1, WordType>::DoGetWord(size_type)\n\t{\n\t\treturn mWord[0];\n\t}\n\n\n\ttemplate \n\tinline typename BitsetBase<1, WordType>::word_type\n\tBitsetBase<1, WordType>::DoGetWord(size_type) const\n\t{\n\t\treturn mWord[0];\n\t}\n\n\n\ttemplate \n\tinline typename BitsetBase<1, WordType>::size_type\n\tBitsetBase<1, WordType>::DoFindFirst() const\n\t{\n\t\treturn GetFirstBit(mWord[0]);\n\t}\n\n\n\ttemplate \n\tinline typename BitsetBase<1, WordType>::size_type \n\tBitsetBase<1, WordType>::DoFindNext(size_type last_find) const\n\t{\n\t\tif(++last_find < kBitsPerWord)\n\t\t{\n\t\t\t// Mask off previous bits of word so our search becomes a \"find first\".\n\t\t\tconst word_type this_word = mWord[0] & (static_cast(~0) << last_find);\n\n\t\t\treturn GetFirstBit(this_word);\n\t\t}\n\n\t\treturn kBitsPerWord;\n\t}\n\n\n\ttemplate \n\tinline typename BitsetBase<1, WordType>::size_type \n\tBitsetBase<1, WordType>::DoFindLast() const\n\t{\n\t\treturn GetLastBit(mWord[0]);\n\t}\n\n\n\ttemplate \n\tinline typename BitsetBase<1, WordType>::size_type \n\tBitsetBase<1, WordType>::DoFindPrev(size_type last_find) const\n\t{\n\t\tif(last_find > 0)\n\t\t{\n\t\t\t// Mask off previous bits of word so our search becomes a \"find first\".\n\t\t\tconst word_type this_word = mWord[0] & (static_cast(~static_cast(0)) >> (kBitsPerWord - last_find));\n\n\t\t\treturn GetLastBit(this_word);\n\t\t}\n\n\t\treturn kBitsPerWord;\n\t}\n\n\n\n\n\t///////////////////////////////////////////////////////////////////////////\n\t// BitsetBase<2, WordType>\n\t///////////////////////////////////////////////////////////////////////////\n\n\n\ttemplate \n\tinline void BitsetBase<2, WordType>::operator&=(const this_type& x)\n\t{\n\t\tmWord[0] &= x.mWord[0];\n\t\tmWord[1] &= x.mWord[1];\n\t}\n\n\n\ttemplate \n\tinline void BitsetBase<2, WordType>::operator|=(const this_type& x)\n\t{\n\t\tmWord[0] |= x.mWord[0];\n\t\tmWord[1] |= x.mWord[1];\n\t}\n\n\n\ttemplate \n\tinline void BitsetBase<2, WordType>::operator^=(const this_type& x)\n\t{\n\t\tmWord[0] ^= x.mWord[0];\n\t\tmWord[1] ^= x.mWord[1];\n\t}\n\n\n\ttemplate \n\tinline void BitsetBase<2, WordType>::operator<<=(size_type n)\n\t{\n\t\tif(n) // to avoid a shift by kBitsPerWord, which is undefined\n\t\t{\n\t\t\tif(EASTL_UNLIKELY(n >= kBitsPerWord)) // parent expected to handle high bits and n >= 64\n\t\t\t{\n\t\t\t\tmWord[1] = mWord[0];\n\t\t\t\tmWord[0] = 0;\n\t\t\t\tn -= kBitsPerWord;\n\t\t\t}\n\n\t\t\tmWord[1] = (mWord[1] << n) | (mWord[0] >> (kBitsPerWord - n)); // Intentionally use | instead of +.\n\t\t\tmWord[0] <<= n;\n\t\t\t// We let the parent class turn off any upper bits.\n\t\t}\n\t}\n\n\n\ttemplate \n\tinline void BitsetBase<2, WordType>::operator>>=(size_type n)\n\t{\n\t\tif(n) // to avoid a shift by kBitsPerWord, which is undefined\n\t\t{\n\t\t\tif(EASTL_UNLIKELY(n >= kBitsPerWord)) // parent expected to handle n >= 64\n\t\t\t{\n\t\t\t\tmWord[0] = mWord[1];\n\t\t\t\tmWord[1] = 0;\n\t\t\t\tn -= kBitsPerWord;\n\t\t\t}\n\t\t\t\n\t\t\tmWord[0] = (mWord[0] >> n) | (mWord[1] << (kBitsPerWord - n)); // Intentionally use | instead of +.\n\t\t\tmWord[1] >>= n;\n\t\t}\n\t}\n\n\n\ttemplate \n\tinline void BitsetBase<2, WordType>::flip()\n\t{\n\t\tmWord[0] = ~mWord[0];\n\t\tmWord[1] = ~mWord[1];\n\t\t// We let the parent class turn off any upper bits.\n\t}\n\n\n\ttemplate \n\tinline void BitsetBase<2, WordType>::set()\n\t{\n\t\tEA_DISABLE_VC_WARNING(4245); // '=': conversion from 'int' to 'unsigned short', signed/unsigned mismatch \n\t\t// https://learn.microsoft.com/en-us/cpp/error-messages/compiler-warnings/compiler-warning-level-4-c4245?view=msvc-170\n\t\t// MSVC incorrectly believes 0 is a negative value.\n\t\tmWord[0] = ~static_cast(0);\n\t\tmWord[1] = ~static_cast(0);\n\t\tEA_RESTORE_VC_WARNING();\n\t\t// We let the parent class turn off any upper bits.\n\t}\n\n\n\ttemplate \n\tinline void BitsetBase<2, WordType>::set(size_type i, bool value)\n\t{\n\t\tif(value)\n\t\t\tmWord[i >> kBitsPerWordShift] |= (static_cast(1) << (i & kBitsPerWordMask));\n\t\telse\n\t\t\tmWord[i >> kBitsPerWordShift] &= ~(static_cast(1) << (i & kBitsPerWordMask));\n\t}\n\n\n\ttemplate \n\tinline void BitsetBase<2, WordType>::reset()\n\t{\n\t\tmWord[0] = 0;\n\t\tmWord[1] = 0;\n\t}\n\n\n\ttemplate \n\tinline bool BitsetBase<2, WordType>::operator==(const this_type& x) const\n\t{\n\t\treturn (mWord[0] == x.mWord[0]) && (mWord[1] == x.mWord[1]);\n\t}\n\n\n\ttemplate \n\tinline bool BitsetBase<2, WordType>::any() const\n\t{\n\t\t// Or with two branches: { return (mWord[0] != 0) || (mWord[1] != 0); }\n\t\treturn (mWord[0] | mWord[1]) != 0; \n\t}\n\n\ttemplate \n\tinline typename BitsetBase<2, WordType>::size_type\n\tBitsetBase<2, WordType>::count() const\n\t{\n\t\treturn popcount(mWord[0]) + popcount(mWord[1]);\n\t}\n\n\n\ttemplate \n\tinline typename BitsetBase<2, WordType>::word_type&\n\tBitsetBase<2, WordType>::DoGetWord(size_type i)\n\t{\n\t\treturn mWord[i >> kBitsPerWordShift];\n\t}\n\n\n\ttemplate \n\tinline typename BitsetBase<2, WordType>::word_type\n\tBitsetBase<2, WordType>::DoGetWord(size_type i) const\n\t{\n\t\treturn mWord[i >> kBitsPerWordShift];\n\t}\n\n\n\ttemplate \n\tinline typename BitsetBase<2, WordType>::size_type \n\tBitsetBase<2, WordType>::DoFindFirst() const\n\t{\n\t\tsize_type fbiw = GetFirstBit(mWord[0]);\n\n\t\tif(fbiw != kBitsPerWord)\n\t\t\treturn fbiw;\n\n\t\tfbiw = GetFirstBit(mWord[1]);\n\n\t\tif(fbiw != kBitsPerWord)\n\t\t\treturn kBitsPerWord + fbiw;\n\n\t\treturn 2 * kBitsPerWord;\n\t}\n\n\n\ttemplate \n\tinline typename BitsetBase<2, WordType>::size_type \n\tBitsetBase<2, WordType>::DoFindNext(size_type last_find) const\n\t{\n\t\t// If the last find was in the first word, we must check it and then possibly the second.\n\t\tif(++last_find < (size_type)kBitsPerWord)\n\t\t{\n\t\t\t// Mask off previous bits of word so our search becomes a \"find first\".\n\t\t\tword_type this_word = mWord[0] & (static_cast(~0) << last_find);\n\n\t\t\t// Step through words.\n\t\t\tsize_type fbiw = GetFirstBit(this_word);\n\n\t\t\tif(fbiw != kBitsPerWord)\n\t\t\t\treturn fbiw;\n\n\t\t\tfbiw = GetFirstBit(mWord[1]);\n\n\t\t\tif(fbiw != kBitsPerWord)\n\t\t\t\treturn kBitsPerWord + fbiw;\n\t\t}\n\t\telse if(last_find < (size_type)(2 * kBitsPerWord))\n\t\t{\n\t\t\t// The last find was in the second word, remove the bit count of the first word from the find.\n\t\t\tlast_find -= kBitsPerWord;\n\n\t\t\t// Mask off previous bits of word so our search becomes a \"find first\".\n\t\t\tword_type this_word = mWord[1] & (static_cast(~0) << last_find);\n\n\t\t\tconst size_type fbiw = GetFirstBit(this_word);\n\n\t\t\tif(fbiw != kBitsPerWord)\n\t\t\t\treturn kBitsPerWord + fbiw;\n\t\t}\n\n\t\treturn 2 * kBitsPerWord;\n\t}\n\n\n\ttemplate \n\tinline typename BitsetBase<2, WordType>::size_type \n\tBitsetBase<2, WordType>::DoFindLast() const\n\t{\n\t\tsize_type lbiw = GetLastBit(mWord[1]);\n\n\t\tif(lbiw != kBitsPerWord)\n\t\t\treturn kBitsPerWord + lbiw;\n\n\t\tlbiw = GetLastBit(mWord[0]);\n\n\t\tif(lbiw != kBitsPerWord)\n\t\t\treturn lbiw;\n\n\t\treturn 2 * kBitsPerWord;\n\t}\n\n\n\ttemplate \n\tinline typename BitsetBase<2, WordType>::size_type \n\tBitsetBase<2, WordType>::DoFindPrev(size_type last_find) const\n\t{\n\t\t// If the last find was in the second word, we must check it and then possibly the first.\n\t\tif(last_find > (size_type)kBitsPerWord)\n\t\t{\n\t\t\t// This has the same effect as last_find %= kBitsPerWord in our case.\n\t\t\tlast_find -= kBitsPerWord;\n\n\t\t\t// Mask off previous bits of word so our search becomes a \"find first\".\n\t\t\tword_type this_word = mWord[1] & (static_cast(~static_cast(0)) >> (kBitsPerWord - last_find));\n\n\t\t\t// Step through words.\n\t\t\tsize_type lbiw = GetLastBit(this_word);\n\n\t\t\tif(lbiw != kBitsPerWord)\n\t\t\t\treturn kBitsPerWord + lbiw;\n\n\t\t\tlbiw = GetLastBit(mWord[0]);\n\n\t\t\tif(lbiw != kBitsPerWord)\n\t\t\t\treturn lbiw;\n\t\t}\n\t\telse if(last_find != 0)\n\t\t{\n\t\t\t// Mask off previous bits of word so our search becomes a \"find first\".\n\t\t\tword_type this_word = mWord[0] & (static_cast(~static_cast(0)) >> (kBitsPerWord - last_find));\n\n\t\t\tconst size_type lbiw = GetLastBit(this_word);\n\n\t\t\tif(lbiw != kBitsPerWord)\n\t\t\t\treturn lbiw;\n\t\t}\n\n\t\treturn 2 * kBitsPerWord;\n\t}\n\n\n\n\t///////////////////////////////////////////////////////////////////////////\n\t// bitset::reference\n\t///////////////////////////////////////////////////////////////////////////\n\n\ttemplate \n\tinline bitset::reference::reference(const bitset& x, size_type i)\n\t\t: mpBitWord(&const_cast(x).DoGetWord(i)),\n\t\t mnBitIndex(i & kBitsPerWordMask)\n\t{ // We have an issue here because the above is casting away the const-ness of the source bitset.\n\t\t// Empty\n\t}\n\n\n\ttemplate \n\tinline typename bitset::reference&\n\tbitset::reference::operator=(bool value)\n\t{\n\t\tif(value)\n\t\t\t*mpBitWord |= (static_cast(1) << (mnBitIndex & kBitsPerWordMask));\n\t\telse\n\t\t\t*mpBitWord &= ~(static_cast(1) << (mnBitIndex & kBitsPerWordMask));\n\t\treturn *this;\n\t}\n\n\n\ttemplate \n\tinline typename bitset::reference&\n\tbitset::reference::operator=(const reference& x)\n\t{\n\t\tif(*x.mpBitWord & (static_cast(1) << (x.mnBitIndex & kBitsPerWordMask)))\n\t\t\t*mpBitWord |= (static_cast(1) << (mnBitIndex & kBitsPerWordMask));\n\t\telse\n\t\t\t*mpBitWord &= ~(static_cast(1) << (mnBitIndex & kBitsPerWordMask));\n\t\treturn *this;\n\t}\n\n\n\ttemplate \n\tinline bool bitset::reference::operator~() const\n\t{\n\t\treturn (*mpBitWord & (static_cast(1) << (mnBitIndex & kBitsPerWordMask))) == 0;\n\t}\n\n\n\t//Defined inline in the class because Metrowerks fails to be able to compile it here.\n\t//template \n\t//inline bitset::reference::operator bool() const\n\t//{\n\t// return (*mpBitWord & (static_cast(1) << (mnBitIndex & kBitsPerWordMask))) != 0;\n\t//}\n\n\n\ttemplate \n\tinline typename bitset::reference&\n\tbitset::reference::flip()\n\t{\n\t\t*mpBitWord ^= static_cast(1) << (mnBitIndex & kBitsPerWordMask);\n\t\treturn *this;\n\t}\n\n\n\n\n\t///////////////////////////////////////////////////////////////////////////\n\t// bitset\n\t///////////////////////////////////////////////////////////////////////////\n\n\ttemplate \n\tinline bitset::bitset()\n\t{\n\t\treset();\n\t}\n\n\tEA_DISABLE_VC_WARNING(6313)\n#if EA_IS_ENABLED(EASTL_DEPRECATIONS_FOR_2024_SEPT)\n\ttemplate \n\tinline bitset::bitset(unsigned long long value)\n\t{\n\t\tdetail::from_unsigned_integral(*this, value);\n\t}\n#else\n\ttemplate \n\tinline bitset::bitset(uint32_t value)\n\t{\n\t\tdetail::from_unsigned_integral(*this, value);\n\t}\n#endif\n\tEA_RESTORE_VC_WARNING()\n\n\n\ttemplate \n\tinline typename bitset::this_type&\n\tbitset::operator&=(const this_type& x)\n\t{\n\t\tbase_type::operator&=(x);\n\t\treturn *this;\n\t}\n\n\n\ttemplate \n\tinline typename bitset::this_type&\n\tbitset::operator|=(const this_type& x)\n\t{\n\t\tbase_type::operator|=(x);\n\t\treturn *this;\n\t}\n\n\n\ttemplate \n\tinline typename bitset::this_type&\n\tbitset::operator^=(const this_type& x)\n\t{\n\t\tbase_type::operator^=(x);\n\t\treturn *this;\n\t}\n\n\n\ttemplate \n\tinline typename bitset::this_type&\n\tbitset::operator<<=(size_type n)\n\t{\n\t\tif(EASTL_LIKELY((intptr_t)n < (intptr_t)N))\n\t\t{\n\t\t\tEA_DISABLE_VC_WARNING(6313)\n\t\t\tbase_type::operator<<=(n);\n\t\t\tif((N & kBitsPerWordMask) || (N == 0)) // If there are any high bits to clear... (If we didn't have this check, then the code below would do the wrong thing when N == 32.\n\t\t\t\tmWord[kWordCount - 1] &= ~(static_cast(~static_cast(0)) << (N & kBitsPerWordMask)); // This clears any high unused bits. We need to do this so that shift operations proceed correctly.\n\t\t\tEA_RESTORE_VC_WARNING()\n\t\t}\n\t\telse\n\t\t\tbase_type::reset();\n\t\treturn *this;\n\t}\n\n\n\ttemplate \n\tinline typename bitset::this_type&\n\tbitset::operator>>=(size_type n)\n\t{\n\t\tif(EASTL_LIKELY(n < N))\n\t\t\tbase_type::operator>>=(n);\n\t\telse\n\t\t\tbase_type::reset();\n\t\treturn *this;\n\t}\n\n\n\ttemplate \n\tinline typename bitset::this_type&\n\tbitset::set()\n\t{\n\t\tbase_type::set(); // This sets all bits.\n\t\tif((N & kBitsPerWordMask) || (N == 0)) // If there are any high bits to clear... (If we didn't have this check, then the code below would do the wrong thing when N == 32.\n\t\t\tmWord[kWordCount - 1] &= ~(static_cast(~static_cast(0)) << (N & kBitsPerWordMask)); // This clears any high unused bits. We need to do this so that shift operations proceed correctly.\n\t\treturn *this;\n\t}\n\n\n\ttemplate \n\tinline typename bitset::this_type&\n\tbitset::set(size_type i, bool value)\n\t{\n\t\tif(i < N)\n\t\t\tbase_type::set(i, value);\n\t\telse\n\t\t{\n\t\t\t#if EASTL_ASSERT_ENABLED\n\t\t\t\tif(EASTL_UNLIKELY(!(i < N)))\n\t\t\t\t\tEASTL_FAIL_MSG(\"bitset::set -- out of range\");\n\t\t\t#endif\n\n\t\t\t#if EASTL_EXCEPTIONS_ENABLED\n\t\t\t\tthrow std::out_of_range(\"bitset::set\");\n\t\t\t#endif\n\t\t}\n\n\t\treturn *this;\n\t}\n\n\n\ttemplate \n\tinline typename bitset::this_type&\n\tbitset::reset()\n\t{\n\t\tbase_type::reset();\n\t\treturn *this;\n\t}\n\n\n\ttemplate \n\tinline typename bitset::this_type&\n\tbitset::reset(size_type i)\n\t{\n\t\tif(EASTL_LIKELY(i < N))\n\t\t\tDoGetWord(i) &= ~(static_cast(1) << (i & kBitsPerWordMask));\n\t\telse\n\t\t{\n\t\t\t#if EASTL_ASSERT_ENABLED\n\t\t\t\tif(EASTL_UNLIKELY(!(i < N)))\n\t\t\t\t\tEASTL_FAIL_MSG(\"bitset::reset -- out of range\");\n\t\t\t#endif\n\n\t\t\t#if EASTL_EXCEPTIONS_ENABLED\n\t\t\t\tthrow std::out_of_range(\"bitset::reset\");\n\t\t\t#endif\n\t\t}\n\n\t\treturn *this;\n\t}\n\n\t\t\n\ttemplate \n\tinline typename bitset::this_type&\n\tbitset::flip()\n\t{\n\t\tEA_DISABLE_VC_WARNING(6313)\n\t\tbase_type::flip();\n\t\tif((N & kBitsPerWordMask) || (N == 0)) // If there are any high bits to clear... (If we didn't have this check, then the code below would do the wrong thing when N == 32.\n\t\t\tmWord[kWordCount - 1] &= ~(static_cast(~static_cast(0)) << (N & kBitsPerWordMask)); // This clears any high unused bits. We need to do this so that shift operations proceed correctly.\n\t\treturn *this;\n\t\tEA_RESTORE_VC_WARNING()\n\t}\n\n\n\ttemplate \n\tinline typename bitset::this_type&\n\tbitset::flip(size_type i)\n\t{\n\t\tif(EASTL_LIKELY(i < N))\n\t\t\tDoGetWord(i) ^= (static_cast(1) << (i & kBitsPerWordMask));\n\t\telse\n\t\t{\n\t\t\t#if EASTL_ASSERT_ENABLED\n\t\t\t\tif(EASTL_UNLIKELY(!(i < N)))\n\t\t\t\t\tEASTL_FAIL_MSG(\"bitset::flip -- out of range\");\n\t\t\t#endif\n\n\t\t\t#if EASTL_EXCEPTIONS_ENABLED\n\t\t\t\tthrow std::out_of_range(\"bitset::flip\");\n\t\t\t#endif\n\t\t}\n\t\treturn *this;\n\t}\n\t\t\n\n\ttemplate \n\tinline typename bitset::this_type\n\tbitset::operator~() const\n\t{\n\t\treturn this_type(*this).flip();\n\t}\n\n\n\ttemplate \n\tinline typename bitset::reference\n\tbitset::operator[](size_type i)\n\t{\n\t\t#if EASTL_ASSERT_ENABLED\n\t\t\tif(EASTL_UNLIKELY(!(i < N)))\n\t\t\t\tEASTL_FAIL_MSG(\"bitset::operator[] -- out of range\");\n\t\t#endif\n\n\t\treturn reference(*this, i);\n\t}\n\n\n\ttemplate \n\tinline bool bitset::operator[](size_type i) const\n\t{\n\t\t#if EASTL_ASSERT_ENABLED\n\t\t\tif(EASTL_UNLIKELY(!(i < N)))\n\t\t\t\tEASTL_FAIL_MSG(\"bitset::operator[] -- out of range\");\n\t\t#endif\n\n\t\treturn (DoGetWord(i) & (static_cast(1) << (i & kBitsPerWordMask))) != 0;\n\t}\n\n\n\ttemplate \n\tinline const typename bitset::word_type* bitset::data() const\n\t{\n\t\treturn base_type::mWord;\n\t}\n\n\n\ttemplate \n\tinline typename bitset::word_type* bitset::data()\n\t{\n\t\treturn base_type::mWord;\n\t}\n\n\n\ttemplate \n\tinline void bitset::from_uint32(uint32_t value)\n\t{\n\t\tdetail::from_unsigned_integral(*this, value);\n\t}\n\n\n\ttemplate \n\tinline void bitset::from_uint64(uint64_t value)\n\t{\n\t\tdetail::from_unsigned_integral(*this, value);\n\t}\n\n\n\ttemplate \n\tinline unsigned long bitset::to_ulong() const\n\t{\n\t\treturn detail::to_unsigned_integral(*this);\n\t}\n\n\n\ttemplate \n\tinline uint32_t bitset::to_uint32() const\n\t{\n\t\treturn detail::to_unsigned_integral(*this);\n\t}\n\n\n\ttemplate \n\tinline uint64_t bitset::to_uint64() const\n\t{\n\t\treturn detail::to_unsigned_integral(*this);\n\t}\n\n\n\t// template \n\t// inline typename bitset::size_type\n\t// bitset::count() const\n\t// {\n\t// return base_type::count();\n\t// }\n\n\n\ttemplate \n\tinline typename bitset::size_type\n\tbitset::size() const\n\t{\n\t\treturn (size_type)N;\n\t}\n\n\n\ttemplate \n\tinline bool bitset::operator==(const this_type& x) const\n\t{\n\t\treturn base_type::operator==(x);\n\t}\n\n#if !defined(EA_COMPILER_HAS_THREE_WAY_COMPARISON)\n\ttemplate \n\tinline bool bitset::operator!=(const this_type& x) const\n\t{\n\t\treturn !base_type::operator==(x);\n\t}\n#endif\n\n\ttemplate \n\tinline bool bitset::test(size_type i) const\n\t{\n\t\tif(EASTL_UNLIKELY(i < N))\n\t\t\treturn (DoGetWord(i) & (static_cast(1) << (i & kBitsPerWordMask))) != 0;\n\n\t\t#if EASTL_ASSERT_ENABLED\n\t\t\tEASTL_FAIL_MSG(\"bitset::test -- out of range\");\n\t\t#endif\n\n\t\t#if EASTL_EXCEPTIONS_ENABLED\n\t\t\tthrow std::out_of_range(\"bitset::test\");\n\t\t#else\n\t\t\treturn false;\n\t\t#endif\n\t}\n\n\n\t// template \n\t// inline bool bitset::any() const\n\t// {\n\t// return base_type::any();\n\t// }\n\n\n\ttemplate \n\tinline bool bitset::all() const\n\t{\n\t\treturn count() == size();\n\t}\n\n\n\ttemplate \n\tinline bool bitset::none() const\n\t{\n\t\treturn !base_type::any();\n\t}\n\n\n\ttemplate \n\tinline typename bitset::this_type\n\tbitset::operator<<(size_type n) const\n\t{\n\t\treturn this_type(*this).operator<<=(n);\n\t}\n\n\n\ttemplate \n\tinline typename bitset::this_type\n\tbitset::operator>>(size_type n) const\n\t{\n\t\treturn this_type(*this).operator>>=(n);\n\t}\n\n\n\ttemplate \n\tinline typename bitset::size_type\n\tbitset::find_first() const\n\t{\n\t\tconst size_type i = base_type::DoFindFirst();\n\n\t\tif(i < kSize)\n\t\t\treturn i;\n\t\t// Else i could be the base type bit count, so we clamp it to our size.\n\n\t\treturn kSize;\n\t}\n\n\n\ttemplate \n\tinline typename bitset::size_type\n\tbitset::find_next(size_type last_find) const\n\t{\n\t\tconst size_type i = base_type::DoFindNext(last_find);\n\n\t\tif(i < kSize)\n\t\t\treturn i;\n\t\t// Else i could be the base type bit count, so we clamp it to our size.\n\n\t\treturn kSize;\n\t}\n\n\n\ttemplate \n\tinline typename bitset::size_type\n\tbitset::find_last() const\n\t{\n\t\tconst size_type i = base_type::DoFindLast();\n\n\t\tif(i < kSize)\n\t\t\treturn i;\n\t\t// Else i could be the base type bit count, so we clamp it to our size.\n\n\t\treturn kSize;\n\t}\n\n\n\ttemplate \n\tinline typename bitset::size_type\n\tbitset::find_prev(size_type last_find) const\n\t{\n\t\tconst size_type i = base_type::DoFindPrev(last_find);\n\n\t\tif(i < kSize)\n\t\t\treturn i;\n\t\t// Else i could be the base type bit count, so we clamp it to our size.\n\n\t\treturn kSize;\n\t}\n\n\n\n\t///////////////////////////////////////////////////////////////////////////\n\t// global operators\n\t///////////////////////////////////////////////////////////////////////////\n\n\ttemplate \n\tinline bitset operator&(const bitset& a, const bitset& b)\n\t{\n\t\t// We get betting inlining when we don't declare temporary variables.\n\t\treturn bitset(a).operator&=(b);\n\t}\n\n\n\ttemplate \n\tinline bitset operator|(const bitset& a, const bitset& b)\n\t{\n\t\treturn bitset(a).operator|=(b);\n\t}\n\n\n\ttemplate \n\tinline bitset operator^(const bitset& a, const bitset& b)\n\t{\n\t\treturn bitset(a).operator^=(b);\n\t}\n\n\n} // namespace eastl\n\n\nEA_RESTORE_VC_WARNING();\n\n#endif // Header include guard\n" }, { "path": "include/EASTL/bitvector.h", "content": "/////////////////////////////////////////////////////////////////////////////\n// Copyright (c) Electronic Arts Inc. All rights reserved.\n/////////////////////////////////////////////////////////////////////////////\n\n///////////////////////////////////////////////////////////////////////////////\n// Implements a bit vector, which is essentially a vector of bool but which\n// uses bits instead of bytes. It is thus similar to the original std::vector.\n///////////////////////////////////////////////////////////////////////////////\n\n///////////////////////////////////////////////////////////////////////////////\n// Note: This code is not yet complete: it isn't tested and doesn't yet \n// support containers other than vector.\n///////////////////////////////////////////////////////////////////////////////\n\n\n#ifndef EASTL_BITVECTOR_H\n#define EASTL_BITVECTOR_H\n\n\n#include \n#include \n#include \n#include \n#include \n#if EASTL_EXCEPTIONS_ENABLED\n#include \n#endif\n\nEA_DISABLE_VC_WARNING(4480); // nonstandard extension used: specifying underlying type for enum\n\n#if defined(EA_PRAGMA_ONCE_SUPPORTED)\n\t#pragma once // Some compilers (e.g. VC++) benefit significantly from using this. We've measured 3-4% build speed improvements in apps as a result.\n#endif\n\n\n\nnamespace eastl\n{\n\n\t/// EASTL_BITVECTOR_DEFAULT_NAME\n\t///\n\t/// Defines a default container name in the absence of a user-provided name.\n\t///\n\t#ifndef EASTL_BITVECTOR_DEFAULT_NAME\n\t\t#define EASTL_BITVECTOR_DEFAULT_NAME EASTL_DEFAULT_NAME_PREFIX \" bitvector\" // Unless the user overrides something, this is \"EASTL bitvector\".\n\t#endif\n\n\t/// EASTL_BITVECTOR_DEFAULT_ALLOCATOR\n\t///\n\t#ifndef EASTL_BITVECTOR_DEFAULT_ALLOCATOR\n\t\t#define EASTL_BITVECTOR_DEFAULT_ALLOCATOR allocator_type(EASTL_BITVECTOR_DEFAULT_NAME)\n\t#endif\n\n\n\n\t/// BitvectorWordType\n\t/// Defines the integral data type used by bitvector.\n\ttypedef EASTL_BITSET_WORD_TYPE_DEFAULT BitvectorWordType;\n\n\n\ttemplate \n\tclass bitvector_const_iterator;\n\n\n\ttemplate \n\tclass bitvector_reference\n\t{\n\tpublic:\n\t\ttypedef eastl_size_t size_type;\n\t\tbitvector_reference(Element* ptr, eastl_size_t i);\n\t\tbitvector_reference(const bitvector_reference& other);\n\n\t\tbitvector_reference& operator=(bool value);\n\t\tbitvector_reference& operator=(const bitvector_reference& rhs);\n\n\t\toperator bool() const // Defined here because some compilers fail otherwise.\n\t\t\t{ return (*mpBitWord & (Element(1) << mnBitIndex)) != 0; }\n\n\tprotected:\n\t\tfriend class bitvector_const_iterator;\n\n\t\tElement* mpBitWord;\n\t\tsize_type mnBitIndex;\n\n\t\tbitvector_reference() {}\n\t\tvoid CopyFrom(const bitvector_reference& rhs);\n\t};\n\n\n\n\ttemplate \n\tclass bitvector_const_iterator\n\t{\n\tpublic:\n\t\ttypedef eastl::random_access_iterator_tag iterator_category;\n\t\ttypedef bitvector_const_iterator this_type;\n\t\ttypedef bool value_type;\n\t\ttypedef bitvector_reference reference_type;\n\t\ttypedef ptrdiff_t difference_type;\n\t\ttypedef Element element_type;\n\t\ttypedef element_type* pointer; // This is wrong. It needs to be someting that acts as a pointer to a bit.\n\t\ttypedef element_type& reference; // This is not right. It needs to be someting that acts as a pointer to a bit.\n\t\ttypedef eastl_size_t size_type;\n\n\tprotected:\n\t\treference_type mReference;\n\n\t\tenum\n\t\t{\n\t\t\tkBitCount = (8 * sizeof(Element))\n\t\t};\n\n\tpublic:\n\t\tbool operator*() const;\n\t\tbool operator[](difference_type n) const;\n\n\t\tbitvector_const_iterator();\n\t\tbitvector_const_iterator(const element_type* p, eastl_size_t i);\n\t\tbitvector_const_iterator(const reference_type& referenceType);\n\t\tbitvector_const_iterator(const bitvector_const_iterator& other);\n\n\t\tbitvector_const_iterator& operator++();\n\t\tbitvector_const_iterator operator++(int);\n\t\tbitvector_const_iterator& operator--();\n\t\tbitvector_const_iterator operator--(int);\n\n\t\tbitvector_const_iterator& operator+=(difference_type dist);\n\t\tbitvector_const_iterator& operator-=(difference_type dist);\n\t\tbitvector_const_iterator operator+ (difference_type dist) const;\n\t\tbitvector_const_iterator operator- (difference_type dist) const;\n\n\t\tdifference_type operator-(const this_type& rhs) const;\n\n\t\tbitvector_const_iterator& operator= (const this_type& rhs);\n\n\t\tbool operator==(const this_type& rhs) const;\n\t\tbool operator!=(const this_type& rhs) const;\n\n\t\tbool operator< (const this_type& rhs) const;\n\t\tbool operator<=(const this_type& rhs) const;\n\t\tbool operator> (const this_type& rhs) const;\n\t\tbool operator>=(const this_type& rhs) const;\n\n\t\tint validate(const element_type* pStart, const element_type* pEnd, eastl_size_t nExtraBits) const;\n\n\tprotected:\n\t\ttemplate \n\t\tfriend class bitvector;\n\n\t\treference_type& get_reference_type() { return mReference; }\n\t};\n\n\n\n\ttemplate \n\tclass bitvector_iterator : public bitvector_const_iterator\n\t{\n\tpublic:\n\t\ttypedef eastl::random_access_iterator_tag iterator_category;\n\t\ttypedef bitvector_iterator this_type;\n\t\ttypedef bitvector_const_iterator base_type;\n\t\ttypedef bool value_type;\n\t\ttypedef bitvector_reference reference_type;\n\t\ttypedef ptrdiff_t difference_type;\n\t\ttypedef Element element_type;\n\t\ttypedef element_type* pointer; // This is wrong. It needs to be someting that acts as a pointer to a bit.\n\t\ttypedef element_type& reference; // This is not right. It needs to be someting that acts as a pointer to a bit.\n\n\tpublic:\n\t\treference_type operator*() const;\n\t\treference_type operator[](difference_type n) const;\n\n\t\tbitvector_iterator();\n\t\tbitvector_iterator(element_type* p, eastl_size_t i);\n\t\tbitvector_iterator(reference_type& referenceType);\n\n\t\tbitvector_iterator& operator++() { base_type::operator++(); return *this; }\n\t\tbitvector_iterator& operator--() { base_type::operator--(); return *this; }\n\t\tbitvector_iterator operator++(int);\n\t\tbitvector_iterator operator--(int);\n\n\t\tbitvector_iterator& operator+=(difference_type dist) { base_type::operator+=(dist); return *this; }\n\t\tbitvector_iterator& operator-=(difference_type dist) { base_type::operator-=(dist); return *this; }\n\t\tbitvector_iterator operator+ (difference_type dist) const;\n\t\tbitvector_iterator operator- (difference_type dist) const;\n\n\t\t// We need this here because we are overloading operator-, so for some reason the\n\t\t// other overload of the function can't be found unless it's explicitly specified.\n\t\tdifference_type operator-(const base_type& rhs) const { return base_type::operator-(rhs); }\n\t};\n\n\n\n\t/// bitvector\n\t///\n\t/// Implements an array of bits treated as boolean values.\n\t/// bitvector is similar to vector but uses bits instead of bytes and \n\t/// allows the user to use other containers such as deque instead of vector.\n\t/// bitvector is different from bitset in that bitset is less flexible but\n\t/// uses less memory and has higher performance.\n\t///\n\t/// To consider: Rename the Element template parameter to WordType, for \n\t/// consistency with bitset.\n\t///\n\ttemplate >\n\tclass bitvector\n\t{\n\tpublic:\n\t\ttypedef bitvector this_type;\n\t\ttypedef bool value_type;\n\t\ttypedef bitvector_reference reference;\n\t\ttypedef bool const_reference;\n\t\ttypedef bitvector_iterator iterator;\n\t\ttypedef bitvector_const_iterator const_iterator;\n\t\ttypedef eastl::reverse_iterator reverse_iterator;\n\t\ttypedef eastl::reverse_iterator const_reverse_iterator;\n\t\ttypedef Allocator allocator_type;\n\t\ttypedef Element element_type;\n\t\ttypedef Container container_type;\n\t\ttypedef eastl_size_t size_type;\n\t\ttypedef ptrdiff_t difference_type;\n\n\t\t#if defined(_MSC_VER) && (_MSC_VER >= 1400) && (_MSC_VER <= 1600) && !EASTL_STD_CPP_ONLY // _MSC_VER of 1400 means VS2005, 1600 means VS2010. VS2012 generates errors with usage of enum:size_type.\n\t\t\tenum : size_type { // Use Microsoft enum language extension, allowing for smaller debug symbols than using a static const. Users have been affected by this.\n\t\t\t\tnpos = container_type::npos,\n\t\t\t\tkMaxSize = container_type::kMaxSize\n\t\t\t};\n\t\t#else\n\t\t\tstatic const size_type npos = container_type::npos; /// 'npos' means non-valid position or simply non-position.\n\t\t\tstatic const size_type kMaxSize = container_type::kMaxSize; /// -1 is reserved for 'npos'. It also happens to be slightly beneficial that kMaxSize is a value less than -1, as it helps us deal with potential integer wraparound issues.\n\t\t#endif\n\n\t\tenum\n\t\t{\n\t\t\tkBitCount = 8 * sizeof(Element)\n\t\t};\n\n\tprotected:\n\t\tcontainer_type mContainer;\n\t\tsize_type mFreeBitCount; // Unused bits in the last word of mContainer.\n\n\tpublic:\n\t\tbitvector();\n\t\texplicit bitvector(const allocator_type& allocator);\n\t\texplicit bitvector(size_type n, const allocator_type& allocator = EASTL_BITVECTOR_DEFAULT_ALLOCATOR);\n\t\tbitvector(size_type n, value_type value, const allocator_type& allocator = EASTL_BITVECTOR_DEFAULT_ALLOCATOR);\n\n\t\ttemplate \n\t\tbitvector(InputIterator first, InputIterator last);\n\n\t\tvoid swap(this_type& x);\n\n\t\ttemplate \n\t\tvoid assign(InputIterator first, InputIterator last);\n\n\t\titerator begin() EA_NOEXCEPT;\n\t\tconst_iterator begin() const EA_NOEXCEPT;\n\t\tconst_iterator cbegin() const EA_NOEXCEPT;\n\n\t\titerator end() EA_NOEXCEPT;\n\t\tconst_iterator end() const EA_NOEXCEPT;\n\t\tconst_iterator cend() const EA_NOEXCEPT;\n\n\t\treverse_iterator rbegin() EA_NOEXCEPT;\n\t\tconst_reverse_iterator rbegin() const EA_NOEXCEPT;\n\t\tconst_reverse_iterator crbegin() const EA_NOEXCEPT;\n\n\t\treverse_iterator rend() EA_NOEXCEPT;\n\t\tconst_reverse_iterator rend() const EA_NOEXCEPT;\n\t\tconst_reverse_iterator crend() const EA_NOEXCEPT;\n\n\t\tbool empty() const EA_NOEXCEPT;\n\t\tsize_type size() const EA_NOEXCEPT;\n\t\tsize_type capacity() const EA_NOEXCEPT;\n\n\t\tvoid resize(size_type n, value_type value);\n\t\tvoid resize(size_type n);\n\t\tvoid reserve(size_type n);\n\t\tvoid set_capacity(size_type n = npos); // Revises the capacity to the user-specified value. Resizes the container to match the capacity if the requested capacity n is less than the current size. If n == npos then the capacity is reallocated (if necessary) such that capacity == size.\n\n\t\tvoid push_back();\n\t\tvoid push_back(value_type value);\n\t\tvoid pop_back();\n\n\t\treference front();\n\t\tconst_reference front() const;\n\t\treference back();\n\t\tconst_reference back() const;\n\n\t\tbool test(size_type n, bool defaultValue) const; // Returns true if the bit index is < size() and set. Returns defaultValue if the bit is >= size().\n\t\tvoid set(size_type n, bool value); // Resizes the container to accomodate n if necessary. \n\n\t\treference at(size_type n); // throws an out_of_range exception if n is invalid.\n\t\tconst_reference at(size_type n) const;\n\n\t\treference operator[](size_type n); // behavior is undefined if n is invalid.\n\t\tconst_reference operator[](size_type n) const;\n\n\t\t/*\n\t\tWork in progress:\n\t\ttemplate iterator find_first(); // Finds the lowest \"on\" bit.\n\t\ttemplate iterator find_next(const_iterator it); // Finds the next lowest \"on\" bit after it.\n\t\ttemplate iterator find_last(); // Finds the index of the last \"on\" bit, returns size if none are set.\n\t\ttemplate iterator find_prev(const_iterator it); // Finds the index of the last \"on\" bit before last_find, returns size if none are set.\n\n\t\ttemplate const_iterator find_first() const; // Finds the lowest \"on\" bit.\n\t\ttemplate const_iterator find_next(const_iterator it) const; // Finds the next lowest \"on\" bit after it.\n\t\ttemplate const_iterator find_last() const; // Finds the index of the last \"on\" bit, returns size if none are set.\n\t\ttemplate const_iterator find_prev(const_iterator it) const; // Finds the index of the last \"on\" bit before last_find, returns size if none are set.\n\t\t*/\n\n\t\telement_type* data() EA_NOEXCEPT;\n\t\tconst element_type* data() const EA_NOEXCEPT;\n\t\t\n\t\titerator insert(const_iterator position, value_type value);\n\t\tvoid insert(const_iterator position, size_type n, value_type value);\n\n\t\t// template Not yet implemented. See below for disabled definition.\n\t\t// void insert(const_iterator position, InputIterator first, InputIterator last);\n\n\t\titerator erase(const_iterator position);\n\t\titerator erase(const_iterator first, const_iterator last);\n\n\t\treverse_iterator erase(const_reverse_iterator position);\n\t\treverse_iterator erase(const_reverse_iterator first, const_reverse_iterator last);\n\n\t\tvoid clear();\n\t\tvoid reset_lose_memory(); // This is a unilateral reset to an initially empty state. No destructors are called, no deallocation occurs.\n\n\t\tcontainer_type& get_container();\n\t\tconst container_type& get_container() const;\n\n\t\tbool validate() const;\n\t\tint validate_iterator(const_iterator i) const;\n\n\t\tbool any() const;\n\t\tbool all() const;\n\t};\n\n\n\n\n\t///////////////////////////////////////////////////////////////////////\n\t// bitvector_reference\n\t///////////////////////////////////////////////////////////////////////\n\n\ttemplate \n\tbitvector_reference::bitvector_reference(Element* p, eastl_size_t i)\n\t : mpBitWord(p), \n\t\tmnBitIndex(i)\n\t{\n\t}\n\n\n\ttemplate \n\tbitvector_reference::bitvector_reference(const bitvector_reference& other)\n\t : mpBitWord(other.mpBitWord), \n\t\tmnBitIndex(other.mnBitIndex)\n\t{\n\t}\n\n\n\ttemplate \n\tbitvector_reference&\n\tbitvector_reference::operator=(bool value)\n\t{\n\t\tconst Element mask = (Element)(Element(1) << mnBitIndex);\n\n\t\tif(value)\n\t\t\t*mpBitWord |= mask;\n\t\telse\n\t\t\t*mpBitWord &= ~mask;\n\n\t\treturn *this;\n\t}\n\n\n\ttemplate \n\tbitvector_reference&\n\tbitvector_reference::operator=(const bitvector_reference& rhs)\n\t{\n\t\treturn (*this = (bool)rhs);\n\t}\n\n\n\ttemplate \n\tvoid bitvector_reference::CopyFrom(const bitvector_reference& rhs)\n\t{\n\t\tmpBitWord = rhs.mpBitWord;\n\t\tmnBitIndex = rhs.mnBitIndex;\n\t}\n\n\n\n\n\t///////////////////////////////////////////////////////////////////////\n\t// bitvector_const_iterator\n\t///////////////////////////////////////////////////////////////////////\n\n\ttemplate \n\tbitvector_const_iterator::bitvector_const_iterator()\n\t\t: mReference(0, 0)\n\t{\n\t}\n\n\n\ttemplate \n\tbitvector_const_iterator::bitvector_const_iterator(const Element* p, eastl_size_t i)\n\t\t: mReference(const_cast(p), i) // const_cast is safe here because we never let mReference leak and we don't modify it.\n\t{\n\t}\n\n\n\ttemplate \n\tbitvector_const_iterator::bitvector_const_iterator(const reference_type& reference)\n\t\t: mReference(reference)\n\t{\n\t}\n\n\n\ttemplate \n\tbitvector_const_iterator::bitvector_const_iterator(const bitvector_const_iterator& other)\n\t\t: mReference(other.mReference)\n\t{\n\t}\n\n\n\ttemplate \n\tbitvector_const_iterator&\n\tbitvector_const_iterator::operator++()\n\t{\n\t\t++mReference.mnBitIndex;\n\n\t\tif(mReference.mnBitIndex == kBitCount)\n\t\t{\n\t\t\t++mReference.mpBitWord;\n\t\t\tmReference.mnBitIndex = 0;\n\t\t}\n\n\t\treturn *this;\n\t}\n\n\n\ttemplate \n\tbitvector_const_iterator&\n\tbitvector_const_iterator::operator--()\n\t{\n\t\tif(mReference.mnBitIndex == 0)\n\t\t{\n\t\t\t--mReference.mpBitWord;\n\t\t\tmReference.mnBitIndex = kBitCount;\n\t\t}\n\n\t\t--mReference.mnBitIndex;\n\t\treturn *this;\n\t}\n\n\n\ttemplate \n\tbitvector_const_iterator\n\tbitvector_const_iterator::operator++(int)\n\t{\n\t\tbitvector_const_iterator copy(*this);\n\t\t++*this;\n\t\treturn copy;\n\t}\n\n\n\ttemplate \n\tbitvector_const_iterator\n\tbitvector_const_iterator::operator--(int)\n\t{\n\t\tbitvector_const_iterator copy(*this);\n\t\t--*this;\n\t\treturn copy;\n\t}\n\n\n\ttemplate \n\tbitvector_const_iterator&\n\tbitvector_const_iterator::operator+=(difference_type n)\n\t{\n\t\tn += mReference.mnBitIndex;\n\n\t\tif(n >= difference_type(0))\n\t\t{\n\t\t\tmReference.mpBitWord += n / kBitCount;\n\t\t\tmReference.mnBitIndex = (size_type)(n % kBitCount);\n\t\t}\n\t\telse\n\t\t{\n\t\t\t// backwards is tricky\n\t\t\t// figure out how many full words backwards we need to move\n\t\t\t// n = [-1..-32] => 1\n\t\t\t// n = [-33..-64] => 2\n\t\t\tconst size_type backwards = (size_type)(-n + kBitCount - 1);\n\t\t\tmReference.mpBitWord -= backwards / kBitCount;\n\n\t\t\t// -1 => 31; backwards = 32; 31 - (backwards % 32) = 31\n\t\t\t// -2 => 30; backwards = 33; 31 - (backwards % 32) = 30\n\t\t\t// -3 => 29; backwards = 34\n\t\t\t// ..\n\t\t\t// -32 => 0; backwards = 63; 31 - (backwards % 32) = 0\n\t\t\t// -33 => 31; backwards = 64; 31 - (backwards % 32) = 31\n\t\t\tmReference.mnBitIndex = (kBitCount - 1) - (backwards % kBitCount);\n\t\t}\n\n\t\treturn *this;\n\t}\n\n\n\ttemplate \n\tbitvector_const_iterator&\n\tbitvector_const_iterator::operator-=(difference_type n)\n\t{\n\t\treturn (*this += -n);\n\t}\n\n\n\ttemplate \n\tbitvector_const_iterator\n\tbitvector_const_iterator::operator+(difference_type n) const\n\t{\n\t\tbitvector_const_iterator copy(*this);\n\t\tcopy += n;\n\t\treturn copy;\n\t}\n\n\t\n\ttemplate \n\tbitvector_const_iterator\n\tbitvector_const_iterator::operator-(difference_type n) const\n\t{\n\t\tbitvector_const_iterator copy(*this);\n\t\tcopy -= n;\n\t\treturn copy;\n\t}\n\n\n\ttemplate \n\ttypename bitvector_const_iterator::difference_type\n\tbitvector_const_iterator::operator-(const this_type& rhs) const\n\t{\n\t\treturn ((mReference.mpBitWord - rhs.mReference.mpBitWord) * kBitCount) + mReference.mnBitIndex - rhs.mReference.mnBitIndex;\n\t}\n\n\n\ttemplate \n\tbool bitvector_const_iterator::operator==(const this_type& rhs) const\n\t{\n\t\treturn (mReference.mpBitWord == rhs.mReference.mpBitWord) && (mReference.mnBitIndex == rhs.mReference.mnBitIndex);\n\t}\n\n\n\ttemplate \n\tbool bitvector_const_iterator::operator!=(const this_type& rhs) const\n\t{\n\t\treturn !(*this == rhs);\n\t}\n\n\n\ttemplate \n\tbool bitvector_const_iterator::operator<(const this_type& rhs) const\n\t{\n\t\treturn (mReference.mpBitWord < rhs.mReference.mpBitWord) || \n\t\t\t ((mReference.mpBitWord == rhs.mReference.mpBitWord) && (mReference.mnBitIndex < rhs.mReference.mnBitIndex));\n\t}\n\n\n\ttemplate \n\tbool bitvector_const_iterator::operator<=(const this_type& rhs) const\n\t{\n\t\treturn (mReference.mpBitWord < rhs.mReference.mpBitWord) || \n\t\t\t ((mReference.mpBitWord == rhs.mReference.mpBitWord) && (mReference.mnBitIndex <= rhs.mReference.mnBitIndex));\n\t}\n\n\n\ttemplate \n\tbool bitvector_const_iterator::operator>(const this_type& rhs) const\n\t{\n\t\treturn !(*this <= rhs);\n\t}\n\n\n\ttemplate \n\tbool bitvector_const_iterator::operator>=(const this_type& rhs) const\n\t{\n\t\treturn !(*this < rhs);\n\t}\n\n\n\ttemplate \n\tbool bitvector_const_iterator::operator*() const\n\t{\n\t\treturn mReference;\n\t}\n\n\n\ttemplate \n\tbool bitvector_const_iterator::operator[](difference_type n) const\n\t{\n\t\treturn *(*this + n);\n\t}\n\n\n\ttemplate \n\tbitvector_const_iterator& bitvector_const_iterator::operator= (const this_type& rhs)\n\t{\n\t\tmReference.CopyFrom(rhs.mReference);\n\t\treturn *this;\n\t}\n\n\n\ttemplate \n\tint bitvector_const_iterator::validate(const Element* pStart, const Element* pEnd, eastl_size_t nExtraBits) const\n\t{\n\t\tconst Element* const pCurrent = mReference.mpBitWord;\n\n\t\tif(pCurrent >= pStart)\n\t\t{\n\t\t\tif(nExtraBits == 0)\n\t\t\t{\n\t\t\t\tif(pCurrent == pEnd && mReference)\n\t\t\t\t\treturn eastl::isf_valid | eastl::isf_current;\n\t\t\t\telse if(pCurrent < pEnd)\n\t\t\t\t\treturn eastl::isf_valid | eastl::isf_current | eastl::isf_can_dereference;\n\t\t\t}\n\t\t\telse if(pCurrent == (pEnd - 1))\n\t\t\t{\n\t\t\t\tconst size_type bit = mReference.mnBitIndex;\n\t\t\t\tconst size_type lastbit = kBitCount - nExtraBits;\n\t\t\t\t\n\t\t\t\tif(bit == lastbit)\n\t\t\t\t\treturn eastl::isf_valid | eastl::isf_current;\n\t\t\t\telse if(bit < lastbit)\n\t\t\t\t\treturn eastl::isf_valid | eastl::isf_current | eastl::isf_can_dereference;\n\t\t\t}\n\t\t\telse if(pCurrent < pEnd)\n\t\t\t{\n\t\t\t\treturn eastl::isf_valid | eastl::isf_current | eastl::isf_can_dereference;\n\t\t\t}\n\t\t}\n\n\t\treturn eastl::isf_none;\n\t}\n\n\n\n\t///////////////////////////////////////////////////////////////////////\n\t// bitvector_iterator\n\t///////////////////////////////////////////////////////////////////////\n\n\ttemplate \n\tbitvector_iterator::bitvector_iterator()\n\t\t: base_type()\n\t{\n\t}\n\n\ttemplate \n\tbitvector_iterator::bitvector_iterator(Element* p, eastl_size_t i)\n\t\t: base_type(p, i)\n\t{\n\t}\n\n\n\ttemplate \n\tbitvector_iterator::bitvector_iterator(reference_type& reference)\n\t\t: base_type(reference)\n\t{\n\t}\n\n\n\ttemplate \n\ttypename bitvector_iterator::reference_type\n\tbitvector_iterator::operator*() const\n\t{\n\t\treturn base_type::mReference;\n\t}\n\n\n\ttemplate \n\ttypename bitvector_iterator::reference_type\n\tbitvector_iterator::operator[](difference_type n) const\n\t{\n\t\treturn *(*this + n);\n\t}\n\n\n\ttemplate \n\tvoid MoveBits(bitvector_iterator start, \n\t\t\t\t bitvector_iterator end, \n\t\t\t\t bitvector_iterator dest)\n\t{\n\t\t// Slow implemenation; could optimize by moving a word at a time.\n\t\tif(dest <= start)\n\t\t{\n\t\t\twhile(start != end)\n\t\t\t{\n\t\t\t\t*dest = *start;\n\t\t\t\t++dest;\n\t\t\t\t++start;\n\t\t\t}\n\t\t}\n\t\telse\n\t\t{\n\t\t\t// Need to move backwards\n\t\t\tdest += (end - start);\n\n\t\t\twhile(start != end)\n\t\t\t{\n\t\t\t\t--dest;\n\t\t\t\t--end;\n\t\t\t\t*dest = *end;\n\t\t\t}\n\t\t}\n\t}\n\n\n\ttemplate \n\tbitvector_iterator\n\tbitvector_iterator::operator++(int)\n\t{\n\t\tbitvector_iterator copy(*this);\n\t\t++*this;\n\t\treturn copy;\n\t}\n\n\n\ttemplate \n\tbitvector_iterator\n\tbitvector_iterator::operator--(int)\n\t{\n\t\tbitvector_iterator copy(*this);\n\t\t--*this;\n\t\treturn copy;\n\t}\n\n\n\ttemplate \n\tbitvector_iterator\n\tbitvector_iterator::operator+(difference_type n) const\n\t{\n\t\tbitvector_iterator copy(*this);\n\t\tcopy += n;\n\t\treturn copy;\n\t}\n\n\t\n\ttemplate \n\tbitvector_iterator\n\tbitvector_iterator::operator-(difference_type n) const\n\t{\n\t\tbitvector_iterator copy(*this);\n\t\tcopy -= n;\n\t\treturn copy;\n\t}\n\n\n\n\n\t///////////////////////////////////////////////////////////////////////\n\t// bitvector\n\t///////////////////////////////////////////////////////////////////////\n\n\ttemplate \n\ttemplate \n\tvoid bitvector::assign(InputIterator first, InputIterator last)\n\t{\n\t\t// To consider: We can maybe specialize this on bitvector_iterator to do a fast bitwise copy.\n\t\t// We can also specialize for random access iterators to figure out the size & reserve first.\n\n\t\tclear();\n\n\t\twhile(first != last)\n\t\t{\n\t\t\tpush_back(*first);\n\t\t\t++first;\n\t\t}\n\t}\n\n\n\ttemplate \n\ttypename bitvector::iterator\n\tbitvector::begin() EA_NOEXCEPT\n\t{\n\t\treturn iterator(mContainer.begin(), 0);\n\t}\n\n\n\ttemplate \n\ttypename bitvector::const_iterator\n\tbitvector::begin() const EA_NOEXCEPT\n\t{\n\t\treturn const_iterator(mContainer.begin(), 0);\n\t}\n\n\n\ttemplate \n\ttypename bitvector::const_iterator\n\tbitvector::cbegin() const EA_NOEXCEPT\n\t{\n\t\treturn const_iterator(mContainer.begin(), 0);\n\t}\n\n\n\ttemplate \n\ttypename bitvector::iterator\n\tbitvector::end() EA_NOEXCEPT\n\t{\n\t\treturn iterator(mContainer.end(), 0) - mFreeBitCount;\n\t}\n\n\n\ttemplate \n\ttypename bitvector::const_iterator\n\tbitvector::end() const EA_NOEXCEPT\n\t{\n\t\treturn const_iterator(mContainer.end(), 0) - mFreeBitCount;\n\t}\n\n\n\ttemplate \n\ttypename bitvector::const_iterator\n\tbitvector::cend() const EA_NOEXCEPT\n\t{\n\t\treturn const_iterator(mContainer.end(), 0) - mFreeBitCount;\n\t}\n\n\n\ttemplate \n\tbool bitvector::empty() const EA_NOEXCEPT\n\t{\n\t\treturn mContainer.empty();\n\t}\n\n\n\ttemplate \n\ttypename bitvector::size_type\n\tbitvector::size() const EA_NOEXCEPT\n\t{\n\t\treturn (mContainer.size() * kBitCount) - mFreeBitCount;\n\t}\n\n\n\ttemplate \n\ttypename bitvector::size_type\n\tbitvector::capacity() const EA_NOEXCEPT\n\t{\n\t\treturn mContainer.capacity() * kBitCount;\n\t}\n\n\n\ttemplate \n\tvoid bitvector::set_capacity(size_type n)\n\t{\n\t\tif(n == npos)\n\t\t\tmContainer.set_capacity(npos);\n\t\telse\n\t\t\tmContainer.set_capacity((n + kBitCount - 1) / kBitCount);\n\t}\n\n\n\ttemplate \n\ttypename bitvector::reverse_iterator\n\tbitvector::rbegin() EA_NOEXCEPT\n\t{\n\t\treturn reverse_iterator(end());\n\t}\n\n\n\ttemplate \n\ttypename bitvector::const_reverse_iterator\n\tbitvector::rbegin() const EA_NOEXCEPT\n\t{\n\t\treturn const_reverse_iterator(end());\n\t}\n\n\n\ttemplate \n\ttypename bitvector::const_reverse_iterator\n\tbitvector::crbegin() const EA_NOEXCEPT\n\t{\n\t\treturn const_reverse_iterator(end());\n\t}\n\n\n\ttemplate \n\ttypename bitvector::reverse_iterator\n\tbitvector::rend() EA_NOEXCEPT\n\t{\n\t\treturn reverse_iterator(begin());\n\t}\n\n\n\ttemplate \n\ttypename bitvector::const_reverse_iterator\n\tbitvector::rend() const EA_NOEXCEPT\n\t{\n\t\treturn const_reverse_iterator(begin());\n\t}\n\n\n\ttemplate \n\ttypename bitvector::const_reverse_iterator\n\tbitvector::crend() const EA_NOEXCEPT\n\t{\n\t\treturn const_reverse_iterator(begin());\n\t}\n\n\n\ttemplate \n\ttypename bitvector::reference\n\tbitvector::front()\n\t{\n\t\tEASTL_ASSERT(!empty());\n\t\treturn reference(&mContainer[0], 0);\n\t}\n\n\n\ttemplate \n\ttypename bitvector::const_reference\n\tbitvector::front() const\n\t{\n\t\tEASTL_ASSERT(!empty());\n\n\t\t// To consider: make a better solution to this than const_cast.\n\t\treturn reference(const_cast(&mContainer[0]), 0);\n\t}\n\n\n\ttemplate \n\ttypename bitvector::reference\n\tbitvector::back()\n\t{\n\t\tEASTL_ASSERT(!empty());\n\t\treturn *(--end());\n\t}\n\n\n\ttemplate \n\ttypename bitvector::const_reference\n\tbitvector::back() const\n\t{\n\t\tEASTL_ASSERT(!empty());\n\t\treturn *(--end());\n\t}\n\n\n\ttemplate \n\tvoid bitvector::push_back()\n\t{\n\t\tif(!mFreeBitCount)\n\t\t{\n\t\t\tmContainer.push_back();\n\t\t\tmFreeBitCount = kBitCount;\n\t\t}\n\n\t\t--mFreeBitCount;\n\t}\n\n\n\ttemplate \n\tvoid bitvector::push_back(value_type value)\n\t{\n\t\tpush_back();\n\t\t*--end() = value;\n\t}\n\t\n\n\ttemplate \n\tvoid bitvector::pop_back()\n\t{\n\t\tEASTL_ASSERT(!empty());\n\n\t\tif(++mFreeBitCount == kBitCount)\n\t\t{\n\t\t\tmContainer.pop_back();\n\t\t\tmFreeBitCount = 0;\n\t\t}\n\t}\n\n\n\ttemplate \n\tvoid bitvector::reserve(size_type n)\n\t{\n\t\tconst size_type wordCount = (n + kBitCount - 1) / kBitCount;\n\t\tmContainer.reserve(wordCount);\n\t}\n\n\n\ttemplate \n\tvoid bitvector::resize(size_type n)\n\t{\n\t\tconst size_type wordCount = (n + kBitCount - 1) / kBitCount;\n\t\tconst size_type extra = (wordCount * kBitCount) - n;\n\n\t\tmContainer.resize(wordCount);\n\t\tmFreeBitCount = extra;\n\t}\n\n\n\ttemplate \n\tvoid bitvector::resize(size_type n, value_type value)\n\t{\n\t\tconst size_type s = size();\n\t\tif(n < s)\n\t\t\tresize(n);\n\n\t\t// Fill up to the end of a word\n\t\tsize_type newbits = n - s;\n\n\t\twhile(mFreeBitCount && newbits)\n\t\t{\n\t\t\tpush_back(value);\n\t\t\t--newbits;\n\t\t}\n\n\t\t// Fill the rest a word at a time\n\t\tif(newbits)\n\t\t{\n\t\t\telement_type element(0);\n\t\t\tif(value)\n\t\t\t\telement = ~element;\n\n\t\t\tconst size_type words = (n + kBitCount - 1) / kBitCount;\n\t\t\tconst size_type extra = words * kBitCount - n;\n\t\t\tmContainer.resize(words, element);\n\t\t\tmFreeBitCount = extra;\n\t\t}\n\t}\n\n\n\ttemplate \n\tbool bitvector::test(size_type n, bool defaultValue) const\n\t{\n\t\tif(n < size())\n\t\t\treturn *(begin() + (difference_type)n);\n\n\t\treturn defaultValue;\n\t}\n\n\n\ttemplate \n\tvoid bitvector::set(size_type n, bool value)\n\t{\n\t\tif(EASTL_UNLIKELY(n >= size()))\n\t\t\tresize(n + 1);\n\n\t\t*(begin() + (difference_type)n) = value;\n\t}\n\n\n\ttemplate \n\ttypename bitvector::reference\n\tbitvector::at(size_type n)\n\t{\n\t\t// The difference between at and operator[] is that at signals \n\t\t// if the requested position is out of range by throwing an \n\t\t// out_of_range exception.\n\n\t\t#if EASTL_EXCEPTIONS_ENABLED\n\t\t\tif(EASTL_UNLIKELY(n >= size()))\n\t\t\t\tthrow std::out_of_range(\"bitvector::at -- out of range\");\n\t\t#elif EASTL_ASSERT_ENABLED\n\t\t\tif(EASTL_UNLIKELY(n >= size()))\n\t\t\t\tEASTL_FAIL_MSG(\"bitvector::at -- out of range\");\n\t\t#endif\n\t\t\n\t\treturn *(begin() + (difference_type)n);\n\t}\n\n\n\ttemplate \n\ttypename bitvector::const_reference\n\tbitvector::at(size_type n) const\n\t{\n\t\t#if EASTL_EXCEPTIONS_ENABLED\n\t\t\tif(EASTL_UNLIKELY(n >= size()))\n\t\t\t\tthrow std::out_of_range(\"bitvector::at -- out of range\");\n\t\t#elif EASTL_ASSERT_ENABLED\n\t\t\tif(EASTL_UNLIKELY(n >= size()))\n\t\t\t\tEASTL_FAIL_MSG(\"bitvector::at -- out of range\");\n\t\t#endif\n\t\t\n\t\treturn *(begin() + (difference_type)n);\n\t}\n\n\n\ttemplate \n\ttypename bitvector::reference\n\tbitvector::operator[](size_type n)\n\t{\n\t\treturn *(begin() + (difference_type)n);\n\t}\n\n\n\ttemplate \n\ttypename bitvector::const_reference\n\tbitvector::operator[](size_type n) const\n\t{\n\t\treturn *(begin() + (difference_type)n);\n\t}\n\n\n/*\n\ttemplate \n\ttemplate \n\ttypename bitvector::iterator \n\tbitvector::find_first()\n\t{\n\t\treturn begin();\n\t}\n\n\ttemplate iterator find_next(const_iterator it);\n\ttemplate iterator find_last();\n\ttemplate iterator find_prev(const_iterator it);\n\t\t\t\t\t\t\n\ttemplate const_iterator find_first() const;\n\ttemplate const_iterator find_next(const_iterator it) const;\n\ttemplate const_iterator find_last() const;\n\ttemplate const_iterator find_prev(const_iterator it) const;\n*/\n\n\n\n\n\ttemplate \n\tinline typename bitvector::container_type&\n\tbitvector::get_container()\n\t{\n\t\treturn mContainer;\n\t}\n\n\n\ttemplate \n\tinline const typename bitvector::container_type&\n\tbitvector::get_container() const\n\t{\n\t\treturn mContainer;\n\t}\n\n\n\ttemplate \n\tbool bitvector::validate() const\n\t{\n\t\tif(!mContainer.validate())\n\t\t\treturn false;\n\n\t\tif((unsigned)mFreeBitCount >= kBitCount)\n\t\t\treturn false;\n\n\t\treturn true;\n\t}\n\n\n\ttemplate \n\tint bitvector::validate_iterator(const_iterator i) const\n\t{\n\t\treturn i.validate(mContainer.begin(), mContainer.end(), mFreeBitCount);\n\t}\n\n\n\ttemplate \n\ttypename bitvector::element_type*\n\tbitvector::data() EA_NOEXCEPT\n\t{\n\t\treturn mContainer.data();\n\t}\n\t\n\n\ttemplate \n\tconst typename bitvector::element_type*\n\tbitvector::data() const EA_NOEXCEPT\n\t{\n\t\treturn mContainer.data();\n\t}\n\n\n\ttemplate \n\ttypename bitvector::iterator\n\tbitvector::insert(const_iterator position, value_type value)\n\t{\n\t\titerator iPosition(position.get_reference_type()); // This is just a non-const version of position.\n\n\t\t#if EASTL_ASSERT_ENABLED\n\t\t\tif(EASTL_UNLIKELY(validate_iterator(iPosition) & eastl::isf_valid) == 0)\n\t\t\t\tEASTL_FAIL_MSG(\"bitvector::insert -- invalid iterator\");\n\t\t#endif\n\n\t\t// Save because we might reallocate\n\t\tconst typename iterator::difference_type n = iPosition - begin();\n\t\tpush_back();\n\t\tiPosition = begin() + n;\n\n\t\tMoveBits(iPosition, --end(), ++iterator(iPosition));\n\t\t*iPosition = value;\n\n\t\treturn iPosition;\n\t}\n\n\n\ttemplate \n\tvoid bitvector::insert(const_iterator position, size_type n, value_type value)\n\t{\n\t\titerator iPosition(position.get_reference_type()); // This is just a non-const version of position.\n\n\t\t#if EASTL_ASSERT_ENABLED\n\t\t\tif(EASTL_UNLIKELY(validate_iterator(iPosition) & eastl::isf_valid) == 0)\n\t\t\t\tEASTL_FAIL_MSG(\"bitvector::insert -- invalid iterator\");\n\t\t#endif\n\n\t\t// Save because we might reallocate.\n\t\tconst typename iterator::difference_type p = iPosition - begin();\n\t\tresize(size() + n);\n\t\tiPosition = begin() + p;\n\n\t\titerator insert_end = iPosition + n;\n\t\tMoveBits(iPosition, end() - n, insert_end);\n\n\t\t// To do: Optimize this to word-at-a-time for large inserts\n\t\twhile(iPosition != insert_end)\n\t\t{\n\t\t\t*iPosition = value;\n\t\t\t++iPosition;\n\t\t}\n\t}\n\n\n\t/*\n\tThe following is a placeholder for a future implementation. It turns out that a correct implementation of \n\tinsert(pos, first, last) is a non-trivial exercise that would take a few hours to implement and test. \n\tThe reasons why involve primarily the problem of handling the case where insertion source comes from \n\twithin the container itself, and the case that first and last (note they are templated) might not refer \n\tto iterators might refer to a value/count pair. The C++ Standard requires you to handle this case and \n\tI (Paul Pedriana) believe that it applies even for a bitvector, given that bool is an integral type. \n\tSo you have to set up a compile-time type traits function chooser. See vector, for example.\n\n\ttemplate \n\ttemplate \n\tvoid bitvector::insert(const_iterator position, InputIterator first, InputIterator last)\n\t{\n\t\titerator iPosition(position.get_reference_type()); // This is just a non-const version of position.\n\n\t\t// This implementation is probably broken due to not handling insertion into self.\n\t\t// To do: Make a more efficient version of this.\n\t\tdifference_type distance = (iPosition - begin());\n\n\t\twhile(first != last)\n\t\t{\n\t\t\tinsert(iPosition, *first);\n\t\t\tiPosition = begin() + ++distance;\n\t\t\t++first;\n\t\t}\n\t}\n\t*/\n\n\n\ttemplate \n\ttypename bitvector::iterator\n\tbitvector::erase(const_iterator position)\n\t{\n\t\titerator iPosition(position.get_reference_type()); // This is just a non-const version of position.\n\n\t\t#if EASTL_ASSERT_ENABLED\n\t\t\tif(EASTL_UNLIKELY(validate_iterator(iPosition) & eastl::isf_can_dereference) == 0)\n\t\t\t\tEASTL_FAIL_MSG(\"bitvector::erase -- invalid iterator\");\n\t\t#endif\n\n\t\tMoveBits(++iterator(iPosition), end(), iPosition);\n\t\tresize(size() - 1);\n\n\t\t// Verify that no reallocation occurred.\n\t\tEASTL_ASSERT(validate_iterator(iPosition) & eastl::isf_valid);\n\t\treturn iPosition;\n\t}\n\n\n\ttemplate \n\ttypename bitvector::iterator\n\tbitvector::erase(const_iterator first, const_iterator last)\n\t{\n\t\titerator iFirst(first.get_reference_type()); // This is just a non-const version of first.\n\t\titerator iLast(last.get_reference_type()); // This is just a non-const version of last.\n\n\t\t#if EASTL_ASSERT_ENABLED\n\t\t\tif(EASTL_UNLIKELY(validate_iterator(iLast) & eastl::isf_valid) == 0)\n\t\t\t\tEASTL_FAIL_MSG(\"bitvector::erase -- invalid iterator\");\n\t\t#endif\n\n\t\tif(!(iFirst == iLast))\n\t\t{\n\t\t\t#if EASTL_ASSERT_ENABLED\n\t\t\t\tif(EASTL_UNLIKELY(validate_iterator(iFirst) & eastl::isf_can_dereference) == 0)\n\t\t\t\t\tEASTL_FAIL_MSG(\"bitvector::erase -- invalid iterator\");\n\t\t\t#endif\n\n\t\t\tconst size_type eraseCount = (size_type)(iLast - iFirst);\n\t\t\tMoveBits(iLast, end(), iFirst);\n\t\t\tresize(size() - eraseCount);\n\n\t\t\t// Verify that no reallocation occurred.\n\t\t\t#if EASTL_ASSERT_ENABLED\n\t\t\t\tif(EASTL_UNLIKELY(validate_iterator(iFirst) & eastl::isf_valid) == 0)\n\t\t\t\t\tEASTL_FAIL_MSG(\"bitvector::erase -- invalid iterator\");\n\t\t\t#endif\n\t\t}\n\n\t\treturn iFirst;\n\t}\n\n\n\ttemplate \n\ttypename bitvector::reverse_iterator\n\tbitvector::erase(const_reverse_iterator position)\n\t{\n\t\treturn reverse_iterator(erase((++position).base()));\n\t}\n\n\n\ttemplate \n\ttypename bitvector::reverse_iterator\n\tbitvector::erase(const_reverse_iterator first, const_reverse_iterator last)\n\t{\n\t\t// Version which erases in order from first to last.\n\t\t// difference_type i(first.base() - last.base());\n\t\t// while(i--)\n\t\t// first = erase(first);\n\t\t// return first;\n\n\t\t// Version which erases in order from last to first, but is slightly more efficient:\n\t\treturn reverse_iterator(erase(last.base(), first.base()));\n\t}\n\n\n\ttemplate \n\tvoid bitvector::swap(this_type& rhs)\n\t{\n\t\tmContainer.swap(rhs.mContainer);\n\t\teastl::swap(mFreeBitCount, rhs.mFreeBitCount);\n\t}\n\n\n\ttemplate \n\tvoid bitvector::reset_lose_memory()\n\t{\n\t\tmContainer.reset_lose_memory(); // intentional memory leak.\n\t\tmFreeBitCount = 0;\n\t}\n\n\n\ttemplate \n\tvoid bitvector::clear()\n\t{\n\t\tmContainer.clear();\n\t\tmFreeBitCount = 0;\n\t}\n\n\n\ttemplate \n\tbitvector::bitvector()\n\t : mContainer(), \n\t\tmFreeBitCount(0)\n\t{\n\t}\n\n\n\ttemplate \n\tbitvector::bitvector(const allocator_type& allocator)\n\t : mContainer(allocator), \n\t\tmFreeBitCount(0)\n\t{\n\t}\n\n\n\ttemplate \n\tbitvector::bitvector(size_type n, const allocator_type& allocator)\n\t : mContainer((n + kBitCount - 1) / kBitCount, allocator)\n\t{\n\t\tmFreeBitCount = kBitCount - (n % kBitCount);\n\n\t\tif(mFreeBitCount == kBitCount)\n\t\t\tmFreeBitCount = 0;\n\t}\n\n\n\ttemplate \n\tbitvector::bitvector(size_type n, value_type value, const allocator_type& allocator)\n\t : mContainer((n + kBitCount - 1) / kBitCount, value ? ~element_type(0) : element_type(0), allocator)\n\t{\n\t\tmFreeBitCount = kBitCount - (n % kBitCount);\n\n\t\tif(mFreeBitCount == kBitCount)\n\t\t\tmFreeBitCount = 0;\n\t}\n\n\n\ttemplate \n\ttemplate \n\tbitvector::bitvector(InputIterator first, InputIterator last)\n\t : mContainer(), \n\t\tmFreeBitCount(0)\n\t{\n\t\tassign(first, last);\n\t}\n\n\ttemplate \n\tbool bitvector::any() const\n\t{\n\t\tif (mContainer.size() == 0) \n\t\t\treturn false;\n\n\t\tfor (eastl_size_t i = 0, count = mContainer.size() - 1; i < count; ++i)\n\t\t{\n\t\t\tif (mContainer[i] != 0)\n\t\t\t\treturn true;\n\t\t}\n\t\tElement mask = mFreeBitCount == 0 ? (Element)-1 : ((Element(1) << Element(kBitCount - mFreeBitCount)) - 1);\n\t\treturn (mContainer.back() & mask);\n\t}\n\n\ttemplate \n\tbool bitvector::all() const\n\t{\n\t\tif (mContainer.size() == 0) \n\t\t\treturn true;\n\n\t\tfor (eastl_size_t i = 0, count = mContainer.size() - 1; i < count; ++i)\n\t\t{\n\t\t\tif (mContainer[i] != (~(Element)0))\n\t\t\t{\n\t\t\t\treturn false;\n\t\t\t}\n\t\t}\n\n\t\tElement mask = mFreeBitCount == 0 ? (Element)-1 : ((Element(1) << Element(kBitCount - mFreeBitCount)) - 1);\n\t\treturn (mContainer.back() & mask) == mask;\n\t}\n\n\n\t///////////////////////////////////////////////////////////////////////\n\t// global operators\n\t///////////////////////////////////////////////////////////////////////\n\n\ttemplate \n\tinline bool operator==(const bitvector& a, \n\t\t\t\t\t\t const bitvector& b)\n\t{\n\t\t// To do: Replace this with a smart compare implementation. This is much slower than it needs to be.\n\t\treturn ((a.size() == b.size()) && eastl::equal(a.begin(), a.end(), b.begin()));\n\t}\n\n\n\ttemplate \n\tinline bool operator!=(const bitvector& a, \n\t\t\t\t\t\t const bitvector& b)\n\t{\n\t\treturn !operator==(a, b);\n\t}\n\n\n\ttemplate \n\tinline bool operator<(const bitvector& a, \n\t\t\t\t\t\t const bitvector& b)\n\t{\n\t\t// To do: Replace this with a smart compare implementation. This is much slower than it needs to be.\n\t\treturn eastl::lexicographical_compare(a.begin(), a.end(), b.begin(), b.end());\n\t}\n\n\n\ttemplate \n\tinline bool operator>(const bitvector& a, \n\t\t\t\t\t\t const bitvector& b)\n\t{\n\t\treturn b < a;\n\t}\n\n\n\ttemplate \n\tinline bool operator<=(const bitvector& a, \n\t\t\t\t\t\t const bitvector& b)\n\t{\n\t\treturn !(b < a);\n\t}\n\n\n\ttemplate \n\tinline bool operator>=(const bitvector& a, \n\t\t\t\t\t\t const bitvector& b)\n\t{\n\t\treturn !(a < b);\n\t}\n\n\ttemplate \n\tinline void swap(bitvector& a,\n\t\t\t\t\t bitvector& b)\n\t{\n\t\ta.swap(b);\n\t}\n\n\ttemplate >\n\tusing fixed_bitvector = eastl::bitvector;\n\n} // namespace eastl\n\n\nEA_RESTORE_VC_WARNING();\n\n#endif // Header include guard\n" }, { "path": "include/EASTL/bonus/adaptors.h", "content": "/////////////////////////////////////////////////////////////////////////////\n// Copyright (c) Electronic Arts Inc. All rights reserved.\n/////////////////////////////////////////////////////////////////////////////\n\n///////////////////////////////////////////////////////////////////////////////\n///////////////////////////////////////////////////////////////////////////////\n\n\n#ifndef EASTL_ADAPTORS_H\n#define EASTL_ADAPTORS_H\n\n\n#include \n#include \n#include \n#include \n\n#if defined(EA_PRAGMA_ONCE_SUPPORTED)\n\t#pragma once // Some compilers (e.g. VC++) benefit significantly from using this. We've measured 3-4% build speed improvements in apps as a result.\n#endif\n\nEA_DISABLE_VC_WARNING(4512 4626)\n#if defined(_MSC_VER) && (_MSC_VER >= 1900) // VS2015+\n\tEA_DISABLE_VC_WARNING(5027) // move assignment operator was implicitly defined as deleted\n#endif\n\n\nnamespace eastl\n{\n\t/// reverse\n\t///\n\t/// This adaptor allows reverse iteration of a container in ranged base for-loops.\n\t///\n\t/// for (auto& i : reverse(c)) { ... }\n\t///\n\ttemplate \n\tstruct reverse_wrapper\n\t{\n\t\ttemplate \n\t\treverse_wrapper(C&& c)\n\t\t\t: mContainer(eastl::forward(c))\n\t\t{\n\t\t\t/**\n\t\t\t * NOTE:\n\t\t\t *\n\t\t\t * Due to reference collapsing rules of universal references Container type is either\n\t\t\t *\n\t\t\t * const C& if the input is a const lvalue\n\t\t\t * C& if the input is a non-const lvalue\n\t\t\t * C if the input is an rvalue\n\t\t\t * const C if the input is a const rvalue thus the object will have to be copied and the copy-ctor will be called\n\t\t\t *\n\t\t\t *\n\t\t\t * Thus we either move the whole container into this object or take a reference to the lvalue avoiding the copy.\n\t\t\t * The static_assert below ensures this.\n\t\t\t */\n\t\t\tstatic_assert(eastl::is_same_v, \"Reference collapsed deduced type must be the same as the deduced Container type!\");\n\t\t}\n\n\t\tContainer mContainer;\n\t};\n\n\ttemplate \n\tauto begin(const reverse_wrapper& w) -> decltype(eastl::rbegin(w.mContainer))\n\t{\n\t\treturn eastl::rbegin(w.mContainer);\n\t}\n\n\ttemplate \n\tauto end(const reverse_wrapper& w) -> decltype(eastl::rend(w.mContainer))\n\t{\n\t\treturn eastl::rend(w.mContainer);\n\t}\n\n\ttemplate \n\treverse_wrapper reverse(Container&& c)\n\t{\n\t\treturn reverse_wrapper(eastl::forward(c));\n\t}\n\n} // namespace eastl\n\n#if defined(_MSC_VER) && (_MSC_VER >= 1900) // VS2015+\n\tEA_RESTORE_VC_WARNING()\n#endif\nEA_RESTORE_VC_WARNING()\n\n#endif // Header include guard\n" }, { "path": "include/EASTL/bonus/call_traits.h", "content": "/////////////////////////////////////////////////////////////////////////////\n// Copyright (c) Electronic Arts Inc. All rights reserved.\n/////////////////////////////////////////////////////////////////////////////\n\n///////////////////////////////////////////////////////////////////////////////\n// The design for call_traits here is very similar to that found in template\n// metaprogramming libraries such as Boost, GCC, and Metrowerks, given that \n// these libraries have established this interface as a defacto standard for \n// solving this problem. Also, these are described in various books on the \n// topic of template metaprogramming, such as \"Modern C++ Design\".\n//\n// See http://www.boost.org/libs/utility/call_traits.htm or search for \n// call_traits in Google for a description of call_traits.\n///////////////////////////////////////////////////////////////////////////////\n\n\n#ifndef EASTL_CALL_TRAITS_H\n#define EASTL_CALL_TRAITS_H\n\n\n#include \n#include \n\n#if defined(EA_PRAGMA_ONCE_SUPPORTED)\n\t#pragma once // Some compilers (e.g. VC++) benefit significantly from using this. We've measured 3-4% build speed improvements in apps as a result.\n#endif\n\n\n\nnamespace eastl\n{\n\n\n\ttemplate \n\tstruct ct_imp2 { typedef const T& param_type; };\n\n\ttemplate \n\tstruct ct_imp2 { typedef const T param_type; };\n\n\ttemplate \n\tstruct ct_imp { typedef const T& param_type; };\n\n\ttemplate \n\tstruct ct_imp { typedef typename ct_imp2::param_type param_type; };\n\n\ttemplate \n\tstruct ct_imp { typedef T const param_type; };\n\n\n\n\ttemplate \n\tstruct call_traits\n\t{\n\tpublic:\n\t\ttypedef T value_type;\n\t\ttypedef T& reference;\n\t\ttypedef const T& const_reference;\n\t\ttypedef typename ct_imp::value, is_arithmetic::value>::param_type param_type;\n\t};\n\n\n\ttemplate \n\tstruct call_traits\n\t{\n\t\ttypedef T& value_type;\n\t\ttypedef T& reference;\n\t\ttypedef const T& const_reference;\n\t\ttypedef T& param_type;\n\t};\n\n\n\ttemplate \n\tstruct call_traits\n\t{\n\tprivate:\n\t\ttypedef T array_type[N];\n\n\tpublic:\n\t\ttypedef const T* value_type;\n\t\ttypedef array_type& reference;\n\t\ttypedef const array_type& const_reference;\n\t\ttypedef const T* const param_type;\n\t};\n\n\n\ttemplate \n\tstruct call_traits\n\t{\n\tprivate:\n\t\ttypedef const T array_type[N];\n\n\tpublic:\n\t\ttypedef const T* value_type;\n\t\ttypedef array_type& reference;\n\t\ttypedef const array_type& const_reference;\n\t\ttypedef const T* const param_type;\n\t};\n\n\n} // namespace eastl\n\n\n#endif // Header include guard\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n" }, { "path": "include/EASTL/bonus/compressed_pair.h", "content": "/////////////////////////////////////////////////////////////////////////////\n// Copyright (c) Electronic Arts Inc. All rights reserved.\n/////////////////////////////////////////////////////////////////////////////\n\n///////////////////////////////////////////////////////////////////////////////\n// The compressed pair class is very similar to std::pair, but if either of the \n// template arguments are empty classes, then the \"empty base-class optimization\" \n// is applied to compress the size of the pair.\n//\n// The design for compressed_pair here is very similar to that found in template\n// metaprogramming libraries such as Boost, GCC, and Metrowerks, given that \n// these libraries have established this interface as a defacto standard for \n// solving this problem. Also, these are described in various books on the \n// topic of template metaprogramming, such as \"Modern C++ Design\".\n// \n// template \n// class compressed_pair\n// {\n// public:\n// typedef T1 first_type;\n// typedef T2 second_type;\n// typedef typename call_traits::param_type first_param_type;\n// typedef typename call_traits::param_type second_param_type;\n// typedef typename call_traits::reference first_reference;\n// typedef typename call_traits::reference second_reference;\n// typedef typename call_traits::const_reference first_const_reference;\n// typedef typename call_traits::const_reference second_const_reference;\n// \n// compressed_pair() : base() {}\n// compressed_pair(first_param_type x, second_param_type y);\n// explicit compressed_pair(first_param_type x);\n// explicit compressed_pair(second_param_type y);\n// \n// compressed_pair& operator=(const compressed_pair&);\n// \n// first_reference first();\n// first_const_reference first() const;\n// \n// second_reference second();\n// second_const_reference second() const;\n// \n// void swap(compressed_pair& y);\n// };\n// \n// The two members of the pair can be accessed using the member functions first() \n// and second(). Note that not all member functions can be instantiated for all \n// template parameter types. In particular compressed_pair can be instantiated for \n// reference and array types, however in these cases the range of constructors that \n// can be used are limited. If types T1 and T2 are the same type, then there is \n// only one version of the single-argument constructor, and this constructor \n// initialises both values in the pair to the passed value.\n// \n// Note that compressed_pair can not be instantiated if either of the template \n// arguments is a union type, unless there is compiler support for is_union, \n// or if is_union is specialised for the union type.\n///////////////////////////////////////////////////////////////////////////////\n\n\n#ifndef EASTL_COMPRESSED_PAIR_H\n#define EASTL_COMPRESSED_PAIR_H\n\n\n#include \n#include \n#include \n\n#if defined(EA_PRAGMA_ONCE_SUPPORTED)\n\t#pragma once // Some compilers (e.g. VC++) benefit significantly from using this. We've measured 3-4% build speed improvements in apps as a result.\n#endif\n\n#if defined(_MSC_VER) && (_MSC_VER >= 1900) // VS2015 or later\n\tEA_DISABLE_VC_WARNING(4626 5027) // warning C4626: 'eastl::compressed_pair_imp': assignment operator was implicitly defined as deleted because a base class assignment operator is inaccessible or deleted\n#endif\n\nnamespace eastl\n{\n\n\ttemplate \n\tclass compressed_pair;\n\n\n\ttemplate \n\tstruct compressed_pair_switch;\n\n\ttemplate \n\tstruct compressed_pair_switch{ static const int value = 0; };\n\n\ttemplate \n\tstruct compressed_pair_switch { static const int value = 1; };\n\n\ttemplate \n\tstruct compressed_pair_switch { static const int value = 2; };\n\n\ttemplate \n\tstruct compressed_pair_switch { static const int value = 3; };\n\n\ttemplate \n\tstruct compressed_pair_switch { static const int value = 4; };\n\n\ttemplate \n\tstruct compressed_pair_switch { static const int value = 5; };\n\n\ttemplate \n\tclass compressed_pair_imp;\n\n\n\n\ttemplate \n\tinline void cp_swap(T& t1, T& t2)\n\t{\n\t\tT tTemp = t1;\n\t\tt1 = t2;\n\t\tt2 = tTemp;\n\t}\n\n\n\t// Derive from neither\n\ttemplate \n\tclass compressed_pair_imp\n\t{\n\tpublic:\n\t\ttypedef T1 first_type;\n\t\ttypedef T2 second_type;\n\t\ttypedef typename call_traits::param_type first_param_type;\n\t\ttypedef typename call_traits::param_type second_param_type;\n\t\ttypedef typename call_traits::reference first_reference;\n\t\ttypedef typename call_traits::reference second_reference;\n\t\ttypedef typename call_traits::const_reference first_const_reference;\n\t\ttypedef typename call_traits::const_reference second_const_reference;\n\n\t\tcompressed_pair_imp() {} \n\n\t\tcompressed_pair_imp(first_param_type x, second_param_type y)\n\t\t\t: mFirst(x), mSecond(y) {}\n\n\t\tcompressed_pair_imp(first_param_type x)\n\t\t\t: mFirst(x) {}\n\n\t\tcompressed_pair_imp(second_param_type y)\n\t\t\t: mSecond(y) {}\n\n\t\tfirst_reference first() { return mFirst; }\n\t\tfirst_const_reference first() const { return mFirst; }\n\n\t\tsecond_reference second() { return mSecond; }\n\t\tsecond_const_reference second() const { return mSecond; }\n\n\t\tvoid swap(compressed_pair& y)\n\t\t{\n\t\t\tcp_swap(mFirst, y.first());\n\t\t\tcp_swap(mSecond, y.second());\n\t\t}\n\n\tprivate:\n\t\tfirst_type mFirst;\n\t\tsecond_type mSecond;\n\t};\n\n\n\t// Derive from T1\n\ttemplate \n\tclass compressed_pair_imp : private T1\n\t{\n\tpublic:\n\t\ttypedef T1 first_type;\n\t\ttypedef T2 second_type;\n\t\ttypedef typename call_traits::param_type first_param_type;\n\t\ttypedef typename call_traits::param_type second_param_type;\n\t\ttypedef typename call_traits::reference first_reference;\n\t\ttypedef typename call_traits::reference second_reference;\n\t\ttypedef typename call_traits::const_reference first_const_reference;\n\t\ttypedef typename call_traits::const_reference second_const_reference;\n\n\t\tcompressed_pair_imp() {}\n\n\t\tcompressed_pair_imp(first_param_type x, second_param_type y)\n\t\t\t: first_type(x), mSecond(y) {}\n\n\t\tcompressed_pair_imp(first_param_type x)\n\t\t\t: first_type(x) {}\n\n\t\tcompressed_pair_imp(second_param_type y)\n\t\t\t: mSecond(y) {}\n\n\t\tfirst_reference first() { return *this; }\n\t\tfirst_const_reference first() const { return *this; }\n\n\t\tsecond_reference second() { return mSecond; }\n\t\tsecond_const_reference second() const { return mSecond; }\n\n\t\tvoid swap(compressed_pair& y)\n\t\t{\n\t\t\t// No need to swap empty base class\n\t\t\tcp_swap(mSecond, y.second());\n\t\t}\n\n\tprivate:\n\t\tsecond_type mSecond;\n\t};\n\n\n\n\t// Derive from T2\n\ttemplate \n\tclass compressed_pair_imp : private T2\n\t{\n\tpublic:\n\t\ttypedef T1 first_type;\n\t\ttypedef T2 second_type;\n\t\ttypedef typename call_traits::param_type first_param_type;\n\t\ttypedef typename call_traits::param_type second_param_type;\n\t\ttypedef typename call_traits::reference first_reference;\n\t\ttypedef typename call_traits::reference second_reference;\n\t\ttypedef typename call_traits::const_reference first_const_reference;\n\t\ttypedef typename call_traits::const_reference second_const_reference;\n\n\t\tcompressed_pair_imp() {}\n\n\t\tcompressed_pair_imp(first_param_type x, second_param_type y)\n\t\t\t: second_type(y), mFirst(x) {}\n\n\t\tcompressed_pair_imp(first_param_type x)\n\t\t\t: mFirst(x) {}\n\n\t\tcompressed_pair_imp(second_param_type y)\n\t\t\t: second_type(y) {}\n\n\t\tfirst_reference first() { return mFirst; }\n\t\tfirst_const_reference first() const { return mFirst; }\n\n\t\tsecond_reference second() { return *this; }\n\t\tsecond_const_reference second() const { return *this; }\n\n\t\tvoid swap(compressed_pair& y)\n\t\t{\n\t\t\t// No need to swap empty base class\n\t\t\tcp_swap(mFirst, y.first());\n\t\t}\n\n\tprivate:\n\t\tfirst_type mFirst;\n\t};\n\n\n\n\t// Derive from T1 and T2\n\ttemplate \n\tclass compressed_pair_imp : private T1, private T2\n\t{\n\tpublic:\n\t\ttypedef T1 first_type;\n\t\ttypedef T2 second_type;\n\t\ttypedef typename call_traits::param_type first_param_type;\n\t\ttypedef typename call_traits::param_type second_param_type;\n\t\ttypedef typename call_traits::reference first_reference;\n\t\ttypedef typename call_traits::reference second_reference;\n\t\ttypedef typename call_traits::const_reference first_const_reference;\n\t\ttypedef typename call_traits::const_reference second_const_reference;\n\n\t\tcompressed_pair_imp() {}\n\n\t\tcompressed_pair_imp(first_param_type x, second_param_type y)\n\t\t\t: first_type(x), second_type(y) {}\n\n\t\tcompressed_pair_imp(first_param_type x)\n\t\t\t: first_type(x) {}\n\n\t\tcompressed_pair_imp(second_param_type y)\n\t\t\t: second_type(y) {}\n\n\t\tfirst_reference first() { return *this; }\n\t\tfirst_const_reference first() const { return *this; }\n\n\t\tsecond_reference second() { return *this; }\n\t\tsecond_const_reference second() const { return *this; }\n\n\t\t// No need to swap empty bases\n\t\tvoid swap(compressed_pair&) \n\t\t\t{ }\n\t};\n\n\n\t// T1 == T2, T1 and T2 are both empty\n\t// Note does not actually store an instance of T2 at all;\n\t// but reuses T1 base class for both first() and second().\n\ttemplate \n\tclass compressed_pair_imp : private T1\n\t{\n\tpublic:\n\t\ttypedef T1 first_type;\n\t\ttypedef T2 second_type;\n\t\ttypedef typename call_traits::param_type first_param_type;\n\t\ttypedef typename call_traits::param_type second_param_type;\n\t\ttypedef typename call_traits::reference first_reference;\n\t\ttypedef typename call_traits::reference second_reference;\n\t\ttypedef typename call_traits::const_reference first_const_reference;\n\t\ttypedef typename call_traits::const_reference second_const_reference;\n\n\t\tcompressed_pair_imp() {}\n\n\t\tcompressed_pair_imp(first_param_type x, second_param_type)\n\t\t\t: first_type(x) {}\n\n\t\tcompressed_pair_imp(first_param_type x)\n\t\t\t: first_type(x) {}\n\n\t\tfirst_reference first() { return *this; }\n\t\tfirst_const_reference first() const { return *this; }\n\n\t\tsecond_reference second() { return *this; }\n\t\tsecond_const_reference second() const { return *this; }\n\n\t\tvoid swap(compressed_pair&) { }\n\t};\n\n\n\t// T1 == T2 and are not empty\n\ttemplate \n\tclass compressed_pair_imp\n\t{\n\tpublic:\n\t\ttypedef T1 first_type;\n\t\ttypedef T2 second_type;\n\t\ttypedef typename call_traits::param_type first_param_type;\n\t\ttypedef typename call_traits::param_type second_param_type;\n\t\ttypedef typename call_traits::reference first_reference;\n\t\ttypedef typename call_traits::reference second_reference;\n\t\ttypedef typename call_traits::const_reference first_const_reference;\n\t\ttypedef typename call_traits::const_reference second_const_reference;\n\n\t\tcompressed_pair_imp() {}\n\n\t\tcompressed_pair_imp(first_param_type x, second_param_type y)\n\t\t\t: mFirst(x), mSecond(y) {}\n\n\t\tcompressed_pair_imp(first_param_type x)\n\t\t\t: mFirst(x), mSecond(x) {}\n\n\t\tfirst_reference first() { return mFirst; }\n\t\tfirst_const_reference first() const { return mFirst; }\n\n\t\tsecond_reference second() { return mSecond; }\n\t\tsecond_const_reference second() const { return mSecond; }\n\n\t\tvoid swap(compressed_pair& y)\n\t\t{\n\t\t\tcp_swap(mFirst, y.first());\n\t\t\tcp_swap(mSecond, y.second());\n\t\t}\n\n\tprivate:\n\t\tfirst_type mFirst;\n\t\tsecond_type mSecond;\n\t};\n\n\n\n\ttemplate \n\tclass compressed_pair\n\t\t: private compressed_pair_imp::type, typename remove_cv::type>::value,\n\t\t\t\t\t\t\tis_empty::value,\n\t\t\t\t\t\t\tis_empty::value>::value>\n\t{\n\tprivate:\n\t\ttypedef compressed_pair_imp::type, typename remove_cv::type>::value,\n\t\t\t\t\t\tis_empty::value,\n\t\t\t\t\t\tis_empty::value>::value> base;\n\tpublic:\n\t\ttypedef T1 first_type;\n\t\ttypedef T2 second_type;\n\t\ttypedef typename call_traits::param_type first_param_type;\n\t\ttypedef typename call_traits::param_type second_param_type;\n\t\ttypedef typename call_traits::reference first_reference;\n\t\ttypedef typename call_traits::reference second_reference;\n\t\ttypedef typename call_traits::const_reference first_const_reference;\n\t\ttypedef typename call_traits::const_reference second_const_reference;\n\n\t\tcompressed_pair() : base() {}\n\t\tcompressed_pair(first_param_type x, second_param_type y) : base(x, y) {}\n\t\texplicit compressed_pair(first_param_type x) : base(x) {}\n\t\texplicit compressed_pair(second_param_type y) : base(y) {}\n\n\t\tfirst_reference first() { return base::first(); }\n\t\tfirst_const_reference first() const { return base::first(); }\n\n\t\tsecond_reference second() { return base::second(); }\n\t\tsecond_const_reference second() const { return base::second(); }\n\n\t\tvoid swap(compressed_pair& y) { base::swap(y); }\n\t};\n\n\n\t// Partial specialisation for case where T1 == T2:\n\ttemplate \n\tclass compressed_pair\n\t\t: private compressed_pair_imp::type, typename remove_cv::type>::value,\n\t\t\t\t\t\t\tis_empty::value,\n\t\t\t\t\t\t\tis_empty::value>::value>\n\t{\n\tprivate:\n\t\ttypedef compressed_pair_imp::type, typename remove_cv::type>::value,\n\t\t\t\t\t\tis_empty::value,\n\t\t\t\t\t\tis_empty::value>::value> base;\n\tpublic:\n\t\ttypedef T first_type;\n\t\ttypedef T second_type;\n\t\ttypedef typename call_traits::param_type first_param_type;\n\t\ttypedef typename call_traits::param_type second_param_type;\n\t\ttypedef typename call_traits::reference first_reference;\n\t\ttypedef typename call_traits::reference second_reference;\n\t\ttypedef typename call_traits::const_reference first_const_reference;\n\t\ttypedef typename call_traits::const_reference second_const_reference;\n\n\t\tcompressed_pair() : base() {}\n\t\tcompressed_pair(first_param_type x, second_param_type y) : base(x, y) {}\n\t\texplicit compressed_pair(first_param_type x) : base(x) {}\n\n\t\tfirst_reference first() { return base::first(); }\n\t\tfirst_const_reference first() const { return base::first(); }\n\n\t\tsecond_reference second() { return base::second(); }\n\t\tsecond_const_reference second() const { return base::second(); }\n\n\t\tvoid swap(compressed_pair& y) { base::swap(y); }\n\t};\n\n\n\ttemplate \n\tinline void swap(compressed_pair& x, compressed_pair& y)\n\t{\n\t\tx.swap(y);\n\t}\n\n\n} // namespace eastl\n\n#if defined(_MSC_VER) && (_MSC_VER >= 1900) // VS2015 or later\n\tEA_RESTORE_VC_WARNING()\n#endif\n\n#endif // Header include guard\n\n\n\n" }, { "path": "include/EASTL/bonus/fixed_ring_buffer.h", "content": "///////////////////////////////////////////////////////////////////////////////\n// Copyright (c) Electronic Arts Inc. All rights reserved.\n///////////////////////////////////////////////////////////////////////////////\n\n#ifndef EASTL_FIXED_RING_BUFFER_H\n#define EASTL_FIXED_RING_BUFFER_H\n\n#include \n#include \n#include \n\n#if defined(EA_PRAGMA_ONCE_SUPPORTED)\n\t#pragma once // Some compilers (e.g. VC++) benefit significantly from using this. We've measured 3-4% build speed improvements in apps as a result.\n#endif\n\nnamespace eastl\n{\n\n\t/// fixed_ring_buffer\n\t///\n\t/// This is a convenience template alias for creating a fixed-sized\n\t/// ring_buffer using eastl::fixed_vector as its storage container. This has\n\t/// been tricky for users to get correct due to the constructor requirements\n\t/// of eastl::ring_buffer leaking the implementation detail of the sentinel\n\t/// value being used internally. In addition, it was not obvious what the\n\t/// correct allocator_type template parameter should be used for containers\n\t/// providing both a default allocator type and an overflow allocator type.\n\t///\n\t/// We are over-allocating the fixed_vector container to accommodate the\n\t/// ring_buffer sentinel to prevent that implementation detail leaking into\n\t/// user code.\n\t///\n\t/// Example usage:\n\t///\n\t/// \tfixed_ring_buffer rb = {0, 1, 2, 3, 4, 5, 6, 7};\n\t/// or\n\t/// \tfixed_ring_buffer rb(8); // capacity doesn't need to respect sentinel\n\t/// \trb.push_back(0);\n\t///\n\t///\n#if !defined(EA_COMPILER_NO_TEMPLATE_ALIASES)\n\ttemplate \n\tusing fixed_ring_buffer =\n\t ring_buffer, typename fixed_vector::overflow_allocator_type>;\n#endif\n\n} // namespace eastl\n\n#endif // Header include guard\n\n" }, { "path": "include/EASTL/bonus/fixed_tuple_vector.h", "content": "///////////////////////////////////////////////////////////////////////////////\n// Copyright (c) Electronic Arts Inc. All rights reserved.\n///////////////////////////////////////////////////////////////////////////////\n\n#ifndef EASTL_FIXEDTUPLEVECTOR_H\n#define EASTL_FIXEDTUPLEVECTOR_H\n\n#include \n#include \n\n#if defined(EA_PRAGMA_ONCE_SUPPORTED)\n\t#pragma once // Some compilers (e.g. VC++) benefit significantly from using this. We've measured 3-4% build speed improvements in apps as a result.\n#endif\n\nnamespace eastl\n{\n\n\t/// EASTL_FIXED_TUPLE_VECTOR_DEFAULT_NAME\n\t///\n\t/// Defines a default container name in the absence of a user-provided name.\n\t/// In the case of fixed-size containers, the allocator name always refers\n\t/// to overflow allocations. \n\t///\n\t#ifndef EASTL_FIXED_TUPLE_VECTOR_DEFAULT_NAME\n\t\t#define EASTL_FIXED_TUPLE_VECTOR_DEFAULT_NAME EASTL_DEFAULT_NAME_PREFIX \" fixed_tuple_vector\" // Unless the user overrides something, this is \"EASTL fixed_vector\".\n\t#endif\n\n\n\t/// EASTL_FIXED_TUPLE_VECTOR_DEFAULT_ALLOCATOR\n\t///\n\t#ifndef EASTL_FIXED_TUPLE_VECTOR_DEFAULT_ALLOCATOR\n\t\t#define EASTL_FIXED_TUPLE_VECTOR_DEFAULT_ALLOCATOR overflow_allocator_type(EASTL_FIXED_TUPLE_VECTOR_DEFAULT_NAME)\n\t#endif\n\n// External interface of fixed_tuple_vector\ntemplate \nclass fixed_tuple_vector : public TupleVecInternal::TupleVecImpl::GetTotalAllocationSize(nodeCount, 0), 1,\n\tTupleVecInternal::TupleRecurser::GetTotalAlignment(), 0,\n\tbEnableOverflow, EASTLAllocatorType>, make_index_sequence, Ts...>\n{\npublic:\n\ttypedef fixed_vector_allocator<\n\t\tTupleVecInternal::TupleRecurser::GetTotalAllocationSize(nodeCount, 0), 1,\n\t\tTupleVecInternal::TupleRecurser::GetTotalAlignment(), 0,\n\t\tbEnableOverflow, EASTLAllocatorType> fixed_allocator_type;\n\ttypedef aligned_buffer aligned_buffer_type;\n\ttypedef fixed_tuple_vector this_type;\n\ttypedef EASTLAllocatorType overflow_allocator_type;\n\n\ttypedef TupleVecInternal::TupleVecImpl, Ts...> base_type;\n\ttypedef typename base_type::size_type size_type;\n\nprivate:\n\taligned_buffer_type mBuffer;\n\npublic:\n\tfixed_tuple_vector()\n\t\t: base_type(fixed_allocator_type(mBuffer.buffer), mBuffer.buffer, nodeCount, fixed_allocator_type::kNodeSize)\n\t{ }\n\n\tfixed_tuple_vector(const overflow_allocator_type& allocator)\n\t\t: base_type(fixed_allocator_type(mBuffer.buffer, allocator), mBuffer.buffer, nodeCount, fixed_allocator_type::kNodeSize)\n\t{ }\n\n\tfixed_tuple_vector(this_type&& x)\n\t\t: base_type(fixed_allocator_type(mBuffer.buffer), mBuffer.buffer, nodeCount, fixed_allocator_type::kNodeSize)\n\t{ \n\t\tbase_type::get_allocator().copy_overflow_allocator(x.get_allocator());\n\t\tbase_type::DoInitFromIterator(eastl::make_move_iterator(x.begin()), eastl::make_move_iterator(x.end()));\n\t\tx.clear();\n\t}\n\n\tfixed_tuple_vector(this_type&& x, const overflow_allocator_type& allocator)\n\t\t: base_type(fixed_allocator_type(mBuffer.buffer, allocator), mBuffer.buffer, nodeCount, fixed_allocator_type::kNodeSize)\n\t{\n\t\tbase_type::DoInitFromIterator(eastl::make_move_iterator(x.begin()), eastl::make_move_iterator(x.end()));\n\t\tx.clear();\n\t}\n\n\tfixed_tuple_vector(const this_type& x)\n\t\t: base_type(fixed_allocator_type(mBuffer.buffer), mBuffer.buffer, nodeCount, fixed_allocator_type::kNodeSize)\n\t{ \n\t\tbase_type::get_allocator().copy_overflow_allocator(x.get_allocator());\n\t\tbase_type::DoInitFromIterator(x.begin(), x.end());\n\t}\n\n\tfixed_tuple_vector(const this_type& x, const overflow_allocator_type& allocator)\n\t\t: base_type(fixed_allocator_type(mBuffer.buffer, allocator), mBuffer.buffer, nodeCount, fixed_allocator_type::kNodeSize)\n\t{\n\t\tbase_type::DoInitFromIterator(x.begin(), x.end());\n\t}\n\n\ttemplate \n\tfixed_tuple_vector(move_iterator begin, move_iterator end, const overflow_allocator_type& allocator = EASTL_FIXED_TUPLE_VECTOR_DEFAULT_ALLOCATOR)\n\t\t: base_type(fixed_allocator_type(mBuffer.buffer, allocator), mBuffer.buffer, nodeCount, fixed_allocator_type::kNodeSize)\n\t{\n\t\tbase_type::DoInitFromIterator(begin, end);\n\t}\n\n\ttemplate \n\tfixed_tuple_vector(Iterator begin, Iterator end, const overflow_allocator_type& allocator = EASTL_FIXED_TUPLE_VECTOR_DEFAULT_ALLOCATOR)\n\t\t: base_type(fixed_allocator_type(mBuffer.buffer, allocator), mBuffer.buffer, nodeCount, fixed_allocator_type::kNodeSize)\n\t{\n\t\tbase_type::DoInitFromIterator(begin, end);\n\t}\n\n\tfixed_tuple_vector(size_type n, const overflow_allocator_type& allocator = EASTL_FIXED_TUPLE_VECTOR_DEFAULT_ALLOCATOR)\n\t\t: base_type(fixed_allocator_type(mBuffer.buffer, allocator), mBuffer.buffer, nodeCount, fixed_allocator_type::kNodeSize)\n\t{\n\t\tbase_type::DoInitDefaultFill(n);\n\t}\n\n\tfixed_tuple_vector(size_type n, const Ts&... args)\n\t\t: base_type(fixed_allocator_type(mBuffer.buffer), mBuffer.buffer, nodeCount, fixed_allocator_type::kNodeSize)\n\t{\n\t\tbase_type::DoInitFillArgs(n, args...);\n\t}\n\n\tfixed_tuple_vector(size_type n, const Ts&... args, const overflow_allocator_type& allocator)\n\t\t: base_type(fixed_allocator_type(mBuffer.buffer, allocator), mBuffer.buffer, nodeCount, fixed_allocator_type::kNodeSize)\n\t{\n\t\tbase_type::DoInitFillArgs(n, args...);\n\t}\n\n\tfixed_tuple_vector(size_type n,\n\t\t\t\ttypename base_type::const_reference_tuple tup,\n\t\t\t\tconst overflow_allocator_type& allocator = EASTL_FIXED_TUPLE_VECTOR_DEFAULT_ALLOCATOR)\n\t\t: base_type(fixed_allocator_type(mBuffer.buffer, allocator), mBuffer.buffer, nodeCount, fixed_allocator_type::kNodeSize)\n\t{\n\t\tbase_type::DoInitFillTuple(n, tup);\n\t}\n\n\tfixed_tuple_vector(const typename base_type::value_tuple* first, const typename base_type::value_tuple* last,\n\t\tconst overflow_allocator_type& allocator = EASTL_FIXED_TUPLE_VECTOR_DEFAULT_ALLOCATOR)\n\t\t: base_type(fixed_allocator_type(mBuffer.buffer, allocator), mBuffer.buffer, nodeCount, fixed_allocator_type::kNodeSize)\n\t{\n\t\tbase_type::DoInitFromTupleArray(first, last);\n\t}\n\n\tfixed_tuple_vector(std::initializer_list iList,\n\t\tconst overflow_allocator_type& allocator = EASTL_FIXED_TUPLE_VECTOR_DEFAULT_ALLOCATOR)\n\t\t: base_type(fixed_allocator_type(mBuffer.buffer, allocator), mBuffer.buffer, nodeCount, fixed_allocator_type::kNodeSize)\n\t{\n\t\tbase_type::DoInitFromTupleArray(iList.begin(), iList.end());\n\t}\n\n\tthis_type& operator=(const this_type& other)\n\t{\n\t\tbase_type::operator=(other);\n\t\treturn *this;\n\t}\n\n\tthis_type& operator=(this_type&& other)\n\t{\n\t\tbase_type::clear();\n\t\t// OK to call DoInitFromIterator in a non-ctor scenario because clear() reset everything, more-or-less\n\t\tbase_type::DoInitFromIterator(eastl::make_move_iterator(other.begin()), eastl::make_move_iterator(other.end()));\n\t\tother.clear();\n\t\treturn *this;\n\t}\n\n\tthis_type& operator=(std::initializer_list iList)\n\t{\n\t\tbase_type::operator=(iList);\n\t\treturn *this;\n\t}\n\n\tvoid swap(this_type& x)\n\t{\n\t\t// If both containers are using the heap instead of local memory \n\t\t// then we can do a fast pointer swap instead of content swap.\n\t\tif ((has_overflowed() && x.has_overflowed()) && (get_overflow_allocator() == x.get_overflow_allocator()))\n\t\t{\n\t\t\tbase_type::swap(x);\n\t\t}\n\t\telse\n\t\t{\n\t\t\t// Fixed containers use a special swap that can deal with excessively large buffers.\n\t\t\teastl::fixed_swap(*this, x);\n\t\t}\n\t}\n\n\t// Returns the max fixed size, which is the user-supplied nodeCount parameter.\n\tsize_type max_size() const { return nodeCount; }\n\t// Returns true if the fixed space has been fully allocated. Note that if overflow is enabled,\n\t// the container size can be greater than nodeCount but full() could return true because the\n\t// fixed space may have a recently freed slot.\n\tbool full() const { return (base_type::mNumElements >= nodeCount) || ((void*)base_type::mpData != (void*)mBuffer.buffer);\t}\n\t// Returns true if the allocations spilled over into the overflow allocator. Meaningful\n\t// only if overflow is enabled.\n\tbool has_overflowed() const { return ((void*)base_type::mpData != (void*)mBuffer.buffer); }\n\t// Returns the value of the bEnableOverflow template parameter.\n\tstatic constexpr bool can_overflow() { return bEnableOverflow; }\n\n\tconst overflow_allocator_type& get_overflow_allocator() const { return base_type::get_allocator().get_overflow_allocator(); }\n};\n\n\ntemplate \ninline void swap(fixed_tuple_vector& a,\n\t\t\t\tfixed_tuple_vector& b)\n{\n\ta.swap(b);\n}\n\n\n} // namespace eastl\n\n#endif // EASTL_TUPLEVECTOR_H\n" }, { "path": "include/EASTL/bonus/flags.h", "content": "// Copyright (c) Electronic Arts Inc. All rights reserved.\n\n#pragma once\n\n//\n// introduction\n// --------------\n// \n// hello there.\n// \n// Flags are usually defined on a per-bit basis, and stored in integrals. This file\n// defines a templated type that encapsulates that logic as a thin-wrapper around an\n// integral. The benefit here is that [i.e.] enums that are not already shifted can\n// be seamlessly used if the corresponding flags type knows they're pre-shifted.\n// \n// \n// context\n// ---------\n// Here's a really common example where everything is _easy_:\n// (operators & conversions left out for brevity)\n// \n// enum class Dragons : uint32_t { Fire = 1, Ice = 2, Poison = 4, Golden = 8 };\n// uint32_t flags = Dragons::Fire | Dragons::Poison;\n// \n// Here's a really common example where things are _harder_:\n// \n// enum class Knights : uint16_t { Armoured, Cowardly, Shining, Ni };\n// uint32_t flags = (1 << Knights::Armoured) | (1 << Knights::Shining);\n// \n// Fun fact: the shift operator's resultant type is the type of the LHS, and\n// bitwise or-operator will promote its arguments of uint16_t to int on 64-bit\n// systems, meaning there are _many more_ omitted casts then may first appear.\n// \n// In the above examples, we would call `Dragons` _post-shifted_, and `Knights`\n// _pre-shifted_. Example code perhaps trivialises the issue; in large codebases\n// keeping track of which flags are pre- or post-shifted can be annoying, and\n// there is genuine need for both mixed within the same code. Awful!\n// \n// \n// basic_flags (prefer using bitflags/maskflags)\n// -----------------------------------------------\n// This structure wraps an integral and provides all common bitwise operations for\n// that integral. It will automatically shift pre-shifted flags (kind of, you need\n// to tell it that a flag is pre-shifted (bitflags), or post-shifted (maskflags)).\n// \n// This example demonstrates pre-shifted flags being used without any shifting\n// required on the user's part. If the user had accidentally used eastl::maskflags<>\n// instead of bitflags<>, then no shifting would occur and there would be _bugs_:\n// \n// enum class Knights : uint16_t { Armoured, Cowardly, Shining, Ni };\n// using KnightFlags = eastl::bitflags;\n// \n// // default construct = all bits zero\n// KnightFlags knight_useless;\n// \n// // takes an initializer_list if so desired\n// KnightFlags knight_in_shining_armour{Knights::Armoured, Knights::Shining};\n// \n// // supports all typical operators\n// if (knight_in_shining_armour & Knights::Shining)\n// {\n// // ...\n// }\n// \n// // being brave is part of the job description\n// knight_useless = Knights::Cowardly;\n// \n// // integrals would support implicit conversion to bool, so we do too\n// if (knight_useless)\n// {\n// }\n// \n// \n// \n//\n// macros for defining flags\n// ---------------------------\n// \n// The following macros are shorthands for defining a flag-type based off\n// an enum-type. This enum-type can either be known ahead of time, using\n// EASTL_DECLARE_BITFLAGS or EASTL_DECLARE_MASKFLAGS, or it can be defined\n// directly then and there, using the \"_ENUM_CLASS\" versions of the macros.\n// \n// These macros help by defining certain bitwise operators for enum-classes.\n// \n// \n// \n// \n// EASTL_DECLARE_BITFLAGS\n// EASTL_DECLARE_MASKFLAGS\n// -------------------------\n// These macros simply take an existing enum-type and define an alias for a\n// flags-type (bitflags or maskflags) of that enum-type:\n// \n// enum class DragonType { Happy, Sad, Drunk };\n// \n// EASTL_DECLARE_BITFLAGS(DragonFlags, DragonType);\n// \n// ^ the above macro has expanded to something akin to:\n// \n// using DragonFlags = ::eastl::bitflags;\n// inline constexpr DragonFlags operator | (DragonType lhs, DragonType rhs) { /* snip */ }\n//\n// This example shows a post-shifted enum using MASKFLAGS. Note that pre-shifted\n// flags can be combined and thus more than the bitwise-or operator has been\n// provided (the bitwse and-operator and xor-operator and included free of charge):\n//\n// enum class WizardType\n// {\n// Brilliant = 1, Imbecile = 2, Evil = 4, Forgetful = 8,\n// MaybeHarmless = (Evil | Forgetful)\n// };\n// \n// EASTL_DECLARE_MASKFLAGS(WizardFlags, WizardType);\n// \n// ^ macro expansion for the above macro looks like:\n// \n// using WizardFlags = ::eastl::maskflags;\n// inline constexpr WizardFlags operator | (WizardType lhs, WizardType rhs) { /* snip */ }\n// inline constexpr WizardFlags operator & (WizardType lhs, WizardType rhs) { /* snip */ }\n// inline constexpr WizardFlags operator ^ (WizardType lhs, WizardType rhs) { /* snip */ }\n// \n// \n// \n// \n// EASTL_DECLARE_BITFLAGS_ENUM_CLASS\n// EASTL_DECLARE_MASKFLAGS_ENUM_CLASS\n// -----------------------------------\n// These macros are convenience macros to both declare the flag-type, and\n// in-place define an enum-class (the second parameter). Operators for the\n// enum-type are automatically generated too:\n// \n// Note that this first example is again using BITFLAGS.\n// \n// EASTL_DECLARE_BITFLAGS_ENUM_CLASS(DragonFlags, DragonType)\n// {\n// Jubilent,\n// Depressed,\n// Smashed\n// };\n// \n// This generates code similar to the following:\n// \n// enum class DragonType;\n// using DragonFlags = ::eastl::bitflags;\n// inline constexpr DragonFlags operator | (DragonType lhs, DragonType rhs) { /* snip */ }\n// enum class DragonType\n// {\n// Jubilent,\n// Depressed,\n// Smashed\n// };\n// \n// \n// Note: You will still need to pre-shift your enum values yourself when using\n// the MASKFLAGS version of these macros, just as if you were writing the enum\n// without the macro:\n// \n// EASTL_DECLARE_MASKFLAGS_ENUM_CLASS(SquireFlags, Squires)\n// {\n// Absent = 0,\n// Inexperienced = (1<<0),\n// Keen = (1<<1),\n// Jaded = (1<<2),\n// Competant = (1<<3),\n// \n// FreshOutOfUni = Inexperienced | Keen\n// };\n// \n// Macro expansion:\n// \n// enum class Squires;\n// using SquireFlags = ::eastl::bitflags;\n// inline constexpr SquireFlags operator | (Squires lhs, Squires rhs) { /* snip */ }\n// inline constexpr SquireFlags operator & (Squires lhs, Squires rhs) { /* snip */ }\n// inline constexpr SquireFlags operator ^ (Squires lhs, Squires rhs) { /* snip */ }\n// enum class Squires\n// {\n// Absent = 0,\n// Inexperienced = (1<<0),\n// Keen = (1<<1),\n// Jaded = (1<<2),\n// Competant = (1<<3),\n// \n// FreshOutOfUni = Inexperienced | Keen\n// };\n// \n// Usage:\n// \n// SquireFlags flags{Squires::FreshOutOfUni};\n// if (flags & Squires::Keen) { /* snip */ }\n// if (flags != Squires::Absent) { /* snip */ }\n//\n\n\n#include \n#include \n\n\n\n// forward-declares\nnamespace eastl\n{\n\ttemplate \n\tstruct basic_flags;\n\n\ttemplate \n\tstruct flag_marshaller;\n\n\t// tags to determine between flag-types\n\tstruct bitflag_tag {};\n\tstruct maskflag_tag {};\n\n\t// aliases\n\ttemplate \n\tusing bitflags = basic_flags>;\n\n\ttemplate \n\tusing maskflags = basic_flags>;\n}\n\n\n// the mask-type for an enum of a given size\nnamespace eastl::detail\n{\n\ttemplate \n\tstruct flags_mask_type;\n\n\ttemplate <> struct flags_mask_type<1> { using type = uint8_t; };\n\ttemplate <> struct flags_mask_type<2> { using type = uint16_t; };\n\ttemplate <> struct flags_mask_type<4> { using type = uint32_t; };\n\ttemplate <> struct flags_mask_type<8> { using type = uint64_t; };\n\n\ttemplate \n\tusing flags_mask_type_t = typename flags_mask_type::type;\n}\n\n\nnamespace eastl\n{\n\ttemplate \n\tstruct basic_flags\n\t{\n\t\tusing flag_type = Flag;\n\t\tusing marshaller_type = Marshaller;\n\t\tusing mask_type = detail::flags_mask_type_t;\n\n\t\tstatic_assert(is_integral_v, \"mask_type must be integral\");\n\t\tstatic_assert(is_unsigned_v, \"mask_type must be unsigned\");\n\n\t\t// constructors\n\t\tstatic constexpr basic_flags from_mask(mask_type) noexcept;\n\n\t\tconstexpr basic_flags() noexcept = default;\n\t\tconstexpr basic_flags(flag_type) noexcept;\n\t\tconstexpr basic_flags(const basic_flags&) = default;\n\t\tconstexpr basic_flags(std::initializer_list) noexcept;\n\n\t\t// explicit conversions\n\t\tconstexpr operator bool() const noexcept;\n\t\tconstexpr explicit operator mask_type() const noexcept;\n\n\t\t// standard flags operators\n\t\tconstexpr basic_flags& operator = (flag_type) noexcept;\n\t\tconstexpr basic_flags& operator = (const basic_flags&) noexcept = default;\n\n\t\tconstexpr basic_flags& operator |= (basic_flags) noexcept;\n\t\tconstexpr basic_flags& operator &= (basic_flags) noexcept;\n\t\tconstexpr basic_flags& operator ^= (basic_flags) noexcept;\n\t\t\n\t\tconstexpr basic_flags& operator |= (flag_type) noexcept;\n\t\tconstexpr basic_flags& operator &= (flag_type) noexcept;\n\t\tconstexpr basic_flags& operator ^= (flag_type) noexcept;\n\n\t\tconstexpr basic_flags operator ~ () const noexcept;\n\n\t\t// named versions of common operations\n\t\tconstexpr basic_flags& set(flag_type, bool enabled) noexcept;\n\t\tconstexpr basic_flags& set(flag_type) noexcept;\n\t\tconstexpr basic_flags& unset(flag_type) noexcept;\n\t\tconstexpr basic_flags& toggle(flag_type) noexcept;\n\t\tconstexpr void clear() noexcept;\n\t\tconstexpr void reset(mask_type = 0u) noexcept;\n\n\tprivate:\n\t\tconstexpr basic_flags(mask_type mask) noexcept\n\t\t\t: m_mask{mask}\n\t\t{}\n\n\tprivate:\n\t\tmask_type m_mask{};\n\n\tprivate:\n\t\t// friend non-member bitwise operations\n\t\ttemplate friend constexpr basic_flags operator & (basic_flags, basic_flags) noexcept;\n\t\ttemplate friend constexpr basic_flags operator | (basic_flags, basic_flags) noexcept;\n\t\ttemplate friend constexpr basic_flags operator ^ (basic_flags, basic_flags) noexcept;\n\n\t\ttemplate friend constexpr basic_flags operator & (basic_flags, typename basic_flags::flag_type) noexcept;\n\t\ttemplate friend constexpr basic_flags operator | (basic_flags, typename basic_flags::flag_type) noexcept;\n\t\ttemplate friend constexpr basic_flags operator ^ (basic_flags, typename basic_flags::flag_type) noexcept;\n\n\t\ttemplate friend constexpr basic_flags operator & (typename basic_flags::flag_type, basic_flags) noexcept;\n\t\ttemplate friend constexpr basic_flags operator | (typename basic_flags::flag_type, basic_flags) noexcept;\n\t\ttemplate friend constexpr basic_flags operator ^ (typename basic_flags::flag_type, basic_flags) noexcept;\n\n\t\t// friend comparison operators\n\t\ttemplate friend constexpr bool operator == (basic_flags, basic_flags) noexcept;\n\t\ttemplate friend constexpr bool operator == (basic_flags, typename basic_flags::flag_type) noexcept;\n\t\ttemplate friend constexpr bool operator == (typename basic_flags::flag_type, basic_flags) noexcept;\n\n\t\ttemplate friend constexpr bool operator != (basic_flags, basic_flags) noexcept;\n\t\ttemplate friend constexpr bool operator != (basic_flags, typename basic_flags::flag_type) noexcept;\n\t\ttemplate friend constexpr bool operator != (typename basic_flags::flag_type, basic_flags) noexcept;\n\t};\n}\n\n\n\n\n\n\n\n//\n// flag_marshaller\n// -----------------\n// marshalls the flag-type into a mask-type we can perform bitwise operations\n// on with our mask member\n// \n// 'bitflags' expects the flags to be sequentially numbered, where the\n// value of each flag signifies the bit-position within the mask-type that\n// will be affected\n// \n// // the bottom four bits (position 0, 1, 2, 3) will be affected\n// enum class MaidenType { Distressed, Defiant, Conniving, Charasmatic };\n// \n// // bits at positions 3, 4, and 8\n// enum class KnightType { Armoured = 3, Lazy = 4, Jousting = 8 };\n// \n// \n// 'maskflags' on the other hand, expects the values of the flags to be\n// _already_ shifted to the correct position. taking the above examples\n// and rewriting them as bitmasks:\n// \n// // the bottom four bits (position 0, 1, 2, 3) will be affected\n// enum class MaidenType { Distressed = 1, Defiant = 2, Conniving = 4, Charasmatic = 8 };\n// \n// // bits at positions 3, 4, and 8 (note that \"Absent\" contributes nothing)\n// enum class KnightType { Absent = 0, Armoured = (1<<3), Lazy = (1<<4), Jousting = (1<<8) };\n//\n//\nnamespace eastl\n{\n\ttemplate \n\tstruct flag_marshaller\n\t{\n\t\tstatic_assert(!std::is_integral_v);\n\n\t\tusing tag_type = TagType;\n\t\tusing flag_type = FlagType;\n\t\tusing mask_type = detail::flags_mask_type_t;\n\n\t\t// we really want C++ constexpr-if\n\t\ttemplate \n\t\tstatic constexpr mask_type to_mask(flag_type f)\n\t\t{\n\t\t\treturn to_mask_impl(tag_type{}, f);\n\t\t}\n\n\tprivate:\n\t\ttemplate \n\t\tstatic constexpr mask_type to_mask_impl(bitflag_tag, flag_type f)\n\t\t{\n\t\t\treturn mask_type{1} << static_cast(f) << AdditionalOffset;\n\t\t}\n\n\t\ttemplate \n\t\tstatic constexpr mask_type to_mask_impl(maskflag_tag, flag_type f)\n\t\t{\n\t\t\treturn static_cast(f) << AdditionalOffset;\n\t\t}\n\t};\n}\n\n\n\n\n//\n// basic_flags implementation\n//\nnamespace eastl\n{\n\ttemplate \n\tinline constexpr basic_flags basic_flags::from_mask(mask_type mask) noexcept\n\t{\n\t\treturn basic_flags{mask};\n\t}\n\n\ttemplate \n\tinline constexpr basic_flags::basic_flags(flag_type flag) noexcept\n\t\t: m_mask{marshaller_type::to_mask(flag)}\n\t{}\n\n\ttemplate \n\tinline constexpr basic_flags::basic_flags(std::initializer_list flags) noexcept\n\t{\n\t\tfor (auto f : flags)\n\t\t\tset(f);\n\t}\n\n\ttemplate \n\tinline constexpr basic_flags::operator bool() const noexcept\n\t{\n\t\treturn static_cast(m_mask);\n\t}\n\n\ttemplate \n\tinline constexpr basic_flags::operator mask_type() const noexcept\n\t{\n\t\treturn m_mask;\n\t}\n\n\ttemplate \n\tinline constexpr basic_flags& basic_flags::operator = (flag_type flag) noexcept\n\t{\n\t\tm_mask = marshaller_type::to_mask(flag);\n\t\treturn *this;\n\t}\n\n\ttemplate \n\tinline constexpr basic_flags& basic_flags::operator |= (basic_flags flag) noexcept\n\t{\n\t\tm_mask |= flag.m_mask;\n\t\treturn *this;\n\t}\n\n\ttemplate \n\tinline constexpr basic_flags& basic_flags::operator &= (basic_flags flag) noexcept\n\t{\n\t\tm_mask &= flag.m_mask;\n\t\treturn *this;\n\t}\n\n\ttemplate \n\tinline constexpr basic_flags& basic_flags::operator ^= (basic_flags flag) noexcept\n\t{\n\t\tm_mask ^= flag.m_mask;\n\t\treturn *this;\n\t}\n\n\ttemplate \n\tinline constexpr basic_flags& basic_flags::operator |= (flag_type flag) noexcept\n\t{\n\t\tm_mask |= marshaller_type::to_mask(flag);\n\t\treturn *this;\n\t}\n\n\ttemplate \n\tinline constexpr basic_flags& basic_flags::operator &= (flag_type flag) noexcept\n\t{\n\t\tm_mask &= marshaller_type::to_mask(flag);\n\t\treturn *this;\n\t}\n\n\ttemplate \n\tinline constexpr basic_flags& basic_flags::operator ^= (flag_type flag) noexcept\n\t{\n\t\tm_mask ^= marshaller_type::to_mask(flag);\n\t\treturn *this;\n\t}\n\n\ttemplate \n\tinline constexpr basic_flags basic_flags::operator ~ () const noexcept\n\t{\n\t\treturn basic_flags{~m_mask};\n\t}\n\n\ttemplate \n\tinline constexpr basic_flags& basic_flags::set(flag_type flag, bool enabled) noexcept\n\t{\n\t\tmask_type const rhs = marshaller_type::to_mask(flag);\n\t\tm_mask = (m_mask & ~rhs) ^ (rhs * static_cast(enabled));\n\t\treturn *this;\n\t}\n\n\ttemplate \n\tinline constexpr basic_flags& basic_flags::set(flag_type flag) noexcept\n\t{\n\t\tm_mask |= marshaller_type::to_mask(flag);\n\t\treturn *this;\n\t}\n\n\ttemplate \n\tinline constexpr basic_flags& basic_flags::unset(flag_type flag) noexcept\n\t{\n\t\tm_mask &= ~marshaller_type::to_mask(flag);\n\t\treturn *this;\n\t}\n\n\ttemplate \n\tinline constexpr basic_flags& basic_flags::toggle(flag_type flag) noexcept\n\t{\n\t\tm_mask ^= marshaller_type::to_mask(flag);\n\t\treturn *this;\n\t}\n\n\ttemplate \n\tinline constexpr void basic_flags::clear() noexcept\n\t{\n\t\tm_mask = 0u;\n\t}\n\n\ttemplate \n\tinline constexpr void basic_flags::reset(mask_type mask) noexcept\n\t{\n\t\tm_mask = mask;\n\t}\n}\n\n\n//\n// BF_MASK_CAST_\n// ---------------\n//\n// bitwise operations will promote to int when available.\n//\n// that is undesireable, as we will then encounter narrowing conversion warnings\n// when assigning to our m_mask of those narrower types. so static-cast.\n//\n#define BF_MASK_CAST_(expr) static_cast::mask_type>(expr)\n\n\n// non-member operators\nnamespace eastl\n{\n\n\ttemplate \n\tinline constexpr basic_flags operator & (basic_flags lhs, basic_flags rhs) noexcept\n\t{\n\t\treturn basic_flags{BF_MASK_CAST_(lhs.m_mask & rhs.m_mask)};\n\t}\n\n\ttemplate \n\tinline constexpr basic_flags operator | (basic_flags lhs, basic_flags rhs) noexcept\n\t{\n\t\treturn basic_flags{BF_MASK_CAST_(lhs.m_mask | rhs.m_mask)};\n\t}\n\n\ttemplate \n\tinline constexpr basic_flags operator ^ (basic_flags lhs, basic_flags rhs) noexcept\n\t{\n\t\treturn basic_flags{BF_MASK_CAST_(lhs.m_mask ^ rhs.m_mask)};\n\t}\n\n\ttemplate \n\tinline constexpr basic_flags operator & (basic_flags lhs, typename basic_flags::flag_type rhs) noexcept\n\t{\n\t\treturn basic_flags{BF_MASK_CAST_(lhs.m_mask & M::to_mask(rhs))};\n\t}\n\n\ttemplate \n\tinline constexpr basic_flags operator | (basic_flags lhs, typename basic_flags::flag_type rhs) noexcept\n\t{\n\t\treturn basic_flags{BF_MASK_CAST_(lhs.m_mask | M::to_mask(rhs))};\n\t}\n\n\ttemplate \n\tinline constexpr basic_flags operator ^ (basic_flags lhs, typename basic_flags::flag_type rhs) noexcept\n\t{\n\t\treturn basic_flags{BF_MASK_CAST_(lhs.m_mask ^ M::to_mask(rhs))};\n\t}\n\t\n\ttemplate \n\tinline constexpr basic_flags operator & (typename basic_flags::flag_type lhs, basic_flags rhs) noexcept\n\t{\n\t\treturn basic_flags{BF_MASK_CAST_(M::to_mask(lhs) & rhs.m_mask)};\n\t}\n\n\ttemplate \n\tinline constexpr basic_flags operator | (typename basic_flags::flag_type lhs, basic_flags rhs) noexcept\n\t{\n\t\treturn basic_flags{BF_MASK_CAST_(M::to_mask(lhs) | rhs.m_mask)};\n\t}\n\n\ttemplate \n\tinline constexpr basic_flags operator ^ (typename basic_flags::flag_type lhs, basic_flags rhs) noexcept\n\t{\n\t\treturn basic_flags{BF_MASK_CAST_(M::to_mask(lhs) ^ rhs.m_mask)};\n\t}\n\n\ttemplate \n\tinline constexpr bool operator == (basic_flags lhs, basic_flags rhs) noexcept\n\t{\n\t\treturn lhs.m_mask == rhs.m_mask;\n\t}\n\n\ttemplate \n\tinline constexpr bool operator == (basic_flags lhs, typename basic_flags::flag_type rhs) noexcept\n\t{\n\t\treturn lhs.m_mask == M::to_mask(rhs);\n\t}\n\n\ttemplate \n\tinline constexpr bool operator == (typename basic_flags::flag_type lhs, basic_flags rhs) noexcept\n\t{\n\t\treturn M::to_mask(lhs) == rhs.m_mask;\n\t}\n\n\ttemplate \n\tinline constexpr bool operator != (basic_flags lhs, basic_flags rhs) noexcept\n\t{\n\t\treturn lhs.m_mask != rhs.m_mask;\n\t}\n\n\ttemplate \n\tinline constexpr bool operator != (basic_flags lhs, typename basic_flags::flag_type rhs) noexcept\n\t{\n\t\treturn lhs.m_mask != M::to_mask(rhs);\n\t}\n\n\ttemplate \n\tinline constexpr bool operator != (typename basic_flags::flag_type lhs, basic_flags rhs) noexcept\n\t{\n\t\treturn M::to_mask(lhs) != rhs.m_mask;\n\t}\n}\n\n#undef BF_MASK_CAST_\n\n\n//\n// mask_of\n// ---------\n// returns the mask of a basic_flags. we have made the conversion operator\n// explicit, so users would have to first know (or get, as the case may be)\n// the mask_type, and perform an explicit cast.\n// \n// this is good because it makes people aware of when their flags are being\n// interpreted as an integral, but it is kind of wordy. so 'mask_of' has\n// been introduced to shorten this.\n// \n// 'mask' was not chosen due to the high potential for name clashes.\n//\nnamespace eastl\n{\n\ttemplate \n\tinline constexpr typename basic_flags::mask_type mask_of(basic_flags flags)\n\t{\n\t\treturn static_cast::mask_type>(flags);\n\t}\n}\n\n\n//\n// macros\n// --------\n// \n// see top-of-file for explanation\n//\n#define EASTL_DECLARE_BITFLAGS(flagstype, enumtype) \\\n\tusing flagstype = ::eastl::bitflags; \\\n\tinline constexpr flagstype operator | (enumtype lhs, enumtype rhs) \\\n\t{ \\\n\t\tusing msh = typename flagstype::marshaller_type; \\\n\t\treturn flagstype::from_mask(static_cast(msh::to_mask(lhs) | msh::to_mask(rhs))); \\\n\t}\n\n#define EASTL_DECLARE_BITFLAGS_ENUM_CLASS(flagstype, enumtype) \\\n\tenum class enumtype; \\\n\tEASTL_DECLARE_BITFLAGS(flagstype, enumtype) \\\n\tenum class enumtype\n\n#define EASTL_DECLARE_BITFLAGS_ENUM_CLASS_SIZED(sizetype, flagstype, enumtype) \\\n\tenum class enumtype : sizetype; \\\n\tEASTL_DECLARE_BITFLAGS(flagstype, enumtype) \\\n\tenum class enumtype : sizetype\n\n\n\n\n#define EASTL_DECLARE_MASKFLAGS(flagstype, enumtype) \\\n\tusing flagstype = ::eastl::maskflags; \\\n\tinline constexpr flagstype operator | (enumtype lhs, enumtype rhs) \\\n\t{ \\\n\t\tusing msh = typename flagstype::marshaller_type; \\\n\t\treturn flagstype::from_mask(static_cast(msh::to_mask(lhs) | msh::to_mask(rhs))); \\\n\t} \\\n\tinline constexpr flagstype operator & (enumtype lhs, enumtype rhs) \\\n\t{ \\\n\t\tusing msh = typename flagstype::marshaller_type; \\\n\t\treturn flagstype::from_mask(static_cast(msh::to_mask(lhs) & msh::to_mask(rhs))); \\\n\t} \\\n\tinline constexpr flagstype operator ^ (enumtype lhs, enumtype rhs) \\\n\t{ \\\n\t\tusing msh = typename flagstype::marshaller_type; \\\n\t\treturn flagstype::from_mask(static_cast(msh::to_mask(lhs) ^ msh::to_mask(rhs))); \\\n\t}\n\n#define EASTL_DECLARE_MASKFLAGS_ENUM_CLASS(flagstype, enumtype) \\\n\tenum class enumtype; \\\n\tEASTL_DECLARE_MASKFLAGS(flagstype, enumtype) \\\n\tenum class enumtype\n\n#define EASTL_DECLARE_MASKFLAGS_ENUM_CLASS_SIZED(sizetype, flagstype, enumtype) \\\n\tenum class enumtype : sizetype; \\\n\tEASTL_DECLARE_MASKFLAGS(flagstype, enumtype) \\\n\tenum class enumtype : sizetype\n\n\n\n" }, { "path": "include/EASTL/bonus/intrusive_sdlist.h", "content": "/////////////////////////////////////////////////////////////////////////////\n// Copyright (c) Electronic Arts Inc. All rights reserved.\n/////////////////////////////////////////////////////////////////////////////\n\n///////////////////////////////////////////////////////////////////////////////\n// intrusive_sdlist is a special kind of intrusive list which we say is \n// \"singly-doubly\" linked. Instead of having a typical intrusive list node\n// which looks like this:\n//\n// struct intrusive_sdlist_node {\n// intrusive_sdlist_node *mpNext;\n// intrusive_sdlist_node *mpPrev;\n// };\n//\n// We instead have one that looks like this:\n//\n// struct intrusive_sdlist_node {\n// intrusive_sdlist_node* mpNext;\n// intrusive_sdlist_node** mppPrevNext;\n// };\n// \n// This may seem to be suboptimal, but it has one specific advantage: it allows\n// the intrusive_sdlist class to be the size of only one pointer instead of two.\n// This may seem like a minor optimization, but some users have wanted to create\n// thousands of empty instances of these.\n// This is because while an intrusive_list class looks like this:\n//\n// class intrusive_list {\n// intrusive_list_node mBaseNode;\n// };\n// \n// an intrusive_sdlist class looks like this:\n//\n// class intrusive_sdlist {\n// intrusive_sdlist_node* mpNext;\n// };\n// \n// So here we make a list of plusses and minuses of intrusive sdlists\n// compared to intrusive_lists and intrusive_slists:\n//\n// | list | slist | sdlist\n// ---------------------------------------------------------\n// min size | 8 | 4 | 4\n// node size | 8 | 4 | 8\n// anonymous erase | yes | no | yes\n// reverse iteration | yes | no | no\n// \n///////////////////////////////////////////////////////////////////////////////\n\n\n#ifndef EASTL_INTRUSIVE_SDLIST_H\n#define EASTL_INTRUSIVE_SDLIST_H\n\n\n#include \n#include \n#include \n\n#if defined(EA_PRAGMA_ONCE_SUPPORTED)\n\t#pragma once // Some compilers (e.g. VC++) benefit significantly from using this. We've measured 3-4% build speed improvements in apps as a result.\n#endif\n\n\n\nnamespace eastl\n{\n\n\n\t/// intrusive_sdlist_node\n\t///\n\tstruct intrusive_sdlist_node\n\t{\n\t\tintrusive_sdlist_node* mpNext;\n\t\tintrusive_sdlist_node** mppPrevNext;\n\t};\n\n\n\t/// IntrusiveSDListIterator\n\t///\n\ttemplate \n\tstruct IntrusiveSDListIterator\n\t{\n\t\ttypedef IntrusiveSDListIterator this_type;\n\t\ttypedef IntrusiveSDListIterator iterator;\n\t\ttypedef IntrusiveSDListIterator const_iterator;\n\t\ttypedef eastl_size_t size_type; // See config.h for the definition of eastl_size_t, which defaults to size_t.\n\t\ttypedef ptrdiff_t difference_type;\n\t\ttypedef T value_type;\n\t\ttypedef T node_type;\n\t\ttypedef Pointer pointer;\n\t\ttypedef Reference reference;\n\t\ttypedef eastl::forward_iterator_tag iterator_category;\n\n\tpublic:\n\t\tpointer mpNode;\n\n\tpublic:\n\t\tIntrusiveSDListIterator();\n\t\texplicit IntrusiveSDListIterator(pointer pNode); // Note that you can also construct an iterator from T via this, since value_type == node_type.\n\t\tIntrusiveSDListIterator(const iterator& x);\n\n\t\treference operator*() const;\n\t\tpointer operator->() const;\n\n\t\tthis_type& operator++();\n\t\tthis_type operator++(int);\n\n\t}; // struct IntrusiveSDListIterator\n\n\n\n\n\t/// intrusive_sdlist_base\n\t///\n\t/// Provides a template-less base class for intrusive_sdlist.\n\t///\n\tclass intrusive_sdlist_base\n\t{\n\tpublic:\n\t\ttypedef eastl_size_t size_type; // See config.h for the definition of eastl_size_t, which defaults to size_t.\n\t\ttypedef ptrdiff_t difference_type;\n\n\tprotected:\n\t\tintrusive_sdlist_node* mpNext;\n\n\tpublic:\n\t\tintrusive_sdlist_base();\n\n\t\tbool empty() const; ///< Returns true if the container is empty.\n\t\tsize_type size() const; ///< Returns the number of elements in the list; O(n).\n\n\t\tvoid clear(); ///< Clears the list; O(1). No deallocation occurs.\n\t\tvoid pop_front(); ///< Removes an element from the front of the list; O(1). The element must be present, but is not deallocated.\n\t\tvoid reverse(); ///< Reverses a list so that front and back are swapped; O(n).\n\n\t\t//bool validate() const; ///< Scans a list for linkage inconsistencies; O(n) time, O(1) space. Returns false if errors are detected, such as loops or branching.\n\n\t}; // class intrusive_sdlist_base\n\n\n\n\t/// intrusive_sdlist\n\t///\n\ttemplate \n\tclass intrusive_sdlist : public intrusive_sdlist_base\n\t{\n\tpublic:\n\t\ttypedef intrusive_sdlist this_type;\n\t\ttypedef intrusive_sdlist_base base_type;\n\t\ttypedef T node_type;\n\t\ttypedef T value_type;\n\t\ttypedef typename base_type::size_type size_type;\n\t\ttypedef typename base_type::difference_type difference_type;\n\t\ttypedef T& reference;\n\t\ttypedef const T& const_reference;\n\t\ttypedef T* pointer;\n\t\ttypedef const T* const_pointer;\n\t\ttypedef IntrusiveSDListIterator iterator;\n\t\ttypedef IntrusiveSDListIterator const_iterator;\n\t\ttypedef eastl::reverse_iterator reverse_iterator;\n\t\ttypedef eastl::reverse_iterator const_reverse_iterator;\n\n\tpublic:\n\t\tintrusive_sdlist(); ///< Creates an empty list.\n\t\tintrusive_sdlist(const this_type& x); ///< Creates an empty list; ignores the argument.\n\t\tthis_type& operator=(const this_type& x); ///< Clears the list; ignores the argument.\n\n\t\titerator begin(); ///< Returns an iterator pointing to the first element in the list.\n\t\tconst_iterator begin() const; ///< Returns a const_iterator pointing to the first element in the list.\n\t\tconst_iterator cbegin() const; ///< Returns a const_iterator pointing to the first element in the list.\n\n\t\titerator end(); ///< Returns an iterator pointing one-after the last element in the list.\n\t\tconst_iterator end() const; ///< Returns a const_iterator pointing one-after the last element in the list.\n\t\tconst_iterator cend() const; ///< Returns a const_iterator pointing one-after the last element in the list.\n\n\t\treference front(); ///< Returns a reference to the first element. The list must not be empty.\n\t\tconst_reference front() const; ///< Returns a const reference to the first element. The list must not be empty.\n\n\t\tvoid push_front(value_type& value); ///< Adds an element to the front of the list; O(1). The element is not copied. The element must not be in any other list.\n\t\tvoid push_back(value_type& value); ///< Adds an element to the back of the list; O(N). The element is not copied. The element must not be in any other list.\n\t\tvoid pop_back(); ///< Removes an element from the back of the list; O(N). The element must be present, but is not deallocated.\n\n\t\tbool contains(const value_type& value) const; ///< Returns true if the given element is in the list; O(n). Equivalent to (locate(x) != end()).\n\n\t\titerator locate(value_type& value); ///< Converts a reference to an object in the list back to an iterator, or returns end() if it is not part of the list. O(n)\n\t\tconst_iterator locate(const value_type& value) const; ///< Converts a const reference to an object in the list back to a const iterator, or returns end() if it is not part of the list. O(n)\n\n\t\titerator insert(iterator position, value_type& value); ///< Inserts an element before the element pointed to by the iterator. O(1)\n\t\titerator erase(iterator position); ///< Erases the element pointed to by the iterator. O(1)\n\t\titerator erase(iterator first, iterator last); ///< Erases elements within the iterator range [first, last). O(1).\n\t\tvoid swap(intrusive_sdlist& x); ///< Swaps the contents of two intrusive lists; O(1).\n\n\t\tstatic void remove(value_type& value); ///< Erases an element from a list; O(1). Note that this is static so you don't need to know which list the element, although it must be in some list.\n\n\t\tvoid splice(iterator position, value_type& value); ///< Moves the given element into this list before the element pointed to by position; O(1).\n\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t ///< Required: x must be in some list or have first/next pointers that point it itself.\n\n\t\tvoid splice(iterator position, this_type& x); ///< Moves the contents of a list into this list before the element pointed to by position; O(1).\n\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t ///< Required: &x != this (same as std::list).\n\n\t\tvoid splice(iterator position, this_type& x, iterator xPosition); ///< Moves the given element pointed to i within the list x into the current list before\n\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t///< the element pointed to by position; O(1).\n\n\t\tvoid splice(iterator position, this_type& x, iterator first, iterator last); ///< Moves the range of elements [first, last) from list x into the current list before\n\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t///< the element pointed to by position; O(1).\n\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t///< Required: position must not be in [first, last). (same as std::list).\n\t\tbool validate() const;\n\t\tint validate_iterator(const_iterator i) const;\n\n\t}; // intrusive_sdlist\n\n\n\n\n\t///////////////////////////////////////////////////////////////////////\n\t// IntrusiveSDListIterator functions\n\t///////////////////////////////////////////////////////////////////////\n\n\ttemplate \n\tinline IntrusiveSDListIterator::IntrusiveSDListIterator()\n\t{\n\t\t#if EASTL_DEBUG\n\t\t\tmpNode = NULL;\n\t\t#endif\n\t}\n\n\ttemplate \n\tinline IntrusiveSDListIterator::IntrusiveSDListIterator(pointer pNode)\n\t\t: mpNode(pNode)\n\t{\n\t}\n\n\ttemplate \n\tinline IntrusiveSDListIterator::IntrusiveSDListIterator(const iterator& x)\n\t\t: mpNode(x.mpNode)\n\t{\n\t}\n\n\ttemplate \n\tinline typename IntrusiveSDListIterator::reference\n\tIntrusiveSDListIterator::operator*() const\n\t{\n\t\treturn *mpNode;\n\t}\n\n\ttemplate \n\tinline typename IntrusiveSDListIterator::pointer\n\tIntrusiveSDListIterator::operator->() const\n\t{\n\t\treturn mpNode;\n\t}\n\n\ttemplate \n\tinline typename IntrusiveSDListIterator::this_type&\n\tIntrusiveSDListIterator::operator++()\n\t{\n\t\tmpNode = static_cast(mpNode->mpNext);\n\t\treturn *this;\n\t}\n\n\ttemplate \n\tinline typename IntrusiveSDListIterator::this_type\n\tIntrusiveSDListIterator::operator++(int)\n\t{\n\t\tthis_type temp = *this;\n\t\tmpNode = static_cast(mpNode->mpNext);\n\t\treturn temp;\n\t}\n\n\t// The C++ defect report #179 requires that we support comparisons between const and non-const iterators.\n\t// Thus we provide additional template paremeters here to support this. The defect report does not\n\t// require us to support comparisons between reverse_iterators and const_reverse_iterators.\n\ttemplate \n\tinline bool operator==(const IntrusiveSDListIterator& a, \n\t\t\t\t\t\t const IntrusiveSDListIterator& b)\n\t{\n\t\treturn a.mpNode == b.mpNode;\n\t}\n\n\n\ttemplate \n\tinline bool operator!=(const IntrusiveSDListIterator& a, \n\t\t\t\t\t\t const IntrusiveSDListIterator& b)\n\t{\n\t\treturn a.mpNode != b.mpNode;\n\t}\n\n\n\t// We provide a version of operator!= for the case where the iterators are of the \n\t// same type. This helps prevent ambiguity errors in the presence of rel_ops.\n\ttemplate \n\tinline bool operator!=(const IntrusiveSDListIterator& a, \n\t\t\t\t\t\t const IntrusiveSDListIterator& b)\n\t{\n\t\treturn a.mpNode != b.mpNode;\n\t}\n\n\n\n\t///////////////////////////////////////////////////////////////////////\n\t// intrusive_sdlist_base\n\t///////////////////////////////////////////////////////////////////////\n\n\tinline intrusive_sdlist_base::intrusive_sdlist_base() \n\t\t{ mpNext = NULL; }\n\n\n\tinline bool intrusive_sdlist_base::empty() const\n\t\t{ return mpNext == NULL; }\n\n\n\tinline intrusive_sdlist_base::size_type intrusive_sdlist_base::size() const\n\t{\n\t\tsize_type n = 0;\n\t\tfor(const intrusive_sdlist_node* pCurrent = mpNext; pCurrent; pCurrent = pCurrent->mpNext)\n\t\t\tn++;\n\t\treturn n;\n\t}\n\n\n\tinline void intrusive_sdlist_base::clear()\n\t\t{ mpNext = NULL; } // Note that we don't do anything with the list nodes.\n\n\n\tinline void intrusive_sdlist_base::pop_front()\n\t{\n\t\t// To consider: Set mpNext's pointers to NULL in debug builds.\n\t\tmpNext = mpNext->mpNext;\n\t\tmpNext->mppPrevNext = &mpNext;\n\t}\n\n\n\n\t///////////////////////////////////////////////////////////////////////\n\t// intrusive_sdlist\n\t///////////////////////////////////////////////////////////////////////\n\n\ttemplate \n\tinline intrusive_sdlist::intrusive_sdlist()\n\t{\n\t}\n\n\n\ttemplate \n\tinline intrusive_sdlist::intrusive_sdlist(const this_type& /*x*/)\n\t : intrusive_sdlist_base()\n\t{\n\t\t// We intentionally ignore argument x.\n\t}\n\n\n\ttemplate \n\tinline typename intrusive_sdlist::this_type& intrusive_sdlist::operator=(const this_type& /*x*/)\n\t{ \n\t\treturn *this; // We intentionally ignore argument x.\n\t}\n\n\n\ttemplate \n\tinline typename intrusive_sdlist::iterator intrusive_sdlist::begin()\n\t\t{ return iterator(static_cast(mpNext)); }\n\n\n\ttemplate \n\tinline typename intrusive_sdlist::const_iterator intrusive_sdlist::begin() const\n\t\t{ return const_iterator(static_cast(const_cast(mpNext))); }\n\n\n\ttemplate \n\tinline typename intrusive_sdlist::const_iterator intrusive_sdlist::cbegin() const\n\t\t{ return const_iterator(static_cast(const_cast(mpNext))); }\n\n\n\ttemplate \n\tinline typename intrusive_sdlist::iterator intrusive_sdlist::end()\n\t\t{ return iterator(static_cast(NULL)); }\n\n\n\ttemplate \n\tinline typename intrusive_sdlist::const_iterator intrusive_sdlist::end() const\n\t\t{ return const_iterator(static_cast(NULL)); }\n\n\n\ttemplate \n\tinline typename intrusive_sdlist::const_iterator intrusive_sdlist::cend() const\n\t\t{ return const_iterator(static_cast(NULL)); }\n\n\n\ttemplate \n\tinline typename intrusive_sdlist::reference intrusive_sdlist::front()\n\t\t{ return *static_cast(mpNext); }\n\n\n\ttemplate \n\tinline typename intrusive_sdlist::const_reference intrusive_sdlist::front() const\n\t\t{ return *static_cast(mpNext); }\n\n\n\ttemplate \n\tinline void intrusive_sdlist::push_front(value_type& value)\n\t{\n\t\tvalue.mpNext = mpNext;\n\t\tvalue.mppPrevNext = &mpNext;\n\t\tif(mpNext)\n\t\t\tmpNext->mppPrevNext = &value.mpNext;\n\t\tmpNext = &value;\n\t}\n\n\n\ttemplate \n\tinline void intrusive_sdlist::push_back(value_type& value)\n\t{\n\t\tintrusive_sdlist_node* pNext = mpNext;\n\t\tintrusive_sdlist_node** ppPrevNext = &mpNext;\n\n\t\twhile(pNext)\n\t\t{\n\t\t\tppPrevNext = &pNext->mpNext;\n\t\t\tpNext = pNext->mpNext;\n\t\t}\n\n\t\t*ppPrevNext = &value;\n\t\tvalue.mppPrevNext = ppPrevNext;\n\t\tvalue.mpNext = NULL;\n\t}\n\n\n\ttemplate \n\tinline void intrusive_sdlist::pop_back()\n\t{\n\t\tnode_type* pCurrent = static_cast(mpNext);\n\n\t\twhile(pCurrent->mpNext)\n\t\t\tpCurrent = static_cast(pCurrent->mpNext);\n\n\t\t*pCurrent->mppPrevNext = NULL;\n\t}\n\n\ttemplate \n\tinline bool intrusive_sdlist::contains(const value_type& value) const\n\t{\n\t\tconst intrusive_sdlist_node* pCurrent;\n\n\t\tfor(pCurrent = mpNext; pCurrent; pCurrent = pCurrent->mpNext)\n\t\t{\n\t\t\tif(pCurrent == &value)\n\t\t\t\tbreak;\n\t\t}\n\n\t\treturn (pCurrent != NULL);\n\t}\n\n\n\ttemplate \n\tinline typename intrusive_sdlist::iterator intrusive_sdlist::locate(value_type& value)\n\t{\n\t\tintrusive_sdlist_node* pCurrent;\n\n\t\tfor(pCurrent = static_cast(mpNext); pCurrent; pCurrent = pCurrent->mpNext)\n\t\t{\n\t\t\tif(pCurrent == &value)\n\t\t\t\tbreak;\n\t\t}\n\n\t\treturn iterator(static_cast(pCurrent));\n\t}\n\n\n\ttemplate \n\tinline typename intrusive_sdlist::const_iterator intrusive_sdlist::locate(const T& value) const\n\t{\n\t\tconst intrusive_sdlist_node* pCurrent;\n\n\t\tfor(pCurrent = static_cast(mpNext); pCurrent; pCurrent = pCurrent->mpNext)\n\t\t{\n\t\t\tif(pCurrent == &value)\n\t\t\t\tbreak;\n\t\t}\n\n\t\treturn const_iterator(static_cast(const_cast(pCurrent)));\n\t}\n\n\n\ttemplate \n\tinline typename intrusive_sdlist::iterator\n\tintrusive_sdlist::insert(iterator position, value_type& value)\n\t{\n\t\tvalue.mppPrevNext = position.mpNode->mppPrevNext;\n\t\tvalue.mpNext = position.mpNode;\n\t *value.mppPrevNext = &value;\n\t\tposition.mpNode->mppPrevNext = &value.mpNext;\n\n\t\treturn iterator(&value);\n\t}\n\n\n\ttemplate \n\tinline typename intrusive_sdlist::iterator\n\tintrusive_sdlist::erase(iterator position)\n\t{\n\t *position.mpNode->mppPrevNext = position.mpNode->mpNext;\n\t\tposition.mpNode->mpNext->mppPrevNext = position.mpNode->mppPrevNext;\n\n\t\treturn iterator(position.mpNode);\n\t}\n\n\n\ttemplate \n\tinline typename intrusive_sdlist::iterator\n\tintrusive_sdlist::erase(iterator first, iterator last)\n\t{\n\t\tif(first.mpNode) // If not erasing the end...\n\t\t{\n\t\t\t*first.mpNode->mppPrevNext = last.mpNode;\n\n\t\t\tif(last.mpNode) // If not erasing to the end...\n\t\t\t\tlast.mpNode->mppPrevNext = first.mpNode->mppPrevNext;\n\t\t}\n\n\t\treturn last;\n\t}\n\n\n\ttemplate \n\tinline void intrusive_sdlist::remove(value_type& value)\n\t{\n\t\t*value.mppPrevNext = value.mpNext;\n\t\tif(value.mpNext)\n\t\t\tvalue.mpNext->mppPrevNext = value.mppPrevNext;\n\t}\n\n\n\ttemplate \n\tvoid intrusive_sdlist::swap(intrusive_sdlist& x)\n\t{\n\t\t// swap anchors\n\t\tintrusive_sdlist_node* const temp(mpNext);\n\t\tmpNext = x.mpNext;\n\t\tx.mpNext = temp;\n\n\t\tif(x.mpNext)\n\t\t\tx.mpNext->mppPrevNext = &mpNext;\n\n\t\tif(mpNext)\n\t\t\tmpNext->mppPrevNext = &x.mpNext;\n\t}\n\n\n\n\n\n\t// To do: Complete these splice functions. Might want to look at intrusive_sdlist for help.\n\n\ttemplate \n\tvoid intrusive_sdlist::splice(iterator /*position*/, value_type& /*value*/)\n\t{\n\t\tEASTL_ASSERT(false); // If you need this working, ask Paul Pedriana or submit a working version for inclusion.\n\t}\n\n\n\ttemplate \n\tvoid intrusive_sdlist::splice(iterator /*position*/, intrusive_sdlist& /*x*/)\n\t{\n\t\tEASTL_ASSERT(false); // If you need this working, ask Paul Pedriana or submit a working version for inclusion.\n\t}\n\n\n\ttemplate \n\tvoid intrusive_sdlist::splice(iterator /*position*/, intrusive_sdlist& /*x*/, iterator /*xPosition*/)\n\t{\n\t\tEASTL_ASSERT(false); // If you need this working, ask Paul Pedriana or submit a working version for inclusion.\n\t}\n\n\n\ttemplate \n\tvoid intrusive_sdlist::splice(iterator /*position*/, intrusive_sdlist& /*x*/, iterator /*first*/, iterator /*last*/)\n\t{\n\t\tEASTL_ASSERT(false); // If you need this working, ask Paul Pedriana or submit a working version for inclusion.\n\t}\n\n\n\ttemplate \n\tinline bool intrusive_sdlist::validate() const\n\t{\n\t\treturn true; // To do.\n\t}\n\n\n\ttemplate \n\tinline int intrusive_sdlist::validate_iterator(const_iterator i) const\n\t{\n\t\t// To do: Come up with a more efficient mechanism of doing this.\n\n\t\tfor(const_iterator temp = begin(), tempEnd = end(); temp != tempEnd; ++temp)\n\t\t{\n\t\t\tif(temp == i)\n\t\t\t\treturn (isf_valid | isf_current | isf_can_dereference);\n\t\t}\n\n\t\tif(i == end())\n\t\t\treturn (isf_valid | isf_current); \n\n\t\treturn isf_none;\n\t}\n\n\n\n\n\t///////////////////////////////////////////////////////////////////////\n\t// global operators\n\t///////////////////////////////////////////////////////////////////////\n\n\ttemplate \n\tbool operator==(const intrusive_sdlist& a, const intrusive_sdlist& b)\n\t{\n\t\t// If we store an mSize member for intrusive_sdlist, we want to take advantage of it here.\n\t\ttypename intrusive_sdlist::const_iterator ia = a.begin();\n\t\ttypename intrusive_sdlist::const_iterator ib = b.begin();\n\t\ttypename intrusive_sdlist::const_iterator enda = a.end();\n\t\ttypename intrusive_sdlist::const_iterator endb = b.end();\n\n\t\twhile((ia != enda) && (ib != endb) && (*ia == *ib))\n\t\t{\n\t\t\t++ia;\n\t\t\t++ib;\n\t\t}\n\t\treturn (ia == enda) && (ib == endb);\n\t}\n\n\ttemplate \n\tbool operator<(const intrusive_sdlist& a, const intrusive_sdlist& b)\n\t{\n\t\treturn eastl::lexicographical_compare(a.begin(), a.end(), b.begin(), b.end());\n\t}\n\n\ttemplate \n\tbool operator!=(const intrusive_sdlist& a, const intrusive_sdlist& b)\n\t{\n\t\treturn !(a == b);\n\t}\n\n\ttemplate \n\tbool operator>(const intrusive_sdlist& a, const intrusive_sdlist& b)\n\t{\n\t\treturn b < a;\n\t}\n\n\ttemplate \n\tbool operator<=(const intrusive_sdlist& a, const intrusive_sdlist& b)\n\t{\n\t\treturn !(b < a);\n\t}\n\n\ttemplate \n\tbool operator>=(const intrusive_sdlist& a, const intrusive_sdlist& b)\n\t{\n\t\treturn !(a < b);\n\t}\n\n\ttemplate \n\tvoid swap(intrusive_sdlist& a, intrusive_sdlist& b)\n\t{\n\t\ta.swap(b);\n\t}\n\n\n} // namespace eastl\n\n\n#endif // Header include guard\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n" }, { "path": "include/EASTL/bonus/intrusive_slist.h", "content": "/////////////////////////////////////////////////////////////////////////////\n// Copyright (c) Electronic Arts Inc. All rights reserved.\n/////////////////////////////////////////////////////////////////////////////\n\n\n///////////////////////////////////////////////////////////////////////////////\n// *** Note ***\n// This implementation is incomplete.\n///////////////////////////////////////////////////////////////////////////////\n\n\n#ifndef EASTL_INTRUSIVE_SLIST_H\n#define EASTL_INTRUSIVE_SLIST_H\n\n\n#include \n#include \n#include \n\n#if defined(EA_PRAGMA_ONCE_SUPPORTED)\n\t#pragma once // Some compilers (e.g. VC++) benefit significantly from using this. We've measured 3-4% build speed improvements in apps as a result.\n#endif\n\n\n\nnamespace eastl\n{\n\n\t/// intrusive_slist_node\n\t///\n\tstruct intrusive_slist_node\n\t{\n\t\tintrusive_slist_node* mpNext;\n\t};\n\n\n\t/// IntrusiveSListIterator\n\t///\n\ttemplate \n\tstruct IntrusiveSListIterator\n\t{\n\t\ttypedef IntrusiveSListIterator this_type;\n\t\ttypedef IntrusiveSListIterator iterator;\n\t\ttypedef IntrusiveSListIterator const_iterator;\n\t\ttypedef eastl_size_t size_type; // See config.h for the definition of eastl_size_t, which defaults to size_t.\n\t\ttypedef ptrdiff_t difference_type;\n\t\ttypedef T value_type;\n\t\ttypedef T node_type;\n\t\ttypedef Pointer pointer;\n\t\ttypedef Reference reference;\n\t\ttypedef eastl::forward_iterator_tag iterator_category;\n\n\tpublic:\n\t\tnode_type* mpNode;\n\n\tpublic:\n\t\tIntrusiveSListIterator();\n\t\texplicit IntrusiveSListIterator(pointer pNode); // Note that you can also construct an iterator from T via this, since value_type == node_type.\n\t\tIntrusiveSListIterator(const iterator& x);\n\n\t\treference operator*() const;\n\t\tpointer operator->() const;\n\n\t\tthis_type& operator++();\n\t\tthis_type operator++(int);\n\n\t}; // struct IntrusiveSListIterator\n\n\n\n\t/// intrusive_slist_base\n\t///\n\t/// Provides a template-less base class for intrusive_slist.\n\t///\n\tclass intrusive_slist_base\n\t{\n\tpublic:\n\t\ttypedef eastl_size_t size_type; // See config.h for the definition of eastl_size_t, which defaults to size_t.\n\t\ttypedef ptrdiff_t difference_type;\n\n\tprotected:\n\t\tintrusive_slist_node* mpNext;\n\n\tpublic:\n\t\tintrusive_slist_base();\n\n\t\tbool empty() const; ///< Returns true if the container is empty.\n\t\tsize_type size() const; ///< Returns the number of elements in the list; O(n).\n\n\t\tvoid clear(); ///< Clears the list; O(1). No deallocation occurs.\n\t\tvoid pop_front(); ///< Removes an element from the front of the list; O(1). The element must be present, but is not deallocated.\n\t\tvoid reverse(); ///< Reverses a list so that front and back are swapped; O(n).\n\n\t\t//bool validate() const; ///< Scans a list for linkage inconsistencies; O(n) time, O(1) space. Returns false if errors are detected, such as loops or branching.\n\n\t}; // class intrusive_slist_base\n\n\n\n\t/// intrusive_slist\n\t///\n\ttemplate \n\tclass intrusive_slist : public intrusive_slist_base\n\t{\n\tpublic:\n\t\ttypedef intrusive_slist this_type;\n\t\ttypedef intrusive_slist_base base_type;\n\t\ttypedef T node_type;\n\t\ttypedef T value_type;\n\t\ttypedef typename base_type::size_type size_type;\n\t\ttypedef typename base_type::difference_type difference_type;\n\t\ttypedef T& reference;\n\t\ttypedef const T& const_reference;\n\t\ttypedef T* pointer;\n\t\ttypedef const T* const_pointer;\n\t\ttypedef IntrusiveSListIterator iterator;\n\t\ttypedef IntrusiveSListIterator const_iterator;\n\n\tpublic:\n\t\tintrusive_slist(); ///< Creates an empty list.\n\t //intrusive_slist(const this_type& x); ///< Creates an empty list; ignores the argument. To consider: Is this a useful function?\n\t //this_type& operator=(const this_type& x); ///< Clears the list; ignores the argument. To consider: Is this a useful function?\n\n\t\titerator begin(); ///< Returns an iterator pointing to the first element in the list. O(1).\n\t\tconst_iterator begin() const; ///< Returns a const_iterator pointing to the first element in the list. O(1).\n\t\tconst_iterator cbegin() const; ///< Returns a const_iterator pointing to the first element in the list. O(1).\n\t\titerator end(); ///< Returns an iterator pointing one-after the last element in the list. O(1).\n\t\tconst_iterator end() const; ///< Returns a const_iterator pointing one-after the last element in the list. O(1).\n\t\tconst_iterator cend() const; ///< Returns a const_iterator pointing one-after the last element in the list. O(1).\n\t\titerator before_begin(); ///< Returns iterator to position before begin. O(1).\n\t\tconst_iterator before_begin() const; ///< Returns iterator to previous position. O(1).\n\t\tconst_iterator cbefore_begin() const; ///< Returns iterator to previous position. O(1).\n\n\t\titerator previous(const_iterator position); ///< Returns iterator to previous position. O(n).\n\t\tconst_iterator previous(const_iterator position) const; ///< Returns iterator to previous position. O(n).\n\n\t\treference front(); ///< Returns a reference to the first element. The list must be empty.\n\t\tconst_reference front() const; ///< Returns a const reference to the first element. The list must be empty.\n\n\t\tvoid push_front(value_type& value); ///< Adds an element to the front of the list; O(1). The element is not copied. The element must not be in any other list.\n\t\tvoid pop_front(); ///< Removes an element from the back of the list; O(n). The element must be present, but is not deallocated.\n\n\t\tbool contains(const value_type& value) const; ///< Returns true if the given element is in the list; O(n). Equivalent to (locate(x) != end()).\n\n\t\titerator locate(value_type& value); ///< Converts a reference to an object in the list back to an iterator, or returns end() if it is not part of the list. O(n)\n\t\tconst_iterator locate(const value_type& value) const; ///< Converts a const reference to an object in the list back to a const iterator, or returns end() if it is not part of the list. O(n)\n\n\t\titerator insert(iterator position, value_type& value); ///< Inserts an element before the element pointed to by the iterator. O(n)\n\t\titerator insert_after(iterator position, value_type& value); ///< Inserts an element after the element pointed to by the iterator. O(1)\n\n\t\titerator erase(iterator position); ///< Erases the element pointed to by the iterator. O(n)\n\t\titerator erase_after(iterator position); ///< Erases the element after the element pointed to by the iterator. O(1)\n\n\t\titerator erase(iterator first, iterator last); ///< Erases elements within the iterator range [first, last). O(n).\n\t\titerator erase_after(iterator before_first, iterator last); ///< Erases elements within the iterator range [before_first, last). O(1).\n\n\t\tvoid swap(this_type& x); ///< Swaps the contents of two intrusive lists; O(1).\n\n\n\t\tvoid splice(iterator position, value_type& value); ///< Moves the given element into this list before the element pointed to by position; O(n).\n\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t///< Required: x must be in some list or have first/next pointers that point it itself.\n\n\t\tvoid splice(iterator position, this_type& x); ///< Moves the contents of a list into this list before the element pointed to by position; O(n).\n\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t///< Required: &x != this (same as std::list).\n\n\t\tvoid splice(iterator position, this_type& x, iterator xPosition); ///< Moves the given element pointed to i within the list x into the current list before\n\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t ///< the element pointed to by position; O(n).\n\n\t\tvoid splice(iterator position, this_type& x, iterator first, iterator last); ///< Moves the range of elements [first, last) from list x into the current list before\n\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t ///< the element pointed to by position; O(n).\n\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t ///< Required: position must not be in [first, last). (same as std::list).\n\n\t\tvoid splice_after(iterator position, value_type& value); ///< Moves the given element into this list after the element pointed to by position; O(1).\n\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t///< Required: x must be in some list or have first/next pointers that point it itself.\n\n\t\tvoid splice_after(iterator position, this_type& x); ///< Moves the contents of a list into this list after the element pointed to by position; O(n).\n\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t///< Required: &x != this (same as std::list).\n\n\t\tvoid splice_after(iterator position, this_type& x, iterator xPrevious); ///< Moves the element after xPrevious to be after position. O(1).\n\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t///< Required: &x != this (same as std::list).\n\n\t\tvoid splice_after(iterator position, this_type& x, iterator before_first, iterator before_last); ///< Moves the elements in the range of [before_first+1, before_last+1) to be after position. O(1).\n\n\t\tbool validate() const;\n\t\tint validate_iterator(const_iterator i) const;\n\n\t}; // intrusive_slist\n\n\n\n\n\t///////////////////////////////////////////////////////////////////////\n\t// IntrusiveSListIterator\n\t///////////////////////////////////////////////////////////////////////\n\n\ttemplate \n\tinline IntrusiveSListIterator::IntrusiveSListIterator()\n\t{\n\t\t#if EASTL_DEBUG\n\t\t\tmpNode = NULL;\n\t\t#endif\n\t}\n\n\ttemplate \n\tinline IntrusiveSListIterator::IntrusiveSListIterator(pointer pNode)\n\t\t: mpNode(pNode)\n\t{\n\t}\n\n\ttemplate \n\tinline IntrusiveSListIterator::IntrusiveSListIterator(const iterator& x)\n\t\t: mpNode(x.mpNode)\n\t{\n\t}\n\n\n\t///////////////////////////////////////////////////////////////////////\n\t// intrusive_slist_base\n\t///////////////////////////////////////////////////////////////////////\n\n\t// To do.\n\n\n\t///////////////////////////////////////////////////////////////////////\n\t// intrusive_slist\n\t///////////////////////////////////////////////////////////////////////\n\n\t// To do.\n\n\n\t///////////////////////////////////////////////////////////////////////\n\t// global operators\n\t///////////////////////////////////////////////////////////////////////\n\n\n\n\t///////////////////////////////////////////////////////////////////////\n\t// global operators\n\t///////////////////////////////////////////////////////////////////////\n\n\ttemplate \n\tbool operator==(const intrusive_slist& a, const intrusive_slist& b)\n\t{\n\t\t// If we store an mSize member for intrusive_slist, we want to take advantage of it here.\n\t\ttypename intrusive_slist::const_iterator ia = a.begin();\n\t\ttypename intrusive_slist::const_iterator ib = b.begin();\n\t\ttypename intrusive_slist::const_iterator enda = a.end();\n\t\ttypename intrusive_slist::const_iterator endb = b.end();\n\n\t\twhile((ia != enda) && (ib != endb) && (*ia == *ib))\n\t\t{\n\t\t\t++ia;\n\t\t\t++ib;\n\t\t}\n\t\treturn (ia == enda) && (ib == endb);\n\t}\n\n\ttemplate \n\tbool operator<(const intrusive_slist& a, const intrusive_slist& b)\n\t{\n\t\treturn eastl::lexicographical_compare(a.begin(), a.end(), b.begin(), b.end());\n\t}\n\n\ttemplate \n\tbool operator!=(const intrusive_slist& a, const intrusive_slist& b)\n\t{\n\t\treturn !(a == b);\n\t}\n\n\ttemplate \n\tbool operator>(const intrusive_slist& a, const intrusive_slist& b)\n\t{\n\t\treturn b < a;\n\t}\n\n\ttemplate \n\tbool operator<=(const intrusive_slist& a, const intrusive_slist& b)\n\t{\n\t\treturn !(b < a);\n\t}\n\n\ttemplate \n\tbool operator>=(const intrusive_slist& a, const intrusive_slist& b)\n\t{\n\t\treturn !(a < b);\n\t}\n\n\ttemplate \n\tvoid swap(intrusive_slist& a, intrusive_slist& b)\n\t{\n\t\ta.swap(b);\n\t}\n\n} // namespace eastl\n\n\n#endif // Header include guard\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n" }, { "path": "include/EASTL/bonus/list_map.h", "content": "/////////////////////////////////////////////////////////////////////////////\n// Copyright (c) Electronic Arts Inc. All rights reserved.\n/////////////////////////////////////////////////////////////////////////////\n\n\n#ifndef EASTL_LIST_MAP_H\n#define EASTL_LIST_MAP_H\n\n\n#include \n\n// 4512/4626 - 'class' : assignment operator could not be generated. // This disabling would best be put elsewhere.\nEA_DISABLE_VC_WARNING(4512 4626);\n\nnamespace eastl\n{\n\n\t/// EASTL_MAP_DEFAULT_NAME\n\t///\n\t/// Defines a default container name in the absence of a user-provided name.\n\t///\n\t#ifndef EASTL_LIST_MAP_DEFAULT_NAME\n\t\t#define EASTL_LIST_MAP_DEFAULT_NAME EASTL_DEFAULT_NAME_PREFIX \" list_map\" // Unless the user overrides something, this is \"EASTL list_map\".\n\t#endif\n\n\t/// EASTL_MAP_DEFAULT_ALLOCATOR\n\t///\n\t#ifndef EASTL_LIST_MAP_DEFAULT_ALLOCATOR\n\t\t#define EASTL_LIST_MAP_DEFAULT_ALLOCATOR allocator_type(EASTL_LIST_MAP_DEFAULT_NAME)\n\t#endif\n\n\n\t/// list_map_data_base\n\t///\n\t/// We define a list_map_data_base separately from list_map_data (below), because it \n\t/// allows us to have non-templated operations, and it makes it so that the \n\t/// list_map anchor node doesn't carry a T with it, which would waste space and \n\t/// possibly lead to surprising the user due to extra Ts existing that the user \n\t/// didn't explicitly create. The downside to all of this is that it makes debug \n\t/// viewing of an list_map harder, given that the node pointers are of type \n\t/// list_map_data_base and not list_map_data.\n\t///\n\tstruct list_map_data_base\n\t{\n\t\tlist_map_data_base* mpNext;\n\t\tlist_map_data_base* mpPrev;\n\t};\n\n\n\t/// list_map_data\n\t///\n\ttemplate \n\tstruct list_map_data : public list_map_data_base\n\t{\n\t\ttypedef Value value_type;\n\n\t\tlist_map_data(const value_type& value);\n\n\t\tvalue_type mValue; // This is a pair of key/value.\n\t};\n\n\n\t/// list_map_iterator\n\t///\n\ttemplate \n\tstruct list_map_iterator\n\t{\n\t\ttypedef list_map_iterator this_type;\n\t\ttypedef list_map_iterator iterator;\n\t\ttypedef list_map_iterator const_iterator;\n\t\ttypedef eastl_size_t size_type; // See config.h for the definition of eastl_size_t, which defaults to size_t.\n\t\ttypedef ptrdiff_t difference_type;\n\t\ttypedef T value_type;\n\t\ttypedef list_map_data_base base_node_type;\n\t\ttypedef list_map_data node_type;\n\t\ttypedef Pointer pointer;\n\t\ttypedef Reference reference;\n\t\ttypedef eastl::bidirectional_iterator_tag iterator_category;\n\n\tprivate:\n\t\tbase_node_type* mpNode;\n\n\tpublic:\n\t\tlist_map_iterator();\n\t\tlist_map_iterator(const base_node_type* pNode);\n\n\t\t// This is the converting constructor of a non-const iterator to a const iterator\n\t\t// This is never a copy constructor (due to enable_if)\n\t\ttemplate , bool> = true>\n\t\tinline list_map_iterator(const iterator& x)\n\t\t\t: mpNode(x.mpNode)\n\t\t{\n\t\t\t// Empty\n\t\t}\n\n\t\treference operator*() const;\n\t\tpointer operator->() const;\n\n\t\tthis_type& operator++();\n\t\tthis_type operator++(int);\n\n\t\tthis_type& operator--();\n\t\tthis_type operator--(int);\n\n\tprivate:\n\t\ttemplate\n\t\tfriend bool operator==(const list_map_iterator&, const list_map_iterator&);\n\n\t\ttemplate\n\t\tfriend bool operator!=(const list_map_iterator&, const list_map_iterator&);\n\n\t\ttemplate\n\t\tfriend bool operator!=(const list_map_iterator&, const list_map_iterator&);\n\n\t\t// list_map uses mpNode\n\t\ttemplate \n\t\tfriend class list_map;\n\n\t\t// for the \"copy\" constructor, which uses non-const iterator even in the\n\t\t// const_iterator case.\n\t\tfriend iterator;\n\t\tfriend const_iterator;\n\t}; // list_map_iterator\n\n\n\t/// use_value_first\n\t///\n\t/// operator()(x) simply returns x.mValue.first. Used in list_map.\n\t/// This is similar to eastl::use_first, however it assumes that the input type is an object\n\t/// whose mValue is an eastl::pair, and the first value in the pair is the desired return.\n\t///\n\ttemplate \n\tstruct use_value_first\n\t{\n\t\ttypedef Object argument_type;\n\t\ttypedef typename Object::value_type::first_type result_type;\n\n\t\tconst result_type& operator()(const Object& x) const\n\t\t\t{ return x.mValue.first; }\n\t};\n\n\n\t/// list_map\n\t///\n\t/// Implements a map like container, which also provides functionality similar to a list.\n\t/// \n\t/// Note: Like a map, keys must still be unique. As such, push_back() and push_front() operations\n\t/// return a bool indicating success, or failure if the entry's key is already in use.\n\t///\n\t/// list_map is designed to improve performance for situations commonly implemented as:\n\t/// A map, which must be iterated over to find the oldest entry, or purge expired entries.\n\t/// A list, which must be iterated over to remove a player's record when they sign off.\n\t/// \n\t/// list_map requires a little more memory per node than either a list or map alone,\n\t/// and many of list_map's functions have a higher operational cost (CPU time) than their\n\t/// counterparts in list and map. However, as the node count increases, list_map quickly outperforms\n\t/// either a list or a map when find [by-index] and front/back type operations are required.\n\t/// \n\t/// In essence, list_map avoids O(n) iterations at the expense of additional costs to quick (O(1) and O(log n) operations:\n\t/// push_front(), push_back(), pop_front() and pop_back() have O(log n) operation time, similar to map::insert(), rather than O(1) time like a list,\n\t/// however, front() and back() maintain O(1) operation time.\n\t/// \n\t/// As a canonical example, consider a large backlog of player group invites, which are removed when either:\n\t/// The invitation times out - in main loop: while( !listMap.empty() && listMap.front().IsExpired() ) { listMap.pop_front(); }\n\t/// The player rejects the outstanding invitation - on rejection: iter = listMap.find(playerId); if (iter != listMap.end()) { listMap.erase(iter); }\n\t/// \n\t/// For a similar example, consider a high volume pending request container which must:\n\t/// Time out old requests (similar to invites timing out above)\n\t/// Remove requests once they've been handled (similar to rejecting invites above)\n\t/// \n\t/// For such usage patterns, the performance benefits of list_map become dramatic with\n\t/// common O(n) operations once the node count rises to hundreds or more.\n\t/// \n\t/// When high performance is a priority, Containers with thousands of nodes or more\n\t/// can quickly result in unacceptable performance when executing even infrequenty O(n) operations.\n\t/// \n\t/// In order to maintain strong performance, avoid iterating over list_map whenever possible.\n\t/// \n\t///////////////////////////////////////////////////////////////////////\n\t/// find_as\n\t/// In order to support the ability to have a tree of strings but\n\t/// be able to do efficiently lookups via char pointers (i.e. so they\n\t/// aren't converted to string objects), we provide the find_as\n\t/// function. This function allows you to do a find with a key of a\n\t/// type other than the tree's key type. See the find_as function\n\t/// for more documentation on this.\n\t///\n\t///////////////////////////////////////////////////////////////////////\n\t/// Pool allocation\n\t/// If you want to make a custom memory pool for a list_map container, your pool \n\t/// needs to contain items of type list_map::node_type. So if you have a memory\n\t/// pool that has a constructor that takes the size of pool items and the\n\t/// count of pool items, you would do this (assuming that MemoryPool implements\n\t/// the Allocator interface):\n\t/// typedef list_map, MemoryPool> WidgetMap; // Delare your WidgetMap type.\n\t/// MemoryPool myPool(sizeof(WidgetMap::node_type), 100); // Make a pool of 100 Widget nodes.\n\t/// WidgetMap myMap(&myPool); // Create a map that uses the pool.\n\t///\n\ttemplate , typename Allocator = EASTLAllocatorType>\n\tclass list_map\n\t\t: protected rbtree >, Compare, Allocator, eastl::use_value_first > >, true, true>\n\t{\n\tpublic:\n\t\ttypedef rbtree >, Compare, Allocator,\n\t\t\t\t\t eastl::use_value_first > >, true, true> base_type;\n\t\ttypedef list_map this_type;\n\t\ttypedef typename base_type::size_type size_type;\n\t\ttypedef typename base_type::key_type key_type;\n\t\ttypedef T mapped_type;\n\t\ttypedef typename eastl::pair value_type; // This is intentionally different from base_type::value_type\n\t\ttypedef value_type& reference;\n\t\ttypedef const value_type& const_reference;\n\t\ttypedef typename base_type::node_type node_type; // Despite the internal and external values being different, we're keeping the node type the same as the base\n\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t // in order to allow for pool allocation. See EASTL/map.h for more information.\n\t\ttypedef typename eastl::list_map_iterator iterator; // This is intentionally different from base_type::iterator\n\t\ttypedef typename eastl::list_map_iterator const_iterator; // This is intentionally different from base_type::const_iterator\n\t\ttypedef eastl::reverse_iterator reverse_iterator;\n\t\ttypedef eastl::reverse_iterator const_reverse_iterator;\n\t\ttypedef typename base_type::allocator_type allocator_type;\n\t\ttypedef typename eastl::pair insert_return_type; // This is intentionally removed, as list_map doesn't support insert() functions, in favor of list like push_back and push_front\n\t\ttypedef typename eastl::use_first extract_key; // This is intentionally different from base_type::extract_key\n\n\t\tusing base_type::get_allocator;\n\t\tusing base_type::set_allocator;\n\t\tusing base_type::key_comp;\n\t\tusing base_type::empty;\n\t\tusing base_type::size;\n\n\tprotected:\n\t\ttypedef typename eastl::list_map_data > internal_value_type;\n\n\tprotected:\n\t\t// internal base node, acting as the sentinel for list like behaviors\n\t\tlist_map_data_base mNode;\n\n\tpublic:\n\t\tlist_map(const allocator_type& allocator = EASTL_LIST_MAP_DEFAULT_ALLOCATOR);\n\t\tlist_map(const Compare& compare, const allocator_type& allocator = EASTL_MAP_DEFAULT_ALLOCATOR);\n\n\t\t// To do: Implement the following:\n\n\t\t//list_map(const this_type& x);\n\t\t//list_map(this_type&& x);\n\t\t//list_map(this_type&& x, const allocator_type& allocator);\n\t\t//list_map(std::initializer_list ilist, const Compare& compare = Compare(), const allocator_type& allocator = EASTL_LIST_MAP_DEFAULT_ALLOCATOR);\n\n\t\t//template \n\t\t//list_map(Iterator itBegin, Iterator itEnd);\n\n\t\t//this_type& operator=(const this_type& x);\n\t\t//this_type& operator=(std::initializer_list ilist);\n\t\t//this_type& operator=(this_type&& x);\n\n\t\t//void swap(this_type& x);\n\n\tpublic:\n\t\t// iterators\n\t\titerator begin() EA_NOEXCEPT;\n\t\tconst_iterator begin() const EA_NOEXCEPT;\n\t\tconst_iterator cbegin() const EA_NOEXCEPT;\n\n\t\titerator end() EA_NOEXCEPT;\n\t\tconst_iterator end() const EA_NOEXCEPT;\n\t\tconst_iterator cend() const EA_NOEXCEPT;\n\n\t\treverse_iterator rbegin() EA_NOEXCEPT;\n\t\tconst_reverse_iterator rbegin() const EA_NOEXCEPT;\n\t\tconst_reverse_iterator crbegin() const EA_NOEXCEPT;\n\n\t\treverse_iterator rend() EA_NOEXCEPT;\n\t\tconst_reverse_iterator rend() const EA_NOEXCEPT;\n\t\tconst_reverse_iterator crend() const EA_NOEXCEPT;\n\n\tpublic:\n\t\t// List like methods\n\t\treference front();\n\t\tconst_reference front() const;\n\n\t\treference back();\n\t\tconst_reference back() const;\n\n\t\t// push_front and push_back which takes in a key/value pair\n\t\tbool push_front(const value_type& value);\n\t\tbool push_back(const value_type& value);\n\n\t\t// push_front and push_back which take key and value separately, for convenience\n\t\tbool push_front(const key_type& key, const mapped_type& value);\n\t\tbool push_back(const key_type& key, const mapped_type& value);\n\n\t\tvoid pop_front();\n\t\tvoid pop_back();\n\n\tpublic:\n\t\t// Map like methods\n\t\titerator find(const key_type& key);\n\t\tconst_iterator find(const key_type& key) const;\n\n\t\ttemplate \n\t\titerator find_as(const U& u, Compare2 compare2);\n\t\ttemplate \n\t\tconst_iterator find_as(const U& u, Compare2 compare2) const;\n\n\t\tsize_type count(const key_type& key) const;\n\t\tsize_type erase(const key_type& key);\n\n\t\t// todo: add heterogenous lookup support (using a heterogeneous comparator - a type 'Comp' where 'Comp::is_transparent' is valid and denotes a type):\n\t\t// template, bool> = true>\n\t\t// iterator find(const KX& key);\n\t\t//\n\t\t// ... also for count() ...\n\t\t// ... also for erase() ...\n\n\tpublic:\n\t\t// Shared methods which are common to list and map\n\t\titerator erase(const_iterator position);\n\t\treverse_iterator erase(const_reverse_iterator position);\n\n\t\tvoid clear();\n\t\tvoid reset_lose_memory();\n\n\t\tbool validate() const;\n\t\tint validate_iterator(const_iterator i) const;\n\n\tpublic:\n\t\t// list like functionality which is in consideration for implementation:\n\t\t// iterator insert(const_iterator position, const value_type& value);\n\t\t// void remove(const mapped_type& x); \n\t\t \n\tpublic:\n\t\t// list like functionality which may be implemented, but is discouraged from implementation:\n\t\t// due to the liklihood that they would require O(n) time to execute.\n\t\t// template \n\t\t// void remove_if(Predicate);\n\t\t// void reverse();\n\t\t// void sort();\n\t\t// template\n\t\t// void sort(Compare compare); \n\n\tpublic:\n\t\t// map like functionality which list_map does not support, due to abmiguity with list like functionality:\n\t\t#if !defined(EA_COMPILER_NO_DELETED_FUNCTIONS)\n\t\ttemplate \n\t\t\tlist_map(InputIterator first, InputIterator last, const Compare& compare, const allocator_type& allocator = EASTL_RBTREE_DEFAULT_ALLOCATOR) = delete;\n\t\t \n\t\t\tinsert_return_type insert(const value_type& value) = delete;\n\t\t\titerator insert(const_iterator position, const value_type& value) = delete;\n\n\t\t\ttemplate \n\t\t\tvoid insert(InputIterator first, InputIterator last) = delete;\n\t\t\t\t \n\t\t\tinsert_return_type insert(const key_type& key) = delete;\n\t\t \n\t\t\titerator erase(const_iterator first, const_iterator last) = delete;\n\t\t\treverse_iterator erase(reverse_iterator first, reverse_iterator last) = delete;\n\t\t \n\t\t\tvoid erase(const key_type* first, const key_type* last) = delete;\n\t\t \n\t\t\titerator lower_bound(const key_type& key) = delete;\n\t\t\tconst_iterator lower_bound(const key_type& key) const = delete;\n\n\t\t\titerator upper_bound(const key_type& key) = delete;\n\t\t\tconst_iterator upper_bound(const key_type& key) const = delete;\n\t\t \n\t\t\teastl::pair equal_range(const key_type& key) = delete;\n\t\t\teastl::pair equal_range(const key_type& key) const = delete;\n\n\t\t\tmapped_type& operator[](const key_type& key) = delete; // Of map, multimap, set, and multimap, only map has operator[].\n\t\t#endif\n\n\tpublic:\n\t\t// list like functionality which list_map does not support, due to ambiguity with map like functionality:\n\t\t#if 0\n\t\t\treference push_front() = delete;\n\t\t\tvoid* push_front_uninitialized() = delete;\n\n\t\t\treference push_back() = delete;\n\t\t\tvoid* push_back_uninitialized() = delete;\n\n\t\t\titerator insert(const_iterator position) = delete;\n\t\t \n\t\t\tvoid insert(const_iterator position, size_type n, const value_type& value) = delete;\n\n\t\ttemplate \n\t\t\tvoid insert(const_iterator position, InputIterator first, InputIterator last) = delete;\n\t\t \n\t\t\titerator erase(const_iterator first, const_iterator last) = delete;\n\t\t\treverse_iterator erase(const_reverse_iterator first, const_reverse_iterator last) = delete;\n\t\t \n\t\t\tvoid splice(const_iterator position, this_type& x) = delete\n\t\t\tvoid splice(const_iterator position, this_type& x, const_iterator i) = delete;\n\t\t\tvoid splice(const_iterator position, this_type& x, const_iterator first, const_iterator last) = delete;\n\n\t\t\tvoid merge(this_type& x) = delete;\n\n\t\ttemplate \n\t\t\tvoid merge(this_type& x, Compare compare) = delete;\n\t\t \n\t\t\tvoid unique() = delete; // Uniqueness is enforced by map functionality\n\n\t\ttemplate \n\t\t\tvoid unique(BinaryPredicate) = delete; // Uniqueness is enforced by map functionality\n\t\t#endif\n\n\t}; // list_map\n\n\n\t///////////////////////////////////////////////////////////////////////\n\t// list_map_data\n\t///////////////////////////////////////////////////////////////////////\n\n\ttemplate \n\tinline list_map_data::list_map_data(const Value& value)\n\t : mValue(value)\n\t{\n\t\tmpNext = NULL; // GCC 4.8 is generating warnings about referencing these values in list_map::push_front unless we \n\t\tmpPrev = NULL; // initialize them here. The compiler seems to be mistaken, as our code isn't actually using them unintialized.\n\t}\n\n\n\t///////////////////////////////////////////////////////////////////////\n\t// list_map_iterator\n\t///////////////////////////////////////////////////////////////////////\n\n\ttemplate \n\tinline list_map_iterator::list_map_iterator()\n\t\t: mpNode(NULL)\n\t{\n\t\t// Empty\n\t}\n\n\n\ttemplate \n\tinline list_map_iterator::list_map_iterator(const base_node_type* pNode)\n\t\t: mpNode(const_cast(pNode))\n\t{\n\t\t// Empty\n\t}\n\n\n\ttemplate \n\tinline typename list_map_iterator::reference\n\tlist_map_iterator::operator*() const\n\t{\n\t\treturn static_cast(mpNode)->mValue;\n\t}\n\n\n\ttemplate \n\tinline typename list_map_iterator::pointer\n\tlist_map_iterator::operator->() const\n\t{\n\t\treturn &static_cast(mpNode)->mValue;\n\t}\n\n\n\ttemplate \n\tinline typename list_map_iterator::this_type&\n\tlist_map_iterator::operator++()\n\t{\n\t\tmpNode = mpNode->mpNext;\n\t\treturn *this;\n\t}\n\n\n\ttemplate \n\tinline typename list_map_iterator::this_type\n\tlist_map_iterator::operator++(int)\n\t{\n\t\tthis_type temp(*this);\n\t\tmpNode = mpNode->mpNext;\n\t\treturn temp;\n\t}\n\n\n\ttemplate \n\tinline typename list_map_iterator::this_type&\n\tlist_map_iterator::operator--()\n\t{\n\t\tmpNode = mpNode->mpPrev;\n\t\treturn *this;\n\t}\n\n\n\ttemplate \n\tinline typename list_map_iterator::this_type \n\tlist_map_iterator::operator--(int)\n\t{\n\t\tthis_type temp(*this);\n\t\tmpNode = mpNode->mpPrev;\n\t\treturn temp;\n\t}\n\n\n\t// We provide additional template paremeters here to support comparisons between const and non-const iterators.\n\t// See C++ defect report #179, or EASTL/list.h for more information.\n\ttemplate \n\tinline bool operator==(const list_map_iterator& a, \n\t\t\t\t\t\t const list_map_iterator& b)\n\t{\n\t\treturn a.mpNode == b.mpNode;\n\t}\n\n\n\ttemplate \n\tinline bool operator!=(const list_map_iterator& a, \n\t\t\t\t\t\t const list_map_iterator& b)\n\t{\n\t\treturn a.mpNode != b.mpNode;\n\t}\n\n\n\t// We provide a version of operator!= for the case where the iterators are of the \n\t// same type. This helps prevent ambiguity errors in the presence of rel_ops.\n\ttemplate \n\tinline bool operator!=(const list_map_iterator& a, \n\t\t\t\t\t\t const list_map_iterator& b)\n\t{\n\t\treturn a.mpNode != b.mpNode;\n\t}\n\n\n\t///////////////////////////////////////////////////////////////////////\n\t// list_map\n\t///////////////////////////////////////////////////////////////////////\n\n\ttemplate \n\tinline list_map::list_map(const allocator_type& allocator)\n\t\t: base_type(allocator)\n\t{\n\t\tmNode.mpNext = &mNode;\n\t\tmNode.mpPrev = &mNode;\n\t}\n\n\ttemplate \n\tinline list_map::list_map(const Compare& compare, const allocator_type& allocator)\n\t\t: base_type(compare, allocator)\n\t{\n\t\tmNode.mpNext = &mNode;\n\t\tmNode.mpPrev = &mNode;\n\t}\n\n\ttemplate \n\tinline typename list_map::iterator \n\tlist_map::begin() EA_NOEXCEPT\n\t{\n\t\treturn iterator(mNode.mpNext);\n\t}\n\n\ttemplate \n\tinline typename list_map::const_iterator \n\tlist_map::begin() const EA_NOEXCEPT\n\t{\n\t\treturn const_iterator(mNode.mpNext);\n\t}\n\n\ttemplate \n\tinline typename list_map::const_iterator \n\tlist_map::cbegin() const EA_NOEXCEPT\n\t{\n\t\treturn const_iterator(mNode.mpNext);\n\t}\n\n\ttemplate \n\tinline typename list_map::iterator \n\tlist_map::end() EA_NOEXCEPT\n\t{\n\t\treturn iterator(&mNode);\n\t}\n\n\ttemplate \n\tinline typename list_map::const_iterator \n\tlist_map::end() const EA_NOEXCEPT\n\t{\n\t\treturn const_iterator(&mNode);\n\t}\n\n\ttemplate \n\tinline typename list_map::const_iterator \n\tlist_map::cend() const EA_NOEXCEPT\n\t{\n\t\treturn const_iterator(&mNode);\n\t}\n\n\ttemplate \n\tinline typename list_map::reverse_iterator \n\tlist_map::rbegin() EA_NOEXCEPT\n\t{\n\t\treturn reverse_iterator(&mNode);\n\t}\n\n\ttemplate \n\tinline typename list_map::const_reverse_iterator \n\tlist_map::rbegin() const EA_NOEXCEPT\n\t{\n\t\treturn const_reverse_iterator(&mNode);\n\t}\n\n\ttemplate \n\tinline typename list_map::const_reverse_iterator \n\tlist_map::crbegin() const EA_NOEXCEPT\n\t{\n\t\treturn const_reverse_iterator(&mNode);\n\t}\n\n\ttemplate \n\tinline typename list_map::reverse_iterator \n\tlist_map::rend() EA_NOEXCEPT\n\t{\n\t\treturn reverse_iterator(mNode.mpNext);\n\t}\n\n\ttemplate \n\tinline typename list_map::const_reverse_iterator \n\tlist_map::rend() const EA_NOEXCEPT\n\t{\n\t\treturn const_reverse_iterator(mNode.mpNext);\n\t}\n\n\ttemplate \n\tinline typename list_map::const_reverse_iterator \n\tlist_map::crend() const EA_NOEXCEPT\n\t{\n\t\treturn const_reverse_iterator(mNode.mpNext);\n\t}\n\n\ttemplate \n\tinline typename list_map::reference\n\tlist_map::front()\n\t{\n\t\t#if EASTL_ASSERT_ENABLED && EASTL_EMPTY_REFERENCE_ASSERT_ENABLED\n\t\t\tif (EASTL_UNLIKELY(static_cast(mNode.mpNext) == &mNode))\n\t\t\t\tEASTL_FAIL_MSG(\"list_map::front -- empty container\");\n\t\t#else\n\t\t\t// We allow the user to reference an empty container.\n\t\t#endif\n\n\t\treturn static_cast(mNode.mpNext)->mValue;\n\t}\n\n\ttemplate \n\tinline typename list_map::const_reference\n\tlist_map::front() const\n\t{\n\t\t#if EASTL_ASSERT_ENABLED && EASTL_EMPTY_REFERENCE_ASSERT_ENABLED\n\t\t\tif (EASTL_UNLIKELY(static_cast(mNode.mpNext) == &mNode))\n\t\t\t\tEASTL_FAIL_MSG(\"list_map::front -- empty container\");\n\t\t#else\n\t\t\t// We allow the user to reference an empty container.\n\t\t#endif\n\n\t\treturn static_cast(mNode.mpNext)->mValue;\n\t}\n\n\ttemplate \n\tinline typename list_map::reference\n\tlist_map::back()\n\t{\n\t\t#if EASTL_ASSERT_ENABLED && EASTL_EMPTY_REFERENCE_ASSERT_ENABLED\n\t\t\tif (EASTL_UNLIKELY(static_cast(mNode.mpNext) == &mNode))\n\t\t\t\tEASTL_FAIL_MSG(\"list_map::back -- empty container\");\n\t\t#else\n\t\t\t// We allow the user to reference an empty container.\n\t\t#endif\n\n\t\treturn static_cast(mNode.mpPrev)->mValue;\n\t}\n\n\ttemplate \n\tinline typename list_map::const_reference\n\tlist_map::back() const\n\t{\n\t\t#if EASTL_ASSERT_ENABLED && EASTL_EMPTY_REFERENCE_ASSERT_ENABLED\n\t\t\tif (EASTL_UNLIKELY(static_cast(mNode.mpNext) == &mNode))\n\t\t\t\tEASTL_FAIL_MSG(\"list_map::back -- empty container\");\n\t\t#else\n\t\t\t// We allow the user to reference an empty container.\n\t\t#endif\n\n\t\treturn static_cast(mNode.mpPrev)->mValue;\n\t}\n\n\ttemplate \n\tbool list_map::push_front(const value_type& value)\n\t{\n\t\tinternal_value_type tempValue(value);\n\t\ttypename base_type::insert_return_type baseReturn = base_type::insert(tempValue);\n\n\t\t// Did the insert succeed?\n\t\tif (baseReturn.second)\n\t\t{\n\t\t\tinternal_value_type* pNode = &(*baseReturn.first);\n\n\t\t\tpNode->mpNext = mNode.mpNext;\n\t\t\tpNode->mpPrev = &mNode;\n\n\t\t\tmNode.mpNext->mpPrev = pNode;\n\t\t\tmNode.mpNext = pNode;\n\n\t\t\treturn true;\n\t\t}\n\t\telse\n\t\t{\n\t\t\treturn false;\n\t\t}\n\t}\n\n\ttemplate \n\tbool list_map::push_back(const value_type& value)\n\t{\n\t\tinternal_value_type tempValue(value);\n\t\ttypename base_type::insert_return_type baseReturn = base_type::insert(tempValue);\n\n\t\t// Did the insert succeed?\n\t\tif (baseReturn.second)\n\t\t{\n\t\t\tinternal_value_type* pNode = &(*baseReturn.first);\n\n\t\t\tpNode->mpPrev = mNode.mpPrev;\n\t\t\tpNode->mpNext = &mNode;\n\n\t\t\tmNode.mpPrev->mpNext = pNode;\n\t\t\tmNode.mpPrev = pNode;\n\n\t\t\treturn true;\n\t\t}\n\t\telse\n\t\t{\n\t\t\treturn false;\n\t\t}\n\t}\n\n\ttemplate \n\tbool list_map::push_front(const key_type& key, const mapped_type& value)\n\t{\n\t\treturn push_front(eastl::make_pair(key, value));\n\t}\n\n\ttemplate \n\tbool list_map::push_back(const key_type& key, const mapped_type& value)\n\t{\n\t\treturn push_back(eastl::make_pair(key, value));\n\t}\n\n\ttemplate \n\tvoid list_map::pop_front()\n\t{\n\t\t#if EASTL_ASSERT_ENABLED\n\t\t\tif (EASTL_UNLIKELY(empty()))\n\t\t\t\tEASTL_FAIL_MSG(\"list_map::pop_front -- empty container\");\n\t\t#endif\n\n\t\terase(static_cast(mNode.mpNext)->mValue.first);\n\t}\n\n\ttemplate \n\tvoid list_map::pop_back()\n\t{\n\t\t#if EASTL_ASSERT_ENABLED\n\t\t\tif (EASTL_UNLIKELY(empty()))\n\t\t\t\tEASTL_FAIL_MSG(\"list_map::pop_back -- empty container\");\n\t\t#endif\n\n\t\terase(static_cast(mNode.mpPrev)->mValue.first);\n\t}\n\n\ttemplate \n\tinline typename list_map::iterator \n\tlist_map::find(const key_type& key)\n\t{\n\t\ttypename base_type::iterator baseIter = base_type::find(key);\n\t\tif (baseIter != base_type::end())\n\t\t{\n\t\t\treturn iterator(&(*baseIter));\n\t\t}\n\t\telse\n\t\t{\n\t\t\treturn end();\n\t\t}\n\t}\n\t\n\ttemplate \n\tinline typename list_map::const_iterator\n\tlist_map::find(const key_type& key) const\n\t{\n\t\ttypename base_type::const_iterator baseIter = base_type::find(key);\n\t\tif (baseIter != base_type::end())\n\t\t{\n\t\t\treturn const_iterator(&(*baseIter));\n\t\t}\n\t\telse\n\t\t{\n\t\t\treturn end();\n\t\t}\n\t}\n\n\ttemplate \n\ttemplate \n\tinline typename list_map::iterator\n\tlist_map::find_as(const U& u, Compare2 compare2)\n\t{\n\t\ttypename base_type::iterator baseIter = base_type::find_as(u, compare2);\n\t\tif (baseIter != base_type::end())\n\t\t{\n\t\t\treturn iterator(&(*baseIter));\n\t\t}\n\t\telse\n\t\t{\n\t\t\treturn end();\n\t\t}\n\t}\n\n\ttemplate \n\ttemplate \n\tinline typename list_map::const_iterator\n\tlist_map::find_as(const U& u, Compare2 compare2) const\n\t{\n\t\ttypename base_type::const_iterator baseIter = base_type::find_as(u, compare2);\n\t\tif (baseIter != base_type::end())\n\t\t{\n\t\t\treturn const_iterator(&(*baseIter));\n\t\t}\n\t\telse\n\t\t{\n\t\t\treturn end();\n\t\t}\n\t}\n\n\ttemplate \n\tinline typename list_map::size_type\n\tlist_map::count(const key_type& key) const\n\t{\n\t\tconst typename base_type::const_iterator it = base_type::find(key);\n\t\treturn (it != base_type::end()) ? 1 : 0;\n\t}\n\n\ttemplate \n\tinline typename list_map::size_type\n\tlist_map::erase(const key_type& key)\n\t{\n\t\ttypename base_type::iterator baseIter = base_type::find(key);\n\t\tif (baseIter != base_type::end())\n\t\t{\n\t\t\tinternal_value_type* node = &(*baseIter);\n\n\t\t\tnode->mpNext->mpPrev = node->mpPrev;\n\t\t\tnode->mpPrev->mpNext = node->mpNext;\n\n\t\t\tbase_type::erase(baseIter);\n\n\t\t\treturn 1;\n\t\t}\n\t\treturn 0;\n\t}\n\n\ttemplate \n\tinline typename list_map::iterator\n\tlist_map::erase(const_iterator position)\n\t{\n\t\titerator posIter(position.mpNode); // Convert from const.\n\t\titerator eraseIter(posIter++);\n\t\terase(eraseIter->first);\n\t\treturn posIter;\n\t}\n\n\ttemplate \n\tinline typename list_map::reverse_iterator\n\tlist_map::erase(const_reverse_iterator position)\n\t{\n\t\treturn reverse_iterator(erase((++position).base()));\n\t}\n\n\ttemplate \n\tvoid list_map::clear()\n\t{\n\t\tbase_type::clear();\n\n\t\tmNode.mpNext = &mNode;\n\t\tmNode.mpPrev = &mNode;\n\t}\n\n\ttemplate \n\tvoid list_map::reset_lose_memory()\n\t{\n\t\tbase_type::reset_lose_memory();\n\n\t\tmNode.mpNext = &mNode;\n\t\tmNode.mpPrev = &mNode;\n\t}\n\n\ttemplate \n\tbool list_map::validate() const\n\t{\n\t\tif (!base_type::validate())\n\t\t{\n\t\t\treturn false;\n\t\t}\n\n\t\tsize_type nodeCount(0);\n\t\tlist_map_data_base* node = mNode.mpNext;\n\t\twhile (node != &mNode)\n\t\t{\n\t\t\tinternal_value_type* data = static_cast(node);\n\t\t\tif (base_type::find(data->mValue.first) == base_type::end())\n\t\t\t{\n\t\t\t\treturn false;\n\t\t\t}\n\t\t\tnode = node->mpNext;\n\t\t\t++nodeCount;\n\t\t}\n\t\tif (nodeCount != size())\n\t\t{\n\t\t\treturn false;\n\t\t}\n\t\tnodeCount = 0;\n\t\tnode = mNode.mpPrev;\n\t\twhile (node != &mNode)\n\t\t{\n\t\t\tinternal_value_type* data = static_cast(node);\n\t\t\tif (base_type::find(data->mValue.first) == base_type::end())\n\t\t\t{\n\t\t\t\treturn false;\n\t\t\t}\n\t\t\tnode = node->mpPrev;\n\t\t\t++nodeCount;\n\t\t}\n\t\tif (nodeCount != size())\n\t\t{\n\t\t\treturn false;\n\t\t}\n\n\t\treturn true;\n\t}\n\n\ttemplate \n\tint list_map::validate_iterator(const_iterator iter) const\n\t{\n\t\tfor (const_iterator temp = begin(), tempEnd = end(); temp != tempEnd; ++temp)\n\t\t{\n\t\t\tif (temp == iter)\n\t\t\t{\n\t\t\t\treturn (isf_valid | isf_current | isf_can_dereference);\n\t\t\t}\n\t\t}\n\n\t\tif (iter == end())\n\t\t\treturn (isf_valid | isf_current); \n\n\t\treturn isf_none;\n\t}\n\n\n} // namespace eastl\n\nEA_RESTORE_VC_WARNING();\n\n#endif // Header include guard\n\n\n\n\n" }, { "path": "include/EASTL/bonus/lru_cache.h", "content": "///////////////////////////////////////////////////////////////////////////////\n// Copyright (c) Electronic Arts Inc. All rights reserved.\n///////////////////////////////////////////////////////////////////////////////\n\n///////////////////////////////////////////////////////////////////////////////\n// lru_cache is a container that simplifies caching of objects in a map.\n// Basically, you give the container a key, like a string, and the data you want.\n// The container provides callback mechanisms to generate data if it's missing\n// as well as delete data when it's purged from the cache. This container\n// uses a least recently used method: whatever the oldest item is will be \n// replaced with a new entry.\n//\n// Algorithmically, the container is a combination of a map and a list.\n// The list stores the age of the entries by moving the entry to the head\n// of the list on each access, either by a call to get() or to touch().\n// The map is just the map as one would expect.\n//\n// This is useful for caching off data that is expensive to generate, \n// for example text to speech wave files that are dynamically generated,\n// but that will need to be reused, as is the case in narration of menu\n// entries as a user scrolls through the entries.\n///////////////////////////////////////////////////////////////////////////////\n\n#ifndef EASTL_LRUCACHE_H\n#define EASTL_LRUCACHE_H\n\n#if defined(EA_PRAGMA_ONCE_SUPPORTED)\n#pragma once\n#endif\n\n#include \n#include \n#include \n#include // for pair\n#include // for function, hash, equal_to\n\nnamespace eastl\n{\n\t/// EASTL_LRUCACHE_DEFAULT_NAME\n\t///\n\t/// Defines a default container name in the absence of a user-provided name.\n\t///\n\t#ifndef EASTL_LRUCACHE_DEFAULT_NAME\n\t#define EASTL_LRUCACHE_DEFAULT_NAME EASTL_DEFAULT_NAME_PREFIX \" lru_cache\" // Unless the user overrides something, this is \"EASTL lru_cache\".\n\t#endif\n\n\n\t/// EASTL_LRUCACHE_DEFAULT_ALLOCATOR\n\t///\n\t#ifndef EASTL_LRUCACHE_DEFAULT_ALLOCATOR\n\t#define EASTL_LRUCACHE_DEFAULT_ALLOCATOR allocator_type(EASTL_LRUCACHE_DEFAULT_NAME)\n\t#endif\n\n\t/// lru_cache\n\t///\n\t/// Implements a caching map based off of a key and data.\n\t/// LRUList parameter is any container that guarantees the validity of its iterator even after a modification (e.g. list)\n\t/// LRUMap is any associative container that can map a key to some data. By default, we use unordered_map, but it might be better\n\t/// to use hash_map or some other structure depending on your key/data combination. For example, you may want to swap the \n\t/// map backing if using strings as keys or if the data objects are small. In any case, unordered_map is a good default and should\n\t/// work well enough since the purpose of this class is to cache results of expensive, order of milliseconds, operations\n\t///\n\t/// Algorithmic Performance (default data structures):\n\t///\t\ttouch() -> O(1)\n\t///\t\tinsert() / update(), get() / operator[] -> equivalent to unordered_map (O(1) on average, O(n) worst)\n\t///\t\tsize() -> O(1)\n\t///\n\t/// All accesses to a given key (insert, update, get) will push that key to most recently used.\n\t/// If the data objects are shared between threads, it would be best to use a smartptr to manage the lifetime of the data.\n\t/// as it could be removed from the cache while in use by another thread.\n\ttemplate ,\n\t typename map_type = eastl::unordered_map,\n\t eastl::hash,\n\t eastl::equal_to,\n\t Allocator>>\n\tclass lru_cache\n\t{\n\tpublic:\n\t\tusing key_type = Key;\n\t\tusing value_type = Value;\n\t\tusing allocator_type = Allocator;\n\t\tusing size_type = eastl_size_t;\n\t\tusing list_iterator = typename list_type::iterator;\n\t\tusing map_iterator = typename map_type::iterator;\n\t\tusing data_container_type = eastl::pair;\n\t\tusing iterator = typename map_type::iterator;\n\t\tusing const_iterator = typename map_type::const_iterator;\n\t\tusing this_type = lru_cache;\n\t\tusing create_callback_type = eastl::function;\n\t\tusing delete_callback_type = eastl::function;\n\n\t\t/// lru_cache constructor\n\t\t///\n\t\t/// Creates a Key / Value map that only stores size Value objects until it deletes them.\n\t\t/// For complex objects or operations, the creator and deletor callbacks can be used.\n\t\t/// This works just like a regular map object: on access, the Value will be created if it doesn't exist, returned otherwise.\n\t\texplicit lru_cache(size_type size,\n\t\t const allocator_type& allocator = EASTL_LRUCACHE_DEFAULT_ALLOCATOR,\n\t\t create_callback_type creator = nullptr,\n\t\t delete_callback_type deletor = nullptr)\n\t\t : m_list(allocator)\n\t\t , m_map(allocator)\n\t\t , m_capacity(size)\n\t\t , m_create_callback(creator)\n\t\t , m_delete_callback(deletor)\n\t\t{\n\t\t}\n\n\t\t/// lru_cache destructor\n\t\t///\n\t\t/// Iterates across every entry in the map and calls the deletor before calling the standard destructors\n\t\t~lru_cache()\n\t\t{\n\t\t\t// Destruct everything we have cached\n\t\t\tfor (auto& iter : m_map)\n\t\t\t{\n\t\t\t\tif (m_delete_callback)\n\t\t\t\t\tm_delete_callback(iter.second.first);\n\t\t\t}\n\t\t}\n\n\t\tlru_cache(std::initializer_list> il)\n\t\t\t: lru_cache(static_cast(il.size()))\n\t\t{\n\t\t\tfor(auto& p : il)\n\t\t\t\tinsert_or_assign(p.first, p.second);\n\t\t}\n\n\t\t// TODO(rparolin): Why do we prevent copies? And what about moves?\n\t\tlru_cache(const this_type&) = delete;\n\t\tthis_type &operator=(const this_type&) = delete;\n\n\t\t/// insert\n\t\t/// \n\t\t/// insert key k with value v.\n\t\t/// If key already exists, no change is made and the return value is false.\n\t\t/// If the key doesn't exist, the data is added to the map and the return value is true.\n\t\tbool insert(const key_type& k, const value_type& v)\n\t\t{\n\t\t\tif (m_map.find(k) == m_map.end())\n\t\t\t{\n\t\t\t\tmake_space();\n\n\t\t\t\tm_list.push_front(k);\n\t\t\t\tm_map[k] = data_container_type(v, m_list.begin());\n\n\t\t\t\treturn true;\n\t\t\t}\n\t\t\telse\n\t\t\t{\n\t\t\t\treturn false;\n\t\t\t}\n\t\t}\n\n\t\t/// emplace\n\t\t/// \n\t\t/// Places a new object in place k created with args\n\t\t/// If the key already exists, no change is made.\n\t\t/// return value is a pair of the iterator to the emplaced or already-existing element and a bool denoting whether insertion took place.\n\t\ttemplate \n\t\teastl::pair emplace(const key_type& k, Args&&... args)\n\t\t{\n\t\t\tauto it = m_map.find(k);\n\t\t\tif (it == m_map.end())\n\t\t\t{\n\t\t\t\tmake_space();\n\n\t\t\t\tm_list.push_front(k);\n\t\t\t\treturn m_map.emplace(k, data_container_type(piecewise_construct, eastl::forward_as_tuple(eastl::forward(args)...), make_tuple(m_list.begin())));\n\t\t\t}\n\t\t\telse\n\t\t\t{\n\t\t\t\treturn make_pair(it, false);\n\t\t\t}\n\t\t}\n\n\t\t/// insert_or_assign\n\t\t///\n\t\t/// Same as add, but replaces the data at key k, if it exists, with the new entry v\n\t\t/// Note that the deletor for the old v will be called before it's replaced with the new value of v\n\t\tvoid insert_or_assign(const key_type& k, const value_type& v)\n\t\t{\n\t\t\tauto iter = m_map.find(k);\n\n\t\t\tif (m_map.find(k) != m_map.end())\n\t\t\t{\n\t\t\t\tassign(iter, v);\n\t\t\t}\n\t\t\telse\n\t\t\t{\n\t\t\t\tinsert(k, v);\n\t\t\t}\n\t\t}\n\n\t\t/// contains\n\t\t/// \n\t\t/// Returns true if key k exists in the cache\n\t\tbool contains(const key_type& k) const\n\t\t{\n\t\t\treturn m_map.find(k) != m_map.end();\n\t\t}\n\n\t\t/// at\n\t\t///\n\t\t/// Retrives the data for key k, not valid if k does not exist\n\t\teastl::optional at(const key_type& k)\n\t\t{\n\t\t\tauto iter = m_map.find(k);\n\n\t\t\tif (iter != m_map.end())\n\t\t\t{\n\t\t\t\treturn iter->second.first;\n\t\t\t}\n\t\t\telse\n\t\t\t{\n\t\t\t\treturn eastl::nullopt;\n\t\t\t}\n\t\t}\n\n\t\t/// get\n\t\t///\n\t\t/// Retrives the data for key k. If no data exists, it will be created by calling the\n\t\t/// creator.\n\t\tvalue_type& get(const key_type& k)\n\t\t{\n\t\t\tauto iter = m_map.find(k);\n\n\t\t\t// The entry exists in the cache\n\t\t\tif (iter != m_map.end())\n\t\t\t{\n\t\t\t\ttouch(k);\n\t\t\t\treturn iter->second.first;\n\t\t\t}\n\t\t\telse // The entry doesn't exist in the cache, so create one\n\t\t\t{\n\t\t\t\t// Add the entry to the map\n\t\t\t\tinsert(k, m_create_callback ? m_create_callback(k) : value_type());\n\n\t\t\t\t// return the new data\n\t\t\t\treturn m_map[k].first;\n\t\t\t}\n\t\t}\n\n\t\t/// Equivalent to get(k)\n\t\tvalue_type& operator[](const key_type& k) { return get(k); }\n\n\t\t/// erase\n\t\t///\n\t\t/// erases key k from the cache.\n\t\t/// If k does not exist, returns false. If k exists, returns true.\n\t\tbool erase(const key_type& k)\n\t\t{\n\t\t\tauto iter = m_map.find(k);\n\n\t\t\tif (iter != m_map.end())\n\t\t\t{\n\t\t\t\tm_list.erase(iter->second.second);\n\n\t\t\t\t// Delete the actual entry\n\t\t\t\tmap_erase(iter);\n\n\t\t\t\treturn true;\n\t\t\t}\n\n\t\t\treturn false;\n\t\t}\n\n\t\t/// erase_oldest\n\t\t///\n\t\t/// Removes the oldest entry from the cache.\n\t\tvoid erase_oldest()\n\t\t{\n\t\t\tauto key = m_list.back();\n\t\t\tm_list.pop_back();\n\n\t\t\t// Delete the actual entry\n\t\t\tauto iter = m_map.find(key);\n\t\t\tmap_erase(iter);\n\t\t}\n\n\t\t/// touch\n\t\t///\n\t\t/// Touches key k, marking it as most recently used.\n\t\t/// If k does not exist, returns false. If the touch was successful, returns true.\n\t\tbool touch(const key_type& k)\n\t\t{\n\t\t\tauto iter = m_map.find(k);\n\n\t\t\tif (iter != m_map.end())\n\t\t\t{\n\t\t\t\ttouch(iter);\n\t\t\t\treturn true;\n\t\t\t}\n\n\t\t\treturn false;\n\t\t}\n\n\t\t/// touch\n\t\t///\n\t\t/// Touches key at iterator iter, moving it to most recently used position\n\t\tvoid touch(iterator& iter)\n\t\t{\n\t\t\tauto listRef = iter->second.second;\n\n\t\t\tm_list.erase(listRef);\n\t\t\tm_list.push_front(iter->first);\n\t\t\titer->second.second = m_list.begin();\n\t\t}\n\n\t\t/// assign\n\t\t///\n\t\t/// Updates key k with data v.\n\t\t/// If key k does not exist, returns false and no changes are made.\n\t\t/// If key k exists, existing data has its deletor called and key k's data is replaced with new v data\n\t\tbool assign(const key_type& k, const value_type& v)\n\t\t{\n\t\t\tauto iter = m_map.find(k);\n\n\t\t\tif (iter != m_map.end())\n\t\t\t{\n\t\t\t\tassign(iter, v);\n\t\t\t\treturn true;\n\t\t\t}\n\n\t\t\treturn false;\n\t\t}\n\n\t\t/// assign\n\t\t///\n\t\t/// Updates data at spot iter with data v.\n\t\tvoid assign(iterator& iter, const value_type& v)\n\t\t{\n\t\t\tif (m_delete_callback)\n\t\t\t\tm_delete_callback(iter->second.first);\n\t\t\ttouch(iter);\n\t\t\titer->second.first = v;\n\t\t}\n\n\t\t// standard container functions\n\t\titerator begin() EA_NOEXCEPT { return m_map.begin(); }\n\t\titerator end() EA_NOEXCEPT { return m_map.end(); }\n\t\titerator rbegin() EA_NOEXCEPT { return m_map.rbegin(); }\n\t\titerator rend() EA_NOEXCEPT { return m_map.rend(); }\n\t\tconst_iterator begin() const EA_NOEXCEPT { return m_map.begin(); }\n\t\tconst_iterator cbegin() const EA_NOEXCEPT { return m_map.cbegin(); }\n\t\tconst_iterator crbegin() const EA_NOEXCEPT { return m_map.crbegin(); }\n\t\tconst_iterator end() const EA_NOEXCEPT { return m_map.end(); }\n\t\tconst_iterator cend() const EA_NOEXCEPT { return m_map.cend(); }\n\t\tconst_iterator crend() const EA_NOEXCEPT { return m_map.crend(); }\n\n\t\tbool empty() const EA_NOEXCEPT { return m_map.empty(); }\n\t\tsize_type size() const EA_NOEXCEPT { return m_map.size(); }\n\t\tsize_type capacity() const EA_NOEXCEPT { return m_capacity; }\n\n\t\tvoid clear() EA_NOEXCEPT\n\t\t{\n\t\t\t// Since we have a delete callback, we want to reuse the trim function by cheating the max\n\t\t\t// size to clear all the entries to avoid duplicating code.\n\t\t\tauto old_max = m_capacity;\n\n\t\t\tm_capacity = 0;\n\t\t\ttrim();\n\t\t\tm_capacity = old_max;\n\t\t}\n\n\t\t/// resize\n\t\t///\n\t\t/// Resizes the cache. Can be used to either expand or contract the cache.\n\t\t/// In the case of a contraction, the oldest entries will be evicted with their respective\n\t\t/// deletors called before completing.\n\t\tvoid resize(size_type newSize)\t\n\t\t{\n\t\t\tm_capacity = newSize;\n\t\t\ttrim();\n\t\t}\n\t\t\n\t\tvoid setCreateCallback(create_callback_type callback) { m_create_callback = callback; }\n\t\tvoid setDeleteCallback(delete_callback_type callback) { m_delete_callback = callback; }\n\n\t\t// EASTL extensions\n\t\tconst allocator_type& get_allocator() const EA_NOEXCEPT\t\t\t\t\t{ return m_map.get_allocator(); }\n\t\tallocator_type& get_allocator() EA_NOEXCEPT\t\t\t\t\t\t{ return m_map.get_allocator(); }\n\t\tvoid set_allocator(const allocator_type& allocator)\t{ m_map.set_allocator(allocator); m_list.set_allocator(allocator); }\n\n\t\t/// Does not reset the callbacks\n\t\tvoid reset_lose_memory() EA_NOEXCEPT\t\t\t\t\t\t\t\t\t{ m_map.reset_lose_memory(); m_list.reset_lose_memory(); }\n\n\tprivate:\n\t\tinline void map_erase(map_iterator pos)\n\t\t{\n\t\t\tif (m_delete_callback)\n\t\t\t\tm_delete_callback(pos->second.first);\n\t\t\tm_map.erase(pos);\n\t\t}\n\t\t\n\t\tbool trim()\n\t\t{\n\t\t\tif (size() <= m_capacity)\n\t\t\t{\n\t\t\t\treturn false; // No trim necessary\n\t\t\t}\n\n\t\t\t// We need to trim\n\t\t\tdo\n\t\t\t{\n\t\t\t\terase_oldest();\n\t\t\t} while (m_list.size() > m_capacity);\n\n\t\t\treturn true;\n\t\t}\n\n\t\tvoid make_space()\n\t\t{\n\t\t\tif (size() == m_capacity)\n\t\t\t{\n\t\t\t\terase_oldest();\n\t\t\t}\n\t\t}\n\n\tprivate:\n\t\tlist_type\t\t\t\tm_list;\n\t\tmap_type\t\t\t\tm_map;\n\t\tsize_type\t\t\t\tm_capacity;\n\t\tcreate_callback_type\tm_create_callback;\n\t\tdelete_callback_type\tm_delete_callback;\n\t};\n}\n\n\n\n#endif\n" }, { "path": "include/EASTL/bonus/overloaded.h", "content": "/////////////////////////////////////////////////////////////////////////////\n// Copyright (c) Electronic Arts Inc. All rights reserved.\n/////////////////////////////////////////////////////////////////////////////\n\n#ifndef EASTL_OVERLOADED_H\n#define EASTL_OVERLOADED_H\n\n#include \n#include \n\n\n#if defined(EA_PRAGMA_ONCE_SUPPORTED)\n#pragma once // Some compilers (e.g. VC++) benefit significantly from using this. We've measured 3-4% build speed\n\t\t\t // improvements in apps as a result.\n#endif\n\n// 4512/4626 - 'class' : assignment operator could not be generated. // This disabling would best be put elsewhere.\nEA_DISABLE_VC_WARNING(4512 4626);\n\nnamespace eastl\n{\n\t///////////////////////////////////////////////////////////////////////////\n\t/// overloaded\n\t/// \n\t/// A helper class that permits you to combine multiple function objects into one.\n\t/// Typically, this helper is really handy when visiting an eastl::variant with multiple lambdas.\n\t/// Example:\n\t///\n\t/// eastl::variant v{42};\n\t/// \n\t/// eastl::visit(\n\t///\t eastl::overloaded{\n\t///\t\t [](const int& x) { std::cout << \"Visited an integer: \" << x << \"\\n\"; }, // Will reach that lambda with x == 42.\n\t///\t\t [](const string& s) { std::cout << \"Visited an string: \" << s << \"\\n\"; }\n\t///\t },\n\t///\t v\n\t/// );\n\t///////////////////////////////////////////////////////////////////////////\n\ttemplate \n\tstruct overloaded;\n\n\ttemplate \n\tstruct overloaded : T\n\t{\n\t\ttemplate \n\t\tEA_CPP14_CONSTEXPR overloaded(U&& u) : T(eastl::forward(u))\n\t\t{\n\t\t}\n\n\t\tusing T::operator();\n\t};\n\n\ttemplate \n\tstruct overloaded : T, overloaded\n\t{\n\t\ttemplate \n\t\tEA_CPP14_CONSTEXPR overloaded(U&& u, V&&... v) : T(eastl::forward(u)), overloaded(eastl::forward(v)...)\n\t\t{\n\t\t}\n\n\t\tusing T::operator();\n\t\tusing overloaded::operator();\n\t};\n\n\t#ifdef __cpp_deduction_guides\n\ttemplate \n\toverloaded(T...) -> overloaded;\n\t#endif\n\n\t///////////////////////////////////////////////////////////////////////////\n\t/// make_overloaded\n\t///\n\t/// Helper function to create an overloaded instance when lacking deduction guides.\n\t/// make_overloaded(f1, f2, f3) == overloaded{f1, f2, f3}\n\t///////////////////////////////////////////////////////////////////////////\n\ttemplate \n\tEA_CPP14_CONSTEXPR overloaded::type...> make_overloaded(T&&... t)\n\t{\n\t\treturn overloaded::type...>{eastl::forward(t)...};\n\t}\n\n} // namespace eastl\n\nEA_RESTORE_VC_WARNING();\n\n#endif // EASTL_OVERLOADED_H\n" }, { "path": "include/EASTL/bonus/ring_buffer.h", "content": "/////////////////////////////////////////////////////////////////////////////\n// Copyright (c) Electronic Arts Inc. All rights reserved.\n/////////////////////////////////////////////////////////////////////////////\n\n///////////////////////////////////////////////////////////////////////////////\n// A ring buffer is a FIFO (first-in, first-out) container which acts\n// much like a queue. The difference is that a ring buffer is implemented\n// via chasing pointers around a given container instead of like queue\n// adds to the writes to the end of the container are reads from the begin.\n// The benefit of a ring buffer is that memory allocations don't occur\n// and new elements are neither added nor removed from the container.\n// Elements in the container are simply assigned values in circles around\n// the container.\n///////////////////////////////////////////////////////////////////////////////\n\n\n#ifndef EASTL_RING_BUFFER_H\n#define EASTL_RING_BUFFER_H\n\n\n#include \n#include \n#include \n#include \n#include \n\n#if defined(EA_PRAGMA_ONCE_SUPPORTED)\n\t#pragma once // Some compilers (e.g. VC++) benefit significantly from using this. We've measured 3-4% build speed improvements in apps as a result.\n#endif\n\n\n\nnamespace eastl\n{\n\t/// EASTL_RING_BUFFER_DEFAULT_NAME\n\t///\n\t/// Defines a default container name in the absence of a user-provided name.\n\t///\n\t#ifndef EASTL_RING_BUFFER_DEFAULT_NAME\n\t\t#define EASTL_RING_BUFFER_DEFAULT_NAME EASTL_DEFAULT_NAME_PREFIX \" ring_buffer\" // Unless the user overrides something, this is \"EASTL ring_buffer\".\n\t#endif\n\n\t/// EASTL_RING_BUFFER_DEFAULT_ALLOCATOR\n\t///\n\t#ifndef EASTL_RING_BUFFER_DEFAULT_ALLOCATOR\n\t\t#define EASTL_RING_BUFFER_DEFAULT_ALLOCATOR allocator_type(EASTL_RING_BUFFER_DEFAULT_NAME)\n\t#endif\n\n\n\t/// ring_buffer_iterator\n\t///\n\t/// We force this iterator to act like a random access iterator even if \n\t/// the underlying container doesn't support random access iteration.\n\t/// Any BidirectionalIterator can be a RandomAccessIterator; it just\n\t/// might be inefficient in some cases.\n\t///\n\ttemplate \n\tstruct ring_buffer_iterator\n\t{\n\tpublic:\n\t\ttypedef ring_buffer_iterator this_type;\n\t\ttypedef T value_type;\n\t\ttypedef Pointer pointer;\n\t\ttypedef Reference reference;\n\t\ttypedef typename Container::size_type size_type;\n\t\ttypedef typename Container::difference_type difference_type;\n\t\ttypedef typename Container::iterator container_iterator;\n\t\ttypedef typename Container::const_iterator container_const_iterator;\n\t\ttypedef ring_buffer_iterator iterator;\n\t\ttypedef ring_buffer_iterator const_iterator;\n\t\ttypedef eastl::random_access_iterator_tag iterator_category;\n\n\tpublic:\n\t\tContainer* mpContainer;\n\t\tcontainer_iterator mContainerIterator;\n\n\tpublic:\n\t\tring_buffer_iterator();\n\t\tring_buffer_iterator(Container* pContainer, const container_iterator& containerIterator);\n\t\tring_buffer_iterator(const iterator& x);\n\n\t\tring_buffer_iterator& operator=(const iterator& x);\n\n\t\treference operator*() const;\n\t\tpointer operator->() const;\n\n\t\tthis_type& operator++();\n\t\tthis_type operator++(int);\n\n\t\tthis_type& operator--();\n\t\tthis_type operator--(int);\n\n\t\tthis_type& operator+=(difference_type n);\n\t\tthis_type& operator-=(difference_type n);\n\n\t\tthis_type operator+(difference_type n) const;\n\t\tthis_type operator-(difference_type n) const;\n\n\tprotected:\n\t\tvoid increment(difference_type n, eastl::input_iterator_tag);\n\t\tvoid increment(difference_type n, eastl::random_access_iterator_tag);\n\n\t}; // struct ring_buffer_iterator\n\n\n\n\t/// ring_buffer\n\t///\n\t/// Implements a ring buffer via a given container type, which would \n\t/// typically be a vector or array, though any container which supports \n\t/// bidirectional iteration would work.\n\t///\n\t/// A ring buffer is a FIFO (first-in, first-out) container which acts\n\t/// much like a queue. The difference is that a ring buffer is implemented\n\t/// via chasing pointers around a container and moving the read and write\n\t/// positions forward (and possibly wrapping around) as the container is \n\t/// read and written via pop_front and push_back.\n\t///\n\t/// The benefit of a ring buffer is that memory allocations don't occur\n\t/// and new elements are neither added nor removed from the container.\n\t/// Elements in the container are simply assigned values in circles around\n\t/// the container.\n\t/// \n\t/// ring_buffer is different from other containers -- including adapter\n\t/// containers -- in how iteration is done. Iteration of a ring buffer\n\t/// starts at the current begin position, proceeds to the end of the underlying\n\t/// container, and continues at the begin of the underlying container until\n\t/// the ring buffer's current end position. Thus a ring_buffer does \n\t/// indeed have a begin and an end, though the values of begin and end \n\t/// chase each other around the container. An empty ring_buffer is one \n\t/// in which end == begin, and a full ring_buffer is one in which \n\t/// end + 1 == begin. \n\t///\n\t/// Example of a ring buffer layout, where + indicates queued items:\n\t/// ++++++++++--------------------------------+++++++++\n\t/// ^ ^\n\t/// end begin\n\t///\n\t/// Empty ring buffer:\n\t/// ---------------------------------------------------\n\t/// ^\n\t/// begin / end\n\t///\n\t/// Full ring buffer. Note that one item is necessarily unused; it is \n\t/// analagous to a '\\0' at the end of a C string:\n\t/// +++++++++++++++++++++++++++++++++++++++++-+++++++++\n\t/// ^^\n\t/// end begin\n\t///\n\t/// A push_back operation on a ring buffer assigns the new value to end. \n\t/// If there is no more space in the buffer, this will result in begin\n\t/// being overwritten and the begin position being moved foward one position.\n\t/// The user can use the full() function to detect this condition.\n\t/// Note that elements in a ring buffer are not created or destroyed as \n\t/// their are added and removed; they are merely assigned. Only on \n\t/// container construction and destruction are any elements created and \n\t/// destroyed.\n\t///\n\t/// The ring buffer can be used in either direction. By this we mean that \n\t/// you can use push_back to add items and pop_front to remove them; or you can\n\t/// use push_front to add items and pop_back to remove them. You aren't \n\t/// limited to these operations; you can push or pop from either side\n\t/// arbitrarily and you can insert or erase anywhere in the container.\n\t///\n\t/// The ring buffer requires the user to specify a Container type, which \n\t/// by default is vector. However, any container with bidirectional iterators\n\t/// will work, such as list, deque, string or any of the fixed_* versions\n\t/// of these containers, such as fixed_string. Since ring buffer works via copying\n\t/// elements instead of allocating and freeing nodes, inserting in the middle\n\t/// of a ring buffer based on list (instead of vector) is no more efficient.\n\t///\n\t/// To use the ring buffer, its container must be resized to the desired\n\t/// ring buffer size. Changing the size of a ring buffer may cause ring\n\t/// buffer iterators to invalidate.\n\t///\n\t/// An alternative to using a ring buffer is to use a list with a user-created \n\t/// node pool and custom allocator. There are various tradeoffs that result from this.\n\t///\n\t/// Example usage:\n\t/// ring_buffer< int, list > rb(100);\n\t/// rb.push_back(1);\n\t/// \n\t/// Example usage:\n\t/// // Example of creating an on-screen debug log that shows 16 \n\t/// // strings at a time and scrolls older strings away.\n\t///\n\t/// // Create ring buffer of 16 strings.\n\t/// ring_buffer< string, vector > debugLogText(16);\n\t/// \n\t/// // Reserve 128 chars for each line. This can make it so that no \n\t/// // runtime memory allocations occur.\n\t/// for(vector::iterator it = debugLogText.get_container().begin(),\n\t/// itEnd = debugLogText.get_container().end(); it != itEnd; ++it)\n\t/// {\n\t/// (*it).reserve(128);\n\t/// }\n\t/// \n\t/// // Add a new string, using push_front() and front() instead of \n\t/// // push_front(str) in order to avoid creating a temporary str.\n\t/// debugLogText.push_front();\n\t/// debugLogText.front() = \"Player fired weapon\";\n\t///\n\ttemplate , typename Allocator = typename Container::allocator_type>\n\tclass ring_buffer\n\t{\n\tpublic:\n\t\ttypedef ring_buffer this_type;\n\t\ttypedef Container container_type;\n\t\ttypedef Allocator allocator_type;\n\n\t\ttypedef typename Container::value_type value_type;\n\t\ttypedef typename Container::reference reference;\n\t\ttypedef typename Container::const_reference const_reference;\n\t\ttypedef typename Container::size_type size_type;\n\t\ttypedef typename Container::difference_type difference_type;\n\t\ttypedef typename Container::iterator container_iterator;\n\t\ttypedef typename Container::const_iterator container_const_iterator;\n\t\ttypedef ring_buffer_iterator iterator;\n\t\ttypedef ring_buffer_iterator const_iterator;\n\t\ttypedef eastl::reverse_iterator reverse_iterator;\n\t\ttypedef eastl::reverse_iterator const_reverse_iterator; \n\n\tpublic: // We declare public so that global comparison operators can be implemented without adding an inline level and without tripping up GCC 2.x friend declaration failures. GCC (through at least v4.0) is poor at inlining and performance wins over correctness.\n\t\tContainer c; // We follow the naming convention established for stack, queue, priority_queue and name this 'c'. This variable must always have a size of at least 1, as even an empty ring_buffer has an unused terminating element.\n\n\tprotected:\n\t\tcontainer_iterator mBegin; // We keep track of where our begin and end are by using Container iterators. \n\t\tcontainer_iterator mEnd;\n\t\tsize_type mSize;\n\n\tpublic:\n\t\t// There currently isn't a ring_buffer constructor that specifies an initial size, unlike other containers.\n\t\texplicit ring_buffer(size_type cap = 0); // Construct with an initial capacity (but size of 0).\n\t\texplicit ring_buffer(size_type cap, const allocator_type& allocator); \n\t\texplicit ring_buffer(const Container& x);\n\t\texplicit ring_buffer(const allocator_type& allocator);\n\t\tring_buffer(const this_type& x);\n\t\tring_buffer(this_type&& x);\n\t\tring_buffer(this_type&& x, const allocator_type& allocator);\n\t\tring_buffer(std::initializer_list ilist, const allocator_type& allocator = EASTL_RING_BUFFER_DEFAULT_ALLOCATOR); // This function sets the capacity to be equal to the size of the initializer list.\n\n\t\t// No destructor necessary. Default will do.\n\n\t\tthis_type& operator=(const this_type& x);\n\t\tthis_type& operator=(std::initializer_list ilist);\n\t\tthis_type& operator=(this_type&& x);\n\n\t\ttemplate \n\t\tvoid assign(InputIterator first, InputIterator last);\n\n\t\tvoid swap(this_type& x);\n\n\t\titerator begin() EA_NOEXCEPT;\n\t\tconst_iterator begin() const EA_NOEXCEPT;\n\t\tconst_iterator cbegin() const EA_NOEXCEPT;\n\n\t\titerator end() EA_NOEXCEPT;\n\t\tconst_iterator end() const EA_NOEXCEPT;\n\t\tconst_iterator cend() const EA_NOEXCEPT;\n\n\t\treverse_iterator rbegin() EA_NOEXCEPT;\n\t\tconst_reverse_iterator rbegin() const EA_NOEXCEPT;\n\t\tconst_reverse_iterator crbegin() const EA_NOEXCEPT;\n\n\t\treverse_iterator rend() EA_NOEXCEPT;\n\t\tconst_reverse_iterator rend() const EA_NOEXCEPT;\n\t\tconst_reverse_iterator crend() const EA_NOEXCEPT;\n\n\t\tbool empty() const EA_NOEXCEPT;\n\t\tbool full() const EA_NOEXCEPT;\n\t\tsize_type size() const EA_NOEXCEPT;\n\t\tsize_type capacity() const EA_NOEXCEPT;\n\n\t\tvoid resize(size_type n);\n\t\tvoid set_capacity(size_type n); // Sets the capacity to the given value, including values less than the current capacity. Adjusts the size downward if n < size, by throwing out the oldest elements in the buffer.\n\t\tvoid reserve(size_type n); // Reserve a given capacity. Doesn't decrease the capacity; it only increases it (for compatibility with other containers' behavior).\n\n\t\treference front();\n\t\tconst_reference front() const;\n\n\t\treference back(); \n\t\tconst_reference back() const;\n\n\t\tvoid push_back(const value_type& value);\n\t\treference push_back();\n\n\t\tvoid push_front(const value_type& value);\n\t\treference push_front();\n\n\t\tvoid pop_back();\n\t\tvoid pop_front();\n\n\t\treference operator[](size_type n);\n\t\tconst_reference operator[](size_type n) const;\n\n\t\t// To consider:\n\t\t// size_type read(value_type* pDestination, size_type nCount);\n\t\t// size_type read(iterator** pPosition1, iterator** pPosition2, size_type& nCount1, size_type& nCount2);\n\n\t\t/* To do:\n\t\t\ttemplate \n\t\t\treference emplace_front(Args&&... args);\n\n\t\t\ttemplate \n\t\t\treference emplace_back(Args&&... args);\n\n\t\t\ttemplate \n\t\t\titerator emplace(const_iterator position, Args&&... args);\n\t\t*/\n\n\t\titerator insert(const_iterator position, const value_type& value);\n\t\tvoid insert(const_iterator position, size_type n, const value_type& value);\n\t\tvoid insert(const_iterator position, std::initializer_list ilist);\n\n\t\ttemplate \n\t\tvoid insert(const_iterator position, InputIterator first, InputIterator last);\n\n\t\titerator erase(const_iterator position);\n\t\titerator erase(const_iterator first, const_iterator last);\n\t\treverse_iterator erase(const_reverse_iterator position);\n\t\treverse_iterator erase(const_reverse_iterator first, const_reverse_iterator last);\n\n\t\tvoid clear();\n\n\t\tcontainer_type& get_container();\n\t\tconst container_type& get_container() const;\n\n\t\tbool validate() const;\n\t\tint validate_iterator(const_iterator i) const;\n\n\tprotected:\n\t\t//size_type DoGetSize(eastl::input_iterator_tag) const;\n\t\t//size_type DoGetSize(eastl::random_access_iterator_tag) const;\n\n\t}; // class ring_buffer\n\n\n\n\n\t///////////////////////////////////////////////////////////////////////\n\t// ring_buffer_iterator\n\t///////////////////////////////////////////////////////////////////////\n\n\ttemplate \n\tring_buffer_iterator::ring_buffer_iterator()\n\t\t: mpContainer(NULL), mContainerIterator()\n\t{\n\t}\n\n\n\ttemplate \n\tring_buffer_iterator::ring_buffer_iterator(Container* pContainer, const container_iterator& containerIterator)\n\t\t: mpContainer(pContainer), mContainerIterator(containerIterator)\n\t{\n\t}\n\n\n\ttemplate \n\tring_buffer_iterator::ring_buffer_iterator(const iterator& x)\n\t\t: mpContainer(x.mpContainer), mContainerIterator(x.mContainerIterator)\n\t{\n\t}\n\n\n\ttemplate \n\tring_buffer_iterator& \n\tring_buffer_iterator::operator=(const iterator& x)\n\t{\n\t\tmpContainer = x.mpContainer;\n\t\tmContainerIterator = x.mContainerIterator;\n\t\treturn *this;\n\t}\n\n\ttemplate \n\ttypename ring_buffer_iterator::reference\n\tring_buffer_iterator::operator*() const\n\t{\n\t\treturn *mContainerIterator;\n\t}\n\n\n\ttemplate \n\ttypename ring_buffer_iterator::pointer\n\tring_buffer_iterator::operator->() const\n\t{\n\t\treturn &*mContainerIterator;\n\t}\n\n\n\ttemplate \n\ttypename ring_buffer_iterator::this_type&\n\tring_buffer_iterator::operator++()\n\t{\n\t\tif(EASTL_UNLIKELY(++mContainerIterator == mpContainer->end()))\n\t\t\tmContainerIterator = mpContainer->begin();\n\t\treturn *this;\n\t}\n\n\n\ttemplate \n\ttypename ring_buffer_iterator::this_type\n\tring_buffer_iterator::operator++(int)\n\t{\n\t\tconst this_type temp(*this);\n\t\tif(EASTL_UNLIKELY(++mContainerIterator == mpContainer->end()))\n\t\t\tmContainerIterator = mpContainer->begin();\n\t\treturn temp;\n\t}\n\n\n\ttemplate \n\ttypename ring_buffer_iterator::this_type&\n\tring_buffer_iterator::operator--()\n\t{\n\t\tif(EASTL_UNLIKELY(mContainerIterator == mpContainer->begin()))\n\t\t\tmContainerIterator = mpContainer->end();\n\t\t--mContainerIterator;\n\t\treturn *this;\n\t}\n\n\n\ttemplate \n\ttypename ring_buffer_iterator::this_type\n\tring_buffer_iterator::operator--(int)\n\t{\n\t\tconst this_type temp(*this);\n\t\tif(EASTL_UNLIKELY(mContainerIterator == mpContainer->begin()))\n\t\t\tmContainerIterator = mpContainer->end();\n\t\t--mContainerIterator;\n\t\treturn temp;\n\t}\n\n\n\ttemplate \n\ttypename ring_buffer_iterator::this_type&\n\tring_buffer_iterator::operator+=(difference_type n)\n\t{\n\t\ttypedef typename eastl::iterator_traits::iterator_category IC;\n\t\tincrement(n, IC());\n\t\treturn *this;\n\t}\n\n\n\ttemplate \n\ttypename ring_buffer_iterator::this_type&\n\tring_buffer_iterator::operator-=(difference_type n)\n\t{\n\t\ttypedef typename eastl::iterator_traits::iterator_category IC;\n\t\tincrement(-n, IC());\n\t\treturn *this;\n\t}\n\n\n\ttemplate \n\ttypename ring_buffer_iterator::this_type\n\tring_buffer_iterator::operator+(difference_type n) const\n\t{\n\t\treturn this_type(*this).operator+=(n);\n\t}\n\n\n\ttemplate \n\ttypename ring_buffer_iterator::this_type\n\tring_buffer_iterator::operator-(difference_type n) const\n\t{\n\t\treturn this_type(*this).operator+=(-n);\n\t}\n\n\n\ttemplate \n\tvoid ring_buffer_iterator::increment(difference_type n, eastl::input_iterator_tag)\n\t{\n\t\t// n cannot be negative, as input iterators don't support reverse iteration.\n\t\twhile(n-- > 0)\n\t\t\toperator++();\n\t}\n\n\n\ttemplate \n\tvoid ring_buffer_iterator::increment(difference_type n, eastl::random_access_iterator_tag)\n\t{\n\t\t// We make the assumption here that the user is incrementing from a valid\n\t\t// starting position to a valid ending position. Thus *this + n yields a \n\t\t// valid iterator, including if n happens to be a negative value.\n\n\t\tif(n >= 0)\n\t\t{\n\t\t\tconst difference_type d = mpContainer->end() - mContainerIterator;\n\n\t\t\tif(n < d)\n\t\t\t\tmContainerIterator += n;\n\t\t\telse\n\t\t\t\tmContainerIterator = mpContainer->begin() + (n - d);\n\t\t}\n\t\telse\n\t\t{\n\t\t\t// Recall that n and d here will be negative and so the logic here works as intended.\n\t\t\tconst difference_type d = mpContainer->begin() - mContainerIterator;\n\n\t\t\tif(n >= d)\n\t\t\t\tmContainerIterator += n;\n\t\t\telse\n\t\t\t\tmContainerIterator = mpContainer->end() + (n - d);\n\t\t}\n\t}\n\n\n\t// Random access iterators must support operator + and operator -.\n\t// You can only add an integer to an iterator, and you cannot add two iterators.\n\ttemplate \n\tinline ring_buffer_iterator\n\toperator+(ptrdiff_t n, const ring_buffer_iterator& x)\n\t{\n\t\treturn x + n; // Implement (n + x) in terms of (x + n).\n\t}\n\n\n\t// You can only add an integer to an iterator, but you can subtract two iterators.\n\ttemplate \n\tinline typename ring_buffer_iterator::difference_type\n\toperator-(const ring_buffer_iterator& a,\n\t\t\t const ring_buffer_iterator& b)\n\t{\n\t\ttypedef typename ring_buffer_iterator::difference_type difference_type;\n\n\t\t// To do: If container_iterator is a random access iterator, then do a simple calculation.\n\t\t// Otherwise, we have little choice but to iterate from a to b and count as we go.\n\t\t// See the ring_buffer::size function for an implementation of this.\n\n\t\t// Iteration implementation:\n\t\tdifference_type d = 0;\n\n\t\tfor(ring_buffer_iterator temp(b); temp != a; ++temp)\n\t\t\t++d;\n\n\t\treturn d;\n\t}\n\n\n\t// The C++ defect report #179 requires that we support comparisons between const and non-const iterators.\n\t// Thus we provide additional template paremeters here to support this. The defect report does not\n\t// require us to support comparisons between reverse_iterators and const_reverse_iterators.\n\ttemplate \n\tinline bool operator==(const ring_buffer_iterator& a, \n\t\t\t\t\t\t const ring_buffer_iterator& b)\n\t{\n\t\t// Perhaps we should compare the container pointer as well.\n\t\t// However, for valid iterators this shouldn't be necessary.\n\t\treturn a.mContainerIterator == b.mContainerIterator;\n\t}\n\n\n\ttemplate \n\tinline bool operator!=(const ring_buffer_iterator& a, \n\t\t\t\t\t\t const ring_buffer_iterator& b)\n\t{\n\t\t// Perhaps we should compare the container pointer as well.\n\t\t// However, for valid iterators this shouldn't be necessary.\n\t\treturn !(a.mContainerIterator == b.mContainerIterator);\n\t}\n\n\n\t// We provide a version of operator!= for the case where the iterators are of the \n\t// same type. This helps prevent ambiguity errors in the presence of rel_ops.\n\ttemplate \n\tinline bool operator!=(const ring_buffer_iterator& a, \n\t\t\t\t\t\t const ring_buffer_iterator& b)\n\t{\n\t\treturn !(a.mContainerIterator == b.mContainerIterator);\n\t}\n\n\n\n\n\t///////////////////////////////////////////////////////////////////////\n\t// ring_buffer\n\t///////////////////////////////////////////////////////////////////////\n\n\ttemplate \n\tring_buffer::ring_buffer(size_type cap)\n\t\t: c() // Default construction with default allocator for the container.\n\t{\n\t\t// To do: This code needs to be amended to deal with possible exceptions \n\t\t// that could occur during the resize call below.\n\n\t\t// We add one because the element at mEnd is necessarily unused.\n\t\tc.resize(cap + 1); // Possibly we could construct 'c' with size, but c may not have such a ctor, though we rely on it having a resize function. \n\t\tmBegin = c.begin();\n\t\tmEnd = mBegin;\n\t\tmSize = 0;\n\t}\n\n\n\ttemplate \n\tring_buffer::ring_buffer(size_type cap, const allocator_type& allocator)\n\t\t: c(allocator)\n\t{\n\t\t// To do: This code needs to be amended to deal with possible exceptions \n\t\t// that could occur during the resize call below.\n\n\t\t// We add one because the element at mEnd is necessarily unused.\n\t\tc.resize(cap + 1); // Possibly we could construct 'c' with size, but c may not have such a ctor, though we rely on it having a resize function. \n\t\tmBegin = c.begin();\n\t\tmEnd = mBegin;\n\t\tmSize = 0;\n\t}\n\n\n\ttemplate \n\tring_buffer::ring_buffer(const Container& x)\n\t\t: c(x) // This copies elements from x, but unless the user is doing some tricks, the only thing that matters is that c.size() == x.size().\n\t{\n\t\t// To do: This code needs to be amended to deal with possible exceptions \n\t\t// that could occur during the resize call below.\n\t\tif(c.empty())\n\t\t\tc.resize(1);\n\t\tmBegin = c.begin();\n\t\tmEnd = mBegin;\n\t\tmSize = 0;\n\t}\n\n\n\ttemplate \n\tring_buffer::ring_buffer(const allocator_type& allocator)\n\t\t: c(allocator)\n\t{\n\t\t// To do: This code needs to be amended to deal with possible exceptions \n\t\t// that could occur during the resize call below.\n\n\t\t// We add one because the element at mEnd is necessarily unused.\n\t\tc.resize(1); // Possibly we could construct 'c' with size, but c may not have such a ctor, though we rely on it having a resize function.\n\t\tmBegin = c.begin();\n\t\tmEnd = mBegin;\n\t\tmSize = 0;\n\t}\n\n\n\ttemplate \n\tring_buffer::ring_buffer(const this_type& x)\n\t\t: c(x.c)\n\t{\n\t\tmBegin = c.begin();\n\t\tmEnd = mBegin;\n\t\tmSize = x.mSize;\n\n\t\teastl::advance(mBegin, eastl::distance(const_cast(x).c.begin(), x.mBegin)); // We can do a simple distance algorithm here, as there will be no wraparound.\n\t\teastl::advance(mEnd, eastl::distance(const_cast(x).c.begin(), x.mEnd));\n\t}\n\n\ttemplate \n\tring_buffer::ring_buffer(this_type&& x)\n\t: c() // Default construction with default allocator for the container.\n\t{\n\t\tc.resize(1); // Possibly we could construct 'c' with size, but c may not have such a ctor, though we rely on it having a resize function.\n\t\tmBegin = c.begin();\n\t\tmEnd = mBegin;\n\t\tmSize = 0;\n\n\t\tswap(x); // We are leaving x in an unusual state by swapping default-initialized members with it, as it won't be usable and can be only destructible.\n\t}\n\n\ttemplate \n\tring_buffer::ring_buffer(this_type&& x, const allocator_type& allocator)\n\t\t: c(allocator)\n\t{\n\t\tc.resize(1); // Possibly we could construct 'c' with size, but c may not have such a ctor, though we rely on it having a resize function.\n\t\tmBegin = c.begin();\n\t\tmEnd = mBegin;\n\t\tmSize = 0;\n\n\t\tif(c.get_allocator() == x.c.get_allocator())\n\t\t\tswap(x); // We are leaving x in an unusual state by swapping default-initialized members with it, as it won't be usable and can be only destructible.\n\t\telse\n\t\t\toperator=(x);\n\t}\n\n\n\ttemplate \n\tring_buffer::ring_buffer(std::initializer_list ilist, const allocator_type& allocator)\n\t\t: c(allocator)\n\t{\n\t\tc.resize((eastl_size_t)ilist.size() + 1);\n\t\tmBegin = c.begin();\n\t\tmEnd = mBegin;\n\t\tmSize = 0;\n\n\t\tassign(ilist.begin(), ilist.end());\n\t}\n\n\n\ttemplate \n\ttypename ring_buffer::this_type&\n\tring_buffer::operator=(const this_type& x)\n\t{\n\t\tif(&x != this)\n\t\t{\n\t\t\tc = x.c;\n\n\t\t\tmBegin = c.begin();\n\t\t\tmEnd = mBegin;\n\t\t\tmSize = x.mSize;\n\n\t\t\teastl::advance(mBegin, eastl::distance(const_cast(x).c.begin(), x.mBegin)); // We can do a simple distance algorithm here, as there will be no wraparound.\n\t\t\teastl::advance(mEnd, eastl::distance(const_cast(x).c.begin(), x.mEnd));\n\t\t}\n\n\t\treturn *this;\n\t}\n\n\n\ttemplate \n\ttypename ring_buffer::this_type&\n\tring_buffer::operator=(this_type&& x)\n\t{\n\t\tswap(x);\n\t\treturn *this;\n\t}\n\n\n\ttemplate \n\ttypename ring_buffer::this_type&\n\tring_buffer::operator=(std::initializer_list ilist)\n\t{\n\t\tassign(ilist.begin(), ilist.end());\n\t\treturn *this;\n\t}\n\n\n\ttemplate \n\ttemplate \n\tvoid ring_buffer::assign(InputIterator first, InputIterator last)\n\t{\n\t\t// To consider: We can make specializations of this for pointer-based \n\t\t// iterators to PODs and turn the action into a memcpy.\n\t\tclear();\n\n\t\tfor(; first != last; ++first)\n\t\t\tpush_back(*first);\n\t}\n\n\n\ttemplate \n\tvoid ring_buffer::swap(this_type& x)\n\t{\n\t\tif(&x != this)\n\t\t{\n\t\t\tconst difference_type dBegin = eastl::distance(c.begin(), mBegin); // We can do a simple distance algorithm here, as there will be no wraparound.\n\t\t\tconst difference_type dEnd = eastl::distance(c.begin(), mEnd);\n\n\t\t\tconst difference_type dxBegin = eastl::distance(x.c.begin(), x.mBegin);\n\t\t\tconst difference_type dxEnd = eastl::distance(x.c.begin(), x.mEnd);\n\n\t\t\teastl::swap(c, x.c);\n\t\t\teastl::swap(mSize, x.mSize);\n\n\t\t\tmBegin = c.begin();\n\t\t\teastl::advance(mBegin, dxBegin); // We can do a simple advance algorithm here, as there will be no wraparound.\n\n\t\t\tmEnd = c.begin();\n\t\t\teastl::advance(mEnd, dxEnd);\n\n\t\t\tx.mBegin = x.c.begin();\n\t\t\teastl::advance(x.mBegin, dBegin);\n\n\t\t\tx.mEnd = x.c.begin();\n\t\t\teastl::advance(x.mEnd, dEnd);\n\t\t}\n\t}\n\n\n\ttemplate \n\ttypename ring_buffer::iterator\n\tring_buffer::begin() EA_NOEXCEPT\n\t{\n\t\treturn iterator(&c, mBegin);\n\t}\n\n\n\ttemplate \n\ttypename ring_buffer::const_iterator\n\tring_buffer::begin() const EA_NOEXCEPT\n\t{\n\t\treturn const_iterator(const_cast(&c), mBegin); // We trust that the const_iterator will respect const-ness.\n\t}\n\n\n\ttemplate \n\ttypename ring_buffer::const_iterator\n\tring_buffer::cbegin() const EA_NOEXCEPT\n\t{\n\t\treturn const_iterator(const_cast(&c), mBegin); // We trust that the const_iterator will respect const-ness.\n\t}\n\n\n\ttemplate \n\ttypename ring_buffer::iterator\n\tring_buffer::end() EA_NOEXCEPT\n\t{\n\t\treturn iterator(&c, mEnd);\n\t}\n\n\n\ttemplate \n\ttypename ring_buffer::const_iterator\n\tring_buffer::end() const EA_NOEXCEPT\n\t{\n\t\treturn const_iterator(const_cast(&c), mEnd); // We trust that the const_iterator will respect const-ness.\n\t}\n\n\n\ttemplate \n\ttypename ring_buffer::const_iterator\n\tring_buffer::cend() const EA_NOEXCEPT\n\t{\n\t\treturn const_iterator(const_cast(&c), mEnd); // We trust that the const_iterator will respect const-ness.\n\t}\n\n\n\ttemplate \n\ttypename ring_buffer::reverse_iterator \n\tring_buffer::rbegin() EA_NOEXCEPT\n\t{\n\t\treturn reverse_iterator(iterator(&c, mEnd));\n\t}\n\n\n\ttemplate \n\ttypename ring_buffer::const_reverse_iterator\n\tring_buffer::rbegin() const EA_NOEXCEPT\n\t{\n\t\treturn const_reverse_iterator(const_iterator(const_cast(&c), mEnd));\n\t}\n\n\n\ttemplate \n\ttypename ring_buffer::const_reverse_iterator\n\tring_buffer::crbegin() const EA_NOEXCEPT\n\t{\n\t\treturn const_reverse_iterator(const_iterator(const_cast(&c), mEnd));\n\t}\n\n\n\ttemplate \n\ttypename ring_buffer::reverse_iterator\n\tring_buffer::rend() EA_NOEXCEPT\n\t{\n\t\treturn reverse_iterator(iterator(&c, mBegin));\n\t}\n\n\n\ttemplate \n\ttypename ring_buffer::const_reverse_iterator\n\tring_buffer::rend() const EA_NOEXCEPT\n\t{\n\t\treturn const_reverse_iterator(const_iterator(const_cast(&c), mBegin));\n\t}\n\n\n\ttemplate \n\ttypename ring_buffer::const_reverse_iterator\n\tring_buffer::crend() const EA_NOEXCEPT\n\t{\n\t\treturn const_reverse_iterator(const_iterator(const_cast(&c), mBegin));\n\t}\n\n\n\ttemplate \n\tbool ring_buffer::empty() const EA_NOEXCEPT\n\t{\n\t\treturn mBegin == mEnd;\n\t}\n\n\n\ttemplate \n\tbool ring_buffer::full() const EA_NOEXCEPT\n\t{\n\t\t// Implementation that relies on c.size() being a fast operation:\n\t\t// return mSize == (c.size() - 1); // (c.size() - 1) == capacity(); we are attempting to reduce function calls.\n\n\t\t// Version that has constant speed guarantees, but is still pretty fast.\n\t\tconst_iterator afterEnd(end());\n\t\t++afterEnd;\n\t\treturn afterEnd.mContainerIterator == mBegin;\n\t}\n\n\n\ttemplate \n\ttypename ring_buffer::size_type\n\tring_buffer::size() const EA_NOEXCEPT\n\t{\n\t\treturn mSize;\n\n\t\t// Alternatives:\n\t\t// return eastl::distance(begin(), end());\n\t\t// return end() - begin(); // This is more direct than using distance().\n\t\t//typedef typename eastl::iterator_traits::iterator_category IC;\n\t\t//return DoGetSize(IC()); // This is more direct than using iterator math.\n\t}\n\n\n\t/*\n\ttemplate \n\ttypename ring_buffer::size_type\n\tring_buffer::DoGetSize(eastl::input_iterator_tag) const\n\t{\n\t\t// We could alternatively just use eastl::distance() here, but we happen to\n\t\t// know that such code would boil down to what we have here, and we might\n\t\t// as well remove function calls where possible. \n\t\tdifference_type d = 0;\n\n\t\tfor(const_iterator temp(begin()), tempEnd(end()); temp != tempEnd; ++temp)\n\t\t\t++d;\n\n\t\treturn (size_type)d;\n\t}\n\t*/\n\n\t/*\n\ttemplate \n\ttypename ring_buffer::size_type\n\tring_buffer::DoGetSize(eastl::random_access_iterator_tag) const\n\t{\n\t\t// A simpler but less efficient implementation fo this function would be:\n\t\t// return eastl::distance(mBegin, mEnd);\n\t\t//\n\t\t// The calculation of distance here takes advantage of the fact that random\n\t\t// access iterators' distances can be calculated by simple pointer calculation.\n\t\t// Thus the code below boils down to a few subtractions when using a vector,\n\t\t// string, or array as the Container type. \n\t\t//\n\t\tconst difference_type dBegin = eastl::distance(const_cast(c).begin(), mBegin); // const_cast here solves a little compiler \n\t\tconst difference_type dEnd = eastl::distance(const_cast(c).begin(), mEnd); // argument matching problem.\n\n\t\tif(dEnd >= dBegin)\n\t\t\treturn dEnd - dBegin;\n\n\t\treturn c.size() - (dBegin - dEnd);\n\t}\n\t*/\n\n\n\tnamespace Internal \n\t{\n\t\t///////////////////////////////////////////////////////////////\n\t\t// has_overflow_allocator\n\t\t//\n\t\t// returns true_type when the specified container type is an \n\t\t// eastl::fixed_* container and therefore has an overflow \n\t\t// allocator type.\n\t\t//\n\t\ttemplate \n\t\tstruct has_overflow_allocator : false_type {};\n\n\t\ttemplate \n\t\tstruct has_overflow_allocator().get_overflow_allocator())>> : true_type {};\n\n\n\t\t///////////////////////////////////////////////////////////////\n\t\t// GetFixedContainerCtorAllocator\n\t\t//\n\t\t// eastl::fixed_* containers are only constructible via their \n\t\t// overflow allocator type. This helper select the appropriate \n\t\t// allocator from the specified container.\n\t\t//\n\t\ttemplate ()()>\n\t\tstruct GetFixedContainerCtorAllocator\n\t\t{\n\t\t\tauto& operator()(Container& c) { return c.get_overflow_allocator(); }\n\t\t};\n\n\t\ttemplate \n\t\tstruct GetFixedContainerCtorAllocator\n\t\t{\n\t\t\tauto& operator()(Container& c) { return c.get_allocator(); }\n\t\t};\n\t} // namespace Internal\n\n\n\t///////////////////////////////////////////////////////////////\n\t// ContainerTemporary\n\t// \n\t// Helper type which prevents utilizing excessive stack space \n\t// when creating temporaries when swapping/copying the underlying \n\t// ring_buffer container type. \n\t//\n\ttemplate = EASTL_MAX_STACK_USAGE)>\n\tstruct ContainerTemporary\n\t{\n\t\tContainer mContainer;\n\n\t\tContainerTemporary(Container& parentContainer)\n\t\t : mContainer(Internal::GetFixedContainerCtorAllocator{}(parentContainer))\n\t\t{\n\t\t}\n\n\t\tContainer& get() { return mContainer; }\n\t};\n\n\ttemplate \n\tstruct ContainerTemporary\n\t{\n\t\ttypename Container::allocator_type* mAllocator;\n\t\tContainer* mContainer;\n\n\t\tContainerTemporary(Container& parentContainer)\n\t\t : mAllocator(&parentContainer.get_allocator())\n\t\t , mContainer(new (mAllocator->allocate(sizeof(Container))) Container)\n\t\t{\n\t\t}\n\n\t\t~ContainerTemporary()\n\t\t{\n\t\t\tmContainer->~Container();\n\t\t\tmAllocator->deallocate(mContainer, sizeof(Container));\n\t\t}\n\n\t\tContainer& get() { return *mContainer; }\n\t};\n\n\n\ttemplate \n\tvoid ring_buffer::resize(size_type n)\n\t{\n\t\t// Note that if n > size(), we just move the end position out to\n\t\t// the begin + n, with the data being the old end and the new end\n\t\t// being stale values from the past. This is by design, as the concept\n\t\t// of arbitrarily resizing a ring buffer like this is currently deemed\n\t\t// to be vague in what it intends to do. We can only assume that the\n\t\t// user knows what he is doing and will deal with the stale values.\n\t\tEASTL_ASSERT(c.size() >= 1);\n\t\tconst size_type cap = (c.size() - 1);\n\n\t\tmSize = n;\n\n\t\tif(n > cap) // If we need to grow in capacity...\n\t\t{\n\t\t\t// Given that a growing operation will always result in memory allocation, \n\t\t\t// we currently implement this function via the usage of a temp container.\n\t\t\t// This makes for a simple implementation, but in some cases it is less\n\t\t\t// efficient. In particular, if the container is a node-based container like\n\t\t\t// a (linked) list, this function would be faster if we simply added nodes\n\t\t\t// to ourself. We would do this by inserting the nodes to be after end()\n\t\t\t// and adjusting the begin() position if it was after end().\n\n\t\t\t// To do: This code needs to be amended to deal with possible exceptions \n\t\t\t// that could occur during the resize call below.\n\n\t\t\tContainerTemporary cTemp(c);\n\t\t\tcTemp.get().resize(n + 1);\n\t\t\teastl::copy(begin(), end(), cTemp.get().begin());\n\t\t\teastl::swap(c, cTemp.get());\n\n\t\t\tmBegin = c.begin();\n\t\t\tmEnd = mBegin;\n\t\t\teastl::advance(mEnd, n); // We can do a simple advance algorithm on this because we know that mEnd will not wrap around.\n\t\t}\n\t\telse // We could do a check here for n != size(), but that would be costly and people don't usually resize things to their same size.\n\t\t{\n\t\t\tmEnd = mBegin;\n\n\t\t\t// eastl::advance(mEnd, n); // We *cannot* use this because there may be wraparound involved.\n\n\t\t\t// To consider: Possibly we should implement some more detailed logic to optimize the code here.\n\t\t\t// We'd need to do different behaviour dending on whether the container iterator type is a \n\t\t\t// random access iterator or otherwise.\n\n\t\t\twhile(n--)\n\t\t\t{\n\t\t\t\tif(EASTL_UNLIKELY(++mEnd == c.end()))\n\t\t\t\t\tmEnd = c.begin();\n\t\t\t}\n\t\t}\n\t}\n\n\n\ttemplate \n\ttypename ring_buffer::size_type\n\tring_buffer::capacity() const EA_NOEXCEPT\n\t{\n\t\tEASTL_ASSERT(c.size() >= 1); // This is required because even an empty ring_buffer has one unused termination element, somewhat like a \\0 at the end of a C string.\n\n\t\treturn (c.size() - 1); // Need to subtract one because the position at mEnd is unused.\n\t}\n\n\n\ttemplate \n\tvoid ring_buffer::set_capacity(size_type n)\n\t{\n\t\tconst size_type capacity = (c.size() - 1);\n\n\t\tif(n != capacity) // If we need to change capacity...\n\t\t{\n\t\t\tContainerTemporary cTemp(c);\n\t\t\tcTemp.get().resize(n + 1);\n\n\t\t\titerator itCopyBegin = begin();\n\n\t\t\tif(n < mSize) // If we are shrinking the capacity, to less than our size...\n\t\t\t{\n\t\t\t\teastl::advance(itCopyBegin, mSize - n);\n\t\t\t\tmSize = n;\n\t\t\t}\n\n\t\t\teastl::copy(itCopyBegin, end(), cTemp.get().begin()); // The begin-end range may in fact be larger than n, in which case values will be overwritten.\n\t\t\teastl::swap(c, cTemp.get());\n\n\t\t\tmBegin = c.begin();\n\t\t\tmEnd = mBegin;\n\t\t\teastl::advance(mEnd, mSize); // We can do a simple advance algorithm on this because we know that mEnd will not wrap around.\n\t\t}\n\t}\n\n\n\ttemplate \n\tvoid ring_buffer::reserve(size_type n)\n\t{\n\t\t// We follow the pattern of vector and only do something if n > capacity.\n\t\tEASTL_ASSERT(c.size() >= 1);\n\n\t\tif(n > (c.size() - 1)) // If we need to grow in capacity... // (c.size() - 1) == capacity(); we are attempting to reduce function calls.\n\t\t{\n\t\t\tContainerTemporary cTemp(c);\n\t\t\tcTemp.get().resize(n + 1);\n\t\t\teastl::copy(begin(), end(), cTemp.get().begin());\n\t\t\teastl::swap(c, cTemp.get());\n\n\t\t\tmBegin = c.begin();\n\t\t\tmEnd = mBegin;\n\t\t\teastl::advance(mEnd, mSize); // We can do a simple advance algorithm on this because we know that mEnd will not wrap around.\n\t\t}\n\t}\n\n\n\ttemplate \n\ttypename ring_buffer::reference\n\tring_buffer::front()\n\t{\n\t\treturn *mBegin;\n\t}\n\n\n\ttemplate \n\ttypename ring_buffer::const_reference\n\tring_buffer::front() const\n\t{\n\t\treturn *mBegin;\n\t}\n\n\n\ttemplate \n\ttypename ring_buffer::reference\n\tring_buffer::back()\n\t{\n\t\t// return *(end() - 1); // Can't use this because not all iterators support operator-.\n\n\t\titerator temp(end()); // To do: Find a way to construct this temporary in the return statement.\n\t\treturn *(--temp); // We can do it by making all our containers' iterators support operator-.\n\t}\n\n\t\t\n\ttemplate \n\ttypename ring_buffer::const_reference\n\tring_buffer::back() const\n\t{\n\t\t// return *(end() - 1); // Can't use this because not all iterators support operator-.\n\n\t\tconst_iterator temp(end()); // To do: Find a way to construct this temporary in the return statement.\n\t\treturn *(--temp); // We can do it by making all our containers' iterators support operator-.\n\t}\n\n\n\t/// A push_back operation on a ring buffer assigns the new value to end. \n\t/// If there is no more space in the buffer, this will result in begin\n\t/// being overwritten and the begin position being moved foward one position.\n\ttemplate \n\tvoid ring_buffer::push_back(const value_type& value)\n\t{\n\t\t*mEnd = value;\n\n\t\tif(++mEnd == c.end())\n\t\t\tmEnd = c.begin();\n\n\t\tif(mEnd == mBegin)\n\t\t{\n\t\t\tif(++mBegin == c.end())\n\t\t\t\tmBegin = c.begin();\n\t\t}\n\t\telse\n\t\t\t++mSize;\n\t}\n\n\n\t/// A push_back operation on a ring buffer assigns the new value to end. \n\t/// If there is no more space in the buffer, this will result in begin\n\t/// being overwritten and the begin position being moved foward one position.\n\ttemplate \n\ttypename ring_buffer::reference\n\tring_buffer::push_back()\n\t{\n\t\t// We don't do the following assignment, as the value at mEnd is already constructed;\n\t\t// it is merely possibly not default-constructed. However, the spirit of push_back\n\t\t// is that the user intends to do an assignment or data modification after the \n\t\t// push_back call. The user can always execute *back() = value_type() if he wants.\n\t\t//*mEnd = value_type();\n\n\t\tif(++mEnd == c.end())\n\t\t\tmEnd = c.begin();\n\n\t\tif(mEnd == mBegin)\n\t\t{\n\t\t\tif(++mBegin == c.end())\n\t\t\t\tmBegin = c.begin();\n\t\t}\n\t\telse\n\t\t\t++mSize;\n\n\t\treturn back();\n\t}\n\n\n\ttemplate \n\tvoid ring_buffer::pop_back()\n\t{\n\t\tEASTL_ASSERT(mEnd != mBegin); // We assume that size() > 0 and thus that there is something to pop.\n\n\t\tif(EASTL_UNLIKELY(mEnd == c.begin()))\n\t\t\tmEnd = c.end();\n\t\t--mEnd;\n\t\t--mSize;\n\t}\n\n\n\ttemplate \n\tvoid ring_buffer::push_front(const value_type& value)\n\t{\n\t\tif(EASTL_UNLIKELY(mBegin == c.begin()))\n\t\t\tmBegin = c.end();\n\n\t\tif(--mBegin == mEnd)\n\t\t{\n\t\t\tif(EASTL_UNLIKELY(mEnd == c.begin()))\n\t\t\t\tmEnd = c.end();\n\t\t\t--mEnd;\n\t\t}\n\t\telse\n\t\t\t++mSize;\n\n\t\t*mBegin = value;\n\t}\n\n\n\ttemplate \n\ttypename ring_buffer::reference\n\tring_buffer::push_front()\n\t{\n\t\tif(EASTL_UNLIKELY(mBegin == c.begin()))\n\t\t\tmBegin = c.end();\n\n\t\tif(--mBegin == mEnd)\n\t\t{\n\t\t\tif(EASTL_UNLIKELY(mEnd == c.begin()))\n\t\t\t\tmEnd = c.end();\n\t\t\t--mEnd;\n\t\t}\n\t\telse\n\t\t\t++mSize;\n\n\t\t// See comments above in push_back for why we don't execute this:\n\t\t// *mBegin = value_type();\n\n\t\treturn *mBegin; // Same as return front();\n\t}\n\n\n\ttemplate \n\tvoid ring_buffer::pop_front()\n\t{\n\t\tEASTL_ASSERT(mBegin != mEnd); // We assume that mEnd > mBegin and thus that there is something to pop.\n\n\t\tif(++mBegin == c.end())\n\t\t\tmBegin = c.begin();\n\t\t--mSize;\n\t}\n\n\n\ttemplate \n\ttypename ring_buffer::reference\n\tring_buffer::operator[](size_type n)\n\t{\n\t\t// return *(begin() + n); // Can't use this because not all iterators support operator+.\n\n\t\t// This should compile to code that is nearly as efficient as that above.\n\t\t// The primary difference is the possible generation of a temporary in this case.\n\t\titerator temp(begin());\n\t\teastl::advance(temp, n);\n\t\treturn *(temp.mContainerIterator);\n\t}\n\n\n\ttemplate \n\ttypename ring_buffer::const_reference\n\tring_buffer::operator[](size_type n) const\n\t{\n\t\t// return *(begin() + n); // Can't use this because not all iterators support operator+.\n\n\t\t// This should compile to code that is nearly as efficient as that above.\n\t\t// The primary difference is the possible generation of a temporary in this case.\n\t\tconst_iterator temp(begin());\n\t\teastl::advance(temp, n);\n\t\treturn *(temp.mContainerIterator);\n\t}\n\n\n\ttemplate \n\ttypename ring_buffer::iterator\n\tring_buffer::insert(const_iterator position, const value_type& value)\n\t{\n\t\t// To consider: It would be faster if we could tell that position was in the first\n\t\t// half of the container and instead of moving things after the position back, \n\t\t// we could move things before the position forward. \n\n\t\titerator afterEnd(end());\n\t\titerator beforeEnd(afterEnd);\n\n\t\t++afterEnd;\n\n\t\tif(afterEnd.mContainerIterator == mBegin) // If we are at full capacity...\n\t\t\t--beforeEnd;\n\t\telse\n\t\t\tpush_back();\n\n\t\titerator itPosition(position.mpContainer, position.mContainerIterator); // We merely copy from const_iterator to iterator.\n\t\teastl::copy_backward(itPosition, beforeEnd, end());\n\t\t*itPosition = value;\n\n\t\treturn itPosition;\n\t}\n\n\n\ttemplate \n\tvoid ring_buffer::insert(const_iterator position, size_type n, const value_type& value)\n\t{\n\t\t// To do: This can be improved with a smarter version. However, \n\t\t// this is a little tricky because we need to deal with the case \n\t\t// whereby n is greater than the size of the container itself. \n\t\twhile(n--)\n\t\t\tinsert(position, value);\n\t}\n\n\n\ttemplate \n\tvoid ring_buffer::insert(const_iterator position, std::initializer_list ilist)\n\t{\n\t\tinsert(position, ilist.begin(), ilist.end());\n\t}\n\n\n\ttemplate \n\ttemplate \n\tvoid ring_buffer::insert(const_iterator position, InputIterator first, InputIterator last)\n\t{\n\t\t// To do: This can possibly be improved with a smarter version.\n\t\t// However, this can be tricky if distance(first, last) is greater\n\t\t// than the size of the container itself.\n\t\tfor(; first != last; ++first, ++position)\n\t\t\tinsert(position, *first);\n\t}\n\n\n\ttemplate \n\ttypename ring_buffer::iterator\n\tring_buffer::erase(const_iterator position)\n\t{\n\t\titerator itPosition(position.mpContainer, position.mContainerIterator); // We merely copy from const_iterator to iterator.\n\t\titerator iNext(itPosition);\n\n\t\teastl::copy(++iNext, end(), itPosition);\n\t\tpop_back();\n\n\t\treturn itPosition;\n\t}\n\n\n\ttemplate \n\ttypename ring_buffer::iterator\n\tring_buffer::erase(const_iterator first, const_iterator last)\n\t{\n\t\titerator itFirst(first.mpContainer, first.mContainerIterator); // We merely copy from const_iterator to iterator.\n\t\titerator itLast(last.mpContainer, last.mContainerIterator);\n\n\t\ttypename iterator::difference_type d = eastl::distance(itFirst, itLast);\n\n\t\teastl::copy(itLast, end(), itFirst);\n\n\t\twhile(d--) // To do: improve this implementation.\n\t\t\tpop_back();\n\n\t\treturn itFirst;\n\t}\n\n\n\ttemplate \n\ttypename ring_buffer::reverse_iterator\n\tring_buffer::erase(const_reverse_iterator position)\n\t{\n\t\treturn reverse_iterator(erase((++position).base()));\n\t}\n\n\n\ttemplate \n\ttypename ring_buffer::reverse_iterator\n\tring_buffer::erase(const_reverse_iterator first, const_reverse_iterator last)\n\t{\n\t\t// Version which erases in order from first to last.\n\t\t// difference_type i(first.base() - last.base());\n\t\t// while(i--)\n\t\t// first = erase(first);\n\t\t// return first;\n\n\t\t// Version which erases in order from last to first, but is slightly more efficient:\n\t\treturn reverse_iterator(erase((++last).base(), (++first).base()));\n\t}\n\n\n\ttemplate \n\tvoid ring_buffer::clear()\n\t{\n\t\t// Don't clear the container; we use its valid data for our elements.\n\t\tmBegin = c.begin();\n\t\tmEnd = c.begin();\n\t\tmSize = 0;\n\t}\n\n\n\ttemplate \n\ttypename ring_buffer::container_type&\n\tring_buffer::get_container()\n\t{\n\t\treturn c;\n\t}\n\n\n\ttemplate \n\tconst typename ring_buffer::container_type&\n\tring_buffer::get_container() const\n\t{\n\t\treturn c;\n\t}\n\n\n\ttemplate \n\tinline bool ring_buffer::validate() const\n\t{\n\t\tif(!c.validate()) // This requires that the container implement the validate function. That pretty much \n\t\t\treturn false; // means that the container is an EASTL container and not a std STL container. \n\n\t\tif(c.empty()) // c must always have a size of at least 1, as even an empty ring_buffer has an unused terminating element.\n\t\t\treturn false;\n\n\t\tif(size() > capacity())\n\t\t\treturn false;\n\n\t\tif((validate_iterator(begin()) & (isf_valid | isf_current)) != (isf_valid | isf_current))\n\t\t\treturn false;\n\n\t\tif((validate_iterator(end()) & (isf_valid | isf_current)) != (isf_valid | isf_current))\n\t\t\treturn false;\n\n\t\t// Verify that the size calculation is consistent.\n\t\tsize_type n = 0;\n\t\tfor(const_iterator i(begin()), iEnd(end()); i != iEnd; ++i)\n\t\t\t++n;\n\t\tif(n != mSize)\n\t\t\treturn false;\n\n\t\treturn true;\n\t}\n\n\n\ttemplate \n\tinline int ring_buffer::validate_iterator(const_iterator i) const\n\t{\n\t\t// To do: Replace this with a more efficient implementation if possible.\n\n\t\tfor(const_iterator temp = begin(), tempEnd = end(); temp != tempEnd; ++temp)\n\t\t{\n\t\t\tif(temp == i)\n\t\t\t\treturn (isf_valid | isf_current | isf_can_dereference);\n\t\t}\n\n\t\tif(i == end())\n\t\t\treturn (isf_valid | isf_current); \n\n\t\treturn isf_none;\n\t}\n\n\n\n\t///////////////////////////////////////////////////////////////////////\n\t// global operators\n\t///////////////////////////////////////////////////////////////////////\n\n\ttemplate \n\tinline bool operator==(const ring_buffer& a, const ring_buffer& b)\n\t{\n\t\treturn (a.size() == b.size()) && eastl::equal(a.begin(), a.end(), b.begin());\n\t}\n\n\n\ttemplate \n\tinline bool operator<(const ring_buffer& a, const ring_buffer& b)\n\t{\n\t\treturn eastl::lexicographical_compare(a.begin(), a.end(), b.begin(), b.end());\n\t}\n\n\n\ttemplate \n\tinline bool operator!=(const ring_buffer& a, const ring_buffer& b)\n\t{\n\t\treturn !(a == b);\n\t}\n\n\n\ttemplate \n\tinline bool operator>(const ring_buffer& a, const ring_buffer& b)\n\t{\n\t\treturn (b < a);\n\t}\n\n\n\ttemplate \n\tinline bool operator<=(const ring_buffer& a, const ring_buffer& b)\n\t{\n\t\treturn !(b < a);\n\t}\n\n\n\ttemplate \n\tinline bool operator>=(const ring_buffer& a, const ring_buffer& b)\n\t{\n\t\treturn !(a < b);\n\t}\n\n\n\ttemplate \n\tinline void swap(ring_buffer& a, ring_buffer& b)\n\t{\n\t\ta.swap(b);\n\t}\n\n\n} // namespace eastl\n\n\n#endif // Header include guard\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n" }, { "path": "include/EASTL/bonus/sort_extra.h", "content": "/////////////////////////////////////////////////////////////////////////////\n// Copyright (c) Electronic Arts Inc. All rights reserved.\n/////////////////////////////////////////////////////////////////////////////\n\n//////////////////////////////////////////////////////////////////////////////\n// This file implements additional sort algorithms beyond the basic set.\n// Included here are:\n// selection_sort -- Unstable.\n// shaker_sort -- Stable.\n// bucket_sort -- Stable. \n//\n//////////////////////////////////////////////////////////////////////////////\n\n\n#ifndef EASTL_SORT_EXTRA_H\n#define EASTL_SORT_EXTRA_H\n\n\n#include \n#include \n#include \n#include \n#include \n#include // For backwards compatibility due to sorts moved from here to sort.h.\n#include \n\n#if defined(EA_PRAGMA_ONCE_SUPPORTED)\n\t#pragma once // Some compilers (e.g. VC++) benefit significantly from using this. We've measured 3-4% build speed improvements in apps as a result.\n#endif\n\n\n\nnamespace eastl\n{\n\t/// selection_sort\n\t///\n\t/// Implements the SelectionSort algorithm.\n\t///\n\ttemplate \n\tvoid selection_sort(ForwardIterator first, ForwardIterator last, StrictWeakOrdering compare)\n\t{\n\t\tForwardIterator iCurrent, iMin;\n\n\t\tfor(; first != last; ++first)\n\t\t{\n\t\t\tiCurrent = first;\n\t\t\tiMin = iCurrent;\n\n\t\t\tfor(++iCurrent; iCurrent != last; ++iCurrent)\n\t\t\t{\n\t\t\t\tif(compare(*iCurrent, *iMin))\n\t\t\t\t{\n\t\t\t\t\tEASTL_VALIDATE_COMPARE(!compare(*iMin, *iCurrent)); // Validate that the compare function is sane.\n\t\t\t\t\tiMin = iCurrent;\n\t\t\t\t}\n\t\t\t}\n\n\t\t\tif(first != iMin)\n\t\t\t\teastl::iter_swap(first, iMin);\n\t\t}\n\t} // selection_sort\n\n\ttemplate \n\tinline void selection_sort(ForwardIterator first, ForwardIterator last)\n\t{\n\t\ttypedef eastl::less::value_type> Less;\n\n\t\teastl::selection_sort(first, last, Less());\n\t}\n\n\n\n\t/// shaker_sort\n\t///\n\t/// Implements the ShakerSort algorithm, which is a sorting algorithm which \n\t/// improves on bubble_sort by sweeping both from left to right and right \n\t/// to left, resulting in less iteration.\n\t///\n\ttemplate \n\tvoid shaker_sort(BidirectionalIterator first, BidirectionalIterator last, StrictWeakOrdering compare)\n\t{\n\t\tif(first != last)\n\t\t{\n\t\t\tBidirectionalIterator iCurrent, iNext, iLastModified;\n\n\t\t\t--last;\n\n\t\t\twhile(first != last)\n\t\t\t{\n\t\t\t\tiLastModified = first;\n\n\t\t\t\tfor(iCurrent = first; iCurrent != last; iCurrent = iNext)\n\t\t\t\t{\n\t\t\t\t\tiNext = iCurrent;\n\t\t\t\t\t++iNext;\n\n\t\t\t\t\tif(compare(*iNext, *iCurrent))\n\t\t\t\t\t{\n\t\t\t\t\t\tEASTL_VALIDATE_COMPARE(!compare(*iCurrent, *iNext)); // Validate that the compare function is sane.\n\t\t\t\t\t\tiLastModified = iCurrent;\n\t\t\t\t\t\teastl::iter_swap(iCurrent, iNext);\n\t\t\t\t\t}\n\t\t\t\t}\n\n\t\t\t\tlast = iLastModified;\n\n\t\t\t\tif(first != last)\n\t\t\t\t{\n\t\t\t\t\tfor(iCurrent = last; iCurrent != first; iCurrent = iNext)\n\t\t\t\t\t{\n\t\t\t\t\t\tiNext = iCurrent;\n\t\t\t\t\t\t--iNext;\n\n\t\t\t\t\t\tif(compare(*iCurrent, *iNext))\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\tEASTL_VALIDATE_COMPARE(!compare(*iNext, *iCurrent)); // Validate that the compare function is sane.\n\t\t\t\t\t\t\tiLastModified = iCurrent;\n\t\t\t\t\t\t\teastl::iter_swap(iNext, iCurrent);\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t\tfirst = iLastModified;\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t} // shaker_sort\n\n\ttemplate \n\tinline void shaker_sort(BidirectionalIterator first, BidirectionalIterator last)\n\t{\n\t\ttypedef eastl::less::value_type> Less;\n\n\t\teastl::shaker_sort(first, last, Less());\n\t}\n\n\n\n\t/// bucket_sort\n\t///\n\t/// Implements the BucketSort algorithm. \n\t///\n\t/// Example usage:\n\t/// const size_t kElementRange = 32;\n\t/// vector intArray(1000);\n\t/// \n\t/// for(int i = 0; i < 1000; i++)\n\t/// intArray[i] = rand() % kElementRange;\n\t/// \n\t/// vector< vector > bucketArray(kElementRange);\n\t/// bucket_sort(intArray.begin(), intArray.end(), bucketArray, eastl::hash_use_self());\n\t///\n\ttemplate \n\tstruct hash_use_self\n\t{\n\t\tT operator()(const T& x) const\n\t\t\t{ return x; }\n\t};\n\n\t// Requires buckeyArray to be an array of arrays with a size equal to the range of values\n\t// returned by the hash function. The hash function is required to return a unique value\n\t// for each uniquely sorted element. Usually the way this is done is the elements are \n\t// integers of a limited range (e.g. 0-64) and the hash function returns the element value\n\t// itself. If you had a case where all elements were always even numbers (e.g. 0-128), \n\t// you could use a custom hash function that returns (element value / 2).\n\t//\n\t// The user is required to provide an empty bucketArray to this function. This function returns\n\t// with the bucketArray non-empty. This function doesn't clear the bucketArray because that takes\n\t// time and the user might not need it to be cleared, at least at that time.\n\t// \n\ttemplate \n\tvoid bucket_sort(ForwardIterator first, ForwardIterator last, ContainerArray& bucketArray, HashFunction hash /*= hash_use_self*/)\n\t{\n\t\tfor(ForwardIterator iInput = first; iInput != last; ++iInput)\n\t\t\tbucketArray[hash(*iInput)].push_back(*iInput);\n\n\t\tfor(typename ContainerArray::const_iterator iBucket = bucketArray.begin(); iBucket != bucketArray.end(); ++iBucket)\n\t\t\tfirst = eastl::copy((*iBucket).begin(), (*iBucket).end(), first);\n\t}\n\n\n\n} // namespace eastl\n\n\n#endif // Header include guard\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n" }, { "path": "include/EASTL/bonus/tuple_vector.h", "content": "///////////////////////////////////////////////////////////////////////////////\n// Copyright (c) Electronic Arts Inc. All rights reserved.\n///////////////////////////////////////////////////////////////////////////////\n\n///////////////////////////////////////////////////////////////////////////////\n// tuple_vector is a data container that is designed to abstract and simplify\n// the handling of a \"structure of arrays\" layout of data in memory. In\n// particular, it mimics the interface of vector, including functionality to do\n// inserts, erases, push_backs, and random-access. It also provides a\n// RandomAccessIterator and corresponding functionality, making it compatible\n// with most STL (and STL-esque) algorithms such as ranged-for loops, find_if,\n// remove_if, or sort.\n\n// When used or applied properly, this container can improve performance of\n// some algorithms through cache-coherent data accesses or allowing for\n// sensible SIMD programming, while keeping the structure of a single\n// container, to permit a developer to continue to use existing algorithms in\n// STL and the like.\n//\n// Consult doc/Bonus/tuple_vector_readme.md for more information.\n///////////////////////////////////////////////////////////////////////////////\n\n#ifndef EASTL_TUPLEVECTOR_H\n#define EASTL_TUPLEVECTOR_H\n\n#include \n#include \n#include \n#include \n#include \n#include \n#if EASTL_EXCEPTIONS_ENABLED\n#include \n#endif\n\n#if defined(EA_PRAGMA_ONCE_SUPPORTED)\n\t#pragma once // Some compilers (e.g. VC++) benefit significantly from using this. We've measured 3-4% build speed improvements in apps as a result.\n#endif\n\nEA_DISABLE_VC_WARNING(4244) // warning C4244: 'conversion from '___' to '___', possible loss of data\nEA_DISABLE_VC_WARNING(4623) // warning C4623: default constructor was implicitly defined as deleted\nEA_DISABLE_VC_WARNING(4625) // warning C4625: copy constructor was implicitly defined as deleted\nEA_DISABLE_VC_WARNING(4510) // warning C4510: default constructor could not be generated\n\nnamespace eastl\n{\n\t/// EASTL_TUPLE_VECTOR_DEFAULT_NAME\n\t///\n\t/// Defines a default container name in the absence of a user-provided name.\n\t///\n\t#ifndef EASTL_TUPLE_VECTOR_DEFAULT_NAME\n\t#define EASTL_TUPLE_VECTOR_DEFAULT_NAME EASTL_DEFAULT_NAME_PREFIX \" tuple-vector\" // Unless the user overrides something, this is \"EASTL tuple-vector\".\n\t#endif\n\n\n\t/// EASTL_TUPLE_VECTOR_DEFAULT_ALLOCATOR\n\t///\n\t#ifndef EASTL_TUPLE_VECTOR_DEFAULT_ALLOCATOR\n\t#define EASTL_TUPLE_VECTOR_DEFAULT_ALLOCATOR allocator_type(EASTL_TUPLE_VECTOR_DEFAULT_NAME)\n\t#endif\n\nnamespace TupleVecInternal\n{\n\n// forward declarations\ntemplate \nstruct tuplevec_element;\n\ntemplate \nusing tuplevec_element_t = typename tuplevec_element::type;\n\ntemplate \nstruct TupleTypes {};\n\ntemplate \nclass TupleVecImpl;\n\ntemplate \nstruct TupleRecurser;\n\ntemplate \nstruct TupleIndexRecurser;\n\ntemplate \nstruct TupleVecLeaf;\n\ntemplate \nstruct TupleVecIter;\n\n// tuplevec_element helper to be able to isolate a type given an index\ntemplate \nstruct tuplevec_element\n{\n\tstatic_assert(I != I, \"tuplevec_element index out of range\");\n};\n\ntemplate \nstruct tuplevec_element<0, T, Ts...>\n{\n\ttuplevec_element() = delete; // tuplevec_element should only be used for compile-time assistance, and never be instantiated\n\ttypedef T type;\n};\n\ntemplate \nstruct tuplevec_element\n{\n\ttypedef tuplevec_element_t type;\n};\n\n// attempt to isolate index given a type\ntemplate \nstruct tuplevec_index\n{\n};\n\ntemplate \nstruct tuplevec_index>\n{\n\ttypedef void DuplicateTypeCheck;\n\ttuplevec_index() = delete; // tuplevec_index should only be used for compile-time assistance, and never be instantiated\n\tstatic const eastl_size_t index = 0;\n};\n\ntemplate \nstruct tuplevec_index>\n{\n\ttypedef int DuplicateTypeCheck;\n\tstatic_assert(is_void>::DuplicateTypeCheck>::value, \"duplicate type T in tuple_vector::get(); unique types must be provided in declaration, or only use get()\");\n\n\tstatic const eastl_size_t index = 0;\n};\n\ntemplate \nstruct tuplevec_index>\n{\n\ttypedef typename tuplevec_index>::DuplicateTypeCheck DuplicateTypeCheck;\n\tstatic const eastl_size_t index = tuplevec_index>::index + 1;\n};\n\ntemplate \nstruct tuplevec_index> : public tuplevec_index>\n{\n};\n\n\n// helper to calculate the layout of the allocations for the tuple of types (esp. to take alignment into account)\ntemplate <>\nstruct TupleRecurser<>\n{\n\ttypedef eastl_size_t size_type;\n\n\t// This class should never be instantiated. This is just a helper for working with static functions when anonymous functions don't work\n\t// and provide some other utilities\n\tTupleRecurser() = delete;\n\t\t\n\tstatic EA_CONSTEXPR size_type GetTotalAlignment()\n\t{\n\t\treturn 0;\n\t}\n\n\tstatic EA_CONSTEXPR size_type GetTotalAllocationSize(size_type capacity, size_type offset)\n\t{\n\t\tEA_UNUSED(capacity);\n\t\treturn offset;\n\t}\n\n\ttemplate\n\tstatic pair DoAllocate(TupleVecImpl &vec, void** ppNewLeaf, size_type capacity, size_type offset)\n\t{\n\t\tEA_UNUSED(ppNewLeaf);\n\n\t\t// If n is zero, then we allocate no memory and just return NULL. \n\t\t// This is fine, as our default ctor initializes with NULL pointers. \n\t\tsize_type alignment = TupleRecurser::GetTotalAlignment();\n\t\tvoid* ptr = capacity ? allocate_memory(vec.get_allocator(), offset, alignment, 0) : nullptr;\n\n\t#if EASTL_ASSERT_ENABLED\n\t\tif (EASTL_UNLIKELY((size_t)ptr & (alignment - 1)) != 0)\n\t\t{\n\t\t\tEASTL_FAIL_MSG(\"tuple_vector::DoAllocate -- memory not alignment at requested alignment\");\n\t\t}\n\t#endif\n\n\t\treturn make_pair(ptr, offset);\n\t}\n\n\ttemplate\n\tstatic void SetNewData(TupleVecImplType &vec, void* pData, size_type capacity, size_type offset) \n\t{ \n\t\tEA_UNUSED(vec);\n\t\tEA_UNUSED(pData);\n\t\tEA_UNUSED(capacity);\n\t\tEA_UNUSED(offset);\n\t}\n};\n\ntemplate \nstruct TupleRecurser : TupleRecurser\n{\n\ttypedef eastl_size_t size_type;\n\t\n\tstatic EA_CONSTEXPR size_type GetTotalAlignment()\n\t{\n\t\treturn max(static_cast(alignof(T)), TupleRecurser::GetTotalAlignment());\n\t}\n\n\tstatic EA_CONSTEXPR size_type GetTotalAllocationSize(size_type capacity, size_type offset)\n\t{\n\t\treturn TupleRecurser::GetTotalAllocationSize(capacity, CalculateAllocationSize(offset, capacity));\n\t}\n\n\ttemplate\n\tstatic pair DoAllocate(TupleVecImpl &vec, void** ppNewLeaf, size_type capacity, size_type offset)\n\t{\n\t\tsize_type allocationOffset = CalculatAllocationOffset(offset);\n\t\tsize_type allocationSize = CalculateAllocationSize(offset, capacity);\n\t\tpair allocation = TupleRecurser::template DoAllocate(\n\t\t\tvec, ppNewLeaf, capacity, allocationSize);\n\t\tppNewLeaf[I] = (void*)((uintptr_t)(allocation.first) + allocationOffset);\n\t\treturn allocation;\n\t}\n\n\ttemplate\n\tstatic void SetNewData(TupleVecImplType &vec, void* pData, size_type capacity, size_type offset)\n\t{\n\t\tsize_type allocationOffset = CalculatAllocationOffset(offset);\n\t\tsize_type allocationSize = CalculateAllocationSize(offset, capacity);\n\t\tvec.TupleVecLeaf::mpData = (T*)((uintptr_t)pData + allocationOffset);\n\t\tTupleRecurser::template SetNewData(vec, pData, capacity, allocationSize);\n\t}\n\nprivate:\n\tstatic EA_CONSTEXPR size_type CalculateAllocationSize(size_type offset, size_type capacity)\n\t{\n\t\treturn CalculatAllocationOffset(offset) + sizeof(T) * capacity;\n\t}\n\n\tstatic EA_CONSTEXPR size_type CalculatAllocationOffset(size_type offset) { return (offset + alignof(T) - 1) & (~alignof(T) + 1); }\n};\n\ntemplate \nstruct TupleVecLeaf\n{\n\ttypedef eastl_size_t size_type;\n\n\tvoid DoUninitializedMoveAndDestruct(const size_type begin, const size_type end, T* pDest)\n\t{\n\t\tT* pBegin = mpData + begin;\n\t\tT* pEnd = mpData + end;\n\t\teastl::uninitialized_move_if_noexcept(pBegin, pEnd, pDest);\n\t\teastl::destruct(pBegin, pEnd);\n\t}\n\n\tvoid DoInsertAndFill(size_type pos, size_type n, size_type numElements, const T& arg)\n\t{\n\t\tT* pDest = mpData + pos;\n\t\tT* pDataEnd = mpData + numElements;\n\t\tconst T temp = arg;\n\t\tconst size_type nExtra = (numElements - pos);\n\t\tif (n < nExtra) // If the inserted values are entirely within initialized memory (i.e. are before mpEnd)...\n\t\t{\n\t\t\teastl::uninitialized_move(pDataEnd - n, pDataEnd, pDataEnd);\n\t\t\teastl::move_backward(pDest, pDataEnd - n, pDataEnd); // We need move_backward because of potential overlap issues.\n\t\t\teastl::fill(pDest, pDest + n, temp);\n\t\t}\n\t\telse\n\t\t{\n\t\t\teastl::uninitialized_fill_n(pDataEnd, n - nExtra, temp);\n\t\t\teastl::uninitialized_move(pDest, pDataEnd, pDataEnd + n - nExtra);\n\t\t\teastl::fill(pDest, pDataEnd, temp);\n\t\t}\n\t}\n\n\tvoid DoInsertRange(T* pSrcBegin, T* pSrcEnd, T* pDestBegin, size_type numDataElements)\n\t{\n\t\tsize_type pos = static_cast(pDestBegin - mpData);\n\t\tsize_type n = static_cast(pSrcEnd - pSrcBegin);\n\t\tT* pDataEnd = mpData + numDataElements;\n\t\tconst size_type nExtra = numDataElements - pos;\n\t\tif (n < nExtra) // If the inserted values are entirely within initialized memory (i.e. are before mpEnd)...\n\t\t{\n\t\t\teastl::uninitialized_move(pDataEnd - n, pDataEnd, pDataEnd);\n\t\t\teastl::move_backward(pDestBegin, pDataEnd - n, pDataEnd); // We need move_backward because of potential overlap issues.\n\t\t\teastl::copy(pSrcBegin, pSrcEnd, pDestBegin);\n\t\t}\n\t\telse\n\t\t{\n\t\t\teastl::uninitialized_copy(pSrcEnd - (n - nExtra), pSrcEnd, pDataEnd);\n\t\t\teastl::uninitialized_move(pDestBegin, pDataEnd, pDataEnd + n - nExtra);\n\t\t\teastl::copy(pSrcBegin, pSrcEnd - (n - nExtra), pDestBegin);\n\t\t}\n\t}\n\n\tvoid DoInsertValue(size_type pos, size_type numElements, T&& arg)\n\t{\n\t\tT* pDest = mpData + pos;\n\t\tT* pDataEnd = mpData + numElements;\n\n\t\teastl::uninitialized_move(pDataEnd - 1, pDataEnd, pDataEnd);\n\t\teastl::move_backward(pDest, pDataEnd - 1, pDataEnd); // We need move_backward because of potential overlap issues.\n\t\teastl::destruct(pDest);\n\t\t::new (pDest) T(eastl::forward(arg));\n\t}\n\n\tT* mpData = nullptr;\n};\n\n// swallow allows for parameter pack expansion of arguments as means of expanding operations performed\n// if a void function is used for operation expansion, it should be wrapped in (..., 0) so that the compiler\n// thinks it has a parameter to pass into the function\ntemplate \nvoid swallow(Ts&&...) { }\n\ninline bool variadicAnd(bool cond) { return cond; }\n\ninline bool variadicAnd(bool cond, bool conds...) { return cond && variadicAnd(conds); }\n\n// Helper struct to check for strict compatibility between two iterators, whilst still allowing for\n// conversion between TupleVecImpl::iterator and TupleVecImpl::const_iterator. \ntemplate \nstruct TupleVecIterCompatibleImpl : public false_type { };\n\t\ntemplate<>\nstruct TupleVecIterCompatibleImpl, TupleTypes<>> : public true_type { };\n\ntemplate \nstruct TupleVecIterCompatibleImpl, TupleTypes> : public integral_constant, TupleTypes>::value &&\n\t\tis_same::type, typename remove_const::type>::value >\n{ };\n\ntemplate \nstruct TupleVecIterCompatible;\n\ntemplate\nstruct TupleVecIterCompatible, TupleTypes> :\n\tpublic TupleVecIterCompatibleImpl, TupleTypes>\n{ };\n\n// The Iterator operates by storing a persistent index internally,\n// and resolving the tuple of pointers to the various parts of the original tupleVec when dereferenced.\n// While resolving the tuple is a non-zero operation, it consistently generated better code than the alternative of\n// storing - and harmoniously updating on each modification - a full tuple of pointers to the tupleVec's data\ntemplate \nstruct TupleVecIter, Ts...>\n{\nprivate:\n\ttypedef TupleVecIter, Ts...> this_type;\n\ttypedef eastl_size_t size_type;\n\n\ttemplate \n\tfriend struct TupleVecIter;\n\n\ttemplate\n\tfriend class TupleVecImpl;\n\n\ttemplate\n\tfriend class move_iterator;\npublic:\n\ttypedef eastl::random_access_iterator_tag iterator_category;\n\ttypedef tuple value_type;\n\ttypedef eastl_size_t difference_type;\n\ttypedef tuple pointer;\n\ttypedef tuple reference;\n\n\tTupleVecIter() = default;\n\n\ttemplate\n\tTupleVecIter(VecImplType* tupleVec, size_type index)\n\t\t: mIndex(index)\n\t\t, mpData{(void*)tupleVec->TupleVecLeaf::mpData...}\n\t{ }\n\n\ttemplate , TupleTypes>::value, bool>::type>\n\tTupleVecIter(const TupleVecIter& other)\n\t\t: mIndex(other.mIndex)\n\t\t, mpData{other.mpData[Indices]...}\n\t{\n\t}\n\n\tbool operator==(const TupleVecIter& other) const { return mIndex == other.mIndex && mpData[0] == other.mpData[0]; }\n\tbool operator!=(const TupleVecIter& other) const { return mIndex != other.mIndex || mpData[0] != other.mpData[0]; }\n\treference operator*() const { return MakeReference(); }\n\n\tthis_type& operator++() { ++mIndex; return *this; }\n\tthis_type operator++(int)\n\t{\n\t\tthis_type temp = *this;\n\t\t++mIndex;\n\t\treturn temp;\n\t}\n\n\tthis_type& operator--() { --mIndex; return *this; }\n\tthis_type operator--(int)\n\t{\n\t\tthis_type temp = *this;\n\t\t--mIndex;\n\t\treturn temp;\n\t}\n\n\tthis_type& operator+=(difference_type n) { mIndex += n; return *this; }\n\tthis_type operator+(difference_type n) const\n\t{\n\t\tthis_type temp = *this;\n\t\treturn temp += n;\n\t}\n\tfriend this_type operator+(difference_type n, const this_type& rhs)\n\t{\n\t\tthis_type temp = rhs;\n\t\treturn temp += n;\n\t}\n\n\tthis_type& operator-=(difference_type n) { mIndex -= n; return *this; }\n\tthis_type operator-(difference_type n) const\n\t{\n\t\tthis_type temp = *this;\n\t\treturn temp -= n;\n\t}\n\tfriend this_type operator-(difference_type n, const this_type& rhs)\n\t{\n\t\tthis_type temp = rhs;\n\t\treturn temp -= n;\n\t}\n\n\tdifference_type operator-(const this_type& rhs) const { return mIndex - rhs.mIndex; }\n\tbool operator<(const this_type& rhs) const { return mIndex < rhs.mIndex; }\n\tbool operator>(const this_type& rhs) const { return mIndex > rhs.mIndex; }\n\tbool operator>=(const this_type& rhs) const { return mIndex >= rhs.mIndex; }\n\tbool operator<=(const this_type& rhs) const { return mIndex <= rhs.mIndex; }\n\n\treference operator[](const size_type n) const\n\t{\n\t\treturn *(*this + n);\n\t}\n\nprivate:\n\n\tvalue_type MakeValue() const\n\t{\n\t\treturn value_type(((Ts*)mpData[Indices])[mIndex]...);\n\t}\n\n\treference MakeReference() const\n\t{\n\t\treturn reference(((Ts*)mpData[Indices])[mIndex]...);\n\t}\n\n\tpointer MakePointer() const\n\t{\n\t\treturn pointer(&((Ts*)mpData[Indices])[mIndex]...);\n\t}\n\n\tsize_type mIndex = 0;\n\tconst void* mpData[sizeof...(Ts)];\n};\n\n// TupleVecImpl\ntemplate \nclass TupleVecImpl, Ts...> : public TupleVecLeaf...\n{\n\ttypedef Allocator\tallocator_type;\n\ttypedef index_sequence index_sequence_type;\n\ttypedef TupleVecImpl this_type;\n\ttypedef TupleVecImpl const_this_type;\n\npublic:\n\ttypedef TupleVecInternal::TupleVecIter iterator;\n\ttypedef TupleVecInternal::TupleVecIter const_iterator;\n\ttypedef eastl::reverse_iterator reverse_iterator;\n\ttypedef eastl::reverse_iterator const_reverse_iterator;\n\ttypedef eastl_size_t size_type;\n\ttypedef eastl::tuple value_tuple;\n\ttypedef eastl::tuple reference_tuple;\n\ttypedef eastl::tuple const_reference_tuple;\n\ttypedef eastl::tuple ptr_tuple;\n\ttypedef eastl::tuple const_ptr_tuple;\n\ttypedef eastl::tuple rvalue_tuple;\n\n\tTupleVecImpl()\n\t\t: mDataSizeAndAllocator(0, EASTL_TUPLE_VECTOR_DEFAULT_ALLOCATOR)\n\t{}\n\n\tTupleVecImpl(const allocator_type& allocator)\n\t\t: mDataSizeAndAllocator(0, allocator)\n\t{}\n\n\tTupleVecImpl(this_type&& x)\n\t\t: mDataSizeAndAllocator(0, eastl::move(x.get_allocator()))\n\t{\n\t\tswap(x);\n\t}\n\n\tTupleVecImpl(this_type&& x, const Allocator& allocator) \n\t\t: mDataSizeAndAllocator(0, allocator)\n\t{\n\t\tif (get_allocator() == x.get_allocator()) // If allocators are equivalent, then we can safely swap member-by-member\n\t\t{\n\t\t\tswap(x);\n\t\t}\n\t\telse\n\t\t{\n\t\t\tthis_type temp(eastl::move(*this));\n\t\t\ttemp.swap(x);\n\t\t}\n\t}\n\n\tTupleVecImpl(const this_type& x) \n\t\t: mDataSizeAndAllocator(0, x.get_allocator())\n\t{\n\t\tDoInitFromIterator(x.begin(), x.end());\n\t}\n\n\ttemplate\n\tTupleVecImpl(const TupleVecImpl& x, const Allocator& allocator) \n\t\t: mDataSizeAndAllocator(0, allocator)\n\t{\n\t\tDoInitFromIterator(x.begin(), x.end());\n\t}\n\n\ttemplate\n\tTupleVecImpl(move_iterator begin, move_iterator end, const allocator_type& allocator = EASTL_TUPLE_VECTOR_DEFAULT_ALLOCATOR)\n\t\t: mDataSizeAndAllocator(0, allocator)\n\t{\n\t\tDoInitFromIterator(begin, end);\n\t}\n\n\tTupleVecImpl(const_iterator begin, const_iterator end, const allocator_type& allocator = EASTL_TUPLE_VECTOR_DEFAULT_ALLOCATOR)\n\t\t: mDataSizeAndAllocator(0, allocator )\n\t{\n\t\tDoInitFromIterator(begin, end);\n\t}\n\n\tTupleVecImpl(size_type n, const allocator_type& allocator = EASTL_TUPLE_VECTOR_DEFAULT_ALLOCATOR)\n\t\t: mDataSizeAndAllocator(0, allocator)\n\t{\n\t\tDoInitDefaultFill(n);\n\t}\n\n\tTupleVecImpl(size_type n, const Ts&... args) \n\t\t: mDataSizeAndAllocator(0, EASTL_TUPLE_VECTOR_DEFAULT_ALLOCATOR)\n\t{\n\t\tDoInitFillArgs(n, args...);\n\t}\n\n\tTupleVecImpl(size_type n, const Ts&... args, const allocator_type& allocator) \n\t\t: mDataSizeAndAllocator(0, allocator)\n\t{\n\t\tDoInitFillArgs(n, args...);\n\t}\n\n\tTupleVecImpl(size_type n, const_reference_tuple tup, const allocator_type& allocator = EASTL_TUPLE_VECTOR_DEFAULT_ALLOCATOR)\n\t\t: mDataSizeAndAllocator(0, allocator)\n\t{\n\t\tDoInitFillTuple(n, tup);\n\t}\n\n\tTupleVecImpl(const value_tuple* first, const value_tuple* last, const allocator_type& allocator = EASTL_TUPLE_VECTOR_DEFAULT_ALLOCATOR)\n\t\t: mDataSizeAndAllocator(0, allocator)\n\t{\n\t\tDoInitFromTupleArray(first, last);\n\t}\n\n\tTupleVecImpl(std::initializer_list iList, const allocator_type& allocator = EASTL_TUPLE_VECTOR_DEFAULT_ALLOCATOR)\n\t\t: mDataSizeAndAllocator(0, allocator)\n\t{\n\t\tDoInitFromTupleArray(iList.begin(), iList.end());\n\t}\n\nprotected:\n\t// ctor to provide a pre-allocated field of data that the container will own, specifically for fixed_tuple_vector\n\tTupleVecImpl(const allocator_type& allocator, void* pData, size_type capacity, size_type dataSize)\n\t\t: mpData(pData), mNumCapacity(capacity), mDataSizeAndAllocator(dataSize, allocator)\n\t{\n\t\tTupleRecurser::template SetNewData(*this, mpData, mNumCapacity, 0);\n\t}\n\npublic:\n\t~TupleVecImpl()\n\t{ \n\t\tswallow((eastl::destruct(TupleVecLeaf::mpData, TupleVecLeaf::mpData + mNumElements), 0)...);\n\t\tif (mpData)\n\t\t\tEASTLFree(get_allocator(), mpData, internalDataSize()); \n\t}\n\n\tvoid assign(size_type n, const Ts&... args)\n\t{\n\t\tif (n > mNumCapacity)\n\t\t{\n\t\t\tthis_type temp(n, args..., get_allocator()); // We have little choice but to reallocate with new memory.\n\t\t\tswap(temp);\n\t\t}\n\t\telse if (n > mNumElements) // If n > mNumElements ...\n\t\t{\n\t\t\tsize_type oldNumElements = mNumElements;\n\t\t\tswallow((eastl::fill(TupleVecLeaf::mpData, TupleVecLeaf::mpData + oldNumElements, args), 0)...);\n\t\t\tswallow((eastl::uninitialized_fill(TupleVecLeaf::mpData + oldNumElements,\n\t\t\t\t\t TupleVecLeaf::mpData + n, args), 0)...);\n\t\t\tmNumElements = n;\n\t\t}\n\t\telse // else 0 <= n <= mNumElements\n\t\t{\n\t\t\tswallow((eastl::fill(TupleVecLeaf::mpData, TupleVecLeaf::mpData + n, args), 0)...);\n\t\t\terase(begin() + n, end());\n\t\t}\n\t}\n\n\tvoid assign(const_iterator first, const_iterator last)\n\t{\n#if EASTL_ASSERT_ENABLED\n\t\tif (EASTL_UNLIKELY(!validate_iterator_pair(first, last)))\n\t\t\tEASTL_FAIL_MSG(\"tuple_vector::assign -- invalid iterator pair\");\n#endif\n\t\tsize_type newNumElements = last - first;\n\t\tif (newNumElements > mNumCapacity)\n\t\t{\n\t\t\tthis_type temp(first, last, get_allocator());\n\t\t\tswap(temp);\n\t\t}\n\t\telse\n\t\t{\n\t\t\tconst void* ppOtherData[sizeof...(Ts)] = {first.mpData[Indices]...};\n\t\t\tsize_type firstIdx = first.mIndex;\n\t\t\tsize_type lastIdx = last.mIndex;\n\t\t\tif (newNumElements > mNumElements) // If n > mNumElements ...\n\t\t\t{\n\t\t\t\tsize_type oldNumElements = mNumElements;\n\t\t\t\tswallow((eastl::copy((Ts*)(ppOtherData[Indices]) + firstIdx,\n\t\t\t\t\t\t (Ts*)(ppOtherData[Indices]) + firstIdx + oldNumElements,\n\t\t\t\t\t\t TupleVecLeaf::mpData), 0)...);\n\t\t\t\tswallow((eastl::uninitialized_copy((Ts*)(ppOtherData[Indices]) + firstIdx + oldNumElements,\n\t\t\t\t\t\t (Ts*)(ppOtherData[Indices]) + lastIdx,\n\t\t\t\t\t\t TupleVecLeaf::mpData + oldNumElements), 0)...);\n\t\t\t\tmNumElements = newNumElements;\n\t\t\t}\n\t\t\telse // else 0 <= n <= mNumElements\n\t\t\t{\n\t\t\t\tswallow((eastl::copy((Ts*)(ppOtherData[Indices]) + firstIdx, (Ts*)(ppOtherData[Indices]) + lastIdx,\n\t\t\t\t\t\t TupleVecLeaf::mpData), 0)...);\n\t\t\t\terase(begin() + newNumElements, end());\n\t\t\t}\n\t\t}\n\t}\n\n\tvoid assign(const value_tuple* first, const value_tuple* last)\n\t{\n#if EASTL_ASSERT_ENABLED\n\t\tif (EASTL_UNLIKELY(first > last || first == nullptr || last == nullptr))\n\t\t\tEASTL_FAIL_MSG(\"tuple_vector::assign from tuple array -- invalid ptrs\");\n#endif\n size_type newNumElements = static_cast(last - first);\n\t\tif (newNumElements > mNumCapacity)\n\t\t{\n\t\t\tthis_type temp(first, last, get_allocator());\n\t\t\tswap(temp);\n\t\t}\n\t\telse\n\t\t{\n\t\t\tif (newNumElements > mNumElements) // If n > mNumElements ...\n\t\t\t{\n\t\t\t\tsize_type oldNumElements = mNumElements;\n\t\t\t\t\n\t\t\t\tDoCopyFromTupleArray(begin(), begin() + oldNumElements, first);\n\t\t\t\tDoUninitializedCopyFromTupleArray(begin() + oldNumElements, begin() + newNumElements, first + oldNumElements);\n\t\t\t\tmNumElements = newNumElements;\n\t\t\t}\n\t\t\telse // else 0 <= n <= mNumElements\n\t\t\t{\n\t\t\t\tDoCopyFromTupleArray(begin(), begin() + newNumElements, first);\n\t\t\t\terase(begin() + newNumElements, end());\n\t\t\t}\n\t\t}\n\t}\n\n\treference_tuple push_back()\n\t{\n\t\tsize_type oldNumElements = mNumElements;\n\t\tsize_type newNumElements = oldNumElements + 1;\n\t\tsize_type oldNumCapacity = mNumCapacity;\n\t\tmNumElements = newNumElements;\n\t\tDoGrow(oldNumElements, oldNumCapacity, newNumElements);\n\t\tswallow((detail::allocator_construct(get_allocator(), TupleVecLeaf::mpData + oldNumElements), 0)...);\n\t\treturn back();\n\t}\n\n\tvoid push_back(const Ts&... args)\n\t{\n\t\tsize_type oldNumElements = mNumElements;\n\t\tsize_type newNumElements = oldNumElements + 1;\n\t\tsize_type oldNumCapacity = mNumCapacity;\n\t\tmNumElements = newNumElements;\n\t\tDoGrow(oldNumElements, oldNumCapacity, newNumElements);\n\t\tswallow((detail::allocator_construct(get_allocator(), TupleVecLeaf::mpData + oldNumElements, args), 0)...);\n\t}\n\n\tvoid push_back_uninitialized()\n\t{\n\t\tsize_type oldNumElements = mNumElements;\n\t\tsize_type newNumElements = oldNumElements + 1;\n\t\tsize_type oldNumCapacity = mNumCapacity;\n\t\tmNumElements = newNumElements;\n\t\tDoGrow(oldNumElements, oldNumCapacity, newNumElements);\n\t}\n\t\n\treference_tuple emplace_back(Ts&&... args)\n\t{\n\t\tsize_type oldNumElements = mNumElements;\n\t\tsize_type newNumElements = oldNumElements + 1;\n\t\tsize_type oldNumCapacity = mNumCapacity;\n\t\tmNumElements = newNumElements;\n\t\tDoGrow(oldNumElements, oldNumCapacity, newNumElements);\n\t\tswallow((detail::allocator_construct(get_allocator(), TupleVecLeaf::mpData + oldNumElements, eastl::forward(args)), 0)...);\n\t\treturn back();\n\t}\n\n\titerator emplace(const_iterator pos, Ts&&... args)\n\t{\n#if EASTL_ASSERT_ENABLED\n\t\tif (EASTL_UNLIKELY(validate_iterator(pos) == isf_none))\n\t\t\tEASTL_FAIL_MSG(\"tuple_vector::emplace -- invalid iterator\");\n#endif\n\t\tsize_type firstIdx = pos - cbegin();\n\t\tsize_type oldNumElements = mNumElements;\n\t\tsize_type newNumElements = mNumElements + 1;\n\t\tsize_type oldNumCapacity = mNumCapacity;\n\t\tmNumElements = newNumElements;\n\t\tif (newNumElements > oldNumCapacity || firstIdx != oldNumElements)\n\t\t{\n\t\t\tif (newNumElements > oldNumCapacity)\n\t\t\t{\n\t\t\t\tconst size_type newCapacity = eastl::max(GetNewCapacity(oldNumCapacity), newNumElements);\n\n\t\t\t\tvoid* ppNewLeaf[sizeof...(Ts)];\n\t\t\t\tpair allocation =\tTupleRecurser::template DoAllocate(\n\t\t\t\t\t*this, ppNewLeaf, newCapacity, 0);\n\n\t\t\t\tswallow((TupleVecLeaf::DoUninitializedMoveAndDestruct(\n\t\t\t\t\t0, firstIdx, (Ts*)ppNewLeaf[Indices]), 0)...);\n\t\t\t\tswallow((TupleVecLeaf::DoUninitializedMoveAndDestruct(\n\t\t\t\t\tfirstIdx, oldNumElements, (Ts*)ppNewLeaf[Indices] + firstIdx + 1), 0)...);\n\t\t\t\tswallow(::new ((Ts*)ppNewLeaf[Indices] + firstIdx) Ts(eastl::forward(args))...);\n\t\t\t\tswallow(TupleVecLeaf::mpData = (Ts*)ppNewLeaf[Indices]...);\n\n\t\t\t\tEASTLFree(get_allocator(), mpData, internalDataSize());\n\t\t\t\tmpData = allocation.first;\n\t\t\t\tmNumCapacity = newCapacity;\n\t\t\t\tinternalDataSize() = allocation.second;\n\t\t\t}\n\t\t\telse\n\t\t\t{\n\t\t\t\tswallow((TupleVecLeaf::DoInsertValue(firstIdx, oldNumElements, eastl::forward(args)), 0)...);\n\t\t\t}\n\t\t}\n\t\telse\n\t\t{\n\t\t\tswallow(::new (TupleVecLeaf::mpData + oldNumElements) Ts(eastl::forward(args))...);\n\t\t}\n\t\treturn begin() + firstIdx;\n\t}\n\n\titerator insert(const_iterator pos, size_type n, const Ts&... args)\n\t{\n#if EASTL_ASSERT_ENABLED\n\t\tif (EASTL_UNLIKELY(validate_iterator(pos) == isf_none))\n\t\t\tEASTL_FAIL_MSG(\"tuple_vector::insert -- invalid iterator\");\n#endif\n\t\tsize_type firstIdx = pos - cbegin();\n\t\tsize_type lastIdx = firstIdx + n;\n\t\tsize_type oldNumElements = mNumElements;\n\t\tsize_type newNumElements = mNumElements + n;\n\t\tsize_type oldNumCapacity = mNumCapacity;\n\t\tmNumElements = newNumElements;\n\t\tif (newNumElements > oldNumCapacity || firstIdx != oldNumElements)\n\t\t{\n\t\t\tif (newNumElements > oldNumCapacity)\n\t\t\t{\n\t\t\t\tconst size_type newCapacity = eastl::max(GetNewCapacity(oldNumCapacity), newNumElements);\n\n\t\t\t\tvoid* ppNewLeaf[sizeof...(Ts)];\n\t\t\t\tpair allocation = TupleRecurser::template DoAllocate(\n\t\t\t\t\t\t*this, ppNewLeaf, newCapacity, 0);\n\n\t\t\t\tswallow((TupleVecLeaf::DoUninitializedMoveAndDestruct(\n\t\t\t\t\t0, firstIdx, (Ts*)ppNewLeaf[Indices]), 0)...);\n\t\t\t\tswallow((TupleVecLeaf::DoUninitializedMoveAndDestruct(\n\t\t\t\t\tfirstIdx, oldNumElements, (Ts*)ppNewLeaf[Indices] + lastIdx), 0)...);\n\t\t\t\tswallow((eastl::uninitialized_fill((Ts*)ppNewLeaf[Indices] + firstIdx, (Ts*)ppNewLeaf[Indices] + lastIdx, args), 0)...);\n\t\t\t\tswallow(TupleVecLeaf::mpData = (Ts*)ppNewLeaf[Indices]...);\n\t\t\n\t\t\t\tEASTLFree(get_allocator(), mpData, internalDataSize());\n\t\t\t\tmpData = allocation.first;\n\t\t\t\tmNumCapacity = newCapacity;\n\t\t\t\tinternalDataSize() = allocation.second;\n\t\t\t}\n\t\t\telse\n\t\t\t{\n\t\t\t\tswallow((TupleVecLeaf::DoInsertAndFill(firstIdx, n, oldNumElements, args), 0)...);\n\t\t\t}\n\t\t}\n\t\telse\n\t\t{\n\t\t\tswallow((eastl::uninitialized_fill(TupleVecLeaf::mpData + oldNumElements,\n\t\t\t\t\t TupleVecLeaf::mpData + newNumElements, args), 0)...);\n\t\t}\n\t\treturn begin() + firstIdx;\n\t}\n\n\titerator insert(const_iterator pos, const_iterator first, const_iterator last)\n\t{\n#if EASTL_ASSERT_ENABLED\n\t\tif (EASTL_UNLIKELY(validate_iterator(pos) == isf_none))\n\t\t\tEASTL_FAIL_MSG(\"tuple_vector::insert -- invalid iterator\");\n\t\tif (EASTL_UNLIKELY(!validate_iterator_pair(first, last)))\n\t\t\tEASTL_FAIL_MSG(\"tuple_vector::insert -- invalid iterator pair\");\n#endif\n\t\tsize_type posIdx = pos - cbegin();\n\t\tsize_type firstIdx = first.mIndex;\n\t\tsize_type lastIdx = last.mIndex;\n\t\tsize_type numToInsert = last - first;\n\t\tsize_type oldNumElements = mNumElements;\n\t\tsize_type newNumElements = oldNumElements + numToInsert;\n\t\tsize_type oldNumCapacity = mNumCapacity;\n\t\tmNumElements = newNumElements;\n\t\tconst void* ppOtherData[sizeof...(Ts)] = {first.mpData[Indices]...};\n\t\tif (newNumElements > oldNumCapacity || posIdx != oldNumElements)\n\t\t{\n\t\t\tif (newNumElements > oldNumCapacity)\n\t\t\t{\n\t\t\t\tconst size_type newCapacity = eastl::max(GetNewCapacity(oldNumCapacity), newNumElements);\n\n\t\t\t\tvoid* ppNewLeaf[sizeof...(Ts)];\n\t\t\t\tpair allocation = TupleRecurser::template DoAllocate(\n\t\t\t\t\t\t*this, ppNewLeaf, newCapacity, 0);\n\n\t\t\t\tswallow((TupleVecLeaf::DoUninitializedMoveAndDestruct(\n\t\t\t\t\t0, posIdx, (Ts*)ppNewLeaf[Indices]), 0)...);\n\t\t\t\tswallow((TupleVecLeaf::DoUninitializedMoveAndDestruct(\n\t\t\t\t\tposIdx, oldNumElements, (Ts*)ppNewLeaf[Indices] + posIdx + numToInsert), 0)...);\n\t\t\t\tswallow((eastl::uninitialized_copy((Ts*)(ppOtherData[Indices]) + firstIdx,\n\t\t\t\t\t\t (Ts*)(ppOtherData[Indices]) + lastIdx,\n\t\t\t\t\t\t (Ts*)ppNewLeaf[Indices] + posIdx), 0)...);\n\t\t\t\tswallow(TupleVecLeaf::mpData = (Ts*)ppNewLeaf[Indices]...);\n\t\t\t\t\n\t\t\t\tEASTLFree(get_allocator(), mpData, internalDataSize());\n\t\t\t\tmpData = allocation.first;\n\t\t\t\tmNumCapacity = newCapacity;\n\t\t\t\tinternalDataSize() = allocation.second;\n\t\t\t}\n\t\t\telse\n\t\t\t{\n\t\t\t\tswallow((TupleVecLeaf::DoInsertRange(\n\t\t\t\t\t(Ts*)(ppOtherData[Indices]) + firstIdx, (Ts*)(ppOtherData[Indices]) + lastIdx,\n\t\t\t\t\tTupleVecLeaf::mpData + posIdx, oldNumElements), 0)...);\n\t\t\t}\n\t\t}\n\t\telse\n\t\t{\n\t\t\tswallow((eastl::uninitialized_copy((Ts*)(ppOtherData[Indices]) + firstIdx,\n\t\t\t\t\t (Ts*)(ppOtherData[Indices]) + lastIdx,\n\t\t\t\t\t TupleVecLeaf::mpData + posIdx), 0)...);\n\t\t}\n\t\treturn begin() + posIdx;\n\t}\n\n\titerator insert(const_iterator pos, const value_tuple* first, const value_tuple* last)\n\t{\n#if EASTL_ASSERT_ENABLED\n\t\tif (EASTL_UNLIKELY(validate_iterator(pos) == isf_none))\n\t\t\tEASTL_FAIL_MSG(\"tuple_vector::insert -- invalid iterator\");\n\t\tif (EASTL_UNLIKELY(first > last || first == nullptr || last == nullptr))\n\t\t\tEASTL_FAIL_MSG(\"tuple_vector::insert -- invalid source pointers\");\n#endif\n\t\tsize_type posIdx = pos - cbegin();\n\t\tsize_type numToInsert = static_cast(last - first);\n\t\tsize_type oldNumElements = mNumElements;\n\t\tsize_type newNumElements = oldNumElements + numToInsert;\n\t\tsize_type oldNumCapacity = mNumCapacity;\n\t\tmNumElements = newNumElements;\n\t\tif (newNumElements > oldNumCapacity || posIdx != oldNumElements)\n\t\t{\n\t\t\tif (newNumElements > oldNumCapacity)\n\t\t\t{\n\t\t\t\tconst size_type newCapacity = eastl::max(GetNewCapacity(oldNumCapacity), newNumElements);\n\n\t\t\t\tvoid* ppNewLeaf[sizeof...(Ts)];\n\t\t\t\tpair allocation = TupleRecurser::template DoAllocate(\n\t\t\t\t\t*this, ppNewLeaf, newCapacity, 0);\n\n\t\t\t\tswallow((TupleVecLeaf::DoUninitializedMoveAndDestruct(\n\t\t\t\t\t0, posIdx, (Ts*)ppNewLeaf[Indices]), 0)...);\n\t\t\t\tswallow((TupleVecLeaf::DoUninitializedMoveAndDestruct(\n\t\t\t\t\tposIdx, oldNumElements, (Ts*)ppNewLeaf[Indices] + posIdx + numToInsert), 0)...);\n\t\t\t\t\n\t\t\t\tswallow(TupleVecLeaf::mpData = (Ts*)ppNewLeaf[Indices]...);\n\n\t\t\t\t// Do this after mpData is updated so that we can use new iterators\n\t\t\t\tDoUninitializedCopyFromTupleArray(begin() + posIdx, begin() + posIdx + numToInsert, first);\n\n\t\t\t\tEASTLFree(get_allocator(), mpData, internalDataSize());\n\t\t\t\tmpData = allocation.first;\n\t\t\t\tmNumCapacity = newCapacity;\n\t\t\t\tinternalDataSize() = allocation.second;\n\t\t\t}\n\t\t\telse\n\t\t\t{\n\t\t\t\tconst size_type nExtra = oldNumElements - posIdx;\n\t\t\t\tvoid* ppDataEnd[sizeof...(Ts)] = { (void*)(TupleVecLeaf::mpData + oldNumElements)... };\n\t\t\t\tvoid* ppDataBegin[sizeof...(Ts)] = { (void*)(TupleVecLeaf::mpData + posIdx)... };\n\t\t\t\tif (numToInsert < nExtra) // If the inserted values are entirely within initialized memory (i.e. are before mpEnd)...\n\t\t\t\t{\n\t\t\t\t\tswallow((eastl::uninitialized_move((Ts*)ppDataEnd[Indices] - numToInsert,\n\t\t\t\t\t\t(Ts*)ppDataEnd[Indices], (Ts*)ppDataEnd[Indices]), 0)...);\n\t\t\t\t\t// We need move_backward because of potential overlap issues.\n\t\t\t\t\tswallow((eastl::move_backward((Ts*)ppDataBegin[Indices],\n\t\t\t\t\t\t(Ts*)ppDataEnd[Indices] - numToInsert, (Ts*)ppDataEnd[Indices]), 0)...); \n\t\t\t\t\t\n\t\t\t\t\tDoCopyFromTupleArray(pos, pos + numToInsert, first);\n\t\t\t\t}\n\t\t\t\telse\n\t\t\t\t{\n\t\t\t\t\tsize_type numToInitialize = numToInsert - nExtra;\n\t\t\t\t\tswallow((eastl::uninitialized_move((Ts*)ppDataBegin[Indices],\n\t\t\t\t\t\t(Ts*)ppDataEnd[Indices], (Ts*)ppDataEnd[Indices] + numToInitialize), 0)...);\n\t\t\t\t\t\n\t\t\t\t\tDoCopyFromTupleArray(pos, begin() + oldNumElements, first);\n\t\t\t\t\tDoUninitializedCopyFromTupleArray(begin() + oldNumElements, pos + numToInsert, first + nExtra);\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t\telse\n\t\t{\n\t\t\tDoUninitializedCopyFromTupleArray(pos, pos + numToInsert, first);\n\t\t}\n\t\treturn begin() + posIdx;\n\t}\n\n\titerator erase(const_iterator first, const_iterator last)\n\t{\n#if EASTL_ASSERT_ENABLED\n\t\tif (EASTL_UNLIKELY(validate_iterator(first) == isf_none || validate_iterator(last) == isf_none))\n\t\t\tEASTL_FAIL_MSG(\"tuple_vector::erase -- invalid iterator\");\n\t\tif (EASTL_UNLIKELY(!validate_iterator_pair(first, last)))\n\t\t\tEASTL_FAIL_MSG(\"tuple_vector::erase -- invalid iterator pair\");\n#endif\n\t\tif (first != last)\n\t\t{\n\t\t\tsize_type firstIdx = first - cbegin();\n\t\t\tsize_type lastIdx = last - cbegin();\n\t\t\tsize_type oldNumElements = mNumElements;\n\t\t\tsize_type newNumElements = oldNumElements - (lastIdx - firstIdx);\n\t\t\tmNumElements = newNumElements;\n\t\t\tswallow((eastl::move(TupleVecLeaf::mpData + lastIdx,\n\t\t\t\t\t TupleVecLeaf::mpData + oldNumElements,\n\t\t\t\t\t TupleVecLeaf::mpData + firstIdx), 0)...);\n\t\t\tswallow((eastl::destruct(TupleVecLeaf::mpData + newNumElements,\n\t\t\t\t\t TupleVecLeaf::mpData + oldNumElements), 0)...);\n\t\t}\n\t\treturn begin() + first.mIndex;\n\t}\n\t\n\titerator erase_unsorted(const_iterator pos)\n\t{\n#if EASTL_ASSERT_ENABLED\n\t\tif (EASTL_UNLIKELY(validate_iterator(pos) == isf_none))\n\t\t\tEASTL_FAIL_MSG(\"tuple_vector::erase_unsorted -- invalid iterator\");\n#endif\n\t\tsize_type oldNumElements = mNumElements;\n\t\tsize_type newNumElements = oldNumElements - 1;\n\t\tmNumElements = newNumElements;\n\t\tswallow((eastl::move(TupleVecLeaf::mpData + newNumElements,\n\t\t\t\t TupleVecLeaf::mpData + oldNumElements,\n\t\t\t\t TupleVecLeaf::mpData + (pos - begin())), 0)...);\n\t\tswallow((eastl::destruct(TupleVecLeaf::mpData + newNumElements,\n\t\t\t\t TupleVecLeaf::mpData + oldNumElements), 0)...);\n\t\treturn begin() + pos.mIndex;\n\t}\n\n\tvoid resize(size_type n)\n\t{\n\t\tsize_type oldNumElements = mNumElements;\n\t\tsize_type oldNumCapacity = mNumCapacity;\n\t\tmNumElements = n;\n\t\tif (n > oldNumElements)\n\t\t{\n\t\t\tif (n > oldNumCapacity)\n\t\t\t{\n\t\t\t\tDoReallocate(oldNumElements, eastl::max(GetNewCapacity(oldNumCapacity), n));\n\t\t\t}\n\t\t\tswallow((eastl::uninitialized_value_construct_n(TupleVecLeaf::mpData + oldNumElements, n - oldNumElements), 0)...);\n\t\t}\n\t\telse\n\t\t{\n\t\t\tswallow((eastl::destruct(TupleVecLeaf::mpData + n,\n\t\t\t\t\t TupleVecLeaf::mpData + oldNumElements), 0)...);\n\t\t}\n\t}\n\n\tvoid resize(size_type n, const Ts&... args)\n\t{\n\t\tsize_type oldNumElements = mNumElements;\n\t\tsize_type oldNumCapacity = mNumCapacity;\n\t\tmNumElements = n;\n\t\tif (n > oldNumElements)\n\t\t{\n\t\t\tif (n > oldNumCapacity)\n\t\t\t{\n\t\t\t\tDoReallocate(oldNumElements, eastl::max(GetNewCapacity(oldNumCapacity), n));\n\t\t\t} \n\t\t\tswallow((eastl::uninitialized_fill(TupleVecLeaf::mpData + oldNumElements,\n\t\t\t\t\t TupleVecLeaf::mpData + n, args), 0)...);\n\t\t}\n\t\telse\n\t\t{\n\t\t\tswallow((eastl::destruct(TupleVecLeaf::mpData + n,\n\t\t\t\t\t TupleVecLeaf::mpData + oldNumElements), 0)...);\n\t\t}\n\t}\n\n\tvoid reserve(size_type n)\n\t{\n\t\tDoConditionalReallocate(mNumElements, mNumCapacity, n);\n\t}\n\n\tvoid shrink_to_fit()\n\t{\n\t\tthis_type temp(move_iterator(begin()), move_iterator(end()), get_allocator());\n\t\tswap(temp);\n\t}\n\n\tvoid clear() EA_NOEXCEPT\n\t{\n\t\tsize_type oldNumElements = mNumElements;\n\t\tmNumElements = 0;\n\t\tswallow((eastl::destruct(TupleVecLeaf::mpData, TupleVecLeaf::mpData + oldNumElements), 0)...);\n\t}\n\n\tvoid pop_back()\n\t{\n#if EASTL_ASSERT_ENABLED\n\t\tif (EASTL_UNLIKELY(mNumElements <= 0))\n\t\t\tEASTL_FAIL_MSG(\"tuple_vector::pop_back -- container is empty\");\n#endif\n\t\tsize_type oldNumElements = mNumElements--;\n\t\tswallow((eastl::destruct(TupleVecLeaf::mpData + oldNumElements - 1,\n\t\t\t\t TupleVecLeaf::mpData + oldNumElements), 0)...);\n\t}\n\n\tvoid swap(this_type& x)\n\t{\n\t\tswallow((eastl::swap(TupleVecLeaf::mpData, x.TupleVecLeaf::mpData), 0)...);\n\t\teastl::swap(mpData, x.mpData);\n\t\teastl::swap(mNumElements, x.mNumElements);\n\t\teastl::swap(mNumCapacity, x.mNumCapacity);\n\t\teastl::swap(get_allocator(), x.get_allocator());\n\t\teastl::swap(internalDataSize(), x.internalDataSize());\n\t}\n\n\tvoid assign(size_type n, const_reference_tuple tup) { assign(n, eastl::get(tup)...); }\n\tvoid assign(std::initializer_list iList) { assign(iList.begin(), iList.end()); }\n\n\tvoid push_back(Ts&&... args) { emplace_back(eastl::forward(args)...); }\n\tvoid push_back(const_reference_tuple tup) { push_back(eastl::get(tup)...); }\n\tvoid push_back(rvalue_tuple tup) { emplace_back(eastl::forward(eastl::get(tup))...); }\n\n\tvoid emplace_back(rvalue_tuple tup) { emplace_back(eastl::forward(eastl::get(tup))...); }\n\tvoid emplace(const_iterator pos, rvalue_tuple tup) { emplace(pos, eastl::forward(eastl::get(tup))...); }\n\n\titerator insert(const_iterator pos, const Ts&... args) { return insert(pos, 1, args...); }\n\titerator insert(const_iterator pos, Ts&&... args) { return emplace(pos, eastl::forward(args)...); }\n\titerator insert(const_iterator pos, rvalue_tuple tup) { return emplace(pos, eastl::forward(eastl::get(tup))...); }\n\titerator insert(const_iterator pos, const_reference_tuple tup) { return insert(pos, eastl::get(tup)...); }\n\titerator insert(const_iterator pos, size_type n, const_reference_tuple tup) { return insert(pos, n, eastl::get(tup)...); }\n\titerator insert(const_iterator pos, std::initializer_list iList) { return insert(pos, iList.begin(), iList.end()); }\n\n\titerator erase(const_iterator pos) { return erase(pos, pos + 1); }\n\treverse_iterator erase(const_reverse_iterator pos) { return reverse_iterator(erase((pos + 1).base(), (pos).base())); }\n\treverse_iterator erase(const_reverse_iterator first, const_reverse_iterator last) { return reverse_iterator(erase((last).base(), (first).base())); }\n\treverse_iterator erase_unsorted(const_reverse_iterator pos) { return reverse_iterator(erase_unsorted((pos + 1).base())); }\n\n\tvoid resize(size_type n, const_reference_tuple tup) { resize(n, eastl::get(tup)...); }\n\n\tbool empty() const EA_NOEXCEPT { return mNumElements == 0; }\n\tsize_type size() const EA_NOEXCEPT { return mNumElements; }\n\tsize_type capacity() const EA_NOEXCEPT { return mNumCapacity; }\n\n\titerator begin() EA_NOEXCEPT { return iterator(this, 0); }\n\tconst_iterator begin() const EA_NOEXCEPT { return const_iterator((const_this_type*)(this), 0); }\n\tconst_iterator cbegin() const EA_NOEXCEPT { return const_iterator((const_this_type*)(this), 0); }\n\n\titerator end() EA_NOEXCEPT { return iterator(this, size()); }\n\tconst_iterator end() const EA_NOEXCEPT { return const_iterator((const_this_type*)(this), size()); }\n\tconst_iterator cend() const EA_NOEXCEPT { return const_iterator((const_this_type*)(this), size()); }\n\n\treverse_iterator rbegin() EA_NOEXCEPT { return reverse_iterator(end()); }\n\tconst_reverse_iterator rbegin() const EA_NOEXCEPT { return const_reverse_iterator(end()); }\n\tconst_reverse_iterator crbegin() const EA_NOEXCEPT { return const_reverse_iterator(end()); }\n\t\n\treverse_iterator rend() EA_NOEXCEPT { return reverse_iterator(begin()); }\n\tconst_reverse_iterator rend() const EA_NOEXCEPT { return const_reverse_iterator(begin()); }\n\tconst_reverse_iterator crend() const EA_NOEXCEPT { return const_reverse_iterator(begin()); }\n\n\tptr_tuple data() EA_NOEXCEPT { return ptr_tuple(TupleVecLeaf::mpData...); }\n\tconst_ptr_tuple data() const EA_NOEXCEPT { return const_ptr_tuple(TupleVecLeaf::mpData...); }\n\n\treference_tuple at(size_type n) \n\t{ \n#if EASTL_EXCEPTIONS_ENABLED\n\t\tif (EASTL_UNLIKELY(n >= mNumElements))\n\t\t\tthrow std::out_of_range(\"tuple_vector::at -- out of range\");\n#elif EASTL_ASSERT_ENABLED\n\t\tif (EASTL_UNLIKELY(n >= mNumElements))\n\t\t\tEASTL_FAIL_MSG(\"tuple_vector::at -- out of range\");\n#endif\n\t\treturn reference_tuple(*(TupleVecLeaf::mpData + n)...); \n\t}\n\n\tconst_reference_tuple at(size_type n) const\n\t{\n#if EASTL_EXCEPTIONS_ENABLED\n\t\tif (EASTL_UNLIKELY(n >= mNumElements))\n\t\t\tthrow std::out_of_range(\"tuple_vector::at -- out of range\");\n#elif EASTL_ASSERT_ENABLED\n\t\tif (EASTL_UNLIKELY(n >= mNumElements))\n\t\t\tEASTL_FAIL_MSG(\"tuple_vector::at -- out of range\");\n#endif\n\t\treturn const_reference_tuple(*(TupleVecLeaf::mpData + n)...); \n\t}\n\t\n\treference_tuple operator[](size_type n) { return at(n); }\n\tconst_reference_tuple operator[](size_type n) const { return at(n); }\n\t\n\treference_tuple front() \n\t{\n\t\t#if EASTL_ASSERT_ENABLED && EASTL_EMPTY_REFERENCE_ASSERT_ENABLED\n\t\t\tif (EASTL_UNLIKELY(mNumElements == 0)) // We don't allow the user to reference an empty container.\n\t\t\t\tEASTL_FAIL_MSG(\"tuple_vector::front -- empty vector\");\n\t\t#else\n\t\t\t// We allow the user to reference an empty container.\n\t\t#endif\n\n\t\treturn at(0); \n\t}\n\n\tconst_reference_tuple front() const\n\t{\n\t\t#if EASTL_ASSERT_ENABLED && EASTL_EMPTY_REFERENCE_ASSERT_ENABLED\n\t\t\tif (EASTL_UNLIKELY(mNumElements == 0)) // We don't allow the user to reference an empty container.\n\t\t\t\tEASTL_FAIL_MSG(\"tuple_vector::front -- empty vector\");\n\t\t#else\n\t\t\t// We allow the user to reference an empty container.\n\t\t#endif\n\n\t\treturn at(0); \n\t}\n\t\n\treference_tuple back() \n\t{\n\t\t#if EASTL_ASSERT_ENABLED\n\t\t\tif (EASTL_UNLIKELY(mNumElements == 0)) // We don't allow the user to reference an empty container.\n\t\t\t\tEASTL_FAIL_MSG(\"tuple_vector::back -- empty vector\");\n\t\t#endif\n\n\t\treturn at(size() - 1); \n\t}\n\n\tconst_reference_tuple back() const \n\t{\n\t\t#if EASTL_ASSERT_ENABLED\n\t\t\tif (EASTL_UNLIKELY(mNumElements == 0)) // We don't allow the user to reference an empty container.\n\t\t\t\tEASTL_FAIL_MSG(\"tuple_vector::back -- empty vector\");\n\t\t#endif\n\n\t\treturn at(size() - 1); \n\t}\n\n\ttemplate \n\ttuplevec_element_t* get() \n\t{\n\t\ttypedef tuplevec_element_t Element;\n\t\treturn TupleVecLeaf::mpData;\n\t}\n\ttemplate \n\tconst tuplevec_element_t* get() const\n\t{\n\t\ttypedef tuplevec_element_t Element;\n\t\treturn TupleVecLeaf::mpData;\n\t}\n\n\ttemplate \n\tT* get() \n\t{ \n\t\ttypedef tuplevec_index> Index;\n\t\treturn TupleVecLeaf::mpData;\n\t}\n\ttemplate \n\tconst T* get() const\n\t{\n\t\ttypedef tuplevec_index> Index;\n\t\treturn TupleVecLeaf::mpData;\n\t}\n\n\tthis_type& operator=(const this_type& other)\n\t{\n\t\tif (this != &other)\n\t\t{\n\t\t\tclear();\n\t\t\tassign(other.begin(), other.end());\n\t\t}\n\t\treturn *this;\n\t}\n\n\tthis_type& operator=(this_type&& other)\n\t{\n\t\tif (this != &other)\n\t\t{\n\t\t\tswap(other);\n\t\t}\n\t\treturn *this;\n\t}\n\n\tthis_type& operator=(std::initializer_list iList) \n\t{\n\t\tassign(iList.begin(), iList.end());\n\t\treturn *this; \n\t}\n\n\tbool validate() const EA_NOEXCEPT\n\t{\n\t\tif (mNumElements > mNumCapacity)\n\t\t\treturn false;\n\t\tif (!(variadicAnd(mpData <= TupleVecLeaf::mpData...)))\n\t\t\treturn false;\n\t\tvoid* pDataEnd = (void*)((uintptr_t)mpData + internalDataSize());\n\t\tif (!(variadicAnd(pDataEnd >= TupleVecLeaf::mpData...)))\n\t\t\treturn false;\n\t\treturn true;\n\t}\n\n\tint validate_iterator(const_iterator iter) const EA_NOEXCEPT\n\t{\n\t\tif (!(variadicAnd(iter.mpData[Indices] == TupleVecLeaf::mpData...)))\n\t\t\treturn isf_none;\n\t\tif (iter.mIndex < mNumElements)\n\t\t\treturn (isf_valid | isf_current | isf_can_dereference);\n\t\tif (iter.mIndex <= mNumElements)\n\t\t\treturn (isf_valid | isf_current);\n\t\treturn isf_none;\n\t}\n\n\tstatic bool validate_iterator_pair(const_iterator first, const_iterator last) EA_NOEXCEPT\n\t{\n\t\treturn (first.mIndex <= last.mIndex) && variadicAnd(first.mpData[Indices] == last.mpData[Indices]...);\n\t}\n\n\tEASTL_INTERNAL_DISABLE_DEPRECATED() // 'unwrap_iterator': was declared deprecated\n\t\n\ttemplate ::value, bool>::type>\n\tEASTL_REMOVE_AT_2024_SEPT int validate_iterator(Iterator iter) const EA_NOEXCEPT { return validate_iterator(unwrap_iterator(iter)); }\n\n\ttemplate ::value, bool>::type>\n\tEASTL_REMOVE_AT_2024_SEPT static bool validate_iterator_pair(Iterator first, Iterator last) EA_NOEXCEPT { return validate_iterator_pair(unwrap_iterator(first), unwrap_iterator(last)); }\n\n\tEASTL_INTERNAL_RESTORE_DEPRECATED()\n\n\tallocator_type& get_allocator() EA_NOEXCEPT { return mDataSizeAndAllocator.second(); }\n\tconst allocator_type& get_allocator() const EA_NOEXCEPT { return mDataSizeAndAllocator.second(); }\n\n\tvoid set_allocator(const allocator_type& alloc)\n\t{\n\t\tif(mNumCapacity > 0 && mDataSizeAndAllocator.second() != alloc)\n\t\t\tEASTL_THROW_MSG_OR_ASSERT(std::logic_error, \"tuple_vector::set_allocator -- cannot change allocator after allocations have been made.\");\n\t\tmDataSizeAndAllocator.second() = alloc;\n\t}\n\nprotected:\n\n\tvoid* mpData = nullptr;\n\tsize_type mNumElements = 0;\n\tsize_type mNumCapacity = 0;\n\n\tcompressed_pair mDataSizeAndAllocator;\n\n\tsize_type& internalDataSize() EA_NOEXCEPT { return mDataSizeAndAllocator.first(); }\n\tsize_type const& internalDataSize() const EA_NOEXCEPT { return mDataSizeAndAllocator.first(); }\n\n\tfriend struct TupleRecurser<>;\n\ttemplate\n\tfriend struct TupleRecurser;\n\n\ttemplate \n\tvoid DoInitFromIterator(move_iterator begin, move_iterator end)\n\t{\n#if EASTL_ASSERT_ENABLED\n\t\tif (EASTL_UNLIKELY(!validate_iterator_pair(begin.base(), end.base())))\n\t\t\tEASTL_FAIL_MSG(\"tuple_vector::erase -- invalid iterator pair\");\n#endif\n\t\tsize_type newNumElements = (size_type)(end - begin);\n\t\tconst void* ppOtherData[sizeof...(Ts)] = { begin.base().mpData[Indices]... };\n\t\tsize_type beginIdx = begin.base().mIndex;\n\t\tsize_type endIdx = end.base().mIndex;\n\t\tDoConditionalReallocate(0, mNumCapacity, newNumElements);\n\t\tmNumElements = newNumElements;\n\t\tswallow((eastl::uninitialized_move(eastl::move_iterator((Ts*)(ppOtherData[Indices]) + beginIdx),\n\t\t\t\t eastl::move_iterator((Ts*)(ppOtherData[Indices]) + endIdx),\n\t\t\t\t TupleVecLeaf::mpData), 0)...);\n\t}\n\n\tvoid DoInitFromIterator(const_iterator begin, const_iterator end)\n\t{\n#if EASTL_ASSERT_ENABLED\n\t\tif (EASTL_UNLIKELY(!validate_iterator_pair(begin, end)))\n\t\t\tEASTL_FAIL_MSG(\"tuple_vector::erase -- invalid iterator pair\");\n#endif\n\t\tsize_type newNumElements = (size_type)(end - begin);\n\t\tconst void* ppOtherData[sizeof...(Ts)] = { begin.mpData[Indices]... };\n\t\tsize_type beginIdx = begin.mIndex;\n\t\tsize_type endIdx = end.mIndex;\n\t\tDoConditionalReallocate(0, mNumCapacity, newNumElements);\n\t\tmNumElements = newNumElements;\n\t\tswallow((eastl::uninitialized_copy((Ts*)(ppOtherData[Indices]) + beginIdx,\n\t\t\t\t (Ts*)(ppOtherData[Indices]) + endIdx,\n\t\t\t\t TupleVecLeaf::mpData), 0)...);\n\t}\n\n\tvoid DoInitFillTuple(size_type n, const_reference_tuple tup) { DoInitFillArgs(n, eastl::get(tup)...); }\n\n\tvoid DoInitFillArgs(size_type n, const Ts&... args)\n\t{\n\t\tDoConditionalReallocate(0, mNumCapacity, n);\n\t\tmNumElements = n;\n\t\tswallow((eastl::uninitialized_fill(TupleVecLeaf::mpData, TupleVecLeaf::mpData + n, args), 0)...);\n\t}\n\n\tvoid DoInitDefaultFill(size_type n)\n\t{\n\t\tDoConditionalReallocate(0, mNumCapacity, n);\n\t\tmNumElements = n;\n\t\tswallow((eastl::uninitialized_value_construct_n(TupleVecLeaf::mpData, n), 0)...);\n\t}\n\n\tvoid DoInitFromTupleArray(const value_tuple* first, const value_tuple* last)\n\t{\n#if EASTL_ASSERT_ENABLED\n\t\tif (EASTL_UNLIKELY(first > last || first == nullptr || last == nullptr))\n\t\t\tEASTL_FAIL_MSG(\"tuple_vector::ctor from tuple array -- invalid ptrs\");\n#endif\n\t\tsize_type newNumElements = static_cast(last - first);\n\t\tDoConditionalReallocate(0, mNumCapacity, newNumElements);\n\t\tmNumElements = newNumElements;\n\t\tDoUninitializedCopyFromTupleArray(begin(), end(), first);\n\t}\n\n\tvoid DoCopyFromTupleArray(iterator destPos, iterator destEnd, const value_tuple* srcTuple)\n\t{\n\t\t// assign to constructed region\n\t\twhile (destPos < destEnd)\n\t\t{\n\t\t\t*destPos = *srcTuple;\n\t\t\t++destPos;\n\t\t\t++srcTuple;\n\t\t}\n\t}\n\n\tvoid DoUninitializedCopyFromTupleArray(iterator destPos, iterator destEnd, const value_tuple* srcTuple)\n\t{\n\t\t// placement-new/copy-ctor to unconstructed regions\n\t\twhile (destPos < destEnd)\n\t\t{\n\t\t\tswallow((detail::allocator_construct(get_allocator(), eastl::get(destPos.MakePointer()), eastl::get(*srcTuple)), 0)...);\n\t\t\t++destPos;\n\t\t\t++srcTuple;\n\t\t}\n\t}\n\n\t// Try to grow the size of the container \"naturally\" given the number of elements being used\n\tvoid DoGrow(size_type oldNumElements, size_type oldNumCapacity, size_type requiredCapacity)\n\t{\n\t\tif (requiredCapacity > oldNumCapacity)\n\t\t\tDoReallocate(oldNumElements, GetNewCapacity(requiredCapacity));\n\t}\n\n\t// Reallocate to the newCapacity (IFF it's actually larger, though)\n\tvoid DoConditionalReallocate(size_type oldNumElements, size_type oldNumCapacity, size_type requiredCapacity)\n\t{\n\t\tif (requiredCapacity > oldNumCapacity)\n\t\t\tDoReallocate(oldNumElements, requiredCapacity);\n\t}\n\n\tvoid DoReallocate(size_type oldNumElements, size_type requiredCapacity)\n\t{\n\t\tvoid* ppNewLeaf[sizeof...(Ts)];\n\t\tpair allocation = TupleRecurser::template DoAllocate(\n\t\t\t*this, ppNewLeaf, requiredCapacity, 0);\n\t\tswallow((TupleVecLeaf::DoUninitializedMoveAndDestruct(0, oldNumElements, (Ts*)ppNewLeaf[Indices]), 0)...);\n\t\tswallow(TupleVecLeaf::mpData = (Ts*)ppNewLeaf[Indices]...);\n\n\t\tEASTLFree(get_allocator(), mpData, internalDataSize());\n\t\tmpData = allocation.first;\n\t\tmNumCapacity = requiredCapacity;\n\t\tinternalDataSize() = allocation.second;\n\t}\n\n\tsize_type GetNewCapacity(size_type oldNumCapacity)\n\t{\n\t\treturn (oldNumCapacity > 0) ? (2 * oldNumCapacity) : 1;\n\t}\n};\n\n} // namespace TupleVecInternal\n\n// Move_iterator specialization for TupleVecIter.\n// An rvalue reference of a move_iterator would normaly be \"tuple &&\" whereas\n// what we actually want is \"tuple\". This specialization gives us that.\ntemplate \nclass move_iterator, Ts...>>\n{\npublic:\n\ttypedef TupleVecInternal::TupleVecIter, Ts...> iterator_type;\n\ttypedef iterator_traits traits_type;\n\ttypedef typename traits_type::iterator_category iterator_category;\n\ttypedef typename traits_type::value_type value_type;\n\ttypedef typename traits_type::difference_type difference_type;\n\ttypedef typename traits_type::pointer pointer;\n\ttypedef tuple reference;\n\ttypedef move_iterator this_type;\n\nprotected:\n\titerator_type mIterator;\n\npublic:\n\tmove_iterator() : mIterator() {}\n\texplicit move_iterator(iterator_type mi) : mIterator(mi) {}\n\n\ttemplate \n\tmove_iterator(const move_iterator& mi) : mIterator(mi.base()) {}\n\n\titerator_type base() const { return mIterator; }\n\treference operator*() const { return eastl::move(MakeReference()); }\n\tpointer operator->() const { return mIterator; }\n\n\tthis_type& operator++() { ++mIterator; return *this; }\n\tthis_type operator++(int) {\n\t\tthis_type tempMoveIterator = *this;\n\t\t++mIterator;\n\t\treturn tempMoveIterator;\n\t}\n\n\tthis_type& operator--() { --mIterator; return *this; }\n\tthis_type operator--(int)\n\t{\n\t\tthis_type tempMoveIterator = *this;\n\t\t--mIterator;\n\t\treturn tempMoveIterator;\n\t}\n\n\tthis_type operator+(difference_type n) const { return move_iterator(mIterator + n); }\n\tthis_type& operator+=(difference_type n)\n\t{\n\t\tmIterator += n;\n\t\treturn *this;\n\t}\n\n\tthis_type operator-(difference_type n) const { return move_iterator(mIterator - n); }\n\tthis_type& operator-=(difference_type n)\n\t{\n\t\tmIterator -= n;\n\t\treturn *this;\n\t}\n\n\tdifference_type operator-(const this_type& rhs) const { return mIterator - rhs.mIterator; }\n\tbool operator<(const this_type& rhs) const { return mIterator < rhs.mIterator; }\n\tbool operator>(const this_type& rhs) const { return mIterator > rhs.mIterator; }\n\tbool operator>=(const this_type& rhs) const { return mIterator >= rhs.mIterator; }\n\tbool operator<=(const this_type& rhs) const { return mIterator <= rhs.mIterator; }\n\n\treference operator[](difference_type n) const { return *(*this + n); }\n\nprivate:\n\treference MakeReference() const\n\t{\n\t\treturn reference(eastl::move(((Ts*)mIterator.mpData[Indices])[mIterator.mIndex])...);\n\t}\n\n\tEASTL_INTERNAL_DISABLE_DEPRECATED() // 'is_iterator_wrapper': was declared deprecated\n\t// Unwrapping interface, not part of the public API.\n\tEASTL_REMOVE_AT_2024_SEPT iterator_type unwrap() const { return mIterator; }\n\n\t// The unwrapper helpers need access to unwrap().\n\tfriend is_iterator_wrapper_helper;\n\tfriend is_iterator_wrapper;\n\tEASTL_INTERNAL_RESTORE_DEPRECATED()\n};\n\ntemplate \ninline bool operator==(const TupleVecInternal::TupleVecImpl& a,\n\t\t\t\t\t const TupleVecInternal::TupleVecImpl& b)\n{\n\treturn ((a.size() == b.size()) && eastl::equal(a.begin(), a.end(), b.begin()));\n}\n\ntemplate \ninline bool operator!=(const TupleVecInternal::TupleVecImpl& a,\n\t\t\t\t\t const TupleVecInternal::TupleVecImpl& b)\n{\n\treturn ((a.size() != b.size()) || !eastl::equal(a.begin(), a.end(), b.begin()));\n}\n\ntemplate \ninline bool operator<(const TupleVecInternal::TupleVecImpl& a,\n\t\t\t\t\t const TupleVecInternal::TupleVecImpl& b)\n{\n\treturn eastl::lexicographical_compare(a.begin(), a.end(), b.begin(), b.end());\n}\n\ntemplate \ninline bool operator>(const TupleVecInternal::TupleVecImpl& a,\n\t\t\t\t\t const TupleVecInternal::TupleVecImpl& b)\n{\n\treturn b < a;\n}\n\ntemplate \ninline bool operator<=(const TupleVecInternal::TupleVecImpl& a,\n\t\t\t\t\t const TupleVecInternal::TupleVecImpl& b)\n{\n\treturn !(b < a);\n}\n\ntemplate \ninline bool operator>=(const TupleVecInternal::TupleVecImpl& a,\n\t\t\t\t\t const TupleVecInternal::TupleVecImpl& b)\n{\n\treturn !(a < b);\n}\n\ntemplate \ninline void swap(TupleVecInternal::TupleVecImpl& a,\n\t\t\t\tTupleVecInternal::TupleVecImpl& b)\n{\n\ta.swap(b);\n}\n\n// A customization of swap is made for r-values of tuples-of-references - \n// normally, swapping rvalues doesn't make sense, but in this case, we do want to \n// swap the contents of what the tuple-of-references are referring to\n//\n// This is required due to TupleVecIter returning a value-type for its dereferencing,\n// as opposed to an actual real reference of some sort\ntemplate\ninline\ntypename enable_if...>::value>::type\nswap(tuple&& a, tuple&& b)\n{\n\ta.swap(b);\n}\n\ntemplate\ninline\ntypename enable_if...>::value>::type\nswap(tuple&& a, tuple&& b) = delete;\n\n\n// External interface of tuple_vector\ntemplate \nclass tuple_vector : public TupleVecInternal::TupleVecImpl, Ts...>\n{\n\ttypedef tuple_vector this_type;\n\ttypedef TupleVecInternal::TupleVecImpl, Ts...> base_type;\n\tusing base_type::base_type;\n\npublic:\n\tthis_type& operator=(std::initializer_list iList) \n\t{\n\t\tbase_type::operator=(iList);\n\t\treturn *this;\n\t}\n};\n\n// Variant of tuple_vector that allows a user-defined allocator type (can't mix default template params with variadics)\ntemplate \nclass tuple_vector_alloc\n\t: public TupleVecInternal::TupleVecImpl, Ts...>\n{\n\ttypedef tuple_vector_alloc this_type;\n\ttypedef TupleVecInternal::TupleVecImpl, Ts...> base_type;\n\tusing base_type::base_type;\n\npublic:\n\n\tthis_type& operator=(std::initializer_list iList)\n\t{\n\t\tbase_type::operator=(iList);\n\t\treturn *this;\n\t}\n};\n\n} // namespace eastl\n\nEA_RESTORE_VC_WARNING()\nEA_RESTORE_VC_WARNING()\nEA_RESTORE_VC_WARNING()\nEA_RESTORE_VC_WARNING()\n\n#endif // EASTL_TUPLEVECTOR_H\n" }, { "path": "include/EASTL/chrono.h", "content": "/////////////////////////////////////////////////////////////////////////////\n// Copyright (c) Electronic Arts Inc. All rights reserved.\n/////////////////////////////////////////////////////////////////////////////\n\n\n///////////////////////////////////////////////////////////////////////////////\n// This file implements the eastl::chrono specification which is part of the\n// standard STL date and time library. eastl::chrono implements all the\n// mechanisms required to capture and manipulate times retrieved from the\n// provided clocks. It implements the all of the features to allow type safe\n// durations to be used in code.\n///////////////////////////////////////////////////////////////////////////////\n\n\n#ifndef EASTL_CHRONO_H\n#define EASTL_CHRONO_H\n\n#if defined(EA_PRAGMA_ONCE_SUPPORTED)\n\t#pragma once \n#endif\n\n#include \n#include \n#include \n#include \n\n\n// TODO: move to platform specific cpp or header file\n#if defined EA_PLATFORM_MICROSOFT\n\tEA_DISABLE_ALL_VC_WARNINGS()\n\n\t#ifndef WIN32_LEAN_AND_MEAN\n\t\t#define WIN32_LEAN_AND_MEAN\n\t#endif\n\n\t#undef NOMINMAX\n\t#define NOMINMAX\n\n\t#include \n\n\t#ifdef min\n\t\t#undef min\n\t#endif\n\t#ifdef max\n\t\t#undef max\n\t#endif\n\n\tEA_RESTORE_ALL_VC_WARNINGS()\n#endif\n\n#if defined(EA_PLATFORM_MICROSOFT) && !defined(EA_PLATFORM_MINGW)\n\t// Nothing to do\n#elif defined(EA_PLATFORM_SONY)\n\t#include \n\t#include \n#elif defined(EA_PLATFORM_APPLE)\n\t#include \n#elif defined(EA_PLATFORM_POSIX) || defined(EA_PLATFORM_MINGW) || defined(EA_PLATFORM_ANDROID) \n\t// Posix means Linux, Unix, and Macintosh OSX, among others (including Linux-based mobile platforms).\n\t#if defined(EA_PLATFORM_MINGW)\n\t\t#include \n\t#endif\n\t#include \n\t#if (defined(CLOCK_REALTIME) || defined(CLOCK_MONOTONIC))\n\t\t#include \n\t#else\n\t\t#include \n\t\t#include \n\t#endif\n#endif\n\n\nnamespace eastl\n{\nnamespace chrono\n{\n\t///////////////////////////////////////////////////////////////////////////////\n\t// treat_as_floating_point\n\t///////////////////////////////////////////////////////////////////////////////\n\ttemplate \n\tstruct treat_as_floating_point : is_floating_point {};\n\n\n ///////////////////////////////////////////////////////////////////////////////\n\t// 20.12.4, duration_values\n\t///////////////////////////////////////////////////////////////////////////////\n\ttemplate \n\tstruct duration_values\n\t{\n\tpublic:\n\t\tEASTL_FORCE_INLINE static EA_CONSTEXPR Rep zero() { return Rep(0); }\n\t\tEASTL_FORCE_INLINE static EA_CONSTEXPR Rep max() { return eastl::numeric_limits::max(); }\n\t\tEASTL_FORCE_INLINE static EA_CONSTEXPR Rep min() { return eastl::numeric_limits::lowest(); }\n\t};\n\n\n\t///////////////////////////////////////////////////////////////////////////////\n\t// duration fwd_decl\n\t///////////////////////////////////////////////////////////////////////////////\n\ttemplate >\n\tclass duration;\n\n\n\tnamespace Internal\n\t{\n\t\t///////////////////////////////////////////////////////////////////////////////\n\t\t// IsRatio \n\t\t///////////////////////////////////////////////////////////////////////////////\n\t\ttemplate struct IsRatio : eastl::false_type {};\n\t\ttemplate struct IsRatio> : eastl::true_type {};\n\t\ttemplate struct IsRatio> : eastl::true_type {};\n\t\ttemplate struct IsRatio> : eastl::true_type {};\n\t\ttemplate struct IsRatio> : eastl::true_type {};\n\n\n\t\t///////////////////////////////////////////////////////////////////////////////\n\t\t// IsDuration \n\t\t///////////////////////////////////////////////////////////////////////////////\n\t\ttemplate struct IsDuration : eastl::false_type{};\n\t\ttemplate struct IsDuration> : eastl::true_type{};\n\t\ttemplate struct IsDuration> : eastl::true_type{};\n\t\ttemplate struct IsDuration> : eastl::true_type{};\n\t\ttemplate struct IsDuration> : eastl::true_type{};\n\n\n\t\t///////////////////////////////////////////////////////////////////////////////\n\t\t// RatioGCD \n\t\t///////////////////////////////////////////////////////////////////////////////\n\t\ttemplate \n\t\tstruct RatioGCD\n\t\t{\n\t\t\tstatic_assert(IsRatio::value, \"Period1 is not a eastl::ratio type\");\n\t\t\tstatic_assert(IsRatio::value, \"Period2 is not a eastl::ratio type\");\n\n\t\t\ttypedef ratio::value,\n\t\t\t eastl::Internal::lcm::value> type;\n\t\t};\n\t};\n\n\n\t///////////////////////////////////////////////////////////////////////////////\n\t// 20.12.5.7, duration_cast\n\t///////////////////////////////////////////////////////////////////////////////\n\tnamespace Internal\n\t{\n\t\ttemplate ::type,\n\t\t typename CommonRep = typename eastl::decay::type>::type,\n\t\t bool = CommonPeriod::num == 1,\n\t\t bool = CommonPeriod::den == 1>\n\t\tstruct DurationCastImpl;\n\n\t\ttemplate \n\t\tstruct DurationCastImpl\n\t\t{\n\t\t\tinline static ToDuration DoCast(const FromDuration& fd)\n\t\t\t{\n\t\t\t\treturn ToDuration(static_cast(fd.count()));\n\t\t\t}\n\t\t};\n\n\t\ttemplate \n\t\tstruct DurationCastImpl\n\t\t{\n\t\t\tinline static ToDuration DoCast(const FromDuration& d)\n\t\t\t{\n\t\t\t\treturn ToDuration(static_cast(static_cast(d.count()) *\n\t\t\t\t static_cast(CommonPeriod::num)));\n\t\t\t}\n\t\t};\n\n\t\ttemplate \n\t\tstruct DurationCastImpl\n\t\t{\n\t\t\tinline static ToDuration DoCast(const FromDuration& d)\n\t\t\t{\n\t\t\t\treturn ToDuration(static_cast(static_cast(d.count()) /\n\t\t\t\t static_cast(CommonPeriod::den)));\n\t\t\t}\n\t\t};\n\n\t\ttemplate \n\t\tstruct DurationCastImpl\n\t\t{\n\t\t\tinline static ToDuration DoCast(const FromDuration& d)\n\t\t\t{\n\t\t\t\treturn ToDuration(static_cast(static_cast(d.count()) *\n\t\t\t\t static_cast(CommonPeriod::num) /\n\t\t\t\t static_cast(CommonPeriod::den)));\n\t\t\t}\n\t\t};\n\t}; // namespace Internal\n\n\n\t///////////////////////////////////////////////////////////////////////////////\n\t// duration_cast \n\t///////////////////////////////////////////////////////////////////////////////\n\ttemplate \n\tinline typename eastl::enable_if::value, ToDuration>::type \n\tduration_cast(const duration& d)\n\t{\n\t\ttypedef typename duration::this_type FromDuration;\n\t\treturn Internal::DurationCastImpl::DoCast(d);\n\t}\n\n\n\t///////////////////////////////////////////////////////////////////////////////\n\t// duration \n\t///////////////////////////////////////////////////////////////////////////////\n\ttemplate \n\tclass duration\n\t{\n\t\tRep mRep;\t\n\n\tpublic:\n\t\ttypedef Rep rep;\n\t\ttypedef Period period;\n\t\ttypedef duration this_type;\n\n #if defined(EA_COMPILER_NO_DEFAULTED_FUNCTIONS)\n\t\tEA_CONSTEXPR duration() \n\t\t\t: mRep() {}\n\n\t\tduration(const duration& other)\n\t\t\t: mRep(Rep(other.mRep)) {}\n\n\t\tduration& operator=(const duration& other)\n\t\t\t{ mRep = other.mRep; return *this; }\n\t#else\n\t\tEA_CONSTEXPR duration() = default;\n\t\tduration(const duration&) = default;\n\t\tduration& operator=(const duration&) = default;\n #endif\n\n\n\t\t///////////////////////////////////////////////////////////////////////////////\n\t\t// conversion constructors \n\t\t///////////////////////////////////////////////////////////////////////////////\n\t\ttemplate \n\t\tinline EA_CONSTEXPR explicit duration(\n\t\t const Rep2& rep2,\n\t\t typename eastl::enable_if::value &&\n\t\t (treat_as_floating_point::value ||\n\t\t !treat_as_floating_point::value)>::type** = 0)\n\t\t : mRep(static_cast(rep2)) {}\n\n\n\t\ttemplate \n\t\tEA_CONSTEXPR duration(const duration& d2,\n\t\t typename eastl::enable_if::value ||\n\t\t (eastl::ratio_divide::type::den == 1 &&\n\t\t !treat_as_floating_point::value),\n\t\t void>::type** = 0)\n\t\t : mRep(duration_cast(d2).count()) {}\n\n\t\t///////////////////////////////////////////////////////////////////////////////\n\t\t// returns the count of ticks \n\t\t///////////////////////////////////////////////////////////////////////////////\n\t\tEA_CONSTEXPR Rep count() const { return mRep; }\n\n\t\t///////////////////////////////////////////////////////////////////////////////\n\t\t// static accessors of special duration values \n\t\t///////////////////////////////////////////////////////////////////////////////\n\t\tEA_CONSTEXPR inline static duration zero() { return duration(duration_values::zero()); }\n\t\tEA_CONSTEXPR inline static duration min() { return duration(duration_values::min()); }\n\t\tEA_CONSTEXPR inline static duration max() { return duration(duration_values::max()); }\n\n\t\t///////////////////////////////////////////////////////////////////////////////\n\t\t// const arithmetic operations\n\t\t///////////////////////////////////////////////////////////////////////////////\n\t\tEA_CONSTEXPR inline duration operator+() const { return *this; }\n\t\tEA_CONSTEXPR inline duration operator-() const { return duration(0-mRep); }\n\n\t\t///////////////////////////////////////////////////////////////////////////////\n\t\t// arithmetic operations\n\t\t///////////////////////////////////////////////////////////////////////////////\n\t\tinline duration operator++(int) { return duration(mRep++); }\n\t\tinline duration operator--(int) { return duration(mRep--); }\n\t\tinline duration& operator++() { ++mRep; return *this; }\n\t\tinline duration& operator--() { --mRep; return *this; }\n\t\tinline duration& operator+=(const duration& d) { mRep += d.count(); return *this; }\n\t\tinline duration& operator-=(const duration& d) { mRep -= d.count(); return *this; }\n\t\tinline duration& operator*=(const Rep& rhs) { mRep *= rhs; return *this; }\n\t\tinline duration& operator/=(const Rep& rhs) { mRep /= rhs; return *this; }\n\t\tinline duration& operator%=(const Rep& rhs) { mRep %= rhs; return *this; }\n\t\tinline duration& operator%=(const duration& d) { mRep %= d.count(); return *this; }\n\t};\n\n\n\t///////////////////////////////////////////////////////////////////////////////\n\t// 20.12.5.5, arithmetic operations with durations as arguments\n\t///////////////////////////////////////////////////////////////////////////////\n\ttemplate \n\ttypename eastl::common_type, duration>::type EASTL_FORCE_INLINE\n\toperator+(const duration& lhs, const duration& rhs)\n\t{\n\t\ttypedef typename eastl::common_type, duration>::type common_duration_t;\n\t\treturn common_duration_t(common_duration_t(lhs).count() + common_duration_t(rhs).count());\n\t}\n\n\ttemplate \n\ttypename eastl::common_type, duration>::type EASTL_FORCE_INLINE\n\toperator-(const duration& lhs, const duration& rhs)\n\t{\n\t\ttypedef typename eastl::common_type, duration>::type common_duration_t;\n\t\treturn common_duration_t(common_duration_t(lhs).count() - common_duration_t(rhs).count());\n\t}\n\n\ttemplate \n\tduration::type, Period1> EASTL_FORCE_INLINE\n\toperator*(const duration& lhs, const Rep2& rhs)\n\t{\n\t\ttypedef duration::type, Period1> common_duration_t;\n\t\treturn common_duration_t(common_duration_t(lhs).count() * rhs);\n\t}\n\n\ttemplate \n\tduration::type, Period2> EASTL_FORCE_INLINE\n\toperator*(const Rep1& lhs, const duration& rhs)\n\t{\n\t\ttypedef duration::type, Period2> common_duration_t;\n\t\treturn common_duration_t(lhs * common_duration_t(rhs).count());\n\t}\n\n\ttemplate \n\tduration::type, Period1> EASTL_FORCE_INLINE\n\toperator/(const duration& lhs, const Rep2& rhs)\n\t{\n\t\ttypedef duration::type, Period1> common_duration_t;\n\t\treturn common_duration_t(common_duration_t(lhs).count() / rhs);\n\t}\n\n\ttemplate \n\ttypename eastl::common_type, duration>::type EASTL_FORCE_INLINE\n\toperator/(const duration& lhs, const duration& rhs)\n\t{\n\t\ttypedef typename eastl::common_type, duration>::type common_duration_t;\n\t\treturn common_duration_t(common_duration_t(lhs).count() / common_duration_t(rhs).count());\n\t}\n\n\ttemplate \n\tduration::type, Period1> EASTL_FORCE_INLINE\n\toperator%(const duration& lhs, const Rep2& rhs)\n\t{\n\t\ttypedef duration::type, Period1> common_duration_t;\n\t\treturn common_duration_t(common_duration_t(lhs).count() % rhs);\n\t}\n\n\ttemplate \n\ttypename eastl::common_type, duration>::type EASTL_FORCE_INLINE\n\toperator%(const duration& lhs, const duration& rhs)\n\t{\n\t\ttypedef typename eastl::common_type, duration>::type common_duration_t;\n\t\treturn common_duration_t(common_duration_t(lhs).count() % common_duration_t(rhs).count());\n\t}\n\n\n\t///////////////////////////////////////////////////////////////////////////////\n\t// 20.12.5.6, compares two durations\n\t///////////////////////////////////////////////////////////////////////////////\n\ttemplate \n\tEASTL_FORCE_INLINE bool operator==(const duration& lhs,\n\t const duration& rhs)\n\t{\n\t\ttypedef typename eastl::common_type, duration>::type common_duration_t;\n\t\treturn common_duration_t(lhs).count() == common_duration_t(rhs).count();\n\t}\n\n\ttemplate \n\tEASTL_FORCE_INLINE bool operator<(const duration& lhs,\n\t const duration& rhs)\n\t{\n\t\ttypedef typename eastl::common_type, duration>::type common_duration_t;\n\t\treturn common_duration_t(lhs).count() < common_duration_t(rhs).count();\n\t}\n\n\ttemplate \n\tEASTL_FORCE_INLINE bool operator!=(const duration& lhs,\n\t const duration& rhs)\n\t{\n\t\treturn !(lhs == rhs);\n\t}\n\n\ttemplate \n\tEASTL_FORCE_INLINE bool operator<=(const duration& lhs,\n\t const duration& rhs)\n\t{\n\t\treturn !(rhs < lhs);\n\t}\n\n\ttemplate \n\tEASTL_FORCE_INLINE bool operator>(const duration& lhs,\n\t const duration& rhs)\n\t{\n\t\treturn rhs < lhs;\n\t}\n\n\ttemplate \n\tEASTL_FORCE_INLINE bool operator>=(const duration& lhs,\n\t const duration& rhs)\n\t{\n\t\treturn !(lhs < rhs);\n\t}\n\n\n\t///////////////////////////////////////////////////////////////////////////////\n\t// standard duration units\n\t///////////////////////////////////////////////////////////////////////////////\n typedef duration nanoseconds;\n typedef duration microseconds;\n typedef duration milliseconds;\n typedef duration seconds;\n typedef duration> minutes;\n typedef duration> hours;\n\n\n\t///////////////////////////////////////////////////////////////////////////////\n\t// 20.12.6, time_point\n\t///////////////////////////////////////////////////////////////////////////////\n\ttemplate \n\tclass time_point\n\t{\n\t\tDuration mDuration;\n\n\tpublic:\n\t\ttypedef Clock clock;\n\t\ttypedef Duration duration;\n\t\ttypedef typename Duration::rep rep;\n\t\ttypedef typename Duration::period period;\n\n\t\tinline EA_CONSTEXPR time_point() : mDuration(Duration::zero()) {}\n\t\tEA_CONSTEXPR explicit time_point(const Duration& other) : mDuration(other) {}\n\n\t\ttemplate \n\t\tinline EA_CONSTEXPR time_point(\n\t\t const time_point& t,\n\t\t typename eastl::enable_if::value>::type** = 0)\n\t\t : mDuration(t.time_since_epoch()) {}\n\n\t\tEA_CONSTEXPR Duration time_since_epoch() const { return mDuration; }\n\n\t\ttime_point& operator+=(const Duration& d) { mDuration += d; return *this; } \n\t\ttime_point& operator-=(const Duration& d) { mDuration -= d; return *this; }\n\n\t\tstatic EA_CONSTEXPR time_point min() { return time_point(Duration::min()); }\n\t\tstatic EA_CONSTEXPR time_point max() { return time_point(Duration::max()); }\n\t};\n\n\n\t///////////////////////////////////////////////////////////////////////////////\n\t// 20.12.6.5, time_point arithmetic\n\t///////////////////////////////////////////////////////////////////////////////\n\ttemplate \n\tinline EA_CONSTEXPR time_point>::type>\n\toperator+(const time_point& lhs, const duration& rhs)\n\t{\n\t\ttypedef time_point>::type> common_timepoint_t;\n\t\treturn common_timepoint_t(lhs.time_since_epoch() + rhs);\n\t}\n\n\ttemplate \n\tinline EA_CONSTEXPR time_point>::type>\n\toperator+(const duration& lhs, const time_point& rhs)\n\t{\n\t\ttypedef time_point>::type> common_timepoint_t;\n\t\treturn common_timepoint_t(lhs + rhs.time_since_epoch());\n\t}\n\n\ttemplate \n\tinline EA_CONSTEXPR time_point>::type>\n\toperator-(const time_point& lhs, const duration& rhs)\n\t{\n\t\ttypedef time_point>::type> common_timepoint_t;\n\t\treturn common_timepoint_t(lhs.time_since_epoch() - rhs);\n\t}\n\n\ttemplate \n\tinline EA_CONSTEXPR typename eastl::common_type::type operator-(\n\t const time_point& lhs,\n\t const time_point& rhs)\n\t{\n\t\treturn lhs.time_since_epoch() - rhs.time_since_epoch();\n\t}\n\n\ttemplate \n\tinline EA_CONSTEXPR bool operator==(const time_point& lhs,\n\t const time_point& rhs)\n\t{\n\t\treturn lhs.time_since_epoch() == rhs.time_since_epoch();\n\t}\n\n\ttemplate \n\tinline EA_CONSTEXPR bool operator!=(const time_point& lhs,\n\t const time_point& rhs)\n\t{\n\t\treturn !(lhs == rhs);\n\t}\n\n\ttemplate \n\tinline EA_CONSTEXPR bool operator<(const time_point& lhs, const time_point& rhs)\n\t{\n\t\treturn lhs.time_since_epoch() < rhs.time_since_epoch();\n\t}\n\n\ttemplate \n\tinline EA_CONSTEXPR bool operator<=(const time_point& lhs,\n\t const time_point& rhs)\n\t{\n\t\treturn !(rhs < lhs);\n\t}\n\n\ttemplate \n\tinline EA_CONSTEXPR bool operator>(const time_point& lhs, const time_point& rhs)\n\t{\n\t\treturn rhs < lhs;\n\t}\n\n\ttemplate \n\tinline EA_CONSTEXPR bool operator>=(const time_point& lhs,\n\t const time_point& rhs)\n\t{\n\t\treturn !(lhs < rhs);\n\t}\n\n\n\t///////////////////////////////////////////////////////////////////////////////\n\t// 20.12.6.7, time_point_cast\n\t///////////////////////////////////////////////////////////////////////////////\n\ttemplate \n\tEA_CONSTEXPR time_point time_point_cast(\n\t const time_point& t,\n\t typename eastl::enable_if::value>::type** = 0)\n\t{\n\t\treturn time_point(duration_cast(t.time_since_epoch()));\n\t}\n\n\n\t///////////////////////////////////////////////////////////////////////////////\n\t// 20.12.7, clocks\n\t///////////////////////////////////////////////////////////////////////////////\n\n\tnamespace Internal\n\t{\n\t\t#if defined(EA_PLATFORM_MICROSOFT) && !defined(EA_PLATFORM_MINGW)\n\t\t\t#define EASTL_NS_PER_TICK 1 \n\t\t#elif defined EA_PLATFORM_SONY\n\t\t\t#define EASTL_NS_PER_TICK 1\n\t\t#elif defined EA_PLATFORM_POSIX\n\t\t\t#define EASTL_NS_PER_TICK _XTIME_NSECS_PER_TICK\n\t\t#else\n\t\t\t#define EASTL_NS_PER_TICK 100\n\t\t#endif\n\n\t\t#if defined(EA_PLATFORM_POSIX) \n\t\t\ttypedef chrono::nanoseconds::period SystemClock_Period;\n\t\t\ttypedef chrono::nanoseconds::period SteadyClock_Period;\n\t\t#else\n\t\t\ttypedef eastl::ratio_multiply, nano>::type SystemClock_Period; \n\t\t\ttypedef eastl::ratio_multiply, nano>::type SteadyClock_Period; \n\t\t#endif\n\n\n\t\t///////////////////////////////////////////////////////////////////////////////\n\t\t// Internal::GetTicks \n\t\t///////////////////////////////////////////////////////////////////////////////\n\t\tinline uint64_t GetTicks()\n\t\t{\n\t\t#if defined EA_PLATFORM_MICROSOFT\n\t\t\tauto queryFrequency = []\n\t\t\t{\n\t\t\t\tLARGE_INTEGER frequency;\n\t\t\t\tQueryPerformanceFrequency(&frequency);\n\t\t\t\treturn double(1000000000.0L / (long double)frequency.QuadPart); // nanoseconds per tick\n\t\t\t};\n\n\t\t\tauto queryCounter = []\n\t\t\t{\n\t\t\t\tLARGE_INTEGER counter;\n\t\t\t\tQueryPerformanceCounter(&counter);\n\t\t\t\treturn counter.QuadPart;\n\t\t\t};\n\n\t\t\tEA_DISABLE_VC_WARNING(4640) // warning C4640: construction of local static object is not thread-safe (VS2013)\n\t\t\tstatic auto frequency = queryFrequency(); // cache cpu frequency on first call\n\t\t\tEA_RESTORE_VC_WARNING()\n\t\t\treturn uint64_t(frequency * (double)queryCounter());\n\t\t#elif defined EA_PLATFORM_SONY\n\t\t\tauto queryFrequency = []\n\t\t\t{\n\t\t\t\t// nanoseconds/seconds / ticks/seconds\n\t\t\t\treturn double(1000000000.0L / (long double)sceKernelGetProcessTimeCounterFrequency()); // nanoseconds per tick\n\t\t\t};\n\n\t\t\tauto queryCounter = []\n\t\t\t{\n\t\t\t\treturn sceKernelGetProcessTimeCounter();\n\t\t\t};\n\n\t\t\tEA_DISABLE_VC_WARNING(4640) // warning C4640: construction of local static object is not thread-safe (VS2013)\n\t\t\tstatic auto frequency = queryFrequency(); // cache cpu frequency on first call\n\t\t\tEA_RESTORE_VC_WARNING()\n\t\t\treturn uint64_t(frequency * (double)queryCounter());\n\t\t#elif defined(EA_PLATFORM_APPLE)\n\t\t\tauto queryTimeInfo = []\n\t\t\t{\n\t\t\t\tmach_timebase_info_data_t info;\n\t\t\t\tmach_timebase_info(&info);\n\t\t\t\treturn info;\n\t\t\t};\n\t\t\t\n\t\t\tstatic auto timeInfo = queryTimeInfo();\n\t\t\tuint64_t t = mach_absolute_time();\n\t\t\tt *= timeInfo.numer;\n\t\t\tt /= timeInfo.denom;\n\t\t\treturn t;\n\t\t#elif defined(EA_PLATFORM_POSIX) // Posix means Linux, Unix, and Macintosh OSX, among others (including Linux-based mobile platforms).\n\t\t\t#if (defined(CLOCK_REALTIME) || defined(CLOCK_MONOTONIC))\n\t\t\t\ttimespec ts;\n\t\t\t\tint result = clock_gettime(CLOCK_MONOTONIC, &ts);\n\n\t\t\t\tif (result == -1 && errno == EINVAL)\n\t\t\t\t\tresult = clock_gettime(CLOCK_REALTIME, &ts);\n\n\t\t\t\tconst uint64_t nNanoseconds = (uint64_t)ts.tv_nsec + ((uint64_t)ts.tv_sec * UINT64_C(1000000000));\n\t\t\t\treturn nNanoseconds;\n\t\t\t#else\n\t\t\t\tstruct timeval tv;\n\t\t\t\tgettimeofday(&tv, NULL);\n\t\t\t\tconst uint64_t nMicroseconds = (uint64_t)tv.tv_usec + ((uint64_t)tv.tv_sec * 1000000);\n\t\t\t\treturn nMicroseconds;\n\t\t\t#endif\n #else\n\t\t\t#error \"chrono not implemented for platform\"\n\t\t#endif\n\t\t}\n\t} // namespace Internal\n\n\n\t///////////////////////////////////////////////////////////////////////////////\n\t// system_clock \n\t///////////////////////////////////////////////////////////////////////////////\n\tclass system_clock\n\t{\n\tpublic:\n\t\ttypedef long long rep; // signed arithmetic type representing the number of ticks in the clock's duration\n\t\ttypedef Internal::SystemClock_Period period;\n\t\ttypedef chrono::duration duration; // duration, capable of representing negative durations\n\t\ttypedef chrono::time_point time_point;\n\n\t\t// true if the time between ticks is always increases monotonically\n\t\tEA_CONSTEXPR_OR_CONST static bool is_steady = false;\n\n\t\t// returns a time point representing the current point in time.\n\t\tstatic time_point now() EA_NOEXCEPT \n\t\t{ \n\t\t\treturn time_point(duration(Internal::GetTicks())); \n\t\t}\n\t};\n\n\n\t///////////////////////////////////////////////////////////////////////////////\n\t// steady_clock \n\t///////////////////////////////////////////////////////////////////////////////\n\tclass steady_clock\n\t{\n\tpublic:\n\t\ttypedef long long rep; // signed arithmetic type representing the number of ticks in the clock's duration\n\t\ttypedef Internal::SteadyClock_Period period;\n\t\ttypedef chrono::duration duration; // duration, capable of representing negative durations\n\t\ttypedef chrono::time_point time_point;\n\n\t\t// true if the time between ticks is always increases monotonically\n\t\tEA_CONSTEXPR_OR_CONST static bool is_steady = true;\n\n\t\t// returns a time point representing the current point in time.\n\t\tstatic time_point now() EA_NOEXCEPT \n\t\t{ \n\t\t\treturn time_point(duration(Internal::GetTicks())); \n\t\t}\n\t};\n\n\n\t///////////////////////////////////////////////////////////////////////////////\n\t// high_resolution_clock \n\t///////////////////////////////////////////////////////////////////////////////\n\ttypedef system_clock high_resolution_clock;\n\n\n} // namespace chrono \n\n\n\t///////////////////////////////////////////////////////////////////////////////\n\t// duration common_type specialization \n\t///////////////////////////////////////////////////////////////////////////////\n\ttemplate \n\tstruct common_type, chrono::duration>\n\t{\n\t typedef chrono::duration::type>::type,\n\t typename chrono::Internal::RatioGCD::type> type;\n };\n\n\n\t///////////////////////////////////////////////////////////////////////////////\n\t// time_point common_type specialization \n\t///////////////////////////////////////////////////////////////////////////////\n\ttemplate \n\tstruct common_type, chrono::time_point>\n\t{\n\t\ttypedef chrono::time_point::type> type;\n\t};\n\n\n\t///////////////////////////////////////////////////////////////////////////////\n\t// chrono_literals \n\t///////////////////////////////////////////////////////////////////////////////\n\t#if EASTL_USER_LITERALS_ENABLED && EASTL_INLINE_NAMESPACES_ENABLED\n\t\t// Disabling the Clang/GCC/MSVC warning about using user\n\t\t// defined literals without a leading '_' as they are reserved\n\t\t// for standard libary usage.\n\t\tEA_DISABLE_VC_WARNING(4455)\n\t\tEA_DISABLE_CLANG_WARNING(-Wuser-defined-literals)\n\t\tEA_DISABLE_GCC_WARNING(-Wliteral-suffix)\n\t\tinline namespace literals\n\t\t{\n\t\t\tinline namespace chrono_literals\n\t\t\t{\n\t\t\t\t///////////////////////////////////////////////////////////////////////////////\n\t\t\t\t// integer chrono literals\n\t\t\t\t///////////////////////////////////////////////////////////////////////////////\n\t\t\t\tEA_CONSTEXPR chrono::hours operator\"\" h(unsigned long long h) { return chrono::hours(h); }\n\t\t\t\tEA_CONSTEXPR chrono::minutes operator\"\" min(unsigned long long m) { return chrono::minutes(m); }\n\t\t\t\tEA_CONSTEXPR chrono::seconds operator\"\" s(unsigned long long s) { return chrono::seconds(s); }\n\t\t\t\tEA_CONSTEXPR chrono::milliseconds operator\"\" ms(unsigned long long ms) { return chrono::milliseconds(ms); }\n\t\t\t\tEA_CONSTEXPR chrono::microseconds operator\"\" us(unsigned long long us) { return chrono::microseconds(us); }\n\t\t\t\tEA_CONSTEXPR chrono::nanoseconds operator\"\" ns(unsigned long long ns) { return chrono::nanoseconds(ns); }\n\n\t\t\t\t///////////////////////////////////////////////////////////////////////////////\n\t\t\t\t// float chrono literals\n\t\t\t\t///////////////////////////////////////////////////////////////////////////////\n\t\t\t\tEA_CONSTEXPR chrono::duration> operator\"\" h(long double h)\n\t\t\t\t\t{ return chrono::duration>(h); }\n\t\t\t\tEA_CONSTEXPR chrono::duration> operator\"\" min(long double m)\n\t\t\t\t\t{ return chrono::duration>(m); }\n\t\t\t\tEA_CONSTEXPR chrono::duration operator\"\" s(long double s)\n\t\t\t\t\t{ return chrono::duration(s); }\n\t\t\t\tEA_CONSTEXPR chrono::duration operator\"\" ms(long double ms)\n\t\t\t\t\t{ return chrono::duration(ms); }\n\t\t\t\tEA_CONSTEXPR chrono::duration operator\"\" us(long double us)\n\t\t\t\t\t{ return chrono::duration(us); }\n\t\t\t\tEA_CONSTEXPR chrono::duration operator\"\" ns(long double ns)\n\t\t\t\t\t{ return chrono::duration(ns); }\n\n\t\t\t} // namespace chrono_literals\n\t\t}// namespace literals\n\t\tEA_RESTORE_GCC_WARNING()\t// -Wliteral-suffix\n\t\tEA_RESTORE_CLANG_WARNING()\t// -Wuser-defined-literals\n\t\tEA_RESTORE_VC_WARNING()\t\t// warning: 4455\n\t#endif\n\n} // namespace eastl\n\n\n#if EASTL_USER_LITERALS_ENABLED && EASTL_INLINE_NAMESPACES_ENABLED\nnamespace chrono\n{\n\tusing namespace eastl::literals::chrono_literals;\n} // namespace chrono\n#endif\n\n\n#endif \n" }, { "path": "include/EASTL/compare.h", "content": "///////////////////////////////////////////////////////////////////////////////\n// Copyright (c) Electronic Arts Inc. All rights reserved.\n///////////////////////////////////////////////////////////////////////////////\n\n\n#ifndef EASTL_COMPARE_H\n#define EASTL_COMPARE_H\n\n\n#include \n\nnamespace eastl\n{\n\n#if defined(EA_COMPILER_HAS_THREE_WAY_COMPARISON)\n\tstruct synth_three_way\n\t{\n\t\ttemplate \n\t\tconstexpr auto operator()(const T& t, const U& u) const requires requires\n\t\t{\n\t\t\t{t < u}->std::convertible_to;\n\t\t\t{u < t}->std::convertible_to;\n\t\t}\n\t\t{\n\t\t\tif constexpr (std::three_way_comparable_with)\n\t\t\t{\n\t\t\t\treturn t <=> u;\n\t\t\t}\n\t\t\telse\n\t\t\t{\n\t\t\t\treturn (t < u) ? std::weak_ordering::less :\n\t\t\t\t (u < t) ? std::weak_ordering::greater :\n std::weak_ordering::equivalent;\n\t\t\t}\n\t\t}\n\t};\n\n\ttemplate \n\tusing synth_three_way_result = decltype(synth_three_way{}(declval(), declval()));\n#endif\n\n} // namespace eastl\n\n\n#endif // Header include guard" }, { "path": "include/EASTL/core_allocator.h", "content": "/////////////////////////////////////////////////////////////////////////////\n// Copyright (c) Electronic Arts Inc. All rights reserved.\n/////////////////////////////////////////////////////////////////////////////\n\n#ifndef EASTL_CORE_ALLOCATOR_H\n#define EASTL_CORE_ALLOCATOR_H\n\n#if EASTL_CORE_ALLOCATOR_ENABLED\n\n#include \n\nnamespace EA\n{\n\tnamespace Allocator\n\t{\n\t\t/// EASTLCoreAllocatorImpl\n\t\t///\n\t\t/// EASTL provides an out of the box implementation of the\n\t\t/// ICoreAllocator interface. This is provided as a convenience for\n\t\t/// users who wish to provide ICoreAllocator implementations for EASTL to use. \n\t\t///\n\t\t/// EASTL has a dependency on coreallocator so to provide an out of \n\t\t/// the box implementation for EASTLCoreAlloctor and EASTLCoreDeleter \n\t\t/// that can be used and tested. Historically we could not test \n\t\t/// ICoreAllocator interface because we relied on the code being linked \n\t\t/// in user code.\n\t\t///\n\n\t\tclass EASTLCoreAllocatorImpl : public ICoreAllocator\n\t\t{\n\t\tpublic:\n\t\t\tvirtual void* Alloc(size_t size, const char* name, unsigned int flags)\n\t\t\t{\n\t\t\t\treturn ::operator new[](size, name, flags, 0, __FILE__, __LINE__);\n\t\t\t}\n\n\t\t\tvirtual void* Alloc(size_t size, const char* name, unsigned int flags, unsigned int alignment, unsigned int alignOffset = 0)\n\t\t\t{\n\t\t\t\treturn ::operator new[](size, alignment, alignOffset, name, flags, 0, __FILE__, __LINE__);\n\t\t\t}\n\n\t\t\tvirtual void Free(void* ptr, size_t size = 0)\n\t\t\t{\n\t\t\t\t::operator delete(static_cast(ptr));\n\t\t\t}\n\n\t\t\tvirtual void* AllocDebug(size_t size, const DebugParams debugParams, unsigned int flags)\n\t\t\t{\n\t\t\t\treturn Alloc(size, debugParams.mName, flags);\n\t\t\t}\n\n\t\t\tvirtual void* AllocDebug(size_t size, const DebugParams debugParams, unsigned int flags, unsigned int align, unsigned int alignOffset = 0)\n\t\t\t{\n\t\t\t\treturn Alloc(size, debugParams.mName, flags, align, alignOffset);\n\t\t\t}\n\n\t\t\tstatic EASTLCoreAllocatorImpl* GetDefaultAllocator();\n\t\t};\n\n\t\tinline EASTLCoreAllocatorImpl* EASTLCoreAllocatorImpl::GetDefaultAllocator()\n\t\t{\n\t\t\tstatic EASTLCoreAllocatorImpl allocator;\n\t\t\treturn &allocator;\n\t\t}\n\t}\n}\n\n#endif // EASTL_CORE_ALLOCATOR_ENABLED\n#endif // EASTL_CORE_ALLOCATOR_H\n\n" }, { "path": "include/EASTL/core_allocator_adapter.h", "content": "/////////////////////////////////////////////////////////////////////////////\n// Copyright (c) Electronic Arts Inc. All rights reserved.\n/////////////////////////////////////////////////////////////////////////////\n\n///////////////////////////////////////////////////////////////////////////////\n// Implements an EASTL allocator that uses an ICoreAllocator.\n// However, this header file is not dependent on ICoreAllocator or its package.\n///////////////////////////////////////////////////////////////////////////////\n\n#ifndef EASTL_CORE_ALLOCATOR_ADAPTER_H\n#define EASTL_CORE_ALLOCATOR_ADAPTER_H\n\n#if EASTL_CORE_ALLOCATOR_ENABLED\n\n\n#include \n\n#if defined(EA_PRAGMA_ONCE_SUPPORTED)\n\t#pragma once // Some compilers (e.g. VC++) benefit significantly from using this. We've measured 3-4% build speed improvements in apps as a result.\n#endif\n\n\n/// EASTL_CORE_ALLOCATOR_ADAPTER_GET_DEFAULT_CORE_ALLOCATOR\n///\n/// This allows the application to override the default name for the default global core allocator.\n/// However, you must be careful in your usage of this, as if this file is shared between uses then \n/// you will need to be careful that your override of this doesn't conflict with others. \n///\n#ifndef EASTL_CORE_ALLOCATOR_ADAPTER_GET_DEFAULT_CORE_ALLOCATOR\n\t#define EASTL_CORE_ALLOCATOR_ADAPTER_GET_DEFAULT_CORE_ALLOCATOR AllocatorType::GetDefaultAllocator\n#endif\n\n\n\nnamespace EA\n{\n\tnamespace Allocator\n\t{\n\t\t/// CoreAllocatorAdapter\n\t\t///\n\t\t/// Implements the EASTL allocator interface.\n\t\t/// Allocates memory from an instance of ICoreAllocator or another class with an equivalent interface.\n\t\t/// ICoreAllocator is a pure-virtual memory allocation interface used by a number of EA games and \n\t\t/// shared libraries. It's completely unrelated to EASTL, but it's prevalent enough that it's useful\n\t\t/// for EASTL to have a built-in adapter for this interface. ICoreAllocator is declared in the \n\t\t/// CoreAllocator package icoreallocator_interface.h header, but CoreAllocatorAdapter can work with\n\t\t/// any equivalent interface, as defined below.\n\t\t///\n\t\t/// Expected interface:\n\t\t/// enum AllocFlags {\n\t\t/// kFlagTempMemory = 0,\n\t\t/// kFlagPermMemory = 1\n\t\t/// };\n\t\t/// \n\t\t/// struct CoreAllocator {\n\t\t/// void* Alloc(size_t size, const char* name, unsigned int allocFlags);\n\t\t/// void* Alloc(size_t size, const char* name, unsigned int allocFlags, // Not required unless you are working with types that require custom alignment.\n\t\t/// unsigned int align, unsigned int alignOffset = 0);\n\t\t/// void Free(void* block, size_t size = 0);\n\t\t/// static CoreAllocator* GetDefaultAllocator();\n\t\t/// };\n\t\t///\n\t\t/// Example usage:\n\t\t/// #include \n\t\t/// typedef EA::Allocator::CoreAllocatorAdapter Adapter;\n\t\t/// eastl::list widgetList(Adapter(\"UI/WidgetList\", pSomeCoreAllocator));\n\t\t/// widgetList.push_back(Widget());\n\t\t///\n\t\t/// Example usage:\n\t\t/// #include \n\t\t/// eastl::list > widgetList;\n\t\t/// widgetList.push_back(Widget());\n\t\t///\n\t\t/// Example usage:\n\t\t/// #include \n\t\t/// typedef EA::Allocator::CoreAllocatorAdapter Adapter;\n\t\t/// typedef eastl::list WidgetList;\n\t\t/// CoreAllocatorFixed widgetCoreAllocator(pFixedAllocatorForWidgetListValueType); // CoreAllocatorFixed is a hypothetical implementation of the ICoreAllocator interface.\n\t\t/// WidgetList widgetList(Adapter(\"UI/WidgetList\", &widgetCoreAllocator)); // Note that the widgetCoreAllocator is declared before and thus destroyed after the widget list.\n\t\t///\n\t\ttemplate\n\t\tclass CoreAllocatorAdapter\n\t\t{\n\t\tpublic:\n\t\t\ttypedef CoreAllocatorAdapter this_type;\n\n\t\tpublic:\n\t\t\t// To do: Make this constructor explicit, when there is no known code dependent on it being otherwise.\n\t\t\tCoreAllocatorAdapter(const char* pName = EASTL_NAME_VAL(EASTL_ALLOCATOR_DEFAULT_NAME), AllocatorType* pAllocator = EASTL_CORE_ALLOCATOR_ADAPTER_GET_DEFAULT_CORE_ALLOCATOR());\n\t\t\tCoreAllocatorAdapter(const char* pName, AllocatorType* pAllocator, int flags);\n\t\t\tCoreAllocatorAdapter(const CoreAllocatorAdapter& x);\n\t\t\tCoreAllocatorAdapter(const CoreAllocatorAdapter& x, const char* pName);\n\n\t\t\tCoreAllocatorAdapter& operator=(const CoreAllocatorAdapter& x);\n\n\t\t\tvoid* allocate(size_t n, int flags = 0);\n\t\t\tvoid* allocate(size_t n, size_t alignment, size_t offset, int flags = 0);\n\t\t\tvoid deallocate(void* p, size_t n);\n\n\t\t\tAllocatorType* get_allocator() const;\n\t\t\tvoid set_allocator(AllocatorType* pAllocator);\n\n\t\t\tint get_flags() const;\n\t\t\tvoid set_flags(int flags);\n\n\t\t\tconst char* get_name() const;\n\t\t\tvoid set_name(const char* pName);\n\n\t\tpublic: // Public because otherwise VC++ generates (possibly invalid) warnings about inline friend template specializations.\n\t\t\tAllocatorType* mpCoreAllocator;\n\t\t\tint mnFlags; // Allocation flags. See ICoreAllocator/AllocFlags.\n\n\t\t\t#if EASTL_NAME_ENABLED\n\t\t\t\tconst char* mpName; // Debug name, used to track memory.\n\t\t\t#endif\n\t\t};\n\n\t\ttemplate\n\t\tbool operator==(const CoreAllocatorAdapter& a, const CoreAllocatorAdapter& b);\n\n\t\ttemplate\n\t\tbool operator!=(const CoreAllocatorAdapter& a, const CoreAllocatorAdapter& b);\n\n\n\n\t\t/// EASTLICoreAllocator\n\t\t///\n\t\t/// Provides a standardized typedef for ICoreAllocator;\n\t\t/// \n\t\t/// Example usage:\n\t\t/// eastl::list widgetList(\"UI/WidgetList\", pSomeCoreAllocator);\n\t\t/// widgetList.push_back(Widget());\n\t\t///\n\t\tclass ICoreAllocator;\n\t\tclass EASTLCoreAllocatorImpl;\n\n\t\ttypedef CoreAllocatorAdapter EASTLICoreAllocatorAdapter;\n\t\ttypedef CoreAllocatorAdapter EASTLCoreAllocatorAdapter;\n\t\ttypedef EASTLICoreAllocatorAdapter EASTLICoreAllocator; // for backwards compatibility\n\n\n\n\t\t/// EASTLICoreDeleter\n\t\t///\n\t\t/// Implements a functor which can free memory from the specified\n\t\t/// ICoreAllocator interface. This is a convenience object provided for\n\t\t/// users who wish to have EASTL containers deallocate memory obtained from\n\t\t/// ICoreAllocator interfaces.\n\t\t///\n\t\ttemplate \n\t\tclass CoreDeleterAdapter\n\t\t{\n\t\tpublic:\n\t\t\ttypedef CoreDeleterAdapter this_type;\n\t\t\tAllocatorType* mpCoreAllocator;\n\n\t\tpublic:\n\t\t\tCoreDeleterAdapter(AllocatorType* pAllocator = EASTL_CORE_ALLOCATOR_ADAPTER_GET_DEFAULT_CORE_ALLOCATOR()) EA_NOEXCEPT \n\t\t\t: mpCoreAllocator(pAllocator) {}\n\n\t\t\t~CoreDeleterAdapter() EA_NOEXCEPT {}\n\n\t\t\ttemplate \n\t\t\tvoid operator()(T* p)\n\t\t\t{\n\t\t\t\tp->~T();\n\t\t\t\tmpCoreAllocator->Free(p);\n\t\t\t}\n\n\t\t\tCoreDeleterAdapter(const CoreDeleterAdapter& in) { mpCoreAllocator = in.mpCoreAllocator; }\n\n\t\t\tCoreDeleterAdapter(CoreDeleterAdapter&& in)\n\t\t\t{\n\t\t\t\tmpCoreAllocator = in.mpCoreAllocator;\n\t\t\t\tin.mpCoreAllocator = nullptr;\n\t\t\t}\n\n\t\t\tCoreDeleterAdapter& operator=(const CoreDeleterAdapter& in)\n\t\t\t{\n\t\t\t\tmpCoreAllocator = in.mpCoreAllocator;\n\t\t\t\treturn *this;\n\t\t\t}\n\n\t\t\tCoreDeleterAdapter& operator=(CoreDeleterAdapter&& in)\n\t\t\t{\n\t\t\t\tmpCoreAllocator = in.mpCoreAllocator;\n\t\t\t\tin.mpCoreAllocator = nullptr;\n\t\t\t\treturn *this;\n\t\t\t}\n\t\t};\n\n\n\n\t\t/// EASTLICoreDeleter\n\t\t///\n\t\t/// Provides a standardized typedef for ICoreAllocator implementations.\n\t\t///\n\t\t/// Example usage: \n\t\t/// eastl::shared_ptr foo(pA, EASTLCoreDeleter());\n\t\t///\n\t\ttypedef CoreDeleterAdapter EASTLICoreDeleterAdapter;\n\t\ttypedef CoreDeleterAdapter EASTLCoreDeleterAdapter;\n\n\t} // namespace Allocator\n\n} // namespace EA\n\n\n\n\n\n///////////////////////////////////////////////////////////////////////////////\n// Inlines\n///////////////////////////////////////////////////////////////////////////////\n\nnamespace EA\n{\n\tnamespace Allocator\n\t{\n\t\ttemplate\n\t\tinline CoreAllocatorAdapter::CoreAllocatorAdapter(const char* EASTL_NAME(pName), AllocatorType* pCoreAllocator)\n\t\t\t: mpCoreAllocator(pCoreAllocator), mnFlags(0)\n\t\t{\n\t\t\t#if EASTL_NAME_ENABLED\n\t\t\t\tmpName = pName ? pName : EASTL_ALLOCATOR_DEFAULT_NAME;\n\t\t\t#endif\n\t\t}\n\n\t\ttemplate\n\t\tinline CoreAllocatorAdapter::CoreAllocatorAdapter(const char* EASTL_NAME(pName), AllocatorType* pCoreAllocator, int flags)\n\t\t\t: mpCoreAllocator(pCoreAllocator), mnFlags(flags)\n\t\t{\n\t\t\t#if EASTL_NAME_ENABLED\n\t\t\t\tmpName = pName ? pName : EASTL_ALLOCATOR_DEFAULT_NAME;\n\t\t\t#endif\n\t\t}\n\n\t\ttemplate\n\t\tinline CoreAllocatorAdapter::CoreAllocatorAdapter(const CoreAllocatorAdapter& x)\n\t\t\t: mpCoreAllocator(x.mpCoreAllocator), mnFlags(x.mnFlags)\n\t\t{\n\t\t\t#if EASTL_NAME_ENABLED\n\t\t\t\tmpName = x.mpName;\n\t\t\t#endif\n\t\t}\n\n\t\ttemplate\n\t\tinline CoreAllocatorAdapter::CoreAllocatorAdapter(const CoreAllocatorAdapter& x, const char* EASTL_NAME(pName))\n\t\t\t: mpCoreAllocator(x.mpCoreAllocator), mnFlags(x.mnFlags)\n\t\t{\n\t\t\t#if EASTL_NAME_ENABLED\n\t\t\t\tmpName = pName ? pName : EASTL_ALLOCATOR_DEFAULT_NAME;\n\t\t\t#endif\n\t\t}\n\n\t\ttemplate\n\t\tinline CoreAllocatorAdapter& CoreAllocatorAdapter::operator=(const CoreAllocatorAdapter& x)\n\t\t{\n\t\t\tmpCoreAllocator = x.mpCoreAllocator;\n\t\t\tmnFlags = x.mnFlags;\n\n\t\t\t#if EASTL_NAME_ENABLED\n\t\t\t\tmpName = x.mpName;\n\t\t\t#endif\n\t\t\t\t\n\t\t\treturn *this;\n\t\t}\n\n\t\ttemplate\n\t\tinline void* CoreAllocatorAdapter::allocate(size_t n, int /*flags*/)\n\t\t{\n\t\t\t// It turns out that EASTL itself doesn't use the flags parameter, \n\t\t\t// whereas the user here might well want to specify a flags \n\t\t\t// parameter. So we use ours instead of the one passed in.\n\t\t\treturn mpCoreAllocator->Alloc(n, EASTL_NAME_VAL(mpName), (unsigned)mnFlags);\n\t\t}\n\n\t\ttemplate\n\t\tinline void* CoreAllocatorAdapter::allocate(size_t n, size_t alignment, size_t offset, int /*flags*/)\n\t\t{\n\t\t\t// It turns out that EASTL itself doesn't use the flags parameter, \n\t\t\t// whereas the user here might well want to specify a flags \n\t\t\t// parameter. So we use ours instead of the one passed in.\n\t\t\treturn mpCoreAllocator->Alloc(n, EASTL_NAME_VAL(mpName), (unsigned)mnFlags, (unsigned)alignment, (unsigned)offset);\n\t\t}\n\n\t\ttemplate\n\t\tinline void CoreAllocatorAdapter::deallocate(void* p, size_t n)\n\t\t{\n\t\t\treturn mpCoreAllocator->Free(p, n);\n\t\t}\n\n\t\ttemplate\n\t\tinline AllocatorType* CoreAllocatorAdapter::get_allocator() const\n\t\t{\n\t\t\treturn mpCoreAllocator;\n\t\t}\n\n\t\ttemplate\n\t\tinline void CoreAllocatorAdapter::set_allocator(AllocatorType* pAllocator)\n\t\t{\n\t\t\tmpCoreAllocator = pAllocator;\n\t\t}\n\n\t\ttemplate\n\t\tinline int CoreAllocatorAdapter::get_flags() const\n\t\t{\n\t\t\treturn mnFlags;\n\t\t}\n\n\t\ttemplate\n\t\tinline void CoreAllocatorAdapter::set_flags(int flags)\n\t\t{\n\t\t\tmnFlags = flags;\n\t\t}\n\n\t\ttemplate\n\t\tinline const char* CoreAllocatorAdapter::get_name() const\n\t\t{\n\t\t\t#if EASTL_NAME_ENABLED\n\t\t\t\treturn mpName;\n\t\t\t#else\n\t\t\t\treturn EASTL_ALLOCATOR_DEFAULT_NAME;\n\t\t\t#endif\n\t\t}\n\n\t\ttemplate\n\t\tinline void CoreAllocatorAdapter::set_name(const char* pName)\n\t\t{\n\t\t\t#if EASTL_NAME_ENABLED\n\t\t\t\tmpName = pName;\n\t\t\t#else\n\t\t\t\t(void)pName;\n\t\t\t#endif\n\t\t}\n\n\n\n\t\ttemplate\n\t\tinline bool operator==(const CoreAllocatorAdapter& a, const CoreAllocatorAdapter& b)\n\t\t{\n\t\t\treturn (a.mpCoreAllocator == b.mpCoreAllocator) &&\n\t\t\t\t (a.mnFlags == b.mnFlags);\n\t\t}\n\n\t\ttemplate\n\t\tinline bool operator!=(const CoreAllocatorAdapter& a, const CoreAllocatorAdapter& b)\n\t\t{\n\t\t\treturn (a.mpCoreAllocator != b.mpCoreAllocator) ||\n\t\t\t\t (a.mnFlags != b.mnFlags);\n\t\t}\n\n\n\t} // namespace Allocator\n\n} // namespace EA\n\n\n#endif // EASTL_CORE_ALLOCATOR_ENABLED\n#endif // Header include guard\n\n\n\n\n\n\n\n\n" }, { "path": "include/EASTL/deque.h", "content": "/////////////////////////////////////////////////////////////////////////////\n// Copyright (c) Electronic Arts Inc. All rights reserved.\n/////////////////////////////////////////////////////////////////////////////\n\n//////////////////////////////////////////////////////////////////////////////\n// deque design\n//\n// A deque (pronounced \"deck\") is a double-ended queue, though this is partially \n// of a misnomer. A deque does indeed let you add and remove values from both ends\n// of the container, but it's not usually used for such a thing and instead is used\n// as a more flexible version of a vector. It provides operator[] (random access) \n// and can insert items anywhere and not just at the front and back.\n// \n// While you can implement a double-ended queue via a doubly-linked list, deque is \n// instead implemented as a list of arrays. The benefit of this is that memory usage \n// is lower and that random access can be had with decent efficiency. \n// \n// Our implementation of deque is just like every other implementation of deque,\n// as the C++ standard all but dictates that you make it work this way. Below \n// we have a depiction of an array (or vector) of 48 items, with each node being \n// a '+' character and extra capacity being a '-' character. What we have is one \n// contiguous block of memory:\n// \n// ++++++++++++++++++++++++++++++++++++++++++++++++-----------------\n// 0 47\n// \n// With a deque, the same array of 48 items would be implemented as multiple smaller\n// arrays of contiguous memory, each of fixed size. We will call these \"sub-arrays.\"\n// In the case here, we have six arrays of 8 nodes:\n// \n// ++++++++ ++++++++ ++++++++ ++++++++ ++++++++ ++++++++\n// \n// With an vector, item [0] is the first item and item [47] is the last item. With a \n// deque, item [0] is usually not the first item and neither is item [47]. There is \n// extra capacity on both the front side and the back side of the deque. So a deque\n// (of 24 items) actually looks like this:\n// \n// -------- -----+++ ++++++++ ++++++++ +++++--- --------\n// 0 23\n// \n// To insert items at the front, you move into the capacity on the left, and to insert\n// items at the back, you append items on the right. As you can see, inserting an item\n// at the front doesn't require allocating new memory nor does it require moving any \n// items in the container. It merely involves moving the pointer to the [0] item to\n// the left by one node.\n// \n// We keep track of these sub-arrays by having an array of pointers, with each array \n// entry pointing to each of the sub-arrays. We could alternatively use a linked\n// list of pointers, but it turns out we can implement our deque::operator[] more \n// efficiently if we use an array of pointers instead of a list of pointers.\n//\n// To implement deque::iterator, we could keep a struct which is essentially this:\n// struct iterator {\n// int subArrayIndex;\n// int subArrayOffset;\n// }\n//\n// In practice, we implement iterators a little differently, but in reality our \n// implementation isn't much different from the above. It turns out that it's most\n// simple if we also manage the location of item [0] and item [end] by using these\n// same iterators.\n//\n// To consider: Implement the deque as a circular deque instead of a linear one.\n// This would use a similar subarray layout but iterators would\n// wrap around when they reached the end of the subarray pointer list.\n//\n//////////////////////////////////////////////////////////////////////////////\n\n\n#ifndef EASTL_DEQUE_H\n#define EASTL_DEQUE_H\n\n\n#include \n#include \n#include \n#include \n#include \n#include \n#include \n\nEA_DISABLE_ALL_VC_WARNINGS()\n#include \n#include \nEA_RESTORE_ALL_VC_WARNINGS()\n\n#if EASTL_EXCEPTIONS_ENABLED\n\tEA_DISABLE_ALL_VC_WARNINGS()\n\t#include // std::out_of_range, std::length_error, std::logic_error.\n\tEA_RESTORE_ALL_VC_WARNINGS()\n#endif\n\n\n// 4267 - 'argument' : conversion from 'size_t' to 'const uint32_t', possible loss of data. This is a bogus warning resulting from a bug in VC++.\n// 4345 - Behavior change: an object of POD type constructed with an initializer of the form () will be default-initialized\n// 4480 - nonstandard extension used: specifying underlying type for enum\n// 4530 - C++ exception handler used, but unwind semantics are not enabled. Specify /EHsc\n// 4571 - catch(...) semantics changed since Visual C++ 7.1; structured exceptions (SEH) are no longer caught.\nEA_DISABLE_VC_WARNING(4267 4345 4480 4530 4571);\n\n#if EASTL_EXCEPTIONS_ENABLED\n\t// 4703 - potentially uninitialized local pointer variable used. VC++ is mistakenly analyzing the possibility of uninitialized variables, though it's not easy for it to do so.\n\t// 4701 - potentially uninitialized local variable used.\n\tEA_DISABLE_VC_WARNING(4703 4701)\n#endif\n\n\n#if defined(EA_PRAGMA_ONCE_SUPPORTED)\n\t#pragma once // Some compilers (e.g. VC++) benefit significantly from using this. We've measured 3-4% build speed improvements in apps as a result.\n#endif\n\n\nnamespace eastl\n{\n\n\t/// EASTL_DEQUE_DEFAULT_NAME\n\t///\n\t/// Defines a default container name in the absence of a user-provided name.\n\t///\n\t#ifndef EASTL_DEQUE_DEFAULT_NAME\n\t\t#define EASTL_DEQUE_DEFAULT_NAME EASTL_DEFAULT_NAME_PREFIX \" deque\" // Unless the user overrides something, this is \"EASTL deque\".\n\t#endif\n\n\n\t/// EASTL_DEQUE_DEFAULT_ALLOCATOR\n\t///\n\t#ifndef EASTL_DEQUE_DEFAULT_ALLOCATOR\n\t\t#define EASTL_DEQUE_DEFAULT_ALLOCATOR allocator_type(EASTL_DEQUE_DEFAULT_NAME)\n\t#endif\n\n\n\t/// DEQUE_DEFAULT_SUBARRAY_SIZE\n\t///\n\t/// Defines the default number of items in a subarray.\n\t/// Note that the user has the option of specifying the subarray size\n\t/// in the deque template declaration.\n\t///\n\t#if !defined(__GNUC__) || (__GNUC__ >= 3) // GCC 2.x can't handle the declaration below.\n\t\t#define DEQUE_DEFAULT_SUBARRAY_SIZE(T) ((sizeof(T) <= 4) ? 64 : ((sizeof(T) <= 8) ? 32 : ((sizeof(T) <= 16) ? 16 : ((sizeof(T) <= 32) ? 8 : 4))))\n\t#else\n\t\t#define DEQUE_DEFAULT_SUBARRAY_SIZE(T) 16\n\t#endif\n\n\n\n\t/// DequeIterator\n\t///\n\t/// The DequeIterator provides both const and non-const iterators for deque. \n\t/// It also is used for the tracking of the begin and end for the deque.\n\t///\n\ttemplate \n\tstruct DequeIterator\n\t{\n\t\ttypedef DequeIterator this_type;\n\t\ttypedef DequeIterator iterator;\n\t\ttypedef DequeIterator const_iterator;\n\t\ttypedef ptrdiff_t difference_type;\n\t\ttypedef eastl::random_access_iterator_tag iterator_category;\n\t\ttypedef T value_type;\n\t\ttypedef T* pointer;\n\t\ttypedef T& reference;\n\n\tpublic:\n\t\tDequeIterator();\n\t\tDequeIterator(const iterator& x);\n\t\tDequeIterator& operator=(const iterator& x);\n\n\t\tpointer operator->() const;\n\t\treference operator*() const;\n\n\t\tthis_type& operator++();\n\t\tthis_type operator++(int);\n\n\t\tthis_type& operator--();\n\t\tthis_type operator--(int);\n\n\t\tthis_type& operator+=(difference_type n);\n\t\tthis_type& operator-=(difference_type n);\n\n\t\tthis_type operator+(difference_type n) const;\n\t\tthis_type operator-(difference_type n) const;\n\n\tprotected:\n\t\ttemplate \n\t\tfriend struct DequeIterator;\n\n\t\ttemplate \n\t\tfriend struct DequeBase;\n\n\t\ttemplate \n\t\tfriend class deque;\n\n\t\ttemplate \n\t\tfriend bool operator==(const DequeIterator&, \n\t\t\t\t\t\t\t const DequeIterator&);\n\n\t\ttemplate \n\t\tfriend bool operator!=(const DequeIterator&, \n\t\t\t\t\t\t\t const DequeIterator&);\n\n\t\ttemplate \n\t\tfriend bool operator!=(const DequeIterator& a, \n\t\t\t\t\t\t\t const DequeIterator& b);\n\n\t\ttemplate \n\t\tfriend bool operator< (const DequeIterator&, \n\t\t\t\t\t\t\t const DequeIterator&);\n\n\t\ttemplate \n\t\tfriend bool operator> (const DequeIterator&, \n\t\t\t\t\t\t\t const DequeIterator&);\n\n\t\ttemplate \n\t\tfriend bool operator<=(const DequeIterator&, \n\t\t\t\t\t\t\t const DequeIterator&);\n\n\t\ttemplate \n\t\tfriend bool operator>=(const DequeIterator&, \n\t\t\t\t\t\t\t const DequeIterator&);\n\n\t\ttemplate \n\t\tfriend typename DequeIterator::difference_type\n\t\toperator-(const DequeIterator& a,\n\t\t\t\t const DequeIterator& b);\n\n\tprotected:\n\t\tT* mpCurrent; // Where we currently point. Declared first because it's used most often.\n\t\tT* mpBegin; // The beginning of the current subarray.\n\t\tT* mpEnd; // The end of the current subarray. To consider: remove this member, as it is always equal to 'mpBegin + kDequeSubarraySize'. Given that deque subarrays usually consist of hundreds of bytes, this isn't a massive win. Also, now that we are implementing a zero-allocation new deque policy, mpEnd may in fact not be equal to 'mpBegin + kDequeSubarraySize'.\n\t\tT** mpCurrentArrayPtr; // Pointer to current subarray. We could alternatively implement this as a list node iterator if the deque used a linked list.\n\n\t\tstruct Increment {};\n\t\tstruct Decrement {};\n\t\tstruct FromConst {};\n\n\t\tDequeIterator(T** pCurrentArrayPtr, T* pCurrent);\n\t\tDequeIterator(const const_iterator& x, FromConst) : mpCurrent(x.mpCurrent), mpBegin(x.mpBegin), mpEnd(x.mpEnd), mpCurrentArrayPtr(x.mpCurrentArrayPtr){}\n\t\tDequeIterator(const iterator& x, Increment);\n\t\tDequeIterator(const iterator& x, Decrement);\n\n\t\tthis_type move(const iterator& first, const iterator& last, true_type); // true means that value_type has the type_trait is_trivially_copyable,\n\t\tthis_type move(const iterator& first, const iterator& last, false_type); // false means it does not. \n\n\t\tvoid move_backward(const iterator& first, const iterator& last, true_type); // true means that value_type has the type_trait is_trivially_copyable,\n\t\tvoid move_backward(const iterator& first, const iterator& last, false_type); // false means it does not.\n\n\t\tvoid SetSubarray(T** pCurrentArrayPtr);\n\t};\n\n\n\n\n\t/// DequeBase\n\t///\n\t/// The DequeBase implements memory allocation for deque.\n\t/// See VectorBase (class vector) for an explanation of why we \n\t/// create this separate base class.\n\t///\n\ttemplate \n\tstruct DequeBase\n\t{\n\t\ttypedef T value_type;\n\t\ttypedef Allocator allocator_type;\n\t\ttypedef eastl_size_t size_type; // See config.h for the definition of eastl_size_t, which defaults to size_t.\n\t\ttypedef ptrdiff_t difference_type;\n\t\ttypedef DequeIterator iterator;\n\t\ttypedef DequeIterator const_iterator;\n\n\t\tstatic const size_type npos = (size_type)-1; /// 'npos' means non-valid position or simply non-position.\n\t\tstatic const size_type kMaxSize = (size_type)-2; /// -1 is reserved for 'npos'. It also happens to be slightly beneficial that kMaxSize is a value less than -1, as it helps us deal with potential integer wraparound issues.\n\n\t\tenum\n\t\t{\n\t\t\tkMinPtrArraySize = 8, /// A new empty deque has a ptrArraySize of 0, but any allocated ptrArrays use this min size.\n\t\t\tkSubarraySize = kDequeSubarraySize /// \n\t\t //kNodeSize = kDequeSubarraySize * sizeof(T) /// Disabled because it prevents the ability to do this: struct X{ eastl::deque mDequeOfSelf; };\n\t\t};\n\n\tprotected:\n\t\tenum Side /// Defines the side of the deque: front or back.\n\t\t{\n\t\t\tkSideFront, /// Identifies the front side of the deque.\n\t\t\tkSideBack /// Identifies the back side of the deque.\n\t\t};\n\n\t\tT** mpPtrArray; // Array of pointers to subarrays.\n\t\tsize_type mnPtrArraySize; // Possibly we should store this as T** mpArrayEnd.\n\t\titerator mItBegin; // Where within the subarrays is our beginning.\n\t\titerator mItEnd; // Where within the subarrays is our end.\n\t\tallocator_type mAllocator; // To do: Use base class optimization to make this go away.\n\n\tpublic:\n\t\tDequeBase(const allocator_type& allocator);\n\t\tDequeBase(size_type n);\n\t\tDequeBase(size_type n, const allocator_type& allocator);\n\t ~DequeBase();\n\n\t\tconst allocator_type& get_allocator() const EA_NOEXCEPT;\n\t\tallocator_type& get_allocator() EA_NOEXCEPT;\n\t\tvoid set_allocator(const allocator_type& allocator);\n\n\tprotected:\n\t\tT* DoAllocateSubarray();\n\t\tvoid DoFreeSubarray(T* p);\n\t\tvoid DoFreeSubarrays(T** pBegin, T** pEnd);\n\n\t\tT** DoAllocatePtrArray(size_type n);\n\t\tvoid DoFreePtrArray(T** p, size_t n);\n\n\t\titerator DoReallocSubarray(size_type nAdditionalCapacity, Side allocationSide);\n\t\tvoid DoReallocPtrArray(size_type nAdditionalCapacity, Side allocationSide);\n\n\t\tvoid DoInit(size_type n);\n\n\t}; // DequeBase\n\n\n\n\n\t/// deque\n\t///\n\t/// Implements a conventional C++ double-ended queue. The implementation used here\n\t/// is very much like any other deque implementations you may have seen, as it \n\t/// follows the standard algorithm for deque design. \n\t///\n\t/// Note:\n\t/// As of this writing, deque does not support zero-allocation initial emptiness.\n\t/// A newly created deque with zero elements will still allocate a subarray\n\t/// pointer set. We are looking for efficient and clean ways to get around this,\n\t/// but current efforts have resulted in less efficient and more fragile code.\n\t/// The logic of this class doesn't lend itself to a clean implementation. \n\t/// It turns out that deques are one of the least likely classes you'd want this\n\t/// behaviour in, so until this functionality becomes very important to somebody,\n\t/// we will leave it as-is. It can probably be solved by adding some extra code to\n\t/// the Do* functions and adding good comments explaining the situation.\n\t/// \n\ttemplate \n\tclass deque : public DequeBase\n\t{\n\tpublic:\n\t\ttypedef DequeBase base_type;\n\t\ttypedef deque this_type;\n\t\ttypedef T value_type;\n\t\ttypedef T* pointer;\n\t\ttypedef const T* const_pointer;\n\t\ttypedef T& reference;\n\t\ttypedef const T& const_reference;\n\t\ttypedef DequeIterator iterator;\n\t\ttypedef DequeIterator const_iterator;\n\t\ttypedef eastl::reverse_iterator reverse_iterator;\n\t\ttypedef eastl::reverse_iterator const_reverse_iterator;\n\t\ttypedef typename base_type::size_type size_type;\n\t\ttypedef typename base_type::difference_type difference_type;\n\t\ttypedef typename base_type::allocator_type allocator_type;\n\n\t\tusing base_type::npos;\n\n\t\tstatic_assert(!is_const::value, \"deque::value_type must be non-const.\");\n\t\tstatic_assert(!is_volatile::value, \"deque::value_type must be non-volatile.\");\n\n\tprotected:\n\t\tusing base_type::kSideFront;\n\t\tusing base_type::kSideBack;\n\t\tusing base_type::mpPtrArray;\n\t\tusing base_type::mnPtrArraySize;\n\t\tusing base_type::mItBegin;\n\t\tusing base_type::mItEnd;\n\t\tusing base_type::mAllocator;\n\t\tusing base_type::DoAllocateSubarray;\n\t\tusing base_type::DoFreeSubarray;\n\t\tusing base_type::DoFreeSubarrays;\n\t\tusing base_type::DoAllocatePtrArray;\n\t\tusing base_type::DoFreePtrArray;\n\t\tusing base_type::DoReallocSubarray;\n\t\tusing base_type::DoReallocPtrArray;\n\n\tpublic:\n\t\tdeque();\n\t\texplicit deque(const allocator_type& allocator);\n\t\texplicit deque(size_type n, const allocator_type& allocator = EASTL_DEQUE_DEFAULT_ALLOCATOR);\n\t\tdeque(size_type n, const value_type& value, const allocator_type& allocator = EASTL_DEQUE_DEFAULT_ALLOCATOR);\n\t\tdeque(const this_type& x);\n\t\tdeque(this_type&& x);\n\t\tdeque(this_type&& x, const allocator_type& allocator);\n\t\tdeque(std::initializer_list ilist, const allocator_type& allocator = EASTL_DEQUE_DEFAULT_ALLOCATOR);\n\n\t\t// note: this has pre-C++11 semantics:\n\t\t// this constructor is equivalent to the constructor deque(static_cast(first), static_cast(last)) if InputIterator is an integral type.\n\t\ttemplate \n\t\tdeque(InputIterator first, InputIterator last); // allocator arg removed because VC7.1 fails on the default arg. To do: Make a second version of this function without a default arg.\n\n\t ~deque();\n\n\t\tthis_type& operator=(const this_type& x);\n\t\tthis_type& operator=(std::initializer_list ilist);\n\t\tthis_type& operator=(this_type&& x);\n\n\t\tvoid swap(this_type& x);\n\n\t\tvoid assign(size_type n, const value_type& value);\n\t\tvoid assign(std::initializer_list ilist);\n\n\t\ttemplate // It turns out that the C++ std::deque specifies a two argument\n\t\tvoid assign(InputIterator first, InputIterator last); // version of assign that takes (int size, int value). These are not \n\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t// iterators, so we need to do a template compiler trick to do the right thing.\n\n\t\titerator begin() EA_NOEXCEPT;\n\t\tconst_iterator begin() const EA_NOEXCEPT;\n\t\tconst_iterator cbegin() const EA_NOEXCEPT;\n\n\t\titerator end() EA_NOEXCEPT;\n\t\tconst_iterator end() const EA_NOEXCEPT;\n\t\tconst_iterator cend() const EA_NOEXCEPT;\n\n\t\treverse_iterator rbegin() EA_NOEXCEPT;\n\t\tconst_reverse_iterator rbegin() const EA_NOEXCEPT;\n\t\tconst_reverse_iterator crbegin() const EA_NOEXCEPT;\n\n\t\treverse_iterator rend() EA_NOEXCEPT;\n\t\tconst_reverse_iterator rend() const EA_NOEXCEPT;\n\t\tconst_reverse_iterator crend() const EA_NOEXCEPT;\n\n\t\tbool empty() const EA_NOEXCEPT; \n\t\tsize_type size() const EA_NOEXCEPT;\n\n\t\tvoid resize(size_type n, const value_type& value);\n\t\tvoid resize(size_type n);\n\n\t\tvoid shrink_to_fit();\n\t\tvoid set_capacity(size_type n = base_type::npos);\n\n\t\treference operator[](size_type n);\n\t\tconst_reference operator[](size_type n) const;\n\n\t\treference at(size_type n);\n\t\tconst_reference at(size_type n) const;\n\n\t\treference front();\n\t\tconst_reference front() const;\n\n\t\treference back();\n\t\tconst_reference back() const;\n\n\t\tvoid push_front(const value_type& value);\n\t\treference push_front();\n\t\tvoid push_front(value_type&& value);\n\n\t\tvoid push_back(const value_type& value);\n\t\treference push_back();\n\t\tvoid push_back(value_type&& value);\n\n\t\tvoid pop_front();\n\t\tvoid pop_back();\n\n\t\ttemplate\n\t\titerator emplace(const_iterator position, Args&&... args);\n\n\t\ttemplate\n\t\treference emplace_front(Args&&... args);\n\n\t\ttemplate\n\t\treference emplace_back(Args&&... args);\n\n\t\titerator insert(const_iterator position, const value_type& value);\n\t\titerator insert(const_iterator position, value_type&& value);\n\t\titerator insert(const_iterator position, size_type n, const value_type& value);\n\t\titerator insert(const_iterator position, std::initializer_list ilist);\n\n\t\t// note: this has pre-C++11 semantics:\n\t\t// this function is equivalent to insert(const_iterator position, static_cast(first), static_cast(last)) if InputIterator is an integral type.\n\t\t// ie. same as insert(const_iterator position, size_type n, const value_type& value)\n\t\ttemplate \n\t\titerator insert(const_iterator position, InputIterator first, InputIterator last);\n\n\t\titerator erase(const_iterator position);\n\t\titerator erase(const_iterator first, const_iterator last);\n\t\treverse_iterator erase(reverse_iterator position);\n\t\treverse_iterator erase(reverse_iterator first, reverse_iterator last);\n\n\t\tvoid clear();\n\t\t//void reset_lose_memory(); // Disabled until it can be implemented efficiently and cleanly. // This is a unilateral reset to an initially empty state. No destructors are called, no deallocation occurs.\n\n\t\tbool validate() const;\n\t\tint validate_iterator(const_iterator i) const;\n\n\tprotected:\n\t\ttemplate \n\t\tvoid DoInit(Integer n, Integer value, true_type);\n\n\t\ttemplate \n\t\tvoid DoInit(InputIterator first, InputIterator last, false_type);\n\n\t\ttemplate \n\t\tvoid DoInitFromIterator(InputIterator first, InputIterator last, eastl::input_iterator_tag);\n\n\t\ttemplate \n\t\tvoid DoInitFromIterator(ForwardIterator first, ForwardIterator last, eastl::forward_iterator_tag);\n\n\t\tvoid DoFillInit(const value_type& value);\n\n\t\ttemplate \n\t\tvoid DoAssign(Integer n, Integer value, true_type);\n\n\t\ttemplate \n\t\tvoid DoAssign(InputIterator first, InputIterator last, false_type);\n\n\t\tvoid DoAssignValues(size_type n, const value_type& value);\n\n\t\ttemplate \n\t\titerator DoInsert(const const_iterator& position, Integer n, Integer value, true_type);\n\n\t\ttemplate \n\t\titerator DoInsert(const const_iterator& position, const InputIterator& first, const InputIterator& last, false_type);\n\n\t\ttemplate \n\t\titerator DoInsertFromIterator(const_iterator position, const InputIterator& first, const InputIterator& last, eastl::input_iterator_tag);\n\n\t\ttemplate \n\t\titerator DoInsertFromIterator(const_iterator position, const ForwardIterator& first, const ForwardIterator& last, eastl::forward_iterator_tag);\n\n\t\titerator DoInsertValues(const_iterator position, size_type n, const value_type& value);\n\n\t\tvoid DoSwap(this_type& x);\n\t}; // class deque\n\n\n\n\n\t///////////////////////////////////////////////////////////////////////\n\t// DequeBase\n\t///////////////////////////////////////////////////////////////////////\n\n\ttemplate \n\tDequeBase::DequeBase(const allocator_type& allocator)\n\t\t: mpPtrArray(NULL),\n\t\t mnPtrArraySize(0),\n\t\t mItBegin(),\n\t\t mItEnd(),\n\t\t mAllocator(allocator)\n\t{\n\t\t// It is assumed here that the deque subclass will init us when/as needed.\n\t}\n\n\n\ttemplate \n\tDequeBase::DequeBase(size_type n)\n\t\t: mpPtrArray(NULL),\n\t\t mnPtrArraySize(0),\n\t\t mItBegin(),\n\t\t mItEnd(),\n\t\t mAllocator(EASTL_DEQUE_DEFAULT_NAME)\n\t{\n\t\t// It's important to note that DoInit creates space for elements and assigns \n\t\t// mItBegin/mItEnd to point to them, but these elements are not constructed. \n\t\t// You need to immediately follow this constructor with code that constructs the values.\n\t\tDoInit(n); \n\t}\n\n\n\ttemplate \n\tDequeBase::DequeBase(size_type n, const allocator_type& allocator)\n\t\t: mpPtrArray(NULL),\n\t\t mnPtrArraySize(0),\n\t\t mItBegin(),\n\t\t mItEnd(),\n\t\t mAllocator(allocator)\n\t{\n\t\t// It's important to note that DoInit creates space for elements and assigns \n\t\t// mItBegin/mItEnd to point to them, but these elements are not constructed. \n\t\t// You need to immediately follow this constructor with code that constructs the values.\n\t\tDoInit(n); \n\t}\n\n\n\ttemplate \n\tDequeBase::~DequeBase()\n\t{\n\t\tif(mpPtrArray)\n\t\t{\n\t\t\tDoFreeSubarrays(mItBegin.mpCurrentArrayPtr, mItEnd.mpCurrentArrayPtr + 1);\n\t\t\tDoFreePtrArray(mpPtrArray, mnPtrArraySize);\n\t\t\tmpPtrArray = nullptr;\n\t\t}\n\t}\n\n\n\ttemplate \n\tconst typename DequeBase::allocator_type&\n\tDequeBase::get_allocator() const EA_NOEXCEPT\n\t{\n\t\treturn mAllocator;\n\t}\n\n\n\ttemplate \n\ttypename DequeBase::allocator_type&\n\tDequeBase::get_allocator() EA_NOEXCEPT\n\t{\n\t\treturn mAllocator;\n\t}\n\n\n\ttemplate \n\tvoid DequeBase::set_allocator(const allocator_type& allocator)\n\t{\n\t\t// The only time you can set an allocator is with an empty unused container, such as right after construction.\n\t\tif(EASTL_LIKELY(mAllocator != allocator))\n\t\t{\n\t\t\t// our deque implementation always has allocations for mpPtrArray. this set_allocator() is unlike other container's set_allocator() member function\n\t\t\t// in that it actually frees allocations when assigning the allocator. this lack of consistency is unfortunate.\n\t\t\tif(EASTL_LIKELY(mpPtrArray && (mItBegin.mpCurrent == mItEnd.mpCurrent))) // is the container empty?\n\t\t\t{\n\t\t\t\tDoFreeSubarrays(mItBegin.mpCurrentArrayPtr, mItEnd.mpCurrentArrayPtr + 1);\n\t\t\t\tDoFreePtrArray(mpPtrArray, mnPtrArraySize);\n\n\t\t\t\tmAllocator = allocator;\n\t\t\t\tDoInit(0);\n\t\t\t}\n\t\t\telse\n\t\t\t{\n\t\t\t\tEASTL_THROW_MSG_OR_ASSERT(std::logic_error, \"deque::set_allocator -- attempt to change allocator after inserting elements.\");\n\t\t\t}\n\t\t}\n\t}\n\n\n\ttemplate \n\tT* DequeBase::DoAllocateSubarray()\n\t{\n\t\tT* p = (T*)allocate_memory(mAllocator, kDequeSubarraySize * sizeof(T), EASTL_ALIGN_OF(T), 0);\n\t\tEASTL_ASSERT_MSG(p != nullptr, \"the behaviour of eastl::allocators that return nullptr is not defined.\");\n\n\t\t#if EASTL_DEBUG\n\t\t\tmemset((void*)p, 0, kDequeSubarraySize * sizeof(T));\n\t\t#endif\n\n\t\treturn (T*)p;\n\t}\n\n\n\ttemplate \n\tvoid DequeBase::DoFreeSubarray(T* p)\n\t{\n\t\tif(p)\n\t\t\tEASTLFree(mAllocator, p, kDequeSubarraySize * sizeof(T)); \n\t}\n\n\ttemplate \n\tvoid DequeBase::DoFreeSubarrays(T** pBegin, T** pEnd)\n\t{\n\t\twhile(pBegin < pEnd)\n\t\t\tDoFreeSubarray(*pBegin++);\n\t}\n\n\ttemplate \n\tT** DequeBase::DoAllocatePtrArray(size_type n)\n\t{\n\t\t#if EASTL_ASSERT_ENABLED\n\t\t\tif(EASTL_UNLIKELY(n >= 0x80000000))\n\t\t\t\tEASTL_FAIL_MSG(\"deque::DoAllocatePtrArray -- improbably large request.\");\n\t\t#endif\n\n\t\tT** pp = (T**)allocate_memory(mAllocator, n * sizeof(T*), EASTL_ALIGN_OF(T), 0);\n\t\tEASTL_ASSERT_MSG(pp != nullptr, \"the behaviour of eastl::allocators that return nullptr is not defined.\");\n\n\t\t#if EASTL_DEBUG\n\t\t\tmemset((void*)pp, 0, n * sizeof(T*));\n\t\t#endif\n\n\t\treturn pp;\n\t}\n\n\n\ttemplate \n\tvoid DequeBase::DoFreePtrArray(T** pp, size_t n)\n\t{\n\t\tif(pp)\n\t\t\tEASTLFree(mAllocator, pp, n * sizeof(T*)); \n\t}\n\n\n\ttemplate \n\ttypename DequeBase::iterator\n\tDequeBase::DoReallocSubarray(size_type nAdditionalCapacity, Side allocationSide)\n\t{\n\t\t// nAdditionalCapacity refers to the amount of additional space we need to be \n\t\t// able to store in this deque. Typically this function is called as part of \n\t\t// an insert or append operation. This is the function that makes sure there\n\t\t// is enough capacity for the new elements to be copied into the deque.\n\t\t// The new capacity here is always at the front or back of the deque.\n\t\t// This function returns an iterator to that points to the new begin or\n\t\t// the new end of the deque space, depending on allocationSide.\n\n\t\tif(allocationSide == kSideFront)\n\t\t{\n\t\t\t// There might be some free space (nCurrentAdditionalCapacity) at the front of the existing subarray.\n\t\t\tconst size_type nCurrentAdditionalCapacity = (size_type)(mItBegin.mpCurrent - mItBegin.mpBegin);\n\n\t\t\tif(EASTL_UNLIKELY(nCurrentAdditionalCapacity < nAdditionalCapacity)) // If we need to grow downward into a new subarray...\n\t\t\t{\n\t\t\t\tconst difference_type nSubarrayIncrease = (difference_type)(((nAdditionalCapacity - nCurrentAdditionalCapacity) + kDequeSubarraySize - 1) / kDequeSubarraySize);\n\t\t\t\tdifference_type i;\n\n\t\t\t\tif(nSubarrayIncrease > (mItBegin.mpCurrentArrayPtr - mpPtrArray)) // If there are not enough pointers in front of the current (first) one...\n\t\t\t\t\tDoReallocPtrArray((size_type)(nSubarrayIncrease - (mItBegin.mpCurrentArrayPtr - mpPtrArray)), kSideFront);\n\n\t\t\t\t#if EASTL_EXCEPTIONS_ENABLED\n\t\t\t\t\ttry\n\t\t\t\t\t{\n\t\t\t\t#endif\n\t\t\t\t\t\tfor(i = 1; i <= nSubarrayIncrease; ++i)\n\t\t\t\t\t\t\tmItBegin.mpCurrentArrayPtr[-i] = DoAllocateSubarray();\n\t\t\t\t#if EASTL_EXCEPTIONS_ENABLED\n\t\t\t\t\t}\n\t\t\t\t\tcatch(...)\n\t\t\t\t\t{\n\t\t\t\t\t\tfor(difference_type j = 1; j < i; ++j)\n\t\t\t\t\t\t\tDoFreeSubarray(mItBegin.mpCurrentArrayPtr[-j]);\n\t\t\t\t\t\tthrow;\n\t\t\t\t\t}\n\t\t\t\t#endif\n\t\t\t}\n\n\t\t\treturn mItBegin - (difference_type)nAdditionalCapacity;\n\t\t}\n\t\telse // else kSideBack\n\t\t{\n\t\t\tconst size_type nCurrentAdditionalCapacity = (size_type)((mItEnd.mpEnd - 1) - mItEnd.mpCurrent);\n\n\t\t\tif(EASTL_UNLIKELY(nCurrentAdditionalCapacity < nAdditionalCapacity)) // If we need to grow forward into a new subarray...\n\t\t\t{\n\t\t\t\tconst difference_type nSubarrayIncrease = (difference_type)(((nAdditionalCapacity - nCurrentAdditionalCapacity) + kDequeSubarraySize - 1) / kDequeSubarraySize);\n\t\t\t\tdifference_type i;\n\n\t\t\t\tif(nSubarrayIncrease > ((mpPtrArray + mnPtrArraySize) - mItEnd.mpCurrentArrayPtr) - 1) // If there are not enough pointers after the current (last) one...\n\t\t\t\t\tDoReallocPtrArray((size_type)(nSubarrayIncrease - (((mpPtrArray + mnPtrArraySize) - mItEnd.mpCurrentArrayPtr) - 1)), kSideBack);\n\n\t\t\t\t#if EASTL_EXCEPTIONS_ENABLED\n\t\t\t\t\ttry\n\t\t\t\t\t{\n\t\t\t\t#endif\n\t\t\t\t\t\tfor(i = 1; i <= nSubarrayIncrease; ++i)\n\t\t\t\t\t\t\tmItEnd.mpCurrentArrayPtr[i] = DoAllocateSubarray();\n\t\t\t\t#if EASTL_EXCEPTIONS_ENABLED\n\t\t\t\t\t}\n\t\t\t\t\tcatch(...)\n\t\t\t\t\t{\n\t\t\t\t\t\tfor(difference_type j = 1; j < i; ++j)\n\t\t\t\t\t\t\tDoFreeSubarray(mItEnd.mpCurrentArrayPtr[j]);\n\t\t\t\t\t\tthrow;\n\t\t\t\t\t}\n\t\t\t\t#endif\n\t\t\t}\n\n\t\t\treturn mItEnd + (difference_type)nAdditionalCapacity;\n\t\t}\n\t}\n\n\n\ttemplate \n\tvoid DequeBase::DoReallocPtrArray(size_type nAdditionalCapacity, Side allocationSide)\n\t{\n\t\t// This function is not called unless the capacity is known to require a resize.\n\t\t//\n\t\t// We have an array of pointers (mpPtrArray), of which a segment of them are in use and \n\t\t// at either end of the array are zero or more unused pointers. This function is being\n\t\t// called because we need to extend the capacity on either side of this array by \n\t\t// nAdditionalCapacity pointers. However, it's possible that if the user is continually\n\t\t// using push_back and pop_front then the pointer array will continue to be extended \n\t\t// on the back side and unused on the front side. So while we are doing this resizing \n\t\t// here we also take the opportunity to recenter the pointers and thus be balanced.\n\t\t// It man turn out that we don't even need to reallocate the pointer array in order\n\t\t// to increase capacity on one side, as simply moving the pointers to the center may\n\t\t// be enough to open up the requires space.\n\t\t//\n\t\t// Balanced pointer array Unbalanced pointer array (unused space at front, no free space at back)\n\t\t// ----++++++++++++---- ---------+++++++++++\n\n\t\tconst size_type nUnusedPtrCountAtFront = (size_type)(mItBegin.mpCurrentArrayPtr - mpPtrArray);\n\t\tconst size_type nUsedPtrCount = (size_type)(mItEnd.mpCurrentArrayPtr - mItBegin.mpCurrentArrayPtr) + 1;\n\t\tconst size_type nUsedPtrSpace = nUsedPtrCount * sizeof(void*);\n\t\tconst size_type nUnusedPtrCountAtBack = (mnPtrArraySize - nUnusedPtrCountAtFront) - nUsedPtrCount;\n\t\tvalue_type** pPtrArrayBegin;\n\n\t\tif((allocationSide == kSideBack) && (nAdditionalCapacity <= nUnusedPtrCountAtFront)) // If we can take advantage of unused pointers at the front without doing any reallocation...\n\t\t{\n\t\t\tif(nAdditionalCapacity < (nUnusedPtrCountAtFront / 2)) // Possibly use more space than required, if there's a lot of extra space.\n\t\t\t\tnAdditionalCapacity = (nUnusedPtrCountAtFront / 2);\n\n\t\t\tpPtrArrayBegin = mpPtrArray + (nUnusedPtrCountAtFront - nAdditionalCapacity);\n\t\t\tmemmove(pPtrArrayBegin, mItBegin.mpCurrentArrayPtr, nUsedPtrSpace);\n\n\t\t\t#if EASTL_DEBUG\n\t\t\t\tmemset(pPtrArrayBegin + nUsedPtrCount, 0, (size_t)(mpPtrArray + mnPtrArraySize) - (size_t)(pPtrArrayBegin + nUsedPtrCount));\n\t\t\t#endif\n\t\t}\n\t\telse if((allocationSide == kSideFront) && (nAdditionalCapacity <= nUnusedPtrCountAtBack)) // If we can take advantage of unused pointers at the back without doing any reallocation...\n\t\t{\n\t\t\tif(nAdditionalCapacity < (nUnusedPtrCountAtBack / 2)) // Possibly use more space than required, if there's a lot of extra space.\n\t\t\t\tnAdditionalCapacity = (nUnusedPtrCountAtBack / 2);\n\n\t\t\tpPtrArrayBegin = mItBegin.mpCurrentArrayPtr + nAdditionalCapacity;\n\t\t\tmemmove(pPtrArrayBegin, mItBegin.mpCurrentArrayPtr, nUsedPtrSpace);\n\n\t\t\t#if EASTL_DEBUG\n\t\t\t\tmemset(mpPtrArray, 0, (size_t)((uintptr_t)pPtrArrayBegin - (uintptr_t)mpPtrArray));\n\t\t\t#endif\n\t\t}\n\t\telse\n\t\t{\n\t\t\t// In this case we will have to do a reallocation.\n\t\t\tconst size_type nNewPtrArraySize = mnPtrArraySize + eastl::max_alt(mnPtrArraySize, nAdditionalCapacity) + 2; // Allocate extra capacity.\n\t\t\tvalue_type** const pNewPtrArray = DoAllocatePtrArray(nNewPtrArraySize);\n\n\t\t\tpPtrArrayBegin = pNewPtrArray + (mItBegin.mpCurrentArrayPtr - mpPtrArray) + ((allocationSide == kSideFront) ? nAdditionalCapacity : 0);\n\n\t\t\t// The following is equivalent to: eastl::copy(mItBegin.mpCurrentArrayPtr, mItEnd.mpCurrentArrayPtr + 1, pPtrArrayBegin);\n\t\t\t// It's OK to use memcpy instead of memmove because the destination is guaranteed to non-overlap the source.\n\t\t\tif(mpPtrArray) // Could also say: 'if(mItBegin.mpCurrentArrayPtr)' \n\t\t\t\tmemcpy(pPtrArrayBegin, mItBegin.mpCurrentArrayPtr, nUsedPtrSpace);\n\n\t\t\tDoFreePtrArray(mpPtrArray, mnPtrArraySize);\n\n\t\t\tmpPtrArray = pNewPtrArray;\n\t\t\tmnPtrArraySize = nNewPtrArraySize;\n\t\t}\n\n\t\t// We need to reset the begin and end iterators, as code that calls this expects them to *not* be invalidated.\n\t\tmItBegin.SetSubarray(pPtrArrayBegin);\n\t\tmItEnd.SetSubarray((pPtrArrayBegin + nUsedPtrCount) - 1);\n\t}\n\t\n\n\ttemplate \n\tvoid DequeBase::DoInit(size_type n)\n\t{\n\t\t// This code is disabled because it doesn't currently work properly.\n\t\t// We are trying to make it so that a deque can have a zero allocation \n\t\t// initial empty state, but we (OK, I) am having a hard time making\n\t\t// this elegant and efficient. \n\t\t//if(n)\n\t\t//{\n\t\t\tconst size_type nNewPtrArraySize = (size_type)((n / kDequeSubarraySize) + 1); // Always have at least one, even if n is zero.\n\t\t\tconst size_type kMinPtrArraySize_ = kMinPtrArraySize;\n\n\t\t\tmnPtrArraySize = eastl::max_alt(kMinPtrArraySize_, (nNewPtrArraySize + 2)); \n\t\t\tmpPtrArray = DoAllocatePtrArray(mnPtrArraySize);\n\n\t\t\tvalue_type** const pPtrArrayBegin = (mpPtrArray + ((mnPtrArraySize - nNewPtrArraySize) / 2)); // Try to place it in the middle.\n\t\t\tvalue_type** const pPtrArrayEnd = pPtrArrayBegin + nNewPtrArraySize;\n\t\t\tvalue_type** pPtrArrayCurrent = pPtrArrayBegin;\n\n\t\t\t#if EASTL_EXCEPTIONS_ENABLED\n\t\t\t\ttry\n\t\t\t\t{\n\t\t\t\t\ttry\n\t\t\t\t\t{\n\t\t\t#endif\n\t\t\t\t\t\twhile(pPtrArrayCurrent < pPtrArrayEnd)\n\t\t\t\t\t\t\t*pPtrArrayCurrent++ = DoAllocateSubarray();\n\t\t\t#if EASTL_EXCEPTIONS_ENABLED\n\t\t\t\t\t}\n\t\t\t\t\tcatch(...)\n\t\t\t\t\t{\n\t\t\t\t\t\tDoFreeSubarrays(pPtrArrayBegin, pPtrArrayCurrent);\n\t\t\t\t\t\tthrow;\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\tcatch(...)\n\t\t\t\t{\n\t\t\t\t\tDoFreePtrArray(mpPtrArray, mnPtrArraySize);\n\t\t\t\t\tmpPtrArray = NULL;\n\t\t\t\t\tmnPtrArraySize = 0;\n\t\t\t\t\tthrow;\n\t\t\t\t}\n\t\t\t#endif\n\n\t\t\tmItBegin.SetSubarray(pPtrArrayBegin);\n\t\t\tmItBegin.mpCurrent = mItBegin.mpBegin;\n\n\t\t\tmItEnd.SetSubarray(pPtrArrayEnd - 1);\n\t\t\tmItEnd.mpCurrent = mItEnd.mpBegin + (difference_type)(n % kDequeSubarraySize);\n\t\t//}\n\t\t//else // Else we do a zero-allocation initialization.\n\t\t//{\n\t\t// mpPtrArray = NULL;\n\t\t// mnPtrArraySize = 0;\n\t\t//\n\t\t// mItBegin.mpCurrentArrayPtr = NULL;\n\t\t// mItBegin.mpBegin = NULL;\n\t\t// mItBegin.mpEnd = NULL; // We intentionally create a situation whereby the subarray that has no capacity.\n\t\t// mItBegin.mpCurrent = NULL;\n\t\t//\n\t\t// mItEnd = mItBegin;\n\t\t//}\n\t}\n\n\n\n\t///////////////////////////////////////////////////////////////////////\n\t// DequeIterator\n\t///////////////////////////////////////////////////////////////////////\n\n\ttemplate \n\tDequeIterator::DequeIterator()\n\t\t: mpCurrent(NULL), mpBegin(NULL), mpEnd(NULL), mpCurrentArrayPtr(NULL)\n\t{\n\t\t// Empty\n\t}\n\n\n\ttemplate \n\tDequeIterator::DequeIterator(T** pCurrentArrayPtr, T* pCurrent)\n\t\t: mpCurrent(pCurrent), mpBegin(*pCurrentArrayPtr), mpEnd(pCurrent + kDequeSubarraySize), mpCurrentArrayPtr(pCurrentArrayPtr)\n\t{\n\t\t// Empty\n\t}\n\n\n\ttemplate \n\tDequeIterator::DequeIterator(const iterator& x)\n\t\t: mpCurrent(x.mpCurrent), mpBegin(x.mpBegin), mpEnd(x.mpEnd), mpCurrentArrayPtr(x.mpCurrentArrayPtr)\n\t{\n\t\t// Empty\n\t}\n\n\ttemplate \n\tDequeIterator& DequeIterator::operator=(const iterator& x)\n\t{\n\t\tmpCurrent = x.mpCurrent;\n\t\tmpBegin = x.mpBegin;\n\t\tmpEnd = x.mpEnd;\n\t\tmpCurrentArrayPtr = x.mpCurrentArrayPtr;\n\n\t\treturn *this;\n\t}\n\n\n\ttemplate \n\tDequeIterator::DequeIterator(const iterator& x, Increment)\n\t\t: mpCurrent(x.mpCurrent), mpBegin(x.mpBegin), mpEnd(x.mpEnd), mpCurrentArrayPtr(x.mpCurrentArrayPtr)\n\t{\n\t\toperator++();\n\t}\n\n\n\ttemplate \n\tDequeIterator::DequeIterator(const iterator& x, Decrement)\n\t\t: mpCurrent(x.mpCurrent), mpBegin(x.mpBegin), mpEnd(x.mpEnd), mpCurrentArrayPtr(x.mpCurrentArrayPtr)\n\t{\n\t\toperator--();\n\t}\n\n\n\ttemplate \n\ttypename DequeIterator::pointer\n\tDequeIterator::operator->() const\n\t{\n\t\treturn mpCurrent;\n\t}\n\n\n\ttemplate \n\ttypename DequeIterator::reference\n\tDequeIterator::operator*() const\n\t{\n\t\treturn *mpCurrent;\n\t}\n\n\n\ttemplate \n\ttypename DequeIterator::this_type&\n\tDequeIterator::operator++()\n\t{\n\t\tif(EASTL_UNLIKELY(++mpCurrent == mpEnd))\n\t\t{\n\t\t\tmpBegin = *++mpCurrentArrayPtr;\n\t\t\tmpEnd = mpBegin + kDequeSubarraySize;\n\t\t\tmpCurrent = mpBegin;\n\t\t}\n\t\treturn *this;\n\t}\n\n\n\ttemplate \n\ttypename DequeIterator::this_type\n\tDequeIterator::operator++(int)\n\t{\n\t\tconst this_type temp(*this);\n\t\toperator++();\n\t\treturn temp;\n\t}\n\n\n\ttemplate \n\ttypename DequeIterator::this_type&\n\tDequeIterator::operator--()\n\t{\n\t\tif(EASTL_UNLIKELY(mpCurrent == mpBegin))\n\t\t{\n\t\t\tmpBegin = *--mpCurrentArrayPtr;\n\t\t\tmpEnd = mpBegin + kDequeSubarraySize;\n\t\t\tmpCurrent = mpEnd; // fall through...\n\t\t}\n\t\t--mpCurrent;\n\t\treturn *this;\n\t}\n\n\n\ttemplate \n\ttypename DequeIterator::this_type\n\tDequeIterator::operator--(int)\n\t{\n\t\tconst this_type temp(*this);\n\t\toperator--();\n\t\treturn temp;\n\t}\n\n\n\ttemplate \n\ttypename DequeIterator::this_type&\n\tDequeIterator::operator+=(difference_type n)\n\t{\n\t\tconst difference_type subarrayPosition = (mpCurrent - mpBegin) + n;\n\n\t\t// Cast from signed to unsigned (size_t) in order to obviate the need to compare to < 0. \n\t\tif((size_t)subarrayPosition < (size_t)kDequeSubarraySize) // If the new position is within the current subarray (i.e. >= 0 && < kSubArraySize)...\n\t\t\tmpCurrent += n;\n\t\telse\n\t\t{\n\t\t\t// This implementation is a branchless version which works by offsetting \n\t\t\t// the math to always be in the positive range. Much of the values here\n\t\t\t// reduce to constants and both the multiplication and division are of \n\t\t\t// power of two sizes and so this calculation ends up compiling down to \n\t\t\t// just one addition, one shift and one subtraction. This algorithm has \n\t\t\t// a theoretical weakness in that on 32 bit systems it will fail if the \n\t\t\t// value of n is >= (2^32 - 2^24) or 4,278,190,080 of if kDequeSubarraySize\n\t\t\t// is >= 2^24 or 16,777,216.\n\t\t\tEASTL_CT_ASSERT((kDequeSubarraySize & (kDequeSubarraySize - 1)) == 0); // Verify that it is a power of 2.\n\t\t\tconst difference_type subarrayIndex = (((16777216 + subarrayPosition) / (difference_type)kDequeSubarraySize)) - (16777216 / (difference_type)kDequeSubarraySize);\n\n\t\t\tSetSubarray(mpCurrentArrayPtr + subarrayIndex);\n\t\t\tmpCurrent = mpBegin + (subarrayPosition - (subarrayIndex * (difference_type)kDequeSubarraySize));\n\t\t}\n\t\treturn *this;\n\t}\n\n\n\ttemplate \n\ttypename DequeIterator::this_type&\n\tDequeIterator::operator-=(difference_type n)\n\t{\n\t\treturn (*this).operator+=(-n);\n\t}\n\n\n\ttemplate \n\ttypename DequeIterator::this_type\n\tDequeIterator::operator+(difference_type n) const\n\t{\n\t\treturn this_type(*this).operator+=(n);\n\t}\n\n\n\ttemplate \n\ttypename DequeIterator::this_type\n\tDequeIterator::operator-(difference_type n) const\n\t{\n\t\treturn this_type(*this).operator+=(-n);\n\t}\n\n\n\ttemplate \n\ttypename DequeIterator::this_type\n\tDequeIterator::move(const iterator& first, const iterator& last, true_type)\n\t{\n\t\t// To do: Implement this as a loop which does memcpys between subarrays appropriately.\n\t\t// Currently we only do memcpy if the entire operation occurs within a single subarray.\n\t\tif((first.mpBegin == last.mpBegin) && (first.mpBegin == mpBegin)) // If all operations are within the same subarray, implement the operation as a memmove.\n\t\t{\n\t\t\tmemmove(mpCurrent, first.mpCurrent, (size_t)((uintptr_t)last.mpCurrent - (uintptr_t)first.mpCurrent));\n\t\t\treturn *this + (last.mpCurrent - first.mpCurrent);\n\t\t}\n\t\treturn eastl::move(first, last, *this);\n\t}\n\n\n\ttemplate \n\ttypename DequeIterator::this_type\n\tDequeIterator::move(const iterator& first, const iterator& last, false_type)\n\t{\n\t\treturn eastl::move(first, last, *this);\n\t}\n\n\n\ttemplate \n\tvoid DequeIterator::move_backward(const iterator& first, const iterator& last, true_type)\n\t{\n\t\t// To do: Implement this as a loop which does memmoves between subarrays appropriately.\n\t\t// Currently we only do memcpy if the entire operation occurs within a single subarray.\n\t\tif((first.mpBegin == last.mpBegin) && (first.mpBegin == mpBegin)) // If all operations are within the same subarray, implement the operation as a memcpy.\n\t\t\tmemmove(mpCurrent - (last.mpCurrent - first.mpCurrent), first.mpCurrent, (size_t)((uintptr_t)last.mpCurrent - (uintptr_t)first.mpCurrent));\n\t\telse\n\t\t\teastl::move_backward(first, last, *this);\n\t}\n\n\n\ttemplate \n\tvoid DequeIterator::move_backward(const iterator& first, const iterator& last, false_type)\n\t{\n\t\teastl::move_backward(first, last, *this);\n\t}\n\n\n\ttemplate \n\tvoid DequeIterator::SetSubarray(T** pCurrentArrayPtr)\n\t{\n\t\tmpCurrentArrayPtr = pCurrentArrayPtr;\n\t\tmpBegin = *pCurrentArrayPtr;\n\t\tmpEnd = mpBegin + kDequeSubarraySize;\n\t}\n\n\n\t// The C++ defect report #179 requires that we support comparisons between const and non-const iterators.\n\t// Thus we provide additional template paremeters here to support this. The defect report does not\n\t// require us to support comparisons between reverse_iterators and const_reverse_iterators.\n\ttemplate \n\tinline bool operator==(const DequeIterator& a, \n\t\t\t\t\t\t const DequeIterator& b)\n\t{\n\t\treturn a.mpCurrent == b.mpCurrent;\n\t}\n\n\n\ttemplate \n\tinline bool operator!=(const DequeIterator& a, \n\t\t\t\t\t\t const DequeIterator& b)\n\t{\n\t\treturn a.mpCurrent != b.mpCurrent;\n\t}\n\n\n\t// We provide a version of operator!= for the case where the iterators are of the \n\t// same type. This helps prevent ambiguity errors in the presence of rel_ops.\n\ttemplate \n\tinline bool operator!=(const DequeIterator& a, \n\t\t\t\t\t\t const DequeIterator& b)\n\t{\n\t\treturn a.mpCurrent != b.mpCurrent;\n\t}\n\n\n\ttemplate \n\tinline bool operator<(const DequeIterator& a, \n\t\t\t\t\t\t const DequeIterator& b)\n\t{\n\t\treturn (a.mpCurrentArrayPtr == b.mpCurrentArrayPtr) ? (a.mpCurrent < b.mpCurrent) : (a.mpCurrentArrayPtr < b.mpCurrentArrayPtr);\n\t}\n\n\n\ttemplate \n\tinline bool operator>(const DequeIterator& a, \n\t\t\t\t\t\t const DequeIterator& b)\n\t{\n\t\treturn (a.mpCurrentArrayPtr == b.mpCurrentArrayPtr) ? (a.mpCurrent > b.mpCurrent) : (a.mpCurrentArrayPtr > b.mpCurrentArrayPtr);\n\t}\n\n\n\ttemplate \n\tinline bool operator<=(const DequeIterator& a, \n\t\t\t\t\t\t const DequeIterator& b)\n\t{\n\t\treturn (a.mpCurrentArrayPtr == b.mpCurrentArrayPtr) ? (a.mpCurrent <= b.mpCurrent) : (a.mpCurrentArrayPtr <= b.mpCurrentArrayPtr);\n\t}\n\n\n\ttemplate \n\tinline bool operator>=(const DequeIterator& a, \n\t\t\t\t\t\t const DequeIterator& b)\n\t{\n\t\treturn (a.mpCurrentArrayPtr == b.mpCurrentArrayPtr) ? (a.mpCurrent >= b.mpCurrent) : (a.mpCurrentArrayPtr >= b.mpCurrentArrayPtr);\n\t}\n\n\n\t// Random access iterators must support operator + and operator -.\n\t// You can only add an integer to an iterator, and you cannot add two iterators.\n\ttemplate \n\tinline DequeIterator\n\toperator+(ptrdiff_t n, const DequeIterator& x)\n\t{\n\t\treturn x + n; // Implement (n + x) in terms of (x + n).\n\t}\n\n\n\t// You can only add an integer to an iterator, but you can subtract two iterators.\n\t// The C++ defect report #179 mentioned above specifically refers to \n\t// operator - and states that we support the subtraction of const and non-const iterators.\n\ttemplate \n\tinline typename DequeIterator::difference_type\n\toperator-(const DequeIterator& a,\n\t\t\t const DequeIterator& b)\n\t{\n\t\t// This is a fairly clever algorithm that has been used in STL deque implementations since the original HP STL:\n\t\ttypedef typename DequeIterator::difference_type difference_type;\n\n\t\treturn ((difference_type)kDequeSubarraySize * ((a.mpCurrentArrayPtr - b.mpCurrentArrayPtr) - 1)) + (a.mpCurrent - a.mpBegin) + (b.mpEnd - b.mpCurrent);\n\t}\n\n\n\n\n\t///////////////////////////////////////////////////////////////////////\n\t// deque\n\t///////////////////////////////////////////////////////////////////////\n\n\ttemplate \n\tinline deque::deque()\n\t\t: base_type((size_type)0)\n\t{\n\t\t// Empty\n\t}\n\n\n\ttemplate \n\tinline deque::deque(const allocator_type& allocator)\n\t\t: base_type((size_type)0, allocator)\n\t{\n\t\t// Empty\n\t}\n\n\n\ttemplate \n\tinline deque::deque(size_type n, const allocator_type& allocator)\n\t\t: base_type(n, allocator)\n\t{\n\t\tDoFillInit(value_type());\n\t}\n\n\n\ttemplate \n\tinline deque::deque(size_type n, const value_type& value, const allocator_type& allocator)\n\t\t: base_type(n, allocator)\n\t{\n\t\tDoFillInit(value);\n\t}\n\n\n\ttemplate \n\tinline deque::deque(const this_type& x)\n\t\t: base_type(x.size(), x.mAllocator)\n\t{\n\t\teastl::uninitialized_copy(x.mItBegin, x.mItEnd, mItBegin);\n\t}\n\n\n\ttemplate \n\tinline deque::deque(this_type&& x)\n\t : base_type((size_type)0, x.mAllocator)\n\t{\n\t\tswap(x);\n\t}\n\n\n\ttemplate \n\tinline deque::deque(this_type&& x, const allocator_type& allocator)\n\t : base_type((size_type)0, allocator)\n\t{\n\t\tswap(x); // member swap handles the case that x has a different allocator than our allocator by doing a copy.\n\t}\n\n\n\ttemplate \n\tinline deque::deque(std::initializer_list ilist, const allocator_type& allocator)\n\t\t: base_type(allocator)\n\t{\n\t\tDoInit(ilist.begin(), ilist.end(), false_type());\n\t}\n\n\n\ttemplate \n\ttemplate \n\tinline deque::deque(InputIterator first, InputIterator last)\n\t\t: base_type(EASTL_DEQUE_DEFAULT_ALLOCATOR) // Call the empty base constructor, which does nothing. We need to do all the work in our own DoInit.\n\t{\n\t\tDoInit(first, last, is_integral());\n\t}\n\n\n\ttemplate \n\tinline deque::~deque()\n\t{\n\t\t// Call destructors. Parent class will free the memory.\n\t\tfor(iterator itCurrent(mItBegin); itCurrent != mItEnd; ++itCurrent)\n\t\t\titCurrent.mpCurrent->~value_type();\n\t} \n\n\n\ttemplate \n\ttypename deque::this_type& \n\tdeque::operator=(const this_type& x)\n\t{\n\t\tif(&x != this) // If not assigning to ourselves...\n\t\t{\n\t\t\t// If (EASTL_ALLOCATOR_COPY_ENABLED == 1) and the current contents are allocated by an \n\t\t\t// allocator that's unequal to x's allocator, we need to reallocate our elements with \n\t\t\t// our current allocator and reallocate it with x's allocator. If the allocators are \n\t\t\t// equal then we can use a more optimal algorithm that doesn't reallocate our elements\n\t\t\t// but instead can copy them in place.\n\n\t\t\t#if EASTL_ALLOCATOR_COPY_ENABLED\n\t\t\t\tbool bSlowerPathwayRequired = (mAllocator != x.mAllocator);\n\t\t\t#else\n\t\t\t\tbool bSlowerPathwayRequired = false;\n\t\t\t#endif\n\n\t\t\tif(bSlowerPathwayRequired)\n\t\t\t{\n\t\t\t\t// We can't currently use set_capacity(0) or shrink_to_fit, because they \n\t\t\t\t// leave a remaining allocation with our old allocator. So we do a similar \n\t\t\t\t// thing but set our allocator to x.mAllocator while doing so.\n\t\t\t\tthis_type temp(x.mAllocator);\n\t\t\t\tDoSwap(temp);\n\t\t\t\t// Now we have an empty container with an allocator equal to x.mAllocator, ready to assign from x.\n\t\t\t}\n\n\t\t\tDoAssign(x.begin(), x.end(), eastl::false_type());\n\t\t}\n\n\t\treturn *this;\n\t}\n\n\n\ttemplate \n\tinline typename deque::this_type& \n\tdeque::operator=(this_type&& x)\n\t{\n\t\tif(this != &x)\n\t\t{\n\t\t\tthis_type temp(mAllocator);\n\t\t\tswap(temp);\n\t\t\tswap(x); // member swap handles the case that x has a different allocator than our allocator by doing a copy.\n\t\t}\n\t\treturn *this; \n\t}\n\n\n\ttemplate \n\tinline typename deque::this_type& \n\tdeque::operator=(std::initializer_list ilist)\n\t{\n\t\tDoAssign(ilist.begin(), ilist.end(), false_type());\n\t\treturn *this;\n\t}\n\n\n\ttemplate \n\tinline void deque::assign(size_type n, const value_type& value)\n\t{\n\t\tDoAssignValues(n, value);\n\t}\n\n\n\ttemplate \n\tinline void deque::assign(std::initializer_list ilist)\n\t{\n\t\tDoAssign(ilist.begin(), ilist.end(), false_type());\n\t}\n\n\n\t// It turns out that the C++ std::deque specifies a two argument\n\t// version of assign that takes (int size, int value). These are not\n\t// iterators, so we need to do a template compiler trick to do the right thing. \n\ttemplate \n\ttemplate \n\tinline void deque::assign(InputIterator first, InputIterator last)\n\t{\n\t\tDoAssign(first, last, is_integral());\n\t}\n\n\n\ttemplate \n\tinline typename deque::iterator \n\tdeque::begin() EA_NOEXCEPT\n\t{\n\t\treturn mItBegin;\n\t}\n\n\n\ttemplate \n\tinline typename deque::const_iterator \n\tdeque::begin() const EA_NOEXCEPT\n\t{\n\t\treturn mItBegin;\n\t}\n\n\n\ttemplate \n\tinline typename deque::const_iterator \n\tdeque::cbegin() const EA_NOEXCEPT\n\t{\n\t\treturn mItBegin;\n\t}\n\n\n\ttemplate \n\tinline typename deque::iterator \n\tdeque::end() EA_NOEXCEPT\n\t{\n\t\treturn mItEnd;\n\t}\n\n\n\ttemplate \n\ttypename deque::const_iterator\n\tdeque::end() const EA_NOEXCEPT\n\t{\n\t\treturn mItEnd;\n\t}\n\n\n\ttemplate \n\tinline typename deque::const_iterator\n\tdeque::cend() const EA_NOEXCEPT\n\t{\n\t\treturn mItEnd;\n\t}\n\n\n\ttemplate \n\tinline typename deque::reverse_iterator\n\tdeque::rbegin() EA_NOEXCEPT\n\t{\n\t\treturn reverse_iterator(mItEnd);\n\t}\n\n\n\ttemplate \n\tinline typename deque::const_reverse_iterator\n\tdeque::rbegin() const EA_NOEXCEPT\n\t{\n\t\treturn const_reverse_iterator(mItEnd);\n\t}\n\n\n\ttemplate \n\tinline typename deque::const_reverse_iterator\n\tdeque::crbegin() const EA_NOEXCEPT\n\t{\n\t\treturn const_reverse_iterator(mItEnd);\n\t}\n\n\n\ttemplate \n\tinline typename deque::reverse_iterator\n\tdeque::rend() EA_NOEXCEPT\n\t{\n\t\treturn reverse_iterator(mItBegin);\n\t}\n\n\n\ttemplate \n\tinline typename deque::const_reverse_iterator\n\tdeque::rend() const EA_NOEXCEPT\n\t{\n\t\treturn const_reverse_iterator(mItBegin);\n\t}\n\n\n\ttemplate \n\tinline typename deque::const_reverse_iterator\n\tdeque::crend() const EA_NOEXCEPT\n\t{\n\t\treturn const_reverse_iterator(mItBegin);\n\t}\n\n\n\ttemplate \n\tinline bool deque::empty() const EA_NOEXCEPT\n\t{\n\t\treturn mItBegin.mpCurrent == mItEnd.mpCurrent;\n\t}\n\n\n\ttemplate \n\ttypename deque::size_type\n\tinline deque::size() const EA_NOEXCEPT\n\t{\n\t\treturn (size_type)(mItEnd - mItBegin);\n\t}\n\n\n\ttemplate \n\tinline void deque::resize(size_type n, const value_type& value)\n\t{\n\t\tconst size_type nSizeCurrent = size();\n\n\t\tif(n > nSizeCurrent) // We expect that more often than not, resizes will be upsizes.\n\t\t\tinsert(mItEnd, n - nSizeCurrent, value);\n\t\telse\n\t\t\terase(mItBegin + (difference_type)n, mItEnd);\n\t}\n\n\n\ttemplate \n\tinline void deque::resize(size_type n)\n\t{\n\t\tresize(n, value_type());\n\t}\n\n\n\ttemplate \n\tinline void deque::shrink_to_fit()\n\t{\n\t\tthis_type x(eastl::make_move_iterator(begin()), eastl::make_move_iterator(end()));\n\t\tswap(x);\n\t}\n\n\n\ttemplate \n\tinline void deque::set_capacity(size_type n)\n\t{\n\t\t// Currently there isn't a way to remove all allocations from a deque, as it \n\t\t// requires a single starting allocation for the subarrays. So we can't just\n\t\t// free all memory without leaving it in a bad state. So the best means of \n\t\t// implementing set_capacity() is to do what we do below.\n\n\t\tif(n == 0)\n\t\t{\n\t\t\tthis_type temp(mAllocator);\n\t\t\tDoSwap(temp);\n\t\t}\n\t\telse if(n < size())\n\t\t{\n\t\t\t// We currently ignore the request to reduce capacity. To do: Implement this\n\t\t\t// and do it in a way that doesn't result in temporarily ~doubling our memory usage.\n\t\t\t// That might involve trimming unused subarrays from the front or back of \n\t\t\t// the container.\n\t\t\tresize(n);\n\t\t} \n\t}\n\n\n\ttemplate \n\ttypename deque::reference\n\tdeque::operator[](size_type n)\n\t{\n\t\t#if EASTL_ASSERT_ENABLED && EASTL_EMPTY_REFERENCE_ASSERT_ENABLED\n\t\t\tif (EASTL_UNLIKELY(n >= (size_type)(mItEnd - mItBegin)))\n\t\t\t\tEASTL_FAIL_MSG(\"deque::operator[] -- out of range\");\n\t\t#elif EASTL_ASSERT_ENABLED\n\t\t\t// We allow taking a reference to deque[0]\n\t\t\tif (EASTL_UNLIKELY((n != 0) && n >= (size_type)(mItEnd - mItBegin)))\n\t\t\t\tEASTL_FAIL_MSG(\"deque::operator[] -- out of range\");\n\t\t#endif\n\n\t\t// See DequeIterator::operator+=() for an explanation of the code below.\n\t\titerator it(mItBegin);\n\n\t\tconst difference_type subarrayPosition = (difference_type)((it.mpCurrent - it.mpBegin) + (difference_type)n);\n\t\tconst difference_type subarrayIndex = (((16777216 + subarrayPosition) / (difference_type)kDequeSubarraySize)) - (16777216 / (difference_type)kDequeSubarraySize);\n\n\t\treturn *(*(it.mpCurrentArrayPtr + subarrayIndex) + (subarrayPosition - (subarrayIndex * (difference_type)kDequeSubarraySize)));\n\t}\n\n\n\ttemplate \n\ttypename deque::const_reference\n\tdeque::operator[](size_type n) const\n\t{\n\t\t#if EASTL_ASSERT_ENABLED && EASTL_EMPTY_REFERENCE_ASSERT_ENABLED\n\t\t\tif (EASTL_UNLIKELY(n >= (size_type)(mItEnd - mItBegin)))\n\t\t\t\tEASTL_FAIL_MSG(\"deque::operator[] -- out of range\");\n\t\t#elif EASTL_ASSERT_ENABLED\n\t\t\t// We allow the user to use a reference to deque[0] of an empty container.\n\t\t\tif (EASTL_UNLIKELY((n != 0) && n >= (size_type)(mItEnd - mItBegin)))\n\t\t\t\tEASTL_FAIL_MSG(\"deque::operator[] -- out of range\");\n\t\t#endif\n\n\t\t// See DequeIterator::operator+=() for an explanation of the code below.\n\t\titerator it(mItBegin);\n\n\t\tconst difference_type subarrayPosition = (it.mpCurrent - it.mpBegin) + (difference_type)n;\n\t\tconst difference_type subarrayIndex = (((16777216 + subarrayPosition) / (difference_type)kDequeSubarraySize)) - (16777216 / (difference_type)kDequeSubarraySize);\n\n\t\treturn *(*(it.mpCurrentArrayPtr + subarrayIndex) + (subarrayPosition - (subarrayIndex * (difference_type)kDequeSubarraySize)));\n\t}\n\n\n\ttemplate \n\ttypename deque::reference\n\tdeque::at(size_type n)\n\t{\n\t\t#if EASTL_EXCEPTIONS_ENABLED\n\t\t\tif(n >= (size_type)(mItEnd - mItBegin))\n\t\t\t\tthrow std::out_of_range(\"deque::at -- out of range\");\n\t\t#elif EASTL_ASSERT_ENABLED\n\t\t\tif(n >= (size_type)(mItEnd - mItBegin))\n\t\t\t\tEASTL_FAIL_MSG(\"deque::at -- out of range\");\n\t\t#endif\n\t\treturn *(mItBegin.operator+((difference_type)n));\n\t}\n\n\n\ttemplate \n\ttypename deque::const_reference\n\tdeque::at(size_type n) const\n\t{\n\t\t#if EASTL_EXCEPTIONS_ENABLED\n\t\t\tif(n >= (size_type)(mItEnd - mItBegin))\n\t\t\t\tthrow std::out_of_range(\"deque::at -- out of range\");\n\t\t#elif EASTL_ASSERT_ENABLED\n\t\t\tif(n >= (size_type)(mItEnd - mItBegin))\n\t\t\t\tEASTL_FAIL_MSG(\"deque::at -- out of range\");\n\t\t#endif\n\t\treturn *(mItBegin.operator+((difference_type)n));\n\t}\n\n\n\ttemplate \n\ttypename deque::reference\n\tdeque::front()\n\t{\n\t\t#if EASTL_ASSERT_ENABLED && EASTL_EMPTY_REFERENCE_ASSERT_ENABLED\n\t\t\tif (EASTL_UNLIKELY((size_type)(mItEnd == mItBegin)))\n\t\t\t\tEASTL_FAIL_MSG(\"deque::front -- empty deque\");\n\t\t#else\n\t\t\t// We allow the user to reference an empty container.\n\t\t#endif\n\n\t\treturn *mItBegin;\n\t}\n\n\n\ttemplate \n\ttypename deque::const_reference\n\tdeque::front() const\n\t{\n\t\t#if EASTL_ASSERT_ENABLED && EASTL_EMPTY_REFERENCE_ASSERT_ENABLED\n\t\t\tif (EASTL_UNLIKELY((size_type)(mItEnd == mItBegin)))\n\t\t\t\tEASTL_FAIL_MSG(\"deque::front -- empty deque\");\n\t\t#else\n\t\t\t// We allow the user to reference an empty container.\n\t\t#endif\n\n\t\treturn *mItBegin;\n\t}\n\n\n\ttemplate \n\ttypename deque::reference\n\tdeque::back()\n\t{\n\t\t#if EASTL_ASSERT_ENABLED\n\t\t\t// Decrementing an iterator with an empty container will result in undefined behaviour.\n\t\t\t// specifically: the iterator decrement will apply pointer arithmetic to a nullptr (depending on the situation either mpCurrentArrayPtr or mpBegin).\n\t\t\tif (EASTL_UNLIKELY((size_type)(mItEnd == mItBegin)))\n\t\t\t\tEASTL_FAIL_MSG(\"deque::back -- empty deque\");\n\t\t#endif\n\n\t\treturn *iterator(mItEnd, typename iterator::Decrement());\n\t}\n\n\n\ttemplate \n\ttypename deque::const_reference\n\tdeque::back() const\n\t{\n\t\t#if EASTL_ASSERT_ENABLED\n\t\t\t// Decrementing an iterator with an empty container will result in undefined behaviour.\n\t\t\t// specifically: the iterator decrement will apply pointer arithmetic to a nullptr (depending on the situation either mpCurrentArrayPtr or mpBegin).\n\t\t\tif (EASTL_UNLIKELY((size_type)(mItEnd == mItBegin)))\n\t\t\t\tEASTL_FAIL_MSG(\"deque::back -- empty deque\");\n\t\t#endif\n\n\t\treturn *iterator(mItEnd, typename iterator::Decrement());\n\t}\n\n\n\ttemplate \n\tvoid deque::push_front(const value_type& value)\n\t{\n\t\templace_front(value);\n\t}\n\n\n\ttemplate \n\tvoid deque::push_front(value_type&& value)\n\t{\n\t\templace_front(eastl::move(value));\n\t}\n\n\n\ttemplate \n\ttypename deque::reference\n\tdeque::push_front()\n\t{\n\t\templace_front(value_type());\n\t\treturn *mItBegin; // Same as return front();\n\t}\n\n\n\ttemplate \n\tvoid deque::push_back(const value_type& value)\n\t{\n\t\templace_back(value);\n\t}\n\n\n\ttemplate \n\tvoid deque::push_back(value_type&& value)\n\t{\n\t\templace_back(eastl::move(value));\n\t}\n\n\n\ttemplate \n\ttypename deque::reference\n\tdeque::push_back()\n\t{\n\t\templace_back(value_type());\n\t\treturn *iterator(mItEnd, typename iterator::Decrement()); // Same thing as return back();\n\t}\n\n\n\ttemplate \n\tvoid deque::pop_front()\n\t{\n\t\t#if EASTL_ASSERT_ENABLED\n\t\t\tif(EASTL_UNLIKELY((size_type)(mItEnd == mItBegin)))\n\t\t\t\tEASTL_FAIL_MSG(\"deque::pop_front -- empty deque\");\n\t\t#endif\n\n\t\tif((mItBegin.mpCurrent + 1) != mItBegin.mpEnd) // If the operation is very simple...\n\t\t\t(mItBegin.mpCurrent++)->~value_type();\n\t\telse\n\t\t{\n\t\t\t// This is executed only when we are popping the end (last) item off the front-most subarray.\n\t\t\t// In this case we need to free the subarray and point mItBegin to the next subarray.\n\t\t\t#ifdef EA_DEBUG\n\t\t\t\tvalue_type** pp = mItBegin.mpCurrentArrayPtr;\n\t\t\t#endif\n\n\t\t\tmItBegin.mpCurrent->~value_type(); // mpCurrent == mpEnd - 1\n\t\t\tDoFreeSubarray(mItBegin.mpBegin);\n\t\t\tmItBegin.SetSubarray(mItBegin.mpCurrentArrayPtr + 1);\n\t\t\tmItBegin.mpCurrent = mItBegin.mpBegin;\n\n\t\t\t#ifdef EA_DEBUG\n\t\t\t\t*pp = NULL;\n\t\t\t#endif\n\t\t}\n\t}\n\n\n\ttemplate \n\tvoid deque::pop_back()\n\t{\n\t\t#if EASTL_ASSERT_ENABLED\n\t\t\tif(EASTL_UNLIKELY((size_type)(mItEnd == mItBegin)))\n\t\t\t\tEASTL_FAIL_MSG(\"deque::pop_back -- empty deque\");\n\t\t#endif\n\n\t\tif(mItEnd.mpCurrent != mItEnd.mpBegin) // If the operation is very simple...\n\t\t\t(--mItEnd.mpCurrent)->~value_type();\n\t\telse\n\t\t{\n\t\t\t// This is executed only when we are popping the first item off the last subarray.\n\t\t\t// In this case we need to free the subarray and point mItEnd to the previous subarray.\n\t\t\t#ifdef EA_DEBUG\n\t\t\t\tvalue_type** pp = mItEnd.mpCurrentArrayPtr;\n\t\t\t#endif\n\n\t\t\tDoFreeSubarray(mItEnd.mpBegin);\n\t\t\tmItEnd.SetSubarray(mItEnd.mpCurrentArrayPtr - 1);\n\t\t\tmItEnd.mpCurrent = mItEnd.mpEnd - 1; // Recall that mItEnd points to one-past the last item in the container.\n\t\t\tmItEnd.mpCurrent->~value_type(); // Thus we need to call the destructor on the item *before* that last item.\n\n\t\t\t#ifdef EA_DEBUG\n\t\t\t\t*pp = NULL;\n\t\t\t#endif\n\t\t}\n\t}\n\n\n\ttemplate \n\ttemplate\n\ttypename deque::iterator\n\tdeque::emplace(const_iterator position, Args&&... args)\n\t{\n\t\tif(EASTL_UNLIKELY(position.mpCurrent == mItEnd.mpCurrent)) // If we are doing the same thing as push_back...\n\t\t{\n\t\t\templace_back(eastl::forward(args)...);\n\t\t\treturn iterator(mItEnd, typename iterator::Decrement()); // Unfortunately, we need to make an iterator here, as the above push_back is an operation that can invalidate existing iterators.\n\t\t}\n\t\telse if(EASTL_UNLIKELY(position.mpCurrent == mItBegin.mpCurrent)) // If we are doing the same thing as push_front...\n\t\t{\n\t\t\templace_front(eastl::forward(args)...);\n\t\t\treturn mItBegin;\n\t\t}\n\n\t\titerator itPosition(position, typename iterator::FromConst());\n\t\tvalue_type valueSaved(eastl::forward(args)...); // We need to save this because value may come from within our container. It would be somewhat tedious to make a workaround that could avoid this.\n\t\tconst difference_type i(itPosition - mItBegin);\n\n\t\t#if EASTL_ASSERT_ENABLED\n\t\t\tEASTL_ASSERT(!empty()); // The push_front and push_back calls below assume that we are non-empty. It turns out this is never called unless so.\n\n\t\t\tif(EASTL_UNLIKELY(!(validate_iterator(itPosition) & isf_valid)))\n\t\t\t\tEASTL_FAIL_MSG(\"deque::emplace -- invalid iterator\");\n\t\t#endif\n\n\t\tif(i < (difference_type)(size() / 2)) // Should we insert at the front or at the back? We divide the range in half.\n\t\t{\n\t\t\templace_front(eastl::move(*mItBegin)); // This operation potentially invalidates all existing iterators and so we need to assign them anew relative to mItBegin below.\n\n\t\t\titPosition = mItBegin + i;\n\n\t\t\tconst iterator newPosition (itPosition, typename iterator::Increment());\n\t\t\t\t iterator oldBegin (mItBegin, typename iterator::Increment());\n\t\t\tconst iterator oldBeginPlus1(oldBegin, typename iterator::Increment());\n\n\t\t\toldBegin.move(oldBeginPlus1, newPosition, eastl::is_trivially_copyable());\n\t\t}\n\t\telse\n\t\t{\n\t\t\templace_back(eastl::move(*iterator(mItEnd, typename iterator::Decrement())));\n\n\t\t\titPosition = mItBegin + i;\n\n\t\t\t\t iterator oldBack (mItEnd, typename iterator::Decrement());\n\t\t\tconst iterator oldBackMinus1(oldBack, typename iterator::Decrement());\n\n\t\t\toldBack.move_backward(itPosition, oldBackMinus1, eastl::is_trivially_copyable());\n\t\t}\n\n\t\t*itPosition = eastl::move(valueSaved);\n\n\t\treturn itPosition;\n\t}\n\n\ttemplate \n\ttemplate\n\ttypename deque::reference deque::emplace_front(Args&&... args)\n\t{\n\t\tif(mItBegin.mpCurrent != mItBegin.mpBegin) // If we have room in the first subarray... we hope that usually this 'new' pathway gets executed, as it is slightly faster.\n\t\t\tdetail::allocator_construct(mAllocator, --mItBegin.mpCurrent, eastl::forward(args)...);\n\t\telse\n\t\t{\n\t\t\t// To consider: Detect if value isn't coming from within this container and handle that efficiently.\n\t\t\tvalue_type valueSaved(eastl::forward(args)...); // We need to make a temporary, because args may be a value_type that comes from within our container and the operations below may change the container. But we can use move instead of copy.\n\n\t\t\tif(mItBegin.mpCurrentArrayPtr == mpPtrArray) // If there are no more pointers in front of the current (first) one...\n\t\t\t\tDoReallocPtrArray(1, kSideFront);\n\n\t\t\tmItBegin.mpCurrentArrayPtr[-1] = DoAllocateSubarray();\n\n\t\t\t#if EASTL_EXCEPTIONS_ENABLED\n\t\t\t\ttry\n\t\t\t\t{\n\t\t\t#endif\n\t\t\t\t\tmItBegin.SetSubarray(mItBegin.mpCurrentArrayPtr - 1);\n\t\t\t\t\tmItBegin.mpCurrent = mItBegin.mpEnd - 1;\n\t\t\t\t\tdetail::allocator_construct(mAllocator, mItBegin.mpCurrent, eastl::move(valueSaved));\n\t\t\t#if EASTL_EXCEPTIONS_ENABLED\n\t\t\t\t}\n\t\t\t\tcatch(...)\n\t\t\t\t{\n\t\t\t\t\t++mItBegin; // The exception could only occur in the new operation above, after we have incremented mItBegin. So we need to undo it.\n\t\t\t\t\tDoFreeSubarray(mItBegin.mpCurrentArrayPtr[-1]);\n\t\t\t\t\tthrow;\n\t\t\t\t}\n\t\t\t#endif\n\t\t}\n\n\t\treturn *mItBegin; // Same as return front();\n\t}\n\n\ttemplate \n\ttemplate\n\ttypename deque::reference deque::emplace_back(Args&&... args)\n\t{\n\t\tif ((mItEnd.mpCurrent + 1) != mItEnd.mpEnd) // If we have room in the last subarray... we hope that usually this 'new' pathway gets executed, as it is slightly faster.\n\t\t{\n\t\t\treference back = *mItEnd.mpCurrent;\n\t\t\tdetail::allocator_construct(mAllocator, mItEnd.mpCurrent++, eastl::forward(args)...);\n\t\t\treturn back;\n\t\t}\n\t\telse\n\t\t{\n\t\t\t// To consider: Detect if value isn't coming from within this container and handle that efficiently.\n\t\t\tvalue_type valueSaved(eastl::forward(args)...); // We need to make a temporary, because args may be a value_type that comes from within our container and the operations below may change the container. But we can use move instead of copy.\n\t\t\tif(((mItEnd.mpCurrentArrayPtr - mpPtrArray) + 1) >= (difference_type)mnPtrArraySize) // If there are no more pointers after the current (last) one.\n\t\t\t\tDoReallocPtrArray(1, kSideBack);\n\n\t\t\tmItEnd.mpCurrentArrayPtr[1] = DoAllocateSubarray();\n\n\t\t\t#if EASTL_EXCEPTIONS_ENABLED\n\t\t\t\ttry\n\t\t\t\t{\n\t\t\t#endif\n\t\t\t\t\tdetail::allocator_construct(mAllocator, mItEnd.mpCurrent, eastl::move(valueSaved));\n\t\t\t\t\tmItEnd.SetSubarray(mItEnd.mpCurrentArrayPtr + 1);\n\t\t\t\t\tmItEnd.mpCurrent = mItEnd.mpBegin;\n\t\t\t#if EASTL_EXCEPTIONS_ENABLED\n\t\t\t\t}\n\t\t\t\tcatch(...)\n\t\t\t\t{\n\t\t\t\t\t// No need to execute '--mItEnd', as the exception could only occur in the new operation above before we set mItEnd.\n\t\t\t\t\tDoFreeSubarray(mItEnd.mpCurrentArrayPtr[1]);\n\t\t\t\t\tthrow;\n\t\t\t\t}\n\t\t\t#endif\n\n\t\t\treturn *iterator(mItEnd, typename iterator::Decrement()); // Same as return back();\n\t\t}\n\t}\n\n\n\ttemplate \n\ttypename deque::iterator\n\tdeque::insert(const_iterator position, const value_type& value)\n\t{\n\t\treturn emplace(position, value);\n\t}\n\n\n\ttemplate \n\ttypename deque::iterator\n\tdeque::insert(const_iterator position, value_type&& value)\n\t{\n\t\treturn emplace(position, eastl::move(value));\n\t}\n\n\n\ttemplate \n\ttypename deque::iterator\n\tdeque::insert(const_iterator position, size_type n, const value_type& value)\n\t{\n\t\treturn DoInsertValues(position, n, value);\n\t}\n\n\n\ttemplate \n\ttemplate \n\ttypename deque::iterator\n\tdeque::insert(const_iterator position, InputIterator first, InputIterator last)\n\t{\n\t\treturn DoInsert(position, first, last, is_integral()); // The C++ standard requires this sort of behaviour, as InputIterator might actually be Integer and 'first' is really 'count' and 'last' is really 'value'.\n\t}\n\n\n\ttemplate \n\ttypename deque::iterator\n\tdeque::insert(const_iterator position, std::initializer_list ilist)\n\t{\n\t\tconst difference_type i(position - mItBegin);\n\t\tDoInsert(position, ilist.begin(), ilist.end(), false_type());\n\t\treturn (mItBegin + i);\n\t}\n\n\n\ttemplate \n\ttypename deque::iterator\n\tdeque::erase(const_iterator position)\n\t{\n\t\t#if EASTL_ASSERT_ENABLED\n\t\t\tif(EASTL_UNLIKELY(!(validate_iterator(position) & isf_valid)))\n\t\t\t\tEASTL_FAIL_MSG(\"deque::erase -- invalid iterator\");\n\n\t\t\tif(EASTL_UNLIKELY(position == end()))\n\t\t\t\tEASTL_FAIL_MSG(\"deque::erase -- end() iterator is an invalid iterator for erase\");\n\t\t#endif\n\n\t\titerator itPosition(position, typename iterator::FromConst());\n\t\titerator itNext(itPosition, typename iterator::Increment());\n\t\tconst difference_type i(itPosition - mItBegin);\n\n\t\tif(i < (difference_type)(size() / 2)) // Should we move the front entries forward or the back entries backward? We divide the range in half.\n\t\t{\n\t\t\titNext.move_backward(mItBegin, itPosition, eastl::is_trivially_copyable());\n\t\t\tpop_front();\n\t\t}\n\t\telse\n\t\t{\n\t\t\titPosition.move(itNext, mItEnd, eastl::is_trivially_copyable());\n\t\t\tpop_back();\n\t\t}\n\n\t\treturn mItBegin + i;\n\t}\n\n\n\ttemplate \n\ttypename deque::iterator\n\tdeque::erase(const_iterator first, const_iterator last)\n\t{\n\t\titerator itFirst(first, typename iterator::FromConst());\n\t\titerator itLast(last, typename iterator::FromConst());\n\n\t\t#if EASTL_ASSERT_ENABLED\n\t\t\tif(EASTL_UNLIKELY(!(validate_iterator(itFirst) & isf_valid)))\n\t\t\t\tEASTL_FAIL_MSG(\"deque::erase -- invalid iterator\");\n\t\t\tif(EASTL_UNLIKELY(!(validate_iterator(itLast) & isf_valid)))\n\t\t\t\tEASTL_FAIL_MSG(\"deque::erase -- invalid iterator\");\n\t\t#endif\n\n\t\tif((itFirst != mItBegin) || (itLast != mItEnd)) // If not erasing everything... (We expect that the user won't call erase(begin, end) because instead the user would just call clear.)\n\t\t{\n\t\t\tconst difference_type n(itLast - itFirst);\n\t\t\tconst difference_type i(itFirst - mItBegin);\n\n\t\t\tif(i < (difference_type)((size() - n) / 2)) // Should we move the front entries forward or the back entries backward? We divide the range in half.\n\t\t\t{\n\t\t\t\tconst iterator itNewBegin(mItBegin + n);\n\t\t\t\tvalue_type** const pPtrArrayBegin = mItBegin.mpCurrentArrayPtr;\n\n\t\t\t\titLast.move_backward(mItBegin, itFirst, eastl::is_trivially_copyable());\n\n\t\t\t\tfor(; mItBegin != itNewBegin; ++mItBegin) // Question: If value_type is a POD type, will the compiler generate this loop at all?\n\t\t\t\t\tmItBegin.mpCurrent->~value_type(); // If so, then we need to make a specialization for destructing PODs.\n\n\t\t\t\tDoFreeSubarrays(pPtrArrayBegin, itNewBegin.mpCurrentArrayPtr);\n\n\t\t\t\t// mItBegin = itNewBegin; <-- Not necessary, as the above loop makes it so already.\n\t\t\t}\n\t\t\telse // Else we will be moving back entries backward.\n\t\t\t{\n\t\t\t\titerator itNewEnd(mItEnd - n);\n\t\t\t\tvalue_type** const pPtrArrayEnd = itNewEnd.mpCurrentArrayPtr + 1;\n\n\t\t\t\titFirst.move(itLast, mItEnd, eastl::is_trivially_copyable());\n\n\t\t\t\tfor(iterator itTemp(itNewEnd); itTemp != mItEnd; ++itTemp)\n\t\t\t\t\titTemp.mpCurrent->~value_type();\n\n\t\t\t\tDoFreeSubarrays(pPtrArrayEnd, mItEnd.mpCurrentArrayPtr + 1);\n\n\t\t\t\tmItEnd = itNewEnd;\n\t\t\t}\n\n\t\t\treturn mItBegin + i;\n\t\t}\n\n\t\tclear();\n\t\treturn mItEnd;\n\t}\n\n\n\ttemplate \n\ttypename deque::reverse_iterator\n\tdeque::erase(reverse_iterator position)\n\t{\n\t\treturn reverse_iterator(erase((++position).base()));\n\t}\n\n\n\ttemplate \n\ttypename deque::reverse_iterator\n\tdeque::erase(reverse_iterator first, reverse_iterator last)\n\t{\n\t\t// Version which erases in order from first to last.\n\t\t// difference_type i(first.base() - last.base());\n\t\t// while(i--)\n\t\t// first = erase(first);\n\t\t// return first;\n\n\t\t// Version which erases in order from last to first, but is slightly more efficient:\n\t\treturn reverse_iterator(erase(last.base(), first.base()));\n\t}\n\n\n\ttemplate \n\tvoid deque::clear()\n\t{\n\t\t// Destroy all values and all subarrays they belong to, except for the first one, \n\t\t// as we need to reserve some space for a valid mItBegin/mItEnd.\n\t\tif(mItBegin.mpCurrentArrayPtr != mItEnd.mpCurrentArrayPtr) // If there are multiple subarrays (more often than not, this will be so)...\n\t\t{\n\t\t\tfor(value_type* p1 = mItBegin.mpCurrent; p1 < mItBegin.mpEnd; ++p1)\n\t\t\t\tp1->~value_type();\n\t\t\tfor(value_type* p2 = mItEnd.mpBegin; p2 < mItEnd.mpCurrent; ++p2)\n\t\t\t\tp2->~value_type();\n\t\t\tDoFreeSubarray(mItEnd.mpBegin); // Leave mItBegin with a valid subarray.\n\t\t}\n\t\telse\n\t\t{\n\t\t\tfor(value_type* p = mItBegin.mpCurrent; p < mItEnd.mpCurrent; ++p)\n\t\t\t\tp->~value_type();\n\t\t\t// Don't free the one existing subarray, as we need it for mItBegin/mItEnd.\n\t\t}\n\n\t\tfor(value_type** pPtrArray = mItBegin.mpCurrentArrayPtr + 1; pPtrArray < mItEnd.mpCurrentArrayPtr; ++pPtrArray)\n\t\t{\n\t\t\tfor(value_type* p = *pPtrArray, *pEnd = *pPtrArray + kDequeSubarraySize; p < pEnd; ++p)\n\t\t\t\tp->~value_type();\n\t\t\tDoFreeSubarray(*pPtrArray);\n\t\t}\n\n\t\tmItEnd = mItBegin; // mItBegin/mItEnd will not be dereferencable.\n\t}\n\n\n\t//template \n\t//void deque::reset_lose_memory()\n\t//{\n\t// // The reset_lose_memory function is a special extension function which unilaterally \n\t// // resets the container to an empty state without freeing the memory of \n\t// // the contained objects. This is useful for very quickly tearing down a \n\t// // container built into scratch memory.\n\t//\n\t// // Currently we are unable to get this reset_lose_memory operation to work correctly \n\t// // as we haven't been able to find a good way to have a deque initialize\n\t// // without allocating memory. We can lose the old memory, but DoInit \n\t// // would necessarily do a ptrArray allocation. And this is not within\n\t// // our definition of how reset_lose_memory works.\n\t// base_type::DoInit(0);\n\t//\n\t//}\n\n\n\ttemplate \n\tvoid deque::swap(deque& x)\n\t{\n\t#if defined(EASTL_DEQUE_LEGACY_SWAP_BEHAVIOUR_REQUIRES_COPY_CTOR) && EASTL_DEQUE_LEGACY_SWAP_BEHAVIOUR_REQUIRES_COPY_CTOR\n\t\tif(mAllocator == x.mAllocator) // If allocators are equivalent...\n\t\t\tDoSwap(x);\n\t\telse // else swap the contents.\n\t\t{\n\t\t\tconst this_type temp(*this); // Can't call eastl::swap because that would\n\t\t\t*this = x; // itself call this member swap function.\n\t\t\tx = temp;\n\t\t}\n\t#else\n\t\t// NOTE(rparolin): The previous implementation required T to be copy-constructible in the fall-back case where\n\t\t// allocators with unique instances copied elements. This was an unnecessary restriction and prevented the common\n\t\t// usage of deque with non-copyable types (eg. eastl::deque or eastl::deque). \n\t\t// \n\t\t// The previous implementation violated the following requirements of deque::swap so the fall-back code has\n\t\t// been removed. EASTL implicitly defines 'propagate_on_container_swap = true' therefore the fall-back case is\n\t\t// not required. We simply swap the contents and the allocator as that is the common expectation of\n\t\t// users and does not put the container into an invalid state since it can not free its memory via its current\n\t\t// allocator instance.\n\t\t//\n\t\tDoSwap(x);\n\t#endif\n\t}\n\n\n\ttemplate \n\ttemplate \n\tvoid deque::DoInit(Integer n, Integer value, true_type)\n\t{\n\t\tbase_type::DoInit(n); // Call the base uninitialized init function. \n\t\tDoFillInit(value);\n\t}\n\n\n\ttemplate \n\ttemplate \n\tvoid deque::DoInit(InputIterator first, InputIterator last, false_type)\n\t{\n\t\ttypedef typename eastl::iterator_traits::iterator_category IC;\n\t\tDoInitFromIterator(first, last, IC());\n\t}\n\n\n\ttemplate \n\ttemplate \n\tvoid deque::DoInitFromIterator(InputIterator first, InputIterator last, eastl::input_iterator_tag)\n\t{\n\t\tbase_type::DoInit(0); // Call the base uninitialized init function, but don't actually allocate any values.\n\n\t\t#if EASTL_EXCEPTIONS_ENABLED\n\t\t\ttry\n\t\t\t{\n\t\t#endif\n\t\t\t\t// We have little choice but to iterate through the source iterator and call \n\t\t\t\t// push_back for each item. It can be slow because it will keep reallocating the \n\t\t\t\t// container memory as we go (every kDequeSubarraySize elements). We are not allowed to use distance() on an InputIterator.\n\t\t\t\tfor(; first != last; ++first) // InputIterators by definition actually only allow you to iterate through them once.\n\t\t\t\t{ // Thus the standard *requires* that we do this (inefficient) implementation. \n\t\t\t\t\tpush_back(*first); // Luckily, InputIterators are in practice almost never used, so this code will likely never get executed.\n\t\t\t\t}\n\t\t#if EASTL_EXCEPTIONS_ENABLED\n\t\t\t}\n\t\t\tcatch(...)\n\t\t\t{\n\t\t\t\tclear();\n\t\t\t\tthrow;\n\t\t\t}\n\t\t#endif\n\t}\n\n\n\ttemplate \n\ttemplate \n\tvoid deque::DoInitFromIterator(ForwardIterator first, ForwardIterator last, eastl::forward_iterator_tag)\n\t{\n\t\ttypedef typename eastl::remove_const::type non_const_iterator_type; // If T is a const type (e.g. const int) then we need to initialize it as if it were non-const.\n\t\ttypedef typename eastl::remove_const::type non_const_value_type;\n\n\t\tconst size_type n = (size_type)eastl::distance(first, last);\n\t\tvalue_type** pPtrArrayCurrent;\n\n\t\tbase_type::DoInit(n); // Call the base uninitialized init function.\n\n\t\t#if EASTL_EXCEPTIONS_ENABLED\n\t\t\ttry\n\t\t\t{\n\t\t#endif\n\t\t\t\tfor(pPtrArrayCurrent = mItBegin.mpCurrentArrayPtr; pPtrArrayCurrent < mItEnd.mpCurrentArrayPtr; ++pPtrArrayCurrent) // Copy to the known-to-be-completely-used subarrays.\n\t\t\t\t{\n\t\t\t\t\t// We implment an algorithm here whereby we use uninitialized_copy() and advance() instead of just iterating from first to last and constructing as we go.\n\t\t\t\t\t// The reason for this is that we can take advantage of trivially copyable data types and implement construction as memcpy operations.\n\t\t\t\t\tForwardIterator current(first); // To do: Implement a specialization of this algorithm for non-trivially copyable types which eliminates the need for 'current'.\n\n\t\t\t\t\teastl::advance(current, kDequeSubarraySize);\n\t\t\t\t\teastl::uninitialized_copy((non_const_iterator_type)first, (non_const_iterator_type)current, (non_const_value_type*)*pPtrArrayCurrent);\n\t\t\t\t\tfirst = current;\n\t\t\t\t}\n\n\t\t\t\teastl::uninitialized_copy((non_const_iterator_type)first, (non_const_iterator_type)last, (non_const_value_type*)mItEnd.mpBegin);\n\t\t#if EASTL_EXCEPTIONS_ENABLED\n\t\t\t}\n\t\t\tcatch(...)\n\t\t\t{\n\t\t\t\tfor(iterator itCurrent(mItBegin), itEnd(pPtrArrayCurrent, *pPtrArrayCurrent); itCurrent != itEnd; ++itCurrent)\n\t\t\t\t\titCurrent.mpCurrent->~value_type();\n\t\t\t\tthrow;\n\t\t\t}\n\t\t#endif\n\t}\n\n\n\ttemplate \n\tvoid deque::DoFillInit(const value_type& value)\n\t{\n\t\tvalue_type** pPtrArrayCurrent = mItBegin.mpCurrentArrayPtr;\n\n\t\t#if EASTL_EXCEPTIONS_ENABLED\n\t\t\ttry\n\t\t\t{\n\t\t#endif\n\t\t\t\twhile(pPtrArrayCurrent < mItEnd.mpCurrentArrayPtr)\n\t\t\t\t{\n\t\t\t\t\teastl::uninitialized_fill(*pPtrArrayCurrent, *pPtrArrayCurrent + kDequeSubarraySize, value);\n\t\t\t\t\t++pPtrArrayCurrent;\n\t\t\t\t}\n\t\t\t\teastl::uninitialized_fill(mItEnd.mpBegin, mItEnd.mpCurrent, value);\n\t\t#if EASTL_EXCEPTIONS_ENABLED\n\t\t\t}\n\t\t\tcatch(...)\n\t\t\t{\n\t\t\t\tfor(iterator itCurrent(mItBegin), itEnd(pPtrArrayCurrent, *pPtrArrayCurrent); itCurrent != itEnd; ++itCurrent)\n\t\t\t\t\titCurrent.mpCurrent->~value_type();\n\t\t\t\tthrow;\n\t\t\t}\n\t\t#endif\n\t}\n\n\n\ttemplate \n\ttemplate \n\tvoid deque::DoAssign(Integer n, Integer value, true_type) // false_type means this is the integer version instead of iterator version.\n\t{\n\t\tDoAssignValues(static_cast(n), static_cast(value));\n\t}\n\n\n\ttemplate \n\ttemplate \n\tvoid deque::DoAssign(InputIterator first, InputIterator last, false_type) // false_type means this is the iterator version instead of integer version.\n\t{\n\t\t// Actually, the implementation below requires first/last to be a ForwardIterator and not just an InputIterator.\n\t\t// But Paul Pedriana if you somehow need to work with an InputIterator and we can deal with it.\n\t\tconst size_type n = (size_type)eastl::distance(first, last);\n\t\tconst size_type nSize = size();\n\n\t\tif(n > nSize) // If we are increasing the size...\n\t\t{\n\t\t\tInputIterator atEnd(first);\n\n\t\t\teastl::advance(atEnd, (difference_type)nSize);\n\t\t\teastl::copy(first, atEnd, mItBegin);\n\t\t\tinsert(mItEnd, atEnd, last);\n\t\t}\n\t\telse // n is <= size.\n\t\t{\n\t\t\titerator itEnd(eastl::copy(first, last, mItBegin));\n\n\t\t\tif(n < nSize) // If we need to erase any trailing elements...\n\t\t\t\terase(itEnd, mItEnd);\n\t\t}\n\t}\n\n\n\ttemplate \n\tvoid deque::DoAssignValues(size_type n, const value_type& value)\n\t{\n\t\tconst size_type nSize = size();\n\n\t\tif(n > nSize) // If we are increasing the size...\n\t\t{\n\t\t\teastl::fill(mItBegin, mItEnd, value);\n\t\t\tinsert(mItEnd, n - nSize, value);\n\t\t}\n\t\telse\n\t\t{\n\t\t\terase(mItBegin + (difference_type)n, mItEnd);\n\t\t\teastl::fill(mItBegin, mItEnd, value);\n\t\t}\n\t}\n\n\n\ttemplate \n\ttemplate \n\ttypename deque::iterator\n\tdeque::DoInsert(const const_iterator& position, Integer n, Integer value, true_type)\n\t{\n\t\treturn DoInsertValues(position, (size_type)n, (value_type)value);\n\t}\n\n\n\ttemplate \n\ttemplate \n\ttypename deque::iterator\n\tdeque::DoInsert(const const_iterator& position, const InputIterator& first, const InputIterator& last, false_type)\n\t{\n\t\ttypedef typename eastl::iterator_traits::iterator_category IC;\n\t\treturn DoInsertFromIterator(position, first, last, IC());\n\t}\n\n\ttemplate \n\ttemplate \n\ttypename deque::iterator\n\tdeque::DoInsertFromIterator(const_iterator position, const InputIterator& first, const InputIterator& last, eastl::input_iterator_tag)\n\t{\n\t\tconst difference_type index = eastl::distance(cbegin(), position);\n#if EASTL_EXCEPTIONS_ENABLED\n\t\ttry\n\t\t{\n#endif\n\t\t\t// We have little choice but to iterate through the source iterator and call\n\t\t\t// insert for each item. It can be slow because it will keep reallocating the\n\t\t\t// container memory as we go (every kDequeSubarraySize elements). We are not\n\t\t\t// allowed to use distance() on an InputIterator. InputIterators by definition\n\t\t\t// actually only allow you to iterate through them once. Thus the standard\n\t\t\t// *requires* that we do this (inefficient) implementation. Luckily,\n\t\t\t// InputIterators are in practice almost never used, so this code will likely\n\t\t\t// never get executed.\n\t\t\tfor (InputIterator iter = first; iter != last; ++iter)\n\t\t\t{\n\t\t\t\tposition = insert(position, *iter) + 1;\n\t\t\t}\n#if EASTL_EXCEPTIONS_ENABLED\n\t\t}\n\t\tcatch (...)\n\t\t{\n\t\t\terase(cbegin() + index, position);\n\t\t\tthrow;\n\t\t}\n#endif\n\n\t\treturn begin() + index;\n\t}\n\n\ttemplate \n\ttemplate \n\ttypename deque::iterator\n\tdeque::DoInsertFromIterator(const_iterator position, const ForwardIterator& first, const ForwardIterator& last, eastl::forward_iterator_tag)\n\t{\n\t\tconst size_type n = (size_type)eastl::distance(first, last);\n\n\t\t// This implementation is nearly identical to DoInsertValues below. \n\t\t// If you make a bug fix to one, you will likely want to fix the other.\n\t\tif(position.mpCurrent == mItBegin.mpCurrent) // If inserting at the beginning or into an empty container...\n\t\t{\n\t\t\titerator itNewBegin(DoReallocSubarray(n, kSideFront)); // itNewBegin to mItBegin refers to memory that isn't initialized yet; so it's not truly a valid iterator. Or at least not a dereferencable one.\n\n\t\t\t#if EASTL_EXCEPTIONS_ENABLED\n\t\t\t\ttry\n\t\t\t\t{\n\t\t\t#endif\n\t\t\t\t\t// We would like to use move here instead of copy when possible, which would be useful for \n\t\t\t\t\t// when inserting from a std::initializer_list, for example.\n\t\t\t\t\t// To do: solve this by having a template or runtime parameter which specifies move vs copy.\n\t\t\t\t\teastl::uninitialized_copy(first, last, itNewBegin);\n\t\t\t\t\tmItBegin = itNewBegin;\n\t\t\t#if EASTL_EXCEPTIONS_ENABLED\n\t\t\t\t}\n\t\t\t\tcatch(...)\n\t\t\t\t{\n\t\t\t\t\tDoFreeSubarrays(itNewBegin.mpCurrentArrayPtr, mItBegin.mpCurrentArrayPtr);\n\t\t\t\t\tthrow;\n\t\t\t\t}\n\t\t\t#endif\n\n\t\t\treturn mItBegin;\n\t\t}\n\t\telse if(EASTL_UNLIKELY(position.mpCurrent == mItEnd.mpCurrent)) // If inserting at the end (i.e. appending)...\n\t\t{\n\t\t\tconst iterator itNewEnd(DoReallocSubarray(n, kSideBack)); // mItEnd to itNewEnd refers to memory that isn't initialized yet; so it's not truly a valid iterator. Or at least not a dereferencable one.\n\t\t\tconst iterator itFirstInserted(mItEnd);\n\n\t\t\t#if EASTL_EXCEPTIONS_ENABLED\n\t\t\t\ttry\n\t\t\t\t{\n\t\t\t#endif\n\t\t\t\t\t// We would like to use move here instead of copy when possible, which would be useful for \n\t\t\t\t\t// when inserting from a std::initializer_list, for example.\n\t\t\t\t\t// To do: solve this by having a template or runtime parameter which specifies move vs copy.\n\t\t\t\t\teastl::uninitialized_copy(first, last, mItEnd);\n\t\t\t\t\tmItEnd = itNewEnd;\n\t\t\t#if EASTL_EXCEPTIONS_ENABLED\n\t\t\t\t}\n\t\t\t\tcatch(...)\n\t\t\t\t{\n\t\t\t\t\tDoFreeSubarrays(mItEnd.mpCurrentArrayPtr + 1, itNewEnd.mpCurrentArrayPtr + 1);\n\t\t\t\t\tthrow;\n\t\t\t\t}\n\t\t\t#endif\n\n\t\t\treturn itFirstInserted;\n\t\t}\n\t\telse\n\t\t{\n\t\t\tconst difference_type nInsertionIndex = position - mItBegin;\n\t\t\tconst size_type nSize = size();\n\n\t\t\tif(nInsertionIndex < (difference_type)(nSize / 2)) // If the insertion index is in the front half of the deque... grow the deque at the front.\n\t\t\t{\n\t\t\t\tconst iterator itNewBegin(DoReallocSubarray(n, kSideFront)); // itNewBegin to mItBegin refers to memory that isn't initialized yet; so it's not truly a valid iterator. Or at least not a dereferencable one.\n\t\t\t\tconst iterator itOldBegin(mItBegin);\n\t\t\t\tconst iterator itPosition(mItBegin + nInsertionIndex); // We need to reset this value because the reallocation above can invalidate iterators.\n\n\t\t\t\t#if EASTL_EXCEPTIONS_ENABLED\n\t\t\t\t\ttry\n\t\t\t\t\t{\n\t\t\t\t#endif\n\t\t\t\t\t\t// We have a problem here: we would like to use move instead of copy, but it may be that the range to be inserted comes from\n\t\t\t\t\t\t// this container and comes from the segment we need to move. So we can't use move operations unless we are careful to handle\n\t\t\t\t\t\t// that situation. The newly inserted contents must be contents that were moved to and not moved from. To do: solve this.\n\t\t\t\t\t\tif(nInsertionIndex >= (difference_type)n) // If the newly inserted items will be entirely within the old area...\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\titerator itUCopyEnd(mItBegin + (difference_type)n);\n\n\t\t\t\t\t\t\teastl::uninitialized_copy(mItBegin, itUCopyEnd, itNewBegin); // This can throw.\n\t\t\t\t\t\t\titUCopyEnd = eastl::copy(itUCopyEnd, itPosition, itOldBegin); // Recycle 'itUCopyEnd' to mean something else.\n\t\t\t\t\t\t\teastl::copy(first, last, itUCopyEnd);\n\t\t\t\t\t\t}\n\t\t\t\t\t\telse // Else the newly inserted items are going within the newly allocated area at the front.\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\tForwardIterator mid(first);\n\n\t\t\t\t\t\t\teastl::advance(mid, (difference_type)n - nInsertionIndex);\n\t\t\t\t\t\t\teastl::uninitialized_copy_copy(mItBegin, itPosition, first, mid, itNewBegin); // This can throw.\n\t\t\t\t\t\t\teastl::copy(mid, last, itOldBegin);\n\t\t\t\t\t\t}\n\t\t\t\t\t\tmItBegin = itNewBegin;\n\t\t\t\t#if EASTL_EXCEPTIONS_ENABLED\n\t\t\t\t\t}\n\t\t\t\t\tcatch(...)\n\t\t\t\t\t{\n\t\t\t\t\t\tDoFreeSubarrays(itNewBegin.mpCurrentArrayPtr, mItBegin.mpCurrentArrayPtr);\n\t\t\t\t\t\tthrow;\n\t\t\t\t\t}\n\t\t\t\t#endif\n\t\t\t}\n\t\t\telse\n\t\t\t{\n\t\t\t\tconst iterator itNewEnd(DoReallocSubarray(n, kSideBack));\n\t\t\t\tconst iterator itOldEnd(mItEnd);\n\t\t\t\tconst difference_type nPushedCount = (difference_type)nSize - nInsertionIndex;\n\t\t\t\tconst iterator itPosition(mItEnd - nPushedCount); // We need to reset this value because the reallocation above can invalidate iterators.\n\n\t\t\t\t#if EASTL_EXCEPTIONS_ENABLED\n\t\t\t\t\ttry\n\t\t\t\t\t{\n\t\t\t\t#endif\n\t\t\t\t\t\t// We have a problem here: we would like to use move instead of copy, but it may be that the range to be inserted comes from\n\t\t\t\t\t\t// this container and comes from the segment we need to move. So we can't use move operations unless we are careful to handle\n\t\t\t\t\t\t// that situation. The newly inserted contents must be contents that were moved to and not moved from. To do: solve this.\n\t\t\t\t\t\tif(nPushedCount > (difference_type)n)\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\tconst iterator itUCopyEnd(mItEnd - (difference_type)n);\n\n\t\t\t\t\t\t\teastl::uninitialized_copy(itUCopyEnd, mItEnd, mItEnd);\n\t\t\t\t\t\t\teastl::copy_backward(itPosition, itUCopyEnd, itOldEnd);\n\t\t\t\t\t\t\teastl::copy(first, last, itPosition);\n\t\t\t\t\t\t}\n\t\t\t\t\t\telse\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\tForwardIterator mid(first);\n\n\t\t\t\t\t\t\teastl::advance(mid, nPushedCount);\n\t\t\t\t\t\t\teastl::uninitialized_copy_copy(mid, last, itPosition, mItEnd, mItEnd);\n\t\t\t\t\t\t\teastl::copy(first, mid, itPosition);\n\t\t\t\t\t\t}\n\t\t\t\t\t\tmItEnd = itNewEnd;\n\t\t\t\t#if EASTL_EXCEPTIONS_ENABLED\n\t\t\t\t\t}\n\t\t\t\t\tcatch(...)\n\t\t\t\t\t{\n\t\t\t\t\t\tDoFreeSubarrays(mItEnd.mpCurrentArrayPtr + 1, itNewEnd.mpCurrentArrayPtr + 1);\n\t\t\t\t\t\tthrow;\n\t\t\t\t\t}\n\t\t\t\t#endif\n\t\t\t}\n\n\t\t\treturn iterator(mItBegin + nInsertionIndex);\n\t\t}\n\t}\n\n\n\ttemplate \n\ttypename deque::iterator\n\tdeque::DoInsertValues(const_iterator position, size_type n, const value_type& value)\n\t{\n\t\t#if EASTL_ASSERT_ENABLED\n\t\t\tif(EASTL_UNLIKELY(!(validate_iterator(position) & isf_valid)))\n\t\t\t\tEASTL_FAIL_MSG(\"deque::insert -- invalid iterator\");\n\t\t#endif\n\n\t\t// This implementation is nearly identical to DoInsertFromIterator above. \n\t\t// If you make a bug fix to one, you will likely want to fix the other.\n\t\tif(position.mpCurrent == mItBegin.mpCurrent) // If inserting at the beginning...\n\t\t{\n\t\t\tconst iterator itNewBegin(DoReallocSubarray(n, kSideFront));\n\n\t\t\t#if EASTL_EXCEPTIONS_ENABLED\n\t\t\t\ttry\n\t\t\t\t{\n\t\t\t#endif\n\t\t\t\t\t// Note that we don't make a temp copy of 'value' here. This is because in a \n\t\t\t\t\t// deque, insertion at either the front or back doesn't cause a reallocation\n\t\t\t\t\t// or move of data in the middle. That's a key feature of deques, in fact.\n\t\t\t\t\teastl::uninitialized_fill(itNewBegin, mItBegin, value);\n\t\t\t\t\tmItBegin = itNewBegin;\n\t\t\t#if EASTL_EXCEPTIONS_ENABLED\n\t\t\t\t}\n\t\t\t\tcatch(...)\n\t\t\t\t{\n\t\t\t\t\tDoFreeSubarrays(itNewBegin.mpCurrentArrayPtr, mItBegin.mpCurrentArrayPtr);\n\t\t\t\t\tthrow;\n\t\t\t\t}\n\t\t\t#endif\n\n\t\t\treturn mItBegin;\n\t\t}\n\t\telse if(EASTL_UNLIKELY(position.mpCurrent == mItEnd.mpCurrent)) // If inserting at the end (i.e. appending)...\n\t\t{\n\t\t\tconst iterator itNewEnd(DoReallocSubarray(n, kSideBack));\n\t\t\tconst iterator itFirstInserted(mItEnd);\n\n\t\t\t#if EASTL_EXCEPTIONS_ENABLED\n\t\t\t\ttry\n\t\t\t\t{\n\t\t\t#endif\n\t\t\t\t\t// Note that we don't make a temp copy of 'value' here. This is because in a \n\t\t\t\t\t// deque, insertion at either the front or back doesn't cause a reallocation\n\t\t\t\t\t// or move of data in the middle. That's a key feature of deques, in fact.\n\t\t\t\t\teastl::uninitialized_fill(mItEnd, itNewEnd, value);\n\t\t\t\t\tmItEnd = itNewEnd;\n\t\t\t#if EASTL_EXCEPTIONS_ENABLED\n\t\t\t\t}\n\t\t\t\tcatch(...)\n\t\t\t\t{\n\t\t\t\t\tDoFreeSubarrays(mItEnd.mpCurrentArrayPtr + 1, itNewEnd.mpCurrentArrayPtr + 1);\n\t\t\t\t\tthrow;\n\t\t\t\t}\n\t\t\t#endif\n\n\t\t\treturn itFirstInserted;\n\t\t}\n\t\telse\n\t\t{\n\t\t\t// A key purpose of a deque is to implement insertions and removals more efficiently \n\t\t\t// than with a vector. We are inserting into the middle of the deque here. A quick and \n\t\t\t// dirty implementation of this would be to reallocate the subarrays and simply push \n\t\t\t// all values in the middle upward like you would do with a vector. Instead we implement\n\t\t\t// the minimum amount of reallocations needed but may need to do some value moving, \n\t\t\t// as the subarray sizes need to remain constant and can have no holes in them.\n\t\t\tconst difference_type nInsertionIndex = position - mItBegin;\n\t\t\tconst size_type nSize = size();\n\t\t\tconst value_type valueSaved(value);\n\n\t\t\tif(nInsertionIndex < (difference_type)(nSize / 2)) // If the insertion index is in the front half of the deque... grow the deque at the front.\n\t\t\t{\n\t\t\t\tconst iterator itNewBegin(DoReallocSubarray(n, kSideFront));\n\t\t\t\tconst iterator itOldBegin(mItBegin);\n\t\t\t\tconst iterator itPosition(mItBegin + nInsertionIndex); // We need to reset this value because the reallocation above can invalidate iterators.\n\n\t\t\t\t#if EASTL_EXCEPTIONS_ENABLED\n\t\t\t\t\ttry\n\t\t\t\t\t{\n\t\t\t\t#endif\n\t\t\t\t\t\tif(nInsertionIndex >= (difference_type)n) // If the newly inserted items will be entirely within the old area...\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\titerator itUCopyEnd(mItBegin + (difference_type)n);\n\n\t\t\t\t\t\t\teastl::uninitialized_move_if_noexcept(mItBegin, itUCopyEnd, itNewBegin); // This can throw.\n\t\t\t\t\t\t\titUCopyEnd = eastl::move(itUCopyEnd, itPosition, itOldBegin); // Recycle 'itUCopyEnd' to mean something else.\n\t\t\t\t\t\t\teastl::fill(itUCopyEnd, itPosition, valueSaved);\n\t\t\t\t\t\t}\n\t\t\t\t\t\telse // Else the newly inserted items are going within the newly allocated area at the front.\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\teastl::uninitialized_move_fill(mItBegin, itPosition, itNewBegin, mItBegin, valueSaved); // This can throw.\n\t\t\t\t\t\t\teastl::fill(itOldBegin, itPosition, valueSaved);\n\t\t\t\t\t\t}\n\t\t\t\t\t\tmItBegin = itNewBegin;\n\t\t\t\t#if EASTL_EXCEPTIONS_ENABLED\n\t\t\t\t\t}\n\t\t\t\t\tcatch(...)\n\t\t\t\t\t{\n\t\t\t\t\t\tDoFreeSubarrays(itNewBegin.mpCurrentArrayPtr, mItBegin.mpCurrentArrayPtr);\n\t\t\t\t\t\tthrow;\n\t\t\t\t\t}\n\t\t\t\t#endif\n\n\t\t\t\treturn iterator(mItBegin + nInsertionIndex);\n\t\t\t}\n\t\t\telse // Else the insertion index is in the back half of the deque, so grow the deque at the back.\n\t\t\t{\n\t\t\t\tconst iterator itNewEnd(DoReallocSubarray(n, kSideBack));\n\t\t\t\tconst iterator itOldEnd(mItEnd);\n\t\t\t\tconst difference_type nPushedCount = (difference_type)nSize - nInsertionIndex;\n\t\t\t\tconst iterator itPosition(mItEnd - nPushedCount); // We need to reset this value because the reallocation above can invalidate iterators.\n\n\t\t\t\t#if EASTL_EXCEPTIONS_ENABLED\n\t\t\t\t\ttry\n\t\t\t\t\t{\n\t\t\t\t#endif\n\t\t\t\t\t\tif(nPushedCount > (difference_type)n) // If the newly inserted items will be entirely within the old area...\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\titerator itUCopyEnd(mItEnd - (difference_type)n);\n\n\t\t\t\t\t\t\teastl::uninitialized_move_if_noexcept(itUCopyEnd, mItEnd, mItEnd); // This can throw.\n\t\t\t\t\t\t\titUCopyEnd = eastl::move_backward(itPosition, itUCopyEnd, itOldEnd); // Recycle 'itUCopyEnd' to mean something else.\n\t\t\t\t\t\t\teastl::fill(itPosition, itUCopyEnd, valueSaved);\n\t\t\t\t\t\t}\n\t\t\t\t\t\telse // Else the newly inserted items are going within the newly allocated area at the back.\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\teastl::uninitialized_fill_move(mItEnd, itPosition + (difference_type)n, valueSaved, itPosition, mItEnd); // This can throw.\n\t\t\t\t\t\t\teastl::fill(itPosition, itOldEnd, valueSaved);\n\t\t\t\t\t\t}\n\t\t\t\t\t\tmItEnd = itNewEnd;\n\t\t\t\t#if EASTL_EXCEPTIONS_ENABLED\n\t\t\t\t\t}\n\t\t\t\t\tcatch(...)\n\t\t\t\t\t{\n\t\t\t\t\t\tDoFreeSubarrays(mItEnd.mpCurrentArrayPtr + 1, itNewEnd.mpCurrentArrayPtr + 1);\n\t\t\t\t\t\tthrow;\n\t\t\t\t\t}\n\t\t\t\t#endif\n\n\t\t\t\treturn iterator(mItBegin + nInsertionIndex);\n\t\t\t}\n\t\t}\n\t}\n\n\n\ttemplate \n\tinline void deque::DoSwap(this_type& x)\n\t{\n\t\teastl::swap(mpPtrArray, x.mpPtrArray);\n\t\teastl::swap(mnPtrArraySize, x.mnPtrArraySize);\n\t\teastl::swap(mItBegin, x.mItBegin);\n\t\teastl::swap(mItEnd, x.mItEnd);\n\t\teastl::swap(mAllocator, x.mAllocator); // We do this even if EASTL_ALLOCATOR_COPY_ENABLED is 0.\n\n\t}\n\n\n\ttemplate \n\tinline bool deque::validate() const\n\t{\n\t\t// To do: More detailed validation.\n\t\t// To do: Try to make the validation resistant to crashes if the data is invalid.\n\t\tif((end() - begin()) < 0)\n\t\t\treturn false;\n\t\treturn true;\n\t}\n\n\n\ttemplate \n\tinline int deque::validate_iterator(const_iterator i) const\n\t{\n\t\t// To do: We don't currently track isf_current, will need to make it do so.\n\t\t// To do: Fix the validation below, as it will not catch all invalid iterators.\n\t\tif((i - begin()) < 0)\n\t\t\treturn isf_none;\n\n\t\tif((end() - i) < 0)\n\t\t\treturn isf_none;\n\n\t\tif(i == end())\n\t\t\treturn (isf_valid | isf_current);\n\n\t\treturn (isf_valid | isf_current | isf_can_dereference);\n\t}\n\n\n\n\t///////////////////////////////////////////////////////////////////////\n\t// global operators\n\t///////////////////////////////////////////////////////////////////////\n\n\ttemplate \n\tinline bool operator==(const deque& a, const deque& b)\n\t{\n\t\treturn ((a.size() == b.size()) && eastl::equal(a.begin(), a.end(), b.begin()));\n\t}\n\n#if defined(EA_COMPILER_HAS_THREE_WAY_COMPARISON)\n\ttemplate \n\tinline synth_three_way_result operator<=>(const deque& a, const deque& b)\n\t{\n\t return eastl::lexicographical_compare_three_way(a.begin(), a.end(), b.begin(), b.end(), synth_three_way{});\n\t}\n\n#else\n\ttemplate \n\tinline bool operator!=(const deque& a, const deque& b)\n\t{\n\t\treturn ((a.size() != b.size()) || !eastl::equal(a.begin(), a.end(), b.begin()));\n\t}\n\n\ttemplate \n\tinline bool operator<(const deque& a, const deque& b)\n\t{\n\t\treturn eastl::lexicographical_compare(a.begin(), a.end(), b.begin(), b.end());\n\t}\n\n\ttemplate \n\tinline bool operator>(const deque& a, const deque& b)\n\t{\n\t\treturn b < a;\n\t}\n\n\ttemplate \n\tinline bool operator<=(const deque& a, const deque& b)\n\t{\n\t\treturn !(b < a);\n\t}\n\n\ttemplate \n\tinline bool operator>=(const deque& a, const deque& b)\n\t{\n\t\treturn !(a < b);\n\t}\n#endif\n\n\ttemplate \n\tinline void swap(deque& a, deque& b)\n\t{\n\t\ta.swap(b);\n\t}\n\n\t///////////////////////////////////////////////////////////////////////\n\t// erase / erase_if\n\t//\n\t// https://en.cppreference.com/w/cpp/container/deque/erase2\n\t///////////////////////////////////////////////////////////////////////\n\ttemplate \n\ttypename deque::size_type erase(deque& c, const U& value)\n\t{\n\t\t// Erases all elements that compare equal to value from the container. \n\t\tauto origEnd = c.end();\n\t\tauto newEnd = eastl::remove(c.begin(), origEnd, value);\n\t\tauto numRemoved = eastl::distance(newEnd, origEnd);\n\t\tc.erase(newEnd, origEnd);\n\n\t\t// Note: This is technically a lossy conversion when size_type\n\t\t// is 32bits and ptrdiff_t is 64bits (could happen on 64bit\n\t\t// systems when EASTL_SIZE_T_32BIT is set). In practice this\n\t\t// is fine because if EASTL_SIZE_T_32BIT is set then the deque\n\t\t// should not have more elements than fit in a uint32_t and so\n\t\t// the distance here should fit in a size_type.\n\t\treturn static_cast::size_type>(numRemoved);\n\t}\n\n\ttemplate \n\ttypename deque::size_type erase_if(deque& c, Predicate predicate)\n\t{\n\t\t// Erases all elements that satisfy the predicate pred from the container. \n\t\tauto origEnd = c.end();\n\t\tauto newEnd = eastl::remove_if(c.begin(), origEnd, predicate);\n\t\tauto numRemoved = eastl::distance(newEnd, origEnd);\n\t\tc.erase(newEnd, origEnd);\n\n\t\t// Note: This is technically a lossy conversion when size_type\n\t\t// is 32bits and ptrdiff_t is 64bits (could happen on 64bit\n\t\t// systems when EASTL_SIZE_T_32BIT is set). In practice this\n\t\t// is fine because if EASTL_SIZE_T_32BIT is set then the deque\n\t\t// should not have more elements than fit in a uint32_t and so\n\t\t// the distance here should fit in a size_type.\n\t\treturn static_cast::size_type>(numRemoved);\n\t}\n\n\n\t///////////////////////////////////////////////////////////////////////\n\t// erase_unsorted\n\t//\n\t// This serves a similar purpose as erase above but with the difference\n\t// that it doesn't preserve the relative order of what is left in the\n\t// deque.\n\t//\n\t// Effects: Removes all elements equal to value from the deque while\n\t// optimizing for speed with the potential reordering of elements as a\n\t// side effect.\n\t//\n\t// Complexity: Linear\n\t//\n\t///////////////////////////////////////////////////////////////////////\n\ttemplate \n\ttypename deque::size_type erase_unsorted(deque& c, const U& value)\n\t{\n\t\tauto itRemove = c.begin();\n\t\tauto ritMove = c.rbegin();\n\n\t\twhile(true)\n\t\t{\n\t\t\titRemove = eastl::find(itRemove, ritMove.base(), value);\n\t\t\tif (itRemove == ritMove.base()) // any elements to remove?\n\t\t\t\tbreak;\n\n\t\t\tritMove = eastl::find_if(ritMove, eastl::make_reverse_iterator(itRemove), [&value](const T& elem) { return elem != value; });\n\t\t\tif (itRemove == ritMove.base()) // any elements that can be moved into place?\n\t\t\t\tbreak;\n\n\t\t\t*itRemove = eastl::move(*ritMove);\n\t\t\t++itRemove;\n\t\t\t++ritMove;\n\t\t}\n\n\t\t// now all elements in the range [itRemove, c.end()) are either to be removed or have already been moved from.\n\n\t\tauto origEnd = end(c);\n\t\tauto numRemoved = distance(itRemove, origEnd);\n\t\tc.erase(itRemove, origEnd);\n\n\t\t// Note: This is technically a lossy conversion when size_type\n\t\t// is 32bits and ptrdiff_t is 64bits (could happen on 64bit\n\t\t// systems when EASTL_SIZE_T_32BIT is set). In practice this\n\t\t// is fine because if EASTL_SIZE_T_32BIT is set then the deque\n\t\t// should not have more elements than fit in a uint32_t and so\n\t\t// the distance here should fit in a size_type.\n\t\treturn static_cast::size_type>(numRemoved);\n\t}\n\n\t///////////////////////////////////////////////////////////////////////\n\t// erase_unsorted_if\n\t//\n\t// This serves a similar purpose as erase_if above but with the\n\t// difference that it doesn't preserve the relative order of what is\n\t// left in the deque.\n\t//\n\t// Effects: Removes all elements that return true for the predicate\n\t// while optimizing for speed with the potential reordering of elements\n\t// as a side effect.\n\t//\n\t// Complexity: Linear\n\t//\n\t///////////////////////////////////////////////////////////////////////\n\ttemplate \n\ttypename deque::size_type erase_unsorted_if(deque& c, Predicate predicate)\n\t{\n\t\t// Erases all elements that satisfy predicate from the container. \n\t\tauto itRemove = c.begin();\n\t\tauto ritMove = c.rbegin();\n\n\t\twhile(true)\n\t\t{\n\t\t\titRemove = eastl::find_if(itRemove, ritMove.base(), predicate);\n\t\t\tif (itRemove == ritMove.base()) // any elements to remove?\n\t\t\t\tbreak;\n\n\t\t\tritMove = eastl::find_if(ritMove, eastl::make_reverse_iterator(itRemove), not_fn(predicate));\n\t\t\tif (itRemove == ritMove.base()) // any elements that can be moved into place?\n\t\t\t\tbreak;\n\n\t\t\t*itRemove = eastl::move(*ritMove);\n\t\t\t++itRemove;\n\t\t\t++ritMove;\n\t\t}\n\n\t\t// now all elements in the range [itRemove, c.end()) are either to be removed or have already been moved from.\n\n\t\tauto origEnd = end(c);\n\t\tauto numRemoved = distance(itRemove, origEnd);\n\t\tc.erase(itRemove, origEnd);\n\n\t\t// Note: This is technically a lossy conversion when size_type\n\t\t// is 32bits and ptrdiff_t is 64bits (could happen on 64bit\n\t\t// systems when EASTL_SIZE_T_32BIT is set). In practice this\n\t\t// is fine because if EASTL_SIZE_T_32BIT is set then the deque\n\t\t// should not have more elements than fit in a uint32_t and so\n\t\t// the distance here should fit in a size_type.\n\t\treturn static_cast::size_type>(numRemoved);\n\t}\n\n} // namespace eastl\n\n\nEA_RESTORE_VC_WARNING();\n#if EASTL_EXCEPTIONS_ENABLED\n\tEA_RESTORE_VC_WARNING();\n#endif\n\n\n#endif // Header include guard\n" }, { "path": "include/EASTL/expected.h", "content": "///////////////////////////////////////////////////////////////////////////////\n// Copyright (c) Electronic Arts Inc. All rights reserved.\n///////////////////////////////////////////////////////////////////////////////\n#pragma once\n\n// We use a few c++17 features in the implementation of eastl::expceted, so we only provide\n// it from c++17 onwards.\n#if EA_COMPILER_CPP17_ENABLED\n\n#include \n\nEA_DISABLE_VC_WARNING(4623) // warning C4623: default constructor was implicitly defined as deleted\nEA_DISABLE_VC_WARNING(4625) // warning C4625: copy constructor was implicitly defined as deleted\nEA_DISABLE_VC_WARNING(4510) // warning C4510: default constructor could not be generated\n\n#include \n#include \n#include \n#include \n#include \n\n#include // for std::initializer_list\n\n#if EASTL_EXCEPTIONS_ENABLED\n#include // for std::exception in bad_exception_access.\n#endif\n\nnamespace eastl\n{\n\ttemplate \n\tclass expected;\n\n\ttemplate \n\tclass unexpected;\n\n\t// Some helper type traits:\n\tnamespace internal\n\t{\n\t\t// TODO: move this somewhere else? It doesn't handle\n\t\t// templates with non-type template parameters so it isn't\n\t\t// really generic...\n\t\ttemplate class Template>\n\t\tstruct is_specialization : eastl::false_type\n\t\t{\n\t\t};\n\n\t\ttemplate