feat: deprecate Array.mkArray in favour of Array.replicate

This PR fixes a bug introduced in #7589, causing pretty printed
structure instances to not be hoverable in the Infoview.

This was caused by a choice node being introduced, since `{ $fields,* }`
is ambiguous syntax.

.github/workflows/awaiting-mathlib.yml

@@ -0,0 +1,20 @@
+name: Check awaiting-mathlib label
+
+on:
+  merge_group:
+  pull_request:
+    types: [opened, synchronize, reopened, labeled, unlabeled]
+
+jobs:
+  check-awaiting-mathlib:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check awaiting-mathlib label
+        if: github.event_name == 'pull_request'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const { labels } = context.payload.pull_request;
+            if (labels.some(label => label.name == "awaiting-mathlib") && !labels.some(label => label.name == "builds-mathlib")) {
+              core.setFailed('PR is marked "awaiting-mathlib" but "builds-mathlib" label has not been applied yet by the bot');
+            }

.github/workflows/build-template.yml

@@ -0,0 +1,246 @@
+name: build-template
+on:
+  workflow_call:
+    inputs:
+      check-level:
+        type: string
+        required: true
+      config:
+        type: string
+        required: true
+      nightly:
+        type: string
+        required: true
+      LEAN_VERSION_MAJOR:
+        type: string
+        required: true
+      LEAN_VERSION_MINOR:
+        type: string
+        required: true
+      LEAN_VERSION_PATCH:
+        type: string
+        required: true
+      LEAN_SPECIAL_VERSION_DESC:
+        type: string
+        required: true
+      RELEASE_TAG:
+        type: string
+        required: true
+
+jobs:
+  build:
+    if: github.event_name != 'schedule' || github.repository == 'leanprover/lean4'
+    strategy:
+      matrix:
+        include: ${{fromJson(inputs.config)}}
+      # complete all jobs
+      fail-fast: false
+    runs-on: ${{ matrix.os }}
+    defaults:
+      run:
+        shell: ${{ matrix.shell || 'nix develop -c bash -euxo pipefail {0}' }}
+    name: ${{ matrix.name }}
+    env:
+      # must be inside workspace
+      CCACHE_DIR: ${{ github.workspace }}/.ccache
+      CCACHE_COMPRESS: true
+      # current cache limit
+      CCACHE_MAXSIZE: 200M
+      # squelch error message about missing nixpkgs channel
+      NIX_BUILD_SHELL: bash
+      LSAN_OPTIONS: max_leaks=10
+      # somehow MinGW clang64 (or cmake?) defaults to `g++` even though it doesn't exist
+      CXX: c++
+      MACOSX_DEPLOYMENT_TARGET: 10.15
+    steps:
+      - name: Install Nix
+        uses: DeterminateSystems/nix-installer-action@main
+        if: runner.os == 'Linux' && !matrix.cmultilib
+      - name: Install MSYS2
+        uses: msys2/setup-msys2@v2
+        with:
+          msystem: clang64
+          # `:` means do not prefix with msystem
+          pacboy: "make: python: cmake clang ccache gmp libuv git: zip: unzip: diffutils: binutils: tree: zstd tar:"
+        if: runner.os == 'Windows'
+      - name: Install Brew Packages
+        run: |
+          brew install ccache tree zstd coreutils gmp libuv
+        if: runner.os == 'macOS'
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          # the default is to use a virtual merge commit between the PR and master: just use the PR
+          ref: ${{ github.event.pull_request.head.sha }}
+      - name: Open Nix shell once
+        run: true
+        if: runner.os == 'Linux'
+      # Do check out some CI-relevant files from virtual merge commit to accommodate CI changes on
+      # master (as the workflow files themselves are always taken from the merge)
+      # (needs to be after "Install *" to use the right shell)
+      - name: CI Merge Checkout
+        run: |
+          git fetch --depth=1 origin ${{ github.sha }}
+          git checkout FETCH_HEAD flake.nix flake.lock
+        if: github.event_name == 'pull_request'
+      # (needs to be after "Checkout" so files don't get overridden)
+      - name: Setup emsdk
+        uses: mymindstorm/setup-emsdk@v14
+        with:
+          version: 3.1.44
+          actions-cache-folder: emsdk
+        if: matrix.wasm
+      - name: Install 32bit c libs
+        run: |
+          sudo dpkg --add-architecture i386
+          sudo apt-get update
+          sudo apt-get install -y gcc-multilib g++-multilib ccache libuv1-dev:i386 pkgconf:i386
+        if: matrix.cmultilib
+      - name: Cache
+        if: matrix.name != 'Linux Lake'
+        uses: actions/cache@v4
+        with:
+          path: |
+            .ccache
+          key: ${{ matrix.name }}-build-v3-${{ github.event.pull_request.head.sha }}
+          # fall back to (latest) previous cache
+          restore-keys: |
+            ${{ matrix.name }}-build-v3
+          save-always: true
+      - name: Cache
+        if: matrix.name == 'Linux Lake'
+        uses: actions/cache@v4
+        with:
+          path: |
+            .ccache
+            build/stage1/**/*.trace
+            build/stage1/**/*.olean
+            build/stage1/**/*.ilean
+            build/stage1/**/*.c
+            build/stage1/**/*.c.o*
+          key: ${{ matrix.name }}-build-v3-${{ github.event.pull_request.head.sha }}
+          # fall back to (latest) previous cache
+          restore-keys: |
+            ${{ matrix.name }}-build-v3
+          save-always: true
+      # open nix-shell once for initial setup
+      - name: Setup
+        run: |
+          ccache --zero-stats
+        if: runner.os == 'Linux'
+      - name: Set up NPROC
+        run: |
+          echo "NPROC=$(nproc 2>/dev/null || sysctl -n hw.logicalcpu 2>/dev/null || echo 4)" >> $GITHUB_ENV
+      - name: Build
+        run: |
+          ulimit -c unlimited  # coredumps
+          [ -d build ] || mkdir build
+          cd build
+          # arguments passed to `cmake`
+          # this also enables githash embedding into stage 1 library
+          OPTIONS=(-DCHECK_OLEAN_VERSION=ON)
+          OPTIONS+=(-DLEAN_EXTRA_MAKE_OPTS=-DwarningAsError=true)
+          if [[ -n '${{ matrix.cross_target }}' ]]; then
+            # used by `prepare-llvm`
+            export EXTRA_FLAGS=--target=${{ matrix.cross_target }}
+            OPTIONS+=(-DLEAN_PLATFORM_TARGET=${{ matrix.cross_target }})
+          fi
+          if [[ -n '${{ matrix.prepare-llvm }}' ]]; then
+            wget -q ${{ matrix.llvm-url }}
+            PREPARE="$(${{ matrix.prepare-llvm }})"
+            eval "OPTIONS+=($PREPARE)"
+          fi
+          if [[ -n '${{ matrix.release }}' && -n '${{ inputs.nightly }}' ]]; then
+            OPTIONS+=(-DLEAN_SPECIAL_VERSION_DESC=${{ inputs.nightly }})
+          fi
+          if [[ -n '${{ matrix.release }}' && -n '${{ inputs.RELEASE_TAG }}' ]]; then
+            OPTIONS+=(-DLEAN_VERSION_MAJOR=${{ inputs.LEAN_VERSION_MAJOR }})
+            OPTIONS+=(-DLEAN_VERSION_MINOR=${{ inputs.LEAN_VERSION_MINOR }})
+            OPTIONS+=(-DLEAN_VERSION_PATCH=${{ inputs.LEAN_VERSION_PATCH }})
+            OPTIONS+=(-DLEAN_VERSION_IS_RELEASE=1)
+            OPTIONS+=(-DLEAN_SPECIAL_VERSION_DESC=${{ inputs.LEAN_SPECIAL_VERSION_DESC }})
+          fi
+          # contortion to support empty OPTIONS with old macOS bash
+          cmake .. --preset ${{ matrix.CMAKE_PRESET || 'release' }} -B . ${{ matrix.CMAKE_OPTIONS }} ${OPTIONS[@]+"${OPTIONS[@]}"} -DLEAN_INSTALL_PREFIX=$PWD/..
+          time make -j$NPROC
+      - name: Install
+        run: |
+          make -C build install
+      - name: Check Binaries
+        run: ${{ matrix.binary-check }} lean-*/bin/* || true
+      - name: Count binary symbols
+        run: |
+          for f in lean-*/bin/*; do
+            echo "$f: $(nm $f | grep " T " | wc -l) exported symbols"
+          done
+        if: matrix.name == 'Windows'
+      - name: List Install Tree
+        run: |
+          # omit contents of Init/, ...
+          tree --du -h lean-*-* | grep -E ' (Init|Lean|Lake|LICENSE|[a-z])'
+      - name: Pack
+        run: |
+          dir=$(echo lean-*-*)
+          mkdir pack
+          # high-compression tar.zst + zip for release, fast tar.zst otherwise
+          if [[ '${{ startsWith(github.ref, 'refs/tags/') && matrix.release }}' == true || -n '${{ inputs.nightly }}' || -n '${{ inputs.RELEASE_TAG }}' ]]; then
+            ${{ matrix.tar || 'tar' }} cf - $dir | zstd -T0 --no-progress -19 -o pack/$dir.tar.zst
+            zip -rq pack/$dir.zip $dir
+          else
+            ${{ matrix.tar || 'tar' }} cf - $dir | zstd -T0 --no-progress -o pack/$dir.tar.zst
+          fi
+      - uses: actions/upload-artifact@v4
+        if: matrix.release
+        with:
+          name: build-${{ matrix.name }}
+          path: pack/*
+      - name: Lean stats
+        run: |
+          build/stage1/bin/lean --stats src/Lean.lean
+        if: ${{ !matrix.cross }}
+      - name: Test
+        id: test
+        run: |
+          ulimit -c unlimited  # coredumps
+          time ctest --preset ${{ matrix.CMAKE_PRESET || 'release' }} --test-dir build/stage1 -j$NPROC --output-junit test-results.xml ${{ matrix.CTEST_OPTIONS }}
+        if: (matrix.wasm || !matrix.cross) && inputs.check-level >= 1
+      - name: Test Summary
+        uses: test-summary/action@v2
+        with:
+          paths: build/stage1/test-results.xml
+        # prefix `if` above with `always` so it's run even if tests failed
+        if: always() && steps.test.conclusion != 'skipped'
+      - name: Check Test Binary
+        run: ${{ matrix.binary-check }} tests/compiler/534.lean.out
+        if: (!matrix.cross) && steps.test.conclusion != 'skipped'
+      - name: Build Stage 2
+        run: |
+          make -C build -j$NPROC stage2
+        if: matrix.test-speedcenter
+      - name: Check Stage 3
+        run: |
+          make -C build -j$NPROC check-stage3
+        if: matrix.test-speedcenter
+      - name: Test Speedcenter Benchmarks
+        run: |
+          # Necessary for some timing metrics but does not work on Namespace runners
+          # and we just want to test that the benchmarks run at all here
+          #echo -1 | sudo tee /proc/sys/kernel/perf_event_paranoid
+          export BUILD=$PWD/build PATH=$PWD/build/stage1/bin:$PATH
+          cd tests/bench
+          nix shell .#temci -c temci exec --config speedcenter.yaml --included_blocks fast --runs 1
+        if: matrix.test-speedcenter
+      - name: Check rebootstrap
+        run: |
+          # clean rebuild in case of Makefile changes
+          make -C build update-stage0 && rm -rf build/stage* && make -C build -j$NPROC
+        if: matrix.name == 'Linux' && inputs.check-level >= 1
+      - name: CCache stats
+        run: ccache -s
+      - name: Show stacktrace for coredumps
+        if: failure() && runner.os == 'Linux'
+        run: |
+          for c in $(find . -name core); do
+            progbin="$(file $c | sed "s/.*execfn: '\([^']*\)'.*/\1/")"
+            echo bt | $GDB/bin/gdb -q $progbin $c || true
+          done

.github/workflows/check-stage0.yml

@@ -20,9 +20,7 @@ jobs:
 
     - name: Identify stage0 changes
       run: |
-        git diff "${BASE:-HEAD^}..HEAD" --name-only -- stage0 |
-          grep -v -x -F $'stage0/src/stdlib_flags.h\nstage0/src/lean.mk.in' \
-          > "$RUNNER_TEMP/stage0" || true
+        git diff "${BASE:-HEAD^}..HEAD" --name-only -- stage0/stdlib > "$RUNNER_TEMP/stage0" || true
         if test -s "$RUNNER_TEMP/stage0"
         then
           echo "CHANGES=yes" >> "$GITHUB_ENV"

.github/workflows/ci.yml

@@ -36,7 +36,9 @@ jobs:
       # 2: PRs with `release-ci` label, releases (incl. nightlies)
       check-level: ${{ steps.set-level.outputs.check-level }}
       # The build matrix, dynamically generated here
-      matrix: ${{ steps.set-matrix.outputs.result }}
+      matrix: ${{ steps.set-matrix.outputs.matrix }}
+      # secondary build jobs that should not block the CI success/merge queue
+      matrix-secondary: ${{ steps.set-matrix.outputs.matrix-secondary }}
       # Should we make a nightly release? If so, this output contains the lean version string, else it is empty
       nightly: ${{ steps.set-nightly.outputs.nightly }}
       # Should this be the CI for a tagged release?
@@ -135,6 +137,7 @@ jobs:
             console.log(`level: ${level}`);
             // use large runners where available (original repo)
             let large = ${{ github.repository == 'leanprover/lean4' }};
+            const isPr = "${{ github.event_name }}" == "pull_request";
             let matrix = [
               {
                 "name": "Linux LLVM",
@@ -163,6 +166,14 @@ jobs:
                 // foreign code may be linked against more recent glibc
                 "CTEST_OPTIONS": "-E 'foreign'"
               },
+              {
+                "name": "Linux Lake",
+                "os": large ? "nscloud-ubuntu-22.04-amd64-4x8" : "ubuntu-latest",
+                // just a secondary PR build job for now
+                "check-level": isPr ? 0 : 3,
+                "secondary": true,
+                "CMAKE_OPTIONS": "-DUSE_LAKE=ON"
+              },
               {
                 "name": "Linux",
                 "os": large ? "nscloud-ubuntu-22.04-amd64-4x8" : "ubuntu-latest",
@@ -204,12 +215,18 @@ jobs:
                 "os": "macos-14",
                 "CMAKE_OPTIONS": "-DLEAN_INSTALL_SUFFIX=-darwin_aarch64",
                 "release": true,
-                "check-level": 0,
                 "shell": "bash -euxo pipefail {0}",
                 "llvm-url": "https://github.com/leanprover/lean-llvm/releases/download/15.0.1/lean-llvm-aarch64-apple-darwin.tar.zst",
                 "prepare-llvm": "../script/prepare-llvm-macos.sh lean-llvm*",
                 "binary-check": "otool -L",
-                "tar": "gtar" // https://github.com/actions/runner-images/issues/2619
+                "tar": "gtar", // https://github.com/actions/runner-images/issues/2619
+                // Special handling for MacOS aarch64, we want:
+                // 1. To run it in PRs so Mac devs get PR toolchains (so secondary is sufficient)
+                // 2. To skip it in merge queues as it takes longer than the Linux build and adds
+                //    little value in the merge queue
+                // 3. To run it in release (obviously)
+                "check-level": isPr ? 0 : 2,
+                "secondary": isPr,
               },
               {
                 "name": "Windows",
@@ -260,196 +277,41 @@ jobs:
               //   "CTEST_OPTIONS": "-R \"leantest_1007\\.lean|leantest_Format\\.lean|leanruntest\\_1037.lean|leanruntest_ac_rfl\\.lean|leanruntest_tempfile.lean\\.|leanruntest_libuv\\.lean\""
               // }
             ];
-            console.log(`matrix:\n${JSON.stringify(matrix, null, 2)}`)
-            return matrix.filter((job) => level >= job["check-level"])
+            console.log(`matrix:\n${JSON.stringify(matrix, null, 2)}`);
+            matrix = matrix.filter((job) => level >= job["check-level"]);
+            core.setOutput('matrix', matrix.filter((job) => !job["secondary"]));
+            core.setOutput('matrix-secondary', matrix.filter((job) => job["secondary"]));
 
   build:
-    needs: [configure]
     if: github.event_name != 'schedule' || github.repository == 'leanprover/lean4'
-    strategy:
-      matrix:
-        include: ${{fromJson(needs.configure.outputs.matrix)}}
-      # complete all jobs
-      fail-fast: false
-    runs-on: ${{ matrix.os }}
-    defaults:
-      run:
-        shell: ${{ matrix.shell || 'nix develop -c bash -euxo pipefail {0}' }}
-    name: ${{ matrix.name }}
-    env:
-      # must be inside workspace
-      CCACHE_DIR: ${{ github.workspace }}/.ccache
-      CCACHE_COMPRESS: true
-      # current cache limit
-      CCACHE_MAXSIZE: 200M
-      # squelch error message about missing nixpkgs channel
-      NIX_BUILD_SHELL: bash
-      LSAN_OPTIONS: max_leaks=10
-      # somehow MinGW clang64 (or cmake?) defaults to `g++` even though it doesn't exist
-      CXX: c++
-      MACOSX_DEPLOYMENT_TARGET: 10.15
-    steps:
-      - name: Install Nix
-        uses: DeterminateSystems/nix-installer-action@main
-        if: runner.os == 'Linux' && !matrix.cmultilib
-      - name: Install MSYS2
-        uses: msys2/setup-msys2@v2
-        with:
-          msystem: clang64
-          # `:` means do not prefix with msystem
-          pacboy: "make: python: cmake clang ccache gmp libuv git: zip: unzip: diffutils: binutils: tree: zstd tar:"
-        if: runner.os == 'Windows'
-      - name: Install Brew Packages
-        run: |
-          brew install ccache tree zstd coreutils gmp libuv
-        if: runner.os == 'macOS'
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          # the default is to use a virtual merge commit between the PR and master: just use the PR
-          ref: ${{ github.event.pull_request.head.sha }}
-      # Do check out some CI-relevant files from virtual merge commit to accommodate CI changes on
-      # master (as the workflow files themselves are always taken from the merge)
-      # (needs to be after "Install *" to use the right shell)
-      - name: CI Merge Checkout
-        run: |
-          git fetch --depth=1 origin ${{ github.sha }}
-          git checkout FETCH_HEAD flake.nix flake.lock
-        if: github.event_name == 'pull_request'
-      # (needs to be after "Checkout" so files don't get overridden)
-      - name: Setup emsdk
-        uses: mymindstorm/setup-emsdk@v14
-        with:
-          version: 3.1.44
-          actions-cache-folder: emsdk
-        if: matrix.wasm
-      - name: Install 32bit c libs
-        run: |
-          sudo dpkg --add-architecture i386
-          sudo apt-get update
-          sudo apt-get install -y gcc-multilib g++-multilib ccache libuv1-dev:i386 pkgconf:i386
-        if: matrix.cmultilib
-      - name: Cache
-        uses: actions/cache@v4
-        with:
-          path: .ccache
-          key: ${{ matrix.name }}-build-v3-${{ github.event.pull_request.head.sha }}
-          # fall back to (latest) previous cache
-          restore-keys: |
-            ${{ matrix.name }}-build-v3
-          save-always: true
-      # open nix-shell once for initial setup
-      - name: Setup
-        run: |
-          ccache --zero-stats
-        if: runner.os == 'Linux'
-      - name: Set up NPROC
-        run: |
-          echo "NPROC=$(nproc 2>/dev/null || sysctl -n hw.logicalcpu 2>/dev/null || echo 4)" >> $GITHUB_ENV
-      - name: Build
-        run: |
-          mkdir build
-          cd build
-          # arguments passed to `cmake`
-          # this also enables githash embedding into stage 1 library
-          OPTIONS=(-DCHECK_OLEAN_VERSION=ON)
-          OPTIONS+=(-DLEAN_EXTRA_MAKE_OPTS=-DwarningAsError=true)
-          if [[ -n '${{ matrix.cross_target }}' ]]; then
-            # used by `prepare-llvm`
-            export EXTRA_FLAGS=--target=${{ matrix.cross_target }}
-            OPTIONS+=(-DLEAN_PLATFORM_TARGET=${{ matrix.cross_target }})
-          fi
-          if [[ -n '${{ matrix.prepare-llvm }}' ]]; then
-            wget -q ${{ matrix.llvm-url }}
-            PREPARE="$(${{ matrix.prepare-llvm }})"
-            eval "OPTIONS+=($PREPARE)"
-          fi
-          if [[ -n '${{ matrix.release }}' && -n '${{ needs.configure.outputs.nightly }}' ]]; then
-            OPTIONS+=(-DLEAN_SPECIAL_VERSION_DESC=${{ needs.configure.outputs.nightly }})
-          fi
-          if [[ -n '${{ matrix.release }}' && -n '${{ needs.configure.outputs.RELEASE_TAG }}' ]]; then
-            OPTIONS+=(-DLEAN_VERSION_MAJOR=${{ needs.configure.outputs.LEAN_VERSION_MAJOR }})
-            OPTIONS+=(-DLEAN_VERSION_MINOR=${{ needs.configure.outputs.LEAN_VERSION_MINOR }})
-            OPTIONS+=(-DLEAN_VERSION_PATCH=${{ needs.configure.outputs.LEAN_VERSION_PATCH }})
-            OPTIONS+=(-DLEAN_VERSION_IS_RELEASE=1)
-            OPTIONS+=(-DLEAN_SPECIAL_VERSION_DESC=${{ needs.configure.outputs.LEAN_SPECIAL_VERSION_DESC }})
-          fi
-          # contortion to support empty OPTIONS with old macOS bash
-          cmake .. --preset ${{ matrix.CMAKE_PRESET || 'release' }} -B . ${{ matrix.CMAKE_OPTIONS }} ${OPTIONS[@]+"${OPTIONS[@]}"} -DLEAN_INSTALL_PREFIX=$PWD/..
-          time make -j$NPROC
-      - name: Install
-        run: |
-          make -C build install
-      - name: Check Binaries
-        run: ${{ matrix.binary-check }} lean-*/bin/* || true
-      - name: Count binary symbols
-        run: |
-          for f in lean-*/bin/*; do
-            echo "$f: $(nm $f | grep " T " | wc -l) exported symbols"
-          done
-        if: matrix.name == 'Windows'
-      - name: List Install Tree
-        run: |
-          # omit contents of Init/, ...
-          tree --du -h lean-*-* | grep -E ' (Init|Lean|Lake|LICENSE|[a-z])'
-      - name: Pack
-        run: |
-          dir=$(echo lean-*-*)
-          mkdir pack
-          # high-compression tar.zst + zip for release, fast tar.zst otherwise
-          if [[ '${{ startsWith(github.ref, 'refs/tags/') && matrix.release }}' == true || -n '${{ needs.configure.outputs.nightly }}' || -n '${{ needs.configure.outputs.RELEASE_TAG }}' ]]; then
-            ${{ matrix.tar || 'tar' }} cf - $dir | zstd -T0 --no-progress -19 -o pack/$dir.tar.zst
-            zip -rq pack/$dir.zip $dir
-          else
-            ${{ matrix.tar || 'tar' }} cf - $dir | zstd -T0 --no-progress -o pack/$dir.tar.zst
-          fi
-      - uses: actions/upload-artifact@v4
-        if: matrix.release
-        with:
-          name: build-${{ matrix.name }}
-          path: pack/*
-      - name: Lean stats
-        run: |
-          build/stage1/bin/lean --stats src/Lean.lean
-        if: ${{ !matrix.cross }}
-      - name: Test
-        id: test
-        run: |
-          time ctest --preset ${{ matrix.CMAKE_PRESET || 'release' }} --test-dir build/stage1 -j$NPROC --output-junit test-results.xml ${{ matrix.CTEST_OPTIONS }}
-        if: (matrix.wasm || !matrix.cross) && needs.configure.outputs.check-level >= 1
-      - name: Test Summary
-        uses: test-summary/action@v2
-        with:
-          paths: build/stage1/test-results.xml
-        # prefix `if` above with `always` so it's run even if tests failed
-        if: always() && steps.test.conclusion != 'skipped'
-      - name: Check Test Binary
-        run: ${{ matrix.binary-check }} tests/compiler/534.lean.out
-        if: (!matrix.cross) && steps.test.conclusion != 'skipped'
-      - name: Build Stage 2
-        run: |
-          make -C build -j$NPROC stage2
-        if: matrix.test-speedcenter
-      - name: Check Stage 3
-        run: |
-          make -C build -j$NPROC check-stage3
-        if: matrix.test-speedcenter
-      - name: Test Speedcenter Benchmarks
-        run: |
-          # Necessary for some timing metrics but does not work on Namespace runners
-          # and we just want to test that the benchmarks run at all here
-          #echo -1 | sudo tee /proc/sys/kernel/perf_event_paranoid
-          export BUILD=$PWD/build PATH=$PWD/build/stage1/bin:$PATH
-          cd tests/bench
-          nix shell .#temci -c temci exec --config speedcenter.yaml --included_blocks fast --runs 1
-        if: matrix.test-speedcenter
-      - name: Check rebootstrap
-        run: |
-          # clean rebuild in case of Makefile changes
-          make -C build update-stage0 && rm -rf build/stage* && make -C build -j$NPROC
-        if: matrix.name == 'Linux' && needs.configure.outputs.check-level >= 1
-      - name: CCache stats
-        run: ccache -s
+    needs: [configure]
+    uses: ./.github/workflows/build-template.yml
+    with:
+      config: ${{needs.configure.outputs.matrix}}
+      check-level: ${{ needs.configure.outputs.check-level }}
+      nightly: ${{ needs.configure.outputs.nightly }}
+      LEAN_VERSION_MAJOR: ${{ needs.configure.outputs.LEAN_VERSION_MAJOR }}
+      LEAN_VERSION_MINOR: ${{ needs.configure.outputs.LEAN_VERSION_MINOR }}
+      LEAN_VERSION_PATCH: ${{ needs.configure.outputs.LEAN_VERSION_PATCH }}
+      LEAN_SPECIAL_VERSION_DESC: ${{ needs.configure.outputs.LEAN_SPECIAL_VERSION_DESC }}
+      RELEASE_TAG: ${{ needs.configure.outputs.RELEASE_TAG }}
+    secrets: inherit
+
+  # build jobs that should not be considered by `all-done` below
+  build-secondary:
+    needs: [configure]
+    if: needs.configure.outputs.matrix-secondary != '[]'
+    uses: ./.github/workflows/build-template.yml
+    with:
+      config: ${{needs.configure.outputs.matrix-secondary}}
+      check-level: ${{ needs.configure.outputs.check-level }}
+      nightly: ${{ needs.configure.outputs.nightly }}
+      LEAN_VERSION_MAJOR: ${{ needs.configure.outputs.LEAN_VERSION_MAJOR }}
+      LEAN_VERSION_MINOR: ${{ needs.configure.outputs.LEAN_VERSION_MINOR }}
+      LEAN_VERSION_PATCH: ${{ needs.configure.outputs.LEAN_VERSION_PATCH }}
+      LEAN_SPECIAL_VERSION_DESC: ${{ needs.configure.outputs.LEAN_SPECIAL_VERSION_DESC }}
+      RELEASE_TAG: ${{ needs.configure.outputs.RELEASE_TAG }}
+    secrets: inherit
 
   # This job collects results from all the matrix jobs
   # This can be made the "required" job, instead of listing each

.github/workflows/pr-release.yml

@@ -34,7 +34,7 @@ jobs:
       - name: Download artifact from the previous workflow.
         if: ${{ steps.workflow-info.outputs.pullRequestNumber != '' }}
         id: download-artifact
-        uses: dawidd6/action-download-artifact@v8 # https://github.com/marketplace/actions/download-workflow-artifact
+        uses: dawidd6/action-download-artifact@v9 # https://github.com/marketplace/actions/download-workflow-artifact
         with:
           run_id: ${{ github.event.workflow_run.id }}
           path: artifacts
@@ -155,6 +155,20 @@ jobs:
           fi
 
           if [[ -n "$MESSAGE" ]]; then
+            # Check if force-mathlib-ci label is present
+            LABELS="$(curl --retry 3 --location --silent \
+                          -H "Authorization: token ${{ secrets.MATHLIB4_COMMENT_BOT }}" \
+                          -H "Accept: application/vnd.github.v3+json" \
+                          "https://api.github.com/repos/leanprover/lean4/issues/${{ steps.workflow-info.outputs.pullRequestNumber }}/labels" \
+                          | jq -r '.[].name')"
+            
+            if echo "$LABELS" | grep -q "^force-mathlib-ci$"; then
+              echo "force-mathlib-ci label detected, forcing CI despite issues"
+              MESSAGE="Forcing Mathlib CI because the \`force-mathlib-ci\` label is present, despite problem: $MESSAGE"
+              FORCE_CI=true
+            else
+              MESSAGE="$MESSAGE You can force Mathlib CI using the \`force-mathlib-ci\` label."
+            fi
 
             echo "Checking existing messages"
 
@@ -201,7 +215,12 @@ jobs:
             else
               echo "The message already exists in the comment body."
             fi
-            echo "mathlib_ready=false" >> "$GITHUB_OUTPUT"
+
+            if [[ "$FORCE_CI" == "true" ]]; then
+              echo "mathlib_ready=true" >> "$GITHUB_OUTPUT"
+            else
+              echo "mathlib_ready=false" >> "$GITHUB_OUTPUT"
+            fi
           else
             echo "mathlib_ready=true" >> "$GITHUB_OUTPUT"
           fi
@@ -252,7 +271,7 @@ jobs:
           if git ls-remote --heads --tags --exit-code origin "nightly-testing-${MOST_RECENT_NIGHTLY}" >/dev/null; then
             BASE="nightly-testing-${MOST_RECENT_NIGHTLY}"
           else
-            echo "This shouldn't be possible: couldn't find a 'nightly-testing-${MOST_RECENT_NIGHTLY}' tag at Batteries. Falling back to 'nightly-testing'."
+            echo "Couldn't find a 'nightly-testing-${MOST_RECENT_NIGHTLY}' tag at Batteries. Falling back to 'nightly-testing'."
             BASE=nightly-testing
           fi
 
@@ -316,7 +335,7 @@ jobs:
           if git ls-remote --heads --tags --exit-code origin "nightly-testing-${MOST_RECENT_NIGHTLY}" >/dev/null; then
             BASE="nightly-testing-${MOST_RECENT_NIGHTLY}"
           else
-            echo "This shouldn't be possible: couldn't find a 'nightly-testing-${MOST_RECENT_NIGHTLY}' branch at Mathlib. Falling back to 'nightly-testing'."
+            echo "Couldn't find a 'nightly-testing-${MOST_RECENT_NIGHTLY}' branch at Mathlib. Falling back to 'nightly-testing'."
             BASE=nightly-testing
           fi
 

CMakeLists.txt

@@ -15,10 +15,7 @@ foreach(var ${vars})
       # must forward options that generate incompatible .olean format
       list(APPEND STAGE0_ARGS "-D${var}=${${var}}")
     endif()
-    if("${var}" MATCHES "LLVM*")
-      list(APPEND STAGE0_ARGS "-D${var}=${${var}}")
-    endif()
-    if("${var}" MATCHES "PKG_CONFIG*")
+    if("${var}" MATCHES "LLVM*|PKG_CONFIG|USE_LAKE")
       list(APPEND STAGE0_ARGS "-D${var}=${${var}}")
     endif()
   elseif(("${var}" MATCHES "CMAKE_.*") AND NOT ("${var}" MATCHES "CMAKE_BUILD_TYPE") AND NOT ("${var}" MATCHES "CMAKE_HOME_DIRECTORY"))
@@ -47,10 +44,11 @@ if (NOT ${CMAKE_SYSTEM_NAME} MATCHES "Emscripten")
     if(${CMAKE_SYSTEM_NAME} MATCHES "Windows")
       string(APPEND CADICAL_CXXFLAGS " -DNUNLOCKED")
     endif()
+    string(APPEND CADICAL_CXXFLAGS " -DNCLOSEFROM")
     ExternalProject_add(cadical
       PREFIX cadical
       GIT_REPOSITORY https://github.com/arminbiere/cadical
-      GIT_TAG rel-1.9.5
+      GIT_TAG rel-2.1.2
       CONFIGURE_COMMAND ""
       # https://github.com/arminbiere/cadical/blob/master/BUILD.md#manual-build
       BUILD_COMMAND $(MAKE) -f ${CMAKE_SOURCE_DIR}/src/cadical.mk CMAKE_EXECUTABLE_SUFFIX=${CMAKE_EXECUTABLE_SUFFIX} CXX=${CADICAL_CXX} CXXFLAGS=${CADICAL_CXXFLAGS}
@@ -67,8 +65,8 @@ ExternalProject_add(stage0
   SOURCE_SUBDIR src
   BINARY_DIR stage0
   # do not rebuild stage0 when git hash changes; it's not from this commit anyway
-  # (however, `CHECK_OLEAN_VERSION=ON` in CI will override this as we need to
-  # embed the githash into the stage 1 library built by stage 0)
+  # (however, CI will override this as we need to embed the githash into the stage 1 library built
+  # by stage 0)
   CMAKE_ARGS -DSTAGE=0 -DUSE_GITHASH=OFF ${PLATFORM_ARGS} ${STAGE0_ARGS}
   BUILD_ALWAYS ON  # cmake doesn't auto-detect changes without a download method
   INSTALL_COMMAND ""  # skip install
@@ -82,6 +80,7 @@ ExternalProject_add(stage1
   BUILD_ALWAYS ON
   INSTALL_COMMAND ""
   DEPENDS stage0
+  STEP_TARGETS configure
 )
 ExternalProject_add(stage2
   SOURCE_DIR "${LEAN_SOURCE_DIR}"

doc/declarations.md

@@ -764,11 +764,12 @@ Structures and Records
 The ``structure`` command in Lean is used to define an inductive data type with a single constructor and to define its projections at the same time. The syntax is as follows:
 
 ```
-structure Foo (a : α) extends Bar, Baz : Sort u :=
+structure Foo (a : α) : Sort u extends Bar, Baz :=
 constructor :: (field₁ : β₁) ... (fieldₙ : βₙ)
 ```
 
-Here ``(a : α)`` is a telescope, that is, the parameters to the inductive definition. The name ``constructor`` followed by the double colon is optional; if it is not present, the name ``mk`` is used by default. The keyword ``extends`` followed by a list of previously defined structures is also optional; if it is present, an instance of each of these structures is included among the fields to ``Foo``, and the types ``βᵢ`` can refer to their fields as well. The output type, ``Sort u``, can be omitted, in which case Lean infers to smallest non-``Prop`` sort possible. Finally, ``(field₁ : β₁) ... (fieldₙ : βₙ)`` is a telescope relative to ``(a : α)`` and the fields in ``bar`` and ``baz``.
+Here ``(a : α)`` is a telescope, that is, the parameters to the inductive definition. The name ``constructor`` followed by the double colon is optional; if it is not present, the name ``mk`` is used by default. The keyword ``extends`` followed by a list of previously defined structures is also optional; if it is present, an instance of each of these structures is included among the fields to ``Foo``, and the types ``βᵢ`` can refer to their fields as well. The output type, ``Sort u``, can be omitted, in which case Lean infers to smallest non-``Prop`` sort possible (unless all the fields are ``Prop``, in which case it infers ``Prop``).
+Finally, ``(field₁ : β₁) ... (fieldₙ : βₙ)`` is a telescope relative to ``(a : α)`` and the fields in ``bar`` and ``baz``.
 
 The declaration above is syntactic sugar for an inductive type declaration, and so results in the addition of the following constants to the environment:
 

doc/std/naming.md

@@ -239,3 +239,22 @@ If an acronym is typically spelled using mixed case, this mixed spelling may be
 
 Simp sets centered around a conversion function should be called `source_to_target`. For example, a simp set for the `BitVec.toNat` function, which goes from `BitVec` to
 `Nat`, should be called `bitvec_to_nat`.
+
+## Variable names
+
+We make the following recommendations for variable names, but without insisting on them:
+* Simple hypotheses should be named `h`, `h'`, or using a numerical sequence `h₁`, `h₂`, etc.
+* Another common name for a simple hypothesis is `w` (for "witness").
+* `List`s should be named `l`, `l'`, `l₁`, etc, or `as`, `bs`, etc.
+  (Use of `as`, `bs` is encouraged when the lists are of different types, e.g. `as : List α` and `bs : List β`.)
+  `xs`, `ys`, `zs` are allowed, but it is better if these are reserved for `Array` and `Vector`.
+  A list of lists may be named `L`.
+* `Array`s should be named `xs`, `ys`, `zs`, although `as`, `bs` are encouraged when the arrays are of different types, e.g. `as : Array α` and `bs : Array β`.
+  An array of arrays may be named `xss`.
+* `Vector`s should be named `xs`, `ys`, `zs`, although `as`, `bs` are encouraged when the vectors are of different types, e.g. `as : Vector α n` and `bs : Vector β n`.
+  A vector of vectors may be named `xss`.
+* A common exception for `List` / `Array` / `Vector` is to use `acc` for an accumulator in a recursive function.
+* `i`, `j`, `k` are preferred for numerical indices.
+  Descriptive names such as `start`, `stop`, `lo`, and `hi` are encouraged when they increase readability.
+* `n`, `m` are preferred for sizes, e.g. in `Vector α n` or `xs.size = n`.
+* `w` is preferred for the width of a `BitVec`.

flake.lock

@@ -36,17 +36,17 @@
     },
     "nixpkgs-cadical": {
       "locked": {
-        "lastModified": 1722221733,
-        "narHash": "sha256-sga9SrrPb+pQJxG1ttJfMPheZvDOxApFfwXCFO0H9xw=",
+        "lastModified": 1740791350,
+        "narHash": "sha256-igS2Z4tVw5W/x3lCZeeadt0vcU9fxtetZ/RyrqsCRQ0=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "12bf09802d77264e441f48e25459c10c93eada2e",
+        "rev": "199169a2135e6b864a888e89a2ace345703c025d",
         "type": "github"
       },
       "original": {
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "12bf09802d77264e441f48e25459c10c93eada2e",
+        "rev": "199169a2135e6b864a888e89a2ace345703c025d",
         "type": "github"
       }
     },

flake.nix

@@ -8,8 +8,8 @@
   # old nixpkgs used for portable release with older glibc (2.26)
   inputs.nixpkgs-older.url = "github:NixOS/nixpkgs/0b307aa73804bbd7a7172899e59ae0b8c347a62d";
   inputs.nixpkgs-older.flake = false;
-  # for cadical 1.9.5; sync with CMakeLists.txt
-  inputs.nixpkgs-cadical.url = "github:NixOS/nixpkgs/12bf09802d77264e441f48e25459c10c93eada2e";
+  # for cadical 2.1.2; sync with CMakeLists.txt by taking commit from https://www.nixhub.io/packages/cadical
+  inputs.nixpkgs-cadical.url = "github:NixOS/nixpkgs/199169a2135e6b864a888e89a2ace345703c025d";
   inputs.flake-utils.url = "github:numtide/flake-utils";
 
   outputs = inputs: inputs.flake-utils.lib.eachDefaultSystem (system:
@@ -63,6 +63,7 @@
           GLIBC_DEV = pkgsDist.glibc.dev;
           GCC_LIB = pkgsDist.gcc.cc.lib;
           ZLIB = pkgsDist.zlib;
+          # for CI coredumps
           GDB = pkgsDist.gdb;
         });
     in {

script/prepare-llvm-mingw.sh

@@ -25,7 +25,10 @@ cp llvm/lib/clang/*/include/{std*,__std*,limits}.h stage1/include/clang
 echo '
 // https://docs.microsoft.com/en-us/windows/win32/api/errhandlingapi/nf-errhandlingapi-seterrormode
 #define SEM_FAILCRITICALERRORS 0x0001
-__declspec(dllimport) __stdcall unsigned int SetErrorMode(unsigned int uMode);' > stage1/include/clang/windows.h
+__declspec(dllimport) __stdcall unsigned int SetErrorMode(unsigned int uMode);
+// https://docs.microsoft.com/en-us/windows/console/setconsoleoutputcp
+#define CP_UTF8 65001
+__declspec(dllimport) __stdcall int SetConsoleOutputCP(unsigned int wCodePageID);' > stage1/include/clang/windows.h
 # COFF dependencies
 cp /clang64/lib/{crtbegin,crtend,crt2,dllcrt2}.o stage1/lib/
 # runtime

script/release_notes.py

@@ -65,20 +65,21 @@ def format_markdown_description(pr_number, description):
     link = f"[#{pr_number}](https://github.com/leanprover/lean4/pull/{pr_number})"
     return f"{link} {description}"
 
+def commit_types():
+    # see doc/dev/commit_convention.md
+    return ['feat', 'fix', 'doc', 'style', 'refactor', 'test', 'chore', 'perf']
+
 def count_commit_types(commits):
     counts = {
         'total': len(commits),
-        'feat': 0,
-        'fix': 0,
-        'refactor': 0,
-        'doc': 0,
-        'chore': 0
     }
+    for commit_type in commit_types():
+        counts[commit_type] = 0
     
     for _, first_line, _ in commits:
-        for commit_type in ['feat:', 'fix:', 'refactor:', 'doc:', 'chore:']:
-            if first_line.startswith(commit_type):
-                counts[commit_type.rstrip(':')] += 1
+        for commit_type in commit_types():
+            if first_line.startswith(f'{commit_type}:'):
+                counts[commit_type] += 1
                 break
     
     return counts
@@ -158,8 +159,9 @@ def main():
     counts = count_commit_types(commits)
     print(f"For this release, {counts['total']} changes landed. "
           f"In addition to the {counts['feat']} feature additions and {counts['fix']} fixes listed below "
-          f"there were {counts['refactor']} refactoring changes, {counts['doc']} documentation improvements "
-          f"and {counts['chore']} chores.\n")
+          f"there were {counts['refactor']} refactoring changes, {counts['doc']} documentation improvements, "
+          f"{counts['perf']} performance improvements, {counts['test']} improvements to the test suite "
+          f"and {counts['style'] + counts['chore']} other changes.\n")
 
     section_order = sort_sections_order()
     sorted_changelog = sorted(changelog.items(), key=lambda item: section_order.index(format_section_title(item[0])) if format_section_title(item[0]) in section_order else len(section_order))
@@ -168,7 +170,12 @@ def main():
         section_title = format_section_title(label) if label != "Uncategorised" else "Uncategorised"
         print(f"## {section_title}\n")
         for _, entry in sorted(entries, key=lambda x: x[0]):
-            print(f"* {entry}\n")
+            # Split entry into lines and indent all lines after the first
+            lines = entry.splitlines()
+            print(f"* {lines[0]}")
+            for line in lines[1:]:
+                print(f"  {line}")
+            print()  # Empty line after each entry
 
 if __name__ == "__main__":
     main()

src/CMakeLists.txt

@@ -10,7 +10,7 @@ endif()
 include(ExternalProject)
 project(LEAN CXX C)
 set(LEAN_VERSION_MAJOR 4)
-set(LEAN_VERSION_MINOR 18)
+set(LEAN_VERSION_MINOR 19)
 set(LEAN_VERSION_PATCH 0)
 set(LEAN_VERSION_IS_RELEASE 0)  # This number is 1 in the release revision, and 0 otherwise.
 set(LEAN_SPECIAL_VERSION_DESC "" CACHE STRING "Additional version description like 'nightly-2018-03-11'")
@@ -144,11 +144,12 @@ if(${CMAKE_SYSTEM_NAME} MATCHES "Windows")
   # do not import the world from windows.h using appropriately named flag
   string(APPEND LEAN_EXTRA_CXX_FLAGS " -D WIN32_LEAN_AND_MEAN")
   # DLLs must go next to executables on Windows
-  set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/bin")
+  set(CMAKE_RELATIVE_LIBRARY_OUTPUT_DIRECTORY "bin")
 else()
-  set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/lib/lean")
+  set(CMAKE_RELATIVE_LIBRARY_OUTPUT_DIRECTORY "lib/lean")
 endif()
 
+set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/${CMAKE_RELATIVE_LIBRARY_OUTPUT_DIRECTORY}")
 set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/lib/lean")
 
 # OSX default thread stack size is very small. Moreover, in Debug mode, each new stack frame consumes a lot of extra memory.
@@ -454,20 +455,20 @@ if(${CMAKE_SYSTEM_NAME} MATCHES "Linux")
   string(APPEND CMAKE_CXX_FLAGS " -fPIC -ftls-model=initial-exec")
   string(APPEND LEANC_EXTRA_CC_FLAGS " -fPIC")
   string(APPEND TOOLCHAIN_SHARED_LINKER_FLAGS " -Wl,-rpath=\\$$ORIGIN/..:\\$$ORIGIN")
-  string(APPEND LAKESHARED_LINKER_FLAGS " -Wl,--whole-archive ${CMAKE_BINARY_DIR}/lib/temp/libLake.a.export -Wl,--no-whole-archive")
-  string(APPEND CMAKE_EXE_LINKER_FLAGS " -Wl,-rpath=\\\$ORIGIN/../lib:\\\$ORIGIN/../lib/lean")
+  string(APPEND LAKESHARED_LINKER_FLAGS " -Wl,--whole-archive ${CMAKE_BINARY_DIR}/lib/lean/libLake.a.export -Wl,--no-whole-archive")
+  string(APPEND CMAKE_EXE_LINKER_FLAGS " -Wl,-rpath=$ORIGIN/../lib:$ORIGIN/../lib/lean")
 elseif(${CMAKE_SYSTEM_NAME} MATCHES "Darwin")
   string(APPEND CMAKE_CXX_FLAGS " -ftls-model=initial-exec")
   string(APPEND INIT_SHARED_LINKER_FLAGS " -install_name @rpath/libInit_shared.dylib")
   string(APPEND LEANSHARED_1_LINKER_FLAGS " -install_name @rpath/libleanshared_1.dylib")
   string(APPEND LEANSHARED_LINKER_FLAGS " -install_name @rpath/libleanshared.dylib")
-  string(APPEND LAKESHARED_LINKER_FLAGS " -Wl,-force_load,${CMAKE_BINARY_DIR}/lib/temp/libLake.a.export -install_name @rpath/libLake_shared.dylib")
+  string(APPEND LAKESHARED_LINKER_FLAGS " -Wl,-force_load,${CMAKE_BINARY_DIR}/lib/lean/libLake.a.export -install_name @rpath/libLake_shared.dylib")
   string(APPEND CMAKE_EXE_LINKER_FLAGS " -Wl,-rpath,@executable_path/../lib -Wl,-rpath,@executable_path/../lib/lean")
 elseif(${CMAKE_SYSTEM_NAME} MATCHES "Emscripten")
   string(APPEND CMAKE_CXX_FLAGS " -fPIC")
   string(APPEND LEANC_EXTRA_CC_FLAGS " -fPIC")
 elseif(${CMAKE_SYSTEM_NAME} MATCHES "Windows")
-  string(APPEND LAKESHARED_LINKER_FLAGS " -Wl,--out-implib,${CMAKE_BINARY_DIR}/lib/lean/libLake_shared.dll.a -Wl,--whole-archive ${CMAKE_BINARY_DIR}/lib/temp/libLake.a.export -Wl,--no-whole-archive")
+  string(APPEND LAKESHARED_LINKER_FLAGS " -Wl,--out-implib,${CMAKE_BINARY_DIR}/lib/lean/libLake_shared.dll.a -Wl,--whole-archive ${CMAKE_BINARY_DIR}/lib/lean/libLake.a.export -Wl,--no-whole-archive")
 endif()
 
 if(${CMAKE_SYSTEM_NAME} MATCHES "Linux")
@@ -514,7 +515,16 @@ if(USE_GITHASH)
     message(STATUS "git commit sha1: ${GIT_SHA1}")
   endif()
 else()
-  set(GIT_SHA1 "")
+  if(USE_LAKE AND ${STAGE} EQUAL 0)
+    # we need to embed *some* hash for Lake to invalidate stage 1 on stage 0 changes
+    execute_process(
+        COMMAND git ls-tree HEAD "${CMAKE_CURRENT_SOURCE_DIR}/../../stage0" --object-only
+        OUTPUT_VARIABLE GIT_SHA1
+        OUTPUT_STRIP_TRAILING_WHITESPACE)
+    message(STATUS "stage0 sha1: ${GIT_SHA1}")
+  else()
+    set(GIT_SHA1 "")
+  endif()
 endif()
 configure_file("${LEAN_SOURCE_DIR}/githash.h.in" "${LEAN_BINARY_DIR}/githash.h")
 
@@ -541,6 +551,9 @@ include_directories(${LEAN_SOURCE_DIR})
 include_directories(${CMAKE_BINARY_DIR})  # version.h etc., "private" headers
 include_directories(${CMAKE_BINARY_DIR}/include)  # config.h etc., "public" headers
 
+# Lean code only needs this one include
+string(APPEND LEANC_OPTS " -I${CMAKE_BINARY_DIR}/include")
+
 # Use CMake profile C++ flags for building Lean libraries, but do not embed in `leanc`
 string(TOUPPER "${CMAKE_BUILD_TYPE}" uppercase_CMAKE_BUILD_TYPE)
 string(APPEND LEANC_OPTS " ${CMAKE_CXX_FLAGS_${uppercase_CMAKE_BUILD_TYPE}}")
@@ -753,7 +766,12 @@ add_custom_target(clean-olean
   DEPENDS clean-stdlib)
 
 install(DIRECTORY "${CMAKE_BINARY_DIR}/lib/" DESTINATION lib
-  PATTERN temp EXCLUDE)
+  PATTERN temp
+  PATTERN "*.export"
+  PATTERN "*.hash"
+  PATTERN "*.trace"
+  PATTERN "*.rsp"
+  EXCLUDE)
 
 # symlink source into expected installation location for go-to-definition, if file system allows it
 file(MAKE_DIRECTORY ${CMAKE_BINARY_DIR}/src)
@@ -784,10 +802,32 @@ if(LEAN_INSTALL_PREFIX)
 endif()
 
 # Escape for `make`. Yes, twice.
-string(REPLACE "$" "$$" CMAKE_EXE_LINKER_FLAGS_MAKE "${CMAKE_EXE_LINKER_FLAGS}")
+string(REPLACE "$" "\\\$$" CMAKE_EXE_LINKER_FLAGS_MAKE "${CMAKE_EXE_LINKER_FLAGS}")
 string(REPLACE "$" "$$" CMAKE_EXE_LINKER_FLAGS_MAKE_MAKE "${CMAKE_EXE_LINKER_FLAGS_MAKE}")
 configure_file(${LEAN_SOURCE_DIR}/stdlib.make.in ${CMAKE_BINARY_DIR}/stdlib.make)
 
+# hacky
+function(toml_escape IN OUTVAR)
+  if(IN)
+    string(STRIP "${IN}" OUT)
+    string(REPLACE " " "\", \"" OUT "${OUT}")
+    set(${OUTVAR} "\"${OUT}\"" PARENT_SCOPE)
+  endif()
+endfunction()
+string(REPLACE "ROOT" "${CMAKE_BINARY_DIR}" LEANC_CC "${LEANC_CC}")
+string(REPLACE "ROOT" "${CMAKE_BINARY_DIR}" LEANC_INTERNAL_FLAGS "${LEANC_INTERNAL_FLAGS}")
+string(REPLACE "ROOT" "${CMAKE_BINARY_DIR}" LEANC_INTERNAL_LINKER_FLAGS "${LEANC_INTERNAL_LINKER_FLAGS}")
+set(LEANC_OPTS_TOML "${LEANC_OPTS} ${LEANC_EXTRA_CC_FLAGS} ${LEANC_INTERNAL_FLAGS}")
+set(LINK_OPTS_TOML "${LEANC_INTERNAL_LINKER_FLAGS} -L${CMAKE_BINARY_DIR}/lib/lean ${LEAN_EXTRA_LINKER_FLAGS}")
+
+toml_escape("${LEAN_EXTRA_MAKE_OPTS}" LEAN_EXTRA_OPTS_TOML)
+toml_escape("${LEANC_OPTS_TOML}" LEANC_OPTS_TOML)
+toml_escape("${LINK_OPTS_TOML}" LINK_OPTS_TOML)
+
+if(${CMAKE_SYSTEM_NAME} MATCHES "Windows")
+  set(LAKE_LIB_PREFIX "lib")
+endif()
+
 if(USE_LAKE AND STAGE EQUAL 1)
   configure_file(${LEAN_SOURCE_DIR}/lakefile.toml.in ${LEAN_SOURCE_DIR}/lakefile.toml)
   configure_file(${LEAN_SOURCE_DIR}/lakefile.toml.in ${LEAN_SOURCE_DIR}/../tests/lakefile.toml)

src/Init.lean

@@ -40,3 +40,4 @@ import Init.Syntax
 import Init.Internal
 import Init.Try
 import Init.BinderNameHint
+import Init.Task

src/Init/Classical.lean

@@ -175,7 +175,10 @@ theorem or_iff_not_imp_right : a ∨ b ↔ (¬b → a) := Decidable.or_iff_not_i
 
 theorem not_imp_iff_and_not : ¬(a → b) ↔ a ∧ ¬b := Decidable.not_imp_iff_and_not
 
-theorem not_and_iff_or_not_not : ¬(a ∧ b) ↔ ¬a ∨ ¬b := Decidable.not_and_iff_or_not_not
+theorem not_and_iff_not_or_not : ¬(a ∧ b) ↔ ¬a ∨ ¬b := Decidable.not_and_iff_not_or_not
+
+@[deprecated not_and_iff_not_or_not (since := "2025-03-18")]
+abbrev not_and_iff_or_not_not := @not_and_iff_not_or_not
 
 theorem not_iff : ¬(a ↔ b) ↔ (¬a ↔ b) := Decidable.not_iff
 

src/Init/Control/Basic.lean

@@ -51,14 +51,28 @@ def ForInStep.value (x : ForInStep α) : α :=
 @[simp] theorem ForInStep.value_done (b : β) : (ForInStep.done b).value = b := rfl
 @[simp] theorem ForInStep.value_yield (b : β) : (ForInStep.yield b).value = b := rfl
 
+/--
+Maps a function over a functor, with parameters swapped so that the function comes last.
+
+This function is `Functor.map` with the parameters reversed, typically used via the `<&>` operator.
+-/
 @[reducible]
 def Functor.mapRev {f : Type u → Type v} [Functor f] {α β : Type u} : f α → (α → β) → f β :=
   fun a f => f <$> a
 
+@[inherit_doc Functor.mapRev]
 infixr:100 " <&> " => Functor.mapRev
 
 recommended_spelling "mapRev" for "<&>" in [Functor.mapRev, «term_<&>_»]
 
+/--
+Discards the value in a functor, retaining the functor's structure.
+
+Discarding values is especially useful when using `Applicative` functors or `Monad`s to implement
+effects, and some operation should be carried out only for its effects. In `do`-notation, statements
+whose values are discarded must return `Unit`, and `discard` can be used to explicitly discard their
+values.
+-/
 @[always_inline, inline]
 def Functor.discard {f : Type u → Type v} {α : Type u} [Functor f] (x : f α) : f PUnit :=
   Functor.mapConst PUnit.unit x
@@ -78,7 +92,7 @@ Error recovery and state can interact subtly. For example, the implementation of
 -/
 -- NB: List instance is in mathlib. Once upstreamed, add
 -- * `List`, where `failure` is the empty list and `<|>` concatenates.
-class Alternative (f : Type u → Type v) extends Applicative f : Type (max (u+1) v) where
+class Alternative (f : Type u → Type v) : Type (max (u+1) v) extends Applicative f where
   /--
   Produces an empty collection or recoverable failure.  The `<|>` operator collects values or recovers
   from failures. See `Alternative` for more details.
@@ -121,6 +135,13 @@ instance : ToBool Bool where
   | true  => t
   | false => f
 
+/--
+Converts the result of the monadic action `x` to a `Bool`. If it is `true`, returns it and ignores
+`y`; otherwise, runs `y` and returns its result.
+
+This a monadic counterpart to the short-circuiting `||` operator, usually accessed via the `<||>`
+operator.
+-/
 @[macro_inline] def orM {m : Type u → Type v} {β : Type u} [Monad m] [ToBool β] (x y : m β) : m β := do
   let b ← x
   match toBool b with
@@ -131,6 +152,13 @@ infixr:30 " <||> " => orM
 
 recommended_spelling "orM" for "<||>" in [orM, «term_<||>_»]
 
+/--
+Converts the result of the monadic action `x` to a `Bool`. If it is `true`, returns `y`; otherwise,
+returns the original result of `x`.
+
+This a monadic counterpart to the short-circuiting `&&` operator, usually accessed via the `<&&>`
+operator.
+-/
 @[macro_inline] def andM {m : Type u → Type v} {β : Type u} [Monad m] [ToBool β] (x y : m β) : m β := do
   let b ← x
   match toBool b with
@@ -141,6 +169,9 @@ infixr:35 " <&&> " => andM
 
 recommended_spelling "andM" for "<&&>" in [andM, «term_<&&>_»]
 
+/--
+Runs a monadic action and returns the negation of its result.
+-/
 @[macro_inline] def notM {m : Type → Type v} [Applicative m] (x : m Bool) : m Bool :=
   not <$> x
 
@@ -256,21 +287,61 @@ Using `control` means that `runInBase` can be used multiple times.
 -/
 
 
-/-- MonadControl is a way of stating that the monad `m` can be 'run inside' the monad `n`.
-
-This is the same as [`MonadBaseControl`](https://hackage.haskell.org/package/monad-control-1.0.3.1/docs/Control-Monad-Trans-Control.html#t:MonadBaseControl) in Haskell.
-To learn about `MonadControl`, see the comment above this docstring.
+/--
+A way to lift a computation from one monad to another while providing the lifted computation with a
+means of interpreting computations from the outer monad. This provides a means of lifting
+higher-order operations automatically.
 
+Clients should typically use `control` or `controlAt`, which request an instance of `MonadControlT`:
+the reflexive, transitive closure of `MonadControl`. New instances should be defined for
+`MonadControl` itself.
 -/
+-- This is the same as
+-- [`MonadBaseControl`](https://hackage.haskell.org/package/monad-control-1.0.3.1/docs/Control-Monad-Trans-Control.html#t:MonadBaseControl)
+-- in Haskell.
 class MonadControl (m : semiOutParam (Type u → Type v)) (n : Type u → Type w) where
+  /--
+  A type that can be used to reconstruct both a returned value and any state used by the outer
+  monad.
+  -/
   stM      : Type u → Type u
+  /--
+  Lifts an action from the inner monad `m` to the outer monad `n`. The inner monad has access to a
+  reverse lifting operator that can run an `n` action, returning a value and state together.
+  -/
   liftWith : {α : Type u} → (({β : Type u} → n β → m (stM β)) → m α) → n α
+  /--
+  Lifts a monadic action that returns a state and a value in the inner monad to an action in the
+  outer monad. The extra state information is used to restore the results of effects from the
+  reverse lift passed to `liftWith`'s parameter.
+  -/
   restoreM : {α : Type u} → m (stM α) → n α
 
-/-- Transitive closure of MonadControl. -/
+/--
+A way to lift a computation from one monad to another while providing the lifted computation with a
+means of interpreting computations from the outer monad. This provides a means of lifting
+higher-order operations automatically.
+
+Clients should typically use `control` or `controlAt`, which request an instance of `MonadControlT`:
+the reflexive, transitive closure of `MonadControl`. New instances should be defined for
+`MonadControl` itself.
+-/
 class MonadControlT (m : Type u → Type v) (n : Type u → Type w) where
+  /--
+  A type that can be used to reconstruct both a returned value and any state used by the outer
+  monad.
+  -/
   stM      : Type u → Type u
+  /--
+  Lifts an action from the inner monad `m` to the outer monad `n`. The inner monad has access to a
+  reverse lifting operator that can run an `n` action, returning a value and state together.
+  -/
   liftWith : {α : Type u} → (({β : Type u} → n β → m (stM β)) → m α) → n α
+  /--
+  Lifts a monadic action that returns a state and a value in the inner monad to an action in the
+  outer monad. The extra state information is used to restore the results of effects from the
+  reverse lift passed to `liftWith`'s parameter.
+  -/
   restoreM {α : Type u} : stM α → n α
 
 export MonadControlT (stM liftWith restoreM)
@@ -286,11 +357,28 @@ instance (m : Type u → Type v) [Pure m] : MonadControlT m m where
   liftWith f := f fun x => x
   restoreM x := pure x
 
+/--
+Lifts an operation from an inner monad to an outer monad, providing it with a reverse lifting
+operator that allows outer monad computations to be run in the inner monad. The lifted operation is
+required to return extra information that is required in order to reconstruct the reverse lift's
+effects in the outer monad; this extra information is determined by `stM`.
+
+This function takes the inner monad as an explicit parameter. Use `control` to infer the monad.
+-/
 @[always_inline, inline]
 def controlAt (m : Type u → Type v) {n : Type u → Type w} [MonadControlT m n] [Bind n] {α : Type u}
     (f : ({β : Type u} → n β → m (stM m n β)) → m (stM m n α)) : n α :=
   liftWith f >>= restoreM
 
+/--
+Lifts an operation from an inner monad to an outer monad, providing it with a reverse lifting
+operator that allows outer monad computations to be run in the inner monad. The lifted operation is
+required to return extra information that is required in order to reconstruct the reverse lift's
+effects in the outer monad; this extra information is determined by `stM`.
+
+This function takes the inner monad as an implicit parameter. Use `controlAt` to specify it
+explicitly.
+-/
 @[always_inline, inline]
 def control {m : Type u → Type v} {n : Type u → Type w} [MonadControlT m n] [Bind n] {α : Type u}
     (f : ({β : Type u} → n β → m (stM m n β)) → m (stM m n α)) : n α :=

src/Init/Control/Except.lean

@@ -13,10 +13,20 @@ import Init.Coe
 namespace Except
 variable {ε : Type u}
 
+/--
+A successful computation in the `Except ε` monad: `a` is returned, and no exception is thrown.
+-/
 @[always_inline, inline]
 protected def pure (a : α) : Except ε α :=
   Except.ok a
 
+/--
+Transforms a successful result with a function, doing nothing when an exception is thrown.
+
+Examples:
+ * `(pure 2 : Except String Nat).map toString = pure 2`
+ * `(throw "Error" : Except String Nat).map toString = throw "Error"`
+-/
 @[always_inline, inline]
 protected def map (f : α → β) : Except ε α → Except ε β
   | Except.error err => Except.error err
@@ -27,36 +37,78 @@ protected def map (f : α → β) : Except ε α → Except ε β
   intro e
   simp [Except.map]; cases e <;> rfl
 
+/--
+Transforms exceptions with a function, doing nothing on successful results.
+
+Examples:
+ * `(pure 2 : Except String Nat).mapError (·.length) = pure 2`
+ * `(throw "Error" : Except String Nat).mapError (·.length) = throw 5`
+-/
 @[always_inline, inline]
 protected def mapError (f : ε → ε') : Except ε α → Except ε' α
   | Except.error err => Except.error <| f err
   | Except.ok v      => Except.ok v
 
+/--
+Sequences two operations that may throw exceptions, allowing the second to depend on the value
+returned by the first.
+
+If the first operation throws an exception, then it is the result of the computation. If the first
+succeeds but the second throws an exception, then that exception is the result. If both succeed,
+then the result is the result of the second computation.
+
+This is the implementation of the `>>=` operator for `Except ε`.
+-/
 @[always_inline, inline]
 protected def bind (ma : Except ε α) (f : α → Except ε β) : Except ε β :=
   match ma with
   | Except.error err => Except.error err
   | Except.ok v      => f v
 
-/-- Returns true if the value is `Except.ok`, false otherwise. -/
+/-- Returns `true` if the value is `Except.ok`, `false` otherwise. -/
 @[always_inline, inline]
 protected def toBool : Except ε α → Bool
   | Except.ok _    => true
   | Except.error _ => false
 
+@[inherit_doc Except.toBool]
 abbrev isOk : Except ε α → Bool := Except.toBool
 
+/--
+Returns `none` if an exception was thrown, or `some` around the value on success.
+
+Examples:
+ * `(pure 10 : Except String Nat).toOption = some 10`
+ * `(throw "Failure" : Except String Nat).toOption = none`
+-/
 @[always_inline, inline]
 protected def toOption : Except ε α → Option α
   | Except.ok a    => some a
   | Except.error _ => none
 
+/--
+Handles exceptions thrown in the `Except ε` monad.
+
+If `ma` is successful, its result is returned. If it throws an exception, then `handle` is invoked
+on the exception's value.
+
+Examples:
+ * `(pure 2 : Except String Nat).tryCatch (pure ·.length) = pure 2`
+ * `(throw "Error" : Except String Nat).tryCatch (pure ·.length) = pure 5`
+ * `(throw "Error" : Except String Nat).tryCatch (fun x => throw ("E: " ++ x)) = throw "E: Error"`
+-/
 @[always_inline, inline]
 protected def tryCatch (ma : Except ε α) (handle : ε → Except ε α) : Except ε α :=
   match ma with
   | Except.ok a    => Except.ok a
   | Except.error e => handle e
 
+/--
+Recovers from exceptions thrown in the `Except ε` monad. Typically used via the `<|>` operator.
+
+`Except.tryCatch` is a related operator that allows the recovery procedure to depend on _which_
+exception was thrown.
+-/
 def orElseLazy (x : Except ε α) (y : Unit → Except ε α) : Except ε α :=
   match x with
   | Except.ok a    => Except.ok a
@@ -70,12 +122,26 @@ instance : Monad (Except ε) where
 
 end Except
 
+/--
+Adds exceptions of type `ε` to a monad `m`.
+-/
 def ExceptT (ε : Type u) (m : Type u → Type v) (α : Type u) : Type v :=
   m (Except ε α)
 
+/--
+Use a monadic action that may return an exception's value as an action in the transformed monad that
+may throw the corresponding exception.
+
+This is the inverse of `ExceptT.run`.
+-/
 @[always_inline, inline]
 def ExceptT.mk {ε : Type u} {m : Type u → Type v} {α : Type u} (x : m (Except ε α)) : ExceptT ε m α := x
 
+/--
+Use a monadic action that may throw an exception as an action that may return an exception's value.
+
+This is the inverse of `ExceptT.mk`.
+-/
 @[always_inline, inline]
 def ExceptT.run {ε : Type u} {m : Type u → Type v} {α : Type u} (x : ExceptT ε m α) : m (Except ε α) := x
 
@@ -83,25 +149,41 @@ namespace ExceptT
 
 variable {ε : Type u} {m : Type u → Type v} [Monad m]
 
+/--
+Returns the value `a` without throwing exceptions or having any other effect.
+-/
 @[always_inline, inline]
 protected def pure {α : Type u} (a : α) : ExceptT ε m α :=
   ExceptT.mk <| pure (Except.ok a)
 
+/--
+Handles exceptions thrown by an action that can have no effects _other_ than throwing exceptions.
+-/
 @[always_inline, inline]
 protected def bindCont {α β : Type u} (f : α → ExceptT ε m β) : Except ε α → m (Except ε β)
   | Except.ok a    => f a
   | Except.error e => pure (Except.error e)
 
+/--
+Sequences two actions that may throw exceptions. Typically used via `do`-notation or the `>>=`
+operator.
+-/
 @[always_inline, inline]
 protected def bind {α β : Type u} (ma : ExceptT ε m α) (f : α → ExceptT ε m β) : ExceptT ε m β :=
   ExceptT.mk <| ma >>= ExceptT.bindCont f
 
+/--
+Transforms a successful computation's value using `f`. Typically used via the `<$>` operator.
+-/
 @[always_inline, inline]
 protected def map {α β : Type u} (f : α → β) (x : ExceptT ε m α) : ExceptT ε m β :=
   ExceptT.mk <| x >>= fun a => match a with
     | (Except.ok a)    => pure <| Except.ok (f a)
     | (Except.error e) => pure <| Except.error e
 
+/--
+Runs a computation from an underlying monad in the transformed monad with exceptions.
+-/
 @[always_inline, inline]
 protected def lift {α : Type u} (t : m α) : ExceptT ε m α :=
   ExceptT.mk <| Except.ok <$> t
@@ -110,6 +192,9 @@ protected def lift {α : Type u} (t : m α) : ExceptT ε m α :=
 instance : MonadLift (Except ε) (ExceptT ε m) := ⟨fun e => ExceptT.mk <| pure e⟩
 instance : MonadLift m (ExceptT ε m) := ⟨ExceptT.lift⟩
 
+/--
+Handles exceptions produced in the `ExceptT ε` transformer.
+-/
 @[always_inline, inline]
 protected def tryCatch {α : Type u} (ma : ExceptT ε m α) (handle : ε → ExceptT ε m α) : ExceptT ε m α :=
   ExceptT.mk <| ma >>= fun res => match res with
@@ -124,6 +209,11 @@ instance : Monad (ExceptT ε m) where
   bind := ExceptT.bind
   map  := ExceptT.map
 
+/--
+Transforms exceptions using the function `f`.
+
+This is the `ExceptT` version of `Except.mapError`.
+-/
 @[always_inline, inline]
 protected def adapt {ε' α : Type u} (f : ε → ε') : ExceptT ε m α → ExceptT ε' m α := fun x =>
   ExceptT.mk <| Except.mapError f <$> x
@@ -150,8 +240,12 @@ instance (ε) : MonadExceptOf ε (Except ε) where
 namespace MonadExcept
 variable {ε : Type u} {m : Type v → Type w}
 
-/-- Alternative orelse operator that allows to select which exception should be used.
-    The default is to use the first exception since the standard `orelse` uses the second. -/
+/--
+An alternative unconditional error recovery operator that allows callers to specify which exception
+to throw in cases where both operations throw exceptions.
+
+By default, the first is thrown, because the `<|>` operator throws the second.
+-/
 @[always_inline, inline]
 def orelse' [MonadExcept ε m] {α : Type v} (t₁ t₂ : m α) (useFirstEx := true) : m α :=
   tryCatch t₁ fun e₁ => tryCatch t₂ fun e₂ => throw (if useFirstEx then e₁ else e₂)
@@ -171,13 +265,24 @@ instance (ε : Type u) (m : Type u → Type v) [Monad m] : MonadControl m (Excep
   liftWith f := liftM <| f fun x => x.run
   restoreM x := x
 
+/--
+Monads that provide the ability to ensure an action happens, regardless of exceptions or other
+failures.
+
+`MonadFinally.tryFinally'` is used to desugar `try ... finally ...` syntax.
+-/
 class MonadFinally (m : Type u → Type v) where
-  /-- `tryFinally' x f` runs `x` and then the "finally" computation `f`.
-  When `x` succeeds with `a : α`, `f (some a)` is returned. If `x` fails
-  for `m`'s definition of failure, `f none` is returned. Hence `tryFinally'`
-  can be thought of as performing the same role as a `finally` block in
-  an imperative programming language. -/
-  tryFinally' {α β} : m α → (Option α → m β) → m (α × β)
+  /--
+  Runs an action, ensuring that some other action always happens afterward.
+
+  More specifically, `tryFinally' x f` runs `x` and then the “finally” computation `f`. If `x`
+  succeeds with some value `a : α`, `f (some a)` is returned. If `x` fails for `m`'s definition of
+  failure, `f none` is returned.
+
+  `tryFinally'` can be thought of as performing the same role as a `finally` block in an imperative
+  programming language.
+  -/
+  tryFinally' {α β} : (x : m α) → (f : Option α → m β) → m (α × β)
 
 export MonadFinally (tryFinally')
 

src/Init/Control/ExceptCps.lean

@@ -10,19 +10,37 @@ import Init.Control.Lawful.Basic
 The Exception monad transformer using CPS style.
 -/
 
+/--
+Adds exceptions of type `ε` to a monad `m`.
+
+Instead of using `Except ε` to model exceptions, this implementation uses continuation passing
+style. This has different performance characteristics from `ExceptT ε`.
+-/
 def ExceptCpsT (ε : Type u) (m : Type u → Type v) (α : Type u) := (β : Type u) → (α → m β) → (ε → m β) → m β
 
 namespace ExceptCpsT
 
+/--
+Use a monadic action that may throw an exception as an action that may return an exception's value.
+-/
 @[always_inline, inline]
 def run {ε α : Type u} [Monad m] (x : ExceptCpsT ε m α) : m (Except ε α) :=
   x _ (fun a => pure (Except.ok a)) (fun e => pure (Except.error e))
 
 set_option linter.unusedVariables false in  -- `s` unused
+/--
+Use a monadic action that may throw an exception by providing explicit success and failure
+continuations.
+-/
 @[always_inline, inline]
 def runK {ε α : Type u} (x : ExceptCpsT ε m α) (s : ε) (ok : α → m β) (error : ε → m β) : m β :=
   x _ ok error
 
+/--
+Returns the value of a computation, forgetting whether it was an exception or a success.
+
+This corresponds to early return.
+-/
 @[always_inline, inline]
 def runCatch [Monad m] (x : ExceptCpsT α m α) : m α :=
   x α pure pure
@@ -40,6 +58,9 @@ instance : MonadExceptOf ε (ExceptCpsT ε m) where
   throw e  := fun _ _ k => k e
   tryCatch x handle := fun _ k₁ k₂ => x _ k₁ (fun e => handle e _ k₁ k₂)
 
+/--
+Run an action from the transformed monad in the exception monad.
+-/
 @[always_inline, inline]
 def lift [Monad m] (x : m α) : ExceptCpsT ε m α :=
   fun _ k _ => x >>= k

src/Init/Control/Id.lean

@@ -10,6 +10,28 @@ import Init.Core
 
 universe u
 
+/--
+The identity function on types, used primarily for its `Monad` instance.
+
+The identity monad is useful together with monad transformers to construct monads for particular
+purposes. Additionally, it can be used with `do`-notation in order to use control structures such as
+local mutability, `for`-loops, and early returns in code that does not otherwise use monads.
+
+Examples:
+```lean example
+def containsFive (xs : List Nat) : Bool := Id.run do
+  for x in xs do
+    if x == 5 then return true
+  return false
+```
+
+```lean example
+#eval containsFive [1, 3, 5, 7]
+```
+```output
+true
+```
+-/
 def Id (type : Type u) : Type u := type
 
 namespace Id
@@ -20,9 +42,18 @@ instance : Monad Id where
   bind x f := f x
   map f x := f x
 
+/--
+The identity monad has a `bind` operator.
+-/
 def hasBind : Bind Id :=
   inferInstance
 
+/--
+Runs a computation in the identity monad.
+
+This function is the identity function. Because its parameter has type `Id α`, it causes
+`do`-notation in its arguments to use the `Monad Id` instance.
+-/
 @[always_inline, inline]
 protected def run (x : Id α) : α := x
 

src/Init/Control/Lawful/Basic.lean

@@ -13,17 +13,26 @@ open Function
   rfl
 
 /--
-The `Functor` typeclass only contains the operations of a functor.
-`LawfulFunctor` further asserts that these operations satisfy the laws of a functor,
-including the preservation of the identity and composition laws:
-```
-id <$> x = x
-(h ∘ g) <$> x = h <$> g <$> x
-```
+A functor satisfies the functor laws.
+
+The `Functor` class contains the operations of a functor, but does not require that instances
+prove they satisfy the laws of a functor. A `LawfulFunctor` instance includes proofs that the laws
+are satisfied. Because `Functor` instances may provide optimized implementations of `mapConst`,
+`LawfulFunctor` instances must also prove that the optimized implementation is equivalent to the
+standard implementation.
 -/
 class LawfulFunctor (f : Type u → Type v) [Functor f] : Prop where
+  /--
+  The `mapConst` implementation is equivalent to the default implementation.
+  -/
   map_const          : (Functor.mapConst : α → f β → f α) = Functor.map ∘ const β
+  /--
+  The `map` implementation preserves identity.
+  -/
   id_map   (x : f α) : id <$> x = x
+  /--
+  The `map` implementation preserves function composition.
+  -/
   comp_map (g : α → β) (h : β → γ) (x : f α) : (h ∘ g) <$> x = h <$> g <$> x
 
 export LawfulFunctor (map_const id_map comp_map)
@@ -38,21 +47,48 @@ attribute [simp] id_map
   (comp_map _ _ _).symm
 
 /--
-The `Applicative` typeclass only contains the operations of an applicative functor.
-`LawfulApplicative` further asserts that these operations satisfy the laws of an applicative functor:
-```
-pure id <*> v = v
-pure (·∘·) <*> u <*> v <*> w = u <*> (v <*> w)
-pure f <*> pure x = pure (f x)
-u <*> pure y = pure (· y) <*> u
-```
+An applicative functor satisfies the laws of an applicative functor.
+
+The `Applicative` class contains the operations of an applicative functor, but does not require that
+instances prove they satisfy the laws of an applicative functor. A `LawfulApplicative` instance
+includes proofs that the laws are satisfied.
+
+Because `Applicative` instances may provide optimized implementations of `seqLeft` and `seqRight`,
+`LawfulApplicative` instances must also prove that the optimized implementation is equivalent to the
+standard implementation.
 -/
-class LawfulApplicative (f : Type u → Type v) [Applicative f] extends LawfulFunctor f : Prop where
+class LawfulApplicative (f : Type u → Type v) [Applicative f] : Prop extends LawfulFunctor f where
+  /-- `seqLeft` is equivalent to the default implementation. -/
   seqLeft_eq  (x : f α) (y : f β)     : x <* y = const β <$> x <*> y
+  /-- `seqRight` is equivalent to the default implementation. -/
   seqRight_eq (x : f α) (y : f β)     : x *> y = const α id <$> x <*> y
+  /--
+  `pure` before `seq` is equivalent to `Functor.map`.
+
+  This means that `pure` really is pure when occurring immediately prior to `seq`.
+   -/
   pure_seq    (g : α → β) (x : f α)   : pure g <*> x = g <$> x
+
+  /--
+  Mapping a function over the result of `pure` is equivalent to applying the function under `pure`.
+
+  This means that `pure` really is pure with respect to `Functor.map`.
+  -/
   map_pure    (g : α → β) (x : α)     : g <$> (pure x : f α) = pure (g x)
+
+  /--
+  `pure` after `seq` is equivalent to `Functor.map`.
+
+  This means that `pure` really is pure when occurring just after `seq`.
+  -/
   seq_pure    {α β : Type u} (g : f (α → β)) (x : α) : g <*> pure x = (fun h => h x) <$> g
+
+  /--
+  `seq` is associative.
+
+  Changing the nesting of `seq` calls while maintaining the order of computations results in an
+  equivalent computation. This means that `seq` is not doing any more than sequencing.
+  -/
   seq_assoc   {α β γ : Type u} (x : f α) (g : f (α → β)) (h : f (β → γ)) : h <*> (g <*> x) = ((@comp α β γ) <$> h) <*> g <*> x
   comp_map g h x := (by
     repeat rw [← pure_seq]
@@ -66,21 +102,36 @@ attribute [simp] map_pure seq_pure
   simp [pure_seq]
 
 /--
-The `Monad` typeclass only contains the operations of a monad.
-`LawfulMonad` further asserts that these operations satisfy the laws of a monad,
-including associativity and identity laws for `bind`:
-```
-pure x >>= f = f x
-x >>= pure = x
-x >>= f >>= g = x >>= (fun x => f x >>= g)
-```
+Lawful monads are those that satisfy a certain behavioral specification. While all instances of
+`Monad` should satisfy these laws, not all implementations are required to prove this.
 
-`LawfulMonad.mk'` is an alternative constructor containing useful defaults for many fields.
+`LawfulMonad.mk'` is an alternative constructor that contains useful defaults for many fields.
 -/
-class LawfulMonad (m : Type u → Type v) [Monad m] extends LawfulApplicative m : Prop where
+class LawfulMonad (m : Type u → Type v) [Monad m] : Prop extends LawfulApplicative m where
+  /--
+  A `bind` followed by `pure` composed with a function is equivalent to a functorial map.
+
+  This means that `pure` really is pure after a `bind` and has no effects.
+  -/
   bind_pure_comp (f : α → β) (x : m α) : x >>= (fun a => pure (f a)) = f <$> x
+  /--
+  A `bind` followed by a functorial map is equivalent to `Applicative` sequencing.
+
+  This means that the effect sequencing from `Monad` and `Applicative` are the same.
+  -/
   bind_map       {α β : Type u} (f : m (α → β)) (x : m α) : f >>= (. <$> x) = f <*> x
+  /--
+  `pure` followed by `bind` is equivalent to function application.
+
+  This means that `pure` really is pure before a `bind` and has no effects.
+  -/
   pure_bind      (x : α) (f : α → m β) : pure x >>= f = f x
+  /--
+  `bind` is associative.
+
+  Changing the nesting of `bind` calls while maintaining the order of computations results in an
+  equivalent computation. This means that `bind` is not doing more than data-dependent sequencing.
+  -/
   bind_assoc     (x : m α) (f : α → m β) (g : β → m γ) : x >>= f >>= g = x >>= fun x => f x >>= g
   map_pure g x    := (by rw [← bind_pure_comp, pure_bind])
   seq_pure g x    := (by rw [← bind_map]; simp [map_pure, bind_pure_comp])

src/Init/Control/Option.lean

@@ -8,13 +8,22 @@ import Init.Data.Option.Basic
 import Init.Control.Basic
 import Init.Control.Except
 
+set_option linter.missingDocs true
+
 universe u v
 
 instance : ToBool (Option α) := ⟨Option.isSome⟩
 
+/--
+Adds the ability to fail to a monad. Unlike ordinary exceptions, there is no way to signal why a
+failure occurred.
+-/
 def OptionT (m : Type u → Type v) (α : Type u) : Type v :=
   m (Option α)
 
+/--
+Executes an action that might fail in the underlying monad `m`, returning `none` in case of failure.
+-/
 @[always_inline, inline]
 def OptionT.run {m : Type u → Type v} {α : Type u} (x : OptionT m α) : m (Option α) :=
   x
@@ -22,15 +31,25 @@ def OptionT.run {m : Type u → Type v} {α : Type u} (x : OptionT m α) : m (Op
 namespace OptionT
 variable {m : Type u → Type v} [Monad m] {α β : Type u}
 
+/--
+Converts an action that returns an `Option` into one that might fail, with `none` indicating
+failure.
+-/
 protected def mk (x : m (Option α)) : OptionT m α :=
   x
 
+/--
+Sequences two potentially-failing actions. The second action is run only if the first succeeds.
+-/
 @[always_inline, inline]
 protected def bind (x : OptionT m α) (f : α → OptionT m β) : OptionT m β := OptionT.mk do
   match (← x) with
   | some a => f a
   | none   => pure none
 
+/--
+Succeeds with the provided value.
+-/
 @[always_inline, inline]
 protected def pure (a : α) : OptionT m α := OptionT.mk do
   pure (some a)
@@ -40,11 +59,17 @@ instance : Monad (OptionT m) where
   pure := OptionT.pure
   bind := OptionT.bind
 
+/--
+Recovers from failures. Typically used via the `<|>` operator.
+-/
 @[always_inline, inline] protected def orElse (x : OptionT m α) (y : Unit → OptionT m α) : OptionT m α := OptionT.mk do
   match (← x) with
   | some a => pure (some a)
   | _      => y ()
 
+/--
+A recoverable failure.
+-/
 @[always_inline, inline] protected def fail : OptionT m α := OptionT.mk do
   pure none
 
@@ -52,6 +77,12 @@ instance : Alternative (OptionT m) where
   failure := OptionT.fail
   orElse  := OptionT.orElse
 
+/--
+Converts a computation from the underlying monad into one that could fail, even though it does not.
+
+This function is typically implicitly accessed via a `MonadLiftT` instance as part of [automatic
+lifting](lean-manual://section/monad-lifting).
+-/
 @[always_inline, inline] protected def lift (x : m α) : OptionT m α := OptionT.mk do
   return some (← x)
 
@@ -59,6 +90,9 @@ instance : MonadLift m (OptionT m) := ⟨OptionT.lift⟩
 
 instance : MonadFunctor m (OptionT m) := ⟨fun f x => f x⟩
 
+/--
+Handles failures by treating them as exceptions of type `Unit`.
+-/
 @[always_inline, inline] protected def tryCatch (x : OptionT m α) (handle : Unit → OptionT m α) : OptionT m α := OptionT.mk do
   let some a ← x | handle ()
   pure a

src/Init/Control/Reader.lean

@@ -10,12 +10,21 @@ import Init.Control.Basic
 import Init.Control.Id
 import Init.Control.Except
 
+set_option linter.missingDocs true
+
 namespace ReaderT
 
+/--
+Recovers from errors. The same local value is provided to both branches. Typically used via the
+`<|>` operator.
+-/
 @[always_inline, inline]
 protected def orElse [Alternative m] (x₁ : ReaderT ρ m α) (x₂ : Unit → ReaderT ρ m α) : ReaderT ρ m α :=
   fun s => x₁ s <|> x₂ () s
 
+/--
+Fails with a recoverable error.
+-/
 @[always_inline, inline]
 protected def failure [Alternative m] : ReaderT ρ m α :=
   fun _ => failure
@@ -35,4 +44,8 @@ instance : MonadControl m (ReaderT ρ m) where
 instance ReaderT.tryFinally [MonadFinally m] : MonadFinally (ReaderT ρ m) where
   tryFinally' x h ctx := tryFinally' (x ctx) (fun a? => h a? ctx)
 
+/--
+A monad with access to a read-only value of type `ρ`. The value can be locally overridden by
+`withReader`, but it cannot be mutated.
+-/
 @[reducible] def ReaderM (ρ : Type u) := ReaderT ρ Id

src/Init/Control/State.lean

@@ -9,19 +9,42 @@ prelude
 import Init.Control.Basic
 import Init.Control.Id
 import Init.Control.Except
+
+set_option linter.missingDocs true
+
 universe u v w
 
+/--
+Adds a mutable state of type `σ` to a monad.
+
+Actions in the resulting monad are functions that take an initial state and return, in `m`, a tuple
+of a value and a state.
+-/
 def StateT (σ : Type u) (m : Type u → Type v) (α : Type u) : Type (max u v) :=
   σ → m (α × σ)
 
+/--
+Executes an action from a monad with added state in the underlying monad `m`. Given an initial
+state, it returns a value paired with the final state.
+-/
 @[always_inline, inline]
 def StateT.run {σ : Type u} {m : Type u → Type v} {α : Type u} (x : StateT σ m α) (s : σ) : m (α × σ) :=
   x s
 
+/--
+Executes an action from a monad with added state in the underlying monad `m`. Given an initial
+state, it returns a value, discarding the final state.
+-/
 @[always_inline, inline]
 def StateT.run' {σ : Type u} {m : Type u → Type v} [Functor m] {α : Type u} (x : StateT σ m α) (s : σ) : m α :=
   (·.1) <$> x s
 
+/--
+A tuple-based state monad.
+
+Actions in `StateM σ` are functions that take an initial state and return a value paired with a
+final state.
+-/
 @[reducible]
 def StateM (σ α : Type u) : Type u := StateT σ Id α
 
@@ -38,14 +61,23 @@ section
 variable {σ : Type u} {m : Type u → Type v}
 variable [Monad m] {α β : Type u}
 
+/--
+Returns the given value without modifying the state. Typically used via `Pure.pure`.
+-/
 @[always_inline, inline]
 protected def pure (a : α) : StateT σ m α :=
   fun s => pure (a, s)
 
+/--
+Sequences two actions. Typically used via the `>>=` operator.
+-/
 @[always_inline, inline]
 protected def bind (x : StateT σ m α) (f : α → StateT σ m β) : StateT σ m β :=
   fun s => do let (a, s) ← x s; f a s
 
+/--
+Modifies the value returned by a computation. Typically used via the `<$>` operator.
+-/
 @[always_inline, inline]
 protected def map (f : α → β) (x : StateT σ m α) : StateT σ m β :=
   fun s => do let (a, s) ← x s; pure (f a, s)
@@ -56,10 +88,17 @@ instance : Monad (StateT σ m) where
   bind := StateT.bind
   map  := StateT.map
 
+/--
+Recovers from errors. The state is rolled back on error recovery. Typically used via the `<|>`
+operator.
+-/
 @[always_inline, inline]
 protected def orElse [Alternative m] {α : Type u} (x₁ : StateT σ m α) (x₂ : Unit → StateT σ m α) : StateT σ m α :=
   fun s => x₁ s <|> x₂ () s
 
+/--
+Fails with a recoverable error. The state is rolled back on error recovery.
+-/
 @[always_inline, inline]
 protected def failure [Alternative m] {α : Type u} : StateT σ m α :=
   fun _ => failure
@@ -68,18 +107,40 @@ instance [Alternative m] : Alternative (StateT σ m) where
   failure := StateT.failure
   orElse  := StateT.orElse
 
+/--
+Retrieves the current value of the monad's mutable state.
+
+This increments the reference count of the state, which may inhibit in-place updates.
+-/
 @[always_inline, inline]
 protected def get : StateT σ m σ :=
   fun s => pure (s, s)
 
+/--
+Replaces the mutable state with a new value.
+-/
 @[always_inline, inline]
 protected def set : σ → StateT σ m PUnit :=
   fun s' _ => pure (⟨⟩, s')
 
+/--
+Applies a function to the current state that both computes a new state and a value. The new state
+replaces the current state, and the value is returned.
+
+It is equivalent to `do let (a, s) := f (← StateT.get); StateT.set s; pure a`. However, using
+`StateT.modifyGet` may lead to better performance because it doesn't add a new reference to the
+state value, and additional references can inhibit in-place updates of data.
+-/
 @[always_inline, inline]
 protected def modifyGet (f : σ → α × σ) : StateT σ m α :=
   fun s => pure (f s)
 
+/--
+Runs an action from the underlying monad in the monad with state. The state is not modified.
+
+This function is typically implicitly accessed via a `MonadLiftT` instance as part of [automatic
+lifting](lean-manual://section/monad-lifting).
+-/
 @[always_inline, inline]
 protected def lift {α : Type u} (t : m α) : StateT σ m α :=
   fun s => do let a ← t; pure (a, s)

src/Init/Control/StateCps.lean

@@ -6,24 +6,45 @@ Authors: Leonardo de Moura
 prelude
 import Init.Control.Lawful.Basic
 
+set_option linter.missingDocs true
+
 /-!
 The State monad transformer using CPS style.
 -/
 
+/--
+An alternative implementation of a state monad transformer that internally uses continuation passing
+style instead of tuples.
+-/
 def StateCpsT (σ : Type u) (m : Type u → Type v) (α : Type u) := (δ : Type u) → σ → (α → σ → m δ) → m δ
 
 namespace StateCpsT
 
 variable {α σ : Type u} {m : Type u → Type v}
 
+/--
+Runs a stateful computation that's represented using continuation passing style by providing it with
+an initial state and a continuation.
+-/
 @[always_inline, inline]
 def runK (x : StateCpsT σ m α) (s : σ) (k : α → σ → m β) : m β :=
   x _ s k
 
+/--
+Executes an action from a monad with added state in the underlying monad `m`. Given an initial
+state, it returns a value paired with the final state.
+
+While the state is internally represented in continuation passing style, the resulting value is the
+same as for a non-CPS state monad.
+-/
 @[always_inline, inline]
 def run [Monad m] (x : StateCpsT σ m α) (s : σ) : m (α × σ) :=
   runK x s (fun a s => pure (a, s))
 
+/--
+Executes an action from a monad with added state in the underlying monad `m`. Given an initial
+state, it returns a value, discarding the final state.
+-/
 @[always_inline, inline]
 def run' [Monad m] (x : StateCpsT σ m α) (s : σ) : m α :=
   runK x s (fun a _ => pure a)
@@ -43,6 +64,12 @@ instance : MonadStateOf σ (StateCpsT σ m) where
   set s := fun _ _ k => k ⟨⟩ s
   modifyGet f := fun _ s k => let (a, s) := f s; k a s
 
+/--
+Runs an action from the underlying monad in the monad with state. The state is not modified.
+
+This function is typically implicitly accessed via a `MonadLiftT` instance as part of [automatic
+lifting](lean-manual://section/monad-lifting).
+-/
 @[always_inline, inline]
 protected def lift [Monad m] (x : m α) : StateCpsT σ m α :=
   fun _ s k => x >>= (k . s)

src/Init/Control/StateRef.lean

@@ -8,10 +8,23 @@ The State monad transformer using IO references.
 prelude
 import Init.System.ST
 
+set_option linter.missingDocs true
+
+/--
+A state monad that uses an actual mutable reference cell (i.e. an `ST.Ref ω σ`).
+
+The macro `StateRefT σ m α` infers `ω` from `m`. It should normally be used instead.
+-/
 def StateRefT' (ω : Type) (σ : Type) (m : Type → Type) (α : Type) : Type := ReaderT (ST.Ref ω σ) m α
 
 /-! Recall that `StateRefT` is a macro that infers `ω` from the `m`. -/
 
+/--
+Executes an action from a monad with added state in the underlying monad `m`. Given an initial
+state, it returns a value paired with the final state.
+
+The monad `m` must support `ST` effects in order to create and mutate reference cells.
+-/
 @[always_inline, inline]
 def StateRefT'.run {ω σ : Type} {m : Type → Type} [Monad m] [MonadLiftT (ST ω) m] {α : Type} (x : StateRefT' ω σ m α) (s : σ) : m (α × σ) := do
   let ref ← ST.mkRef s
@@ -19,6 +32,12 @@ def StateRefT'.run {ω σ : Type} {m : Type → Type} [Monad m] [MonadLiftT (ST
   let s ← ref.get
   pure (a, s)
 
+/--
+Executes an action from a monad with added state in the underlying monad `m`. Given an initial
+state, it returns a value, discarding the final state.
+
+The monad `m` must support `ST` effects in order to create and mutate reference cells.
+-/
 @[always_inline, inline]
 def StateRefT'.run' {ω σ : Type} {m : Type → Type} [Monad m] [MonadLiftT (ST ω) m] {α : Type} (x : StateRefT' ω σ m α) (s : σ) : m α := do
   let (a, _) ← x.run s
@@ -27,6 +46,12 @@ def StateRefT'.run' {ω σ : Type} {m : Type → Type} [Monad m] [MonadLiftT (ST
 namespace StateRefT'
 variable {ω σ : Type} {m : Type → Type} {α : Type}
 
+/--
+Runs an action from the underlying monad in the monad with state. The state is not modified.
+
+This function is typically implicitly accessed via a `MonadLiftT` instance as part of [automatic
+lifting](lean-manual://section/monad-lifting).
+-/
 @[always_inline, inline]
 protected def lift (x : m α) : StateRefT' ω σ m α :=
   fun _ => x
@@ -36,14 +61,30 @@ instance : MonadLift m (StateRefT' ω σ m) := ⟨StateRefT'.lift⟩
 instance (σ m) : MonadFunctor m (StateRefT' ω σ m) := inferInstanceAs (MonadFunctor m (ReaderT _ _))
 instance [Alternative m] [Monad m] : Alternative (StateRefT' ω σ m) := inferInstanceAs (Alternative (ReaderT _ _))
 
+/--
+Retrieves the current value of the monad's mutable state.
+
+This increments the reference count of the state, which may inhibit in-place updates.
+-/
 @[inline]
 protected def get [MonadLiftT (ST ω) m] : StateRefT' ω σ m σ :=
   fun ref => ref.get
 
+/--
+Replaces the mutable state with a new value.
+-/
 @[inline]
 protected def set [MonadLiftT (ST ω) m] (s : σ) : StateRefT' ω σ m PUnit :=
   fun ref => ref.set s
 
+/--
+Applies a function to the current state that both computes a new state and a value. The new state
+replaces the current state, and the value is returned.
+
+It is equivalent to a `get` followed by a `set`. However, using `modifyGet` may lead to higher
+performance because it doesn't add a new reference to the state value. Additional references can
+inhibit in-place updates of data.
+-/
 @[inline]
 protected def modifyGet [MonadLiftT (ST ω) m] (f : σ → α × σ) : StateRefT' ω σ m α :=
   fun ref => ref.modifyGet f

src/Init/Data/Array/Attach.lean

@@ -9,18 +9,20 @@ import Init.Data.Array.Lemmas
 import Init.Data.Array.Count
 import Init.Data.List.Attach
 
+set_option linter.listVariables true -- Enforce naming conventions for `List`/`Array`/`Vector` variables.
+set_option linter.indexVariables true -- Enforce naming conventions for index variables.
+
 namespace Array
 
 /--
-`O(n)`. Partial map. If `f : Π a, P a → β` is a partial function defined on
-`a : α` satisfying `P`, then `pmap f l h` is essentially the same as `map f l`
-but is defined only when all members of `l` satisfy `P`, using the proof
-to apply `f`.
+Maps a partially defined function (defined on those terms of `α` that satisfy a predicate `P`) over
+an array `xs : Array α`, given a proof that every element of `xs` in fact satisfies `P`.
 
-We replace this at runtime with a more efficient version via the `csimp` lemma `pmap_eq_pmapImpl`.
+`Array.pmap`, named for “partial map,” is the equivalent of `Array.map` for such partial functions.
 -/
-def pmap {P : α → Prop} (f : ∀ a, P a → β) (l : Array α) (H : ∀ a ∈ l, P a) : Array β :=
-  (l.toList.pmap f (fun a m => H a (mem_def.mpr m))).toArray
+
+def pmap {P : α → Prop} (f : ∀ a, P a → β) (xs : Array α) (H : ∀ a ∈ xs, P a) : Array β :=
+  (xs.toList.pmap f (fun a m => H a (mem_def.mpr m))).toArray
 
 /--
 Unsafe implementation of `attachWith`, taking advantage of the fact that the representation of
@@ -29,14 +31,27 @@ Unsafe implementation of `attachWith`, taking advantage of the fact that the rep
 @[inline] private unsafe def attachWithImpl
     (xs : Array α) (P : α → Prop) (_ : ∀ x ∈ xs, P x) : Array {x // P x} := unsafeCast xs
 
-/-- `O(1)`. "Attach" a proof `P x` that holds for all the elements of `xs` to produce a new array
-  with the same elements but in the type `{x // P x}`. -/
+/--
+“Attaches” individual proofs to an array of values that satisfy a predicate `P`, returning an array
+of elements in the corresponding subtype `{ x // P x }`.
+
+`O(1)`.
+-/
 @[implemented_by attachWithImpl] def attachWith
     (xs : Array α) (P : α → Prop) (H : ∀ x ∈ xs, P x) : Array {x // P x} :=
   ⟨xs.toList.attachWith P fun x h => H x (Array.Mem.mk h)⟩
 
-/-- `O(1)`. "Attach" the proof that the elements of `xs` are in `xs` to produce a new array
-  with the same elements but in the type `{x // x ∈ xs}`. -/
+/--
+“Attaches” the proof that the elements of `xs` are in fact elements of `xs`, producing a new array with
+the same elements but in the subtype `{ x // x ∈ xs }`.
+
+`O(1)`.
+
+This function is primarily used to allow definitions by [well-founded
+recursion](lean-manual://section/well-founded-recursion) that use higher-order functions (such as
+`Array.map`) to prove that an value taken from a list is smaller than the list. This allows the
+well-founded recursion mechanism to prove that the function terminates.
+-/
 @[inline] def attach (xs : Array α) : Array {x // x ∈ xs} := xs.attachWith _ fun _ => id
 
 @[simp] theorem _root_.List.attachWith_toArray {l : List α} {P : α → Prop} {H : ∀ x ∈ l.toArray, P x} :
@@ -51,25 +66,25 @@ Unsafe implementation of `attachWith`, taking advantage of the fact that the rep
     l.toArray.pmap f H = (l.pmap f (by simpa using H)).toArray := by
   simp [pmap]
 
-@[simp] theorem toList_attachWith {l : Array α} {P : α → Prop} {H : ∀ x ∈ l, P x} :
-   (l.attachWith P H).toList = l.toList.attachWith P (by simpa [mem_toList] using H) := by
+@[simp] theorem toList_attachWith {xs : Array α} {P : α → Prop} {H : ∀ x ∈ xs, P x} :
+   (xs.attachWith P H).toList = xs.toList.attachWith P (by simpa [mem_toList] using H) := by
   simp [attachWith]
 
-@[simp] theorem toList_attach {α : Type _} {l : Array α} :
-    l.attach.toList = l.toList.attachWith (· ∈ l) (by simp [mem_toList]) := by
+@[simp] theorem toList_attach {xs : Array α} :
+    xs.attach.toList = xs.toList.attachWith (· ∈ xs) (by simp [mem_toList]) := by
   simp [attach]
 
-@[simp] theorem toList_pmap {l : Array α} {P : α → Prop} {f : ∀ a, P a → β} {H : ∀ a ∈ l, P a} :
-    (l.pmap f H).toList = l.toList.pmap f (fun a m => H a (mem_def.mpr m)) := by
+@[simp] theorem toList_pmap {xs : Array α} {P : α → Prop} {f : ∀ a, P a → β} {H : ∀ a ∈ xs, P a} :
+    (xs.pmap f H).toList = xs.toList.pmap f (fun a m => H a (mem_def.mpr m)) := by
   simp [pmap]
 
 /-- Implementation of `pmap` using the zero-copy version of `attach`. -/
-@[inline] private def pmapImpl {P : α → Prop} (f : ∀ a, P a → β) (l : Array α) (H : ∀ a ∈ l, P a) :
-    Array β := (l.attachWith _ H).map fun ⟨x, h'⟩ => f x h'
+@[inline] private def pmapImpl {P : α → Prop} (f : ∀ a, P a → β) (xs : Array α) (H : ∀ a ∈ xs, P a) :
+    Array β := (xs.attachWith _ H).map fun ⟨x, h'⟩ => f x h'
 
 @[csimp] private theorem pmap_eq_pmapImpl : @pmap = @pmapImpl := by
-  funext α β p f L h'
-  cases L
+  funext α β p f xs H
+  cases xs
   simp only [pmap, pmapImpl, List.attachWith_toArray, List.map_toArray, mk.injEq, List.map_attachWith_eq_pmap]
   apply List.pmap_congr_left
   intro a m h₁ h₂
@@ -77,9 +92,9 @@ Unsafe implementation of `attachWith`, taking advantage of the fact that the rep
 
 @[simp] theorem pmap_empty {P : α → Prop} (f : ∀ a, P a → β) : pmap f #[] (by simp) = #[] := rfl
 
-@[simp] theorem pmap_push {P : α → Prop} (f : ∀ a, P a → β) (a : α) (l : Array α) (h : ∀ b ∈ l.push a, P b) :
-    pmap f (l.push a) h =
-      (pmap f l (fun a m => by simp at h; exact h a (.inl m))).push (f a (h a (by simp))) := by
+@[simp] theorem pmap_push {P : α → Prop} (f : ∀ a, P a → β) (a : α) (xs : Array α) (h : ∀ b ∈ xs.push a, P b) :
+    pmap f (xs.push a) h =
+      (pmap f xs (fun a m => by simp at h; exact h a (.inl m))).push (f a (h a (by simp))) := by
   simp [pmap]
 
 @[simp] theorem attach_empty : (#[] : Array α).attach = #[] := rfl
@@ -94,158 +109,158 @@ Unsafe implementation of `attachWith`, taking advantage of the fact that the rep
   simp
 
 @[simp]
-theorem pmap_eq_map (p : α → Prop) (f : α → β) (l : Array α) (H) :
-    @pmap _ _ p (fun a _ => f a) l H = map f l := by
-  cases l; simp
+theorem pmap_eq_map (p : α → Prop) (f : α → β) (xs : Array α) (H) :
+    @pmap _ _ p (fun a _ => f a) xs H = map f xs := by
+  cases xs; simp
 
-theorem pmap_congr_left {p q : α → Prop} {f : ∀ a, p a → β} {g : ∀ a, q a → β} (l : Array α) {H₁ H₂}
-    (h : ∀ a ∈ l, ∀ (h₁ h₂), f a h₁ = g a h₂) : pmap f l H₁ = pmap g l H₂ := by
-  cases l
+theorem pmap_congr_left {p q : α → Prop} {f : ∀ a, p a → β} {g : ∀ a, q a → β} (xs : Array α) {H₁ H₂}
+    (h : ∀ a ∈ xs, ∀ (h₁ h₂), f a h₁ = g a h₂) : pmap f xs H₁ = pmap g xs H₂ := by
+  cases xs
   simp only [mem_toArray] at h
   simp only [List.pmap_toArray, mk.injEq]
   rw [List.pmap_congr_left _ h]
 
-theorem map_pmap {p : α → Prop} (g : β → γ) (f : ∀ a, p a → β) (l H) :
-    map g (pmap f l H) = pmap (fun a h => g (f a h)) l H := by
-  cases l
+theorem map_pmap {p : α → Prop} (g : β → γ) (f : ∀ a, p a → β) (xs H) :
+    map g (pmap f xs H) = pmap (fun a h => g (f a h)) xs H := by
+  cases xs
   simp [List.map_pmap]
 
-theorem pmap_map {p : β → Prop} (g : ∀ b, p b → γ) (f : α → β) (l H) :
-    pmap g (map f l) H = pmap (fun a h => g (f a) h) l fun _ h => H _ (mem_map_of_mem _ h) := by
-  cases l
+theorem pmap_map {p : β → Prop} (g : ∀ b, p b → γ) (f : α → β) (xs H) :
+    pmap g (map f xs) H = pmap (fun a h => g (f a) h) xs fun _ h => H _ (mem_map_of_mem _ h) := by
+  cases xs
   simp [List.pmap_map]
 
-theorem attach_congr {l₁ l₂ : Array α} (h : l₁ = l₂) :
-    l₁.attach = l₂.attach.map (fun x => ⟨x.1, h ▸ x.2⟩) := by
+theorem attach_congr {xs ys : Array α} (h : xs = ys) :
+    xs.attach = ys.attach.map (fun x => ⟨x.1, h ▸ x.2⟩) := by
   subst h
   simp
 
-theorem attachWith_congr {l₁ l₂ : Array α} (w : l₁ = l₂) {P : α → Prop} {H : ∀ x ∈ l₁, P x} :
-    l₁.attachWith P H = l₂.attachWith P fun _ h => H _ (w ▸ h) := by
+theorem attachWith_congr {xs ys : Array α} (w : xs = ys) {P : α → Prop} {H : ∀ x ∈ xs, P x} :
+    xs.attachWith P H = ys.attachWith P fun _ h => H _ (w ▸ h) := by
   subst w
   simp
 
-@[simp] theorem attach_push {a : α} {l : Array α} :
-    (l.push a).attach =
-      (l.attach.map (fun ⟨x, h⟩ => ⟨x, mem_push_of_mem a h⟩)).push ⟨a, by simp⟩ := by
-  cases l
+@[simp] theorem attach_push {a : α} {xs : Array α} :
+    (xs.push a).attach =
+      (xs.attach.map (fun ⟨x, h⟩ => ⟨x, mem_push_of_mem a h⟩)).push ⟨a, by simp⟩ := by
+  cases xs
   rw [attach_congr (List.push_toArray _ _)]
   simp [Function.comp_def]
 
-@[simp] theorem attachWith_push {a : α} {l : Array α} {P : α → Prop} {H : ∀ x ∈ l.push a, P x} :
-    (l.push a).attachWith P H =
-      (l.attachWith P (fun x h => by simp at H; exact H x (.inl h))).push ⟨a, H a (by simp)⟩ := by
-  cases l
+@[simp] theorem attachWith_push {a : α} {xs : Array α} {P : α → Prop} {H : ∀ x ∈ xs.push a, P x} :
+    (xs.push a).attachWith P H =
+      (xs.attachWith P (fun x h => by simp at H; exact H x (.inl h))).push ⟨a, H a (by simp)⟩ := by
+  cases xs
   simp [attachWith_congr (List.push_toArray _ _)]
 
-theorem pmap_eq_map_attach {p : α → Prop} (f : ∀ a, p a → β) (l H) :
-    pmap f l H = l.attach.map fun x => f x.1 (H _ x.2) := by
-  cases l
+theorem pmap_eq_map_attach {p : α → Prop} (f : ∀ a, p a → β) (xs H) :
+    pmap f xs H = xs.attach.map fun x => f x.1 (H _ x.2) := by
+  cases xs
   simp [List.pmap_eq_map_attach]
 
 @[simp]
-theorem pmap_eq_attachWith {p q : α → Prop} (f : ∀ a, p a → q a) (l H) :
-    pmap (fun a h => ⟨a, f a h⟩) l H = l.attachWith q (fun x h => f x (H x h)) := by
-  cases l
+theorem pmap_eq_attachWith {p q : α → Prop} (f : ∀ a, p a → q a) (xs H) :
+    pmap (fun a h => ⟨a, f a h⟩) xs H = xs.attachWith q (fun x h => f x (H x h)) := by
+  cases xs
   simp [List.pmap_eq_attachWith]
 
-theorem attach_map_val (l : Array α) (f : α → β) :
-    (l.attach.map fun (i : {i // i ∈ l}) => f i) = l.map f := by
-  cases l
+theorem attach_map_val (xs : Array α) (f : α → β) :
+    (xs.attach.map fun (i : {i // i ∈ xs}) => f i) = xs.map f := by
+  cases xs
   simp
 
 @[deprecated attach_map_val (since := "2025-02-17")]
 abbrev attach_map_coe := @attach_map_val
 
-theorem attach_map_subtype_val (l : Array α) : l.attach.map Subtype.val = l := by
-  cases l; simp
+theorem attach_map_subtype_val (xs : Array α) : xs.attach.map Subtype.val = xs := by
+  cases xs; simp
 
-theorem attachWith_map_val {p : α → Prop} (f : α → β) (l : Array α) (H : ∀ a ∈ l, p a) :
-    ((l.attachWith p H).map fun (i : { i // p i}) => f i) = l.map f := by
-  cases l; simp
+theorem attachWith_map_val {p : α → Prop} (f : α → β) (xs : Array α) (H : ∀ a ∈ xs, p a) :
+    ((xs.attachWith p H).map fun (i : { i // p i}) => f i) = xs.map f := by
+  cases xs; simp
 
 @[deprecated attachWith_map_val (since := "2025-02-17")]
 abbrev attachWith_map_coe := @attachWith_map_val
 
-theorem attachWith_map_subtype_val {p : α → Prop} (l : Array α) (H : ∀ a ∈ l, p a) :
-    (l.attachWith p H).map Subtype.val = l := by
-  cases l; simp
+theorem attachWith_map_subtype_val {p : α → Prop} (xs : Array α) (H : ∀ a ∈ xs, p a) :
+    (xs.attachWith p H).map Subtype.val = xs := by
+  cases xs; simp
 
 @[simp]
-theorem mem_attach (l : Array α) : ∀ x, x ∈ l.attach
+theorem mem_attach (xs : Array α) : ∀ x, x ∈ xs.attach
   | ⟨a, h⟩ => by
     have := mem_map.1 (by rw [attach_map_subtype_val] <;> exact h)
     rcases this with ⟨⟨_, _⟩, m, rfl⟩
     exact m
 
 @[simp]
-theorem mem_attachWith (l : Array α) {q : α → Prop} (H) (x : {x // q x}) :
-    x ∈ l.attachWith q H ↔ x.1 ∈ l := by
-  cases l
+theorem mem_attachWith (xs : Array α) {q : α → Prop} (H) (x : {x // q x}) :
+    x ∈ xs.attachWith q H ↔ x.1 ∈ xs := by
+  cases xs
   simp
 
 @[simp]
-theorem mem_pmap {p : α → Prop} {f : ∀ a, p a → β} {l H b} :
-    b ∈ pmap f l H ↔ ∃ (a : _) (h : a ∈ l), f a (H a h) = b := by
+theorem mem_pmap {p : α → Prop} {f : ∀ a, p a → β} {xs H b} :
+    b ∈ pmap f xs H ↔ ∃ (a : _) (h : a ∈ xs), f a (H a h) = b := by
   simp only [pmap_eq_map_attach, mem_map, mem_attach, true_and, Subtype.exists, eq_comm]
 
-theorem mem_pmap_of_mem {p : α → Prop} {f : ∀ a, p a → β} {l H} {a} (h : a ∈ l) :
-    f a (H a h) ∈ pmap f l H := by
+theorem mem_pmap_of_mem {p : α → Prop} {f : ∀ a, p a → β} {xs H} {a} (h : a ∈ xs) :
+    f a (H a h) ∈ pmap f xs H := by
   rw [mem_pmap]
   exact ⟨a, h, rfl⟩
 
 @[simp]
-theorem size_pmap {p : α → Prop} {f : ∀ a, p a → β} {l H} : (pmap f l H).size = l.size := by
-  cases l; simp
+theorem size_pmap {p : α → Prop} {f : ∀ a, p a → β} {xs H} : (pmap f xs H).size = xs.size := by
+  cases xs; simp
 
 @[simp]
-theorem size_attach {L : Array α} : L.attach.size = L.size := by
-  cases L; simp
+theorem size_attach {xs : Array α} : xs.attach.size = xs.size := by
+  cases xs; simp
 
 @[simp]
-theorem size_attachWith {p : α → Prop} {l : Array α} {H} : (l.attachWith p H).size = l.size := by
-  cases l; simp
+theorem size_attachWith {p : α → Prop} {xs : Array α} {H} : (xs.attachWith p H).size = xs.size := by
+  cases xs; simp
 
 @[simp]
-theorem pmap_eq_empty_iff {p : α → Prop} {f : ∀ a, p a → β} {l H} : pmap f l H = #[] ↔ l = #[] := by
-  cases l; simp
+theorem pmap_eq_empty_iff {p : α → Prop} {f : ∀ a, p a → β} {xs H} : pmap f xs H = #[] ↔ xs = #[] := by
+  cases xs; simp
 
 theorem pmap_ne_empty_iff {P : α → Prop} (f : (a : α) → P a → β) {xs : Array α}
     (H : ∀ (a : α), a ∈ xs → P a) : xs.pmap f H ≠ #[] ↔ xs ≠ #[] := by
   cases xs; simp
 
-theorem pmap_eq_self {l : Array α} {p : α → Prop} {hp : ∀ (a : α), a ∈ l → p a}
-    {f : (a : α) → p a → α} : l.pmap f hp = l ↔ ∀ a (h : a ∈ l), f a (hp a h) = a := by
-  cases l; simp [List.pmap_eq_self]
+theorem pmap_eq_self {xs : Array α} {p : α → Prop} {hp : ∀ (a : α), a ∈ xs → p a}
+    {f : (a : α) → p a → α} : xs.pmap f hp = xs ↔ ∀ a (h : a ∈ xs), f a (hp a h) = a := by
+  cases xs; simp [List.pmap_eq_self]
 
 @[simp]
-theorem attach_eq_empty_iff {l : Array α} : l.attach = #[] ↔ l = #[] := by
-  cases l; simp
+theorem attach_eq_empty_iff {xs : Array α} : xs.attach = #[] ↔ xs = #[] := by
+  cases xs; simp
 
-theorem attach_ne_empty_iff {l : Array α} : l.attach ≠ #[] ↔ l ≠ #[] := by
-  cases l; simp
+theorem attach_ne_empty_iff {xs : Array α} : xs.attach ≠ #[] ↔ xs ≠ #[] := by
+  cases xs; simp
 
 @[simp]
-theorem attachWith_eq_empty_iff {l : Array α} {P : α → Prop} {H : ∀ a ∈ l, P a} :
-    l.attachWith P H = #[] ↔ l = #[] := by
-  cases l; simp
+theorem attachWith_eq_empty_iff {xs : Array α} {P : α → Prop} {H : ∀ a ∈ xs, P a} :
+    xs.attachWith P H = #[] ↔ xs = #[] := by
+  cases xs; simp
 
-theorem attachWith_ne_empty_iff {l : Array α} {P : α → Prop} {H : ∀ a ∈ l, P a} :
-    l.attachWith P H ≠ #[] ↔ l ≠ #[] := by
-  cases l; simp
+theorem attachWith_ne_empty_iff {xs : Array α} {P : α → Prop} {H : ∀ a ∈ xs, P a} :
+    xs.attachWith P H ≠ #[] ↔ xs ≠ #[] := by
+  cases xs; simp
 
 @[simp]
-theorem getElem?_pmap {p : α → Prop} (f : ∀ a, p a → β) {l : Array α} (h : ∀ a ∈ l, p a) (i : Nat) :
-    (pmap f l h)[i]? = Option.pmap f l[i]? fun x H => h x (mem_of_getElem? H) := by
-  cases l; simp
+theorem getElem?_pmap {p : α → Prop} (f : ∀ a, p a → β) {xs : Array α} (h : ∀ a ∈ xs, p a) (i : Nat) :
+    (pmap f xs h)[i]? = Option.pmap f xs[i]? fun x H => h x (mem_of_getElem? H) := by
+  cases xs; simp
 
 @[simp]
-theorem getElem_pmap {p : α → Prop} (f : ∀ a, p a → β) {l : Array α} (h : ∀ a ∈ l, p a) {i : Nat}
-    (hi : i < (pmap f l h).size) :
-    (pmap f l h)[i] =
-      f (l[i]'(@size_pmap _ _ p f l h ▸ hi))
-        (h _ (getElem_mem (@size_pmap _ _ p f l h ▸ hi))) := by
-  cases l; simp
+theorem getElem_pmap {p : α → Prop} (f : ∀ a, p a → β) {xs : Array α} (h : ∀ a ∈ xs, p a) {i : Nat}
+    (hi : i < (pmap f xs h).size) :
+    (pmap f xs h)[i] =
+      f (xs[i]'(@size_pmap _ _ p f xs h ▸ hi))
+        (h _ (getElem_mem (@size_pmap _ _ p f xs h ▸ hi))) := by
+  cases xs; simp
 
 @[simp]
 theorem getElem?_attachWith {xs : Array α} {i : Nat} {P : α → Prop} {H : ∀ a ∈ xs, P a} :
@@ -268,40 +283,40 @@ theorem getElem_attach {xs : Array α} {i : Nat} (h : i < xs.attach.size) :
     xs.attach[i] = ⟨xs[i]'(by simpa using h), getElem_mem (by simpa using h)⟩ :=
   getElem_attachWith h
 
-@[simp] theorem pmap_attach (l : Array α) {p : {x // x ∈ l} → Prop} (f : ∀ a, p a → β) (H) :
-    pmap f l.attach H =
-      l.pmap (P := fun a => ∃ h : a ∈ l, p ⟨a, h⟩)
+@[simp] theorem pmap_attach (xs : Array α) {p : {x // x ∈ xs} → Prop} (f : ∀ a, p a → β) (H) :
+    pmap f xs.attach H =
+      xs.pmap (P := fun a => ∃ h : a ∈ xs, p ⟨a, h⟩)
         (fun a h => f ⟨a, h.1⟩ h.2) (fun a h => ⟨h, H ⟨a, h⟩ (by simp)⟩) := by
   ext <;> simp
 
-@[simp] theorem pmap_attachWith (l : Array α) {p : {x // q x} → Prop} (f : ∀ a, p a → β) (H₁ H₂) :
-    pmap f (l.attachWith q H₁) H₂ =
-      l.pmap (P := fun a => ∃ h : q a, p ⟨a, h⟩)
+@[simp] theorem pmap_attachWith (xs : Array α) {p : {x // q x} → Prop} (f : ∀ a, p a → β) (H₁ H₂) :
+    pmap f (xs.attachWith q H₁) H₂ =
+      xs.pmap (P := fun a => ∃ h : q a, p ⟨a, h⟩)
         (fun a h => f ⟨a, h.1⟩ h.2) (fun a h => ⟨H₁ _ h, H₂ ⟨a, H₁ _ h⟩ (by simpa)⟩) := by
   ext <;> simp
 
-theorem foldl_pmap (l : Array α) {P : α → Prop} (f : (a : α) → P a → β)
-  (H : ∀ (a : α), a ∈ l → P a) (g : γ → β → γ) (x : γ) :
-    (l.pmap f H).foldl g x = l.attach.foldl (fun acc a => g acc (f a.1 (H _ a.2))) x := by
+theorem foldl_pmap (xs : Array α) {P : α → Prop} (f : (a : α) → P a → β)
+  (H : ∀ (a : α), a ∈ xs → P a) (g : γ → β → γ) (x : γ) :
+    (xs.pmap f H).foldl g x = xs.attach.foldl (fun acc a => g acc (f a.1 (H _ a.2))) x := by
   rw [pmap_eq_map_attach, foldl_map]
 
-theorem foldr_pmap (l : Array α) {P : α → Prop} (f : (a : α) → P a → β)
-  (H : ∀ (a : α), a ∈ l → P a) (g : β → γ → γ) (x : γ) :
-    (l.pmap f H).foldr g x = l.attach.foldr (fun a acc => g (f a.1 (H _ a.2)) acc) x := by
+theorem foldr_pmap (xs : Array α) {P : α → Prop} (f : (a : α) → P a → β)
+  (H : ∀ (a : α), a ∈ xs → P a) (g : β → γ → γ) (x : γ) :
+    (xs.pmap f H).foldr g x = xs.attach.foldr (fun a acc => g (f a.1 (H _ a.2)) acc) x := by
   rw [pmap_eq_map_attach, foldr_map]
 
 @[simp] theorem foldl_attachWith
-    (l : Array α) {q : α → Prop} (H : ∀ a, a ∈ l → q a) {f : β → { x // q x} → β} {b} (w : stop = l.size) :
-    (l.attachWith q H).foldl f b 0 stop = l.attach.foldl (fun b ⟨a, h⟩ => f b ⟨a, H _ h⟩) b := by
+    (xs : Array α) {q : α → Prop} (H : ∀ a, a ∈ xs → q a) {f : β → { x // q x} → β} {b} (w : stop = xs.size) :
+    (xs.attachWith q H).foldl f b 0 stop = xs.attach.foldl (fun b ⟨a, h⟩ => f b ⟨a, H _ h⟩) b := by
   subst w
-  rcases l with ⟨l⟩
+  rcases xs with ⟨xs⟩
   simp [List.foldl_attachWith, List.foldl_map]
 
 @[simp] theorem foldr_attachWith
-    (l : Array α) {q : α → Prop} (H : ∀ a, a ∈ l → q a) {f : { x // q x} → β → β} {b} (w : start = l.size) :
-    (l.attachWith q H).foldr f b start 0 = l.attach.foldr (fun a acc => f ⟨a.1, H _ a.2⟩ acc) b := by
+    (xs : Array α) {q : α → Prop} (H : ∀ a, a ∈ xs → q a) {f : { x // q x} → β → β} {b} (w : start = xs.size) :
+    (xs.attachWith q H).foldr f b start 0 = xs.attach.foldr (fun a acc => f ⟨a.1, H _ a.2⟩ acc) b := by
   subst w
-  rcases l with ⟨l⟩
+  rcases xs with ⟨xs⟩
   simp [List.foldr_attachWith, List.foldr_map]
 
 /--
@@ -314,9 +329,9 @@ Unfortunately this can't be applied by `simp` because of the higher order unific
 and even when rewriting we need to specify the function explicitly.
 See however `foldl_subtype` below.
 -/
-theorem foldl_attach (l : Array α) (f : β → α → β) (b : β) :
-    l.attach.foldl (fun acc t => f acc t.1) b = l.foldl f b := by
-  rcases l with ⟨l⟩
+theorem foldl_attach (xs : Array α) (f : β → α → β) (b : β) :
+    xs.attach.foldl (fun acc t => f acc t.1) b = xs.foldl f b := by
+  rcases xs with ⟨xs⟩
   simp only [List.attach_toArray, List.attachWith_mem_toArray, List.size_toArray,
     List.length_pmap, List.foldl_toArray', mem_toArray, List.foldl_subtype]
   congr
@@ -333,101 +348,101 @@ Unfortunately this can't be applied by `simp` because of the higher order unific
 and even when rewriting we need to specify the function explicitly.
 See however `foldr_subtype` below.
 -/
-theorem foldr_attach (l : Array α) (f : α → β → β) (b : β) :
-    l.attach.foldr (fun t acc => f t.1 acc) b = l.foldr f b := by
-  rcases l with ⟨l⟩
+theorem foldr_attach (xs : Array α) (f : α → β → β) (b : β) :
+    xs.attach.foldr (fun t acc => f t.1 acc) b = xs.foldr f b := by
+  rcases xs with ⟨xs⟩
   simp only [List.attach_toArray, List.attachWith_mem_toArray, List.size_toArray,
     List.length_pmap, List.foldr_toArray', mem_toArray, List.foldr_subtype]
   congr
   ext
   simpa using fun a => List.mem_of_getElem? a
 
-theorem attach_map {l : Array α} (f : α → β) :
-    (l.map f).attach = l.attach.map (fun ⟨x, h⟩ => ⟨f x, mem_map_of_mem f h⟩) := by
-  cases l
+theorem attach_map {xs : Array α} (f : α → β) :
+    (xs.map f).attach = xs.attach.map (fun ⟨x, h⟩ => ⟨f x, mem_map_of_mem f h⟩) := by
+  cases xs
   ext <;> simp
 
-theorem attachWith_map {l : Array α} (f : α → β) {P : β → Prop} {H : ∀ (b : β), b ∈ l.map f → P b} :
-    (l.map f).attachWith P H = (l.attachWith (P ∘ f) (fun _ h => H _ (mem_map_of_mem f h))).map
+theorem attachWith_map {xs : Array α} (f : α → β) {P : β → Prop} {H : ∀ (b : β), b ∈ xs.map f → P b} :
+    (xs.map f).attachWith P H = (xs.attachWith (P ∘ f) (fun _ h => H _ (mem_map_of_mem f h))).map
       fun ⟨x, h⟩ => ⟨f x, h⟩ := by
-  cases l
+  cases xs
   simp [List.attachWith_map]
 
-@[simp] theorem map_attachWith {l : Array α} {P : α → Prop} {H : ∀ (a : α), a ∈ l → P a}
+@[simp] theorem map_attachWith {xs : Array α} {P : α → Prop} {H : ∀ (a : α), a ∈ xs → P a}
     (f : { x // P x } → β) :
-    (l.attachWith P H).map f = l.attach.map fun ⟨x, h⟩ => f ⟨x, H _ h⟩ := by
-  cases l <;> simp_all
+    (xs.attachWith P H).map f = xs.attach.map fun ⟨x, h⟩ => f ⟨x, H _ h⟩ := by
+  cases xs <;> simp_all
 
-theorem map_attachWith_eq_pmap {l : Array α} {P : α → Prop} {H : ∀ (a : α), a ∈ l → P a}
+theorem map_attachWith_eq_pmap {xs : Array α} {P : α → Prop} {H : ∀ (a : α), a ∈ xs → P a}
     (f : { x // P x } → β) :
-    (l.attachWith P H).map f =
-      l.pmap (fun a (h : a ∈ l ∧ P a) => f ⟨a, H _ h.1⟩) (fun a h => ⟨h, H a h⟩) := by
-  cases l
+    (xs.attachWith P H).map f =
+      xs.pmap (fun a (h : a ∈ xs ∧ P a) => f ⟨a, H _ h.1⟩) (fun a h => ⟨h, H a h⟩) := by
+  cases xs
   ext <;> simp
 
 /-- See also `pmap_eq_map_attach` for writing `pmap` in terms of `map` and `attach`. -/
-theorem map_attach_eq_pmap {l : Array α} (f : { x // x ∈ l } → β) :
-    l.attach.map f = l.pmap (fun a h => f ⟨a, h⟩) (fun _ => id) := by
-  cases l
+theorem map_attach_eq_pmap {xs : Array α} (f : { x // x ∈ xs } → β) :
+    xs.attach.map f = xs.pmap (fun a h => f ⟨a, h⟩) (fun _ => id) := by
+  cases xs
   ext <;> simp
 
 @[deprecated map_attach_eq_pmap (since := "2025-02-09")]
 abbrev map_attach := @map_attach_eq_pmap
 
-theorem attach_filterMap {l : Array α} {f : α → Option β} :
-    (l.filterMap f).attach = l.attach.filterMap
+theorem attach_filterMap {xs : Array α} {f : α → Option β} :
+    (xs.filterMap f).attach = xs.attach.filterMap
       fun ⟨x, h⟩ => (f x).pbind (fun b m => some ⟨b, mem_filterMap.mpr ⟨x, h, m⟩⟩) := by
-  cases l
+  cases xs
   rw [attach_congr (List.filterMap_toArray f _)]
   simp [List.attach_filterMap, List.map_filterMap, Function.comp_def]
 
-theorem attach_filter {l : Array α} (p : α → Bool) :
-    (l.filter p).attach = l.attach.filterMap
+theorem attach_filter {xs : Array α} (p : α → Bool) :
+    (xs.filter p).attach = xs.attach.filterMap
       fun x => if w : p x.1 then some ⟨x.1, mem_filter.mpr ⟨x.2, w⟩⟩ else none := by
-  cases l
+  cases xs
   rw [attach_congr (List.filter_toArray p _)]
   simp [List.attach_filter, List.map_filterMap, Function.comp_def]
 
 -- We are still missing here `attachWith_filterMap` and `attachWith_filter`.
 
 @[simp]
-theorem filterMap_attachWith {q : α → Prop} {l : Array α} {f : {x // q x} → Option β} (H)
-    (w : stop = (l.attachWith q H).size) :
-    (l.attachWith q H).filterMap f 0 stop = l.attach.filterMap (fun ⟨x, h⟩ => f ⟨x, H _ h⟩) := by
+theorem filterMap_attachWith {q : α → Prop} {xs : Array α} {f : {x // q x} → Option β} (H)
+    (w : stop = (xs.attachWith q H).size) :
+    (xs.attachWith q H).filterMap f 0 stop = xs.attach.filterMap (fun ⟨x, h⟩ => f ⟨x, H _ h⟩) := by
   subst w
-  cases l
+  cases xs
   simp [Function.comp_def]
 
 @[simp]
-theorem filter_attachWith {q : α → Prop} {l : Array α} {p : {x // q x} → Bool} (H)
-    (w : stop = (l.attachWith q H).size) :
-    (l.attachWith q H).filter p 0 stop =
-      (l.attach.filter (fun ⟨x, h⟩ => p ⟨x, H _ h⟩)).map (fun ⟨x, h⟩ => ⟨x, H _ h⟩) := by
+theorem filter_attachWith {q : α → Prop} {xs : Array α} {p : {x // q x} → Bool} (H)
+    (w : stop = (xs.attachWith q H).size) :
+    (xs.attachWith q H).filter p 0 stop =
+      (xs.attach.filter (fun ⟨x, h⟩ => p ⟨x, H _ h⟩)).map (fun ⟨x, h⟩ => ⟨x, H _ h⟩) := by
   subst w
-  cases l
+  cases xs
   simp [Function.comp_def, List.filter_map]
 
-theorem pmap_pmap {p : α → Prop} {q : β → Prop} (g : ∀ a, p a → β) (f : ∀ b, q b → γ) (l H₁ H₂) :
-    pmap f (pmap g l H₁) H₂ =
-      pmap (α := { x // x ∈ l }) (fun a h => f (g a h) (H₂ (g a h) (mem_pmap_of_mem a.2))) l.attach
+theorem pmap_pmap {p : α → Prop} {q : β → Prop} (g : ∀ a, p a → β) (f : ∀ b, q b → γ) (xs H₁ H₂) :
+    pmap f (pmap g xs H₁) H₂ =
+      pmap (α := { x // x ∈ xs }) (fun a h => f (g a h) (H₂ (g a h) (mem_pmap_of_mem a.2))) xs.attach
         (fun a _ => H₁ a a.2) := by
-  cases l
+  cases xs
   simp [List.pmap_pmap, List.pmap_map]
 
-@[simp] theorem pmap_append {p : ι → Prop} (f : ∀ a : ι, p a → α) (l₁ l₂ : Array ι)
-    (h : ∀ a ∈ l₁ ++ l₂, p a) :
-    (l₁ ++ l₂).pmap f h =
-      (l₁.pmap f fun a ha => h a (mem_append_left l₂ ha)) ++
-        l₂.pmap f fun a ha => h a (mem_append_right l₁ ha) := by
-  cases l₁
-  cases l₂
+@[simp] theorem pmap_append {p : ι → Prop} (f : ∀ a : ι, p a → α) (xs ys : Array ι)
+    (h : ∀ a ∈ xs ++ ys, p a) :
+    (xs ++ ys).pmap f h =
+      (xs.pmap f fun a ha => h a (mem_append_left ys ha)) ++
+        ys.pmap f fun a ha => h a (mem_append_right xs ha) := by
+  cases xs
+  cases ys
   simp
 
-theorem pmap_append' {p : α → Prop} (f : ∀ a : α, p a → β) (l₁ l₂ : Array α)
-    (h₁ : ∀ a ∈ l₁, p a) (h₂ : ∀ a ∈ l₂, p a) :
-    ((l₁ ++ l₂).pmap f fun a ha => (mem_append.1 ha).elim (h₁ a) (h₂ a)) =
-      l₁.pmap f h₁ ++ l₂.pmap f h₂ :=
-  pmap_append f l₁ l₂ _
+theorem pmap_append' {p : α → Prop} (f : ∀ a : α, p a → β) (xs ys : Array α)
+    (h₁ : ∀ a ∈ xs, p a) (h₂ : ∀ a ∈ ys, p a) :
+    ((xs ++ ys).pmap f fun a ha => (mem_append.1 ha).elim (h₁ a) (h₂ a)) =
+      xs.pmap f h₁ ++ ys.pmap f h₂ :=
+  pmap_append f xs ys _
 
 @[simp] theorem attach_append (xs ys : Array α) :
     (xs ++ ys).attach = xs.attach.map (fun ⟨x, h⟩ => ⟨x, mem_append_left ys h⟩) ++
@@ -496,35 +511,35 @@ theorem back?_attach {xs : Array α} :
   simp
 
 @[simp]
-theorem countP_attach (l : Array α) (p : α → Bool) :
-    l.attach.countP (fun a : {x // x ∈ l} => p a) = l.countP p := by
-  cases l
+theorem countP_attach (xs : Array α) (p : α → Bool) :
+    xs.attach.countP (fun a : {x // x ∈ xs} => p a) = xs.countP p := by
+  cases xs
   simp [Function.comp_def]
 
 @[simp]
-theorem countP_attachWith {p : α → Prop} (l : Array α) (H : ∀ a ∈ l, p a) (q : α → Bool) :
-    (l.attachWith p H).countP (fun a : {x // p x} => q a) = l.countP q := by
-  cases l
+theorem countP_attachWith {p : α → Prop} (xs : Array α) (H : ∀ a ∈ xs, p a) (q : α → Bool) :
+    (xs.attachWith p H).countP (fun a : {x // p x} => q a) = xs.countP q := by
+  cases xs
   simp
 
 @[simp]
-theorem count_attach [DecidableEq α] (l : Array α) (a : {x // x ∈ l}) :
-    l.attach.count a = l.count ↑a := by
-  rcases l with ⟨l⟩
+theorem count_attach [DecidableEq α] (xs : Array α) (a : {x // x ∈ xs}) :
+    xs.attach.count a = xs.count ↑a := by
+  rcases xs with ⟨xs⟩
   simp only [List.attach_toArray, List.attachWith_mem_toArray, List.count_toArray]
   rw [List.map_attach_eq_pmap, List.count_eq_countP]
   simp only [Subtype.beq_iff]
   rw [List.countP_pmap, List.countP_attach (p := (fun x => x == a.1)), List.count]
 
 @[simp]
-theorem count_attachWith [DecidableEq α] {p : α → Prop} (l : Array α) (H : ∀ a ∈ l, p a) (a : {x // p x}) :
-    (l.attachWith p H).count a = l.count ↑a := by
-  cases l
+theorem count_attachWith [DecidableEq α] {p : α → Prop} (xs : Array α) (H : ∀ a ∈ xs, p a) (a : {x // p x}) :
+    (xs.attachWith p H).count a = xs.count ↑a := by
+  cases xs
   simp
 
-@[simp] theorem countP_pmap {p : α → Prop} (g : ∀ a, p a → β) (f : β → Bool) (l : Array α) (H₁) :
-    (l.pmap g H₁).countP f =
-      l.attach.countP (fun ⟨a, m⟩ => f (g a (H₁ a m))) := by
+@[simp] theorem countP_pmap {p : α → Prop} (g : ∀ a, p a → β) (f : β → Bool) (xs : Array α) (H₁) :
+    (xs.pmap g H₁).countP f =
+      xs.attach.countP (fun ⟨a, m⟩ => f (g a (H₁ a m))) := by
   simp [pmap_eq_map_attach, countP_map, Function.comp_def]
 
 /-! ## unattach
@@ -539,49 +554,63 @@ Further, we provide simp lemmas that push `unattach` inwards.
 -/
 
 /--
-A synonym for `l.map (·.val)`. Mostly this should not be needed by users.
-It is introduced as in intermediate step by lemmas such as `map_subtype`,
-and is ideally subsequently simplified away by `unattach_attach`.
+Maps an array of terms in a subtype to the corresponding terms in the type by forgetting that they
+satisfy the predicate.
 
-If not, usually the right approach is `simp [Array.unattach, -Array.map_subtype]` to unfold.
+This is the inverse of `Array.attachWith` and a synonym for `xs.map (·.val)`.
+
+Mostly this should not be needed by users. It is introduced as an intermediate step by lemmas such
+as `map_subtype`, and is ideally subsequently simplified away by `unattach_attach`.
+
+This function is usually inserted automatically by Lean as an intermediate step while proving
+termination. It is rarely used explicitly in code. It is introduced as an intermediate step during
+the elaboration of definitions by [well-founded
+recursion](lean-manual://section/well-founded-recursion). If this function is encountered in a proof
+state, the right approach is usually the tactic `simp [Array.unattach, -Array.map_subtype]`.
 -/
-def unattach {α : Type _} {p : α → Prop} (l : Array { x // p x }) : Array α := l.map (·.val)
+def unattach {α : Type _} {p : α → Prop} (xs : Array { x // p x }) : Array α := xs.map (·.val)
 
-@[simp] theorem unattach_nil {p : α → Prop} : (#[] : Array { x // p x }).unattach = #[] := rfl
-@[simp] theorem unattach_push {p : α → Prop} {a : { x // p x }} {l : Array { x // p x }} :
-    (l.push a).unattach = l.unattach.push a.1 := by
+@[simp] theorem unattach_nil {p : α → Prop} : (#[] : Array { x // p x }).unattach = #[] := by
+  simp [unattach]
+
+@[simp] theorem unattach_push {p : α → Prop} {a : { x // p x }} {xs : Array { x // p x }} :
+    (xs.push a).unattach = xs.unattach.push a.1 := by
   simp only [unattach, Array.map_push]
 
-@[simp] theorem size_unattach {p : α → Prop} {l : Array { x // p x }} :
-    l.unattach.size = l.size := by
+@[simp] theorem mem_unattach {p : α → Prop} {xs : Array { x // p x }} {a} :
+    a ∈ xs.unattach ↔ ∃ h : p a, ⟨a, h⟩ ∈ xs := by
+  simp only [unattach, mem_map, Subtype.exists, exists_and_right, exists_eq_right]
+
+@[simp] theorem size_unattach {p : α → Prop} {xs : Array { x // p x }} :
+    xs.unattach.size = xs.size := by
   unfold unattach
   simp
 
-@[simp] theorem _root_.List.unattach_toArray {p : α → Prop} {l : List { x // p x }} :
-    l.toArray.unattach = l.unattach.toArray := by
+@[simp] theorem _root_.List.unattach_toArray {p : α → Prop} {xs : List { x // p x }} :
+    xs.toArray.unattach = xs.unattach.toArray := by
   simp only [unattach, List.map_toArray, List.unattach]
 
-@[simp] theorem toList_unattach {p : α → Prop} {l : Array { x // p x }} :
-    l.unattach.toList = l.toList.unattach := by
+@[simp] theorem toList_unattach {p : α → Prop} {xs : Array { x // p x }} :
+    xs.unattach.toList = xs.toList.unattach := by
   simp only [unattach, toList_map, List.unattach]
 
-@[simp] theorem unattach_attach {l : Array α} : l.attach.unattach = l := by
-  cases l
+@[simp] theorem unattach_attach {xs : Array α} : xs.attach.unattach = xs := by
+  cases xs
   simp only [List.attach_toArray, List.unattach_toArray, List.unattach_attachWith]
 
-@[simp] theorem unattach_attachWith {p : α → Prop} {l : Array α}
-    {H : ∀ a ∈ l, p a} :
-    (l.attachWith p H).unattach = l := by
-  cases l
+@[simp] theorem unattach_attachWith {p : α → Prop} {xs : Array α}
+    {H : ∀ a ∈ xs, p a} :
+    (xs.attachWith p H).unattach = xs := by
+  cases xs
   simp
 
-@[simp] theorem getElem?_unattach {p : α → Prop} {l : Array { x // p x }} (i : Nat) :
-    l.unattach[i]? = l[i]?.map Subtype.val := by
+@[simp] theorem getElem?_unattach {p : α → Prop} {xs : Array { x // p x }} (i : Nat) :
+    xs.unattach[i]? = xs[i]?.map Subtype.val := by
   simp [unattach]
 
 @[simp] theorem getElem_unattach
-    {p : α → Prop} {l : Array { x // p x }} (i : Nat) (h : i < l.unattach.size) :
-    l.unattach[i] = (l[i]'(by simpa using h)).1 := by
+    {p : α → Prop} {xs : Array { x // p x }} (i : Nat) (h : i < xs.unattach.size) :
+    xs.unattach[i] = (xs[i]'(by simpa using h)).1 := by
   simp [unattach]
 
 /-! ### Recognizing higher order functions using a function that only depends on the value. -/
@@ -590,20 +619,20 @@ def unattach {α : Type _} {p : α → Prop} (l : Array { x // p x }) : Array α
 This lemma identifies folds over arrays of subtypes, where the function only depends on the value, not the proposition,
 and simplifies these to the function directly taking the value.
 -/
-theorem foldl_subtype {p : α → Prop} {l : Array { x // p x }}
+theorem foldl_subtype {p : α → Prop} {xs : Array { x // p x }}
     {f : β → { x // p x } → β} {g : β → α → β} {x : β}
     (hf : ∀ b x h, f b ⟨x, h⟩ = g b x) :
-    l.foldl f x = l.unattach.foldl g x := by
-  cases l
+    xs.foldl f x = xs.unattach.foldl g x := by
+  cases xs
   simp only [List.foldl_toArray', List.unattach_toArray]
   rw [List.foldl_subtype] -- Why can't simp do this?
   simp [hf]
 
 /-- Variant of `foldl_subtype` with side condition to check `stop = l.size`. -/
-@[simp] theorem foldl_subtype' {p : α → Prop} {l : Array { x // p x }}
+@[simp] theorem foldl_subtype' {p : α → Prop} {xs : Array { x // p x }}
     {f : β → { x // p x } → β} {g : β → α → β} {x : β}
-    (hf : ∀ b x h, f b ⟨x, h⟩ = g b x) (h : stop = l.size) :
-    l.foldl f x 0 stop = l.unattach.foldl g x := by
+    (hf : ∀ b x h, f b ⟨x, h⟩ = g b x) (h : stop = xs.size) :
+    xs.foldl f x 0 stop = xs.unattach.foldl g x := by
   subst h
   rwa [foldl_subtype]
 
@@ -611,20 +640,20 @@ theorem foldl_subtype {p : α → Prop} {l : Array { x // p x }}
 This lemma identifies folds over arrays of subtypes, where the function only depends on the value, not the proposition,
 and simplifies these to the function directly taking the value.
 -/
-theorem foldr_subtype {p : α → Prop} {l : Array { x // p x }}
+theorem foldr_subtype {p : α → Prop} {xs : Array { x // p x }}
     {f : { x // p x } → β → β} {g : α → β → β} {x : β}
     (hf : ∀ x h b, f ⟨x, h⟩ b = g x b) :
-    l.foldr f x = l.unattach.foldr g x := by
-  cases l
+    xs.foldr f x = xs.unattach.foldr g x := by
+  cases xs
   simp only [List.foldr_toArray', List.unattach_toArray]
   rw [List.foldr_subtype]
   simp [hf]
 
 /-- Variant of `foldr_subtype` with side condition to check `stop = l.size`. -/
-@[simp] theorem foldr_subtype' {p : α → Prop} {l : Array { x // p x }}
+@[simp] theorem foldr_subtype' {p : α → Prop} {xs : Array { x // p x }}
     {f : { x // p x } → β → β} {g : α → β → β} {x : β}
-    (hf : ∀ x h b, f ⟨x, h⟩ b = g x b) (h : start = l.size) :
-    l.foldr f x start 0 = l.unattach.foldr g x := by
+    (hf : ∀ x h b, f ⟨x, h⟩ b = g x b) (h : start = xs.size) :
+    xs.foldr f x start 0 = xs.unattach.foldr g x := by
   subst h
   rwa [foldr_subtype]
 
@@ -632,78 +661,95 @@ theorem foldr_subtype {p : α → Prop} {l : Array { x // p x }}
 This lemma identifies maps over arrays of subtypes, where the function only depends on the value, not the proposition,
 and simplifies these to the function directly taking the value.
 -/
-@[simp] theorem map_subtype {p : α → Prop} {l : Array { x // p x }}
+@[simp] theorem map_subtype {p : α → Prop} {xs : Array { x // p x }}
     {f : { x // p x } → β} {g : α → β} (hf : ∀ x h, f ⟨x, h⟩ = g x) :
-    l.map f = l.unattach.map g := by
-  cases l
+    xs.map f = xs.unattach.map g := by
+  cases xs
   simp only [List.map_toArray, List.unattach_toArray]
   rw [List.map_subtype]
   simp [hf]
 
-@[simp] theorem filterMap_subtype {p : α → Prop} {l : Array { x // p x }}
+@[simp] theorem filterMap_subtype {p : α → Prop} {xs : Array { x // p x }}
     {f : { x // p x } → Option β} {g : α → Option β} (hf : ∀ x h, f ⟨x, h⟩ = g x) :
-    l.filterMap f = l.unattach.filterMap g := by
-  cases l
+    xs.filterMap f = xs.unattach.filterMap g := by
+  cases xs
   simp only [List.size_toArray, List.filterMap_toArray', List.unattach_toArray, List.length_unattach,
     mk.injEq]
   rw [List.filterMap_subtype]
   simp [hf]
 
 
-@[simp] theorem flatMap_subtype {p : α → Prop} {l : Array { x // p x }}
+@[simp] theorem flatMap_subtype {p : α → Prop} {xs : Array { x // p x }}
     {f : { x // p x } → Array β} {g : α → Array β} (hf : ∀ x h, f ⟨x, h⟩ = g x) :
-    (l.flatMap f) = l.unattach.flatMap g := by
-  cases l
+    (xs.flatMap f) = xs.unattach.flatMap g := by
+  cases xs
   simp only [List.size_toArray, List.flatMap_toArray, List.unattach_toArray, List.length_unattach,
     mk.injEq]
   rw [List.flatMap_subtype]
   simp [hf]
 
-@[simp] theorem findSome?_subtype {p : α → Prop} {l : Array { x // p x }}
+@[simp] theorem findSome?_subtype {p : α → Prop} {xs : Array { x // p x }}
     {f : { x // p x } → Option β} {g : α → Option β} (hf : ∀ x h, f ⟨x, h⟩ = g x) :
-    l.findSome? f = l.unattach.findSome? g := by
-  cases l
+    xs.findSome? f = xs.unattach.findSome? g := by
+  cases xs
   simp
   rw [List.findSome?_subtype hf]
 
-@[simp] theorem find?_subtype {p : α → Prop} {l : Array { x // p x }}
+@[simp] theorem find?_subtype {p : α → Prop} {xs : Array { x // p x }}
     {f : { x // p x } → Bool} {g : α → Bool} (hf : ∀ x h, f ⟨x, h⟩ = g x) :
-    (l.find? f).map Subtype.val = l.unattach.find? g := by
-  cases l
+    (xs.find? f).map Subtype.val = xs.unattach.find? g := by
+  cases xs
   simp
   rw [List.find?_subtype hf]
 
-/-! ### Simp lemmas pushing `unattach` inwards. -/
-
-@[simp] theorem unattach_filter {p : α → Prop} {l : Array { x // p x }}
-    {f : { x // p x } → Bool} {g : α → Bool} (hf : ∀ x h, f ⟨x, h⟩ = g x) :
-    (l.filter f).unattach = l.unattach.filter g := by
-  cases l
+@[simp] theorem all_subtype {p : α → Prop} {xs : Array { x // p x }} {f : { x // p x } → Bool} {g : α → Bool}
+    (hf : ∀ x h, f ⟨x, h⟩ = g x) (w : stop = xs.size) :
+    xs.all f 0 stop = xs.unattach.all g := by
+  subst w
+  rcases xs with ⟨xs⟩
   simp [hf]
 
-@[simp] theorem unattach_reverse {p : α → Prop} {l : Array { x // p x }} :
-    l.reverse.unattach = l.unattach.reverse := by
-  cases l
+@[simp] theorem any_subtype {p : α → Prop} {xs : Array { x // p x }} {f : { x // p x } → Bool} {g : α → Bool}
+    (hf : ∀ x h, f ⟨x, h⟩ = g x) (w : stop = xs.size) :
+    xs.any f 0 stop = xs.unattach.any g := by
+  subst w
+  rcases xs with ⟨xs⟩
+  simp [hf]
+
+/-! ### Simp lemmas pushing `unattach` inwards. -/
+
+@[simp] theorem unattach_filter {p : α → Prop} {xs : Array { x // p x }}
+    {f : { x // p x } → Bool} {g : α → Bool} (hf : ∀ x h, f ⟨x, h⟩ = g x) :
+    (xs.filter f).unattach = xs.unattach.filter g := by
+  cases xs
+  simp [hf]
+
+@[simp] theorem unattach_reverse {p : α → Prop} {xs : Array { x // p x }} :
+    xs.reverse.unattach = xs.unattach.reverse := by
+  cases xs
   simp
 
-@[simp] theorem unattach_append {p : α → Prop} {l₁ l₂ : Array { x // p x }} :
-    (l₁ ++ l₂).unattach = l₁.unattach ++ l₂.unattach := by
-  cases l₁
-  cases l₂
+@[simp] theorem unattach_append {p : α → Prop} {xs₁ xs₂ : Array { x // p x }} :
+    (xs₁ ++ xs₂).unattach = xs₁.unattach ++ xs₂.unattach := by
+  cases xs₁
+  cases xs₂
   simp
 
-@[simp] theorem unattach_flatten {p : α → Prop} {l : Array (Array { x // p x })} :
-    l.flatten.unattach = (l.map unattach).flatten := by
+@[simp] theorem unattach_flatten {p : α → Prop} {xs : Array (Array { x // p x })} :
+    xs.flatten.unattach = (xs.map unattach).flatten := by
   unfold unattach
-  cases l using array₂_induction
+  cases xs using array₂_induction
   simp only [flatten_toArray, List.map_map, Function.comp_def, List.map_id_fun', id_eq,
     List.map_toArray, List.map_flatten, map_subtype, map_id_fun', List.unattach_toArray, mk.injEq]
   simp only [List.unattach]
 
-@[simp] theorem unattach_mkArray {p : α → Prop} {n : Nat} {x : { x // p x }} :
-    (Array.mkArray n x).unattach = Array.mkArray n x.1 := by
+@[simp] theorem unattach_replicate {p : α → Prop} {n : Nat} {x : { x // p x }} :
+    (Array.replicate n x).unattach = Array.replicate n x.1 := by
   simp [unattach]
 
+@[deprecated unattach_replicate (since := "2025-03-18")]
+abbrev unattach_mkArray := @unattach_replicate
+
 /-! ### Well-founded recursion preprocessing setup -/
 
 @[wf_preprocess] theorem Array.map_wfParam (xs : Array α) (f : α → β) :

src/Init/Data/Array/BasicAux.lean

@@ -8,6 +8,9 @@ import Init.Data.Array.Basic
 import Init.Data.Nat.Linear
 import Init.NotationExtra
 
+set_option linter.listVariables true -- Enforce naming conventions for `List`/`Array`/`Vector` variables.
+set_option linter.indexVariables true -- Enforce naming conventions for index variables.
+
 theorem Array.of_push_eq_push {as bs : Array α} (h : as.push a = bs.push b) : as = bs ∧ a = b := by
   simp only [push, mk.injEq] at h
   have ⟨h₁, h₂⟩ := List.of_concat_eq_concat h
@@ -35,6 +38,11 @@ private theorem List.of_toArrayAux_eq_toArrayAux {as bs : List α} {cs ds : Arra
 theorem List.toArray_eq_toArray_eq (as bs : List α) : (as.toArray = bs.toArray) = (as = bs) := by
   simp
 
+/--
+Applies the monadic action `f` to every element in the array, left-to-right, and returns the array
+of results. Furthermore, the resulting array's type guarantees that it contains the same number of
+elements as the input array.
+-/
 def Array.mapM' [Monad m] (f : α → m β) (as : Array α) : m { bs : Array β // bs.size = as.size } :=
   go 0 ⟨mkEmpty as.size, rfl⟩ (by simp)
 where
@@ -63,11 +71,19 @@ where
       return as
 
 /--
-Monomorphic `Array.mapM`. The internal implementation uses pointer equality, and does not allocate a new array
-if the result of each `f a` is a pointer equal value `a`.
+Applies a monadic function to each element of an array, returning the array of results. The function is
+monomorphic: it is required to return a value of the same type. The internal implementation uses
+pointer equality, and does not allocate a new array if the result of each function call is
+pointer-equal to its argument.
 -/
 @[implemented_by mapMonoMImp] def Array.mapMonoM [Monad m] (as : Array α) (f : α → m α) : m (Array α) :=
   as.mapM f
 
+/--
+Applies a function to each element of an array, returning the array of results. The function is
+monomorphic: it is required to return a value of the same type. The internal implementation uses
+pointer equality, and does not allocate a new array if the result of each function call is
+pointer-equal to its argument.
+-/
 @[inline] def Array.mapMono (as : Array α) (f : α → α) : Array α :=
   Id.run <| as.mapMonoM f

src/Init/Data/Array/BinSearch.lean

@@ -5,9 +5,13 @@ Authors: Leonardo de Moura
 -/
 prelude
 import Init.Data.Array.Basic
+import Init.Data.Int.DivMod.Lemmas
 import Init.Omega
 universe u v
 
+set_option linter.listVariables true -- Enforce naming conventions for `List`/`Array`/`Vector` variables.
+-- We do not use `linter.indexVariables` here as it is helpful to name the index variables as `lo`, `mid`, and `hi`.
+
 namespace Array
 
 @[specialize] def binSearchAux {α : Type u} {β : Type v} (lt : α → α → Bool) (found : Option α → β) (as : Array α) (k : α) :
@@ -25,6 +29,16 @@ namespace Array
     else found (some a)
 termination_by lo hi => hi.1 - lo.1
 
+/--
+Binary search for an element equivalent to `k` in the sorted array `as`. Returns the element from
+the array, if it is found, or `none` otherwise.
+
+The array `as` must be sorted according to the comparison operator `lt`, which should be a total
+order.
+
+The optional parameters `lo` and `hi` determine the region of the array indices to be searched. Both
+are inclusive, and default to searching the entire array.
+-/
 @[inline] def binSearch {α : Type} (as : Array α) (k : α) (lt : α → α → Bool) (lo := 0) (hi := as.size - 1) : Option α :=
   if h : lo < as.size then
     let hi := if hi < as.size then hi else as.size - 1
@@ -35,6 +49,16 @@ termination_by lo hi => hi.1 - lo.1
   else
     none
 
+/--
+Binary search for an element equivalent to `k` in the sorted array `as`. Returns `true` if the
+element is found, or `false` otherwise.
+
+The array `as` must be sorted according to the comparison operator `lt`, which should be a total
+order.
+
+The optional parameters `lo` and `hi` determine the region of the array indices to be searched. Both
+are inclusive, and default to searching the entire array.
+-/
 @[inline] def binSearchContains {α : Type} (as : Array α) (k : α) (lt : α → α → Bool) (lo := 0) (hi := as.size - 1) : Bool :=
   if h : lo < as.size then
     let hi := if hi < as.size then hi else as.size - 1
@@ -64,6 +88,16 @@ termination_by lo hi => hi.1 - lo.1
       as.modifyM mid <| fun v => merge v
 termination_by lo hi => hi.1 - lo.1
 
+/--
+Inserts an element `k` into a sorted array `as` such that the resulting array is sorted.
+
+The ordering predicate `lt` should be a total order on elements, and the array `as` should be sorted
+with respect to `lt`.
+
+If an element that `lt` equates to `k` is already present in `as`, then `merge` is applied to the
+existing element to determine the value of that position in the resulting array. If no element equal
+to `k` is present, then `add` is used to determine the value to be inserted.
+-/
 @[specialize] def binInsertM {α : Type u} {m : Type u → Type v} [Monad m]
     (lt : α → α → Bool)
     (merge : α → m α)
@@ -77,6 +111,21 @@ termination_by lo hi => hi.1 - lo.1
   else if !lt k as[as.size - 1] then as.modifyM (as.size - 1) <| merge
   else binInsertAux lt merge add as k ⟨0, by omega⟩ ⟨as.size - 1, by omega⟩ (by simp) (by simpa using h')
 
+/--
+Inserts an element into a sorted array such that the resulting array is sorted. If the element is
+already present in the array, it is not inserted.
+
+The ordering predicate `lt` should be a total order on elements, and the array `as` should be sorted
+with respect to `lt`.
+
+`Array.binInsertM` is a more general operator that provides greater control over the handling of
+duplicate elements in addition to running in a monad.
+
+Examples:
+* `#[0, 1, 3, 5].binInsert (· < ·) 2 = #[0, 1, 2, 3, 5]`
+* `#[0, 1, 3, 5].binInsert (· < ·) 1 = #[0, 1, 3, 5]`
+* `#[].binInsert (· < ·) 1 = #[1]`
+-/
 @[inline] def binInsert {α : Type u} (lt : α → α → Bool) (as : Array α) (k : α) : Array α :=
   Id.run <| binInsertM lt (fun _ => k) (fun _ => k) as k
 

src/Init/Data/Array/Bootstrap.lean

@@ -13,6 +13,9 @@ import Init.Data.List.TakeDrop
 This file contains some theorems about `Array` and `List` needed for `Init.Data.List.Impl`.
 -/
 
+set_option linter.listVariables true -- Enforce naming conventions for `List`/`Array`/`Vector` variables.
+set_option linter.indexVariables true -- Enforce naming conventions for index variables.
+
 namespace Array
 
 /--
@@ -39,122 +42,122 @@ def get! {α : Type u} [Inhabited α] (a : @& Array α) (i : @& Nat) : α :=
   Array.getD a i default
 
 theorem foldlM_toList.aux [Monad m]
-    (f : β → α → m β) (arr : Array α) (i j) (H : arr.size ≤ i + j) (b) :
-    foldlM.loop f arr arr.size (Nat.le_refl _) i j b = (arr.toList.drop j).foldlM f b := by
+    (f : β → α → m β) (xs : Array α) (i j) (H : xs.size ≤ i + j) (b) :
+    foldlM.loop f xs xs.size (Nat.le_refl _) i j b = (xs.toList.drop j).foldlM f b := by
   unfold foldlM.loop
   split; split
   · cases Nat.not_le_of_gt ‹_› (Nat.zero_add _ ▸ H)
   · rename_i i; rw [Nat.succ_add] at H
-    simp [foldlM_toList.aux f arr i (j+1) H]
+    simp [foldlM_toList.aux f xs i (j+1) H]
     rw (occs := [2]) [← List.getElem_cons_drop_succ_eq_drop ‹_›]
     rfl
   · rw [List.drop_of_length_le (Nat.ge_of_not_lt ‹_›)]; rfl
 
 @[simp] theorem foldlM_toList [Monad m]
-    (f : β → α → m β) (init : β) (arr : Array α) :
-    arr.toList.foldlM f init = arr.foldlM f init := by
+    (f : β → α → m β) (init : β) (xs : Array α) :
+    xs.toList.foldlM f init = xs.foldlM f init := by
   simp [foldlM, foldlM_toList.aux]
 
-@[simp] theorem foldl_toList (f : β → α → β) (init : β) (arr : Array α) :
-    arr.toList.foldl f init = arr.foldl f init :=
+@[simp] theorem foldl_toList (f : β → α → β) (init : β) (xs : Array α) :
+    xs.toList.foldl f init = xs.foldl f init :=
   List.foldl_eq_foldlM .. ▸ foldlM_toList ..
 
 theorem foldrM_eq_reverse_foldlM_toList.aux [Monad m]
-    (f : α → β → m β) (arr : Array α) (init : β) (i h) :
-    (arr.toList.take i).reverse.foldlM (fun x y => f y x) init = foldrM.fold f arr 0 i h init := by
+    (f : α → β → m β) (xs : Array α) (init : β) (i h) :
+    (xs.toList.take i).reverse.foldlM (fun x y => f y x) init = foldrM.fold f xs 0 i h init := by
   unfold foldrM.fold
   match i with
   | 0 => simp [List.foldlM, List.take]
-  | i+1 => rw [← List.take_concat_get _ _ h]; simp [← (aux f arr · i)]
+  | i+1 => rw [← List.take_concat_get _ _ h]; simp [← (aux f xs · i)]
 
-theorem foldrM_eq_reverse_foldlM_toList [Monad m] (f : α → β → m β) (init : β) (arr : Array α) :
-    arr.foldrM f init = arr.toList.reverse.foldlM (fun x y => f y x) init := by
-  have : arr = #[] ∨ 0 < arr.size :=
-    match arr with | ⟨[]⟩ => .inl rfl | ⟨a::l⟩ => .inr (Nat.zero_lt_succ _)
-  match arr, this with | _, .inl rfl => rfl | arr, .inr h => ?_
+theorem foldrM_eq_reverse_foldlM_toList [Monad m] (f : α → β → m β) (init : β) (xs : Array α) :
+    xs.foldrM f init = xs.toList.reverse.foldlM (fun x y => f y x) init := by
+  have : xs = #[] ∨ 0 < xs.size :=
+    match xs with | ⟨[]⟩ => .inl rfl | ⟨a::l⟩ => .inr (Nat.zero_lt_succ _)
+  match xs, this with | _, .inl rfl => rfl | xs, .inr h => ?_
   simp [foldrM, h, ← foldrM_eq_reverse_foldlM_toList.aux, List.take_length]
 
 @[simp] theorem foldrM_toList [Monad m]
-    (f : α → β → m β) (init : β) (arr : Array α) :
-    arr.toList.foldrM f init = arr.foldrM f init := by
+    (f : α → β → m β) (init : β) (xs : Array α) :
+    xs.toList.foldrM f init = xs.foldrM f init := by
   rw [foldrM_eq_reverse_foldlM_toList, List.foldlM_reverse]
 
-@[simp] theorem foldr_toList (f : α → β → β) (init : β) (arr : Array α) :
-    arr.toList.foldr f init = arr.foldr f init :=
+@[simp] theorem foldr_toList (f : α → β → β) (init : β) (xs : Array α) :
+    xs.toList.foldr f init = xs.foldr f init :=
   List.foldr_eq_foldrM .. ▸ foldrM_toList ..
 
-@[simp] theorem push_toList (arr : Array α) (a : α) : (arr.push a).toList = arr.toList ++ [a] := by
+@[simp] theorem push_toList (xs : Array α) (a : α) : (xs.push a).toList = xs.toList ++ [a] := by
   simp [push, List.concat_eq_append]
 
-@[simp] theorem toListAppend_eq (arr : Array α) (l) : arr.toListAppend l = arr.toList ++ l := by
+@[simp] theorem toListAppend_eq (xs : Array α) (l : List α) : xs.toListAppend l = xs.toList ++ l := by
   simp [toListAppend, ← foldr_toList]
 
-@[simp] theorem toListImpl_eq (arr : Array α) : arr.toListImpl = arr.toList := by
+@[simp] theorem toListImpl_eq (xs : Array α) : xs.toListImpl = xs.toList := by
   simp [toListImpl, ← foldr_toList]
 
-@[simp] theorem toList_pop (a : Array α) : a.pop.toList = a.toList.dropLast := rfl
+@[simp] theorem toList_pop (xs : Array α) : xs.pop.toList = xs.toList.dropLast := rfl
 
 @[deprecated toList_pop (since := "2025-02-17")]
 abbrev pop_toList := @Array.toList_pop
 
-@[simp] theorem append_eq_append (arr arr' : Array α) : arr.append arr' = arr ++ arr' := rfl
+@[simp] theorem append_eq_append (xs ys : Array α) : xs.append ys = xs ++ ys := rfl
 
-@[simp] theorem toList_append (arr arr' : Array α) :
-    (arr ++ arr').toList = arr.toList ++ arr'.toList := by
+@[simp] theorem toList_append (xs ys : Array α) :
+    (xs ++ ys).toList = xs.toList ++ ys.toList := by
   rw [← append_eq_append]; unfold Array.append
   rw [← foldl_toList]
-  induction arr'.toList generalizing arr <;> simp [*]
+  induction ys.toList generalizing xs <;> simp [*]
 
 @[simp] theorem toList_empty : (#[] : Array α).toList = [] := rfl
 
-@[simp] theorem append_empty (as : Array α) : as ++ #[] = as := by
+@[simp] theorem append_empty (xs : Array α) : xs ++ #[] = xs := by
   apply ext'; simp only [toList_append, toList_empty, List.append_nil]
 
 @[deprecated append_empty (since := "2025-01-13")]
 abbrev append_nil := @append_empty
 
-@[simp] theorem empty_append (as : Array α) : #[] ++ as = as := by
+@[simp] theorem empty_append (xs : Array α) : #[] ++ xs = xs := by
   apply ext'; simp only [toList_append, toList_empty, List.nil_append]
 
 @[deprecated empty_append (since := "2025-01-13")]
 abbrev nil_append := @empty_append
 
-@[simp] theorem append_assoc (as bs cs : Array α) : as ++ bs ++ cs = as ++ (bs ++ cs) := by
+@[simp] theorem append_assoc (xs ys zs : Array α) : xs ++ ys ++ zs = xs ++ (ys ++ zs) := by
   apply ext'; simp only [toList_append, List.append_assoc]
 
 @[simp] theorem appendList_eq_append
-    (arr : Array α) (l : List α) : arr.appendList l = arr ++ l := rfl
+    (xs : Array α) (l : List α) : xs.appendList l = xs ++ l := rfl
 
-@[simp] theorem toList_appendList (arr : Array α) (l : List α) :
-    (arr ++ l).toList = arr.toList ++ l := by
+@[simp] theorem toList_appendList (xs : Array α) (l : List α) :
+    (xs ++ l).toList = xs.toList ++ l := by
   rw [← appendList_eq_append]; unfold Array.appendList
-  induction l generalizing arr <;> simp [*]
+  induction l generalizing xs <;> simp [*]
 
 @[deprecated toList_appendList (since := "2024-12-11")]
 abbrev appendList_toList := @toList_appendList
 
 @[deprecated "Use the reverse direction of `foldrM_toList`." (since := "2024-11-13")]
 theorem foldrM_eq_foldrM_toList [Monad m]
-    (f : α → β → m β) (init : β) (arr : Array α) :
-    arr.foldrM f init = arr.toList.foldrM f init := by
+    (f : α → β → m β) (init : β) (xs : Array α) :
+    xs.foldrM f init = xs.toList.foldrM f init := by
   simp
 
 @[deprecated "Use the reverse direction of `foldlM_toList`." (since := "2024-11-13")]
 theorem foldlM_eq_foldlM_toList [Monad m]
-    (f : β → α → m β) (init : β) (arr : Array α) :
-    arr.foldlM f init = arr.toList.foldlM f init:= by
+    (f : β → α → m β) (init : β) (xs : Array α) :
+    xs.foldlM f init = xs.toList.foldlM f init:= by
   simp
 
 @[deprecated "Use the reverse direction of `foldr_toList`." (since := "2024-11-13")]
 theorem foldr_eq_foldr_toList
-    (f : α → β → β) (init : β) (arr : Array α) :
-    arr.foldr f init = arr.toList.foldr f init := by
+    (f : α → β → β) (init : β) (xs : Array α) :
+    xs.foldr f init = xs.toList.foldr f init := by
   simp
 
 @[deprecated "Use the reverse direction of `foldl_toList`." (since := "2024-11-13")]
 theorem foldl_eq_foldl_toList
-    (f : β → α → β) (init : β) (arr : Array α) :
-    arr.foldl f init = arr.toList.foldl f init:= by
+    (f : β → α → β) (init : β) (xs : Array α) :
+    xs.foldl f init = xs.toList.foldl f init:= by
   simp
 
 @[deprecated foldlM_toList (since := "2024-09-09")]

src/Init/Data/Array/Count.lean

@@ -11,6 +11,9 @@ import Init.Data.List.Nat.Count
 # Lemmas about `Array.countP` and `Array.count`.
 -/
 
+set_option linter.listVariables true -- Enforce naming conventions for `List`/`Array`/`Vector` variables.
+set_option linter.indexVariables true -- Enforce naming conventions for index variables.
+
 namespace Array
 
 open Nat
@@ -20,122 +23,137 @@ section countP
 
 variable (p q : α → Bool)
 
+@[simp] theorem _root_.List.countP_toArray (l : List α) : countP p l.toArray = l.countP p := by
+  simp [countP]
+  induction l with
+  | nil => rfl
+  | cons hd tl ih =>
+    simp only [List.foldr_cons, ih, List.countP_cons]
+    split <;> simp_all
+
+@[simp] theorem countP_toList (xs : Array α) : xs.toList.countP p = countP p xs := by
+  cases xs
+  simp
+
 @[simp] theorem countP_empty : countP p #[] = 0 := rfl
 
-@[simp] theorem countP_push_of_pos (l) (pa : p a) : countP p (l.push a) = countP p l + 1 := by
-  rcases l with ⟨l⟩
+@[simp] theorem countP_push_of_pos (xs) (pa : p a) : countP p (xs.push a) = countP p xs + 1 := by
+  rcases xs with ⟨xs⟩
   simp_all
 
-@[simp] theorem countP_push_of_neg (l) (pa : ¬p a) : countP p (l.push a) = countP p l := by
-  rcases l with ⟨l⟩
+@[simp] theorem countP_push_of_neg (xs) (pa : ¬p a) : countP p (xs.push a) = countP p xs := by
+  rcases xs with ⟨xs⟩
   simp_all
 
-theorem countP_push (a : α) (l) : countP p (l.push a) = countP p l + if p a then 1 else 0 := by
-  rcases l with ⟨l⟩
+theorem countP_push (a : α) (xs) : countP p (xs.push a) = countP p xs + if p a then 1 else 0 := by
+  rcases xs with ⟨xs⟩
   simp_all
 
 @[simp] theorem countP_singleton (a : α) : countP p #[a] = if p a then 1 else 0 := by
   simp [countP_push]
 
-theorem size_eq_countP_add_countP (l) : l.size = countP p l + countP (fun a => ¬p a) l := by
-  cases l
+theorem size_eq_countP_add_countP (xs) : xs.size = countP p xs + countP (fun a => ¬p a) xs := by
+  rcases xs with ⟨xs⟩
   simp [List.length_eq_countP_add_countP (p := p)]
 
-theorem countP_eq_size_filter (l) : countP p l = (filter p l).size := by
-  cases l
+theorem countP_eq_size_filter (xs) : countP p xs = (filter p xs).size := by
+  rcases xs with ⟨xs⟩
   simp [List.countP_eq_length_filter]
 
 theorem countP_eq_size_filter' : countP p = size ∘ filter p := by
-  funext l
+  funext xs
   apply countP_eq_size_filter
 
-theorem countP_le_size : countP p l ≤ l.size := by
+theorem countP_le_size : countP p xs ≤ xs.size := by
   simp only [countP_eq_size_filter]
   apply size_filter_le
 
-@[simp] theorem countP_append (l₁ l₂) : countP p (l₁ ++ l₂) = countP p l₁ + countP p l₂ := by
-  cases l₁
-  cases l₂
+@[simp] theorem countP_append (xs ys) : countP p (xs ++ ys) = countP p xs + countP p ys := by
+  rcases xs with ⟨xs⟩
+  rcases ys with ⟨ys⟩
   simp
 
-@[simp] theorem countP_pos_iff {p} : 0 < countP p l ↔ ∃ a ∈ l, p a := by
-  cases l
+@[simp] theorem countP_pos_iff {p} : 0 < countP p xs ↔ ∃ a ∈ xs, p a := by
+  rcases xs with ⟨xs⟩
   simp
 
-@[simp] theorem one_le_countP_iff {p} : 1 ≤ countP p l ↔ ∃ a ∈ l, p a :=
+@[simp] theorem one_le_countP_iff {p} : 1 ≤ countP p xs ↔ ∃ a ∈ xs, p a :=
   countP_pos_iff
 
-@[simp] theorem countP_eq_zero {p} : countP p l = 0 ↔ ∀ a ∈ l, ¬p a := by
-  cases l
+@[simp] theorem countP_eq_zero {p} : countP p xs = 0 ↔ ∀ a ∈ xs, ¬p a := by
+  rcases xs with ⟨xs⟩
   simp
 
-@[simp] theorem countP_eq_size {p} : countP p l = l.size ↔ ∀ a ∈ l, p a := by
-  cases l
+@[simp] theorem countP_eq_size {p} : countP p xs = xs.size ↔ ∀ a ∈ xs, p a := by
+  rcases xs with ⟨xs⟩
   simp
 
-theorem countP_mkArray (p : α → Bool) (a : α) (n : Nat) :
-    countP p (mkArray n a) = if p a then n else 0 := by
+theorem countP_replicate (p : α → Bool) (a : α) (n : Nat) :
+    countP p (replicate n a) = if p a then n else 0 := by
   simp [← List.toArray_replicate, List.countP_replicate]
 
-theorem boole_getElem_le_countP (p : α → Bool) (l : Array α) (i : Nat) (h : i < l.size) :
-    (if p l[i] then 1 else 0) ≤ l.countP p := by
-  cases l
+@[deprecated countP_replicate (since := "2025-03-18")]
+abbrev countP_mkArray := @countP_replicate
+
+theorem boole_getElem_le_countP (p : α → Bool) (xs : Array α) (i : Nat) (h : i < xs.size) :
+    (if p xs[i] then 1 else 0) ≤ xs.countP p := by
+  rcases xs with ⟨xs⟩
   simp [List.boole_getElem_le_countP]
 
-theorem countP_set (p : α → Bool) (l : Array α) (i : Nat) (a : α) (h : i < l.size) :
-    (l.set i a).countP p = l.countP p - (if p l[i] then 1 else 0) + (if p a then 1 else 0) := by
-  cases l
+theorem countP_set (p : α → Bool) (xs : Array α) (i : Nat) (a : α) (h : i < xs.size) :
+    (xs.set i a).countP p = xs.countP p - (if p xs[i] then 1 else 0) + (if p a then 1 else 0) := by
+  rcases xs with ⟨xs⟩
   simp [List.countP_set, h]
 
-theorem countP_filter (l : Array α) :
-    countP p (filter q l) = countP (fun a => p a && q a) l := by
-  cases l
+theorem countP_filter (xs : Array α) :
+    countP p (filter q xs) = countP (fun a => p a && q a) xs := by
+  rcases xs with ⟨xs⟩
   simp [List.countP_filter]
 
 @[simp] theorem countP_true : (countP fun (_ : α) => true) = size := by
-  funext l
+  funext xs
   simp
 
 @[simp] theorem countP_false : (countP fun (_ : α) => false) = Function.const _ 0 := by
-  funext l
+  funext xs
   simp
 
-@[simp] theorem countP_map (p : β → Bool) (f : α → β) (l : Array α) :
-    countP p (map f l) = countP (p ∘ f) l := by
-  cases l
+@[simp] theorem countP_map (p : β → Bool) (f : α → β) (xs : Array α) :
+    countP p (map f xs) = countP (p ∘ f) xs := by
+  rcases xs with ⟨xs⟩
   simp
 
-theorem size_filterMap_eq_countP (f : α → Option β) (l : Array α) :
-    (filterMap f l).size = countP (fun a => (f a).isSome) l := by
-  cases l
+theorem size_filterMap_eq_countP (f : α → Option β) (xs : Array α) :
+    (filterMap f xs).size = countP (fun a => (f a).isSome) xs := by
+  rcases xs with ⟨xs⟩
   simp [List.length_filterMap_eq_countP]
 
-theorem countP_filterMap (p : β → Bool) (f : α → Option β) (l : Array α) :
-    countP p (filterMap f l) = countP (fun a => ((f a).map p).getD false) l := by
-  cases l
+theorem countP_filterMap (p : β → Bool) (f : α → Option β) (xs : Array α) :
+    countP p (filterMap f xs) = countP (fun a => ((f a).map p).getD false) xs := by
+  rcases xs with ⟨xs⟩
   simp [List.countP_filterMap]
 
-@[simp] theorem countP_flatten (l : Array (Array α)) :
-    countP p l.flatten = (l.map (countP p)).sum := by
-  cases l using array₂_induction
+@[simp] theorem countP_flatten (xss : Array (Array α)) :
+    countP p xss.flatten = (xss.map (countP p)).sum := by
+  cases xss using array₂_induction
   simp [List.countP_flatten, Function.comp_def]
 
-theorem countP_flatMap (p : β → Bool) (l : Array α) (f : α → Array β) :
-    countP p (l.flatMap f) = sum (map (countP p ∘ f) l) := by
-  cases l
+theorem countP_flatMap (p : β → Bool) (xs : Array α) (f : α → Array β) :
+    countP p (xs.flatMap f) = sum (map (countP p ∘ f) xs) := by
+  rcases xs with ⟨xs⟩
   simp [List.countP_flatMap, Function.comp_def]
 
-@[simp] theorem countP_reverse (l : Array α) : countP p l.reverse = countP p l := by
-  cases l
+@[simp] theorem countP_reverse (xs : Array α) : countP p xs.reverse = countP p xs := by
+  rcases xs with ⟨xs⟩
   simp [List.countP_reverse]
 
 variable {p q}
 
-theorem countP_mono_left (h : ∀ x ∈ l, p x → q x) : countP p l ≤ countP q l := by
-  cases l
+theorem countP_mono_left (h : ∀ x ∈ xs, p x → q x) : countP p xs ≤ countP q xs := by
+  rcases xs with ⟨xs⟩
   simpa using List.countP_mono_left (by simpa using h)
 
-theorem countP_congr (h : ∀ x ∈ l, p x ↔ q x) : countP p l = countP q l :=
+theorem countP_congr (h : ∀ x ∈ xs, p x ↔ q x) : countP p xs = countP q xs :=
   Nat.le_antisymm
     (countP_mono_left fun x hx => (h x hx).1)
     (countP_mono_left fun x hx => (h x hx).2)
@@ -147,114 +165,131 @@ section count
 
 variable [BEq α]
 
+@[simp] theorem _root_.List.count_toArray (l : List α) (a : α) : count a l.toArray = l.count a := by
+  simp [count, List.count_eq_countP]
+
+@[simp] theorem count_toList (xs : Array α) (a : α) : xs.toList.count a = xs.count a := by
+  cases xs
+  simp
+
 @[simp] theorem count_empty (a : α) : count a #[] = 0 := rfl
 
-theorem count_push (a b : α) (l : Array α) :
-    count a (l.push b) = count a l + if b == a then 1 else 0 := by
+theorem count_push (a b : α) (xs : Array α) :
+    count a (xs.push b) = count a xs + if b == a then 1 else 0 := by
   simp [count, countP_push]
 
-theorem count_eq_countP (a : α) (l : Array α) : count a l = countP (· == a) l := rfl
+theorem count_eq_countP (a : α) (xs : Array α) : count a xs = countP (· == a) xs := rfl
 theorem count_eq_countP' {a : α} : count a = countP (· == a) := by
-  funext l
+  funext xs
   apply count_eq_countP
 
-theorem count_le_size (a : α) (l : Array α) : count a l ≤ l.size := countP_le_size _
+theorem count_le_size (a : α) (xs : Array α) : count a xs ≤ xs.size := countP_le_size _
 
-theorem count_le_count_push (a b : α) (l : Array α) : count a l ≤ count a (l.push b) := by
+theorem count_le_count_push (a b : α) (xs : Array α) : count a xs ≤ count a (xs.push b) := by
   simp [count_push]
 
 theorem count_singleton (a b : α) : count a #[b] = if b == a then 1 else 0 := by
   simp [count_eq_countP]
 
-@[simp] theorem count_append (a : α) : ∀ l₁ l₂, count a (l₁ ++ l₂) = count a l₁ + count a l₂ :=
+@[simp] theorem count_append (a : α) : ∀ xs ys, count a (xs ++ ys) = count a xs + count a ys :=
   countP_append _
 
-@[simp] theorem count_flatten (a : α) (l : Array (Array α)) :
-    count a l.flatten = (l.map (count a)).sum := by
-  cases l using array₂_induction
+@[simp] theorem count_flatten (a : α) (xss : Array (Array α)) :
+    count a xss.flatten = (xss.map (count a)).sum := by
+  cases xss using array₂_induction
   simp [List.count_flatten, Function.comp_def]
 
-@[simp] theorem count_reverse (a : α) (l : Array α) : count a l.reverse = count a l := by
-  cases l
+@[simp] theorem count_reverse (a : α) (xs : Array α) : count a xs.reverse = count a xs := by
+  rcases xs with ⟨xs⟩
   simp
 
-theorem boole_getElem_le_count (a : α) (l : Array α) (i : Nat) (h : i < l.size) :
-    (if l[i] == a then 1 else 0) ≤ l.count a := by
+theorem boole_getElem_le_count (a : α) (xs : Array α) (i : Nat) (h : i < xs.size) :
+    (if xs[i] == a then 1 else 0) ≤ xs.count a := by
   rw [count_eq_countP]
   apply boole_getElem_le_countP (· == a)
 
-theorem count_set (a b : α) (l : Array α) (i : Nat) (h : i < l.size) :
-    (l.set i a).count b = l.count b - (if l[i] == b then 1 else 0) + (if a == b then 1 else 0) := by
+theorem count_set (a b : α) (xs : Array α) (i : Nat) (h : i < xs.size) :
+    (xs.set i a).count b = xs.count b - (if xs[i] == b then 1 else 0) + (if a == b then 1 else 0) := by
   simp [count_eq_countP, countP_set, h]
 
 variable [LawfulBEq α]
 
-@[simp] theorem count_push_self (a : α) (l : Array α) : count a (l.push a) = count a l + 1 := by
+@[simp] theorem count_push_self (a : α) (xs : Array α) : count a (xs.push a) = count a xs + 1 := by
   simp [count_push]
 
-@[simp] theorem count_push_of_ne (h : b ≠ a) (l : Array α) : count a (l.push b) = count a l := by
+@[simp] theorem count_push_of_ne (h : b ≠ a) (xs : Array α) : count a (xs.push b) = count a xs := by
   simp_all [count_push, h]
 
 theorem count_singleton_self (a : α) : count a #[a] = 1 := by simp
 
 @[simp]
-theorem count_pos_iff {a : α} {l : Array α} : 0 < count a l ↔ a ∈ l := by
+theorem count_pos_iff {a : α} {xs : Array α} : 0 < count a xs ↔ a ∈ xs := by
   simp only [count, countP_pos_iff, beq_iff_eq, exists_eq_right]
 
-@[simp] theorem one_le_count_iff {a : α} {l : Array α} : 1 ≤ count a l ↔ a ∈ l :=
+@[simp] theorem one_le_count_iff {a : α} {xs : Array α} : 1 ≤ count a xs ↔ a ∈ xs :=
   count_pos_iff
 
-theorem count_eq_zero_of_not_mem {a : α} {l : Array α} (h : a ∉ l) : count a l = 0 :=
+theorem count_eq_zero_of_not_mem {a : α} {xs : Array α} (h : a ∉ xs) : count a xs = 0 :=
   Decidable.byContradiction fun h' => h <| count_pos_iff.1 (Nat.pos_of_ne_zero h')
 
-theorem not_mem_of_count_eq_zero {a : α} {l : Array α} (h : count a l = 0) : a ∉ l :=
+theorem not_mem_of_count_eq_zero {a : α} {xs : Array α} (h : count a xs = 0) : a ∉ xs :=
   fun h' => Nat.ne_of_lt (count_pos_iff.2 h') h.symm
 
-theorem count_eq_zero {l : Array α} : count a l = 0 ↔ a ∉ l :=
+theorem count_eq_zero {xs : Array α} : count a xs = 0 ↔ a ∉ xs :=
   ⟨not_mem_of_count_eq_zero, count_eq_zero_of_not_mem⟩
 
-theorem count_eq_size {l : Array α} : count a l = l.size ↔ ∀ b ∈ l, a = b := by
+theorem count_eq_size {xs : Array α} : count a xs = xs.size ↔ ∀ b ∈ xs, a = b := by
   rw [count, countP_eq_size]
   refine ⟨fun h b hb => Eq.symm ?_, fun h b hb => ?_⟩
   · simpa using h b hb
   · rw [h b hb, beq_self_eq_true]
 
-@[simp] theorem count_mkArray_self (a : α) (n : Nat) : count a (mkArray n a) = n := by
+@[simp] theorem count_replicate_self (a : α) (n : Nat) : count a (replicate n a) = n := by
   simp [← List.toArray_replicate]
 
-theorem count_mkArray (a b : α) (n : Nat) : count a (mkArray n b) = if b == a then n else 0 := by
+@[deprecated count_replicate_self (since := "2025-03-18")]
+abbrev count_mkArray_self := @count_replicate_self
+
+theorem count_replicate (a b : α) (n : Nat) : count a (replicate n b) = if b == a then n else 0 := by
   simp [← List.toArray_replicate, List.count_replicate]
 
-theorem filter_beq (l : Array α) (a : α) : l.filter (· == a) = mkArray (count a l) a := by
-  cases l
+@[deprecated count_replicate (since := "2025-03-18")]
+abbrev count_mkArray := @count_replicate
+
+theorem filter_beq (xs : Array α) (a : α) : xs.filter (· == a) = replicate (count a xs) a := by
+  rcases xs with ⟨xs⟩
   simp [List.filter_beq]
 
-theorem filter_eq {α} [DecidableEq α] (l : Array α) (a : α) : l.filter (· = a) = mkArray (count a l) a :=
-  filter_beq l a
+theorem filter_eq {α} [DecidableEq α] (xs : Array α) (a : α) : xs.filter (· = a) = replicate (count a xs) a :=
+  filter_beq xs a
 
-theorem mkArray_count_eq_of_count_eq_size {l : Array α} (h : count a l = l.size) :
-    mkArray (count a l) a = l := by
-  cases l
+theorem replicate_count_eq_of_count_eq_size {xs : Array α} (h : count a xs = xs.size) :
+    replicate (count a xs) a = xs := by
+  rcases xs with ⟨xs⟩
   rw [← toList_inj]
   simp [List.replicate_count_eq_of_count_eq_length (by simpa using h)]
 
-@[simp] theorem count_filter {l : Array α} (h : p a) : count a (filter p l) = count a l := by
-  cases l
+@[deprecated replicate_count_eq_of_count_eq_size (since := "2025-03-18")]
+abbrev mkArray_count_eq_of_count_eq_size := @replicate_count_eq_of_count_eq_size
+
+@[simp] theorem count_filter {xs : Array α} (h : p a) : count a (filter p xs) = count a xs := by
+  rcases xs with ⟨xs⟩
   simp [List.count_filter, h]
 
-theorem count_le_count_map [DecidableEq β] (l : Array α) (f : α → β) (x : α) :
-    count x l ≤ count (f x) (map f l) := by
-  cases l
+theorem count_le_count_map [DecidableEq β] (xs : Array α) (f : α → β) (x : α) :
+    count x xs ≤ count (f x) (map f xs) := by
+  rcases xs with ⟨xs⟩
   simp [List.count_le_count_map, countP_map]
 
-theorem count_filterMap {α} [BEq β] (b : β) (f : α → Option β) (l : Array α) :
-    count b (filterMap f l) = countP (fun a => f a == some b) l := by
-  cases l
+theorem count_filterMap {α} [BEq β] (b : β) (f : α → Option β) (xs : Array α) :
+    count b (filterMap f xs) = countP (fun a => f a == some b) xs := by
+  rcases xs with ⟨xs⟩
   simp [List.count_filterMap, countP_filterMap]
 
-theorem count_flatMap {α} [BEq β] (l : Array α) (f : α → Array β) (x : β) :
-    count x (l.flatMap f) = sum (map (count x ∘ f) l) := by
-  simp [count_eq_countP, countP_flatMap, Function.comp_def]
+theorem count_flatMap {α} [BEq β] (xs : Array α) (f : α → Array β) (x : β) :
+    count x (xs.flatMap f) = sum (map (count x ∘ f) xs) := by
+  rcases xs with ⟨xs⟩
+  simp [List.count_flatMap, countP_flatMap, Function.comp_def]
 
 -- FIXME these theorems can be restored once `List.erase` and `Array.erase` have been related.
 

src/Init/Data/Array/DecidableEq.lean

@@ -9,6 +9,9 @@ import Init.Data.BEq
 import Init.Data.List.Nat.BEq
 import Init.ByCases
 
+set_option linter.listVariables true -- Enforce naming conventions for `List`/`Array`/`Vector` variables.
+set_option linter.indexVariables true -- Enforce naming conventions for index variables.
+
 namespace Array
 
 private theorem rel_of_isEqvAux
@@ -84,9 +87,9 @@ theorem isEqv_self [DecidableEq α] (xs : Array α) : Array.isEqv xs xs (· = ·
   simp [isEqv, isEqvAux_self]
 
 instance [DecidableEq α] : DecidableEq (Array α) :=
-  fun a b =>
-    match h:isEqv a b (fun a b => a = b) with
-    | true  => isTrue (eq_of_isEqv a b h)
+  fun xs ys =>
+    match h:isEqv xs ys (fun a b => a = b) with
+    | true  => isTrue (eq_of_isEqv xs ys h)
     | false => isFalse fun h' => by subst h'; rw [isEqv_self] at h; contradiction
 
 theorem beq_eq_decide [BEq α] (xs ys : Array α) :

src/Init/Data/Array/Erase.lean

@@ -12,19 +12,22 @@ import Init.Data.List.Nat.Basic
 # Lemmas about `Array.eraseP`, `Array.erase`, and `Array.eraseIdx`.
 -/
 
+set_option linter.listVariables true -- Enforce naming conventions for `List`/`Array`/`Vector` variables.
+set_option linter.indexVariables true -- Enforce naming conventions for index variables.
+
 namespace Array
 
 open Nat
 
 /-! ### eraseP -/
 
-@[simp] theorem eraseP_empty : #[].eraseP p = #[] := rfl
+@[simp] theorem eraseP_empty : #[].eraseP p = #[] := by simp
 
-theorem eraseP_of_forall_mem_not {l : Array α} (h : ∀ a, a ∈ l → ¬p a) : l.eraseP p = l := by
-  cases l
+theorem eraseP_of_forall_mem_not {xs : Array α} (h : ∀ a, a ∈ xs → ¬p a) : xs.eraseP p = xs := by
+  rcases xs with ⟨xs⟩
   simp_all [List.eraseP_of_forall_not]
 
-theorem eraseP_of_forall_getElem_not {l : Array α} (h : ∀ i, (h : i < l.size) → ¬p l[i]) : l.eraseP p = l :=
+theorem eraseP_of_forall_getElem_not {xs : Array α} (h : ∀ i, (h : i < xs.size) → ¬p xs[i]) : xs.eraseP p = xs :=
   eraseP_of_forall_mem_not fun a m => by
     rw [mem_iff_getElem] at m
     obtain ⟨i, w, rfl⟩ := m
@@ -37,121 +40,130 @@ theorem eraseP_of_forall_getElem_not {l : Array α} (h : ∀ i, (h : i < l.size)
 theorem eraseP_ne_empty_iff {xs : Array α} {p : α → Bool} : xs.eraseP p ≠ #[] ↔ xs ≠ #[] ∧ ∀ x, p x → xs ≠ #[x] := by
   simp
 
-theorem exists_of_eraseP {l : Array α} {a} (hm : a ∈ l) (hp : p a) :
-    ∃ a l₁ l₂, (∀ b ∈ l₁, ¬p b) ∧ p a ∧ l = l₁.push a ++ l₂ ∧ l.eraseP p = l₁ ++ l₂ := by
-  rcases l with ⟨l⟩
+theorem exists_of_eraseP {xs : Array α} {a} (hm : a ∈ xs) (hp : p a) :
+    ∃ a ys zs, (∀ b ∈ ys, ¬p b) ∧ p a ∧ xs = ys.push a ++ zs ∧ xs.eraseP p = ys ++ zs := by
+  rcases xs with ⟨xs⟩
   obtain ⟨a, l₁, l₂, h₁, h₂, rfl, h₃⟩ := List.exists_of_eraseP (by simpa using hm) (hp)
   refine ⟨a, ⟨l₁⟩, ⟨l₂⟩, by simpa using h₁, h₂, by simp, by simpa using h₃⟩
 
-theorem exists_or_eq_self_of_eraseP (p) (l : Array α) :
-    l.eraseP p = l ∨
-    ∃ a l₁ l₂, (∀ b ∈ l₁, ¬p b) ∧ p a ∧ l = l₁.push a ++ l₂ ∧ l.eraseP p = l₁ ++ l₂ :=
-  if h : ∃ a ∈ l, p a then
+theorem exists_or_eq_self_of_eraseP (p) (xs : Array α) :
+    xs.eraseP p = xs ∨
+    ∃ a ys zs, (∀ b ∈ ys, ¬p b) ∧ p a ∧ xs = ys.push a ++ zs ∧ xs.eraseP p = ys ++ zs :=
+  if h : ∃ a ∈ xs, p a then
     let ⟨_, ha, pa⟩ := h
     .inr (exists_of_eraseP ha pa)
   else
     .inl (eraseP_of_forall_mem_not (h ⟨·, ·, ·⟩))
 
-@[simp] theorem size_eraseP_of_mem {l : Array α} (al : a ∈ l) (pa : p a) :
-    (l.eraseP p).size = l.size - 1 := by
-  let ⟨_, l₁, l₂, _, _, e₁, e₂⟩ := exists_of_eraseP al pa
+@[simp] theorem size_eraseP_of_mem {xs : Array α} (al : a ∈ xs) (pa : p a) :
+    (xs.eraseP p).size = xs.size - 1 := by
+  let ⟨_, ys, zs, _, _, e₁, e₂⟩ := exists_of_eraseP al pa
   rw [e₂]; simp [size_append, e₁]; omega
 
-theorem size_eraseP {l : Array α} : (l.eraseP p).size = if l.any p then l.size - 1 else l.size := by
+theorem size_eraseP {xs : Array α} : (xs.eraseP p).size = if xs.any p then xs.size - 1 else xs.size := by
   split <;> rename_i h
   · simp only [any_eq_true] at h
     obtain ⟨i, h, w⟩ := h
-    simp [size_eraseP_of_mem (l := l) (by simp) w]
+    simp [size_eraseP_of_mem (xs := xs) (by simp) w]
   · simp only [any_eq_true] at h
     rw [eraseP_of_forall_getElem_not]
     simp_all
 
-theorem size_eraseP_le (l : Array α) : (l.eraseP p).size ≤ l.size := by
-  rcases l with ⟨l⟩
-  simpa using List.length_eraseP_le l
+theorem size_eraseP_le (xs : Array α) : (xs.eraseP p).size ≤ xs.size := by
+  rcases xs with ⟨xs⟩
+  simpa using List.length_eraseP_le xs
 
-theorem le_size_eraseP (l : Array α) : l.size - 1 ≤ (l.eraseP p).size := by
-  rcases l with ⟨l⟩
-  simpa using List.le_length_eraseP l
+theorem le_size_eraseP (xs : Array α) : xs.size - 1 ≤ (xs.eraseP p).size := by
+  rcases xs with ⟨xs⟩
+  simpa using List.le_length_eraseP xs
 
-theorem mem_of_mem_eraseP {l : Array α} : a ∈ l.eraseP p → a ∈ l := by
-  rcases l with ⟨l⟩
+theorem mem_of_mem_eraseP {xs : Array α} : a ∈ xs.eraseP p → a ∈ xs := by
+  rcases xs with ⟨xs⟩
   simpa using List.mem_of_mem_eraseP
 
-@[simp] theorem mem_eraseP_of_neg {l : Array α} (pa : ¬p a) : a ∈ l.eraseP p ↔ a ∈ l := by
-  rcases l with ⟨l⟩
+@[simp] theorem mem_eraseP_of_neg {xs : Array α} (pa : ¬p a) : a ∈ xs.eraseP p ↔ a ∈ xs := by
+  rcases xs with ⟨xs⟩
   simpa using List.mem_eraseP_of_neg pa
 
-@[simp] theorem eraseP_eq_self_iff {p} {l : Array α} : l.eraseP p = l ↔ ∀ a ∈ l, ¬ p a := by
-  rcases l with ⟨l⟩
+@[simp] theorem eraseP_eq_self_iff {xs : Array α} : xs.eraseP p = xs ↔ ∀ a ∈ xs, ¬ p a := by
+  rcases xs with ⟨xs⟩
   simp
 
-theorem eraseP_map (f : β → α) (l : Array β) : (map f l).eraseP p = map f (l.eraseP (p ∘ f)) := by
-  rcases l with ⟨l⟩
-  simpa using List.eraseP_map f l
+theorem eraseP_map (f : β → α) (xs : Array β) : (xs.map f).eraseP p = (xs.eraseP (p ∘ f)).map f := by
+  rcases xs with ⟨xs⟩
+  simpa using List.eraseP_map f xs
 
-theorem eraseP_filterMap (f : α → Option β) (l : Array α) :
-    (filterMap f l).eraseP p = filterMap f (l.eraseP (fun x => match f x with | some y => p y | none => false)) := by
-  rcases l with ⟨l⟩
-  simpa using List.eraseP_filterMap f l
+theorem eraseP_filterMap (f : α → Option β) (xs : Array α) :
+    (filterMap f xs).eraseP p = filterMap f (xs.eraseP (fun x => match f x with | some y => p y | none => false)) := by
+  rcases xs with ⟨xs⟩
+  simpa using List.eraseP_filterMap f xs
 
-theorem eraseP_filter (f : α → Bool) (l : Array α) :
-    (filter f l).eraseP p = filter f (l.eraseP (fun x => p x && f x)) := by
-  rcases l with ⟨l⟩
-  simpa using List.eraseP_filter f l
+theorem eraseP_filter (f : α → Bool) (xs : Array α) :
+    (filter f xs).eraseP p = filter f (xs.eraseP (fun x => p x && f x)) := by
+  rcases xs with ⟨xs⟩
+  simpa using List.eraseP_filter f xs
 
-theorem eraseP_append_left {a : α} (pa : p a) {l₁ : Array α} l₂ (h : a ∈ l₁) :
-    (l₁ ++ l₂).eraseP p = l₁.eraseP p ++ l₂ := by
-  rcases l₁ with ⟨l₁⟩
-  rcases l₂ with ⟨l₂⟩
-  simpa using List.eraseP_append_left pa l₂ (by simpa using h)
+theorem eraseP_append_left {a : α} (pa : p a) {xs : Array α} {ys : Array α} (h : a ∈ xs) :
+    (xs ++ ys).eraseP p = xs.eraseP p ++ ys := by
+  rcases xs with ⟨xs⟩
+  rcases ys with ⟨ys⟩
+  simpa using List.eraseP_append_left pa ys (by simpa using h)
 
-theorem eraseP_append_right {l₁ : Array α} l₂ (h : ∀ b ∈ l₁, ¬p b) :
-    (l₁ ++ l₂).eraseP p = l₁ ++ l₂.eraseP p := by
-  rcases l₁ with ⟨l₁⟩
-  rcases l₂ with ⟨l₂⟩
-  simpa using List.eraseP_append_right l₂ (by simpa using h)
+theorem eraseP_append_right {xs : Array α} ys (h : ∀ b ∈ xs, ¬p b) :
+    (xs ++ ys).eraseP p = xs ++ ys.eraseP p := by
+  rcases xs with ⟨xs⟩
+  rcases ys with ⟨ys⟩
+  simpa using List.eraseP_append_right ys (by simpa using h)
 
-theorem eraseP_append (l₁ l₂ : Array α) :
-    (l₁ ++ l₂).eraseP p = if l₁.any p then l₁.eraseP p ++ l₂ else l₁ ++ l₂.eraseP p := by
-  rcases l₁ with ⟨l₁⟩
-  rcases l₂ with ⟨l₂⟩
-  simp only [List.append_toArray, List.eraseP_toArray, List.eraseP_append l₁ l₂, List.any_toArray']
+theorem eraseP_append {xs : Array α} {ys : Array α} :
+    (xs ++ ys).eraseP p = if xs.any p then xs.eraseP p ++ ys else xs ++ ys.eraseP p := by
+  rcases xs with ⟨xs⟩
+  rcases ys with ⟨ys⟩
+  simp only [List.append_toArray, List.eraseP_toArray, List.eraseP_append, List.any_toArray]
   split <;> simp
 
-theorem eraseP_mkArray (n : Nat) (a : α) (p : α → Bool) :
-    (mkArray n a).eraseP p = if p a then mkArray (n - 1) a else mkArray n a := by
+theorem eraseP_replicate (n : Nat) (a : α) (p : α → Bool) :
+    (replicate n a).eraseP p = if p a then replicate (n - 1) a else replicate n a := by
   simp only [← List.toArray_replicate, List.eraseP_toArray, List.eraseP_replicate]
   split <;> simp
 
-@[simp] theorem eraseP_mkArray_of_pos {n : Nat} {a : α} (h : p a) :
-    (mkArray n a).eraseP p = mkArray (n - 1) a := by
+@[deprecated eraseP_replicate (since := "2025-03-18")]
+abbrev eraseP_mkArray := @eraseP_replicate
+
+@[simp] theorem eraseP_replicate_of_pos {n : Nat} {a : α} (h : p a) :
+    (replicate n a).eraseP p = replicate (n - 1) a := by
   simp only [← List.toArray_replicate, List.eraseP_toArray]
   simp [h]
 
-@[simp] theorem eraseP_mkArray_of_neg {n : Nat} {a : α} (h : ¬p a) :
-    (mkArray n a).eraseP p = mkArray n a := by
+@[deprecated eraseP_replicate_of_pos (since := "2025-03-18")]
+abbrev eraseP_mkArray_of_pos := @eraseP_replicate_of_pos
+
+@[simp] theorem eraseP_replicate_of_neg {n : Nat} {a : α} (h : ¬p a) :
+    (replicate n a).eraseP p = replicate n a := by
   simp only [← List.toArray_replicate, List.eraseP_toArray]
   simp [h]
 
-theorem eraseP_eq_iff {p} {l : Array α} :
-    l.eraseP p = l' ↔
-      ((∀ a ∈ l, ¬ p a) ∧ l = l') ∨
-        ∃ a l₁ l₂, (∀ b ∈ l₁, ¬ p b) ∧ p a ∧ l = l₁.push a ++ l₂ ∧ l' = l₁ ++ l₂ := by
-  rcases l with ⟨l⟩
-  rcases l' with ⟨l'⟩
+@[deprecated eraseP_replicate_of_neg (since := "2025-03-18")]
+abbrev eraseP_mkArray_of_neg := @eraseP_replicate_of_neg
+
+theorem eraseP_eq_iff {p} {xs : Array α} :
+    xs.eraseP p = ys ↔
+      ((∀ a ∈ xs, ¬ p a) ∧ xs = ys) ∨
+        ∃ a as bs, (∀ b ∈ as, ¬ p b) ∧ p a ∧ xs = as.push a ++ bs ∧ ys = as ++ bs := by
+  rcases xs with ⟨l⟩
+  rcases ys with ⟨ys⟩
   simp [List.eraseP_eq_iff]
   constructor
-  · rintro (h | ⟨a, l₁, h₁, h₂, ⟨x, rfl, rfl⟩⟩)
+  · rintro (h | ⟨a, l₁, h₁, h₂, ⟨l, rfl, rfl⟩⟩)
     · exact Or.inl h
-    · exact Or.inr ⟨a, ⟨l₁⟩, by simpa using h₁, h₂, ⟨⟨x⟩, by simp⟩⟩
-  · rintro (h | ⟨a, ⟨l₁⟩, h₁, h₂, ⟨⟨x⟩, rfl, rfl⟩⟩)
+    · exact Or.inr ⟨a, ⟨l₁⟩, by simpa using h₁, h₂, ⟨⟨l⟩, by simp⟩⟩
+  · rintro (h | ⟨a, ⟨l₁⟩, h₁, h₂, ⟨⟨l⟩, rfl, rfl⟩⟩)
     · exact Or.inl h
-    · exact Or.inr ⟨a, l₁, by simpa using h₁, h₂, ⟨x, by simp⟩⟩
+    · exact Or.inr ⟨a, l₁, by simpa using h₁, h₂, ⟨l, by simp⟩⟩
 
-theorem eraseP_comm {l : Array α} (h : ∀ a ∈ l, ¬ p a ∨ ¬ q a) :
-    (l.eraseP p).eraseP q = (l.eraseP q).eraseP p := by
-  rcases l with ⟨l⟩
+theorem eraseP_comm {xs : Array α} (h : ∀ a ∈ xs, ¬ p a ∨ ¬ q a) :
+    (xs.eraseP p).eraseP q = (xs.eraseP q).eraseP p := by
+  rcases xs with ⟨xs⟩
   simpa using List.eraseP_comm (by simpa using h)
 
 /-! ### erase -/
@@ -159,16 +171,16 @@ theorem eraseP_comm {l : Array α} (h : ∀ a ∈ l, ¬ p a ∨ ¬ q a) :
 section erase
 variable [BEq α]
 
-theorem erase_of_not_mem [LawfulBEq α] {a : α} {l : Array α} (h : a ∉ l) : l.erase a = l := by
-  rcases l with ⟨l⟩
+theorem erase_of_not_mem [LawfulBEq α] {a : α} {xs : Array α} (h : a ∉ xs) : xs.erase a = xs := by
+  rcases xs with ⟨xs⟩
   simp [List.erase_of_not_mem (by simpa using h)]
 
-theorem erase_eq_eraseP' (a : α) (l : Array α) : l.erase a = l.eraseP (· == a) := by
-  rcases l with ⟨l⟩
+theorem erase_eq_eraseP' (a : α) (xs : Array α) : xs.erase a = xs.eraseP (· == a) := by
+  rcases xs with ⟨xs⟩
   simp [List.erase_eq_eraseP']
 
-theorem erase_eq_eraseP [LawfulBEq α] (a : α) (l : Array α) : l.erase a = l.eraseP (a == ·) := by
-  rcases l with ⟨l⟩
+theorem erase_eq_eraseP [LawfulBEq α] (a : α) (xs : Array α) : xs.erase a = xs.eraseP (a == ·) := by
+  rcases xs with ⟨xs⟩
   simp [List.erase_eq_eraseP]
 
 @[simp] theorem erase_eq_empty_iff [LawfulBEq α] {xs : Array α} {a : α} :
@@ -181,106 +193,119 @@ theorem erase_ne_empty_iff [LawfulBEq α] {xs : Array α} {a : α} :
   rcases xs with ⟨xs⟩
   simp [List.erase_ne_nil_iff]
 
-theorem exists_erase_eq [LawfulBEq α] {a : α} {l : Array α} (h : a ∈ l) :
-    ∃ l₁ l₂, a ∉ l₁ ∧ l = l₁.push a ++ l₂ ∧ l.erase a = l₁ ++ l₂ := by
-  let ⟨_, l₁, l₂, h₁, e, h₂, h₃⟩ := exists_of_eraseP h (beq_self_eq_true _)
-  rw [erase_eq_eraseP]; exact ⟨l₁, l₂, fun h => h₁ _ h (beq_self_eq_true _), eq_of_beq e ▸ h₂, h₃⟩
+theorem exists_erase_eq [LawfulBEq α] {a : α} {xs : Array α} (h : a ∈ xs) :
+    ∃ ys zs, a ∉ ys ∧ xs = ys.push a ++ zs ∧ xs.erase a = ys ++ zs := by
+  let ⟨_, ys, zs, h₁, e, h₂, h₃⟩ := exists_of_eraseP h (beq_self_eq_true _)
+  rw [erase_eq_eraseP]; exact ⟨ys, zs, fun h => h₁ _ h (beq_self_eq_true _), eq_of_beq e ▸ h₂, h₃⟩
 
-@[simp] theorem size_erase_of_mem [LawfulBEq α] {a : α} {l : Array α} (h : a ∈ l) :
-    (l.erase a).size = l.size - 1 := by
+@[simp] theorem size_erase_of_mem [LawfulBEq α] {a : α} {xs : Array α} (h : a ∈ xs) :
+    (xs.erase a).size = xs.size - 1 := by
   rw [erase_eq_eraseP]; exact size_eraseP_of_mem h (beq_self_eq_true a)
 
-theorem size_erase [LawfulBEq α] (a : α) (l : Array α) :
-    (l.erase a).size = if a ∈ l then l.size - 1 else l.size := by
+theorem size_erase [LawfulBEq α] (a : α) (xs : Array α) :
+    (xs.erase a).size = if a ∈ xs then xs.size - 1 else xs.size := by
   rw [erase_eq_eraseP, size_eraseP]
   congr
   simp [mem_iff_getElem, eq_comm (a := a)]
 
-theorem size_erase_le (a : α) (l : Array α) : (l.erase a).size ≤ l.size := by
-  rcases l with ⟨l⟩
-  simpa using List.length_erase_le a l
+theorem size_erase_le (a : α) (xs : Array α) : (xs.erase a).size ≤ xs.size := by
+  rcases xs with ⟨xs⟩
+  simpa using List.length_erase_le a xs
 
-theorem le_size_erase [LawfulBEq α] (a : α) (l : Array α) : l.size - 1 ≤ (l.erase a).size := by
-  rcases l with ⟨l⟩
-  simpa using List.le_length_erase a l
+theorem le_size_erase [LawfulBEq α] (a : α) (xs : Array α) : xs.size - 1 ≤ (xs.erase a).size := by
+  rcases xs with ⟨xs⟩
+  simpa using List.le_length_erase a xs
 
-theorem mem_of_mem_erase {a b : α} {l : Array α} (h : a ∈ l.erase b) : a ∈ l := by
-  rcases l with ⟨l⟩
+theorem mem_of_mem_erase {a b : α} {xs : Array α} (h : a ∈ xs.erase b) : a ∈ xs := by
+  rcases xs with ⟨xs⟩
   simpa using List.mem_of_mem_erase (by simpa using h)
 
-@[simp] theorem mem_erase_of_ne [LawfulBEq α] {a b : α} {l : Array α} (ab : a ≠ b) :
-    a ∈ l.erase b ↔ a ∈ l :=
-  erase_eq_eraseP b l ▸ mem_eraseP_of_neg (mt eq_of_beq ab.symm)
+@[simp] theorem mem_erase_of_ne [LawfulBEq α] {a b : α} {xs : Array α} (ab : a ≠ b) :
+    a ∈ xs.erase b ↔ a ∈ xs :=
+  erase_eq_eraseP b xs ▸ mem_eraseP_of_neg (mt eq_of_beq ab.symm)
 
-@[simp] theorem erase_eq_self_iff [LawfulBEq α] {l : Array α} : l.erase a = l ↔ a ∉ l := by
+@[simp] theorem erase_eq_self_iff [LawfulBEq α] {xs : Array α} : xs.erase a = xs ↔ a ∉ xs := by
   rw [erase_eq_eraseP', eraseP_eq_self_iff]
   simp [forall_mem_ne']
 
-theorem erase_filter [LawfulBEq α] (f : α → Bool) (l : Array α) :
-    (filter f l).erase a = filter f (l.erase a) := by
-  rcases l with ⟨l⟩
-  simpa using List.erase_filter f l
+theorem erase_filter [LawfulBEq α] (f : α → Bool) (xs : Array α) :
+    (filter f xs).erase a = filter f (xs.erase a) := by
+  rcases xs with ⟨xs⟩
+  simpa using List.erase_filter f xs
 
-theorem erase_append_left [LawfulBEq α] {l₁ : Array α} (l₂) (h : a ∈ l₁) :
-    (l₁ ++ l₂).erase a = l₁.erase a ++ l₂ := by
-  rcases l₁ with ⟨l₁⟩
-  rcases l₂ with ⟨l₂⟩
-  simpa using List.erase_append_left l₂ (by simpa using h)
+theorem erase_append_left [LawfulBEq α] {xs : Array α} (ys) (h : a ∈ xs) :
+    (xs ++ ys).erase a = xs.erase a ++ ys := by
+  rcases xs with ⟨xs⟩
+  rcases ys with ⟨ys⟩
+  simpa using List.erase_append_left ys (by simpa using h)
 
-theorem erase_append_right [LawfulBEq α] {a : α} {l₁ : Array α} (l₂ : Array α) (h : a ∉ l₁) :
-    (l₁ ++ l₂).erase a = (l₁ ++ l₂.erase a) := by
-  rcases l₁ with ⟨l₁⟩
-  rcases l₂ with ⟨l₂⟩
-  simpa using List.erase_append_right l₂ (by simpa using h)
+theorem erase_append_right [LawfulBEq α] {a : α} {xs : Array α} (ys : Array α) (h : a ∉ xs) :
+    (xs ++ ys).erase a = (xs ++ ys.erase a) := by
+  rcases xs with ⟨xs⟩
+  rcases ys with ⟨ys⟩
+  simpa using List.erase_append_right ys (by simpa using h)
 
-theorem erase_append [LawfulBEq α] {a : α} {l₁ l₂ : Array α} :
-    (l₁ ++ l₂).erase a = if a ∈ l₁ then l₁.erase a ++ l₂ else l₁ ++ l₂.erase a := by
-  rcases l₁ with ⟨l₁⟩
-  rcases l₂ with ⟨l₂⟩
+theorem erase_append [LawfulBEq α] {a : α} {xs ys : Array α} :
+    (xs ++ ys).erase a = if a ∈ xs then xs.erase a ++ ys else xs ++ ys.erase a := by
+  rcases xs with ⟨xs⟩
+  rcases ys with ⟨ys⟩
   simp only [List.append_toArray, List.erase_toArray, List.erase_append, mem_toArray]
   split <;> simp
 
-theorem erase_mkArray [LawfulBEq α] (n : Nat) (a b : α) :
-    (mkArray n a).erase b = if b == a then mkArray (n - 1) a else mkArray n a := by
+theorem erase_replicate [LawfulBEq α] (n : Nat) (a b : α) :
+    (replicate n a).erase b = if b == a then replicate (n - 1) a else replicate n a := by
   simp only [← List.toArray_replicate, List.erase_toArray]
   simp only [List.erase_replicate, beq_iff_eq, List.toArray_replicate]
   split <;> simp
 
-theorem erase_comm [LawfulBEq α] (a b : α) (l : Array α) :
-    (l.erase a).erase b = (l.erase b).erase a := by
-  rcases l with ⟨l⟩
-  simpa using List.erase_comm a b l
+@[deprecated erase_replicate (since := "2025-03-18")]
+abbrev erase_mkArray := @erase_replicate
 
-theorem erase_eq_iff [LawfulBEq α] {a : α} {l : Array α} :
-    l.erase a = l' ↔
-      (a ∉ l ∧ l = l') ∨
-        ∃ l₁ l₂, a ∉ l₁ ∧ l = l₁.push a ++ l₂ ∧ l' = l₁ ++ l₂ := by
+theorem erase_comm [LawfulBEq α] (a b : α) (xs : Array α) :
+    (xs.erase a).erase b = (xs.erase b).erase a := by
+  rcases xs with ⟨xs⟩
+  simpa using List.erase_comm a b xs
+
+theorem erase_eq_iff [LawfulBEq α] {a : α} {xs : Array α} :
+    xs.erase a = ys ↔
+      (a ∉ xs ∧ xs = ys) ∨
+        ∃ as bs, a ∉ as ∧ xs = as.push a ++ bs ∧ ys = as ++ bs := by
   rw [erase_eq_eraseP', eraseP_eq_iff]
   simp only [beq_iff_eq, forall_mem_ne', exists_and_left]
   constructor
-  · rintro (⟨h, rfl⟩ | ⟨a', l', h, rfl, x, rfl, rfl⟩)
+  · rintro (⟨h, rfl⟩ | ⟨a', as, h, rfl, bs, rfl, rfl⟩)
     · left; simp_all
-    · right; refine ⟨l', h, x, by simp⟩
-  · rintro (⟨h, rfl⟩ | ⟨l₁, h, x, rfl, rfl⟩)
+    · right; refine ⟨as, h, bs, by simp⟩
+  · rintro (⟨h, rfl⟩ | ⟨as, h, bs, rfl, rfl⟩)
     · left; simp_all
-    · right; refine ⟨a, l₁, h, rfl, x, by simp⟩
+    · right; refine ⟨a, as, h, rfl, bs, by simp⟩
 
-@[simp] theorem erase_mkArray_self [LawfulBEq α] {a : α} :
-    (mkArray n a).erase a = mkArray (n - 1) a := by
+@[simp] theorem erase_replicate_self [LawfulBEq α] {a : α} :
+    (replicate n a).erase a = replicate (n - 1) a := by
   simp only [← List.toArray_replicate, List.erase_toArray]
   simp [List.erase_replicate]
 
-@[simp] theorem erase_mkArray_ne [LawfulBEq α] {a b : α} (h : !b == a) :
-    (mkArray n a).erase b = mkArray n a := by
+@[deprecated erase_replicate_self (since := "2025-03-18")]
+abbrev erase_mkArray_self := @erase_replicate_self
+
+@[simp] theorem erase_replicate_ne [LawfulBEq α] {a b : α} (h : !b == a) :
+    (replicate n a).erase b = replicate n a := by
   rw [erase_of_not_mem]
   simp_all
 
+@[deprecated erase_replicate_ne (since := "2025-03-18")]
+abbrev erase_mkArray_ne := @erase_replicate_ne
+
 end erase
 
 /-! ### eraseIdx -/
 
-theorem eraseIdx_eq_take_drop_succ (l : Array α) (i : Nat) (h) : l.eraseIdx i = l.take i ++ l.drop (i + 1) := by
-  rcases l with ⟨l⟩
+theorem eraseIdx_eq_eraseIdxIfInBounds {xs : Array α} {i : Nat} (h : i < xs.size) :
+    xs.eraseIdx i h = xs.eraseIdxIfInBounds i := by
+  simp [eraseIdxIfInBounds, h]
+
+theorem eraseIdx_eq_take_drop_succ (xs : Array α) (i : Nat) (h) : xs.eraseIdx i = xs.take i ++ xs.drop (i + 1) := by
+  rcases xs with ⟨xs⟩
   simp only [List.size_toArray] at h
   simp only [List.eraseIdx_toArray, List.eraseIdx_eq_take_drop_succ, take_eq_extract,
     List.extract_toArray, List.extract_eq_drop_take, Nat.sub_zero, List.drop_zero, drop_eq_extract,
@@ -288,113 +313,116 @@ theorem eraseIdx_eq_take_drop_succ (l : Array α) (i : Nat) (h) : l.eraseIdx i =
   rw [List.take_of_length_le]
   simp
 
-theorem getElem?_eraseIdx (l : Array α) (i : Nat) (h : i < l.size) (j : Nat) :
-    (l.eraseIdx i)[j]? = if j < i then l[j]? else l[j + 1]? := by
-  rcases l with ⟨l⟩
+theorem getElem?_eraseIdx (xs : Array α) (i : Nat) (h : i < xs.size) (j : Nat) :
+    (xs.eraseIdx i)[j]? = if j < i then xs[j]? else xs[j + 1]? := by
+  rcases xs with ⟨xs⟩
   simp [List.getElem?_eraseIdx]
 
-theorem getElem?_eraseIdx_of_lt (l : Array α) (i : Nat) (h : i < l.size) (j : Nat) (h' : j < i) :
-    (l.eraseIdx i)[j]? = l[j]? := by
+theorem getElem?_eraseIdx_of_lt (xs : Array α) (i : Nat) (h : i < xs.size) (j : Nat) (h' : j < i) :
+    (xs.eraseIdx i)[j]? = xs[j]? := by
   rw [getElem?_eraseIdx]
   simp [h']
 
-theorem getElem?_eraseIdx_of_ge (l : Array α) (i : Nat) (h : i < l.size) (j : Nat) (h' : i ≤ j) :
-    (l.eraseIdx i)[j]? = l[j + 1]? := by
+theorem getElem?_eraseIdx_of_ge (xs : Array α) (i : Nat) (h : i < xs.size) (j : Nat) (h' : i ≤ j) :
+    (xs.eraseIdx i)[j]? = xs[j + 1]? := by
   rw [getElem?_eraseIdx]
   simp only [dite_eq_ite, ite_eq_right_iff]
   intro h'
   omega
 
-theorem getElem_eraseIdx (l : Array α) (i : Nat) (h : i < l.size) (j : Nat) (h' : j < (l.eraseIdx i).size) :
-    (l.eraseIdx i)[j] = if h'' : j < i then
-        l[j]
+theorem getElem_eraseIdx (xs : Array α) (i : Nat) (h : i < xs.size) (j : Nat) (h' : j < (xs.eraseIdx i).size) :
+    (xs.eraseIdx i)[j] = if h'' : j < i then
+        xs[j]
       else
-        l[j + 1]'(by rw [size_eraseIdx] at h'; omega) := by
+        xs[j + 1]'(by rw [size_eraseIdx] at h'; omega) := by
   apply Option.some.inj
   rw [← getElem?_eq_getElem, getElem?_eraseIdx]
   split <;> simp
 
-@[simp] theorem eraseIdx_eq_empty_iff {l : Array α} {i : Nat} {h} : eraseIdx l i = #[] ↔ l.size = 1 ∧ i = 0 := by
-  rcases l with ⟨l⟩
+@[simp] theorem eraseIdx_eq_empty_iff {xs : Array α} {i : Nat} {h} : xs.eraseIdx i = #[] ↔ xs.size = 1 ∧ i = 0 := by
+  rcases xs with ⟨xs⟩
   simp only [List.eraseIdx_toArray, mk.injEq, List.eraseIdx_eq_nil_iff, List.size_toArray,
     or_iff_right_iff_imp]
   rintro rfl
   simp_all
 
-theorem eraseIdx_ne_empty_iff {l : Array α} {i : Nat} {h} : eraseIdx l i ≠ #[] ↔ 2 ≤ l.size := by
-  rcases l with ⟨_ | ⟨a, (_ | ⟨b, l⟩)⟩⟩
+theorem eraseIdx_ne_empty_iff {xs : Array α} {i : Nat} {h} : xs.eraseIdx i ≠ #[] ↔ 2 ≤ xs.size := by
+  rcases xs with ⟨_ | ⟨a, (_ | ⟨b, l⟩)⟩⟩
   · simp
   · simp at h
     simp [h]
   · simp
 
-theorem mem_of_mem_eraseIdx {l : Array α} {i : Nat} {h} {a : α} (h : a ∈ l.eraseIdx i) : a ∈ l := by
-  rcases l with ⟨l⟩
+theorem mem_of_mem_eraseIdx {xs : Array α} {i : Nat} {h} {a : α} (h : a ∈ xs.eraseIdx i) : a ∈ xs := by
+  rcases xs with ⟨xs⟩
   simpa using List.mem_of_mem_eraseIdx (by simpa using h)
 
-theorem eraseIdx_append_of_lt_size {l : Array α} {k : Nat} (hk : k < l.size) (l' : Array α) (h) :
-    eraseIdx (l ++ l') k = eraseIdx l k ++ l' := by
-  rcases l with ⟨l⟩
-  rcases l' with ⟨l'⟩
+theorem eraseIdx_append_of_lt_size {xs : Array α} {k : Nat} (hk : k < xs.size) (ys : Array α) (h) :
+    eraseIdx (xs ++ ys) k = eraseIdx xs k ++ ys := by
+  rcases xs with ⟨l⟩
+  rcases ys with ⟨l'⟩
   simp at hk
   simp [List.eraseIdx_append_of_lt_length, *]
 
-theorem eraseIdx_append_of_length_le {l : Array α} {k : Nat} (hk : l.size ≤ k) (l' : Array α) (h) :
-    eraseIdx (l ++ l') k = l ++ eraseIdx l' (k - l.size) (by simp at h; omega) := by
-  rcases l with ⟨l⟩
-  rcases l' with ⟨l'⟩
+theorem eraseIdx_append_of_length_le {xs : Array α} {k : Nat} (hk : xs.size ≤ k) (ys : Array α) (h) :
+    eraseIdx (xs ++ ys) k = xs ++ eraseIdx ys (k - xs.size) (by simp at h; omega) := by
+  rcases xs with ⟨l⟩
+  rcases ys with ⟨l'⟩
   simp at hk
   simp [List.eraseIdx_append_of_length_le, *]
 
-theorem eraseIdx_mkArray {n : Nat} {a : α} {k : Nat} {h} :
-    (mkArray n a).eraseIdx k = mkArray (n - 1) a := by
+theorem eraseIdx_replicate {n : Nat} {a : α} {k : Nat} {h} :
+    (replicate n a).eraseIdx k = replicate (n - 1) a := by
   simp at h
   simp only [← List.toArray_replicate, List.eraseIdx_toArray]
   simp [List.eraseIdx_replicate, h]
 
-theorem mem_eraseIdx_iff_getElem {x : α} {l} {k} {h} : x ∈ eraseIdx l k h ↔ ∃ i w, i ≠ k ∧ l[i]'w = x := by
-  rcases l with ⟨l⟩
+@[deprecated eraseIdx_replicate (since := "2025-03-18")]
+abbrev eraseIdx_mkArray := @eraseIdx_replicate
+
+theorem mem_eraseIdx_iff_getElem {x : α} {xs : Array α} {k} {h} : x ∈ xs.eraseIdx k h ↔ ∃ i w, i ≠ k ∧ xs[i]'w = x := by
+  rcases xs with ⟨xs⟩
   simp [List.mem_eraseIdx_iff_getElem, *]
 
-theorem mem_eraseIdx_iff_getElem? {x : α} {l} {k} {h} : x ∈ eraseIdx l k h ↔ ∃ i ≠ k, l[i]? = some x := by
-  rcases l with ⟨l⟩
+theorem mem_eraseIdx_iff_getElem? {x : α} {xs : Array α} {k} {h} : x ∈ xs.eraseIdx k h ↔ ∃ i ≠ k, xs[i]? = some x := by
+  rcases xs with ⟨xs⟩
   simp [List.mem_eraseIdx_iff_getElem?, *]
 
-theorem erase_eq_eraseIdx_of_idxOf [BEq α] [LawfulBEq α] (l : Array α) (a : α) (i : Nat) (w : l.idxOf a = i) (h : i < l.size) :
-    l.erase a = l.eraseIdx i := by
-  rcases l with ⟨l⟩
+theorem erase_eq_eraseIdx_of_idxOf [BEq α] [LawfulBEq α] (xs : Array α) (a : α) (i : Nat) (w : xs.idxOf a = i) (h : i < xs.size) :
+    xs.erase a = xs.eraseIdx i := by
+  rcases xs with ⟨xs⟩
   simp at w
   simp [List.erase_eq_eraseIdx_of_idxOf, *]
 
-theorem getElem_eraseIdx_of_lt (l : Array α) (i : Nat) (w : i < l.size) (j : Nat) (h : j < (l.eraseIdx i).size) (h' : j < i) :
-    (l.eraseIdx i)[j] = l[j] := by
-  rcases l with ⟨l⟩
+theorem getElem_eraseIdx_of_lt (xs : Array α) (i : Nat) (w : i < xs.size) (j : Nat) (h : j < (xs.eraseIdx i).size) (h' : j < i) :
+    (xs.eraseIdx i)[j] = xs[j] := by
+  rcases xs with ⟨xs⟩
   simp [List.getElem_eraseIdx_of_lt, *]
 
-theorem getElem_eraseIdx_of_ge (l : Array α) (i : Nat) (w : i < l.size) (j : Nat) (h : j < (l.eraseIdx i).size) (h' : i ≤ j) :
-    (l.eraseIdx i)[j] = l[j + 1]'(by simp at h; omega) := by
-  rcases l with ⟨l⟩
+theorem getElem_eraseIdx_of_ge (xs : Array α) (i : Nat) (w : i < xs.size) (j : Nat) (h : j < (xs.eraseIdx i).size) (h' : i ≤ j) :
+    (xs.eraseIdx i)[j] = xs[j + 1]'(by simp at h; omega) := by
+  rcases xs with ⟨xs⟩
   simp [List.getElem_eraseIdx_of_ge, *]
 
-theorem eraseIdx_set_eq {l : Array α} {i : Nat} {a : α} {h : i < l.size} :
-    (l.set i a).eraseIdx i (by simp; omega) = l.eraseIdx i := by
-  rcases l with ⟨l⟩
+theorem eraseIdx_set_eq {xs : Array α} {i : Nat} {a : α} {h : i < xs.size} :
+    (xs.set i a).eraseIdx i (by simp; omega) = xs.eraseIdx i := by
+  rcases xs with ⟨xs⟩
   simp [List.eraseIdx_set_eq, *]
 
-theorem eraseIdx_set_lt {l : Array α} {i : Nat} {w : i < l.size} {j : Nat} {a : α} (h : j < i) :
-    (l.set i a).eraseIdx j (by simp; omega) = (l.eraseIdx j).set (i - 1) a (by simp; omega) := by
-  rcases l with ⟨l⟩
+theorem eraseIdx_set_lt {xs : Array α} {i : Nat} {w : i < xs.size} {j : Nat} {a : α} (h : j < i) :
+    (xs.set i a).eraseIdx j (by simp; omega) = (xs.eraseIdx j).set (i - 1) a (by simp; omega) := by
+  rcases xs with ⟨xs⟩
   simp [List.eraseIdx_set_lt, *]
 
-theorem eraseIdx_set_gt {l : Array α} {i : Nat} {j : Nat} {a : α} (h : i < j) {w : j < l.size} :
-    (l.set i a).eraseIdx j (by simp; omega) = (l.eraseIdx j).set i a (by simp; omega) := by
-  rcases l with ⟨l⟩
+theorem eraseIdx_set_gt {xs : Array α} {i : Nat} {j : Nat} {a : α} (h : i < j) {w : j < xs.size} :
+    (xs.set i a).eraseIdx j (by simp; omega) = (xs.eraseIdx j).set i a (by simp; omega) := by
+  rcases xs with ⟨xs⟩
   simp [List.eraseIdx_set_gt, *]
 
 @[simp] theorem set_getElem_succ_eraseIdx_succ
-    {l : Array α} {i : Nat} (h : i + 1 < l.size) :
-    (l.eraseIdx (i + 1)).set i l[i + 1] (by simp; omega) = l.eraseIdx i := by
-  rcases l with ⟨l⟩
+    {xs : Array α} {i : Nat} (h : i + 1 < xs.size) :
+    (xs.eraseIdx (i + 1)).set i xs[i + 1] (by simp; omega) = xs.eraseIdx i := by
+  rcases xs with ⟨xs⟩
   simp [List.set_getElem_succ_eraseIdx_succ, *]
 
 end Array

src/Init/Data/Array/Extract.lean

@@ -13,6 +13,9 @@ import Init.Data.List.Nat.TakeDrop
 This file follows the contents of `Init.Data.List.TakeDrop` and `Init.Data.List.Nat.TakeDrop`.
 -/
 
+set_option linter.listVariables true -- Enforce naming conventions for `List`/`Array`/`Vector` variables.
+set_option linter.indexVariables true -- Enforce naming conventions for index variables.
+
 open Nat
 namespace Array
 
@@ -246,12 +249,15 @@ theorem extract_append_left {as bs : Array α} :
   · simp only [size_map, size_extract] at h₁ h₂
     simp only [getElem_map, getElem_extract]
 
-@[simp] theorem extract_mkArray {a : α} {n i j : Nat} :
-    (mkArray n a).extract i j = mkArray (min j n - i) a := by
+@[simp] theorem extract_replicate {a : α} {n i j : Nat} :
+    (replicate n a).extract i j = replicate (min j n - i) a := by
   ext l h₁ h₂
   · simp
-  · simp only [size_extract, size_mkArray] at h₁ h₂
-    simp only [getElem_extract, getElem_mkArray]
+  · simp only [size_extract, size_replicate] at h₁ h₂
+    simp only [getElem_extract, getElem_replicate]
+
+@[deprecated extract_replicate (since := "2025-03-18")]
+abbrev extract_mkArray := @extract_replicate
 
 theorem extract_eq_extract_right {as : Array α} {i j j' : Nat} :
     as.extract i j = as.extract i j' ↔ min (j - i) (as.size - i) = min (j' - i) (as.size - i) := by
@@ -354,10 +360,10 @@ theorem takeWhile_append {xs ys : Array α} :
   simp only [List.append_toArray, List.takeWhile_toArray, List.takeWhile_append, List.size_toArray]
   split <;> rfl
 
-@[simp] theorem takeWhile_append_of_pos {p : α → Bool} {l₁ l₂ : Array α} (h : ∀ a ∈ l₁, p a) :
-    (l₁ ++ l₂).takeWhile p = l₁ ++ l₂.takeWhile p := by
-  rcases l₁ with ⟨l₁⟩
-  rcases l₂ with ⟨l₂⟩
+@[simp] theorem takeWhile_append_of_pos {p : α → Bool} {xs ys : Array α} (h : ∀ a ∈ xs, p a) :
+    (xs ++ ys).takeWhile p = xs ++ ys.takeWhile p := by
+  rcases xs with ⟨xs⟩
+  rcases ys with ⟨ys⟩
   simp at h
   simp [List.takeWhile_append_of_pos h]
 
@@ -374,34 +380,46 @@ theorem popWhile_append {xs ys : Array α} :
   · rfl
   · simp
 
-@[simp] theorem popWhile_append_of_pos {p : α → Bool} {l₁ l₂ : Array α} (h : ∀ a ∈ l₂, p a) :
-    (l₁ ++ l₂).popWhile p = l₁.popWhile p := by
-  rcases l₁ with ⟨l₁⟩
-  rcases l₂ with ⟨l₂⟩
+@[simp] theorem popWhile_append_of_pos {p : α → Bool} {xs ys : Array α} (h : ∀ a ∈ ys, p a) :
+    (xs ++ ys).popWhile p = xs.popWhile p := by
+  rcases xs with ⟨xs⟩
+  rcases ys with ⟨ys⟩
   simp at h
   simp only [List.append_toArray, List.popWhile_toArray, List.reverse_append, mk.injEq,
     List.reverse_inj]
   rw [List.dropWhile_append_of_pos]
   simpa
 
-@[simp] theorem takeWhile_mkArray_eq_filter (p : α → Bool) :
-    (mkArray n a).takeWhile p = (mkArray n a).filter p := by
+@[simp] theorem takeWhile_replicate_eq_filter (p : α → Bool) :
+    (replicate n a).takeWhile p = (replicate n a).filter p := by
   simp [← List.toArray_replicate]
 
-theorem takeWhile_mkArray (p : α → Bool) :
-    (mkArray n a).takeWhile p = if p a then mkArray n a else #[] := by
-  simp [takeWhile_mkArray_eq_filter, filter_mkArray]
+@[deprecated takeWhile_replicate_eq_filter (since := "2025-03-18")]
+abbrev takeWhile_mkArray_eq_filter := @takeWhile_replicate_eq_filter
 
-@[simp] theorem popWhile_mkArray_eq_filter_not (p : α → Bool) :
-    (mkArray n a).popWhile p = (mkArray n a).filter (fun a => !p a) := by
+theorem takeWhile_replicate (p : α → Bool) :
+    (replicate n a).takeWhile p = if p a then replicate n a else #[] := by
+  simp [takeWhile_replicate_eq_filter, filter_replicate]
+
+@[deprecated takeWhile_replicate (since := "2025-03-18")]
+abbrev takeWhile_mkArray := @takeWhile_replicate
+
+@[simp] theorem popWhile_replicate_eq_filter_not (p : α → Bool) :
+    (replicate n a).popWhile p = (replicate n a).filter (fun a => !p a) := by
   simp [← List.toArray_replicate, ← List.filter_reverse]
 
-theorem popWhile_mkArray (p : α → Bool) :
-    (mkArray n a).popWhile p = if p a then #[] else mkArray n a := by
-  simp only [popWhile_mkArray_eq_filter_not, size_mkArray, filter_mkArray, Bool.not_eq_eq_eq_not,
+@[deprecated popWhile_replicate_eq_filter_not (since := "2025-03-18")]
+abbrev popWhile_mkArray_eq_filter_not := @popWhile_replicate_eq_filter_not
+
+theorem popWhile_replicate (p : α → Bool) :
+    (replicate n a).popWhile p = if p a then #[] else replicate n a := by
+  simp only [popWhile_replicate_eq_filter_not, size_replicate, filter_replicate, Bool.not_eq_eq_eq_not,
     Bool.not_true]
   split <;> simp_all
 
+@[deprecated popWhile_replicate (since := "2025-03-18")]
+abbrev popWhile_mkArray := @popWhile_replicate
+
 theorem extract_takeWhile {as : Array α} {i : Nat} :
     (as.takeWhile p).extract 0 i = (as.extract 0 i).takeWhile p := by
   rcases as with ⟨as⟩

src/Init/Data/Array/FinRange.lean

@@ -7,9 +7,18 @@ prelude
 import Init.Data.List.FinRange
 import Init.Data.Array.OfFn
 
+set_option linter.listVariables true -- Enforce naming conventions for `List`/`Array`/`Vector` variables.
+set_option linter.indexVariables true -- Enforce naming conventions for index variables.
+
 namespace Array
 
-/-- `finRange n` is the array of all elements of `Fin n` in order. -/
+/--
+Returns an array of all elements of `Fin n` in order, starting at `0`.
+
+Examples:
+ * `Array.finRange 0 = (#[] : Array (Fin 0))`
+ * `Array.finRange 2 = (#[0, 1] : Array (Fin 2))`
+-/
 protected def finRange (n : Nat) : Array (Fin n) := ofFn fun i => i
 
 @[simp] theorem size_finRange (n) : (Array.finRange n).size = n := by

src/Init/Data/Array/Find.lean

@@ -13,77 +13,79 @@ import Init.Data.Array.Range
 # Lemmas about `Array.findSome?`, `Array.find?, `Array.findIdx`, `Array.findIdx?`, `Array.idxOf`.
 -/
 
+set_option linter.listVariables true -- Enforce naming conventions for `List`/`Array`/`Vector` variables.
+set_option linter.indexVariables true -- Enforce naming conventions for index variables.
 namespace Array
 
 open Nat
 
 /-! ### findSome? -/
 
-@[simp] theorem findSomeRev?_push_of_isSome (l : Array α) (h : (f a).isSome) : (l.push a).findSomeRev? f = f a := by
-  cases l; simp_all
+@[simp] theorem findSomeRev?_push_of_isSome (xs : Array α) (h : (f a).isSome) : (xs.push a).findSomeRev? f = f a := by
+  cases xs; simp_all
 
-@[simp] theorem findSomeRev?_push_of_isNone (l : Array α) (h : (f a).isNone) : (l.push a).findSomeRev? f = l.findSomeRev? f := by
-  cases l; simp_all
+@[simp] theorem findSomeRev?_push_of_isNone (xs : Array α) (h : (f a).isNone) : (xs.push a).findSomeRev? f = xs.findSomeRev? f := by
+  cases xs; simp_all
 
-theorem exists_of_findSome?_eq_some {f : α → Option β} {l : Array α} (w : l.findSome? f = some b) :
-    ∃ a, a ∈ l ∧ f a = b := by
-  cases l; simp_all [List.exists_of_findSome?_eq_some]
+theorem exists_of_findSome?_eq_some {f : α → Option β} {xs : Array α} (w : xs.findSome? f = some b) :
+    ∃ a, a ∈ xs ∧ f a = b := by
+  cases xs; simp_all [List.exists_of_findSome?_eq_some]
 
-@[simp] theorem findSome?_eq_none_iff : findSome? p l = none ↔ ∀ x ∈ l, p x = none := by
-  cases l; simp
+@[simp] theorem findSome?_eq_none_iff : findSome? p xs = none ↔ ∀ x ∈ xs, p x = none := by
+  cases xs; simp
 
-@[simp] theorem findSome?_isSome_iff {f : α → Option β} {l : Array α} :
-    (l.findSome? f).isSome ↔ ∃ x, x ∈ l ∧ (f x).isSome := by
-  cases l; simp
+@[simp] theorem findSome?_isSome_iff {f : α → Option β} {xs : Array α} :
+    (xs.findSome? f).isSome ↔ ∃ x, x ∈ xs ∧ (f x).isSome := by
+  cases xs; simp
 
-theorem findSome?_eq_some_iff {f : α → Option β} {l : Array α} {b : β} :
-    l.findSome? f = some b ↔ ∃ (l₁ : Array α) (a : α) (l₂ : Array α), l = l₁.push a ++ l₂ ∧ f a = some b ∧ ∀ x ∈ l₁, f x = none := by
-  cases l
+theorem findSome?_eq_some_iff {f : α → Option β} {xs : Array α} {b : β} :
+    xs.findSome? f = some b ↔ ∃ (ys : Array α) (a : α) (zs : Array α), xs = ys.push a ++ zs ∧ f a = some b ∧ ∀ x ∈ ys, f x = none := by
+  cases xs
   simp only [List.findSome?_toArray, List.findSome?_eq_some_iff]
   constructor
   · rintro ⟨l₁, a, l₂, rfl, h₁, h₂⟩
     exact ⟨l₁.toArray, a, l₂.toArray, by simp_all⟩
-  · rintro ⟨l₁, a, l₂, h₀, h₁, h₂⟩
-    exact ⟨l₁.toList, a, l₂.toList, by simpa using congrArg toList h₀, h₁, by simpa⟩
+  · rintro ⟨xs, a, ys, h₀, h₁, h₂⟩
+    exact ⟨xs.toList, a, ys.toList, by simpa using congrArg toList h₀, h₁, by simpa⟩
 
-@[simp] theorem findSome?_guard (l : Array α) : findSome? (Option.guard fun x => p x) l = find? p l := by
-  cases l; simp
+@[simp] theorem findSome?_guard (xs : Array α) : findSome? (Option.guard fun x => p x) xs = find? p xs := by
+  cases xs; simp
 
-theorem find?_eq_findSome?_guard (l : Array α) : find? p l = findSome? (Option.guard fun x => p x) l :=
-  (findSome?_guard l).symm
+theorem find?_eq_findSome?_guard (xs : Array α) : find? p xs = findSome? (Option.guard fun x => p x) xs :=
+  (findSome?_guard xs).symm
 
-@[simp] theorem getElem?_zero_filterMap (f : α → Option β) (l : Array α) : (l.filterMap f)[0]? = l.findSome? f := by
-  cases l; simp [← List.head?_eq_getElem?]
+@[simp] theorem getElem?_zero_filterMap (f : α → Option β) (xs : Array α) : (xs.filterMap f)[0]? = xs.findSome? f := by
+  cases xs; simp [← List.head?_eq_getElem?]
 
-@[simp] theorem getElem_zero_filterMap (f : α → Option β) (l : Array α) (h) :
-    (l.filterMap f)[0] = (l.findSome? f).get (by cases l; simpa [List.length_filterMap_eq_countP] using h) := by
-  cases l; simp [← List.head_eq_getElem, ← getElem?_zero_filterMap]
+@[simp] theorem getElem_zero_filterMap (f : α → Option β) (xs : Array α) (h) :
+    (xs.filterMap f)[0] = (xs.findSome? f).get (by cases xs; simpa [List.length_filterMap_eq_countP] using h) := by
+  cases xs; simp [← List.head_eq_getElem, ← getElem?_zero_filterMap]
 
-@[simp] theorem back?_filterMap (f : α → Option β) (l : Array α) : (l.filterMap f).back? = l.findSomeRev? f := by
-  cases l; simp
+@[simp] theorem back?_filterMap (f : α → Option β) (xs : Array α) : (xs.filterMap f).back? = xs.findSomeRev? f := by
+  cases xs; simp
 
-@[simp] theorem back!_filterMap [Inhabited β] (f : α → Option β) (l : Array α) :
-    (l.filterMap f).back! = (l.findSomeRev? f).getD default := by
-  cases l; simp
+@[simp] theorem back!_filterMap [Inhabited β] (f : α → Option β) (xs : Array α) :
+    (xs.filterMap f).back! = (xs.findSomeRev? f).getD default := by
+  cases xs; simp
 
-@[simp] theorem map_findSome? (f : α → Option β) (g : β → γ) (l : Array α) :
-    (l.findSome? f).map g = l.findSome? (Option.map g ∘ f) := by
-  cases l; simp
+@[simp] theorem map_findSome? (f : α → Option β) (g : β → γ) (xs : Array α) :
+    (xs.findSome? f).map g = xs.findSome? (Option.map g ∘ f) := by
+  cases xs; simp
 
-theorem findSome?_map (f : β → γ) (l : Array β) : findSome? p (l.map f) = l.findSome? (p ∘ f) := by
-  cases l; simp [List.findSome?_map]
+theorem findSome?_map (f : β → γ) (xs : Array β) : findSome? p (xs.map f) = xs.findSome? (p ∘ f) := by
+  cases xs; simp [List.findSome?_map]
 
-theorem findSome?_append {l₁ l₂ : Array α} : (l₁ ++ l₂).findSome? f = (l₁.findSome? f).or (l₂.findSome? f) := by
-  cases l₁; cases l₂; simp [List.findSome?_append]
+theorem findSome?_append {xs ys : Array α} : (xs ++ ys).findSome? f = (xs.findSome? f).or (ys.findSome? f) := by
+  cases xs; cases ys; simp [List.findSome?_append]
 
-theorem getElem?_zero_flatten (L : Array (Array α)) :
-    (flatten L)[0]? = L.findSome? fun l => l[0]? := by
-  cases L using array₂_induction
+theorem getElem?_zero_flatten (xss : Array (Array α)) :
+    (flatten xss)[0]? = xss.findSome? fun xs => xs[0]? := by
+  cases xss using array₂_induction
   simp [← List.head?_eq_getElem?, List.head?_flatten, List.findSome?_map, Function.comp_def]
 
-theorem getElem_zero_flatten.proof {L : Array (Array α)} (h : 0 < L.flatten.size) :
-    (L.findSome? fun l => l[0]?).isSome := by
-  cases L using array₂_induction
+theorem getElem_zero_flatten.proof {xss : Array (Array α)} (h : 0 < xss.flatten.size) :
+    (xss.findSome? fun xs => xs[0]?).isSome := by
+  cases xss using array₂_induction
   simp only [List.findSome?_toArray, List.findSome?_map, Function.comp_def, List.getElem?_toArray,
     List.findSome?_isSome_iff, isSome_getElem?]
   simp only [flatten_toArray_map_toArray, List.size_toArray, List.length_flatten,
@@ -91,32 +93,39 @@ theorem getElem_zero_flatten.proof {L : Array (Array α)} (h : 0 < L.flatten.siz
   obtain ⟨_, ⟨xs, m, rfl⟩, h⟩ := h
   exact ⟨xs, m, by simpa using h⟩
 
-theorem getElem_zero_flatten {L : Array (Array α)} (h) :
-    (flatten L)[0] = (L.findSome? fun l => l[0]?).get (getElem_zero_flatten.proof h) := by
-  have t := getElem?_zero_flatten L
+theorem getElem_zero_flatten {xss : Array (Array α)} (h) :
+    (flatten xss)[0] = (xss.findSome? fun xs => xs[0]?).get (getElem_zero_flatten.proof h) := by
+  have t := getElem?_zero_flatten xss
   simp [getElem?_eq_getElem, h] at t
   simp [← t]
 
-theorem back?_flatten {L : Array (Array α)} :
-    (flatten L).back? = (L.findSomeRev? fun l => l.back?) := by
-  cases L using array₂_induction
-  simp [List.getLast?_flatten, ← List.map_reverse, List.findSome?_map, Function.comp_def]
-
-theorem findSome?_mkArray : findSome? f (mkArray n a) = if n = 0 then none else f a := by
+theorem findSome?_replicate : findSome? f (replicate n a) = if n = 0 then none else f a := by
   simp [← List.toArray_replicate, List.findSome?_replicate]
 
-@[simp] theorem findSome?_mkArray_of_pos (h : 0 < n) : findSome? f (mkArray n a) = f a := by
-  simp [findSome?_mkArray, Nat.ne_of_gt h]
+@[deprecated findSome?_replicate (since := "2025-03-18")]
+abbrev findSome?_mkArray := @findSome?_replicate
+
+@[simp] theorem findSome?_replicate_of_pos (h : 0 < n) : findSome? f (replicate n a) = f a := by
+  simp [findSome?_replicate, Nat.ne_of_gt h]
+
+@[deprecated findSome?_replicate_of_pos (since := "2025-03-18")]
+abbrev findSome?_mkArray_of_pos := @findSome?_replicate_of_pos
 
 -- Argument is unused, but used to decide whether `simp` should unfold.
-@[simp] theorem findSome?_mkArray_of_isSome (_ : (f a).isSome) :
-   findSome? f (mkArray n a) = if n = 0 then none else f a := by
-  simp [findSome?_mkArray]
+@[simp] theorem findSome?_replicate_of_isSome (_ : (f a).isSome) :
+   findSome? f (replicate n a) = if n = 0 then none else f a := by
+  simp [findSome?_replicate]
 
-@[simp] theorem findSome?_mkArray_of_isNone (h : (f a).isNone) :
-    findSome? f (mkArray n a) = none := by
+@[deprecated findSome?_replicate_of_isSome (since := "2025-03-18")]
+abbrev findSome?_mkArray_of_isSome := @findSome?_replicate_of_isSome
+
+@[simp] theorem findSome?_replicate_of_isNone (h : (f a).isNone) :
+    findSome? f (replicate n a) = none := by
   rw [Option.isNone_iff_eq_none] at h
-  simp [findSome?_mkArray, h]
+  simp [findSome?_replicate, h]
+
+@[deprecated findSome?_replicate_of_isNone (since := "2025-03-18")]
+abbrev findSome?_mkArray_of_isNone := @findSome?_replicate_of_isNone
 
 /-! ### find? -/
 
@@ -124,16 +133,16 @@ theorem findSome?_mkArray : findSome? f (mkArray n a) = if n = 0 then none else
     #[a].find? p = if p a then some a else none := by
   simp [singleton_eq_toArray_singleton]
 
-@[simp] theorem findRev?_push_of_pos (l : Array α) (h : p a) :
-    findRev? p (l.push a) = some a := by
-  cases l; simp [h]
+@[simp] theorem findRev?_push_of_pos (xs : Array α) (h : p a) :
+    findRev? p (xs.push a) = some a := by
+  cases xs; simp [h]
 
-@[simp] theorem findRev?_cons_of_neg (l : Array α) (h : ¬p a) :
-    findRev? p (l.push a) = findRev? p l := by
-  cases l; simp [h]
+@[simp] theorem findRev?_cons_of_neg (xs : Array α) (h : ¬p a) :
+    findRev? p (xs.push a) = findRev? p xs := by
+  cases xs; simp [h]
 
-@[simp] theorem find?_eq_none : find? p l = none ↔ ∀ x ∈ l, ¬ p x := by
-  cases l; simp
+@[simp] theorem find?_eq_none : find? p xs = none ↔ ∀ x ∈ xs, ¬ p x := by
+  cases xs; simp
 
 theorem find?_eq_some_iff_append {xs : Array α} :
     xs.find? p = some b ↔ p b ∧ ∃ (as bs : Array α), xs = as.push b ++ bs ∧ ∀ a ∈ as, !p a := by
@@ -142,10 +151,10 @@ theorem find?_eq_some_iff_append {xs : Array α} :
     Bool.not_true, exists_and_right, and_congr_right_iff]
   intro w
   constructor
-  · rintro ⟨as, ⟨⟨x, rfl⟩, h⟩⟩
-    exact ⟨as.toArray, ⟨x.toArray, by simp⟩ , by simpa using h⟩
-  · rintro ⟨as, ⟨⟨x, h'⟩, h⟩⟩
-    exact ⟨as.toList, ⟨x.toList, by simpa using congrArg Array.toList h'⟩,
+  · rintro ⟨as, ⟨⟨xs, rfl⟩, h⟩⟩
+    exact ⟨as.toArray, ⟨xs.toArray, by simp⟩ , by simpa using h⟩
+  · rintro ⟨as, ⟨⟨⟨l⟩, h'⟩, h⟩⟩
+    exact ⟨as.toList, ⟨l, by simpa using congrArg Array.toList h'⟩,
       by simpa using h⟩
 
 @[simp]
@@ -174,22 +183,22 @@ theorem get_find?_mem {xs : Array α} (h) : (xs.find? p).get h ∈ xs := by
     (xs.filter p).find? q = xs.find? (fun a => p a ∧ q a) := by
   cases xs; simp
 
-@[simp] theorem getElem?_zero_filter (p : α → Bool) (l : Array α) :
-    (l.filter p)[0]? = l.find? p := by
-  cases l; simp [← List.head?_eq_getElem?]
+@[simp] theorem getElem?_zero_filter (p : α → Bool) (xs : Array α) :
+    (xs.filter p)[0]? = xs.find? p := by
+  cases xs; simp [← List.head?_eq_getElem?]
 
-@[simp] theorem getElem_zero_filter (p : α → Bool) (l : Array α) (h) :
-    (l.filter p)[0] =
-      (l.find? p).get (by cases l; simpa [← List.countP_eq_length_filter] using h) := by
-  cases l
+@[simp] theorem getElem_zero_filter (p : α → Bool) (xs : Array α) (h) :
+    (xs.filter p)[0] =
+      (xs.find? p).get (by cases xs; simpa [← List.countP_eq_length_filter] using h) := by
+  cases xs
   simp [List.getElem_zero_eq_head]
 
-@[simp] theorem back?_filter (p : α → Bool) (l : Array α) : (l.filter p).back? = l.findRev? p := by
-  cases l; simp
+@[simp] theorem back?_filter (p : α → Bool) (xs : Array α) : (xs.filter p).back? = xs.findRev? p := by
+  cases xs; simp
 
-@[simp] theorem back!_filter [Inhabited α] (p : α → Bool) (l : Array α) :
-    (l.filter p).back! = (l.findRev? p).get! := by
-  cases l; simp [Option.get!_eq_getD]
+@[simp] theorem back!_filter [Inhabited α] (p : α → Bool) (xs : Array α) :
+    (xs.filter p).back! = (xs.findRev? p).get! := by
+  cases xs; simp [Option.get!_eq_getD]
 
 @[simp] theorem find?_filterMap (xs : Array α) (f : α → Option β) (p : β → Bool) :
     (xs.filterMap f).find? p = (xs.find? (fun a => (f a).any p)).bind f := by
@@ -199,19 +208,19 @@ theorem get_find?_mem {xs : Array α} (h) : (xs.find? p).get h ∈ xs := by
     find? p (xs.map f) = (xs.find? (p ∘ f)).map f := by
   cases xs; simp
 
-@[simp] theorem find?_append {l₁ l₂ : Array α} :
-    (l₁ ++ l₂).find? p = (l₁.find? p).or (l₂.find? p) := by
-  cases l₁
-  cases l₂
+@[simp] theorem find?_append {xs ys : Array α} :
+    (xs ++ ys).find? p = (xs.find? p).or (ys.find? p) := by
+  cases xs
+  cases ys
   simp
 
-@[simp] theorem find?_flatten (xs : Array (Array α)) (p : α → Bool) :
-    xs.flatten.find? p = xs.findSome? (·.find? p) := by
-  cases xs using array₂_induction
+@[simp] theorem find?_flatten (xss : Array (Array α)) (p : α → Bool) :
+    xss.flatten.find? p = xss.findSome? (·.find? p) := by
+  cases xss using array₂_induction
   simp [List.findSome?_map, Function.comp_def]
 
-theorem find?_flatten_eq_none_iff {xs : Array (Array α)} {p : α → Bool} :
-    xs.flatten.find? p = none ↔ ∀ ys ∈ xs, ∀ x ∈ ys, !p x := by
+theorem find?_flatten_eq_none_iff {xss : Array (Array α)} {p : α → Bool} :
+    xss.flatten.find? p = none ↔ ∀ ys ∈ xss, ∀ x ∈ ys, !p x := by
   simp
 
 @[deprecated find?_flatten_eq_none_iff (since := "2025-02-03")]
@@ -222,12 +231,12 @@ If `find? p` returns `some a` from `xs.flatten`, then `p a` holds, and
 some array in `xs` contains `a`, and no earlier element of that array satisfies `p`.
 Moreover, no earlier array in `xs` has an element satisfying `p`.
 -/
-theorem find?_flatten_eq_some_iff {xs : Array (Array α)} {p : α → Bool} {a : α} :
-    xs.flatten.find? p = some a ↔
+theorem find?_flatten_eq_some_iff {xss : Array (Array α)} {p : α → Bool} {a : α} :
+    xss.flatten.find? p = some a ↔
       p a ∧ ∃ (as : Array (Array α)) (ys zs : Array α) (bs : Array (Array α)),
-        xs = as.push (ys.push a ++ zs) ++ bs ∧
-        (∀ a ∈ as, ∀ x ∈ a, !p x) ∧ (∀ x ∈ ys, !p x) := by
-  cases xs using array₂_induction
+        xss = as.push (ys.push a ++ zs) ++ bs ∧
+        (∀ ws ∈ as, ∀ x ∈ ws, !p x) ∧ (∀ x ∈ ys, !p x) := by
+  cases xss using array₂_induction
   simp only [flatten_toArray_map_toArray, List.find?_toArray, List.find?_flatten_eq_some_iff]
   simp only [Bool.not_eq_eq_eq_not, Bool.not_true, exists_and_right, and_congr_right_iff]
   intro w
@@ -257,40 +266,58 @@ theorem find?_flatMap_eq_none_iff {xs : Array α} {f : α → Array β} {p : β
 @[deprecated find?_flatMap_eq_none_iff (since := "2025-02-03")]
 abbrev find?_flatMap_eq_none := @find?_flatMap_eq_none_iff
 
-theorem find?_mkArray :
-    find? p (mkArray n a) = if n = 0 then none else if p a then some a else none := by
+theorem find?_replicate :
+    find? p (replicate n a) = if n = 0 then none else if p a then some a else none := by
   simp [← List.toArray_replicate, List.find?_replicate]
 
-@[simp] theorem find?_mkArray_of_length_pos (h : 0 < n) :
-    find? p (mkArray n a) = if p a then some a else none := by
-  simp [find?_mkArray, Nat.ne_of_gt h]
+@[deprecated find?_replicate (since := "2025-03-18")]
+abbrev find?_mkArray := @find?_replicate
 
-@[simp] theorem find?_mkArray_of_pos (h : p a) :
-    find? p (mkArray n a) = if n = 0 then none else some a := by
-  simp [find?_mkArray, h]
+@[simp] theorem find?_replicate_of_size_pos (h : 0 < n) :
+    find? p (replicate n a) = if p a then some a else none := by
+  simp [find?_replicate, Nat.ne_of_gt h]
 
-@[simp] theorem find?_mkArray_of_neg (h : ¬ p a) : find? p (mkArray n a) = none := by
-  simp [find?_mkArray, h]
+@[deprecated find?_replicate_of_size_pos (since := "2025-03-18")]
+abbrev find?_mkArray_of_length_pos := @find?_replicate_of_size_pos
+
+@[simp] theorem find?_replicate_of_pos (h : p a) :
+    find? p (replicate n a) = if n = 0 then none else some a := by
+  simp [find?_replicate, h]
+
+@[deprecated find?_replicate_of_pos (since := "2025-03-18")]
+abbrev find?_mkArray_of_pos := @find?_replicate_of_pos
+
+@[simp] theorem find?_replicate_of_neg (h : ¬ p a) : find? p (replicate n a) = none := by
+  simp [find?_replicate, h]
+
+@[deprecated find?_replicate_of_neg (since := "2025-03-18")]
+abbrev find?_mkArray_of_neg := @find?_replicate_of_neg
 
 -- This isn't a `@[simp]` lemma since there is already a lemma for `l.find? p = none` for any `l`.
-theorem find?_mkArray_eq_none_iff {n : Nat} {a : α} {p : α → Bool} :
-    (mkArray n a).find? p = none ↔ n = 0 ∨ !p a := by
+theorem find?_replicate_eq_none_iff {n : Nat} {a : α} {p : α → Bool} :
+    (replicate n a).find? p = none ↔ n = 0 ∨ !p a := by
   simp [← List.toArray_replicate, List.find?_replicate_eq_none_iff, Classical.or_iff_not_imp_left]
 
-@[deprecated find?_mkArray_eq_none_iff (since := "2025-02-03")]
-abbrev find?_mkArray_eq_none := @find?_mkArray_eq_none_iff
+@[deprecated find?_replicate_eq_none_iff (since := "2025-03-18")]
+abbrev find?_mkArray_eq_none_iff := @find?_replicate_eq_none_iff
 
-@[simp] theorem find?_mkArray_eq_some_iff {n : Nat} {a b : α} {p : α → Bool} :
-    (mkArray n a).find? p = some b ↔ n ≠ 0 ∧ p a ∧ a = b := by
+@[simp] theorem find?_replicate_eq_some_iff {n : Nat} {a b : α} {p : α → Bool} :
+    (replicate n a).find? p = some b ↔ n ≠ 0 ∧ p a ∧ a = b := by
   simp [← List.toArray_replicate]
 
-@[deprecated find?_mkArray_eq_some_iff (since := "2025-02-03")]
-abbrev find?_mkArray_eq_some := @find?_mkArray_eq_some_iff
+@[deprecated find?_replicate_eq_some_iff (since := "2025-03-18")]
+abbrev find?_mkArray_eq_some_iff := @find?_replicate_eq_some_iff
 
-@[simp] theorem get_find?_mkArray (n : Nat) (a : α) (p : α → Bool) (h) :
-    ((mkArray n a).find? p).get h = a := by
+@[deprecated find?_replicate_eq_some_iff (since := "2025-02-03")]
+abbrev find?_mkArray_eq_some := @find?_replicate_eq_some_iff
+
+@[simp] theorem get_find?_replicate (n : Nat) (a : α) (p : α → Bool) (h) :
+    ((replicate n a).find? p).get h = a := by
   simp [← List.toArray_replicate]
 
+@[deprecated get_find?_replicate (since := "2025-03-18")]
+abbrev get_find?_mkArray := @get_find?_replicate
+
 theorem find?_pmap {P : α → Prop} (f : (a : α) → P a → β) (xs : Array α)
     (H : ∀ (a : α), a ∈ xs → P a) (p : β → Bool) :
     (xs.pmap f H).find? p = (xs.attach.find? (fun ⟨a, m⟩ => p (f a (H a m)))).map fun ⟨a, m⟩ => f a (H a m) := by
@@ -302,24 +329,6 @@ theorem find?_eq_some_iff_getElem {xs : Array α} {p : α → Bool} {b : α} :
   rcases xs with ⟨xs⟩
   simp [List.find?_eq_some_iff_getElem]
 
-/-! ### findFinIdx? -/
-
-@[simp] theorem findFinIdx?_empty {p : α → Bool} : findFinIdx? p #[] = none := rfl
-
--- We can't mark this as a `@[congr]` lemma since the head of the RHS is not `findFinIdx?`.
-theorem findFinIdx?_congr {p : α → Bool} {l₁ : Array α} {l₂ : Array α} (w : l₁ = l₂) :
-    findFinIdx? p l₁ = (findFinIdx? p l₂).map (fun i => i.cast (by simp [w])) := by
-  subst w
-  simp
-
-@[simp] theorem findFinIdx?_subtype {p : α → Prop} {l : Array { x // p x }}
-    {f : { x // p x } → Bool} {g : α → Bool} (hf : ∀ x h, f ⟨x, h⟩ = g x) :
-    l.findFinIdx? f = (l.unattach.findFinIdx? g).map (fun i => i.cast (by simp)) := by
-  cases l
-  simp only [List.findFinIdx?_toArray, hf, List.findFinIdx?_subtype]
-  rw [findFinIdx?_congr List.unattach_toArray]
-  simp [Function.comp_def]
-
 /-! ### findIdx -/
 
 theorem findIdx_of_getElem?_eq_some {xs : Array α} (w : xs[xs.findIdx p]? = some y) : p y := by
@@ -395,21 +404,21 @@ theorem findIdx_eq {p : α → Bool} {xs : Array α} {i : Nat} (h : i < xs.size)
   simp at h3
   simp_all [not_of_lt_findIdx h3]
 
-theorem findIdx_append (p : α → Bool) (l₁ l₂ : Array α) :
-    (l₁ ++ l₂).findIdx p =
-      if l₁.findIdx p < l₁.size then l₁.findIdx p else l₂.findIdx p + l₁.size := by
-  rcases l₁ with ⟨l₁⟩
-  rcases l₂ with ⟨l₂⟩
+theorem findIdx_append (p : α → Bool) (xs ys : Array α) :
+    (xs ++ ys).findIdx p =
+      if xs.findIdx p < xs.size then xs.findIdx p else ys.findIdx p + xs.size := by
+  rcases xs with ⟨xs⟩
+  rcases ys with ⟨ys⟩
   simp [List.findIdx_append]
 
-theorem findIdx_le_findIdx {l : Array α} {p q : α → Bool} (h : ∀ x ∈ l, p x → q x) : l.findIdx q ≤ l.findIdx p := by
-  rcases l with ⟨l⟩
+theorem findIdx_le_findIdx {xs : Array α} {p q : α → Bool} (h : ∀ x ∈ xs, p x → q x) : xs.findIdx q ≤ xs.findIdx p := by
+  rcases xs with ⟨xs⟩
   simp_all [List.findIdx_le_findIdx]
 
-@[simp] theorem findIdx_subtype {p : α → Prop} {l : Array { x // p x }}
+@[simp] theorem findIdx_subtype {p : α → Prop} {xs : Array { x // p x }}
     {f : { x // p x } → Bool} {g : α → Bool} (hf : ∀ x h, f ⟨x, h⟩ = g x) :
-    l.findIdx f = l.unattach.findIdx g := by
-  cases l
+    xs.findIdx f = xs.unattach.findIdx g := by
+  cases xs
   simp [hf]
 
 theorem false_of_mem_extract_findIdx {xs : Array α} {p : α → Bool} (h : x ∈ xs.extract 0 (xs.findIdx p)) :
@@ -429,7 +438,7 @@ theorem false_of_mem_extract_findIdx {xs : Array α} {p : α → Bool} (h : x
 
 /-! ### findIdx? -/
 
-@[simp] theorem findIdx?_empty : (#[] : Array α).findIdx? p = none := rfl
+@[simp] theorem findIdx?_empty : (#[] : Array α).findIdx? p = none := by simp
 
 @[simp]
 theorem findIdx?_eq_none_iff {xs : Array α} {p : α → Bool} :
@@ -483,8 +492,8 @@ theorem of_findIdx?_eq_none {xs : Array α} {p : α → Bool} (w : xs.findIdx? p
   rcases xs with ⟨xs⟩
   simpa using List.of_findIdx?_eq_none (by simpa using w)
 
-@[simp] theorem findIdx?_map (f : β → α) (l : Array β) : findIdx? p (l.map f) = l.findIdx? (p ∘ f) := by
-  rcases l with ⟨l⟩
+@[simp] theorem findIdx?_map (f : β → α) (xs : Array β) : findIdx? p (xs.map f) = xs.findIdx? (p ∘ f) := by
+  rcases xs with ⟨xs⟩
   simp [List.findIdx?_map]
 
 @[simp] theorem findIdx?_append :
@@ -494,20 +503,23 @@ theorem of_findIdx?_eq_none {xs : Array α} {p : α → Bool} (w : xs.findIdx? p
   rcases ys with ⟨ys⟩
   simp [List.findIdx?_append]
 
-theorem findIdx?_flatten {l : Array (Array α)} {p : α → Bool} :
-    l.flatten.findIdx? p =
-      (l.findIdx? (·.any p)).map
-        fun i => ((l.take i).map Array.size).sum +
-          (l[i]?.map fun xs => xs.findIdx p).getD 0 := by
-  cases l using array₂_induction
+theorem findIdx?_flatten {xss : Array (Array α)} {p : α → Bool} :
+    xss.flatten.findIdx? p =
+      (xss.findIdx? (·.any p)).map
+        fun i => ((xss.take i).map Array.size).sum +
+          (xss[i]?.map fun xs => xs.findIdx p).getD 0 := by
+  cases xss using array₂_induction
   simp [List.findIdx?_flatten, Function.comp_def]
 
-@[simp] theorem findIdx?_mkArray :
-    (mkArray n a).findIdx? p = if 0 < n ∧ p a then some 0 else none := by
+@[simp] theorem findIdx?_replicate :
+    (replicate n a).findIdx? p = if 0 < n ∧ p a then some 0 else none := by
   rw [← List.toArray_replicate]
   simp only [List.findIdx?_toArray]
   simp
 
+@[deprecated findIdx?_replicate (since := "2025-03-18")]
+abbrev findIdx?_mkArray := @findIdx?_replicate
+
 theorem findIdx?_eq_findSome?_zipIdx {xs : Array α} {p : α → Bool} :
     xs.findIdx? p = xs.zipIdx.findSome? fun ⟨a, i⟩ => if p a then some i else none := by
   rcases xs with ⟨xs⟩
@@ -534,10 +546,10 @@ theorem findIdx?_eq_some_le_of_findIdx?_eq_some {xs : Array α} {p q : α → Bo
   rcases xs with ⟨xs⟩
   simp [List.findIdx?_eq_some_le_of_findIdx?_eq_some (by simpa using w) (by simpa using h)]
 
-@[simp] theorem findIdx?_subtype {p : α → Prop} {l : Array { x // p x }}
+@[simp] theorem findIdx?_subtype {p : α → Prop} {xs : Array { x // p x }}
     {f : { x // p x } → Bool} {g : α → Bool} (hf : ∀ x h, f ⟨x, h⟩ = g x) :
-    l.findIdx? f = l.unattach.findIdx? g := by
-  cases l
+    xs.findIdx? f = xs.unattach.findIdx? g := by
+  cases xs
   simp [hf]
 
 @[simp] theorem findIdx?_take {xs : Array α} {i : Nat} {p : α → Bool} :
@@ -545,14 +557,55 @@ theorem findIdx?_eq_some_le_of_findIdx?_eq_some {xs : Array α} {p q : α → Bo
   cases xs
   simp
 
+/-! ### findFinIdx? -/
+
+@[simp] theorem findFinIdx?_empty {p : α → Bool} : findFinIdx? p #[] = none := by simp
+
+-- We can't mark this as a `@[congr]` lemma since the head of the RHS is not `findFinIdx?`.
+theorem findFinIdx?_congr {p : α → Bool} {xs ys : Array α} (w : xs = ys) :
+    findFinIdx? p xs = (findFinIdx? p ys).map (fun i => i.cast (by simp [w])) := by
+  subst w
+  simp
+
+theorem findFinIdx?_eq_pmap_findIdx? {xs : Array α} {p : α → Bool} :
+    xs.findFinIdx? p =
+      (xs.findIdx? p).pmap
+        (fun i m => by simp [findIdx?_eq_some_iff_getElem] at m; exact ⟨i, m.choose⟩)
+        (fun i h => h) := by
+  simp [findIdx?_eq_map_findFinIdx?_val, Option.pmap_map]
+
+@[simp] theorem findFinIdx?_eq_none_iff {xs : Array α} {p : α → Bool} :
+    xs.findFinIdx? p = none ↔ ∀ x, x ∈ xs → ¬ p x := by
+  simp [findFinIdx?_eq_pmap_findIdx?]
+
+@[simp]
+theorem findFinIdx?_eq_some_iff {xs : Array α} {p : α → Bool} {i : Fin xs.size} :
+    xs.findFinIdx? p = some i ↔
+      p xs[i] ∧ ∀ j (hji : j < i), ¬p (xs[j]'(Nat.lt_trans hji i.2)) := by
+  simp only [findFinIdx?_eq_pmap_findIdx?, Option.pmap_eq_some_iff, findIdx?_eq_some_iff_getElem,
+    Bool.not_eq_true, Option.mem_def, exists_and_left, and_exists_self, Fin.getElem_fin]
+  constructor
+  · rintro ⟨a, ⟨h, w₁, w₂⟩, rfl⟩
+    exact ⟨w₁, fun j hji => by simpa using w₂ j hji⟩
+  · rintro ⟨h, w⟩
+    exact ⟨i, ⟨i.2, h, fun j hji => w ⟨j, by omega⟩ hji⟩, rfl⟩
+
+@[simp] theorem findFinIdx?_subtype {p : α → Prop} {xs : Array { x // p x }}
+    {f : { x // p x } → Bool} {g : α → Bool} (hf : ∀ x h, f ⟨x, h⟩ = g x) :
+    xs.findFinIdx? f = (xs.unattach.findFinIdx? g).map (fun i => i.cast (by simp)) := by
+  cases xs
+  simp only [List.findFinIdx?_toArray, hf, List.findFinIdx?_subtype]
+  rw [findFinIdx?_congr List.unattach_toArray]
+  simp [Function.comp_def]
+
 /-! ### idxOf
 
 The verification API for `idxOf` is still incomplete.
 The lemmas below should be made consistent with those for `findIdx` (and proved using them).
 -/
 
-theorem idxOf_append [BEq α] [LawfulBEq α] {l₁ l₂ : Array α} {a : α} :
-    (l₁ ++ l₂).idxOf a = if a ∈ l₁ then l₁.idxOf a else l₂.idxOf a + l₁.size := by
+theorem idxOf_append [BEq α] [LawfulBEq α] {xs ys : Array α} {a : α} :
+    (xs ++ ys).idxOf a = if a ∈ xs then xs.idxOf a else ys.idxOf a + xs.size := by
   rw [idxOf, findIdx_append]
   split <;> rename_i h
   · rw [if_pos]
@@ -560,12 +613,12 @@ theorem idxOf_append [BEq α] [LawfulBEq α] {l₁ l₂ : Array α} {a : α} :
   · rw [if_neg]
     simpa using h
 
-theorem idxOf_eq_size [BEq α] [LawfulBEq α] {l : Array α} (h : a ∉ l) : l.idxOf a = l.size := by
-  rcases l with ⟨l⟩
+theorem idxOf_eq_size [BEq α] [LawfulBEq α] {xs : Array α} (h : a ∉ xs) : xs.idxOf a = xs.size := by
+  rcases xs with ⟨xs⟩
   simp [List.idxOf_eq_length (by simpa using h)]
 
-theorem idxOf_lt_length [BEq α] [LawfulBEq α] {l : Array α} (h : a ∈ l) : l.idxOf a < l.size := by
-  rcases l with ⟨l⟩
+theorem idxOf_lt_length [BEq α] [LawfulBEq α] {xs : Array α} (h : a ∈ xs) : xs.idxOf a < xs.size := by
+  rcases xs with ⟨xs⟩
   simp [List.idxOf_lt_length (by simpa using h)]
 
 
@@ -575,17 +628,33 @@ The verification API for `idxOf?` is still incomplete.
 The lemmas below should be made consistent with those for `findIdx?` (and proved using them).
 -/
 
-@[simp] theorem idxOf?_empty [BEq α] : (#[] : Array α).idxOf? a = none := rfl
+@[simp] theorem idxOf?_empty [BEq α] : (#[] : Array α).idxOf? a = none := by simp
 
-@[simp] theorem idxOf?_eq_none_iff [BEq α] [LawfulBEq α] {l : Array α} {a : α} :
-    l.idxOf? a = none ↔ a ∉ l := by
-  rcases l with ⟨l⟩
+@[simp] theorem idxOf?_eq_none_iff [BEq α] [LawfulBEq α] {xs : Array α} {a : α} :
+    xs.idxOf? a = none ↔ a ∉ xs := by
+  rcases xs with ⟨xs⟩
   simp [List.idxOf?_eq_none_iff]
 
-/-! ### finIdxOf? -/
+/-! ### finIdxOf?
+
+The verification API for `finIdxOf?` is still incomplete.
+The lemmas below should be made consistent with those for `findFinIdx?` (and proved using them).
+-/
 
 theorem idxOf?_eq_map_finIdxOf?_val [BEq α] {xs : Array α} {a : α} :
     xs.idxOf? a = (xs.finIdxOf? a).map (·.val) := by
   simp [idxOf?, finIdxOf?, findIdx?_eq_map_findFinIdx?_val]
 
+@[simp] theorem finIdxOf?_empty [BEq α] : (#[] : Array α).finIdxOf? a = none := by simp
+
+@[simp] theorem finIdxOf?_eq_none_iff [BEq α] [LawfulBEq α] {xs : Array α} {a : α} :
+    xs.finIdxOf? a = none ↔ a ∉ xs := by
+  rcases xs with ⟨xs⟩
+  simp [List.finIdxOf?_eq_none_iff]
+
+@[simp] theorem finIdxOf?_eq_some_iff [BEq α] [LawfulBEq α] {xs : Array α} {a : α} {i : Fin xs.size} :
+    xs.finIdxOf? a = some i ↔ xs[i] = a ∧ ∀ j (_ : j < i), ¬xs[j] = a := by
+  rcases xs with ⟨xs⟩
+  simp [List.finIdxOf?_eq_some_iff]
+
 end Array

src/Init/Data/Array/GetLit.lean

@@ -7,40 +7,43 @@ Authors: Leonardo de Moura
 prelude
 import Init.Data.Array.Basic
 
+set_option linter.listVariables true -- Enforce naming conventions for `List`/`Array`/`Vector` variables.
+set_option linter.indexVariables true -- Enforce naming conventions for index variables.
+
 namespace Array
 
 /-! ### getLit -/
 
 -- auxiliary declaration used in the equation compiler when pattern matching array literals.
-abbrev getLit {α : Type u} {n : Nat} (a : Array α) (i : Nat) (h₁ : a.size = n) (h₂ : i < n) : α :=
+abbrev getLit {α : Type u} {n : Nat} (xs : Array α) (i : Nat) (h₁ : xs.size = n) (h₂ : i < n) : α :=
   have := h₁.symm ▸ h₂
-  a[i]
+  xs[i]
 
 theorem extLit {n : Nat}
-    (a b : Array α)
-    (hsz₁ : a.size = n) (hsz₂ : b.size = n)
-    (h : (i : Nat) → (hi : i < n) → a.getLit i hsz₁ hi = b.getLit i hsz₂ hi) : a = b :=
-  Array.ext a b (hsz₁.trans hsz₂.symm) fun i hi₁ _ => h i (hsz₁ ▸ hi₁)
+    (xs ys : Array α)
+    (hsz₁ : xs.size = n) (hsz₂ : ys.size = n)
+    (h : (i : Nat) → (hi : i < n) → xs.getLit i hsz₁ hi = ys.getLit i hsz₂ hi) : xs = ys :=
+  Array.ext xs ys (hsz₁.trans hsz₂.symm) fun i hi₁ _ => h i (hsz₁ ▸ hi₁)
 
-def toListLitAux (a : Array α) (n : Nat) (hsz : a.size = n) : ∀ (i : Nat), i ≤ a.size → List α → List α
+def toListLitAux (xs : Array α) (n : Nat) (hsz : xs.size = n) : ∀ (i : Nat), i ≤ xs.size → List α → List α
   | 0,     _,  acc => acc
-  | (i+1), hi, acc => toListLitAux a n hsz i (Nat.le_of_succ_le hi) (a.getLit i hsz (Nat.lt_of_lt_of_eq (Nat.lt_of_lt_of_le (Nat.lt_succ_self i) hi) hsz) :: acc)
+  | (i+1), hi, acc => toListLitAux xs n hsz i (Nat.le_of_succ_le hi) (xs.getLit i hsz (Nat.lt_of_lt_of_eq (Nat.lt_of_lt_of_le (Nat.lt_succ_self i) hi) hsz) :: acc)
 
-def toArrayLit (a : Array α) (n : Nat) (hsz : a.size = n) : Array α :=
-  List.toArray <| toListLitAux a n hsz n (hsz ▸ Nat.le_refl _) []
+def toArrayLit (xs : Array α) (n : Nat) (hsz : xs.size = n) : Array α :=
+  List.toArray <| toListLitAux xs n hsz n (hsz ▸ Nat.le_refl _) []
 
-theorem toArrayLit_eq (as : Array α) (n : Nat) (hsz : as.size = n) : as = toArrayLit as n hsz := by
+theorem toArrayLit_eq (xs : Array α) (n : Nat) (hsz : xs.size = n) : xs = toArrayLit xs n hsz := by
   apply ext'
   simp [toArrayLit, List.toList_toArray]
-  have hle : n ≤ as.size := hsz ▸ Nat.le_refl _
-  have hge : as.size ≤ n := hsz ▸ Nat.le_refl _
+  have hle : n ≤ xs.size := hsz ▸ Nat.le_refl _
+  have hge : xs.size ≤ n := hsz ▸ Nat.le_refl _
   have := go n hle
   rw [List.drop_eq_nil_of_le hge] at this
   rw [this]
 where
-  getLit_eq (as : Array α) (i : Nat) (h₁ : as.size = n) (h₂ : i < n) : as.getLit i h₁ h₂ = getElem as.toList i ((id (α := as.toList.length = n) h₁) ▸ h₂) :=
+  getLit_eq (xs : Array α) (i : Nat) (h₁ : xs.size = n) (h₂ : i < n) : xs.getLit i h₁ h₂ = getElem xs.toList i ((id (α := xs.toList.length = n) h₁) ▸ h₂) :=
     rfl
-  go (i : Nat) (hi : i ≤ as.size) : toListLitAux as n hsz i hi (as.toList.drop i) = as.toList := by
+  go (i : Nat) (hi : i ≤ xs.size) : toListLitAux xs n hsz i hi (xs.toList.drop i) = xs.toList := by
     induction i <;> simp only [List.drop, toListLitAux, getLit_eq, List.getElem_cons_drop_succ_eq_drop, *]
 
 end Array

src/Init/Data/Array/InsertIdx.lean

@@ -13,6 +13,9 @@ import Init.Data.List.Nat.InsertIdx
 Proves various lemmas about `Array.insertIdx`.
 -/
 
+set_option linter.listVariables true -- Enforce naming conventions for `List`/`Array`/`Vector` variables.
+set_option linter.indexVariables true -- Enforce naming conventions for index variables.
+
 open Function
 
 open Nat
@@ -27,23 +30,23 @@ section InsertIdx
 
 variable {a : α}
 
-@[simp] theorem toList_insertIdx (a : Array α) (i x) (h) :
-    (a.insertIdx i x h).toList = a.toList.insertIdx i x := by
-  rcases a with ⟨a⟩
+@[simp] theorem toList_insertIdx (xs : Array α) (i x) (h) :
+    (xs.insertIdx i x h).toList = xs.toList.insertIdx i x := by
+  rcases xs with ⟨xs⟩
   simp
 
 @[simp]
-theorem insertIdx_zero (s : Array α) (x : α) : s.insertIdx 0 x = #[x] ++ s := by
-  cases s
+theorem insertIdx_zero (xs : Array α) (x : α) : xs.insertIdx 0 x = #[x] ++ xs := by
+  rcases xs with ⟨xs⟩
   simp
 
-@[simp] theorem size_insertIdx {as : Array α} (h : n ≤ as.size) : (as.insertIdx n a).size = as.size + 1 := by
-  cases as
+@[simp] theorem size_insertIdx {xs : Array α} (h : i ≤ xs.size) : (xs.insertIdx i a).size = xs.size + 1 := by
+  rcases xs with ⟨xs⟩
   simp [List.length_insertIdx, h]
 
-theorem eraseIdx_insertIdx (i : Nat) (l : Array α) (h : i ≤ l.size) :
-    (l.insertIdx i a).eraseIdx i (by simp; omega) = l := by
-  cases l
+theorem eraseIdx_insertIdx (i : Nat) (xs : Array α) (h : i ≤ xs.size) :
+    (xs.insertIdx i a).eraseIdx i (by simp; omega) = xs := by
+  rcases xs with ⟨xs⟩
   simp_all
 
 theorem insertIdx_eraseIdx_of_ge {as : Array α}
@@ -60,68 +63,68 @@ theorem insertIdx_eraseIdx_of_le {as : Array α}
   cases as
   simpa using List.insertIdx_eraseIdx_of_le _ _ _ (by simpa) (by simpa)
 
-theorem insertIdx_comm (a b : α) (i j : Nat) (l : Array α) (_ : i ≤ j) (_ : j ≤ l.size) :
-    (l.insertIdx i a).insertIdx (j + 1) b (by simpa) =
-      (l.insertIdx j b).insertIdx i a (by simp; omega) := by
-  cases l
+theorem insertIdx_comm (a b : α) (i j : Nat) (xs : Array α) (_ : i ≤ j) (_ : j ≤ xs.size) :
+    (xs.insertIdx i a).insertIdx (j + 1) b (by simpa) =
+      (xs.insertIdx j b).insertIdx i a (by simp; omega) := by
+  rcases xs with ⟨xs⟩
   simpa using List.insertIdx_comm a b i j _ (by simpa) (by simpa)
 
-theorem mem_insertIdx {l : Array α} {h : i ≤ l.size} : a ∈ l.insertIdx i b h ↔ a = b ∨ a ∈ l := by
-  cases l
+theorem mem_insertIdx {xs : Array α} {h : i ≤ xs.size} : a ∈ xs.insertIdx i b h ↔ a = b ∨ a ∈ xs := by
+  rcases xs with ⟨xs⟩
   simpa using List.mem_insertIdx (by simpa)
 
 @[simp]
-theorem insertIdx_size_self (l : Array α) (x : α) : l.insertIdx l.size x = l.push x := by
-  cases l
+theorem insertIdx_size_self (xs : Array α) (x : α) : xs.insertIdx xs.size x = xs.push x := by
+  rcases xs with ⟨xs⟩
   simp
 
-theorem getElem_insertIdx {as : Array α} {x : α} {i k : Nat} (w : i ≤ as.size) (h : k < (as.insertIdx i x).size) :
-    (as.insertIdx i x)[k] =
+theorem getElem_insertIdx {xs : Array α} {x : α} {i k : Nat} (w : i ≤ xs.size) (h : k < (xs.insertIdx i x).size) :
+    (xs.insertIdx i x)[k] =
       if h₁ : k < i then
-        as[k]'(by simp [size_insertIdx] at h; omega)
+        xs[k]'(by simp [size_insertIdx] at h; omega)
       else
         if h₂ : k = i then
           x
         else
-          as[k-1]'(by simp [size_insertIdx] at h; omega) := by
-  cases as
+          xs[k-1]'(by simp [size_insertIdx] at h; omega) := by
+  cases xs
   simp [List.getElem_insertIdx, w]
 
-theorem getElem_insertIdx_of_lt {as : Array α} {x : α} {i k : Nat} (w : i ≤ as.size) (h : k < i) :
-    (as.insertIdx i x)[k]'(by simp; omega) = as[k] := by
+theorem getElem_insertIdx_of_lt {xs : Array α} {x : α} {i k : Nat} (w : i ≤ xs.size) (h : k < i) :
+    (xs.insertIdx i x)[k]'(by simp; omega) = xs[k] := by
   simp [getElem_insertIdx, w, h]
 
-theorem getElem_insertIdx_self {as : Array α} {x : α} {i : Nat} (w : i ≤ as.size) :
-    (as.insertIdx i x)[i]'(by simp; omega) = x := by
+theorem getElem_insertIdx_self {xs : Array α} {x : α} {i : Nat} (w : i ≤ xs.size) :
+    (xs.insertIdx i x)[i]'(by simp; omega) = x := by
   simp [getElem_insertIdx, w]
 
-theorem getElem_insertIdx_of_gt {as : Array α} {x : α} {i k : Nat} (w : k ≤ as.size) (h : k > i) :
-    (as.insertIdx i x)[k]'(by simp; omega) = as[k - 1]'(by omega) := by
+theorem getElem_insertIdx_of_gt {xs : Array α} {x : α} {i k : Nat} (w : k ≤ xs.size) (h : k > i) :
+    (xs.insertIdx i x)[k]'(by simp; omega) = xs[k - 1]'(by omega) := by
   simp [getElem_insertIdx, w, h]
   rw [dif_neg (by omega), dif_neg (by omega)]
 
-theorem getElem?_insertIdx {l : Array α} {x : α} {i k : Nat} (h : i ≤ l.size) :
-    (l.insertIdx i x)[k]? =
+theorem getElem?_insertIdx {xs : Array α} {x : α} {i k : Nat} (h : i ≤ xs.size) :
+    (xs.insertIdx i x)[k]? =
       if k < i then
-        l[k]?
+        xs[k]?
       else
         if k = i then
-          if k ≤ l.size then some x else none
+          if k ≤ xs.size then some x else none
         else
-          l[k-1]? := by
-  cases l
+          xs[k-1]? := by
+  cases xs
   simp [List.getElem?_insertIdx, h]
 
-theorem getElem?_insertIdx_of_lt {l : Array α} {x : α} {i k : Nat} (w : i ≤ l.size) (h : k < i) :
-    (l.insertIdx i x)[k]? = l[k]? := by
+theorem getElem?_insertIdx_of_lt {xs : Array α} {x : α} {i k : Nat} (w : i ≤ xs.size) (h : k < i) :
+    (xs.insertIdx i x)[k]? = xs[k]? := by
   rw [getElem?_insertIdx, if_pos h]
 
-theorem getElem?_insertIdx_self {l : Array α} {x : α} {i : Nat} (w : i ≤ l.size) :
-    (l.insertIdx i x)[i]? = some x := by
+theorem getElem?_insertIdx_self {xs : Array α} {x : α} {i : Nat} (w : i ≤ xs.size) :
+    (xs.insertIdx i x)[i]? = some x := by
   rw [getElem?_insertIdx, if_neg (by omega), if_pos rfl, if_pos w]
 
-theorem getElem?_insertIdx_of_ge {l : Array α} {x : α} {i k : Nat} (w : i < k) (h : k ≤ l.size) :
-    (l.insertIdx i x)[k]? = l[k - 1]? := by
+theorem getElem?_insertIdx_of_ge {xs : Array α} {x : α} {i k : Nat} (w : i < k) (h : k ≤ xs.size) :
+    (xs.insertIdx i x)[k]? = xs[k - 1]? := by
   rw [getElem?_insertIdx, if_neg (by omega), if_neg (by omega)]
 
 end InsertIdx

src/Init/Data/Array/InsertionSort.lean

@@ -6,23 +6,32 @@ Authors: Leonardo de Moura
 prelude
 import Init.Data.Array.Basic
 
-@[inline] def Array.insertionSort (a : Array α) (lt : α → α → Bool := by exact (· < ·)) : Array α :=
-  traverse a 0 a.size
+set_option linter.listVariables true -- Enforce naming conventions for `List`/`Array`/`Vector` variables.
+set_option linter.indexVariables true -- Enforce naming conventions for index variables.
+
+/--
+Sorts an array using insertion sort.
+
+The optional parameter `lt` specifies an ordering predicate. It defaults to `LT.lt`, which must be
+decidable to be used for sorting.
+-/
+@[inline] def Array.insertionSort (xs : Array α) (lt : α → α → Bool := by exact (· < ·)) : Array α :=
+  traverse xs 0 xs.size
 where
-  @[specialize] traverse (a : Array α) (i : Nat) (fuel : Nat) : Array α :=
+  @[specialize] traverse (xs : Array α) (i : Nat) (fuel : Nat) : Array α :=
     match fuel with
-    | 0      => a
+    | 0      => xs
     | fuel+1 =>
-      if h : i < a.size then
-        traverse (swapLoop a i h) (i+1) fuel
+      if h : i < xs.size then
+        traverse (swapLoop xs i h) (i+1) fuel
       else
-        a
-  @[specialize] swapLoop (a : Array α) (j : Nat) (h : j < a.size) : Array α :=
+        xs
+  @[specialize] swapLoop (xs : Array α) (j : Nat) (h : j < xs.size) : Array α :=
     match (generalizing := false) he:j with -- using `generalizing` because we don't want to refine the type of `h`
-    | 0    => a
+    | 0    => xs
     | j'+1 =>
-      have h' : j' < a.size := by subst j; exact Nat.lt_trans (Nat.lt_succ_self _) h
-      if lt a[j] a[j'] then
-        swapLoop (a.swap j j') j' (by rw [size_swap]; assumption; done)
+      have h' : j' < xs.size := by subst j; exact Nat.lt_trans (Nat.lt_succ_self _) h
+      if lt xs[j] xs[j'] then
+        swapLoop (xs.swap j j') j' (by rw [size_swap]; assumption; done)
       else
-        a
+        xs

src/Init/Data/Array/Lex/Basic.lean

@@ -8,17 +8,18 @@ import Init.Data.Array.Basic
 import Init.Data.Nat.Lemmas
 import Init.Data.Range
 
--- set_option linter.listVariables true -- Enforce naming conventions for `List`/`Array`/`Vector` variables.
--- set_option linter.indexVariables true -- Enforce naming conventions for index variables.
+set_option linter.listVariables true -- Enforce naming conventions for `List`/`Array`/`Vector` variables.
+set_option linter.indexVariables true -- Enforce naming conventions for index variables.
 
 namespace Array
 
 /--
-Lexicographic comparator for arrays.
+Compares arrays lexicographically with respect to a comparison `lt` on their elements.
 
-`lex as bs lt` is true if
-- `bs` is larger than `as` and `as` is pairwise equivalent via `==` to the initial segment of `bs`, or
-- there is an index `i` such that `lt as[i] bs[i]`, and for all `j < i`, `as[j] == bs[j]`.
+Specifically, `Array.lex as bs lt` is true if
+* `bs` is larger than `as` and `as` is pairwise equivalent via `==` to the initial segment of `bs`,
+  or
+* there is an index `i` such that `lt as[i] bs[i]`, and for all `j < i`, `as[j] == bs[j]`.
 -/
 def lex [BEq α] (as bs : Array α) (lt : α → α → Bool := by exact (· < ·)) : Bool := Id.run do
   for h : i in [0 : min as.size bs.size] do

src/Init/Data/Array/Lex/Lemmas.lean

@@ -7,6 +7,9 @@ prelude
 import Init.Data.Array.Lemmas
 import Init.Data.List.Lex
 
+set_option linter.listVariables true -- Enforce naming conventions for `List`/`Array`/`Vector` variables.
+set_option linter.indexVariables true -- Enforce naming conventions for index variables.
+
 namespace Array
 
 /-! ### Lexicographic ordering -/
@@ -14,15 +17,15 @@ namespace Array
 @[simp] theorem _root_.List.lt_toArray [LT α] (l₁ l₂ : List α) : l₁.toArray < l₂.toArray ↔ l₁ < l₂ := Iff.rfl
 @[simp] theorem _root_.List.le_toArray [LT α] (l₁ l₂ : List α) : l₁.toArray ≤ l₂.toArray ↔ l₁ ≤ l₂ := Iff.rfl
 
-@[simp] theorem lt_toList [LT α] (l₁ l₂ : Array α) : l₁.toList < l₂.toList ↔ l₁ < l₂ := Iff.rfl
-@[simp] theorem le_toList [LT α] (l₁ l₂ : Array α) : l₁.toList ≤ l₂.toList ↔ l₁ ≤ l₂ := Iff.rfl
+@[simp] theorem lt_toList [LT α] (xs ys : Array α) : xs.toList < ys.toList ↔ xs < ys := Iff.rfl
+@[simp] theorem le_toList [LT α] (xs ys : Array α) : xs.toList ≤ ys.toList ↔ xs ≤ ys := Iff.rfl
 
 protected theorem not_lt_iff_ge [LT α] (l₁ l₂ : List α) : ¬ l₁ < l₂ ↔ l₂ ≤ l₁ := Iff.rfl
 protected theorem not_le_iff_gt [DecidableEq α] [LT α] [DecidableLT α] (l₁ l₂ : List α) :
     ¬ l₁ ≤ l₂ ↔ l₂ < l₁ :=
   Decidable.not_not
 
-@[simp] theorem lex_empty [BEq α] {lt : α → α → Bool} (l : Array α) : l.lex #[] lt = false := by
+@[simp] theorem lex_empty [BEq α] {lt : α → α → Bool} (xs : Array α) : xs.lex #[] lt = false := by
   simp [lex, Id.run]
 
 @[simp] theorem singleton_lex_singleton [BEq α] {lt : α → α → Bool} : #[a].lex #[b] lt = lt a b := by
@@ -52,35 +55,35 @@ private theorem cons_lex_cons [BEq α] {lt : α → α → Bool} {a b : α} {xs
     | cons y l₂ =>
       rw [List.toArray_cons, List.toArray_cons y, cons_lex_cons, List.lex, ih]
 
-@[simp] theorem lex_toList [BEq α] (lt : α → α → Bool) (l₁ l₂ : Array α) :
-    l₁.toList.lex l₂.toList lt = l₁.lex l₂ lt := by
-  cases l₁ <;> cases l₂ <;> simp
+@[simp] theorem lex_toList [BEq α] (lt : α → α → Bool) (xs ys : Array α) :
+    xs.toList.lex ys.toList lt = xs.lex ys lt := by
+  cases xs <;> cases ys <;> simp
 
-protected theorem lt_irrefl [LT α] [Std.Irrefl (· < · : α → α → Prop)] (l : Array α) : ¬ l < l :=
-  List.lt_irrefl l.toList
+protected theorem lt_irrefl [LT α] [Std.Irrefl (· < · : α → α → Prop)] (xs : Array α) : ¬ xs < xs :=
+  List.lt_irrefl xs.toList
 
 instance ltIrrefl [LT α] [Std.Irrefl (· < · : α → α → Prop)] : Std.Irrefl (α := Array α) (· < ·) where
   irrefl := Array.lt_irrefl
 
-@[simp] theorem not_lt_empty [LT α] (l : Array α) : ¬ l < #[] := List.not_lt_nil l.toList
-@[simp] theorem empty_le [LT α] (l : Array α) : #[] ≤ l := List.nil_le l.toList
+@[simp] theorem not_lt_empty [LT α] (xs : Array α) : ¬ xs < #[] := List.not_lt_nil xs.toList
+@[simp] theorem empty_le [LT α] (xs : Array α) : #[] ≤ xs := List.nil_le xs.toList
 
-@[simp] theorem le_empty [LT α] (l : Array α) : l ≤ #[] ↔ l = #[] := by
-  cases l
+@[simp] theorem le_empty [LT α] (xs : Array α) : xs ≤ #[] ↔ xs = #[] := by
+  cases xs
   simp
 
-@[simp] theorem empty_lt_push [LT α] (l : Array α) (a : α) : #[] < l.push a := by
-  rcases l with (_ | ⟨x, l⟩) <;> simp
+@[simp] theorem empty_lt_push [LT α] (xs : Array α) (a : α) : #[] < xs.push a := by
+  rcases xs with (_ | ⟨x, xs⟩) <;> simp
 
-protected theorem le_refl [LT α] [i₀ : Std.Irrefl (· < · : α → α → Prop)] (l : Array α) : l ≤ l :=
-  List.le_refl l.toList
+protected theorem le_refl [LT α] [i₀ : Std.Irrefl (· < · : α → α → Prop)] (xs : Array α) : xs ≤ xs :=
+  List.le_refl xs.toList
 
 instance [LT α] [Std.Irrefl (· < · : α → α → Prop)] : Std.Refl (· ≤ · : Array α → Array α → Prop) where
   refl := Array.le_refl
 
 protected theorem lt_trans [LT α]
     [i₁ : Trans (· < · : α → α → Prop) (· < ·) (· < ·)]
-    {l₁ l₂ l₃ : Array α} (h₁ : l₁ < l₂) (h₂ : l₂ < l₃) : l₁ < l₃ :=
+    {xs ys zs : Array α} (h₁ : xs < ys) (h₂ : ys < zs) : xs < zs :=
   List.lt_trans h₁ h₂
 
 instance [LT α] [Trans (· < · : α → α → Prop) (· < ·) (· < ·)] :
@@ -92,7 +95,7 @@ protected theorem lt_of_le_of_lt [DecidableEq α] [LT α] [DecidableLT α]
     [i₁ : Std.Asymm (· < · : α → α → Prop)]
     [i₂ : Std.Antisymm (¬ · < · : α → α → Prop)]
     [i₃ : Trans (¬ · < · : α → α → Prop) (¬ · < ·) (¬ · < ·)]
-    {l₁ l₂ l₃ : Array α} (h₁ : l₁ ≤ l₂) (h₂ : l₂ < l₃) : l₁ < l₃ :=
+    {xs ys zs : Array α} (h₁ : xs ≤ ys) (h₂ : ys < zs) : xs < zs :=
   List.lt_of_le_of_lt h₁ h₂
 
 protected theorem le_trans [DecidableEq α] [LT α] [DecidableLT α]
@@ -100,7 +103,7 @@ protected theorem le_trans [DecidableEq α] [LT α] [DecidableLT α]
     [Std.Asymm (· < · : α → α → Prop)]
     [Std.Antisymm (¬ · < · : α → α → Prop)]
     [Trans (¬ · < · : α → α → Prop) (¬ · < ·) (¬ · < ·)]
-    {l₁ l₂ l₃ : Array α} (h₁ : l₁ ≤ l₂) (h₂ : l₂ ≤ l₃) : l₁ ≤ l₃ :=
+    {xs ys zs : Array α} (h₁ : xs ≤ ys) (h₂ : ys ≤ zs) : xs ≤ zs :=
   fun h₃ => h₁ (Array.lt_of_le_of_lt h₂ h₃)
 
 instance [DecidableEq α] [LT α] [DecidableLT α]
@@ -113,7 +116,7 @@ instance [DecidableEq α] [LT α] [DecidableLT α]
 
 protected theorem lt_asymm [LT α]
     [i : Std.Asymm (· < · : α → α → Prop)]
-    {l₁ l₂ : Array α} (h : l₁ < l₂) : ¬ l₂ < l₁ := List.lt_asymm h
+    {xs ys : Array α} (h : xs < ys) : ¬ ys < xs := List.lt_asymm h
 
 instance [DecidableEq α] [LT α] [DecidableLT α]
     [Std.Asymm (· < · : α → α → Prop)] :
@@ -121,26 +124,26 @@ instance [DecidableEq α] [LT α] [DecidableLT α]
   asymm _ _ := Array.lt_asymm
 
 protected theorem le_total [DecidableEq α] [LT α] [DecidableLT α]
-    [i : Std.Total (¬ · < · : α → α → Prop)] (l₁ l₂ : Array α) : l₁ ≤ l₂ ∨ l₂ ≤ l₁ :=
-  List.le_total _ _
+    [i : Std.Total (¬ · < · : α → α → Prop)] (xs ys : Array α) : xs ≤ ys ∨ ys ≤ xs :=
+  List.le_total xs.toList ys.toList
 
 @[simp] protected theorem not_lt [LT α]
-    {l₁ l₂ : Array α} : ¬ l₁ < l₂ ↔ l₂ ≤ l₁ := Iff.rfl
+    {xs ys : Array α} : ¬ xs < ys ↔ ys ≤ xs := Iff.rfl
 
 @[simp] protected theorem not_le [DecidableEq α] [LT α] [DecidableLT α]
-    {l₁ l₂ : Array α} : ¬ l₂ ≤ l₁ ↔ l₁ < l₂ := Decidable.not_not
+    {xs ys : Array α} : ¬ ys ≤ xs ↔ xs < ys := Decidable.not_not
 
 protected theorem le_of_lt [DecidableEq α] [LT α] [DecidableLT α]
     [i : Std.Total (¬ · < · : α → α → Prop)]
-    {l₁ l₂ : Array α} (h : l₁ < l₂) : l₁ ≤ l₂ :=
+    {xs ys : Array α} (h : xs < ys) : xs ≤ ys :=
   List.le_of_lt h
 
 protected theorem le_iff_lt_or_eq [DecidableEq α] [LT α] [DecidableLT α]
     [Std.Irrefl (· < · : α → α → Prop)]
     [Std.Antisymm (¬ · < · : α → α → Prop)]
     [Std.Total (¬ · < · : α → α → Prop)]
-    {l₁ l₂ : Array α} : l₁ ≤ l₂ ↔ l₁ < l₂ ∨ l₁ = l₂ := by
-  simpa using List.le_iff_lt_or_eq (l₁ := l₁.toList) (l₂ := l₂.toList)
+    {xs ys : Array α} : xs ≤ ys ↔ xs < ys ∨ xs = ys := by
+  simpa using List.le_iff_lt_or_eq (l₁ := xs.toList) (l₂ := ys.toList)
 
 instance [DecidableEq α] [LT α] [DecidableLT α]
     [Std.Total (¬ · < · : α → α → Prop)] :
@@ -148,22 +151,22 @@ instance [DecidableEq α] [LT α] [DecidableLT α]
   total := Array.le_total
 
 @[simp] theorem lex_eq_true_iff_lt [DecidableEq α] [LT α] [DecidableLT α]
-    {l₁ l₂ : Array α} : lex l₁ l₂ = true ↔ l₁ < l₂ := by
-  cases l₁
-  cases l₂
+    {xs ys : Array α} : lex xs ys = true ↔ xs < ys := by
+  cases xs
+  cases ys
   simp
 
 @[simp] theorem lex_eq_false_iff_ge [DecidableEq α] [LT α] [DecidableLT α]
-    {l₁ l₂ : Array α} : lex l₁ l₂ = false ↔ l₂ ≤ l₁ := by
-  cases l₁
-  cases l₂
+    {xs ys : Array α} : lex xs ys = false ↔ ys ≤ xs := by
+  cases xs
+  cases ys
   simp [List.not_lt_iff_ge]
 
 instance [DecidableEq α] [LT α] [DecidableLT α] : DecidableLT (Array α) :=
-  fun l₁ l₂ => decidable_of_iff (lex l₁ l₂ = true) lex_eq_true_iff_lt
+  fun xs ys => decidable_of_iff (lex xs ys = true) lex_eq_true_iff_lt
 
 instance [DecidableEq α] [LT α] [DecidableLT α] : DecidableLE (Array α) :=
-  fun l₁ l₂ => decidable_of_iff (lex l₂ l₁ = false) lex_eq_false_iff_ge
+  fun xs ys => decidable_of_iff (lex ys xs = false) lex_eq_false_iff_ge
 
 /--
 `l₁` is lexicographically less than `l₂` if either
@@ -211,58 +214,58 @@ theorem lex_eq_false_iff_exists [BEq α] [PartialEquivBEq α] (lt : α → α
   cases l₂
   simp_all [List.lex_eq_false_iff_exists]
 
-protected theorem lt_iff_exists [DecidableEq α] [LT α] [DecidableLT α] {l₁ l₂ : Array α} :
-    l₁ < l₂ ↔
-      (l₁ = l₂.take l₁.size ∧ l₁.size < l₂.size) ∨
-        (∃ (i : Nat) (h₁ : i < l₁.size) (h₂ : i < l₂.size),
+protected theorem lt_iff_exists [DecidableEq α] [LT α] [DecidableLT α] {xs ys : Array α} :
+    xs < ys ↔
+      (xs = ys.take xs.size ∧ xs.size < ys.size) ∨
+        (∃ (i : Nat) (h₁ : i < xs.size) (h₂ : i < ys.size),
           (∀ j, (hj : j < i) →
-            l₁[j]'(Nat.lt_trans hj h₁) = l₂[j]'(Nat.lt_trans hj h₂)) ∧ l₁[i] < l₂[i]) := by
-  cases l₁
-  cases l₂
+            xs[j]'(Nat.lt_trans hj h₁) = ys[j]'(Nat.lt_trans hj h₂)) ∧ xs[i] < ys[i]) := by
+  cases xs
+  cases ys
   simp [List.lt_iff_exists]
 
 protected theorem le_iff_exists [DecidableEq α] [LT α] [DecidableLT α]
     [Std.Irrefl (· < · : α → α → Prop)]
     [Std.Asymm (· < · : α → α → Prop)]
-    [Std.Antisymm (¬ · < · : α → α → Prop)] {l₁ l₂ : Array α} :
-    l₁ ≤ l₂ ↔
-      (l₁ = l₂.take l₁.size) ∨
-        (∃ (i : Nat) (h₁ : i < l₁.size) (h₂ : i < l₂.size),
+    [Std.Antisymm (¬ · < · : α → α → Prop)] {xs ys : Array α} :
+    xs ≤ ys ↔
+      (xs = ys.take xs.size) ∨
+        (∃ (i : Nat) (h₁ : i < xs.size) (h₂ : i < ys.size),
           (∀ j, (hj : j < i) →
-            l₁[j]'(Nat.lt_trans hj h₁) = l₂[j]'(Nat.lt_trans hj h₂)) ∧ l₁[i] < l₂[i]) := by
-  cases l₁
-  cases l₂
+            xs[j]'(Nat.lt_trans hj h₁) = ys[j]'(Nat.lt_trans hj h₂)) ∧ xs[i] < ys[i]) := by
+  cases xs
+  cases ys
   simp [List.le_iff_exists]
 
-theorem append_left_lt [LT α] {l₁ l₂ l₃ : Array α} (h : l₂ < l₃) :
-    l₁ ++ l₂ < l₁ ++ l₃ := by
-  cases l₁
-  cases l₂
-  cases l₃
+theorem append_left_lt [LT α] {xs ys zs : Array α} (h : ys < zs) :
+    xs ++ ys < xs ++ zs := by
+  cases xs
+  cases ys
+  cases zs
   simpa using List.append_left_lt h
 
 theorem append_left_le [DecidableEq α] [LT α] [DecidableLT α]
     [Std.Irrefl (· < · : α → α → Prop)]
     [Std.Asymm (· < · : α → α → Prop)]
     [Std.Antisymm (¬ · < · : α → α → Prop)]
-    {l₁ l₂ l₃ : Array α} (h : l₂ ≤ l₃) :
-    l₁ ++ l₂ ≤ l₁ ++ l₃ := by
-  cases l₁
-  cases l₂
-  cases l₃
+    {xs ys zs : Array α} (h : ys ≤ zs) :
+    xs ++ ys ≤ xs ++ zs := by
+  cases xs
+  cases ys
+  cases zs
   simpa using List.append_left_le h
 
 theorem le_append_left [LT α] [Std.Irrefl (· < · : α → α → Prop)]
-    {l₁ l₂ : Array α} : l₁ ≤ l₁ ++ l₂ := by
-  cases l₁
-  cases l₂
+    {xs ys : Array α} : xs ≤ xs ++ ys := by
+  cases xs
+  cases ys
   simpa using List.le_append_left
 
 protected theorem map_lt [LT α] [LT β]
-    {l₁ l₂ : Array α} {f : α → β} (w : ∀ x y, x < y → f x < f y) (h : l₁ < l₂) :
-    map f l₁ < map f l₂ := by
-  cases l₁
-  cases l₂
+    {xs ys : Array α} {f : α → β} (w : ∀ x y, x < y → f x < f y) (h : xs < ys) :
+    map f xs < map f ys := by
+  cases xs
+  cases ys
   simpa using List.map_lt w h
 
 protected theorem map_le [DecidableEq α] [LT α] [DecidableLT α] [DecidableEq β] [LT β] [DecidableLT β]
@@ -272,10 +275,10 @@ protected theorem map_le [DecidableEq α] [LT α] [DecidableLT α] [DecidableEq
     [Std.Irrefl (· < · : β → β → Prop)]
     [Std.Asymm (· < · : β → β → Prop)]
     [Std.Antisymm (¬ · < · : β → β → Prop)]
-    {l₁ l₂ : Array α} {f : α → β} (w : ∀ x y, x < y → f x < f y) (h : l₁ ≤ l₂) :
-    map f l₁ ≤ map f l₂ := by
-  cases l₁
-  cases l₂
+    {xs ys : Array α} {f : α → β} (w : ∀ x y, x < y → f x < f y) (h : xs ≤ ys) :
+    map f xs ≤ map f ys := by
+  cases xs
+  cases ys
   simpa using List.map_le w h
 
 end Array

src/Init/Data/Array/MapIdx.lean

@@ -6,28 +6,32 @@ Authors: Mario Carneiro, Kim Morrison
 prelude
 import Init.Data.Array.Lemmas
 import Init.Data.Array.Attach
+import Init.Data.Array.OfFn
 import Init.Data.List.MapIdx
 
+set_option linter.listVariables true -- Enforce naming conventions for `List`/`Array`/`Vector` variables.
+set_option linter.indexVariables true -- Enforce naming conventions for index variables.
+
 namespace Array
 
 /-! ### mapFinIdx -/
 
 -- This could also be proved from `SatisfiesM_mapIdxM` in Batteries.
-theorem mapFinIdx_induction (as : Array α) (f : (i : Nat) → α → (h : i < as.size) → β)
+theorem mapFinIdx_induction (xs : Array α) (f : (i : Nat) → α → (h : i < xs.size) → β)
     (motive : Nat → Prop) (h0 : motive 0)
-    (p : (i : Nat) → β → (h : i < as.size) → Prop)
-    (hs : ∀ i h, motive i → p i (f i as[i] h) h ∧ motive (i + 1)) :
-    motive as.size ∧ ∃ eq : (Array.mapFinIdx as f).size = as.size,
-      ∀ i h, p i ((Array.mapFinIdx as f)[i]) h := by
+    (p : (i : Nat) → β → (h : i < xs.size) → Prop)
+    (hs : ∀ i h, motive i → p i (f i xs[i] h) h ∧ motive (i + 1)) :
+    motive xs.size ∧ ∃ eq : (Array.mapFinIdx xs f).size = xs.size,
+      ∀ i h, p i ((Array.mapFinIdx xs f)[i]) h := by
   let rec go {bs i j h} (h₁ : j = bs.size) (h₂ : ∀ i h h', p i bs[i] h) (hm : motive j) :
-    let arr : Array β := Array.mapFinIdxM.map (m := Id) as f i j h bs
-    motive as.size ∧ ∃ eq : arr.size = as.size, ∀ i h, p i arr[i] h := by
+    let as : Array β := Array.mapFinIdxM.map (m := Id) xs f i j h bs
+    motive xs.size ∧ ∃ eq : as.size = xs.size, ∀ i h, p i as[i] h := by
     induction i generalizing j bs with simp [mapFinIdxM.map]
     | zero =>
       have := (Nat.zero_add _).symm.trans h
       exact ⟨this ▸ hm, h₁ ▸ this, fun _ _ => h₂ ..⟩
     | succ i ih =>
-      apply @ih (bs.push (f j as[j] (by omega))) (j + 1) (by omega) (by simp; omega)
+      apply @ih (bs.push (f j xs[j] (by omega))) (j + 1) (by omega) (by simp; omega)
       · intro i i_lt h'
         rw [getElem_push]
         split
@@ -38,67 +42,67 @@ theorem mapFinIdx_induction (as : Array α) (f : (i : Nat) → α → (h : i < a
       · exact (hs j (by omega) hm).2
   simp [mapFinIdx, mapFinIdxM]; exact go rfl nofun h0
 
-theorem mapFinIdx_spec (as : Array α) (f : (i : Nat) → α → (h : i < as.size) → β)
-    (p : (i : Nat) → β → (h : i < as.size) → Prop) (hs : ∀ i h, p i (f i as[i] h) h) :
-    ∃ eq : (Array.mapFinIdx as f).size = as.size,
-      ∀ i h, p i ((Array.mapFinIdx as f)[i]) h :=
+theorem mapFinIdx_spec (xs : Array α) (f : (i : Nat) → α → (h : i < xs.size) → β)
+    (p : (i : Nat) → β → (h : i < xs.size) → Prop) (hs : ∀ i h, p i (f i xs[i] h) h) :
+    ∃ eq : (Array.mapFinIdx xs f).size = xs.size,
+      ∀ i h, p i ((Array.mapFinIdx xs f)[i]) h :=
   (mapFinIdx_induction _ _ (fun _ => True) trivial p fun _ _ _ => ⟨hs .., trivial⟩).2
 
-@[simp] theorem size_mapFinIdx (a : Array α) (f : (i : Nat) → α → (h : i < a.size) → β) :
-    (a.mapFinIdx f).size = a.size :=
+@[simp] theorem size_mapFinIdx (xs : Array α) (f : (i : Nat) → α → (h : i < xs.size) → β) :
+    (xs.mapFinIdx f).size = xs.size :=
   (mapFinIdx_spec (p := fun _ _ _ => True) (hs := fun _ _ => trivial)).1
 
-@[simp] theorem size_zipIdx (as : Array α) (k : Nat) : (as.zipIdx k).size = as.size :=
+@[simp] theorem size_zipIdx (xs : Array α) (k : Nat) : (xs.zipIdx k).size = xs.size :=
   Array.size_mapFinIdx _ _
 
 @[deprecated size_zipIdx (since := "2025-01-21")] abbrev size_zipWithIndex := @size_zipIdx
 
-@[simp] theorem getElem_mapFinIdx (a : Array α) (f : (i : Nat) → α → (h : i < a.size) → β) (i : Nat)
-    (h : i < (mapFinIdx a f).size) :
-    (a.mapFinIdx f)[i] = f i (a[i]'(by simp_all))  (by simp_all) :=
-  (mapFinIdx_spec _ _ (fun i b h => b = f i a[i] h) fun _ _ => rfl).2 i _
+@[simp] theorem getElem_mapFinIdx (xs : Array α) (f : (i : Nat) → α → (h : i < xs.size) → β) (i : Nat)
+    (h : i < (xs.mapFinIdx f).size) :
+    (xs.mapFinIdx f)[i] = f i (xs[i]'(by simp_all)) (by simp_all) :=
+  (mapFinIdx_spec _ _ (fun i b h => b = f i xs[i] h) fun _ _ => rfl).2 i _
 
-@[simp] theorem getElem?_mapFinIdx (a : Array α) (f : (i : Nat) → α → (h : i < a.size) → β) (i : Nat) :
-    (a.mapFinIdx f)[i]? =
-      a[i]?.pbind fun b h => f i b (getElem?_eq_some_iff.1 h).1 := by
+@[simp] theorem getElem?_mapFinIdx (xs : Array α) (f : (i : Nat) → α → (h : i < xs.size) → β) (i : Nat) :
+    (xs.mapFinIdx f)[i]? =
+      xs[i]?.pbind fun b h => f i b (getElem?_eq_some_iff.1 h).1 := by
   simp only [getElem?_def, size_mapFinIdx, getElem_mapFinIdx]
   split <;> simp_all
 
-@[simp] theorem toList_mapFinIdx (a : Array α) (f : (i : Nat) → α → (h : i < a.size) → β) :
-    (a.mapFinIdx f).toList = a.toList.mapFinIdx (fun i a h => f i a (by simpa)) := by
+@[simp] theorem toList_mapFinIdx (xs : Array α) (f : (i : Nat) → α → (h : i < xs.size) → β) :
+    (xs.mapFinIdx f).toList = xs.toList.mapFinIdx (fun i a h => f i a (by simpa)) := by
   apply List.ext_getElem <;> simp
 
 /-! ### mapIdx -/
 
-theorem mapIdx_induction (f : Nat → α → β) (as : Array α)
+theorem mapIdx_induction (f : Nat → α → β) (xs : Array α)
     (motive : Nat → Prop) (h0 : motive 0)
-    (p : (i : Nat) → β → (h : i < as.size) → Prop)
-    (hs : ∀ i h, motive i → p i (f i as[i]) h ∧ motive (i + 1)) :
-    motive as.size ∧ ∃ eq : (as.mapIdx f).size = as.size,
-      ∀ i h, p i ((as.mapIdx f)[i]) h :=
-  mapFinIdx_induction as (fun i a _ => f i a) motive h0 p hs
+    (p : (i : Nat) → β → (h : i < xs.size) → Prop)
+    (hs : ∀ i h, motive i → p i (f i xs[i]) h ∧ motive (i + 1)) :
+    motive xs.size ∧ ∃ eq : (xs.mapIdx f).size = xs.size,
+      ∀ i h, p i ((xs.mapIdx f)[i]) h :=
+  mapFinIdx_induction xs (fun i a _ => f i a) motive h0 p hs
 
-theorem mapIdx_spec (f : Nat → α → β) (as : Array α)
-    (p : (i : Nat) → β → (h : i < as.size) → Prop) (hs : ∀ i h, p i (f i as[i]) h) :
-    ∃ eq : (as.mapIdx f).size = as.size,
-      ∀ i h, p i ((as.mapIdx f)[i]) h :=
+theorem mapIdx_spec (f : Nat → α → β) (xs : Array α)
+    (p : (i : Nat) → β → (h : i < xs.size) → Prop) (hs : ∀ i h, p i (f i xs[i]) h) :
+    ∃ eq : (xs.mapIdx f).size = xs.size,
+      ∀ i h, p i ((xs.mapIdx f)[i]) h :=
   (mapIdx_induction _ _ (fun _ => True) trivial p fun _ _ _ => ⟨hs .., trivial⟩).2
 
-@[simp] theorem size_mapIdx (f : Nat → α → β) (as : Array α) : (as.mapIdx f).size = as.size :=
+@[simp] theorem size_mapIdx (f : Nat → α → β) (xs : Array α) : (xs.mapIdx f).size = xs.size :=
   (mapIdx_spec (p := fun _ _ _ => True) (hs := fun _ _ => trivial)).1
 
-@[simp] theorem getElem_mapIdx (f : Nat → α → β) (as : Array α) (i : Nat)
-    (h : i < (as.mapIdx f).size) :
-    (as.mapIdx f)[i] = f i (as[i]'(by simp_all)) :=
-  (mapIdx_spec _ _ (fun i b h => b = f i as[i]) fun _ _ => rfl).2 i (by simp_all)
+@[simp] theorem getElem_mapIdx (f : Nat → α → β) (xs : Array α) (i : Nat)
+    (h : i < (xs.mapIdx f).size) :
+    (xs.mapIdx f)[i] = f i (xs[i]'(by simp_all)) :=
+  (mapIdx_spec _ _ (fun i b h => b = f i xs[i]) fun _ _ => rfl).2 i (by simp_all)
 
-@[simp] theorem getElem?_mapIdx (f : Nat → α → β) (as : Array α) (i : Nat) :
-    (as.mapIdx f)[i]? =
-      as[i]?.map (f i) := by
+@[simp] theorem getElem?_mapIdx (f : Nat → α → β) (xs : Array α) (i : Nat) :
+    (xs.mapIdx f)[i]? =
+      xs[i]?.map (f i) := by
   simp [getElem?_def, size_mapIdx, getElem_mapIdx]
 
-@[simp] theorem toList_mapIdx (f : Nat → α → β) (as : Array α) :
-    (as.mapIdx f).toList = as.toList.mapIdx (fun i a => f i a) := by
+@[simp] theorem toList_mapIdx (f : Nat → α → β) (xs : Array α) :
+    (xs.mapIdx f).toList = xs.toList.mapIdx (fun i a => f i a) := by
   apply List.ext_getElem <;> simp
 
 end Array
@@ -119,8 +123,8 @@ namespace Array
 
 /-! ### zipIdx -/
 
-@[simp] theorem getElem_zipIdx (a : Array α) (k : Nat) (i : Nat) (h : i < (a.zipIdx k).size) :
-    (a.zipIdx k)[i] = (a[i]'(by simp_all), k + i) := by
+@[simp] theorem getElem_zipIdx (xs : Array α) (k : Nat) (i : Nat) (h : i < (xs.zipIdx k).size) :
+    (xs.zipIdx k)[i] = (xs[i]'(by simp_all), k + i) := by
   simp [zipIdx]
 
 @[deprecated getElem_zipIdx (since := "2025-01-21")]
@@ -133,35 +137,35 @@ abbrev getElem_zipWithIndex := @getElem_zipIdx
 @[deprecated zipIdx_toArray (since := "2025-01-21")]
 abbrev zipWithIndex_toArray := @zipIdx_toArray
 
-@[simp] theorem toList_zipIdx (a : Array α) (k : Nat) :
-    (a.zipIdx k).toList = a.toList.zipIdx k := by
-  rcases a with ⟨a⟩
+@[simp] theorem toList_zipIdx (xs : Array α) (k : Nat) :
+    (xs.zipIdx k).toList = xs.toList.zipIdx k := by
+  rcases xs with ⟨xs⟩
   simp
 
 @[deprecated toList_zipIdx (since := "2025-01-21")]
 abbrev toList_zipWithIndex := @toList_zipIdx
 
-theorem mk_mem_zipIdx_iff_le_and_getElem?_sub {k i : Nat} {x : α} {l : Array α} :
-    (x, i) ∈ zipIdx l k ↔ k ≤ i ∧ l[i - k]? = some x := by
-  rcases l with ⟨l⟩
+theorem mk_mem_zipIdx_iff_le_and_getElem?_sub {k i : Nat} {x : α} {xs : Array α} :
+    (x, i) ∈ xs.zipIdx k ↔ k ≤ i ∧ xs[i - k]? = some x := by
+  rcases xs with ⟨xs⟩
   simp [List.mk_mem_zipIdx_iff_le_and_getElem?_sub]
 
 /-- Variant of `mk_mem_zipIdx_iff_le_and_getElem?_sub` specialized at `k = 0`,
 to avoid the inequality and the subtraction. -/
-theorem mk_mem_zipIdx_iff_getElem? {x : α} {i : Nat} {l : Array α} :
-    (x, i) ∈ l.zipIdx ↔ l[i]? = x := by
+theorem mk_mem_zipIdx_iff_getElem? {x : α} {i : Nat} {xs : Array α} :
+    (x, i) ∈ xs.zipIdx ↔ xs[i]? = x := by
   rw [mk_mem_zipIdx_iff_le_and_getElem?_sub]
   simp
 
-theorem mem_zipIdx_iff_le_and_getElem?_sub {x : α × Nat} {l : Array α} {k : Nat} :
-    x ∈ zipIdx l k ↔ k ≤ x.2 ∧ l[x.2 - k]? = some x.1 := by
+theorem mem_zipIdx_iff_le_and_getElem?_sub {x : α × Nat} {xs : Array α} {k : Nat} :
+    x ∈ xs.zipIdx k ↔ k ≤ x.2 ∧ xs[x.2 - k]? = some x.1 := by
   cases x
   simp [mk_mem_zipIdx_iff_le_and_getElem?_sub]
 
 /-- Variant of `mem_zipIdx_iff_le_and_getElem?_sub` specialized at `k = 0`,
 to avoid the inequality and the subtraction. -/
-theorem mem_zipIdx_iff_getElem? {x : α × Nat} {l : Array α} :
-    x ∈ l.zipIdx ↔ l[x.2]? = some x.1 := by
+theorem mem_zipIdx_iff_getElem? {x : α × Nat} {xs : Array α} :
+    x ∈ xs.zipIdx ↔ xs[x.2]? = some x.1 := by
   rw [mk_mem_zipIdx_iff_getElem?]
 
 @[deprecated mk_mem_zipIdx_iff_getElem? (since := "2025-01-21")]
@@ -182,31 +186,31 @@ abbrev mem_zipWithIndex_iff_getElem? := @mem_zipIdx_iff_getElem?
 theorem mapFinIdx_empty {f : (i : Nat) → α → (h : i < 0) → β} : mapFinIdx #[] f = #[] :=
   rfl
 
-theorem mapFinIdx_eq_ofFn {as : Array α} {f : (i : Nat) → α → (h : i < as.size) → β} :
-    as.mapFinIdx f = Array.ofFn fun i : Fin as.size => f i as[i] i.2 := by
-  cases as
+theorem mapFinIdx_eq_ofFn {xs : Array α} {f : (i : Nat) → α → (h : i < xs.size) → β} :
+    xs.mapFinIdx f = Array.ofFn fun i : Fin xs.size => f i xs[i] i.2 := by
+  cases xs
   simp [List.mapFinIdx_eq_ofFn]
 
-theorem mapFinIdx_append {K L : Array α} {f : (i : Nat) → α → (h : i < (K ++ L).size) → β} :
-    (K ++ L).mapFinIdx f =
-      K.mapFinIdx (fun i a h => f i a (by simp; omega)) ++
-        L.mapFinIdx (fun i a h => f (i + K.size) a (by simp; omega)) := by
-  cases K
-  cases L
+theorem mapFinIdx_append {xs ys : Array α} {f : (i : Nat) → α → (h : i < (xs ++ ys).size) → β} :
+    (xs ++ ys).mapFinIdx f =
+      xs.mapFinIdx (fun i a h => f i a (by simp; omega)) ++
+        ys.mapFinIdx (fun i a h => f (i + xs.size) a (by simp; omega)) := by
+  cases xs
+  cases ys
   simp [List.mapFinIdx_append]
 
 @[simp]
-theorem mapFinIdx_push {l : Array α} {a : α} {f : (i : Nat) → α → (h : i < (l.push a).size) → β} :
-    mapFinIdx (l.push a) f =
-      (mapFinIdx l (fun i a h => f i a (by simp; omega))).push (f l.size a (by simp)) := by
+theorem mapFinIdx_push {xs : Array α} {a : α} {f : (i : Nat) → α → (h : i < (xs.push a).size) → β} :
+    mapFinIdx (xs.push a) f =
+      (mapFinIdx xs (fun i a h => f i a (by simp; omega))).push (f xs.size a (by simp)) := by
   simp [← append_singleton, mapFinIdx_append]
 
 theorem mapFinIdx_singleton {a : α} {f : (i : Nat) → α → (h : i < 1) → β} :
     #[a].mapFinIdx f = #[f 0 a (by simp)] := by
   simp
 
-theorem mapFinIdx_eq_zipIdx_map {l : Array α} {f : (i : Nat) → α → (h : i < l.size) → β} :
-    l.mapFinIdx f = l.zipIdx.attach.map
+theorem mapFinIdx_eq_zipIdx_map {xs : Array α} {f : (i : Nat) → α → (h : i < xs.size) → β} :
+    xs.mapFinIdx f = xs.zipIdx.attach.map
       fun ⟨⟨x, i⟩, m⟩ =>
         f i x (by simp [mk_mem_zipIdx_iff_getElem?, getElem?_eq_some_iff] at m; exact m.1) := by
   ext <;> simp
@@ -215,44 +219,44 @@ theorem mapFinIdx_eq_zipIdx_map {l : Array α} {f : (i : Nat) → α → (h : i
 abbrev mapFinIdx_eq_zipWithIndex_map := @mapFinIdx_eq_zipIdx_map
 
 @[simp]
-theorem mapFinIdx_eq_empty_iff {l : Array α} {f : (i : Nat) → α → (h : i < l.size) → β} :
-    l.mapFinIdx f = #[] ↔ l = #[] := by
-  cases l
+theorem mapFinIdx_eq_empty_iff {xs : Array α} {f : (i : Nat) → α → (h : i < xs.size) → β} :
+    xs.mapFinIdx f = #[] ↔ xs = #[] := by
+  cases xs
   simp
 
-theorem mapFinIdx_ne_empty_iff {l : Array α} {f : (i : Nat) → α → (h : i < l.size) → β} :
-    l.mapFinIdx f ≠ #[] ↔ l ≠ #[] := by
+theorem mapFinIdx_ne_empty_iff {xs : Array α} {f : (i : Nat) → α → (h : i < xs.size) → β} :
+    xs.mapFinIdx f ≠ #[] ↔ xs ≠ #[] := by
   simp
 
-theorem exists_of_mem_mapFinIdx {b : β} {l : Array α} {f : (i : Nat) → α → (h : i < l.size) → β}
-    (h : b ∈ l.mapFinIdx f) : ∃ (i : Nat) (h : i < l.size), f i l[i] h = b := by
-  rcases l with ⟨l⟩
+theorem exists_of_mem_mapFinIdx {b : β} {xs : Array α} {f : (i : Nat) → α → (h : i < xs.size) → β}
+    (h : b ∈ xs.mapFinIdx f) : ∃ (i : Nat) (h : i < xs.size), f i xs[i] h = b := by
+  rcases xs with ⟨xs⟩
   exact List.exists_of_mem_mapFinIdx (by simpa using h)
 
-@[simp] theorem mem_mapFinIdx {b : β} {l : Array α} {f : (i : Nat) → α → (h : i < l.size) → β} :
-    b ∈ l.mapFinIdx f ↔ ∃ (i : Nat) (h : i < l.size), f i l[i] h = b := by
-  rcases l with ⟨l⟩
+@[simp] theorem mem_mapFinIdx {b : β} {xs : Array α} {f : (i : Nat) → α → (h : i < xs.size) → β} :
+    b ∈ xs.mapFinIdx f ↔ ∃ (i : Nat) (h : i < xs.size), f i xs[i] h = b := by
+  rcases xs with ⟨xs⟩
   simp
 
-theorem mapFinIdx_eq_iff {l : Array α} {f : (i : Nat) → α → (h : i < l.size) → β} :
-    l.mapFinIdx f = l' ↔ ∃ h : l'.size = l.size, ∀ (i : Nat) (h : i < l.size), l'[i] = f i l[i] h := by
-  rcases l with ⟨l⟩
-  rcases l' with ⟨l'⟩
+theorem mapFinIdx_eq_iff {xs : Array α} {f : (i : Nat) → α → (h : i < xs.size) → β} {ys : Array β} :
+    xs.mapFinIdx f = ys ↔ ∃ h : ys.size = xs.size, ∀ (i : Nat) (h : i < xs.size), ys[i] = f i xs[i] h := by
+  rcases xs with ⟨xs⟩
+  rcases ys with ⟨ys⟩
   simpa using List.mapFinIdx_eq_iff
 
-@[simp] theorem mapFinIdx_eq_singleton_iff {l : Array α} {f : (i : Nat) → α → (h : i < l.size) → β} {b : β} :
-    l.mapFinIdx f = #[b] ↔ ∃ (a : α) (w : l = #[a]), f 0 a (by simp [w]) = b := by
-  rcases l with ⟨l⟩
+@[simp] theorem mapFinIdx_eq_singleton_iff {xs : Array α} {f : (i : Nat) → α → (h : i < xs.size) → β} {b : β} :
+    xs.mapFinIdx f = #[b] ↔ ∃ (a : α) (w : xs = #[a]), f 0 a (by simp [w]) = b := by
+  rcases xs with ⟨xs⟩
   simp
 
-theorem mapFinIdx_eq_append_iff {l : Array α} {f : (i : Nat) → α → (h : i < l.size) → β} {l₁ l₂ : Array β} :
-    l.mapFinIdx f = l₁ ++ l₂ ↔
-      ∃ (l₁' : Array α) (l₂' : Array α) (w : l = l₁' ++ l₂'),
-        l₁'.mapFinIdx (fun i a h => f i a (by simp [w]; omega)) = l₁ ∧
-        l₂'.mapFinIdx (fun i a h => f (i + l₁'.size) a (by simp [w]; omega)) = l₂ := by
-  rcases l with ⟨l⟩
-  rcases l₁ with ⟨l₁⟩
-  rcases l₂ with ⟨l₂⟩
+theorem mapFinIdx_eq_append_iff {xs : Array α} {f : (i : Nat) → α → (h : i < xs.size) → β} {ys zs : Array β} :
+    xs.mapFinIdx f = ys ++ zs ↔
+      ∃ (ys' : Array α) (zs' : Array α) (w : xs = ys' ++ zs'),
+        ys'.mapFinIdx (fun i a h => f i a (by simp [w]; omega)) = ys ∧
+        zs'.mapFinIdx (fun i a h => f (i + ys'.size) a (by simp [w]; omega)) = zs := by
+  rcases xs with ⟨l⟩
+  rcases ys with ⟨l₁⟩
+  rcases zs with ⟨l₂⟩
   simp only [List.mapFinIdx_toArray, List.append_toArray, mk.injEq, List.mapFinIdx_eq_append_iff,
     toArray_eq_append_iff]
   constructor
@@ -264,39 +268,42 @@ theorem mapFinIdx_eq_append_iff {l : Array α} {f : (i : Nat) → α → (h : i
     obtain rfl := h₂
     refine ⟨l₁, l₂, by simp_all⟩
 
-theorem mapFinIdx_eq_push_iff {l : Array α} {b : β} {f : (i : Nat) → α → (h : i < l.size) → β} :
-    l.mapFinIdx f = l₂.push b ↔
-      ∃ (l₁ : Array α) (a : α) (w : l = l₁.push a),
-        l₁.mapFinIdx (fun i a h => f i a (by simp [w]; omega)) = l₂ ∧ b = f (l.size - 1) a (by simp [w]) := by
+theorem mapFinIdx_eq_push_iff {xs : Array α} {b : β} {f : (i : Nat) → α → (h : i < xs.size) → β} :
+    xs.mapFinIdx f = ys.push b ↔
+      ∃ (zs : Array α) (a : α) (w : xs = zs.push a),
+        zs.mapFinIdx (fun i a h => f i a (by simp [w]; omega)) = ys ∧ b = f (xs.size - 1) a (by simp [w]) := by
   rw [push_eq_append, mapFinIdx_eq_append_iff]
   constructor
-  · rintro ⟨l₁, l₂, rfl, rfl, h₂⟩
+  · rintro ⟨ys', zs', rfl, rfl, h₂⟩
     simp only [mapFinIdx_eq_singleton_iff, Nat.zero_add] at h₂
     obtain ⟨a, rfl, rfl⟩ := h₂
-    exact ⟨l₁, a, by simp⟩
-  · rintro ⟨l₁, a, rfl, rfl, rfl⟩
-    exact ⟨l₁, #[a], by simp⟩
+    exact ⟨ys', a, by simp⟩
+  · rintro ⟨zs, a, rfl, rfl, rfl⟩
+    exact ⟨zs, #[a], by simp⟩
 
-theorem mapFinIdx_eq_mapFinIdx_iff {l : Array α} {f g : (i : Nat) → α → (h : i < l.size) → β} :
-    l.mapFinIdx f = l.mapFinIdx g ↔ ∀ (i : Nat) (h : i < l.size), f i l[i] h = g i l[i] h := by
+theorem mapFinIdx_eq_mapFinIdx_iff {xs : Array α} {f g : (i : Nat) → α → (h : i < xs.size) → β} :
+    xs.mapFinIdx f = xs.mapFinIdx g ↔ ∀ (i : Nat) (h : i < xs.size), f i xs[i] h = g i xs[i] h := by
   rw [eq_comm, mapFinIdx_eq_iff]
   simp
 
-@[simp] theorem mapFinIdx_mapFinIdx {l : Array α}
-    {f : (i : Nat) → α → (h : i < l.size) → β}
-    {g : (i : Nat) → β → (h : i < (l.mapFinIdx f).size) → γ} :
-    (l.mapFinIdx f).mapFinIdx g = l.mapFinIdx (fun i a h => g i (f i a h) (by simpa using h)) := by
+@[simp] theorem mapFinIdx_mapFinIdx {xs : Array α}
+    {f : (i : Nat) → α → (h : i < xs.size) → β}
+    {g : (i : Nat) → β → (h : i < (xs.mapFinIdx f).size) → γ} :
+    (xs.mapFinIdx f).mapFinIdx g = xs.mapFinIdx (fun i a h => g i (f i a h) (by simpa using h)) := by
   simp [mapFinIdx_eq_iff]
 
-theorem mapFinIdx_eq_mkArray_iff {l : Array α} {f : (i : Nat) → α → (h : i < l.size) → β} {b : β} :
-    l.mapFinIdx f = mkArray l.size b ↔ ∀ (i : Nat) (h : i < l.size), f i l[i] h = b := by
-  rcases l with ⟨l⟩
+theorem mapFinIdx_eq_replicate_iff {xs : Array α} {f : (i : Nat) → α → (h : i < xs.size) → β} {b : β} :
+    xs.mapFinIdx f = replicate xs.size b ↔ ∀ (i : Nat) (h : i < xs.size), f i xs[i] h = b := by
+  rcases xs with ⟨l⟩
   rw [← toList_inj]
   simp [List.mapFinIdx_eq_replicate_iff]
 
-@[simp] theorem mapFinIdx_reverse {l : Array α} {f : (i : Nat) → α → (h : i < l.reverse.size) → β} :
-    l.reverse.mapFinIdx f = (l.mapFinIdx (fun i a h => f (l.size - 1 - i) a (by simp; omega))).reverse := by
-  rcases l with ⟨l⟩
+@[deprecated mapFinIdx_eq_replicate_iff (since := "2025-03-18")]
+abbrev mapFinIdx_eq_mkArray_iff := @mapFinIdx_eq_replicate_iff
+
+@[simp] theorem mapFinIdx_reverse {xs : Array α} {f : (i : Nat) → α → (h : i < xs.reverse.size) → β} :
+    xs.reverse.mapFinIdx f = (xs.mapFinIdx (fun i a h => f (xs.size - 1 - i) a (by simp; omega))).reverse := by
+  rcases xs with ⟨l⟩
   simp [List.mapFinIdx_reverse]
 
 /-! ### mapIdx -/
@@ -305,52 +312,52 @@ theorem mapFinIdx_eq_mkArray_iff {l : Array α} {f : (i : Nat) → α → (h : i
 theorem mapIdx_empty {f : Nat → α → β} : mapIdx f #[] = #[] :=
   rfl
 
-@[simp] theorem mapFinIdx_eq_mapIdx {l : Array α} {f : (i : Nat) → α → (h : i < l.size) → β} {g : Nat → α → β}
-    (h : ∀ (i : Nat) (h : i < l.size), f i l[i] h = g i l[i]) :
-    l.mapFinIdx f = l.mapIdx g := by
+@[simp] theorem mapFinIdx_eq_mapIdx {xs : Array α} {f : (i : Nat) → α → (h : i < xs.size) → β} {g : Nat → α → β}
+    (h : ∀ (i : Nat) (h : i < xs.size), f i xs[i] h = g i xs[i]) :
+    xs.mapFinIdx f = xs.mapIdx g := by
   simp_all [mapFinIdx_eq_iff]
 
-theorem mapIdx_eq_mapFinIdx {l : Array α} {f : Nat → α → β} :
-    l.mapIdx f = l.mapFinIdx (fun i a _ => f i a) := by
+theorem mapIdx_eq_mapFinIdx {xs : Array α} {f : Nat → α → β} :
+    xs.mapIdx f = xs.mapFinIdx (fun i a _ => f i a) := by
   simp [mapFinIdx_eq_mapIdx]
 
-theorem mapIdx_eq_zipIdx_map {l : Array α} {f : Nat → α → β} :
-    l.mapIdx f = l.zipIdx.map fun ⟨a, i⟩ => f i a := by
+theorem mapIdx_eq_zipIdx_map {xs : Array α} {f : Nat → α → β} :
+    xs.mapIdx f = xs.zipIdx.map fun ⟨a, i⟩ => f i a := by
   ext <;> simp
 
 @[deprecated mapIdx_eq_zipIdx_map (since := "2025-01-21")]
 abbrev mapIdx_eq_zipWithIndex_map := @mapIdx_eq_zipIdx_map
 
-theorem mapIdx_append {K L : Array α} :
-    (K ++ L).mapIdx f = K.mapIdx f ++ L.mapIdx fun i => f (i + K.size) := by
-  rcases K with ⟨K⟩
-  rcases L with ⟨L⟩
+theorem mapIdx_append {xs ys : Array α} :
+    (xs ++ ys).mapIdx f = xs.mapIdx f ++ ys.mapIdx (fun i => f (i + xs.size)) := by
+  rcases xs with ⟨xs⟩
+  rcases ys with ⟨ys⟩
   simp [List.mapIdx_append]
 
 @[simp]
-theorem mapIdx_push {l : Array α} {a : α} :
-    mapIdx f (l.push a) = (mapIdx f l).push (f l.size a) := by
+theorem mapIdx_push {xs : Array α} {a : α} :
+    mapIdx f (xs.push a) = (mapIdx f xs).push (f xs.size a) := by
   simp [← append_singleton, mapIdx_append]
 
 theorem mapIdx_singleton {a : α} : mapIdx f #[a] = #[f 0 a] := by
   simp
 
 @[simp]
-theorem mapIdx_eq_empty_iff {l : Array α} : mapIdx f l = #[] ↔ l = #[] := by
-  rcases l with ⟨l⟩
+theorem mapIdx_eq_empty_iff {xs : Array α} : mapIdx f xs = #[] ↔ xs = #[] := by
+  rcases xs with ⟨xs⟩
   simp
 
-theorem mapIdx_ne_empty_iff {l : Array α} :
-    mapIdx f l ≠ #[] ↔ l ≠ #[] := by
+theorem mapIdx_ne_empty_iff {xs : Array α} :
+    mapIdx f xs ≠ #[] ↔ xs ≠ #[] := by
   simp
 
-theorem exists_of_mem_mapIdx {b : β} {l : Array α}
-    (h : b ∈ mapIdx f l) : ∃ (i : Nat) (h : i < l.size), f i l[i] = b := by
+theorem exists_of_mem_mapIdx {b : β} {xs : Array α}
+    (h : b ∈ mapIdx f xs) : ∃ (i : Nat) (h : i < xs.size), f i xs[i] = b := by
   rw [mapIdx_eq_mapFinIdx] at h
   simpa [Fin.exists_iff] using exists_of_mem_mapFinIdx h
 
-@[simp] theorem mem_mapIdx {b : β} {l : Array α} :
-    b ∈ mapIdx f l ↔ ∃ (i : Nat) (h : i < l.size), f i l[i] = b := by
+@[simp] theorem mem_mapIdx {b : β} {xs : Array α} :
+    b ∈ mapIdx f xs ↔ ∃ (i : Nat) (h : i < xs.size), f i xs[i] = b := by
   constructor
   · intro h
     exact exists_of_mem_mapIdx h
@@ -358,30 +365,30 @@ theorem exists_of_mem_mapIdx {b : β} {l : Array α}
     rw [mem_iff_getElem]
     exact ⟨i, by simpa using h, by simp⟩
 
-theorem mapIdx_eq_push_iff {l : Array α} {b : β} :
-    mapIdx f l = l₂.push b ↔
-      ∃ (a : α) (l₁ : Array α), l = l₁.push a ∧ mapIdx f l₁ = l₂ ∧ f l₁.size a = b := by
+theorem mapIdx_eq_push_iff {xs : Array α} {b : β} :
+    mapIdx f xs = ys.push b ↔
+      ∃ (a : α) (zs : Array α), xs = zs.push a ∧ mapIdx f zs = ys ∧ f zs.size a = b := by
   rw [mapIdx_eq_mapFinIdx, mapFinIdx_eq_push_iff]
   simp only [mapFinIdx_eq_mapIdx, exists_and_left, exists_prop]
   constructor
-  · rintro ⟨l₁, rfl, a, rfl, rfl⟩
-    exact ⟨a, l₁, by simp⟩
-  · rintro ⟨a, l₁, rfl, rfl, rfl⟩
-    exact ⟨l₁, rfl, a, by simp⟩
+  · rintro ⟨zs, rfl, a, rfl, rfl⟩
+    exact ⟨a, zs, by simp⟩
+  · rintro ⟨a, zs, rfl, rfl, rfl⟩
+    exact ⟨zs, rfl, a, by simp⟩
 
-@[simp] theorem mapIdx_eq_singleton_iff {l : Array α} {f : Nat → α → β} {b : β} :
-    mapIdx f l = #[b] ↔ ∃ (a : α), l = #[a] ∧ f 0 a = b := by
-  rcases l with ⟨l⟩
+@[simp] theorem mapIdx_eq_singleton_iff {xs : Array α} {f : Nat → α → β} {b : β} :
+    mapIdx f xs = #[b] ↔ ∃ (a : α), xs = #[a] ∧ f 0 a = b := by
+  rcases xs with ⟨xs⟩
   simp [List.mapIdx_eq_singleton_iff]
 
-theorem mapIdx_eq_append_iff {l : Array α} {f : Nat → α → β} {l₁ l₂ : Array β} :
-    mapIdx f l = l₁ ++ l₂ ↔
-      ∃ (l₁' : Array α) (l₂' : Array α), l = l₁' ++ l₂' ∧
-        l₁'.mapIdx f = l₁ ∧
-        l₂'.mapIdx (fun i => f (i + l₁'.size)) = l₂ := by
-  rcases l with ⟨l⟩
-  rcases l₁ with ⟨l₁⟩
-  rcases l₂ with ⟨l₂⟩
+theorem mapIdx_eq_append_iff {xs : Array α} {f : Nat → α → β} {ys zs : Array β} :
+    mapIdx f xs = ys ++ zs ↔
+      ∃ (xs' : Array α) (zs' : Array α), xs = xs' ++ zs' ∧
+        xs'.mapIdx f = ys ∧
+        zs'.mapIdx (fun i => f (i + xs'.size)) = zs := by
+  rcases xs with ⟨xs⟩
+  rcases ys with ⟨ys⟩
+  rcases zs with ⟨zs⟩
   simp only [List.mapIdx_toArray, List.append_toArray, mk.injEq, List.mapIdx_eq_append_iff,
     toArray_eq_append_iff]
   constructor
@@ -393,49 +400,52 @@ theorem mapIdx_eq_append_iff {l : Array α} {f : Nat → α → β} {l₁ l₂ :
     obtain rfl := h₂
     exact ⟨l₁, l₂, by simp⟩
 
-theorem mapIdx_eq_iff {l : Array α} : mapIdx f l = l' ↔ ∀ i : Nat, l'[i]? = l[i]?.map (f i) := by
-  rcases l with ⟨l⟩
-  rcases l' with ⟨l'⟩
+theorem mapIdx_eq_iff {xs : Array α} : mapIdx f xs = ys ↔ ∀ i : Nat, ys[i]? = xs[i]?.map (f i) := by
+  rcases xs with ⟨xs⟩
+  rcases ys with ⟨ys⟩
   simp [List.mapIdx_eq_iff]
 
-theorem mapIdx_eq_mapIdx_iff {l : Array α} :
-    mapIdx f l = mapIdx g l ↔ ∀ i : Nat, (h : i < l.size) → f i l[i] = g i l[i] := by
-  rcases l with ⟨l⟩
+theorem mapIdx_eq_mapIdx_iff {xs : Array α} :
+    mapIdx f xs = mapIdx g xs ↔ ∀ i : Nat, (h : i < xs.size) → f i xs[i] = g i xs[i] := by
+  rcases xs with ⟨xs⟩
   simp [List.mapIdx_eq_mapIdx_iff]
 
-@[simp] theorem mapIdx_set {l : Array α} {i : Nat} {h : i < l.size} {a : α} :
-    (l.set i a).mapIdx f = (l.mapIdx f).set i (f i a) (by simpa) := by
-  rcases l with ⟨l⟩
+@[simp] theorem mapIdx_set {xs : Array α} {i : Nat} {h : i < xs.size} {a : α} :
+    (xs.set i a).mapIdx f = (xs.mapIdx f).set i (f i a) (by simpa) := by
+  rcases xs with ⟨xs⟩
   simp [List.mapIdx_set]
 
-@[simp] theorem mapIdx_setIfInBounds {l : Array α} {i : Nat} {a : α} :
-    (l.setIfInBounds i a).mapIdx f = (l.mapIdx f).setIfInBounds i (f i a) := by
-  rcases l with ⟨l⟩
+@[simp] theorem mapIdx_setIfInBounds {xs : Array α} {i : Nat} {a : α} :
+    (xs.setIfInBounds i a).mapIdx f = (xs.mapIdx f).setIfInBounds i (f i a) := by
+  rcases xs with ⟨xs⟩
   simp [List.mapIdx_set]
 
-@[simp] theorem back?_mapIdx {l : Array α} {f : Nat → α → β} :
-    (mapIdx f l).back? = (l.back?).map (f (l.size - 1)) := by
-  rcases l with ⟨l⟩
+@[simp] theorem back?_mapIdx {xs : Array α} {f : Nat → α → β} :
+    (mapIdx f xs).back? = (xs.back?).map (f (xs.size - 1)) := by
+  rcases xs with ⟨xs⟩
   simp [List.getLast?_mapIdx]
 
-@[simp] theorem back_mapIdx {l : Array α} {f : Nat → α → β} (h) :
-    (l.mapIdx f).back h = f (l.size - 1) (l.back (by simpa using h)) := by
-  rcases l with ⟨l⟩
+@[simp] theorem back_mapIdx {xs : Array α} {f : Nat → α → β} (h) :
+    (xs.mapIdx f).back h = f (xs.size - 1) (xs.back (by simpa using h)) := by
+  rcases xs with ⟨xs⟩
   simp [List.getLast_mapIdx]
 
-@[simp] theorem mapIdx_mapIdx {l : Array α} {f : Nat → α → β} {g : Nat → β → γ} :
-    (l.mapIdx f).mapIdx g = l.mapIdx (fun i => g i ∘ f i) := by
+@[simp] theorem mapIdx_mapIdx {xs : Array α} {f : Nat → α → β} {g : Nat → β → γ} :
+    (xs.mapIdx f).mapIdx g = xs.mapIdx (fun i => g i ∘ f i) := by
   simp [mapIdx_eq_iff]
 
-theorem mapIdx_eq_mkArray_iff {l : Array α} {f : Nat → α → β} {b : β} :
-    mapIdx f l = mkArray l.size b ↔ ∀ (i : Nat) (h : i < l.size), f i l[i] = b := by
-  rcases l with ⟨l⟩
+theorem mapIdx_eq_replicate_iff {xs : Array α} {f : Nat → α → β} {b : β} :
+    mapIdx f xs = replicate xs.size b ↔ ∀ (i : Nat) (h : i < xs.size), f i xs[i] = b := by
+  rcases xs with ⟨xs⟩
   rw [← toList_inj]
   simp [List.mapIdx_eq_replicate_iff]
 
-@[simp] theorem mapIdx_reverse {l : Array α} {f : Nat → α → β} :
-    l.reverse.mapIdx f = (mapIdx (fun i => f (l.size - 1 - i)) l).reverse := by
-  rcases l with ⟨l⟩
+@[deprecated mapIdx_eq_replicate_iff (since := "2025-03-18")]
+abbrev mapIdx_eq_mkArray_iff := @mapIdx_eq_replicate_iff
+
+@[simp] theorem mapIdx_reverse {xs : Array α} {f : Nat → α → β} :
+    xs.reverse.mapIdx f = (mapIdx (fun i => f (xs.size - 1 - i)) xs).reverse := by
+  rcases xs with ⟨xs⟩
   simp [List.mapIdx_reverse]
 
 end Array
@@ -480,15 +490,15 @@ end List
 
 namespace Array
 
-theorem toList_mapFinIdxM [Monad m] [LawfulMonad m] (l : Array α)
-    (f : (i : Nat) → α → (h : i < l.size) → m β) :
-    toList <$> l.mapFinIdxM f = l.toList.mapFinIdxM f := by
+theorem toList_mapFinIdxM [Monad m] [LawfulMonad m] (xs : Array α)
+    (f : (i : Nat) → α → (h : i < xs.size) → m β) :
+    toList <$> xs.mapFinIdxM f = xs.toList.mapFinIdxM f := by
   rw [List.mapFinIdxM_toArray]
   simp only [Functor.map_map, id_map']
 
-theorem toList_mapIdxM [Monad m] [LawfulMonad m] (l : Array α)
+theorem toList_mapIdxM [Monad m] [LawfulMonad m] (xs : Array α)
     (f : Nat → α → m β) :
-    toList <$> l.mapIdxM f = l.toList.mapIdxM f := by
+    toList <$> xs.mapIdxM f = xs.toList.mapIdxM f := by
   rw [List.mapIdxM_toArray]
   simp only [Functor.map_map, id_map']
 

src/Init/Data/Array/Mem.lean

@@ -8,6 +8,9 @@ import Init.Data.Array.Basic
 import Init.Data.Nat.Linear
 import Init.Data.List.BasicAux
 
+set_option linter.listVariables true -- Enforce naming conventions for `List`/`Array`/`Vector` variables.
+set_option linter.indexVariables true -- Enforce naming conventions for index variables.
+
 namespace Array
 
 theorem sizeOf_lt_of_mem [SizeOf α] {as : Array α} (h : a ∈ as) : sizeOf a < sizeOf as := by

src/Init/Data/Array/Monadic.lean

@@ -12,6 +12,9 @@ import Init.Data.List.Monadic
 # Lemmas about `Array.forIn'` and `Array.forIn`.
 -/
 
+set_option linter.listVariables true -- Enforce naming conventions for `List`/`Array`/`Vector` variables.
+set_option linter.indexVariables true -- Enforce naming conventions for index variables.
+
 namespace Array
 
 open Nat
@@ -20,90 +23,97 @@ open Nat
 
 /-! ### mapM -/
 
-@[simp] theorem mapM_append [Monad m] [LawfulMonad m] (f : α → m β) {l₁ l₂ : Array α} :
-    (l₁ ++ l₂).mapM f = (return (← l₁.mapM f) ++ (← l₂.mapM f)) := by
-  rcases l₁ with ⟨l₁⟩
-  rcases l₂ with ⟨l₂⟩
+@[simp] theorem mapM_pure [Monad m] [LawfulMonad m] (xs : Array α) (f : α → β) :
+    xs.mapM (m := m) (pure <| f ·) = pure (xs.map f) := by
+  induction xs; simp_all
+
+@[simp] theorem mapM_id {xs : Array α} {f : α → Id β} : xs.mapM f = xs.map f :=
+  mapM_pure _ _
+
+@[simp] theorem mapM_append [Monad m] [LawfulMonad m] (f : α → m β) {xs ys : Array α} :
+    (xs ++ ys).mapM f = (return (← xs.mapM f) ++ (← ys.mapM f)) := by
+  rcases xs with ⟨xs⟩
+  rcases ys with ⟨ys⟩
   simp
 
-theorem mapM_eq_foldlM_push [Monad m] [LawfulMonad m] (f : α → m β) (l : Array α) :
-    mapM f l = l.foldlM (fun acc a => return (acc.push (← f a))) #[] := by
-  rcases l with ⟨l⟩
+theorem mapM_eq_foldlM_push [Monad m] [LawfulMonad m] (f : α → m β) (xs : Array α) :
+    mapM f xs = xs.foldlM (fun acc a => return (acc.push (← f a))) #[] := by
+  rcases xs with ⟨xs⟩
   simp only [List.mapM_toArray, bind_pure_comp, List.size_toArray, List.foldlM_toArray']
   rw [List.mapM_eq_reverse_foldlM_cons]
   simp only [bind_pure_comp, Functor.map_map]
-  suffices ∀ (k), (fun a => a.reverse.toArray) <$> List.foldlM (fun acc a => (fun a => a :: acc) <$> f a) k l =
-      List.foldlM (fun acc a => acc.push <$> f a) k.reverse.toArray l by
+  suffices ∀ (l), (fun l' => l'.reverse.toArray) <$> List.foldlM (fun acc a => (fun a => a :: acc) <$> f a) l xs =
+      List.foldlM (fun acc a => acc.push <$> f a) l.reverse.toArray xs by
     exact this []
-  intro k
-  induction l generalizing k with
+  intro l
+  induction xs generalizing l with
   | nil => simp
   | cons a as ih =>
     simp [ih, List.foldlM_cons]
 
 /-! ### foldlM and foldrM -/
 
-theorem foldlM_map [Monad m] (f : β₁ → β₂) (g : α → β₂ → m α) (l : Array β₁) (init : α) (w : stop = l.size) :
-    (l.map f).foldlM g init 0 stop = l.foldlM (fun x y => g x (f y)) init 0 stop := by
+theorem foldlM_map [Monad m] (f : β₁ → β₂) (g : α → β₂ → m α) (xs : Array β₁) (init : α) (w : stop = xs.size) :
+    (xs.map f).foldlM g init 0 stop = xs.foldlM (fun x y => g x (f y)) init 0 stop := by
   subst w
-  cases l
+  cases xs
   simp [List.foldlM_map]
 
-theorem foldrM_map [Monad m] [LawfulMonad m] (f : β₁ → β₂) (g : β₂ → α → m α) (l : Array β₁)
-    (init : α) (w : start = l.size) :
-    (l.map f).foldrM g init start 0 = l.foldrM (fun x y => g (f x) y) init start 0 := by
+theorem foldrM_map [Monad m] [LawfulMonad m] (f : β₁ → β₂) (g : β₂ → α → m α) (xs : Array β₁)
+    (init : α) (w : start = xs.size) :
+    (xs.map f).foldrM g init start 0 = xs.foldrM (fun x y => g (f x) y) init start 0 := by
   subst w
-  cases l
+  cases xs
   simp [List.foldrM_map]
 
 theorem foldlM_filterMap [Monad m] [LawfulMonad m] (f : α → Option β) (g : γ → β → m γ)
-    (l : Array α) (init : γ) (w : stop = (l.filterMap f).size) :
-    (l.filterMap f).foldlM g init 0 stop =
-      l.foldlM (fun x y => match f y with | some b => g x b | none => pure x) init := by
+    (xs : Array α) (init : γ) (w : stop = (xs.filterMap f).size) :
+    (xs.filterMap f).foldlM g init 0 stop =
+      xs.foldlM (fun x y => match f y with | some b => g x b | none => pure x) init := by
   subst w
-  cases l
+  cases xs
   simp [List.foldlM_filterMap]
   rfl
 
 theorem foldrM_filterMap [Monad m] [LawfulMonad m] (f : α → Option β) (g : β → γ → m γ)
-    (l : Array α) (init : γ) (w : start = (l.filterMap f).size) :
-    (l.filterMap f).foldrM g init start 0 =
-      l.foldrM (fun x y => match f x with | some b => g b y | none => pure y) init := by
+    (xs : Array α) (init : γ) (w : start = (xs.filterMap f).size) :
+    (xs.filterMap f).foldrM g init start 0 =
+      xs.foldrM (fun x y => match f x with | some b => g b y | none => pure y) init := by
   subst w
-  cases l
+  cases xs
   simp [List.foldrM_filterMap]
   rfl
 
 theorem foldlM_filter [Monad m] [LawfulMonad m] (p : α → Bool) (g : β → α → m β)
-    (l : Array α) (init : β) (w : stop = (l.filter p).size) :
-    (l.filter p).foldlM g init 0 stop =
-      l.foldlM (fun x y => if p y then g x y else pure x) init := by
+    (xs : Array α) (init : β) (w : stop = (xs.filter p).size) :
+    (xs.filter p).foldlM g init 0 stop =
+      xs.foldlM (fun x y => if p y then g x y else pure x) init := by
   subst w
-  cases l
+  cases xs
   simp [List.foldlM_filter]
 
 theorem foldrM_filter [Monad m] [LawfulMonad m] (p : α → Bool) (g : α → β → m β)
-    (l : Array α) (init : β) (w : start = (l.filter p).size) :
-    (l.filter p).foldrM g init start 0 =
-      l.foldrM (fun x y => if p x then g x y else pure y) init := by
+    (xs : Array α) (init : β) (w : start = (xs.filter p).size) :
+    (xs.filter p).foldrM g init start 0 =
+      xs.foldrM (fun x y => if p x then g x y else pure y) init := by
   subst w
-  cases l
+  cases xs
   simp [List.foldrM_filter]
 
 @[simp] theorem foldlM_attachWith [Monad m]
-    (l : Array α) {q : α → Prop} (H : ∀ a, a ∈ l → q a) {f : β → { x // q x} → m β} {b} (w : stop = l.size):
-    (l.attachWith q H).foldlM f b 0 stop =
-      l.attach.foldlM (fun b ⟨a, h⟩ => f b ⟨a, H _ h⟩) b := by
+    (xs : Array α) {q : α → Prop} (H : ∀ a, a ∈ xs → q a) {f : β → { x // q x} → m β} {b} (w : stop = xs.size):
+    (xs.attachWith q H).foldlM f b 0 stop =
+      xs.attach.foldlM (fun b ⟨a, h⟩ => f b ⟨a, H _ h⟩) b := by
   subst w
-  rcases l with ⟨l⟩
+  rcases xs with ⟨xs⟩
   simp [List.foldlM_map]
 
 @[simp] theorem foldrM_attachWith [Monad m] [LawfulMonad m]
-    (l : Array α) {q : α → Prop} (H : ∀ a, a ∈ l → q a) {f : { x // q x} → β → m β} {b} (w : start = l.size):
-    (l.attachWith q H).foldrM f b start 0 =
-      l.attach.foldrM (fun a acc => f ⟨a.1, H _ a.2⟩ acc) b := by
+    (xs : Array α) {q : α → Prop} (H : ∀ a, a ∈ xs → q a) {f : { x // q x} → β → m β} {b} (w : start = xs.size):
+    (xs.attachWith q H).foldrM f b start 0 =
+      xs.attach.foldrM (fun a acc => f ⟨a.1, H _ a.2⟩ acc) b := by
   subst w
-  rcases l with ⟨l⟩
+  rcases xs with ⟨xs⟩
   simp [List.foldrM_map]
 
 /-! ### forM -/
@@ -114,15 +124,15 @@ theorem foldrM_filter [Monad m] [LawfulMonad m] (p : α → Bool) (g : α → β
   cases as <;> cases bs
   simp_all
 
-@[simp] theorem forM_append [Monad m] [LawfulMonad m] (l₁ l₂ : Array α) (f : α → m PUnit) :
-    forM (l₁ ++ l₂) f = (do forM l₁ f; forM l₂ f) := by
-  rcases l₁ with ⟨l₁⟩
-  rcases l₂ with ⟨l₂⟩
+@[simp] theorem forM_append [Monad m] [LawfulMonad m] (xs ys : Array α) (f : α → m PUnit) :
+    forM (xs ++ ys) f = (do forM xs f; forM ys f) := by
+  rcases xs with ⟨xs⟩
+  rcases ys with ⟨ys⟩
   simp
 
-@[simp] theorem forM_map [Monad m] [LawfulMonad m] (l : Array α) (g : α → β) (f : β → m PUnit) :
-    forM (l.map g) f = forM l (fun a => f (g a)) := by
-  cases l
+@[simp] theorem forM_map [Monad m] [LawfulMonad m] (xs : Array α) (g : α → β) (f : β → m PUnit) :
+    forM (xs.map g) f = forM xs (fun a => f (g a)) := by
+  rcases xs with ⟨xs⟩
   simp
 
 /-! ### forIn' -/
@@ -142,41 +152,41 @@ We can express a for loop over an array as a fold,
 in which whenever we reach `.done b` we keep that value through the rest of the fold.
 -/
 theorem forIn'_eq_foldlM [Monad m] [LawfulMonad m]
-    (l : Array α) (f : (a : α) → a ∈ l → β → m (ForInStep β)) (init : β) :
-    forIn' l init f = ForInStep.value <$>
-      l.attach.foldlM (fun b ⟨a, m⟩ => match b with
+    (xs : Array α) (f : (a : α) → a ∈ xs → β → m (ForInStep β)) (init : β) :
+    forIn' xs init f = ForInStep.value <$>
+      xs.attach.foldlM (fun b ⟨a, m⟩ => match b with
         | .yield b => f a m b
         | .done b => pure (.done b)) (ForInStep.yield init) := by
-  cases l
+  rcases xs with ⟨xs⟩
   simp [List.forIn'_eq_foldlM, List.foldlM_map]
   congr
 
 /-- We can express a for loop over an array which always yields as a fold. -/
 @[simp] theorem forIn'_yield_eq_foldlM [Monad m] [LawfulMonad m]
-    (l : Array α) (f : (a : α) → a ∈ l → β → m γ) (g : (a : α) → a ∈ l → β → γ → β) (init : β) :
-    forIn' l init (fun a m b => (fun c => .yield (g a m b c)) <$> f a m b) =
-      l.attach.foldlM (fun b ⟨a, m⟩ => g a m b <$> f a m b) init := by
-  cases l
+    (xs : Array α) (f : (a : α) → a ∈ xs → β → m γ) (g : (a : α) → a ∈ xs → β → γ → β) (init : β) :
+    forIn' xs init (fun a m b => (fun c => .yield (g a m b c)) <$> f a m b) =
+      xs.attach.foldlM (fun b ⟨a, m⟩ => g a m b <$> f a m b) init := by
+  rcases xs with ⟨xs⟩
   simp [List.foldlM_map]
 
-theorem forIn'_pure_yield_eq_foldl [Monad m] [LawfulMonad m]
-    (l : Array α) (f : (a : α) → a ∈ l → β → β) (init : β) :
-    forIn' l init (fun a m b => pure (.yield (f a m b))) =
-      pure (f := m) (l.attach.foldl (fun b ⟨a, h⟩ => f a h b) init) := by
-  cases l
+@[simp] theorem forIn'_pure_yield_eq_foldl [Monad m] [LawfulMonad m]
+    (xs : Array α) (f : (a : α) → a ∈ xs → β → β) (init : β) :
+    forIn' xs init (fun a m b => pure (.yield (f a m b))) =
+      pure (f := m) (xs.attach.foldl (fun b ⟨a, h⟩ => f a h b) init) := by
+  rcases xs with ⟨xs⟩
   simp [List.forIn'_pure_yield_eq_foldl, List.foldl_map]
 
 @[simp] theorem forIn'_yield_eq_foldl
-    (l : Array α) (f : (a : α) → a ∈ l → β → β) (init : β) :
-    forIn' (m := Id) l init (fun a m b => .yield (f a m b)) =
-      l.attach.foldl (fun b ⟨a, h⟩ => f a h b) init := by
-  cases l
+    (xs : Array α) (f : (a : α) → a ∈ xs → β → β) (init : β) :
+    forIn' (m := Id) xs init (fun a m b => .yield (f a m b)) =
+      xs.attach.foldl (fun b ⟨a, h⟩ => f a h b) init := by
+  rcases xs with ⟨xs⟩
   simp [List.foldl_map]
 
 @[simp] theorem forIn'_map [Monad m] [LawfulMonad m]
-    (l : Array α) (g : α → β) (f : (b : β) → b ∈ l.map g → γ → m (ForInStep γ)) :
-    forIn' (l.map g) init f = forIn' l init fun a h y => f (g a) (mem_map_of_mem g h) y := by
-  cases l
+    (xs : Array α) (g : α → β) (f : (b : β) → b ∈ xs.map g → γ → m (ForInStep γ)) :
+    forIn' (xs.map g) init f = forIn' xs init fun a h y => f (g a) (mem_map_of_mem g h) y := by
+  rcases xs with ⟨xs⟩
   simp
 
 /--
@@ -184,41 +194,67 @@ We can express a for loop over an array as a fold,
 in which whenever we reach `.done b` we keep that value through the rest of the fold.
 -/
 theorem forIn_eq_foldlM [Monad m] [LawfulMonad m]
-    (f : α → β → m (ForInStep β)) (init : β) (l : Array α) :
-    forIn l init f = ForInStep.value <$>
-      l.foldlM (fun b a => match b with
+    (f : α → β → m (ForInStep β)) (init : β) (xs : Array α) :
+    forIn xs init f = ForInStep.value <$>
+      xs.foldlM (fun b a => match b with
         | .yield b => f a b
         | .done b => pure (.done b)) (ForInStep.yield init) := by
-  cases l
+  rcases xs with ⟨xs⟩
   simp only [List.forIn_toArray, List.forIn_eq_foldlM, List.size_toArray, List.foldlM_toArray']
   congr
 
 /-- We can express a for loop over an array which always yields as a fold. -/
 @[simp] theorem forIn_yield_eq_foldlM [Monad m] [LawfulMonad m]
-    (l : Array α) (f : α → β → m γ) (g : α → β → γ → β) (init : β) :
-    forIn l init (fun a b => (fun c => .yield (g a b c)) <$> f a b) =
-      l.foldlM (fun b a => g a b <$> f a b) init := by
-  cases l
+    (xs : Array α) (f : α → β → m γ) (g : α → β → γ → β) (init : β) :
+    forIn xs init (fun a b => (fun c => .yield (g a b c)) <$> f a b) =
+      xs.foldlM (fun b a => g a b <$> f a b) init := by
+  rcases xs with ⟨xs⟩
   simp [List.foldlM_map]
 
-theorem forIn_pure_yield_eq_foldl [Monad m] [LawfulMonad m]
-    (l : Array α) (f : α → β → β) (init : β) :
-    forIn l init (fun a b => pure (.yield (f a b))) =
-      pure (f := m) (l.foldl (fun b a => f a b) init) := by
-  cases l
+@[simp] theorem forIn_pure_yield_eq_foldl [Monad m] [LawfulMonad m]
+    (xs : Array α) (f : α → β → β) (init : β) :
+    forIn xs init (fun a b => pure (.yield (f a b))) =
+      pure (f := m) (xs.foldl (fun b a => f a b) init) := by
+  rcases xs with ⟨xs⟩
   simp [List.forIn_pure_yield_eq_foldl, List.foldl_map]
 
 @[simp] theorem forIn_yield_eq_foldl
-    (l : Array α) (f : α → β → β) (init : β) :
-    forIn (m := Id) l init (fun a b => .yield (f a b)) =
-      l.foldl (fun b a => f a b) init := by
-  cases l
+    (xs : Array α) (f : α → β → β) (init : β) :
+    forIn (m := Id) xs init (fun a b => .yield (f a b)) =
+      xs.foldl (fun b a => f a b) init := by
+  rcases xs with ⟨xs⟩
   simp [List.foldl_map]
 
 @[simp] theorem forIn_map [Monad m] [LawfulMonad m]
-    (l : Array α) (g : α → β) (f : β → γ → m (ForInStep γ)) :
-    forIn (l.map g) init f = forIn l init fun a y => f (g a) y := by
-  cases l
+    (xs : Array α) (g : α → β) (f : β → γ → m (ForInStep γ)) :
+    forIn (xs.map g) init f = forIn xs init fun a y => f (g a) y := by
+  rcases xs with ⟨xs⟩
+  simp
+
+/-! ### allM and anyM -/
+
+@[simp] theorem anyM_pure [Monad m] [LawfulMonad m] (p : α → Bool) (xs : Array α) :
+    xs.anyM (m := m) (pure <| p ·) = pure (xs.any p) := by
+  cases xs
+  simp
+
+@[simp] theorem allM_pure [Monad m] [LawfulMonad m] (p : α → Bool) (xs : Array α) :
+    xs.allM (m := m) (pure <| p ·) = pure (xs.all p) := by
+  cases xs
+  simp
+
+/-! ### findM? and findSomeM? -/
+
+@[simp]
+theorem findM?_pure {m} [Monad m] [LawfulMonad m] (p : α → Bool) (xs : Array α) :
+    findM? (m := m) (pure <| p ·) xs = pure (xs.find? p) := by
+  cases xs
+  simp
+
+@[simp]
+theorem findSomeM?_pure [Monad m] [LawfulMonad m] (f : α → Option β) (xs : Array α) :
+    findSomeM? (m := m) (pure <| f ·) xs = pure (xs.findSome? f) := by
+  cases xs
   simp
 
 end Array
@@ -284,7 +320,7 @@ theorem filterMapM_toArray [Monad m] [LawfulMonad m] (l : List α) (f : α → m
   | nil => simp only [foldlM_nil, flatMapM.loop, map_pure]
   | cons x xs ih =>
     simp only [foldlM_cons, bind_map_left, flatMapM.loop, _root_.map_bind]
-    congr; funext a
+    congr; funext xs
     conv => lhs; rw [Array.toArray_append, ← flatten_concat, ← reverse_cons]
     exact ih _
 
@@ -316,23 +352,23 @@ namespace Array
   subst w
   simp [flatMapM, h]
 
-theorem toList_filterM [Monad m] [LawfulMonad m] (a : Array α) (p : α → m Bool) :
-    toList <$> a.filterM p = a.toList.filterM p := by
+theorem toList_filterM [Monad m] [LawfulMonad m] (xs : Array α) (p : α → m Bool) :
+    toList <$> xs.filterM p = xs.toList.filterM p := by
   rw [List.filterM_toArray]
   simp only [Functor.map_map, id_map']
 
-theorem toList_filterRevM [Monad m] [LawfulMonad m] (a : Array α) (p : α → m Bool) :
-    toList <$> a.filterRevM p = a.toList.filterRevM p := by
+theorem toList_filterRevM [Monad m] [LawfulMonad m] (xs : Array α) (p : α → m Bool) :
+    toList <$> xs.filterRevM p = xs.toList.filterRevM p := by
   rw [List.filterRevM_toArray]
   simp only [Functor.map_map, id_map']
 
-theorem toList_filterMapM [Monad m] [LawfulMonad m] (a : Array α) (f : α → m (Option β)) :
-    toList <$> a.filterMapM f = a.toList.filterMapM f := by
+theorem toList_filterMapM [Monad m] [LawfulMonad m] (xs : Array α) (f : α → m (Option β)) :
+    toList <$> xs.filterMapM f = xs.toList.filterMapM f := by
   rw [List.filterMapM_toArray]
   simp only [Functor.map_map, id_map']
 
-theorem toList_flatMapM [Monad m] [LawfulMonad m] (a : Array α) (f : α → m (Array β)) :
-    toList <$> a.flatMapM f = a.toList.flatMapM (fun a => toList <$> f a) := by
+theorem toList_flatMapM [Monad m] [LawfulMonad m] (xs : Array α) (f : α → m (Array β)) :
+    toList <$> xs.flatMapM f = xs.toList.flatMapM (fun a => toList <$> f a) := by
   rw [List.flatMapM_toArray]
   simp only [Functor.map_map, id_map']
 
@@ -342,21 +378,21 @@ theorem toList_flatMapM [Monad m] [LawfulMonad m] (a : Array α) (f : α → m (
 This lemma identifies monadic folds over lists of subtypes, where the function only depends on the value, not the proposition,
 and simplifies these to the function directly taking the value.
 -/
-@[simp] theorem foldlM_subtype [Monad m] {p : α → Prop} {l : Array { x // p x }}
+@[simp] theorem foldlM_subtype [Monad m] {p : α → Prop} {xs : Array { x // p x }}
     {f : β → { x // p x } → m β} {g : β → α → m β} {x : β}
-    (hf : ∀ b x h, f b ⟨x, h⟩ = g b x) (w : stop = l.size) :
-    l.foldlM f x 0 stop = l.unattach.foldlM g x 0 stop := by
+    (hf : ∀ b x h, f b ⟨x, h⟩ = g b x) (w : stop = xs.size) :
+    xs.foldlM f x 0 stop = xs.unattach.foldlM g x 0 stop := by
   subst w
-  rcases l with ⟨l⟩
+  rcases xs with ⟨l⟩
   simp
   rw [List.foldlM_subtype hf]
 
-@[wf_preprocess] theorem foldlM_wfParam [Monad m] (xs : Array α) (f : β → α → m β) :
-    (wfParam xs).foldlM f = xs.attach.unattach.foldlM f := by
+@[wf_preprocess] theorem foldlM_wfParam [Monad m] (xs : Array α) (f : β → α → m β) (init : β) :
+    (wfParam xs).foldlM f init = xs.attach.unattach.foldlM f init := by
   simp [wfParam]
 
-@[wf_preprocess] theorem foldlM_unattach [Monad m] (P : α → Prop) (xs : Array (Subtype P)) (f : β → α → m β) :
-    xs.unattach.foldlM f = xs.foldlM fun b ⟨x, h⟩ =>
+@[wf_preprocess] theorem foldlM_unattach [Monad m] (P : α → Prop) (xs : Array (Subtype P)) (f : β → α → m β) (init : β) :
+    xs.unattach.foldlM f init = xs.foldlM (init := init) fun b ⟨x, h⟩ =>
       binderNameHint b f <| binderNameHint x (f b) <| binderNameHint h () <|
       f b (wfParam x) := by
   simp [wfParam]
@@ -365,22 +401,22 @@ and simplifies these to the function directly taking the value.
 This lemma identifies monadic folds over lists of subtypes, where the function only depends on the value, not the proposition,
 and simplifies these to the function directly taking the value.
 -/
-@[simp] theorem foldrM_subtype [Monad m] [LawfulMonad m] {p : α → Prop} {l : Array { x // p x }}
+@[simp] theorem foldrM_subtype [Monad m] [LawfulMonad m] {p : α → Prop} {xs : Array { x // p x }}
     {f : { x // p x } → β → m β} {g : α → β → m β} {x : β}
-    (hf : ∀ x h b, f ⟨x, h⟩ b = g x b) (w : start = l.size) :
-    l.foldrM f x start 0 = l.unattach.foldrM g x start 0:= by
+    (hf : ∀ x h b, f ⟨x, h⟩ b = g x b) (w : start = xs.size) :
+    xs.foldrM f x start 0 = xs.unattach.foldrM g x start 0:= by
   subst w
-  rcases l with ⟨l⟩
+  rcases xs with ⟨xs⟩
   simp
   rw [List.foldrM_subtype hf]
 
 
-@[wf_preprocess] theorem foldrM_wfParam [Monad m] [LawfulMonad m] (xs : Array α) (f : α → β → m β) :
-    (wfParam xs).foldrM f = xs.attach.unattach.foldrM f := by
+@[wf_preprocess] theorem foldrM_wfParam [Monad m] [LawfulMonad m] (xs : Array α) (f : α → β → m β) (init : β) :
+    (wfParam xs).foldrM f init = xs.attach.unattach.foldrM f init := by
   simp [wfParam]
 
-@[wf_preprocess] theorem foldrM_unattach [Monad m] [LawfulMonad m] (P : α → Prop) (xs : Array (Subtype P)) (f : α → β → m β) :
-    xs.unattach.foldrM f = xs.foldrM fun ⟨x, h⟩ b =>
+@[wf_preprocess] theorem foldrM_unattach [Monad m] [LawfulMonad m] (P : α → Prop) (xs : Array (Subtype P)) (f : α → β → m β) (init : β):
+    xs.unattach.foldrM f init = xs.foldrM (init := init) fun ⟨x, h⟩ b =>
       binderNameHint x f <| binderNameHint h () <| binderNameHint b (f x) <|
       f (wfParam x) b := by
   simp [wfParam]
@@ -389,10 +425,10 @@ and simplifies these to the function directly taking the value.
 This lemma identifies monadic maps over lists of subtypes, where the function only depends on the value, not the proposition,
 and simplifies these to the function directly taking the value.
 -/
-@[simp] theorem mapM_subtype [Monad m] [LawfulMonad m] {p : α → Prop} {l : Array { x // p x }}
+@[simp] theorem mapM_subtype [Monad m] [LawfulMonad m] {p : α → Prop} {xs : Array { x // p x }}
     {f : { x // p x } → m β} {g : α → m β} (hf : ∀ x h, f ⟨x, h⟩ = g x) :
-    l.mapM f = l.unattach.mapM g := by
-  rcases l with ⟨l⟩
+    xs.mapM f = xs.unattach.mapM g := by
+  rcases xs with ⟨xs⟩
   simp
   rw [List.mapM_subtype hf]
 
@@ -405,11 +441,11 @@ and simplifies these to the function directly taking the value.
       binderNameHint x f <| binderNameHint h () <| f (wfParam x) := by
   simp [wfParam]
 
-@[simp] theorem filterMapM_subtype [Monad m] [LawfulMonad m] {p : α → Prop} {l : Array { x // p x }}
-    {f : { x // p x } → m (Option β)} {g : α → m (Option β)} (hf : ∀ x h, f ⟨x, h⟩ = g x) (w : stop = l.size) :
-    l.filterMapM f 0 stop = l.unattach.filterMapM g := by
+@[simp] theorem filterMapM_subtype [Monad m] [LawfulMonad m] {p : α → Prop} {xs : Array { x // p x }}
+    {f : { x // p x } → m (Option β)} {g : α → m (Option β)} (hf : ∀ x h, f ⟨x, h⟩ = g x) (w : stop = xs.size) :
+    xs.filterMapM f 0 stop = xs.unattach.filterMapM g := by
   subst w
-  rcases l with ⟨l⟩
+  rcases xs with ⟨xs⟩
   simp
   rw [List.filterMapM_subtype hf]
 
@@ -425,15 +461,14 @@ and simplifies these to the function directly taking the value.
       binderNameHint x f <| binderNameHint h () <| f (wfParam x) := by
   simp [wfParam]
 
-@[simp] theorem flatMapM_subtype [Monad m] [LawfulMonad m] {p : α → Prop} {l : Array { x // p x }}
+@[simp] theorem flatMapM_subtype [Monad m] [LawfulMonad m] {p : α → Prop} {xs : Array { x // p x }}
     {f : { x // p x } → m (Array β)} {g : α → m (Array β)} (hf : ∀ x h, f ⟨x, h⟩ = g x) :
-    (l.flatMapM f) = l.unattach.flatMapM g := by
-  rcases l with ⟨l⟩
+    (xs.flatMapM f) = xs.unattach.flatMapM g := by
+  rcases xs with ⟨xs⟩
   simp
   rw [List.flatMapM_subtype]
   simp [hf]
 
-
 @[wf_preprocess] theorem flatMapM_wfParam [Monad m] [LawfulMonad m]
     (xs : Array α) (f : α → m (Array β)) :
     (wfParam xs).flatMapM f = xs.attach.unattach.flatMapM f := by

src/Init/Data/Array/OfFn.lean

@@ -11,8 +11,31 @@ import Init.Data.List.OfFn
 # Theorems about `Array.ofFn`
 -/
 
+set_option linter.listVariables true -- Enforce naming conventions for `List`/`Array`/`Vector` variables.
+set_option linter.indexVariables true -- Enforce naming conventions for index variables.
+
 namespace Array
 
+@[simp] theorem ofFn_zero (f : Fin 0 → α) : ofFn f = #[] := by
+  simp [ofFn, ofFn.go]
+
+theorem ofFn_succ (f : Fin (n+1) → α) :
+    ofFn f = (ofFn (fun (i : Fin n) => f i.castSucc)).push (f ⟨n, by omega⟩) := by
+  ext i h₁ h₂
+  · simp
+  · simp [getElem_push]
+    split <;> rename_i h₃
+    · rfl
+    · congr
+      simp at h₁ h₂
+      omega
+
+@[simp] theorem _rooy_.List.toArray_ofFn (f : Fin n → α) : (List.ofFn f).toArray = Array.ofFn f := by
+  ext <;> simp
+
+@[simp] theorem toList_ofFn (f : Fin n → α) : (Array.ofFn f).toList = List.ofFn f := by
+  apply List.ext_getElem <;> simp
+
 @[simp]
 theorem ofFn_eq_empty_iff {f : Fin n → α} : ofFn f = #[] ↔ n = 0 := by
   rw [← Array.toList_inj]

src/Init/Data/Array/Perm.lean

@@ -7,6 +7,9 @@ prelude
 import Init.Data.List.Nat.Perm
 import Init.Data.Array.Lemmas
 
+set_option linter.listVariables true -- Enforce naming conventions for `List`/`Array`/`Vector` variables.
+set_option linter.indexVariables true -- Enforce naming conventions for index variables.
+
 namespace Array
 
 open List
@@ -27,38 +30,38 @@ theorem perm_iff_toList_perm {as bs : Array α} : as ~ bs ↔ as.toList ~ bs.toL
 @[simp] theorem perm_toArray (as bs : List α) : as.toArray ~ bs.toArray ↔ as ~ bs := by
   simp [perm_iff_toList_perm]
 
-@[simp, refl] protected theorem Perm.refl (l : Array α) : l ~ l := by
-  cases l
+@[simp, refl] protected theorem Perm.refl (xs : Array α) : xs ~ xs := by
+  cases xs
   simp
 
-protected theorem Perm.rfl {l : List α} : l ~ l := .refl _
+protected theorem Perm.rfl {xs : List α} : xs ~ xs := .refl _
 
-theorem Perm.of_eq {l₁ l₂ : Array α} (h : l₁ = l₂) : l₁ ~ l₂ := h ▸ .rfl
+theorem Perm.of_eq {xs ys : Array α} (h : xs = ys) : xs ~ ys := h ▸ .rfl
 
-protected theorem Perm.symm {l₁ l₂ : Array α} (h : l₁ ~ l₂) : l₂ ~ l₁ := by
-  cases l₁; cases l₂
+protected theorem Perm.symm {xs ys : Array α} (h : xs ~ ys) : ys ~ xs := by
+  cases xs; cases ys
   simp only [perm_toArray] at h
   simpa using h.symm
 
-protected theorem Perm.trans {l₁ l₂ l₃ : Array α} (h₁ : l₁ ~ l₂) (h₂ : l₂ ~ l₃) : l₁ ~ l₃ := by
-  cases l₁; cases l₂; cases l₃
+protected theorem Perm.trans {xs ys zs : Array α} (h₁ : xs ~ ys) (h₂ : ys ~ zs) : xs ~ zs := by
+  cases xs; cases ys; cases zs
   simp only [perm_toArray] at h₁ h₂
   simpa using h₁.trans h₂
 
 instance : Trans (Perm (α := α)) (Perm (α := α)) (Perm (α := α)) where
   trans h₁ h₂ := Perm.trans h₁ h₂
 
-theorem perm_comm {l₁ l₂ : Array α} : l₁ ~ l₂ ↔ l₂ ~ l₁ := ⟨Perm.symm, Perm.symm⟩
+theorem perm_comm {xs ys : Array α} : xs ~ ys ↔ ys ~ xs := ⟨Perm.symm, Perm.symm⟩
 
-theorem Perm.push (x y : α) {l₁ l₂ : Array α} (p : l₁ ~ l₂) :
-    (l₁.push x).push y ~ (l₂.push y).push x := by
-  cases l₁; cases l₂
+theorem Perm.push (x y : α) {xs ys : Array α} (p : xs ~ ys) :
+    (xs.push x).push y ~ (ys.push y).push x := by
+  cases xs; cases ys
   simp only [perm_toArray] at p
   simp only [push_toArray, List.append_assoc, singleton_append, perm_toArray]
   exact p.append (Perm.swap' _ _ Perm.nil)
 
-theorem swap_perm {as : Array α} {i j : Nat} (h₁ : i < as.size) (h₂ : j < as.size) :
-    as.swap i j ~ as := by
+theorem swap_perm {xs : Array α} {i j : Nat} (h₁ : i < xs.size) (h₂ : j < xs.size) :
+    xs.swap i j ~ xs := by
   simp only [swap, perm_iff_toList_perm, toList_set]
   apply set_set_perm
 

src/Init/Data/Array/QSort.lean

@@ -7,6 +7,9 @@ prelude
 import Init.Data.Vector.Basic
 import Init.Data.Ord
 
+set_option linter.listVariables true -- Enforce naming conventions for `List`/`Array`/`Vector` variables.
+-- We do not enable `linter.indexVariables` because it is helpful to name index variables `lo`, `mid`, `hi`, etc.
+
 namespace Array
 
 private def qpartition {n} (as : Vector α n) (lt : α → α → Bool) (lo hi : Nat)
@@ -27,6 +30,16 @@ private def qpartition {n} (as : Vector α n) (lt : α → α → Bool) (lo hi :
       (⟨i, ilo⟩, as.swap i hi)
   loop as lo lo
 
+/--
+Sorts an array using the Quicksort algorithm.
+
+The optional parameter `lt` specifies an ordering predicate. It defaults to `LT.lt`, which must be
+decidable to be used for sorting. Use `Array.qsortOrd` to sort the array according to the `Ord α`
+instance.
+
+The optional parameters `low` and `high` delimit the region of the array that is sorted. Both are
+inclusive, and default to sorting the entire array.
+-/
 @[inline] def qsort (as : Array α) (lt : α → α → Bool := by exact (· < ·))
     (low := 0) (high := as.size - 1) : Array α :=
   let rec @[specialize] sort {n} (as : Vector α n) (lo hi : Nat)
@@ -47,7 +60,7 @@ private def qpartition {n} (as : Vector α n) (lt : α → α → Bool) (lo hi :
 
 set_option linter.unusedVariables.funArgs false in
 /--
-Sort an array using `compare` to compare elements.
+Sorts an array using the Quicksort algorithm, using `Ord.compare` to compare elements.
 -/
 def qsortOrd [ord : Ord α] (xs : Array α) : Array α :=
   xs.qsort fun x y => compare x y |>.isLT

src/Init/Data/Array/Range.lean

@@ -15,6 +15,9 @@ import Init.Data.List.Nat.Range
 
 -/
 
+set_option linter.listVariables true -- Enforce naming conventions for `List`/`Array`/`Vector` variables.
+set_option linter.indexVariables true -- Enforce naming conventions for index variables.
+
 namespace Array
 
 open Nat
@@ -28,7 +31,7 @@ theorem range'_succ (s n step) : range' s (n + 1) step = #[s] ++ range' (s + ste
   simp [List.range'_succ]
 
 @[simp] theorem range'_eq_empty_iff : range' s n step = #[] ↔ n = 0 := by
-  rw [← size_eq_zero, size_range']
+  rw [← size_eq_zero_iff, size_range']
 
 theorem range'_ne_empty_iff (s : Nat) {n step : Nat} : range' s n step ≠ #[] ↔ n ≠ 0 := by
   cases n <;> simp
@@ -36,7 +39,8 @@ theorem range'_ne_empty_iff (s : Nat) {n step : Nat} : range' s n step ≠ #[]
 @[simp] theorem range'_zero : range' s 0 step = #[] := by
   simp
 
-@[simp] theorem range'_one {s step : Nat} : range' s 1 step = #[s] := rfl
+@[simp] theorem range'_one {s step : Nat} : range' s 1 step = #[s] := by
+  simp [range', ofFn, ofFn.go]
 
 @[simp] theorem range'_inj : range' s n = range' s' n' ↔ n = n' ∧ (n = 0 ∨ s = s') := by
   rw [← toList_inj]
@@ -74,7 +78,7 @@ theorem range'_append (s m n step : Nat) :
     range' s m ++ range' (s + m) n = range' s (m + n) := by simpa using range'_append s m n 1
 
 theorem range'_concat (s n : Nat) : range' s (n + 1) step = range' s n step ++ #[s + step * n] := by
-  exact (range'_append s n 1 step).symm
+  simpa using (range'_append s n 1 step).symm
 
 theorem range'_1_concat (s n : Nat) : range' s (n + 1) = range' s n ++ #[s + n] := by
   simp [range'_concat]
@@ -133,7 +137,7 @@ theorem range'_eq_map_range (s n : Nat) : range' s n = map (s + ·) (range n) :=
   rw [range_eq_range', map_add_range']; rfl
 
 @[simp] theorem range_eq_empty_iff {n : Nat} : range n = #[] ↔ n = 0 := by
-  rw [← size_eq_zero, size_range]
+  rw [← size_eq_zero_iff, size_range]
 
 theorem range_ne_empty_iff {n : Nat} : range n ≠ #[] ↔ n ≠ 0 := by
   cases n <;> simp
@@ -146,9 +150,9 @@ theorem range_succ (n : Nat) : range (succ n) = range n ++ #[n] := by
       dite_eq_ite]
     split <;> omega
 
-theorem range_add (a b : Nat) : range (a + b) = range a ++ (range b).map (a + ·) := by
+theorem range_add (n m : Nat) : range (n + m) = range n ++ (range m).map (n + ·) := by
   rw [← range'_eq_map_range]
-  simpa [range_eq_range', Nat.add_comm] using (range'_append_1 0 a b).symm
+  simpa [range_eq_range', Nat.add_comm] using (range'_append_1 0 n m).symm
 
 theorem reverse_range' (s n : Nat) : reverse (range' s n) = map (s + n - 1 - ·) (range n) := by
   simp [← toList_inj, List.reverse_range']
@@ -161,7 +165,7 @@ theorem not_mem_range_self {n : Nat} : n ∉ range n := by simp
 
 theorem self_mem_range_succ (n : Nat) : n ∈ range (n + 1) := by simp
 
-@[simp] theorem take_range (m n : Nat) : take (range n) m = range (min m n) := by
+@[simp] theorem take_range (i n : Nat) : take (range n) i = range (min i n) := by
   ext <;> simp
 
 @[simp] theorem find?_range_eq_some {n : Nat} {i : Nat} {p : Nat → Bool} :
@@ -179,48 +183,48 @@ theorem erase_range : (range n).erase i = range (min n i) ++ range' (i + 1) (n -
 /-! ### zipIdx -/
 
 @[simp]
-theorem zipIdx_eq_empty_iff {l : Array α} {n : Nat} : l.zipIdx n = #[] ↔ l = #[] := by
-  cases l
+theorem zipIdx_eq_empty_iff {xs : Array α} {i : Nat} : xs.zipIdx i = #[] ↔ xs = #[] := by
+  cases xs
   simp
 
 @[simp]
-theorem getElem?_zipIdx (l : Array α) (n m) : (zipIdx l n)[m]? = l[m]?.map fun a => (a, n + m) := by
+theorem getElem?_zipIdx (xs : Array α) (i j) : (zipIdx xs i)[j]? = xs[j]?.map fun a => (a, i + j) := by
   simp [getElem?_def]
 
-theorem map_snd_add_zipIdx_eq_zipIdx (l : Array α) (n k : Nat) :
-    map (Prod.map id (· + n)) (zipIdx l k) = zipIdx l (n + k) :=
+theorem map_snd_add_zipIdx_eq_zipIdx (xs : Array α) (n k : Nat) :
+    map (Prod.map id (· + n)) (zipIdx xs k) = zipIdx xs (n + k) :=
   ext_getElem? fun i ↦ by simp [(· ∘ ·), Nat.add_comm, Nat.add_left_comm]; rfl
 
 @[simp]
-theorem zipIdx_map_snd (n) (l : Array α) : map Prod.snd (zipIdx l n) = range' n l.size := by
-  cases l
+theorem zipIdx_map_snd (i) (xs : Array α) : map Prod.snd (zipIdx xs i) = range' i xs.size := by
+  cases xs
   simp
 
 @[simp]
-theorem zipIdx_map_fst (n) (l : Array α) : map Prod.fst (zipIdx l n) = l := by
-  cases l
+theorem zipIdx_map_fst (i) (xs : Array α) : map Prod.fst (zipIdx xs i) = xs := by
+  cases xs
   simp
 
-theorem zipIdx_eq_zip_range' (l : Array α) {n : Nat} : l.zipIdx n = l.zip (range' n l.size) := by
+theorem zipIdx_eq_zip_range' (xs : Array α) {i : Nat} : xs.zipIdx i = xs.zip (range' i xs.size) := by
   simp [zip_of_prod (zipIdx_map_fst _ _) (zipIdx_map_snd _ _)]
 
 @[simp]
-theorem unzip_zipIdx_eq_prod (l : Array α) {n : Nat} :
-    (l.zipIdx n).unzip = (l, range' n l.size) := by
+theorem unzip_zipIdx_eq_prod (xs : Array α) {i : Nat} :
+    (xs.zipIdx i).unzip = (xs, range' i xs.size) := by
   simp only [zipIdx_eq_zip_range', unzip_zip, size_range']
 
 /-- Replace `zipIdx` with a starting index `n+1` with `zipIdx` starting from `n`,
 followed by a `map` increasing the indices by one. -/
-theorem zipIdx_succ (l : Array α) (n : Nat) :
-    l.zipIdx (n + 1) = (l.zipIdx n).map (fun ⟨a, i⟩ => (a, i + 1)) := by
-  cases l
+theorem zipIdx_succ (xs : Array α) (i : Nat) :
+    xs.zipIdx (i + 1) = (xs.zipIdx i).map (fun ⟨a, j⟩ => (a, j + 1)) := by
+  cases xs
   simp [List.zipIdx_succ]
 
 /-- Replace `zipIdx` with a starting index with `zipIdx` starting from 0,
 followed by a `map` increasing the indices. -/
-theorem zipIdx_eq_map_add (l : Array α) (n : Nat) :
-    l.zipIdx n = l.zipIdx.map (fun ⟨a, i⟩ => (a, n + i)) := by
-  cases l
+theorem zipIdx_eq_map_add (xs : Array α) (i : Nat) :
+    xs.zipIdx i = (xs.zipIdx 0).map (fun ⟨a, j⟩ => (a, i + j)) := by
+  cases xs
   simp only [zipIdx_toArray, List.map_toArray, mk.injEq]
   rw [List.zipIdx_eq_map_add]
 
@@ -228,33 +232,33 @@ theorem zipIdx_eq_map_add (l : Array α) (n : Nat) :
 theorem zipIdx_singleton (x : α) (k : Nat) : zipIdx #[x] k = #[(x, k)] :=
   rfl
 
-theorem mk_add_mem_zipIdx_iff_getElem? {k i : Nat} {x : α} {l : Array α} :
-    (x, k + i) ∈ zipIdx l k ↔ l[i]? = some x := by
+theorem mk_add_mem_zipIdx_iff_getElem? {k i : Nat} {x : α} {xs : Array α} :
+    (x, k + i) ∈ zipIdx xs k ↔ xs[i]? = some x := by
   simp [mem_iff_getElem?, and_left_comm]
 
-theorem le_snd_of_mem_zipIdx {x : α × Nat} {k : Nat} {l : Array α} (h : x ∈ zipIdx l k) :
+theorem le_snd_of_mem_zipIdx {x : α × Nat} {k : Nat} {xs : Array α} (h : x ∈ zipIdx xs k) :
     k ≤ x.2 :=
   (mk_mem_zipIdx_iff_le_and_getElem?_sub.1 h).1
 
-theorem snd_lt_add_of_mem_zipIdx {x : α × Nat} {l : Array α} {k : Nat} (h : x ∈ zipIdx l k) :
-    x.2 < k + l.size := by
+theorem snd_lt_add_of_mem_zipIdx {x : α × Nat} {k : Nat} {xs : Array α} (h : x ∈ zipIdx xs k) :
+    x.2 < k + xs.size := by
   rcases mem_iff_getElem.1 h with ⟨i, h', rfl⟩
   simpa using h'
 
-theorem snd_lt_of_mem_zipIdx {x : α × Nat} {l : Array α} {k : Nat} (h : x ∈ l.zipIdx k) : x.2 < l.size + k := by
+theorem snd_lt_of_mem_zipIdx {x : α × Nat} {k : Nat} {xs : Array α} (h : x ∈ zipIdx xs k) : x.2 < xs.size + k := by
   simpa [Nat.add_comm] using snd_lt_add_of_mem_zipIdx h
 
-theorem map_zipIdx (f : α → β) (l : Array α) (k : Nat) :
-    map (Prod.map f id) (zipIdx l k) = zipIdx (l.map f) k := by
-  cases l
+theorem map_zipIdx (f : α → β) (xs : Array α) (k : Nat) :
+    map (Prod.map f id) (zipIdx xs k) = zipIdx (xs.map f) k := by
+  cases xs
   simp [List.map_zipIdx]
 
-theorem fst_mem_of_mem_zipIdx {x : α × Nat} {l : Array α} {k : Nat} (h : x ∈ zipIdx l k) : x.1 ∈ l :=
-  zipIdx_map_fst k l ▸ mem_map_of_mem _ h
+theorem fst_mem_of_mem_zipIdx {x : α × Nat} {xs : Array α} {k : Nat} (h : x ∈ zipIdx xs k) : x.1 ∈ xs :=
+  zipIdx_map_fst k xs ▸ mem_map_of_mem _ h
 
-theorem fst_eq_of_mem_zipIdx {x : α × Nat} {l : Array α} {k : Nat} (h : x ∈ zipIdx l k) :
-    x.1 = l[x.2 - k]'(by have := le_snd_of_mem_zipIdx h; have := snd_lt_add_of_mem_zipIdx h; omega) := by
-  cases l
+theorem fst_eq_of_mem_zipIdx {x : α × Nat} {xs : Array α} {k : Nat} (h : x ∈ zipIdx xs k) :
+    x.1 = xs[x.2 - k]'(by have := le_snd_of_mem_zipIdx h; have := snd_lt_add_of_mem_zipIdx h; omega) := by
+  cases xs
   exact List.fst_eq_of_mem_zipIdx (by simpa using h)
 
 theorem mem_zipIdx {x : α} {i : Nat} {xs : Array α} {k : Nat} (h : (x, i) ∈ xs.zipIdx k) :
@@ -267,9 +271,9 @@ theorem mem_zipIdx' {x : α} {i : Nat} {xs : Array α} (h : (x, i) ∈ xs.zipIdx
     i < xs.size ∧ x = xs[i]'(by have := le_snd_of_mem_zipIdx h; have := snd_lt_add_of_mem_zipIdx h; omega) :=
   ⟨by simpa using snd_lt_add_of_mem_zipIdx h, fst_eq_of_mem_zipIdx h⟩
 
-theorem zipIdx_map (l : Array α) (k : Nat) (f : α → β) :
-    zipIdx (l.map f) k = (zipIdx l k).map (Prod.map f id) := by
-  cases l
+theorem zipIdx_map (xs : Array α) (k : Nat) (f : α → β) :
+    zipIdx (xs.map f) k = (zipIdx xs k).map (Prod.map f id) := by
+  cases xs
   simp [List.zipIdx_map]
 
 theorem zipIdx_append (xs ys : Array α) (k : Nat) :
@@ -278,12 +282,12 @@ theorem zipIdx_append (xs ys : Array α) (k : Nat) :
   cases ys
   simp [List.zipIdx_append]
 
-theorem zipIdx_eq_append_iff {l : Array α} {k : Nat} :
-    zipIdx l k = l₁ ++ l₂ ↔
-      ∃ l₁' l₂', l = l₁' ++ l₂' ∧ l₁ = zipIdx l₁' k ∧ l₂ = zipIdx l₂' (k + l₁'.size) := by
-  rcases l with ⟨l⟩
-  rcases l₁ with ⟨l₁⟩
-  rcases l₂ with ⟨l₂⟩
+theorem zipIdx_eq_append_iff {xs : Array α} {k : Nat} :
+    zipIdx xs k = ys ++ zs ↔
+      ∃ ys' zs', xs = ys' ++ zs' ∧ ys = zipIdx ys' k ∧ zs = zipIdx zs' (k + ys'.size) := by
+  rcases xs with ⟨xs⟩
+  rcases ys with ⟨ys⟩
+  rcases zs with ⟨zs⟩
   simp only [zipIdx_toArray, List.append_toArray, mk.injEq, List.zipIdx_eq_append_iff,
     toArray_eq_append_iff]
   constructor

src/Init/Data/Array/Set.lean

@@ -6,27 +6,40 @@ Authors: Leonardo de Moura, Mario Carneiro
 prelude
 import Init.Tactics
 
+set_option linter.listVariables true -- Enforce naming conventions for `List`/`Array`/`Vector` variables.
+set_option linter.indexVariables true -- Enforce naming conventions for index variables.
+
 
 /--
-Set an element in an array, using a proof that the index is in bounds.
-(This proof can usually be omitted, and will be synthesized automatically.)
+Replaces the element at a given index in an array.
 
-This will perform the update destructively provided that `a` has a reference
-count of 1 when called.
+No bounds check is performed, but the function requires a proof that the index is in bounds. This
+proof can usually be omitted, and will be synthesized automatically.
+
+The array is modified in-place if there are no other references to it.
+
+Examples:
+* `#[0, 1, 2].set 1 5 = #[0, 5, 2]`
+* `#["orange", "apple"].set 1 "grape" = #["orange", "grape"]`
 -/
 @[extern "lean_array_fset"]
-def Array.set (a : Array α) (i : @& Nat) (v : α) (h : i < a.size := by get_elem_tactic) :
+def Array.set (xs : Array α) (i : @& Nat) (v : α) (h : i < xs.size := by get_elem_tactic) :
     Array α where
-  toList := a.toList.set i v
+  toList := xs.toList.set i v
 
 /--
-Set an element in an array, or do nothing if the index is out of bounds.
+Replaces the element at the provided index in an array. The array is returned unmodified if the
+index is out of bounds.
 
-This will perform the update destructively provided that `a` has a reference
-count of 1 when called.
+The array is modified in-place if there are no other references to it.
+
+Examples:
+* `#[0, 1, 2].setIfInBounds 1 5 = #[0, 5, 2]`
+* `#["orange", "apple"].setIfInBounds 1 "grape" = #["orange", "grape"]`
+* `#["orange", "apple"].setIfInBounds 5 "grape" = #["orange", "apple"]`
 -/
-@[inline] def Array.setIfInBounds (a : Array α) (i : Nat) (v : α) : Array α :=
-  dite (LT.lt i a.size) (fun h => a.set i v h) (fun _ => a)
+@[inline] def Array.setIfInBounds (xs : Array α) (i : Nat) (v : α) : Array α :=
+  dite (LT.lt i xs.size) (fun h => xs.set i v h) (fun _ => xs)
 
 @[deprecated Array.setIfInBounds (since := "2024-11-24")] abbrev Array.setD := @Array.setIfInBounds
 
@@ -37,5 +50,5 @@ This will perform the update destructively provided that `a` has a reference
 count of 1 when called.
 -/
 @[extern "lean_array_set"]
-def Array.set! (a : Array α) (i : @& Nat) (v : α) : Array α :=
-  Array.setIfInBounds a i v
+def Array.set! (xs : Array α) (i : @& Nat) (v : α) : Array α :=
+  Array.setIfInBounds xs i v

src/Init/Data/Array/Subarray.lean

@@ -6,17 +6,45 @@ Authors: Leonardo de Moura
 prelude
 import Init.Data.Array.Basic
 
+set_option linter.indexVariables true -- Enforce naming conventions for index variables.
+set_option linter.missingDocs true
+
 universe u v w
 
-structure Subarray (α : Type u)  where
+/--
+A region of some underlying array.
+
+A subarray contains an array together with the start and end indices of a region of interest.
+Subarrays can be used to avoid copying or allocating space, while being more convenient than
+tracking the bounds by hand. The region of interest consists of every index that is both greater
+than or equal to `start` and strictly less than `stop`.
+-/
+structure Subarray (α : Type u) where
+  /-- The underlying array. -/
   array : Array α
+  /-- The starting index of the region of interest (inclusive). -/
   start : Nat
+  /-- The ending index of the region of interest (exclusive). -/
   stop : Nat
+  /--
+  The starting index is no later than the ending index.
+
+  The ending index is exclusive. If the starting and ending indices are equal, then the subarray is
+  empty.
+  -/
   start_le_stop : start ≤ stop
+  /-- The stopping index is no later than the end of the array.
+
+  The ending index is exclusive. If it is equal to the size of the array, then the last element of
+  the array is in the subarray.
+  -/
   stop_le_array_size : stop ≤ array.size
 
 namespace Subarray
 
+/--
+Computes the size of the subarray.
+-/
 def size (s : Subarray α) : Nat :=
   s.stop - s.start
 
@@ -26,6 +54,11 @@ theorem size_le_array_size {s : Subarray α} : s.size ≤ s.array.size := by
   apply Nat.le_trans (Nat.sub_le stop start)
   assumption
 
+/--
+Extracts an element from the subarray.
+
+The index is relative to the start of the subarray, rather than the underlying array.
+-/
 def get (s : Subarray α) (i : Fin s.size) : α :=
   have : s.start + i.val < s.array.size := by
    apply Nat.lt_of_lt_of_le _ s.stop_le_array_size
@@ -38,12 +71,33 @@ def get (s : Subarray α) (i : Fin s.size) : α :=
 instance : GetElem (Subarray α) Nat α fun xs i => i < xs.size where
   getElem xs i h := xs.get ⟨i, h⟩
 
+/--
+Extracts an element from the subarray, or returns a default value `v₀` when the index is out of
+bounds.
+
+The index is relative to the start and end of the subarray, rather than the underlying array.
+-/
 @[inline] def getD (s : Subarray α) (i : Nat) (v₀ : α) : α :=
   if h : i < s.size then s[i] else v₀
 
+/--
+Extracts an element from the subarray, or returns a default value when the index is out of bounds.
+
+The index is relative to the start and end of the subarray, rather than the underlying array. The
+default value is that provided by the `Inhabited α` instance.
+-/
 abbrev get! [Inhabited α] (s : Subarray α) (i : Nat) : α :=
   getD s i default
 
+/--
+Shrinks the subarray by incrementing its starting index if possible, returning it unchanged if not.
+
+Examples:
+ * `#[1,2,3].toSubarray.popFront.toArray = #[2, 3]`
+ * `#[1,2,3].toSubarray.popFront.popFront.toArray = #[3]`
+ * `#[1,2,3].toSubarray.popFront.popFront.popFront.toArray = #[]`
+ * `#[1,2,3].toSubarray.popFront.popFront.popFront.popFront.toArray = #[]`
+-/
 def popFront (s : Subarray α) : Subarray α :=
   if h : s.start < s.stop then
     { s with start := s.start + 1, start_le_stop := Nat.le_of_lt_succ (Nat.add_lt_add_right h 1) }
@@ -52,6 +106,8 @@ def popFront (s : Subarray α) : Subarray α :=
 
 /--
 The empty subarray.
+
+This empty subarray is backed by an empty array.
 -/
 protected def empty : Subarray α where
   array := #[]
@@ -66,6 +122,12 @@ instance : EmptyCollection (Subarray α) :=
 instance : Inhabited (Subarray α) :=
   ⟨{}⟩
 
+/--
+The run-time implementation of `ForIn.forIn` for `Subarray`, which allows it to be used with `for`
+loops in `do`-notation.
+
+This definition replaces `Subarray.forIn`.
+-/
 @[inline] unsafe def forInUnsafe {α : Type u} {β : Type v} {m : Type v → Type w} [Monad m] (s : Subarray α) (b : β) (f : α → β → m (ForInStep β)) : m β :=
   let sz := USize.ofNat s.stop
   let rec @[specialize] loop (i : USize) (b : β) : m β := do
@@ -78,6 +140,10 @@ instance : Inhabited (Subarray α) :=
       pure b
   loop (USize.ofNat s.start) b
 
+/--
+The implementation of `ForIn.forIn` for `Subarray`, which allows it to be used with `for` loops in
+`do`-notation.
+-/
 -- TODO: provide reference implementation
 @[implemented_by Subarray.forInUnsafe]
 protected opaque forIn {α : Type u} {β : Type v} {m : Type v → Type w} [Monad m] (s : Subarray α) (b : β) (f : α → β → m (ForInStep β)) : m β :=
@@ -86,46 +152,197 @@ protected opaque forIn {α : Type u} {β : Type v} {m : Type v → Type w} [Mona
 instance : ForIn m (Subarray α) α where
   forIn := Subarray.forIn
 
+/--
+Folds a monadic operation from left to right over the elements in a subarray.
+
+An accumulator of type `β` is constructed by starting with `init` and monadically combining each
+element of the subarray with the current accumulator value in turn. The monad in question may permit
+early termination or repetition.
+
+Examples:
+```lean example
+#eval #["red", "green", "blue"].toSubarray.foldlM (init := "") fun acc x => do
+  let l ← Option.guard (· ≠ 0) x.length
+  return s!"{acc}({l}){x} "
+```
+```output
+some "(3)red (5)green (4)blue "
+```
+```lean example
+#eval #["red", "green", "blue"].toSubarray.foldlM (init := 0) fun acc x => do
+  let l ← Option.guard (· ≠ 5) x.length
+  return s!"{acc}({l}){x} "
+```
+```output
+none
+```
+-/
 @[inline]
 def foldlM {α : Type u} {β : Type v} {m : Type v → Type w} [Monad m] (f : β → α → m β) (init : β) (as : Subarray α) : m β :=
   as.array.foldlM f (init := init) (start := as.start) (stop := as.stop)
 
+/--
+Folds a monadic operation from right to left over the elements in a subarray.
+
+An accumulator of type `β` is constructed by starting with `init` and monadically combining each
+element of the subarray with the current accumulator value in turn, moving from the end to the
+start. The monad in question may permit early termination or repetition.
+
+Examples:
+```lean example
+#eval #["red", "green", "blue"].toSubarray.foldrM (init := "") fun x acc => do
+  let l ← Option.guard (· ≠ 0) x.length
+  return s!"{acc}({l}){x} "
+```
+```output
+some "(4)blue (5)green (3)red "
+```
+```lean example
+#eval #["red", "green", "blue"].toSubarray.foldrM (init := 0) fun x acc => do
+  let l ← Option.guard (· ≠ 5) x.length
+  return s!"{acc}({l}){x} "
+```
+```output
+none
+```
+-/
 @[inline]
 def foldrM {α : Type u} {β : Type v} {m : Type v → Type w} [Monad m] (f : α → β → m β) (init : β) (as : Subarray α) : m β :=
   as.array.foldrM f (init := init) (start := as.stop) (stop := as.start)
 
+/--
+Checks whether any of the elements in a subarray satisfy a monadic Boolean predicate.
+
+The elements are tested starting at the lowest index and moving up. The search terminates as soon as
+an element that satisfies the predicate is found.
+
+Example:
+```lean example
+#eval #["red", "green", "blue", "orange"].toSubarray.popFront.anyM fun x => do
+  IO.println x
+  pure (x == "blue")
+```
+```output
+green
+blue
+```
+```output
+true
+```
+-/
 @[inline]
 def anyM {α : Type u} {m : Type → Type w} [Monad m] (p : α → m Bool) (as : Subarray α) : m Bool :=
   as.array.anyM p (start := as.start) (stop := as.stop)
 
+/--
+Checks whether all of the elements in a subarray satisfy a monadic Boolean predicate.
+
+The elements are tested starting at the lowest index and moving up. The search terminates as soon as
+an element that does not satisfy the predicate is found.
+
+Example:
+```lean example
+#eval #["red", "green", "blue", "orange"].toSubarray.popFront.allM fun x => do
+  IO.println x
+  pure (x.length == 5)
+```
+```output
+green
+blue
+```
+```output
+false
+```
+-/
 @[inline]
 def allM {α : Type u} {m : Type → Type w} [Monad m] (p : α → m Bool) (as : Subarray α) : m Bool :=
   as.array.allM p (start := as.start) (stop := as.stop)
 
+/--
+Runs a monadic action on each element of a subarray.
+
+The elements are processed starting at the lowest index and moving up.
+-/
 @[inline]
 def forM {α : Type u} {m : Type v → Type w} [Monad m] (f : α → m PUnit) (as : Subarray α) : m PUnit :=
   as.array.forM f (start := as.start) (stop := as.stop)
 
+/--
+Runs a monadic action on each element of a subarray, in reverse order.
+
+The elements are processed starting at the highest index and moving down.
+-/
 @[inline]
 def forRevM {α : Type u} {m : Type v → Type w} [Monad m] (f : α → m PUnit) (as : Subarray α) : m PUnit :=
   as.array.forRevM f (start := as.stop) (stop := as.start)
 
+/--
+Folds an operation from left to right over the elements in a subarray.
+
+An accumulator of type `β` is constructed by starting with `init` and combining each
+element of the subarray with the current accumulator value in turn.
+
+Examples:
+ * `#["red", "green", "blue"].toSubarray.foldl (· + ·.length) 0 = 12`
+ * `#["red", "green", "blue"].toSubarray.popFront.foldl (· + ·.length) 0 = 9`
+-/
 @[inline]
 def foldl {α : Type u} {β : Type v} (f : β → α → β) (init : β) (as : Subarray α) : β :=
   Id.run <| as.foldlM f (init := init)
 
+/--
+Folds an operation from right to left over the elements in a subarray.
+
+An accumulator of type `β` is constructed by starting with `init` and combining each element of the
+subarray with the current accumulator value in turn, moving from the end to the start.
+
+Examples:
+ * `#eval #["red", "green", "blue"].toSubarray.foldr (·.length + ·) 0 = 12`
+ * `#["red", "green", "blue"].toSubarray.popFront.foldlr (·.length + ·) 0 = 9`
+-/
 @[inline]
 def foldr {α : Type u} {β : Type v} (f : α → β → β) (init : β) (as : Subarray α) : β :=
   Id.run <| as.foldrM f (init := init)
 
+/--
+Checks whether any of the elements in a subarray satisfy a Boolean predicate.
+
+The elements are tested starting at the lowest index and moving up. The search terminates as soon as
+an element that satisfies the predicate is found.
+-/
 @[inline]
 def any {α : Type u} (p : α → Bool) (as : Subarray α) : Bool :=
   Id.run <| as.anyM p
 
+/--
+Checks whether all of the elements in a subarray satisfy a Boolean predicate.
+
+The elements are tested starting at the lowest index and moving up. The search terminates as soon as
+an element that does not satisfy the predicate is found.
+-/
 @[inline]
 def all {α : Type u} (p : α → Bool) (as : Subarray α) : Bool :=
   Id.run <| as.allM p
 
+/--
+Applies a monadic function to each element in a subarray in reverse order, stopping at the first
+element for which the function succeeds by returning a value other than `none`. The succeeding value
+is returned, or `none` if there is no success.
+
+Example:
+```lean example
+#eval #["red", "green", "blue"].toSubarray.findSomeRevM? fun x => do
+  IO.println x
+  return Option.guard (· = 5) x.length
+```
+```output
+blue
+green
+```
+```output
+some 5
+```
+-/
 @[inline]
 def findSomeRevM? {α : Type u} {β : Type v} {m : Type v → Type w} [Monad m] (as : Subarray α) (f : α → m (Option β)) : m (Option β) :=
   let rec @[specialize] find : (i : Nat) → i ≤ as.size → m (Option β)
@@ -140,10 +357,39 @@ def findSomeRevM? {α : Type u} {β : Type v} {m : Type v → Type w} [Monad m]
         find i this
   find as.size (Nat.le_refl _)
 
+/--
+Applies a monadic Boolean predicate to each element in a subarray in reverse order, stopping at the
+first element that satisfies the predicate. The element that satisfies the predicate is returned, or
+`none` if no element satisfies it.
+
+Example:
+```lean example
+#eval #["red", "green", "blue"].toSubarray.findRevM? fun x => do
+  IO.println x
+  return (x.length = 5)
+```
+```output
+blue
+green
+```
+```output
+some 5
+```
+-/
 @[inline]
 def findRevM? {α : Type} {m : Type → Type w} [Monad m] (as : Subarray α) (p : α → m Bool) : m (Option α) :=
   as.findSomeRevM? fun a => return if (← p a) then some a else none
 
+/--
+Tests each element in a subarray with a Boolean predicate in reverse order, stopping at the first
+element that satisfies the predicate. The element that satisfies the predicate is returned, or
+`none` if no element satisfies the predicate.
+
+Examples:
+ * `#["red", "green", "blue"].toSubarray.findRev? (·.length ≠ 4) = some "green"`
+ * `#["red", "green", "blue"].toSubarray.findRev? (fun _ => true) = some "blue"`
+ * `#["red", "green", "blue"].toSubarray 0 0 |>.findRev? (fun _ => true) = none`
+-/
 @[inline]
 def findRev? {α : Type} (as : Subarray α) (p : α → Bool) : Option α :=
   Id.run <| as.findRevM? p
@@ -153,6 +399,12 @@ end Subarray
 namespace Array
 variable {α : Type u}
 
+/--
+Returns a subarray of an array, with the given bounds.
+
+If `start` or `stop` are not valid bounds for a subarray, then they are clamped to array's size.
+Additionally, the starting index is clamped to the ending index.
+-/
 def toSubarray (as : Array α) (start : Nat := 0) (stop : Nat := as.size) : Subarray α :=
   if h₂ : stop ≤ as.size then
     if h₁ : start ≤ stop then
@@ -175,6 +427,9 @@ def toSubarray (as : Array α) (start : Nat := 0) (stop : Nat := as.size) : Suba
         start_le_stop := Nat.le_refl _,
         stop_le_array_size := Nat.le_refl _ }
 
+/--
+Allocates a new array that contains the contents of the subarray.
+-/
 @[coe]
 def ofSubarray (s : Subarray α) : Array α := Id.run do
   let mut as := mkEmpty (s.stop - s.start)
@@ -184,8 +439,11 @@ def ofSubarray (s : Subarray α) : Array α := Id.run do
 
 instance : Coe (Subarray α) (Array α) := ⟨ofSubarray⟩
 
+/-- A subarray with the provided bounds.-/
 syntax:max term noWs "[" withoutPosition(term ":" term) "]" : term
+/-- A subarray with the provided lower bound that extends to the rest of the array. -/
 syntax:max term noWs "[" withoutPosition(term ":") "]" : term
+/-- A subarray with the provided upper bound, starting at the index 0. -/
 syntax:max term noWs "[" withoutPosition(":" term) "]" : term
 
 macro_rules
@@ -195,6 +453,7 @@ macro_rules
 
 end Array
 
+@[inherit_doc Array.ofSubarray]
 def Subarray.toArray (s : Subarray α) : Array α :=
   Array.ofSubarray s
 

src/Init/Data/Array/Subarray/Split.lean

@@ -15,9 +15,13 @@ automation. Placing them in another module breaks an import cycle, because `omeg
 array library.
 -/
 
+set_option linter.listVariables true -- Enforce naming conventions for `List`/`Array`/`Vector` variables.
+set_option linter.indexVariables true -- Enforce naming conventions for index variables.
+
 namespace Subarray
 /--
-Splits a subarray into two parts.
+Splits a subarray into two parts, the first of which contains the first `i` elements and the second
+of which contains the remainder.
 -/
 def split (s : Subarray α) (i : Fin s.size.succ) : (Subarray α × Subarray α) :=
   let ⟨i', isLt⟩ := i

src/Init/Data/Array/TakeDrop.lean

@@ -12,6 +12,9 @@ These lemmas are used in the internals of HashMap.
 They should find a new home and/or be reformulated.
 -/
 
+set_option linter.listVariables true -- Enforce naming conventions for `List`/`Array`/`Vector` variables.
+set_option linter.indexVariables true -- Enforce naming conventions for index variables.
+
 namespace List
 
 theorem exists_of_set {i : Nat} {a' : α} {l : List α} (h : i < l.length) :
@@ -23,9 +26,9 @@ end List
 
 namespace Array
 
-theorem exists_of_uset (self : Array α) (i d h) :
-    ∃ l₁ l₂, self.toList = l₁ ++ self[i] :: l₂ ∧ List.length l₁ = i.toNat ∧
-      (self.uset i d h).toList = l₁ ++ d :: l₂ := by
+theorem exists_of_uset (xs : Array α) (i d h) :
+    ∃ l₁ l₂, xs.toList = l₁ ++ xs[i] :: l₂ ∧ List.length l₁ = i.toNat ∧
+      (xs.uset i d h).toList = l₁ ++ d :: l₂ := by
   simpa only [ugetElem_eq_getElem, ← getElem_toList, uset, toList_set] using
     List.exists_of_set _
 

src/Init/Data/Array/Zip.lean

@@ -11,6 +11,9 @@ import Init.Data.List.Zip
 # Lemmas about `Array.zip`, `Array.zipWith`, `Array.zipWithAll`, and `Array.unzip`.
 -/
 
+set_option linter.listVariables true -- Enforce naming conventions for `List`/`Array`/`Vector` variables.
+set_option linter.indexVariables true -- Enforce naming conventions for index variables.
+
 namespace Array
 
 open Nat
@@ -19,20 +22,20 @@ open Nat
 
 /-! ### zipWith -/
 
-theorem zipWith_comm (f : α → β → γ) (la : Array α) (lb : Array β) :
-    zipWith f la lb = zipWith (fun b a => f a b) lb la := by
-  cases la
-  cases lb
+theorem zipWith_comm (f : α → β → γ) (as : Array α) (bs : Array β) :
+    zipWith f as bs = zipWith (fun b a => f a b) bs as := by
+  cases as
+  cases bs
   simpa using List.zipWith_comm _ _ _
 
-theorem zipWith_comm_of_comm (f : α → α → β) (comm : ∀ x y : α, f x y = f y x) (l l' : Array α) :
-    zipWith f l l' = zipWith f l' l := by
+theorem zipWith_comm_of_comm (f : α → α → β) (comm : ∀ x y : α, f x y = f y x) (xs ys : Array α) :
+    zipWith f xs ys = zipWith f ys xs := by
   rw [zipWith_comm]
   simp only [comm]
 
 @[simp]
-theorem zipWith_self (f : α → α → δ) (l : Array α) : zipWith f l l = l.map fun a => f a a := by
-  cases l
+theorem zipWith_self (f : α → α → δ) (xs : Array α) : zipWith f xs xs = xs.map fun a => f a a := by
+  cases xs
   simp
 
 /--
@@ -54,15 +57,15 @@ theorem getElem?_zipWith' {f : α → β → γ} {i : Nat} :
   cases l₂
   simp [List.getElem?_zipWith']
 
-theorem getElem?_zipWith_eq_some {f : α → β → γ} {l₁ : Array α} {l₂ : Array β} {z : γ} {i : Nat} :
-    (zipWith f l₁ l₂)[i]? = some z ↔
-      ∃ x y, l₁[i]? = some x ∧ l₂[i]? = some y ∧ f x y = z := by
-  cases l₁
-  cases l₂
+theorem getElem?_zipWith_eq_some {f : α → β → γ} {as : Array α} {bs : Array β} {z : γ} {i : Nat} :
+    (zipWith f as bs)[i]? = some z ↔
+      ∃ x y, as[i]? = some x ∧ bs[i]? = some y ∧ f x y = z := by
+  cases as
+  cases bs
   simp [List.getElem?_zipWith_eq_some]
 
-theorem getElem?_zip_eq_some {l₁ : Array α} {l₂ : Array β} {z : α × β} {i : Nat} :
-    (zip l₁ l₂)[i]? = some z ↔ l₁[i]? = some z.1 ∧ l₂[i]? = some z.2 := by
+theorem getElem?_zip_eq_some {as : Array α} {bs : Array β} {z : α × β} {i : Nat} :
+    (zip as bs)[i]? = some z ↔ as[i]? = some z.1 ∧ bs[i]? = some z.2 := by
   cases z
   rw [zip, getElem?_zipWith_eq_some]; constructor
   · rintro ⟨x, y, h₀, h₁, h₂⟩
@@ -71,210 +74,216 @@ theorem getElem?_zip_eq_some {l₁ : Array α} {l₂ : Array β} {z : α × β}
     exact ⟨_, _, h₀, h₁, rfl⟩
 
 @[simp]
-theorem zipWith_map {μ} (f : γ → δ → μ) (g : α → γ) (h : β → δ) (l₁ : Array α) (l₂ : Array β) :
-    zipWith f (l₁.map g) (l₂.map h) = zipWith (fun a b => f (g a) (h b)) l₁ l₂ := by
-  cases l₁
-  cases l₂
+theorem zipWith_map {μ} (f : γ → δ → μ) (g : α → γ) (h : β → δ) (as : Array α) (bs : Array β) :
+    zipWith f (as.map g) (bs.map h) = zipWith (fun a b => f (g a) (h b)) as bs := by
+  cases as
+  cases bs
   simp [List.zipWith_map]
 
-theorem zipWith_map_left (l₁ : Array α) (l₂ : Array β) (f : α → α') (g : α' → β → γ) :
-    zipWith g (l₁.map f) l₂ = zipWith (fun a b => g (f a) b) l₁ l₂ := by
-  cases l₁
-  cases l₂
+theorem zipWith_map_left (as : Array α) (bs : Array β) (f : α → α') (g : α' → β → γ) :
+    zipWith g (as.map f) bs = zipWith (fun a b => g (f a) b) as bs := by
+  cases as
+  cases bs
   simp [List.zipWith_map_left]
 
-theorem zipWith_map_right (l₁ : Array α) (l₂ : Array β) (f : β → β') (g : α → β' → γ) :
-    zipWith g l₁ (l₂.map f) = zipWith (fun a b => g a (f b)) l₁ l₂ := by
-  cases l₁
-  cases l₂
+theorem zipWith_map_right (as : Array α) (bs : Array β) (f : β → β') (g : α → β' → γ) :
+    zipWith g as (bs.map f) = zipWith (fun a b => g a (f b)) as bs := by
+  cases as
+  cases bs
   simp [List.zipWith_map_right]
 
 theorem zipWith_foldr_eq_zip_foldr {f : α → β → γ} (i : δ):
-    (zipWith f l₁ l₂).foldr g i = (zip l₁ l₂).foldr (fun p r => g (f p.1 p.2) r) i := by
-  cases l₁
-  cases l₂
+    (zipWith f as bs).foldr g i = (zip as bs).foldr (fun p r => g (f p.1 p.2) r) i := by
+  cases as
+  cases bs
   simp [List.zipWith_foldr_eq_zip_foldr]
 
 theorem zipWith_foldl_eq_zip_foldl {f : α → β → γ} (i : δ):
-    (zipWith f l₁ l₂).foldl g i = (zip l₁ l₂).foldl (fun r p => g r (f p.1 p.2)) i := by
-  cases l₁
-  cases l₂
+    (zipWith f as bs).foldl g i = (zip as bs).foldl (fun r p => g r (f p.1 p.2)) i := by
+  cases as
+  cases bs
   simp [List.zipWith_foldl_eq_zip_foldl]
 
 @[simp]
-theorem zipWith_eq_empty_iff {f : α → β → γ} {l l'} : zipWith f l l' = #[] ↔ l = #[] ∨ l' = #[] := by
-  cases l <;> cases l' <;> simp
+theorem zipWith_eq_empty_iff {f : α → β → γ} {as : Array α} {bs : Array β} : zipWith f as bs = #[] ↔ as = #[] ∨ bs = #[] := by
+  cases as <;> cases bs <;> simp
 
-theorem map_zipWith {δ : Type _} (f : α → β) (g : γ → δ → α) (l : Array γ) (l' : Array δ) :
-    map f (zipWith g l l') = zipWith (fun x y => f (g x y)) l l' := by
-  cases l
-  cases l'
+theorem map_zipWith {δ : Type _} (f : α → β) (g : γ → δ → α) (cs : Array γ) (ds : Array δ) :
+    map f (zipWith g cs ds) = zipWith (fun x y => f (g x y)) cs ds := by
+  cases cs
+  cases ds
   simp [List.map_zipWith]
 
-theorem take_zipWith : (zipWith f l l').take n = zipWith f (l.take n) (l'.take n) := by
-  cases l
-  cases l'
+theorem take_zipWith : (zipWith f as bs).take i = zipWith f (as.take i) (bs.take i) := by
+  cases as
+  cases bs
   simp [List.take_zipWith]
 
-theorem extract_zipWith : (zipWith f l l').extract m n = zipWith f (l.extract m n) (l'.extract m n) := by
-  cases l
-  cases l'
+theorem extract_zipWith : (zipWith f as bs).extract i j = zipWith f (as.extract i j) (bs.extract i j) := by
+  cases as
+  cases bs
   simp [List.drop_zipWith, List.take_zipWith]
 
-theorem zipWith_append (f : α → β → γ) (l la : Array α) (l' lb : Array β)
-    (h : l.size = l'.size) :
-    zipWith f (l ++ la) (l' ++ lb) = zipWith f l l' ++ zipWith f la lb := by
-  cases l
-  cases l'
-  cases la
-  cases lb
+theorem zipWith_append (f : α → β → γ) (as as' : Array α) (bs bs' : Array β)
+    (h : as.size = bs.size) :
+    zipWith f (as ++ as') (bs ++ bs') = zipWith f as bs ++ zipWith f as' bs' := by
+  cases as
+  cases bs
+  cases as'
+  cases bs'
   simp at h
   simp [List.zipWith_append, h]
 
-theorem zipWith_eq_append_iff {f : α → β → γ} {l₁ : Array α} {l₂ : Array β} :
-    zipWith f l₁ l₂ = l₁' ++ l₂' ↔
-      ∃ w x y z, w.size = y.size ∧ l₁ = w ++ x ∧ l₂ = y ++ z ∧ l₁' = zipWith f w y ∧ l₂' = zipWith f x z := by
-  cases l₁
-  cases l₂
-  cases l₁'
-  cases l₂'
+theorem zipWith_eq_append_iff {f : α → β → γ} {as : Array α} {bs : Array β} :
+    zipWith f as bs = xs ++ ys ↔
+      ∃ as₁ as₂ bs₁ bs₂, as₁.size = bs₁.size ∧ as = as₁ ++ as₂ ∧ bs = bs₁ ++ bs₂ ∧ xs = zipWith f as₁ bs₁ ∧ ys = zipWith f as₂ bs₂ := by
+  cases as
+  cases bs
+  cases xs
+  cases ys
   simp only [List.zipWith_toArray, List.append_toArray, mk.injEq, List.zipWith_eq_append_iff,
     toArray_eq_append_iff]
   constructor
-  · rintro ⟨w, x, y, z, h, rfl, rfl, rfl, rfl⟩
-    exact ⟨w.toArray, x.toArray, y.toArray, z.toArray, by simp [h]⟩
-  · rintro ⟨⟨w⟩, ⟨x⟩, ⟨y⟩, ⟨z⟩, h, rfl, rfl, h₁, h₂⟩
-    exact ⟨w, x, y, z, by simp_all⟩
+  · rintro ⟨ws, xs, ys, zs, h, rfl, rfl, rfl, rfl⟩
+    exact ⟨ws.toArray, xs.toArray, ys.toArray, zs.toArray, by simp [h]⟩
+  · rintro ⟨⟨ws⟩, ⟨xs⟩, ⟨ys⟩, ⟨zs⟩, h, rfl, rfl, h₁, h₂⟩
+    exact ⟨ws, xs, ys, zs, by simp_all⟩
 
-@[simp] theorem zipWith_mkArray {a : α} {b : β} {m n : Nat} :
-    zipWith f (mkArray m a) (mkArray n b) = mkArray (min m n) (f a b) := by
+@[simp] theorem zipWith_replicate {a : α} {b : β} {m n : Nat} :
+    zipWith f (replicate m a) (replicate n b) = replicate (min m n) (f a b) := by
   simp [← List.toArray_replicate]
 
-theorem map_uncurry_zip_eq_zipWith (f : α → β → γ) (l : Array α) (l' : Array β) :
-    map (Function.uncurry f) (l.zip l') = zipWith f l l' := by
-  cases l
-  cases l'
+@[deprecated zipWith_replicate (since := "2025-03-18")]
+abbrev zipWith_mkArray := @zipWith_replicate
+
+theorem map_uncurry_zip_eq_zipWith (f : α → β → γ) (as : Array α) (bs : Array β) :
+    map (Function.uncurry f) (as.zip bs) = zipWith f as bs := by
+  cases as
+  cases bs
   simp [List.map_uncurry_zip_eq_zipWith]
 
-theorem map_zip_eq_zipWith (f : α × β → γ) (l : Array α) (l' : Array β) :
-    map f (l.zip l') = zipWith (Function.curry f) l l' := by
-  cases l
-  cases l'
+theorem map_zip_eq_zipWith (f : α × β → γ) (as : Array α) (bs : Array β) :
+    map f (as.zip bs) = zipWith (Function.curry f) as bs := by
+  cases as
+  cases bs
   simp [List.map_zip_eq_zipWith]
 
-theorem lt_size_left_of_zipWith {f : α → β → γ} {i : Nat} {l : Array α} {l' : Array β}
-    (h : i < (zipWith f l l').size) : i < l.size := by rw [size_zipWith] at h; omega
+theorem lt_size_left_of_zipWith {f : α → β → γ} {i : Nat} {as : Array α} {bs : Array β}
+    (h : i < (zipWith f as bs).size) : i < as.size := by rw [size_zipWith] at h; omega
 
-theorem lt_size_right_of_zipWith {f : α → β → γ} {i : Nat} {l : Array α} {l' : Array β}
-    (h : i < (zipWith f l l').size) : i < l'.size := by rw [size_zipWith] at h; omega
+theorem lt_size_right_of_zipWith {f : α → β → γ} {i : Nat} {as : Array α} {bs : Array β}
+    (h : i < (zipWith f as bs).size) : i < bs.size := by rw [size_zipWith] at h; omega
 
-theorem zipWith_eq_zipWith_take_min (l₁ : Array α) (l₂ : Array β) :
-    zipWith f l₁ l₂ = zipWith f (l₁.take (min l₁.size l₂.size)) (l₂.take (min l₁.size l₂.size)) := by
-  cases l₁
-  cases l₂
+theorem zipWith_eq_zipWith_take_min (as : Array α) (bs : Array β) :
+    zipWith f as bs = zipWith f (as.take (min as.size bs.size)) (bs.take (min as.size bs.size)) := by
+  cases as
+  cases bs
   simp
   rw [List.zipWith_eq_zipWith_take_min]
 
-theorem reverse_zipWith (h : l.size = l'.size) :
-    (zipWith f l l').reverse = zipWith f l.reverse l'.reverse := by
-  cases l
-  cases l'
+theorem reverse_zipWith (h : as.size = bs.size) :
+    (zipWith f as bs).reverse = zipWith f as.reverse bs.reverse := by
+  cases as
+  cases bs
   simp [List.reverse_zipWith (by simpa using h)]
 
 /-! ### zip -/
 
-theorem lt_size_left_of_zip {i : Nat} {l : Array α} {l' : Array β} (h : i < (zip l l').size) :
-    i < l.size :=
+theorem lt_size_left_of_zip {i : Nat} {as : Array α} {bs : Array β} (h : i < (zip as bs).size) :
+    i < as.size :=
   lt_size_left_of_zipWith h
 
-theorem lt_size_right_of_zip {i : Nat} {l : Array α} {l' : Array β} (h : i < (zip l l').size) :
-    i < l'.size :=
+theorem lt_size_right_of_zip {i : Nat} {as : Array α} {bs : Array β} (h : i < (zip as bs).size) :
+    i < bs.size :=
   lt_size_right_of_zipWith h
 
 @[simp]
-theorem getElem_zip {l : Array α} {l' : Array β} {i : Nat} {h : i < (zip l l').size} :
-    (zip l l')[i] =
-      (l[i]'(lt_size_left_of_zip h), l'[i]'(lt_size_right_of_zip h)) :=
+theorem getElem_zip {as : Array α} {bs : Array β} {i : Nat} {h : i < (zip as bs).size} :
+    (zip as bs)[i] =
+      (as[i]'(lt_size_left_of_zip h), bs[i]'(lt_size_right_of_zip h)) :=
   getElem_zipWith (hi := by simpa using h)
 
-theorem zip_eq_zipWith (l₁ : Array α) (l₂ : Array β) : zip l₁ l₂ = zipWith Prod.mk l₁ l₂ := by
-  cases l₁
-  cases l₂
+theorem zip_eq_zipWith (as : Array α) (bs : Array β) : zip as bs = zipWith Prod.mk as bs := by
+  cases as
+  cases bs
   simp [List.zip_eq_zipWith]
 
-theorem zip_map (f : α → γ) (g : β → δ) (l₁ : Array α) (l₂ : Array β) :
-    zip (l₁.map f) (l₂.map g) = (zip l₁ l₂).map (Prod.map f g) := by
-  cases l₁
-  cases l₂
+theorem zip_map (f : α → γ) (g : β → δ) (as : Array α) (bs : Array β) :
+    zip (as.map f) (bs.map g) = (zip as bs).map (Prod.map f g) := by
+  cases as
+  cases bs
   simp [List.zip_map]
 
-theorem zip_map_left (f : α → γ) (l₁ : Array α) (l₂ : Array β) :
-    zip (l₁.map f) l₂ = (zip l₁ l₂).map (Prod.map f id) := by rw [← zip_map, map_id]
+theorem zip_map_left (f : α → γ) (as : Array α) (bs : Array β) :
+    zip (as.map f) bs = (zip as bs).map (Prod.map f id) := by rw [← zip_map, map_id]
 
-theorem zip_map_right (f : β → γ) (l₁ : Array α) (l₂ : Array β) :
-    zip l₁ (l₂.map f) = (zip l₁ l₂).map (Prod.map id f) := by rw [← zip_map, map_id]
+theorem zip_map_right (f : β → γ) (as : Array α) (bs : Array β) :
+    zip as (bs.map f) = (zip as bs).map (Prod.map id f) := by rw [← zip_map, map_id]
 
-theorem zip_append {l₁ r₁ : Array α} {l₂ r₂ : Array β} (_h : l₁.size = l₂.size) :
-    zip (l₁ ++ r₁) (l₂ ++ r₂) = zip l₁ l₂ ++ zip r₁ r₂ := by
-  cases l₁
-  cases l₂
-  cases r₁
-  cases r₂
+theorem zip_append {as bs : Array α} {cs ds : Array β} (_h : as.size = cs.size) :
+    zip (as ++ bs) (cs ++ ds) = zip as cs ++ zip bs ds := by
+  cases as
+  cases cs
+  cases bs
+  cases ds
   simp_all [List.zip_append]
 
-theorem zip_map' (f : α → β) (g : α → γ) (l : Array α) :
-    zip (l.map f) (l.map g) = l.map fun a => (f a, g a) := by
-  cases l
+theorem zip_map' (f : α → β) (g : α → γ) (xs : Array α) :
+    zip (xs.map f) (xs.map g) = xs.map fun a => (f a, g a) := by
+  cases xs
   simp [List.zip_map']
 
-theorem of_mem_zip {a b} {l₁ : Array α} {l₂ : Array β} : (a, b) ∈ zip l₁ l₂ → a ∈ l₁ ∧ b ∈ l₂ := by
-  cases l₁
-  cases l₂
+theorem of_mem_zip {a b} {as : Array α} {bs : Array β} : (a, b) ∈ zip as bs → a ∈ as ∧ b ∈ bs := by
+  cases as
+  cases bs
   simpa using List.of_mem_zip
 
-theorem map_fst_zip (l₁ : Array α) (l₂ : Array β) (h : l₁.size ≤ l₂.size) :
-    map Prod.fst (zip l₁ l₂) = l₁ := by
-  cases l₁
-  cases l₂
+theorem map_fst_zip (as : Array α) (bs : Array β) (h : as.size ≤ bs.size) :
+    map Prod.fst (zip as bs) = as := by
+  cases as
+  cases bs
   simp_all [List.map_fst_zip]
 
-theorem map_snd_zip (l₁ : Array α) (l₂ : Array β) (h : l₂.size ≤ l₁.size) :
-    map Prod.snd (zip l₁ l₂) = l₂ := by
-  cases l₁
-  cases l₂
+theorem map_snd_zip (as : Array α) (bs : Array β) (h : bs.size ≤ as.size) :
+    map Prod.snd (zip as bs) = bs := by
+  cases as
+  cases bs
   simp_all [List.map_snd_zip]
 
-theorem map_prod_left_eq_zip {l : Array α} (f : α → β) :
-    (l.map fun x => (x, f x)) = l.zip (l.map f) := by
+theorem map_prod_left_eq_zip {xs : Array α} (f : α → β) :
+    (xs.map fun x => (x, f x)) = xs.zip (xs.map f) := by
   rw [← zip_map']
   congr
   simp
 
-theorem map_prod_right_eq_zip {l : Array α} (f : α → β) :
-    (l.map fun x => (f x, x)) = (l.map f).zip l := by
+theorem map_prod_right_eq_zip {xs : Array α} (f : α → β) :
+    (xs.map fun x => (f x, x)) = (xs.map f).zip xs := by
   rw [← zip_map']
   congr
   simp
 
-@[simp] theorem zip_eq_empty_iff {l₁ : Array α} {l₂ : Array β} :
-    zip l₁ l₂ = #[] ↔ l₁ = #[] ∨ l₂ = #[] := by
-  cases l₁
-  cases l₂
+@[simp] theorem zip_eq_empty_iff {as : Array α} {bs : Array β} :
+    zip as bs = #[] ↔ as = #[] ∨ bs = #[] := by
+  cases as
+  cases bs
   simp [List.zip_eq_nil_iff]
 
-theorem zip_eq_append_iff {l₁ : Array α} {l₂ : Array β} :
-    zip l₁ l₂ = l₁' ++ l₂' ↔
-      ∃ w x y z, w.size = y.size ∧ l₁ = w ++ x ∧ l₂ = y ++ z ∧ l₁' = zip w y ∧ l₂' = zip x z := by
+theorem zip_eq_append_iff {as : Array α} {bs : Array β} :
+    zip as bs = xs ++ ys ↔
+      ∃ as₁ as₂ bs₁ bs₂, as₁.size = bs₁.size ∧ as = as₁ ++ as₂ ∧ bs = bs₁ ++ bs₂ ∧ xs = zip as₁ bs₁ ∧ ys = zip as₂ bs₂ := by
   simp [zip_eq_zipWith, zipWith_eq_append_iff]
 
-@[simp] theorem zip_mkArray {a : α} {b : β} {m n : Nat} :
-    zip (mkArray m a) (mkArray n b) = mkArray (min m n) (a, b) := by
+@[simp] theorem zip_replicate {a : α} {b : β} {m n : Nat} :
+    zip (replicate m a) (replicate n b) = replicate (min m n) (a, b) := by
   simp [← List.toArray_replicate]
 
-theorem zip_eq_zip_take_min (l₁ : Array α) (l₂ : Array β) :
-    zip l₁ l₂ = zip (l₁.take (min l₁.size l₂.size)) (l₂.take (min l₁.size l₂.size)) := by
-  cases l₁
-  cases l₂
+@[deprecated zip_replicate (since := "2025-03-18")]
+abbrev zip_mkArray := @zip_replicate
+
+theorem zip_eq_zip_take_min (as : Array α) (bs : Array β) :
+    zip as bs = zip (as.take (min as.size bs.size)) (bs.take (min as.size bs.size)) := by
+  cases as
+  cases bs
   simp only [List.zip_toArray, List.size_toArray, List.take_toArray, mk.injEq]
   rw [List.zip_eq_zip_take_min]
 
@@ -289,35 +298,37 @@ theorem getElem?_zipWithAll {f : Option α → Option β → γ} {i : Nat} :
   simp [List.getElem?_zipWithAll]
   rfl
 
-theorem zipWithAll_map {μ} (f : Option γ → Option δ → μ) (g : α → γ) (h : β → δ) (l₁ : Array α) (l₂ : Array β) :
-    zipWithAll f (l₁.map g) (l₂.map h) = zipWithAll (fun a b => f (g <$> a) (h <$> b)) l₁ l₂ := by
-  cases l₁
-  cases l₂
+theorem zipWithAll_map {μ} (f : Option γ → Option δ → μ) (g : α → γ) (h : β → δ) (as : Array α) (bs : Array β) :
+    zipWithAll f (as.map g) (bs.map h) = zipWithAll (fun a b => f (g <$> a) (h <$> b)) as bs := by
+  cases as
+  cases bs
   simp [List.zipWithAll_map]
 
-theorem zipWithAll_map_left (l₁ : Array α) (l₂ : Array β) (f : α → α') (g : Option α' → Option β → γ) :
-    zipWithAll g (l₁.map f) l₂ = zipWithAll (fun a b => g (f <$> a) b) l₁ l₂ := by
-  cases l₁
-  cases l₂
+theorem zipWithAll_map_left (as : Array α) (bs : Array β) (f : α → α') (g : Option α' → Option β → γ) :
+    zipWithAll g (as.map f) bs = zipWithAll (fun a b => g (f <$> a) b) as bs := by
+  cases as
+  cases bs
   simp [List.zipWithAll_map_left]
 
-theorem zipWithAll_map_right (l₁ : Array α) (l₂ : Array β) (f : β → β') (g : Option α → Option β' → γ) :
-    zipWithAll g l₁ (l₂.map f) = zipWithAll (fun a b => g a (f <$> b)) l₁ l₂ := by
-  cases l₁
-  cases l₂
+theorem zipWithAll_map_right (as : Array α) (bs : Array β) (f : β → β') (g : Option α → Option β' → γ) :
+    zipWithAll g as (bs.map f) = zipWithAll (fun a b => g a (f <$> b)) as bs := by
+  cases as
+  cases bs
   simp [List.zipWithAll_map_right]
 
-theorem map_zipWithAll {δ : Type _} (f : α → β) (g : Option γ → Option δ → α) (l : Array γ) (l' : Array δ) :
-    map f (zipWithAll g l l') = zipWithAll (fun x y => f (g x y)) l l' := by
-  cases l
-  cases l'
+theorem map_zipWithAll {δ : Type _} (f : α → β) (g : Option γ → Option δ → α) (cs : Array γ) (ds : Array δ) :
+    map f (zipWithAll g cs ds) = zipWithAll (fun x y => f (g x y)) cs ds := by
+  cases cs
+  cases ds
   simp [List.map_zipWithAll]
 
-
 @[simp] theorem zipWithAll_replicate {a : α} {b : β} {n : Nat} :
-    zipWithAll f (mkArray n a) (mkArray n b) = mkArray n (f a b) := by
+    zipWithAll f (replicate n a) (replicate n b) = replicate n (f a b) := by
   simp [← List.toArray_replicate]
 
+@[deprecated zipWithAll_replicate (since := "2025-03-18")]
+abbrev zipWithAll_mkArray := @zipWithAll_replicate
+
 /-! ### unzip -/
 
 @[simp] theorem unzip_fst : (unzip l).fst = l.map Prod.fst := by
@@ -326,38 +337,41 @@ theorem map_zipWithAll {δ : Type _} (f : α → β) (g : Option γ → Option
 @[simp] theorem unzip_snd : (unzip l).snd = l.map Prod.snd := by
   induction l <;> simp_all
 
-theorem unzip_eq_map (l : Array (α × β)) : unzip l = (l.map Prod.fst, l.map Prod.snd) := by
-  cases l
+theorem unzip_eq_map (xs : Array (α × β)) : unzip xs = (xs.map Prod.fst, xs.map Prod.snd) := by
+  cases xs
   simp [List.unzip_eq_map]
 
-theorem zip_unzip (l : Array (α × β)) : zip (unzip l).1 (unzip l).2 = l := by
-  cases l
+theorem zip_unzip (xs : Array (α × β)) : zip (unzip xs).1 (unzip xs).2 = xs := by
+  cases xs
   simp only [List.unzip_toArray, Prod.map_fst, Prod.map_snd, List.zip_toArray, List.zip_unzip]
 
-theorem unzip_zip_left {l₁ : Array α} {l₂ : Array β} (h : l₁.size ≤ l₂.size) :
-    (unzip (zip l₁ l₂)).1 = l₁ := by
-  cases l₁
-  cases l₂
+theorem unzip_zip_left {as : Array α} {bs : Array β} (h : as.size ≤ bs.size) :
+    (unzip (zip as bs)).1 = as := by
+  cases as
+  cases bs
   simp_all only [List.size_toArray, List.zip_toArray, List.unzip_toArray, Prod.map_fst,
     List.unzip_zip_left]
 
-theorem unzip_zip_right {l₁ : Array α} {l₂ : Array β} (h : l₂.size ≤ l₁.size) :
-    (unzip (zip l₁ l₂)).2 = l₂ := by
-  cases l₁
-  cases l₂
+theorem unzip_zip_right {as : Array α} {bs : Array β} (h : bs.size ≤ as.size) :
+    (unzip (zip as bs)).2 = bs := by
+  cases as
+  cases bs
   simp_all only [List.size_toArray, List.zip_toArray, List.unzip_toArray, Prod.map_snd,
     List.unzip_zip_right]
 
-theorem unzip_zip {l₁ : Array α} {l₂ : Array β} (h : l₁.size = l₂.size) :
-    unzip (zip l₁ l₂) = (l₁, l₂) := by
-  cases l₁
-  cases l₂
+theorem unzip_zip {as : Array α} {bs : Array β} (h : as.size = bs.size) :
+    unzip (zip as bs) = (as, bs) := by
+  cases as
+  cases bs
   simp_all only [List.size_toArray, List.zip_toArray, List.unzip_toArray, List.unzip_zip, Prod.map_apply]
 
-theorem zip_of_prod {l : Array α} {l' : Array β} {lp : Array (α × β)} (hl : lp.map Prod.fst = l)
-    (hr : lp.map Prod.snd = l') : lp = l.zip l' := by
-  rw [← hl, ← hr, ← zip_unzip lp, ← unzip_fst, ← unzip_snd, zip_unzip, zip_unzip]
+theorem zip_of_prod {as : Array α} {bs : Array β} {xs : Array (α × β)} (hl : xs.map Prod.fst = as)
+    (hr : xs.map Prod.snd = bs) : xs = as.zip bs := by
+  rw [← hl, ← hr, ← zip_unzip xs, ← unzip_fst, ← unzip_snd, zip_unzip, zip_unzip]
 
-@[simp] theorem unzip_mkArray {n : Nat} {a : α} {b : β} :
-    unzip (mkArray n (a, b)) = (mkArray n a, mkArray n b) := by
+@[simp] theorem unzip_replicate {n : Nat} {a : α} {b : β} :
+    unzip (replicate n (a, b)) = (replicate n a, replicate n b) := by
   ext1 <;> simp
+
+@[deprecated unzip_replicate (since := "2025-03-18")]
+abbrev unzip_mkArray := @unzip_replicate

src/Init/Data/BEq.lean

@@ -25,7 +25,7 @@ class ReflBEq (α) [BEq α] : Prop where
   refl : (a : α) == a
 
 /-- `EquivBEq` says that the `BEq` implementation is an equivalence relation. -/
-class EquivBEq (α) [BEq α] extends PartialEquivBEq α, ReflBEq α : Prop
+class EquivBEq (α) [BEq α] : Prop extends PartialEquivBEq α, ReflBEq α
 
 @[simp]
 theorem BEq.refl [BEq α] [ReflBEq α] {a : α} : a == a :=
@@ -49,6 +49,14 @@ theorem BEq.symm_false [BEq α] [PartialEquivBEq α] {a b : α} : (a == b) = fal
 theorem BEq.trans [BEq α] [PartialEquivBEq α] {a b c : α} : a == b → b == c → a == c :=
   PartialEquivBEq.trans
 
+theorem BEq.congr_left [BEq α] [PartialEquivBEq α] {a b c : α} (h : a == b) :
+    (a == c) = (b == c) :=
+  Bool.eq_iff_iff.mpr ⟨BEq.trans (BEq.symm h), BEq.trans h⟩
+
+theorem BEq.congr_right [BEq α] [PartialEquivBEq α] {a b c : α} (h : b == c) :
+    (a == b) = (a == c) :=
+  Bool.eq_iff_iff.mpr ⟨fun h' => BEq.trans h' h, fun h' => BEq.trans h' (BEq.symm h)⟩
+
 theorem BEq.neq_of_neq_of_beq [BEq α] [PartialEquivBEq α] {a b c : α} :
     (a == b) = false → b == c → (a == c) = false :=
   fun h₁ h₂ => Bool.eq_false_iff.2 fun h₃ => Bool.eq_false_iff.1 h₁ (BEq.trans h₃ (BEq.symm h₂))

src/Init/Data/BitVec/Basic.lean

@@ -18,7 +18,7 @@ operations on `Fin` are already defined. Some other possible representations are
 
 We define many of the bitvector operations from the
 [`QF_BV` logic](https://smtlib.cs.uiowa.edu/logics-all.shtml#QF_BV).
-of SMT-LIBv2.
+of SMT-LIB v2.
 -/
 
 set_option linter.missingDocs true
@@ -96,16 +96,10 @@ This will be renamed `getMsb` after the existing deprecated alias is removed.
 @[inline] def getLsbD (x : BitVec w) (i : Nat) : Bool :=
   x.toNat.testBit i
 
-@[deprecated getLsbD (since := "2024-08-29"), inherit_doc getLsbD]
-def getLsb (x : BitVec w) (i : Nat) : Bool := x.getLsbD i
-
 /-- Return the `i`-th most significant bit or `false` if `i ≥ w`. -/
 @[inline] def getMsbD (x : BitVec w) (i : Nat) : Bool :=
   i < w && x.getLsbD (w-1-i)
 
-@[deprecated getMsbD (since := "2024-08-29"), inherit_doc getMsbD]
-def getMsb (x : BitVec w) (i : Nat) : Bool := x.getMsbD i
-
 /-- Return most-significant bit in bitvector. -/
 @[inline] protected def msb (x : BitVec n) : Bool := getMsbD x 0
 
@@ -202,7 +196,7 @@ section arithmetic
 Negation for bit vectors. This can be interpreted as either signed or unsigned negation
 modulo `2^n`.
 
-SMT-Lib name: `bvneg`.
+SMT-LIB name: `bvneg`.
 -/
 protected def neg (x : BitVec n) : BitVec n := .ofNat n (2^n - x.toNat)
 instance : Neg (BitVec n) := ⟨.neg⟩
@@ -216,7 +210,7 @@ protected def abs (x : BitVec n) : BitVec n := if x.msb then .neg x else x
 Multiplication for bit vectors. This can be interpreted as either signed or unsigned
 multiplication modulo `2^n`.
 
-SMT-Lib name: `bvmul`.
+SMT-LIB name: `bvmul`.
 -/
 protected def mul (x y : BitVec n) : BitVec n := BitVec.ofNat n (x.toNat * y.toNat)
 instance : Mul (BitVec n) := ⟨.mul⟩
@@ -231,7 +225,7 @@ instance : Div (BitVec n) := ⟨.udiv⟩
 /--
 Unsigned modulo for bit vectors.
 
-SMT-Lib name: `bvurem`.
+SMT-LIB name: `bvurem`.
 -/
 def umod (x y : BitVec n) : BitVec n :=
   (x.toNat % y.toNat)#'(Nat.lt_of_le_of_lt (Nat.mod_le _ _) x.isLt)
@@ -239,10 +233,10 @@ instance : Mod (BitVec n) := ⟨.umod⟩
 
 /--
 Unsigned division for bit vectors using the
-[SMT-Lib convention](http://smtlib.cs.uiowa.edu/theories-FixedSizeBitVectors.shtml)
+[SMT-LIB convention](http://smtlib.cs.uiowa.edu/theories-FixedSizeBitVectors.shtml)
 where division by zero returns the `allOnes` bitvector.
 
-SMT-Lib name: `bvudiv`.
+SMT-LIB name: `bvudiv`.
 -/
 def smtUDiv (x y : BitVec n) : BitVec n := if y = 0 then allOnes n else udiv x y
 
@@ -265,11 +259,11 @@ def sdiv (x y : BitVec n) : BitVec n :=
   | true,  true  => udiv (.neg x) (.neg y)
 
 /--
-Signed division for bit vectors using SMTLIB rules for division by zero.
+Signed division for bit vectors using SMT-LIB rules for division by zero.
 
 Specifically, `smtSDiv x 0 = if x >= 0 then -1 else 1`
 
-SMT-Lib name: `bvsdiv`.
+SMT-LIB name: `bvsdiv`.
 -/
 def smtSDiv (x y : BitVec n) : BitVec n :=
   match x.msb, y.msb with
@@ -281,7 +275,7 @@ def smtSDiv (x y : BitVec n) : BitVec n :=
 /--
 Remainder for signed division rounding to zero.
 
-SMT_Lib name: `bvsrem`.
+SMT-LIB name: `bvsrem`.
 -/
 def srem (x y : BitVec n) : BitVec n :=
   match x.msb, y.msb with
@@ -293,7 +287,7 @@ def srem (x y : BitVec n) : BitVec n :=
 /--
 Remainder for signed division rounded to negative infinity.
 
-SMT_Lib name: `bvsmod`.
+SMT-LIB name: `bvsmod`.
 -/
 def smod (x y : BitVec m) : BitVec m :=
   match x.msb, y.msb with
@@ -327,14 +321,14 @@ section relations
 /--
 Unsigned less-than for bit vectors.
 
-SMT-Lib name: `bvult`.
+SMT-LIB name: `bvult`.
 -/
 protected def ult (x y : BitVec n) : Bool := x.toNat < y.toNat
 
 /--
 Unsigned less-than-or-equal-to for bit vectors.
 
-SMT-Lib name: `bvule`.
+SMT-LIB name: `bvule`.
 -/
 protected def ule (x y : BitVec n) : Bool := x.toNat ≤ y.toNat
 
@@ -345,14 +339,14 @@ Signed less-than for bit vectors.
 BitVec.slt 6#4 7 = true
 BitVec.slt 7#4 8 = false
 ```
-SMT-Lib name: `bvslt`.
+SMT-LIB name: `bvslt`.
 -/
 protected def slt (x y : BitVec n) : Bool := x.toInt < y.toInt
 
 /--
 Signed less-than-or-equal-to for bit vectors.
 
-SMT-Lib name: `bvsle`.
+SMT-LIB name: `bvsle`.
 -/
 protected def sle (x y : BitVec n) : Bool := x.toInt ≤ y.toInt
 
@@ -384,7 +378,7 @@ def extractLsb' (start len : Nat) (x : BitVec n) : BitVec len := .ofNat _ (x.toN
 Extraction of bits `hi` (inclusive) down to `lo` (inclusive) from a bit vector of size `n` to
 yield a new bitvector of size `hi - lo + 1`.
 
-SMT-Lib name: `extract`.
+SMT-LIB name: `extract`.
 -/
 def extractLsb (hi lo : Nat) (x : BitVec n) : BitVec (hi - lo + 1) := extractLsb' lo _ x
 
@@ -415,7 +409,7 @@ Transform `x` of length `w` into a bitvector of length `v`, by either:
 - zero extending, that is, adding zeros in the high bits until it has length `v`, if `v > w`, or
 - truncating the high bits, if `v < w`.
 
-SMT-Lib name: `zero_extend`.
+SMT-LIB name: `zero_extend`.
 -/
 def setWidth (v : Nat) (x : BitVec w) : BitVec v :=
   if h : w ≤ v then
@@ -428,7 +422,7 @@ Transform `x` of length `w` into a bitvector of length `v`, by either:
 - zero extending, that is, adding zeros in the high bits until it has length `v`, if `v > w`, or
 - truncating the high bits, if `v < w`.
 
-SMT-Lib name: `zero_extend`.
+SMT-LIB name: `zero_extend`.
 -/
 abbrev zeroExtend := @setWidth
 
@@ -437,7 +431,7 @@ Transform `x` of length `w` into a bitvector of length `v`, by either:
 - zero extending, that is, adding zeros in the high bits until it has length `v`, if `v > w`, or
 - truncating the high bits, if `v < w`.
 
-SMT-Lib name: `zero_extend`.
+SMT-LIB name: `zero_extend`.
 -/
 abbrev truncate := @setWidth
 
@@ -445,7 +439,7 @@ abbrev truncate := @setWidth
 Sign extend a vector of length `w`, extending with `i` additional copies of the most significant
 bit in `x`. If `x` is an empty vector, then the sign is treated as zero.
 
-SMT-Lib name: `sign_extend`.
+SMT-LIB name: `sign_extend`.
 -/
 def signExtend (v : Nat) (x : BitVec w) : BitVec v := .ofInt v x.toInt
 
@@ -460,7 +454,7 @@ Bitwise AND for bit vectors.
 0b1010#4 &&& 0b0110#4 = 0b0010#4
 ```
 
-SMT-Lib name: `bvand`.
+SMT-LIB name: `bvand`.
 -/
 protected def and (x y : BitVec n) : BitVec n :=
   (x.toNat &&& y.toNat)#'(Nat.and_lt_two_pow x.toNat y.isLt)
@@ -473,7 +467,7 @@ Bitwise OR for bit vectors.
 0b1010#4 ||| 0b0110#4 = 0b1110#4
 ```
 
-SMT-Lib name: `bvor`.
+SMT-LIB name: `bvor`.
 -/
 protected def or (x y : BitVec n) : BitVec n :=
   (x.toNat ||| y.toNat)#'(Nat.or_lt_two_pow x.isLt y.isLt)
@@ -486,7 +480,7 @@ instance : OrOp (BitVec w) := ⟨.or⟩
 0b1010#4 ^^^ 0b0110#4 = 0b1100#4
 ```
 
-SMT-Lib name: `bvxor`.
+SMT-LIB name: `bvxor`.
 -/
 protected def xor (x y : BitVec n) : BitVec n :=
   (x.toNat ^^^ y.toNat)#'(Nat.xor_lt_two_pow x.isLt y.isLt)
@@ -498,7 +492,7 @@ Bitwise NOT for bit vectors.
 ```lean
 ~~~(0b0101#4) == 0b1010
 ```
-SMT-Lib name: `bvnot`.
+SMT-LIB name: `bvnot`.
 -/
 protected def not (x : BitVec n) : BitVec n := allOnes n ^^^ x
 instance : Complement (BitVec w) := ⟨.not⟩
@@ -507,7 +501,7 @@ instance : Complement (BitVec w) := ⟨.not⟩
 Left shift for bit vectors. The low bits are filled with zeros. As a numeric operation, this is
 equivalent to `x * 2^s`, modulo `2^n`.
 
-SMT-Lib name: `bvshl` except this operator uses a `Nat` shift value.
+SMT-LIB name: `bvshl` except this operator uses a `Nat` shift value.
 -/
 protected def shiftLeft (x : BitVec n) (s : Nat) : BitVec n := BitVec.ofNat n (x.toNat <<< s)
 instance : HShiftLeft (BitVec w) Nat (BitVec w) := ⟨.shiftLeft⟩
@@ -516,7 +510,7 @@ instance : HShiftLeft (BitVec w) Nat (BitVec w) := ⟨.shiftLeft⟩
 (Logical) right shift for bit vectors. The high bits are filled with zeros.
 As a numeric operation, this is equivalent to `x / 2^s`, rounding down.
 
-SMT-Lib name: `bvlshr` except this operator uses a `Nat` shift value.
+SMT-LIB name: `bvlshr` except this operator uses a `Nat` shift value.
 -/
 def ushiftRight (x : BitVec n) (s : Nat) : BitVec n :=
   (x.toNat >>> s)#'(by
@@ -532,7 +526,7 @@ Arithmetic right shift for bit vectors. The high bits are filled with the
 most-significant bit.
 As a numeric operation, this is equivalent to `x.toInt >>> s`.
 
-SMT-Lib name: `bvashr` except this operator uses a `Nat` shift value.
+SMT-LIB name: `bvashr` except this operator uses a `Nat` shift value.
 -/
 def sshiftRight (x : BitVec n) (s : Nat) : BitVec n := .ofInt n (x.toInt >>> s)
 
@@ -544,7 +538,7 @@ Arithmetic right shift for bit vectors. The high bits are filled with the
 most-significant bit.
 As a numeric operation, this is equivalent to `a.toInt >>> s.toNat`.
 
-SMT-Lib name: `bvashr`.
+SMT-LIB name: `bvashr`.
 -/
 def sshiftRight' (a : BitVec n) (s : BitVec m) : BitVec n := a.sshiftRight s.toNat
 
@@ -560,7 +554,7 @@ bits wrapping around to fill the low bits.
 ```lean
 rotateLeft  0b0011#4 3 = 0b1001
 ```
-SMT-Lib name: `rotate_left` except this operator uses a `Nat` shift amount.
+SMT-LIB name: `rotate_left` except this operator uses a `Nat` shift amount.
 -/
 def rotateLeft (x : BitVec w) (n : Nat) : BitVec w := rotateLeftAux x (n % w)
 
@@ -579,7 +573,7 @@ bottom `n` bits wrapping around to fill the high bits.
 ```lean
 rotateRight 0b01001#5 1 = 0b10100
 ```
-SMT-Lib name: `rotate_right` except this operator uses a `Nat` shift amount.
+SMT-LIB name: `rotate_right` except this operator uses a `Nat` shift amount.
 -/
 def rotateRight (x : BitVec w) (n : Nat) : BitVec w := rotateRightAux x (n % w)
 
@@ -587,7 +581,7 @@ def rotateRight (x : BitVec w) (n : Nat) : BitVec w := rotateRightAux x (n % w)
 Concatenation of bitvectors. This uses the "big endian" convention that the more significant
 input is on the left, so `0xAB#8 ++ 0xCD#8 = 0xABCD#16`.
 
-SMT-Lib name: `concat`.
+SMT-LIB name: `concat`.
 -/
 def append (msbs : BitVec n) (lsbs : BitVec m) : BitVec (n+m) :=
   shiftLeftZeroExtend msbs m ||| setWidth' (Nat.le_add_left m n) lsbs
@@ -684,18 +678,26 @@ def ofBoolListLE : (bs : List Bool) → BitVec bs.length
 
 /-- `uaddOverflow x y` returns `true` if addition of `x` and `y` results in *unsigned* overflow.
 
-  SMT-Lib name: `bvuaddo`.
+  SMT-LIB name: `bvuaddo`.
 -/
 def uaddOverflow {w : Nat} (x y : BitVec w) : Bool := x.toNat + y.toNat ≥ 2 ^ w
 
 /-- `saddOverflow x y` returns `true` if addition of `x` and `y` results in *signed* overflow,
 treating `x` and `y` as 2's complement signed bitvectors.
 
-  SMT-Lib name: `bvsaddo`.
+  SMT-LIB name: `bvsaddo`.
 -/
 def saddOverflow {w : Nat} (x y : BitVec w) : Bool :=
   (x.toInt + y.toInt ≥ 2 ^ (w - 1)) || (x.toInt + y.toInt < - 2 ^ (w - 1))
 
+/-- `negOverflow x` returns `true` if the negation of `x` results in overflow. 
+For a BitVec `x` with width `0 < w`, this only happens if `x = intMin`. 
+
+  SMT-Lib name: `bvnego`.
+-/
+def negOverflow {w : Nat} (x : BitVec w) : Bool :=
+  x.toInt == - 2 ^ (w - 1)
+
 /- ### reverse -/
 
 /-- Reverse the bits in a bitvector. -/

src/Init/Data/BitVec/BasicAux.lean

@@ -35,7 +35,7 @@ section arithmetic
 Addition for bit vectors. This can be interpreted as either signed or unsigned addition
 modulo `2^n`.
 
-SMT-Lib name: `bvadd`.
+SMT-LIB name: `bvadd`.
 -/
 protected def add (x y : BitVec n) : BitVec n := .ofNat n (x.toNat + y.toNat)
 instance : Add (BitVec n) := ⟨BitVec.add⟩

src/Init/Data/BitVec/Bitblast.lean

@@ -91,7 +91,7 @@ First, we prove bitvector lemmas to unfold a high-level operation (such as multi
 into already bitblastable operations (such as addition and left shift).
 We then use these lemmas to prove the correctness of the circuit that `bv_decide` builds.
 
-We use this workflow to implement bitblasting for all SMT-LIB2 operations.
+We use this workflow to implement bitblasting for all SMT-LIB v2 operations.
 
 ## Main results
 * `x + y : BitVec w` is `(adc x y false).2`.
@@ -109,7 +109,12 @@ open Nat Bool
 
 namespace Bool
 
-/-- At least two out of three booleans are true. -/
+/--
+At least two out of three Booleans are true.
+
+This function is typically used to model addition of binary numbers, to combine a carry bit with two
+addend bits.
+-/
 abbrev atLeastTwo (a b c : Bool) : Bool := a && b || a && c || b && c
 
 @[simp] theorem atLeastTwo_false_left  : atLeastTwo false b c = (b && c) := by simp [atLeastTwo]
@@ -478,6 +483,39 @@ theorem msb_neg {w : Nat} {x : BitVec w} :
         case zero => exact hmsb
         case succ => exact getMsbD_x _ hi (by omega)
 
+/-- This is false if `v < w` and `b = intMin`. See also `signExtend_neg_of_ne_intMin`. -/
+@[simp] theorem signExtend_neg_of_le {v w : Nat} (h : w ≤ v) (b : BitVec v) :
+    (-b).signExtend w = -b.signExtend w := by
+  apply BitVec.eq_of_getElem_eq
+  intro i hi
+  simp only [getElem_signExtend, getElem_neg]
+  rw [dif_pos (by omega), dif_pos (by omega)]
+  simp only [getLsbD_signExtend, Bool.and_eq_true, decide_eq_true_eq, Bool.ite_eq_true_distrib,
+    Bool.bne_right_inj, decide_eq_decide]
+  exact ⟨fun ⟨j, hj₁, hj₂⟩ => ⟨j, ⟨hj₁, ⟨by omega, by rwa [if_pos (by omega)]⟩⟩⟩,
+    fun ⟨j, hj₁, hj₂, hj₃⟩ => ⟨j, hj₁, by rwa [if_pos (by omega)] at hj₃⟩⟩
+
+/-- This is false if `v < w` and `b = intMin`. See also `signExtend_neg_of_le`. -/
+@[simp] theorem signExtend_neg_of_ne_intMin {v w : Nat} (b : BitVec v) (hb : b ≠ intMin v) :
+    (-b).signExtend w = -b.signExtend w := by
+  refine (by omega : w ≤ v ∨ v < w).elim (fun h => signExtend_neg_of_le h b) (fun h => ?_)
+  apply BitVec.eq_of_toInt_eq
+  rw [toInt_signExtend_of_le (by omega), toInt_neg_of_ne_intMin hb, toInt_neg_of_ne_intMin,
+    toInt_signExtend_of_le (by omega)]
+  apply ne_of_apply_ne BitVec.toInt
+  rw [toInt_signExtend_of_le (by omega), toInt_intMin_of_pos (by omega)]
+  have := b.le_two_mul_toInt
+  have : -2 ^ w < -2 ^ v := by
+    apply Int.neg_lt_neg
+    norm_cast
+    rwa [Nat.pow_lt_pow_iff_right (by omega)]
+  have : 2 * b.toInt ≠ -2 ^ w := by omega
+  rw [(show w = w - 1 + 1 by omega), Int.pow_succ] at this
+  omega
+
+@[simp] theorem BitVec.setWidth_neg_of_le {x : BitVec v} (h : w ≤ v) : BitVec.setWidth w (-x) = -BitVec.setWidth w x := by
+  simp [← BitVec.signExtend_eq_setWidth_of_le _ h, BitVec.signExtend_neg_of_le h]
+
 /-! ### abs -/
 
 theorem msb_abs {w : Nat} {x : BitVec w} :
@@ -544,6 +582,15 @@ theorem slt_eq_not_carry (x y : BitVec w) :
 theorem sle_eq_not_slt (x y : BitVec w) : x.sle y = !y.slt x := by
   simp only [BitVec.sle, BitVec.slt, ← decide_not, decide_eq_decide]; omega
 
+theorem zero_sle_eq_not_msb {w : Nat} {x : BitVec w} : BitVec.sle 0#w x = !x.msb := by
+  rw [sle_eq_not_slt, BitVec.slt_zero_eq_msb]
+
+theorem zero_sle_iff_msb_eq_false {w : Nat} {x : BitVec w} : BitVec.sle 0#w x ↔ x.msb = false := by
+  simp [zero_sle_eq_not_msb]
+
+theorem toNat_toInt_of_sle {w : Nat} (b : BitVec w) (hb : BitVec.sle 0#w b) : b.toInt.toNat = b.toNat :=
+  toNat_toInt_of_msb b (zero_sle_iff_msb_eq_false.1 hb)
+
 theorem sle_eq_carry (x y : BitVec w) :
     x.sle y = !((x.msb == y.msb).xor (carry w y (~~~x) true)) := by
   rw [sle_eq_not_slt, slt_eq_not_carry, beq_comm]
@@ -907,7 +954,7 @@ The input to the shift subtractor is a legal input to `divrem`, and we also need
 input bit to perform shift subtraction on, and thus we need `0 < wn`.
 -/
 structure DivModState.Poised {w : Nat} (args : DivModArgs w) (qr : DivModState w)
-  extends DivModState.Lawful args qr : Type where
+  extends DivModState.Lawful args qr where
   /-- Only perform a round of shift-subtract if we have dividend bits. -/
   hwn_lt : 0 < qr.wn
 
@@ -1034,11 +1081,10 @@ theorem divRec_succ (m : Nat) (args : DivModArgs w) (qr : DivModState w) :
 theorem lawful_divRec {args : DivModArgs w} {qr : DivModState w}
     (h : DivModState.Lawful args qr) :
     DivModState.Lawful args (divRec qr.wn args qr) := by
-  generalize hm : qr.wn = m
-  induction m generalizing qr
-  case zero =>
+  induction hm : qr.wn generalizing qr with
+  | zero =>
     exact h
-  case succ wn' ih =>
+  | succ wn' ih =>
     simp only [divRec_succ]
     apply ih
     · apply lawful_divSubtractShift
@@ -1052,11 +1098,10 @@ theorem lawful_divRec {args : DivModArgs w} {qr : DivModState w}
 @[simp]
 theorem wn_divRec (args : DivModArgs w) (qr : DivModState w) :
     (divRec qr.wn args qr).wn = 0 := by
-  generalize hm : qr.wn = m
-  induction m generalizing qr
-  case zero =>
+  induction hm : qr.wn generalizing qr with
+  | zero =>
     assumption
-  case succ wn' ih =>
+  | succ wn' ih =>
     apply ih
     simp only [divSubtractShift, hm]
     split <;> rfl
@@ -1246,14 +1291,23 @@ theorem saddOverflow_eq {w : Nat} (x y : BitVec w) :
   simp only [saddOverflow]
   rcases w with _|w
   · revert x y; decide
-  · have := le_toInt (x := x); have := toInt_lt (x := x)
-    have := le_toInt (x := y); have := toInt_lt (x := y)
+  · have := le_two_mul_toInt (x := x); have := two_mul_toInt_lt (x := x)
+    have := le_two_mul_toInt (x := y); have := two_mul_toInt_lt (x := y)
     simp only [← decide_or, msb_eq_toInt, decide_beq_decide, toInt_add, ← decide_not, ← decide_and,
       decide_eq_decide]
     rw_mod_cast [Int.bmod_neg_iff (by omega) (by omega)]
     simp
     omega
 
+theorem negOverflow_eq {w : Nat} (x : BitVec w) :
+    (negOverflow x) = (decide (0 < w) && (x == intMin w)) := by
+  simp only [negOverflow]
+  rcases w with _|w
+  · simp [toInt_of_zero_length, Int.min_eq_right]
+  · suffices - 2 ^ w = (intMin (w + 1)).toInt by simp [beq_eq_decide_eq, ← toInt_inj, this]
+    simp only [toInt_intMin, Nat.add_one_sub_one, Int.ofNat_emod, Int.neg_inj]
+    rw_mod_cast [Nat.mod_eq_of_lt (by simp [Nat.pow_lt_pow_succ])]
+
 /- ### umod -/
 
 theorem getElem_umod {n d : BitVec w} (hi : i < w) :
@@ -1296,4 +1350,53 @@ theorem eq_iff_eq_of_inv (f : α → BitVec w) (g : BitVec w → α) (h : ∀ x,
     have := congrArg g h'
     simpa [h] using this
 
+/-! ### Lemmas that use Bitblasting circuits -/
+
+theorem add_sub_comm {x y : BitVec w} : x + y - z = x - z + y := by
+  apply eq_of_toNat_eq
+  simp only [toNat_sub, toNat_add, add_mod_mod, mod_add_mod]
+  congr 1
+  omega
+
+theorem sub_add_comm {x y : BitVec w} : x - y + z = x + z - y := by
+  rw [add_sub_comm]
+
+theorem not_add_one {x : BitVec w} : ~~~ (x + 1#w) = ~~~ x - 1#w := by
+  rw [not_eq_neg_add, not_eq_neg_add, neg_add]
+
+theorem not_add_eq_not_neg {x y : BitVec w} : ~~~ (x + y) = ~~~ x - y := by
+  rw [not_eq_neg_add, not_eq_neg_add, neg_add]
+  simp only [sub_toAdd]
+  rw [BitVec.add_assoc, @BitVec.add_comm _ (-y), ← BitVec.add_assoc]
+
+theorem not_sub_one_eq_not_add_one {x : BitVec w} : ~~~ (x - 1#w) = ~~~ x + 1#w := by
+  rw [not_eq_neg_add, not_eq_neg_add, neg_sub,
+    BitVec.add_sub_cancel, BitVec.sub_add_cancel]
+
+theorem not_sub_eq_not_add {x y : BitVec w} : ~~~ (x - y) = ~~~ x + y := by
+  rw [BitVec.sub_toAdd, not_add_eq_not_neg, sub_neg]
+
+/-- The value of `(carry i x y false)` can be computed by truncating `x` and `y`
+to `len` bits where `len ≥ i`. -/
+theorem carry_extractLsb'_eq_carry {w i len : Nat} (hi : i < len)
+    {x y : BitVec w} {b : Bool}: 
+    (carry i (extractLsb' 0 len x) (extractLsb' 0 len y) b)
+    = (carry i x y b) := by
+  simp only [carry, extractLsb'_toNat, shiftRight_zero, toNat_false, Nat.add_zero, ge_iff_le,
+    decide_eq_decide]
+  have : 2 ^ i ∣ 2^len := by
+    apply Nat.pow_dvd_pow
+    omega
+  rw [Nat.mod_mod_of_dvd _ this, Nat.mod_mod_of_dvd _ this]
+
+/--
+The `[0..len)` low bits of `x + y` can be computed by truncating `x` and `y`
+to `len` bits and then adding.
+-/
+theorem extractLsb'_add {w len : Nat} {x y : BitVec w} (hlen : len ≤ w) : 
+    (x + y).extractLsb' 0 len = x.extractLsb' 0 len + y.extractLsb' 0 len := by
+  ext i hi
+  rw [getElem_extractLsb', Nat.zero_add, getLsbD_add (by omega)]
+  simp [getElem_add, carry_extractLsb'_eq_carry hi, getElem_extractLsb', Nat.zero_add]
+
 end BitVec

src/Init/Data/Bool.lean

@@ -9,7 +9,19 @@ import Init.NotationExtra
 
 namespace Bool
 
-/-- Boolean exclusive or -/
+/--
+Boolean “exclusive or”. `xor x y` can be written `x ^^ y`.
+
+`x ^^ y` is `true` when precisely one of `x` or `y` is `true`. Unlike `and` and `or`, it does not
+have short-circuiting behavior, because one argument's value never determines the final value. Also
+unlike `and` and `or`, there is no commonly-used corresponding propositional connective.
+
+Examples:
+ * `false ^^ false = false`
+ * `true ^^ false = true`
+ * `false ^^ true = true`
+ * `true ^^ true = false`
+-/
 abbrev xor : Bool → Bool → Bool := bne
 
 @[inherit_doc] infixl:33 " ^^ " => xor
@@ -367,7 +379,9 @@ theorem and_or_inj_left_iff :
 
 /-! ## toNat -/
 
-/-- convert a `Bool` to a `Nat`, `false -> 0`, `true -> 1` -/
+/--
+Converts `true` to `1` and `false` to `0`.
+-/
 def toNat (b : Bool) : Nat := cond b 1 0
 
 @[simp, bitvec_to_nat] theorem toNat_false : false.toNat = 0 := rfl
@@ -388,7 +402,9 @@ theorem toNat_lt (b : Bool) : b.toNat < 2 :=
 
 /-! ## toInt -/
 
-/-- convert a `Bool` to an `Int`, `false -> 0`, `true -> 1` -/
+/--
+Converts `true` to `1` and `false` to `0`.
+-/
 def toInt (b : Bool) : Int := cond b 1 0
 
 @[simp] theorem toInt_false : false.toInt = 0 := rfl
@@ -539,8 +555,8 @@ theorem cond_decide {α} (p : Prop) [Decidable p] (t e : α) :
 @[simp] theorem cond_eq_false_distrib : ∀(c t f : Bool),
     (cond c t f = false) = ite (c = true) (t = false) (f = false) := by decide
 
-protected theorem cond_true  {α : Type u} {a b : α} : cond true  a b = a := cond_true  a b
-protected theorem cond_false {α : Type u} {a b : α} : cond false a b = b := cond_false a b
+protected theorem cond_true  {α : Sort u} {a b : α} : cond true  a b = a := cond_true  a b
+protected theorem cond_false {α : Sort u} {a b : α} : cond false a b = b := cond_false a b
 
 @[simp] theorem cond_true_left   : ∀(c f : Bool), cond c true f  = ( c || f) := by decide
 @[simp] theorem cond_false_left  : ∀(c f : Bool), cond c false f = (!c && f) := by decide

src/Init/Data/ByteArray/Basic.lean

@@ -18,10 +18,13 @@ attribute [extern "lean_byte_array_data"] ByteArray.data
 
 namespace ByteArray
 @[extern "lean_mk_empty_byte_array"]
-def mkEmpty (c : @& Nat) : ByteArray :=
+def emptyWithCapacity (c : @& Nat) : ByteArray :=
   { data := #[] }
 
-def empty : ByteArray := mkEmpty 0
+@[deprecated emptyWithCapacity (since := "2025-03-12")]
+abbrev mkEmpty := emptyWithCapacity
+
+def empty : ByteArray := emptyWithCapacity 0
 
 instance : Inhabited ByteArray where
   default := empty
@@ -334,6 +337,9 @@ def prevn : Iterator → Nat → Iterator
 end Iterator
 end ByteArray
 
+/--
+Converts a list of bytes into a `ByteArray`.
+-/
 def List.toByteArray (bs : List UInt8) : ByteArray :=
   let rec loop
     | [],    r => r

src/Init/Data/Char/Basic.lean

@@ -15,7 +15,15 @@ Note that values in `[0xd800, 0xdfff]` are reserved for [UTF-16 surrogate pairs]
 
 namespace Char
 
+/--
+One character is less than another if its code point is strictly less than the other's.
+-/
 protected def lt (a b : Char) : Prop := a.val < b.val
+
+/--
+One character is less than or equal to another if its code point is less than or equal to the
+other's.
+-/
 protected def le (a b : Char) : Prop := a.val ≤ b.val
 
 instance : LT Char := ⟨Char.lt⟩
@@ -27,7 +35,10 @@ instance (a b : Char) :  Decidable (a < b) :=
 instance (a b : Char) : Decidable (a ≤ b) :=
   UInt32.decLe _ _
 
-/-- Determines if the given nat is a valid [Unicode scalar value](https://www.unicode.org/glossary/#unicode_scalar_value).-/
+/--
+True for natural numbers that are valid [Unicode scalar
+values](https://www.unicode.org/glossary/#unicode_scalar_value).
+-/
 abbrev isValidCharNat (n : Nat) : Prop :=
   n < 0xd800 ∨ (0xdfff < n ∧ n < 0x110000)
 
@@ -50,55 +61,93 @@ theorem isValidChar_of_isValidCharNat (n : Nat) (h : isValidCharNat n) : isValid
 theorem isValidChar_zero : isValidChar 0 :=
   Or.inl (by decide)
 
-/-- Underlying unicode code point as a `Nat`. -/
+/--
+The character's Unicode code point as a `Nat`.
+-/
 @[inline] def toNat (c : Char) : Nat :=
   c.val.toNat
 
-/-- Convert a character into a `UInt8`, by truncating (reducing modulo 256) if necessary. -/
+/--
+Converts a character into a `UInt8` that contains its code point.
+
+If the code point is larger than 255, it is truncated (reduced modulo 256).
+-/
 @[inline] def toUInt8 (c : Char) : UInt8 :=
   c.val.toUInt8
 
-/-- The numbers from 0 to 256 are all valid UTF-8 characters, so we can embed one in the other. -/
+/--
+Converts an 8-bit unsigned integer into a character.
+
+The integer's value is interpreted as a Unicode code point.
+-/
 def ofUInt8 (n : UInt8) : Char := ⟨n.toUInt32, .inl (Nat.lt_trans n.toBitVec.isLt (by decide))⟩
 
 instance : Inhabited Char where
   default := 'A'
 
-/-- Is the character a space (U+0020) a tab (U+0009), a carriage return (U+000D) or a newline (U+000A)? -/
+/--
+Returns `true` if the character is a space `(' ', U+0020)`, a tab `('\t', U+0009)`, a carriage
+return `('\r', U+000D)`, or a newline `('\n', U+000A)`.
+-/
 @[inline] def isWhitespace (c : Char) : Bool :=
   c = ' ' || c = '\t' || c = '\r' || c = '\n'
 
-/-- Is the character in `ABCDEFGHIJKLMNOPQRSTUVWXYZ`? -/
+/--
+Returns `true` if the character is a uppercase ASCII letter.
+
+The uppercase ASCII letters are the following: `ABCDEFGHIJKLMNOPQRSTUVWXYZ`.
+-/
 @[inline] def isUpper (c : Char) : Bool :=
   c.val ≥ 65 && c.val ≤ 90
 
-/-- Is the character in `abcdefghijklmnopqrstuvwxyz`? -/
+/--
+Returns `true` if the character is a lowercase ASCII letter.
+
+The lowercase ASCII letters are the following: `abcdefghijklmnopqrstuvwxyz`.
+-/
 @[inline] def isLower (c : Char) : Bool :=
   c.val ≥ 97 && c.val ≤ 122
 
-/-- Is the character in `ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz`? -/
+/--
+Returns `true` if the character is an ASCII letter.
+
+The ASCII letters are the following: `ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz`.
+-/
 @[inline] def isAlpha (c : Char) : Bool :=
   c.isUpper || c.isLower
 
-/-- Is the character in `0123456789`? -/
+/--
+Returns `true` if the character is an ASCII digit.
+
+The ASCII digits are the following: `0123456789`.
+-/
 @[inline] def isDigit (c : Char) : Bool :=
   c.val ≥ 48 && c.val ≤ 57
 
-/-- Is the character in `ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789`? -/
+/--
+Returns `true` if the character is an ASCII letter or digit.
+
+The ASCII letters are the following: `ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz`.
+The ASCII digits are the following: `0123456789`.
+-/
 @[inline] def isAlphanum (c : Char) : Bool :=
   c.isAlpha || c.isDigit
 
-/-- Convert an upper case character to its lower case character.
+/--
+Converts an uppercase ASCII letter to the corresponding lowercase letter. Letters outside the ASCII
+alphabet are returned unchanged.
 
-Only works on basic latin letters.
+The uppercase ASCII letters are the following: `ABCDEFGHIJKLMNOPQRSTUVWXYZ`.
 -/
 def toLower (c : Char) : Char :=
   let n := toNat c;
   if n >= 65 ∧ n <= 90 then ofNat (n + 32) else c
 
-/-- Convert a lower case character to its upper case character.
+/--
+Converts a lowercase ASCII letter to the corresponding uppercase letter. Letters outside the ASCII
+alphabet are returned unchanged.
 
-Only works on basic latin letters.
+The lowercase ASCII letters are the following: `abcdefghijklmnopqrstuvwxyz`.
 -/
 def toUpper (c : Char) : Char :=
   let n := toNat c;

src/Init/Data/Fin/Basic.lean

@@ -14,22 +14,23 @@ instance coeToNat : CoeOut (Fin n) Nat :=
   ⟨fun v => v.val⟩
 
 /--
-From the empty type `Fin 0`, any desired result `α` can be derived. This is similar to `Empty.elim`.
+The type `Fin 0` is uninhabited, so it can be used to derive any result whatsoever.
+
+This is similar to `Empty.elim`. It can be thought of as a compiler-checked assertion that a code
+path is unreachable, or a logical contradiction from which `False` and thus anything else could be
+derived.
 -/
 def elim0.{u} {α : Sort u} : Fin 0 → α
   | ⟨_, h⟩ => absurd h (not_lt_zero _)
 
 /--
-Returns the successor of the argument.
+The successor, with an increased bound.
 
-The bound in the result type is increased:
-```
-(2 : Fin 3).succ = (3 : Fin 4)
-```
-This differs from addition, which wraps around:
-```
-(2 : Fin 3) + 1 = (0 : Fin 3)
-```
+This differs from adding `1`, which instead wraps around.
+
+Examples:
+ * `(2 : Fin 3).succ = (3 : Fin 4)`
+ * `(2 : Fin 3) + 1 = (0 : Fin 3)`
 -/
 def succ : Fin n → Fin (n + 1)
   | ⟨i, h⟩ => ⟨i+1, Nat.succ_lt_succ h⟩
@@ -53,7 +54,13 @@ protected def ofNat {n : Nat} (a : Nat) : Fin (n + 1) :=
 
 -- We provide this because other similar types have a `toNat` function, but `simp` rewrites
 -- `i.toNat` to `i.val`.
-@[inline, inherit_doc val]
+/--
+Extracts the underlying `Nat` value.
+
+This function is a synonym for `Fin.val`, which is the simp normal form. `Fin.val` is also a
+coercion, so values of type `Fin n` are automatically converted to `Nat`s as needed.
+-/
+@[inline]
 protected def toNat (i : Fin n) : Nat :=
   i.val
 
@@ -65,15 +72,34 @@ private theorem mlt {b : Nat} : {a : Nat} → a < n → b % n < n
     have : n > 0 := Nat.lt_trans (Nat.zero_lt_succ _) h;
     Nat.mod_lt _ this
 
-/-- Addition modulo `n` -/
+/--
+Addition modulo `n`, usually invoked via the `+` operator.
+
+Examples:
+ * `(2 : Fin 8) + (2 : Fin 8) = (4 : Fin 8)`
+ * `(2 : Fin 3) + (2 : Fin 3) = (1 : Fin 3)`
+-/
 protected def add : Fin n → Fin n → Fin n
   | ⟨a, h⟩, ⟨b, _⟩ => ⟨(a + b) % n, mlt h⟩
 
-/-- Multiplication modulo `n` -/
+/--
+Multiplication modulo `n`, usually invoked via the `*` operator.
+
+Examples:
+ * `(2 : Fin 10) * (2 : Fin 10) = (4 : Fin 10)`
+ * `(2 : Fin 10) * (7 : Fin 10) = (4 : Fin 10)`
+ * `(3 : Fin 10) * (7 : Fin 10) = (1 : Fin 10)`
+-/
 protected def mul : Fin n → Fin n → Fin n
   | ⟨a, h⟩, ⟨b, _⟩ => ⟨(a * b) % n, mlt h⟩
 
-/-- Subtraction modulo `n` -/
+/--
+Subtraction modulo `n`, usually invoked via the `-` operator.
+
+Examples:
+ * `(5 : Fin 11) - (3 : Fin 11) = (2 : Fin 11)`
+ * `(3 : Fin 11) - (5 : Fin 11) = (9 : Fin 11)`
+-/
 protected def sub : Fin n → Fin n → Fin n
   /-
   The definition of `Fin.sub` has been updated to improve performance.
@@ -100,27 +126,76 @@ we are trying to minimize the number of Nat theorems
 needed to bootstrap Lean.
 -/
 
+/--
+Modulus of bounded numbers, usually invoked via the `%` operator.
+
+The resulting value is that computed by the `%` operator on `Nat`.
+-/
 protected def mod : Fin n → Fin n → Fin n
   | ⟨a, h⟩, ⟨b, _⟩ => ⟨a % b,  Nat.lt_of_le_of_lt (Nat.mod_le _ _) h⟩
 
+/--
+Division of bounded numbers, usually invoked via the `/` operator.
+
+The resulting value is that computed by the `/` operator on `Nat`. In particular, the result of
+division by `0` is `0`.
+
+Examples:
+ * `(5 : Fin 10) / (2 : Fin 10) = (2 : Fin 10)`
+ * `(5 : Fin 10) / (0 : Fin 10) = (0 : Fin 10)`
+ * `(5 : Fin 10) / (7 : Fin 10) = (0 : Fin 10)`
+-/
 protected def div : Fin n → Fin n → Fin n
   | ⟨a, h⟩, ⟨b, _⟩ => ⟨a / b, Nat.lt_of_le_of_lt (Nat.div_le_self _ _) h⟩
 
+/--
+Modulus of bounded numbers with respect to a `Nat`.
+
+The resulting value is that computed by the `%` operator on `Nat`.
+-/
 def modn : Fin n → Nat → Fin n
   | ⟨a, h⟩, m => ⟨a % m, Nat.lt_of_le_of_lt (Nat.mod_le _ _) h⟩
 
+/--
+Bitwise and.
+-/
 def land : Fin n → Fin n → Fin n
   | ⟨a, h⟩, ⟨b, _⟩ => ⟨(Nat.land a b) % n, mlt h⟩
 
+/--
+Bitwise or.
+-/
 def lor : Fin n → Fin n → Fin n
   | ⟨a, h⟩, ⟨b, _⟩ => ⟨(Nat.lor a b) % n, mlt h⟩
 
+/--
+Bitwise xor (“exclusive or”).
+-/
 def xor : Fin n → Fin n → Fin n
   | ⟨a, h⟩, ⟨b, _⟩ => ⟨(Nat.xor a b) % n, mlt h⟩
 
+/--
+Bitwise left shift of bounded numbers, with wraparound on overflow.
+
+Examples:
+ * `(1 : Fin 10) <<< (1 : Fin 10) = (2 : Fin 10)`
+ * `(1 : Fin 10) <<< (3 : Fin 10) = (8 : Fin 10)`
+ * `(1 : Fin 10) <<< (4 : Fin 10) = (6 : Fin 10)`
+-/
 def shiftLeft : Fin n → Fin n → Fin n
   | ⟨a, h⟩, ⟨b, _⟩ => ⟨(a <<< b) % n, mlt h⟩
 
+/--
+Bitwise right shift of bounded numbers.
+
+This operator corresponds to logical rather than arithmetic bit shifting. The new bits are always
+`0`.
+
+Examples:
+ * `(15 : Fin 16) >>> (1 : Fin 16) = (7 : Fin 16)`
+ * `(15 : Fin 16) >>> (2 : Fin 16) = (3 : Fin 16)`
+ * `(15 : Fin 17) >>> (2 : Fin 17) = (3 : Fin 17)`
+-/
 def shiftRight : Fin n → Fin n → Fin n
   | ⟨a, h⟩, ⟨b, _⟩ => ⟨(a >>> b) % n, mlt h⟩
 
@@ -174,39 +249,125 @@ theorem val_lt_of_le (i : Fin b) (h : b ≤ n) : i.val < n :=
 protected theorem pos (i : Fin n) : 0 < n :=
   Nat.lt_of_le_of_lt (Nat.zero_le _) i.2
 
-/-- The greatest value of `Fin (n+1)`. -/
+/--
+The greatest value of `Fin (n+1)`, namely `n`.
+
+Examples:
+ * `Fin.last 4 = (4 : Fin 5)`
+ * `(Fin.last 0).val = (0 : Nat)`
+-/
 @[inline] def last (n : Nat) : Fin (n + 1) := ⟨n, n.lt_succ_self⟩
 
-/-- `castLT i h` embeds `i` into a `Fin` where `h` proves it belongs into.  -/
+/--
+Replaces the bound with another that is suitable for the value.
+
+The proof embedded in `i` can be used to cast to a larger bound even if the concrete value is not
+known.
+
+Examples:
+```lean example
+example : Fin 12 := (7 : Fin 10).castLT (by decide : 7 < 12)
+```
+```lean example
+example (i : Fin 10) : Fin 12 :=
+  i.castLT <| by
+    cases i; simp; omega
+```
+-/
 @[inline] def castLT (i : Fin m) (h : i.1 < n) : Fin n := ⟨i.1, h⟩
 
-/-- `castLE h i` embeds `i` into a larger `Fin` type.  -/
+/--
+Coarsens a bound to one at least as large.
+
+See also `Fin.castAdd` for a version that represents the larger bound with addition rather than an
+explicit inequality proof.
+-/
 @[inline] def castLE (h : n ≤ m) (i : Fin n) : Fin m := ⟨i, Nat.lt_of_lt_of_le i.2 h⟩
 
-/-- `cast eq i` embeds `i` into an equal `Fin` type. -/
+/--
+Uses a proof that two bounds are equal to allow a value bounded by one to be used with the other.
+
+In other words, when `eq : n = m`, `Fin.cast eq i` converts `i : Fin n` into a `Fin m`.
+-/
 @[inline] protected def cast (eq : n = m) (i : Fin n) : Fin m := ⟨i, eq ▸ i.2⟩
 
-/-- `castAdd m i` embeds `i : Fin n` in `Fin (n+m)`. See also `Fin.natAdd` and `Fin.addNat`. -/
+/--
+Coarsens a bound to one at least as large.
+
+See also `Fin.natAdd` and `Fin.addNat` for addition functions that increase the bound, and
+`Fin.castLE` for a version that uses an explicit inequality proof.
+-/
 @[inline] def castAdd (m) : Fin n → Fin (n + m) :=
   castLE <| Nat.le_add_right n m
 
-/-- `castSucc i` embeds `i : Fin n` in `Fin (n+1)`. -/
+/--
+Coarsens a bound by one.
+-/
 @[inline] def castSucc : Fin n → Fin (n + 1) := castAdd 1
 
-/-- `addNat m i` adds `m` to `i`, generalizes `Fin.succ`. -/
+/--
+Adds a natural number to a `Fin`, increasing the bound.
+
+This is a generalization of `Fin.succ`.
+
+`Fin.natAdd` is a version of this function that takes its `Nat` parameter first.
+
+Examples:
+ * `Fin.addNat (5 : Fin 8) 3 = (8 : Fin 11)`
+ * `Fin.addNat (0 : Fin 8) 1 = (1 : Fin 9)`
+ * `Fin.addNat (1 : Fin 8) 2 = (3 : Fin 10)`
+
+-/
 def addNat (i : Fin n) (m) : Fin (n + m) := ⟨i + m, Nat.add_lt_add_right i.2 _⟩
 
-/-- `natAdd n i` adds `n` to `i` "on the left". -/
+/--
+Adds a natural number to a `Fin`, increasing the bound.
+
+This is a generalization of `Fin.succ`.
+
+`Fin.addNat` is a version of this function that takes its `Nat` parameter second.
+
+Examples:
+ * `Fin.natAdd 3 (5 : Fin 8) = (8 : Fin 11)`
+ * `Fin.natAdd 1 (0 : Fin 8) = (1 : Fin 9)`
+ * `Fin.natAdd 1 (2 : Fin 8) = (3 : Fin 9)`
+-/
 def natAdd (n) (i : Fin m) : Fin (n + m) := ⟨n + i, Nat.add_lt_add_left i.2 _⟩
 
-/-- Maps `0` to `n-1`, `1` to `n-2`, ..., `n-1` to `0`. -/
+/--
+Replaces a value with its difference from the largest value in the type.
+
+Considering the values of `Fin n` as a sequence `0`, `1`, …, `n-2`, `n-1`, `Fin.rev` finds the
+corresponding element of the reversed sequence. In other words, it maps `0` to `n-1`, `1` to `n-2`,
+..., and `n-1` to `0`.
+
+Examples:
+ * `(5 : Fin 6).rev = (0 : Fin 6)`
+ * `(0 : Fin 6).rev = (5 : Fin 6)`
+ * `(2 : Fin 5).rev = (2 : Fin 5)`
+-/
 @[inline] def rev (i : Fin n) : Fin n := ⟨n - (i + 1), Nat.sub_lt i.pos (Nat.succ_pos _)⟩
 
-/-- `subNat i h` subtracts `m` from `i`, generalizes `Fin.pred`. -/
+/--
+Subtraction of a natural number from a `Fin`, with the bound narrowed.
+
+This is a generalization of `Fin.pred`. It is guaranteed to not underflow or wrap around.
+
+Examples:
+ * `(5 : Fin 9).subNat 2 (by decide) = (3 : Fin 7)`
+ * `(5 : Fin 9).subNat 0 (by decide) = (5 : Fin 9)`
+ * `(3 : Fin 9).subNat 3 (by decide) = (0 : Fin 6)`
+-/
 @[inline] def subNat (m) (i : Fin (n + m)) (h : m ≤ i) : Fin n :=
   ⟨i - m, Nat.sub_lt_right_of_lt_add h i.2⟩
 
-/-- Predecessor of a nonzero element of `Fin (n+1)`. -/
+/--
+The predecessor of a non-zero element of `Fin (n+1)`, with the bound decreased.
+
+Examples:
+ * `(4 : Fin 8).pred (by decide) = (3 : Fin 7)`
+ * `(1 : Fin 2).pred (by decide) = (0 : Fin 1)`
+-/
 @[inline] def pred {n : Nat} (i : Fin (n + 1)) (h : i ≠ 0) : Fin n :=
   subNat 1 i <| Nat.pos_of_ne_zero <| mt (Fin.eq_of_val_eq (j := 0)) h
 

src/Init/Data/Fin/Bitwise.lean

@@ -12,4 +12,31 @@ namespace Fin
 @[simp] theorem and_val (a b : Fin n) : (a &&& b).val = a.val &&& b.val :=
   Nat.mod_eq_of_lt (Nat.lt_of_le_of_lt Nat.and_le_left a.isLt)
 
+@[simp] theorem or_val_of_two_pow {w} (a b : Fin (2 ^ w)) : (a ||| b).val = a.val ||| b.val :=
+  Nat.mod_eq_of_lt (Nat.or_lt_two_pow a.isLt b.isLt)
+
+@[simp] theorem or_val_of_uInt8Size (a b : Fin UInt8.size) : (a ||| b).val = a.val ||| b.val := or_val_of_two_pow (w := 8) a b
+@[simp] theorem or_val_of_uInt16Size (a b : Fin UInt16.size) : (a ||| b).val = a.val ||| b.val := or_val_of_two_pow (w := 16) a b
+@[simp] theorem or_val_of_uInt32Size (a b : Fin UInt32.size) : (a ||| b).val = a.val ||| b.val := or_val_of_two_pow (w := 32) a b
+@[simp] theorem or_val_of_uInt64Size (a b : Fin UInt64.size) : (a ||| b).val = a.val ||| b.val := or_val_of_two_pow (w := 64) a b
+@[simp] theorem or_val_of_uSizeSize (a b : Fin USize.size) : (a ||| b).val = a.val ||| b.val := or_val_of_two_pow a b
+
+theorem or_val (a b : Fin n) : (a ||| b).val = (a.val ||| b.val) % n := rfl
+
+@[simp] theorem xor_val_of_two_pow {w} (a b : Fin (2 ^ w)) : (a ^^^ b).val = a.val ^^^ b.val :=
+  Nat.mod_eq_of_lt (Nat.xor_lt_two_pow a.isLt b.isLt)
+
+@[simp] theorem xor_val_of_uInt8Size (a b : Fin UInt8.size) : (a ^^^ b).val = a.val ^^^ b.val := xor_val_of_two_pow (w := 8) a b
+@[simp] theorem xor_val_of_uInt16Size (a b : Fin UInt16.size) : (a ^^^ b).val = a.val ^^^ b.val := xor_val_of_two_pow (w := 16) a b
+@[simp] theorem xor_val_of_uInt32Size (a b : Fin UInt32.size) : (a ^^^ b).val = a.val ^^^ b.val := xor_val_of_two_pow (w := 32) a b
+@[simp] theorem xor_val_of_uInt64Size (a b : Fin UInt64.size) : (a ^^^ b).val = a.val ^^^ b.val := xor_val_of_two_pow (w := 64) a b
+@[simp] theorem xor_val_of_uSizeSize (a b : Fin USize.size) : (a ^^^ b).val = a.val ^^^ b.val := xor_val_of_two_pow a b
+
+theorem xor_val (a b : Fin n) : (a ^^^ b).val = (a.val ^^^ b.val) % n := rfl
+
+@[simp] theorem shiftLeft_val (a b : Fin n) : (a <<< b).val = (a.val <<< b.val) % n := rfl
+
+@[simp] theorem shiftRight_val (a b : Fin n) : (a >>> b).val = a.val >>> b.val :=
+  Nat.mod_eq_of_lt (Nat.lt_of_le_of_lt (Nat.shiftRight_le _ _) a.isLt)
+
 end Fin

src/Init/Data/Fin/Fold.lean

@@ -10,14 +10,26 @@ import Init.Data.Fin.Lemmas
 
 namespace Fin
 
-/-- Folds over `Fin n` from the left: `foldl 3 f x = f (f (f x 0) 1) 2`. -/
+/--
+Combine all the values that can be represented by `Fin n` with an initial value, starting at `0` and
+nesting to the left.
+
+Example:
+ * `Fin.foldl 3 (· + ·.val) (0 : Nat) = ((0 + (0 : Fin 3).val) + (1 : Fin 3).val) + (2 : Fin 3).val`
+-/
 @[inline] def foldl (n) (f : α → Fin n → α) (init : α) : α := loop init 0 where
   /-- Inner loop for `Fin.foldl`. `Fin.foldl.loop n f x i = f (f (f x i) ...) (n-1)`  -/
   @[semireducible, specialize] loop (x : α) (i : Nat) : α :=
     if h : i < n then loop (f x ⟨i, h⟩) (i+1) else x
   termination_by n - i
 
-/-- Folds over `Fin n` from the right: `foldr 3 f x = f 0 (f 1 (f 2 x))`. -/
+/--
+Combine all the values that can be represented by `Fin n` with an initial value, starting at `n - 1`
+and nesting to the right.
+
+Example:
+ * `Fin.foldr 3 (·.val + ·) (0 : Nat) = (0 : Fin 3).val + ((1 : Fin 3).val + ((2 : Fin 3).val + 0))`
+-/
 @[inline] def foldr (n) (f : Fin n → α → α) (init : α) : α := loop n (Nat.le_refl n) init where
   /-- Inner loop for `Fin.foldr`. `Fin.foldr.loop n f i x = f 0 (f ... (f (i-1) x))`  -/
   @[specialize] loop : (i : _) → i ≤ n → α → α
@@ -26,7 +38,9 @@ namespace Fin
   termination_by structural i => i
 
 /--
-Folds a monadic function over `Fin n` from left to right:
+Folds a monadic function over all the values in `Fin n` from left to right, starting with `0`.
+
+It is the sequence of steps:
 ```
 Fin.foldlM n f x₀ = do
   let x₁ ← f x₀ 0
@@ -53,7 +67,9 @@ Fin.foldlM n f x₀ = do
   decreasing_by decreasing_trivial_pre_omega
 
 /--
-Folds a monadic function over `Fin n` from right to left:
+Folds a monadic function over `Fin n` from right to left, starting with `n-1`.
+
+It is the sequence of steps:
 ```
 Fin.foldrM n f xₙ = do
   let xₙ₋₁ ← f (n-1) xₙ
@@ -125,7 +141,9 @@ theorem foldrM_loop [Monad m] [LawfulMonad m] (f : Fin (n+1) → α → m α) (x
   | zero =>
     rw [foldrM_loop_zero, foldrM_loop_succ, pure_bind]
     conv => rhs; rw [←bind_pure (f 0 x)]
-    congr; funext
+    congr
+    funext
+    try simp only [foldrM.loop] -- the try makes this proof work with and without opaque wf rec
   | succ i ih =>
     rw [foldrM_loop_succ, foldrM_loop_succ, bind_assoc]
     congr; funext; exact ih ..

src/Init/Data/Fin/Iterate.lean

@@ -10,10 +10,18 @@ import Init.Data.Fin.Basic
 namespace Fin
 
 /--
-`hIterateFrom f i bnd a` applies `f` over indices `[i:n]` to compute `P n`
-from `P i`.
+Applies an index-dependent function `f` to all of the values in `[i:n]`, starting at `i` with an
+initial accumulator `a`.
 
-See `hIterate` below for more details.
+Concretely, `Fin.hIterateFrom P f i a` is equal to
+```lean
+  a |> f i |> f (i + 1) |> ... |> f (n - 1)
+```
+
+Theorems about `Fin.hIterateFrom` can be proven using the general theorem `Fin.hIterateFrom_elim` or
+other more specialized theorems.
+
+`Fin.hIterate` is a variant that always starts at `0`.
 -/
 def hIterateFrom (P : Nat → Sort _) {n} (f : ∀(i : Fin n), P i.val → P (i.val+1))
       (i : Nat) (ubnd : i ≤ n) (a : P i) : P n :=
@@ -26,20 +34,18 @@ def hIterateFrom (P : Nat → Sort _) {n} (f : ∀(i : Fin n), P i.val → P (i.
   decreasing_by decreasing_trivial_pre_omega
 
 /--
-`hIterate` is a heterogeneous iterative operation that applies a
-index-dependent function `f` to a value `init : P start` a total of
-`stop - start` times to produce a value of type `P stop`.
+Applies an index-dependent function to all the values less than the given bound `n`, starting at
+`0` with an accumulator.
 
-Concretely, `hIterate start stop f init` is equal to
+Concretely, `Fin.hIterate P init f` is equal to
 ```lean
-  init |> f start _ |> f (start+1) _ ... |> f (end-1) _
+  init |> f 0 |> f 1 |> ... |> f (n-1)
 ```
 
-Because it is heterogeneous and must return a value of type `P stop`,
-`hIterate` requires proof that `start ≤ stop`.
+Theorems about `Fin.hIterate` can be proven using the general theorem `Fin.hIterate_elim` or other more
+specialized theorems.
 
-One can prove properties of `hIterate` using the general theorem
-`hIterate_elim` or other more specialized theorems.
+`Fin.hIterateFrom` is a variant that takes a custom starting value instead of `0`.
  -/
 def hIterate (P : Nat → Sort _) {n : Nat} (init : P 0) (f : ∀(i : Fin n), P i.val → P (i.val+1)) :
     P n :=

src/Init/Data/Fin/Lemmas.lean

@@ -45,6 +45,7 @@ theorem val_ne_iff {a b : Fin n} : a.1 ≠ b.1 ↔ a ≠ b := not_congr val_inj
 theorem forall_iff {p : Fin n → Prop} : (∀ i, p i) ↔ ∀ i h, p ⟨i, h⟩ :=
   ⟨fun h i hi => h ⟨i, hi⟩, fun h ⟨i, hi⟩ => h i hi⟩
 
+/-- Restatement of `Fin.mk.injEq` as an `iff`. -/
 protected theorem mk.inj_iff {n a b : Nat} {ha : a < n} {hb : b < n} :
     (⟨a, ha⟩ : Fin n) = ⟨b, hb⟩ ↔ a = b := Fin.ext_iff
 
@@ -55,6 +56,14 @@ theorem eq_mk_iff_val_eq {a : Fin n} {k : Nat} {hk : k < n} :
 
 theorem mk_val (i : Fin n) : (⟨i, i.isLt⟩ : Fin n) = i := Fin.eta ..
 
+@[simp] theorem mk_eq_zero {n a : Nat} {ha : a < n} [NeZero n] :
+    (⟨a, ha⟩ : Fin n) = 0 ↔ a = 0 :=
+  mk.inj_iff
+
+@[simp] theorem zero_eq_mk {n a : Nat} {ha : a < n} [NeZero n] :
+    0 = (⟨a, ha⟩ : Fin n) ↔ a = 0 := by
+  simp [eq_comm]
+
 @[simp] theorem val_ofNat' (n : Nat) [NeZero n] (a : Nat) :
   (Fin.ofNat' n a).val = a % n := rfl
 
@@ -661,12 +670,20 @@ theorem pred_add_one (i : Fin (n + 2)) (h : (i : Nat) < n + 1) :
 @[simp] theorem natAdd_subNat_cast {i : Fin (n + m)} (h : n ≤ i) :
     natAdd n (subNat n (i.cast (Nat.add_comm ..)) h) = i := by simp [← cast_addNat]
 
-/-! ### recursion and induction principles -/
+/-! ### Recursion and induction principles -/
 
-/-- Define `motive n i` by induction on `i : Fin n` interpreted as `(0 : Fin (n - i)).succ.succ…`.
-This function has two arguments: `zero n` defines `0`-th element `motive (n+1) 0` of an
-`(n+1)`-tuple, and `succ n i` defines `(i+1)`-st element of `(n+1)`-tuple based on `n`, `i`, and
-`i`-th element of `n`-tuple. -/
+/--
+An induction principle for `Fin` that considers a given `i : Fin n` as given by a sequence of `i`
+applications of `Fin.succ`.
+
+The cases in the induction are:
+ * `zero` demonstrates the motive for `(0 : Fin (n + 1))` for all bounds `n`
+ * `succ` demonstrates the motive for `Fin.succ` applied to an arbitrary `Fin` for an arbitrary
+   bound `n`
+
+Unlike `Fin.induction`, the motive quantifies over the bound, and the bound varies at each inductive
+step. `Fin.succRecOn` is a version of this induction principle that takes the `Fin` argument first.
+-/
 -- FIXME: Performance review
 @[elab_as_elim] def succRec {motive : ∀ n, Fin n → Sort _}
     (zero : ∀ n, motive n.succ (0 : Fin (n + 1)))
@@ -675,13 +692,18 @@ This function has two arguments: `zero n` defines `0`-th element `motive (n+1) 0
   | Nat.succ n, ⟨0, _⟩ => by rw [mk_zero]; exact zero n
   | Nat.succ _, ⟨Nat.succ i, h⟩ => succ _ _ (succRec zero succ ⟨i, Nat.lt_of_succ_lt_succ h⟩)
 
-/-- Define `motive n i` by induction on `i : Fin n` interpreted as `(0 : Fin (n - i)).succ.succ…`.
-This function has two arguments:
-`zero n` defines the `0`-th element `motive (n+1) 0` of an `(n+1)`-tuple, and
-`succ n i` defines the `(i+1)`-st element of an `(n+1)`-tuple based on `n`, `i`,
-and the `i`-th element of an `n`-tuple.
+/--
+An induction principle for `Fin` that considers a given `i : Fin n` as given by a sequence of `i`
+applications of `Fin.succ`.
 
-A version of `Fin.succRec` taking `i : Fin n` as the first argument. -/
+The cases in the induction are:
+ * `zero` demonstrates the motive for `(0 : Fin (n + 1))` for all bounds `n`
+ * `succ` demonstrates the motive for `Fin.succ` applied to an arbitrary `Fin` for an arbitrary
+   bound `n`
+
+Unlike `Fin.induction`, the motive quantifies over the bound, and the bound varies at each inductive
+step. `Fin.succRec` is a version of this induction principle that takes the `Fin` argument last.
+-/
 -- FIXME: Performance review
 @[elab_as_elim] def succRecOn {n : Nat} (i : Fin n) {motive : ∀ n, Fin n → Sort _}
     (zero : ∀ n, motive (n + 1) 0) (succ : ∀ n i, motive n i → motive (Nat.succ n) i.succ) :
@@ -696,9 +718,17 @@ A version of `Fin.succRec` taking `i : Fin n` as the first argument. -/
   cases i; rfl
 
 
-/-- Define `motive i` by induction on `i : Fin (n + 1)` via induction on the underlying `Nat` value.
-This function has two arguments: `zero` handles the base case on `motive 0`,
-and `succ` defines the inductive step using `motive i.castSucc`.
+/--
+Proves a statement by induction on the underlying `Nat` value in a `Fin (n + 1)`.
+
+For the induction:
+ * `zero` is the base case, demonstrating `motive 0`.
+ * `succ` is the inductive step, assuming the motive for `i : Fin n` (lifted to `Fin (n + 1)` with
+   `Fin.castSucc`) and demonstrating it for `i.succ`.
+
+`Fin.inductionOn` is a version of this induction principle that takes the `Fin` as its first
+parameter, `Fin.cases` is the corresponding case analysis operator, and `Fin.reverseInduction` is a
+version that starts at the greatest value instead of `0`.
 -/
 -- FIXME: Performance review
 @[elab_as_elim] def induction {motive : Fin (n + 1) → Sort _} (zero : motive 0)
@@ -719,18 +749,30 @@ where
     (succ : ∀ i : Fin n, motive (castSucc i) → motive i.succ) (i : Fin n) :
     induction (motive := motive) zero succ i.succ = succ i (induction zero succ (castSucc i)) := rfl
 
-/-- Define `motive i` by induction on `i : Fin (n + 1)` via induction on the underlying `Nat` value.
-This function has two arguments: `zero` handles the base case on `motive 0`,
-and `succ` defines the inductive step using `motive i.castSucc`.
+/--
+Proves a statement by induction on the underlying `Nat` value in a `Fin (n + 1)`.
 
-A version of `Fin.induction` taking `i : Fin (n + 1)` as the first argument.
+For the induction:
+ * `zero` is the base case, demonstrating `motive 0`.
+ * `succ` is the inductive step, assuming the motive for `i : Fin n` (lifted to `Fin (n + 1)` with
+   `Fin.castSucc`) and demonstrating it for `i.succ`.
+
+`Fin.induction` is a version of this induction principle that takes the `Fin` as its last
+parameter.
 -/
 -- FIXME: Performance review
 @[elab_as_elim] def inductionOn (i : Fin (n + 1)) {motive : Fin (n + 1) → Sort _} (zero : motive 0)
     (succ : ∀ i : Fin n, motive (castSucc i) → motive i.succ) : motive i := induction zero succ i
 
-/-- Define `f : Π i : Fin n.succ, motive i` by separately handling the cases `i = 0` and
-`i = j.succ`, `j : Fin n`. -/
+/--
+Proves a statement by cases on the underlying `Nat` value in a `Fin (n + 1)`.
+
+The two cases are:
+ * `zero`, used when the value is of the form `(0 : Fin (n + 1))`
+ * `succ`, used when the value is of the form `(j : Fin n).succ`
+
+The corresponding induction principle is `Fin.induction`.
+-/
 @[elab_as_elim] def cases {motive : Fin (n + 1) → Sort _}
     (zero : motive 0) (succ : ∀ i : Fin n, motive i.succ) :
     ∀ i : Fin (n + 1), motive i := induction zero fun i _ => succ i
@@ -768,9 +810,14 @@ theorem fin_two_eq_of_eq_zero_iff : ∀ {a b : Fin 2}, (a = 0 ↔ b = 0) → a =
   simp only [forall_fin_two]; decide
 
 /--
-Define `motive i` by reverse induction on `i : Fin (n + 1)` via induction on the underlying `Nat`
-value. This function has two arguments: `last` handles the base case on `motive (Fin.last n)`,
-and `cast` defines the inductive step using `motive i.succ`, inducting downwards.
+Proves a statement by reverse induction on the underlying `Nat` value in a `Fin (n + 1)`.
+
+For the induction:
+ * `last` is the base case, demonstrating `motive (Fin.last n)`.
+ * `cast` is the inductive step, assuming the motive for `(j : Fin n).succ` and demonstrating it for
+    the predecessor `j.castSucc`.
+
+`Fin.induction` is the non-reverse induction principle.
 -/
 @[elab_as_elim] def reverseInduction {motive : Fin (n + 1) → Sort _} (last : motive (Fin.last n))
     (cast : ∀ i : Fin n, motive i.succ → motive (castSucc i)) (i : Fin (n + 1)) : motive i :=
@@ -793,8 +840,16 @@ decreasing_by decreasing_with
       succ i (reverseInduction zero succ i.succ) := by
   rw [reverseInduction, dif_neg (Fin.ne_of_lt (Fin.castSucc_lt_last i))]; rfl
 
-/-- Define `f : Π i : Fin n.succ, motive i` by separately handling the cases `i = Fin.last n` and
-`i = j.castSucc`, `j : Fin n`. -/
+/--
+Proves a statement by cases on the underlying `Nat` value in a `Fin (n + 1)`, checking whether the
+value is the greatest representable or a predecessor of some other.
+
+The two cases are:
+ * `last`, used when the value is `Fin.last n`
+ * `cast`, used when the value is of the form `(j : Fin n).succ`
+
+The corresponding induction principle is `Fin.reverseInduction`.
+-/
 @[elab_as_elim] def lastCases {n : Nat} {motive : Fin (n + 1) → Sort _} (last : motive (Fin.last n))
     (cast : ∀ i : Fin n, motive (castSucc i)) (i : Fin (n + 1)) : motive i :=
   reverseInduction last (fun i _ => cast i) i
@@ -807,8 +862,16 @@ decreasing_by decreasing_with
     (i : Fin n) : (Fin.lastCases last cast (Fin.castSucc i) : motive (Fin.castSucc i)) = cast i :=
   reverseInduction_castSucc ..
 
-/-- Define `f : Π i : Fin (m + n), motive i` by separately handling the cases `i = castAdd n i`,
-`j : Fin m` and `i = natAdd m j`, `j : Fin n`. -/
+/--
+A case analysis operator for `i : Fin (m + n)` that separately handles the cases where `i < m` and
+where `m ≤ i < m + n`.
+
+The first case, where `i < m`, is handled by `left`. In this case, `i` can be represented as
+`Fin.castAdd n (j : Fin m)`.
+
+The second case, where `m ≤ i < m + n`, is handled by `right`. In this case, `i` can be represented
+as `Fin.natAdd m (j : Fin n)`.
+-/
 @[elab_as_elim] def addCases {m n : Nat} {motive : Fin (m + n) → Sort u}
     (left : ∀ i, motive (castAdd n i)) (right : ∀ i, motive (natAdd m i))
     (i : Fin (m + n)) : motive i :=

src/Init/Data/Fin/Log2.lean

@@ -6,4 +6,20 @@ Authors: Henrik Böving
 prelude
 import Init.Data.Nat.Log2
 
+set_option linter.missingDocs true
+
+/--
+Logarithm base 2 for bounded numbers.
+
+The resulting value is the same as that computed by `Nat.log2`. In particular, the result for `0` is
+`0`.
+
+Examples:
+ * `(8 : Fin 10).log2 = (3 : Fin 10)`
+ * `(7 : Fin 10).log2 = (2 : Fin 10)`
+ * `(4 : Fin 10).log2 = (2 : Fin 10)`
+ * `(3 : Fin 10).log2 = (1 : Fin 10)`
+ * `(1 : Fin 10).log2 = (0 : Fin 10)`
+ * `(0 : Fin 10).log2 = (0 : Fin 10)`
+-/
 def Fin.log2 (n : Fin m) : Fin m := ⟨Nat.log2 n.val, Nat.lt_of_le_of_lt (Nat.log2_le_self n.val) n.isLt⟩

src/Init/Data/Float.lean

@@ -140,15 +140,27 @@ instance : ToString Float where
 @[extern "lean_uint16_to_float"] opaque UInt16.toFloat (n : UInt16) : Float
 /-- Obtains the `Float` whose value is the same as the given `UInt32`. -/
 @[extern "lean_uint32_to_float"] opaque UInt32.toFloat (n : UInt32) : Float
-/-- Obtains a `Float` whose value is near the given `UInt64`. It will be exactly the value of the
-given `UInt64` if such a `Float` exists. If no such `Float` exists, the returned value will either
-be the smallest `Float` this is larger than the given value, or the largest `Float` this is smaller
-than the given value. -/
+/--
+Obtains a `Float` whose value is near the given `UInt64`.
+
+It will be exactly the value of the given `UInt64` if such a `Float` exists. If no such `Float`
+exists, the returned value will either be the smallest `Float` that is larger than the given value,
+or the largest `Float` that is smaller than the given value.
+
+This function is opaque in the kernel, but is overridden at runtime with an efficient
+implementation.
+-/
 @[extern "lean_uint64_to_float"] opaque UInt64.toFloat (n : UInt64) : Float
-/-- Obtains a `Float` whose value is near the given `USize`. It will be exactly the value of the
-given `USize` if such a `Float` exists. If no such `Float` exists, the returned value will either
-be the smallest `Float` this is larger than the given value, or the largest `Float` this is smaller
-than the given value. -/
+/--
+Obtains a `Float` whose value is near the given `USize`.
+
+It will be exactly the value of the given `USize` if such a `Float` exists. If no such `Float`
+exists, the returned value will either be the smallest `Float` that is larger than the given value,
+or the largest `Float` that is smaller than the given value.
+
+This function is opaque in the kernel, but is overridden at runtime with an efficient
+implementation.
+-/
 @[extern "lean_usize_to_float"] opaque USize.toFloat (n : USize) : Float
 
 instance : Inhabited Float where

src/Init/Data/Float32.lean

@@ -131,20 +131,37 @@ instance : ToString Float32 where
 @[extern "lean_uint8_to_float32"] opaque UInt8.toFloat32 (n : UInt8) : Float32
 /-- Obtains the `Float32` whose value is the same as the given `UInt16`. -/
 @[extern "lean_uint16_to_float32"] opaque UInt16.toFloat32 (n : UInt16) : Float32
-/-- Obtains a `Float32` whose value is near the given `UInt32`. It will be exactly the value of the
-given `UInt32` if such a `Float32` exists. If no such `Float32` exists, the returned value will either
-be the smallest `Float32` this is larger than the given value, or the largest `Float32` this is smaller
-than the given value. -/
+/--
+Obtains a `Float32` whose value is near the given `UInt32`.
+
+It will be exactly the value of the given `UInt32` if such a `Float32` exists. If no such `Float32`
+exists, the returned value will either be the smallest `Float32` that is larger than the given
+value, or the largest `Float32` that is smaller than the given value.
+
+This function is opaque in the kernel, but is overridden at runtime with an efficient
+implementation.
+-/
 @[extern "lean_uint32_to_float32"] opaque UInt32.toFloat32 (n : UInt32) : Float32
-/-- Obtains a `Float32` whose value is near the given `UInt64`. It will be exactly the value of the
-given `UInt64` if such a `Float32` exists. If no such `Float32` exists, the returned value will either
-be the smallest `Float32` this is larger than the given value, or the largest `Float32` this is smaller
-than the given value. -/
+/--
+Obtains a `Float32` whose value is near the given `UInt64`.
+
+It will be exactly the value of the given `UInt64` if such a `Float32` exists. If no such `Float32`
+exists, the returned value will either be the smallest `Float32` that is larger than the given
+value, or the largest `Float32` that is smaller than the given value.
+
+This function is opaque in the kernel, but is overridden at runtime with an efficient
+implementation.
+-/
 @[extern "lean_uint64_to_float32"] opaque UInt64.toFloat32 (n : UInt64) : Float32
-/-- Obtains a `Float32` whose value is near the given `USize`. It will be exactly the value of the
-given `USize` if such a `Float32` exists. If no such `Float32` exists, the returned value will either
-be the smallest `Float32` this is larger than the given value, or the largest `Float32` this is smaller
-than the given value. -/
+/-- Obtains a `Float32` whose value is near the given `USize`.
+
+It will be exactly the value of the given `USize` if such a `Float32` exists. If no such `Float32`
+exists, the returned value will either be the smallest `Float32` that is larger than the given
+value, or the largest `Float32` that is smaller than the given value.
+
+This function is opaque in the kernel, but is overridden at runtime with an efficient
+implementation.
+-/
 @[extern "lean_usize_to_float32"] opaque USize.toFloat32 (n : USize) : Float32
 
 instance : Inhabited Float32 where

src/Init/Data/FloatArray/Basic.lean

@@ -17,11 +17,14 @@ attribute [extern "lean_float_array_data"] FloatArray.data
 
 namespace FloatArray
 @[extern "lean_mk_empty_float_array"]
-def mkEmpty (c : @& Nat) : FloatArray :=
+def emptyWithCapacity (c : @& Nat) : FloatArray :=
   { data := #[] }
 
+@[deprecated emptyWithCapacity (since := "2025-03-12")]
+abbrev mkEmpty := emptyWithCapacity
+
 def empty : FloatArray :=
-  mkEmpty 0
+  emptyWithCapacity 0
 
 instance : Inhabited FloatArray where
   default := empty
@@ -164,6 +167,9 @@ def foldl {β : Type v} (f : β → Float → β) (init : β) (as : FloatArray)
 
 end FloatArray
 
+/--
+Converts a list of floats into a `FloatArray`.
+-/
 def List.toFloatArray (ds : List Float) : FloatArray :=
   let rec loop
     | [],    r => r

src/Init/Data/Format/Instances.lean

@@ -23,6 +23,12 @@ instance [ToFormat α] : ToFormat (List α) where
 instance [ToFormat α] : ToFormat (Array α) where
   format a := "#" ++ format a.toList
 
+/--
+Formats an optional value, with no expectation that the Lean parser should be able to parse the
+result.
+
+This function is usually accessed through the `ToFormat (Option α)` instance.
+-/
 def Option.format {α : Type u} [ToFormat α] : Option α → Format
   | none   => "none"
   | some a => "some " ++ Std.format a
@@ -33,6 +39,10 @@ instance {α : Type u} [ToFormat α] : ToFormat (Option α) :=
 instance {α : Type u} {β : Type v} [ToFormat α] [ToFormat β] : ToFormat (Prod α β) where
   format := fun (a, b) => Format.paren <| format a ++ "," ++ Format.line ++ format b
 
+/--
+Converts a string to a pretty-printer document, replacing newlines in the string with
+`Std.Format.line`.
+-/
 def String.toFormat (s : String) : Std.Format :=
   Std.Format.joinSep (s.splitOn "\n") Std.Format.line
 

src/Init/Data/Function.lean

@@ -9,10 +9,23 @@ import Init.Core
 
 namespace Function
 
+/--
+Transforms a function from pairs into an equivalent two-parameter function.
+
+Examples:
+ * `Function.curry (fun (x, y) => x + y) 3 5 = 8`
+ * `Function.curry Prod.swap 3 "five" = ("five", 3)`
+-/
 @[inline]
 def curry : (α × β → φ) → α → β → φ := fun f a b => f (a, b)
 
-/-- Interpret a function with two arguments as a function on `α × β` -/
+/--
+Transforms a two-parameter function into an equivalent function from pairs.
+
+Examples:
+ * `Function.uncurry List.drop (1, ["a", "b", "c"]) = ["b", "c"]`
+ * `[("orange", 2), ("android", 3) ].map (Function.uncurry String.take) = ["or", "and"]`
+-/
 @[inline]
 def uncurry : (α → β → φ) → α × β → φ := fun f a => f a.1 a.2
 

src/Init/Data/Hashable.lean

@@ -75,13 +75,19 @@ instance (P : Prop) : Hashable P where
 @[always_inline, inline] def hash64 (u : UInt64) : UInt64 :=
   mixHash u 11
 
-/-- `LawfulHashable α` says that the `BEq α` and `Hashable α` instances on `α` are compatible, i.e.,
-that `a == b` implies `hash a = hash b`. This is automatic if the `BEq` instance is lawful.
+/--
+The `BEq α` and `Hashable α` instances on `α` are compatible. This means that that `a == b` implies
+`hash a = hash b`.
+
+This is automatic if the `BEq` instance is lawful.
 -/
 class LawfulHashable (α : Type u) [BEq α] [Hashable α] where
   /-- If `a == b`, then `hash a = hash b`. -/
   hash_eq (a b : α) : a == b → hash a = hash b
 
+/--
+A lawful hash function respects its Boolean equality test.
+-/
 theorem hash_eq [BEq α] [Hashable α] [LawfulHashable α] {a b : α} : a == b → hash a = hash b :=
   LawfulHashable.hash_eq a b
 

src/Init/Data/Int.lean

@@ -7,7 +7,6 @@ prelude
 import Init.Data.Int.Basic
 import Init.Data.Int.Bitwise
 import Init.Data.Int.DivMod
-import Init.Data.Int.DivModLemmas
 import Init.Data.Int.Gcd
 import Init.Data.Int.Lemmas
 import Init.Data.Int.LemmasAux
@@ -15,3 +14,4 @@ import Init.Data.Int.Order
 import Init.Data.Int.Pow
 import Init.Data.Int.Cooper
 import Init.Data.Int.Linear
+import Init.Data.Int.OfNat

src/Init/Data/Int/Basic.lean

@@ -17,31 +17,36 @@ open Nat
 This file defines the `Int` type as well as
 
 * coercions, conversions, and compatibility with numeric literals,
-* basic arithmetic operations add/sub/mul/div/mod/pow,
+* basic arithmetic operations add/sub/mul/pow,
 * a few `Nat`-related operations such as `negOfNat` and `subNatNat`,
 * relations `<`/`≤`/`≥`/`>`, the `NonNeg` property and `min`/`max`,
 * decidability of equality, relations and `NonNeg`.
+
+Division and modulus operations are defined in `Init.Data.Int.DivMod.Basic`.
 -/
 
 /--
-The type of integers. It is defined as an inductive type based on the
-natural number type `Nat` featuring two constructors: "a natural
-number is an integer", and "the negation of a successor of a natural
-number is an integer". The former represents integers between `0`
-(inclusive) and `∞`, and the latter integers between `-∞` and `-1`
-(inclusive).
+The integers.
 
-This type is special-cased by the compiler. The runtime has a special
-representation for `Int` which stores "small" signed numbers directly,
-and larger numbers use an arbitrary precision "bignum" library
-(usually [GMP](https://gmplib.org/)). A "small number" is an integer
-that can be encoded with 63 bits (31 bits on 32-bits architectures).
+This type is special-cased by the compiler and overridden with an efficient implementation. The
+runtime has a special representation for `Int` that stores “small” signed numbers directly, while
+larger numbers use a fast arbitrary-precision arithmetic library (usually
+[GMP](https://gmplib.org/)). A “small number” is an integer that can be encoded with one fewer bits
+than the platform's pointer size (i.e. 63 bits on 64-bit architectures and 31 bits on 32-bit
+architectures).
 -/
 inductive Int : Type where
-  /-- A natural number is an integer (`0` to `∞`). -/
+  /--
+  A natural number is an integer.
+
+  This constructor covers the non-negative integers (from `0` to `∞`).
+  -/
   | ofNat   : Nat → Int
-  /-- The negation of the successor of a natural number is an integer
-    (`-1` to `-∞`). -/
+  /--
+  The negation of the successor of a natural number is an integer.
+
+  This constructor covers the negative integers (from `-1` to `-∞`).
+  -/
   | negSucc : Nat → Int
 
 attribute [extern "lean_nat_to_int"] Int.ofNat
@@ -76,15 +81,29 @@ protected theorem zero_ne_one : (0 : Int) ≠ 1 := nofun
 
 theorem ofNat_two : ((2 : Nat) : Int) = 2 := rfl
 
-/-- Negation of a natural number. -/
+/--
+Negation of natural numbers.
+
+Examples:
+ * `Int.negOfNat 6 = -6`
+ * `Int.negOfNat 0 = 0`
+-/
 def negOfNat : Nat → Int
   | 0      => 0
   | succ m => negSucc m
 
 set_option bootstrap.genMatcherCode false in
-/-- Negation of an integer.
+/--
+Negation of integers, usually accessed via the `-` prefix operator.
 
-  Implemented by efficient native code. -/
+This function is overridden by the compiler with an efficient implementation. This definition is
+the logical model.
+
+Examples:
+ * `-(6 : Int) = -6`
+ * `-(-6 : Int) = 6`
+ * `(12 : Int).neg = -12`
+-/
 @[extern "lean_int_neg"]
 protected def neg (n : @& Int) : Int :=
   match n with
@@ -103,21 +122,30 @@ protected def neg (n : @& Int) : Int :=
 instance instNegInt : Neg Int where
   neg := Int.neg
 
-/-- Subtraction of two natural numbers. -/
+/--
+Non-truncating subtraction of two natural numbers.
+
+Examples:
+ * `Int.subNatNat 5 2 = 3`
+ * `Int.subNatNat 2 5 = -3`
+ * `Int.subNatNat 0 13 = -13`
+-/
 def subNatNat (m n : Nat) : Int :=
   match (n - m : Nat) with
   | 0        => ofNat (m - n)  -- m ≥ n
   | (succ k) => negSucc k
 
 set_option bootstrap.genMatcherCode false in
-/-- Addition of two integers.
+/--
+Addition of integers, usually accessed via the `+` operator.
 
-  ```
-  #eval (7 : Int) + (6 : Int) -- 13
-  #eval (6 : Int) + (-6 : Int) -- 0
-  ```
+This function is overridden by the compiler with an efficient implementation. This definition is
+the logical model.
 
-  Implemented by efficient native code. -/
+Examples:
+ * `(7 : Int) + (6 : Int) = 13`
+ * `(6 : Int) + (-6 : Int) = 0`
+-/
 @[extern "lean_int_add"]
 protected def add (m n : @& Int) : Int :=
   match m, n with
@@ -130,15 +158,17 @@ instance : Add Int where
   add := Int.add
 
 set_option bootstrap.genMatcherCode false in
-/-- Multiplication of two integers.
+/--
+Multiplication of integers, usually accessed via the `*` operator.
 
-  ```
-  #eval (63 : Int) * (6 : Int) -- 378
-  #eval (6 : Int) * (-6 : Int) -- -36
-  #eval (7 : Int) * (0 : Int) -- 0
-  ```
+This function is overridden by the compiler with an efficient implementation. This definition is
+the logical model.
 
-  Implemented by efficient native code. -/
+Examples:
+ * `(63 : Int) * (6 : Int) = 378`
+ * `(6 : Int) * (-6 : Int) = -36`
+ * `(7 : Int) * (0 : Int) = 0`
+-/
 @[extern "lean_int_mul"]
 protected def mul (m n : @& Int) : Int :=
   match m, n with
@@ -150,48 +180,65 @@ protected def mul (m n : @& Int) : Int :=
 instance : Mul Int where
   mul := Int.mul
 
-/-- Subtraction of two integers.
 
-  ```
-  #eval (63 : Int) - (6 : Int) -- 57
-  #eval (7 : Int) - (0 : Int) -- 7
-  #eval (0 : Int) - (7 : Int) -- -7
-  ```
+/--
+Subtraction of integers, usually accessed via the `-` operator.
 
-  Implemented by efficient native code. -/
+This function is overridden by the compiler with an efficient implementation. This definition is
+the logical model.
+
+Examples:
+* `(63 : Int) - (6 : Int) = 57`
+* `(7 : Int) - (0 : Int) = 7`
+* `(0 : Int) - (7 : Int) = -7`
+-/
 @[extern "lean_int_sub"]
 protected def sub (m n : @& Int) : Int := m + (- n)
 
 instance : Sub Int where
   sub := Int.sub
 
-/-- A proof that an `Int` is non-negative. -/
+/--
+An integer is non-negative if it is equal to a natural number.
+-/
 inductive NonNeg : Int → Prop where
-  /-- Sole constructor, proving that `ofNat n` is positive. -/
+  /--
+  For all natural numbers `n`, `Int.ofNat n` is non-negative.
+  -/
   | mk (n : Nat) : NonNeg (ofNat n)
 
-/-- Definition of `a ≤ b`, encoded as `b - a ≥ 0`. -/
+/--
+Non-strict inequality of integers, usually accessed via the `≤` operator.
+
+`a ≤ b` is defined as `b - a ≥ 0`, using `Int.NonNeg`.
+-/
 protected def le (a b : Int) : Prop := NonNeg (b - a)
 
 instance instLEInt : LE Int where
   le := Int.le
 
-/-- Definition of `a < b`, encoded as `a + 1 ≤ b`. -/
+/--
+Strict inequality of integers, usually accessed via the `<` operator.
+
+`a < b` when `a + 1 ≤ b`.
+-/
 protected def lt (a b : Int) : Prop := (a + 1) ≤ b
 
 instance instLTInt : LT Int where
   lt := Int.lt
 
 set_option bootstrap.genMatcherCode false in
-/-- Decides equality between two `Int`s.
+/--
+Decides whether two integers are equal. Usually accessed via the `DecidableEq Int` instance.
 
-  ```
-  #eval (7 : Int) = (3 : Int) + (4 : Int) -- true
-  #eval (6 : Int) = (3 : Int) * (2 : Int) -- true
-  #eval ¬ (6 : Int) = (3 : Int) -- true
-  ```
+This function is overridden by the compiler with an efficient implementation. This definition is the
+logical model.
 
-  Implemented by efficient native code. -/
+Examples:
+* `show (7 : Int) = (3 : Int) + (4 : Int) by decide`
+* `if (6 : Int) = (3 : Int) * (2 : Int) then "yes" else "no" = "yes"`
+* `(¬ (6 : Int) = (3 : Int)) = true`
+-/
 @[extern "lean_int_dec_eq"]
 protected def decEq (a b : @& Int) : Decidable (a = b) :=
   match a, b with
@@ -204,6 +251,7 @@ protected def decEq (a b : @& Int) : Decidable (a = b) :=
     | isTrue h  => isTrue  <| h ▸ rfl
     | isFalse h => isFalse <| fun h' => Int.noConfusion h' (fun h' => absurd h' h)
 
+@[inherit_doc Int.decEq]
 instance : DecidableEq Int := Int.decEq
 
 set_option bootstrap.genMatcherCode false in
@@ -249,15 +297,17 @@ instance decLt (a b : @& Int) : Decidable (a < b) :=
   decNonneg _
 
 set_option bootstrap.genMatcherCode false in
-/-- Absolute value (`Nat`) of an integer.
+/--
+The absolute value of an integer is its distance from `0`.
 
-  ```
-  #eval (7 : Int).natAbs -- 7
-  #eval (0 : Int).natAbs -- 0
-  #eval (-11 : Int).natAbs -- 11
-  ```
+This function is overridden by the compiler with an efficient implementation. This definition is
+the logical model.
 
-  Implemented by efficient native code. -/
+Examples:
+ * `(7 : Int).natAbs = 7`
+ * `(0 : Int).natAbs = 0`
+ * `((-11 : Int).natAbs = 11`
+-/
 @[extern "lean_nat_abs"]
 def natAbs (m : @& Int) : Nat :=
   match m with
@@ -267,8 +317,17 @@ def natAbs (m : @& Int) : Nat :=
 /-! ## sign -/
 
 /--
-Returns the "sign" of the integer as another integer: `1` for positive numbers,
-`-1` for negative numbers, and `0` for `0`.
+Returns the “sign” of the integer as another integer:
+ * `1` for positive numbers,
+ * `-1` for negative numbers, and
+ * `0` for `0`.
+
+Examples:
+ * `Int.sign 34 = 1`
+ * `Int.sign 2 = 1`
+ * `Int.sign 0 = 0`
+ * `Int.sign -1 = -1`
+ * `Int.sign -362 = -1`
 -/
 def sign : Int → Int
   | Int.ofNat (succ _) => 1
@@ -277,27 +336,33 @@ def sign : Int → Int
 
 /-! ## Conversion -/
 
-/-- Turns an integer into a natural number, negative numbers become
-  `0`.
+/--
+Converts an integer into a natural number. Negative numbers are converted to `0`.
 
-  ```
-  #eval (7 : Int).toNat -- 7
-  #eval (0 : Int).toNat -- 0
-  #eval (-7 : Int).toNat -- 0
-  ```
+Examples:
+* `(7 : Int).toNat = 7`
+* `(0 : Int).toNat = 0`
+* `(-7 : Int).toNat = 0`
 -/
 def toNat : Int → Nat
   | ofNat n   => n
   | negSucc _ => 0
 
 /--
-* If `n : Nat`, then `int.toNat' n = some n`
-* If `n : Int` is negative, then `int.toNat' n = none`.
+Converts an integer into a natural number. Returns `none` for negative numbers.
+
+Examples:
+* `(7 : Int).toNat? = some 7`
+* `(0 : Int).toNat? = some 0`
+* `(-7 : Int).toNat? = none`
 -/
-def toNat' : Int → Option Nat
+def toNat? : Int → Option Nat
   | (n : Nat) => some n
   | -[_+1] => none
 
+@[deprecated toNat? (since := "2025-03-11"), inherit_doc toNat?]
+abbrev toNat' := toNat?
+
 /-! ## divisibility -/
 
 /--
@@ -309,14 +374,14 @@ instance : Dvd Int where
 
 /-! ## Powers -/
 
-/-- Power of an integer to some natural number.
+/--
+Power of an integer to a natural number, usually accessed via the `^` operator.
 
-  ```
-  #eval (2 : Int) ^ 4 -- 16
-  #eval (10 : Int) ^ 0 -- 1
-  #eval (0 : Int) ^ 10 -- 0
-  #eval (-7 : Int) ^ 3 -- -343
-  ```
+Examples:
+* `(2 : Int) ^ 4 = 16`
+* `(10 : Int) ^ 0 = 1`
+* `(0 : Int) ^ 10 = 0`
+* `(-7 : Int) ^ 3 = -343`
 -/
 protected def pow (m : Int) : Nat → Int
   | 0      => 1

src/Init/Data/Int/Bitwise.lean

@@ -1,50 +1,8 @@
 /-
-Copyright (c) 2022 Mario Carneiro. All rights reserved.
+Copyright (c) 2025 Lean FRO, LLC. All rights reserved.
 Released under Apache 2.0 license as described in the file LICENSE.
-Authors: Mario Carneiro
+Authors: Kim Morrison
 -/
 prelude
-import Init.Data.Int.Basic
-import Init.Data.Nat.Bitwise.Basic
-
-namespace Int
-
-/-! ## bit operations -/
-
-/--
-Bitwise not
-
-Interprets the integer as an infinite sequence of bits in two's complement
-and complements each bit.
-```
-~~~(0:Int) = -1
-~~~(1:Int) = -2
-~~~(-1:Int) = 0
-```
--/
-protected def not : Int -> Int
-  | Int.ofNat n => Int.negSucc n
-  | Int.negSucc n => Int.ofNat n
-
-instance : Complement Int := ⟨.not⟩
-
-/--
-Bitwise shift right.
-
-Conceptually, this treats the integer as an infinite sequence of bits in two's
-complement and shifts the value to the right.
-
-```lean
-( 0b0111:Int) >>> 1 =  0b0011
-( 0b1000:Int) >>> 1 =  0b0100
-(-0b1000:Int) >>> 1 = -0b0100
-(-0b0111:Int) >>> 1 = -0b0100
-```
--/
-protected def shiftRight : Int → Nat → Int
-  | Int.ofNat n, s => Int.ofNat (n >>> s)
-  | Int.negSucc n, s => Int.negSucc (n >>> s)
-
-instance : HShiftRight Int Nat Int := ⟨.shiftRight⟩
-
-end Int
+import Init.Data.Int.Bitwise.Basic
+import Init.Data.Int.Bitwise.Lemmas

src/Init/Data/Int/Bitwise/Basic.lean

@@ -0,0 +1,48 @@
+/-
+Copyright (c) 2022 Mario Carneiro. All rights reserved.
+Released under Apache 2.0 license as described in the file LICENSE.
+Authors: Mario Carneiro
+-/
+prelude
+import Init.Data.Int.Basic
+import Init.Data.Nat.Bitwise.Basic
+
+namespace Int
+
+/-! ## bit operations -/
+
+/--
+Bitwise not, usually accessed via the `~~~` prefix operator.
+
+Interprets the integer as an infinite sequence of bits in two's complement and complements each bit.
+
+Examples:
+ * `~~~(0 : Int) = -1`
+ * `~~~(1 : Int) = -2`
+ * `~~~(-1 : Int) = 0`
+-/
+protected def not : Int → Int
+  | Int.ofNat n => Int.negSucc n
+  | Int.negSucc n => Int.ofNat n
+
+instance : Complement Int := ⟨.not⟩
+
+/--
+Bitwise right shift, usually accessed via the `>>>` operator.
+
+Interprets the integer as an infinite sequence of bits in two's complement and shifts the value to
+the right.
+
+Examples:
+* `( 0b0111 : Int) >>> 1 =  0b0011`
+* `( 0b1000 : Int) >>> 1 =  0b0100`
+* `(-0b1000 : Int) >>> 1 = -0b0100`
+* `(-0b0111 : Int) >>> 1 = -0b0100`
+-/
+protected def shiftRight : Int → Nat → Int
+  | Int.ofNat n, s => Int.ofNat (n >>> s)
+  | Int.negSucc n, s => Int.negSucc (n >>> s)
+
+instance : HShiftRight Int Nat Int := ⟨.shiftRight⟩
+
+end Int

src/Init/Data/Int/Bitwise/Lemmas.lean

@@ -5,11 +5,13 @@ Authors: Siddharth Bhat, Jeremy Avigad
 -/
 prelude
 import Init.Data.Nat.Bitwise.Lemmas
-import Init.Data.Int.Bitwise
+import Init.Data.Int.Bitwise.Basic
+import Init.Data.Int.DivMod.Lemmas
 
 namespace Int
 
 theorem shiftRight_eq (n : Int) (s : Nat) : n >>> s = Int.shiftRight n s := rfl
+
 @[simp]
 theorem natCast_shiftRight (n s : Nat) : (n : Int) >>> s = n >>> s := rfl
 
@@ -26,7 +28,7 @@ theorem shiftRight_eq_div_pow (m : Int) (n : Nat) :
     m >>> n = m / ((2 ^ n) : Nat) := by
   simp only [shiftRight_eq, Int.shiftRight, Nat.shiftRight_eq_div_pow]
   split
-  · simp
+  · simp; norm_cast
   · rw [negSucc_ediv _ (by norm_cast; exact Nat.pow_pos (Nat.zero_lt_two))]
     rfl
 
@@ -38,4 +40,47 @@ theorem zero_shiftRight (n : Nat) : (0 : Int) >>> n = 0 := by
 theorem shiftRight_zero (n : Int) : n >>> 0 = n := by
   simp [Int.shiftRight_eq_div_pow]
 
+theorem le_shiftRight_of_nonpos {n : Int} {s : Nat} (h : n ≤ 0) : n ≤ n >>> s := by
+  simp only [Int.shiftRight_eq, Int.shiftRight, Int.ofNat_eq_coe]
+  split
+  case _ _ _ m =>
+    simp only [ofNat_eq_coe] at h
+    by_cases hm : m = 0
+    · simp [hm]
+    · omega
+  case _ _ _ m =>
+    by_cases hm : m = 0
+    · simp [hm]
+    · have := Nat.shiftRight_le m s
+      omega
+
+theorem shiftRight_le_of_nonneg {n : Int} {s : Nat} (h : 0 ≤ n) : n >>> s ≤ n := by
+  simp only [Int.shiftRight_eq, Int.shiftRight, Int.ofNat_eq_coe]
+  split
+  case _ _ _ m =>
+    simp only [Int.ofNat_eq_coe] at h
+    by_cases hm : m = 0
+    · simp [hm]
+    · have := Nat.shiftRight_le m s
+      simp
+      omega
+  case _ _ _ m =>
+    omega
+
+theorem le_shiftRight_of_nonneg {n : Int} {s : Nat} (h : 0 ≤ n) : 0 ≤ (n >>> s) := by
+  rw [Int.shiftRight_eq_div_pow]
+  by_cases h' : s = 0
+  · simp [h', h]
+  · have := @Nat.pow_pos 2 s (by omega)
+    have := @Int.ediv_nonneg n (2^s) h (by norm_cast at *; omega)
+    norm_cast at *
+
+theorem shiftRight_le_of_nonpos {n : Int} {s : Nat} (h : n ≤ 0) : (n >>> s) ≤ 0 := by
+  rw [Int.shiftRight_eq_div_pow]
+  by_cases h' : s = 0
+  · simp [h', h]
+  · have : 1 < 2 ^ s := Nat.one_lt_two_pow (by omega)
+    have rl : n / 2 ^ s ≤ 0 := Int.ediv_nonpos_of_nonpos_of_neg (by omega) (by norm_cast at *; omega)
+    norm_cast at *
+
 end Int

src/Init/Data/Int/Cooper.lean

@@ -4,7 +4,7 @@ Released under Apache 2.0 license as described in the file LICENSE.
 Authors: Kim Morrison
 -/
 prelude
-import Init.Data.Int.DivModLemmas
+import Init.Data.Int.DivMod.Lemmas
 import Init.Data.Int.Gcd
 
 /-!
@@ -99,7 +99,7 @@ def resolve_left' (a c d p x : Int) (h₁ : p ≤ a * x) : Nat := (add_of_le h
 /-- `resolve_left` is nonnegative when `p ≤ a * x`. -/
 theorem le_zero_resolve_left (a c d p x : Int) (h₁ : p ≤ a * x) :
     0 ≤ resolve_left a c d p x := by
-  simpa [h₁] using Int.ofNat_nonneg _
+  simp [h₁]
 
 /-- `resolve_left` is bounded above by `lcm a (a * d / gcd (a * d) c)`. -/
 theorem resolve_left_lt_lcm (a c d p x : Int) (a_pos : 0 < a) (d_pos : 0 < d) (h₁ : p ≤ a * x) :
@@ -227,33 +227,4 @@ theorem cooper_resolution_dvd_right
     · exact Int.mul_neg _ _ ▸ Int.neg_le_of_neg_le lower
     · exact Int.mul_neg _ _ ▸ Int.neg_mul _ _ ▸ dvd
 
-/--
-Left Cooper resolution of an upper and lower bound.
--/
-theorem cooper_resolution_left
-    {a b p q : Int} (a_pos : 0 < a) (b_pos : 0 < b) :
-    (∃ x, p ≤ a * x ∧ b * x ≤ q) ↔
-    (∃ k : Int, 0 ≤ k ∧ k < a ∧ b * k + b * p ≤ a * q ∧ a ∣ k + p) := by
-  have h := cooper_resolution_dvd_left
-    a_pos b_pos Int.zero_lt_one (c := 1) (s := 0) (p := p) (q := q)
-  simp only [Int.mul_one, Int.one_mul, Int.mul_zero, Int.add_zero, gcd_one, Int.ofNat_one,
-    Int.ediv_one, lcm_self, Int.natAbs_of_nonneg (Int.le_of_lt a_pos), Int.one_dvd, and_true,
-    and_self] at h
-  exact h
-
-/--
-Right Cooper resolution of an upper and lower bound.
--/
-theorem cooper_resolution_right
-    {a b p q : Int} (a_pos : 0 < a) (b_pos : 0 < b) :
-    (∃ x, p ≤ a * x ∧ b * x ≤ q) ↔
-    (∃ k : Int, 0 ≤ k ∧ k < b ∧ a * k + b * p ≤ a * q ∧ b ∣ k - q) := by
-  have h := cooper_resolution_dvd_right
-    a_pos b_pos Int.zero_lt_one (c := 1) (s := 0) (p := p) (q := q)
-  have : ∀ k : Int, (b ∣ -k + q) ↔ (b ∣ k - q) := by
-    intro k
-    rw [← Int.dvd_neg, Int.neg_add, Int.neg_neg, Int.sub_eq_add_neg]
-  simp only [Int.mul_one, Int.one_mul, Int.mul_zero, Int.add_zero, gcd_one, Int.ofNat_one,
-    Int.ediv_one, lcm_self, Int.natAbs_of_nonneg (Int.le_of_lt b_pos), Int.one_dvd, and_true,
-    and_self, ← Int.neg_eq_neg_one_mul, this] at h
-  exact h
+end Int

src/Init/Data/Int/DivMod.lean

@@ -1,328 +1,9 @@
 /-
-Copyright (c) 2016 Jeremy Avigad. All rights reserved.
+Copyright (c) 2025 Lean FRO, LLC. All rights reserved.
 Released under Apache 2.0 license as described in the file LICENSE.
-Authors: Jeremy Avigad, Mario Carneiro
+Authors: Kim Morrison
 -/
 prelude
-import Init.Data.Int.Basic
-
-open Nat
-
-namespace Int
-
-/-! ## Quotient and remainder
-
-There are three main conventions for integer division,
-referred here as the E, F, T rounding conventions.
-All three pairs satisfy the identity `x % y + (x / y) * y = x` unconditionally,
-and satisfy `x / 0 = 0` and `x % 0 = x`.
-
-### Historical notes
-In early versions of Lean, the typeclasses provided by `/` and `%`
-were defined in terms of `tdiv` and `tmod`, and these were named simply as `div` and `mod`.
-
-However we decided it was better to use `ediv` and `emod`,
-as they are consistent with the conventions used in SMTLib, and Mathlib,
-and often mathematical reasoning is easier with these conventions.
-
-At that time, we did not rename `div` and `mod` to `tdiv` and `tmod` (along with all their lemma).
-In September 2024, we decided to do this rename (with deprecations in place),
-and later we intend to rename `ediv` and `emod` to `div` and `mod`, as nearly all users will only
-ever need to use these functions and their associated lemmas.
-
-In December 2024, we removed `tdiv` and `tmod`, but have not yet renamed `ediv` and `emod`.
--/
-
-/-! ### T-rounding division -/
-
-/--
-`tdiv` uses the [*"T-rounding"*][t-rounding]
-(**T**runcation-rounding) convention, meaning that it rounds toward
-zero. Also note that division by zero is defined to equal zero.
-
-  The relation between integer division and modulo is found in
-  `Int.tmod_add_tdiv` which states that
-  `tmod a b + b * (tdiv a b) = a`, unconditionally.
-
-  [t-rounding]: https://dl.acm.org/doi/pdf/10.1145/128861.128862
-  [theo tmod_add_tdiv]: https://leanprover-community.github.io/mathlib4_docs/find/?pattern=Int.tmod_add_tdiv#doc
-
-  Examples:
-
-  ```
-  #eval (7 : Int).tdiv (0 : Int) -- 0
-  #eval (0 : Int).tdiv (7 : Int) -- 0
-
-  #eval (12 : Int).tdiv (6 : Int) -- 2
-  #eval (12 : Int).tdiv (-6 : Int) -- -2
-  #eval (-12 : Int).tdiv (6 : Int) -- -2
-  #eval (-12 : Int).tdiv (-6 : Int) -- 2
-
-  #eval (12 : Int).tdiv (7 : Int) -- 1
-  #eval (12 : Int).tdiv (-7 : Int) -- -1
-  #eval (-12 : Int).tdiv (7 : Int) -- -1
-  #eval (-12 : Int).tdiv (-7 : Int) -- 1
-  ```
-
-  Implemented by efficient native code.
--/
-@[extern "lean_int_div"]
-def tdiv : (@& Int) → (@& Int) → Int
-  | ofNat m, ofNat n =>  ofNat (m / n)
-  | ofNat m, -[n +1] => -ofNat (m / succ n)
-  | -[m +1], ofNat n => -ofNat (succ m / n)
-  | -[m +1], -[n +1] =>  ofNat (succ m / succ n)
-
-/-- Integer modulo. This function uses the
-  [*"T-rounding"*][t-rounding] (**T**runcation-rounding) convention
-  to pair with `Int.tdiv`, meaning that `tmod a b + b * (tdiv a b) = a`
-  unconditionally (see [`Int.tmod_add_tdiv`][theo tmod_add_tdiv]). In
-  particular, `a % 0 = a`.
-
-  [t-rounding]: https://dl.acm.org/doi/pdf/10.1145/128861.128862
-  [theo tmod_add_tdiv]: https://leanprover-community.github.io/mathlib4_docs/find/?pattern=Int.tmod_add_tdiv#doc
-
-  Examples:
-
-  ```
-  #eval (7 : Int).tmod (0 : Int) -- 7
-  #eval (0 : Int).tmod (7 : Int) -- 0
-
-  #eval (12 : Int).tmod (6 : Int) -- 0
-  #eval (12 : Int).tmod (-6 : Int) -- 0
-  #eval (-12 : Int).tmod (6 : Int) -- 0
-  #eval (-12 : Int).tmod (-6 : Int) -- 0
-
-  #eval (12 : Int).tmod (7 : Int) -- 5
-  #eval (12 : Int).tmod (-7 : Int) -- 5
-  #eval (-12 : Int).tmod (7 : Int) -- -5
-  #eval (-12 : Int).tmod (-7 : Int) -- -5
-  ```
-
-  Implemented by efficient native code. -/
-@[extern "lean_int_mod"]
-def tmod : (@& Int) → (@& Int) → Int
-  | ofNat m, ofNat n =>  ofNat (m % n)
-  | ofNat m, -[n +1] =>  ofNat (m % succ n)
-  | -[m +1], ofNat n => -ofNat (succ m % n)
-  | -[m +1], -[n +1] => -ofNat (succ m % succ n)
-
-/-! ### F-rounding division
-This pair satisfies `fdiv x y = floor (x / y)`.
--/
-
-/--
-Integer division. This version of division uses the F-rounding convention
-(flooring division), in which `Int.fdiv x y` satisfies `fdiv x y = floor (x / y)`
-and `Int.fmod` is the unique function satisfying `fmod x y + (fdiv x y) * y = x`.
-
-Examples:
-```
-#eval (7 : Int).fdiv (0 : Int) -- 0
-#eval (0 : Int).fdiv (7 : Int) -- 0
-
-#eval (12 : Int).fdiv (6 : Int) -- 2
-#eval (12 : Int).fdiv (-6 : Int) -- -2
-#eval (-12 : Int).fdiv (6 : Int) -- -2
-#eval (-12 : Int).fdiv (-6 : Int) -- 2
-
-#eval (12 : Int).fdiv (7 : Int) -- 1
-#eval (12 : Int).fdiv (-7 : Int) -- -2
-#eval (-12 : Int).fdiv (7 : Int) -- -2
-#eval (-12 : Int).fdiv (-7 : Int) -- 1
-```
--/
-def fdiv : Int → Int → Int
-  | 0,       _       => 0
-  | ofNat m, ofNat n => ofNat (m / n)
-  | ofNat (succ m), -[n+1] => -[m / succ n +1]
-  | -[_+1],  0       => 0
-  | -[m+1],  ofNat (succ n) => -[m / succ n +1]
-  | -[m+1],  -[n+1]  => ofNat (succ m / succ n)
-
-/--
-Integer modulus. This version of `Int.mod` uses the F-rounding convention
-(flooring division), in which `Int.fdiv x y` satisfies `fdiv x y = floor (x / y)`
-and `Int.fmod` is the unique function satisfying `fmod x y + (fdiv x y) * y = x`.
-
-Examples:
-
-```
-#eval (7 : Int).fmod (0 : Int) -- 7
-#eval (0 : Int).fmod (7 : Int) -- 0
-
-#eval (12 : Int).fmod (6 : Int) -- 0
-#eval (12 : Int).fmod (-6 : Int) -- 0
-#eval (-12 : Int).fmod (6 : Int) -- 0
-#eval (-12 : Int).fmod (-6 : Int) -- 0
-
-#eval (12 : Int).fmod (7 : Int) -- 5
-#eval (12 : Int).fmod (-7 : Int) -- -2
-#eval (-12 : Int).fmod (7 : Int) -- 2
-#eval (-12 : Int).fmod (-7 : Int) -- -5
-```
--/
-def fmod : Int → Int → Int
-  | 0,       _       => 0
-  | ofNat m, ofNat n => ofNat (m % n)
-  | ofNat (succ m),  -[n+1]  => subNatNat (m % succ n) n
-  | -[m+1],  ofNat n => subNatNat n (succ (m % n))
-  | -[m+1],  -[n+1]  => -ofNat (succ m % succ n)
-
-/-! ### E-rounding division
-This pair satisfies `0 ≤ mod x y < natAbs y` for `y ≠ 0`.
--/
-
-/--
-Integer division. This version of `Int.div` uses the E-rounding convention
-(euclidean division), in which `Int.emod x y` satisfies `0 ≤ mod x y < natAbs y` for `y ≠ 0`
-and `Int.ediv` is the unique function satisfying `emod x y + (ediv x y) * y = x`.
-
-This is the function powering the `/` notation on integers.
-
-Examples:
-```
-#eval (7 : Int) / (0 : Int) -- 0
-#eval (0 : Int) / (7 : Int) -- 0
-
-#eval (12 : Int) / (6 : Int) -- 2
-#eval (12 : Int) / (-6 : Int) -- -2
-#eval (-12 : Int) / (6 : Int) -- -2
-#eval (-12 : Int) / (-6 : Int) -- 2
-
-#eval (12 : Int) / (7 : Int) -- 1
-#eval (12 : Int) / (-7 : Int) -- -1
-#eval (-12 : Int) / (7 : Int) -- -2
-#eval (-12 : Int) / (-7 : Int) -- 2
-```
-
-Implemented by efficient native code.
--/
-@[extern "lean_int_ediv"]
-def ediv : (@& Int) → (@& Int) → Int
-  | ofNat m, ofNat n => ofNat (m / n)
-  | ofNat m, -[n+1]  => -ofNat (m / succ n)
-  | -[_+1],  0       => 0
-  | -[m+1],  ofNat (succ n) => -[m / succ n +1]
-  | -[m+1],  -[n+1]  => ofNat (succ (m / succ n))
-
-/--
-Integer modulus. This version of `Int.mod` uses the E-rounding convention
-(euclidean division), in which `Int.emod x y` satisfies `0 ≤ emod x y < natAbs y` for `y ≠ 0`
-and `Int.ediv` is the unique function satisfying `emod x y + (ediv x y) * y = x`.
-
-This is the function powering the `%` notation on integers.
-
-Examples:
-```
-#eval (7 : Int) % (0 : Int) -- 7
-#eval (0 : Int) % (7 : Int) -- 0
-
-#eval (12 : Int) % (6 : Int) -- 0
-#eval (12 : Int) % (-6 : Int) -- 0
-#eval (-12 : Int) % (6 : Int) -- 0
-#eval (-12 : Int) % (-6 : Int) -- 0
-
-#eval (12 : Int) % (7 : Int) -- 5
-#eval (12 : Int) % (-7 : Int) -- 5
-#eval (-12 : Int) % (7 : Int) -- 2
-#eval (-12 : Int) % (-7 : Int) -- 2
-```
-
-Implemented by efficient native code.
--/
-@[extern "lean_int_emod"]
-def emod : (@& Int) → (@& Int) → Int
-  | ofNat m, n => ofNat (m % natAbs n)
-  | -[m+1],  n => subNatNat (natAbs n) (succ (m % natAbs n))
-
-/--
-The Div and Mod syntax uses ediv and emod for compatibility with SMTLIb and mathematical
-reasoning tends to be easier.
--/
-instance : Div Int where
-  div := Int.ediv
-instance : Mod Int where
-  mod := Int.emod
-
-@[simp, norm_cast] theorem ofNat_ediv (m n : Nat) : (↑(m / n) : Int) = ↑m / ↑n := rfl
-
-theorem ofNat_tdiv (m n : Nat) : ↑(m / n) = tdiv ↑m ↑n := rfl
-
-theorem ofNat_fdiv : ∀ m n : Nat, ↑(m / n) = fdiv ↑m ↑n
-  | 0, _ => by simp [fdiv]
-  | succ _, _ => rfl
-
-/-!
-# `bmod` ("balanced" mod)
-
-Balanced mod (and balanced div) are a division and modulus pair such
-that `b * (Int.bdiv a b) + Int.bmod a b = a` and `-b/2 ≤ Int.bmod a b <
-b/2` for all `a : Int` and `b > 0`.
-
-This is used in Omega as well as signed bitvectors.
--/
-
-/--
-Balanced modulus.  This version of Integer modulus uses the
-balanced rounding convention, which guarantees that
-`-m/2 ≤ bmod x m < m/2` for `m ≠ 0` and `bmod x m` is congruent
-to `x` modulo `m`.
-
-If `m = 0`, then `bmod x m = x`.
-
-Examples:
-```
-#eval (7 : Int).bdiv 0 -- 0
-#eval (0 : Int).bdiv 7 -- 0
-
-#eval (12 : Int).bdiv 6 -- 2
-#eval (12 : Int).bdiv 7 -- 2
-#eval (12 : Int).bdiv 8 -- 2
-#eval (12 : Int).bdiv 9 -- 1
-
-#eval (-12 : Int).bdiv 6 -- -2
-#eval (-12 : Int).bdiv 7 -- -2
-#eval (-12 : Int).bdiv 8 -- -1
-#eval (-12 : Int).bdiv 9 -- -1
-```
--/
-def bmod (x : Int) (m : Nat) : Int :=
-  let r := x % m
-  if r < (m + 1) / 2 then
-    r
-  else
-    r - m
-
-/--
-Balanced division.  This returns the unique integer so that
-`b * (Int.bdiv a b) + Int.bmod a b = a`.
-
-Examples:
-```
-#eval (7 : Int).bmod 0 -- 7
-#eval (0 : Int).bmod 7 -- 0
-
-#eval (12 : Int).bmod 6 -- 0
-#eval (12 : Int).bmod 7 -- -2
-#eval (12 : Int).bmod 8 -- -4
-#eval (12 : Int).bmod 9 -- 3
-
-#eval (-12 : Int).bmod 6 -- 0
-#eval (-12 : Int).bmod 7 -- 2
-#eval (-12 : Int).bmod 8 -- -4
-#eval (-12 : Int).bmod 9 -- -3
-```
--/
-def bdiv (x : Int) (m : Nat) : Int :=
-  if m = 0 then
-    0
-  else
-    let q := x / m
-    let r := x % m
-    if r < (m + 1) / 2 then
-      q
-    else
-      q + 1
-
-end Int
+import Init.Data.Int.DivMod.Basic
+import Init.Data.Int.DivMod.Bootstrap
+import Init.Data.Int.DivMod.Lemmas

src/Init/Data/Int/DivMod/Basic.lean

@@ -0,0 +1,321 @@
+/-
+Copyright (c) 2016 Jeremy Avigad. All rights reserved.
+Released under Apache 2.0 license as described in the file LICENSE.
+Authors: Jeremy Avigad, Mario Carneiro
+-/
+prelude
+import Init.Data.Int.Basic
+
+open Nat
+
+namespace Int
+
+/-! ## Quotient and remainder
+
+There are three main conventions for integer division,
+referred here as the E, F, T rounding conventions.
+All three pairs satisfy the identity `x % y + (x / y) * y = x` unconditionally,
+and satisfy `x / 0 = 0` and `x % 0 = x`.
+
+### Historical notes
+In early versions of Lean, the typeclasses provided by `/` and `%`
+were defined in terms of `tdiv` and `tmod`, and these were named simply as `div` and `mod`.
+
+However we decided it was better to use `ediv` and `emod` for the default typeclass instances,
+as they are consistent with the conventions used in SMT-LIB, and Mathlib,
+and often mathematical reasoning is easier with these conventions.
+At that time, we did not rename `div` and `mod` to `tdiv` and `tmod` (along with all their lemma).
+
+In September 2024, we decided to do this rename (with deprecations in place),
+and later we intend to rename `ediv` and `emod` to `div` and `mod`, as nearly all users will only
+ever need to use these functions and their associated lemmas.
+
+In December 2024, we removed `div` and `mod`, but have not yet renamed `ediv` and `emod`.
+-/
+
+/-! ### E-rounding division
+This pair satisfies `0 ≤ emod x y < natAbs y` for `y ≠ 0`.
+-/
+
+/--
+Integer division that uses the E-rounding convention. Usually accessed via the `/` operator.
+Division by zero is defined to be zero, rather than an error.
+
+In the E-rounding convention (Euclidean division), `Int.emod x y` satisfies `0 ≤ Int.emod x y < Int.natAbs y`
+for `y ≠ 0` and `Int.ediv` is the unique function satisfying `Int.emod x y + (Int.edivx y) * y = x`
+for `y ≠ 0`.
+
+This means that `Int.ediv x y` is `⌊x / y⌋` when `y > 0` and `⌈x / y⌉` when `y < 0`.
+
+This function is overridden by the compiler with an efficient implementation. This definition is
+the logical model.
+
+Examples:
+* `(7 : Int) / (0 : Int) = 0`
+* `(0 : Int) / (7 : Int) = 0`
+* `(12 : Int) / (6 : Int) = 2`
+* `(12 : Int) / (-6 : Int) = -2`
+* `(-12 : Int) / (6 : Int) = -2`
+* `(-12 : Int) / (-6 : Int) = 2`
+* `(12 : Int) / (7 : Int) = 1`
+* `(12 : Int) / (-7 : Int) = -1`
+* `(-12 : Int) / (7 : Int) = -2`
+* `(-12 : Int) / (-7 : Int) = 2`
+-/
+@[extern "lean_int_ediv"]
+def ediv : (@& Int) → (@& Int) → Int
+  | ofNat m, ofNat n => ofNat (m / n)
+  | ofNat m, -[n+1]  => -ofNat (m / succ n)
+  | -[_+1],  0       => 0
+  | -[m+1],  ofNat (succ n) => -[m / succ n +1]
+  | -[m+1],  -[n+1]  => ofNat (succ (m / succ n))
+
+/--
+Integer modulus that uses the E-rounding convention. Usually accessed via the `%` operator.
+
+In the E-rounding convention (Euclidean division), `Int.emod x y` satisfies `0 ≤ Int.emod x y < Int.natAbs y`
+for `y ≠ 0` and `Int.ediv` is the unique function satisfying `Int.emod x y + (Int.edivx y) * y = x`
+for `y ≠ 0`.
+
+This function is overridden by the compiler with an efficient implementation. This definition is
+the logical model.
+
+Examples:
+* `(7 : Int) % (0 : Int) = 7`
+* `(0 : Int) % (7 : Int) = 0`
+* `(12 : Int) % (6 : Int) = 0`
+* `(12 : Int) % (-6 : Int) = 0`
+* `(-12 : Int) % (6 : Int) = 0`
+* `(-12 : Int) % (-6 : Int) = 0`
+* `(12 : Int) % (7 : Int) = 5`
+* `(12 : Int) % (-7 : Int) = 5`
+* `(-12 : Int) % (7 : Int) = 2`
+* `(-12 : Int) % (-7 : Int) = 2`
+-/
+@[extern "lean_int_emod"]
+def emod : (@& Int) → (@& Int) → Int
+  | ofNat m, n => ofNat (m % natAbs n)
+  | -[m+1],  n => subNatNat (natAbs n) (succ (m % natAbs n))
+
+/--
+The `Div Int` and `Mod Int` instances use `Int.ediv` and `Int.emod` for compatibility with SMT-LIB and
+because mathematical reasoning tends to be easier.
+-/
+instance : Div Int where
+  div := Int.ediv
+/--
+The `Div Int` and `Mod Int` instances use `Int.ediv` and `Int.emod` for compatibility with SMT-LIB and
+because mathematical reasoning tends to be easier.
+-/
+instance : Mod Int where
+  mod := Int.emod
+
+@[norm_cast] theorem ofNat_ediv (m n : Nat) : (↑(m / n) : Int) = ↑m / ↑n := rfl
+
+theorem ofNat_ediv_ofNat {a b : Nat} : (↑a / ↑b : Int) = (a / b : Nat) := rfl
+@[norm_cast]
+theorem negSucc_ediv_ofNat_succ {a b : Nat} : ((-[a+1]) / ↑(b+1) : Int) = -[a / succ b +1] := rfl
+theorem negSucc_ediv_negSucc {a b : Nat} : ((-[a+1]) / (-[b+1]) : Int) = ((a / (b + 1)) + 1 : Nat) := rfl
+theorem ofNat_ediv_negSucc {a b : Nat} : (ofNat a / (-[b+1])) = -(a / (b + 1) : Nat) := rfl
+theorem negSucc_emod_ofNat {a b : Nat} : -[a+1] % (b : Int) = subNatNat b (succ (a % b)) := rfl
+theorem negSucc_emod_negSucc {a b : Nat} : -[a+1] % -[b+1] = subNatNat (b + 1) (succ (a % (b + 1))) := rfl
+
+/-! ### T-rounding division -/
+
+/--
+Integer division using the T-rounding convention.
+
+In [the T-rounding convention][t-rounding] (division with truncation), all rounding is towards zero.
+Division by 0 is defined to be 0. In this convention, `Int.tmod a b + b * (Int.tdiv a b) = a`.
+
+[t-rounding]: https://dl.acm.org/doi/pdf/10.1145/128861.128862
+
+This function is overridden by the compiler with an efficient implementation. This definition is the
+logical model.
+
+Examples:
+* `(7 : Int).tdiv (0 : Int) = 0`
+* `(0 : Int).tdiv (7 : Int) = 0`
+* `(12 : Int).tdiv (6 : Int) = 2`
+* `(12 : Int).tdiv (-6 : Int) = -2`
+* `(-12 : Int).tdiv (6 : Int) = -2`
+* `(-12 : Int).tdiv (-6 : Int) = 2`
+* `(12 : Int).tdiv (7 : Int) = 1`
+* `(12 : Int).tdiv (-7 : Int) = -1`
+* `(-12 : Int).tdiv (7 : Int) = -1`
+* `(-12 : Int).tdiv (-7 : Int) = 1`
+-/
+@[extern "lean_int_div"]
+def tdiv : (@& Int) → (@& Int) → Int
+  | ofNat m, ofNat n =>  ofNat (m / n)
+  | ofNat m, -[n +1] => -ofNat (m / succ n)
+  | -[m +1], ofNat n => -ofNat (succ m / n)
+  | -[m +1], -[n +1] =>  ofNat (succ m / succ n)
+
+/-- Integer modulo using the T-rounding convention.
+
+In [the T-rounding convention][t-rounding] (division with truncation), all rounding is towards zero.
+Division by 0 is defined to be 0 and `Int.tmod a 0 = a`.
+
+In this convention, `Int.tmod a b + b * (Int.tdiv a b) = a`. Additionally,
+`Int.natAbs (Int.tmod a b) = Int.natAbs a % Int.natAbs b`, and when `b` does not divide `a`,
+`Int.tmod a b` has the same sign as `a`.
+
+[t-rounding]: https://dl.acm.org/doi/pdf/10.1145/128861.128862
+
+This function is overridden by the compiler with an efficient implementation. This definition is the
+logical model.
+
+Examples:
+* `(7 : Int).tmod (0 : Int) = 7`
+* `(0 : Int).tmod (7 : Int) = 0`
+* `(12 : Int).tmod (6 : Int) = 0`
+* `(12 : Int).tmod (-6 : Int) = 0`
+* `(-12 : Int).tmod (6 : Int) = 0`
+* `(-12 : Int).tmod (-6 : Int) = 0`
+* `(12 : Int).tmod (7 : Int) = 5`
+* `(12 : Int).tmod (-7 : Int) = 5`
+* `(-12 : Int).tmod (7 : Int) = -5`
+* `(-12 : Int).tmod (-7 : Int) = -5`
+-/
+@[extern "lean_int_mod"]
+def tmod : (@& Int) → (@& Int) → Int
+  | ofNat m, ofNat n =>  ofNat (m % n)
+  | ofNat m, -[n +1] =>  ofNat (m % succ n)
+  | -[m +1], ofNat n => -ofNat (succ m % n)
+  | -[m +1], -[n +1] => -ofNat (succ m % succ n)
+
+theorem ofNat_tdiv (m n : Nat) : ↑(m / n) = tdiv ↑m ↑n := rfl
+
+/-! ### F-rounding division
+This pair satisfies `fdiv x y = floor (x / y)`.
+-/
+
+/--
+Integer division using the F-rounding convention.
+
+In the F-rounding convention (flooring division), `Int.fdiv x y` satisfies `Int.fdiv x y = ⌊x / y⌋`
+and `Int.fmod` is the unique function satisfying `Int.fmod x y + (Int.fdiv x y) * y = x`.
+
+Examples:
+* `(7 : Int).fdiv (0 : Int) = 0`
+* `(0 : Int).fdiv (7 : Int) = 0`
+* `(12 : Int).fdiv (6 : Int) = 2`
+* `(12 : Int).fdiv (-6 : Int) = -2`
+* `(-12 : Int).fdiv (6 : Int) = -2`
+* `(-12 : Int).fdiv (-6 : Int) = 2`
+* `(12 : Int).fdiv (7 : Int) = 1`
+* `(12 : Int).fdiv (-7 : Int) = -2`
+* `(-12 : Int).fdiv (7 : Int) = -2`
+* `(-12 : Int).fdiv (-7 : Int) = 1`
+-/
+def fdiv : Int → Int → Int
+  | 0,       _       => 0
+  | ofNat m, ofNat n => ofNat (m / n)
+  | ofNat (succ m), -[n+1] => -[m / succ n +1]
+  | -[_+1],  0       => 0
+  | -[m+1],  ofNat (succ n) => -[m / succ n +1]
+  | -[m+1],  -[n+1]  => ofNat (succ m / succ n)
+
+/--
+Integer modulus using the F-rounding convention.
+
+In the F-rounding convention (flooring division), `Int.fdiv x y` satisfies `Int.fdiv x y = ⌊x / y⌋`
+and `Int.fmod` is the unique function satisfying `Int.fmod x y + (Int.fdiv x y) * y = x`.
+
+Examples:
+
+* `(7 : Int).fmod (0 : Int) = 7`
+* `(0 : Int).fmod (7 : Int) = 0`
+
+* `(12 : Int).fmod (6 : Int) = 0`
+* `(12 : Int).fmod (-6 : Int) = 0`
+* `(-12 : Int).fmod (6 : Int) = 0`
+* `(-12 : Int).fmod (-6 : Int) = 0`
+
+* `(12 : Int).fmod (7 : Int) = 5`
+* `(12 : Int).fmod (-7 : Int) = -2`
+* `(-12 : Int).fmod (7 : Int) = 2`
+* `(-12 : Int).fmod (-7 : Int) = -5`
+
+-/
+def fmod : Int → Int → Int
+  | 0,       _       => 0
+  | ofNat m, ofNat n => ofNat (m % n)
+  | ofNat (succ m),  -[n+1]  => subNatNat (m % succ n) n
+  | -[m+1],  ofNat n => subNatNat n (succ (m % n))
+  | -[m+1],  -[n+1]  => -ofNat (succ m % succ n)
+
+theorem ofNat_fdiv : ∀ m n : Nat, ↑(m / n) = fdiv ↑m ↑n
+  | 0, _ => by simp [fdiv]
+  | succ _, _ => rfl
+
+/-!
+# `bmod` ("balanced" mod)
+
+Balanced mod (and balanced div) are a division and modulus pair such
+that `b * (Int.bdiv a b) + Int.bmod a b = a` and
+`-b/2 ≤ Int.bmod a b < b/2` for all `a : Int` and `b > 0`.
+
+Note that unlike `emod`, `fmod`, and `tmod`,
+`bmod` takes a natural number as the second argument, rather than an integer.
+
+This function is used in `omega` as well as signed bitvectors.
+-/
+
+/--
+Balanced modulus.
+
+This version of integer modulus uses the balanced rounding convention, which guarantees that
+`-m / 2 ≤ Int.bmod x m < m/2` for `m ≠ 0` and `Int.bmod x m` is congruent to `x` modulo `m`.
+
+If `m = 0`, then `Int.bmod x m = x`.
+
+Examples:
+* `(7 : Int).bmod 0 = 7`
+* `(0 : Int).bmod 7 = 0`
+* `(12 : Int).bmod 6 = 0`
+* `(12 : Int).bmod 7 = -2`
+* `(12 : Int).bmod 8 = -4`
+* `(12 : Int).bmod 9 = 3`
+* `(-12 : Int).bmod 6 = 0`
+* `(-12 : Int).bmod 7 = 2`
+* `(-12 : Int).bmod 8 = -4`
+* `(-12 : Int).bmod 9 = -3`
+-/
+def bmod (x : Int) (m : Nat) : Int :=
+  let r := x % m
+  if r < (m + 1) / 2 then
+    r
+  else
+    r - m
+
+/--
+Balanced division.
+
+This returns the unique integer so that `b * (Int.bdiv a b) + Int.bmod a b = a`.
+
+Examples:
+* `(7 : Int).bdiv 0 = 0`
+* `(0 : Int).bdiv 7 = 0`
+* `(12 : Int).bdiv 6 = 2`
+* `(12 : Int).bdiv 7 = 2`
+* `(12 : Int).bdiv 8 = 2`
+* `(12 : Int).bdiv 9 = 1`
+* `(-12 : Int).bdiv 6 = -2`
+* `(-12 : Int).bdiv 7 = -2`
+* `(-12 : Int).bdiv 8 = -1`
+* `(-12 : Int).bdiv 9 = -1`
+-/
+def bdiv (x : Int) (m : Nat) : Int :=
+  if m = 0 then
+    0
+  else
+    let q := x / m
+    let r := x % m
+    if r < (m + 1) / 2 then
+      q
+    else
+      q + 1
+
+end Int

src/Init/Data/Int/DivMod/Bootstrap.lean

@@ -0,0 +1,333 @@
+/-
+Copyright (c) 2016 Jeremy Avigad. All rights reserved.
+Released under Apache 2.0 license as described in the file LICENSE.
+Authors: Jeremy Avigad, Mario Carneiro
+-/
+
+prelude
+import Init.Data.Int.DivMod.Basic
+import Init.Data.Int.Order
+import Init.Data.Nat.Dvd
+import Init.RCases
+
+/-!
+# Lemmas about integer division needed to bootstrap `omega`.
+-/
+
+open Nat (succ)
+
+namespace Int
+
+/-! ### dvd  -/
+
+protected theorem dvd_def (a b : Int) : (a ∣ b) = Exists (fun c => b = a * c) := rfl
+
+@[simp] protected theorem dvd_zero (n : Int) : n ∣ 0 := ⟨0, (Int.mul_zero _).symm⟩
+
+@[simp] protected theorem dvd_refl (n : Int) : n ∣ n := ⟨1, (Int.mul_one _).symm⟩
+
+@[simp] protected theorem one_dvd (n : Int) : 1 ∣ n := ⟨n, (Int.one_mul n).symm⟩
+
+protected theorem dvd_trans : ∀ {a b c : Int}, a ∣ b → b ∣ c → a ∣ c
+  | _, _, _, ⟨d, rfl⟩, ⟨e, rfl⟩ => Exists.intro (d * e) (by rw [Int.mul_assoc])
+
+@[norm_cast] theorem ofNat_dvd {m n : Nat} : (↑m : Int) ∣ ↑n ↔ m ∣ n := by
+  refine ⟨fun ⟨a, ae⟩ => ?_, fun ⟨k, e⟩ => ⟨k, by rw [e, Int.ofNat_mul]⟩⟩
+  match Int.le_total a 0 with
+  | .inl h =>
+    have := ae.symm ▸ Int.mul_nonpos_of_nonneg_of_nonpos (ofNat_zero_le _) h
+    rw [Nat.le_antisymm (ofNat_le.1 this) (Nat.zero_le _)]
+    apply Nat.dvd_zero
+  | .inr h => match a, eq_ofNat_of_zero_le h with
+    | _, ⟨k, rfl⟩ => exact ⟨k, Int.ofNat.inj ae⟩
+
+@[simp] protected theorem zero_dvd {n : Int} : 0 ∣ n ↔ n = 0 :=
+  Iff.intro (fun ⟨k, e⟩ => by rw [e, Int.zero_mul])
+            (fun h => h.symm ▸ Int.dvd_refl _)
+
+protected theorem dvd_mul_right (a b : Int) : a ∣ a * b := ⟨_, rfl⟩
+
+protected theorem dvd_mul_left (a b : Int) : b ∣ a * b := ⟨_, Int.mul_comm ..⟩
+
+@[simp] protected theorem neg_dvd {a b : Int} : -a ∣ b ↔ a ∣ b := by
+  constructor <;> exact fun ⟨k, e⟩ =>
+    ⟨-k, by simp [e, Int.neg_mul, Int.mul_neg, Int.neg_neg]⟩
+
+@[simp] protected theorem dvd_neg {a b : Int} : a ∣ -b ↔ a ∣ b := by
+  constructor <;> exact fun ⟨k, e⟩ =>
+    ⟨-k, by simp [← e, Int.neg_mul, Int.mul_neg, Int.neg_neg]⟩
+
+@[simp] theorem natAbs_dvd_natAbs {a b : Int} : natAbs a ∣ natAbs b ↔ a ∣ b := by
+  refine ⟨fun ⟨k, hk⟩ => ?_, fun ⟨k, hk⟩ => ⟨natAbs k, hk.symm ▸ natAbs_mul a k⟩⟩
+  rw [← natAbs_ofNat k, ← natAbs_mul, natAbs_eq_natAbs_iff] at hk
+  cases hk <;> subst b
+  · apply Int.dvd_mul_right
+  · rw [← Int.mul_neg]; apply Int.dvd_mul_right
+
+theorem ofNat_dvd_left {n : Nat} {z : Int} : (↑n : Int) ∣ z ↔ n ∣ z.natAbs := by
+  rw [← natAbs_dvd_natAbs, natAbs_ofNat]
+
+/-! ### ediv zero  -/
+
+@[simp] theorem zero_ediv : ∀ b : Int, 0 / b = 0
+  | ofNat _ => show ofNat _ = _ by simp
+  | -[_+1] => show -ofNat _ = _ by simp
+
+@[simp] protected theorem ediv_zero : ∀ a : Int, a / 0 = 0
+  | ofNat _ => show ofNat _ = _ by simp
+  | -[_+1] => rfl
+
+/-! ### emod zero -/
+
+@[simp] theorem zero_emod (b : Int) : 0 % b = 0 := rfl
+
+@[simp] theorem emod_zero : ∀ a : Int, a % 0 = a
+  | ofNat _ => congrArg ofNat <| Nat.mod_zero _
+  | -[_+1]  => congrArg negSucc <| Nat.mod_zero _
+
+/-! ### ofNat mod -/
+
+@[simp, norm_cast] theorem ofNat_emod (m n : Nat) : (↑(m % n) : Int) = m % n := rfl
+
+/-! ### mod definitions -/
+
+theorem emod_add_ediv : ∀ a b : Int, a % b + b * (a / b) = a
+  | ofNat _, ofNat _ => congrArg ofNat <| Nat.mod_add_div ..
+  | ofNat m, -[n+1] => by
+    show (m % succ n + -↑(succ n) * -↑(m / succ n) : Int) = m
+    rw [Int.neg_mul_neg]; exact congrArg ofNat <| Nat.mod_add_div ..
+  | -[_+1], 0 => by rw [emod_zero]; rfl
+  | -[m+1], succ n => aux m n.succ
+  | -[m+1], -[n+1] => aux m n.succ
+where
+  aux (m n : Nat) : n - (m % n + 1) - (n * (m / n) + n) = -[m+1] := by
+    rw [← ofNat_emod, ← ofNat_ediv, ← Int.sub_sub, negSucc_eq, Int.sub_sub n,
+      ← Int.neg_neg (_-_), Int.neg_sub, Int.sub_sub_self, Int.add_right_comm]
+    exact congrArg (fun x => -(ofNat x + 1)) (Nat.mod_add_div ..)
+
+/-- Variant of `emod_add_ediv` with the multiplication written the other way around. -/
+theorem emod_add_ediv' (a b : Int) : a % b + a / b * b = a := by
+  rw [Int.mul_comm]; exact emod_add_ediv ..
+
+theorem ediv_add_emod (a b : Int) : b * (a / b) + a % b = a := by
+  rw [Int.add_comm]; exact emod_add_ediv ..
+
+/-- Variant of `ediv_add_emod` with the multiplication written the other way around. -/
+theorem ediv_add_emod' (a b : Int) : a / b * b + a % b = a := by
+  rw [Int.mul_comm]; exact ediv_add_emod ..
+
+theorem emod_def (a b : Int) : a % b = a - b * (a / b) := by
+  rw [← Int.add_sub_cancel (a % b), emod_add_ediv]
+
+/-! ### `/` ediv -/
+
+@[simp] theorem ediv_neg : ∀ a b : Int, a / (-b) = -(a / b)
+  | ofNat m, 0 => show ofNat (m / 0) = -↑(m / 0) by rw [Nat.div_zero]; rfl
+  | ofNat _, -[_+1] => (Int.neg_neg _).symm
+  | ofNat _, succ _ | -[_+1], 0 | -[_+1], succ _ | -[_+1], -[_+1] => rfl
+
+protected theorem div_def (a b : Int) : a / b = Int.ediv a b := rfl
+
+theorem add_mul_ediv_right (a b : Int) {c : Int} (H : c ≠ 0) : (a + b * c) / c = a / c + b :=
+  suffices ∀ {{a b c : Int}}, 0 < c → (a + b * c).ediv c = a.ediv c + b from
+    match Int.lt_trichotomy c 0 with
+    | Or.inl hlt => by
+      rw [← Int.neg_inj, ← Int.ediv_neg, Int.neg_add, ← Int.ediv_neg, ← Int.neg_mul_neg]
+      exact this (Int.neg_pos_of_neg hlt)
+    | Or.inr (Or.inl HEq) => absurd HEq H
+    | Or.inr (Or.inr hgt) => this hgt
+  suffices ∀ {k n : Nat} {a : Int}, (a + n * k.succ).ediv k.succ = a.ediv k.succ + n from
+    fun a b c H => match c, eq_succ_of_zero_lt H, b with
+      | _, ⟨_, rfl⟩, ofNat _ => this
+      | _, ⟨k, rfl⟩, -[n+1] => show (a - n.succ * k.succ).ediv k.succ = a.ediv k.succ - n.succ by
+        rw [← Int.add_sub_cancel (ediv ..), ← this, Int.sub_add_cancel]
+  fun {k n} => @fun
+  | ofNat _ => congrArg ofNat <| Nat.add_mul_div_right _ _ k.succ_pos
+  | -[m+1] => by
+    show ((n * k.succ : Nat) - m.succ : Int).ediv k.succ = n - (m / k.succ + 1 : Nat)
+    by_cases h : m < n * k.succ
+    · rw [← Int.ofNat_sub h, ← Int.ofNat_sub ((Nat.div_lt_iff_lt_mul k.succ_pos).2 h)]
+      apply congrArg ofNat
+      rw [Nat.mul_comm, Nat.mul_sub_div]; rwa [Nat.mul_comm]
+    · have h := Nat.not_lt.1 h
+      have H {a b : Nat} (h : a ≤ b) : (a : Int) + -((b : Int) + 1) = -[b - a +1] := by
+        rw [negSucc_eq, Int.ofNat_sub h]
+        simp only [Int.sub_eq_add_neg, Int.neg_add, Int.neg_neg, Int.add_left_comm, Int.add_assoc]
+      show ediv (↑(n * succ k) + -((m : Int) + 1)) (succ k) = n + -(↑(m / succ k) + 1 : Int)
+      rw [H h, H ((Nat.le_div_iff_mul_le k.succ_pos).2 h)]
+      apply congrArg negSucc
+      rw [Nat.mul_comm, Nat.sub_mul_div]; rwa [Nat.mul_comm]
+
+theorem add_mul_ediv_left (a : Int) {b : Int}
+    (c : Int) (H : b ≠ 0) : (a + b * c) / b = a / b + c :=
+  Int.mul_comm .. ▸ Int.add_mul_ediv_right _ _ H
+
+theorem add_ediv_of_dvd_right {a b c : Int} (H : c ∣ b) : (a + b) / c = a / c + b / c :=
+  if h : c = 0 then by simp [h] else by
+    let ⟨k, hk⟩ := H
+    rw [hk, Int.mul_comm c k, Int.add_mul_ediv_right _ _ h,
+      ← Int.zero_add (k * c), Int.add_mul_ediv_right _ _ h, Int.zero_ediv, Int.zero_add]
+
+theorem add_ediv_of_dvd_left {a b c : Int} (H : c ∣ a) : (a + b) / c = a / c + b / c := by
+  rw [Int.add_comm, Int.add_ediv_of_dvd_right H, Int.add_comm]
+
+@[simp] theorem mul_ediv_cancel (a : Int) {b : Int} (H : b ≠ 0) : (a * b) / b = a := by
+  have := Int.add_mul_ediv_right 0 a H
+  rwa [Int.zero_add, Int.zero_ediv, Int.zero_add] at this
+
+@[simp] theorem mul_ediv_cancel_left (b : Int) (H : a ≠ 0) : (a * b) / a = b :=
+  Int.mul_comm .. ▸ Int.mul_ediv_cancel _ H
+
+theorem ediv_nonneg_iff_of_pos {a b : Int} (h : 0 < b) : 0 ≤ a / b ↔ 0 ≤ a := by
+  rw [Int.div_def]
+  match b, h with
+  | Int.ofNat (b+1), _ =>
+    rcases a with ⟨a⟩ <;> simp [Int.ediv]
+
+@[deprecated ediv_nonneg_iff_of_pos (since := "2025-02-28")]
+abbrev div_nonneg_iff_of_pos := @ediv_nonneg_iff_of_pos
+
+/-! ### emod -/
+
+theorem emod_nonneg : ∀ (a : Int) {b : Int}, b ≠ 0 → 0 ≤ a % b
+  | ofNat _, _, _ => ofNat_zero_le _
+  | -[_+1], _, H => Int.sub_nonneg_of_le <| ofNat_le.2 <| Nat.mod_lt _ (natAbs_pos.2 H)
+
+theorem emod_lt_of_pos (a : Int) {b : Int} (H : 0 < b) : a % b < b :=
+  match a, b, eq_succ_of_zero_lt H with
+  | ofNat _, _, ⟨_, rfl⟩ => ofNat_lt.2 (Nat.mod_lt _ (Nat.succ_pos _))
+  | -[_+1], _, ⟨_, rfl⟩ => Int.sub_lt_self _ (ofNat_lt.2 <| Nat.succ_pos _)
+
+@[simp] theorem add_mul_emod_self {a b c : Int} : (a + b * c) % c = a % c :=
+  if cz : c = 0 then by
+    rw [cz, Int.mul_zero, Int.add_zero]
+  else by
+    rw [Int.emod_def, Int.emod_def, Int.add_mul_ediv_right _ _ cz, Int.add_comm _ b,
+      Int.mul_add, Int.mul_comm, ← Int.sub_sub, Int.add_sub_cancel]
+
+@[simp] theorem add_mul_emod_self_left (a b c : Int) : (a + b * c) % b = a % b := by
+  rw [Int.mul_comm, Int.add_mul_emod_self]
+
+@[simp] theorem emod_add_emod (m n k : Int) : (m % n + k) % n = (m + k) % n := by
+  have := (add_mul_emod_self_left (m % n + k) n (m / n)).symm
+  rwa [Int.add_right_comm, emod_add_ediv] at this
+
+@[simp] theorem add_emod_emod (m n k : Int) : (m + n % k) % k = (m + n) % k := by
+  rw [Int.add_comm, emod_add_emod, Int.add_comm]
+
+theorem add_emod (a b n : Int) : (a + b) % n = (a % n + b % n) % n := by
+  rw [add_emod_emod, emod_add_emod]
+
+theorem add_emod_eq_add_emod_right {m n k : Int} (i : Int)
+    (H : m % n = k % n) : (m + i) % n = (k + i) % n := by
+  rw [← emod_add_emod, ← emod_add_emod k, H]
+
+theorem emod_add_cancel_right {m n k : Int} (i) : (m + i) % n = (k + i) % n ↔ m % n = k % n :=
+  ⟨fun H => by
+    have := add_emod_eq_add_emod_right (-i) H
+    rwa [Int.add_neg_cancel_right, Int.add_neg_cancel_right] at this,
+  add_emod_eq_add_emod_right _⟩
+
+@[simp] theorem mul_emod_left (a b : Int) : (a * b) % b = 0 := by
+  rw [← Int.zero_add (a * b), Int.add_mul_emod_self, Int.zero_emod]
+
+@[simp] theorem mul_emod_right (a b : Int) : (a * b) % a = 0 := by
+  rw [Int.mul_comm, mul_emod_left]
+
+theorem mul_emod (a b n : Int) : (a * b) % n = (a % n) * (b % n) % n := by
+  conv => lhs; rw [
+    ← emod_add_ediv a n, ← emod_add_ediv' b n, Int.add_mul, Int.mul_add, Int.mul_add,
+    Int.mul_assoc, Int.mul_assoc, ← Int.mul_add n _ _, add_mul_emod_self_left,
+    ← Int.mul_assoc, add_mul_emod_self]
+
+@[simp] theorem emod_self {a : Int} : a % a = 0 := by
+  have := mul_emod_left 1 a; rwa [Int.one_mul] at this
+
+@[simp] theorem emod_emod_of_dvd (n : Int) {m k : Int}
+    (h : m ∣ k) : (n % k) % m = n % m := by
+  conv => rhs; rw [← emod_add_ediv n k]
+  match k, h with
+  | _, ⟨t, rfl⟩ => rw [Int.mul_assoc, add_mul_emod_self_left]
+
+@[simp] theorem emod_emod (a b : Int) : (a % b) % b = a % b := by
+  conv => rhs; rw [← emod_add_ediv a b, add_mul_emod_self_left]
+
+theorem sub_emod (a b n : Int) : (a - b) % n = (a % n - b % n) % n := by
+  apply (emod_add_cancel_right b).mp
+  rw [Int.sub_add_cancel, ← Int.add_emod_emod, Int.sub_add_cancel, emod_emod]
+
+/-! ### properties of `/` and `%` -/
+
+theorem mul_ediv_cancel_of_emod_eq_zero {a b : Int} (H : a % b = 0) : b * (a / b) = a := by
+  have := emod_add_ediv a b; rwa [H, Int.zero_add] at this
+
+theorem ediv_mul_cancel_of_emod_eq_zero {a b : Int} (H : a % b = 0) : a / b * b = a := by
+  rw [Int.mul_comm, mul_ediv_cancel_of_emod_eq_zero H]
+
+theorem dvd_of_emod_eq_zero {a b : Int} (H : b % a = 0) : a ∣ b :=
+  ⟨b / a, (mul_ediv_cancel_of_emod_eq_zero H).symm⟩
+
+theorem emod_eq_zero_of_dvd : ∀ {a b : Int}, a ∣ b → b % a = 0
+  | _, _, ⟨_, rfl⟩ => mul_emod_right ..
+
+theorem dvd_iff_emod_eq_zero {a b : Int} : a ∣ b ↔ b % a = 0 :=
+  ⟨emod_eq_zero_of_dvd, dvd_of_emod_eq_zero⟩
+
+protected theorem mul_ediv_assoc (a : Int) : ∀ {b c : Int}, c ∣ b → (a * b) / c = a * (b / c)
+  | _, c, ⟨d, rfl⟩ =>
+    if cz : c = 0 then by simp [cz, Int.mul_zero] else by
+      rw [Int.mul_left_comm, Int.mul_ediv_cancel_left _ cz, Int.mul_ediv_cancel_left _ cz]
+
+protected theorem mul_ediv_assoc' (b : Int) {a c : Int}
+    (h : c ∣ a) : (a * b) / c = a / c * b := by
+  rw [Int.mul_comm, Int.mul_ediv_assoc _ h, Int.mul_comm]
+
+theorem neg_ediv_of_dvd : ∀ {a b : Int}, b ∣ a → (-a) / b = -(a / b)
+  | _, b, ⟨c, rfl⟩ => by
+    by_cases bz : b = 0
+    · simp [bz]
+    · rw [Int.neg_mul_eq_mul_neg, Int.mul_ediv_cancel_left _ bz, Int.mul_ediv_cancel_left _ bz]
+
+theorem sub_ediv_of_dvd (a : Int) {b c : Int}
+    (hcb : c ∣ b) : (a - b) / c = a / c - b / c := by
+  rw [Int.sub_eq_add_neg, Int.sub_eq_add_neg, Int.add_ediv_of_dvd_right (Int.dvd_neg.2 hcb)]
+  congr; exact Int.neg_ediv_of_dvd hcb
+
+protected theorem ediv_mul_cancel {a b : Int} (H : b ∣ a) : a / b * b = a :=
+  ediv_mul_cancel_of_emod_eq_zero (emod_eq_zero_of_dvd H)
+
+protected theorem mul_ediv_cancel' {a b : Int} (H : a ∣ b) : a * (b / a) = b := by
+  rw [Int.mul_comm, Int.ediv_mul_cancel H]
+
+theorem emod_pos_of_not_dvd {a b : Int} (h : ¬ a ∣ b) : a = 0 ∨ 0 < b % a := by
+  rw [dvd_iff_emod_eq_zero] at h
+  by_cases w : a = 0
+  · simp_all
+  · exact Or.inr (Int.lt_iff_le_and_ne.mpr ⟨emod_nonneg b w, Ne.symm h⟩)
+
+/-! ### `/` and ordering -/
+
+theorem mul_ediv_self_le {x k : Int} (h : k ≠ 0) : k * (x / k) ≤ x :=
+  calc k * (x / k)
+    _ ≤ k * (x / k) + x % k := Int.le_add_of_nonneg_right (emod_nonneg x h)
+    _ = x                   := ediv_add_emod _ _
+
+theorem lt_mul_ediv_self_add {x k : Int} (h : 0 < k) : x < k * (x / k) + k :=
+  calc x
+    _ = k * (x / k) + x % k := (ediv_add_emod _ _).symm
+    _ < k * (x / k) + k     := Int.add_lt_add_left (emod_lt_of_pos x h) _
+
+/-! ### bmod -/
+
+@[simp] theorem bmod_emod : bmod x m % m = x % m := by
+  dsimp [bmod]
+  split <;> simp [Int.sub_emod]
+
+theorem bmod_def (x : Int) (m : Nat) : bmod x m =
+  if (x % m) < (m + 1) / 2 then
+    x % m
+  else
+    (x % m) - m :=
+  rfl
+
+end Int

src/Init/Data/Int/Gcd.lean

@@ -7,16 +7,34 @@ prelude
 import Init.Data.Int.Basic
 import Init.Data.Nat.Gcd
 import Init.Data.Nat.Lcm
-import Init.Data.Int.DivModLemmas
+import Init.Data.Int.DivMod.Lemmas
 
 /-!
 Definition and lemmas for gcd and lcm over Int
+
+## Future work
+Most of the material about `Nat.gcd` and `Nat.lcm` from `Init.Data.Nat.Gcd` and `Init.Data.Nat.Lcm`
+has analogues for `Int.gcd` and `Int.lcm` that should be added to this file.
 -/
 namespace Int
 
 /-! ## gcd -/
 
-/-- Computes the greatest common divisor of two integers, as a `Nat`. -/
+/--
+Computes the greatest common divisor of two integers as a natural number. The GCD of two integers is
+the largest natural number that evenly divides both. However, the GCD of a number and `0` is the
+number's absolute value.
+
+This implementation uses `Nat.gcd`, which is overridden in both the kernel and the compiler to
+efficiently evaluate using arbitrary-precision arithmetic.
+
+Examples:
+* `Int.gcd 10 15 = 5`
+* `Int.gcd 10 (-15) = 5`
+* `Int.gcd (-6) (-9) = 3`
+* `Int.gcd 0 5 = 5`
+* `Int.gcd (-7) 0 = 7`
+-/
 def gcd (m n : Int) : Nat := m.natAbs.gcd n.natAbs
 
 theorem gcd_dvd_left {a b : Int} : (gcd a b : Int) ∣ a := by
@@ -37,7 +55,18 @@ theorem gcd_dvd_right {a b : Int} : (gcd a b : Int) ∣ b := by
 
 /-! ## lcm -/
 
-/-- Computes the least common multiple of two integers, as a `Nat`. -/
+/--
+Computes the least common multiple of two integers as a natural number. The LCM of two integers is
+the smallest natural number that's evenly divisible by the absolute values of both.
+
+Examples:
+ * `Int.lcm 9 6 = 18`
+ * `Int.lcm 9 (-6) = 18`
+ * `Int.lcm 9 3 = 9`
+ * `Int.lcm 9 (-3) = 9`
+ * `Int.lcm 0 3 = 0`
+ * `Int.lcm (-3) 0 = 0`
+-/
 def lcm (m n : Int) : Nat := m.natAbs.lcm n.natAbs
 
 theorem lcm_ne_zero (hm : m ≠ 0) (hn : n ≠ 0) : lcm m n ≠ 0 := by

src/Init/Data/Int/Lemmas.lean

@@ -25,31 +25,32 @@ theorem subNatNat_of_sub_eq_succ {m n k : Nat} (h : n - m = succ k) : subNatNat
 
 @[norm_cast] theorem ofNat_add (n m : Nat) : (↑(n + m) : Int) = n + m := rfl
 @[norm_cast] theorem ofNat_mul (n m : Nat) : (↑(n * m) : Int) = n * m := rfl
-theorem ofNat_succ (n : Nat) : (succ n : Int) = n + 1 := rfl
+@[norm_cast] theorem ofNat_succ (n : Nat) : (succ n : Int) = n + 1 := rfl
 
-@[local simp] theorem neg_ofNat_zero : -((0 : Nat) : Int) = 0 := rfl
-@[local simp] theorem neg_ofNat_succ (n : Nat) : -(succ n : Int) = -[n+1] := rfl
-@[local simp] theorem neg_negSucc (n : Nat) : -(-[n+1]) = succ n := rfl
-
-theorem negSucc_coe (n : Nat) : -[n+1] = -↑(n + 1) := rfl
+theorem neg_ofNat_zero : -((0 : Nat) : Int) = 0 := rfl
+theorem neg_ofNat_succ (n : Nat) : -(succ n : Int) = -[n+1] := rfl
+theorem neg_negSucc (n : Nat) : -(-[n+1]) = succ n := rfl
 
 theorem negOfNat_eq : negOfNat n = -ofNat n := rfl
 
-/-! ## These are only for internal use -/
-
 @[simp] theorem add_def {a b : Int} : Int.add a b = a + b := rfl
+@[simp] theorem mul_def {a b : Int} : Int.mul a b = a * b := rfl
+
+/-!
+## These are only for internal use
+
+Ideally these could all be made private, but they are used in downstream libraries.
+-/
 
 @[local simp] theorem ofNat_add_ofNat (m n : Nat) : (↑m + ↑n : Int) = ↑(m + n) := rfl
 @[local simp] theorem ofNat_add_negSucc (m n : Nat) : ↑m + -[n+1] = subNatNat m (succ n) := rfl
 @[local simp] theorem negSucc_add_ofNat (m n : Nat) : -[m+1] + ↑n = subNatNat n (succ m) := rfl
 @[local simp] theorem negSucc_add_negSucc (m n : Nat) : -[m+1] + -[n+1] = -[succ (m + n) +1] := rfl
 
-@[simp] theorem mul_def {a b : Int} : Int.mul a b = a * b := rfl
-
 @[local simp] theorem ofNat_mul_ofNat (m n : Nat) : (↑m * ↑n : Int) = ↑(m * n) := rfl
-@[local simp] theorem ofNat_mul_negSucc' (m n : Nat) : ↑m * -[n+1] = negOfNat (m * succ n) := rfl
-@[local simp] theorem negSucc_mul_ofNat' (m n : Nat) : -[m+1] * ↑n = negOfNat (succ m * n) := rfl
-@[local simp] theorem negSucc_mul_negSucc' (m n : Nat) :
+@[local simp] private theorem ofNat_mul_negSucc' (m n : Nat) : ↑m * -[n+1] = negOfNat (m * succ n) := rfl
+@[local simp] private theorem negSucc_mul_ofNat' (m n : Nat) : -[m+1] * ↑n = negOfNat (succ m * n) := rfl
+@[local simp] private theorem negSucc_mul_negSucc' (m n : Nat) :
     -[m+1] * -[n+1] = ofNat (succ m * succ n) := rfl
 
 /- ## some basic functions and properties -/
@@ -64,11 +65,14 @@ theorem negSucc_inj : negSucc m = negSucc n ↔ m = n := ⟨negSucc.inj, fun H =
 
 theorem negSucc_eq (n : Nat) : -[n+1] = -((n : Int) + 1) := rfl
 
+@[deprecated negSucc_eq (since := "2025-03-11")]
+theorem negSucc_coe (n : Nat) : -[n+1] = -↑(n + 1) := rfl
+
 @[simp] theorem negSucc_ne_zero (n : Nat) : -[n+1] ≠ 0 := nofun
 
 @[simp] theorem zero_ne_negSucc (n : Nat) : 0 ≠ -[n+1] := nofun
 
-@[simp, norm_cast] theorem Nat.cast_ofNat_Int :
+@[simp, norm_cast] theorem cast_ofNat_Int :
   (Nat.cast (no_index (OfNat.ofNat n)) : Int) = OfNat.ofNat n := rfl
 
 /- ## neg -/
@@ -78,7 +82,7 @@ theorem negSucc_eq (n : Nat) : -[n+1] = -((n : Int) + 1) := rfl
   | succ _ => rfl
   | -[_+1] => rfl
 
-protected theorem neg_inj {a b : Int} : -a = -b ↔ a = b :=
+@[simp] protected theorem neg_inj {a b : Int} : -a = -b ↔ a = b :=
   ⟨fun h => by rw [← Int.neg_neg a, ← Int.neg_neg b, h], congrArg _⟩
 
 @[simp] protected theorem neg_eq_zero : -a = 0 ↔ a = 0 := Int.neg_inj (b := 0)
@@ -86,12 +90,13 @@ protected theorem neg_inj {a b : Int} : -a = -b ↔ a = b :=
 protected theorem neg_ne_zero : -a ≠ 0 ↔ a ≠ 0 := not_congr Int.neg_eq_zero
 
 protected theorem sub_eq_add_neg {a b : Int} : a - b = a + -b := rfl
+protected theorem add_neg_eq_sub {a b : Int} : a + -b = a - b := rfl
 
 theorem add_neg_one (i : Int) : i + -1 = i - 1 := rfl
 
 /- ## basic properties of subNatNat -/
 
--- @[elabAsElim] -- TODO(Mario): unexpected eliminator resulting type
+@[elab_as_elim]
 theorem subNatNat_elim (m n : Nat) (motive : Nat → Nat → Int → Prop)
     (hp : ∀ i n, motive (n + i) n i)
     (hn : ∀ i m, motive m (m + i + 1) -[i+1]) :
@@ -129,28 +134,16 @@ theorem subNatNat_of_le {m n : Nat} (h : n ≤ m) : subNatNat m n = ↑(m - n) :
 theorem subNatNat_of_lt {m n : Nat} (h : m < n) : subNatNat m n = -[pred (n - m) +1] :=
   subNatNat_of_sub_eq_succ <| (Nat.succ_pred_eq_of_pos (Nat.sub_pos_of_lt h)).symm
 
-/- # Additive group properties -/
-
-/- addition -/
-
-protected theorem add_comm : ∀ a b : Int, a + b = b + a
-  | ofNat n, ofNat m => by simp [Nat.add_comm]
-  | ofNat _, -[_+1]  => rfl
-  | -[_+1],  ofNat _ => rfl
-  | -[_+1],  -[_+1]  => by simp [Nat.add_comm]
-instance : Std.Commutative (α := Int) (· + ·) := ⟨Int.add_comm⟩
-
-@[simp] protected theorem add_zero : ∀ a : Int, a + 0 = a
-  | ofNat _ => rfl
-  | -[_+1]  => rfl
-
-@[simp] protected theorem zero_add (a : Int) : 0 + a = a := Int.add_comm .. ▸ a.add_zero
-instance : Std.LawfulIdentity (α := Int) (· + ·) 0 where
-  left_id := Int.zero_add
-  right_id := Int.add_zero
-
-theorem ofNat_add_negSucc_of_lt (h : m < n.succ) : ofNat m + -[n+1] = -[n - m+1] :=
-  show subNatNat .. = _ by simp [succ_sub (le_of_lt_succ h), subNatNat]
+@[simp] theorem subNat_eq_zero_iff {a b : Nat} : subNatNat a b = 0 ↔ a = b := by
+  cases Nat.lt_or_ge a b with
+  | inl h =>
+    rw [subNatNat_of_lt h]
+    simpa using ne_of_lt h
+  | inr h =>
+    rw [subNatNat_of_le h]
+    norm_cast
+    rw [Nat.sub_eq_iff_eq_add' h]
+    simp
 
 theorem subNatNat_sub (h : n ≤ m) (k : Nat) : subNatNat (m - n) k = subNatNat m (k + n) := by
   rwa [← subNatNat_add_add _ _ n, Nat.sub_add_cancel]
@@ -180,6 +173,34 @@ theorem subNatNat_add_negSucc (m n k : Nat) :
       ← Nat.add_assoc, succ_sub_succ_eq_sub, Nat.add_comm n,Nat.add_sub_assoc (Nat.le_of_lt h'),
       Nat.add_comm]
 
+theorem subNatNat_self : ∀ n, subNatNat n n = 0
+  | 0      => rfl
+  | succ m => by rw [subNatNat_of_sub_eq_zero (Nat.sub_self ..), Nat.sub_self, ofNat_zero]
+
+/- # Additive group properties -/
+
+/- addition -/
+
+protected theorem add_comm : ∀ a b : Int, a + b = b + a
+  | ofNat n, ofNat m => by simp [Nat.add_comm]
+  | ofNat _, -[_+1]  => rfl
+  | -[_+1],  ofNat _ => rfl
+  | -[_+1],  -[_+1]  => by simp [Nat.add_comm]
+
+instance : Std.Commutative (α := Int) (· + ·) := ⟨Int.add_comm⟩
+
+@[simp] protected theorem add_zero : ∀ a : Int, a + 0 = a
+  | ofNat _ => rfl
+  | -[_+1]  => rfl
+
+@[simp] protected theorem zero_add (a : Int) : 0 + a = a := Int.add_comm .. ▸ a.add_zero
+instance : Std.LawfulIdentity (α := Int) (· + ·) 0 where
+  left_id := Int.zero_add
+  right_id := Int.add_zero
+
+theorem ofNat_add_negSucc_of_lt (h : m < n.succ) : ofNat m + -[n+1] = -[n - m+1] :=
+  show subNatNat .. = _ by simp [succ_sub (le_of_lt_succ h), subNatNat]
+
 protected theorem add_assoc : ∀ a b c : Int, a + b + c = a + (b + c)
   | (m:Nat), (n:Nat), _ => aux1 ..
   | Nat.cast m, b, Nat.cast k => by
@@ -211,18 +232,12 @@ protected theorem add_right_comm (a b c : Int) : a + b + c = a + c + b := by
 
 /- ## negation -/
 
-theorem subNatNat_self : ∀ n, subNatNat n n = 0
+protected theorem add_left_neg : ∀ a : Int, -a + a = 0
   | 0      => rfl
-  | succ m => by rw [subNatNat_of_sub_eq_zero (Nat.sub_self ..), Nat.sub_self, ofNat_zero]
+  | succ m => by simp [neg_ofNat_succ]
+  | -[m+1] => by simp [neg_negSucc]
 
-attribute [local simp] subNatNat_self
-
-@[local simp] protected theorem add_left_neg : ∀ a : Int, -a + a = 0
-  | 0      => rfl
-  | succ m => by simp
-  | -[m+1] => by simp
-
-@[local simp] protected theorem add_right_neg (a : Int) : a + -a = 0 := by
+protected theorem add_right_neg (a : Int) : a + -a = 0 := by
   rw [Int.add_comm, Int.add_left_neg]
 
 protected theorem neg_eq_of_add_eq_zero {a b : Int} (h : a + b = 0) : -a = b := by
@@ -253,11 +268,22 @@ protected theorem add_left_cancel {a b c : Int} (h : a + b = a + c) : b = c := b
   have h₁ : -a + (a + b) = -a + (a + c) := by rw [h]
   simp [← Int.add_assoc, Int.add_left_neg, Int.zero_add] at h₁; exact h₁
 
-@[local simp] protected theorem neg_add {a b : Int} : -(a + b) = -a + -b := by
+protected theorem neg_add {a b : Int} : -(a + b) = -a + -b := by
   apply Int.add_left_cancel (a := a + b)
   rw [Int.add_right_neg, Int.add_comm a, ← Int.add_assoc, Int.add_assoc b,
     Int.add_right_neg, Int.add_zero, Int.add_right_neg]
 
+/--
+If a predicate on the integers is invariant under negation,
+then it is sufficient to prove it for the nonnegative integers.
+-/
+theorem wlog_sign {P : Int → Prop} (inv : ∀ i, P i ↔ P (-i)) (w : ∀ n : Nat, P n) (i : Int) : P i := by
+  cases i with
+  | ofNat n => exact w n
+  | negSucc n =>
+    rw [negSucc_eq, ← inv, ← ofNat_succ]
+    apply w
+
 /- ## subtraction -/
 
 @[simp] theorem negSucc_sub_one (n : Nat) : -[n+1] - 1 = -[n + 1 +1] := rfl
@@ -281,13 +307,13 @@ protected theorem sub_eq_zero {a b : Int} : a - b = 0 ↔ a = b :=
   ⟨Int.eq_of_sub_eq_zero, Int.sub_eq_zero_of_eq⟩
 
 protected theorem sub_sub (a b c : Int) : a - b - c = a - (b + c) := by
-  simp [Int.sub_eq_add_neg, Int.add_assoc]
+  simp [Int.sub_eq_add_neg, Int.add_assoc, Int.neg_add]
 
 protected theorem neg_sub (a b : Int) : -(a - b) = b - a := by
-  simp [Int.sub_eq_add_neg, Int.add_comm]
+  simp [Int.sub_eq_add_neg, Int.add_comm, Int.neg_add]
 
 protected theorem sub_sub_self (a b : Int) : a - (a - b) = b := by
-  simp [Int.sub_eq_add_neg, ← Int.add_assoc]
+  simp [Int.sub_eq_add_neg, ← Int.add_assoc, Int.neg_add, Int.add_right_neg]
 
 @[simp] protected theorem sub_neg (a b : Int) : a - -b = a + b := by simp [Int.sub_eq_add_neg]
 
@@ -298,7 +324,7 @@ protected theorem sub_sub_self (a b : Int) : a - (a - b) = b := by
   Int.add_neg_cancel_right a b
 
 protected theorem add_sub_assoc (a b c : Int) : a + b - c = a + (b - c) := by
-  rw [Int.sub_eq_add_neg, Int.add_assoc, ← Int.sub_eq_add_neg]
+  rw [Int.sub_eq_add_neg, Int.add_assoc, Int.add_neg_eq_sub]
 
 @[norm_cast] theorem ofNat_sub (h : m ≤ n) : ((n - m : Nat) : Int) = n - m := by
   match m with
@@ -307,6 +333,7 @@ protected theorem add_sub_assoc (a b c : Int) : a + b - c = a + (b - c) := by
     show ofNat (n - succ m) = subNatNat n (succ m)
     rw [subNatNat, Nat.sub_eq_zero_of_le h]
 
+@[deprecated negSucc_eq (since := "2025-03-11")]
 theorem negSucc_coe' (n : Nat) : -[n+1] = -↑n - 1 := by
   rw [Int.sub_eq_add_neg, ← Int.neg_add]; rfl
 
@@ -316,11 +343,11 @@ protected theorem subNatNat_eq_coe {m n : Nat} : subNatNat m n = ↑m - ↑n :=
     rw [Int.ofNat_add, Int.sub_eq_add_neg, Int.add_assoc, Int.add_left_comm,
       Int.add_right_neg, Int.add_zero]
   · intros i n
-    simp only [negSucc_coe, ofNat_add, Int.sub_eq_add_neg, Int.neg_add, ← Int.add_assoc]
-    rw [← @Int.sub_eq_add_neg n, ← ofNat_sub, Nat.sub_self, ofNat_zero, Int.zero_add]
+    simp only [negSucc_eq, ofNat_add, ofNat_one, Int.sub_eq_add_neg, Int.neg_add, ← Int.add_assoc]
+    rw [Int.add_neg_eq_sub (a := n), ← ofNat_sub, Nat.sub_self, ofNat_zero, Int.zero_add]
     apply Nat.le_refl
 
-theorem toNat_sub (m n : Nat) : toNat (m - n) = m - n := by
+@[simp] theorem toNat_sub (m n : Nat) : toNat (m - n) = m - n := by
   rw [← Int.subNatNat_eq_coe]
   refine subNatNat_elim m n (fun m n i => toNat i = m - n) (fun i n => ?_) (fun i n => ?_)
   · exact (Nat.add_sub_cancel_left ..).symm
@@ -330,30 +357,50 @@ theorem toNat_of_nonpos : ∀ {z : Int}, z ≤ 0 → z.toNat = 0
   | 0, _ => rfl
   | -[_+1], _ => rfl
 
+@[simp] theorem neg_ofNat_eq_negSucc_iff {a b : Nat} : - (a : Int) = -[b+1] ↔ a = b + 1 := by
+  rw [Int.neg_eq_comm]
+  rw [Int.neg_negSucc]
+  norm_cast
+  simp [eq_comm]
+
+@[simp] theorem negSucc_eq_neg_ofNat_iff {a b : Nat} : -[a+1] = - (b : Int) ↔ a + 1 = b := by
+  rw [eq_comm, neg_ofNat_eq_negSucc_iff, eq_comm]
+
+@[simp] theorem neg_ofNat_eq_negSucc_add_one_iff {a b : Nat} : - (a : Int) = -[b+1] + 1 ↔ a = b := by
+  cases b with
+  | zero => simp; norm_cast
+  | succ b =>
+    rw [Int.neg_eq_comm, ← Int.negSucc_sub_one, Int.sub_add_cancel, Int.neg_negSucc]
+    norm_cast
+    simp [eq_comm]
+
+@[simp] theorem negSucc_add_one_eq_neg_ofNat_iff {a b : Nat} : -[a+1] + 1 = - (b : Int) ↔ a = b := by
+  rw [eq_comm, neg_ofNat_eq_negSucc_add_one_iff, eq_comm]
+
 /- ## add/sub injectivity -/
 
-protected theorem add_left_inj {i j : Int} (k : Int) : (i + k = j + k) ↔ i = j := by
+@[simp] protected theorem add_left_inj {i j : Int} (k : Int) : (i + k = j + k) ↔ i = j := by
   apply Iff.intro
   · intro p
     rw [←Int.add_sub_cancel i k, ←Int.add_sub_cancel j k, p]
   · exact congrArg (· + k)
 
-protected theorem add_right_inj {i j : Int} (k : Int) : (k + i = k + j) ↔ i = j := by
+@[simp] protected theorem add_right_inj {i j : Int} (k : Int) : (k + i = k + j) ↔ i = j := by
   simp [Int.add_comm k, Int.add_left_inj]
 
-protected theorem sub_right_inj {i j : Int} (k : Int) : (k - i = k - j) ↔ i = j := by
+@[simp] protected theorem sub_right_inj {i j : Int} (k : Int) : (k - i = k - j) ↔ i = j := by
   simp [Int.sub_eq_add_neg, Int.neg_inj, Int.add_right_inj]
 
-protected theorem sub_left_inj {i j : Int} (k : Int) : (i - k = j - k) ↔ i = j := by
+@[simp] protected theorem sub_left_inj {i j : Int} (k : Int) : (i - k = j - k) ↔ i = j := by
   simp [Int.sub_eq_add_neg, Int.add_left_inj]
 
 /- ## Ring properties -/
 
-@[simp] theorem ofNat_mul_negSucc (m n : Nat) : (m : Int) * -[n+1] = -↑(m * succ n) := rfl
+theorem ofNat_mul_negSucc (m n : Nat) : (m : Int) * -[n+1] = -↑(m * succ n) := rfl
 
-@[simp] theorem negSucc_mul_ofNat (m n : Nat) : -[m+1] * n = -↑(succ m * n) := rfl
+theorem negSucc_mul_ofNat (m n : Nat) : -[m+1] * n = -↑(succ m * n) := rfl
 
-@[simp] theorem negSucc_mul_negSucc (m n : Nat) : -[m+1] * -[n+1] = succ m * succ n := rfl
+theorem negSucc_mul_negSucc (m n : Nat) : -[m+1] * -[n+1] = succ m * succ n := rfl
 
 protected theorem mul_comm (a b : Int) : a * b = b * a := by
   cases a <;> cases b <;> simp [Nat.mul_comm]
@@ -371,11 +418,10 @@ theorem negSucc_mul_negOfNat (m n : Nat) : -[m+1] * negOfNat n = ofNat (succ m *
 theorem negOfNat_mul_negSucc (m n : Nat) : negOfNat n * -[m+1] = ofNat (n * succ m) := by
   rw [Int.mul_comm, negSucc_mul_negOfNat, Nat.mul_comm]
 
-attribute [local simp] ofNat_mul_negOfNat negOfNat_mul_ofNat
-  negSucc_mul_negOfNat negOfNat_mul_negSucc
-
 protected theorem mul_assoc (a b c : Int) : a * b * c = a * (b * c) := by
-  cases a <;> cases b <;> cases c <;> simp [Nat.mul_assoc]
+  cases a <;> cases b <;> cases c <;>
+    simp [Nat.mul_assoc, ofNat_mul_negOfNat, negOfNat_mul_ofNat, negSucc_mul_negOfNat, negOfNat_mul_negSucc]
+
 instance : Std.Associative (α := Int) (· * ·) := ⟨Int.mul_assoc⟩
 
 protected theorem mul_left_comm (a b c : Int) : a * (b * c) = b * (a * c) := by
@@ -393,7 +439,7 @@ theorem negOfNat_eq_subNatNat_zero (n) : negOfNat n = subNatNat 0 n := by cases
 theorem ofNat_mul_subNatNat (m n k : Nat) :
     m * subNatNat n k = subNatNat (m * n) (m * k) := by
   cases m with
-  | zero => simp [ofNat_zero, Int.zero_mul, Nat.zero_mul]
+  | zero => simp [ofNat_zero, Int.zero_mul, Nat.zero_mul, subNatNat_self]
   | succ m => cases n.lt_or_ge k with
     | inl h =>
       have h' : succ m * n < succ m * k := Nat.mul_lt_mul_of_pos_left h (Nat.succ_pos m)
@@ -421,8 +467,7 @@ theorem negSucc_mul_subNatNat (m n k : Nat) :
         Nat.mul_sub_left_distrib, ← succ_pred_eq_of_pos (Nat.sub_pos_of_lt h₁)]; rfl
     | inr h' => rw [Nat.le_antisymm h h', subNatNat_self, subNatNat_self, Int.mul_zero]
 
-attribute [local simp] ofNat_mul_subNatNat negOfNat_add negSucc_mul_subNatNat
-
+attribute [local simp] ofNat_mul_subNatNat negOfNat_add negSucc_mul_subNatNat in
 protected theorem mul_add : ∀ a b c : Int, a * (b + c) = a * b + a * c
   | (m:Nat), (n:Nat), (k:Nat) => by simp [Nat.left_distrib]
   | (m:Nat), (n:Nat), -[k+1]  => by
@@ -445,21 +490,23 @@ protected theorem neg_mul_eq_neg_mul (a b : Int) : -(a * b) = -a * b :=
 protected theorem neg_mul_eq_mul_neg (a b : Int) : -(a * b) = a * -b :=
   Int.neg_eq_of_add_eq_zero <| by rw [← Int.mul_add, Int.add_right_neg, Int.mul_zero]
 
-@[simp] protected theorem neg_mul (a b : Int) : -a * b = -(a * b) :=
+-- Note, this is not a `@[simp]` lemma because it interferes with normalization in `simp +arith`.
+protected theorem neg_mul (a b : Int) : -a * b = -(a * b) :=
   (Int.neg_mul_eq_neg_mul a b).symm
 
-@[simp] protected theorem mul_neg (a b : Int) : a * -b = -(a * b) :=
+-- Note, this is not a `@[simp]` lemma because it interferes with normalization in `simp +arith`.
+protected theorem mul_neg (a b : Int) : a * -b = -(a * b) :=
   (Int.neg_mul_eq_mul_neg a b).symm
 
-protected theorem neg_mul_neg (a b : Int) : -a * -b = a * b := by simp
+protected theorem neg_mul_neg (a b : Int) : -a * -b = a * b := by simp [Int.neg_mul, Int.mul_neg]
 
-protected theorem neg_mul_comm (a b : Int) : -a * b = a * -b := by simp
+protected theorem neg_mul_comm (a b : Int) : -a * b = a * -b := by simp [Int.neg_mul, Int.mul_neg]
 
 protected theorem mul_sub (a b c : Int) : a * (b - c) = a * b - a * c := by
-  simp [Int.sub_eq_add_neg, Int.mul_add]
+  simp [Int.sub_eq_add_neg, Int.mul_add, Int.mul_neg]
 
 protected theorem sub_mul (a b c : Int) : (a - b) * c = a * c - b * c := by
-  simp [Int.sub_eq_add_neg, Int.add_mul]
+  simp [Int.sub_eq_add_neg, Int.add_mul, Int.neg_mul]
 
 @[simp] protected theorem one_mul : ∀ a : Int, 1 * a = a
   | ofNat n => show ofNat (1 * n) = ofNat n by rw [Nat.one_mul]
@@ -470,7 +517,9 @@ instance : Std.LawfulIdentity (α := Int) (· * ·) 1 where
   left_id := Int.one_mul
   right_id := Int.mul_one
 
-protected theorem mul_neg_one (a : Int) : a * -1 = -a := by rw [Int.mul_neg, Int.mul_one]
+@[simp] protected theorem mul_neg_one (a : Int) : a * -1 = -a := by rw [Int.mul_neg, Int.mul_one]
+
+@[simp] protected theorem neg_one_mul (a : Int) : -1 * a = -a := by rw [Int.neg_mul, Int.one_mul]
 
 protected theorem neg_eq_neg_one_mul : ∀ a : Int, -a = -1 * a
   | 0      => rfl
@@ -519,16 +568,18 @@ The following lemmas are later subsumed by e.g. `Nat.cast_add` and `Nat.cast_mul
 but it is convenient to have these earlier, for users who only need `Nat` and `Int`.
 -/
 
-theorem natCast_zero : ((0 : Nat) : Int) = (0 : Int) := rfl
+protected theorem natCast_zero : ((0 : Nat) : Int) = (0 : Int) := rfl
 
-theorem natCast_one : ((1 : Nat) : Int) = (1 : Int) := rfl
+protected theorem natCast_one : ((1 : Nat) : Int) = (1 : Int) := rfl
 
-@[simp] theorem natCast_add (a b : Nat) : ((a + b : Nat) : Int) = (a : Int) + (b : Int) := by
+@[simp] protected theorem natCast_add (a b : Nat) : ((a + b : Nat) : Int) = (a : Int) + (b : Int) := by
   -- Note this only works because of local simp attributes in this file,
   -- so it still makes sense to tag the lemmas with `@[simp]`.
   simp
 
-@[simp] theorem natCast_mul (a b : Nat) : ((a * b : Nat) : Int) = (a : Int) * (b : Int) := by
+protected theorem natCast_succ (n : Nat) : ((n + 1 : Nat) : Int) = (n : Int) + 1 := rfl
+
+@[simp] protected theorem natCast_mul (a b : Nat) : ((a * b : Nat) : Int) = (a : Int) * (b : Int) := by
   simp
 
 end Int

src/Init/Data/Int/LemmasAux.lean

@@ -5,6 +5,7 @@ Authors: Kim Morrison
 -/
 prelude
 import Init.Data.Int.Order
+import Init.Data.Int.DivMod.Lemmas
 import Init.Omega
 
 
@@ -14,6 +15,32 @@ import Init.Omega
 
 namespace Int
 
+/-! ### miscellaneous lemmas -/
+
+@[simp] theorem natCast_le_zero : {n : Nat} → (n : Int) ≤ 0 ↔ n = 0 := by omega
+
+protected theorem sub_eq_iff_eq_add {b a c : Int} : a - b = c ↔ a = c + b := by omega
+protected theorem sub_eq_iff_eq_add' {b a c : Int} : a - b = c ↔ a = b + c := by omega
+
+@[simp] protected theorem neg_nonpos_iff (i : Int) : -i ≤ 0 ↔ 0 ≤ i := by omega
+
+@[simp] theorem zero_le_ofNat (n : Nat) : 0 ≤ ((no_index (OfNat.ofNat n)) : Int) :=
+  ofNat_nonneg _
+
+@[simp] theorem neg_natCast_le_natCast (n m : Nat) : -(n : Int) ≤ (m : Int) :=
+  Int.le_trans (by simp) (ofNat_zero_le m)
+
+@[simp] theorem neg_natCast_le_ofNat (n m : Nat) : -(n : Int) ≤ (no_index (OfNat.ofNat m)) :=
+  Int.le_trans (by simp) (ofNat_zero_le m)
+
+@[simp] theorem neg_ofNat_le_ofNat (n m : Nat) : -(no_index (OfNat.ofNat n)) ≤ (no_index (OfNat.ofNat m)) :=
+  Int.le_trans (by simp) (ofNat_zero_le m)
+
+@[simp] theorem neg_ofNat_le_natCast (n m : Nat) : -(no_index (OfNat.ofNat n)) ≤ (m : Int) :=
+  Int.le_trans (by simp) (ofNat_zero_le m)
+
+/-! ### toNat -/
+
 @[simp] theorem toNat_sub' (a : Int) (b : Nat) : (a - b).toNat = a.toNat - b := by
   symm
   simp only [Int.toNat]
@@ -38,6 +65,60 @@ namespace Int
   simp [toNat]
   split <;> simp_all <;> omega
 
+@[simp] theorem toNat_eq_zero : ∀ {n : Int}, n.toNat = 0 ↔ n ≤ 0 := by omega
+
+@[simp] theorem toNat_le {m : Int} {n : Nat} : m.toNat ≤ n ↔ m ≤ n := by omega
+@[simp] theorem toNat_lt' {m : Int} {n : Nat} (hn : 0 < n) : m.toNat < n ↔ m < n := by omega
+
+/-! ### natAbs -/
+
+theorem eq_zero_of_dvd_of_natAbs_lt_natAbs {d n : Int} (h : d ∣ n) (h₁ : n.natAbs < d.natAbs) :
+    n = 0 := by
+  obtain ⟨a, rfl⟩ := h
+  rw [natAbs_mul] at h₁
+  suffices ¬ 0 < a.natAbs by simp [Int.natAbs_eq_zero.1 (Nat.eq_zero_of_not_pos this)]
+  exact fun h => Nat.lt_irrefl _ (Nat.lt_of_le_of_lt (Nat.le_mul_of_pos_right d.natAbs h) h₁)
+
+/-! ### min and max -/
+
+@[simp] protected theorem min_assoc : ∀ (a b c : Int), min (min a b) c = min a (min b c) := by omega
+instance : Std.Associative (α := Nat) min := ⟨Nat.min_assoc⟩
+
+@[simp] protected theorem min_self_assoc {m n : Int} : min m (min m n) = min m n := by
+  rw [← Int.min_assoc, Int.min_self]
+
+@[simp] protected theorem min_self_assoc' {m n : Int} : min n (min m n) = min n m := by
+  rw [Int.min_comm m n, ← Int.min_assoc, Int.min_self]
+
+@[simp] protected theorem max_assoc (a b c : Int) : max (max a b) c = max a (max b c) := by omega
+instance : Std.Associative (α := Nat) max := ⟨Nat.max_assoc⟩
+
+@[simp] protected theorem max_self_assoc {m n : Int} : max m (max m n) = max m n := by
+  rw [← Int.max_assoc, Int.max_self]
+
+@[simp] protected theorem max_self_assoc' {m n : Int} : max n (max m n) = max n m := by
+  rw [Int.max_comm m n, ← Int.max_assoc, Int.max_self]
+
+protected theorem max_min_distrib_left (a b c : Int) : max a (min b c) = min (max a b) (max a c) := by omega
+
+protected theorem min_max_distrib_left (a b c : Int) : min a (max b c) = max (min a b) (min a c) := by omega
+
+protected theorem max_min_distrib_right (a b c : Int) :
+    max (min a b) c = min (max a c) (max b c) := by omega
+
+protected theorem min_max_distrib_right (a b c : Int) :
+    min (max a b) c = max (min a c) (min b c) := by omega
+
+protected theorem sub_min_sub_right (a b c : Int) : min (a - c) (b - c) = min a b - c := by omega
+
+protected theorem sub_max_sub_right (a b c : Int) : max (a - c) (b - c) = max a b - c := by omega
+
+protected theorem sub_min_sub_left (a b c : Int) : min (a - b) (a - c) = a - max b c := by omega
+
+protected theorem sub_max_sub_left (a b c : Int) : max (a - b) (a - c) = a - min b c := by omega
+
+/-! ### bmod -/
+
 theorem bmod_neg_iff {m : Nat} {x : Int} (h2 : -m ≤ x) (h1 : x < m) :
     (x.bmod m) < 0 ↔ (-(m / 2) ≤ x ∧ x < 0) ∨ ((m + 1) / 2 ≤ x) := by
   simp only [Int.bmod_def]
@@ -45,4 +126,18 @@ theorem bmod_neg_iff {m : Nat} {x : Int} (h2 : -m ≤ x) (h1 : x < m) :
   · rw [Int.emod_eq_of_lt xpos (by omega)]; omega
   · rw [Int.add_emod_self.symm, Int.emod_eq_of_lt (by omega) (by omega)]; omega
 
+theorem bmod_eq_self_of_le {n : Int} {m : Nat} (hn' : -(m / 2) ≤ n) (hn : n < (m + 1) / 2) :
+    n.bmod m = n := by
+  rw [← Int.sub_eq_zero]
+  have := le_bmod (x := n) (m := m) (by omega)
+  have := bmod_lt (x := n) (m := m) (by omega)
+  apply eq_zero_of_dvd_of_natAbs_lt_natAbs Int.dvd_bmod_sub_self
+  omega
+
+theorem bmod_bmod_of_dvd {a : Int} {n m : Nat} (hnm : n ∣ m) :
+    (a.bmod m).bmod n = a.bmod n := by
+  rw [← Int.sub_eq_iff_eq_add.2 (bmod_add_bdiv a m).symm]
+  obtain ⟨k, rfl⟩ := hnm
+  simp [Int.mul_assoc]
+
 end Int

src/Init/Data/Int/OfNat.lean

@@ -0,0 +1,90 @@
+/-
+Copyright (c) 2025 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+Released under Apache 2.0 license as described in the file LICENSE.
+Authors: Leonardo de Moura
+-/
+prelude
+import Init.Data.Int.Lemmas
+import Init.Data.Int.DivMod
+import Init.Data.RArray
+
+namespace Int.OfNat
+/-!
+Helper definitions and theorems for converting `Nat` expressions into `Int` one.
+We use them to implement the arithmetic theories in `grind`
+-/
+
+abbrev Var := Nat
+abbrev Context := Lean.RArray Nat
+def Var.denote (ctx : Context) (v : Var) : Nat :=
+  ctx.get v
+
+inductive Expr where
+  | num  (v : Nat)
+  | var  (i : Var)
+  | add  (a b : Expr)
+  | mul  (a b : Expr)
+  | div  (a b : Expr)
+  | mod  (a b : Expr)
+  deriving BEq
+
+def Expr.denote (ctx : Context) : Expr → Nat
+  | .num k    => k
+  | .var v    => v.denote ctx
+  | .add a b  => Nat.add (denote ctx a) (denote ctx b)
+  | .mul a b  => Nat.mul (denote ctx a) (denote ctx b)
+  | .div a b  => Nat.div (denote ctx a) (denote ctx b)
+  | .mod a b  => Nat.mod (denote ctx a) (denote ctx b)
+
+def Expr.denoteAsInt (ctx : Context) : Expr → Int
+  | .num k    => Int.ofNat k
+  | .var v    => Int.ofNat (v.denote ctx)
+  | .add a b  => Int.add (denoteAsInt ctx a) (denoteAsInt ctx b)
+  | .mul a b  => Int.mul (denoteAsInt ctx a) (denoteAsInt ctx b)
+  | .div a b  => Int.ediv (denoteAsInt ctx a) (denoteAsInt ctx b)
+  | .mod a b  => Int.emod (denoteAsInt ctx a) (denoteAsInt ctx b)
+
+theorem Expr.denoteAsInt_eq (ctx : Context) (e : Expr) : e.denoteAsInt ctx = e.denote ctx := by
+  induction e <;> simp [denote, denoteAsInt, Int.ofNat_ediv, *] <;> rfl
+
+theorem Expr.eq (ctx : Context) (lhs rhs : Expr)
+    : (lhs.denote ctx = rhs.denote ctx) = (lhs.denoteAsInt ctx = rhs.denoteAsInt ctx) := by
+  simp [denoteAsInt_eq, Int.ofNat_inj]
+
+theorem Expr.le (ctx : Context) (lhs rhs : Expr)
+    : (lhs.denote ctx ≤ rhs.denote ctx) = (lhs.denoteAsInt ctx ≤ rhs.denoteAsInt ctx) := by
+  simp [denoteAsInt_eq, Int.ofNat_le]
+
+theorem of_le (ctx : Context) (lhs rhs : Expr)
+    : lhs.denote ctx ≤ rhs.denote ctx → lhs.denoteAsInt ctx ≤ rhs.denoteAsInt ctx := by
+  rw [Expr.le ctx lhs rhs]; simp
+
+theorem of_not_le (ctx : Context) (lhs rhs : Expr)
+    : ¬ lhs.denote ctx ≤ rhs.denote ctx → ¬ lhs.denoteAsInt ctx ≤ rhs.denoteAsInt ctx := by
+  rw [Expr.le ctx lhs rhs]; simp
+
+theorem of_dvd (ctx : Context) (d : Nat) (e : Expr)
+    : d ∣ e.denote ctx → Int.ofNat d ∣ e.denoteAsInt ctx := by
+  simp [Expr.denoteAsInt_eq, Int.ofNat_dvd]
+
+theorem of_eq (ctx : Context) (lhs rhs : Expr)
+    : lhs.denote ctx = rhs.denote ctx → lhs.denoteAsInt ctx = rhs.denoteAsInt ctx := by
+  rw [Expr.eq ctx lhs rhs]; simp
+
+theorem of_not_eq (ctx : Context) (lhs rhs : Expr)
+    : ¬ lhs.denote ctx = rhs.denote ctx → ¬ lhs.denoteAsInt ctx = rhs.denoteAsInt ctx := by
+  rw [Expr.eq ctx lhs rhs]; simp
+
+theorem ofNat_toNat (a : Int) : (NatCast.natCast a.toNat : Int) = if a ≤ 0 then 0 else a := by
+  split
+  next h =>
+    rw [Int.toNat_of_nonpos h]; rfl
+  next h =>
+    simp at h
+    have := Int.toNat_of_nonneg (Int.le_of_lt h)
+    assumption
+
+theorem Expr.denoteAsInt_nonneg (ctx : Context) (e : Expr) : e.denoteAsInt ctx ≥ 0 := by
+  simp [Expr.denoteAsInt_eq]
+
+end Int.OfNat

src/Init/Data/Int/Order.lean

@@ -33,20 +33,18 @@ theorem lt_iff_add_one_le {a b : Int} : a < b ↔ a + 1 ≤ b := .rfl
 theorem le.intro_sub {a b : Int} (n : Nat) (h : b - a = n) : a ≤ b := by
   simp [le_def, h]; constructor
 
-attribute [local simp] Int.add_left_neg Int.add_right_neg Int.neg_add
-
 theorem le.intro {a b : Int} (n : Nat) (h : a + n = b) : a ≤ b :=
-  le.intro_sub n <| by rw [← h, Int.add_comm]; simp [Int.sub_eq_add_neg, Int.add_assoc]
+  le.intro_sub n <| by rw [← h, Int.add_comm]; simp [Int.sub_eq_add_neg, Int.add_assoc, Int.add_right_neg]
 
 theorem le.dest_sub {a b : Int} (h : a ≤ b) : ∃ n : Nat, b - a = n := nonneg_def.1 h
 
 theorem le.dest {a b : Int} (h : a ≤ b) : ∃ n : Nat, a + n = b :=
   let ⟨n, h₁⟩ := le.dest_sub h
-  ⟨n, by rw [← h₁, Int.add_comm]; simp [Int.sub_eq_add_neg, Int.add_assoc]⟩
+  ⟨n, by rw [← h₁, Int.add_comm]; simp [Int.sub_eq_add_neg, Int.add_assoc, Int.add_left_neg]⟩
 
 protected theorem le_total (a b : Int) : a ≤ b ∨ b ≤ a :=
   (nonneg_or_nonneg_neg (b - a)).imp_right fun H => by
-    rwa [show -(b - a) = a - b by simp [Int.add_comm, Int.sub_eq_add_neg]] at H
+    rwa [show -(b - a) = a - b by simp [Int.neg_add,Int.add_comm, Int.sub_eq_add_neg]] at H
 
 @[simp, norm_cast] theorem ofNat_le {m n : Nat} : (↑m : Int) ≤ ↑n ↔ m ≤ n :=
   ⟨fun h =>
@@ -56,19 +54,19 @@ protected theorem le_total (a b : Int) : a ≤ b ∨ b ≤ a :=
     let ⟨k, (hk : m + k = n)⟩ := Nat.le.dest h
     le.intro k (by rw [← hk]; rfl)⟩
 
-theorem ofNat_zero_le (n : Nat) : 0 ≤ (↑n : Int) := ofNat_le.2 n.zero_le
+@[simp] theorem ofNat_zero_le (n : Nat) : 0 ≤ (↑n : Int) := ofNat_le.2 n.zero_le
 
 theorem eq_ofNat_of_zero_le {a : Int} (h : 0 ≤ a) : ∃ n : Nat, a = n := by
   have t := le.dest_sub h; rwa [Int.sub_zero] at t
 
-theorem eq_succ_of_zero_lt {a : Int} (h : 0 < a) : ∃ n : Nat, a = n.succ :=
+theorem eq_succ_of_zero_lt {a : Int} (h : 0 < a) : ∃ n : Nat, a = n + 1 :=
   let ⟨n, (h : ↑(1 + n) = a)⟩ := le.dest h
   ⟨n, by rw [Nat.add_comm] at h; exact h.symm⟩
 
-theorem lt_add_succ (a : Int) (n : Nat) : a < a + Nat.succ n :=
-  le.intro n <| by rw [Int.add_comm, Int.add_left_comm]; rfl
+theorem lt_add_succ (a : Int) (n : Nat) : a < a + (n + 1) :=
+  le.intro n <| by rw [Int.add_comm, Int.add_left_comm]
 
-theorem lt.intro {a b : Int} {n : Nat} (h : a + Nat.succ n = b) : a < b :=
+theorem lt.intro {a b : Int} {n : Nat} (h : a + (n + 1) = b) : a < b :=
   h ▸ lt_add_succ a n
 
 theorem lt.dest {a b : Int} (h : a < b) : ∃ n : Nat, a + Nat.succ n = b :=
@@ -117,7 +115,7 @@ protected theorem lt_iff_le_and_ne {a b : Int} : a < b ↔ a ≤ b ∧ a ≠ b :
   have : n ≠ 0 := aneb.imp fun eq => by rw [← hn, eq, ofNat_zero, Int.add_zero]
   apply lt.intro; rwa [← Nat.succ_pred_eq_of_pos (Nat.pos_of_ne_zero this)] at hn
 
-theorem lt_succ (a : Int) : a < a + 1 := Int.le_refl _
+protected theorem lt_succ (a : Int) : a < a + 1 := Int.le_refl _
 
 protected theorem zero_lt_one : (0 : Int) < 1 := ⟨_⟩
 
@@ -133,12 +131,15 @@ protected theorem lt_of_not_ge {a b : Int} (h : ¬a ≤ b) : b < a :=
 protected theorem not_le_of_gt {a b : Int} (h : b < a) : ¬a ≤ b :=
   (Int.lt_iff_le_not_le.mp h).right
 
-protected theorem not_le {a b : Int} : ¬a ≤ b ↔ b < a :=
+@[simp] protected theorem not_le {a b : Int} : ¬a ≤ b ↔ b < a :=
   Iff.intro Int.lt_of_not_ge Int.not_le_of_gt
 
-protected theorem not_lt {a b : Int} : ¬a < b ↔ b ≤ a :=
+@[simp] protected theorem not_lt {a b : Int} : ¬a < b ↔ b ≤ a :=
   by rw [← Int.not_le, Decidable.not_not]
 
+protected theorem le_of_not_gt {a b : Int} (h : ¬ a > b) : a ≤ b :=
+  Int.not_lt.mp h
+
 protected theorem lt_trichotomy (a b : Int) : a < b ∨ a = b ∨ b < a :=
   if eq : a = b then .inr <| .inl eq else
   if le : a ≤ b then .inl <| Int.lt_iff_le_and_ne.2 ⟨le, eq⟩ else
@@ -183,61 +184,19 @@ instance : Trans (α := Int) (· ≤ ·) (· < ·) (· < ·) := ⟨Int.lt_of_le_
 
 instance : Trans (α := Int) (· < ·) (· < ·) (· < ·) := ⟨Int.lt_trans⟩
 
-protected theorem min_def (n m : Int) : min n m = if n ≤ m then n else m := rfl
-
-protected theorem max_def (n m : Int) : max n m = if n ≤ m then m else n := rfl
-
-protected theorem min_comm (a b : Int) : min a b = min b a := by
-  simp [Int.min_def]
-  by_cases h₁ : a ≤ b <;> by_cases h₂ : b ≤ a <;> simp [h₁, h₂]
-  · exact Int.le_antisymm h₁ h₂
-  · cases not_or_intro h₁ h₂ <| Int.le_total ..
-instance : Std.Commutative (α := Int) min := ⟨Int.min_comm⟩
-
-protected theorem min_le_right (a b : Int) : min a b ≤ b := by rw [Int.min_def]; split <;> simp [*]
-
-protected theorem min_le_left (a b : Int) : min a b ≤ a := Int.min_comm .. ▸ Int.min_le_right ..
-
-protected theorem min_eq_left {a b : Int} (h : a ≤ b) : min a b = a := by simp [Int.min_def, h]
-
-protected theorem min_eq_right {a b : Int} (h : b ≤ a) : min a b = b := by
-  rw [Int.min_comm a b]; exact Int.min_eq_left h
-
-protected theorem le_min {a b c : Int} : a ≤ min b c ↔ a ≤ b ∧ a ≤ c :=
-  ⟨fun h => ⟨Int.le_trans h (Int.min_le_left ..), Int.le_trans h (Int.min_le_right ..)⟩,
-   fun ⟨h₁, h₂⟩ => by rw [Int.min_def]; split <;> assumption⟩
-
-protected theorem max_comm (a b : Int) : max a b = max b a := by
-  simp only [Int.max_def]
-  by_cases h₁ : a ≤ b <;> by_cases h₂ : b ≤ a <;> simp [h₁, h₂]
-  · exact Int.le_antisymm h₂ h₁
-  · cases not_or_intro h₁ h₂ <| Int.le_total ..
-instance : Std.Commutative (α := Int) max := ⟨Int.max_comm⟩
-
-protected theorem le_max_left (a b : Int) : a ≤ max a b := by rw [Int.max_def]; split <;> simp [*]
-
-protected theorem le_max_right (a b : Int) : b ≤ max a b := Int.max_comm .. ▸ Int.le_max_left ..
-
-protected theorem max_le {a b c : Int} : max a b ≤ c ↔ a ≤ c ∧ b ≤ c :=
-  ⟨fun h => ⟨Int.le_trans (Int.le_max_left ..) h, Int.le_trans (Int.le_max_right ..) h⟩,
-   fun ⟨h₁, h₂⟩ => by rw [Int.max_def]; split <;> assumption⟩
-
-protected theorem max_eq_right {a b : Int} (h : a ≤ b) : max a b = b := by
-  simp [Int.max_def, h, Int.not_lt.2 h]
-
-protected theorem max_eq_left {a b : Int} (h : b ≤ a) : max a b = a := by
-  rw [← Int.max_comm b a]; exact Int.max_eq_right h
-
-theorem eq_natAbs_of_zero_le {a : Int} (h : 0 ≤ a) : a = natAbs a := by
+theorem eq_natAbs_of_nonneg {a : Int} (h : 0 ≤ a) : a = natAbs a := by
   let ⟨n, e⟩ := eq_ofNat_of_zero_le h
   rw [e]; rfl
 
+@[deprecated eq_natAbs_of_nonneg (since := "2025-03-11")]
+abbrev eq_natAbs_of_zero_le := @eq_natAbs_of_nonneg
+
 theorem le_natAbs {a : Int} : a ≤ natAbs a :=
   match Int.le_total 0 a with
-  | .inl h => by rw [eq_natAbs_of_zero_le h]; apply Int.le_refl
+  | .inl h => by rw [eq_natAbs_of_nonneg h]; apply Int.le_refl
   | .inr h => Int.le_trans h (ofNat_zero_le _)
 
-theorem negSucc_lt_zero (n : Nat) : -[n+1] < 0 :=
+@[simp] theorem negSucc_lt_zero (n : Nat) : -[n+1] < 0 :=
   Int.not_le.1 fun h => let ⟨_, h⟩ := eq_ofNat_of_zero_le h; nomatch h
 
 theorem negSucc_le_zero (n : Nat) : -[n+1] ≤ 0 :=
@@ -246,18 +205,6 @@ theorem negSucc_le_zero (n : Nat) : -[n+1] ≤ 0 :=
 @[simp] theorem negSucc_not_nonneg (n : Nat) : 0 ≤ -[n+1] ↔ False := by
   simp only [Int.not_le, iff_false]; exact Int.negSucc_lt_zero n
 
-@[simp] theorem ofNat_max_zero (n : Nat) : (max (n : Int) 0) = n := by
-  rw [Int.max_eq_left (ofNat_zero_le n)]
-
-@[simp] theorem zero_max_ofNat (n : Nat) : (max 0 (n : Int)) = n := by
-  rw [Int.max_eq_right (ofNat_zero_le n)]
-
-@[simp] theorem negSucc_max_zero (n : Nat) : (max (Int.negSucc n) 0) = 0 := by
-  rw [Int.max_eq_right (negSucc_le_zero _)]
-
-@[simp] theorem zero_max_negSucc (n : Nat) : (max 0 (Int.negSucc n)) = 0 := by
-  rw [Int.max_eq_left (negSucc_le_zero _)]
-
 protected theorem add_le_add_left {a b : Int} (h : a ≤ b) (c : Int) : c + a ≤ c + b :=
   let ⟨n, hn⟩ := le.dest h; le.intro n <| by rw [Int.add_assoc, hn]
 
@@ -279,10 +226,10 @@ protected theorem le_of_add_le_add_left {a b c : Int} (h : a + b ≤ a + c) : b
 protected theorem le_of_add_le_add_right {a b c : Int} (h : a + b ≤ c + b) : a ≤ c :=
   Int.le_of_add_le_add_left (a := b) <| by rwa [Int.add_comm b a, Int.add_comm b c]
 
-protected theorem add_le_add_iff_left (a : Int) : a + b ≤ a + c ↔ b ≤ c :=
+@[simp] protected theorem add_le_add_iff_left (a : Int) : a + b ≤ a + c ↔ b ≤ c :=
   ⟨Int.le_of_add_le_add_left, (Int.add_le_add_left · _)⟩
 
-protected theorem add_le_add_iff_right (c : Int) : a + c ≤ b + c ↔ a ≤ b :=
+@[simp] protected theorem add_le_add_iff_right (c : Int) : a + c ≤ b + c ↔ a ≤ b :=
   ⟨Int.le_of_add_le_add_right, (Int.add_le_add_right · _)⟩
 
 protected theorem add_le_add {a b c d : Int} (h₁ : a ≤ b) (h₂ : c ≤ d) : a + c ≤ b + d :=
@@ -301,6 +248,15 @@ protected theorem neg_le_neg {a b : Int} (h : a ≤ b) : -b ≤ -a := by
   have : 0 + -b ≤ -a + b + -b := Int.add_le_add_right this (-b)
   rwa [Int.add_neg_cancel_right, Int.zero_add] at this
 
+@[simp] protected theorem neg_le_neg_iff {a b : Int} : -a ≤ -b ↔ b ≤ a :=
+  ⟨fun h => by simpa using Int.neg_le_neg h, Int.neg_le_neg⟩
+
+@[simp] protected theorem neg_le_zero_iff {a : Int} : -a ≤ 0 ↔ 0 ≤ a := by
+  rw [← Int.neg_zero, Int.neg_le_neg_iff, Int.neg_zero]
+
+@[simp] protected theorem zero_le_neg_iff {a : Int} : 0 ≤ -a ↔ a ≤ 0 := by
+  rw [← Int.neg_zero, Int.neg_le_neg_iff, Int.neg_zero]
+
 protected theorem le_of_neg_le_neg {a b : Int} (h : -b ≤ -a) : a ≤ b :=
   suffices - -a ≤ - -b by simp [Int.neg_neg] at this; assumption
   Int.neg_le_neg h
@@ -318,6 +274,15 @@ protected theorem neg_lt_neg {a b : Int} (h : a < b) : -b < -a := by
   have : 0 + -b < -a + b + -b := Int.add_lt_add_right this (-b)
   rwa [Int.add_neg_cancel_right, Int.zero_add] at this
 
+@[simp] protected theorem neg_lt_neg_iff {a b : Int} : -a < -b ↔ b < a :=
+  ⟨fun h => by simpa using Int.neg_lt_neg h, Int.neg_lt_neg⟩
+
+@[simp] protected theorem neg_lt_zero_iff {a : Int} : -a < 0 ↔ 0 < a := by
+  rw [← Int.neg_zero, Int.neg_lt_neg_iff, Int.neg_zero]
+
+@[simp] protected theorem zero_lt_neg_iff {a : Int} : 0 < -a ↔ a < 0 := by
+  rw [← Int.neg_zero, Int.neg_lt_neg_iff, Int.neg_zero]
+
 protected theorem neg_neg_of_pos {a : Int} (h : 0 < a) : -a < 0 := by
   have : -a < -0 := Int.neg_lt_neg h
   rwa [Int.neg_zero] at this
@@ -358,8 +323,124 @@ protected theorem sub_lt_self (a : Int) {b : Int} (h : 0 < b) : a - b < a :=
 
 theorem add_one_le_of_lt {a b : Int} (H : a < b) : a + 1 ≤ b := H
 
-/- ### Order properties and multiplication -/
+protected theorem le_iff_lt_add_one {a b : Int} : a ≤ b ↔ a < b + 1 := by
+  rw [Int.lt_iff_add_one_le]
+  exact (Int.add_le_add_iff_right 1).symm
 
+/- ### min and max -/
+
+protected theorem min_def (n m : Int) : min n m = if n ≤ m then n else m := rfl
+
+protected theorem max_def (n m : Int) : max n m = if n ≤ m then m else n := rfl
+
+@[simp] protected theorem neg_min_neg (a b : Int) : min (-a) (-b) = -max a b := by
+  rw [Int.min_def, Int.max_def]
+  simp
+  split <;> rename_i h₁ <;> split <;> rename_i h₂
+  · simpa using Int.le_antisymm h₂ h₁
+  · simp
+  · simp
+  · simp only [Int.not_le] at h₁ h₂
+    exfalso
+    exact Int.lt_irrefl _ (Int.lt_trans h₁ h₂)
+
+@[simp] protected theorem min_add_right (a b c : Int) : min (a + c) (b + c) = min a b + c := by
+  rw [Int.min_def, Int.min_def]
+  simp only [Int.add_le_add_iff_right]
+  split <;> simp
+
+@[simp] protected theorem min_add_left (a b c : Int) : min (a + b) (a + c) = a + min b c := by
+  rw [Int.min_def, Int.min_def]
+  simp only [Int.add_le_add_iff_left]
+  split <;> simp
+
+protected theorem min_comm (a b : Int) : min a b = min b a := by
+  simp [Int.min_def]
+  by_cases h₁ : a ≤ b <;> by_cases h₂ : b ≤ a <;> simp [h₁, h₂]
+  · exact Int.le_antisymm h₁ h₂
+  · cases not_or_intro h₁ h₂ <| Int.le_total ..
+instance : Std.Commutative (α := Int) min := ⟨Int.min_comm⟩
+
+protected theorem min_le_right (a b : Int) : min a b ≤ b := by rw [Int.min_def]; split <;> simp [*]
+
+protected theorem min_le_left (a b : Int) : min a b ≤ a := Int.min_comm .. ▸ Int.min_le_right ..
+
+protected theorem min_eq_left {a b : Int} (h : a ≤ b) : min a b = a := by simp [Int.min_def, h]
+
+protected theorem min_eq_right {a b : Int} (h : b ≤ a) : min a b = b := by
+  rw [Int.min_comm a b]; exact Int.min_eq_left h
+
+protected theorem le_min {a b c : Int} : a ≤ min b c ↔ a ≤ b ∧ a ≤ c :=
+  ⟨fun h => ⟨Int.le_trans h (Int.min_le_left ..), Int.le_trans h (Int.min_le_right ..)⟩,
+   fun ⟨h₁, h₂⟩ => by rw [Int.min_def]; split <;> assumption⟩
+
+protected theorem lt_min {a b c : Int} : a < min b c ↔ a < b ∧ a < c := Int.le_min
+
+@[simp] protected theorem neg_max_neg (a b : Int) : max (-a) (-b) = -min a b := by
+  rw [Int.min_def, Int.max_def]
+  simp
+  split <;> rename_i h₁ <;> split <;> rename_i h₂
+  · simpa using Int.le_antisymm h₁ h₂
+  · simp
+  · simp
+  · simp only [Int.not_le] at h₁ h₂
+    exfalso
+    exact Int.lt_irrefl _ (Int.lt_trans h₁ h₂)
+
+@[simp] protected theorem max_add_right (a b c : Int) : max (a + c) (b + c) = max a b + c := by
+  rw [Int.max_def, Int.max_def]
+  simp only [Int.add_le_add_iff_right]
+  split <;> simp
+
+@[simp] protected theorem max_add_left (a b c : Int) : max (a + b) (a + c) = a + max b c := by
+  rw [Int.max_def, Int.max_def]
+  simp only [Int.add_le_add_iff_left]
+  split <;> simp
+
+protected theorem max_comm (a b : Int) : max a b = max b a := by
+  simp only [Int.max_def]
+  by_cases h₁ : a ≤ b <;> by_cases h₂ : b ≤ a <;> simp [h₁, h₂]
+  · exact Int.le_antisymm h₂ h₁
+  · cases not_or_intro h₁ h₂ <| Int.le_total ..
+instance : Std.Commutative (α := Int) max := ⟨Int.max_comm⟩
+
+protected theorem le_max_left (a b : Int) : a ≤ max a b := by rw [Int.max_def]; split <;> simp [*]
+
+protected theorem le_max_right (a b : Int) : b ≤ max a b := Int.max_comm .. ▸ Int.le_max_left ..
+
+protected theorem max_eq_right {a b : Int} (h : a ≤ b) : max a b = b := by
+  simp [Int.max_def, h, Int.not_lt.2 h]
+
+protected theorem max_eq_left {a b : Int} (h : b ≤ a) : max a b = a := by
+  rw [← Int.max_comm b a]; exact Int.max_eq_right h
+
+protected theorem max_le {a b c : Int} : max a b ≤ c ↔ a ≤ c ∧ b ≤ c :=
+  ⟨fun h => ⟨Int.le_trans (Int.le_max_left ..) h, Int.le_trans (Int.le_max_right ..) h⟩,
+   fun ⟨h₁, h₂⟩ => by rw [Int.max_def]; split <;> assumption⟩
+
+protected theorem max_lt {a b c : Int} : max a b < c ↔ a < c ∧ b < c := by
+  simp only [Int.lt_iff_add_one_le]
+  simpa using Int.max_le (a := a + 1) (b := b + 1) (c := c)
+
+@[simp] theorem ofNat_max_zero (n : Nat) : (max (n : Int) 0) = n := by
+  rw [Int.max_eq_left (ofNat_zero_le n)]
+
+@[simp] theorem zero_max_ofNat (n : Nat) : (max 0 (n : Int)) = n := by
+  rw [Int.max_eq_right (ofNat_zero_le n)]
+
+@[simp] theorem negSucc_max_zero (n : Nat) : (max (Int.negSucc n) 0) = 0 := by
+  rw [Int.max_eq_right (negSucc_le_zero _)]
+
+@[simp] theorem zero_max_negSucc (n : Nat) : (max 0 (Int.negSucc n)) = 0 := by
+  rw [Int.max_eq_left (negSucc_le_zero _)]
+
+@[simp] protected theorem min_self (a : Int) : min a a = a := Int.min_eq_left (Int.le_refl _)
+instance : Std.IdempotentOp (α := Int) min := ⟨Int.min_self⟩
+
+@[simp] protected theorem max_self (a : Int) : max a a = a := Int.max_eq_right (Int.le_refl _)
+instance : Std.IdempotentOp (α := Int) max := ⟨Int.max_self⟩
+
+/- ### Order properties and multiplication -/
 
 protected theorem mul_nonneg {a b : Int} (ha : 0 ≤ a) (hb : 0 ≤ b) : 0 ≤ a * b := by
   let ⟨n, hn⟩ := eq_ofNat_of_zero_le ha
@@ -369,7 +450,8 @@ protected theorem mul_nonneg {a b : Int} (ha : 0 ≤ a) (hb : 0 ≤ b) : 0 ≤ a
 protected theorem mul_pos {a b : Int} (ha : 0 < a) (hb : 0 < b) : 0 < a * b := by
   let ⟨n, hn⟩ := eq_succ_of_zero_lt ha
   let ⟨m, hm⟩ := eq_succ_of_zero_lt hb
-  rw [hn, hm, ← ofNat_mul]; apply ofNat_succ_pos
+  rw [hn, hm]
+  apply ofNat_succ_pos
 
 protected theorem mul_lt_mul_of_pos_left {a b c : Int}
   (h₁ : a < b) (h₂ : 0 < c) : c * a < c * b := by
@@ -425,7 +507,7 @@ protected theorem mul_le_mul_of_nonpos_left {a b c : Int}
 
 /- ## natAbs -/
 
-@[simp] theorem natAbs_ofNat (n : Nat) : natAbs ↑n = n := rfl
+@[simp, norm_cast] theorem natAbs_ofNat (n : Nat) : natAbs ↑n = n := rfl
 @[simp] theorem natAbs_negSucc (n : Nat) : natAbs -[n+1] = n.succ := rfl
 @[simp] theorem natAbs_zero : natAbs (0 : Int) = (0 : Nat) := rfl
 @[simp] theorem natAbs_one : natAbs (1 : Int) = (1 : Nat) := rfl
@@ -470,6 +552,13 @@ theorem natAbs_of_nonneg {a : Int} (H : 0 ≤ a) : (natAbs a : Int) = a :=
 theorem ofNat_natAbs_of_nonpos {a : Int} (H : a ≤ 0) : (natAbs a : Int) = -a := by
   rw [← natAbs_neg, natAbs_of_nonneg (Int.neg_nonneg_of_nonpos H)]
 
+theorem natAbs_sub_of_nonneg_of_le {a b : Int} (h₁ : 0 ≤ b) (h₂ : b ≤ a) :
+    (a - b).natAbs = a.natAbs - b.natAbs := by
+  rw [← Int.ofNat_inj]
+  rw [natAbs_of_nonneg, ofNat_sub, natAbs_of_nonneg (Int.le_trans h₁ h₂), natAbs_of_nonneg h₁]
+  · rwa [← Int.ofNat_le, natAbs_of_nonneg h₁, natAbs_of_nonneg (Int.le_trans h₁ h₂)]
+  · exact Int.sub_nonneg_of_le h₂
+
 /-! ### toNat -/
 
 theorem toNat_eq_max : ∀ a : Int, (toNat a : Int) = max a 0
@@ -492,8 +581,8 @@ theorem toNat_of_nonneg {a : Int} (h : 0 ≤ a) : (toNat a : Int) = a := by
 
 @[simp] theorem ofNat_toNat (a : Int) : (a.toNat : Int) = max a 0 := by
   match a with
-  | Int.ofNat n => simp
-  | Int.negSucc n => simp
+  | (n : Nat) => simp
+  | -(n + 1 : Nat) => norm_cast
 
 theorem self_le_toNat (a : Int) : a ≤ toNat a := by rw [toNat_eq_max]; apply Int.le_max_left
 
@@ -529,12 +618,15 @@ theorem toNat_sub_toNat_neg : ∀ n : Int, ↑n.toNat - ↑(-n).toNat = n
   | 0 => rfl
   | _+1 => rfl
 
-/-! ### toNat' -/
+/-! ### toNat? -/
 
-theorem mem_toNat' : ∀ {a : Int} {n : Nat}, toNat' a = some n ↔ a = n
-  | (m : Nat), n => by simp [toNat', Int.ofNat_inj]
+theorem mem_toNat? : ∀ {a : Int} {n : Nat}, toNat? a = some n ↔ a = n
+  | (m : Nat), n => by simp [toNat?, Int.ofNat_inj]
   | -[m+1], n => by constructor <;> nofun
 
+@[deprecated mem_toNat? (since := "2025-03-11")]
+abbrev mem_toNat' := @mem_toNat?
+
 /-! ## Order properties of the integers -/
 
 protected theorem le_of_not_le {a b : Int} : ¬ a ≤ b → b ≤ a := (Int.le_total a b).resolve_left
@@ -554,10 +646,10 @@ protected theorem lt_of_add_lt_add_left {a b c : Int} (h : a + b < a + c) : b <
 protected theorem lt_of_add_lt_add_right {a b c : Int} (h : a + b < c + b) : a < c :=
   Int.lt_of_add_lt_add_left (a := b) <| by rwa [Int.add_comm b a, Int.add_comm b c]
 
-protected theorem add_lt_add_iff_left (a : Int) : a + b < a + c ↔ b < c :=
+@[simp] protected theorem add_lt_add_iff_left (a : Int) : a + b < a + c ↔ b < c :=
   ⟨Int.lt_of_add_lt_add_left, (Int.add_lt_add_left · _)⟩
 
-protected theorem add_lt_add_iff_right (c : Int) : a + c < b + c ↔ a < b :=
+@[simp] protected theorem add_lt_add_iff_right (c : Int) : a + c < b + c ↔ a < b :=
   ⟨Int.lt_of_add_lt_add_right, (Int.add_lt_add_right · _)⟩
 
 protected theorem add_lt_add {a b c d : Int} (h₁ : a < b) (h₂ : c < d) : a + c < b + d :=
@@ -752,6 +844,18 @@ protected theorem sub_le_sub_right {a b : Int} (h : a ≤ b) (c : Int) : a - c
 protected theorem sub_le_sub {a b c d : Int} (hab : a ≤ b) (hcd : c ≤ d) : a - d ≤ b - c :=
   Int.add_le_add hab (Int.neg_le_neg hcd)
 
+protected theorem le_of_sub_le_sub_left {a b c : Int} (h : c - a ≤ c - b) : b ≤ a :=
+  Int.le_of_neg_le_neg <| Int.le_of_add_le_add_left h
+
+protected theorem le_of_sub_le_sub_right {a b c : Int} (h : a - c ≤ b - c) : a ≤ b :=
+  Int.le_of_add_le_add_right h
+
+@[simp] protected theorem sub_le_sub_left_iff {a b c : Int} : c - a ≤ c - b ↔ b ≤ a :=
+  ⟨Int.le_of_sub_le_sub_left, (Int.sub_le_sub_left · c)⟩
+
+@[simp] protected theorem sub_le_sub_right_iff {a b c : Int} : a - c ≤ b - c ↔ a ≤ b :=
+  ⟨Int.le_of_sub_le_sub_right, (Int.sub_le_sub_right · c)⟩
+
 protected theorem add_lt_of_lt_neg_add {a b c : Int} (h : b < -a + c) : a + b < c := by
   have h := Int.add_lt_add_left h a
   rwa [Int.add_neg_cancel_left] at h
@@ -860,11 +964,11 @@ protected theorem lt_of_sub_lt_sub_right {a b c : Int} (h : a - c < b - c) : a <
   ⟨Int.lt_of_sub_lt_sub_right, (Int.sub_lt_sub_right · c)⟩
 
 protected theorem sub_lt_sub_of_le_of_lt {a b c d : Int}
-  (hab : a ≤ b) (hcd : c < d) : a - d < b - c :=
+    (hab : a ≤ b) (hcd : c < d) : a - d < b - c :=
   Int.add_lt_add_of_le_of_lt hab (Int.neg_lt_neg hcd)
 
 protected theorem sub_lt_sub_of_lt_of_le {a b c d : Int}
-  (hab : a < b) (hcd : c ≤ d) : a - d < b - c :=
+    (hab : a < b) (hcd : c ≤ d) : a - d < b - c :=
   Int.add_lt_add_of_lt_of_le hab (Int.neg_le_neg hcd)
 
 protected theorem add_le_add_three {a b c d e f : Int}
@@ -938,6 +1042,22 @@ protected theorem mul_self_le_mul_self {a b : Int} (h1 : 0 ≤ a) (h2 : a ≤ b)
 protected theorem mul_self_lt_mul_self {a b : Int} (h1 : 0 ≤ a) (h2 : a < b) : a * a < b * b :=
   Int.mul_lt_mul' (Int.le_of_lt h2) h2 h1 (Int.lt_of_le_of_lt h1 h2)
 
+protected theorem nonneg_of_mul_nonneg_left {a b : Int}
+    (h : 0 ≤ a * b) (hb : 0 < b) : 0 ≤ a :=
+  Int.le_of_not_gt fun ha => Int.not_le_of_gt (Int.mul_neg_of_neg_of_pos ha hb) h
+
+protected theorem nonneg_of_mul_nonneg_right {a b : Int}
+    (h : 0 ≤ a * b) (ha : 0 < a) : 0 ≤ b :=
+  Int.le_of_not_gt fun hb => Int.not_le_of_gt (Int.mul_neg_of_pos_of_neg ha hb) h
+
+protected theorem nonpos_of_mul_nonpos_left {a b : Int}
+    (h : a * b ≤ 0) (hb : 0 < b) : a ≤ 0 :=
+  Int.le_of_not_gt fun ha : a > 0 => Int.not_le_of_gt (Int.mul_pos ha hb) h
+
+protected theorem nonpos_of_mul_nonpos_right {a b : Int}
+    (h : a * b ≤ 0) (ha : 0 < a) : b ≤ 0 :=
+  Int.le_of_not_gt fun hb : b > 0 => Int.not_le_of_gt (Int.mul_pos ha hb) h
+
 /- ## sign -/
 
 @[simp] theorem sign_zero : sign 0 = 0 := rfl
@@ -988,10 +1108,10 @@ theorem neg_of_sign_eq_neg_one : ∀ {a : Int}, sign a = -1 → a < 0
   | 0, h => nomatch h
   | -[_+1], _ => negSucc_lt_zero _
 
-theorem sign_eq_one_iff_pos {a : Int} : sign a = 1 ↔ 0 < a :=
+@[simp] theorem sign_eq_one_iff_pos {a : Int} : sign a = 1 ↔ 0 < a :=
   ⟨pos_of_sign_eq_one, sign_eq_one_of_pos⟩
 
-theorem sign_eq_neg_one_iff_neg {a : Int} : sign a = -1 ↔ a < 0 :=
+@[simp] theorem sign_eq_neg_one_iff_neg {a : Int} : sign a = -1 ↔ a < 0 :=
   ⟨neg_of_sign_eq_neg_one, sign_eq_neg_one_of_neg⟩
 
 @[simp] theorem sign_eq_zero_iff_zero {a : Int} : sign a = 0 ↔ a = 0 :=
@@ -1003,7 +1123,7 @@ theorem sign_eq_neg_one_iff_neg {a : Int} : sign a = -1 ↔ a < 0 :=
   | .ofNat (_ + 1) => rfl
   | .negSucc _ => rfl
 
-@[simp] theorem sign_nonneg : 0 ≤ sign x ↔ 0 ≤ x := by
+@[simp] theorem sign_nonneg_iff : 0 ≤ sign x ↔ 0 ≤ x := by
   match x with
   | 0 => rfl
   | .ofNat (_ + 1) =>
@@ -1011,11 +1131,42 @@ theorem sign_eq_neg_one_iff_neg {a : Int} : sign a = -1 ↔ a < 0 :=
     exact Int.le_add_one (ofNat_nonneg _)
   | .negSucc _ => simp +decide [sign]
 
-theorem mul_sign : ∀ i : Int, i * sign i = natAbs i
+@[deprecated sign_nonneg_iff (since := "2025-03-11")] abbrev sign_nonneg := @sign_nonneg_iff
+
+@[simp] theorem sign_pos_iff : 0 < sign x ↔ 0 < x := by
+  match x with
+  | 0
+  | .ofNat (_ + 1) => simp
+  | .negSucc x => simp
+
+@[simp] theorem sign_nonpos_iff : sign x ≤ 0 ↔ x ≤ 0 := by
+  match x with
+  | 0 => rfl
+  | .ofNat (_ + 1) => simp
+  | .negSucc _ => simpa using negSucc_le_zero _
+
+@[simp] theorem sign_neg_iff : sign x < 0 ↔ x < 0 := by
+  match x with
+  | 0 => simp
+  | .ofNat (_ + 1) => simpa using le.intro_sub _ rfl
+  | .negSucc _ => simp
+
+@[simp] theorem mul_sign_self : ∀ i : Int, i * sign i = natAbs i
   | succ _ => Int.mul_one _
   | 0 => Int.mul_zero _
   | -[_+1] => Int.mul_neg_one _
 
+@[deprecated mul_sign_self (since := "2025-02-24")] abbrev mul_sign := @mul_sign_self
+
+@[simp] theorem sign_mul_self : sign i * i = natAbs i := by
+  rw [Int.mul_comm, mul_sign_self]
+
+theorem sign_trichotomy (a : Int) : sign a = 1 ∨ sign a = 0 ∨ sign a = -1 := by
+  match a with
+  | 0 => simp
+  | .ofNat (_ + 1) => simp
+  | .negSucc _ => simp
+
 /- ## natAbs -/
 
 theorem natAbs_ne_zero {a : Int} : a.natAbs ≠ 0 ↔ a ≠ 0 := not_congr Int.natAbs_eq_zero
@@ -1024,7 +1175,7 @@ theorem natAbs_mul_self : ∀ {a : Int}, ↑(natAbs a * natAbs a) = a * a
   | ofNat _ => rfl
   | -[_+1]  => rfl
 
-theorem eq_nat_or_neg (a : Int) : ∃ n : Nat, a = n ∨ a = -↑n := ⟨_, natAbs_eq a⟩
+protected theorem eq_nat_or_neg (a : Int) : ∃ n : Nat, a = n ∨ a = -↑n := ⟨_, natAbs_eq a⟩
 
 theorem natAbs_mul_natAbs_eq {a b : Int} {c : Nat}
     (h : a * b = (c : Int)) : a.natAbs * b.natAbs = c := by rw [← natAbs_mul, h, natAbs.eq_def]
@@ -1038,7 +1189,7 @@ theorem natAbs_eq_iff {a : Int} {n : Nat} : a.natAbs = n ↔ a = n ∨ a = -↑n
 theorem natAbs_add_le (a b : Int) : natAbs (a + b) ≤ natAbs a + natAbs b := by
   suffices ∀ a b : Nat, natAbs (subNatNat a b.succ) ≤ (a + b).succ by
     match a, b with
-    | (a:Nat), (b:Nat) => rw [ofNat_add_ofNat, natAbs_ofNat]; apply Nat.le_refl
+    | (a:Nat), (b:Nat) => rw [← ofNat_add, natAbs_ofNat]; apply Nat.le_refl
     | (a:Nat), -[b+1]  => rw [natAbs_ofNat, natAbs_negSucc]; apply this
     | -[a+1],  (b:Nat) =>
       rw [natAbs_negSucc, natAbs_ofNat, Nat.succ_add, Nat.add_comm a b]; apply this
@@ -1057,6 +1208,7 @@ theorem natAbs_add_le (a b : Int) : natAbs (a + b) ≤ natAbs a + natAbs b := by
 theorem natAbs_sub_le (a b : Int) : natAbs (a - b) ≤ natAbs a + natAbs b := by
   rw [← Int.natAbs_neg b]; apply natAbs_add_le
 
+@[deprecated negSucc_eq (since := "2025-03-11")]
 theorem negSucc_eq' (m : Nat) : -[m+1] = -m - 1 := by simp only [negSucc_eq, Int.neg_add]; rfl
 
 theorem natAbs_lt_natAbs_of_nonneg_of_lt {a b : Int}
@@ -1064,7 +1216,10 @@ theorem natAbs_lt_natAbs_of_nonneg_of_lt {a b : Int}
   match a, b, eq_ofNat_of_zero_le w₁, eq_ofNat_of_zero_le (Int.le_trans w₁ (Int.le_of_lt w₂)) with
   | _, _, ⟨_, rfl⟩, ⟨_, rfl⟩ => ofNat_lt.1 w₂
 
-theorem eq_natAbs_iff_mul_eq_zero : natAbs a = n ↔ (a - n) * (a + n) = 0 := by
+theorem natAbs_eq_iff_mul_eq_zero : natAbs a = n ↔ (a - n) * (a + n) = 0 := by
   rw [natAbs_eq_iff, Int.mul_eq_zero, ← Int.sub_neg, Int.sub_eq_zero, Int.sub_eq_zero]
 
+@[deprecated natAbs_eq_iff_mul_eq_zero (since := "2025-03-11")]
+abbrev eq_natAbs_iff_mul_eq_zero := @natAbs_eq_iff_mul_eq_zero
+
 end Int

src/Init/Data/Int/Pow.lean

@@ -11,7 +11,7 @@ namespace Int
 
 /-! # pow -/
 
-protected theorem pow_zero (b : Int) : b^0 = 1 := rfl
+@[simp] protected theorem pow_zero (b : Int) : b^0 = 1 := rfl
 
 protected theorem pow_succ (b : Int) (e : Nat) : b ^ (e+1) = (b ^ e) * b := rfl
 protected theorem pow_succ' (b : Int) (e : Nat) : b ^ (e+1) = b * (b ^ e) := by
@@ -27,11 +27,11 @@ abbrev pow_le_pow_of_le_right := @Nat.pow_le_pow_right
 abbrev pos_pow_of_pos := @Nat.pow_pos
 
 @[norm_cast]
-theorem natCast_pow (b n : Nat) : ((b^n : Nat) : Int) = (b : Int) ^ n := by
+protected theorem natCast_pow (b n : Nat) : ((b^n : Nat) : Int) = (b : Int) ^ n := by
   match n with
   | 0 => rfl
   | n + 1 =>
-    simp only [Nat.pow_succ, Int.pow_succ, natCast_mul, natCast_pow _ n]
+    simp only [Nat.pow_succ, Int.pow_succ, Int.natCast_mul, Int.natCast_pow _ n]
 
 @[simp]
 protected theorem two_pow_pred_sub_two_pow {w : Nat} (h : 0 < w) :

src/Init/Data/List/Attach.lean

@@ -8,34 +8,49 @@ import Init.Data.List.Count
 import Init.Data.Subtype
 import Init.BinderNameHint
 
--- set_option linter.listVariables true -- Enforce naming conventions for `List`/`Array`/`Vector` variables.
--- set_option linter.indexVariables true -- Enforce naming conventions for index variables.
+set_option linter.listVariables true -- Enforce naming conventions for `List`/`Array`/`Vector` variables.
+set_option linter.indexVariables true -- Enforce naming conventions for index variables.
 
 namespace List
 
-/-- `O(n)`. Partial map. If `f : Π a, P a → β` is a partial function defined on
-  `a : α` satisfying `P`, then `pmap f l h` is essentially the same as `map f l`
-  but is defined only when all members of `l` satisfy `P`, using the proof
-  to apply `f`. -/
+/--
+Maps a partially defined function (defined on those terms of `α` that satisfy a predicate `P`) over
+a list `l : List α`, given a proof that every element of `l` in fact satisfies `P`.
+
+`O(|l|)`. `List.pmap`, named for “partial map,” is the equivalent of `List.map` for such partial
+functions.
+-/
 def pmap {P : α → Prop} (f : ∀ a, P a → β) : ∀ l : List α, (H : ∀ a ∈ l, P a) → List β
   | [], _ => []
   | a :: l, H => f a (forall_mem_cons.1 H).1 :: pmap f l (forall_mem_cons.1 H).2
 
 /--
-Unsafe implementation of `attachWith`, taking advantage of the fact that the representation of
+Unsafe implementation of `attachWith` that takes advantage of the fact that the representation of
 `List {x // P x}` is the same as the input `List α`.
-(Someday, the compiler might do this optimization automatically, but until then...)
 -/
 @[inline] private unsafe def attachWithImpl
     (l : List α) (P : α → Prop) (_ : ∀ x ∈ l, P x) : List {x // P x} := unsafeCast l
 
-/-- `O(1)`. "Attach" a proof `P x` that holds for all the elements of `l` to produce a new list
-  with the same elements but in the type `{x // P x}`. -/
+/--
+“Attaches” individual proofs to a list of values that satisfy a predicate `P`, returning a list of
+elements in the corresponding subtype `{ x // P x }`.
+
+`O(1)`.
+-/
 @[implemented_by attachWithImpl] def attachWith
     (l : List α) (P : α → Prop) (H : ∀ x ∈ l, P x) : List {x // P x} := pmap Subtype.mk l H
 
-/-- `O(1)`. "Attach" the proof that the elements of `l` are in `l` to produce a new list
-  with the same elements but in the type `{x // x ∈ l}`. -/
+/--
+“Attaches” the proof that the elements of `l` are in fact elements of `l`, producing a new list with
+the same elements but in the subtype `{ x // x ∈ l }`.
+
+`O(1)`.
+
+This function is primarily used to allow definitions by [well-founded
+recursion](lean-manual://section/well-founded-recursion) that use higher-order functions (such as
+`List.map`) to prove that an value taken from a list is smaller than the list. This allows the
+well-founded recursion mechanism to prove that the function terminates.
+-/
 @[inline] def attach (l : List α) : List {x // x ∈ l} := attachWith l _ fun _ => id
 
 /-- Implementation of `pmap` using the zero-copy version of `attach`. -/
@@ -190,7 +205,7 @@ theorem length_attachWith {p : α → Prop} {l H} : length (l.attachWith p H) =
 
 @[simp]
 theorem pmap_eq_nil_iff {p : α → Prop} {f : ∀ a, p a → β} {l H} : pmap f l H = [] ↔ l = [] := by
-  rw [← length_eq_zero, length_pmap, length_eq_zero]
+  rw [← length_eq_zero_iff, length_pmap, length_eq_zero_iff]
 
 theorem pmap_ne_nil_iff {P : α → Prop} (f : (a : α) → P a → β) {xs : List α}
     (H : ∀ (a : α), a ∈ xs → P a) : xs.pmap f H ≠ [] ↔ xs ≠ [] := by
@@ -650,11 +665,19 @@ Further, we provide simp lemmas that push `unattach` inwards.
 -/
 
 /--
-A synonym for `l.map (·.val)`. Mostly this should not be needed by users.
-It is introduced as an intermediate step by lemmas such as `map_subtype`,
-and is ideally subsequently simplified away by `unattach_attach`.
+Maps a list of terms in a subtype to the corresponding terms in the type by forgetting that they
+satisfy the predicate.
 
-If not, usually the right approach is `simp [List.unattach, -List.map_subtype]` to unfold.
+This is the inverse of `List.attachWith` and a synonym for `l.map (·.val)`.
+
+Mostly this should not be needed by users. It is introduced as an intermediate step by lemmas such
+as `map_subtype`, and is ideally subsequently simplified away by `unattach_attach`.
+
+This function is usually inserted automatically by Lean as an intermediate step while proving
+termination. It is rarely used explicitly in code. It is introduced as an intermediate step during
+the elaboration of definitions by [well-founded
+recursion](lean-manual://section/well-founded-recursion). If this function is encountered in a proof
+state, the right approach is usually the tactic `simp [List.unattach, -List.map_subtype]`.
 -/
 def unattach {α : Type _} {p : α → Prop} (l : List { x // p x }) : List α := l.map (·.val)
 
@@ -662,6 +685,10 @@ def unattach {α : Type _} {p : α → Prop} (l : List { x // p x }) : List α :
 @[simp] theorem unattach_cons {p : α → Prop} {a : { x // p x }} {l : List { x // p x }} :
   (a :: l).unattach = a.val :: l.unattach := rfl
 
+@[simp] theorem mem_unattach {p : α → Prop} {l : List { x // p x }} {a} :
+    a ∈ l.unattach ↔ ∃ h : p a, ⟨a, h⟩ ∈ l := by
+  simp only [unattach, mem_map, Subtype.exists, exists_and_right, exists_eq_right]
+
 @[simp] theorem length_unattach {p : α → Prop} {l : List { x // p x }} :
     l.unattach.length = l.length := by
   unfold unattach
@@ -766,6 +793,16 @@ and simplifies these to the function directly taking the value.
     simp [hf, find?_cons]
     split <;> simp [ih]
 
+@[simp] theorem all_subtype {p : α → Prop} {l : List { x // p x }} {f : { x // p x } → Bool} {g : α → Bool}
+    (hf : ∀ x h, f ⟨x, h⟩ = g x) :
+    l.all f = l.unattach.all g := by
+  simp [all_eq, hf]
+
+@[simp] theorem any_subtype {p : α → Prop} {l : List { x // p x }} {f : { x // p x } → Bool} {g : α → Bool}
+    (hf : ∀ x h, f ⟨x, h⟩ = g x) :
+    l.any f = l.unattach.any g := by
+  simp [any_eq, hf]
+
 /-! ### Simp lemmas pushing `unattach` inwards. -/
 
 @[simp] theorem unattach_filter {p : α → Prop} {l : List { x // p x }}

src/Init/Data/List/BasicAux.lean

@@ -6,8 +6,8 @@ Author: Leonardo de Moura
 prelude
 import Init.Data.Nat.Linear
 
--- set_option linter.listVariables true -- Enforce naming conventions for `List`/`Array`/`Vector` variables.
--- set_option linter.indexVariables true -- Enforce naming conventions for index variables.
+set_option linter.listVariables true -- Enforce naming conventions for `List`/`Array`/`Vector` variables.
+set_option linter.indexVariables true -- Enforce naming conventions for index variables.
 
 universe u
 
@@ -79,10 +79,16 @@ theorem get!_cons_zero [Inhabited α] (l : List α) (a : α) : (a::l).get! 0 = a
 /-! ### getD -/
 
 /--
-Returns the `i`-th element in the list (zero-based).
+Returns the element at the provided index, counting from `0`. Returns `fallback` if the index is out
+of bounds.
 
-If the index is out of bounds (`i ≥ as.length`), this function returns `fallback`.
-See also `get?` and `get!`.
+To return an `Option` depending on whether the index is in bounds, use `as[i]?`. To panic if the
+index is out of bounds, use `as[i]!`.
+
+Examples:
+ * `["spring", "summer", "fall", "winter"].getD 2 "never" = "fall"`
+ * `["spring", "summer", "fall", "winter"].getD 0 "never" = "spring"`
+ * `["spring", "summer", "fall", "winter"].getD 4 "never" = "never"`
 -/
 def getD (as : List α) (i : Nat) (fallback : α) : α :=
   as[i]?.getD fallback
@@ -92,10 +98,16 @@ def getD (as : List α) (i : Nat) (fallback : α) : α :=
 /-! ### getLast! -/
 
 /--
-Returns the last element in the list.
+Returns the last element in the list. Panics and returns `default` if the list is empty.
 
-If the list is empty, this function panics when executed, and returns `default`.
-See `getLast` and `getLastD` for safer alternatives.
+Safer alternatives include:
+ * `getLast?`, which returns an `Option`,
+ * `getLastD`, which takes a fallback value for empty lists, and
+ * `getLast`, which requires a proof that the list is non-empty.
+
+Examples:
+ * `["circle", "rectangle"].getLast! = "rectangle"`
+ * `["circle"].getLast! = "circle"`
 -/
 def getLast! [Inhabited α] : List α → α
   | []    => panic! "empty list"
@@ -106,10 +118,12 @@ def getLast! [Inhabited α] : List α → α
 /-! ### head! -/
 
 /--
-Returns the first element in the list.
+Returns the first element in the list. If the list is empty, panics and returns `default`.
 
-If the list is empty, this function panics when executed, and returns `default`.
-See `head` and `headD` for safer alternatives.
+Safer alternatives include:
+  * `List.head`, which requires a proof that the list is non-empty,
+  * `List.head?`, which returns an `Option`, and
+  * `List.headD`, which returns an explicitly-provided fallback value on empty lists.
 -/
 def head! [Inhabited α] : List α → α
   | []   => panic! "empty list"
@@ -118,10 +132,17 @@ def head! [Inhabited α] : List α → α
 /-! ### tail! -/
 
 /--
-Drops the first element of the list.
+Drops the first element of a nonempty list, returning the tail. If the list is empty, this function
+panics when executed and returns the empty list.
 
-If the list is empty, this function panics when executed, and returns the empty list.
-See `tail` and `tailD` for safer alternatives.
+Safer alternatives include
+ * `tail`, which returns the empty list without panicking,
+ * `tail?`, which returns an `Option`, and
+ * `tailD`, which returns a fallback value when passed the empty list.
+
+Examples:
+ * `["apple", "banana", "grape"].tail! = ["banana", "grape"]`
+ * `["banana", "grape"].tail! = ["grape"]`
 -/
 def tail! : List α → List α
   | []    => panic! "empty list"
@@ -132,17 +153,30 @@ def tail! : List α → List α
 /-! ### partitionM -/
 
 /--
-Monadic generalization of `List.partition`.
+Returns a pair of lists that together contain all the elements of `as`. The first list contains
+those elements for which the monadic predicate `p` returns `true`, and the second contains those for
+which `p` returns `false`. The list's elements are examined in order, from left to right.
 
-This uses `Array.toList` and which isn't imported by `Init.Data.List.Basic` or `Init.Data.List.Control`.
-```
+This is a monadic version of `List.partition`.
+
+Example:
+```lean example
 def posOrNeg (x : Int) : Except String Bool :=
   if x > 0 then pure true
   else if x < 0 then pure false
   else throw "Zero is not positive or negative"
-
-partitionM posOrNeg [-1, 2, 3] = Except.ok ([2, 3], [-1])
-partitionM posOrNeg [0, 2, 3] = Except.error "Zero is not positive or negative"
+```
+```lean example
+#eval [-1, 2, 3].partitionM posOrNeg
+```
+```output
+Except.ok ([2, 3], [-1])
+```
+```lean example
+#eval [0, 2, 3].partitionM posOrNeg
+```
+```output
+Except.error "Zero is not positive or negative"
 ```
 -/
 @[inline] def partitionM [Monad m] (p : α → m Bool) (l : List α) : m (List α × List α) :=
@@ -162,12 +196,12 @@ where
 /-! ### partitionMap -/
 
 /--
-Given a function `f : α → β ⊕ γ`, `partitionMap f l` maps the list by `f`
-whilst partitioning the result into a pair of lists, `List β × List γ`,
-partitioning the `.inl _` into the left list, and the `.inr _` into the right List.
-```
-partitionMap (id : Nat ⊕ Nat → Nat ⊕ Nat) [inl 0, inr 1, inl 2] = ([0, 2], [1])
-```
+Applies a function that returns a disjoint union to each element of a list, collecting the `Sum.inl`
+and `Sum.inr` results into separate lists.
+
+Examples:
+ * `[0, 1, 2, 3].partitionMap (fun x => if x % 2 = 0 then .inl x else .inr x) = ([0, 2], [1, 3])`
+ * `[0, 1, 2, 3].partitionMap (fun x => if x = 0 then .inl x else .inr x) = ([0], [1, 2, 3])`
 -/
 @[inline] def partitionMap (f : α → β ⊕ γ) (l : List α) : List β × List γ := go l #[] #[] where
   /-- Auxiliary for `partitionMap`:
@@ -199,19 +233,30 @@ For verification purposes, `List.mapMono = List.map`.
       return b' :: bs'
 
 /--
-Monomorphic `List.mapM`. The internal implementation uses pointer equality, and does not allocate a new list
-if the result of each `f a` is a pointer equal value `a`.
+Applies a monadic function to each element of a list, returning the list of results. The function is
+monomorphic: it is required to return a value of the same type. The internal implementation uses
+pointer equality, and does not allocate a new list if the result of each function call is
+pointer-equal to its argument.
 -/
 @[implemented_by mapMonoMImp] def mapMonoM [Monad m] (as : List α) (f : α → m α) : m (List α) :=
   match as with
   | [] => return []
   | a :: as => return (← f a) :: (← mapMonoM as f)
 
+/--
+Applies a function to each element of a list, returning the list of results. The function is
+monomorphic: it is required to return a value of the same type. The internal implementation uses
+pointer equality, and does not allocate a new list if the result of each function call is
+pointer-equal to its argument.
+
+For verification purposes, `List.mapMono = List.map`.
+-/
 def mapMono (as : List α) (f : α → α) : List α :=
   Id.run <| as.mapMonoM f
 
 /-! ## Additional lemmas required for bootstrapping `Array`. -/
 
+@[simp]
 theorem getElem_append_left {as bs : List α} (h : i < as.length) {h' : i < (as ++ bs).length} :
     (as ++ bs)[i] = as[i] := by
   induction as generalizing i with
@@ -221,6 +266,7 @@ theorem getElem_append_left {as bs : List α} (h : i < as.length) {h' : i < (as
     | zero => rfl
     | succ i => apply ih
 
+@[simp]
 theorem getElem_append_right {as bs : List α} {i : Nat} (h₁ : as.length ≤ i) {h₂} :
     (as ++ bs)[i]'h₂ =
       bs[i - as.length]'(by rw [length_append] at h₂; exact Nat.sub_lt_left_of_lt_add h₁ h₂) := by

src/Init/Data/List/Control.lean

@@ -9,8 +9,8 @@ import Init.Control.Id
 import Init.Control.Lawful
 import Init.Data.List.Basic
 
--- set_option linter.listVariables true -- Enforce naming conventions for `List`/`Array`/`Vector` variables.
--- set_option linter.indexVariables true -- Enforce naming conventions for index variables.
+set_option linter.listVariables true -- Enforce naming conventions for `List`/`Array`/`Vector` variables.
+set_option linter.indexVariables true -- Enforce naming conventions for index variables.
 
 namespace List
 universe u v w u₁ u₂
@@ -46,11 +46,12 @@ Users that want to use `mapM` with `Applicative` should use `mapA` instead.
 -/
 
 /--
-Applies the monadic action `f` on every element in the list, left-to-right, and returns the list of
+Applies the monadic action `f` to every element in the list, left-to-right, and returns the list of
 results.
 
-See `List.forM` for the variant that discards the results.
-See `List.mapA` for the variant that works with `Applicative`.
+This implementation is tail recursive. `List.mapM'` is a a non-tail-recursive variant that may be
+more convenient to reason about. `List.forM` is the variant that discards the results and
+`List.mapA` is the variant that works with `Applicative`.
 -/
 @[inline]
 def mapM {m : Type u → Type v} [Monad m] {α : Type w} {β : Type u} (f : α → m β) (as : List α) : m (List β) :=
@@ -60,15 +61,15 @@ def mapM {m : Type u → Type v} [Monad m] {α : Type w} {β : Type u} (f : α
   loop as []
 
 /--
-Applies the applicative action `f` on every element in the list, left-to-right, and returns the list of
-results.
+Applies the applicative action `f` on every element in the list, left-to-right, and returns the list
+of results.
 
-NB: If `m` is also a `Monad`, then using `mapM` can be more efficient.
+If `m` is also a `Monad`, then using `mapM` can be more efficient.
 
-See `List.forA` for the variant that discards the results.
-See `List.mapM` for the variant that works with `Monad`.
+See `List.forA` for the variant that discards the results. See `List.mapM` for the variant that
+works with `Monad`.
 
-**Warning**: this function is not tail-recursive, meaning that it may fail with a stack overflow on long lists.
+This function is not tail-recursive, so it may fail with a stack overflow on long lists.
 -/
 @[specialize]
 def mapA {m : Type u → Type v} [Applicative m] {α : Type w} {β : Type u} (f : α → m β) : List α → m (List β)
@@ -76,10 +77,10 @@ def mapA {m : Type u → Type v} [Applicative m] {α : Type w} {β : Type u} (f
   | a::as => List.cons <$> f a <*> mapA f as
 
 /--
-Applies the monadic action `f` on every element in the list, left-to-right.
+Applies the monadic action `f` to every element in the list, in order.
 
-See `List.mapM` for the variant that collects results.
-See `List.forA` for the variant that works with `Applicative`.
+`List.mapM` is a variant that collects results. `List.forA` is a variant that works on any
+`Applicative`.
 -/
 @[specialize]
 protected def forM {m : Type u → Type v} [Monad m] {α : Type w} (as : List α) (f : α → m PUnit) : m PUnit :=
@@ -88,12 +89,11 @@ protected def forM {m : Type u → Type v} [Monad m] {α : Type w} (as : List α
   | a :: as => do f a; List.forM as f
 
 /--
-Applies the applicative action `f` on every element in the list, left-to-right.
+Applies the applicative action `f` to every element in the list, in order.
 
-NB: If `m` is also a `Monad`, then using `forM` can be more efficient.
+If `m` is also a `Monad`, then using `List.forM` can be more efficient.
 
-See `List.mapA` for the variant that collects results.
-See `List.forM` for the variant that works with `Monad`.
+`List.mapA` is a variant that collects results.
 -/
 @[specialize]
 def forA {m : Type u → Type v} [Applicative m] {α : Type w} (as : List α) (f : α → m PUnit) : m PUnit :=
@@ -110,8 +110,28 @@ def filterAuxM {m : Type → Type v} [Monad m] {α : Type} (f : α → m Bool) :
     filterAuxM f t (cond b (h :: acc) acc)
 
 /--
-Applies the monadic predicate `p` on every element in the list, left-to-right, and returns those
-elements `x` for which `p x` returns `true`.
+Applies the monadic predicate `p` to every element in the list, in order from left to right, and
+returns the list of elements for which `p` returns `true`.
+
+`O(|l|)`.
+
+Example:
+```lean example
+#eval [1, 2, 5, 2, 7, 7].filterM fun x => do
+  IO.println s!"Checking {x}"
+  return x < 3
+```
+```output
+Checking 1
+Checking 2
+Checking 5
+Checking 2
+Checking 7
+Checking 7
+```
+```output
+[1, 2, 2]
+```
 -/
 @[inline]
 def filterM {m : Type → Type v} [Monad m] {α : Type} (p : α → m Bool) (as : List α) : m (List α) := do
@@ -119,16 +139,56 @@ def filterM {m : Type → Type v} [Monad m] {α : Type} (p : α → m Bool) (as
   pure as.reverse
 
 /--
-Applies the monadic predicate `p` on every element in the list, right-to-left, and returns those
-elements `x` for which `p x` returns `true`.
+Applies the monadic predicate `p` on every element in the list in reverse order, from right to left,
+and returns those elements for which `p` returns `true`. The elements of the returned list are in
+the same order as in the input list.
+
+Example:
+```lean example
+#eval [1, 2, 5, 2, 7, 7].filterRevM fun x => do
+  IO.println s!"Checking {x}"
+  return x < 3
+```
+```output
+Checking 7
+Checking 7
+Checking 2
+Checking 5
+Checking 2
+Checking 1
+```
+```output
+[1, 2, 2]
+```
 -/
 @[inline]
 def filterRevM {m : Type → Type v} [Monad m] {α : Type} (p : α → m Bool) (as : List α) : m (List α) :=
   filterAuxM p as.reverse []
 
 /--
-Applies the monadic function `f` on every element `x` in the list, left-to-right, and returns those
-results `y` for which `f x` returns `some y`.
+Applies a monadic function that returns an `Option` to each element of a list, collecting the
+non-`none` values.
+
+`O(|l|)`.
+
+Example:
+```lean example
+#eval [1, 2, 5, 2, 7, 7].filterMapM fun x => do
+  IO.println s!"Examining {x}"
+  if x > 2 then return some (2 * x)
+  else return none
+```
+```output
+Examining 1
+Examining 2
+Examining 5
+Examining 2
+Examining 7
+Examining 7
+```
+```output
+[10, 14, 14]
+```
 -/
 @[inline]
 def filterMapM {m : Type u → Type v} [Monad m] {α : Type w} {β : Type u} (f : α → m (Option β)) (as : List α) : m (List β) :=
@@ -141,8 +201,8 @@ def filterMapM {m : Type u → Type v} [Monad m] {α : Type w} {β : Type u} (f
   loop as []
 
 /--
-Applies the monadic function `f` on every element `x` in the list, left-to-right, and returns the
-concatenation of the results.
+Applies a monadic function that returns a list to each element of a list, from left to right, and
+concatenates the resulting lists.
 -/
 @[inline]
 def flatMapM {m : Type u → Type v} [Monad m] {α : Type w} {β : Type u} (f : α → m (List β)) (as : List α) : m (List β) :=
@@ -153,14 +213,20 @@ def flatMapM {m : Type u → Type v} [Monad m] {α : Type w} {β : Type u} (f :
       loop as (bs' :: bs)
   loop as []
 
+
 /--
-Folds a monadic function over a list from left to right:
-```
-foldlM f x₀ [a, b, c] = do
-  let x₁ ← f x₀ a
-  let x₂ ← f x₁ b
-  let x₃ ← f x₂ c
-  pure x₃
+Folds a monadic function over a list from the left, accumulating a value starting with `init`. The
+accumulated value is combined with the each element of the list in order, using `f`.
+
+Example:
+```lean example
+example [Monad m] (f : α → β → m α) :
+    List.foldlM (m := m) f x₀ [a, b, c] = (do
+      let x₁ ← f x₀ a
+      let x₂ ← f x₁ b
+      let x₃ ← f x₂ c
+      pure x₃)
+  := by rfl
 ```
 -/
 @[specialize]
@@ -176,13 +242,18 @@ def foldlM {m : Type u → Type v} [Monad m] {s : Type u} {α : Type w} : (f : s
   simp [List.foldlM]
 
 /--
-Folds a monadic function over a list from right to left:
-```
-foldrM f x₀ [a, b, c] = do
-  let x₁ ← f c x₀
-  let x₂ ← f b x₁
-  let x₃ ← f a x₂
-  pure x₃
+Folds a monadic function over a list from the right, accumulating a value starting with `init`. The
+accumulated value is combined with the each element of the list in reverse order, using `f`.
+
+Example:
+```lean example
+example [Monad m] (f : α → β → m β) :
+  List.foldrM (m := m) f x₀ [a, b, c] = (do
+    let x₁ ← f c x₀
+    let x₂ ← f b x₁
+    let x₃ ← f a x₂
+    pure x₃)
+  := by rfl
 ```
 -/
 @[inline]
@@ -192,32 +263,70 @@ def foldrM {m : Type u → Type v} [Monad m] {s : Type u} {α : Type w} (f : α
 @[simp] theorem foldrM_nil [Monad m] (f : α → β → m β) (b) : [].foldrM f b = pure b := rfl
 
 /--
-Maps `f` over the list and collects the results with `<|>`.
-```
-firstM f [a, b, c] = f a <|> f b <|> f c <|> failure
-```
+Maps `f` over the list and collects the results with `<|>`. The result for the end of the list is
+`failure`.
+
+Examples:
+ * `[[], [1, 2], [], [2]].firstM List.head? = some 1`
+ * `[[], [], []].firstM List.head? = none`
+ * `[].firstM List.head? = none`
 -/
 @[specialize]
 def firstM {m : Type u → Type v} [Alternative m] {α : Type w} {β : Type u} (f : α → m β) : List α → m β
   | []    => failure
   | a::as => f a <|> firstM f as
 
+/--
+Returns true if the monadic predicate `p` returns `true` for any element of `l`.
+
+`O(|l|)`. Short-circuits upon encountering the first `true`. The elements in `l` are examined in
+order from left to right.
+-/
 @[specialize]
-def anyM {m : Type → Type u} [Monad m] {α : Type v} (f : α → m Bool) : List α → m Bool
+def anyM {m : Type → Type u} [Monad m] {α : Type v} (p : α → m Bool) : (l : List α) → m Bool
   | []    => pure false
   | a::as => do
-    match (← f a) with
+    match (← p a) with
     | true  => pure true
-    | false => anyM f as
+    | false => anyM p as
 
+/--
+Returns true if the monadic predicate `p` returns `true` for every element of `l`.
+
+`O(|l|)`. Short-circuits upon encountering the first `false`. The elements in `l` are examined in
+order from left to right.
+-/
 @[specialize]
-def allM {m : Type → Type u} [Monad m] {α : Type v} (f : α → m Bool) : List α → m Bool
+def allM {m : Type → Type u} [Monad m] {α : Type v} (p : α → m Bool) : (l : List α) → m Bool
   | []    => pure true
   | a::as => do
-    match (← f a) with
-    | true  => allM f as
+    match (← p a) with
+    | true  => allM p as
     | false => pure false
 
+/--
+Returns the first element of the list for which the monadic predicate `p` returns `true`, or `none`
+if no such element is found. Elements of the list are checked in order.
+
+`O(|l|)`.
+
+Example:
+```lean example
+#eval [7, 6, 5, 8, 1, 2, 6].findM? fun i => do
+  if i < 5 then
+    return true
+  if i ≤ 6 then
+    IO.println s!"Almost! {i}"
+  return false
+```
+```output
+Almost! 6
+Almost! 5
+```
+```output
+some 1
+```
+-/
 @[specialize]
 def findM? {m : Type → Type u} [Monad m] {α : Type} (p : α → m Bool) : List α → m (Option α)
   | []    => pure none
@@ -227,15 +336,43 @@ def findM? {m : Type → Type u} [Monad m] {α : Type} (p : α → m Bool) : Lis
     | false => findM? p as
 
 @[simp]
-theorem findM?_id (p : α → Bool) (as : List α) : findM? (m := Id) p as = as.find? p := by
+theorem findM?_pure {m} [Monad m] [LawfulMonad m] (p : α → Bool) (as : List α) :
+    findM? (m := m) (pure <| p ·) as = pure (as.find? p) := by
   induction as with
   | nil => rfl
   | cons a as ih =>
     simp only [findM?, find?]
     cases p a with
-    | true  => rfl
-    | false => rw [ih]; rfl
+    | true  => simp
+    | false => simp [ih]
 
+@[simp]
+theorem findM?_id (p : α → Bool) (as : List α) : findM? (m := Id) p as = as.find? p :=
+  findM?_pure _ _
+
+/--
+Returns the first non-`none` result of applying the monadic function `f` to each element of the
+list, in order. Returns `none` if `f` returns `none` for all elements.
+
+`O(|l|)`.
+
+Example:
+```lean example
+#eval [7, 6, 5, 8, 1, 2, 6].findSomeM? fun i => do
+  if i < 5 then
+    return some (i * 10)
+  if i ≤ 6 then
+    IO.println s!"Almost! {i}"
+  return none
+```
+```output
+Almost! 6
+Almost! 5
+```
+```output
+some 10
+```
+-/
 @[specialize]
 def findSomeM? {m : Type u → Type v} [Monad m] {α : Type w} {β : Type u} (f : α → m (Option β)) : List α → m (Option β)
   | []    => pure none
@@ -245,14 +382,19 @@ def findSomeM? {m : Type u → Type v} [Monad m] {α : Type w} {β : Type u} (f
     | none   => findSomeM? f as
 
 @[simp]
-theorem findSomeM?_id (f : α → Option β) (as : List α) : findSomeM? (m := Id) f as = as.findSome? f := by
+theorem findSomeM?_pure [Monad m] [LawfulMonad m] (f : α → Option β) (as : List α) :
+    findSomeM? (m := m) (pure <| f ·) as = pure (as.findSome? f) := by
   induction as with
   | nil => rfl
   | cons a as ih =>
     simp only [findSomeM?, findSome?]
     cases f a with
-    | some b => rfl
-    | none   => rw [ih]; rfl
+    | some b => simp
+    | none   => simp [ih]
+
+@[simp]
+theorem findSomeM?_id (f : α → Option β) (as : List α) : findSomeM? (m := Id) f as = as.findSome? f :=
+  findSomeM?_pure _ _
 
 theorem findM?_eq_findSomeM? [Monad m] [LawfulMonad m] (p : α → m Bool) (as : List α) :
     as.findM? p = as.findSomeM? fun a => return if (← p a) then some a else none := by

src/Init/Data/List/Count.lean

@@ -10,8 +10,8 @@ import Init.Data.List.Sublist
 # Lemmas about `List.countP` and `List.count`.
 -/
 
--- set_option linter.listVariables true -- Enforce naming conventions for `List`/`Array`/`Vector` variables.
--- set_option linter.indexVariables true -- Enforce naming conventions for index variables.
+set_option linter.listVariables true -- Enforce naming conventions for `List`/`Array`/`Vector` variables.
+set_option linter.indexVariables true -- Enforce naming conventions for index variables.
 
 namespace List
 
@@ -87,10 +87,10 @@ theorem countP_le_length : countP p l ≤ l.length := by
   countP_pos_iff
 
 @[simp] theorem countP_eq_zero {p} : countP p l = 0 ↔ ∀ a ∈ l, ¬p a := by
-  simp only [countP_eq_length_filter, length_eq_zero, filter_eq_nil_iff]
+  simp only [countP_eq_length_filter, length_eq_zero_iff, filter_eq_nil_iff]
 
 @[simp] theorem countP_eq_length {p} : countP p l = l.length ↔ ∀ a ∈ l, p a := by
-  rw [countP_eq_length_filter, filter_length_eq_length]
+  rw [countP_eq_length_filter, length_filter_eq_length_iff]
 
 theorem countP_replicate (p : α → Bool) (a : α) (n : Nat) :
     countP p (replicate n a) = if p a then n else 0 := by

src/Init/Data/List/Erase.lean

@@ -12,8 +12,8 @@ import Init.Data.List.Find
 # Lemmas about `List.eraseP`, `List.erase`, and `List.eraseIdx`.
 -/
 
--- set_option linter.listVariables true -- Enforce naming conventions for `List`/`Array`/`Vector` variables.
--- set_option linter.indexVariables true -- Enforce naming conventions for index variables.
+set_option linter.listVariables true -- Enforce naming conventions for `List`/`Array`/`Vector` variables.
+set_option linter.indexVariables true -- Enforce naming conventions for index variables.
 
 namespace List
 
@@ -137,7 +137,7 @@ theorem mem_of_mem_eraseP {l : List α} : a ∈ l.eraseP p → a ∈ l := (erase
 @[simp] theorem eraseP_eq_self_iff {p} {l : List α} : l.eraseP p = l ↔ ∀ a ∈ l, ¬ p a := by
   rw [← Sublist.length_eq (eraseP_sublist l), length_eraseP]
   split <;> rename_i h
-  · simp only [any_eq_true, length_eq_zero] at h
+  · simp only [any_eq_true, length_eq_zero_iff] at h
     constructor
     · intro; simp_all [Nat.sub_one_eq_self]
     · intro; obtain ⟨x, m, h⟩ := h; simp_all