pax_global_header00006660000000000000000000000064132421203110014477gustar00rootroot0000000000000052 comment=76f5af48c2d6c57f9cbab94eca57ed683b50d38d range-v3-0.3.5/000077500000000000000000000000001324212031100131265ustar00rootroot00000000000000range-v3-0.3.5/.buckconfig000066400000000000000000000000001324212031100152270ustar00rootroot00000000000000range-v3-0.3.5/.gitattributes000066400000000000000000000002741324212031100160240ustar00rootroot00000000000000*.hpp text *.cpp text *.txt text *.html text *.md text *.yml text *.xml text *.in text .gitattributes text .gitignore text *.cmd -text *.sln -text *.vcxproj -text *.vcxproj.filters -text range-v3-0.3.5/.gitignore000066400000000000000000000076321324212031100151260ustar00rootroot00000000000000## Copyright (c) 2013 GitHub, Inc. ## ## Permission is hereby granted, free of charge, to any person obtaining a ## copy of this software and associated documentation files (the "Software"), ## to deal in the Software without restriction, including without limitation ## the rights to use, copy, modify, merge, publish, distribute, sublicense, ## and/or sell copies of the Software, and to permit persons to whom the ## Software is furnished to do so, subject to the following conditions: ## ## The above copyright notice and this permission notice shall be included in ## all copies or substantial portions of the Software. ## ## THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR ## IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, ## FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE ## AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER ## LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING ## FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER ## DEALINGS IN THE SOFTWARE. # Compiled Object files *.slo *.lo *.o *.obj # Compiled Dynamic libraries *.so *.dylib *.dll # Compiled Static libraries *.lai *.la *.a *.lib # Executables *.exe *.out *.app ## Ignore Visual Studio temporary files, build results, and ## files generated by popular Visual Studio add-ons. # User-specific files *.suo *.user *.sln.docstates # Build results [Dd]ebug/ [Dd]ebugPublic/ [Rr]elease/ x64/ build*/ bld/ [Bb]in/ [Oo]bj/ bazel-* # Enable "build/" folder in the NuGet Packages folder since NuGet packages use it for MSBuild targets !packages/*/build/ # MSTest test Results [Tt]est[Rr]esult*/ [Bb]uild[Ll]og.* #NUNIT *.VisualState.xml TestResult.xml *_i.c *_p.c *_i.h *.ilk *.meta *.obj *.pch *.pdb *.pgc *.pgd *.rsp *.sbr *.tlb *.tli *.tlh *.tmp *.tmp_proj *.log *.vspscc *.vssscc .builds *.pidb *.svclog *.scc # Visual C++ cache files ipch/ *.aps *.ncb *.opensdf *.sdf *.cachefile # Visual Studio profiler *.psess *.vsp *.vspx # TFS 2012 Local Workspace $tf/ # Guidance Automation Toolkit *.gpState # ReSharper is a .NET coding add-in _ReSharper*/ *.[Rr]e[Ss]harper *.DotSettings.user # JustCode is a .NET coding addin-in .JustCode # TeamCity is a build add-in _TeamCity* # DotCover is a Code Coverage Tool *.dotCover # NCrunch *.ncrunch* _NCrunch_* .*crunch*.local.xml # MightyMoose *.mm.* AutoTest.Net/ # Installshield output folder [Ee]xpress/ # DocProject is a documentation generator add-in DocProject/buildhelp/ DocProject/Help/*.HxT DocProject/Help/*.HxC DocProject/Help/*.hhc DocProject/Help/*.hhk DocProject/Help/*.hhp DocProject/Help/Html2 DocProject/Help/html # Click-Once directory publish/ # Publish Web Output *.Publish.xml *.azurePubxml # NuGet Packages Directory ## TODO: If you have NuGet Package Restore enabled, uncomment the next line #packages/ ## TODO: If the tool you use requires repositories.config, also uncomment the next line #!packages/repositories.config # Windows Azure Build Output csx/ *.build.csdef # Windows Store app package directory AppPackages/ # Buck build artefacts .buckd/ buck-out/ # Others sql/ *.Cache ClientBin/ [Ss]tyle[Cc]op.* ~$* *~ *.dbmdl *.dbproj.schemaview *.[Pp]ublish.xml *.pfx *.publishsettings # RIA/Silverlight projects Generated_Code/ # Backup & report files from converting an old project file to a newer # Visual Studio version. Backup files are not needed, because we have git ;-) _UpgradeReport_Files/ Backup*/ UpgradeLog*.XML UpgradeLog*.htm # SQL Server files App_Data/*.mdf App_Data/*.ldf # Business Intelligence projects *.rdl.data *.bim.layout *.bim_*.settings # Microsoft Fakes FakesAssemblies/ # ========================= # Windows detritus # ========================= # Windows image file caches Thumbs.db ehthumbs.db # Folder config file Desktop.ini # Recycle Bin used on file shares $RECYCLE.BIN/ # Visual Studio stuff *.VC.db *.VC.opendb .vscode/ .vs/ \#*# .#* range-v3-0.3.5/.gitmodules000066400000000000000000000001661324212031100153060ustar00rootroot00000000000000[submodule "doc/gh-pages"] path = doc/gh-pages url = https://github.com/ericniebler/range-v3.git branch = gh-pages range-v3-0.3.5/.travis.yml000066400000000000000000000246411324212031100152460ustar00rootroot00000000000000# Copyright Louis Dionne 2013-2016 # Copyright Gonzalo BG 2014-2017 # Copyright Julian Becker 2015 # Copyright Manu Sánchez 2015 # Copyright Casey Carter 2015-2017 # Copyright Eric Niebler 2015-2016 # Copyright Paul Fultz II 2015-2016 # Copyright Jakub Szuppe 2016. # Distributed under the Boost Software License, Version 1.0. # (See accompanying file LICENSE.txt or copy at http://boost.org/LICENSE_1_0.txt) # Adapted from various sources, including: # - Louis Dionne's Hana: https://github.com/ldionne/hana # - Paul Fultz II's FIT: https://github.com/pfultz2/Fit language: cpp script: cmake env: global: - DEPS_DIR=${TRAVIS_BUILD_DIR}/deps - BOOST_URL="http://sourceforge.net/projects/boost/files/boost/1.63.0/boost_1_63_0.tar.gz" - BOOST_VERSION="1_63_0" - CMAKE_VERSION="3.9.1" cache: directories: - ${DEPS_DIR}/cmake-${CMAKE_VERSION} matrix: include: - env: BUILD_TYPE=Release CPP=11 SYSTEM_LIBCXX=On os: osx compiler: clang # ASAN disabled for clang < 3.8 builds per resolution of # https://llvm.org/bugs/show_bug.cgi?id=22757 # clang 3.6 C++11/14 Release libc++ - env: CLANG_VERSION=3.6 BUILD_TYPE=Release CPP=11 LIBCXX=On os: linux addons: &clang36 apt: packages: - clang-3.6 - g++-5 - valgrind sources: - ubuntu-toolchain-r-test - llvm-toolchain-precise-3.6 - env: CLANG_VERSION=3.6 BUILD_TYPE=Release CPP=14 LIBCXX=On HEADERS=On os: linux addons: *clang36 # clang 3.7 C++11/14 Release libc++ # # ASAN disabled: cmake'ing libc++-3.7 with -fsanitize=address fails with: # CMake Error at projects/libcxx/CMakeLists.txt:164 (message): # c++11 is required by libc++ but is not supported by the compiler - env: CLANG_VERSION=3.7 BUILD_TYPE=Release CPP=11 LIBCXX=On os: linux addons: &clang37 apt: packages: - util-linux - clang-3.7 - g++-5 - valgrind sources: - ubuntu-toolchain-r-test - llvm-toolchain-precise-3.7 # ASAN disabled (see above): - env: CLANG_VERSION=3.7 BUILD_TYPE=Release CPP=14 LIBCXX=On HEADERS=On os: linux addons: *clang37 # clang 3.8 C++11/14 Release libc++ - env: CLANG_VERSION=3.8 BUILD_TYPE=Release CPP=11 LIBCXX=On os: linux addons: &clang38 apt: packages: - util-linux - clang-3.8 - g++-5 - valgrind sources: - ubuntu-toolchain-r-test - llvm-toolchain-precise-3.8 - env: CLANG_VERSION=3.8 BUILD_TYPE=Release CPP=14 LIBCXX=On HEADERS=On os: linux addons: *clang38 # clang 3.9 C++11/14 Release libc++ - env: CLANG_VERSION=3.9 BUILD_TYPE=Release CPP=11 LIBCXX=On os: linux addons: &clang39 apt: packages: - util-linux - clang-3.9 - g++-5 - valgrind sources: - ubuntu-toolchain-r-test - llvm-toolchain-precise-3.9 - env: CLANG_VERSION=3.9 BUILD_TYPE=Release CPP=14 LIBCXX=On HEADERS=On os: linux addons: *clang39 # clang 5 C++11/14/1z Debug/Release-ASAN libc++, 11 Debug libstdc++ - env: CLANG_VERSION=5.0 BUILD_TYPE=Debug CPP=11 LIBCXX=On os: linux addons: &clang5 apt: packages: - util-linux - clang-5.0 - g++-6 - valgrind sources: - ubuntu-toolchain-r-test - llvm-toolchain-precise - env: CLANG_VERSION=5.0 BUILD_TYPE=Release CPP=11 ASAN=On LIBCXX=On os: linux addons: *clang5 - env: CLANG_VERSION=5.0 BUILD_TYPE=Debug CPP=14 LIBCXX=On os: linux addons: *clang5 - env: CLANG_VERSION=5.0 BUILD_TYPE=Release CPP=14 ASAN=On LIBCXX=On os: linux addons: *clang5 - env: CLANG_VERSION=5.0 BUILD_TYPE=Debug CPP=1z LIBCXX=On HEADERS=On os: linux addons: *clang5 - env: CLANG_VERSION=5.0 BUILD_TYPE=Release CPP=1z ASAN=On LIBCXX=On os: linux addons: *clang5 - env: CLANG_VERSION=5.0 BUILD_TYPE=Release CPP=11 os: linux addons: *clang5 - env: CLANG_VERSION=5.0 BUILD_TYPE=Release CPP=1z MSAN=On LIBCXX=On CLANG_MODULES=On os: linux addons: *clang5 # gcc-4.9 C++11/C++14 Release - env: GCC_VERSION=4.9 BUILD_TYPE=Release CPP=11 os: linux addons: &gcc49 apt: packages: - g++-4.9 - valgrind sources: - ubuntu-toolchain-r-test - env: GCC_VERSION=4.9 BUILD_TYPE=Release CPP=14 HEADERS=On os: linux addons: *gcc49 # gcc-5 C++11/C++14 Release - env: GCC_VERSION=5 BUILD_TYPE=Release CPP=11 os: linux addons: &gcc5 apt: packages: - g++-5 - valgrind sources: - ubuntu-toolchain-r-test - env: GCC_VERSION=5 BUILD_TYPE=Release CPP=14 HEADERS=On os: linux addons: *gcc5 # gcc-6 C++11/14/1z Debug/Release - env: GCC_VERSION=6 BUILD_TYPE=Debug CPP=11 os: linux addons: &gcc6 apt: packages: - g++-6 - valgrind sources: - ubuntu-toolchain-r-test - env: GCC_VERSION=6 BUILD_TYPE=Release CPP=11 os: linux addons: *gcc6 - env: GCC_VERSION=6 BUILD_TYPE=Debug CPP=14 os: linux addons: *gcc6 - env: GCC_VERSION=6 BUILD_TYPE=Release CPP=14 os: linux addons: *gcc6 - env: GCC_VERSION=6 BUILD_TYPE=Debug CPP=1z HEADERS=On os: linux addons: *gcc6 - env: GCC_VERSION=6 BUILD_TYPE=Release CPP=1z os: linux addons: *gcc6 # Install dependencies before_install: - export CHECKOUT_PATH=`pwd`; - | if [ "$TRAVIS_OS_NAME" == "osx" ]; then brew update brew install valgrind brew install gnu-sed --with-default-names brew install gnu-which --with-default-names fi - | if [ "${TRAVIS_OS_NAME}" == "linux" ]; then if [ -z "$(ls -A ${DEPS_DIR}/cmake-${CMAKE_VERSION}/cached)" ]; then CMAKE_URL="https://cmake.org/files/v3.9/cmake-${CMAKE_VERSION}-Linux-x86_64.tar.gz" mkdir -p ${DEPS_DIR}/cmake-${CMAKE_VERSION} travis_retry wget --no-check-certificate --quiet -O - "${CMAKE_URL}" | tar --strip-components=1 -xz -C ${DEPS_DIR}/cmake-${CMAKE_VERSION} touch ${DEPS_DIR}/cmake-${CMAKE_VERSION}/cached else echo "Using cached cmake version ${CMAKE_VERSION}." fi export PATH="${DEPS_DIR}/cmake-${CMAKE_VERSION}/bin:${PATH}" else if ! brew ls --version cmake &>/dev/null; then brew install cmake; fi fi - if [ -n "$GCC_VERSION" ]; then export CXX="g++-${GCC_VERSION}" CC="gcc-${GCC_VERSION}"; fi - if [ -n "$CLANG_VERSION" ]; then export CXX="clang++-${CLANG_VERSION}" CC="clang-${CLANG_VERSION}"; fi - which $CXX - which $CC - which valgrind - $CXX --version - if [ "$ASAN" == "On" ]; then export SANITIZER="Address;Undefined"; fi - if [ "$MSAN" == "On" ]; then export SANITIZER="MemoryWithOrigins"; fi - if [ -n "$CLANG_VERSION" ]; then sudo PATH="${PATH}" CXX="$CXX" CC="$CC" ./install_libcxx.sh; fi # Download and install Boost # Adapted from Boost.Compute (under the Boost License) # Copyright Jakub Szuppe 2016. - | if [[ ${TRAVIS_OS_NAME} == "linux" && ${BOOST} == "On" ]]; then if [ ! -f "${DEPS_DIR}/boost/${BOOST_VERSION}_cached" ]; then # create dirs for source and install mkdir -p ${DEPS_DIR}/boost${BOOST_VERSION} mkdir -p ${DEPS_DIR}/boost rm -rf ${DEPS_DIR}/boost/* # download travis_retry wget --no-check-certificate --quiet -O - ${BOOST_URL} | tar --strip-components=1 -xz -C ${DEPS_DIR}/boost${BOOST_VERSION} pushd ${DEPS_DIR}/boost${BOOST_VERSION} # configure and install ./bootstrap.sh --prefix=${DEPS_DIR}/boost/ --with-libraries=program_options,date_time ./b2 toolset=clang cxxflags="-stdlib=libc++ -nostdinc++ -cxx-isystem /usr/include/c++/v1/" linkflags="-stdlib=libc++" ./b2 -d0 install popd touch ${DEPS_DIR}/boost/${BOOST_VERSION}_cached else echo 'Using cached Boost ${BOOST_VERSION} libraries.' fi fi install: - cd $CHECKOUT_PATH # Workaround for valgrind bug: https://bugs.kde.org/show_bug.cgi?id=326469. # It is fixed in valgrind 3.10 so this won't be necessary if someone # replaces the current valgrind (3.7) with valgrind-3.10 - if [ "$BUILD_TYPE" == "Release" -a "$ASAN" != "On" ]; then sed -i 's/march=native/msse4.2/' cmake/ranges_flags.cmake; fi - mkdir -p build - cd build - if [ "$GCC_VERSION" == "5" ]; then CXX_FLAGS="${CXX_FLAGS} -DRANGES_CXX_CONSTEXPR=RANGES_CXX_CONSTEXPR11"; fi - | if [ "$LIBCXX" == "On" ]; then CXX_FLAGS="${CXX_FLAGS} -stdlib=libc++ -nostdinc++ -cxx-isystem /usr/include/c++/v1/ -Wno-unused-command-line-argument" CXX_LINKER_FLAGS="${CXX_LINKER_FLAGS} -lc++abi" fi # Required to test the C++ compiler since libc++ is compiled with ASan enabled: - if [ -n "$CLANG_VERSION" -a "$ASAN" == "On" -a "$LIBCXX" == "On" ]; then CXX_FLAGS="${CXX_FLAGS} -fsanitize=address"; fi # Required to test the C++ compiler since libc++ is compiled with MSan enabled: - if [ -n "$CLANG_VERSION" -a "$MSAN" == "On" -a "$LIBCXX" == "On" ]; then CXX_FLAGS="${CXX_FLAGS} -fsanitize=memory"; fi - if [ "$HEADERS" == "On" ]; then NO_HEADER_CHECK=0; else NO_HEADER_CHECK=1; fi - cmake .. -DCMAKE_BUILD_TYPE=$BUILD_TYPE -DCMAKE_CXX_FLAGS="${CXX_FLAGS}" -DCMAKE_EXE_LINKER_FLAGS="${CXX_LINKER_FLAGS}" -DRANGES_CXX_STD=$CPP -DRANGE_V3_NO_HEADER_CHECK=$NO_HEADER_CHECK -DRANGES_VERBOSE_BUILD=On -DRANGES_ASAN=$ASAN -DRANGES_MSAN=$MSAN -Wdev - cat CMakeFiles/CMakeError.log - cat CMakeFiles/CMakeOutput.log - | if [ "$BOOST" == "On" ]; then export LD_LIBRARY_PATH=$DEPS_DIR/boost/lib:$LD_LIBRARY_PATH cmake .. -DRANGES_BUILD_CALENDAR_EXAMPLE=On -DBOOST_ROOT=${DEPS_DIR}/boost fi - if [ "$CLANG_MODULES" == "On" -a "$LIBCXX" == "On" ]; then cmake .. -DRANGES_MODULES=On -DRANGES_LIBCXX_MODULE="/usr/include/c++/v1/module.modulemap"; fi - make -j2 VERBOSE=1 script: # Only enable valgrind for non-ASAN Release builds (keep this in sync with line 309) - if [ "$BUILD_TYPE" == "Release" -a "$ASAN" != "On" -a "$MSAN" != "On" ]; then CTEST_FLAGS="-D ExperimentalMemCheck"; fi - ctest -j2 -VV ${CTEST_FLAGS} notifications: email: false range-v3-0.3.5/.vscode/000077500000000000000000000000001324212031100144675ustar00rootroot00000000000000range-v3-0.3.5/.vscode/c_cpp_properties.json000066400000000000000000000043601324212031100207250ustar00rootroot00000000000000{ "configurations": [ { "name": "Mac", "includePath": [ "/Users/eniebler/llvm-install/include/c++/v1", "/usr/local/include", "/Users/eniebler/llvm-install/lib/clang/6.0.0/include", "/usr/include", "${workspaceRoot}/include" ], "defines": [], "intelliSenseMode": "clang-x64", "browse": { "path": [ "/Users/eniebler/llvm-install/include/c++/v1", "/usr/local/include", "/Users/eniebler/llvm-install/lib/clang/6.0.0/include", "/usr/include", "${workspaceRoot}/include" ], "limitSymbolsToIncludedHeaders": true, "databaseFilename": "" }, "macFrameworkPath": [ "/System/Library/Frameworks", "/Library/Frameworks" ] }, { "name": "Linux", "includePath": [ "/usr/include", "/usr/local/include", "${workspaceRoot}/include" ], "defines": [], "intelliSenseMode": "clang-x64", "browse": { "path": [ "/usr/include", "/usr/local/include", "${workspaceRoot}/include" ], "limitSymbolsToIncludedHeaders": true, "databaseFilename": "" } }, { "name": "Win32", "includePath": [ "C:/Program Files (x86)/Microsoft Visual Studio 14.0/VC/include", "${workspaceRoot}/include" ], "defines": [ "_DEBUG", "UNICODE" ], "intelliSenseMode": "msvc-x64", "browse": { "path": [ "C:/Program Files (x86)/Microsoft Visual Studio 14.0/VC/include/*", "${workspaceRoot}/include" ], "limitSymbolsToIncludedHeaders": true, "databaseFilename": "" } } ], "version": 3 }range-v3-0.3.5/.vscode/tasks.json000066400000000000000000000015541324212031100165140ustar00rootroot00000000000000{ // See https://go.microsoft.com/fwlink/?LinkId=733558 // for the documentation about the tasks.json format "version": "2.0.0", "options": { "cwd": "${workspaceRoot}/../range-build" }, "tasks": [ { "label": "cmake", "type": "shell", "command": "cmake -G 'Unix Makefiles' -DCMAKE_BUILD_TYPE=Debug ../range-v3", "group": "build", "presentation": { "reveal": "always", "panel": "new" } }, { "label": "make", "type": "shell", "command": "make -j8", "group": { "kind": "build", "isDefault": true }, "presentation": { "reveal": "always", "panel": "new" } } ] } range-v3-0.3.5/BUCK000066400000000000000000000007511324212031100136000ustar00rootroot00000000000000prebuilt_cxx_library( name = 'meta', header_namespace = 'meta', header_only = True, exported_headers = subdir_glob([ ('include/meta', '**/*.hpp'), ]), licenses = [ 'LICENSE.txt', ], ) prebuilt_cxx_library( name = 'range-v3', header_namespace = 'range/v3', header_only = True, exported_headers = subdir_glob([ ('include/range/v3', '**/*.hpp'), ]), licenses = [ 'LICENSE.txt', ], visibility = [ 'PUBLIC' ], deps = [ ':meta', ], ) range-v3-0.3.5/BUILD.bazel000066400000000000000000000004251324212031100150050ustar00rootroot00000000000000cc_library( name = 'meta', hdrs = glob([ 'include/meta/**/*.hpp', ]), includes = [ "include", ], ) cc_library( name = 'range-v3', hdrs = glob([ 'include/range/v3/**/*.hpp', ]), visibility = ["//visibility:public"], deps = [ ':meta', ], ) range-v3-0.3.5/CMakeLists.txt000066400000000000000000000131761324212031100156760ustar00rootroot00000000000000# Copyright Eric Niebler 2014 # Copyright Gonzalo Brito Gadeschi 2014, 2017 # Copyright Louis Dionne 2015 # Copyright Casey Carter 2016 # Distributed under the Boost Software License, Version 1.0. # (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt) cmake_minimum_required(VERSION 3.6) project(Range-v3 CXX) list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake") set(CMAKE_EXPORT_COMPILE_COMMANDS ON) # Export compilation data-base include(TestHeaders) include(ranges_options) include(ranges_env) include(ranges_flags) include(CTest) enable_testing() add_library(meta INTERFACE) target_include_directories(meta INTERFACE $) target_include_directories(meta SYSTEM INTERFACE $/include>) add_library(range-v3 INTERFACE) target_include_directories(range-v3 INTERFACE $) target_include_directories(range-v3 SYSTEM INTERFACE $/include>) target_link_libraries(range-v3 INTERFACE meta) add_subdirectory(doc) if(NOT RANGE_V3_NO_TESTING) add_subdirectory(test) endif() if(NOT RANGE_V3_NO_EXAMPLE) add_subdirectory(example) endif() if(NOT RANGE_V3_NO_PERF) add_subdirectory(perf) endif() # Test for try_compile(RANGE_V3_TRY_THREAD ${CMAKE_BINARY_DIR} ${CMAKE_CURRENT_SOURCE_DIR}/cmake/thread_test_code.cpp) if(NOT RANGE_V3_TRY_THREAD) set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -DRANGES_CXX_THREAD=0") endif() # Test for coroutine TS support include(CheckCXXSourceCompiles) file(READ "${CMAKE_CURRENT_SOURCE_DIR}/cmake/coro_test_code.cpp" RANGE_V3_CORO_TEST_CODE) set(CMAKE_REQUIRED_FLAGS "-fcoroutines-ts") check_cxx_source_compiles("${RANGE_V3_CORO_TEST_CODE}" RANGE_V3_HAS_FCOROUTINES_TS) if (RANGE_V3_HAS_FCOROUTINES_TS) set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fcoroutines-ts") endif() # Test all headers file(GLOB_RECURSE RANGE_V3_PUBLIC_HEADERS RELATIVE "${CMAKE_CURRENT_SOURCE_DIR}/include" "${CMAKE_CURRENT_SOURCE_DIR}/include/*.hpp") # Add header files as sources to fix MSVS 2017 not finding source during debugging file(GLOB_RECURSE RANGE_V3_PUBLIC_HEADERS_ABSOLUTE "${CMAKE_CURRENT_SOURCE_DIR}/include/*.hpp") include(TestHeaders) if(RANGE_V3_NO_HEADER_CHECK) add_custom_target(headers SOURCES ${RANGE_V3_PUBLIC_HEADERS_ABSOLUTE}) else() add_custom_target(headers ALL SOURCES ${RANGE_V3_PUBLIC_HEADERS_ABSOLUTE}) endif() generate_standalone_header_tests(EXCLUDE_FROM_ALL MASTER_TARGET headers HEADERS ${RANGE_V3_PUBLIC_HEADERS}) # Grab the range-v3 version numbers: include(${CMAKE_CURRENT_SOURCE_DIR}/Version.cmake) set(RANGE_V3_VERSION ${RANGE_V3_MAJOR}.${RANGE_V3_MINOR}.${RANGE_V3_PATCHLEVEL}) # Try to build a new version.hpp configure_file(version.hpp.in include/range/v3/version.hpp @ONLY) file(STRINGS ${CMAKE_CURRENT_BINARY_DIR}/include/range/v3/version.hpp RANGE_V3_OLD_VERSION_HPP) file(STRINGS ${CMAKE_CURRENT_SOURCE_DIR}/include/range/v3/version.hpp RANGE_V3_NEW_VERSION_HPP) # If the new version.hpp is materially different from the one in the source # directory, update it, amend the most recent commit, and tag the commit. if(NOT RANGE_V3_NEW_VERSION_HPP STREQUAL RANGE_V3_OLD_VERSION_HPP) # Check that README.md and Version.cmake are the only changed file: execute_process( COMMAND ${GIT_EXECUTABLE} -C "${CMAKE_CURRENT_SOURCE_DIR}" status --porcelain -uno OUTPUT_VARIABLE RANGE_V3_GIT_STATUS OUTPUT_STRIP_TRAILING_WHITESPACE ) string(REPLACE "\n" ";" RANGE_V3_GIT_STATUS ${RANGE_V3_GIT_STATUS}) if (NOT "x${RANGE_V3_GIT_STATUS}" STREQUAL "x M README.md; M Version.cmake") message(FATAL_ERROR "Cannot update version.hpp: range-v3 source directory has a dirty status") endif() file( COPY ${CMAKE_CURRENT_BINARY_DIR}/include/range/v3/version.hpp DESTINATION ${CMAKE_CURRENT_SOURCE_DIR}/include/range/v3 ) # Update the conanfiles, too configure_file(conanfile.py.in ${CMAKE_CURRENT_SOURCE_DIR}/conanfile.py @ONLY) configure_file(test_package/conanfile.py.in ${CMAKE_CURRENT_SOURCE_DIR}/test_package/conanfile.py @ONLY) execute_process( COMMAND ${GIT_EXECUTABLE} -C "${CMAKE_CURRENT_SOURCE_DIR}" add -u ) execute_process( COMMAND ${GIT_EXECUTABLE} -C "${CMAKE_CURRENT_SOURCE_DIR}" commit --amend --no-edit ) execute_process( COMMAND ${GIT_EXECUTABLE} -C "${CMAKE_CURRENT_SOURCE_DIR}" tag -f -a "${RANGE_V3_VERSION}" -m "${RANGE_V3_VERSION}" ) find_program(CONAN_EXECUTABLE NAMES conan conan.exe) if (NOT "x${CONAN_EXECUTABLE}" STREQUAL "xCONAN_EXECUTABLE-NOTFOUND") message("Exporting conanfile for new version") execute_process( COMMAND ${CONAN_EXECUTABLE} export . ericniebler/stable WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}" ) endif() message("Version updated to ${RANGE_V3_VERSION}. Don't forget to:") message(" git push origin ") message("and (after that is merged to master) then:") message(" conan export ericniebler") message(" conan test_package") message(" conan upload --all range-v3/${RANGE_V3_VERSION}@ericniebler/stable") endif() include(CMakePackageConfigHelpers) write_basic_package_version_file( ${CMAKE_CURRENT_BINARY_DIR}/range-v3-config-version.cmake VERSION ${RANGE_V3_VERSION} COMPATIBILITY ExactVersion ) install(TARGETS meta range-v3 EXPORT range-v3-targets DESTINATION lib) install(EXPORT range-v3-targets FILE range-v3-config.cmake DESTINATION lib/cmake/range-v3) install(FILES ${CMAKE_CURRENT_BINARY_DIR}/range-v3-config-version.cmake DESTINATION lib/cmake/range-v3) install(DIRECTORY include/ DESTINATION include FILES_MATCHING PATTERN "*.hpp") range-v3-0.3.5/CREDITS.md000066400000000000000000000111411324212031100145430ustar00rootroot00000000000000Acknowledgements ---------------- In range-v3, I have integrated many ideas that come from other people. I would be remiss to not mention them. Many others helped either directly or indirectly in a variety of ways. In no particular order... | Contributor | Contribution | |-----------------------------|------| | Jeremy Siek | Container algorithms (in Boost pre-history), Boost.Iterators | | Thorston Ottoson | Boost.Range v1 | | Neil Groves | Boost.Range v2 | | David Abrahams, Thomas Witt | Boost.Iterators, Sentinels | | Sean Parent | ASL, Projections, View / Range distinction, much Generic Program wisdom besides | | Dietmar Kühl | Array Traits, Property Map | | Andrew Sutton | C++ Concepts "Lite", Origin Libraries, Palo Alto Report | | Doug Gregor | C++0x Concepts | | Casey Carter | Co-author and Editor, Ranges TS; major code contributions | | Gonzalo Brito Gadeschi | Many ideas, bug reports, and code contributions | | Alexander Stepanov | STL, Generic Programming, Iterators, Elements of Programming, etc. | | Bjarne Stroustrup | A tireless effort to add proper support for Generic Programming to C++, early support for my Ranges proposal | | Herb Sutter | Early support for my Ranges proposal | | The Standard C++ Foundation | A generous grant supporting my Ranges work | An Abreviated History -------------------- **Range v1** I came to Boost in the early 2000's. By that time, Boost already had a Range library (Thorston Ottoson's). At this time, Boost.Range was little more that the `begin` and `end` free functions, and range-based overloads of the STL algorithms that dispatched to the iterator-based overloads in namespace `std`. Boost also already had the Iterators library by David Abrahams and Jeremy Siek. This library had iterator adaptors like `filter_iterator` and `transform_iterator`. **Range v2** It seemed natural to me that the Range library and the adaptors from the Iterators library should be combined. I wrote the `filter` and `transform` range adaptors, commandeered the pipe operator (`|`) from bash for chaining, and put a rough library together called Range_ex in the Boost File Vault (which would later become the Boost Sandbox). I saw problems with my design and never finished it. A few years later, Neil Groves picked up some of the ideas in my Range\_ex, polished them a great deal, published his own Range\_ex library, and submitted it to Boost. It became Boost.Range v2. At the time of writing (March, 2017), it is the version still shipping with Boost. **Range v3** In 2013, I published a blog post called ["Out Parameters, Move Semantics, and Stateful Algorithms"](http://ericniebler.com/2013/10/13/out-parameters-vs-move-semantics/) that turned my mind to ranges once again. Following that, it became clear to me that the Boost.Range library, designed for C++98, needed a facelift for the post-C++11 world. I began what I believed at the time would be a quick hack to bring Boost.Range into the modern world. I called it "Range v3", thinking it would become the third major version of the Boost.Range library. Subsequent posts detailed the evolution of my thinking as range-v3 took shape. **Standardization** Around this time, some big thinkers in the C++ community were working to resurrect the effort to add Concepts to C++. They published a paper ([N3351](http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3351.pdf)) that would become known as the **"Palo Alto Report"** which detailed the necessary and sufficient language and library support for a concept-checked version of the Standard Template Library. The authors of the paper included Alexander Stepanov, Bjarne Stroustrup, Sean Parent, Andrew Sutton, and more. Andrew Sutton began working in earnest to realize the core language changes, an effort that became known as "Concepts Lite". (It is now the Concepts TS.) I decided early on that Concepts Lite, or something like it, would become part of Standard C++. Recognizing that C++ would need a concept-ified Standard Library to go with the language feature, I began evolving range-v3 in that direction, eventually submitting ["Ranges for the Standard Library, Revision 1"](http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4128.html) to the C++ Standardization Committee, together with Andrew Sutton and Sean Parent. The Committee approved the direction in late 2014, and so it goes... Today (2017-03), we are very close to a final Ranges TS and are on target to integrate into Standard C++ in 2020, with *much* more to come. Stay tuned. range-v3-0.3.5/LICENSE.txt000066400000000000000000000161011324212031100147500ustar00rootroot00000000000000======================================================== Boost Software License - Version 1.0 - August 17th, 2003 ======================================================== Permission is hereby granted, free of charge, to any person or organization obtaining a copy of the software and accompanying documentation covered by this license (the "Software") to use, reproduce, display, distribute, execute, and transmit the Software, and to prepare derivative works of the Software, and to permit third-parties to whom the Software is furnished to do so, all subject to the following: The copyright notices in the Software and this entire statement, including the above license grant, this restriction and the following disclaimer, must be included in all copies of the Software, in whole or in part, and all derivative works of the Software, unless such copies or derivative works are solely in the form of machine-executable object code generated by a source language processor. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ============================================================================== libc++ License ============================================================================== The libc++ library is dual licensed under both the University of Illinois "BSD-Like" license and the MIT license. As a user of this code you may choose to use it under either license. As a contributor, you agree to allow your code to be used under both. Full text of the relevant licenses is included below. ============================================================================== University of Illinois/NCSA Open Source License Copyright (c) 2009-2014 by the contributors listed in CREDITS.TXT http://llvm.org/svn/llvm-project/libcxx/trunk/CREDITS.TXT All rights reserved. Developed by: LLVM Team University of Illinois at Urbana-Champaign http://llvm.org Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal with the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimers. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimers in the documentation and/or other materials provided with the distribution. * Neither the names of the LLVM Team, University of Illinois at Urbana-Champaign, nor the names of its contributors may be used to endorse or promote products derived from this Software without specific prior written permission. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE CONTRIBUTORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS WITH THE SOFTWARE. ============================================================================== Copyright (c) 2009-2014 by the contributors listed in CREDITS.TXT http://llvm.org/svn/llvm-project/libcxx/trunk/CREDITS.TXT Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ============================================================================== Stepanov and McJones, "Elements of Programming" license ============================================================================== // Copyright (c) 2009 Alexander Stepanov and Paul McJones // // Permission to use, copy, modify, distribute and sell this software // and its documentation for any purpose is hereby granted without // fee, provided that the above copyright notice appear in all copies // and that both that copyright notice and this permission notice // appear in supporting documentation. The authors make no // representations about the suitability of this software for any // purpose. It is provided "as is" without express or implied // warranty. // // Algorithms from // Elements of Programming // by Alexander Stepanov and Paul McJones // Addison-Wesley Professional, 2009 ============================================================================== SGI C++ Standard Template Library license ============================================================================== // Copyright (c) 1994 // Hewlett-Packard Company // // Permission to use, copy, modify, distribute and sell this software // and its documentation for any purpose is hereby granted without fee, // provided that the above copyright notice appear in all copies and // that both that copyright notice and this permission notice appear // in supporting documentation. Hewlett-Packard Company makes no // representations about the suitability of this software for any // purpose. It is provided "as is" without express or implied warranty. // // Copyright (c) 1996 // Silicon Graphics Computer Systems, Inc. // // Permission to use, copy, modify, distribute and sell this software // and its documentation for any purpose is hereby granted without fee, // provided that the above copyright notice appear in all copies and // that both that copyright notice and this permission notice appear // in supporting documentation. Silicon Graphics makes no // representations about the suitability of this software for any // purpose. It is provided "as is" without express or implied warranty. // range-v3-0.3.5/README.md000066400000000000000000000254511324212031100144140ustar00rootroot00000000000000range-v3 ======== Range library for C++11/14/17. This code is the basis of [a formal proposal](https://ericniebler.github.io/std/wg21/D4128.html) to add range support to the C++ standard library. About: ------ Why does C++ need another range library? Simply put, the existing solutions haven't kept up with the rapid evolution of C++. Range v3 is a library for the future C++. Not only does it work well with today's C++ -- move semantics, lambdas, automatically deduced types and all -- it also anticipates tomorrow's C++ with Concepts. Range v3 forms the basis of a proposal to add range support to the standard library ([N4128: Ranges for the Standard Library](http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4128.html)). It also will be the reference implementation for an upcoming Technical Specification. These are the first steps toward turning ranges into an international standard. Documentation: -------------- Check out the (woefully incomplete) documentation [here](https://ericniebler.github.io/range-v3/). Other resources (mind the dates, the library probably has changed since then): - Usage: - Talk: [CppCon 2015: Eric Niebler "Ranges for the Standard Library"](https://www.youtube.com/watch?v=mFUXNMfaciE), 2015. - [A slice of Python in C++](http://ericniebler.com/2014/12/07/a-slice-of-python-in-c/), 07.12.2014. - Actions (back then called [Container Algorithms](http://ericniebler.com/2014/11/23/container-algorithms/)), 23.11.2014. - [Range comprehensions](http://ericniebler.com/2014/04/27/range-comprehensions/), 27.04.2014. - [Input iterators vs input ranges](http://ericniebler.com/2013/11/07/input-iterators-vs-input-ranges/), 07.11.2013. - Design / Implementation: - Rationale behind range-v3: [N4128: Ranges for the standard library Revision 1](http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4128.html), 2014. - Ranges TS: [N4560: C++ Extensions for Ranges](http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2015/n4560.pdf), 2015. - Implementation of customization points in range-v3: - [N4381: Suggested Design for Customization Points](http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2015/n4381.html), 2015. - [P0386: Inline variables](http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0386r0.pdf), 2016. - [Customization Point Design in C++11 and Beyond](http://ericniebler.com/2014/10/21/customization-point-design-in-c11-and-beyond/), 2014. - Proxy iterators in range-v3: - [D0022: Proxy Iterators for the Ranges Extensions](https://ericniebler.github.io/std/wg21/D0022.html). - [To Be or Not to Be (an Iterator)](http://ericniebler.com/2015/01/28/to-be-or-not-to-be-an-iterator/), 2015. - [Iterators++: Part1](http://ericniebler.com/2015/02/03/iterators-plus-plus-part-1/), 2015. - [Iterators++: Part2](http://ericniebler.com/2015/02/13/iterators-plus-plus-part-2/), 2015. - [Iterators++: Part3](http://ericniebler.com/2015/03/03/iterators-plus-plus-part-3/), 2015. - Metaprogramming utilities: - See the [meta documentation](https://ericniebler.github.io/meta/index.html), the library has changed significantly since the [2014 blog post](http://ericniebler.com/2014/11/13/tiny-metaprogramming-library/). - Concept emulation layer: [Concept checking in C++11](http://ericniebler.com/2013/11/23/concept-checking-in-c11/), 2013. - [C++Now 2014: Eric Niebler "C++11 Library Design"](https://www.youtube.com/watch?v=zgOF4NrQllo), 2014. License: -------- Most of the source code in this project are mine, and those are under the Boost Software License. Parts are taken from Alex Stepanov's Elements of Programming, Howard Hinnant's libc++, and from the SGI STL. Please see the attached LICENSE file and the CREDITS file for the licensing and acknowledgments. Supported Compilers ------------------- The code is known to work on the following compilers: - clang 3.6.2 (or later) - GCC 4.9.1 (or later) (C++14 support requires GCC 5.2; C++14 "extended constexpr" support is poor before 6.1.) - "Clang with Microsoft CodeGen" (Clang/C2) VS2015 Update 3 (or later) **Development Status:** This code is fairly stable, well-tested, and suitable for casual use, although currently lacking documentation. No promise is made about support or long-term stability. This code *will* evolve without regard to backwards compatibility. **Build status** - on Travis-CI: [![Travis Build Status](https://travis-ci.org/ericniebler/range-v3.svg?branch=master)](https://travis-ci.org/ericniebler/range-v3) - on AppVeyor: [![AppVeyor Build Status](https://ci.appveyor.com/api/projects/status/fwl9ymc2t6ukn9qj/branch/master?svg=true)](https://ci.appveyor.com/project/ericniebler/range-v3) Release Notes: -------------- * **0.3.5** February 17, 2018 - Rvalues may satisfy `Writable` (see [ericniebler/stl2\#387](https://github.com/ericniebler/stl2/issues/387)). - `view_interface` gets a bounds-checking `at` method. - `chunk_view` works on Input ranges. - Fix bug in `group_by_view`. - Improved concept checks for `partial_sum` numeric algorithm. - Define `ContiguousIterator` concept and `contiguous_iterator_tag` iterator category tag. - Sundry `span` fixes. - `action::insert` avoids interfering with `vector`'s exponentional growth strategy. - Add an experimental `shared` view for views that need container-like scratch space to do their work. - Faster, simpler `reverse_view`. - Rework `ranges::reference_wrapper` to avoid [LWG\#2993](http://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#2993). - Reworked `any_view`, the type-erased view wrapper. - `equal` algorithm is `constexpr` in C++14. - `stride_view` no longer needs an `atomic` data member. - `const`-correct `drop_view`. - `adjacent_filter_view` supports bidirectional iteration. - Massive `view_adaptor` cleanup to remove the need for a `mutable` data member holding the adapted view. - Fix `counting_iterator` post-increment bug. - `tail_view` of an empty range is an empty range, not undefined behavior. - Various portability fixes for gcc and clang trunk. * **0.3.0** June 30, 2017 - Input views may now be move-only (from @CaseyCarter) - Input `any_view`s are now *much* more efficicient (from @CaseyCarter) - Better support for systems lacking a working `` header (from @CaseyCarter) * **0.2.6** June 21, 2017 - Experimental coroutines with `ranges::experimental::generator` (from @CaseyCarter) - `ranges::optional` now behaves like `std::optional` (from @CaseyCarter) - Extensive bug fixes with Input ranges (from @CaseyCarter) * **0.2.5** May 16, 2017 - `view::chunk` works on Input ranges (from @CaseyCarter) - `for_each_n` algorithm (from @khlebnikov) - Portability fixes for MinGW, clang-3.6 and -3.7, and gcc-7; and cmake 3.0 * **0.2.4** April 12, 2017 Fix the following bug: - `action::stable_sort` of `vector` broken on Clang 3.8.1 since ~last Xmas (ericniebler/range-v3#632). * **0.2.3** April 4, 2017 Fix the following bug: - iterators that return move-only types by value do not satisfy Readable (ericniebler/stl2#399). * **0.2.2** March 30, 2017 New in this release: - `view::linear_distribute(from,to,n)` - A view of `n` elements between `from` and `to`, distributed evenly. - `view::indices(n)` - A view of the indices `[0,1,2...n-1]`. - `view::closed_indices(n)` - A view of the indices `[0,1,2...n]`. This release deprecates `view::ints(n)` as confusing to new users. * **0.2.1** March 22, 2017 New in this release: - `view::cartesian_product` - `action::reverse` * **0.2.0** March 13, 2017 Bring many interfaces into sync with the Ranges TS. - Many interfaces are simply renamed. The following table shows the old names and the new. (All names are in the `ranges::v3` namespace.) | Old Name | New Name | |-------------------------------|---------------------------| | `indirect_swap` | `iter_swap` | | `indirect_move` | `iter_move` | | `iterator_value_t` | `value_type_t` | | `iterator_reference_t` | `reference_t` | | `iterator_difference_t` | `difference_type_t` | | `iterator_size_t` | `size_type_t` | | `iterator_rvalue_reference_t` | `rvalue_reference_t` | | `iterator_common_reference_t` | `iter_common_reference_t` | | `range_value_t` | `range_value_type_t` | | `range_difference_t` | `range_difference_type_t` | | `range_size_t` | `range_size_type_t` | | `range_iterator_t` | `iterator_t` | | `range_sentinel_t` | `sentinel_t` | - `common_iterator` now requires that its two types (`Iterator` and `Sentinel`) are different. Use `common_iterator_t` to get the old behavior (i.e., if the two types are the same, it is an alias for `I`; otherwise, it is `common_iterator`). - The following iterator adaptors now work with iterators that return proxies from their postfix increment operator (i.e., `operator++(int)`): * `common_iterator` * `counted_iterator` - The following customization points are now implemented per the Ranges TS spec and will no longer find the associated unconstrained overload in namespace `std::`: * `ranges::begin` * `ranges::end` * `ranges::size` * `ranges::swap` * `ranges::iter_swap` (In practice, this has very little effect but it may effect overloading in rare situations.) - `ranges::is_swappable` now only takes one template parameter. The new `ranges::is_swappable_with` tests whether `T` and `U` are swappable. `ranges::is_swappable` is equivalent to `ranges::is_swappable_with`. - The following object concepts have changed to conform with the Ranges TS specification, and approved changes (see [P0547](http://wg21.link/p0547)): * `Destructible` * `Constructible` * `DefaultConstructible` * `MoveConstructible` * `MoveConstructible` * `Movable` * `Assignable` - The `View` concept is no longer satisfied by reference types. - The syntax for defining a concept has changed slightly. See [utility/iterator_concepts.hpp](https://github.com/ericniebler/range-v3/blob/master/include/range/v3/utility/iterator_concepts.hpp) for examples. * **0.1.1** Small tweak to `Writable` concept to fix #537. * **0.1.0** March 8, 2017, Begin semantic versioning Say Thanks! ----------- I do this work because I love it and because I love C++ and want it to be as excellent as I know it can be. If you like my work and are looking for a way to say thank you, you can leave a supportive comment on [my blog](http://ericniebler.com). Or you could leave me some kudos on my Open Hub range-v3 contribution page. Just click the **Give Kudos** button [here](https://www.openhub.net/p/range-v3/contributors/3053743222308608). range-v3-0.3.5/TODO.md000066400000000000000000000023241324212031100142160ustar00rootroot00000000000000* Add contiguous iterator utilities. How about `is_contiguous_iterator` and `as_contiguous_range`: ``` template() && SizedSentinel() && is_contiguous_iterator())> iterator_range>> as_contiguous_range(I begin, S end) { if(begin == end) return {nullptr, nullptr}; else return {addressof(*begin), addressof(*begin) + (end - begin)}; } ``` * Longer-term goals: - Make `inplace_merge` work with forward iterators - Make the sorting algorithms work with forward iterators - Study the impact of allowing ForwardIterator to return proxies * Maybe iterators are not necessarily countable. Is there a relation between the ability to be able to subtract two iterators to find the distance, and with the existence of a DistanceType associated type? Think of: - counted iterators (subtractable regardless of traversal category) - repeat_view iterators (*not* subtractable but could be random access otherwise) - infinite ranges (only countable with an infinite precision integer which we lack) range-v3-0.3.5/Version.cmake000066400000000000000000000004261324212031100155570ustar00rootroot00000000000000# To update the range-v3 version, from a *CLEAN* working directory, update the version numbers below. # This makefile will generate a new version.hpp, *AMEND THE MOST RECENT COMMIT*, and git-tag the commit. set(RANGE_V3_MAJOR 0) set(RANGE_V3_MINOR 3) set(RANGE_V3_PATCHLEVEL 5) range-v3-0.3.5/WORKSPACE000066400000000000000000000000001324212031100143750ustar00rootroot00000000000000range-v3-0.3.5/appveyor.yml000066400000000000000000000015361324212031100155230ustar00rootroot00000000000000shallow_clone: true platform: - x86 - x64 configuration: - Debug - Release cache: - C:\cmake-3.9.1-win32-x86 install: - ps: | if (![IO.File]::Exists("C:\cmake-3.9.1-win32-x86\bin\cmake.exe")) { Start-FileDownload 'https://cmake.org/files/v3.9/cmake-3.9.1-win32-x86.zip' 7z x -y cmake-3.9.1-win32-x86.zip -oC:\ } $env:PATH="C:\cmake-3.9.1-win32-x86\bin;$env:PATH" - mkdir build && cd build - ps: | if ($env:PLATFORM -eq "x64" -and $env:CONFIGURATION -eq "Debug") { $env:NO_HEADER_CHECK=0 } else { $env:NO_HEADER_CHECK=1 } - cmake .. -DRANGE_V3_NO_HEADER_CHECK=%NO_HEADER_CHECK% -DCMAKE_BUILD_TYPE=%CONFIGURATION% -T v140_clang_c2 build: project: c:/projects/range-v3/build/ALL_BUILD.vcxproj parallel: true verbosity: minimal test_script: - ctest -j2 deploy: off range-v3-0.3.5/cmake/000077500000000000000000000000001324212031100142065ustar00rootroot00000000000000range-v3-0.3.5/cmake/TestHeaders.cmake000066400000000000000000000121211324212031100174200ustar00rootroot00000000000000# Copyright Louis Dionne 2013-2016 # Distributed under the Boost Software License, Version 1.0. # (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt) # # # This CMake module provides a function generating unit tests to make sure # that every public header can be included on its own. # # When a C++ library or application has many header files, it can happen that # a header does not include all the other headers it depends on. When this is # the case, it can happen that including that header file on its own will # break the compilation. This CMake module generates a dummy unit test for # each header file considered public: this unit test is just a program of # the form # # #include # int main() { } # # If this succeeds to compile, it means that the header can be included on # its own, which is what clients expect. Otherwise, you have a problem. # Since writing these dumb unit tests by hand is tedious and repetitive, # you can use this CMake module to automate this task. # Generates header-inclusion unit tests for all the specified headers. # # For each specified header with path `xxx/yyy/zzz.hpp`, a target named # `test.header.xxx.yyy.zzz` is created. This target builds the unit test # including `xxx/yyy/zzz.hpp`. # # Parameters # ---------- # HEADERS headers: # A list of header files to generate the inclusion tests for. All headers # in this list must be represented as relative paths from the root of the # include directory added to the compiler's header search path. In other # words, it should be possible to include all headers in this list as # # #include <${header}> # # For example, for a library with the following structure: # # project/ # doc/ # test/ # ... # include/ # boost/ # hana.hpp # hana/ # transform.hpp # tuple.hpp # pair.hpp # ... # # When building the unit tests for that library, we'll add `-I project/include' # to the compiler's arguments. The list of public headers should therefore contain # # boost/hana.hpp # boost/hana/transform.hpp # boost/hana/tuple.hpp # boost/hana/pair.hpp # ... # # Usually, all the 'public' header files of a library should be tested for # standalone inclusion. A header is considered 'public' if a client should # be able to include that header on its own. # # [EXCLUDE excludes]: # An optional list of headers or regexes for which no unit test should be # generated. Basically, any header in the list specified by the `HEADERS` # argument that matches anything in `EXCLUDE` will be skipped. # # [MASTER_TARGET target]: # An optional target name that will be made a dependent of all the generated # targets. This can be used to create a target that will build all the # header-inclusion tests. # # [LINK_LIBRARIES libraries]: # An optional list of libraries that should be linked into each generated # executable. The libraries are linked into the target using the usual # `target_link_libraries`. # # [EXCLUDE_FROM_ALL]: # If set to true, the generated targets are excluded from the 'all' target. # function(generate_standalone_header_tests) cmake_parse_arguments(ARGS "EXCLUDE_FROM_ALL" # options "MASTER_TARGET;LINK_LIBRARIES" # 1 value args "HEADERS;EXCLUDE" # multivalued args ${ARGN}) if (NOT ARGS_HEADERS) message(FATAL_ERROR "The `HEADERS` argument must be provided.") endif() if (ARGS_EXCLUDE_FROM_ALL) set(ARGS_EXCLUDE_FROM_ALL "EXCLUDE_FROM_ALL") else() set(ARGS_EXCLUDE_FROM_ALL "") endif() foreach(header ${ARGS_HEADERS}) set(skip FALSE) foreach(exclude ${ARGS_EXCLUDE}) if (${header} MATCHES ${exclude}) set(skip TRUE) break() endif() endforeach() if (skip) continue() endif() get_filename_component(filename "${header}" NAME_WE) get_filename_component(directory "${header}" DIRECTORY) if (NOT EXISTS "${CMAKE_CURRENT_BINARY_DIR}/headers/${directory}/${filename}.cpp") file(WRITE "${CMAKE_CURRENT_BINARY_DIR}/headers/${directory}/${filename}.cpp" " /* THIS FILE WAS AUTOMATICALLY GENERATED: DO NOT EDIT! */ #include <${header}> int main() { } ") endif() string(REGEX REPLACE "/" "." target "${header}") add_executable(test.header.${target} ${ARGS_EXCLUDE_FROM_ALL} "${CMAKE_CURRENT_BINARY_DIR}/headers/${directory}/${filename}.cpp" ) target_include_directories(test.header.${target} PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/include) if (ARGS_LINK_LIBRARIES) target_link_libraries(test.header.${target} ${ARGS_LINK_LIBRARIES}) endif() if (ARGS_MASTER_TARGET) add_dependencies(${ARGS_MASTER_TARGET} test.header.${target}) endif() endforeach() endfunction() range-v3-0.3.5/cmake/coro_test_code.cpp000066400000000000000000000014141324212031100177050ustar00rootroot00000000000000#include namespace coro = std::experimental::coroutines_v1; struct present { struct promise_type { int result; present get_return_object() { return {*this}; } coro::suspend_never initial_suspend() { return {}; } coro::suspend_never final_suspend() { return {}; } void return_value(int i) { result = i; } void unhandled_exception() {} }; promise_type& promise; bool await_ready() const { return true; } void await_suspend(coro::coroutine_handle<>) const {} int await_resume() const { return promise.result; } }; present f(int n) { if (n < 2) co_return 1; else co_return n * co_await f(n - 1); } int main() { return f(5).promise.result != 120; } range-v3-0.3.5/cmake/ranges_diagnostics.cmake000066400000000000000000000041101324212031100210520ustar00rootroot00000000000000# Copyright Louis Dionne 2015 # Copyright Gonzalo Brito Gadeschi 2015 # Distributed under the Boost Software License, Version 1.0. # (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt) # # Setup compiler flags (more can be set on a per-target basis or in # subdirectories) # Enable all warnings: ranges_append_flag(RANGES_HAS_WEVERYTHING -Weverything) ranges_append_flag(RANGES_HAS_PEDANTIC -pedantic) ranges_append_flag(RANGES_HAS_PEDANTIC_ERRORS -pedantic-errors) # Selectively disable those warnings that are not worth it: ranges_append_flag(RANGES_HAS_WNO_CXX98_COMPAT -Wno-c++98-compat) ranges_append_flag(RANGES_HAS_WNO_CXX98_COMPAT_PEDANTIC -Wno-c++98-compat-pedantic) ranges_append_flag(RANGES_HAS_WNO_WEAK_VTABLES -Wno-weak-vtables) ranges_append_flag(RANGES_HAS_WNO_PADDED -Wno-padded) ranges_append_flag(RANGES_HAS_WNO_MISSING_PROTOTYPES -Wno-missing-prototypes) ranges_append_flag(RANGES_HAS_WNO_MISSING_VARIABLE_DECLARATIONS -Wno-missing-variable-declarations) ranges_append_flag(RANGES_HAS_WNO_DOCUMENTATION -Wno-documentation) ranges_append_flag(RANGES_HAS_WNO_DOCUMENTATION_UNKNOWN_COMMAND -Wno-documentation-unknown-command) ranges_append_flag(RANGES_HAS_WNO_OLD_STYLE_CAST -Wno-old-style-cast) ranges_append_flag(RANGES_HAS_WNO_SHADOW -Wno-shadow) if (RANGES_ENV_MACOSX) ranges_append_flag(RANGES_HAS_WNO_GLOBAL_CONSTRUCTORS -Wno-global-constructors) ranges_append_flag(RANGES_HAS_WNO_EXIT_TIME_DESTRUCTORS -Wno-exit-time-destructors) endif() if (RANGES_CXX_COMPILER_GCC) if (CMAKE_CXX_COMPILER_VERSION VERSION_LESS "6.0") ranges_append_flag(RANGES_HAS_WNO_STRICT_OVERFLOW -Wno-strict-overflow) if (CMAKE_CXX_COMPILER_VERSION VERSION_LESS "5.0") ranges_append_flag(RANGES_HAS_WNO_MISSING_FIELD_INITIALIZERS -Wno-missing-field-initializers) endif() elseif ((CMAKE_CXX_COMPILER_VERSION VERSION_GREATER "7.0") OR (CMAKE_CXX_COMPILER_VERSION VERSION_EQUAL "7.0")) ranges_append_flag(RANGES_HAS_WNO_NOEXCEPT_TYPE -Wno-noexcept-type) endif() endif() if (RANGES_VERBOSE_BUILD) message("[range-v3]: test C++ flags: ${CMAKE_CXX_FLAGS}") endif() range-v3-0.3.5/cmake/ranges_env.cmake000066400000000000000000000051511324212031100173410ustar00rootroot00000000000000# Copyright Gonzalo Brito Gadeschi 2015 # Distributed under the Boost Software License, Version 1.0. # (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt) # # Detects the C++ compiler, system, build-type, etc. include(CheckCXXCompilerFlag) if("x${CMAKE_CXX_COMPILER_ID}" MATCHES "x.*Clang") if("x${CMAKE_CXX_SIMULATE_ID}" STREQUAL "xMSVC") set (RANGES_CXX_COMPILER_CLANGC2 TRUE) if (RANGES_VERBOSE_BUILD) message("[range-v3]: compiler is clangC2.") endif() else() set (RANGES_CXX_COMPILER_CLANG TRUE) if (RANGES_VERBOSE_BUILD) message("[range-v3]: compiler is clang.") endif() endif() elseif(CMAKE_COMPILER_IS_GNUCXX) set (RANGES_CXX_COMPILER_GCC TRUE) if (RANGES_VERBOSE_BUILD) message("[range-v3]: compiler is gcc.") endif() else() message("[range-v3 warning]: unknown compiler ${CMAKE_CXX_COMPILER_ID} !") endif() if(CMAKE_SYSTEM_NAME MATCHES "Darwin") set (RANGES_ENV_MACOSX TRUE) if (RANGES_VERBOSE_BUILD) message("[range-v3]: system is MacOSX.") endif() elseif(CMAKE_SYSTEM_NAME MATCHES "Linux") set (RANGES_ENV_LINUX TRUE) if (RANGES_VERBOSE_BUILD) message("[range-v3]: system is Linux.") endif() elseif(CMAKE_SYSTEM_NAME MATCHES "Windows") set (RANGES_ENV_WINDOWS TRUE) if (RANGES_VERBOSE_BUILD) message("[range-v3]: system is Windows.") endif() else() message("[range-v3 warning]: unknown system ${CMAKE_SYSTEM_NAME} !") endif() # Clang/C2 will blow up with various parts of the standard library # if compiling with -std less than c++14. if ((RANGES_CXX_COMPILER_CLANGC2) AND (RANGES_CXX_STD EQUAL 11)) set(CMAKE_CXX_STANDARD 14) set(RANGES_CXX_STD 14) endif() # Build type set(RANGES_DEBUG_BUILD FALSE) set(RANGES_RELEASE_BUILD FALSE) if (CMAKE_BUILD_TYPE STREQUAL "Debug") set(RANGES_DEBUG_BUILD TRUE) if (RANGES_VERBOSE_BUILD) message("[range-v3]: build type is debug.") endif() elseif(CMAKE_BUILD_TYPE STREQUAL "Release") set(RANGES_RELEASE_BUILD TRUE) if (RANGES_VERBOSE_BUILD) message("[range-v3]: build type is release.") endif() else() message("[range-v3 warning]: unknown build type, defaults to release!") set(CMAKE_BUILD_TYPE "Release") set(RANGES_RELEASE_BUILD TRUE) endif() # Find Valgrind find_program(MEMORYCHECK_COMMAND valgrind) if(MEMORYCHECK_COMMAND) set(MEMORYCHECK_COMMAND_OPTIONS "--trace-children=yes --leak-check=full") if (RANGES_VERBOSE_BUILD) message("[range-v3]: valgrind found at path: ${MEMORYCHECK_COMMAND}") endif() else() if (RANGES_VERBOSE_BUILD) message("[range-v3 warning]: valgrind not found!") endif() endif() find_package(Doxygen) find_package(Git) range-v3-0.3.5/cmake/ranges_flags.cmake000066400000000000000000000160771324212031100176560ustar00rootroot00000000000000# Copyright Louis Dionne 2015 # Copyright Gonzalo Brito Gadeschi 2015 # Distributed under the Boost Software License, Version 1.0. # (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt) # # Setup compiler flags (more can be set on a per-target basis or in # subdirectories) # Compilation flags include(CheckCXXCompilerFlag) macro(ranges_append_flag testname flag ${ARGN}) check_cxx_compiler_flag("${flag} ${ARGN}" ${testname}) if (${testname}) add_compile_options(${flag} ${ARGN}) endif() endmacro() # All compilation flags # Language flag: version of the C++ standard to use message("[range-v3]: C++ std=${RANGES_CXX_STD}") ranges_append_flag(RANGES_HAS_CXXSTD "-std=c++${RANGES_CXX_STD}") # Enable "normal" warnings and make them errors: ranges_append_flag(RANGES_HAS_WERROR -Werror) ranges_append_flag(RANGES_HAS_WX -WX) ranges_append_flag(RANGES_HAS_WALL -Wall) ranges_append_flag(RANGES_HAS_WEXTRA -Wextra) if (RANGES_ENV_LINUX AND RANGES_CXX_COMPILER_CLANG) # On linux libc++ re-exports the system math headers. The ones from libstdc++ # use the GCC __extern_always_inline intrinsic which is not supported by clang # versions 3.6, 3.7, 3.8, 3.9, 4.0, and current trunk 5.0 (as of 2017.04.13). # # This works around it by replacing __extern_always_inline with inline using a # macro: ranges_append_flag(RANGES_HAS_D__EXTERN_ALWAYS_INLINE -D__extern_always_inline=inline) endif() # Template diagnostic flags ranges_append_flag(RANGES_HAS_FDIAGNOSTIC_SHOW_TEMPLATE_TREE -fdiagnostics-show-template-tree) ranges_append_flag(RANGES_HAS_FTEMPLATE_BACKTRACE_LIMIT "-ftemplate-backtrace-limit=0") # Clang modules support if (RANGES_MODULES) ranges_append_flag(RANGES_HAS_MODULES -fmodules) ranges_append_flag(RANGES_HAS_MODULE_MAP_FILE "-fmodule-map-file=${PROJECT_SOURCE_DIR}/include/module.modulemap") ranges_append_flag(RANGES_HAS_MODULE_CACHE_PATH "-fmodules-cache-path=${PROJECT_BINARY_DIR}/module.cache") if (RANGES_LIBCXX_MODULE) ranges_append_flag(RANGES_HAS_LIBCXX_MODULE_MAP_FILE "-fmodule-map-file=${RANGES_LIBCXX_MODULE}") endif() if (RANGES_ENV_MACOSX) ranges_append_flag(RANGES_HAS_NO_IMPLICIT_MODULE_MAPS -fno-implicit-module-maps) endif() if (RANGES_DEBUG_BUILD) ranges_append_flag(RANGES_HAS_GMODULES -gmodules) endif() endif() # Sanitizer support: detect incompatible sanitizer combinations if (RANGES_ASAN AND RANGES_MSAN) message(FATAL_ERROR "[range-v3 error]: AddressSanitizer and MemorySanitizer are both enabled at the same time!") endif() if (RANGES_MSAN AND RANGES_ENV_MACOSX) message(FATAL_ERROR "[range-v3 error]: MemorySanitizer is not supported on MacOSX!") endif() # AddressSanitizer support if (RANGES_ASAN) # This policy enables passing the linker flags to the linker when trying to # test the features, which is required to successfully link ASan binaries cmake_policy(SET CMP0056 NEW) set (ASAN_FLAGS "") if (RANGES_ENV_MACOSX) # LeakSanitizer not supported on MacOSX set (ASAN_FLAGS "-fsanitize=address,integer,undefined,nullability") else() if (RANGES_CXX_COMPILER_CLANG AND CMAKE_CXX_COMPILER_VERSION VERSION_LESS "4.0") set (ASAN_FLAGS "-fsanitize=address") else() set (ASAN_FLAGS "-fsanitize=address,integer,undefined,leak,nullability") endif() endif() ranges_append_flag(RANGES_HAS_ASAN "${ASAN_FLAGS}") if (RANGES_HAS_ASAN) #ASAN flags must be passed to the linker: set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} ${ASAN_FLAGS}") endif() ranges_append_flag(RANGES_HAS_SANITIZE_NO_RECOVER "-fno-sanitize-recover=all") ranges_append_flag(RANGES_HAS_NO_OMIT_FRAME_POINTER -fno-omit-frame-pointer) endif() # MemorySanitizer support if (RANGES_MSAN) # This policy enables passing the linker flags to the linker when trying to # compile the examples, which is required to successfully link MSan binaries cmake_policy(SET CMP0056 NEW) ranges_append_flag(RANGES_HAS_MSAN "-fsanitize=memory") ranges_append_flag(RANGES_HAS_MSAN_TRACK_ORIGINS -fsanitize-memory-track-origins) ranges_append_flag(RANGES_HAS_SANITIZE_RECOVER_ALL "-fno-sanitize-recover=all") ranges_append_flag(RANGES_HAS_NO_OMIT_FRAME_POINTER -fno-omit-frame-pointer) endif() # Build types: if (RANGES_DEBUG_BUILD AND RANGES_RELEASE_BUILD) message(FATAL_ERROR "[range-v3 error] Cannot simultaneously generate debug and release builds!") endif() if (RANGES_DEBUG_BUILD) ranges_append_flag(RANGES_HAS_O0 -O0) ranges_append_flag(RANGES_HAS_NO_INLINE -fno-inline) ranges_append_flag(RANGES_HAS_STACK_PROTECTOR_ALL -fstack-protector-all) ranges_append_flag(RANGES_HAS_G3 -g3) # Clang can generate debug info tuned for LLDB or GDB if (RANGES_CXX_COMPILER_CLANG) if (RANGES_ENV_MACOSX) ranges_append_flag(RANGES_HAS_GLLDB -glldb) elseif(RANGES_ENV_LINUX) ranges_append_flag(RANGES_HAS_GGDB -ggdb) endif() endif() endif() if (RANGES_RELEASE_BUILD) if (NOT RANGES_ASSERTIONS) ranges_append_flag(RANGES_HAS_DNDEBUG -DNDEBUG) endif() if (NOT RANGES_ASAN AND NOT RANGES_MSAN) # The quality of ASan and MSan error messages suffers if we disable the # frame pointer, so leave it enabled when compiling with either of them: ranges_append_flag(RANGES_HAS_OMIT_FRAME_POINTER -fomit-frame-pointer) endif() ranges_append_flag(RANGES_HAS_OFAST -Ofast) if (NOT RANGES_HAS_OFAST) ranges_append_flag(RANGES_HAS_O2 -O2) endif() ranges_append_flag(RANGES_HAS_STRICT_ALIASING -fstrict-aliasing) if (NOT RANGES_CXX_COMPILER_CLANGC2) ranges_append_flag(RANGES_HAS_STRICT_VTABLE_POINTERS -fstrict-vtable-pointers) endif() ranges_append_flag(RANGES_HAS_FAST_MATH -ffast-math) ranges_append_flag(RANGES_HAS_VECTORIZE -fvectorize) if (NOT RANGES_ENV_MACOSX) # Sized deallocation is not available in MacOSX: ranges_append_flag(RANGES_HAS_SIZED_DEALLOCATION -fsized-deallocation) endif() if (RANGES_LLVM_POLLY) set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -mllvm -polly -mllvm -polly-vectorizer=stripmine") endif() if (RANGES_CXX_COMPILER_CLANG AND (NOT (RANGES_INLINE_THRESHOLD EQUAL -1))) set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -mllvm -inline-threshold=${RANGES_INLINE_THRESHOLD}") endif() endif() if (RANGES_NATIVE) ranges_append_flag(RANGES_HAS_MARCH_NATIVE "-march=native") ranges_append_flag(RANGES_HAS_MTUNE_NATIVE "-mtune=native") endif() if (RANGES_VERBOSE_BUILD) message("[range-v3]: C++ flags: ${CMAKE_CXX_FLAGS}") message("[range-v3]: C++ debug flags: ${CMAKE_CXX_FLAGS_DEBUG}") message("[range-v3]: C++ Release Flags: ${CMAKE_CXX_FLAGS_RELEASE}") message("[range-v3]: C++ Compile Flags: ${CMAKE_CXX_COMPILE_FLAGS}") message("[range-v3]: Compile options: ${COMPILE_OPTIONS_}") message("[range-v3]: C Flags: ${CMAKE_C_FLAGS}") message("[range-v3]: C Compile Flags: ${CMAKE_C_COMPILE_FLAGS}") message("[range-v3]: EXE Linker flags: ${CMAKE_EXE_LINKER_FLAGS}") message("[range-v3]: C++ Linker flags: ${CMAKE_CXX_LINK_FLAGS}") message("[range-v3]: MODULE Linker flags: ${CMAKE_MODULE_LINKER_FLAGS}") get_directory_property(CMakeCompDirDefs COMPILE_DEFINITIONS) message("[range-v3]: Compile Definitions: ${CmakeCompDirDefs}") endif() range-v3-0.3.5/cmake/ranges_options.cmake000066400000000000000000000023511324212031100202430ustar00rootroot00000000000000# Copyright Gonzalo Brito Gadeschi 2015 # Distributed under the Boost Software License, Version 1.0. # (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt) # # CMake options include(CMakeDependentOption) set(RANGES_CXX_STD 11 CACHE STRING "C++ standard version.") option(RANGE_V3_NO_HEADER_CHECK "Build all headers." OFF) option(RANGE_BUILD_CALENDAR_EXAMPLE "Builds the calendar example." ON) option(RANGES_ASAN "Run the tests using AddressSanitizer." OFF) option(RANGES_MSAN "Run the tests using MemorySanitizer." OFF) option(RANGES_ASSERTIONS "Enable assertions." ON) option(RANGES_DEBUG_INFO "Include debug information in the binaries." ON) option(RANGES_MODULES "Enables the Modules TS." OFF) option(RANGES_NATIVE "Enables -march/-mtune=native." ON) option(RANGES_VERBOSE_BUILD "Enables debug output from CMake." OFF) option(RANGES_LLVM_POLLY "Enables LLVM Polly." OFF) set(RANGES_INLINE_THRESHOLD -1 CACHE STRING "Force a specific inlining threshold.") # Enable verbose configure when passing -Wdev to CMake if (DEFINED CMAKE_SUPPRESS_DEVELOPER_WARNINGS AND NOT CMAKE_SUPPRESS_DEVELOPER_WARNINGS) set(RANGES_VERBOSE_BUILD ON) endif() if (RANGES_VERBOSE_BUILD) message("[range-v3]: verbose build enabled.") endif() range-v3-0.3.5/cmake/readme.md000066400000000000000000000003501324212031100157630ustar00rootroot00000000000000# CMake files overview: - `ranges_options.cmake`: All options to configure the library. - `ranges_env.cmake`: Detects the environment: operating system, compiler, build-type, ... - `ranges_flags.cmake`: Sets up all compiler flags. range-v3-0.3.5/cmake/thread_test_code.cpp000066400000000000000000000001221324212031100202050ustar00rootroot00000000000000#include int main() { return (void)std::this_thread::get_id(), 0; } range-v3-0.3.5/conanfile.py000066400000000000000000000015271324212031100154430ustar00rootroot00000000000000# Range v3 library # # Copyright Luis Martinez de Bartolome Izquierdo 2016 # # Use, modification and distribution is subject to the # Boost Software License, Version 1.0. (See accompanying # file LICENSE_1_0.txt or copy at # http://www.boost.org/LICENSE_1_0.txt) # # Project home: https://github.com/ericniebler/range-v3 # from conans import ConanFile class Rangev3Conan(ConanFile): name = "range-v3" version = "0.3.5" license = "Boost Software License - Version 1.0 - August 17th, 2003" url = "https://github.com/ericniebler/range-v3" description = """Experimental range library for C++11/14/17""" exports_sources = "include*", "LICENSE.txt" def package(self): self.copy("*.hpp", src="include", dst="include", keep_path=True) self.copy("LICENSE.txt", dst="licenses", ignore_case=True, keep_path=False) range-v3-0.3.5/conanfile.py.in000066400000000000000000000015441324212031100160470ustar00rootroot00000000000000# Range v3 library # # Copyright Luis Martinez de Bartolome Izquierdo 2016 # # Use, modification and distribution is subject to the # Boost Software License, Version 1.0. (See accompanying # file LICENSE_1_0.txt or copy at # http://www.boost.org/LICENSE_1_0.txt) # # Project home: https://github.com/ericniebler/range-v3 # from conans import ConanFile class Rangev3Conan(ConanFile): name = "range-v3" version = "@RANGE_V3_VERSION@" license = "Boost Software License - Version 1.0 - August 17th, 2003" url = "https://github.com/ericniebler/range-v3" description = """Experimental range library for C++11/14/17""" exports_sources = "include*", "LICENSE.txt" def package(self): self.copy("*.hpp", src="include", dst="include", keep_path=True) self.copy("LICENSE.txt", dst="licenses", ignore_case=True, keep_path=False) range-v3-0.3.5/doc/000077500000000000000000000000001324212031100136735ustar00rootroot00000000000000range-v3-0.3.5/doc/CMakeLists.txt000066400000000000000000000044421324212031100164370ustar00rootroot00000000000000#============================================================================= # Setup the documentation #============================================================================= if (NOT DOXYGEN_FOUND) message(STATUS "Doxygen not found; the 'doc' and 'gh-pages.{clean,copy,update}' targets " "will be unavailable.") return() endif() configure_file(Doxyfile.in Doxyfile @ONLY) add_custom_target(doc.check COMMAND ${DOXYGEN_EXECUTABLE} Doxyfile COMMENT "Running Doxygen to validate the documentation" VERBATIM ) # if (NOT TARGET benchmarks) # message(STATUS # "The 'benchmarks' target is not available; the 'doc' and " # "'gh-pages.{clean,copy,update}' targets will be unavailable. " # "The 'doc.check' target can still be used to generate the " # "documentation to check for errors/warnings.") # return() # endif() add_custom_target(doc COMMAND ${DOXYGEN_EXECUTABLE} Doxyfile COMMENT "Generating API documentation with Doxygen" # DEPENDS benchmarks VERBATIM ) if (NOT GIT_FOUND) message(STATUS "Git was not found; the 'gh-pages.{clean,copy,update}' targets " "will be unavailable.") return() endif() add_custom_target(gh-pages.clean COMMAND ${CMAKE_COMMAND} -P ${CMAKE_CURRENT_LIST_DIR}/clean-gh-pages.cmake COMMAND ${CMAKE_COMMAND} -E remove_directory search WORKING_DIRECTORY ${CMAKE_CURRENT_LIST_DIR}/gh-pages COMMENT "Cleaning up doc/gh-pages" VERBATIM ) add_custom_target(gh-pages.copy COMMAND ${CMAKE_COMMAND} -E copy_directory ${CMAKE_CURRENT_BINARY_DIR}/html ${CMAKE_CURRENT_LIST_DIR}/gh-pages WORKING_DIRECTORY ${CMAKE_CURRENT_LIST_DIR}/gh-pages COMMENT "Copying the documentation from ${CMAKE_CURRENT_BINARY_DIR}/html to doc/gh-pages" DEPENDS doc gh-pages.clean VERBATIM ) execute_process( COMMAND ${GIT_EXECUTABLE} -C ${CMAKE_SOURCE_DIR} rev-parse --short HEAD OUTPUT_VARIABLE RANGE_V3_GIT_SHORT_SHA OUTPUT_STRIP_TRAILING_WHITESPACE ) add_custom_target(gh-pages.update COMMAND ${GIT_EXECUTABLE} add --all . COMMAND ${GIT_EXECUTABLE} commit -m "Update to ${RANGE_V3_GIT_SHORT_SHA}" WORKING_DIRECTORY ${CMAKE_CURRENT_LIST_DIR}/gh-pages COMMENT "Updating the gh-pages branch with freshly built documentation" DEPENDS gh-pages.copy VERBATIM ) range-v3-0.3.5/doc/Doxyfile.in000066400000000000000000000077051324212031100160170ustar00rootroot00000000000000PROJECT_NAME = "Range-v3" PROJECT_BRIEF = "Range algorithms, views, and actions for the Standard Library" PROJECT_LOGO = PROJECT_NUMBER = STRIP_FROM_PATH = @Range-v3_SOURCE_DIR@/include BUILTIN_STL_SUPPORT = YES STRIP_FROM_INC_PATH = @Range-v3_SOURCE_DIR@/include ALIASES = ENABLED_SECTIONS = # Resources OUTPUT_DIRECTORY = INPUT = @Range-v3_SOURCE_DIR@/include \ @Range-v3_SOURCE_DIR@/doc/index.md FILE_PATTERNS = *.hpp *.md RECURSIVE = YES EXCLUDE = @Range-v3_SOURCE_DIR@/include/range/v3/detail \ @Range-v3_SOURCE_DIR@/include/range/v3/algorithm/aux_ \ @Range-v3_SOURCE_DIR@/include/range/v3/utility/safe_int.hpp EXAMPLE_PATH = @Range-v3_SOURCE_DIR@/example \ @Range-v3_SOURCE_DIR@/test EXAMPLE_RECURSIVE = YES IMAGE_PATH = @Range-v3_BINARY_DIR@/image WARN_IF_UNDOCUMENTED = NO SHOW_GROUPED_MEMB_INC = YES BRIEF_MEMBER_DESC = YES REPEAT_BRIEF = YES ALWAYS_DETAILED_SEC = NO INLINE_INHERITED_MEMB = NO JAVADOC_AUTOBRIEF = YES QT_AUTOBRIEF = YES MULTILINE_CPP_IS_BRIEF = YES INHERIT_DOCS = NO SEPARATE_MEMBER_PAGES = NO DISTRIBUTE_GROUP_DOC = NO SUBGROUPING = NO INLINE_GROUPED_CLASSES = NO INLINE_SIMPLE_STRUCTS = NO # Generated formats GENERATE_HTML = YES GENERATE_LATEX = NO GENERATE_TODOLIST = YES GENERATE_TESTLIST = YES GENERATE_BUGLIST = YES GENERATE_DEPRECATEDLIST = YES SHOW_USED_FILES = NO SHOW_FILES = YES SHOW_NAMESPACES = YES LAYOUT_FILE = @Range-v3_SOURCE_DIR@/doc/layout.xml CLASS_DIAGRAMS = YES HAVE_DOT = NO HIDE_UNDOC_RELATIONS = NO HIDE_UNDOC_MEMBERS = NO HIDE_UNDOC_CLASSES = NO HIDE_FRIEND_COMPOUNDS = NO HIDE_IN_BODY_DOCS = NO INTERNAL_DOCS = NO HIDE_SCOPE_NAMES = NO SHOW_INCLUDE_FILES = NO FORCE_LOCAL_INCLUDES = NO INLINE_INFO = NO SORT_MEMBER_DOCS = YES SORT_BRIEF_DOCS = YES SORT_MEMBERS_CTORS_1ST = NO SORT_GROUP_NAMES = NO SORT_BY_SCOPE_NAME = YES ALPHABETICAL_INDEX = NO COLS_IN_ALPHA_INDEX = 1 # Preprocessing ENABLE_PREPROCESSING = YES MACRO_EXPANSION = YES EXPAND_ONLY_PREDEF = NO SEARCH_INCLUDES = YES INCLUDE_PATH = @Range-v3_SOURCE_DIR@/include INCLUDE_FILE_PATTERNS = PREDEFINED = RANGES_DOXYGEN_INVOKED \ CONCEPT_REQUIRES_=requires= \ "CONCEPT_REQUIRES(X)=/// \pre X" \ "RANGES_INLINE_VARIABLE(T,N)=inline constexpr T N{};" SKIP_FUNCTION_MACROS = NO # Source browsing SOURCE_BROWSER = NO INLINE_SOURCES = NO STRIP_CODE_COMMENTS = YES REFERENCED_BY_RELATION = YES REFERENCES_RELATION = YES REFERENCES_LINK_SOURCE = YES USE_HTAGS = NO VERBATIM_HEADERS = NO # CLANG_ASSISTED_PARSING = NO # CLANG_OPTIONS = # HTML output HTML_OUTPUT = html HTML_FILE_EXTENSION = .html HTML_HEADER = HTML_FOOTER = HTML_EXTRA_STYLESHEET = HTML_EXTRA_FILES = HTML_COLORSTYLE_HUE = 75 # 0 - 359 HTML_COLORSTYLE_SAT = 100 # 0 - 255 HTML_COLORSTYLE_GAMMA = 80 HTML_TIMESTAMP = NO HTML_DYNAMIC_SECTIONS = YES HTML_INDEX_NUM_ENTRIES = 0 # Fully expand trees in the Indexes by default DISABLE_INDEX = YES GENERATE_TREEVIEW = YES TREEVIEW_WIDTH = 270 EXT_LINKS_IN_WINDOW = NO FORMULA_FONTSIZE = 10 FORMULA_TRANSPARENT = YES SEARCHENGINE = YES # Mathjax (HTML only) USE_MATHJAX = NO MATHJAX_FORMAT = HTML-CSS MATHJAX_RELPATH = http://cdn.mathjax.org/mathjax/latest MATHJAX_EXTENSIONS = MATHJAX_CODEFILE = range-v3-0.3.5/doc/clean-gh-pages.cmake000066400000000000000000000002211324212031100174430ustar00rootroot00000000000000FILE(GLOB gh_files "*.html" "*.js" "*.css" "*.png") IF( gh_files ) execute_process( COMMAND ${CMAKE_COMMAND} -E remove ${gh_files} ) ENDIF() range-v3-0.3.5/doc/gh-pages/000077500000000000000000000000001324212031100153665ustar00rootroot00000000000000range-v3-0.3.5/doc/index.md000066400000000000000000000704301324212031100153300ustar00rootroot00000000000000User Manual {#mainpage} =========== \tableofcontents \section tutorial-preface Preface -------------------------------------------- Range library for C++11/14/17. This code is the basis of [a formal proposal](https://ericniebler.github.io/std/wg21/D4128.html) to add range support to the C++ standard library. **Development Status:** This code is fairly stable, well-tested, and suitable for casual use, although currently lacking documentation. No promise is made about support or long-term stability. This code *will* evolve without regard to backwards compatibility. \subsection tutorial-installation Installation -------------------------------------------- This library is header-only. You can get the source code from the [range-v3 repository](https://github.com/ericniebler/range-v3) on github. To compile with Range-v3, you can either `#%include` the entire library: ~~~~~~~{.cpp} #include ~~~~~~~ Or you can `#%include` only the core, and then the individual headers you want: ~~~~~~~{.cpp} #include #include v{/*...*/}; std::sort( v.begin(), v.end() ); ~~~~~~~ with ~~~~~~~{.cpp} std::vector v{/*...*/}; ranges::sort( v ); ~~~~~~~ Range v3 contains a full implementation of all the standard algorithms with range-based overloads for convenience. ### Composability Having a single range object permits *pipelines* of operations. In a pipeline, a range is lazily adapted or eagerly mutated in some way, with the result immediately available for further adaptation or mutation. Lazy adaption is handled by *views*, and eager mutation is handled by *actions*. #### Views A view is a lightweight wrapper that presents a view of an underlying sequence of elements in some custom way without mutating or copying it. Views are cheap to create and copy, and have non-owning reference semantics. Below are some examples: Filter a container using a predicate and transform it. ~~~~~~~{.cpp} std::vector vi{1,2,3,4,5,6,7,8,9,10}; using namespace ranges; auto rng = vi | view::remove_if([](int i){return i % 2 == 1;}) | view::transform([](int i){return std::to_string(i);}); // rng == {"2","4","6","8","10"}; ~~~~~~~ Generate an infinite list of integers starting at 1, square them, take the first 10, and sum them: ~~~~~~~{.cpp} using namespace ranges; int sum = accumulate(view::ints(1) | view::transform([](int i){return i*i;}) | view::take(10), 0); ~~~~~~~ Generate a sequence on the fly with a range comprehension and initialize a vector with it: ~~~~~~~{.cpp} using namespace ranges; std::vector vi = view::for_each(view::ints(1,10), [](int i){ return yield_from(view::repeat_n(i,i)); }); // vi == {1,2,2,3,3,3,4,4,4,4,5,5,5,5,5,...} ~~~~~~~ #### Actions When you want to mutate a container in-place, or forward it through a chain of mutating operations, you can use actions. The following examples should make it clear. Read data into a vector, sort it, and make it unique. ~~~~~~~{.cpp} extern std::vector read_data(); using namespace ranges; std::vector vi = read_data() | action::sort | action::unique; ~~~~~~~ Do the same to a `vector` that already contains some data: ~~~~~~~{.cpp} vi = std::move(vi) | action::sort | action::unique; ~~~~~~~ Mutate the container in-place: ~~~~~~~{.cpp} vi |= action::sort | action::unique; ~~~~~~~ Same as above, but with function-call syntax instead of pipe syntax: ~~~~~~~{.cpp} action::unique(action::sort(vi)); ~~~~~~~ ## Create Custom Ranges Range v3 provides a utility for easily creating your own range types, called \link ranges::v3::view_facade `ranges::view_facade`\endlink. The code below uses `view_facade` to create a range that traverses a null-terminated string: ~~~~~~~{.cpp} #include // A range that iterates over all the characters in a // null-terminated string. class c_string_range : public ranges::view_facade { friend ranges::range_access; char const * sz_ = ""; char const & read() const { return *sz_; } bool equal(ranges::default_sentinel) const { return *sz_ == '\0'; } void next() { ++sz_; } public: c_string_range() = default; explicit c_string_range(char const *sz) : sz_(sz) { assert(sz != nullptr); } }; ~~~~~~~ The `view_facade` class generates an iterator and begin/end member functions from the minimal interface provided by `c_string_range`. This is an example of a very simple range for which it is not necessary to separate the range itself from the thing that iterates the range. Future examples will show examples of more sophisticated ranges. With `c_string_range`, you can now use algorithms to operate on null-terminated strings, as below: ~~~~~~~{.cpp} #include int main() { c_string_range r("hello world"); // Iterate over all the characters and print them out ranges::for_each(r, [](char ch){ std::cout << ch << ' '; }); // prints: h e l l o w o r l d } ~~~~~~~ ## Adapting Ranges Often, a new range type is most easily expressed by adapting an existing range type. That's the case for many of the range views provided by the Range v3 library; for example, the `view::remove_if` and `view::transform` views. These are rich types with many moving parts, but thanks to a helper class called \link ranges::v3::view_adaptor `ranges::view_adaptor`\endlink, they aren't hard to write. Below in roughly 2 dozen lines of code is the `transform` view, which takes one range and transforms all the elements with a unary function. ~~~~~~~{.cpp} #include // A class that adapts an existing range with a function template class transform_view : public ranges::view_adaptor, Rng> { friend ranges::range_access; ranges::semiregular_t fun_; // Make Fun model SemiRegular if it doesn't class adaptor : public ranges::adaptor_base { ranges::semiregular_t fun_; public: adaptor() = default; adaptor(ranges::semiregular_t const &fun) : fun_(fun) {} // Here is where we apply Fun to the elements: auto read(ranges::iterator_t it) const -> decltype(fun_(*it)) { return fun_(*it); } }; adaptor begin_adaptor() const { return {fun_}; } adaptor end_adaptor() const { return {fun_}; } public: transform_view() = default; transform_view(Rng && rng, Fun fun) : transform_view::view_adaptor{std::forward(rng)} , fun_(std::move(fun)) {} }; template transform_view transform(Rng && rng, Fun fun) { return {std::forward(rng), std::move(fun)}; } ~~~~~~~ Range transformation is achieved by defining a nested `adaptor` class that handles the transformation, and then defining `begin_adaptor` and `end_adaptor` members that return adaptors for the begin iterator and the end sentinel, respectively. The `adaptor` class has a `read` member that performs the transformation. It is passed an iterator to the current element. Other members are available for customization: `equal`, `next`, `prev`, `advance`, and `distance_to`; but the transform adaptor accepts the defaults defined in \link ranges::v3::adaptor_base `ranges::adaptor_base`\endlink. With `transform_view`, we can print out the first 20 squares: ~~~~~~~{.cpp} int main() { auto squares = ::transform(view::ints(1), [](int i){return i*i;}); for(int i : squares | view::take(20)) std::cout << i << ' '; std::cout << '\n'; // prints 1 4 9 16 25 36 49 64 81 100 121 144 169 196 225 256 289 324 361 400 } ~~~~~~~ The `transform_view` defined above is an InputRange when it's wrapping an InputRange, a ForwardRange when it's wrapping a ForwardRange, etc. That happens because of smart defaults defined in the `adaptor_base` class. That frees you from having to deal with a host of niggly detail when implementing iterators. *(Note: the above `transform_view` always stores a copy of the function in the sentinel. That is only necessary if the underlying range's sentinel type models BidirectionalIterator. That's a finer point that you shouldn't worry about right now.)* ## Constrain Functions with Concepts The Range v3 library makes heavy use of concepts to constrain functions, control overloading, and check type constraints at compile-time. It achieves this with the help of a Concepts Lite emulation layer that works on any standard-conforming C++11 compiler. The library provides many useful concepts, both for the core language and for iterators and ranges. You can use the concepts framework to constrain your own code. For instance, if you would like to write a function that takes an iterator/sentinel pair, you can write it like this: ~~~~~~~{.cpp} template())> void my_algorithm(Iter first, Sent last, Comp comp = Comp{}) { // ... } ~~~~~~~ You can then add an overload that take a Range: ~~~~~~~{.cpp} template())> void my_algorithm(Rng && rng, Comp comp = Comp{}) { return my_algorithm(ranges::begin(rng), ranges::end(rng)); } ~~~~~~~ With the type constraints expressed with the `CONCEPTS_REQUIRES_` macro, these two overloads are guaranteed to not be ambiguous. ## Range v3 and the Future Range v3 forms the basis for a proposal to add ranges to the standard library ([N4128](http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4128.html)), and is also be the basis for a Technical Specification on Ranges. The Technical Specification contains many of Range v3's concept definitions (translated into the actual syntax of C++20 Concepts) in addition to constrained versions of the STL algorithms overloaded both for iterator/sentinel pairs and for ranges. The Ranges TS has already been sent to ISO for publication. The views and actions, as well as various utilities, have not yet been reviewed by the committee, although the basic direction has already passed an initial review. A proposal to add a subset of the views to the Ranges TS is in the early stages. \section range-views Range Views -------------------------------------------- The big advantage of ranges over iterators is their *composability*. They permit a functional style of programming where data is manipulated by passing it through a series of combinators. In addition, the combinators can be *lazy*, only doing work when the answer is requested, and *purely functional*, without mutating the original data. This makes it easier to reason about your code, especially when writing concurrent programs. Below is a list of the lazy range combinators, or *views*, that Range v3 provides, and a blurb about how each is intended to be used.
\link ranges::v3::view::adjacent_filter_fn `view::adjacent_filter`\endlink
For each pair of adjacent elements in a source range, evaluate the specified binary predicate. If the predicate evaluates to false, the second element of the pair is removed from the result range; otherwise, it is included. The first element in the source range is always included. (For instance, `adjacent_filter` with `std::not_equal_to` filters out all the non-unique elements.)
\link ranges::v3::view::adjacent_remove_if_fn `view::adjacent_remove_if`\endlink
For each pair of adjacent elements in a source range, evaluate the specified binary predicate. If the predicate evaluates to true, the first element of the pair is removed from the result range; otherwise, it is included. The last element in the source range is always included.
\link ranges::v3::view::all_fn `view::all`\endlink
Return a range containing all the elements in the source. Useful for converting containers to ranges.
\link ranges::v3::any_view `any_view(rng)`\endlink
Type-erased range of elements with value type `T`; can store _any_ range with this value type.
\link ranges::v3::view::bounded_fn `view::bounded`\endlink
Convert the source range to a *bounded* range, where the type of the `end` is the same as the `begin`. Useful for iterating over a range with C++'s range-based `for` loop.
\link ranges::v3::view::cartesian_product_fn `view::cartesian_product`\endlink
Enumerates the n-ary cartesian product of `n` ranges, i.e., generates all `n`-tuples `(e1, e2, ... , en)` where `e1` is an element of the first range, `e2` is an element of the second range, etc.
\link ranges::v3::view::chunk_fn `view::chunk`\endlink
Given a source range and an integer *N*, produce a range of contiguous ranges where each inner range has *N* contiguous elements. The final range may have fewer than *N* elements.
\link ranges::v3::view::concat_fn `view::concat`\endlink
Given *N* source ranges, produce a result range that is the concatenation of all of them.
\link ranges::v3::view::const_fn `view::const_`\endlink
Present a `const` view of a source range.
\link ranges::v3::view::counted_fn `view::counted`\endlink
Given an iterator `it` and a count `n`, create a range that starts at `it` and includes the next `n` elements.
\link ranges::v3::view::cycle_fn `view::cycle`\endlink
Returns an infinite range that endlessly repeats the source range.
\link ranges::v3::view::c_str_fn `view::c_str`\endlink
View a `\0`-terminated C string (e.g. from a `const char*`) as a range.
\link ranges::v3::view::delimit_fn `view::delimit`\endlink
Given a source range and a value, return a new range that ends either at the end of the source or at the first occurrence of the value, whichever comes first. Alternatively, `view::delimit` can be called with an iterator and a value, in which case it returns a range that starts at the specified position and ends at the first occurrence of the value.
\link ranges::v3::view::drop_fn `view::drop`\endlink
Given a source range and an integral count, return a range consisting of all but the first *count* elements from the source range, or an empty range if it has fewer elements.
\link ranges::v3::view::drop_exactly_fn `view::drop_exactly`\endlink
Given a source range and an integral count, return a range consisting of all but the first *count* elements from the source range. The source range must have at least that many elements.
\link ranges::v3::view::drop_while_fn `view::drop_while`\endlink
Remove elements from the front of a range that satisfy a unary predicate.
\link ranges::v3::view::empty() `view::empty`\endlink
Create an empty range with a given value type.
\link ranges::v3::view::filter_fn `view::filter`\endlink
Given a source range and a unary predicate, filter the elements that satisfy the predicate. (For users of Boost.Range, this is like the `filter` adaptor.)
\link ranges::v3::view::for_each_fn `view::for_each`\endlink
Lazily applies an unary function to each element in the source range that returns another range (possibly empty), flattening the result.
\link ranges::v3::view::generate_fn `view::generate`\endlink
Given a nullary function, return an infinite range whose elements are generated with the function.
\link ranges::v3::view::generate_n_fn `view::generate_n`\endlink
Given a nullary function and a count, return a range that generates the requested number of elements by calling the function.
\link ranges::v3::view::group_by_fn `view::group_by`\endlink
Given a source range and a binary predicate, return a range of ranges where each range contains contiguous elements from the source range such that the following condition holds: for each element in the range apart from the first, when that element and the first element are passed to the binary predicate, the result is true. In essence, `view::group_by` *groups* contiguous elements together with a binary predicate.
\link ranges::v3::view::indirect_fn `view::indirect`\endlink
Given a source range of readable values (e.g. pointers or iterators), return a new view that is the result of dereferencing each.
\link ranges::v3::view::intersperse_fn `view::intersperse`\endlink
Given a source range and a value, return a new range where the value is inserted between contiguous elements from the source.
\link ranges::v3::view::ints_fn `view::ints`\endlink
Generate a range of monotonically increasing `int`s. When used without arguments, it generates the quasi-infinite range [0,1,2,3...]. It can also be called with a lower bound, or with a lower and upper bound (exclusive). An inclusive version is provided by `closed_ints`.
\link ranges::v3::view::iota_fn `view::iota`\endlink
A generalization of `view::ints` that generates a sequence of monotonically increasing values of any incrementable type. When specified with a single argument, the result is an infinite range beginning at the specified value. With two arguments, the values are assumed to denote a half-open range.
\link ranges::v3::view::join_fn `view::join`\endlink
Given a range of ranges, join them into a flattened sequence of elements. Optionally, you can specify a value or a range to be inserted between each source range.
\link ranges::v3::view::keys_fn `view::keys`\endlink
Given a range of `pair`s (like a `std::map`), return a new range consisting of just the first element of the `pair`.
\link ranges::v3::view::linear_distribute_fn `view::linear_distribute`\endlink
Distributes `n` values linearly in the closed interval `[from, to]` (the end points are always included). If `from == to`, returns `n`-times `to`, and if `n == 1` it returns `to`.
\link ranges::v3::view::move_fn `view::move`\endlink
Given a source range, return a new range where each element has been has been cast to an rvalue reference.
\link ranges::v3::view::partial_sum_fn `view::partial_sum`\endlink
Given a range and a binary function, return a new range where the *N*th element is the result of applying the function to the *N*th element from the source range and the (N-1)th element from the result range.
\link ranges::v3::view::remove_if_fn `view::remove_if`\endlink
Given a source range and a unary predicate, filter out those elements that do not satisfy the predicate. (For users of Boost.Range, this is like the `filter` adaptor with the predicate negated.)
\link ranges::v3::view::repeat_fn `view::repeat`\endlink
Given a value, create a range that is that value repeated infinitely.
\link ranges::v3::view::repeat_n_fn `view::repeat_n`\endlink
Given a value and a count, create a range that is that value repeated *count* number of times.
\link ranges::v3::view::replace_fn `view::replace`\endlink
Given a source range, a source value and a target value, create a new range where all elements equal to the source value are replaced with the target value.
\link ranges::v3::view::replace_if_fn `view::replace_if`\endlink
Given a source range, a unary predicate and a target value, create a new range where all elements that satisfy the predicate are replaced with the target value.
\link ranges::v3::view::reverse_fn `view::reverse`\endlink
Create a new range that traverses the source range in reverse order.
\link ranges::v3::view::sample_fn `view::sample`\endlink
Returns a random sample of a range of length `size(range)`.
\link ranges::v3::view::single_fn `view::single`\endlink
Given a value, create a range with exactly one element.
\link ranges::v3::view::slice_fn `view::slice`\endlink
Give a source range a lower bound (inclusive) and an upper bound (exclusive), create a new range that begins and ends at the specified offsets. Both the begin and the end can be integers relative to the front, or relative to the end with "`end-2`" syntax.
\link ranges::v3::view::sliding_fn `view::sliding`\endlink
Given a range and a count `n`, place a window over the first `n` elements of the underlying range. Return the contents of that window as the first element of the adapted range, then slide the window forward one element at a time until hitting the end of the underlying range.
\link ranges::v3::view::split_fn `view::split`\endlink
Given a source range and a delimiter specifier, split the source range into a range of ranges using the delimiter specifier to find the boundaries. The delimiter specifier can be a value, a subrange, a predicate, or a function. The predicate should take an single argument of the range's reference type and return true if and only if the element is part of a delimiter. The function should accept current/end iterators into the source range and return `make_pair(true, iterator_past_the_delimiter)` if the current position is a boundary; otherwise, `make_pair(false, cur)`. The delimiter character(s) are excluded from the resulting range of ranges.
\link ranges::v3::view::stride_fn `view::stride`\endlink
Given a source range and an integral stride value, return a range consisting of every *N*th element, starting with the first.
\link ranges::v3::view::tail_fn `view::tail`\endlink
Given a source range, return a new range without the first element. The range must have at least one element.
\link ranges::v3::view::take_fn `view::take`\endlink
Given a source range and an integral count, return a range consisting of the first *count* elements from the source range, or the complete range if it has fewer elements. (The result of `view::take` is not a `SizedRange`.)
\link ranges::v3::view::take_exactly_fn `view::take_exactly`\endlink
Given a source range and an integral count, return a range consisting of the first *count* elements from the source range. The source range must have at least that many elements. (The result of `view::take_exactly` is a `SizedRange`.)
\link ranges::v3::view::take_while_fn `view::take_while`\endlink
Given a source range and a unary predicate, return a new range consisting of the elements from the front that satisfy the predicate.
\link ranges::v3::view::tokenize_fn `view::tokenize`\endlink
Given a source range and optionally a submatch specifier and a `std::regex_constants::match_flag_type`, return a `std::regex_token_iterator` to step through the regex submatches of the source range. The submatch specifier may be either a plain `int`, a `std::vector`, or a `std::initializer_list`.
\link ranges::v3::view::transform_fn `view::transform`\endlink
Given a source range and a unary function, return a new range where each result element is the result of applying the unary function to a source element.
\link ranges::v3::view::unbounded_fn `view::unbounded`\endlink
Given an iterator, return an infinite range that begins at that position.
\link ranges::v3::view::unique_fn `view::unique`\endlink
Given a range, return a new range where all consecutive elements that compare equal save the first have been filtered out.
\link ranges::v3::view::values_fn `view::values`\endlink
Given a range of `pair`s (like a `std::map`), return a new range consisting of just the second element of the `pair`.
\link ranges::v3::view::zip_fn `view::zip`\endlink
Given *N* ranges, return a new range where *M*th element is the result of calling `make_tuple` on the *M*th elements of all *N* ranges.
\link ranges::v3::view::zip_with_fn `view::zip_with`\endlink
Given *N* ranges and a *N*-ary function, return a new range where *M*th element is the result of calling the function on the *M*th elements of all *N* ranges.
\section range-actions Range Actions -------------------------------------------- Below is a list of the eager range combinators, or *actions*, that Range v3 provides, and a blurb about how each is intended to be used.
\link ranges::v3::action::drop_fn `action::drop`\endlink
Removes the first `N` elements of the source range.
\link ranges::v3::action::drop_while_fn `action::drop_while`\endlink
Removes the first elements of the source range that satisfy the unary predicate.
`action::erase`
Removes all elements in the sub-range of the source (range version) or all elements after position.
`action::insert`
Inserts all elements of the range into the source at position.
\link ranges::v3::action::join_fn `action::join`\endlink
Flattens a range of ranges.
`action::push_back`
Appends elements to the tail of the source.
`action::push_front`
Appends elements before the head of the source.
\link ranges::v3::action::remove_if_fn `action::remove_if`\endlink
Removes all elements from the source that satisfy the predicate.
\link ranges::v3::action::shuffle_fn `action::shuffle`\endlink
Shuffles the source range.
\link ranges::v3::action::slice_fn `action::slice`\endlink
Removes all elements from the source that are not part of the sub-range.
\link ranges::v3::action::sort_fn `action::sort`\endlink
Sorts the source range (unstable).
\link ranges::v3::action::split_fn `action::split`\endlink
Split a range into a sequence of subranges using a delimiter (a value, a sequence of values, a predicate, or a binary function returning a `pair`).
\link ranges::v3::action::stable_sort_fn `action::stable_sort`\endlink
Sorts the source range (stable).
\link ranges::v3::action::stride_fn `action::stride`\endlink
Removes all elements whose position does not match the stride.
\link ranges::v3::action::take_fn `action::take`\endlink
Keeps the first `N`-th elements of the range, removes the rest.
\link ranges::v3::action::take_while_fn `action::take_while`\endlink
Keeps the first elements that satisfy the predicate, removes the rest.
\link ranges::v3::action::transform_fn `action::transform`\endlink
Replaces elements of the source with the result of the unary function.
`action::unique`
Removes adjacent elements of the source that compare equal. If the source is sorted, removes all duplicate elements.
\section example-section Examples \subsection example-hello hello ranges \snippet hello.cpp hello \subsection example-count count \snippet count.cpp count \subsection example-count_if count_if \snippet count_if.cpp count_if range-v3-0.3.5/doc/layout.xml000066400000000000000000000153611324212031100157400ustar00rootroot00000000000000 range-v3-0.3.5/doc/std/000077500000000000000000000000001324212031100144655ustar00rootroot00000000000000range-v3-0.3.5/doc/std/D4128.md000066400000000000000000003616651324212031100155320ustar00rootroot00000000000000--- pagetitle: Ranges for the Standard Library, Revision 1 title: Ranges for the Standard Library, Revision 1 ... Introduction ===== This paper outlines what support for ranges in the C++ standard library might look like. Rather than presenting a final design, this paper proposes a set of concepts and guidelines for using them to implement range-based versions of the standard algorithms. It draws inspiration from the [Boost.Range][2][@boostrange] library, the range algorithms in [Adobe Source Libraries][3][@asl], *Elements of Programming* by Stepanov and McJones (2009) [@stepanov09], and from [N3351 "A Concept Design for the STL"][8] by Stroustrup and Sutton (2012) [@n3351]. In addition to presenting the concepts and guidelines, this paper discusses the rationale behind each, weighing different design options. The decision to defer any discussion about specific wording was taken in recognition of the fact that any range design is likely to undergo significant revision by the committee. The paper is intended merely as a starting point for discussion and as a basis for future work. This paper assumes the availability of Concepts Lite; however, everything suggested here has been implemented in C++11, where Concepts Lite has been simulated with the help of generalized SFINAE for expressions. Motivation and Scope ===== A *range* is an object that refers to a sequence of elements, conceptually similar to a pair of iterators. One prime motivation for ranges is to give users a simpler syntax for calling algorithms. Rather than this: std::vector v { /*...*/ }; std::sort( v.begin(), v.end() ); Ranges would give us a pithier syntax: std::sort( v ); Allowing algorithms to take a single range object instead of separate begin and end iterators brings other benefits besides convenience. In particular: * It eliminates the possibility of mismatched iterators. * It opens the door to *range adaptors* which lazily transform or filter their underlying sequence in interesting ways. Range adaptors are far more compelling than iterator adaptors due to the fact that only a single object, the range object, needs to be adapted; hence, adaptors can be easily chained to create lazy computational pipelines, as in the code below which sums the first 10 squares: int total = accumulate(view::iota(1) | view::transform([](int x){return x*x;}) | view::take(10), 0); The standard defines the term "range" in [iterator.requirements.general]: > [...] in general, a range `[i,j)` refers to the elements in the data structure starting with the element pointed to by `i` and up to but not including the element pointed to by `j`. Range `[i,j)` is valid if and only if `j` is reachable from `i`. From the perspective of the standard library, a range *is* a pair of iterators. But there are other interesting ways to denote a range of elements: * An iterator and a count of elements * An iterator and a (possibly stateful) predicate that indicates when the range is exhausted. One of these three range types can be used to denote all other range types, like an iterator and a sentinel value (e.g. a null-terminated string), or a range that spans disjoint ranges. Ideally, we would like our Range abstraction to be general enough to accommodate the three different kinds of ranges since that would increase the applicability of the algorithms. ## Impact on the Standard Although this paper does not offer specific wording for any additions to the standard, we imagine that proper support for ranges in C++ would involve changes to the following parts of the standard: - New library-wide concepts related to ranges. - New iterator algorithms for efficiently dealing with the new abstractions. - Changes to existing algorithms to constrain the templates with concepts. - Additional overloads of existing algorithms that accept ranges instead of pairs of iterators. - Changes to the containers to allow containers to be constructed and assigned from ranges, and to allow range-based insert operations. - A new library section for range adaptors, which are views of existing data that have been transformed or filtered and that compose with other views. - General utilities for the construction of custom range adaptors. - A minor change to the specification of the range-based `for` to make it more efficient and general. Future papers will make specific recommendations for all of the above, modulo any feedback on the design presented here. Proposed Design ===== The design space for ranges is surprisingly large. At one end of the spectrum lies [Boost.Range][2][@boostrange] and [Adobe's ASL][3][@asl] in which ranges are a thin abstraction on top of iterators, which remain the primitives that glue together data structures and algorithms. At the other end of the spectrum we find the [D Standard Library's std.range module][4][@drange], in which ranges and operations on them are the primitives themselves. This proposal picks a single point in this design space, and here we present the decisions that led to the selection of that point, along with guidelines to be applied to the standard library and the rationale for each choice. ## Design Goals We feel that a well-designed range abstraction would: * Allow algorithms to operate on the three kinds of ranges with low or no abstraction penalty and a minimum of syntactic noise, * Allow range-based algorithms to share implementation with iterator-based algorithms, * Make it easy for users to reason about the complexity and expense of range operations (e.g. How many passes over the data are made? Are the elements copied? etc.), * Protect the user from lifetime issues, * Make it straightforward for users to make their types model one of the range concepts. It is helpful at this point to reflect on the success of C++11's range-based `for` loop. It succeeds because most of the types over which one would want to iterate already define iterators and `begin`/`end` members. Cleanly and efficiently interoperating with and reusing the existing abstractions of the STL is critical to the success of any range extensions. ## High-Level Design At the highest level, this paper proposes the addition of two related range concepts: Iterable and Range. An *Iterable* type is one for which we can call `begin()` and `end()` to yield an iterator/sentinel pair. (Sentinels are described below.) The Iterable concept says nothing about the type's constructibility or assignability. Range-based standard algorithms are constrained using the Iterable concept. Consider: int buf[5000]; // Fill buf std::sort( buf ); `buf` denotes a random access range of elements, so we should be able to sort it; but native arrays are neither copyable nor assignable, so these operations should not be required by whatever range-like concept is used to constrain `sort`. The above line of code is equivalent to: using std::begin; using std::end; std::sort( begin( buf ), end( buf ) ); For an Iterable object `o`, the concept requires the following: auto b = begin( o ); // b models Iterator auto e = end( o ); // e models Regular bool f = (b == e); // b and e model EqualityComparable Algorithms will typically be implemented to take iterator/sentinel pairs, rather than the iterator/iterator pairs as they do now. A typical algorithm might look like: template requires EqualityComparable I some_algo(I first, S last, /*...*/) { for(; first != last; ++first) /*...*/ return first; } template IteratorOf some_algo( R & r, /*...*/ ) { return some_algo( begin(r), end(r), /*...*/ ); } The *Range* concept is modeled by lightweight objects that denote a range of elements they do not own. A pair of iterators can be a model of Range, whereas a `vector` is not. Range, as opposed to Iterable, requires copyability and assignability. Copying and assignment are required to execute in constant time; that is, the cost of these operations is not proportional to the number of elements in the Range. The Range concept refines the Iterable concept by additionally requiring following valid expressions for an object `o` of type `O`: // Constructible: auto o1 = o; auto o2 = std::move(o); O o3; // default-constructed, singular // Assignable: o2 = o1; o2 = std::move(o1); // Destructible o.~O(); The Range concept exists to give the range adaptors consistent and predictable semantics, and memory and performance characteristics. Since adaptors allow the composition of range objects, those objects must be efficiently copyable (or at least movable). The result of adapting a Range is a Range. The result of adapting a container is also a Range; the container -- or any Iterable that is not already a Range -- is first converted to a Range automatically by taking the container's `begin` and `end`. The precise definitions of the suggested concepts are given in [Section 4](#concept-definitions), along with other supporting concepts that have proven useful while porting the algorithms. The use of sentinels instead of iterators as an Iterable's bound is best understood by seeing how the three different kinds of ranges can be made to model the Iterable concept. Below is a sketch of how `begin` and `end` might work for each kind. - **Pair of iterators**: An end iterator is a perfectly acceptable sentinel. Existing code that uses iterator pairs to call STL algorithms will continue working with no changes. - **Iterator and predicate**: `begin(rng)` can return a normal iterator, `first`. `end(rng)` can return a sentinel `last` such that `first == last` returns the result of calling `last.predicate_(*first)`. See [Appendix 1](#appendix-1-sentinels-and-code-generation) for a discussion about the code generation benefits of letting the sentinel have a different type than the iterator. - **Iterator and count**: `begin(rng)` can return an iterator `first` that bundles the underlying iterator with the count to the end. Incrementing the iterator decrements the count. `end(rng)` can return an empty sentinel `last` such that `first == last` returns the result of `first.count_ == 0`. See [Appendix 4](#appendix-4-on-counted-ranges-and-efficiency) for a discussion of the performance implications of this design. ## Design Decisions, Guidelines, and Rationale Below we present the decisions that led to the chosen high-level design, along with guidelines to be applied to the standard library and the rationale for each choice. ### Iterator Operations are Primitive The most fundamental decision facing the designer of a generic library like the STL is: what are the *basis operations*? Basis operations are the primitive operations upon which all other desired operations can be efficiently built. In the STL, those operations are the operations on iterators, and they are clustered into the familiar iterator concept hierarchy. Two iterators are required to denote a range. Can these two positions be bundled together into a single range object and -- more ambitiously -- can operations on ranges be made the basis, obviating the need for iterators entirely? Below we describe two libraries that use range operations as the basis, and describe why they are not a good fit for the C++ Standard Library. #### D's Ranges In the C++ Standard Library, iterators fill several roles: * Two of them denote a sequence of elements. * One of them denotes a position within a range. * They allow access to an element at the current position. * They allow access to subsequent (and sometimes prior) positions in the sequence. The [D Standard Library][4][@drange] takes a different approach. In D, ranges and the operations on them form the basis operations of the standard algorithms. D-style ranges fill the following roles: * They denote a sequence of elements. * They allow access to the front of the range, and sometimes to the back or the N-th. * They allow the removal of elements from the front of the range, and sometimes from the back. Would C++ benefit from a similar design? The argument typically given in favor of D's ranges is that they lead to simpler code, both for the algorithms that operate on ranges as well as for users who wish to create custom range types. Code that manipulates positions directly can be harder to reason about and thus more bug-prone, and implementing custom iterators is famously complicated. D-style ranges can only ever shrink, and they have no notion of position within sequence. If one were to try to implement C++'s iterators on top of D's ranges, one would immediately run into trouble implementing ForwardIterator's `operator==`. As D's ranges do not represent position, there would be no way to test two ranges to see if their heads referred to the same element. (The `front` member function that returns the front of a D range is not required to return a reference, nor would that be sufficient to implement a hypothetical `hasSameFront` function; a repeating range might return the same element multiple times, leading to false positives.) Additionally, there would be trouble implementing BidirectionalIterator's `operator--` or RandomAccessIterator's `operator+=` as that might require a range to grow, and D ranges can't grow. On the other hand, two C++ iterators can easily be used to implement a D-style range; thus, every range-based design can be implemented in terms of iterators. Since iterators can implement D ranges, but D ranges cannot be used to implement iterators, we conclude that iterators form a more powerful and foundational basis. D avoids the limits of its ranges by carefully designing the algorithms such that the missing functionality is never needed. This can sometimes require some creativity, and leads to some awkward productions. A good example is the `find` family of algorithms. Since `find` cannot return the position of the found element, it must instead return a range. But which range to return? The D Standard Library has as many `find` algorithms as there are answers to this question ([`find`](http://dlang.org/phobos/std_algorithm.html#find), [`findSkip`](http://dlang.org/phobos/std_algorithm.html#.findSkip), [`findSplit`](http://dlang.org/phobos/std_algorithm.html#.findSplit), [`findSplitBefore`](http://dlang.org/phobos/std_algorithm.html#.findSplitBefore), [`findSplitAfter`](http://dlang.org/phobos/std_algorithm.html#.findSplitAfter)). All these algorithms find an element in a range; they only differ in the information they return. In contrast, C++ has just one `find` algorithm; it returns a position, and the user is free to construct any desired range from that. [Appendix 3](#appendix-3-d-ranges-and-algorithmic-complexity) contains an example of an algorithm that cannot be implemented with the same algorithmic complexity using D-style ranges. Any algorithm that needs to freely move an iterator forward and backward between two bounds will suffer from the same fundamental problem. Just writing the signature of an algorithm like `rotate`, which takes as an argument a position in a sequence, is challenging without a way to specify a position. Since C++ iterators cannot be implemented on top of D's ranges, iterators have to stay both for the increased expressive power and for backwards compatibility. To additionally provide D-style ranges -- essentially offering an incompatible set of basis operations -- would create a schism within the standard library between range-based and iterator-based algorithms, which couldn't share code. We, the authors, consider such a schism unacceptable. #### Position-Based Ranges If a range-first design that abandons "position" as a representable entity is undesirable for C++, perhaps adding position back in yields a satisfactory design. That is the approach taken by [James Touton's range library][5][@bekennrange], where ranges -- together with a new Position concept -- are the primitives. A Position, as its name suggests, represents a position in a range. Unlike an iterator, a position cannot be used to access the element at that position without the range into which it refers, nor can the position be advanced without the range. This design has the following advantages: * In making position a representable entity, it avoids the sometimes awkward constructions of D's range library. * In requiring the range in order to dereference the position, it avoids all dangling iterator issues. * In requiring the range in order to change the position, it makes range-checking trivial. This is a boon not just for debuggability, but also for the design of certain range adaptors like filter and stride whose iterators need to know the end of the range so as not to walk past it. * It permits a clean separation of element traversal and access, much like the suggested [cursor/property map abstraction][11][@n1873]. It is possible to implement iterators on top of a position-based range by bundling a position with a pointer to a range into an iterator. However that results in iterators that may be fatter than necessary. A more workable approach would be to reimplement all the algorithms in terms of the position-based range primitives, and have the iterator-based overloads (that are retained for backwards-compatibility) forward to the range-based versions. In such a scheme, two iterators can be turned into a position-based range by wrapping them in a single range object and using the iterators themselves as the "positions". Although workable in principle, in practice it means there will be two ways of representing a range: an object with `begin()` and `end()` members that return iterators, and one with `begin_pos()` and `end_pos()` members that return positions; and every function that accepts ranges will need to account for that. It would mean that everybody would need to learn a new way to write algorithms. And it would mean that sometimes algorithms would return iterators and sometimes they would return positions, and that users would need to learn a new way to access the elements of a range. As appealing as the design is, it is too disruptive a change for the Standard Library. #### Basis-Operations: Summary In short, it just doesn't seem worth the trouble to change basis-operation horses in midstream. Iterators have a proven track record as a solid basis for the algorithms, and the C++ community has a heavy investment in the abstraction. The most heavily used and vetted C++ range libraries, Boost.Range and ASL Ranges, are built on top of iterators and have shown that it works in practice. This proposal follows suit. ### Ranges Cannot Own Elements As described above, a Container is not a Range; it is, however, an Iterable. Distinguishing between the two makes it possible to be explicit about where copyability is required, and with what performance characteristics. The algorithms discussed in this proposal don't require any distinction between Ranges and Containers since they never copy or assign the ranges passed to them; they only request the `begin` and `end` iterators. The distinction between Iterables and Ranges only becomes important when defining adaptor chains. What does code like the following mean? auto rng = v | view::reverse; This creates a view of `v` that iterates in reverse order. Now: is `rng` copyable, and if so, how expensive is the copy operation? If `v` is a `vector`, can `rng` safely outlive `v`? How about if `v` is just a pair of iterators? What happens when a user does `*rng.begin() = 42`? Is `v` mutated? How do the answers change if we replaced `v` with an rvalue expression? If a copy of `rng` is made, and an element is mutated through the copy, does the original `rng` object "see" the change? By specifying that Ranges do *not* own their elements, and further specifying that range adaptors operate on and produce Ranges (not Containers), we are able to answer these questions in a clear and consistent way. The result of a chain of range adaptors is always a lightweight object that is cheap to copy and assign (O(1) as opposed to O(N)), and that refers to elements whose lifetime is managed by some other object. Mutating an element through the resulting Range object mutates the underlying sequence. Copies of the resulting range are aliases to the same elements, and mutations to the elements are visible through all the aliased ranges. If `v` is a Range in the above line of code, it is copied into the adaptor. If it is a `vector`, the `vector` is first used to construct a Range by taking the `begin` and `end` of the Container. This happens automatically. The downside of this design is that it is sometimes desirable to do this: // Try to adapt an rvalue container auto rng = vector{1,2,3,4} | view::reverse; // OK? Adaptors operate on and yield Ranges; other Iterables (i.e., containers) are used to construct Ranges by first taking their begin and end. The code above is unsafe because `rng` will be left holding invalid iterators into a container that no longer exists. Our solution is to disallow the above code. *It is illegal to adapt an rvalue non-Range.* (Adapting rvalue Ranges, however, is perfectly acceptable; indeed necessary if adaptor pipelines are to work.) See [Appendix 6](#on-distinguishing-ranges-from-non-range-iterables) for the mechanics of how we distinguish between Iterables and Ranges. The alternative is for the rvalue container to be moved (or copied) into the adapted range and held by value. The resulting object would therefore no longer model Range; it would model Iterable. The authors feel that this weakening of the requirements on the return type makes it difficult to reason about the semantics and algorithmic complexity of range adaptors. The recommendation is to first declare the container and then create the adaptor separately. ### Ranges Are Semiregular We've already decided that Ranges (not Iterables) are copyable and assignable. They are, in the terminology of EoP[@stepanov09] and [N3351][8][@n3351], Semiregular types. It follows that copies are independent, even though the copies are both aliases of the same underlying elements. The ranges are independent in the same way that a copy of a pointer or an iterator is independent from the original. Likewise, iterators from two ranges that are copies of each other are also independent. When the source range goes out of scope, it does not invalidate an iterator into the destination range. Semiregular also requires DefaultConstructible in [N3351][8]. We follow suit and require all Ranges to be DefaultConstructible. Although this complicates the implementation of some range types, it has proven useful in practice, so we have kept this requirement. It is tempting to make Ranges Regular by requiring that they be EqualityComparable. A Range type would satisfy this additional requirement by testing whether two Ranges refer to the same elements in a sequence. (Note that it would be an error for `operator==` to test corresponding elements in two Ranges for equality, in the same way that it would be an error for `operator==` invoked on two pointers to compare the pointed-to elements. The state of a Range is not influenced by the content of its elements; a Range is defined only by the identity of the elements it references.) Although such a requirement is appealing in theory, it has problems: * It might conflict with users' expectations of what `rng1 == rng2` means. (See string_view for an example of a Range-like class that implements `operator==` in terms of the values of its elements, rather than identity.) * It is impossible to implement with those semantics in O(1) for some range types; for example, a filter range that stores a predicate. Functors and lambdas are generally not EqualityComparable. Another option is to allow Ranges to trivially model EqualityComparable by narrowly defining the domain over which the operation is valid. Iterators may only be compared if they refer into the same range. We can extend the reasoning to Ranges, which are logically little more than pairs of iterators. Taking this tack, we could allow a Range type to define its `operator==` as: rng1.begin() == rng2.begin() && rng1.end() == rng2.end() The assumption being that the operation is invalid if `rng1` and `rng2` refer to different elements. Although principled (for some set of principles), such a definition is almost certain to lead users into undefined behavior-land. As a result of the above, we have decided that the Range concept should not require EqualityComparable. Ranges are Semiregular, not Regular. If a user would like to check to see if two ranges have elements that compare equal, we suggest the `equal` algorithm: if(std::equal(rng1, rng2)) // ... ### Range Iterators Cannot Outlive Their Ranges Containers own their elements, so it is clear that the container must outlive the iterators it generates. But is the same true for a Range if it does not own its elements? For a trivial range consisting of two iterators, it's clearly not true; the iterators *may* outlive the range. It turns out that if we require that all range's iterators be permitted to outlive the range, a great many interesting range types become significantly more expensive at runtime. A good case study is the filter view. A filter view takes a range and a predicate, and presents a view of the sequence that skips the elements for which the predicate is false. (The filter view can be thought of as a lazy equivalent of the `copy_if` algorithm.) The existence of the `boost::filter_iterator` shows that such an iterator *can* be made such that it doesn't depend on a range, but at a cost. The `filter_iterator` stores: 1. An iterator that indicates the current position in the underlying sequence. 2. An iterator that indicates the end of the underlying sequence (needed by the increment operators to avoid falling off the end while searching for an element that satisfies the predicate). 3. The predicate. In today's STL, the begin and end iterators must have the same type, and they are both needed to call an algorithm. Thus, the information in (2) and (3) is duplicated. Also, the predicate may be expensive to copy, given the ease with which capture-by-value lambdas and `std::function`s can be created. When such iterators are composed with other kinds of views (e.g., a transformed, filtered view), the bloat compounds exponentially (see [Index-Based Ranges][10][@n3782]). By relaxing the constraint that a range's begin and end must have the same type, we can avoid the duplication, but the begin iterator still must hold everything, which is potentially expensive. If we could rely on the range object outliving the iterator, we can make the filter iterators smaller and lighter. The range object can hold the predicate and the underlying range's begin/end iterators. The filter view's iterator only needs to hold the current position and a pointer back to the range object. The same logic applies to the transform view, which applies a transformation function to elements on the fly. If the iterators are required to be valid beyond the lifetime of the transform range, then the transformation function must be cached inside each iterator. This could make the iterators expensive to copy. An implementor might instead want the freedom to put the transformation function in the range object. A final example is `istream_iterator`. Every `istream_iterator` holds a single cached `T` object inside it. If `T` is an expensive-to-copy type like `std::string`, then copying `istream_iterator`s is potentially causing dynamic allocations. The STL assumes iterators are cheap to copy and copies them freely. A better design would see the cached `string` object move into an `istream_range` object whose iterators merely stored pointers back to the range. This would make the iterators smaller and cheaper to copy, but they would become invalid once the range was destroyed. This tradeoff is probably worth it. ### An Iterable's End May Have a Different Type Than Its Begin In today's STL, `c.begin()` must have the same type as `c.end()`. This is because the only kind of range the STL supports is a pair of iterators. However, we've given examples of other kinds of ranges we would like to support, such as an iterator and a predicate, and an iterator and a count. These kinds of ranges can already be supported by shoe-horning them into the pair-of-iterators mold, but at a cost (see [Appendix 1](#appendix-1-sentinels-and-code-generation)). Loosening the constraints of the type of Iterable's end makes it possible to accommodate these other kinds of ranges with lower overhead. Allowing "end-ness" to be encoded in the type system also eliminates the need to mock-up dummy end iterators like `std::istream_iterator` and `std::regex_iterator`, the logic of which is tricky to get right. What's more, it improves code generation for these kinds of ranges. With the use of dummy end iterators, information which is known at compile-time -- namely, that an iterator represents the end -- must be encoded into runtime information in the iterator itself. This robs the compiler of the information it needs to eliminate branches from the core loops of many algorithms. See [Appendix 1](#appendix-1-sentinels-and-code-generation) for an example of how sentinels can positively affect code generation. When considering this choice for the range concept, it's helpful to think about how it would affect the algorithms. Consider `std::for_each`, which currently has this signature: template Function for_each(InputIterator first, InputIterator last, Function f) { for(; first != last; ++first) f(*first); return f; } With sentinels, `for_each` might look like this: template> F> requires EqualityComparable F for_each(I first, S last, F f) { for(; first != last; ++first) f(*first); return f; } None of the code in the algorithm had to change. No calling code would have to change either; this is a strictly backwards-compatible change. You might think that this opens a new category of programming errors where developers inadvertently pass mismatched iterator/sentinel pairs. However, this algorithm signature is constrained with concept checks that ensures that `I` and `S` satisfied the cross-type EqualityComparable concept (see [N3351][8][@n3351]). See [Appendix 2](#appendix-2-sentinels-iterators-and-the-cross-type-equalitycomparable-concept) for further discussion about iterator/sentinel cross-type EqualityComparability constraint. To see the benefit of this design, imagine a sentinel type `null_sentinel`: // For determining whether an iterator refers to a null value: struct null_sentinel { template friend bool operator==(I i, null_sentinel) { return 0 == *i; } // ... and friends }; template struct common_type ... see Appendix 2 ... Now we can use `std::for_each` on null-terminated strings without needing to know the length of the string: std::for_each(argv[1], null_sentinel(), f); Of course, all the algorithms would have overloads that also accept range arguments, so this can be further simplified to: std::for_each(null_terminated(argv[1]), f); where `null_terminated(InputIterator)` returns a range `r` such that the `std::end(r)` is a `null_sentinel`. #### Sentinels and Early Algorithm Termination One excuse sometimes given for not using the standard algorithm is that they don't give the users a way to break out of them early. The use of sentinels makes that possible. Consider a sentinel constructed from both an end iterator and a predicate. Such a sentinel would compare equal to an iterator *either* when the iterator equals the end iterator *or* when the predicate evaluates to true. Using such a sentinel has the effect of terminating an algorithm early. For instance: // Process work items in a queue, allowing for a user interrupt std::queue q; std::function user_interrupt = /*...*/; std::for_each( q | view::until(user_interrupt), f ); In the above, `view::until` is a range modifier that adds `user_interrupt` as an extra termination condition. ### Algorithm Return Types are Changed to Accommodate Sentinels Notice that in the due course of evaluating `std::for_each` with `null_sentinel` above, the position of the null terminator is found. This is potentially useful information that can easily be returned to the user. It is, in fact, a far more interesting and useful result that the `Function` that `for_each` currently returns. So a better signature for `for_each` should look like this: // Returns an InputIterator i such that (i == last) is true: template> F> requires EqualityComparable I for_each(I first, S last, F f); In similar fashion, most algorithm get new return types when they are generalized to support sentinels. This is a source-breaking change in many cases. In some cases, like `for_each`, the change is unlikely to be very disruptive. In other cases it may be more so. Merely accepting the breakage is clearly not acceptable. We can imagine three ways to mitigate the problem: 1. Only change the return type when the types of the iterator and the sentinel differ. This leads to a slightly more complicated interface that may confuse users. It also greatly complicates generic code, which would need metaprogramming logic just to use the result of calling some algorithms. For this reason, this possibility is not explored here. 2. Make the new return type of the algorithms implicitly convertible to the old return type. Consider `copy`, which currently returns the ending position of the output iterator. When changed to accommodate sentinels, the return type would be changed to something like `pair`; that is, a pair of the input and output iterators. Instead of returning a `pair`, we could return a kind of pair that is implicitly convertible to its second argument. This avoids breakage in some, but not all, scenarios. This subterfuge is unlikely to go completely unnoticed. 3. Deliver the new standard library in a separate namespace that users must opt into. In that case, no code is broken until the user explicitly ports their code. The user would have to accommodate the changed return types then. An automated upgrade tool similar to [clang modernize][16][@clangmodernize] can greatly help here. We, the authors, prefer (3). Our expectation is that the addition of concepts will occasion a rewrite of the STL to properly concept-ify it. The experience with C++0x Concepts taught us that baking concepts into the STL in a purely backward-compatible way is hard and leads to an unsatisfactory design with a proliferation of meaningless, purely syntactic concepts. The spirit of [N3351][8][@n3351] is to conceptify the STL in a meaningful way, even at the expense of minor breakage. Although the issue has not yet been discussed, one likely solution would be to deliver a new STL in a separate namespace. Once that happens, it opens the door for other minor breaking changes, provided the benefits are deemed worthy. ### Orthogonality of Traversal and Access Is Not Surfaced in the Iterator Concepts The current iterator concept hierarchy ties together the traversal and access properties of iterators. For instance, no forward iterator may return an rvalue proxy when it is dereferenced; the ForwardIterator concept requires that unary `operator*` return an lvalue. There is no room in the hierarchy for, say, a random-access iterator that returns proxies. This problem is not new to ranges; however, it has serious consequences for lazy ranges that apply transformations to elements on the fly. If the transformation function does not return an lvalue, the range's iterator can model no concept stronger than InputIterator, even if the resulting iterator could in theory allow random access. The result in practice is that most range adaptors today have the unfortunate effect of degrading the underlying range's category to Input, thereby limiting the number of algorithms it can be passed to -- often for no good reason. Prior work has been done by [Abrahams et. al.][9][@new-iter-concepts] to separate the traversal and access properties of iterators in a way that is backwards compatible. When formalizing the iterator concepts for a range library, should new iterator concepts be used, or should we hew to the old, simpler concept hierarchy with its known limitations? A close reading of the iterator concepts proposed by [N3351][8][@n3351] shows that the problematic requirement on ForwardIterator's reference type has been dropped. That is, if the concepts proposed by Stroustrup, Sutton, et. al., are adopted, there will be nothing wrong with, say, a random-access iterator with a proxy for a reference type. The problems described above go away without any need for further complication of the iterator refinement hierarchy. It's unclear at this time if that was the authors' intent, and if so what impact it has on the standard algorithms. This area requires more research. It is noted here that this proposal adopts the [N3351][8][@n3351] iterator concepts as-is. ### Additional Overloads of the Algorithms As should be obvious, this range proposal recommends adding additional overloads of the existing algorithms to allow them to work directly on Iterables. This is done in accordance with the following suggested guidelines: - Any algorithm that currently operates on a range denoted by two iterators gets an overload where the two iterator arguments are replaced with a single Iterable argument. (NOTE: This does *not* include the counted algorithms like `copy_n` that take an iterator and a count instead of two iterators.) - All overloads of an algorithm, whether they take Iterables or separate iterator/sentinel arguments, are *semantically identical*. All overloads have the same return type. All evaluate eagerly. The intention is that the Iterable-based overloads delegate to the iterator-based ones and have the same semantics and algorithmic complexity. - As described above, algorithms that necessarily process their entire input sequence return the iterator position at the end in addition to whatever else they return. The purpose is to return potentially useful information that is computed as a side-effect of the normal execution of the algorithm. Exceptions to this design guideline are made when one of the following is true: * The algorithm might in some cases not consume the entire input sequence. (The point of this exception is to avoid forcing the algorithm to compute something that is not necessary for successful completion. For example, `find`.) * When the sole purpose of the algorithm is specifically to compute a single value; hence, changing the return type will necessarily break code using the C++11 version. Examples include `is_sorted` and `accumulate`. - "Three-legged" iterator-based algorithms (i.e. algorithms that operate on two ranges, the second of which is specified by only a single iterator and is assumed to be long enough) now have 4 versions: 1. The old three-legged iterator version, 2. A four-legged version that uses the sentinel of the second sequence as an additional termination condition, 3. A version that takes an Iterable and an Iterator (which dispatches to the three-legged iterator-based version), and 4. A version that takes two Iterables (which dispatches to the four-legged iterator-based version). Note: Purely as an implementation consideration, overloads (3) and (4) above must be coded to avoid ambiguity when a native array is passed as the second parameter (where either an Iterable or an Iterator may appear). Arrays are Iterables, but if (3) is naively coded to take an Iterator by value, a native array would also match, since native arrays decay into pointers. - If an algorithm returns an iterator into an Iterable argument, the Iterable must be an lvalue. This is to avoid returning an iterator that is immediately made invalid. Conversely, if no iterator into an Iterable argument is returned, then the Iterable should be taken by forwarding reference (aka ["universal reference"][13][@universal-references]). - Algorithms that do not mutate their input sequence must also work when braced initializer lists [dcl.init] are used in place of Iterables. This can require additional `initializer_list` overloads since a type cannot be deduced from a *braced-init-list* used as an argument. ### Range-based for Loop is Changed to Accommodate Sentinels The current range-based `for` loop assumes that a range's end has the same type as its begin. This restriction can be relaxed to allow range-based `for` to operate on Iterables. The range-based for loop is currently specified as: { auto && __range = range-init; for ( auto __begin = begin-expr, __end = end-expr; __begin != __end; ++__begin ) { for-range-declaration = *__begin; statement } } To accommodate Iterables, the change is as simple as: { auto && __range = range-init; auto __begin = begin-expr; auto __end = end-expr; for ( ; __begin != __end; ++__begin ) { for-range-declaration = *__begin; statement } } This is the only core language change required to fully support Iterables. ### Allow Mutable-Only Iterables If a cv-unqualified type `T` models Iterable, then the type `T const` need not. This permits ranges that maintain mutable internal state such as an `istream_range`. Consider the performance short-comings of `istream_iterator`. The iterator reads a string from an `istream` and must store it internally so it can be returned from `operator*`. This means that copying an `istream_iterator` probably incurs a dynamic allocation. Copying iterators is not supposed to be expensive. An alternative range-based design would be to define an `istream_range` class template: template class istream_range { T value_; istream * postr_; public: class iterator { istream_range * prng_; public: /*...*/ }; iterator begin() {/*...*/} iterator end() {/*...*/} }; In this design, the cached value lives in the range object, not in the iterator. The iterator merely stores a pointer back to the range. As the iterator is advanced, values are read from the stream and stored in the cache. Since the range object is mutated as it is iterated, it would be a lie to provide const overloads of `begin()` and `end()`. The need for a range that is mutated in the course of iteration also came up in the design of a `view::flatten` adaptor that takes a range of ranges, and turns it into a single range. This adapted range also must mutate an internal cache. The adaptor is used to make Ranges monads, and is used in the implementation of [Range Comprehensions][12][@range-comprehensions], which are akin to Python's and Haskell's List Comprehensions. (That discussion is beyond the scope of this document.) ### Range Adaptors are Lazy Algorithms Consider the example given at the start of paper: int total = accumulate(view::iota(1) | view::transform([](int x){return x*x;}) | view::take(10), 0); The semantics of the adaptors (the things in the `view::` namespace) are such that computations are only done on demand, when the resulting adapted range is iterated. In this case, the range pipeline expression does no work aside from setting up a computation. Only as `accumulate` executes is the sequence of integers generated and transformed. All adaptors have these lazy semantics. This gives users the ability to reason about the algorithmic complexity of their programs. If an underlying range is transformed and filtered and then passed to an algorithm, users can be certain that the sequence will be traversed exactly once. ### All Algorithms Accept Sentinels Even If They Need An End Iterator Some algorithms like `reverse` really need an end iterator to do their job. One option would be to require users to pass an actual end iterator instead of a non-iterator sentinel. The other option is to accept a sentinel and do an O(N) probe for the end first. We opted for the latter option. No such algorithms have complexity better than O(N), so such a probe doesn't affect the overall algorithmic complexity of the algorithm. And it saves the user the hassle of having to find the end herself before calling the algorithm. In short, it should be possible to `reverse` a null-terminated string *without* needing to call `strlen` first. ### There Is No Function Signature To Express Does-Not-Mutate-The-Range-Elements Raw pointers have an advantage over iterators with regard to the const-correctness of function interfaces; namely, that you can use `const` to guarantee that the function will not mutate the pointed-to data. Consider: // This will not mutate the data template void some_function(const T * data, std::size_t count); When we move to iterators, we lose that expressiveness: // Will this mutate the data? template void some_function(Iter first, Iter last); Since the suggested range design is built on top of iterators, it inherits this limitation. Consider what happens when we change to a range-based API with a simple `range` type like that proposed by [N3350][21][@n3350]: // Accepts a const Range object, but mutates its elements template void some_function(Rng const & rng) { ++*rng.begin(); // Deeply questionable behavior } template struct range : pair { using pair::pair; I begin() const { return this->first; } I end() const { return this->second; } }; int main() { int arr[] = {1,2,3,4}; range rng{ arr, arr + 3 }; some_function(rng); // arr is now {2,2,3,4} } Keep in mind that the Iterable concept describes types like `vector` where a top-level const *does* affect the mutability of the iterable's elements, as well as simple pair-of-iterator style ranges like `range` above, where the top-level constness does *not* affect the elements' mutability. Concepts Lite doesn't help, either. Although it's not hard to write a concept that only matches immutable iterables and use it to constrain an algorithm, it doesn't solve the problem. See below: template concept ConstIterable = is_const())) >>::value; // This is over-constrained: template void non_mutating_algorithm(Rng const & rng); int rgi[] = {1,2,3,4}; range rng{rgi, rgi+4}; // a pair of mutable iterators non_mutating_algorithm(rng); // <== ERROR rng is not a ConstIterable The trouble is that the type `Rng` is deduced as `range` which doesn't satisfy the requirements of the ConstIterable concept. The const in the function signature doesn't help because it doesn't change the const-ness of the iterator's reference type. Even if `rng` is const, `rng.begin()` returns an `int*`. There is no way to write the function signature such that template type deduction works *and* const-ness is applied deeply to the range's elements. That's because such a transformation would necessarily involve a change to the range's type, and type deduction makes no allowance for arbitrary type transformations during the deduction process. #### But it works for `array_view`. Why? [N3851](http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n3851.pdf) proposes an `array_view` class for the second Library Fundamentals TS. That type allows users to independently specify the mutability of the elements and of the view with the `const` keyword. From N3851: > A view can be created over an arbitrary *value_type*, as long as there exists a conversion from the pointer to the underlying collection object type to the pointer to the *value_type*. This allows to distinguish two levels of constness, analogously to the pointer semantics -- the constness of the view and the constness of the data over which the view is defined -- see Table 2. Interfaces of both the *array_view* and the *strided_array_view* allow for implicit conversions from non-const-qualified views to const-qualified views. With this scheme, you presumably would be able to pass any Container (defined in N3851 to be arrays and class types with `size` and `data` member functions) to an algorithm as follows: void some_algorithm( array_view const & arr ); vector vi {1,2,3,4}; array_view arr { vi } some_algorithm( arr ); // OK! In this case, the signature of the algorithm, together with the constructors of `array_view` and the implicit conversion of `int*` to `const int*`, conspire to make `some_function` guarantee deep-constness. If it can work for `array_view`, why can it not work in general for all Iterables? In other words, is there no range design in which users can put `const` somewhere in their function signatures to make their algorithms deeply const? The answer, sadly, is no. Even a trivial change to the above signature shows how fragile the `array_view` design is, and why it cannot be generalized to all range types: template void some_algorithm( array_view const & arr ); vector rgi{1,2,3,4}; array_view arr { vi } some_algorithm( arr ); // ERROR! The compiler cannot figure out what type to pick for `T` during type deduction, and there's no way for the author of `array_view` to give the compiler that guidance. When generalized to arbitrary Iterables and Ranges, the problem is further compounded. There is no place to put a second, "deep" `const` in a signature like below: template void some_algorithm( Rng const & rng ); And even if there were, the problem would be the same as for `array_view`: template type deduction would fail. #### Constraints and contracts There is no clever way around the problem in today's language, or even with Concepts Lite. This is an artifact of the style of generic programming used in C++: stating constraints on template arguments is significantly different than adding `const`-ness to a concrete type or template specialization. A template's constraints define part of that template's contract, and this contract applies not only to the user of that template, but also its implementer. In the earlier example, `some_function` requires its template arguments to satisfy the requirements of the Iterable concept. Under that contract, the implementation should use only the expressions allowed by the concept on objects whose types are constrained by the concept. In other words, those requirements define a set of expressions and types that are *admissible* within the template. Recall the `some_function` define above: // Accepts a const Range object, but mutates its elements template void some_function(Rng const & rng) { ++*rng.begin(); // Deeply questionable behavior } The expression `++*rng.begin()` invokes not one, but two operations not admitted by the requirements of the Iterable concept: - `rng.begin()` (which should be `using std::begin; begin(rng)`), and - `++x` where `x` is the object returned by `*begin(rng)`. While this program is syntactically well-formed, and instantiation may even succeed, its behavior would be undefined under the terms of its contract. In other words, the implementation does not conform to its constraints. This is not fundamentally different than using a `const_cast` to modify the value of a `const`-qualified function argument: it might work, but the modification invokes undefined behavior. *Every* proposed range design will have the same problem. The lack of a library solution to this problem should not hold up a proposal. A work-around is for users to test each algorithm with an archetypal non-mutable iterator, as has been done with the [Boost Concept Check Library][1][@boostconceptcheck]. The standard library could make this task simpler by providing debug archetypal iterators for testing purposes. ### Singular Ranges Are Not Empty Ranges are default-constructible. The question is, what can be done with a such a range? Given a Range type `R` and an object `r` defined as follows: R r; // "singular" range assert( begin(r) == end(r) ); // Is this OK? Default-constructed standard containers are empty. Can we expect the same is true for ranges? No, we cannot. The intention is that a simple pair of iterators may qualify as a valid range. The section [iterator.requirements.general]/5 explains what can be done with singular iterators, and comparing them for equality is not listed as one of the valid operations. Therefore, singular ranges are not "empty". In terms of EoP, they are partially formed objects that must be assigned to before they can be used [8]. A particular model of the Range concept may choose to provide this guarantee, but it is not required by the Range concept itself and, as such, should not be relied upon. Concept Definitions ===== The following concepts are proposed to constrain the standard library. The iterator concepts mentioned here are identical to those specified in [N3351][8][@n3351] except where specified. ## Iterator Concepts The range concepts presented below build on the following iterator concepts. These are largely as found in [N3351][8][@n3351], with the addition of WeakIterator, Iterator, WeakOutputIterator and OutputIterator. The entire hierarchy is presented here for completeness. An important, new concept is: concept WeakIterator = WeaklyIncrementable && Copyable && requires(I i) { { *i } -> auto&&; }; A WeakIterator is a WeaklyIncrementable type that is both copyable and dereferencable, in addition to being pre-incrementable. The only requirement on the result of dereferencing the iterator is that its type can be deduced from `auto&&`. Effectively, the result of dereferencing shall not be `void`. The WeakIterator concept allows iterator adaptors to provide a dereferencing operator for both InputIterators and OutputIterators. This concept is refined by the addition of either Readable or Writable, which allow reading from and writing to a dereferenced iterator, respectively. The Iterator and WeakIterator also obviate the need for separate InputRange and OutputRange concepts (as we see later). concept Iterator = WeakIterator && EqualityComparable; concept WeakOutputIterator = WeakIterator && Writable; concept OutputIterator = WeakOutputIterator && EqualityComparable; N3351 does not define WeakOutputIterator or OutputIterator, preferring instead to define all the algorithms in terms of WeaklyIncrementable and (separately) Writable. We see no disadvantage to rolling these two into the familiar (Weak)OutputIterator concept as a convenience; it saves typing. The WeakInputIterator concept defines requirements for a type whose referred to values can be read (from the requirement for Readable) and which be both pre- and post-incremented. However, WeakInputIterators are not required to be compared for equality. There are a number of algorithms whose input ranges are defined by the equality of comparison of another input range (e.g., `std::mismatch` and `std::equal`). concept WeakInputIterator = Readable && requires(I i) { typename IteratorCategory; { i++ } -> Readable; requires Derived, weak_input_iterator_tag>; }; An InputItreator is a WeakInputIterator that can be compared for equality comparison. This concept defines the basic requirements for a very large number of the algorithm in the standard library. concept InputIterator = WeakInputIterator && EqualityComparable && Derived, input_iterator_tag>; The ForwardIterator concept refines the InputIterator concept, but the refinement is *semantic*. It guarantees the "multipass" property: it allows multiple iterations of a range of elements. This is something that cannot be done with, say, an `istream_iterator`. The current element is consumed when the iterator is incremented. concept ForwardIterator = InputIterator && Incrementable && Derived, forward_iterator_tag>; The BidirectionalIterator concept refines the ForwardIterator concept, and allows both incrementing and decrementing. concept BidirectionalIterator = ForwardIterator && Derived, bidirectional_iterator_tag> && requires decrement (I i, I j) { { ––i } -> I&; { i–– } -> I; }; The RandomAccess concept refines the BidirectionalIterator concept and provides support for constant-time advancement using `+=`, `+`, and `-=`, and the computation of distance in constant time using `-`. Random access iterators also support array notation via subscripting. concept RandomAccessIterator = BidirectionalIterator && TotallyOrdered && Derived, random_access_iterator_tag> && SignedIntegral> && SizedIteratorRange && // see below requires advance (I i, I j, DifferenceType n) { { i += n } -> I&; { i + n } -> I; { n + i } -> I; { i –= n } -> I&; { i – n } -> I; { i[n] } -> ValueType; }; ## Iterator Range Concepts The IteratorRange concept defines a pair of types (an Iterator and a Sentinel), that can be compared for equality. This concept is the key that allows iterator ranges to be defined by pairs of types that are not the same. concept IteratorRange = Iterator && Regular && EqualityComparable; The SizedIteratorRange allows the use of the `-` operator to compute the distance between to an Iterator and a Sentinel. concept SizedIteratorRange = IteratorRange && requires difference (I i, S j) { typename Distance_type; { i - i } -> Distance_type; { j - j } -> Distance_type; { i - j } -> Distance_type; { j - i } -> Distance_type; requires SignedIntegral; }; ## Iterable Concepts This proposal introduces a new concept for describing the requirements on algorithms that require access to the `begin` and `end` of a Range or Container. concept Iterable = requires(T t) { typename IteratorType; typename SentinelType; { begin(t) } -> IteratorType; { end(t) } -> SentinelType; requires IteratorRange; } The Iterable concept requires two associated operations: `begin`, and `end`. Note that the return types of these operations are not required to be the same. The names of those return types are `IteratorType` and `SentinelType`, respectively. Furthermore, that pair of types must satisfy the requirements of the IteratorRange concept defined in the previous section. Iterable types have no other requirements. Most algorithms requiring this concept simply forward to an Iterator-based algorithm by calling `begin` and `end`. The Range concept refines the Iterable concept and defines a view on a range of elements that it does not own. concept Range = Iterable && Semiregular && is_range::value; A possible implementation of the `is_range` predicate is shown below. // For exposition only: struct range_base {}; concept ContainerLike = !Same())), decltype(*begin(declval()))>; // For exposition only: template struct is_range_impl_ : std::integral_constant< bool, Iterable && (!ContainerLike || Derived) > {}; // Specialize this if the default is wrong. template struct is_range : conditional< is_same>>::value, is_range_impl_, is_range>> >::type {}; Note that the "multipass" property--the property that guarantees that you can iterate the same range twice, accessing the same objects in each pass--is guaranteed by the `forward_iterator_tag` class. That is, any iterator having whose iterator category is derived from that tag class is required to be a multipass iterator. ## Sized Iterable Concepts The `SizedIterable` concept exists for the same reasons as `SizedIteratorRange`. There are some iterables that, though they are not random-access, know their size in O(1). A prime example is `std::list`. Another example is a counted view (i.e., a range specified by an iterator and a count). Some algorithms can select a better implementation when the size of the range is known, even if the iterators don't allow random access. (One example is a `search` algorithm that knows to stop searching when there is no longer room in the input sequence for the pattern to match.) // For exposition only: concept SizedIterableLike = requires(R r) { typename SizeType; { size(r) } -> SizeType; // ADL customization point requires Integral; } concept SizedIterable = is_sized_iterable::value; Like [N4017][20][@n4017], we propose `size(r)` as a customization point for accessing the size of an Iterable. A SizedIterable requires that `size(r)` returns the same value as `distance(begin(r), end(r))` (module a possible change in the signed-ness of the Integral type). As in N4017, we suggest `size` overloads in `std::` for arrays and for class types with a `size()` member. In recognition of the fact that nominal conformance to a concept is insufficiently fine-grained, the SizedIterable concept is defined in terms of a `is_sized_iterable` trait. This is to give users explicit control in the case of accidental conformance with the syntactic requirements of the concept. A possible default implementation of the `is_sized_iterable` trait is shown below. // For exposition only: template struct is_sized_iterable_impl_ : std::integral_constant< bool, SizedIterableLike > {}; // Specialize this if the default is wrong. template struct is_sized_iterable : conditional< is_same>>::value, is_sized_iterable_impl_, is_sized_iterable>> >::type {}; Technical Specifications ===== This section is intentionally left blank. Future Directions ===== More work is necessary to get ranges into the standard. Subsequent proposals will recommend specific components for standardization as described in [Impact on the Standard](#impact-on-the-standard). In addition, below are some additional areas that are currently open for research. - Range extensions to things like regex. Make it work with null-terminated strings, e.g.. - Discuss the pros and cons of tying this work with work on a concept-ified standard library (aka Concepts Lite TS2). - Discuss the pros and cons of making this (and the concept-ified standard library) *strictly* backwards compatible, versus delivering the new, conceptified and range-ified standard library in a separate, versioned namespace (and what such a solution should look like). - Discuss how an extension to the Concepts Lite proposal, implicit conversion to concept, bears on the Iterable/Range concepts and the way the algorithms are constrained. Also discuss how it can give a syntax to express "this function does not mutate the range elements." - Assess the impact of allowing ForwardIterators to return proxies. - Consider integrating ContiguousIterator from [N4132][18][@n4132] Acknowledgements ===== I would like to give special thanks to Sean Parent for his advice and feedback on early designs of the range library on which this proposal is based, in addition to his work on the [Adobe Source Libraries][3][@asl] from which this proposal has borrowed liberally. Also deserving of special thanks is Andrew Sutton. His work on Concepts Lite and on the formulations of the algorithms as specified in [N3351][8][@n3351] has proven invaluable, and he has generously donated his time and expertise to expound on the ideas there and improve the quality of this proposal. Chandler Carruth has also helped more than he probably knows. I am indebted to him for his support and perspective. I would be remiss if I didn't acknowledge the foundational work of all the people whose ideas and sweat have gone into various range libraries and proposals in the past. They are too many to list, but I certainly benefited from the work of Dave Abrahams, Dietmar Kühl, Neil Groves, Thorsten Ottosen, Arno Schoedl, Daniel Walker, and Jeremy Seik. Neil Groves also submitted a particularly extensive review of this document. Of course none of this work would be possible without Alex Stepanov's giant leap forward with the STL, or without Bjarne Stroustrup who gave Alex the instrument he needed to most clearly realize his vision. References ===== --- references: - id: boostconceptcheck title: Boost Concept Check Library URL: 'http://boost.org/libs/concept_check' type: webpage accessed: year: 2014 month: 10 day: 8 - id: boostrange title: Boost.Range Library URL: 'http://boost.org/libs/range' type: webpage accessed: year: 2014 month: 10 day: 8 - id: asl title: Adobe Source Libraries URL: 'http://stlab.adobe.com' type: webpage accessed: year: 2014 month: 10 day: 8 - id: drange title: D Phobos std.range URL: 'http://dlang.org/phobos/std_range.html' type: webpage accessed: year: 2014 month: 10 day: 8 - id: bekennrange title: Position-Based Ranges URL: 'https://github.com/Bekenn/range' type: webpage accessed: year: 2014 month: 10 day: 8 - id: stepanov09 title: Elements of Programming type: book author: - family: Stepanov given: Alexander - family: McJones given: Paul edition: 1 isbn: 032163537X, 9780321635372 issued: year: 2009 publisher: Addison-Wesley Professional - id: n3351 title: 'N3351: A Concept Design for the STL' type: article author: - family: Stroustrup given: Bjarne - family: Sutton given: Andrew issued: year: 2012 month: 1 URL: 'http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3351.pdf' - id: n1873 title: 'N1873: The Cursor/Property Map Abstraction' type: article author: - family: Dietmar given: Kühl - family: Abrahams given: David issued: year: 2005 month: 8 day: 26 URL: 'http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1873.html' - id: n3782 title: 'N3782: Index-Based Ranges' type: article author: - family: Schödl given: Arno - family: Fracassi given: Fabio issued: year: 2013 month: 9 day: 24 URL: 'http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3782.pdf' - id: clangmodernize title: Clang Modernize URL: 'http://clang.llvm.org/extra/clang-modernize.html' type: webpage accessed: year: 2014 month: 10 day: 8 - id: new-iter-concepts title: New Iterator Concepts URL: 'http://www.boost.org/libs/iterator/doc/new-iter-concepts.html' type: webpage accessed: year: 2014 month: 10 day: 8 - id: universal-references title: Universal References in C++11 URL: 'http://isocpp.org/blog/2012/11/universal-references-in-c11-scott-meyers' type: webpage accessed: year: 2014 month: 10 day: 8 - id: range-comprehensions title: Range Comprehensions URL: 'http://ericniebler.com/2014/04/27/range-comprehensions/' type: webpage accessed: year: 2014 month: 10 day: 8 - id: n4132 title: 'N4132: Contiguous Iterators' type: article author: - family: Maurer given: Jens issued: year: 2014 month: 9 day: 10 accessed: year: 2014 month: 10 day: 8 URL: 'https://isocpp.org/files/papers/n4132.html' - id: ntcts-iterator title: NTCTS Iterator URL: 'https://github.com/Beman/ntcts_iterator' type: webpage accessed: year: 2014 month: 10 day: 8 - id: range-v3 title: Range v3 URL: 'http://www.github.com/ericniebler/range-v3' type: webpage accessed: year: 2014 month: 10 day: 8 - id: llvm-sroa title: 'Debug info: Support fragmented variables' URL: 'http://reviews.llvm.org/D2680' type: webpage accessed: year: 2014 month: 10 day: 8 - id: libcxx title: 'libc++ C++ Standard Library' URL: 'http://libcxx.llvm.org/' type: webpage accessed: year: 2014 month: 10 day: 8 - id: austern98 title: 'Segmented Iterators and Hierarchical Algorithms' URL: 'http://dl.acm.org/citation.cfm?id=647373.724070' author: - family: Austern given: Matthew type: paper-conference container-title: Selected Papers from the International Seminar on Generic Programming page: 80-90 issued: year: 2000 - id: cpp-seasoning title: 'C++ Seasoning' author: - family: Parent given: Sean type: speech URL: 'https://github.com/sean-parent/sean-parent.github.com/wiki/presentations/2013-09-11-cpp-seasoning/cpp-seasoning.pdf' container-title: 'GoingNative 2013' issued: year: 2013 month: 9 day: 11 - id: muchnick97 title: 'Advanced Compiler Design Implementation' author: - family: Muchnick given: Steven publisher: 'Morgan Kaufmann' issued: year: 1997 isbn: '1558603204, 9781558603202' - id: n4017 title: 'N4017: Non-member size() and more' type: article author: - family: Marcangelo given: Riccardo issued: year: 2014 month: 5 day: 22 accessed: year: 2014 month: 10 day: 10 URL: 'http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4017.htm' - id: n3350 title: 'N3350: A minimal std::range' type: article author: - family: Yasskin given: Jeffrey issued: year: 2012 month: 1 day: 16 accessed: year: 2014 month: 10 day: 10 URL: 'http://www.open-std.org/Jtc1/sc22/wg21/docs/papers/2012/n3350.html' ... [1]: http://boost.org/libs/concept_check "Boost Concept Check Library" [2]: http://www.boost.org/libs/range "Boost.Range" [3]: http://stlab.adobe.com/ "Adobe Source Libraries" [4]: http://dlang.org/phobos/std_range.html "D Phobos std.range" [5]: https://github.com/Bekenn/range "Position-Based Ranges" [6]: https://github.com/sean-parent/sean-parent.github.com/wiki/presentations/2013-09-11-cpp-seasoning/cpp-seasoning.pdf "C++ Seasoning, Sean Parent" [7]: http://www.github.com/ericniebler/range-v3 "Range v3" [8]: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3351.pdf "A Concept Design for the STL" [9]: http://www.boost.org/libs/iterator/doc/new-iter-concepts.html "New Iterator Concepts" [10]: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3782.pdf "Indexed-Based Ranges" [11]: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1873.html "The Cursor/Property Map Abstraction" [12]: http://ericniebler.com/2014/04/27/range-comprehensions/ "Range Comprehensions" [13]: http://isocpp.org/blog/2012/11/universal-references-in-c11-scott-meyers "Universal References in C++11" [14]: http://lafstern.org/matt/segmented.pdf "Segmented Iterators and Hierarchical Algorithms" [15]: http://reviews.llvm.org/D2680 "Debug info: Support fragmented variables." [16]: http://clang.llvm.org/extra/clang-modernize.html "Clang Modernize" [17]: http://libcxx.llvm.org/ "libc++ C++ Standard Library" [18]: https://isocpp.org/files/papers/n4132.html "Contiguous Iterators" [19]: https://github.com/Beman/ntcts_iterator "ntcts_iterator" [20]: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4017.htm "Non-member size() and more" [21]: http://www.open-std.org/Jtc1/sc22/wg21/docs/papers/2012/n3350.html "A minimal std::range" Appendix 1: Sentinels and Code Generation ===== In this appendix we explore the effect of sentinels on code generation. I'll show that allowing the type of the end iterator to differ from the begin can have a positive effect on the performance of algorithms. First, I'll note that nothing that can be done with sentinels cannot also be done with appropriately designed end iterators. Here, for instance, is the code for an iterator that can be used to adapt a null-terminated string to the STL. It is implemented with the help of the Boost.Iterators library: #include #include #include struct c_string_range { private: char const *str_; public: using const_iterator = struct iterator : boost::iterator_facade< iterator , char const , std::forward_iterator_tag > { private: friend class boost::iterator_core_access; friend struct c_string_range; char const * str_; iterator(char const * str) : str_(str) {} bool equal(iterator that) const { return str_ ? (that.str_ == str_ || (!that.str_ && !*str_)) : (!that.str_ || !*that.str_); } void increment() { assert(str_ && *str_); ++str_; } char const& dereference() const { assert(str_ && *str_); return *str_; } public: iterator() : str_(nullptr) {} }; c_string_range(char const * str) : str_(str) { assert(str_); } iterator begin() const { return iterator{str_}; } iterator end() const { return iterator{}; } explicit operator bool() const { return !!*str_; } }; int c_strlen(char const *sz) { int i = 0; for(; *sz; ++sz) ++i; return i; } int range_strlen( c_string_range::iterator begin, c_string_range::iterator end) { int i = 0; for(; begin != end; ++begin) ++i; return i; } The code traverses the sequence of characters without first computing its end. It does it by creating a dummy end iterator such that any time a real iterator is compared to it, it checks to see if the real iterator points to the null terminator. All the comparison logic is in the `c_string_range::iterator::equal` member function. The functions `c_strlen` and `range_strlen` implement equivalent procedures for computing the length of a string, the first using raw pointers and a check for the null terminator, the second using `c_string_range`'s STL iterators. The resulting optimized assembly code (clang 3.4 -O3 -DNDEBUG) generated for the two functions highlights the lost optimization opportunities. 
c_strlen
range_strlen
    pushl   %ebp
    movl    %esp, %ebp
    movl    8(%ebp), %ecx
    xorl    %eax, %eax
    cmpb    $0, (%ecx)
    je      LBB1_3
    xorl    %eax, %eax
    .align  16, 0x90
LBB1_2:
    cmpb    $0, 1(%ecx,%eax)
    leal    1(%eax), %eax
    jne     LBB1_2
LBB1_3:
    popl    %ebp
    ret
    pushl   %ebp
    movl    %esp, %ebp
    pushl   %esi
    leal    8(%ebp), %ecx
    movl    12(%ebp), %esi
    xorl    %eax, %eax
    testl   %esi, %esi
    movl    8(%ebp), %edx
    jne     LBB2_4
    jmp     LBB2_1
    .align  16, 0x90
LBB2_8:
    incl    %eax
    incl    %edx
    movl    %edx, (%ecx)
LBB2_4:
    testl   %edx, %edx
    jne     LBB2_5
    cmpb    $0, (%esi)
    jne     LBB2_8
    jmp     LBB2_6
    .align  16, 0x90
LBB2_5:
    cmpl    %edx, %esi
    jne     LBB2_8
    jmp     LBB2_6
    .align  16, 0x90
LBB2_3:
    leal    1(%edx,%eax), %esi
    incl    %eax
    movl    %esi, (%ecx)
LBB2_1:
    movl    %edx, %esi
    addl    %eax, %esi
    je      LBB2_6
    cmpb    $0, (%esi)
    jne     LBB2_3
LBB2_6:
    popl    %esi
    popl    %ebp
    ret
Code like `c_string_range` exists in the wild; for instance, see [Beman Dawes' `ntcts_iterator`][19][@ntcts-iterator]. But more typically, when users want to use an STL algorithm on a C-style string, they call `strlen` to find the end first (this is what the standard regex algorithms do when passed C-style strings). That traverses the string an extra time needlessly. Also, such a trick is not possible for input sequences like those traversed by `std::istream_iterator` that consume their input. Rather than mocking up a dummy end iterator with a computationally expensive equality comparison operation, we can use a sentinel type that encodes end-ness in its type. Below is an example from the [Range-v3 library][7][@range-v3], which uses a `range_facade` class template to generate iterators and sentinels from a simple range-like interface: using namespace ranges; struct c_string_iterable : range_facade { private: friend range_access; char const *sz_; char const & current() const { return *sz_; } void next() { ++sz_; } bool done() const { return *sz_ == 0; } bool equal(c_string_iterable const &that) const { return sz_ == that.sz_; } public: c_string_iterable() = default; c_string_iterable(char const *sz) : sz_(sz) {} }; // Iterable-based int iterable_strlen( range_iterator_t begin, range_sentinel_t end) { int i = 0; for(; begin != end; ++begin) ++i; return i; } The assembly generated for `iterable_strlen` is nearly identical to that for the hand-coded `c_strlen`: 
c_strlen
iterable_strlen
    pushl   %ebp
    movl    %esp, %ebp
    movl    8(%ebp), %ecx
    xorl    %eax, %eax
    cmpb    $0, (%ecx)
    je      LBB1_3
    xorl    %eax, %eax
    .align  16, 0x90
LBB1_2:
    cmpb    $0, 1(%ecx,%eax)
    leal    1(%eax), %eax
    jne     LBB1_2


LBB1_3:
    popl    %ebp
    ret
    pushl   %ebp
    movl    %esp, %ebp
    movl    8(%ebp), %ecx
    xorl    %eax, %eax
    cmpb    $0, (%ecx)
    je      LBB1_4
    leal    8(%ebp), %edx
    .align  16, 0x90
LBB1_2:
    cmpb    $0, 1(%ecx,%eax)
    leal    1(%eax), %eax
    jne     LBB1_2
    addl    %eax, %ecx
    movl    %ecx, (%edx)
LBB1_4:
    popl    %ebp
    ret
The generated code for `iterable_strlen` is better than for `range_strlen` because the sentinel has a different type than the iterator, so that the expression `begin != end` can be optimized into `*begin == 0`. In `range_strlen`, `begin == end` is comparing two objects of the same type, and since either `begin` or `end` could be a sentinel -- or both, or neither -- the compiler can't elide the extra checks without extra information from the surrounding calling context, which isn't always available; hence, the worse code gen. In addition to the performance impact, the complexity of implementing a correct `operator==` for an iterator with a dummy sentinel can present problems. Chandler Carruth reports that such comparison operators have been a rich source of bugs for Google. Appendix 2: Sentinels, Iterators, and the Cross-Type EqualityComparable Concept ===== This appendix describes the theoretical justification for sentinels from the perspective of the STL concepts as set out in [N3351][8][@n3351]. In that paper, the foundational concept EqualityComparable is described in depth, not only its syntactic constraints but also its semantic axioms. It is not enough that the syntax `a == b` compiles. It has to be a meaningful comparison. Here I explain why I believe it is meaningful to compare an iterator with a sentinel of a different type for equality. In the expression `x == y`, where `x` and `y` have different types, the EqualityComparable concept requires that the types of both `x` and `y` must themselves be EqualityComparable, and there must be a common type to which they can both be converted, and that type must also be EqualityComparable. Think of comparing a `char` with a `short`. It works because both `char` and `short` are EqualityComparable, and because they can both be converted to an `int` which is also EqualityComparable. Iterators are comparable, and sentinels are trivially comparable (they always compare equal). The tricky part is the common type requirement. Logically, every iterator/sentinel pair has a common type that can be constructed as follows: assume the existence of a new iterator type `I` that is a tagged union that contains *either* an iterator *or* a sentinel. When an iterator is compared to a sentinel, it behaves semantically as if both the iterator and the sentinel were first converted to two objects of type `I` — call them `lhs` and `rhs` — and then compared according to the following truth table: LHS IS SENTINEL ? | RHS IS SENTINEL ? | LHS == RHS ? ----------------- | ----------------- | ------------ `true` | `true` | `true`[\[*\]](#sentinel-equality "Sentinel Equality") `true` | `false` | `done(rhs.iter)` `false` | `true` | `done(lhs.iter)` `false` | `false` | `lhs.iter == rhs.iter` In [Appendix 1](#appendix-1-sentinels-and-code-generation), there is an implementation of `c_string_range` whose iterator's `operator==` is a procedure for evaluating this truth table. That’s no coincidence; that was a special case of this more general construction. In summary, for every iterator/sentinel pair, we can construct a common iterator type that implements an equivalent procedure for computing equality. The existence of this common type is what allows iterator/sentinel pairs to satisfy the EqualityComparable requirement. As a final note, the Range v3 library has a general implementation of this common iterator type as a parametrized type, and appropriate specializations of `std::common_type` that allow the constrained algorithms to type-check correctly. It works well in practice, both for the purpose of type-checking the algorithms and for adapting ranges with iterator/sentinel pairs to old code that expects the begin and end of a range to have the same type. ## Sentinel Equality The first line of table above shows that sentinels always compare equal -- regardless of their state. This can seem unintuitive in some situations. For instance: auto s = "Hello World!?"; // Hypothetical range-like facilities for exposition only: auto r1 = make_range( &s[0], equal_to('!') ); auto r2 = make_range( &s[0], equal_to('?') ); // 'end()' returns each 'equal_to' sentinel object: assert(r1.end() == r2.end() && "really?"); In the above example, it's clear that `r1.end()` and `r2.end()` are referring to different elements, and that's reflected in their having different state. So shouldn't sentinel equality be a stateful comparison? It's incorrect to think of sentinels as objects whose position is determined by their value. Thinking that way leads to logical inconsistencies. It's not hard to define sentinels that -- if you consider their state during comparison -- compare equal when they represent a different position, and not equal when they represent the same position. Consider: auto s = "hello! world!"; auto r1 = make_range( &s[0], equal_to('!') ); auto r2 = make_range( &s[7], equal_to('!') ); assert(r1.end() == r2.end() && "really?"); In the above code, although the sentinels have the same type and the same state, they refer to different elements. Also imagine a counted iterator that stores an underlying iterator and a count that starts at zero. It's paired with a sentinel that contains an ending count: auto s = "hello"; // Hypothetical range-like facilities for exposition only: auto r1 = make_range( counting(&s[0]), end_count(5) ); auto r2 = make_range( counting(&s[1]), end_count(4) ); assert(r1.end() != r2.end() && "really?"); The end sentinels have the same type and different state, but they refer to the same element. The question then is: What does it *mean* to compare sentinels for equality? The meaning has to be taken from the context in which the operation appears. In that context -- the algorithms -- the sentinel is one of two positions denoting a range. Iterator comparison is a position comparison. A sentinel, when it's paired with an iterator as in the algorithms, denotes a unique position. Since iterators must be valid sentinels, comparing sentinels should also be a position comparison. In this context, sentinels always represent the same position -- the end -- even though that position is not yet know. Hence, sentinels compare equal always, without any need to consider state. Anything else yields results that are inconsistent with the use of iterators to denote the end of a range. What about the examples above where sentinel comparison seems to give nonsensical results? In those examples, we are expecting sentinels to have meaning outside of their valid domain -- when they are considered in isolation of their paired iterator. It is the paired iterator that give the sentinel its "unique-position-ness", so we shouldn't expect an operation that compares position to make sense on an object that is not capable of representing a position by itself. Appendix 3: D Ranges and Algorithmic Complexity ===== As currently defined, D's ranges make it difficult to implement algorithms over bidirectional sequences that take a position in the middle as an argument. A good example is a hypothetical `is_word_boundary` algorithm. In C++ with iterators, it might look like this: template< BidirectionalIterator I > bool is_word_boundary( I begin, I middle, I end ) { bool is_word_prev = middle == begin ? false : isword(*prev(middle)); bool is_word_this = middle == end ? false : isword(*middle); return is_word_prev != is_word_this; } Users might call this in a loop to find the first word boundary in a range of characters as follows: auto i = myrange.begin(); for( ; i != myrange.end(); ++i ) if( is_word_boundary( myrange.begin(), i, myrange.end() ) ) break; The question is how such an API should be designed in D, since D doesn't have iterators. In a private email exchange, Andrei Alexandrescu, the designer of D's range library, described this potential implementation (the detailed implementation is ours): bool is_word_boundary(Range1, Range2)( Range1 front, Range2 back ) if (isBidirectionalRange!Range1 && isInputRange!Range2 ) { bool is_word_prev = front.empty ? false : isword(front.back); bool is_word_this = back.empty ? false : isword(back.front); return is_word_prev != is_word_this; } range r = myrange; size_t n = 0; for(range r = myrange; !r.empty; r.popFront(), ++n) if( is_word_boundary( takeExactly(myrange, n), r) ) break; This example uses D's `takeExactly` range adaptor. `takeExactly` is like Haskell's `take` function which creates a list from another list by taking the first `n` elements, but `takeExactly` requires that the input range has at least `n` elements begin with. The trouble with the above implementation is that `takeExactly` demotes Bidirectional ranges to Forward ranges. For example, taking the first *N* elements of a linked list cannot give access to the final element in O(1). So the `for` loop is trying to pass a Forward range to an algorithm that clearly requires a Bidirectional range. The only fix is to loosen the requirements of `Range1` to be Forward. To do that, the implementation of `is_word_boundary` needs to change so that, when it is passed a Forward range, it walks to the end of the `front` range and tests the last character. Obviously, that's an O(N) operation. In other words, by converting the `is_word_boundary` from iterators to D-style ranges, the algorithm goes from O(1) to O(N). From this we draw the following conclusion: D's choice of algorithmic *basis operations* is inherently less efficient than C++'s. Appendix 4: On Counted Ranges and Efficiency ===== The three types of ranges that we would like the Iterable concept to be able to efficiently model are: 1. Two iterators 2. An iterator and a predicate 3. An iterator and a count The Iterator/Sentinel abstraction is what makes it possible for the algorithms to handle these three cases with uniform syntax. However, the third option presents challenges when trying to make some algorithms optimally efficient. Counted ranges, formed by specifying a position and a count of elements, have iterators -- as all Iterables do. The iterators of a counted range must know the range's extent and how close they are to reaching it. Therefore, the counted range's iterators must store both an iterator into the underlying sequence and a count -- either a count to the end or a count from the front. Here is one potential design: class counted_sentinel {}; template class counted_iterator { I it_; DistanceType n_; // distance to end public: // ... constructors... using iterator_category = typename iterator_traits::iterator_category; decltype(auto) operator*() const { return *it_; } counted_iterator & operator++() { ++it_; --n_; return *this; } friend bool operator==(counted_iterator const & it, counted_sentinel) { return it.n_ == 0; } // ... other operators... }; template class counted_range { I begin_; DistanceType count_; public: // ... constructors ... counted_iterator begin() const { return {begin_, count_}; } counted_sentinel end() const { return {}; } }; template struct common_type, counted_sentinel> // ... see Appendix 2 ... There are some noteworthy things about the code above. First, `counted_iterator` bundles an iterator and a count. Right off, we see that copying counted iterators is going to be more expensive, and iterators are copied frequently. A mitigating factor is that the sentinel is empty. Passing a `counted_iterator` and a `counted_sentinel` to an algorithm copies as much data as passing an iterator and a count. When passed separately, the compiler probably has an easier time fitting them in registers, but some modern compilers are capable passing the members of a struct in registers. This compiler optimization is sometimes called Scalar Replacement of Aggregates (see Muchnick 1997, ch. 12.2 [@muchnick97]) and is known to be implemented in gcc and LLVM (see [this recent LLVM commit][15][@llvm-sroa] for example). Also, incrementing a counted iterator is expensive: it involves incrementing the underlying iterator and decrementing the internal count. To see why this is potentially expensive, consider the trivial case of passing a `counted_iterator::iterator>` to `advance`. That counted iterator type is bidirectional, and `advance` must increment it *n* times: template void advance(I & i, DistanceType n) { if(n >= 0) for(; n != 0; --n) ++i; else for(; n != 0; ++n) --i; } Notice that for each `++i` or `--i` here, *two* increments or decrements are happening when `I` is a `counted_iterator`. This is sub-optimal. A better implementation for `counted_iterator` is: template void advance(counted_iterator & i, DistanceType n) { i.n_ -= n; advance(i.it_, n); } This has a noticeable effect on the generated code. As it turns out, `advance` is one of the relatively few places in the standard library where special handling of `counted_iterator` is advantageous. Let's examine some algorithms to see why that's the case. ## Single-Pass Algorithms with Counted Iterators First, let's look at a simple algorithm like `for_each` that makes exactly one pass through its input sequence: template> F> requires EqualityComparable I for_each(I first, S last, F f) { for(; first != last; ++first) f(*first); return first; } When passed counted iterators, at each iteration of the loop, we do an increment, a decrement (for the underlying iterator and the count), and a comparison. Let's compare this against a hypothetical `for_each_n` algorithm that takes the underlying iterator and the count separately. It might look like this: template> F> I for_each_n(I first, DifferenceType n, F f) { for(; n != 0; ++first, --n) f(*first); return first; } For the hypothetical `for_each_n`, at each loop iteration, we do an increment, a decrement, and a comparison. That's exactly as many operations as `for_each` does when passed counted iterators. So a separate `for_each_n` algorithm is probably unnecessary if we have sentinels and `counted_iterator`s. This is true for any algorithm that makes only one pass through the input range. That turns out to be a lot of algorithms. ## Multi-Pass Algorithms with Counted Iterators There are other algorithms that make more than one pass over the input sequence. Most of those, however, use `advance` when they need to move iterators by more than one hop. Once we have specialized `advance` for `counted_iterator`, those algorithms that use `advance` get faster without any extra work. Consider `partition_point`. Here is one example implementation, taken from [libc++][17][@libcxx] and ported to Concepts Lite and sentinels: template> P> requires EqualityComparable I partition_point(I first, S last, P pred) { DifferenceType len = distance(first, last); while (len != 0) { DifferenceType l2 = len / 2; I m = first; advance(m, l2); if (pred(*m)) { first = ++m; len -= l2 + 1; } else len = l2; } return first; } Imagine that `I` is a forward `counted_iterator` and `S` is a `counted_sentinel`. If the library does not specialize `advance`, this is certainly inefficient. Every time `advance` is called, needless work is being done. Compare it to a hypothetical `partition_point_n`: template> P> I partition_point_n(I first, DifferenceType len, P pred) { while (len != 0) { DifferenceType l2 = len / 2; I m = first; advance(m, l2); if (pred(*m)) { first = ++m; len -= l2 + 1; } else len = l2; } return first; } The first thing we notice is that `partition_point_n` doesn't need to call `distance`! The more subtle thing to note is that calling `partition_point_n` with a raw iterator and a count saves about O(N) integer decrements over the equivalent call to `partition_point` with `counted_iterator`s ... unless, of course, we have specialized the `advance` algorithm as shown above. Once we have, we trade the O(N) integer decrements for O(log N) integer subtractions. That's a big improvement. But what about the O(N) call to `distance`? Actually, that's easy, and it's the reason why the SizedIteratorRange concept exists. `counted_iterator` stores the distance to the end. So the distance between a `counted_iterator` and a `counted_sentinel` (or between two `counted_iterators`) is known in O(1) *regardless of the iterator's category*. The SizedIteratorRange concept tests whether an iterator `I` and a sentinel `S` can be subtracted to get the distance. This concept is modeled by random-access iterators by their nature, but also by counted iterators and their sentinels. The `distance` algorithm is specialized for SizedIteratorRange, so it is O(1) for counted iterators. With these changes, we see that `partition_point` with counted iterators is very nearly as efficient as a hypothetical `partition_point_n` would be, and we had to make no special accommodations. Why can't we make `partition_point` *exactly* as efficient as `partition_point_n`? When `partition_point` is called with a counted iterator, it also *returns* a counted iterator. Counted iterators contain two datums: the position and distance to the end. But when `partition_point_n` returns just the position, it is actually computing and returning less information. Sometimes users don't need the extra information. But sometimes, after calling `partition_point_n`, the user might want to pass the resulting iterator to another algorithm. If *that* algorithm calls `distance` (like `partition_point` and other algorithms do), then it will be O(N). With counted iterators, however, it's O(1). So in the case of `partition_point`, counted iterators cause the algorithm to do O(log N) extra work, but it sometimes saves O(N) work later. To see an example, imagine a trivial `insertion_sort` algorithm: template requires EqualityComparable && Sortable // from N3351 void insertion_sort(I begin, S end) { for(auto it = begin; it != end; ++it) { auto insertion = upper_bound(begin, it, *it); rotate(insertion, it, next(it)); } } Imagine that `I` is a `counted_iterator`. The first thing `upper_bound` does is call `distance`. Making `distance` O(1) for `counted_iterator`s saves N calls of an O(N) algorithm. To get comparable performance for an equivalent procedure in today's STL, users would have to write a separate `insertion_sort_n` algorithm that dispatches to an `upper_bound_n` algorithm -- that they would also need to write themselves. ## Counted Algorithms with Counted Iterators We've seen that regular algorithms with counted iterators can be made nearly as efficient as dedicated counted algorithms, and that sometimes we are more than compensated for the small performance loss. All is not roses, however. There are a number of *counted algorithms* in the standard (the algorithms whose names end with `_n`). Consider `copy_n`: template> O> pair copy_n(I in, DifferenceType n, O out) { for(; n != 0; ++in, ++out, --n) *out = *in; return {in, out}; } (We've changed the return type of `copy_n` so as not to lose information.) If `I` is a counted iterator, then for every `++in`, an increment and a decrement are happening, and in this case the extra decrement is totally unnecessary. For *any* counted (i.e., `_n`) algorithm, something special needs to be done to keep the performance from degrading when passed counted iterators. The algorithm author has two options here, and neither of them is ideal. **Option 1: Overload the algorithm** The following is an optimized version of `copy_n` for counted iterators: template> O> pair copy_n(counted_iterator in, DifferenceType n, O out) { for(auto m = in.n_ - n; in.n_ != m; ++in.i_, --in.n_, ++out) *out = *in; return {in, out}; } Obviously, creating an overload for counted iterators is unsatisfying. **Option 2: Separate the iterator from the count** This option shows how a library implementer can write just one version of `copy_n` that is automatically optimized for counted iterators. First, we need to provide two utility functions for unpacking and repacking counted iterators: template I uncounted(I i) { return i; } template I uncounted(counted_iterator i) { return i.it_; } template I recounted(I const &, I i, DifferenceType) { return i; } template counted_iterator recounted(counted_iterator const &j, I i, DifferenceType n) { return {i, j.n_ - n}; } With the help of `uncounted` and `recounted`, we can write an optimized `copy_n` just once: template> O> pair copy_n(I in_, DifferenceType n_, O out) { auto in = uncounted(in_); for(auto n = n_; n != 0; ++in, --n, ++out) *out = *in; return {recounted(in_, in, n_), out}; } This version works optimally for both counted and non-counted iterators. It is not a thing of beauty, however. It's slightly annoying to have to do the `uncounted`/`recounted` dance, but it's mostly needed only in the counted algorithms. As a final note, the overload of `advance` for counted iterators can be eliminated with the help of `uncounted` and `recounted`. After all, `advance` is a counted algorithm. ## Benchmark: Insertion Sort To test how expensive counted ranges and counted iterators are, we wrote a benchmark. The benchmark program pits counted ranges against a dedicated `_n` algorithm for [Insertion Sort](http://en.wikipedia.org/wiki/Insertion_sort). The program is listed below: #include #include #include class timer { private: std::chrono::high_resolution_clock::time_point start_; public: timer() { reset(); } void reset() { start_ = std::chrono::high_resolution_clock::now(); } std::chrono::milliseconds elapsed() const { return std::chrono::duration_cast( std::chrono::high_resolution_clock::now() - start_); } friend std::ostream &operator<<(std::ostream &sout, timer const &t) { return sout << t.elapsed().count() << "ms"; } }; template struct forward_iterator { It it_; template friend struct forward_iterator; public: typedef std::forward_iterator_tag iterator_category; typedef typename std::iterator_traits::value_type value_type; typedef typename std::iterator_traits::difference_type difference_type; typedef It pointer; typedef typename std::iterator_traits::reference reference; forward_iterator() : it_() {} explicit forward_iterator(It it) : it_(it) {} reference operator*() const {return *it_;} pointer operator->() const {return it_;} forward_iterator& operator++() {++it_; return *this;} forward_iterator operator++(int) {forward_iterator tmp(*this); ++(*this); return tmp;} friend bool operator==(const forward_iterator& x, const forward_iterator& y) {return x.it_ == y.it_;} friend bool operator!=(const forward_iterator& x, const forward_iterator& y) {return !(x == y);} }; template I upper_bound_n(I begin, typename std::iterator_traits::difference_type d, V2 const &val) { while(0 != d) { auto half = d / 2; auto middle = std::next(begin, half); if(val < *middle) d = half; else { begin = ++middle; d -= half + 1; } } return begin; } template void insertion_sort_n(I begin, typename std::iterator_traits::difference_type n) { auto m = 0; for(auto it = begin; m != n; ++it, ++m) { auto insertion = upper_bound_n(begin, m, *it); ranges::rotate(insertion, it, std::next(it)); } } template void insertion_sort(I begin, S end) { for(auto it = begin; it != end; ++it) { auto insertion = ranges::upper_bound(begin, it, *it); ranges::rotate(insertion, it, std::next(it)); } } template void insertion_sort(Rng && rng) { ::insertion_sort(std::begin(rng), std::end(rng)); } std::unique_ptr data(int i) { std::unique_ptr a(new int[i]); auto rng = ranges::view::counted(a.get(), i); ranges::iota(rng, 0); return a; } void shuffle(int *a, int i) { auto rng = ranges::view::counted(a, i); ranges::random_shuffle(rng); } constexpr int cloops = 3; template void benchmark_n(int i) { auto a = data(i); long ms = 0; for(int j = 0; j < cloops; ++j) { ::shuffle(a.get(), i); timer t; insertion_sort_n(I{a.get()}, i); ms += t.elapsed().count(); } std::cout << (int)((double)ms/cloops) << std::endl; } template void benchmark_counted(int i) { auto a = data(i); long ms = 0; for(int j = 0; j < cloops; ++j) { ::shuffle(a.get(), i); timer t; insertion_sort(ranges::view::counted(I{a.get()}, i)); ms += t.elapsed().count(); } std::cout << (int)((double)ms/cloops) << std::endl; } int main(int argc, char *argv[]) { if(argc < 2) return -1; int i = std::atoi(argv[1]); std::cout << "insertion_sort_n (random-access) : "; benchmark_n(i); std::cout << "insertion_sort (random-access) : "; benchmark_counted(i); std::cout << "\n"; std::cout << "insertion_sort_n (forward) : "; benchmark_n>(i); std::cout << "insertion_sort (forward) : "; benchmark_counted>(i); } The program implements both `insertion_sort_n`, a dedicated counted algorithm, and `insertion_sort`, a general algorithm that accepts any Iterable, to which we pass a counted range. The latter is implemented in terms of the general-purpose `upper_bound` as provided by the Range v3 library, whereas the former requires a dedicated `upper_bound_n` algorithm, which is also provided. The test is run both with raw pointers (hence, random-access) and with an iterator wrapper that only models ForwardIterator. Each test is run three times, and the resulting times are averaged. The test was compiled with `g++` version 4.9.0 with `-O3 -std=gnu++11 -DNDEBUG` and run on a Linux machine. The results are reported below, for N == 30,000:   | `insertion_sort_n` | `insertion_sort` --------------|--------------------|----------------- random-access | 2.692 s | 2.703 s forward | 23.853 s | 23.817 s The performance difference, if there is any, is lost in the noise. At least in this case, with this compiler, on this hardware, there is no performance justification for a dedicated `_n` algorithm. **Summary** In short, counted iterators are not a *perfect* abstraction. There is some precedent here. The iterators for `deque`, and for any segmented data structure, are known to be inefficient (see [Segmented Iterators and Hierarchical Algorithms][14], Austern 1998[@austern98]). The fix for that problem, new iterator abstractions and separate hierarchical algorithm implementations, is invasive and is not attempted in any STL implementation we are aware of. In comparison, the extra complications that come with counted iterators seem quite small. For segmented iterators, the upside was the simplicity and uniformity of the Iterator abstraction. In the case of counted ranges and iterators, the upside is the simplicity and uniformity of the Iterable concept. Algorithms need only one form, not separate bounded, counted, and sentinel forms. Our benchmark gives us reasonable assurance that we aren't sacrificing performance for the sake of a unifying abstraction. Appendix 5: Drive-By Improvements to the Standard Algorithms ===== As we are making changes to the standard algorithms, not all of which are strictly source compatible, here are some other drive-by changes that we might consider making. The changes suggested below have nothing to do with ranges *per se*, but they increase the power and uniformity of the STL and they have proven useful in the Adobe Source Library, so we might consider taking all these changes in one go. ## Higher-Order Algorithms Should Take Invokables Instead of Functions Some algorithms like `for_each` are higher-order; they take functions as parameters. In [N3351][8][@n3351], they are constrained with the `Function` concept which, among other things, requires that its parameters can be used to form a valid callable expression `f(a)`. However, consider a class `S` with a member function `Do`, like: class S { public: void Do() const; }; If we have a `vector` of `S` objects and we want to `Do` all of them, this is what we need to do: for_each( v, [](auto & s) { s.Do(); }); or, more concisely with a `bind` expression: for_each( v, bind(&S::Do, _1) ); Note that `bind` is specified in terms of a hypothetical INVOKE utility in [func.require]. Wouldn't it be more convenient if all the algorithms were required to merely take INVOKE-able things -- that is, things that can be passed to `bind` -- as arguments, instead of Functions? Then we can express the above call to `for_each` more concisely as: for_each( v, &S::Do ); We can define an `invokable` utility function as: template auto invokable(R T::* p) const -> decltype(std::mem_fn(p)) { return std::mem_fn(p); } template> auto invokable(T && t) const -> enable_if_t::value, T> { return std::forward(t); } template using invokable_t = decltype(invokable(std::declval())); We can define an Invokable concept as: concept Invokable = Function, As...> && requires (F f, As... as) { InvokableResultOf; InvokableResultOf == invokable(f)(as...); }; The Invokable concept can be used to constrain algorithms instead of the Function concept. The algorithms would need to apply `invokable` to each Invokable argument before invoking it. This is pure extension and would break no code. ## Algorithms Should Take Invokable Projections The [Adobe Source Libraries (ASL)][3][@asl] pioneered the use of "projections" to make the algorithms more powerful and expressive by increasing interface symmetry. Sean Parent gives a motivating example in his ["C++ Seasoning" talk][6][@cpp-seasoning], on slide 38. With today's STL, when using `sort` and `lower_bound` together with user-defined predicates, the predicate must sometimes differ. Consider: std::sort(a, [](const employee& x, const employee& y) { return x.last < y.last; }); auto p = std::lower_bound(a, "Parent", [](const employee& x, const string& y) { return x.last < y; }); Notice the different predicates used in the invocations of `sort` and `lower_bound`. Since the predicates are different, there is a chance they might get out of sync leading to subtle bugs. By introducing the use of projections, this code is simplified to: std::sort(a, std::less<>(), &employee::last); auto p = std::lower_bound(a, "Parent", std::less<>(), &employee::last); Every element in the input sequence is first passed through the projection `&employee::last`. As a result, the simple comparison predicate `std::less<>` can be used in both places. No effort was made in ASL to use projections consistently. This proposal bakes them in everywhere it makes sense. Here are the guidelines to be applied to the standard algorithms: - Wherever appropriate, algorithms should optionally take INVOKE-able *projections* that are applied to each element in the input sequence(s). This, in effect, allows users to trivially transform each input sequence for the sake of that single algorithm invocation. - Algorithms that take two input sequences should (optionally) take two projections. - For algorithms that optionally accept functions/predicates (e.g. `transform`, `sort`), projection arguments follow functions/predicates. There are no algorithm overloads that allow the user to specify the projection without also specifying a predicate, even if the default would suffice. This is to reduce the number of overloads and also to avoid any potential for ambiguity. An open design question is whether all algorithms should take projections, or only the higher-order algorithms. In our current design, all algorithms take projections. This makes it trivial to, say, copy all the keys of a map by using the standard `copy` algorithm with `&pair::first` as the projection. ### Projections versus Range Transform View In a sense, the use of a projection parameter to an algorithm is similar to applying a transform view directly to a range. For example, calling `std::find` with a projection is similar to applying a transform to a range and calling without the projection: auto it = std::find( a, 42, &employee::age ); auto a2 = a | view::transform( &employee::age ); auto it2 = std::find( a2, 42 ); Aside from the extra verbosity of the view-based solution, there are two meaningful differences: (1) The type of the resulting iterator is different; `*it` refers to an `employee` whereas `*it2` refers to an `int`. And (2) if the transform function returns an rvalue, then the transformed view cannot model a forward sequence due to the current requirements on the ForwardIterator concept. The result of applying a transform view is an Input range unless the transform function returns an lvalue. The projection-based interface suffers no such degradation of the iterator category. (Note: if the concepts in [N3351][8][@n3351] are adopted, this argument is no longer valid.) For those reasons, range transform adapters are not a replacement for projection arguments to algorithms. See [Algorithm Implementation with Projections](#algorithm-implementation-with-projections) for a discussion of how projections affect the implementation. The addition of projection arguments to the algorithms is pure extension. Appendix 6: Implementation Notes ===== ## On Distinguishing Ranges from Non-Range Iterables The design of the range library depends on the ability to tell apart Ranges from Iterables. Ranges are lightweight objects that refer to elements they do not own. As a result, they can guarantee O(1) copyability and assignability. Iterables, on the other hand, may or may not own their elements, and so cannot guarantee anything about the algorithmic complexity of their copy and assign operations. Indeed, an Iterable may not be copyable at all: it may be a native array or a `vector` of move-only types. But how to tell Ranges apart from Iterables? After all, whether an Iterable owns its elements or not is largely a semantic difference with no purely syntactic way to differentiate. Well, that's almost true... It turns out that there is a reasonably good heuristic we can use to tell Iterables and Ranges apart. Imagine that we have some Iterable type `T` that is either a container like `list`, `vector`, or a native array; or else it's a Range like `pair`. Then we can imagine taking iterators to `T` and `const T`, dereferencing them, and comparing the resulting reference types. The following table gives the results we might expect to find. Expression | Container | Range --------------------------------|-----------------------|----------------------- `*begin(declval())` | `value_type &` | `[const] value_type &` `*begin(declval())` | `const value_type &` | `[const] value_type &` Notice how containers and ranges differ in the way a top-level cv-qualifier affects the reference type. Since a range is a proxy to elements stored elsewhere, a top-level `const` qualification on the *range* object typically has no effect at all on its iterator's reference type. But that's not true for a container that owns its elements. We can use this to build an `is_range` traits that gives a pretty good guess whether an Iterable type is a range or not. This trait can be used to define the Range concept. Obviously since it's a trait, users are free to specialize it if the trait guesses wrong. Some people want their range types to behave like containers with respect to the handling of top-level `const`; that is, they would like their ranges to be designed such that if the range object is `const`, the range's elements cannot be mutated through it. There is nothing about the Range concepts that precludes that design, but it does require the developer of such a range to specialize the `is_range` trait. If anything, the default behavior of the trait can be seen as gentle encouragement to handle top-level `const` in a way that is consistent with ranges' nature as a lightweight proxy. As an added convenience, we can provide a class, `range_base`, from which users can create a derived type as another way of opting in to "range-ness". The `is_range` trait can test for derivation from `range_base` as an extra test. This would save users the trouble of opening the `std` namespace to specialize the `is_range` trait on the rare occasions that that is necessary. The `is_range` trait will also need to be specialized for immutable containers, for which both the mutable and const iterators have the same reference type. A good example is `std::set`. If the `is_range` trait erroneously reports `false` for a type that is actually a range, then the library errs on the side of caution and will prevent the user from using rvalues of that type in range adaptor pipelines. If, on the other hand, the `is_range` trait gets the answer wrong for a type that is actually a container, the container ends up being copied or moved into range adaptors. This is a performance bug, and it may give surprising results at runtime if the original container doesn't get mutated when the user thinks it should. It's not a memory error, though. ## Algorithm Implementation with Projections Rather than requiring additional overloads, the addition of projection arguments has very little cost to library implementers. The use of function template default parameters obviates the need for overloads. For instance, `find` can be defined as: template> Proj = identity> requires EqualityComparable && EqualityComparable>> I find(I first, S last, V const & val, Proj proj = Proj{}) { /* ... */ } ## Algorithms That Need An End Iterator Some algorithms need to know the real physical end of the input sequence so that the sequence can be traversed backwards, like `reverse`. In those cases, it's helpful to have an algorithm `advance_to` that takes an iterator and a sentinel and returns a real end iterator. `advance_to` looks like this: template requires IteratorRange I advance_to( I i, S s ) { while(i != s) ++i; return i; } template requires SizedIteratorRange I advance_to( I i, S s ) { advance( i, s - i ); return i; } template I advance_to( I, I s ) { return s; } When the sentinel is actually an iterator, we already know where the end is so we can just return it. Notice how we handle SizedIteratorRanges specially and dispatch to `advance` with a count. [Appendix 4](#appendix-4-on-counted-ranges-and-efficiency) shows how `advance` is optimized for counted iterators. By dispatching to `advance` when we can, we make `advance_to` faster for counted iterators, too. With `advance_to` we can implement `reverse` generically as: template requires EqualityComparable && Permutable I reverse( I first, S last_ ) { I last = advance_to( first, last_ ), end = last; while( first != last ) { if( first == --last ) break; iter_swap( first, last ); ++first; } return end; } Since this algorithm necessarily computes the end of the sequence if it isn't known already, we return it. range-v3-0.3.5/doc/std/header.html000066400000000000000000000016721324212031100166110ustar00rootroot00000000000000
Document number: D4128=yy-nnnn
Date: 2014-10-10
Project: Programming Language C++, Library Working Group
Reply-to: Eric Niebler <eniebler@boost.org>,
Sean Parent <sparent@adobe.com>,
Andrew Sutton <andrew.n.sutton@gmail.com>
range-v3-0.3.5/doc/std/pandoc-template.html000066400000000000000000000031671324212031100204370ustar00rootroot00000000000000 $for(author-meta)$ $endfor$ $if(date-meta)$ $endif$ $if(title-prefix)$$title-prefix$ - $endif$$pagetitle$ $if(quotes)$ $endif$ $if(highlighting-css)$ $endif$ $for(css)$ $endfor$ $if(math)$ $math$ $endif$ $for(header-includes)$ $header-includes$ $endfor$ $for(include-before)$ $include-before$ $endfor$ $if(title)$

$title$

$if(subtitle)$

$subtitle$

$endif$ $for(author)$

$author$

$endfor$ $if(date)$

$date$

$endif$
$endif$

“A beginning is the time for taking the most delicate care that the balances are correct.”

– Frank Herbert, Dune

$if(toc)$
$toc$
$endif$ $body$ $for(include-after)$ $include-after$ $endfor$ range-v3-0.3.5/doc/std/show.cmd000066400000000000000000000003521324212031100161320ustar00rootroot00000000000000pandoc -f markdown_github+yaml_metadata_block+citations -t html -o D4128.html --filter pandoc-citeproc --csl=acm-sig-proceedings.csl --number-sections --toc -s -S --template=pandoc-template --include-before-body=header.html D4128.md range-v3-0.3.5/example/000077500000000000000000000000001324212031100145615ustar00rootroot00000000000000range-v3-0.3.5/example/BUCK000066400000000000000000000004731324212031100152340ustar00rootroot00000000000000cxx_binary( name = 'comprehensions', srcs = [ 'comprehensions.cpp', ], deps = [ '//:range-v3', ], compiler_flags = [ '-std=c++14', ], ) cxx_binary( name = 'fibonacci', srcs = [ 'fibonacci.cpp', ], deps = [ '//:range-v3', ], compiler_flags = [ '-std=c++14', ], ) range-v3-0.3.5/example/CMakeLists.txt000066400000000000000000000030151324212031100173200ustar00rootroot00000000000000# examples use a less draconian set of compiler warnings ranges_append_flag(RANGES_HAS_WNO_MISSING_BRACES -Wno-missing-braces) add_executable(comprehensions comprehensions.cpp) target_link_libraries(comprehensions range-v3) add_test(example.comprehensions, comprehensions) add_executable(hello hello.cpp) target_link_libraries(hello range-v3) add_test(example.hello, hello) add_executable(count count.cpp) target_link_libraries(count range-v3) add_test(example.count, count) add_executable(count_if count_if.cpp) target_link_libraries(count_if range-v3) add_test(example.count_if, count_if) # add_executable(fibonacci fibonacci.cpp) # target_link_libraries(fibonacci range-v3) # add_test(example.fibonacci, fibonacci) # Guarded with a variable because the calendar example causes gcc to puke. if(RANGES_BUILD_CALENDAR_EXAMPLE) set(Boost_USE_STATIC_LIBS ON) set(Boost_USE_MULTITHREADED OFF) set(Boost_USE_STATIC_RUNTIME OFF) find_package(Boost 1.59.0 COMPONENTS date_time program_options) if (Boost_FOUND) include_directories(SYSTEM ${Boost_INCLUDE_DIRS}) add_executable(calendar calendar.cpp) target_link_libraries(calendar range-v3) target_link_libraries(calendar ${Boost_LIBRARIES}) message ("boost: ${Boost_LIBRARY_DIRS}") target_compile_definitions(calendar PUBLIC -DBOOST_NO_AUTO_PTR) target_compile_options(calendar PRIVATE -std=gnu++14) set_target_properties(calendar PROPERTIES LINK_FLAGS "-L${Boost_LIBRARY_DIRS}") endif() endif() range-v3-0.3.5/example/calendar.cpp000066400000000000000000000273531324212031100170500ustar00rootroot00000000000000// Range v3 library // // Copyright Eric Niebler 2013-present // // Use, modification and distribution is subject to the // Boost Software License, Version 1.0. (See accompanying // file LICENSE_1_0.txt or copy at // http://www.boost.org/LICENSE_1_0.txt) // // Project home: https://github.com/ericniebler/range-v3 // // Usage: // calendar 2015 // // Output: /* January February March 1 2 3 1 2 3 4 5 6 7 1 2 3 4 5 6 7 4 5 6 7 8 9 10 8 9 10 11 12 13 14 8 9 10 11 12 13 14 11 12 13 14 15 16 17 15 16 17 18 19 20 21 15 16 17 18 19 20 21 18 19 20 21 22 23 24 22 23 24 25 26 27 28 22 23 24 25 26 27 28 25 26 27 28 29 30 31 29 30 31 April May June 1 2 3 4 1 2 1 2 3 4 5 6 5 6 7 8 9 10 11 3 4 5 6 7 8 9 7 8 9 10 11 12 13 12 13 14 15 16 17 18 10 11 12 13 14 15 16 14 15 16 17 18 19 20 19 20 21 22 23 24 25 17 18 19 20 21 22 23 21 22 23 24 25 26 27 26 27 28 29 30 24 25 26 27 28 29 30 28 29 30 31 July August September 1 2 3 4 1 1 2 3 4 5 5 6 7 8 9 10 11 2 3 4 5 6 7 8 6 7 8 9 10 11 12 12 13 14 15 16 17 18 9 10 11 12 13 14 15 13 14 15 16 17 18 19 19 20 21 22 23 24 25 16 17 18 19 20 21 22 20 21 22 23 24 25 26 26 27 28 29 30 31 23 24 25 26 27 28 29 27 28 29 30 30 31 October November December 1 2 3 1 2 3 4 5 6 7 1 2 3 4 5 4 5 6 7 8 9 10 8 9 10 11 12 13 14 6 7 8 9 10 11 12 11 12 13 14 15 16 17 15 16 17 18 19 20 21 13 14 15 16 17 18 19 18 19 20 21 22 23 24 22 23 24 25 26 27 28 20 21 22 23 24 25 26 25 26 27 28 29 30 31 29 30 27 28 29 30 31 // */ // Credits: // Thanks to H. S. Teoh for the article that served as the // inspiration for this example: // // Thanks to github's Arzar for bringing date::week_number // to my attention. #include #if RANGES_CXX_RETURN_TYPE_DEDUCTION >= RANGES_CXX_RETURN_TYPE_DEDUCTION_14 && \ RANGES_CXX_GENERIC_LAMBDAS >= RANGES_CXX_GENERIC_LAMBDAS_14 #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include namespace po = boost::program_options; namespace greg = boost::gregorian; using date = greg::date; using day = greg::date_duration; using namespace ranges; namespace boost { namespace gregorian { date &operator++(date &d) { return d = d + day(1); } date operator++(date &d, int) { return ++d - day(1); } }} namespace ranges { template<> struct difference_type { using type = date::duration_type::duration_rep::int_type; }; } CONCEPT_ASSERT(Incrementable()); auto dates(unsigned short start, unsigned short stop) { return view::iota(date{start,greg::Jan,1}, date{stop,greg::Jan,1}); } auto dates_from(unsigned short year) { return view::iota(date{year,greg::Jan,1}); } auto by_month() { return view::group_by([](date a, date b) { return a.month() == b.month(); }); } auto by_week() { return view::group_by([](date a, date b) { // ++a because week_number is Mon-Sun and we want Sun-Sat return (++a).week_number() == (++b).week_number(); }); } std::string format_day(date d) { return boost::str(boost::format("%|3|") % d.day()); } // In: Range>: month grouped by weeks. // Out: Range: month with formatted weeks. auto format_weeks() { return view::transform([](/*Range*/ auto week) { return boost::str(boost::format("%1%%2%%|22t|") % std::string(front(week).day_of_week() * 3u, ' ') % (week | view::transform(format_day) | action::join)); }); } // Return a formatted string with the title of the month // corresponding to a date. std::string month_title(date d) { return boost::str(boost::format("%|=22|") % d.month().as_long_string()); } // In: Range>: year of months of days // Out: Range>: year of months of formatted wks auto layout_months() { return view::transform([](/*Range*/ auto month) { auto week_count = static_cast(distance(month | by_week())); return view::concat( view::single(month_title(front(month))), month | by_week() | format_weeks(), view::repeat_n(std::string(22,' '),6-week_count)); }); } namespace cal_example { // In: Range // Out: Range>, where each inner range has $n$ elements. // The last range may have fewer. template class chunk_view : public view_adaptor, Rng> { CONCEPT_ASSERT(ForwardRange()); ranges::range_difference_type_t n_; friend range_access; class adaptor; adaptor begin_adaptor() { return adaptor{n_, ranges::end(this->base())}; } public: chunk_view() = default; chunk_view(Rng rng, ranges::range_difference_type_t n) : chunk_view::view_adaptor(std::move(rng)), n_(n) {} }; template class chunk_view::adaptor : public adaptor_base { ranges::range_difference_type_t n_; sentinel_t end_; public: adaptor() = default; adaptor(ranges::range_difference_type_t n, sentinel_t end) : n_(n), end_(end) {} auto read(iterator_t it) const { return view::take(make_iterator_range(std::move(it), end_), n_); } void next(iterator_t &it) { ranges::advance(it, n_, end_); } void prev() = delete; void distance_to() = delete; }; } // namespace cal_example // In: Range // Out: Range>, where each inner range has $n$ elements. // The last range may have fewer. auto chunk(std::size_t n) { return make_pipeable([=](auto&& rng) { using Rng = decltype(rng); return cal_example::chunk_view>{ view::all(std::forward(rng)), static_cast>(n)}; }); } // Flattens a range of ranges by iterating the inner // ranges in round-robin fashion. template class interleave_view : public view_facade> { friend range_access; std::vector> rngs_; struct cursor; cursor begin_cursor() { return {0, &rngs_, view::transform(rngs_, ranges::begin)}; } public: interleave_view() = default; explicit interleave_view(Rngs rngs) : rngs_(std::move(rngs)) {} }; template struct interleave_view::cursor { std::size_t n_; std::vector> *rngs_; std::vector>> its_; decltype(auto) read() const { return *its_[n_]; } void next() { if(0 == ((++n_) %= its_.size())) for_each(its_, [](auto& it){ ++it; }); } bool equal(default_sentinel) const { return n_ == 0 && its_.end() != mismatch(its_, *rngs_, std::not_equal_to<>(), ident(), ranges::end).in1(); } CONCEPT_REQUIRES(ForwardRange>()) bool equal(cursor const& that) const { return n_ == that.n_ && its_ == that.its_; } }; // In: Range> // Out: Range, flattened by walking the ranges // round-robin fashion. auto interleave() { return make_pipeable([](auto&& rngs) { using Rngs = decltype(rngs); return interleave_view>( view::all(std::forward(rngs))); }); } // In: Range> // Out: Range>, transposing the rows and columns. auto transpose() { return make_pipeable([](auto&& rngs) { using Rngs = decltype(rngs); CONCEPT_ASSERT(ForwardRange()); return std::forward(rngs) | interleave() | chunk(static_cast(distance(rngs))); }); } // In: Range>> // Out: Range>>, transposing months. auto transpose_months() { return view::transform([](/*Range>*/ auto rng) { return rng | transpose(); }); } // In: Range> // Out: Range, joining the strings of the inner ranges auto join_months() { return view::transform([](/*Range*/ auto rng) { return action::join(rng); }); } // In: Range // Out: Range, lines of formatted output auto format_calendar(std::size_t months_per_line) { return make_pipeable([=](auto && rng) { using Rng = decltype(rng); return std::forward(rng) // Group the dates by month: | by_month() // Format the month into a range of strings: | layout_months() // Group the months that belong side-by-side: | chunk(months_per_line) // Transpose the rows and columns of the size-by-side months: | transpose_months() // Ungroup the side-by-side months: | view::join // Join the strings of the transposed months: | join_months(); }); } int main(int argc, char *argv[]) try { // Declare the supported options. po::options_description desc("Allowed options"); desc.add_options() ("help", "produce help message") ("start", po::value(), "Year to start") ("stop", po::value(), "Year to stop") ("per-line", po::value()->default_value(3u), "Nbr of months per line") ; po::positional_options_description p; p.add("start", 1).add("stop", 1); po::variables_map vm; po::store(po::command_line_parser(argc, argv). options(desc).positional(p).run(), vm); po::notify(vm); if(vm.count("help") || 1 != vm.count("start")) { std::cerr << desc << '\n'; return 1; } auto const start = vm["start"].as(); auto const stop = 0 == vm.count("stop") ? (unsigned short)(start + 1) : vm["stop"].as() == "never" ? (unsigned short)-1 : boost::lexical_cast(vm["stop"].as()); auto const months_per_line = vm["per-line"].as(); if(stop != (unsigned short)-1 && stop <= start) { std::cerr << "ERROR: The stop year must be larger than the start" << '\n'; return 1; } if((unsigned short)-1 != stop) { copy(dates(start, stop) | format_calendar(months_per_line), ostream_iterator<>(std::cout, "\n")); } else { copy(dates_from(start) | format_calendar(months_per_line), ostream_iterator<>(std::cout, "\n")); } } catch(std::exception &e) { std::cerr << "ERROR: Unhandled exception\n"; std::cerr << " what(): " << e.what(); return 1; } #else #pragma message("calendar requires C++14 return type deduction and generic lambdas") int main() {} #endif range-v3-0.3.5/example/comprehensions.cpp000066400000000000000000000066451324212031100203340ustar00rootroot00000000000000// Range v3 library // // Copyright Eric Niebler 2013-present // // Use, modification and distribution is subject to the // Boost Software License, Version 1.0. (See accompanying // file LICENSE_1_0.txt or copy at // http://www.boost.org/LICENSE_1_0.txt) // // Project home: https://github.com/ericniebler/range-v3 // #include #include #include using namespace ranges; int main() { // Define an infinite range containing all the Pythagorean triples: auto triples = view::for_each(view::ints(1), [](int z) { return view::for_each(view::ints(1, z+1), [=](int x) { return view::for_each(view::ints(x, z+1), [=](int y) { return yield_if(x*x + y*y == z*z, std::make_tuple(x, y, z)); }); }); }); //// This alternate syntax also works: //auto triples = ints(1) >>= [] (int z) { return // ints(1, z+1) >>= [=](int x) { return // ints(x, z+1) >>= [=](int y) { return // yield_if(x*x + y*y == z*z, // std::make_tuple(x, y, z)); };}; }; // Display the first 100 triples RANGES_FOR(auto triple, triples | view::take(100)) { std::cout << '(' << std::get<0>(triple) << ',' << std::get<1>(triple) << ',' << std::get<2>(triple) << ')' << '\n'; } } //////////////////////////////////////////////////////////////////////////////////////////////////// // Benchmark Code //////////////////////////////////////////////////////////////////////////////////////////////////// class timer { private: std::chrono::high_resolution_clock::time_point start_; public: timer() { reset(); } void reset() { start_ = std::chrono::high_resolution_clock::now(); } std::chrono::milliseconds elapsed() const { return std::chrono::duration_cast( std::chrono::high_resolution_clock::now() - start_); } friend std::ostream &operator<<(std::ostream &sout, timer const &t) { return sout << t.elapsed().count() << "ms"; } }; void benchmark() { // Define an infinite range containing all the Pythagorean triples: auto triples = view::for_each(view::ints(1), [](int z) { return view::for_each(view::ints(1, z+1), [=](int x) { return view::for_each(view::ints(x, z+1), [=](int y) { return yield_if(x*x + y*y == z*z, std::make_tuple(x, y, z)); }); }); }); static constexpr int max_triples = 3000; timer t; int result = 0; RANGES_FOR(auto triple, triples | view::take(max_triples)) { int i, j, k; std::tie(i, j, k) = triple; result += (i + j + k); } std::cout << t << '\n'; std::cout << result << '\n'; result = 0; int found = 0; t.reset(); for(int z = 1;; ++z) { for(int x = 1; x <= z; ++x) { for(int y = x; y <= z; ++y) { if(x*x + y*y == z*z) { result += (x + y + z); ++found; if(found == max_triples) goto done; } } } } done: std::cout << t << '\n'; std::cout << result << '\n'; } range-v3-0.3.5/example/count.cpp000066400000000000000000000016761324212031100164270ustar00rootroot00000000000000 // Range v3 library // // Copyright Jeff Garland 2017 // // Use, modification and distribution is subject to the // Boost Software License, Version 1.0. (See accompanying // file LICENSE_1_0.txt or copy at // http://www.boost.org/LICENSE_1_0.txt) // // Project home: https://github.com/ericniebler/range-v3 // ///[count] // This example demonstrates counting the number of // elements that match a given value. // output... // vector: 2 // array: 2 #include //specific includes #include #include using std::cout; int main() { std::vector v { 6, 2, 3, 4, 5, 6 }; //note the count return is a numeric type //like int or long -- auto below make sure //it matches the implementation auto c = ranges::count( v, 6 ); cout << "vector: " << c << "\n"; std::array a { 6, 2, 3, 4, 5, 6 }; c = ranges::count( a, 6 ); cout << "array: " << c << "\n"; } ///[count] range-v3-0.3.5/example/count_if.cpp000066400000000000000000000016261324212031100171000ustar00rootroot00000000000000 // Range v3 library // // Copyright Jeff Garland 2017 // // Use, modification and distribution is subject to the // Boost Software License, Version 1.0. (See accompanying // file LICENSE_1_0.txt or copy at // http://www.boost.org/LICENSE_1_0.txt) // // Project home: https://github.com/ericniebler/range-v3 // ///[count_if] // This example counts element of a range that match a supplied predicate. // output // vector: 2 // array: 2 #include //specific includes #include #include #include using std::cout; auto is_six = [](int i) -> bool { return i == 6; }; int main() { std::vector v { 6, 2, 3, 4, 5, 6 }; auto c = ranges::count_if( v, is_six ); cout << "vector: " << c << "\n"; //2 std::array a { 6, 2, 3, 4, 5, 6 }; c = ranges::count_if( a, is_six ); cout << "array: " << c << "\n"; //2 } ///[count_if] range-v3-0.3.5/example/fibonacci.cpp000066400000000000000000000022211324212031100171770ustar00rootroot00000000000000// Range v3 library // // Copyright Eric Niebler 2014-present // // Use, modification and distribution is subject to the // Boost Software License, Version 1.0. (See accompanying // file LICENSE_1_0.txt or copy at // http://www.boost.org/LICENSE_1_0.txt) // // Project home: https://github.com/ericniebler/range-v3 // // This example shows how to define a range that is implemented // in terms of itself. The example is generating the Fibonacci // sequence using self-reference and zip_with. // // Note: don't use recursive_range_fn in performance sensitive // code. Self-reference comes with indirection and dynamic // allocation overhead. #include #include #include "./recursive_range.hpp" int main() { using namespace ranges::view; // Define a nullary function fibs that returns an infinite range // that generates the Fibonacci sequence. ranges::ext::recursive_range_fn const fibs {[&]{ return concat(closed_ints(0,1), zip_with(std::plus{}, fibs(), tail(fibs()))); }}; auto x = take(fibs(), 20); ranges::for_each(x, [](int i) { std::cout << i << std::endl; }); } range-v3-0.3.5/example/hello.cpp000066400000000000000000000011061324212031100163660ustar00rootroot00000000000000 // Range v3 library // // Copyright Jeff Garland 2017 // // Use, modification and distribution is subject to the // Boost Software License, Version 1.0. (See accompanying // file LICENSE_1_0.txt or copy at // http://www.boost.org/LICENSE_1_0.txt) // // Project home: https://github.com/ericniebler/range-v3 // ///[hello] #include //get everything #include #include using std::cout; int main() { std::string s{ "hello" }; //output: h e l l o ranges::for_each( s, [](char c){ cout << c << " "; }); cout << "\n"; } ///[hello] range-v3-0.3.5/example/recursive_range.hpp000066400000000000000000000065771324212031100204740ustar00rootroot00000000000000// Range v3 library // // Copyright Eric Niebler 2014-present // // Use, modification and distribution is subject to the // Boost Software License, Version 1.0. (See accompanying // file LICENSE_1_0.txt or copy at // http://www.boost.org/LICENSE_1_0.txt) // // Project home: https://github.com/ericniebler/range-v3 // // DISCLAIMER: This code is incredibly dumb, slow, inefficient // and probably causes tooth decay, hair loss, and love handles. // // DO NOT USE THIS CODE FOR ANYTHING REAL // // (Can't say you weren't warned.) #ifndef RANGES_V3_EXT_VIEW_RECURSIVE_RANGE_HPP #define RANGES_V3_EXT_VIEW_RECURSIVE_RANGE_HPP #include #include #include #include #include #include #include #include #include #include #include #include namespace ranges { inline namespace v3 { namespace ext { template struct recursive_range_fn { private: using value_type = meta::_t>; std::function()> fun_; struct impl : view_interface { private: friend recursive_range_fn; std::function()> const *fun_; optional> rng_; any_input_view &rng() { if(!rng_) rng_ = (*fun_)(); return *rng_; } impl(std::function()> const &fun) : fun_(&fun), rng_{} {} public: impl() = default; impl(impl &&) = default; impl(impl const &that) : fun_(that.fun_) , rng_{} {} impl &operator=(impl &&) = default; impl &operator=(impl const &that) { fun_ = that.fun_; rng_.reset(); return *this; } iterator_t> begin() { return ranges::begin(rng()); } sentinel_t> end() { return ranges::end(rng()); } any_input_view & base() { return rng(); } }; public: template() && Invocable() && ConvertibleTo, any_input_view>())> explicit recursive_range_fn(Fun fun) : fun_{[=]{return view::concat(invoke(fun), view::empty());}} {} recursive_range_fn(recursive_range_fn const &) = delete; recursive_range_fn &operator=(recursive_range_fn const &) = delete; impl operator()() const { return {fun_}; } }; } } } #endif range-v3-0.3.5/include/000077500000000000000000000000001324212031100145515ustar00rootroot00000000000000range-v3-0.3.5/include/meta/000077500000000000000000000000001324212031100154775ustar00rootroot00000000000000range-v3-0.3.5/include/meta/meta.hpp000066400000000000000000003607331324212031100171520ustar00rootroot00000000000000/// \file meta.hpp Tiny meta-programming library. // // Meta library // // Copyright Eric Niebler 2014-present // // Use, modification and distribution is subject to the // Boost Software License, Version 1.0. (See accompanying // file LICENSE_1_0.txt or copy at // http://www.boost.org/LICENSE_1_0.txt) // // Project home: https://github.com/ericniebler/meta // #ifndef META_HPP #define META_HPP #include #include #include #include #include #if defined(__clang__) #pragma GCC diagnostic push #pragma GCC diagnostic ignored "-Wunknown-pragmas" #pragma GCC diagnostic ignored "-Wpragmas" #pragma GCC diagnostic ignored "-Wdocumentation-deprecated-sync" #endif /// \defgroup meta Meta /// /// A tiny metaprogramming library /// \defgroup trait Trait /// Trait invocation/composition. /// \ingroup meta /// \defgroup invocation Invocation /// Trait invocation /// \ingroup trait /// \defgroup composition Composition /// Trait composition /// \ingroup trait /// \defgroup logical Logical /// Logical operations /// \ingroup meta /// \defgroup algorithm Algorithms /// Algorithms. /// \ingroup meta /// \defgroup query Query/Search /// Query and search algorithms /// \ingroup algorithm /// \defgroup transformation Transformation /// Transformation algorithms /// \ingroup algorithm /// \defgroup runtime Runtime /// Runtime algorithms /// \ingroup algorithm /// \defgroup datatype Datatype /// Datatypes. /// \ingroup meta /// \defgroup list List /// \ingroup datatype /// \defgroup integral Integer sequence /// Equivalent to C++14's `std::integer_sequence` /// \ingroup datatype /// \defgroup extension Extension /// Extend meta with your own datatypes. /// \ingroup datatype /// \defgroup math Math /// Integral constant arithmetic. /// \ingroup meta /// \defgroup lazy_trait lazy /// \ingroup trait /// \defgroup lazy_invocation lazy /// \ingroup invocation /// \defgroup lazy_composition lazy /// \ingroup composition /// \defgroup lazy_logical lazy /// \ingroup logical /// \defgroup lazy_query lazy /// \ingroup query /// \defgroup lazy_transformation lazy /// \ingroup transformation /// \defgroup lazy_list lazy /// \ingroup list /// \defgroup lazy_datatype lazy /// \ingroup datatype /// \defgroup lazy_math lazy /// \ingroup math /// Tiny metaprogramming library namespace meta { /// \cond inline namespace v1 { /// \endcond namespace detail { /// Returns a \p T nullptr template constexpr T *_nullptr_v() { return nullptr; } } // namespace detail /// An empty type. /// \ingroup datatype struct nil_ { }; /// Type alias for \p T::type. /// \ingroup invocation template using _t = typename T::type; #if defined(__cpp_variable_templates) || defined(META_DOXYGEN_INVOKED) /// Variable alias for \c T::type::value /// \note Requires C++14 or greater. /// \ingroup invocation template constexpr typename _t::value_type _v = _t::value; #endif /// Lazy versions of meta actions namespace lazy { /// \sa `meta::_t` /// \ingroup lazy_invocation template using _t = defer<_t, T>; } /// An integral constant wrapper for \c std::size_t. /// \ingroup integral template using size_t = std::integral_constant; /// An integral constant wrapper for \c bool. /// \ingroup integral template using bool_ = std::integral_constant; /// An integral constant wrapper for \c int. /// \ingroup integral template using int_ = std::integral_constant; /// An integral constant wrapper for \c char. /// \ingroup integral template using char_ = std::integral_constant; /////////////////////////////////////////////////////////////////////////////////////////// // Math operations /// An integral constant wrapper around the result of incrementing the wrapped /// integer \c /// T::type::value. template using inc = std::integral_constant; /// An integral constant wrapper around the result of decrementing the wrapped /// integer \c /// T::type::value. template using dec = std::integral_constant; /// An integral constant wrapper around the result of adding the two wrapped /// integers /// \c T::type::value and \c U::type::value. /// \ingroup math template using plus = std::integral_constant; /// An integral constant wrapper around the result of subtracting the two /// wrapped integers /// \c T::type::value and \c U::type::value. /// \ingroup math template using minus = std::integral_constant; /// An integral constant wrapper around the result of multiplying the two /// wrapped integers /// \c T::type::value and \c U::type::value. /// \ingroup math template using multiplies = std::integral_constant; /// An integral constant wrapper around the result of dividing the two wrapped /// integers \c /// T::type::value and \c U::type::value. /// \ingroup math template using divides = std::integral_constant; /// An integral constant wrapper around the result of negating the wrapped /// integer /// \c T::type::value. /// \ingroup math template using negate = std::integral_constant; /// An integral constant wrapper around the remainder of dividing the two /// wrapped integers /// \c T::type::value and \c U::type::value. /// \ingroup math template using modulus = std::integral_constant; /// A Boolean integral constant wrapper around the result of comparing \c /// T::type::value and /// \c U::type::value for equality. /// \ingroup math template using equal_to = bool_; /// A Boolean integral constant wrapper around the result of comparing \c /// T::type::value and /// \c U::type::value for inequality. /// \ingroup math template using not_equal_to = bool_; /// A Boolean integral constant wrapper around \c true if \c T::type::value is /// greater than /// \c U::type::value; \c false, otherwise. /// \ingroup math template using greater = bool_<(T::type::value > U::type::value)>; /// A Boolean integral constant wrapper around \c true if \c T::type::value is /// less than \c /// U::type::value; \c false, otherwise. /// \ingroup math template using less = bool_<(T::type::value < U::type::value)>; /// A Boolean integral constant wrapper around \c true if \c T::type::value is /// greater than /// or equal to \c U::type::value; \c false, otherwise. /// \ingroup math template using greater_equal = bool_<(T::type::value >= U::type::value)>; /// A Boolean integral constant wrapper around \c true if \c T::type::value is /// less than or /// equal to \c U::type::value; \c false, otherwise. /// \ingroup math template using less_equal = bool_<(T::type::value <= U::type::value)>; /// An integral constant wrapper around the result of bitwise-and'ing the two /// wrapped /// integers \c T::type::value and \c U::type::value. /// \ingroup math template using bit_and = std::integral_constant; /// An integral constant wrapper around the result of bitwise-or'ing the two /// wrapped /// integers \c T::type::value and \c U::type::value. /// \ingroup math template using bit_or = std::integral_constant; /// An integral constant wrapper around the result of bitwise-exclusive-or'ing /// the two /// wrapped integers \c T::type::value and \c U::type::value. /// \ingroup math template using bit_xor = std::integral_constant; /// An integral constant wrapper around the result of bitwise-complementing the /// wrapped /// integer \c T::type::value. /// \ingroup math template using bit_not = std::integral_constant; namespace lazy { /// \sa 'meta::int' /// \ingroup lazy_math template using inc = defer; /// \sa 'meta::dec' /// \ingroup lazy_math template using dec = defer; /// \sa 'meta::plus' /// \ingroup lazy_math template using plus = defer; /// \sa 'meta::minus' /// \ingroup lazy_math template using minus = defer; /// \sa 'meta::multiplies' /// \ingroup lazy_math template using multiplies = defer; /// \sa 'meta::divides' /// \ingroup lazy_math template using divides = defer; /// \sa 'meta::negate' /// \ingroup lazy_math template using negate = defer; /// \sa 'meta::modulus' /// \ingroup lazy_math template using modulus = defer; /// \sa 'meta::equal_to' /// \ingroup lazy_math template using equal_to = defer; /// \sa 'meta::not_equal_t' /// \ingroup lazy_math template using not_equal_to = defer; /// \sa 'meta::greater' /// \ingroup lazy_math template using greater = defer; /// \sa 'meta::less' /// \ingroup lazy_math template using less = defer; /// \sa 'meta::greater_equal' /// \ingroup lazy_math template using greater_equal = defer; /// \sa 'meta::less_equal' /// \ingroup lazy_math template using less_equal = defer; /// \sa 'meta::bit_and' /// \ingroup lazy_math template using bit_and = defer; /// \sa 'meta::bit_or' /// \ingroup lazy_math template using bit_or = defer; /// \sa 'meta::bit_xor' /// \ingroup lazy_math template using bit_xor = defer; /// \sa 'meta::bit_not' /// \ingroup lazy_math template using bit_not = defer; } /// \cond namespace detail { enum class indices_strategy_ { done, repeat, recurse }; constexpr indices_strategy_ strategy_(std::size_t cur, std::size_t end) { return cur >= end ? indices_strategy_::done : cur * 2 <= end ? indices_strategy_::repeat : indices_strategy_::recurse; } template constexpr std::size_t range_distance_(T begin, T end) { return begin <= end ? static_cast(end - begin) : throw "The start of the integer_sequence must not be " "greater than the end"; } template struct make_indices_ { using type = State; }; template struct coerce_indices_ { }; } /// \endcond /////////////////////////////////////////////////////////////////////////////////////////////// // integer_sequence #ifndef __cpp_lib_integer_sequence /// A container for a sequence of compile-time integer constants. /// \ingroup integral template struct integer_sequence { using value_type = T; /// \return `sizeof...(Is)` static constexpr std::size_t size() noexcept { return sizeof...(Is); } }; #endif /////////////////////////////////////////////////////////////////////////////////////////////// // index_sequence /// A container for a sequence of compile-time integer constants of type /// \c std::size_t /// \ingroup integral template using index_sequence = integer_sequence; #if !defined(META_DOXYGEN_INVOKED) && \ ((defined(__clang__) && __clang_major__ >= 3 && __clang_minor__ >= 8) || \ (defined(_MSC_VER) && _MSC_FULL_VER >= 190023918)) // Implement make_integer_sequence and make_index_sequence with the // __make_integer_seq builtin on compilers that provide it. (Redirect // through decltype to workaround suspected clang bug.) /// \cond namespace detail { template __make_integer_seq make_integer_sequence_(); } /// \endcond template using make_integer_sequence = decltype(detail::make_integer_sequence_()); template using make_index_sequence = make_integer_sequence; #else /// Generate \c index_sequence containing integer constants [0,1,2,...,N-1]. /// \par Complexity /// \f$ O(log(N)) \f$. /// \ingroup integral template using make_index_sequence = _t, detail::strategy_(1, N)>>; /// Generate \c integer_sequence containing integer constants [0,1,2,...,N-1]. /// \par Complexity /// \f$ O(log(N)) \f$. /// \ingroup integral template using make_integer_sequence = _t(N)>>>; #endif /////////////////////////////////////////////////////////////////////////////////////////////// // integer_range /// Makes the integer sequence [From, To). /// \par Complexity /// \f$ O(log(To - From)) \f$. /// \ingroup integral template using integer_range = _t>>; /// \cond namespace detail { template struct concat_indices_ { }; template struct concat_indices_, index_sequence> { using type = index_sequence; }; template <> struct make_indices_<0u, index_sequence<0>, indices_strategy_::done> { using type = index_sequence<>; }; template struct make_indices_, indices_strategy_::repeat> : make_indices_, detail::strategy_(sizeof...(Values)*2, End)> { }; template struct make_indices_, indices_strategy_::recurse> : concat_indices_, make_index_sequence> { }; template struct coerce_indices_> { using type = integer_sequence(static_cast(Values) + Offset)...>; }; } // namespace detail /// \endcond /// Evaluate the Callable \p F with the arguments \p Args. /// \ingroup invocation template using invoke = typename F::template invoke; /// Lazy versions of meta actions namespace lazy { /// \sa `meta::invoke` /// \ingroup lazy_invocation template using invoke = defer; } /// A trait that always returns its argument \p T. Also, a Callable that always /// returns /// \p T. /// \ingroup trait /// \ingroup invocation template struct id { #if defined(__GNUC__) && !defined(__clang__) && __GNUC__ < 5 && !defined(META_DOXYGEN_INVOKED) // Redirect through decltype for compilers that have not // yet implemented CWG 1558: // static id impl(void *); template using invoke = _t *>(nullptr)))>; #else template using invoke = T; #endif using type = T; }; /// An alias for type \p T. Useful in non-deduced contexts. /// \ingroup trait template using id_t = _t>; namespace lazy { /// \sa `meta::id` /// \ingroup lazy_trait /// \ingroup lazy_invocation template using id = defer; } /// An alias for `void`. /// \ingroup trait #if defined(__GNUC__) && !defined(__clang__) && __GNUC__ < 5 && !defined(META_DOXYGEN_INVOKED) // Redirect through decltype for compilers that have not // yet implemented CWG 1558: // template using void_ = invoke, Ts...>; #else template using void_ = void; #endif /// \cond namespace detail { template struct is_trait_ { using type = std::false_type; }; template struct is_trait_> { using type = std::true_type; }; template struct is_callable_ { using type = std::false_type; }; template struct is_callable_>> { using type = std::true_type; }; template