Import Upstream version 4.2.0

.github/workflows/ci.yml

@@ -0,0 +1,494 @@
+name: CI
+
+on:
+  push:
+    paths-ignore:
+      - 'CHANGES*'
+      - 'Doc/**'
+      - 'appveyor.yml'
+  pull_request:
+    branches: master
+    paths-ignore:
+      - 'CHANGES*'
+      - 'Doc/**'
+      - 'appveyor.yml'
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+
+    # When continue-on-error is true for an individual build, that build can fail (it'll show red),
+    # but it won't fail the overall build
+    continue-on-error: ${{ matrix.continue-on-error || false }}
+
+    runs-on: ${{ matrix.os || 'ubuntu-20.04' }}
+
+    # By default, the name of the build is the language used and SWIG options, but matrix entries
+    # can define the additional "desc" field with any additional information to include in the name.
+    name: ${{ matrix.SWIGLANG || 'none' }}${{ matrix.PY2 }} ${{ matrix.ENGINE}} ${{ matrix.VER }} ${{ matrix.SWIG_FEATURES }} ${{ (matrix.compiler || 'gcc') }}${{ matrix.GCC }} ${{ matrix.CPPSTD }} ${{ matrix.CSTD }} ${{ matrix.EXTRA_CXXFLAGS }} ${{ matrix.desc }} ${{ matrix.continue-on-error && '(can fail)' }}
+
+    strategy:
+      matrix:
+        include:
+        - SWIGLANG: ""
+          CPPFLAGS: "-DDOH_POISON"
+        - SWIGLANG: ""
+          GCC: 7
+        - SWIGLANG: ""
+          GCC: 8
+        - SWIGLANG: ""
+          GCC: 9
+        - SWIGLANG: ""
+          GCC: 10
+        - SWIGLANG: ""
+          GCC: 11
+        - SWIGLANG: ""
+          GCC: 12
+          os: ubuntu-22.04
+        - SWIGLANG: ""
+          GCC: 13
+          os: ubuntu-22.04
+        - SWIGLANG: ""
+          compiler: clang
+          os: ubuntu-22.04
+        - SWIGLANG: csharp
+        - SWIGLANG: d
+          VER: 'ldc'
+          CPPSTD: c++14
+        - SWIGLANG: d
+          VER: 'gdmd'
+          CPPSTD: c++11
+        - SWIGLANG: d
+          VER: '2.103.1'
+          CPPSTD: c++17
+        - SWIGLANG: go
+          VER: '1.6'
+          CSTD: gnu11
+        - SWIGLANG: go
+          VER: '1.8'
+        - SWIGLANG: go
+          VER: '1.12'
+          CSTD: gnu11
+        - SWIGLANG: go
+          VER: '1.17'
+        - SWIGLANG: guile
+        - SWIGLANG: guile
+          VER: '2.2'
+        - SWIGLANG: guile
+          VER: '3.0'
+        - SWIGLANG: java
+        - SWIGLANG: javascript
+          ENGINE: jsc
+          VER: '4.0'
+        - SWIGLANG: javascript
+          ENGINE: napi
+          VER: '18'
+          CPPSTD: c++11
+        #- SWIGLANG: javascript
+        #  ENGINE: node
+        #  VER: '6'
+        #  CPPSTD: c++11
+        #  os: ubuntu-18.04
+        #- SWIGLANG: javascript
+        #  ENGINE: node
+        #  VER: '8'
+        #  CPPSTD: c++11
+        #  os: ubuntu-18.04
+        #- SWIGLANG: javascript
+        #  ENGINE: node
+        #  VER: '10'
+        #  CPPSTD: c++11
+        #  os: ubuntu-18.04
+        - SWIGLANG: javascript
+          ENGINE: node
+          VER: '12'
+          CPPSTD: c++11
+        - SWIGLANG: lua
+        - SWIGLANG: lua
+          VER: '5.3'
+        - SWIGLANG: octave
+          CPPSTD: c++11
+        - SWIGLANG: perl5
+        - SWIGLANG: php
+          VER: '8.0'
+        - SWIGLANG: php
+          VER: '8.1'
+        - SWIGLANG: php
+          VER: '8.2'
+        - SWIGLANG: php
+          VER: '8.3'
+        - SWIGLANG: python
+          PY2: 2
+        #- SWIGLANG: python
+        #  VER: '3.3'
+        #  os: ubuntu-18.04 # Python < 3.5 not available for 20.04.
+        #- SWIGLANG: python
+        #  VER: '3.4'
+        #  os: ubuntu-18.04 # Python < 3.5 not available for 20.04.
+        - SWIGLANG: python
+          VER: '3.5'
+        - SWIGLANG: python
+          VER: '3.6'
+        - SWIGLANG: python
+          VER: '3.7'
+        - SWIGLANG: python
+          VER: '3.8'
+        - SWIGLANG: python
+          VER: '3.9'
+        - SWIGLANG: python
+          VER: '3.10'
+        - SWIGLANG: python
+          VER: '3.11'
+        - SWIGLANG: python
+          VER: '3.12'
+          CSTD: gnu99
+        - SWIGLANG: python
+          PY2: 2
+          SWIG_FEATURES: -builtin
+        - SWIGLANG: python
+          PY2: 2
+          SWIG_FEATURES: -builtin -O
+        - SWIGLANG: python
+          SWIG_FEATURES: -builtin
+        - SWIGLANG: python
+          SWIG_FEATURES: -builtin -O
+        - SWIGLANG: python
+          EXTRA_CXXFLAGS: -DPy_LIMITED_API=0x03040000
+          CPPSTD: c++20
+          GCC: 13
+          os: ubuntu-22.04
+        - SWIGLANG: r
+        - SWIGLANG: ruby
+          VER: '2.0'
+        - SWIGLANG: ruby
+          VER: '2.1'
+        - SWIGLANG: ruby
+          VER: '2.2'
+        - SWIGLANG: ruby
+          VER: '2.3'
+        - SWIGLANG: ruby
+          VER: '2.4'
+        - SWIGLANG: ruby
+          VER: '2.5'
+        - SWIGLANG: ruby
+          VER: '2.6'
+        - SWIGLANG: ruby
+          VER: '2.7'
+        - SWIGLANG: ruby
+          VER: '3.0'
+          CPPSTD: c++11
+        - SWIGLANG: ruby
+          VER: '3.1'
+          CPPSTD: c++11
+        - SWIGLANG: ruby
+          CPPSTD: c++11
+          VER: '3.2'
+        - SWIGLANG: scilab
+          VER: '5.5.2'
+        - SWIGLANG: scilab
+          VER: '6.0.2'
+        - SWIGLANG: scilab
+          os: ubuntu-22.04 # scilab 6.1.1
+        - SWIGLANG: scilab
+          VER: '2023.0.0'
+        - SWIGLANG: tcl
+        # c++11 testing
+        - SWIGLANG: csharp
+          CPPSTD: c++11
+        - SWIGLANG: go
+          VER: '1.17'
+          CPPSTD: c++11
+          CSTD: gnu11
+        - SWIGLANG: guile
+          CPPSTD: c++11
+        - SWIGLANG: java
+          CPPSTD: c++11
+        - SWIGLANG: javascript
+          ENGINE: jsc
+          VER: '4.1'
+          os: ubuntu-22.04
+          CPPSTD: c++11
+        - SWIGLANG: javascript
+          ENGINE: node
+          VER: '14'
+          CPPSTD: c++11
+        - SWIGLANG: lua
+          CPPSTD: c++11
+        - SWIGLANG: perl5
+          CPPSTD: c++11
+        - SWIGLANG: php
+          CPPSTD: c++11
+          CSTD: gnu11
+        - SWIGLANG: python
+          CPPSTD: c++11
+        - SWIGLANG: r
+          CPPSTD: c++11
+        - SWIGLANG: ruby
+          CPPSTD: c++11
+          VER: '3.3'
+        - SWIGLANG: ruby
+          CPPSTD: c++11
+        - SWIGLANG: scilab
+          CPPSTD: c++11
+        - SWIGLANG: tcl
+          CPPSTD: c++11
+        # c++14 testing
+        - SWIGLANG: csharp
+          CPPSTD: c++14
+        - SWIGLANG: go
+          VER: '1.17'
+          CPPSTD: c++14
+          CSTD: gnu11
+        - SWIGLANG: guile
+          CPPSTD: c++14
+        - SWIGLANG: java
+          CPPSTD: c++14
+        - SWIGLANG: javascript
+          ENGINE: node
+          VER: '16'
+          CPPSTD: c++14
+        - SWIGLANG: lua
+          CPPSTD: c++14
+        - SWIGLANG: octave
+          CPPSTD: c++14
+        - SWIGLANG: perl5
+          CPPSTD: c++14
+        - SWIGLANG: php
+          CPPSTD: c++14
+          CSTD: gnu11
+        - SWIGLANG: python
+          CPPSTD: c++14
+        - SWIGLANG: r
+          CPPSTD: c++14
+        - SWIGLANG: ruby
+          CPPSTD: c++14
+        - SWIGLANG: scilab
+          CPPSTD: c++14
+        - SWIGLANG: tcl
+          CPPSTD: c++14
+        # c++17 testing (using gcc13)
+        - SWIGLANG: csharp
+          CPPSTD: c++17
+          GCC: 13
+        - SWIGLANG: go
+          VER: '1.17'
+          CPPSTD: c++17
+          GCC: 13
+          CSTD: gnu17
+        - SWIGLANG: guile
+          CPPSTD: c++17
+          GCC: 13
+        - SWIGLANG: java
+          CPPSTD: c++17
+          GCC: 13
+        - SWIGLANG: javascript
+          ENGINE: node
+          VER: '18'
+          CPPSTD: c++17
+          GCC: 13
+        - SWIGLANG: lua
+          CPPSTD: c++17
+          GCC: 13
+        - SWIGLANG: octave
+          CPPSTD: c++17
+          GCC: 13
+        - SWIGLANG: perl5
+          CPPSTD: c++17
+          GCC: 13
+        - SWIGLANG: php
+          CPPSTD: c++17
+          CSTD: gnu17
+          GCC: 13
+        - SWIGLANG: python
+          CPPSTD: c++17
+          GCC: 13
+        - SWIGLANG: r
+          CPPSTD: c++17
+          GCC: 13
+        - SWIGLANG: ruby
+          CPPSTD: c++17
+          GCC: 13
+        - SWIGLANG: scilab
+          CPPSTD: c++17
+          GCC: 13
+        - SWIGLANG: tcl
+          CPPSTD: c++17
+          GCC: 13
+        # c++20 testing (using gcc13)
+        - SWIGLANG: python
+          CPPSTD: c++20
+          GCC: 13
+          os: ubuntu-22.04
+        - SWIGLANG: javascript
+          ENGINE: napi
+          VER: '20'
+          CPPSTD: c++20
+          GCC: 13
+          os: ubuntu-22.04
+        - SWIGLANG: javascript
+          ENGINE: node
+          VER: '20'
+          CPPSTD: c++20
+          GCC: 13
+          os: ubuntu-22.04
+        # Experimental languages (these are allowed to fail)
+        - SWIGLANG: mzscheme
+          continue-on-error: true
+        #- SWIGLANG: ocaml
+        #  CPPSTD: c++17
+        #  GCC: 13
+        #  continue-on-error: true
+        #  os: ubuntu-18.04 # ocaml-4.08 in ubuntu-20.04 not yet working
+      # Run all of them, as opposed to aborting when one fails
+      fail-fast: false
+
+    env:
+      SWIGLANG: ${{ matrix.SWIGLANG }}
+      PY2: ${{ matrix.PY2 }}
+      VER: ${{ matrix.VER }}
+      ENGINE: ${{ matrix.ENGINE }}
+      SWIG_FEATURES: ${{ matrix.SWIG_FEATURES }}
+      GCC: ${{ matrix.GCC }}
+      CSTD: ${{ matrix.CSTD }}
+      CPPSTD: ${{ matrix.CPPSTD }}
+      CPPFLAGS: ${{ matrix.CPPFLAGS }}
+      EXTRA_CXXFLAGS: ${{ matrix.EXTRA_CXXFLAGS }}
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v3
+      with:
+        submodules: recursive
+
+    - name: Install CCache
+      uses: hendrikmuhs/ccache-action@v1
+      with:
+        key: ${{ matrix.os || 'ubuntu-20.04' }}-${{ matrix.compiler || 'gcc' }}${{ matrix.GCC }}
+
+# Uncomment to debug via ssh, see https://github.com/mxschmitt/action-tmate
+#    - name: Setup tmate session
+#      uses: mxschmitt/action-tmate@v3
+
+    - name: Install Dependencies
+      run: |
+          set -x
+          export PATH="/usr/lib/ccache:/usr/local/opt/ccache/libexec:$PATH"
+          echo PATH="$PATH" >> $GITHUB_ENV
+
+          source $GITHUB_WORKSPACE/Tools/GHA-linux-install.sh
+          echo WITHLANG="$WITHLANG" >> $GITHUB_ENV
+
+          case $(uname) in
+              Linux)
+                  cpu_count=$(nproc)
+                  ;;
+
+              Darwin)
+                  cpu_count=$(sysctl -n hw.ncpu)
+                  ;;
+
+              *)
+                  cpu_count=1
+                  ;;
+          esac
+
+          if [[ $cpu_count != 1 ]]; then
+            echo SWIGJOBS=-j$cpu_count >> $GITHUB_ENV
+          fi
+
+          if test '${{ matrix.compiler }}' = 'clang'; then
+            CC="clang"
+            CXX="clang++"
+
+            CFLAGS="$CFLAGS -fPIE"
+            CXXFLAGS="$CXXFLAGS -fPIE"
+          elif test -n "$GCC"; then
+            CC="gcc-$GCC"
+            CXX="g++-$GCC"
+          else
+            CC="gcc"
+            CXX="g++"
+          fi
+
+          export CC CXX
+
+          echo CC="$CC" >> $GITHUB_ENV
+          echo CXX="$CXX" >> $GITHUB_ENV
+
+          ls -la $(which $CC) $(which $CXX)
+          $CC --version
+          $CXX --version
+
+    - name: Configure
+      run: |
+          source $GITHUB_WORKSPACE/Tools/CI-linux-environment.sh
+          set -x
+
+          if [[ -z "$CSTD" ]]; then
+            case "$CPPSTD" in
+              c++11) export CSTD=c11 ;;
+              c++14) export CSTD=c11 ;;
+              c++17) export CSTD=c17 ;;
+              c++20) export CSTD=c17 ;;
+            esac
+            echo CSTD="$CSTD" >> $GITHUB_ENV
+          fi
+          if test -z "$CPPSTD"; then CONFIGOPTS+=("--disable-cpp11-testing"); fi
+          if test -n "$CPPSTD"; then CONFIGOPTS+=("CXXFLAGS=-std=$CPPSTD $CXXFLAGS"); fi
+          if test -n "$CSTD"; then CONFIGOPTS+=("CFLAGS=-std=$CSTD $CFLAGS"); fi
+          if test -n "$SWIGLANG"; then CONFIGOPTS+=(--without-alllang --with-$WITHLANG); fi
+          echo "${CONFIGOPTS[@]}"
+          ./autogen.sh && mkdir -p build/build && cd build/build && ../../configure "${CONFIGOPTS[@]}"
+
+    - name: Build
+      working-directory: build/build
+      run: |
+          set -x
+          make -s $SWIGJOBS
+          ./swig -version && ./swig -pcreversion
+
+    - name: Test
+      working-directory: build/build
+      run: |
+          source $GITHUB_WORKSPACE/Tools/CI-linux-environment.sh
+          set -x
+
+          if test -z "$SWIGLANG"; then
+            make $SWIGJOBS check-ccache
+            make $SWIGJOBS check-errors-test-suite
+          else
+            case "$SWIGLANG" in
+              javascript)
+                case "$ENGINE" in
+                  v8 | jsc)
+                    # Running tests using v8 or jsc involves creating a custom
+                    # interpreter in Tools/javascript, which is currently broken
+                    # for parallel builds (we attempt to update this interpreter
+                    # while running, resulting in "Text file busy" error).
+                    unset SWIGJOBS
+                esac
+                ;;
+            esac
+
+            # Stricter compile flags for examples. Various headers and SWIG generated code prevents full use of -pedantic.
+            cflags="$($GITHUB_WORKSPACE/Tools/testflags.py --language $SWIGLANG --cflags --std=$CSTD --compiler=$CC) $EXTRA_CFLAGS"
+            cxxflags="$($GITHUB_WORKSPACE/Tools/testflags.py --language $SWIGLANG --cxxflags --std=$CPPSTD --compiler=$CC) $EXTRA_CXXFLAGS"
+            make check-$SWIGLANG-version
+            make check-$SWIGLANG-enabled
+            make $SWIGJOBS check-$SWIGLANG-examples CFLAGS="$cflags" CXXFLAGS="$cxxflags"
+            make $SWIGJOBS check-$SWIGLANG-test-suite CFLAGS="$cflags" CXXFLAGS="$cxxflags"
+          fi
+
+    - name: Install
+      working-directory: build/build
+      run: |
+          set -x
+          if test -z "$SWIGLANG"; then sudo make install && swig -version && ccache-swig -V; fi
+
+    - name: Clean
+      working-directory: build/build
+      run: |
+          set -x
+          make check-maintainer-clean && ../../configure

.github/workflows/nuget.yml

@@ -0,0 +1,62 @@
+name: Windows Nuget Build
+
+on:
+  push:
+    paths-ignore:
+      - 'CHANGES*'
+      - 'Doc/**'
+      - 'appveyor.yml'
+  pull_request:
+    branches: master
+    paths-ignore:
+      - 'CHANGES*'
+      - 'Doc/**'
+      - 'appveyor.yml'
+
+permissions:
+  contents: read  #  to fetch code (actions/checkout)
+
+jobs:
+  build:
+
+    runs-on: windows-2019
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v3
+      with:
+        submodules: recursive
+
+    - name: Install Dependencies
+      shell: powershell
+      run: |
+          nuget install CMake-win64 -Version 3.15.5 -OutputDirectory C:\Tools\CMake
+          nuget install Bison -Version 3.7.4 -OutputDirectory C:\Tools\bison
+          nuget install PCRE2 -Version 10.39 -OutputDirectory C:\Tools\pcre2
+
+    - name: Build
+      shell: powershell
+      run: |
+          $env:PATH="C:\Tools\CMake\CMake-win64.3.15.5\bin;C:\Tools\bison\Bison.3.7.4\bin;" + $env:PATH
+          $PCRE_ROOT="C:\Tools\pcre2\PCRE2.10.39.0"
+          $PCRE_PLATFORM="x64"
+          $WORKING_DIR=(Get-Location).ToString() -replace "\\","/"
+          cmake -G "Visual Studio 16 2019" -A "x64" `
+          -DCMAKE_INSTALL_PREFIX="$WORKING_DIR/install2" `
+          -DCMAKE_C_FLAGS="/DPCRE2_STATIC" `
+          -DCMAKE_CXX_FLAGS="/DPCRE2_STATIC" `
+          -DPCRE2_INCLUDE_DIR="$PCRE_ROOT/include" `
+          -DPCRE2_LIBRARY="$PCRE_ROOT/lib/pcre2-8-static.lib" `
+          -S . -B build
+          cmake --build build --config Release
+
+    - name: Install
+      shell: powershell
+      run: |
+          cmake --install build --config Release
+
+    - name: Test
+      shell: powershell
+      working-directory: install2/bin
+      run: |
+          swig.exe -version

.travis.yml

@@ -1,536 +0,0 @@
-language: cpp
-matrix:
-  include:
-    - compiler: clang
-      os: linux
-      env: SWIGLANG=
-      sudo: required
-      dist: xenial
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=
-      sudo: required
-      dist: xenial
-    - os: linux
-      env: SWIGLANG= GCC=4.4
-      sudo: required
-      dist: xenial
-    - os: linux
-      env: SWIGLANG= GCC=4.6
-      sudo: required
-      dist: xenial
-    - os: linux
-      env: SWIGLANG= GCC=4.7
-      sudo: required
-      dist: xenial
-    - os: linux
-      env: SWIGLANG= GCC=4.8
-      sudo: required
-      dist: xenial
-    - os: linux
-      env: SWIGLANG= GCC=4.9
-      sudo: required
-      dist: xenial
-    - os: linux
-      env: SWIGLANG= GCC=6
-      sudo: required
-      dist: xenial
-    - os: linux
-      env: SWIGLANG= GCC=7
-      sudo: required
-      dist: xenial
-    - os: linux
-      env: SWIGLANG= GCC=8
-      sudo: required
-      dist: xenial
-    - os: linux
-      env: SWIGLANG= GCC=9
-      sudo: required
-      dist: xenial
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=csharp
-      sudo: required
-      dist: xenial
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=d VER=2.066.0
-      sudo: required
-      dist: xenial
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=d VER=2.086.1
-      sudo: required
-      dist: xenial
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=go VER=1.3
-      sudo: required
-      dist: xenial
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=go VER=1.8
-      sudo: required
-      dist: xenial
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=go VER=1.12
-      sudo: required
-      dist: xenial
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=guile
-      sudo: required
-      dist: xenial
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=java
-      sudo: required
-      dist: xenial
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=javascript ENGINE=node VER=0.10
-      sudo: required
-      dist: xenial
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=javascript ENGINE=node VER=4 CPP11=1
-      sudo: required
-      dist: xenial
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=javascript ENGINE=node VER=6 CPP11=1
-      sudo: required
-      dist: xenial
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=javascript ENGINE=node VER=8 CPP11=1
-      sudo: required
-      dist: xenial
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=javascript ENGINE=node VER=10 CPP11=1
-      sudo: required
-      dist: xenial
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=javascript ENGINE=jsc
-      sudo: required
-      dist: xenial
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=javascript ENGINE=v8
-      sudo: required
-      dist: xenial
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=lua
-      sudo: required
-      dist: xenial
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=lua VER=5.3
-      sudo: required
-      dist: xenial
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=mzscheme
-      sudo: required
-      dist: xenial
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=ocaml
-      sudo: required
-      dist: xenial
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=octave SWIGJOBS=-j2
-      sudo: required
-      dist: xenial   # Octave v4.0.0
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=octave SWIGJOBS=-j2 CPP11=1
-      sudo: required
-      dist: bionic   # Octave v4.2.2
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=perl5
-      sudo: required
-      dist: xenial
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=php VER=7.0
-      sudo: required
-      dist: xenial
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=php VER=7.1
-      sudo: required
-      dist: xenial
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=php VER=7.2
-      sudo: required
-      dist: xenial
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=php VER=7.3
-      sudo: required
-      dist: xenial
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=python # 2.7
-      sudo: required
-      dist: xenial
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=python PY3=3 VER=3.2
-      sudo: required
-      dist: xenial
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=python PY3=3 VER=3.3
-      sudo: required
-      dist: xenial
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=python PY3=3 VER=3.4
-      sudo: required
-      dist: xenial
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=python PY3=3 VER=3.5
-      sudo: required
-      dist: xenial
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=python PY3=3 VER=3.6
-      sudo: required
-      dist: xenial
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=python PY3=3 VER=3.7
-      sudo: required
-      dist: xenial
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=python PY3=3 VER=3.8
-      sudo: required
-      dist: xenial
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=python SWIG_FEATURES=-builtin
-      sudo: required
-      dist: xenial
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=python SWIG_FEATURES="-builtin -O"
-      sudo: required
-      dist: xenial
-    - os: linux
-      env: SWIGLANG=python SWIG_FEATURES=-builtin GCC=6 CPP11=1
-      sudo: required
-      dist: xenial
-    - os: linux
-      env: SWIGLANG=python SWIG_FEATURES=-builtin GCC=6 CPP11=1 PY3=3 VER=3.8
-      sudo: required
-      dist: xenial
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=python SWIG_FEATURES=-builtin PY3=3 VER=3.4
-      sudo: required
-      dist: xenial
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=python SWIG_FEATURES=-builtin PY3=3 VER=3.5
-      sudo: required
-      dist: xenial
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=python SWIG_FEATURES=-builtin PY3=3 VER=3.7
-      sudo: required
-      dist: xenial
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=python SWIG_FEATURES=-builtin PY3=3 VER=3.8
-      sudo: required
-      dist: xenial
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=python SWIG_FEATURES="-builtin -O" PY3=3 VER=3.8
-      sudo: required
-      dist: xenial
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=python SWIG_FEATURES=-builtin PY3=3 VER=3.8 SWIGOPTPY3=
-      sudo: required
-      dist: xenial
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=python SWIG_FEATURES=-O
-      sudo: required
-      dist: xenial
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=python SWIG_FEATURES=-O PY3=3 VER=3.8
-      sudo: required
-      dist: xenial
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=r
-      sudo: required
-      dist: xenial
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=ruby VER=1.9
-      sudo: required
-      dist: xenial
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=ruby VER=2.0
-      sudo: required
-      dist: xenial
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=ruby VER=2.1
-      sudo: required
-      dist: xenial
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=ruby VER=2.2
-      sudo: required
-      dist: xenial
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=ruby VER=2.3
-      sudo: required
-      dist: xenial
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=ruby VER=2.4
-      sudo: required
-      dist: xenial
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=ruby VER=2.5
-      sudo: required
-      dist: xenial
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=ruby VER=2.6
-      sudo: required
-      dist: xenial
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=ruby VER=2.7
-      sudo: required
-      dist: xenial
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=scilab
-      sudo: required
-      dist: xenial
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=tcl
-      sudo: required
-      dist: xenial
-    - os: linux
-      env: SWIGLANG=csharp CPP11=1
-      sudo: required
-      dist: xenial
-    - os: linux
-      env: SWIGLANG=go VER=1.6 CPP11=1
-      sudo: required
-      dist: xenial
-    - os: linux
-      env: SWIGLANG=java CPP11=1
-      sudo: required
-      dist: xenial
-    - os: linux
-      env: SWIGLANG=python CPP11=1
-      sudo: required
-      dist: xenial
-    - os: linux
-      env: SWIGLANG=r CPP11=1 # Note: making 'R CMD SHLIB' use a different compiler is non-trivial
-      sudo: required
-      dist: xenial
-    - os: linux
-      env: SWIGLANG=ruby CPP11=1
-      sudo: required
-      dist: xenial
-    - os: linux
-      env: SWIGLANG=tcl CPP11=1
-      sudo: required
-      dist: xenial
-    - os: linux
-      env: SWIGLANG=csharp GCC=6 CPP14=1
-      sudo: required
-      dist: xenial
-    - os: linux
-      env: SWIGLANG=go VER=1.6 GCC=6 CPP14=1
-      sudo: required
-      dist: xenial
-    - os: linux
-      env: SWIGLANG=java GCC=6 CPP14=1
-      sudo: required
-      dist: xenial
-    - os: linux
-      env: SWIGLANG=python GCC=6 CPP14=1
-      sudo: required
-      dist: xenial
-    - os: linux
-      env: SWIGLANG=ruby GCC=6 CPP14=1
-      sudo: required
-      dist: xenial
-    - os: linux
-      env: SWIGLANG=tcl GCC=6 CPP14=1
-      sudo: required
-      dist: xenial
-    - os: linux
-      env: SWIGLANG=java GCC=7 CPP14=1
-      sudo: required
-      dist: xenial
-    - os: linux
-      env: SWIGLANG=python GCC=7 CPP14=1
-      sudo: required
-      dist: xenial
-    - os: linux
-      env: SWIGLANG=csharp GCC=8 CPP17=1
-      sudo: required
-      dist: xenial
-    - os: linux
-      env: SWIGLANG=java GCC=8 CPP17=1
-      sudo: required
-      dist: xenial
-    - os: linux
-      env: SWIGLANG=python GCC=8 CPP17=1 PY3=3 VER=3.8
-      sudo: required
-      dist: xenial
-    - os: linux
-      env: SWIGLANG=csharp GCC=9 CPP17=1
-      sudo: required
-      dist: xenial
-    - os: linux
-      env: SWIGLANG=java GCC=9 CPP17=1
-      sudo: required
-      dist: xenial
-    - os: linux
-      env: SWIGLANG=python GCC=9 CPP17=1 PY3=3 VER=3.8
-      sudo: required
-      dist: xenial
-    - os: linux
-      arch: s390x
-      env: SWIGLANG=ruby CPP11=1
-      sudo: required
-      dist: xenial
-    - compiler: gcc
-      os: osx
-      env: SWIGLANG=
-    - compiler: clang
-      os: osx
-      env: SWIGLANG=
-    - compiler: clang
-      os: osx
-      env: SWIGLANG=csharp
-    - compiler: clang
-      os: osx
-      env: SWIGLANG=go
-    - compiler: clang
-      os: osx
-      env: SWIGLANG=guile CSTD=c11
-    - compiler: clang
-      os: osx
-      env: SWIGLANG=java
-    - compiler: clang
-      os: osx
-      env: SWIGLANG=lua
-    - compiler: clang
-      os: osx
-      env: SWIGLANG=octave SWIGJOBS=-j2 CPP11=1
-    - compiler: clang
-      os: osx
-      env: SWIGLANG=perl5
-    - compiler: clang
-      os: osx
-      env: SWIGLANG=python
-    - compiler: clang
-      os: osx
-      env: SWIGLANG=python PY3=3
-    - compiler: clang
-      os: osx
-      env: SWIGLANG=ruby
-    - compiler: clang
-      os: osx
-      env: SWIGLANG=tcl
-    - compiler: clang
-      os: osx
-      env: SWIGLANG=java CPP17=1
-      osx_image: xcode10.2
-    - compiler: clang
-      os: osx
-      env: SWIGLANG=python PY3=3 CPP17=1
-      osx_image: xcode10.2
-
-  allow_failures:
-    # Newer version of D not yet working/supported
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=d VER=2.086.1
-      sudo: required
-      dist: xenial
-    # seg fault in director_basic testcase
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=php VER=7.2
-      sudo: required
-      dist: xenial
-    # Experimental languages
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=mzscheme
-      sudo: required
-      dist: xenial
-    - compiler: gcc
-      os: linux
-      env: SWIGLANG=ocaml
-      sudo: required
-      dist: xenial
-
-before_install:
-  - date -u
-  - uname -a
-  - if test "$TRAVIS_OS_NAME" = "linux"; then lscpu; grep "model name" /proc/cpuinfo || echo 'Unknown CPU model'; grep "MemTotal" /proc/meminfo || echo 'Unknown system memory amount'; fi
-  - if test "$TRAVIS_OS_NAME" = "osx"; then sysctl -a | grep brand_string; fi
-  # Travis overrides CC environment with compiler predefined values
-  - if test -n "$GCC"; then export CC="gcc-$GCC" && export CXX="g++-$GCC"; fi
-install:
-  - if test "$TRAVIS_OS_NAME" = "linux"; then source Tools/travis-linux-install.sh; fi
-  - if test "$TRAVIS_OS_NAME" = "osx"; then source Tools/travis-osx-install.sh; fi
-  - ls -la $(which $CC) $(which $CXX) && $CC --version && $CXX --version
-script:
-  - echo 'Configuring...' && echo -en 'travis_fold:start:script.1\\r'
-  - if test -n "$CPP11"; then CONFIGOPTS+=(--enable-cpp11-testing --without-maximum-compile-warnings "CXXFLAGS=-std=c++11 -Wall -Wextra" "CFLAGS=-std=c11 -Wall -Wextra") && export CSTD=c11 && export CPPSTD=c++11; fi
-  - if test -n "$CPP14"; then CONFIGOPTS+=(--enable-cpp11-testing --without-maximum-compile-warnings "CXXFLAGS=-std=c++14 -Wall -Wextra" "CFLAGS=-std=c11 -Wall -Wextra") && export CSTD=c11 && export CPPSTD=c++14; fi
-  - if test -n "$CPP17"; then CONFIGOPTS+=(--enable-cpp11-testing --without-maximum-compile-warnings "CXXFLAGS=-std=c++17 -Wall -Wextra" "CFLAGS=-std=c17 -Wall -Wextra") && export CSTD=c17 && export CPPSTD=c++17; fi
-  - if test -n "$SWIGLANG"; then CONFIGOPTS+=(--without-alllang --with-$WITHLANG); fi
-  - echo "${CONFIGOPTS[@]}"
-  - ./autogen.sh && mkdir -p build/build && cd build/build && ../../configure "${CONFIGOPTS[@]}"
-  - echo -en 'travis_fold:end:script.1\\r'
-  - make -s $SWIGJOBS
-  - ./swig -version && ./swig -pcreversion
-  - if test -z "$SWIGLANG"; then make -s $SWIGJOBS check-ccache; fi
-  - if test -z "$SWIGLANG"; then make -s $SWIGJOBS check-errors-test-suite; fi
-  - echo 'Installing...' && echo -en 'travis_fold:start:script.2\\r'
-  - if test -z "$SWIGLANG"; then sudo make -s install && swig -version && ccache-swig -V; fi
-  - echo -en 'travis_fold:end:script.2\\r'
-  # Stricter compile flags for examples. Various headers and SWIG generated code prevents full use of -pedantic.
-  - if test -n "$SWIGLANG"; then cflags=$($TRAVIS_BUILD_DIR/Tools/testflags.py --language $SWIGLANG --cflags --std=$CSTD --compiler=$CC) && echo $cflags; fi
-  - if test -n "$SWIGLANG"; then cxxflags=$($TRAVIS_BUILD_DIR/Tools/testflags.py --language $SWIGLANG --cxxflags --std=$CPPSTD --compiler=$CC) && echo $cxxflags; fi
-  - if test -n "$SWIGLANG"; then make -s check-$SWIGLANG-version; fi
-  - if test -n "$SWIGLANG"; then make check-$SWIGLANG-enabled; fi
-  - if test -n "$SWIGLANG"; then make $SWIGJOBS check-$SWIGLANG-examples CFLAGS="$cflags" CXXFLAGS="$cxxflags"; fi
-  - if test -n "$SWIGLANG"; then make $SWIGJOBS check-$SWIGLANG-test-suite CFLAGS="$cflags" CXXFLAGS="$cxxflags"; fi
-  - echo 'Cleaning...' && echo -en 'travis_fold:start:script.3\\r'
-  - make check-maintainer-clean && ../../configure $CONFIGOPTS
-  - echo -en 'travis_fold:end:script.3\\r'

ANNOUNCE

@@ -1,8 +1,8 @@
-*** ANNOUNCE: SWIG 4.0.2 (8 Jun 2020) ***
+*** ANNOUNCE: SWIG 4.2.0 (30 Dec 2023) ***
 
-http://www.swig.org
+https://www.swig.org
 
-We're pleased to announce SWIG-4.0.2, the latest SWIG release.
+We're pleased to announce SWIG-4.2.0, the latest SWIG release.
 
 What is SWIG?
 =============
@@ -19,20 +19,20 @@ and user interface development for large C/C++ systems.
 Release Notes
 =============
 Detailed release notes are available with the release and are also
-published on the SWIG web site at http://swig.org/release.html.
+published on the SWIG web site at https://swig.org/release.html.
 
 Availability
 ============
 The release is available for download on Sourceforge at
 
-     http://prdownloads.sourceforge.net/swig/swig-4.0.2.tar.gz
+     https://prdownloads.sourceforge.net/swig/swig-4.2.0.tar.gz
 
 A Windows version is also available at
 
-     http://prdownloads.sourceforge.net/swig/swigwin-4.0.2.zip
+     https://prdownloads.sourceforge.net/swig/swigwin-4.2.0.zip
 
 Please report problems with this release to the swig-devel mailing list,
-details at http://www.swig.org/mail.html.
+details at https://www.swig.org/mail.html.
 
 --- The SWIG Developers
 

CCache/README.swig

@@ -2,7 +2,7 @@ This directory contains a version of ccache. The initial version was based on cc
 debian patches 01-02, 04-14, see the debian/patches subdirectory. The ccache-win32-2.4 modifications
 to ccache-2.4 have also been merged in.
 
-Changes have been made to support cacheing the output from SWIG. The ability to cache c/c++ compiler 
+Changes have been made to support caching the output from SWIG. The ability to cache c/c++ compiler 
 output has been retained.
 
 Additional features added are the CCACHE_VERBOSE and CCACHE_SWIG environment variables, see docs.

CCache/ccache.c

@@ -735,13 +735,15 @@ static void from_cache(int first)
 	}
 
 	/* send the cpp stderr, if applicable */
-	fd_cpp_stderr = open(cpp_stderr, O_RDONLY | O_BINARY);
-	if (fd_cpp_stderr != -1) {
-		copy_fd(fd_cpp_stderr, 2);
-		close(fd_cpp_stderr);
-		unlink(cpp_stderr);
-		free(cpp_stderr);
-		cpp_stderr = NULL;
+	if (cpp_stderr) {
+		fd_cpp_stderr = open(cpp_stderr, O_RDONLY | O_BINARY);
+		if (fd_cpp_stderr != -1) {
+			copy_fd(fd_cpp_stderr, 2);
+			close(fd_cpp_stderr);
+			unlink(cpp_stderr);
+			free(cpp_stderr);
+			cpp_stderr = NULL;
+		}
 	}
 
 	/* send the stderr */
@@ -1089,7 +1091,7 @@ static void process_args(int argc, char **argv)
 				}
 				*p = 0;
 			}
-			else  {
+			else {
 				int len = p - default_depfile_name;
 				
 				p = x_malloc(len + 3);

CCache/ccache.yo

@@ -409,7 +409,7 @@ ccache was adapted to create ccache-swig for use with SWIG by William Fulton.
 
 If you wish to report a problem or make a suggestion then please email
 the SWIG developers on the swig-devel mailing list, see
-url(http://www.swig.org/mail.html)(http://www.swig.org/mail.html)
+url(https://www.swig.org/mail.html)(https://www.swig.org/mail.html)
 
 ccache is released under the GNU General Public License version 2 or
 later. Please see the file COPYING for license details.

CCache/config.h.in

@@ -28,9 +28,6 @@
 /* Define to 1 if you have the <inttypes.h> header file. */
 #undef HAVE_INTTYPES_H
 
-/* Define to 1 if you have the <memory.h> header file. */
-#undef HAVE_MEMORY_H
-
 /* Define to 1 if you have the `mkstemp' function. */
 #undef HAVE_MKSTEMP
 
@@ -49,6 +46,9 @@
 /* Define to 1 if you have the <stdint.h> header file. */
 #undef HAVE_STDINT_H
 
+/* Define to 1 if you have the <stdio.h> header file. */
+#undef HAVE_STDIO_H
+
 /* Define to 1 if you have the <stdlib.h> header file. */
 #undef HAVE_STDLIB_H
 
@@ -111,11 +111,10 @@
 /* Define my program name */
 #undef PROGRAM_NAME
 
-/* Define to 1 if you have the ANSI C header files. */
+/* Define to 1 if all of the C90 standard headers exist (not just the ones
+   required in a freestanding environment). This macro is provided for
+   backward compatibility; new code need not use it. */
 #undef STDC_HEADERS
 
-/* Define to 1 if you can safely include both <sys/time.h> and <time.h>. */
-#undef TIME_WITH_SYS_TIME
-
 /* Define _GNU_SOURCE so that we get all necessary prototypes */
 #undef _GNU_SOURCE

CCache/configure.ac

@@ -1,12 +1,12 @@
 dnl Process this file with autoconf to produce a configure script.
 
-AC_INIT([ccache-swig], [0.0]) # Get version from SWIG in ccache_swig_config.h.in
-AC_PREREQ(2.52)
+AC_INIT([ccache-swig],[0.0]) # Get version from SWIG in ccache_swig_config.h.in
+AC_PREREQ([2.60])
 AC_CONFIG_SRCDIR([ccache.h])
 
 AC_MSG_NOTICE([Configuring ccache])
 
-AC_CONFIG_HEADER(config.h)
+AC_CONFIG_HEADERS([config.h])
 AC_CONFIG_FILES([config_win32.h])
 
 dnl Checks for programs.
@@ -41,7 +41,7 @@ else
 fi
 
 AC_HEADER_DIRENT
-AC_HEADER_TIME
+
 AC_HEADER_SYS_WAIT
 
 AC_CHECK_HEADERS(ctype.h strings.h stdlib.h string.h pwd.h sys/time.h)
@@ -51,21 +51,21 @@ AC_CHECK_FUNCS(gethostname getpwuid)
 AC_CHECK_FUNCS(utimes)
 
 AC_CACHE_CHECK([for compar_fn_t in stdlib.h],ccache_cv_COMPAR_FN_T, [
-    AC_TRY_COMPILE(
-[#include <stdlib.h>],
-[
+    AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <stdlib.h>]], [[
 void test_fn(void) { qsort(NULL, 0, 0, (__compar_fn_t)NULL); }
-],
-	ccache_cv_COMPAR_FN_T=yes,ccache_cv_COMPAR_FN_T=no)])
+]])],[ccache_cv_COMPAR_FN_T=yes],[ccache_cv_COMPAR_FN_T=no])])
 if test x"$ccache_cv_COMPAR_FN_T" = x"yes"; then
    AC_DEFINE(HAVE_COMPAR_FN_T, 1, [ ])
 fi
 
 dnl Note: This could be replaced by AC_FUNC_SNPRINTF() in the autoconf macro archive
 AC_CACHE_CHECK([for C99 vsnprintf],ccache_cv_HAVE_C99_VSNPRINTF,[
-AC_TRY_RUN([
+AC_RUN_IFELSE([AC_LANG_SOURCE([[
 #include <sys/types.h>
 #include <stdarg.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
 void foo(const char *format, ...) { 
        va_list ap;
        int len;
@@ -80,9 +80,8 @@ void foo(const char *format, ...) {
 
        exit(0);
 }
-main() { foo("hello"); }
-],
-ccache_cv_HAVE_C99_VSNPRINTF=yes,ccache_cv_HAVE_C99_VSNPRINTF=no,ccache_cv_HAVE_C99_VSNPRINTF=cross)])
+int main(void) { foo("hello"); }
+]])],[ccache_cv_HAVE_C99_VSNPRINTF=yes],[ccache_cv_HAVE_C99_VSNPRINTF=no],[ccache_cv_HAVE_C99_VSNPRINTF=cross])])
 if test x"$ccache_cv_HAVE_C99_VSNPRINTF" = x"yes"; then
     AC_DEFINE(HAVE_C99_VSNPRINTF, 1, [ ])
 fi

CCache/execute.c

@@ -137,7 +137,7 @@ int execute(char **argv,
 	_dup2(fd, 2);
 	_close(fd);
 
-	/* Spawn process (_exec* familly doesn't return) */
+	/* Spawn process (_exec* family doesn't return) */
 	status = _spawnv(_P_WAIT, argv[0], (const char **)argv);
 
 	/* Restore descriptors */

CCache/mdfour.c

@@ -24,8 +24,6 @@
    It assumes that a int is at least 32 bits long
 */
 
-static struct mdfour *m;
-
 #define MASK32 (0xffffffff)
 
 #define F(X,Y,Z) ((((X)&(Y)) | ((~(X))&(Z))))
@@ -38,12 +36,12 @@ static struct mdfour *m;
 #define ROUND3(a,b,c,d,k,s) a = lshift((a + H(b,c,d) + M[k] + 0x6ED9EBA1)&MASK32,s)
 
 /* this applies md4 to 64 byte chunks */
-static void mdfour64(uint32 *M)
+static void mdfour64(struct mdfour *md, uint32 *M)
 {
 	uint32 AA, BB, CC, DD;
 	uint32 A,B,C,D;
 
-	A = m->A; B = m->B; C = m->C; D = m->D; 
+	A = md->A; B = md->B; C = md->C; D = md->D;
 	AA = A; BB = B; CC = C; DD = D;
 
         ROUND1(A,B,C,D,  0,  3);  ROUND1(D,A,B,C,  1,  7);  
@@ -80,7 +78,7 @@ static void mdfour64(uint32 *M)
 	A &= MASK32; B &= MASK32; 
 	C &= MASK32; D &= MASK32;
 
-	m->A = A; m->B = B; m->C = C; m->D = D;
+	md->A = A; md->B = B; md->C = C; md->D = D;
 }
 
 static void copy64(uint32 *M, const unsigned char *in)
@@ -88,8 +86,8 @@ static void copy64(uint32 *M, const unsigned char *in)
 	int i;
 
 	for (i=0;i<16;i++)
-		M[i] = (in[i*4+3]<<24) | (in[i*4+2]<<16) |
-			(in[i*4+1]<<8) | (in[i*4+0]<<0);
+		M[i] = ((uint32)in[i*4+3]<<24) | ((uint32)in[i*4+2]<<16) |
+			((uint32)in[i*4+1]<<8) | ((uint32)in[i*4+0]<<0);
 }
 
 static void copy4(unsigned char *out,uint32 x)
@@ -111,15 +109,15 @@ void mdfour_begin(struct mdfour *md)
 }
 
 
-static void mdfour_tail(const unsigned char *in, int n)
+static void mdfour_tail(struct mdfour *md, const unsigned char *in, int n)
 {
 	unsigned char buf[128];
 	uint32 M[16];
 	uint32 b;
 
-	m->totalN += n;
+	md->totalN += n;
 
-	b = m->totalN * 8;
+	b = md->totalN * 8;
 
 	memset(buf, 0, 128);
 	if (n) memcpy(buf, in, n);
@@ -128,13 +126,13 @@ static void mdfour_tail(const unsigned char *in, int n)
 	if (n <= 55) {
 		copy4(buf+56, b);
 		copy64(M, buf);
-		mdfour64(M);
+		mdfour64(md, M);
 	} else {
 		copy4(buf+120, b); 
 		copy64(M, buf);
-		mdfour64(M);
+		mdfour64(md, M);
 		copy64(M, buf+64);
-		mdfour64(M);
+		mdfour64(md, M);
 	}
 }
 
@@ -142,10 +140,8 @@ void mdfour_update(struct mdfour *md, const unsigned char *in, int n)
 {
 	uint32 M[16];
 
-	m = md;
-
 	if (in == NULL) {
-		mdfour_tail(md->tail, md->tail_len);
+		mdfour_tail(md, md->tail, md->tail_len);
 		return;
 	}
 
@@ -158,18 +154,18 @@ void mdfour_update(struct mdfour *md, const unsigned char *in, int n)
 		in += len;
 		if (md->tail_len == 64) {
 			copy64(M, md->tail);
-			mdfour64(M);
-			m->totalN += 64;
+			mdfour64(md, M);
+			md->totalN += 64;
 			md->tail_len = 0;
 		}
 	}
 
 	while (n >= 64) {
 		copy64(M, in);
-		mdfour64(M);
+		mdfour64(md, M);
 		in += 64;
 		n -= 64;
-		m->totalN += 64;
+		md->totalN += 64;
 	}
 
 	if (n) {
@@ -181,12 +177,10 @@ void mdfour_update(struct mdfour *md, const unsigned char *in, int n)
 
 void mdfour_result(struct mdfour *md, unsigned char *out)
 {
-	m = md;
-
-	copy4(out, m->A);
-	copy4(out+4, m->B);
-	copy4(out+8, m->C);
-	copy4(out+12, m->D);
+	copy4(out, md->A);
+	copy4(out+4, md->B);
+	copy4(out+8, md->C);
+	copy4(out+12, md->D);
 }
 
 
@@ -272,7 +266,12 @@ static void file_checksum2(char *fname)
 	printf("\n");
 }
 #endif
-
+/*
+ * To test:
+ *   gcc -DTEST_MDFOUR mdfour.c -o mdfourexe && ./mdfourexe <somefile>
+ * then compare against a reference, such as:
+ *   openssl dgst -md4 <somefile>
+ */
  int main(int argc, char *argv[])
 {
 	file_checksum1(argv[1]);

CCache/snprintf.c

@@ -16,7 +16,7 @@
  * for string length.  This covers a nasty loophole.
  *
  * The other functions are there to prevent NULL pointers from
- * causing nast effects.
+ * causing nasty effects.
  *
  * More Recently:
  *  Brandon Long <blong@fiction.net> 9/15/96 for mutt 0.43
@@ -30,7 +30,7 @@
  *    probably requires libm on most operating systems.  Don't yet
  *    support the exponent (e,E) and sigfig (g,G).  Also, fmtint()
  *    was pretty badly broken, it just wasn't being exercised in ways
- *    which showed it, so that's been fixed.  Also, formated the code
+ *    which showed it, so that's been fixed.  Also, formatted the code
  *    to mutt conventions, and removed dead code left over from the
  *    original.  Also, there is now a builtin-test, just compile with:
  *           gcc -DTEST_SNPRINTF -o snprintf snprintf.c -lm

CCache/web/index.html

@@ -34,7 +34,7 @@ on the new options.<p>
 
 You can get this release from the <a href="http://ccache.samba.org/ftp/ccache/">download directory</a> 
 
-<p>NOTE! This release changes the hash input slighly, so you will
+<p>NOTE! This release changes the hash input slightly, so you will
 probably find that you will not get any hits against your existing
 cache when you upgrade.
 

CMakeLists.txt

@@ -0,0 +1,169 @@
+cmake_minimum_required (VERSION 3.13)
+
+set (CMAKE_BUILD_TYPE Release CACHE STRING "Build type")
+
+project (swig)
+
+if (POLICY CMP0074)
+  cmake_policy (SET CMP0074 NEW)
+endif()
+
+file (STRINGS configure.ac line LIMIT_COUNT 1 REGEX "AC_INIT\\(.*\\)" )
+if (line MATCHES "AC_INIT\\(\\[(.*)\\],[ \t]*\\[(.*)\\],[ \t]*\\[(.*)\\]\\)" )
+  set (SWIG_VERSION ${CMAKE_MATCH_2})
+  set (PACKAGE_BUGREPORT ${CMAKE_MATCH_3})
+else ()
+  message (SEND_ERROR "Could not parse version from configure.ac")
+endif ()
+
+set (SWIG_ROOT ${PROJECT_SOURCE_DIR})
+
+if (WIN32)
+  set (SWIG_LIB bin/Lib)
+else ()
+  set (SWIG_LIB share/swig/${SWIG_VERSION})
+endif ()
+# Project wide configuration variables
+# ------------------------------------
+
+set (SWIG_SOURCE_DIR ${SWIG_ROOT}/Source CACHE INTERNAL "Path of swig sources" FORCE)
+
+set (PACKAGE_NAME swig)
+set (PACKAGE_VERSION ${SWIG_VERSION})
+
+# Configure
+# ---------
+
+list (APPEND CMAKE_MODULE_PATH ${SWIG_ROOT}/Tools/cmake)
+
+include (CheckIncludeFiles)
+include (CheckIncludeFile)
+include (CheckIncludeFileCXX)
+include (CheckTypeSize)
+include (CheckSymbolExists)
+include (CheckFunctionExists)
+include (CheckLibraryExists)
+include (CheckCSourceCompiles)
+
+# HACK: didn't get the bool check working for Visual Studio 2008
+if (MSVC)
+  set(HAVE_BOOL 1)
+else()
+  set (CMAKE_EXTRA_INCLUDE_FILES stdbool.h)
+  check_type_size ("bool" HAVE_BOOL)
+  set (CMAKE_EXTRA_INCLUDE_FILES)
+endif()
+
+check_include_file ("inttypes.h" HAVE_INTTYPES_H)
+check_include_file ("stddef.h" HAVE_STDDEF_H)
+check_include_file ("stdint.h" HAVE_STDINT_H)
+check_include_file ("stdio.h" HAVE_STDIO_H)
+check_include_file ("stdlib.h" HAVE_STDLIB_H)
+check_include_file ("string.h" HAVE_STRING_H)
+check_include_file ("strings.h" HAVE_STRINGS_H)
+check_include_file ("sys/stat.h" HAVE_SYS_STAT_H)
+check_include_file ("sys/types.h" HAVE_SYS_TYPES_H)
+check_include_file ("unistd.h" HAVE_UNISTD_H)
+check_include_files ("stdlib.h;stdarg.h;string.h;float.h" STDC_HEADERS)
+
+check_include_file_cxx ("boost/shared_ptr.hpp" HAVE_BOOST)
+check_library_exists (dl dlopen "" HAVE_LIBDL)
+check_function_exists (popen HAVE_POPEN)
+
+if (MSVC)
+  set (CMAKE_CXX_FLAGS "/EHsc ${CMAKE_CXX_FLAGS}")
+endif ()
+
+option (WITH_PCRE "Enable PCRE" ON)
+if (WITH_PCRE)
+  find_package (PCRE2 REQUIRED)
+  set (HAVE_PCRE 1)
+  include_directories (${PCRE2_INCLUDE_DIRS})
+endif()
+
+#if (WIN32)
+#  file (TO_NATIVE_PATH ${CMAKE_INSTALL_PREFIX}/${SWIG_LIB} SWIG_LIB_WIN_UNIX)
+#  string (REGEX REPLACE "\\\\" "\\\\\\\\" SWIG_LIB_WIN_UNIX "${SWIG_LIB_WIN_UNIX}")
+#endif ()
+configure_file (${SWIG_ROOT}/Tools/cmake/swigconfig.h.in
+                ${CMAKE_CURRENT_BINARY_DIR}/Source/Include/swigconfig.h)
+
+find_package (BISON REQUIRED)
+
+
+# Compiler flags
+# --------------
+
+include_directories (
+    ${SWIG_SOURCE_DIR}/CParse
+    ${SWIG_SOURCE_DIR}/Include
+    ${SWIG_SOURCE_DIR}/DOH
+    ${SWIG_SOURCE_DIR}/Swig
+    ${SWIG_SOURCE_DIR}/Preprocessor
+    ${SWIG_SOURCE_DIR}/Modules
+    ${PROJECT_BINARY_DIR}/Source/Include
+    ${PROJECT_BINARY_DIR}/Source/CParse
+    ${PROJECT_SOURCE_DIR}/Source/Doxygen
+)
+
+# generate the parser source code (depends on bison)
+file (MAKE_DIRECTORY ${PROJECT_BINARY_DIR}/Source/CParse)
+
+BISON_TARGET (swig_parser
+    ${SWIG_SOURCE_DIR}/CParse/parser.y
+    ${PROJECT_BINARY_DIR}/Source/CParse/parser.c
+)
+
+# generate swigwarn.swg
+file (READ ${SWIG_SOURCE_DIR}/Include/swigwarn.h SWIG_WARN_H)
+string (REGEX REPLACE "#define WARN([^ \\t]*)[ \\t]*([0-9]+)" "%define SWIGWARN\\1 \\2 %enddef" SWIG_WARN_SWG ${SWIG_WARN_H})
+file (WRITE ${CMAKE_CURRENT_BINARY_DIR}/swigwarn.swg ${SWIG_WARN_SWG})
+set_property (SOURCE ${CMAKE_CURRENT_BINARY_DIR}/swigwarn.swg PROPERTY GENERATED 1)
+
+# install lib
+install (DIRECTORY ${SWIG_ROOT}/Lib/ DESTINATION ${SWIG_LIB})
+install (FILES ${CMAKE_CURRENT_BINARY_DIR}/swigwarn.swg DESTINATION ${SWIG_LIB})
+
+# sources
+# ---------
+file (GLOB DOH_SOURCES ${SWIG_SOURCE_DIR}/DOH/*.c)
+file (GLOB CPARSE_SOURCES ${SWIG_SOURCE_DIR}/CParse/*.c)
+list (REMOVE_ITEM CPARSE_SOURCES ${SWIG_SOURCE_DIR}/CParse/parser.c)
+list (APPEND CPARSE_SOURCES)
+file (GLOB PREPROCESSOR_SOURCES ${SWIG_SOURCE_DIR}/Preprocessor/*.c)
+file (GLOB CORE_SOURCES ${SWIG_SOURCE_DIR}/Swig/*.c)
+file (GLOB DOXYGEN_SOURCES ${SWIG_SOURCE_DIR}/Doxygen/*.cxx)
+file (GLOB MODULES_SOURCES ${SWIG_SOURCE_DIR}/Modules/*.cxx)
+
+add_executable (swig
+  ${CPARSE_SOURCES}
+  ${DOH_SOURCES}
+  ${DOXYGEN_SOURCES}
+  ${MODULES_SOURCES}
+  ${CORE_SOURCES}
+  ${PREPROCESSOR_SOURCES}
+  ${PROJECT_BINARY_DIR}/Source/Include/swigconfig.h
+  ${SWIG_SOURCE_DIR}/Include/swigwarn.h
+  ${PROJECT_BINARY_DIR}/Source/CParse/parser.c
+  ${PROJECT_BINARY_DIR}/Source/CParse/parser.h
+)
+if (PCRE2_FOUND)
+  target_link_libraries (swig ${PCRE2_LIBRARIES})
+endif ()
+install (TARGETS swig DESTINATION bin)
+
+# 'make package-source' creates tarballs
+set (CPACK_PACKAGE_NAME ${PACKAGE_NAME})
+set (CPACK_SOURCE_GENERATOR "TGZ;TBZ2")
+set (CPACK_SOURCE_IGNORE_FILES "/.git;/build;.*~;${CPACK_SOURCE_IGNORE_FILES}")
+set (CPACK_SOURCE_PACKAGE_FILE_NAME ${PACKAGE_NAME}-${PACKAGE_VERSION})
+include (CPack)
+
+# few tests
+enable_testing ()
+add_test (NAME cmd_version COMMAND swig -version)
+add_test (NAME cmd_pcreversion COMMAND swig -pcreversion)
+add_test (NAME cmd_swiglib COMMAND swig -swiglib)
+add_test (NAME cmd_external_runtime COMMAND swig -external-runtime ext_rt.h)
+set_tests_properties(cmd_external_runtime PROPERTIES ENVIRONMENT "SWIG_LIB=${PROJECT_SOURCE_DIR}/Lib")
+

COPYRIGHT

@@ -1,7 +1,7 @@
 SWIG Copyright and Authors
 --------------------------
 
-Copyright (c) 1995-2011 The SWIG Developers
+Copyright (c) 1995-2023 The SWIG Developers
 Copyright (c) 2005-2006 Arizona Board of Regents (University of Arizona).
 Copyright (c) 1998-2005 University of Chicago.
 Copyright (c) 1995-1998 The University of Utah and the Regents of the University of California
@@ -14,10 +14,7 @@ Active SWIG Developers:
  William Fulton (wsf@fultondesigns.co.uk)                 (SWIG core, Java, C#, Windows, Cygwin)
  Olly Betts (olly@survex.com)                             (PHP)
  Joseph Wang (joequant@gmail.com)                         (R)
- Xavier Delacour (xavier.delacour@gmail.com)              (Octave)
- David Nadlinger (code@klickverbot.at)                    (D)
- Oliver Buchtala (oliver.buchtala@gmail.com)              (Javascript)
- Neha Narang (narangneha03@gmail.com)                     (Javascript)
+ Momtchil Momtchev (momtchil@momtchev.com)                (Javascript Node-API)
  Simon Marchetto (simon.marchetto@scilab-enterprises.com) (Scilab)
  Zackery Spytz (zspytz@gmail.com)                         (OCaml, SWIG core)
 
@@ -69,6 +66,10 @@ Past SWIG developers and major contributors include:
  Vincent Couvert                                          (Scilab)
  Sylvestre Ledru                                          (Scilab)
  Wolfgang Frisch                                          (Scilab)
+ Oliver Buchtala (oliver.buchtala@gmail.com)              (Javascript)
+ Neha Narang (narangneha03@gmail.com)                     (Javascript)
+ Xavier Delacour (xavier.delacour@gmail.com)              (Octave)
+ David Nadlinger (code@klickverbot.at)                    (D)
 
 Past contributors include:
  James Michael DuPont, Clark McGrew, Dustin Mitchell, Ian Cooke, Catalin Dumitrescu, Baran

Doc/Devel/cmdopt.html

@@ -60,7 +60,7 @@ and issues an error message if any unconsumed arguments are found.
 <b><tt>void Swig_check_options()</tt></b>
 <blockquote>
 Checks all command line options to see if they have all been processed.  If not, an error message is generated and
-execution terminates with a call to <tt>exit()</tt>.   This function is currently invoked in <tt>Source/Modules/main.cxx</tt> just before SWIG starts any processing of input files.
+SWIG exits.   This function is currently invoked in <tt>Source/Modules/main.cxx</tt> just before SWIG starts any processing of input files.
 </blockquote>
 
 <h2>Utility Function</h2>
@@ -68,7 +68,7 @@ execution terminates with a call to <tt>exit()</tt>.   This function is currentl
 <b><tt>void Swig_arg_error())</tt></b>
 
 <blockquote>
-A generic function that issues an error message about being unable to parse command line options.  SWIG is terminated by a call to <tt>exit()</tt>.
+A generic function that issues an error message about being unable to parse command line options and SWIG exits.
 
 </body>
 </html>

Doc/Devel/engineering.html

@@ -130,7 +130,7 @@ like this:
  * terms also apply to certain portions of SWIG. The full details of the SWIG
  * license and copyrights can be found in the LICENSE and COPYRIGHT files
  * included with the SWIG source code as distributed by the SWIG developers
- * and at http://www.swig.org/legal.html.
+ * and at https://www.swig.org/legal.html.
  *
  * xxx.c
  *

Doc/Devel/internals.html

@@ -108,7 +108,7 @@ subdir tree.</td>
   </tr>
 
   <tr><td>CParse</td>
-  <td>Parser (lex / yacc) files and support</td>
+  <td>Parser (bison) files and support</td>
   </tr>
 
   <tr><td>Modules</td>
@@ -441,12 +441,12 @@ Resulting output:
 
 <blockquote>
 <pre>
-hash len: 5
-get: hashval2
-hash item: hashval5 [h5]
-hash item: hashval1 [h1]
-hash item: hashval2 [h2]
-hash item: hashval3 [h3]
+list len: 5
+get: listval2
+list item: newlistval1
+list item: listval2
+list item: listval3
+list item: listval5
 </pre>
 </blockquote>
 
@@ -494,12 +494,12 @@ Resulting output:
 
 <blockquote>
 <pre>
-list len: 5
-get: listval2
-list item: newlistval1
-list item: listval2
-list item: listval3
-list item: listval5
+hash len: 5
+get: hashval2
+hash item: hashval5 [h5]
+hash item: hashval1 [h1]
+hash item: hashval2 [h2]
+hash item: hashval3 [h3]
 </pre>
 </blockquote>
 
@@ -519,7 +519,27 @@ list item: listval5
 <h3>2.10 Utility functions </h3>
 </a>
 
-[ TODO ]
+<p>
+DOH wraps some standard C library functions - these wrapped versions should
+always be used in code in the SWIG tool itself (but not in generated code).
+When compiling with GCC or clang, the original library function names are
+marked as "poisoned" symbols so you should get an error if you accidentally
+use one of the unwrapped functions.  These functions are:
+
+<ul>
+    <li><tt>Calloc(m,n)</tt> : wrapper for <tt>calloc(m,n)</tt> which exits on memory failure so never returns <tt>NULL</tt>.
+    <li><tt>Malloc(n)</tt> : wrapper for <tt>malloc(n)</tt> which exits on memory failure so never returns <tt>NULL</tt>.
+    <li><tt>Realloc(p,n)</tt> : wrapper for <tt>realloc(p,n)</tt> which exits on memory failure so never returns <tt>NULL</tt>.
+    <li><tt>Free(p)</tt> : wrapper for <tt>free(p)</tt> (doesn't currently do anything special, really done for consistency with <tt>Malloc()</tt> etc).
+    <li><tt>Exit(r)</tt> : wrapper for <tt>exit(r)</tt> which for SWIG removes generated files if <tt>r&gt;0</tt>.
+</ul>
+
+<tt>abort()</tt> is also poisoned - please use <tt>Exit(EXIT_FAILURE)</tt> instead so that generated files are removed.
+</p>
+
+<p>
+[ TODO document others ]
+</p>
 
 <a name="3" href="#i3">
 <h2>3. Types and Typemaps</h2>
@@ -1194,12 +1214,12 @@ that are used after they have been deleted. This is because the DOH memory alloc
 grabs a chunk of memory from the C memory allocator and manages the usage internally.
 Stale DOH object usage can be checked for by defining <tt>DOH_DEBUG_MEMORY_POOLS</tt> in 
 <tt>memory.c</tt>. If an attempt to use an object is made after the reference count is
-zero, an assertion is triggered instead of quietly re-using the stale object...
+zero, a fatal error is triggered instead of quietly re-using the stale object:
 </p>
 
 <blockquote>
 <pre>
-swig: DOH/memory.c:91: DohCheck: Assertion `!DOH_object_already_deleted' failed.
+Fatal internal error: Attempt to delete a non-DOH object.
 </pre>
 </blockquote>
 
@@ -1209,7 +1229,7 @@ only recommended for diagnosing memory corruption problems.
 </p>
 
 <hr>
-Copyright (C) 1999-2010 SWIG Development Team.
+Copyright (C) 1999-2022 SWIG Development Team.
 
 </body>
 </html>

Doc/Devel/migrate.txt

@@ -101,10 +101,10 @@ parameter values is as follows:
   ParmList *l;
   Parm *p;
 
-  for (p = l; p; p = Getnext(p)) {
-      SwigType *pt = Gettype(p);        /* Get parameter type */
-      String   *pn = Getname(p);        /* Get parameter name */
-      String   *value = Getvalue(p);    /* Get parameter value */
+  for (p = l; p; p = nextSibling(p)) {
+      SwigType *pt = Getattr(p, "type");      /* Get parameter type */
+      String   *pn = Getattr(p, "name");      /* Get parameter name */
+      String   *value = Getattr(p, "value");  /* Get parameter value */
       ...
       do whatever
       ...
@@ -119,7 +119,7 @@ Typemaps more or less work.  However, the interface has changed slightly.  Inste
 
 the function is
 
-     Swig_typemap_lookup("in",type,pname,"$source","$target",wrapper);
+     Swig_typemap_lookup("in", node, pname, wrapper);
 
 There are a variety of other changes to typemaps (see CHANGES).
 

Doc/Devel/plan-gsoc-2012.txt

@@ -45,7 +45,7 @@ Functionality
   -----------------
   
   Note:
-     See 'http://www.stack.nl/~dimitri/doxygen/docblocks.html' for
+     See 'https://www.doxygen.nl/manual/docblocks.html' for
      the detailed description of Doxygen syntax and terms used in this
      section.
 
@@ -72,10 +72,10 @@ Functionality
   ----
 
   This section contains all doxygen tags taken from 
-  http://www.stack.nl/~dimitri/doxygen/commands.html. If a tag is
+  https://www.doxygen.nl/manual/commands.html. If a tag is
   marked as 'ignored', then the tag is ignored, but the text is copied
   to the destination documentation. 'Not implemented' means that the
-  tag with it's contents is stripped out of the output.
+  tag with its contents is stripped out of the output.
 
     Doxygen tags:
     

Doc/Devel/scanner.html

@@ -19,7 +19,7 @@ January 11, 2007<br>
 
 This document describes functions that can be used to tokenize C/C++
 input text.  These functions are relatively low-level and are meant to
-be used in the implementation of scanners that can be plugged into yacc or used for
+be used in the implementation of scanners that can be plugged into bison or used for
 other purposes.  For instance, the preprocessor uses these functions to evaluate and test 
 constant expressions.  
 
@@ -103,7 +103,7 @@ Skips to the end of the current line.   The text skipped can be obtained using <
 </blockquote>
 
 <p>
-<b><tt>void Scanner_skip_balanced(Scanner *s, int startchar, int endchar)</tt></b>
+<b><tt>int Scanner_skip_balanced(Scanner *s, int startchar, int endchar)</tt></b>
 <blockquote>
 Skips to the end of a block of text denoted by starting and ending characters.  For example, <tt>{</tt> and <tt>}</tt>.  The
 function is smart about how it skips text.  String literals and comments are ignored.   The function also is aware of nesting.  The
@@ -187,7 +187,6 @@ SWIG_TOKEN_RPAREN            )
 SWIG_TOKEN_SEMI              ; 
 SWIG_TOKEN_COMMA             , 
 SWIG_TOKEN_STAR              * 
-SWIG_TOKEN_TIMES             *
 SWIG_TOKEN_LBRACE            { 
 SWIG_TOKEN_RBRACE            } 
 SWIG_TOKEN_EQUAL             = 
@@ -204,16 +203,15 @@ SWIG_TOKEN_LESSTHAN          &lt;
 SWIG_TOKEN_GREATERTHAN       &gt; 
 SWIG_TOKEN_LTEQUAL           &lt;= 
 SWIG_TOKEN_GTEQUAL           &gt;= 
+SWIG_TOKEN_LTEQUALGT         &lt;=&gt;
 SWIG_TOKEN_NOT               ~ 
 SWIG_TOKEN_LNOT              ! 
 SWIG_TOKEN_LBRACKET          [ 
 SWIG_TOKEN_RBRACKET          ] 
 SWIG_TOKEN_SLASH             / 
-SWIG_TOKEN_DIVIDE            /
 SWIG_TOKEN_BACKSLASH         \ 
 SWIG_TOKEN_POUND             # 
 SWIG_TOKEN_PERCENT           % 
-SWIG_TOKEN_MODULO            %
 SWIG_TOKEN_COLON             : 
 SWIG_TOKEN_DCOLON            :: 
 SWIG_TOKEN_DCOLONSTAR        ::*
@@ -237,21 +235,28 @@ SWIG_TOKEN_ARROWSTAR         -&gt;*
 SWIG_TOKEN_PERIOD            . 
 SWIG_TOKEN_AT                @ 
 SWIG_TOKEN_DOLLAR            $ 
+SWIG_TOKEN_ELLIPSIS          ...
+SWIG_TOKEN_LLBRACKET         [[
+SWIG_TOKEN_RRBRACKET         ]]
 SWIG_TOKEN_ENDLINE           Literal newline
 SWIG_TOKEN_ID                identifier 
 SWIG_TOKEN_FLOAT             Floating point with F suffix (e.g., 3.1415F)
 SWIG_TOKEN_DOUBLE            Floating point (e.g., 3.1415 )
+SWIG_TOKEN_LONGDOUBLE        Floating point with L suffix (e.g., 3.1415L)
 SWIG_TOKEN_INT               Integer (e.g., 314)
 SWIG_TOKEN_UINT              Unsigned integer (e.g., 314U)
 SWIG_TOKEN_LONG              Long integer (e.g., 314L) 
 SWIG_TOKEN_ULONG             Unsigned long integer (e.g., 314UL)
 SWIG_TOKEN_LONGLONG          Long long integer (e.g., 314LL )
 SWIG_TOKEN_ULONGLONG         Unsigned long long integer (e.g., 314ULL) 
+SWIG_TOKEN_BOOL              Boolean literal (true or false)
 SWIG_TOKEN_CHAR              Character literal in single quotes ('c')
+SWIG_TOKEN_WCHAR             Wide character literal (L'c')
 SWIG_TOKEN_STRING            String literal in double quotes ("str")
 SWIG_TOKEN_RSTRING           Reverse quote string (`str`)
 SWIG_TOKEN_CODEBLOCK         SWIG code literal block %{ ... %}
 SWIG_TOKEN_COMMENT           C or C++ comment  (// or /* ... */)
+SWIG_TOKEN_WSTRING           Wide string literal (L"str")
 SWIG_TOKEN_ILLEGAL           Illegal character
 </pre>
 </blockquote>
@@ -259,9 +264,6 @@ SWIG_TOKEN_ILLEGAL           Illegal character
 <b>Notes</b>
 
 <ul>
-<li>When more than one token code exist for the same token text, those codes are identical (e.g., <tt>SWIG_TOKEN_STAR</tt> and <tt>SWIG_TOKEN_TIMES</tt>).
-
-<p>
 <li>
 String literals are returned in their exact representation in which escape codes (if any) have been interpreted.
 
@@ -276,7 +278,7 @@ add extra checking on the returned text.
 <p>
 <li>The maximum token integer value is found in the constant <tt>SWIG_MAXTOKENS</tt>.   This can be used if you wanted to create 
 an array or table for the purposes of remapping tokens to a different set of codes. For instance, if you are
-using these functions to write a yacc-compatible lexer.
+using these functions to write a bison-compatible lexer.
 </ul>
 
 </body>

Doc/Devel/tree.html

@@ -183,8 +183,8 @@ this function merely records that those attributes did not exist in the original
 <b><tt>void Swig_require(const char *namespace, Node *n, ...)</tt></b>
 
 <blockquote>
-This function is similar to <tt>Swig_save()</tt> except that adds additional attribute checking. There are different interpretations
-of the attribute names.  A name of "attr" merely requests that the function check for the presence of an attribute.  If the attribute is missing, SWIG will exit with a failed assertion.   An attribute name of "?attr" specifies that the attribute "attr" is optional and
+This function is similar to <tt>Swig_save()</tt> except that it performs additional attribute checking. There are different interpretations
+of the attribute names.  A name of "attr" merely requests that the function check for the presence of an attribute.  If the attribute is missing, SWIG will exit with a fatal error.   An attribute name of "?attr" specifies that the attribute "attr" is optional and
 that its old value must be saved (if any).   An attribute name of "*attr" specifies that the attribute is required and that
 its value must be saved.   The saving of attributes is performed in the same manner as with <tt>Swig_save()</tt>. Here is an example:
 
@@ -241,17 +241,17 @@ This function is called by the <tt>-debug-tags</tt> option to SWIG.
 
 <pre>
 % swig -debug-tags -python example.i
- . top (:1)
- . top . include (/Users/beazley/Projects/share/swig/1.3.31/swig.swg:0)
- . top . include . include (/Users/beazley/Projects/share/swig/1.3.31/swigwarnings.swg:0)
- . top . include . include . include (/Users/beazley/Projects/share/swig/1.3.31/swigwarn.swg:0)
+:1:  . top
+:1:  . top . include
+/usr/share/swig/swig.swg:320:  . top . include . include
+/usr/share/swig/swigwarnings.swg:39:  . top . include . include . include
 ...
 ...
- . top . include (example.i:0)
- . top . include . module (example.i:2)
- . top . include . insert (example.i:7)
- . top . include . cdecl (example.i:5)
- . top . include . cdecl (example.i:6)
+:4:  . top . include
+example.i:2:  . top . include . module
+example.i:7:  . top . include . insert
+example.i:5:  . top . include . cdecl
+example.i:6:  . top . include . cdecl
 </pre>
 
 Since many language modules include hundreds of typemaps and other information, the output of this can be significantly more complicated than you might expect.

Doc/Manual/Android.html

@@ -6,7 +6,7 @@
 <meta http-equiv="content-type" content="text/html; charset=UTF-8">
 </head>
 <body bgcolor="#FFFFFF">
-<H1><a name="Android">21 SWIG and Android</a></H1>
+<H1><a name="Android">22 SWIG and Android</a></H1>
 <!-- INDEX -->
 <div class="sectiontoc">
 <ul>
@@ -31,7 +31,7 @@ This chapter describes SWIG's support of Android.
 
 
 
-<H2><a name="Android_overview">21.1 Overview</a></H2>
+<H2><a name="Android_overview">22.1 Overview</a></H2>
 
 
 <p>
@@ -41,10 +41,10 @@ Everything in the <a href="Java.html#Java">Java chapter</a> applies to generatin
 This chapter contains a few Android specific notes and examples.
 </p>
 
-<H2><a name="Android_examples">21.2 Android examples</a></H2>
+<H2><a name="Android_examples">22.2 Android examples</a></H2>
 
 
-<H3><a name="Android_examples_intro">21.2.1 Examples introduction</a></H3>
+<H3><a name="Android_examples_intro">22.2.1 Examples introduction</a></H3>
 
 
 <p>
@@ -77,7 +77,7 @@ $ android list targets
 The following examples are shipped with SWIG under the Examples/android directory and include a Makefile to build and install each example.
 </p>
 
-<H3><a name="Android_example_simple">21.2.2 Simple C example</a></H3>
+<H3><a name="Android_example_simple">22.2.2 Simple C example</a></H3>
 
 
 <p>
@@ -399,7 +399,7 @@ Run the app again and this time you will see the output pictured below, showing
 <center><img src="android-simple.png" alt="Android screenshot of SwigSimple example"></center>
 
 
-<H3><a name="Android_example_class">21.2.3 C++ class example</a></H3>
+<H3><a name="Android_example_class">22.2.3 C++ class example</a></H3>
 
 
 <p>
@@ -747,7 +747,7 @@ Run the app to see the result of calling the C++ code from Java:
 
 <center><img src="android-class.png" alt="Android screenshot of SwigClass example"></center>
 
-<H3><a name="Android_examples_other">21.2.4 Other examples</a></H3>
+<H3><a name="Android_examples_other">22.2.4 Other examples</a></H3>
 
 
 <p>
@@ -759,7 +759,7 @@ Note that the 'extend' example is demonstrates the directors feature.
 Normally C++ exception handling and the STL is not available by default in the version of g++ shipped with Android, but this example turns these features on as described in the next section.
 </p>
 
-<H2><a name="Android_stl">21.3 C++ STL</a></H2>
+<H2><a name="Android_stl">22.3 C++ STL</a></H2>
 
 
 <p>

Doc/Manual/Arguments.html

@@ -7,7 +7,7 @@
 </head>
 
 <body bgcolor="#ffffff">
-<H1><a name="Arguments">12 Argument Handling</a></H1>
+<H1><a name="Arguments">13 Argument Handling</a></H1>
 <!-- INDEX -->
 <div class="sectiontoc">
 <ul>
@@ -43,7 +43,7 @@ return multiple values through the arguments of a function.  This chapter
 describes some of the techniques for doing this.
 </p>
 
-<H2><a name="Arguments_nn2">12.1 The typemaps.i library</a></H2>
+<H2><a name="Arguments_nn2">13.1 The typemaps.i library</a></H2>
 
 
 <p>
@@ -51,7 +51,7 @@ This section describes the <tt>typemaps.i</tt> library file--commonly used to
 change certain properties of argument conversion.
 </p>
 
-<H3><a name="Arguments_nn3">12.1.1 Introduction</a></H3>
+<H3><a name="Arguments_nn3">13.1.1 Introduction</a></H3>
 
 
 <p>
@@ -195,7 +195,7 @@ else.   To clear a typemap, the <tt>%clear</tt> directive should be used.  For e
 </pre>
 </div>
 
-<H3><a name="Arguments_nn4">12.1.2 Input parameters</a></H3>
+<H3><a name="Arguments_nn4">13.1.2 Input parameters</a></H3>
 
 
 <p>
@@ -248,7 +248,7 @@ When the function is used in the scripting language interpreter, it will work li
 result = add(3, 4)
 </pre></div>
 
-<H3><a name="Arguments_nn5">12.1.3 Output parameters</a></H3>
+<H3><a name="Arguments_nn5">13.1.3 Output parameters</a></H3>
 
 
 <p>
@@ -315,7 +315,7 @@ iresult, dresult = foo(3.5, 2)
 </pre>
 </div>
 
-<H3><a name="Arguments_nn6">12.1.4 Input/Output parameters</a></H3>
+<H3><a name="Arguments_nn6">13.1.4 Input/Output parameters</a></H3>
 
 
 <p>
@@ -375,12 +375,7 @@ Therefore, the <tt>INOUT</tt> rule returns the modified value as a new object
 rather than directly overwriting the value of the original input object.
 </p>
 
-<p>
-<b>Compatibility note :</b> The <tt>INOUT</tt> rule used to be known as <tt>BOTH</tt> in earlier versions of
-SWIG.  Backwards compatibility is preserved, but deprecated.
-</p>
-
-<H3><a name="Arguments_nn7">12.1.5 Using different names</a></H3>
+<H3><a name="Arguments_nn7">13.1.5 Using different names</a></H3>
 
 
 <p>
@@ -414,7 +409,7 @@ Typemap declarations are lexically scoped so a typemap takes effect from the poi
 file or a matching <tt>%clear</tt> declaration.
 </p>
 
-<H2><a name="Arguments_nn8">12.2 Applying constraints to input values</a></H2>
+<H2><a name="Arguments_nn8">13.2 Applying constraints to input values</a></H2>
 
 
 <p>
@@ -424,7 +419,7 @@ insure that a value is positive, or that a pointer is non-NULL. This
 can be accomplished including the <tt>constraints.i</tt> library file.
 </p>
 
-<H3><a name="Arguments_nn9">12.2.1 Simple constraint example</a></H3>
+<H3><a name="Arguments_nn9">13.2.1 Simple constraint example</a></H3>
 
 
 <p>
@@ -440,7 +435,7 @@ double exp(double x);
 double log(double POSITIVE);         // Allow only positive values
 double sqrt(double NONNEGATIVE);     // Non-negative values only
 double inv(double NONZERO);          // Non-zero values
-void   free(void *NONNULL);          // Non-NULL pointers only
+int    fclose(FILE *NONNULL);        // Non-NULL pointers only
 
 </pre></div>
 
@@ -450,7 +445,7 @@ the arguments violate the constraint condition, a scripting language
 exception will be raised. As a result, it is possible to catch bad
 values, prevent mysterious program crashes and so on.</p>
 
-<H3><a name="Arguments_nn10">12.2.2 Constraint methods</a></H3>
+<H3><a name="Arguments_nn10">13.2.2 Constraint methods</a></H3>
 
 
 <p>
@@ -466,7 +461,7 @@ NONNULL                      Non-NULL pointer (pointers only).
 
 </pre></div>
 
-<H3><a name="Arguments_nn11">12.2.3 Applying constraints to new datatypes</a></H3>
+<H3><a name="Arguments_nn11">13.2.3 Applying constraints to new datatypes</a></H3>
 
 
 <p>

Doc/Manual/CCache.html

@@ -7,7 +7,7 @@
 </head>
 
 <body bgcolor="#ffffff">
-<H1><a name="CCache">20 Using SWIG with ccache - ccache-swig(1) manpage</a></H1>
+<H1><a name="CCache">21 Using SWIG with ccache - ccache-swig(1) manpage</a></H1>
 <!-- INDEX -->
 <div class="sectiontoc">
 <ul>
@@ -35,7 +35,7 @@
 
 
 <p>
-<H2><a name="CCache_nn2">20.1 NAME</a></H2>
+<H2><a name="CCache_nn2">21.1 NAME</a></H2>
 
 
 <p>
@@ -43,7 +43,7 @@
 ccache-swig - a fast compiler cache
 
 <p>
-<H2><a name="CCache_nn3">20.2 SYNOPSIS</a></H2>
+<H2><a name="CCache_nn3">21.2 SYNOPSIS</a></H2>
 
 
 <p>
@@ -53,7 +53,7 @@ ccache-swig &lt;compiler&gt; [COMPILER OPTIONS]
 <p>
 &lt;compiler&gt; [COMPILER OPTIONS]
 <p>
-<H2><a name="CCache_nn4">20.3 DESCRIPTION</a></H2>
+<H2><a name="CCache_nn4">21.3 DESCRIPTION</a></H2>
 
 
 <p>
@@ -62,7 +62,7 @@ by caching previous compiles and detecting when the same compile is
 being done again. ccache-swig is ccache plus support for SWIG. ccache
 and ccache-swig are used interchangeably in this document.
 <p>
-<H2><a name="CCache_nn5">20.4 OPTIONS SUMMARY</a></H2>
+<H2><a name="CCache_nn5">21.4 OPTIONS SUMMARY</a></H2>
 
 
 <p>
@@ -82,7 +82,7 @@ Here is a summary of the options to ccache-swig.
 </pre>
 
 <p>
-<H2><a name="CCache_nn6">20.5 OPTIONS</a></H2>
+<H2><a name="CCache_nn6">21.5 OPTIONS</a></H2>
 
 
 <p>
@@ -124,7 +124,7 @@ rounded down to the nearest multiple of 16 kilobytes.
 <p>
 </dl>
 <p>
-<H2><a name="CCache_nn7">20.6 INSTALLATION</a></H2>
+<H2><a name="CCache_nn7">21.6 INSTALLATION</a></H2>
 
 
 <p>
@@ -156,7 +156,7 @@ This will work as long as /usr/local/bin comes before the path to gcc
 Note! Do not use a hard link, use a symbolic link. A hardlink will
 cause "interesting" problems.
 <p>
-<H2><a name="CCache_nn8">20.7 EXTRA OPTIONS</a></H2>
+<H2><a name="CCache_nn8">21.7 EXTRA OPTIONS</a></H2>
 
 
 <p>
@@ -176,7 +176,7 @@ file). By using --ccache-skip you can force an option to not be
 treated as an input file name and instead be passed along to the
 compiler as a command line option.
 <p>
-<H2><a name="CCache_nn9">20.8 ENVIRONMENT VARIABLES</a></H2>
+<H2><a name="CCache_nn9">21.8 ENVIRONMENT VARIABLES</a></H2>
 
 
 <p>
@@ -315,7 +315,7 @@ the use of '#pragma SWIG'.
 <p>
 </dl>
 <p>
-<H2><a name="CCache_nn10">20.9 CACHE SIZE MANAGEMENT</a></H2>
+<H2><a name="CCache_nn10">21.9 CACHE SIZE MANAGEMENT</a></H2>
 
 
 <p>
@@ -328,7 +328,7 @@ When these limits are reached ccache will reduce the cache to 20%
 below the numbers you specified in order to avoid doing the cache
 clean operation too often.
 <p>
-<H2><a name="CCache_nn11">20.10 CACHE COMPRESSION</a></H2>
+<H2><a name="CCache_nn11">21.10 CACHE COMPRESSION</a></H2>
 
 
 <p>
@@ -339,7 +339,7 @@ performance slowdown, it significantly increases the number of files
 that fit in the cache. You can turn off compression setting the
 CCACHE_NOCOMPRESS environment variable.
 <p>
-<H2><a name="CCache_nn12">20.11 HOW IT WORKS</a></H2>
+<H2><a name="CCache_nn12">21.11 HOW IT WORKS</a></H2>
 
 
 <p>
@@ -364,7 +364,7 @@ compiler output that you would get without the cache. If you ever
 discover a case where ccache changes the output of your compiler then
 please let me know.
 <p>
-<H2><a name="CCache_nn13">20.12 USING CCACHE WITH DISTCC</a></H2>
+<H2><a name="CCache_nn13">21.12 USING CCACHE WITH DISTCC</a></H2>
 
 
 <p>
@@ -378,7 +378,7 @@ option. You just need to set the environment variable CCACHE_PREFIX to
 'distcc' and ccache will prefix the command line used with the
 compiler with the command 'distcc'.
 <p>
-<H2><a name="CCache_nn14">20.13 SHARING A CACHE</a></H2>
+<H2><a name="CCache_nn14">21.13 SHARING A CACHE</a></H2>
 
 
 <p>
@@ -407,7 +407,7 @@ following conditions need to be met:
   versions of ccache that do not support compression.
 </ul>
 <p>
-<H2><a name="CCache_nn15">20.14 HISTORY</a></H2>
+<H2><a name="CCache_nn15">21.14 HISTORY</a></H2>
 
 
 <p>
@@ -423,7 +423,7 @@ I wrote ccache because I wanted to get a bit more speed out of a
 compiler cache and I wanted to remove some of the limitations of the
 shell-script version.
 <p>
-<H2><a name="CCache_nn16">20.15 DIFFERENCES FROM COMPILERCACHE</a></H2>
+<H2><a name="CCache_nn16">21.15 DIFFERENCES FROM COMPILERCACHE</a></H2>
 
 
 <p>
@@ -441,7 +441,7 @@ are:
 <li> ccache avoids a double call to cpp on a cache miss
 </ul>
 <p>
-<H2><a name="CCache_nn17">20.16 CREDITS</a></H2>
+<H2><a name="CCache_nn17">21.16 CREDITS</a></H2>
 
 
 <p>
@@ -453,7 +453,7 @@ Thanks to the following people for their contributions to ccache
  <li> Paul Russell for many suggestions and the debian packaging
 </ul>
 <p>
-<H2><a name="CCache_nn18">20.17 AUTHOR</a></H2>
+<H2><a name="CCache_nn18">21.17 AUTHOR</a></H2>
 
 
 <p>
@@ -463,7 +463,7 @@ ccache was adapted to create ccache-swig for use with SWIG by William Fulton.
 <p>
 If you wish to report a problem or make a suggestion then please email
 the SWIG developers on the swig-devel mailing list, see
-<a href="http://www.swig.org/mail.html">http://www.swig.org/mail.html</a>
+<a href="https://www.swig.org/mail.html">https://www.swig.org/mail.html</a>
 <p>
 ccache is released under the GNU General Public License version 2 or
 later. Please see the file COPYING for license details.

Doc/Manual/CPlusPlus11.html

@@ -15,6 +15,11 @@
 <li><a href="#CPlusPlus11_core_language_changes">Core language changes</a>
 <ul>
 <li><a href="#CPlusPlus11_rvalue_reference_and_move_semantics">Rvalue reference and move semantics</a>
+<ul>
+<li><a href="#CPlusPlus11_rvalue_reference_inputs">Rvalue reference inputs</a>
+<li><a href="#CPlusPlus11_rvalue_reference_outputs">Rvalue reference outputs</a>
+<li><a href="#CPlusPlus11_move_only">Movable and move-only types by value</a>
+</ul>
 <li><a href="#CPlusPlus11_generalized_constant_expressions">Generalized constant expressions</a>
 <li><a href="#CPlusPlus11_extern_template">Extern template</a>
 <li><a href="#CPlusPlus11_initializer_lists">Initializer lists</a>
@@ -68,8 +73,7 @@
 
 
 <p>This chapter gives you a brief overview about the SWIG
-implementation of the C++11 standard. This part of SWIG is still a work in
-progress. 
+implementation of the C++11 standard.
 </p>
 <p>SWIG supports the new C++ syntax changes with some minor limitations
 in some areas such as decltype expressions and variadic templates. Wrappers for the
@@ -95,6 +99,7 @@ class MyClass {
 ...
   std::vector&lt;int&gt; numbers;
 public:
+  MyClass() : numbers() {}
   MyClass(MyClass &amp;&amp;other) : numbers(std::move(other.numbers)) {}
   MyClass &amp; operator=(MyClass &amp;&amp;other) {
     numbers = std::move(other.numbers);
@@ -104,8 +109,8 @@ public:
 </pre></div>
 
 <p>
-Rvalue references are designed for C++ temporaries and so are not very useful when used from non-C++ target languages.
-Generally you would just ignore them via <tt>%ignore</tt> before parsing the class.
+Rvalue references are designed for C++ temporaries and are not particularly useful when used from non-C++ target languages.
+One option is to just ignore them via <tt>%ignore</tt>.
 For example, ignore the move constructor:
 </p>
 
@@ -113,8 +118,49 @@ For example, ignore the move constructor:
 %ignore MyClass::MyClass(MyClass &amp;&amp;);
 </pre></div>
 
+<H4><a name="CPlusPlus11_rvalue_reference_inputs">7.2.1.1 Rvalue reference inputs</a></H4>
+
+
 <p>
-The plan is to ignore move constructors by default in a future version of SWIG. Note that both normal assignment operators as well as move assignment operators are ignored by default in most target languages with the following warning:
+Rvalue reference parameters are useful as input parameters in C++ for implementing move semantics, such as,
+in the move constructor and move assignment operator.
+This type of usage can be useful from target languages too to avoid copying large objects.
+</p>
+
+<p>
+If you do wrap a function/contructor with an rvalue reference parameter and pass a proxy class to it, SWIG will assume that after the call, the rvalue reference parameter object will have been 'moved'.
+The proxy class passed as the rvalue reference, will own the underlying C++ object up until it is used as an rvalue reference parameter.
+Afterwards, the proxy class will have the underlying C++ pointer set to the nullptr so that the proxy class instance cannot be used again and the underlying (moved from) C++ object will be deleted after the function/constructor call has returned.
+</p>
+
+<p>
+In this way, the SWIG proxy class works much like an exclusively owned smart pointer (think of <tt>std::unique_ptr</tt>), passing ownership to the called C++ function/constructor.
+Let's consider an example in Java using the wrapped proxy class from above:
+</p>
+
+<div class="targetlang"><pre>
+MyClass mc = new MyClass();
+MyClass mc1 = new MyClass(mc); // move constructor
+MyClass mc2 = new MyClass(mc); // move constructor fails
+</pre></div>
+
+<p>
+The second call to the move constructor will fail as the <tt>mc</tt> proxy instance has been moved.
+Each target language handles the moved proxy class slightly differently when attempting to move it again, but typically you'll get an exception such as in Java:
+</p>
+
+<div class="shell">
+<pre>
+Exception in thread "main" java.lang.RuntimeException: Cannot release ownership as memory is not owned
+        at MyClass.swigRelease(MyClass.java:27)
+        at MyClass.&lt;init&gt;(MyClass.java:55)
+        at runme.main(runme.java:18)
+</pre>
+</div>
+
+
+<p>
+Note that both normal copy assignment operators as well as move assignment operators are ignored by default in the target languages with the following warning:
 </p>
 
 <div class="shell">
@@ -123,6 +169,332 @@ example.i:18: Warning 503: Can't wrap 'operator =' unless renamed to a valid ide
 </pre>
 </div>
 
+<p>
+Using a <tt>%rename</tt> will remove the warning and also makes the move assignment operator available from the target language:
+</p>
+<div class="code"><pre>
+%rename(MoveAssign) MyClass::operator=(MyClass &amp;&amp;);
+</pre></div>
+
+<p>
+You can then use it, but like the move constructor example above, you cannot use
+a proxy class once it has already been moved:
+</p>
+
+<div class="targetlang"><pre>
+MyClass mc = new MyClass();
+MyClass mc2 = mc.MoveAssign(mc);
+MyClass mc3 = mc.MoveAssign(mc); // Use of mc again will fail
+</pre></div>
+
+<p>
+It is of course perfectly possible in C++ for a function/constructor to not move an object passed to it in an rvalue reference parameter. The assumption that SWIG makes would then not hold and customisation of the appropriate input typemaps would be required.
+For scripting languages, this would be for the 'in' typemap and for the non-scripting languages additional typemaps such as the 'javain' typemap, which is used to set the memory ownership of the underlying C++ object for Java, would also need copying and modifying appropriately.
+</p>
+
+<p>
+<b>Compatibility note:</b>
+SWIG-4.1.0 changed the way that rvalue reference parameters were handled and implemented typemaps assuming that the
+proxy class owns the underlying C++ object and transfers ownership of the object when a function/constructor with an rvalue reference parameter is called.
+</p>
+
+<H4><a name="CPlusPlus11_rvalue_reference_outputs">7.2.1.2 Rvalue reference outputs</a></H4>
+
+
+<p>
+While rvalue reference parameter inputs are not uncommon in C++ and can be usefully utilised from target languages, this cannot be said for rvalue reference outputs.
+Firstly, it is quite unusual in C++ to have functions that return an rvalue reference.
+Secondly, these cases are nigh on impossible to use from a target language.
+The main problem is these references are for C++ compiler temporaries used on the stack and the target languages use objects on the heap
+and the concept of compiler temporary objects doesn't make sense from another language.
+</p>
+
+<p>
+Using <tt>MyClass</tt> from earlier and this C++ code:
+</p>
+
+<div class="code"><pre>
+void use(MyClass &amp;&amp;mc);
+MyClass &amp;&amp; get1();
+MyClass &amp; get2();
+</pre></div>
+
+<p>
+SWIG wraps the <tt>get1</tt> and <tt>get2</tt> functions more or less identically.
+The returned references are converted into pointers that are not owned by the target language.
+It means that the following perfectly valid C++ has no equivalent in any of the target languages:
+</p>
+
+<div class="code"><pre>
+use(get1());
+use(std::move(get2()));
+</pre></div>
+
+<p>
+An attempt to call the equivalent <tt>use(get1())</tt> from one of the target languages will result in the ownership failure mentioned in the previous section as the object being passed to the <tt>use</tt> function is not owned by the proxy class.
+In order to own the object, it would need to be cloned for the object to move from the stack to the heap, for which an appropriate clone function would be required, but may not even be available.
+Note that a move constructor or copy constructor may slice the object when inheritance is involved.
+Alternatively, customising the input rvalue reference typemap, as mentioned in the previous section, could remove the ownership requirement.
+Another alternative would be to modify the output rvalue reference typemap to always clone the rvalue reference object.
+Fortunately you're highly unlikely to have to solve any of these issues!
+</p>
+
+<H4><a name="CPlusPlus11_move_only">7.2.1.3 Movable and move-only types by value</a></H4>
+
+
+<p>
+SWIG has traditionally relied on wrapped C++ types to be copy constructible or copy assignable, either via an explicit or implicit copy constructor and copy assignment operator.
+Prior to C++11, a function could not return nor take a type by value that was not copyable.
+In C++11 this is no longer the case. A type can also be movable if it has has a move constructor and a move assignment operator.
+A move-only type is movable but not copyable; it has both the copy constructor and copy assignment operator deleted.
+Movable types can appear in function signatures for passing 'by value' and in C++11 the object can then be moved rather than copied.
+</p>
+
+<p>
+SWIG has support for both copyable and/or movable types.
+Support for move semantics is quite seamless when returning by value from a function.
+Support for move semantics is less so and may require some customisation when passing by value to a function.
+First let's consider returning by value from a function.
+</p>
+
+<p>
+The support for function return values is generically implemented in the "out" <tt>SWIGTYPE</tt> typemap which supports any type, including copyable, movable and move-only types.
+The typemap code is very simple and written so that the compiler will call the move constructor if possible,
+otherwise the copy constructor:
+</p>
+
+<div class="code"><pre>
+%typemap(out) SWIGTYPE %{
+  $result = new $1_ltype($1);
+%}
+</pre></div>
+
+<p>
+The above typemap is for C# and when used to wrap a move-only type such as:
+</p>
+
+<div class="code"><pre>
+struct MoveOnly {
+  int  val;
+  MoveOnly(): val(0)  {}
+
+  MoveOnly(const MoveOnly &amp;) = delete;
+  MoveOnly(MoveOnly &amp;&amp;) = default;
+
+  MoveOnly &amp; operator=(const MoveOnly &amp;) = delete;
+  MoveOnly &amp; operator=(MoveOnly &amp;&amp;) = default;
+
+  static MoveOnly create() { return MoveOnly(); }
+  static void take(MoveOnly mo);
+};
+</pre></div>
+
+<p>
+will generate wrapper code for the <tt>create</tt> factory method:
+</p>
+
+<div class="code"><pre>
+SWIGEXPORT void * SWIGSTDCALL CSharp_MoveOnly_create() {
+  void * jresult ;
+  SwigValueWrapper&lt; MoveOnly &gt; result;
+
+  result = MoveOnly::create();
+  jresult = new MoveOnly(result);
+  return jresult;
+}
+</pre></div>
+
+<p>
+<tt>SwigValueWrapper</tt> is covered in <a href="SWIGPlus.html#SWIGPlus_nn19">Pass and return by value</a>.
+Note that the generated code could be optimised further using the <a href="Typemaps.html#Typemaps_optimal">"optimal" attribute</a>
+in the "out" typemap, so if the above typemap is customised as follows (note that this is C# specific):
+</p>
+
+<div class="code"><pre>
+%typemap(out, optimal="1") MoveOnly %{
+  $result = new $1_ltype($1);
+%}
+</pre></div>
+
+<p>
+then the generated code will result in the object being optimally moved:
+</p>
+
+<div class="code"><pre>
+SWIGEXPORT void * SWIGSTDCALL CSharp_MoveOnly_create() {
+  void * jresult ;
+  jresult = new MoveOnly(MoveOnly::create());
+  return jresult;
+}
+</pre></div>
+
+<p>
+Now let's consider passing by value.
+We'll consider three cases; namely types that are:
+</p>
+
+<ol>
+  <li> Copyable and not movable - <tt>CopyOnly</tt>.</li>
+  <li> Copyable and movable - <tt>MovableCopyable</tt>.</li>
+  <li> Movable and not copyable - <tt>MoveOnly</tt>.</li>
+</ol>
+
+<p>
+and for clarification, define these two additional types as follows:
+</p>
+
+<div class="code"><pre>
+struct CopyOnly {
+  int  val;
+  CopyOnly(): val(0)  {}
+
+  CopyOnly(const CopyOnly &amp;) = default;
+  CopyOnly &amp; operator=(const CopyOnly &amp;) = default;
+
+  static CopyOnly create() { return CopyOnly(); }
+  static void take(CopyOnly co);
+};
+
+struct MovableCopyable {
+  int  val;
+  MovableCopyable(): val(0)  {}
+
+  MovableCopyable(const MovableCopyable &amp;) = default;
+  MovableCopyable(MovableCopyable &amp;&amp;) = default;
+  MovableCopyable &amp; operator=(const MovableCopyable &amp;) = default;
+  MovableCopyable &amp; operator=(MovableCopyable &amp;&amp;) = default;
+
+  static MovableCopyable create() { return MovableCopyable(); }
+  static void take(MovableCopyable mc);
+};
+</pre></div>
+
+<p>
+The generated code is shown below for <tt>CopyOnly::take</tt> (with additional comments for when constructors and assignment operators are called).
+While the code shown is C# specific, the generated constructor and/or assignment operator calls are ultimately the same for all target languages.
+</p>
+
+<div class="code"><pre>
+SWIGEXPORT void SWIGSTDCALL CSharp_CopyOnly_take(void * jarg1) {
+  CopyOnly arg1 ; // (a) Default constructor
+  CopyOnly *argp1 ;
+  
+  argp1 = (CopyOnly *)jarg1; 
+  if (!argp1) {
+    SWIG_CSharpSetPendingExceptionArgument(SWIG_CSharpArgumentNullException, "Attempt to dereference null CopyOnly", 0);
+    return ;
+  }
+  arg1 = *argp1; // (b) Copy assignment
+  CopyOnly::take(SWIG_STD_MOVE(arg1)); // (c) Copy constructor
+}
+</pre></div>
+
+<p>
+Note that <tt>SWIG_STD_MOVE</tt> is a macro defined as shown below to use <tt>std::move</tt> which is only available from C++11 onwards:
+</p>
+
+<div class="code"><pre>
+#if __cplusplus &gt;=201103L
+# define SWIG_STD_MOVE(OBJ) std::move(OBJ)
+#else
+# define SWIG_STD_MOVE(OBJ) OBJ
+#endif
+</pre></div>
+
+<p>
+Also note: <i>(c) Copy constructor</i>.
+Yes, when passing by value the copy constructor is called for all versions of C++, even C++11 and later even though std::move is specified.
+It's a C++ language feature for types that don't have move semantics!
+</p>
+
+<p>
+The generated code for <tt>MovableCopyable::take</tt> is the same as for <tt>CopyOnly::take</tt>, however, the C++ compiler will choose the move constructor this time where commented <i>(c) Move constructor</i>:
+</p>
+
+<div class="code"><pre>
+SWIGEXPORT void SWIGSTDCALL CSharp_MovableCopyable_take(void * jarg1) {
+  MovableCopyable arg1 ; // (a) Default constructor
+  MovableCopyable *argp1 ;
+  
+  argp1 = (MovableCopyable *)jarg1; 
+  if (!argp1) {
+    SWIG_CSharpSetPendingExceptionArgument(SWIG_CSharpArgumentNullException, "Attempt to dereference null MovableCopyable", 0);
+    return ;
+  }
+  arg1 = *argp1; // (b) Copy assignment
+  MovableCopyable::take(SWIG_STD_MOVE(arg1)); // (c) Move constructor
+}
+</pre></div>
+
+<p>
+There are two optimisation opportunities available.
+</p>
+<ol>
+  <li> Remove the default constructor call with the <tt>%feature("valuewrapper")</tt> covered in <a href="SWIGPlus.html#SWIGPlus_nn19">Pass and return by value</a> and replace it with <tt>SwigValueWrapper</tt>.
+  </li>
+  <li> Apply the SWIGTYPE MOVE typemaps which are designed specifically to implement full move semantics when passing parameters by value.
+    They replace the copy assignment with a call to <tt>SwigValueWrapper::reset</tt>, which works much like <tt>std::unique_ptr::reset</tt>.
+    These typemaps could alternatively have replaced the copy assignment with a move assignment, but this is not maximally optimal.
+  </li>
+</ol>
+<p>
+Simply add the following before the <tt>MovableCopyable::take</tt> method is parsed:
+</p>
+
+<div class="code"><pre>
+%valuewrapper MovableCopyable;
+%include &lt;swigmove.i&gt;
+%apply SWIGTYPE MOVE { MovableCopyable }
+</pre></div>
+
+<p>
+will result in this optimal code where just one move constructor is invoked:
+</p>
+
+<div class="code"><pre>
+SWIGEXPORT void SWIGSTDCALL CSharp_MovableCopyable_take(void * jarg1) {
+  SwigValueWrapper&lt; MovableCopyable &gt; arg1 ; // (a) No constructors invoked
+  MovableCopyable *argp1 ;
+  
+  argp1 = (MovableCopyable *)jarg1;
+  if (!argp1) {
+    SWIG_CSharpSetPendingExceptionArgument(SWIG_CSharpArgumentNullException, "Attempt to dereference null MovableCopyable", 0);
+    return ;
+  }
+  SwigValueWrapper&lt; MovableCopyable &gt;::reset(arg1, argp1);  // (b) No constructor or assignment operator invoked
+  MovableCopyable::take(SWIG_STD_MOVE(arg1)); // (c) Move constructor
+}
+</pre></div>
+
+<p>
+Note that <tt>SwigValueWrapper</tt> will call the destructor for the pointer passed to it in the <tt>reset</tt> function.
+This pointer is the underlying C++ object that the proxy class owns.
+The details aren't shown, but the 'csin' typemap also generates C# code to ensure that the proxy class releases ownership of the object.
+Please see the 'SWIGTYPE MOVE' typemaps in the swigmove.i file provided for each target language.
+Therefore full move semantics are implemented; ownership is moved from the proxy class into the C++ layer and the net effect
+is the same as using an <a href="#CPlusPlus11_rvalue_reference_inputs">rvalue reference parameter</a> discussed earlier.
+</p>
+
+<p>
+Lastly, let's consider the <tt>MoveOnly::take</tt> function defined earlier.
+By default the generated code fails to compile as <tt>MoveOnly</tt> does not have a copy assignment operator.
+SWIG is not designed to select a different typemap automatically for move-only types and the user
+must apply the SWIGTYPE MOVE typemaps to ensure that only move-only semantics are used.
+However, SWIG is able to automatically use <tt>%feature("valuewrapper")</tt> for move-only
+types so it is not necessary to explicitly use this feature.
+So in this move-only case, simply add the following before <tt>MoveOnly::take</tt> is parsed, which results in the same optimal code shown above for <tt>MovableCopyable</tt>:
+</p>
+
+<div class="code"><pre>
+%include &lt;swigmove.i&gt;
+%apply SWIGTYPE MOVE { MoveOnly }
+</pre></div>
+
+<p>
+<b>Compatibility note:</b>
+SWIG-4.1.0 introduced support for taking advantage of types with move semantics and making it possible to easily use move only types.
+</p>
+
 
 <H3><a name="CPlusPlus11_generalized_constant_expressions">7.2.2 Generalized constant expressions</a></H3>
 
@@ -144,14 +516,39 @@ When either of these is used from a target language, a runtime call is made to o
 <H3><a name="CPlusPlus11_extern_template">7.2.3 Extern template</a></H3>
 
 
-<p>SWIG correctly parses the keywords <tt>extern template</tt>.
+<p>SWIG correctly parses <tt>extern template</tt> explicit instantiation declarations.
 However, this template instantiation suppression in a translation unit has no relevance outside of the C++ compiler and so is not used by SWIG.
-SWIG only uses <tt>%template</tt> for instantiating and wrapping templates.</p>
+SWIG only uses <tt>%template</tt> for instantiating and wrapping templates.
+Consider the class template below:
+</p>
 
 <div class="code"><pre>
-template class std::vector&lt;int&gt;;        // C++03 explicit instantiation in C++
-extern template class std::vector&lt;int&gt;; // C++11 explicit instantiation suppression in C++
-%template(VectorInt) std::vector&lt;int&gt;;  // SWIG instantiation
+// Class template
+template class std::vector&lt;int&gt;;        // C++03 template explicit instantiation definition in C++
+extern template class std::vector&lt;int&gt;; // C++11 template explicit instantiation declaration (extern template)
+%template(VectorInt) std::vector&lt;int&gt;;  // SWIG template instantiation
+</pre></div>
+
+<p>
+The above result in warnings:
+</p>
+
+<div class="shell">
+<pre>
+example.i:2: Warning 320: Explicit template instantiation ignored.
+example.i:3: Warning 327: Extern template ignored.
+</pre>
+</div>
+
+<p>
+Similarly for the function template below:
+</p>
+
+<div class="code"><pre>
+// Function template
+template void Func&lt;int&gt;();              // C++03 template explicit instantiation definition in C++
+extern template void Func&lt;int&gt;();       // C++11 template explicit instantiation declaration (extern template)
+%template(FuncInt) Func&lt;int&gt;;           // SWIG template instantiation
 </pre></div>
 
 <H3><a name="CPlusPlus11_initializer_lists">7.2.4 Initializer lists</a></H3>
@@ -322,20 +719,57 @@ AltStruct var2{2, 4.3};   // calls the constructor
 <H3><a name="CPlusPlus11_type_inference">7.2.6 Type inference</a></H3>
 
 
-<p>SWIG supports <tt>decltype()</tt> with some limitations. Single
-variables are allowed, however, expressions are not supported yet. For
-example, the following code will work:</p>
+<p><tt>decltype()</tt> is supported with a few limitations.  SWIG can parse
+all uses, but can't deduce the type in every situation where a C++ compiler
+can.  The cases SWIG can deduce have expanded with time and hopefully will
+continue to.  For example, for the code</p>
 <div class="code"><pre>
 int i;
 decltype(i) j;
+decltype(i+j) k;
 </pre></div>
 
-<p>However, using an expression inside the decltype results in syntax error:</p>
+<p>SWIG is able to deduce that the variable <tt>i</tt> and the expression
+<tt>i+j</tt> both have type <tt>int</tt>.
+</p>
+
+<p>
+Using an expression for the decltype which SWIG can't handle results in a warning:</p>
 <div class="code"><pre>
-int i; int j;
-decltype(i+j) k;  // syntax error
+int foo(int);
+decltype(foo(0)) k;  // Warning 344: Unable to deduce decltype for 'foo(0)'.
 </pre></div>
 
+<p>
+This warning should be viewed as a prompt to add in a manual ignore of the variable/function as
+in most cases the generated code will not compile.
+For the example above, ignore the symbol that is declared using <tt>decltype</tt> and perhaps additionally
+suppress the warning as follows:
+</p>
+
+<div class="code"><pre>
+#pragma SWIG nowarn=SWIGWARN_CPP11_DECLTYPE
+%ignore k;
+</pre></div>
+
+<p>
+If an ignore is not acceptable, a workaround is to redefine the symbol with the actual type, for example:
+</p>
+
+<div class="code"><pre>
+int k; // define k with the actual type
+%ignore k; // ignore the real definition of k
+</pre></div>
+
+<p>You would typically put one of these workarounds in your interface file before
+using <tt>%include</tt> to get SWIG to parse the header which defines <tt>k</tt>.
+</p>
+
+<p>SWIG supports <tt>auto</tt> as a type specifier for variables (with the same limitations
+for actually deducing the type as for <tt>decltype()</tt>), and for specifying
+the return type of <a href="#CPlusPlus11_lambda_functions_and_expressions">lambdas</a>
+and <a href="#CPlusPlus11_alternate_function_syntax">functions</a>.</p>
+
 <H3><a name="CPlusPlus11_range_based_for_loop">7.2.7 Range-based for-loop</a></H3>
 
 
@@ -431,12 +865,9 @@ where peer constructors can be called. SWIG handles this without any issue.
 
 <p>
 The second improvement is constructor inheritance via a <tt>using</tt> declaration.
-This is parsed correctly, but the additional constructors are not currently added to the derived proxy class in the target language.
-An example is shown below:
-<!--
-The extra constructors provided by the <tt>using</tt> syntax will add the appropriate constructors into the target language proxy derived classes.
-In the example below a wrapper for the <tt>DerivedClass(int)</tt> is added to <tt>DerivedClass</tt>:
--->
+The extra constructors provided by the <tt>using</tt> declaration will add the appropriate constructors into the target language proxy derived classes.
+In the example below a wrapper for the <tt>DerivedClass(int)</tt> constructor is added to <tt>DerivedClass</tt>:
+
 </p>
 
 <div class="code"><pre>
@@ -451,6 +882,10 @@ class DerivedClass: public BaseClass {
 };
 </pre></div>
 
+<p>
+<b>Compatibility note:</b> SWIG-4.2.0 was the first version to generate wrappers for constructors inherited via <tt>using</tt> declarations.
+</p>
+
 <p>
 The final part is member initialization at the site of the declaration.
 This kind of initialization is handled by SWIG.
@@ -489,6 +924,19 @@ struct DerivedStruct : BaseStruct {
 };
 </pre></div>
 
+<p>
+Classes can also be marked as final, such as
+</p>
+
+<div class="code"><pre>
+struct FinalDerivedStruct final : BaseStruct {
+  virtual void ab() const override;
+};
+</pre></div>
+
+<p>
+<b>Compatibility note:</b> Final methods were supported much earlier than final classes. SWIG-4.1.0 was the first version to support classes marked as final.
+</p>
 
 <H3><a name="CPlusPlus11_null_pointer_constant">7.2.12 Null pointer constant</a></H3>
 
@@ -551,6 +999,22 @@ The equivalent in Java is:
 System.out.println(Color.RainbowColors.Red.swigValue() + " " + Color.WarmColors.Red.swigValue() + " " + Color.PrimeColors.Red.swigValue());
 </pre></div>
 
+<p>
+The C++11 enum base type, such as <tt>unsigned int</tt>, in the example above, is used by some language modules and is missing support in others. For example, in C#, the enum base type in the example above is used and converted into a C# <tt>uint</tt> to specify the underlying C# enumeration type as follows:
+</p>
+
+<div class="targetlang"><pre>
+  public enum RainbowColors : uint {
+    Red,
+    Orange,
+    Yellow,
+    Green,
+    Blue,
+    Indigo,
+    Violet
+  }
+</pre></div>
+
 <H3><a name="CPlusPlus11_double_angle_brackets">7.2.14 Double angle brackets</a></H3>
 
 
@@ -683,38 +1147,71 @@ union P {
 <H3><a name="CPlusPlus11_variadic_templates">7.2.18 Variadic templates</a></H3>
 
 
-<p>SWIG supports the variadic templates syntax (inside the &lt;&gt;
-block, variadic class inheritance and variadic constructor and
-initializers) with some limitations. The following code is correctly parsed:</p>
+<p>SWIG supports the variadic templates including the &lt;&gt;
+variadic class inheritance, variadic methods, variadic constructors and
+initializers. Example:</p>
 
 <div class="code"><pre>
 template &lt;typename... BaseClasses&gt; class ClassName : public BaseClasses... {
 public:
-  ClassName (BaseClasses &amp;&amp;... baseClasses) : BaseClasses(baseClasses)... {}
-}
+  ClassName(BaseClasses &amp;&amp;... baseClasses) : BaseClasses(baseClasses)... {}
+  void InstanceMethod(const BaseClasses&amp;... baseClasses) {}
+};
 </pre></div>
 
 <p>
-For now however, the <tt>%template</tt> directive only accepts one parameter substitution
-for the variable template parameters.
+The <tt>%template</tt> directive works as expected for variable template parameters.
 </p>
 
 <div class="code"><pre>
-%template(MyVariant1) ClassName&lt;&gt;         // zero argument not supported yet
-%template(MyVariant2) ClassName&lt;int&gt;      // ok
-%template(MyVariant3) ClassName&lt;int, int&gt; // too many arguments not supported yet
+struct A {
+  virtual void amethod();
+  virtual ~A();
+};
+struct B {
+  virtual void bmethod();
+  virtual ~B();
+};
+%template(ClassName0) ClassName&lt;&gt;
+%template(ClassName1) ClassName&lt;A&gt;
+%template(ClassName2) ClassName&lt;A, B&gt;
 </pre></div>
 
-<p>Support for the variadic <tt>sizeof()</tt> function is correctly parsed:</p>
+<p>
+Example usage from say Python:
+</p>
+
+<div class="targetlang"><pre>
+cn0 = ClassName0()
+cn0.InstanceMethod()
+
+a = A()
+cn1 = ClassName1(a)
+cn1.amethod()
+cn1.InstanceMethod(a)
+
+b = B()
+cn2 = ClassName2(a, b)
+cn2.InstanceMethod(a, b)
+cn2.amethod()
+cn2.bmethod()
+</pre></div>
+
+<p>Support for the variadic <tt>sizeof()</tt> function also works:</p>
 
 <div class="code"><pre>
-const int SIZE = sizeof...(ClassName&lt;int, int&gt;);
+const int SIZE = sizeof...(ClassName&lt;A, B&gt;);
 </pre></div>
 
 <p>
 In the above example <tt>SIZE</tt> is of course wrapped as a constant.
 </p>
 
+<p>
+<b>Compatibility note:</b> SWIG-4.2.0 was the first version to fully support variadic templates.
+SWIG-3.0.0 provided initial support and was limited to only one variadic parameter.
+</p>
+
 <H3><a name="CPlusPlus11_new_char_literals">7.2.19 New character literals</a></H3>
 
 
@@ -981,7 +1478,9 @@ Use the preprocessor to work around this for now:
 
 
 <p>
-Attributes such as those shown below, are not yet supported and will give a syntax error.
+Attributes such as those shown below, are supported since SWIG 4.1.0 but are
+currently crudely ignored by the parser's tokeniser so they have no effect on
+SWIG's code generation.
 </p>
 
 <div class="code"><pre>
@@ -1128,14 +1627,16 @@ While SWIG could provide wrappers for the new C++11 regular expressions classes,
 
 <p>
 SWIG provides special smart pointer handling for <tt>std::shared_ptr</tt> in the same way it has support for <tt>boost::shared_ptr</tt>.
-Please see the <a href="Library.html#Library_std_shared_ptr">shared_ptr smart pointer</a> library section.
-There is no special smart pointer handling available for <tt>std::weak_ptr</tt> and <tt>std::unique_ptr</tt> yet.
+Please see the <a href="Library.html#Library_std_shared_ptr">shared_ptr smart pointer</a>
+and <a href="Library.html#Library_std_unique_ptr">unique_ptr smart pointer</a> library sections.
+There is no special smart pointer handling available for <tt>std::weak_ptr</tt>.
+
 </p>
 
 <H3><a name="CPlusPlus11_extensible_random_number_facility">7.3.6 Extensible random number facility</a></H3>
 
 
-<p>This feature extends and standardizes the standard library only and does not effect the C++ language nor SWIG.</p>
+<p>This feature extends and standardizes the standard library only and does not affect the C++ language nor SWIG.</p>
 
 <H3><a name="CPlusPlus11_wrapper_reference">7.3.7 Wrapper reference</a></H3>
 

Doc/Manual/CPlusPlus14.html

@@ -15,6 +15,7 @@
 <li><a href="#CPlusPlus14_core_language_changes">Core language changes</a>
 <ul>
 <li><a href="#CPlusPlus14_binary_literals">Binary integer literals</a>
+<li><a href="#CPlusPlus14_return_type_deduction">Return type deduction</a>
 </ul>
 <li><a href="#CPlusPlus14_standard_library_changes">Standard library changes</a>
 </ul>
@@ -53,6 +54,67 @@ int b = 0b101011;
 </pre>
 </div>
 
+<H3><a name="CPlusPlus14_return_type_deduction">8.2.2 Return type deduction</a></H3>
+
+
+<p>
+C++14 added the ability to specify <tt>auto</tt> for the return type of a function
+and have the compiler deduce it from the body of the function (in C++11 you had
+to explicitly specify a trailing return type if you used <tt>auto</tt> for the
+return type).
+</p>
+
+<p>
+SWIG parses these types of functions, but with one significant limitation: SWIG
+can't actually deduce the return type!  If you want to wrap such a function
+you will need to tell SWIG the return type explicitly.
+</p>
+
+<p>
+The trick for specifying the return type is to use <tt>%ignore</tt> to tell
+SWIG to ignore the function with the deduced return type, but first provide
+SWIG with an alternative declaration of the function with an explicit return
+type.  The generated wrapper will wrap this alternative declaration, and the
+call in the wrapper to the function will call the actual declaration.  Here is
+an actual example:
+</p>
+
+<div class="code"><pre>
+std::tuple&lt;int, int&gt; va_static_cast();
+%ignore va_static_cast();
+#pragma SWIG nowarn=SWIGWARN_CPP14_AUTO
+
+%inline %{
+#include &lt;tuple&gt;
+
+auto va_static_cast() {
+    return std::make_tuple(0, 0);
+}
+%}
+</pre></div>
+
+<p>
+For member methods the trick is to use <tt>%extend</tt> to redeclare the method and call it as follows:
+</p>
+
+<div class="code"><pre>
+%extend X {
+  const char * a() const { return $self-&gt;a(); }
+}
+%inline %{
+struct X {
+  auto a() const {
+    return "a string";
+  }
+};
+%}
+</pre></div>
+
+<p>
+<b>Compatibility note:</b> SWIG-4.2.0 first introduced support for functions declared with an auto return without a trailing return type.
+</p>
+
+
 <H2><a name="CPlusPlus14_standard_library_changes">8.3 Standard library changes</a></H2>
 
 

Doc/Manual/CPlusPlus20.html

@@ -0,0 +1,91 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+<title>SWIG and C++20</title>
+<link rel="stylesheet" type="text/css" href="style.css">
+<meta http-equiv="content-type" content="text/html; charset=UTF-8">
+</head>
+
+<body bgcolor="#ffffff">
+<H1><a name="CPlusPlus20">10 SWIG and C++20</a></H1>
+<!-- INDEX -->
+<div class="sectiontoc">
+<ul>
+<li><a href="#CPlusPlus20_introduction">Introduction</a>
+<li><a href="#CPlusPlus20_core_language_changes">Core language changes</a>
+<ul>
+<li><a href="#CPlusPlus20_spaceship_operator">Spaceship operator</a>
+<li><a href="#CPlusPlus20_lambda_templates">Lambda templates</a>
+<li><a href="#CPlusPlus20_constexpr_destructors">Constexpr destructors</a>
+</ul>
+<li><a href="#CPlusPlus20_standard_library_changes">Standard library changes</a>
+</ul>
+</div>
+<!-- INDEX -->
+
+
+
+<H2><a name="CPlusPlus20_introduction">10.1 Introduction</a></H2>
+
+
+<p>This chapter gives you a brief overview about the SWIG
+implementation of the C++20 standard.
+Work has only just begun on adding C++20 support.
+</p>
+
+<p>
+<b>Compatibility note:</b> SWIG-4.1.0 is the first version to support any C++20 features.
+</p>
+
+<H2><a name="CPlusPlus20_core_language_changes">10.2 Core language changes</a></H2>
+
+
+<H3><a name="CPlusPlus20_spaceship_operator">10.2.1 Spaceship operator</a></H3>
+
+
+<p>
+SWIG supports the spaceship operator <tt>&lt;=&gt;</tt> in constant
+expressions.  To simplify handling of the return value type, it is currently
+treated as an integer rather than <tt>std::strong_ordering</tt>, etc.
+In practice we think that should do the right thing in most cases.
+</p>
+
+<p>
+SWIG also recognises <tt>operator&lt;=&gt;</tt> which can be wrapped
+if renamed.  There is not currently any default renaming for the operator
+or any attempt to automatically map it to a three-way comparison operator
+in any of the target languages.
+</p>
+
+<H3><a name="CPlusPlus20_lambda_templates">10.2.2 Lambda templates</a></H3>
+
+
+<p>
+SWIG should parse lambda templates, but like
+<a href="CPlusPlus11.html#CPlusPlus11_lambda_functions_and_expressions">
+non-templated lambdas</a> they aren't currently wrapped.
+</p>
+
+
+<H3><a name="CPlusPlus20_constexpr_destructors">10.2.3 Constexpr destructors</a></H3>
+
+
+<p>
+Destructors that are declared <tt>constexpr</tt> are parsed and handled like any other constructor.
+For example:
+</p>
+
+<div class="code">
+<pre>
+class DtorA {
+public:
+  constexpr ~DtorA() {}
+};
+</pre>
+</div>
+
+<H2><a name="CPlusPlus20_standard_library_changes">10.3 Standard library changes</a></H2>
+
+
+</body>
+</html>

Doc/Manual/CSharp.html

@@ -6,7 +6,7 @@
 <meta http-equiv="content-type" content="text/html; charset=UTF-8">
 </head>
 <body bgcolor="#FFFFFF">
-<H1><a name="CSharp">22 SWIG and C#</a></H1>
+<H1><a name="CSharp">23 SWIG and C#</a></H1>
 <!-- INDEX -->
 <div class="sectiontoc">
 <ul>
@@ -16,7 +16,12 @@
 <li><a href="#CSharp_commandline">Additional command line options</a>
 </ul>
 <li><a href="#CSharp_differences_java">Differences to the Java module</a>
+<li><a href="#CSharp_type_mapping">Type mapping</a>
+<ul>
+<li><a href="#CSharp_primitive_types">Primitive types</a>
+<li><a href="#CSharp_other_type_mappings">Other types</a>
 <li><a href="#CSharp_void_pointers">Void pointers</a>
+</ul>
 <li><a href="#CSharp_arrays">C# Arrays</a>
 <ul>
 <li><a href="#CSharp_arrays_swig_library">The SWIG C arrays library</a>
@@ -37,6 +42,7 @@
 <li><a href="#CSharp_director_caveats">Director caveats</a>
 </ul>
 <li><a href="#CSharp_multiple_modules">Multiple modules</a>
+<li><a href="#CSharp_named_arguments">C# named and optional arguments</a>
 <li><a href="#CSharp_typemap_examples">C# Typemap examples</a>
 <ul>
 <li><a href="#CSharp_memory_management_member_variables">Memory management when returning references to member variables</a>
@@ -55,7 +61,7 @@
 
 
 
-<H2><a name="CSharp_introduction">22.1 Introduction</a></H2>
+<H2><a name="CSharp_introduction">23.1 Introduction</a></H2>
 
 
 <p>
@@ -81,7 +87,7 @@ The <a href="https://msdn.microsoft.com">Microsoft Developer Network (MSDN)</a>
 Monodoc, available from the Mono project, has a very useful section titled <a href="https://www.mono-project.com/docs/advanced/pinvoke/">Interop with native libraries</a>.
 </p>
 
-<H3><a name="CSharp_introduction_swig2_compatibility">22.1.1 SWIG 2 Compatibility</a></H3>
+<H3><a name="CSharp_introduction_swig2_compatibility">23.1.1 SWIG 2 Compatibility</a></H3>
 
 
 <p>
@@ -89,7 +95,7 @@ In order to minimize name collisions between names generated based on input to S
 </p>
 
 
-<H3><a name="CSharp_commandline">22.1.2 Additional command line options</a></H3>
+<H3><a name="CSharp_commandline">23.1.2 Additional command line options</a></H3>
 
 
 <p>
@@ -141,7 +147,7 @@ Note that the file extension (.cs) will not be automatically added and needs to
 Due to possible compiler limits it is not advisable to use <tt>-outfile</tt> for large projects.
 </p>
 
-<H2><a name="CSharp_differences_java">22.2 Differences to the Java module</a></H2>
+<H2><a name="CSharp_differences_java">23.2 Differences to the Java module</a></H2>
 
 
 <p>
@@ -240,6 +246,7 @@ javabody                    -&gt; csbody
 javafinalize                -&gt; csfinalize
 javadestruct                -&gt; csdisposing and csdispose
 javadestruct_derived        -&gt; csdisposing_derived and csdispose_derived
+javainterfacemodifiers      -&gt; csinterfacemodifiers
 javainterfacecode           -&gt; csinterfacecode
 </pre></div>
 
@@ -519,7 +526,7 @@ The module directive attribute <tt>imclassname</tt> is used to achieve this:
 
 <div class="code">
 <pre>
-%module (imclassname="name") modulename
+%module(imclassname="name") modulename
 </pre>
 </div>
 
@@ -529,6 +536,38 @@ from <tt>modulename</tt> to <tt>modulenameModule</tt>.
 </p>
 </li>
 
+<li>
+<a name="CSharp_begin"></a>
+<p>
+The <tt>%module</tt> directive supports the <tt>csbegin</tt> option for adding code to the start of every generated C# file.
+This is useful for adding common comments, using statements and/or preprocessor statements into all generated .cs files. For example,
+C# 8 nullable reference types can be enabled via a C# preprocessor directive by adding <tt>#nullable enable</tt> into C# files as follows:
+</p>
+
+<div class="code">
+<pre>
+%module(csbegin="#nullable enable\n") mymodule
+</pre>
+</div>
+
+<p>
+It might be easier to use a macro for multiple lines of code, for example:
+</p>
+
+<div class="code">
+<pre>
+%define CSBEGIN_CODE
+"
+/* Copyright statement */
+using System.Text;
+#nullable enable
+"
+%enddef
+
+%module(csbegin=CSBEGIN_CODE) mymodule
+</pre>
+</div>
+
 <li>
 There is no additional 'premature garbage collection prevention parameter' as the marshalling of the <tt>HandleRef</tt> object
 takes care of ensuring a reference to the proxy class is held until the unmanaged call completed.
@@ -549,6 +588,12 @@ This special variable expands to the intermediary class name. For C# this is usu
 unless the imclassname attribute is specified in the <a href="CSharp.html#CSharp_module_directive">%module directive</a>.
 </p>
 
+<p>
+<b><tt>$imfuncname</tt></b><br>
+This special variable expands to the name of the function in the intermediary class that will be used in $imcall.
+Like, $imcall, this special variable is only expanded in the "csout", "csvarin" and "csvarout" typemaps.
+</p>
+
 <p>
 The directory <tt>Examples/csharp</tt> has a number of simple examples. 
 Visual Studio .NET 2003 solution and project files are available for compiling with the Microsoft .NET C#
@@ -559,17 +604,313 @@ After SWIG has run and both the C# and C/C++ compilers have finished building,
 the examples will be run, by either running <tt>runme.exe</tt> or by running
 <tt>mono runme.exe</tt> (Mono C# compiler).
 Windows users can also get the examples working using a
-<a href="http://www.cygwin.com">Cygwin</a> or <a href="http://www.mingw.org">MinGW</a> environment for automatic configuration of the example makefiles.
+<a href="http://www.cygwin.com">Cygwin</a> or <a href="https://osdn.net/projects/mingw/">MinGW</a> environment for automatic configuration of the example makefiles.
 Any one of the C# compilers (Mono or Microsoft) can be detected from within a Cygwin or Mingw environment if installed in your path. 
 
-<H2><a name="CSharp_void_pointers">22.3 Void pointers</a></H2>
+<H2><a name="CSharp_type_mapping">23.3 Type mapping</a></H2>
 
 
 <p>
-By default SWIG treats <tt>void *</tt> as any other pointer and hence marshalls it as a type wrapper class called <tt>SWIGTYPE_p_void</tt>.
+The marshalling of the types and typemaps used for marshalling across the managed/unmanaged layers are discussed in this section.
+The interested reader will find the implementation in the csharp.swg file.
+</p>
+
+<H3><a name="CSharp_primitive_types">23.3.1 Primitive types</a></H3>
+
+
+<p>
+Primitive types are marshalled between the unmanaged and managed layers as blittable types.
+</p>
+
+<ul>
+<li> The first column in the table below shows various C/C++ types that might be parsed by SWIG.
+<li> The second column contains the default type provided by the 'ctype' typemap, that is, the type used for marshalling on the C side.
+<li> The third column shows the default type provided by both the 'imtype' and the 'cstype' typemaps, that is, the equivalent type on the C# side.
+<li> The fourth column shows the size or number of bytes of the 'imtype'/'cstype', which may or may not match the size of the C/C++ type and is discussed next.
+</ul>
+
+<table BORDER summary="Default primitive type mappings">
+<tr>
+<td><b>C/C++ type</b></td>
+<td><b>ctype</b></td>
+<td><b>imtype/cstype</b></td>
+<td><b>Size</b></td>
+</tr>
+
+<tr>
+<td>bool<br> const bool &amp; </td>
+<td>unsigned int</td>
+<td>bool</td>
+<td>1</td>
+</tr>
+
+<tr>
+<td>char<br>const char &amp;</td>
+<td>char</td>
+<td>char</td>
+<td>1</td>
+</tr>
+
+<tr>
+<td>signed char<br>const signed char &amp;</td>
+<td>signed char</td>
+<td>sbyte</td>
+<td>1</td>
+</tr>
+
+<tr>
+<td>unsigned char<br>const unsigned char &amp;</td>
+<td>unsigned char</td>
+<td>byte</td>
+<td>1</td>
+</tr>
+
+<tr>
+<td>short<br>const short &amp;</td>
+<td>short</td>
+<td>short</td>
+<td>2</td>
+</tr>
+
+<tr>
+<td>unsigned short<br> const unsigned short &amp;</td>
+<td>unsigned short</td>
+<td>ushort</td>
+<td>2</td>
+</tr>
+
+<tr>
+<td>int<br> const int &amp;</td>
+<td>int</td>
+<td>int</td>
+<td>4</td>
+</tr>
+
+<tr>
+<td>unsigned int<br> const unsigned int &amp;</td>
+<td>unsigned int</td>
+<td>uint</td>
+<td>4</td>
+</tr>
+
+<tr>
+<td>long<br>const long &amp;</td>
+<td>int</td>
+<td>int</td>
+<td>4</td>
+</tr>
+
+<tr>
+<td>unsigned long<br>const unsigned long &amp;</td>
+<td>unsigned int</td>
+<td>uint</td>
+<td>4</td>
+</tr>
+
+<tr>
+<td>long long<br> const long long &amp;</td>
+<td>long long</td>
+<td>long</td>
+<td>8</td>
+</tr>
+
+<tr>
+<td>unsigned long long<br>const unsigned long long &amp;</td>
+<td>unsigned long long</td>
+<td>ulong</td>
+<td>8</td>
+</tr>
+
+<tr>
+<td>float<br>const float &amp;</td>
+<td>float</td>
+<td>float</td>
+<td>4</td>
+</tr>
+
+<tr>
+<td>double<br> const double &amp;</td>
+<td>double</td>
+<td>double</td>
+<td>8</td>
+</tr>
+
+<tr>
+<td>size_t<br> const size_t &amp;</td>
+<td>unsigned int</td>
+<td>uint</td>
+<td>4</td>
+</tr>
+
+
+</table>
+
+<p>
+The size in bytes of the C type, 'ctype', should match the C# type, 'imtype' for blitting across the managed/unmanaged layers.
+They do match across the common 32-bit and 64-bit operating systems, Unix, Windows and MacOS, except for the C long/unsigned long and size_t types.
+From the table above the default is to handle C long and size_t as a 32-bit (4 byte) type, so large numbers could be truncated on some 64-bit operating systems.
+If <tt>SWIGWORDSIZE64</tt> is defined the C long type is instead handled as a 64-bit (8 byte) type, as per the table below.
+</p>
+
+<table BORDER summary="SWIGWORDSIZE64 primitive type mappings">
+
+<tr>
+<td><b>C/C++ type</b></td>
+<td><b>ctype</b></td>
+<td><b>imtype/cstype</b></td>
+<td><b>Size</b></td>
+</tr>
+
+<tr>
+<td>long<br>const long &amp;</td>
+<td>long long</td>
+<td>long</td>
+<td>8</td>
+</tr>
+
+<tr>
+<td>unsigned long<br>const unsigned long &amp;</td>
+<td>unsigned long long</td>
+<td>ulong</td>
+<td>8</td>
+</tr>
+
+</table>
+
+<p>
+However, truncation may then occur when the C long type is actually 32-bits (4 bytes).
+It's best to avoid using C long for portability across different operating systems!
+</p>
+
+<p>
+If you need to support long on a range of systems where the size of long varies, then steps must be taken before invoking SWIG to determine whether or not to define <tt>SWIGWORDSIZE64</tt> when invoking SWIG.
+</p>
+
+<p>
+In order to treat the C size_t type as a 64-bit (8 byte) type, apply the 64-bit typemaps as follows:
+</p>
+
+<div class="code">
+<pre>
+%apply unsigned long long { size_t };
+%apply const unsigned long long &amp; { const size_t &amp; };
+</pre>
+</div>
+
+<p>
+The net effect then changes from the default shown earlier to:
+</p>
+
+<table BORDER summary="size_t long long mappings">
+
+<tr>
+<td><b>C/C++ type</b></td>
+<td><b>ctype</b></td>
+<td><b>imtype/cstype</b></td>
+<td><b>Size</b></td>
+</tr>
+
+<tr>
+<td>size_t<br>const size_t &amp;</td>
+<td>unsigned long long</td>
+<td>ulong</td>
+<td>8</td>
+</tr>
+
+</table>
+
+<p>
+If you need to support size_t on a range of systems where the size of size_t varies, then steps must be taken before invoking SWIG to determine whether or not to apply the typemaps.
+Conditionally applying the typemaps using a macro is easily done. For example define <tt>MY_SIZET_WORDSIZE64</tt> to generate 64-bit (8 byte) handling using the following:
+</p>
+
+<div class="code">
+<pre>
+#if defined(MY_SIZET_WORDSIZE64)
+%apply unsigned long long { size_t };
+%apply const unsigned long long &amp; { const size_t &amp; };
+#endif
+</pre>
+</div>
+
+<H3><a name="CSharp_other_type_mappings">23.3.2 Other types</a></H3>
+
+
+<p>
+The table below shows the equivalent mappings for pointers and strings.
+Classes and structs are marshalled using a pointer to the instance of the object.
+Note the types in the 'imtype' and 'cstype' typemaps can be different.
+</p>
+
+<ul>
+<li> The 'imtype' type is used for marshalling across the managed and unmanaged boundary.
+<li> The 'cstype' is the final C# proxy or intermediary class type.
+<li> In the table below, the 'imtype' type is used for marshalling from the managed to the unmanaged layer.
+<li> The 'imtype out' type is used for marshalling from the unmanaged to the managed layer.
+</ul>
+
+<table BORDER summary="Other type mappings">
+
+<tr>
+<td><b>C/C++ type</b></td>
+<td><b>ctype</b></td>
+<td><b>imtype</b></td>
+<td><b>imtype out</b></td>
+<td><b>cstype</b></td>
+</tr>
+
+<tr>
+<td>char *<br>char []</td>
+<td>char *</td>
+<td>string</td>
+<td>string</td>
+<td>string</td>
+</tr>
+
+<tr>
+<td>void *</td>
+<td>void *</td>
+<td>System.Runtime.InteropServices.HandleRef</td>
+<td>System.IntPtr</td>
+<td>SWIGTYPE_p_void</td>
+</tr>
+
+</table>
+
+
+<H3><a name="CSharp_void_pointers">23.3.3 Void pointers</a></H3>
+
+
+<p>
+By default SWIG treats <tt>void *</tt> as any other pointer and hence marshalls it as a type wrapper class called <tt>SWIGTYPE_p_void</tt>,
+as shown in the table in the previous section.
 If you want to marshall with the .NET <tt>System.IntPtr</tt> type instead, there is a simple set of named typemaps called
 <tt>void *VOID_INT_PTR</tt> that can be used.
-They can be applied like any other named typemaps:
+The net effect is then:
+</p>
+
+<table BORDER summary="VOID_INT_PTR type mappings">
+
+<tr>
+<td><b>C/C++ type</b></td>
+<td><b>ctype</b></td>
+<td><b>imtype</b></td>
+<td><b>imtype out</b></td>
+<td><b>cstype</b></td>
+</tr>
+
+<tr>
+<td>void *VOID_INT_PTR</td>
+<td>void *</td>
+<td>System.IntPtr</td>
+<td>System.IntPtr</td>
+<td>System.IntPtr</td>
+</tr>
+
+</table>
+
+<p>
+This is achieved by applying them like any other named typemaps:
 </p>
 
 
@@ -580,7 +921,7 @@ void * f(void *v);
 </pre>
 </div>
 
-<H2><a name="CSharp_arrays">22.4 C# Arrays</a></H2>
+<H2><a name="CSharp_arrays">23.4 C# Arrays</a></H2>
 
 
 <p>
@@ -592,7 +933,7 @@ with one of the following three approaches; namely the SWIG C arrays library, P/
 pinned arrays.
 </p>
 
-<H3><a name="CSharp_arrays_swig_library">22.4.1 The SWIG C arrays library</a></H3>
+<H3><a name="CSharp_arrays_swig_library">23.4.1 The SWIG C arrays library</a></H3>
 
 
 <p>
@@ -629,7 +970,7 @@ example.print_array(c.cast());          // Pass to C
 </div>
 
 
-<H3><a name="CSharp_arrays_pinvoke_default_array_marshalling">22.4.2 Managed arrays using P/Invoke default array marshalling</a></H3>
+<H3><a name="CSharp_arrays_pinvoke_default_array_marshalling">23.4.2 Managed arrays using P/Invoke default array marshalling</a></H3>
 
 
 <p>
@@ -756,7 +1097,7 @@ and intermediary class method
 </div>
 
 
-<H3><a name="CSharp_arrays_pinning">22.4.3 Managed arrays using pinning</a></H3>
+<H3><a name="CSharp_arrays_pinning">23.4.3 Managed arrays using pinning</a></H3>
 
 
 <p>
@@ -851,7 +1192,7 @@ public static extern void myArrayCopy(global::System.IntPtr jarg1, global::Syste
 
 
 
-<H2><a name="CSharp_exceptions">22.5 C# Exceptions</a></H2>
+<H2><a name="CSharp_exceptions">23.5 C# Exceptions</a></H2>
 
 
 <p>
@@ -948,7 +1289,7 @@ set so should only be used when a C# exception is not created.
 </p>
 
 
-<H3><a name="CSharp_exception_example_check_typemap">22.5.1 C# exception example using "check" typemap</a></H3>
+<H3><a name="CSharp_exception_example_check_typemap">23.5.1 C# exception example using "check" typemap</a></H3>
 
 
 <p>
@@ -1130,7 +1471,7 @@ method and C# code does not handle pending exceptions via the canthrow attribute
 Actually it will issue this warning for any function beginning with <tt>SWIG_CSharpSetPendingException</tt>.
 </P>
 
-<H3><a name="CSharp_exception_example_percent_exception">22.5.2 C# exception example using %exception</a></H3>
+<H3><a name="CSharp_exception_example_percent_exception">23.5.2 C# exception example using %exception</a></H3>
 
 
 <p>
@@ -1195,7 +1536,7 @@ The managed code generated does check for the pending exception as mentioned ear
 </pre>
 </div>
 
-<H3><a name="CSharp_exception_example_exception_specifications">22.5.3 C# exception example using exception specifications</a></H3>
+<H3><a name="CSharp_exception_example_exception_specifications">23.5.3 C# exception example using exception specifications</a></H3>
 
 
 <p>
@@ -1251,7 +1592,7 @@ SWIGEXPORT void SWIGSTDCALL CSharp_evensonly(int jarg1) {
 Multiple catch handlers are generated should there be more than one exception specifications declared.
 </p>
 
-<H3><a name="CSharp_custom_application_exception">22.5.4 Custom C# ApplicationException example</a></H3>
+<H3><a name="CSharp_custom_application_exception">23.5.4 Custom C# ApplicationException example</a></H3>
 
 
 <p>
@@ -1385,7 +1726,7 @@ try {
 </pre>
 </div>
 
-<H2><a name="CSharp_directors">22.6 C# Directors</a></H2>
+<H2><a name="CSharp_directors">23.6 C# Directors</a></H2>
 
 
 <p>
@@ -1398,7 +1739,7 @@ The following sections provide information on the C# director implementation and
 However, the <a href="Java.html#Java_directors">Java directors</a> section should also be read in order to gain more insight into directors.
 </p>
 
-<H3><a name="CSharp_directors_example">22.6.1 Directors example</a></H3>
+<H3><a name="CSharp_directors_example">23.6.1 Directors example</a></H3>
 
 
 <p>
@@ -1466,7 +1807,7 @@ public class CSharpDerived : Base
 {
   public override uint UIntMethod(uint x)
   {
-    Console.WriteLine("CSharpDerived - UIntMethod({0})", x);
+    global::System.Console.WriteLine("CSharpDerived - UIntMethod({0})", x);
     return x;
   }
 }
@@ -1519,7 +1860,7 @@ CSharpDerived - UIntMethod(123)
 </pre>
 </div>
 
-<H3><a name="CSharp_directors_implementation">22.6.2 Directors implementation</a></H3>
+<H3><a name="CSharp_directors_implementation">23.6.2 Directors implementation</a></H3>
 
 
 <p>
@@ -1727,7 +2068,7 @@ before SWIG parses the Base class will change all the delegates to <tt>internal<
 </pre>
 </div>
 
-<H3><a name="CSharp_director_caveats">22.6.3 Director caveats</a></H3>
+<H3><a name="CSharp_director_caveats">23.6.3 Director caveats</a></H3>
 
 
 <p>
@@ -1775,7 +2116,7 @@ However, a call from C# to <tt>CSharpDefaults.DefaultMethod()</tt> will of cours
 should pass the call on to <tt>CSharpDefaults.DefaultMethod(int)</tt>using the C++ default value, as shown above.
 </p>
 
-<H2><a name="CSharp_multiple_modules">22.7 Multiple modules</a></H2>
+<H2><a name="CSharp_multiple_modules">23.7 Multiple modules</a></H2>
 
 
 <p>
@@ -1810,7 +2151,96 @@ the <tt>[System.ComponentModel.EditorBrowsable(System.ComponentModel.EditorBrows
 if you don't want users to easily stumble upon these so called 'internal workings' of the wrappers.
 </p>
 
-<H2><a name="CSharp_typemap_examples">22.8 C# Typemap examples</a></H2>
+
+<H2><a name="CSharp_named_arguments">23.8 C# named and optional arguments</a></H2>
+
+
+<p>
+  In C++ you can specify default arguments for functions, methods, and constructors.  C# offers named arguments.  This feature, specific to C#, lets you bind default argument functions with default arguments in C#.  SWIG also allows you to add default arguments to C# functions which don't have default arguments in C++.
+</p>
+
+<p>
+The <tt>cs:defaultargs</tt> feature enables C# named arguments with C# default values.
+Using this feature will turn off SWIG's default handling for default arguments, which would create an override for each defaulted argument.
+</p>
+
+<p>For this feature, you first specify the function/method/constructor you want it to impact.  Inside the feature
+  call you specify each argument you want to override.  If you specify none, it will take the literal text from c++
+  for each argument and apply that in C#.  That often works fine, but when it doesn't you can supply a string literal
+  with a C# expression to be used as an override.  Or you can supply an int literal, or a float literal.  If you want to give a literal
+  string you need to include an escaped quote at the start and end of the literal such as  <tt>"\"a string\""</tt>.
+</p>
+
+<p>
+Let's consider an example:
+</p>
+
+<div class="code">
+  <pre>
+    %feature("cs:defaultargs") Foo::Foo;
+    %feature("cs:defaultargs", x=0, z=4) Foo::bar;
+    %feature("cs:defaultargs", x="\"five\"") Foo::zoo;
+
+    %inline %{
+    class Foo {
+    public:
+        Foo(int a, int b=1, int c=2)
+        {
+        }
+        int bar(int x, int y=2, int z=3)
+        {
+            return x+y+z;
+        }
+        int bat(int x=1, int y=2, int z=3)
+        {
+            return x+y+z;
+        }
+        int zoo(std::string x="four")
+        {
+            return (int)x.size();
+        }
+    };
+    %}
+  </pre>
+</div>
+
+<p>
+The generated C# proxy class contains:
+</p>
+
+<div class="code">
+<pre>
+public class Foo : global::System.IDisposable {
+  ...
+  public Foo(int a, int b=1, int c=2) ...
+
+  public int bar(int x=0, int y=2, int z=4) ...
+
+  public int bat(int x, int y, int z) ...
+  public int bat(int x, int y) ...
+  public int bat(int x) ...
+  public int bat() ...
+
+  public int zoo(string x="five") ...
+}
+</pre>
+</div>
+
+<p>
+Note that:
+</p>
+<ol>
+<li> The constructor uses the default arguments exactly as taken from C++.  </li>
+<li> The <tt>bar</tt> method uses the default arguments exactly as taken from C++ apart from <tt>z</tt> whose default value is changed to 4, and <tt>x</tt> did not have a default value in C++, but does in the generated C#.</li>
+<li> The <tt>bat</tt> method does not use the <tt>cs:defaultargs</tt> feature and so the default handling of one overloaded C# method per defaulted C++ argument is generated.</li>
+<li> The <tt>zoo</tt> method's string value is overridden by the new string value from the feature. </li>
+</ol>
+
+<p>
+<b>Compatibility Note:</b> SWIG-4.2.0 added support for the <tt>cs:defaultargs</tt> feature.
+</p>
+
+<H2><a name="CSharp_typemap_examples">23.9 C# Typemap examples</a></H2>
 
 
 This section includes a few examples of typemaps.  For more examples, you
@@ -1818,7 +2248,7 @@ might look at the files "<tt>csharp.swg</tt>" and "<tt>typemaps.i</tt>" in
 the SWIG library.
 
 
-<H3><a name="CSharp_memory_management_member_variables">22.8.1 Memory management when returning references to member variables</a></H3>
+<H3><a name="CSharp_memory_management_member_variables">23.9.1 Memory management when returning references to member variables</a></H3>
 
 
 <p>
@@ -1854,7 +2284,7 @@ and the following usage from C# after running the code through SWIG:
 <div class="code">
 <pre>
   Wheel wheel = new Bike(10).getWheel();
-  Console.WriteLine("wheel size: " + wheel.size);
+  global::System.Console.WriteLine("wheel size: " + wheel.size);
   // Simulate a garbage collection
   global::System.GC.Collect();
   global::System.GC.WaitForPendingFinalizers();
@@ -1942,7 +2372,7 @@ public class Bike : global::System.IDisposable {
 Note the <tt>addReference</tt> call.
 </p>
 
-<H3><a name="CSharp_memory_management_objects">22.8.2 Memory management for objects passed to the C++ layer</a></H3>
+<H3><a name="CSharp_memory_management_objects">23.9.2 Memory management for objects passed to the C++ layer</a></H3>
 
 
 <p>
@@ -2003,7 +2433,7 @@ In order to understand why, consider a garbage collection occurring...
   Container container = new Container();
   Element element = new Element(20);
   container.setElement(element);
-  Console.WriteLine("element.value: " + container.getElement().value);
+  global::System.Console.WriteLine("element.value: " + container.getElement().value);
   // Simulate a garbage collection
   global::System.GC.Collect();
   global::System.GC.WaitForPendingFinalizers();
@@ -2074,7 +2504,7 @@ as mentioned earlier, <tt>setElement</tt> is actually:
 </div>
 
 
-<H3><a name="CSharp_date_marshalling">22.8.3 Date marshalling using the csin typemap and associated attributes</a></H3>
+<H3><a name="CSharp_date_marshalling">23.9.3 Date marshalling using the csin typemap and associated attributes</a></H3>
 
 
 <p>
@@ -2360,7 +2790,7 @@ public class example {
 </pre>
 </div>
 
-<H3><a name="CSharp_date_properties">22.8.4 A date example demonstrating marshalling of C# properties</a></H3>
+<H3><a name="CSharp_date_properties">23.9.4 A date example demonstrating marshalling of C# properties</a></H3>
 
 
 <p>
@@ -2460,7 +2890,7 @@ Some points to note:
   <li>The 'csin' typemap has 'pre', 'post' and 'cshin' attributes, and these are all ignored in the property set. The code in these attributes must instead be replicated within the 'csvarin' typemap. The line creating the <tt>temp$csinput</tt> variable is such an example; it is identical to what is in the 'pre' attribute.
 </ul>
 
-<H3><a name="CSharp_date_pre_post_directors">22.8.5 Date example demonstrating the 'pre' and 'post' typemap attributes for directors</a></H3>
+<H3><a name="CSharp_date_pre_post_directors">23.9.5 Date example demonstrating the 'pre' and 'post' typemap attributes for directors</a></H3>
 
 
 <p>
@@ -2522,7 +2952,7 @@ Pay special attention to the memory management issues, using these attributes.
 </p>
 
 
-<H3><a name="CSharp_partial_classes">22.8.6 Turning proxy classes into partial classes</a></H3>
+<H3><a name="CSharp_partial_classes">23.9.6 Turning proxy classes into partial classes</a></H3>
 
 
 <p>
@@ -2622,7 +3052,7 @@ demonstrating that the class contains methods calling both unmanaged code - <tt>
 The following example is an alternative approach to adding managed code to the generated proxy class.
 </p>
 
-<H3><a name="CSharp_sealed_proxy_class">22.8.7 Turning proxy classes into sealed classes</a></H3>
+<H3><a name="CSharp_sealed_proxy_class">23.9.7 Turning proxy classes into sealed classes</a></H3>
 
 
 <p>
@@ -2712,7 +3142,7 @@ Either suppress the warning or modify the generated code by copying and tweaking
 'csbody' typemap code in csharp.swg by modifying swigCMemOwn to not be protected.
 </p>
 
-<H3><a name="CSharp_extending_proxy_class">22.8.8 Extending proxy classes with additional C# code</a></H3>
+<H3><a name="CSharp_extending_proxy_class">23.9.8 Extending proxy classes with additional C# code</a></H3>
 
 
 <p>
@@ -2751,11 +3181,12 @@ public class ExtendMe : global::System.IDisposable {
 </pre>
 </div>
 
-<H3><a name="CSharp_enum_underlying_type">22.8.9 Underlying type for enums</a></H3>
+<H3><a name="CSharp_enum_underlying_type">23.9.9 Underlying type for enums</a></H3>
 
 
 <P>
-C# enums use int as the underlying type for each enum item.
+C# enums use int as the underlying type for each enum item, unless there is a C++11 enum base specifiying the underlying C++ enum type.
+If there is a C++ base enum then this is automatically converted to the equivalent C# integral type.
 If you wish to change the underlying type to something else, then use the <tt>csbase</tt> typemap.
 For example when your C++ code uses a value larger than int, this is necessary as the C# compiler will not compile values which are too large to fit into an int.
 Here is an example:
@@ -2774,7 +3205,7 @@ Here is an example:
 The generated enum will then use the given underlying type and compile correctly:
 </p>
 
-<div class="code">
+<div class="targetlang">
 <pre>
 public enum BigNumbers : uint {
   big = 0x80000000,
@@ -2783,6 +3214,58 @@ public enum BigNumbers : uint {
 </pre>
 </div>
 
+<p>
+If a C++11 enum base is specified, such as <tt>unsigned short</tt> in the following:
+</p>
+
+<div class="code">
+<pre>
+%inline %{
+  enum SmallNumbers : unsigned short { tiny, small=1  };
+%}
+</pre>
+</div>
+
+<p>
+The underlying type is automatically converted to the C# equivalent, <tt>ushort</tt>:
+</p>
+
+<div class="targetlang">
+<pre>
+public enum SmallNumbers : ushort {
+  tiny,
+  small = 1
+}
+</pre>
+</div>
+
+<p>
+The underlying C# type can still be changed to something else using the csbase typemap but the <tt>replace</tt> attribute must be set to avoid an ignored warnings as there are effectively two specified bases, which of course is not possible. For example:
+</p>
+
+<div class="code">
+<pre>
+%typemap(csbase, replace="1") SmallNumbers "byte"
+%inline %{
+  enum SmallNumbers : unsigned short { tiny, small=1  };
+%}
+</pre>
+</div>
+
+<p>
+which generates the desired underlying enum type:
+</p>
+
+<div class="targetlang">
+<pre>
+public enum SmallNumbers : byte {
+  tiny,
+  small = 1
+}
+</pre>
+</div>
+
+
 </body>
 </html>
 

Doc/Manual/Chicken.html

@@ -1,597 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<title>SWIG and Chicken</title>
-<link rel="stylesheet" type="text/css" href="style.css">
-<meta http-equiv="content-type" content="text/html; charset=UTF-8">
-</head>
-
-<body bgcolor="#ffffff">
-
-<H1><a name="Chicken">23 SWIG and Chicken</a></H1>
-<!-- INDEX -->
-<div class="sectiontoc">
-<ul>
-<li><a href="#Chicken_nn2">Preliminaries</a>
-<ul>
-<li><a href="#Chicken_nn3">Running SWIG in C mode</a>
-<li><a href="#Chicken_nn4">Running SWIG in C++ mode</a>
-</ul>
-<li><a href="#Chicken_nn5">Code Generation</a>
-<ul>
-<li><a href="#Chicken_nn6">Naming Conventions</a>
-<li><a href="#Chicken_nn7">Modules</a>
-<li><a href="#Chicken_nn8">Constants and Variables</a>
-<li><a href="#Chicken_nn9">Functions</a>
-<li><a href="#Chicken_nn10">Exceptions</a>
-</ul>
-<li><a href="#Chicken_nn11">TinyCLOS</a>
-<li><a href="#Chicken_nn12">Linkage</a>
-<ul>
-<li><a href="#Chicken_nn13">Static binary or shared library linked at compile time</a>
-<li><a href="#Chicken_nn14">Building chicken extension libraries</a>
-<li><a href="#Chicken_nn15">Linking multiple SWIG modules with TinyCLOS</a>
-</ul>
-<li><a href="#Chicken_nn16">Typemaps</a>
-<li><a href="#Chicken_nn17">Pointers</a>
-<ul>
-<li><a href="#Chicken_collection">Garbage collection</a>
-</ul>
-<li><a href="#Chicken_nn18">Unsupported features and known problems</a>
-<ul>
-<li><a href="#Chicken_nn19">TinyCLOS problems with Chicken version &lt;= 1.92</a>
-</ul>
-</ul>
-</div>
-<!-- INDEX -->
-
-
-
-    <p>
-      This chapter describes SWIG's support of CHICKEN.  CHICKEN is a
-      Scheme-to-C compiler supporting most of the language features as
-      defined in the <i>Revised^5 Report on Scheme</i>.  Its main
-      attributes are that it
-    </p>
-
-      <ol>
-        <li>generates portable C code</li>
-        <li>includes a customizable interpreter</li>
-        <li>links to C libraries with a simple Foreign Function Interface</li>
-        <li>supports full tail-recursion and first-class continuations</li>
-      </ol>
-
-    <p>
-      When confronted with a large C library, CHICKEN users can use
-      SWIG to generate CHICKEN wrappers for the C library.  However,
-      the real advantages of using SWIG with CHICKEN are its
-      <strong>support for C++</strong> -- object-oriented code is
-      difficult to wrap by hand in CHICKEN -- and its <strong>typed
-      pointer representation</strong>, essential for C and C++
-      libraries involving structures or classes.
-
-    </p>
-
-<H2><a name="Chicken_nn2">23.1 Preliminaries</a></H2>
-
-
-    <p>
-      CHICKEN support was introduced to SWIG in version 1.3.18.  SWIG
-      relies on some recent additions to CHICKEN, which are only
-      present in releases of CHICKEN with version number
-      <strong>greater than or equal to 1.89</strong>.  
-      To use a chicken version between 1.40 and 1.89, see the <a href="#Chicken_collection">Garbage collection</a>
-      section below.
-    </p>
-
-      <p>
-      You may want to look at any of the examples in Examples/chicken/
-      directory for the basic steps to run SWIG CHICKEN.
-      </p>
-
-<H3><a name="Chicken_nn3">23.1.1 Running SWIG in C mode</a></H3>
-
-
-      <p>
-      To run SWIG CHICKEN in C mode, use
-      the -chicken option.
-      </p>
-
-      <div class="shell">
-        <pre>% swig -chicken example.i</pre>
-      </div>
-
-      <p>
-      To allow the wrapper to take advantage of future CHICKEN code
-      generation improvements, part of the wrapper is direct CHICKEN
-      function calls (<tt>example_wrap.c</tt>) and part is CHICKEN
-      Scheme (<tt>example.scm</tt>).  The basic Scheme code must
-      be compiled to C using your system's CHICKEN compiler or
-      both files can be compiled directly using the much simpler <tt>csc</tt>.
-      </p>
-
-      <div class="shell">
-<pre>
-% chicken example.scm -output-file oexample.c
-</pre>
-      </div>
-
-      <p>
-      So for the C mode of SWIG CHICKEN, <tt>example_wrap.c</tt> and
-      <tt>oexample.c</tt> are the files that must be compiled to
-      object files and linked into your project.
-      </p>
-
-<H3><a name="Chicken_nn4">23.1.2 Running SWIG in C++ mode</a></H3>
-
-
-      <p>
-      To run SWIG CHICKEN in C++ mode, use
-      the -chicken -c++ option.
-      </p>
-
-      <div class="shell">
-        <pre>% swig -chicken -c++ example.i</pre>
-      </div>
-
-      <p>
-      This will generate <tt>example_wrap.cxx</tt> and
-      <tt>example.scm</tt>.  The basic Scheme code must be
-      compiled to C using your system's CHICKEN compiler or
-      both files can be compiled directly using the much simpler <tt>csc</tt>.
-      </p>
-
-      <div class="shell">
-        <pre>% chicken example.scm -output-file oexample.c</pre>
-      </div>
-
-      <p>
-      So for the C++ mode of SWIG CHICKEN, <tt>example_wrap.cxx</tt>
-      and <tt>oexample.c</tt> are the files that must be compiled to
-      object files and linked into your project.
-      </p>
-
-<H2><a name="Chicken_nn5">23.2 Code Generation</a></H2>
-
-
-<H3><a name="Chicken_nn6">23.2.1 Naming Conventions</a></H3>
-
-
-    <p>
-      Given a C variable, function or constant declaration named
-      <tt>Foo_Bar</tt>, the declaration will be available
-      in CHICKEN as an identifier ending with
-      <tt>Foo-Bar</tt>.  That is, an underscore is converted
-      to a dash.
-    </p>
-
-    <p>
-      You may control what the CHICKEN identifier will be by using the
-      <tt>%rename</tt> SWIG directive in the SWIG interface file.
-    </p>
-
-<H3><a name="Chicken_nn7">23.2.2 Modules</a></H3>
-
-
-      <p>
-      The name of the module must be declared one of two ways:
-      <ul>
-        <li>Placing <tt>%module example</tt> in the SWIG interface
-        file.</li>
-        <li>Using <tt>-module example</tt> on the SWIG command
-        line.</li>
-      </ul>
-
-      <p>
-      The generated example.scm file then exports <code>(declare (unit modulename))</code>.
-      If you do not want SWIG to export the <code>(declare (unit modulename))</code>, pass
-      the -nounit option to SWIG.
-
-    <p>
-      CHICKEN will be able to access the module using the <code>(declare
-        (uses <i>modulename</i>))</code> CHICKEN Scheme form.
-    </p>
-
-<H3><a name="Chicken_nn8">23.2.3 Constants and Variables</a></H3>
-
-
-    <p>
-      Constants may be created using any of the four constructs in
-      the interface file:
-    </p>
-      <ol>
-        <li><code>#define MYCONSTANT1 ...</code></li>
-        <li><code>%constant int MYCONSTANT2 = ...</code></li>
-        <li><code>const int MYCONSTANT3 = ...</code></li>
-        <li><code>enum { MYCONSTANT4  = ... };</code></li>
-      </ol>
-
-    <p>
-      In all cases, the constants may be accessed from within CHICKEN
-      using the form <tt>(MYCONSTANT1)</tt>; that is, the constants
-      may be accessed using the read-only parameter form.
-    </p>
-
-    <p>
-      Variables are accessed using the full parameter form.
-      For example, to set the C variable "int my_variable;", use the
-      Scheme form <tt>(my-variable 2345)</tt>.  To get the C variable,
-      use <tt>(my-variable)</tt>.
-    </p>
-
-    <p>
-      The <tt>%feature("constasvar")</tt> can be applied to any constant
-      or immutable variable.  Instead of exporting the constant as
-      a function that must be called, the constant will appear as a
-      scheme variable.  This causes the generated .scm file to just contain the code
-      <tt>(set! MYCONSTANT1 (MYCONSTANT1))</tt>. See 
-      <a href="Customization.html#Customization_features">Features and the %feature directive</a>
-      for info on how to apply the %feature.
-    </p>
-
-<H3><a name="Chicken_nn9">23.2.4 Functions</a></H3>
-
-
-    <p>
-      C functions declared in the SWIG interface file will have
-      corresponding CHICKEN Scheme procedures.  For example, the C
-      function "int sqrt(double x);" will be available using the
-      Scheme form <tt>(sqrt 2345.0)</tt>.  A <code>void</code> return
-      value will give C_SCHEME_UNDEFINED as a result.
-    </p>
-    <p>
-      A function may return more than one value by using the
-      <code>OUTPUT</code> specifier (see Lib/chicken/typemaps.i).
-      They will be returned as multiple values using <code>(values)</code> if there is more than one
-      result (that is, a non-void return value and at least one argout
-      parameter, or a void return value and at least two argout
-      parameters).  The return values can then be accessed with <code>(call-with-values)</code>.
-    </p>
-
-<H3><a name="Chicken_nn10">23.2.5 Exceptions</a></H3>
-
-
-     <p>The SWIG chicken module has support for exceptions thrown from
-     C or C++ code to be caught in scheme.  
-     See <a href="Customization.html#Customization_exception">Exception handling with %exception</a>
-     for more information about declaring exceptions in the interface file.
-     </p>
-
-     <p>Chicken supports both the <code>SWIG_exception(int code, const char *msg)</code> interface
-     as well as a <code>SWIG_ThrowException(C_word val)</code> function for throwing exceptions from
-     inside the %exception blocks.  <code>SWIG_exception</code> will throw a list consisting of the code
-     (as an integer) and the message.  Both of these will throw an exception using <code>(abort)</code>,
-     which can be handled by <code>(handle-exceptions)</code>.  See
-     the Chicken manual on Exceptions
-     and <a href="http://srfi.schemers.org/srfi-12/srfi-12.html">SFRI-12</a>.  Since the exception values are thrown
-     directly, if <code>(condition-case)</code> is used to catch an exception the exception will come through in the <code>val ()</code> case.
-     </p>
-
-     <p>The following simple module</p>
-     
-<div class="code"><pre>
-%module exception_test
-
-%inline %{
-  void test_throw(int i) throws (int) { 
-    if (i == 1) throw 15; 
-  }
-%}
-</pre></div>
-
-     <p>could be run with</p>
-
-<div class="targetlang"><pre>
-(handle-exceptions exvar 
-  (if (= exvar 15)
-    (print "Correct!") 
-    (print "Threw something else " exvar))
-  (test-throw 1))
-</pre></div>
-
-
-<H2><a name="Chicken_nn11">23.3 TinyCLOS</a></H2>
-
-
-      <p>
-      The author of TinyCLOS, Gregor Kiczales, describes TinyCLOS as:
-      "Tiny CLOS is a Scheme implementation of a 'kernelized' CLOS, with a
-      metaobject protocol. The implementation is even simpler than
-      the simple CLOS found in 'The Art of the Metaobject Protocol',
-      weighing in at around 850 lines of code, including (some)
-      comments and documentation."
-      </p>
-
-      <p>
-      Almost all good Scheme books describe how to use metaobjects and
-      generic procedures to implement an object-oriented Scheme
-      system.  Please consult a Scheme book if you are unfamiliar
-      with the concept.
-      </p>
-
-      <p>
-
-      CHICKEN has a modified version of TinyCLOS, which SWIG CHICKEN
-      uses if the -proxy argument is given.  If -proxy is passed, then
-      the generated example.scm file will contain TinyCLOS class definitions.
-      A class named Foo is declared as &lt;Foo&gt;, and each member variable
-      is allocated a slot.  Member functions are exported as generic functions.
-
-      <p>
-      
-      Primitive symbols and functions (the interface that would be presented if
-      -proxy was not passed) are hidden and no longer accessible.  If the -unhideprimitive
-      command line argument is passed to SWIG, then the primitive symbols will be
-      available, but each will be prefixed by the string "primitive:"
-
-      <p>
-
-      The exported symbol names can be controlled with the -closprefix and -useclassprefix arguments.
-      If -useclassprefix is passed to SWIG, every member function will be generated with the class name
-      as a prefix.  If the -closprefix mymod: argument is passed to SWIG, then the exported functions will
-      be prefixed by the string "mymod:".  If -useclassprefix is passed, -closprefix is ignored.
-      
-      </p>
-
-<H2><a name="Chicken_nn12">23.4 Linkage</a></H2>
-
-
-    <p>
-      Please refer to <em>CHICKEN - A practical and portable Scheme
-      system - User's manual</em> for detailed help on how to link
-      object files to create a CHICKEN Scheme program.  Briefly, to
-      link object files, be sure to add <tt>`chicken-config
-      -extra-libs -libs`</tt> or <tt>`chicken-config -shared
-      -extra-libs -libs`</tt>to your linker options.  Use the
-      <tt>-shared</tt> option if you want to create a dynamically
-      loadable module.  You might also want to use the much simpler
-      <tt>csc</tt> or <tt>csc.bat</tt>.
-    </p>
-
-    <p>Each scheme file that is generated
-   by SWIG contains <code>(declare (uses <i>modname</i>))</code>.  This means that to load the
-   module from scheme code, the code must include <code>(declare (uses <i>modname</i>))</code>.
-   </p>
-
-
-<H3><a name="Chicken_nn13">23.4.1 Static binary or shared library linked at compile time</a></H3>
-
-
-   <p>We can easily use csc to build a static binary.</p>
-
-<div class="shell">
-<pre>
-$ swig -chicken example.i
-$ csc -v example.scm example_impl.c example_wrap.c test_script.scm -o example
-$ ./example
-</pre>
-</div>
-
-<p>Similar to the above, any number of <tt>module.scm</tt> files could be compiled
-into a shared library, and then that shared library linked when compiling the
-main application.</p>
-
-<div class="shell">
-<pre>
-$ swig -chicken example.i
-$ csc -sv example.scm example_wrap.c example_impl.c -o example.so
-</pre>
-</div>
-
-<p>The <tt>example.so</tt> file can then linked with <tt>test_script.scm</tt> when it
-is compiled, in which case <tt>test_script.scm</tt> must have <code>(declare (uses example))</code>.
-Multiple SWIG modules could have been linked into <tt>example.so</tt> and each
-one accessed with a <code>(declare (uses ... ))</code>.
-</p>
-
-<div class="shell">
-<pre>
-$ csc -v test_script.scm -lexample
-</pre>
-</div>
-
-<p>An alternative is that the test_script.scm can have the code <code>(load-library 'example "example.so")</code>,
-in which case the test script does not need to be linked with example.so.  The test_script.scm file can then
-be run with <tt>csi</tt>.
-</p>
-
-<H3><a name="Chicken_nn14">23.4.2 Building chicken extension libraries</a></H3>
-
-
-<p>Building a shared library like in the above section only works if the library
-is linked at compile time with a script containing <code>(declare (uses ...))</code> or is
-loaded explicitly with <code>(load-library 'example "example.so")</code>. It is
-not the format that CHICKEN expects for extension libraries and eggs.  The problem is the
-<code>(declare (unit <i>modname</i>))</code> inside the <tt>modname.scm</tt> file.  There are
-two possible solutions to this.</p>
-
-<p>First, SWIG accepts a <tt>-nounit</tt> argument, in which case the <code>(declare (unit <i>modname</i>))</code>
-is not generated.  Then, the <tt>modname.scm</tt> and <tt>modname_wrap.c</tt> files <b>must</b> be compiled into
-their own shared library.</p>
-
-<div class="shell">
-<pre>
-$ csc -sv modname.scm modname_wrap.c modname_impl.c -o modname.so
-</pre>
-</div>
-
-<p>This library can then be loaded by scheme code with the <code>(require 'modname)</code> function.
-See the
-Loading-extension-libraries in the eval unit inside the CHICKEN manual for more information.</p>
-
-<p>Another alternative is to run SWIG normally and create a scheme file that contains <code>(declare (uses <i>modname</i>))</code>
-and then compile that file into the shared library as well.  For example, inside the <tt>mod_load.scm</tt> file,</p>
-
-<div class="targetlang">
-<pre>
-(declare (uses mod1))
-(declare (uses mod2))
-</pre>
-</div>
-
-<p>Which would then be compiled with</p>
-
-<div class="shell">
-<pre>
-$ swig -chicken mod1.i
-$ swig -chicken mod2.i
-$ csc -sv mod_load.scm mod1.scm mod2.scm mod1_wrap.c mod2_wrap.c mod1_impl.c mod2_impl.c -o mod.so
-</pre>
-</div>
-
-<p>Then the extension library can be loaded with <code>(require 'mod)</code>.  As we can see here,
-<tt>mod_load.scm</tt> contains the code that gets executed when the module is loaded.  All this code
-does is load both mod1 and mod2.  As we can see, this technique is more useful when you want to
-combine a few SWIG modules into one chicken extension library, especially if modules are related by
-<code>%import</code></p>
-
-<p>In either method, the files that are compiled into the shared library could also be
-packaged into an egg.  The <tt>mod1_wrap.c</tt> and <tt>mod2_wrap.c</tt> files that are created by SWIG
-are stand alone and do not need SWIG to be installed to be compiled.  Thus the egg could be
-distributed and used by anyone, even if SWIG is not installed.</p>
-
-<p>See the <tt>Examples/chicken/egg</tt> directory in the SWIG source for an example that builds
-two eggs, one using the first method and one using the second method.</p>
-
-<H3><a name="Chicken_nn15">23.4.3 Linking multiple SWIG modules with TinyCLOS</a></H3>
-
-
-<p>Linking together multiple modules that share type information using the <code>%import</code>
-directive while also using <tt>-proxy</tt> is more complicated.  For example, if <tt>mod2.i</tt> imports <tt>mod1.i</tt>, then the
-<tt>mod2.scm</tt> file contains references to symbols declared in <tt>mod1.scm</tt>,
-and thus a <code>(declare (uses <i>mod1</i>))</code> or <code>(require '<i>mod1</i>)</code> must be exported
-to the top of <tt>mod2.scm</tt>.  By default, when SWIG encounters an <code>%import "modname.i"</code> directive,
-it exports <code>(declare (uses <i>modname</i>))</code> into the scm file.  This works fine unless mod1 was compiled with
-the <tt>-nounit</tt> argument or was compiled into an extension library with other modules under a different name.</p>
-
-<p>One option is to override the automatic generation of <code>(declare (uses mod1))</code>
-by passing the <tt>-noclosuses</tt> option to SWIG when compiling <tt>mod2.i</tt>.
-SWIG then provides the <code>%insert(closprefix) %{ %}</code> directive.  Any scheme code inside that directive is inserted into the
-generated .scm file, and if <tt>mod1</tt> was compiled with <tt>-nounit</tt>, the directive should contain <code>(require 'mod1)</code>.
-This option allows for mixed loading as well, where some modules are imported with <code>(declare (uses <i>modname</i>))</code>
-(which means they were compiled without -nounit) and some are imported with <code>(require 'modname)</code>.</p>
-
-<p>The other option is to use the second idea in the above section.  Compile all the modules normally, without any
-<code>%insert(closprefix)</code>, <tt>-nounit</tt>, or <tt>-noclosuses</tt>.  Then the modules will import each other correctly
-with <code>(declare (uses ...))</code>.
-To create an extension library or an egg, just create a <tt>module_load.scm</tt> file that <code>(declare (uses ...))</code>
-all the modules.</p>
-
-<H2><a name="Chicken_nn16">23.5 Typemaps</a></H2>
-
-
-    <p>
-      The Chicken module handles all types via typemaps. This information is
-      read from <code>Lib/chicken/typemaps.i</code> and
-      <code>Lib/chicken/chicken.swg</code>.
-    </p>
-
-<H2><a name="Chicken_nn17">23.6 Pointers</a></H2>
-
-
-    <p>
-      For pointer types, SWIG uses CHICKEN tagged pointers.
-
-      A tagged pointer is an ordinary CHICKEN pointer with an
-      extra slot for a void *.  With SWIG
-      CHICKEN, this void * is a pointer to a type-info
-      structure.  So each pointer used as input or output from
-      the SWIG-generated CHICKEN wrappers will have type
-      information attached to it.  This will let the wrappers
-      correctly determine which method should be called
-      according to the object type hierarchy exposed in the SWIG
-      interface files.
-    </p>
-    <p>
-      To construct a Scheme object from a C pointer, the wrapper code
-      calls the function 
-      <code>SWIG_NewPointerObj(void *ptr, swig_type_info *type, int owner)</code>,
-      The function that calls <code>SWIG_NewPointerObj</code> must have a variable declared
-      <code>C_word *known_space = C_alloc(C_SIZEOF_SWIG_POINTER);</code>
-      It is ok to call <code>SWIG_NewPointerObj</code> more than once, 
-      just make sure known_space has enough space for all the created pointers.
-    </p>
-    <p>
-      To get the pointer represented by a CHICKEN tagged pointer, the
-      wrapper code calls the function 
-      <code>SWIG_ConvertPtr(C_word s, void **result, swig_type_info *type, int flags)</code>,
-      passing a pointer to a struct representing the expected pointer
-      type. flags is either zero or SWIG_POINTER_DISOWN (see below).
-    </p>
-
-<H3><a name="Chicken_collection">23.6.1 Garbage collection</a></H3>
-
-
-  <p>If the owner flag passed to <code>SWIG_NewPointerObj</code> is 1, <code>NewPointerObj</code> will add a
-     finalizer to the type which will call the destructor or delete method of
-     that type.  The destructor and delete functions are no longer exported for
-     use in scheme code, instead SWIG and chicken manage pointers.
-  In situations where SWIG knows that a function is returning a type that should
-  be garbage collected, SWIG will automatically set the owner flag to 1.  For other functions,
-  the <code>%newobject</code> directive must be specified for functions whose return values
-  should be garbage collected.  See 
-  <a href="Customization.html#Customization_ownership">Object ownership and %newobject</a> for more information.
-  </p>
-
-  <p>In situations where a C or C++ function will assume ownership of a pointer, and thus
-  chicken should no longer garbage collect it, SWIG provides the <code>DISOWN</code> input typemap.
-  After applying this typemap (see the <a href="Typemaps.html#Typemaps">Typemaps chapter</a> for more information on how to apply typemaps),
-  any pointer that gets passed in will no longer be garbage collected.  
-  An object is disowned by passing the <code>SWIG_POINTER_DISOWN</code> flag to <code>SWIG_ConvertPtr</code>.
-  <b>Warning:</b> Since the lifetime of the object is now controlled by the underlying code, the object might
-  get deleted while the scheme code still holds a pointer to it.  Further use of this pointer
-  can lead to a crash.
-  </p>
-
-  <p>Adding a finalizer function from C code was added to chicken in the 1.89 release, so garbage collection
-  does not work for chicken versions below 1.89.  If you would like the SWIG generated code to work with
-  chicken 1.40 to 1.89, pass the <code>-nocollection</code> argument to SWIG.  This will not export code
-  inside the _wrap.c file to register finalizers, and will then export destructor functions which
-  must be called manually.
-  </p>
-
-<H2><a name="Chicken_nn18">23.7 Unsupported features and known problems</a></H2>
-
-
-    <ul>
-      <li>No director support.</li>
-      <li>No support for c++ standard types like std::vector.</li>
-      <li>The TinyCLOS wrappers for overloaded functions will not work correctly when using 
-          <a href="SWIGPlus.html#SWIGPlus_default_args">%feature(compactdefaultargs)</a>.</li>
-    </ul>
-
-<H3><a name="Chicken_nn19">23.7.1 TinyCLOS problems with Chicken version &lt;= 1.92</a></H3>
-
-
-    <p>In Chicken versions equal to or below 1.92, TinyCLOS has a limitation such that generic methods do not properly work on methods
-    with different number of specializers: TinyCLOS assumes that every method added to a generic function
-    will have the same number of specializers. SWIG generates functions with different lengths of specializers
-    when C/C++ functions are overloaded.  For example, the code</p>
-
-<div class="code">
-<pre>
-class Foo {};
-int foo(int a, Foo *b);
-int foo(int a);
-</pre></div>
-
-<p>will produce scheme code</p>
-
-<div class="targetlang">
-<pre>
-(define-method (foo (arg0 &lt;top&gt;) (arg1 &lt;Foo&gt;)) (<i>call primitive function</i>))
-(define-method (foo (arg0 &lt;top&gt;)) (<i>call primitive function</i>))
-</pre></div>
-
-<p>Using unpatched TinyCLOS, the second <code>(define-method)</code> will replace the first one,
-so calling <code>(foo 3 f)</code> will produce an error.</p>
-
-<p>There are three solutions to this.  The easist is to upgrade to the latest Chicken version.  Otherwise, the
-file <tt>Lib/chicken/tinyclos-multi-generic.patch</tt> in the SWIG source contains a patch against
-tinyclos.scm inside the 1.92 chicken source to add support into TinyCLOS for multi-argument generics.  (This patch was accepted into Chicken)
-This requires chicken to be rebuilt and custom install of chicken.  An alternative is the <tt>Lib/chicken/multi-generic.scm</tt>
-file in the SWIG source.  This file can be loaded after TinyCLOS is loaded, and it will override some functions
-inside TinyCLOS to correctly support multi-argument generics.  Please see the comments at the top of both files for more information.</p>
-
-  </body>
-</html>

Doc/Manual/Contents.html

@@ -91,16 +91,16 @@
 </ul>
 <li><a href="Windows.html#Windows_other_compilers">Instructions for using the Examples with other compilers</a>
 </ul>
-<li><a href="Windows.html#Windows_cygwin_mingw">SWIG on Cygwin and MinGW</a>
-<ul>
 <li><a href="Windows.html#Windows_swig_exe">Building swig.exe on Windows</a>
 <ul>
+<li><a href="Windows.html#Windows_cmake">Building swig.exe using CMake</a>
+<li><a href="Windows.html#Windows_msys2">Building swig.exe using MSYS2</a>
 <li><a href="Windows.html#Windows_mingw_msys">Building swig.exe using MinGW and MSYS</a>
 <li><a href="Windows.html#Windows_cygwin">Building swig.exe using Cygwin</a>
-<li><a href="Windows.html#Windows_building_alternatives">Building swig.exe alternatives</a>
-</ul>
+<ul>
 <li><a href="Windows.html#Windows_examples_cygwin">Running the examples on Windows using Cygwin</a>
 </ul>
+</ul>
 <li><a href="Windows.html#Windows_interface_file">Microsoft extensions and other Windows quirks</a>
 </ul>
 </div>
@@ -171,6 +171,7 @@
 <li><a href="SWIG.html#SWIG_rename_ignore">Renaming and ignoring declarations</a>
 <ul>
 <li><a href="SWIG.html#SWIG_nn29">Simple renaming of specific identifiers</a>
+<li><a href="SWIG.html#SWIG_ignore">Ignoring identifiers</a>
 <li><a href="SWIG.html#SWIG_advanced_renaming">Advanced renaming support</a>
 <li><a href="SWIG.html#SWIG_limiting_renaming">Limiting global renaming rules</a>
 <li><a href="SWIG.html#SWIG_chosen_unignore">Ignoring everything then wrapping a few selected symbols</a>
@@ -250,12 +251,16 @@
 </ul>
 <li><a href="SWIGPlus.html#SWIGPlus_nn28">Overloaded operators</a>
 <li><a href="SWIGPlus.html#SWIGPlus_class_extension">Class extension</a>
+<ul>
+<li><a href="SWIGPlus.html#SWIGPlus_replacing_methods">Replacing class methods</a>
+</ul>
 <li><a href="SWIGPlus.html#SWIGPlus_nn30">Templates</a>
 <ul>
 <li><a href="SWIGPlus.html#SWIGPlus_template_directive">The %template directive</a>
 <li><a href="SWIGPlus.html#SWIGPlus_template_functions">Function templates</a>
 <li><a href="SWIGPlus.html#SWIGPlus_template_classes">Default template arguments</a>
 <li><a href="SWIGPlus.html#SWIGPlus_template_class_inheritance">Template base classes</a>
+<li><a href="SWIGPlus.html#SWIGPlus_template_empty">Empty template instantiation</a>
 <li><a href="SWIGPlus.html#SWIGPlus_template_specialization">Template specialization</a>
 <li><a href="SWIGPlus.html#SWIGPlus_template_member">Member templates</a>
 <li><a href="SWIGPlus.html#SWIGPlus_template_scoping">Scoping and templates</a>
@@ -293,6 +298,11 @@
 <li><a href="CPlusPlus11.html#CPlusPlus11_core_language_changes">Core language changes</a>
 <ul>
 <li><a href="CPlusPlus11.html#CPlusPlus11_rvalue_reference_and_move_semantics">Rvalue reference and move semantics</a>
+<ul>
+<li><a href="CPlusPlus11.html#CPlusPlus11_rvalue_reference_inputs">Rvalue reference inputs</a>
+<li><a href="CPlusPlus11.html#CPlusPlus11_rvalue_reference_outputs">Rvalue reference outputs</a>
+<li><a href="CPlusPlus11.html#CPlusPlus11_move_only">Movable and move-only types by value</a>
+</ul>
 <li><a href="CPlusPlus11.html#CPlusPlus11_generalized_constant_expressions">Generalized constant expressions</a>
 <li><a href="CPlusPlus11.html#CPlusPlus11_extern_template">Extern template</a>
 <li><a href="CPlusPlus11.html#CPlusPlus11_initializer_lists">Initializer lists</a>
@@ -349,6 +359,7 @@
 <li><a href="CPlusPlus14.html#CPlusPlus14_core_language_changes">Core language changes</a>
 <ul>
 <li><a href="CPlusPlus14.html#CPlusPlus14_binary_literals">Binary integer literals</a>
+<li><a href="CPlusPlus14.html#CPlusPlus14_return_type_deduction">Return type deduction</a>
 </ul>
 <li><a href="CPlusPlus14.html#CPlusPlus14_standard_library_changes">Standard library changes</a>
 </ul>
@@ -372,7 +383,24 @@
 </div>
 <!-- INDEX -->
 
-<h3><a href="Preprocessor.html#Preprocessor">10 Preprocessing</a></h3>
+<h3><a href="CPlusPlus20.html#CPlusPlus20">10 SWIG and C++20</a></h3>
+
+<!-- INDEX -->
+<div class="sectiontoc">
+<ul>
+<li><a href="CPlusPlus20.html#CPlusPlus20_introduction">Introduction</a>
+<li><a href="CPlusPlus20.html#CPlusPlus20_core_language_changes">Core language changes</a>
+<ul>
+<li><a href="CPlusPlus20.html#CPlusPlus20_spaceship_operator">Spaceship operator</a>
+<li><a href="CPlusPlus20.html#CPlusPlus20_lambda_templates">Lambda templates</a>
+<li><a href="CPlusPlus20.html#CPlusPlus20_constexpr_destructors">Constexpr destructors</a>
+</ul>
+<li><a href="CPlusPlus20.html#CPlusPlus20_standard_library_changes">Standard library changes</a>
+</ul>
+</div>
+<!-- INDEX -->
+
+<h3><a href="Preprocessor.html#Preprocessor">11 Preprocessing</a></h3>
 
 <!-- INDEX -->
 <div class="sectiontoc">
@@ -395,7 +423,7 @@
 </div>
 <!-- INDEX -->
 
-<h3><a href="Library.html#Library">11 SWIG library</a></h3>
+<h3><a href="Library.html#Library">12 SWIG library</a></h3>
 
 <!-- INDEX -->
 <div class="sectiontoc">
@@ -403,6 +431,7 @@
 <li><a href="Library.html#Library_nn2">The %include directive and library search path</a>
 <li><a href="Library.html#Library_nn3">C arrays and pointers</a>
 <ul>
+<li><a href="Library.html#Library_argcargv">argcargv.i</a>
 <li><a href="Library.html#Library_nn4">cpointer.i</a>
 <li><a href="Library.html#Library_carrays">carrays.i</a>
 <li><a href="Library.html#Library_nn6">cmalloc.i</a>
@@ -418,6 +447,7 @@
 <li><a href="Library.html#Library_stl_cpp_library">STL/C++ library</a>
 <ul>
 <li><a href="Library.html#Library_std_string">std::string</a>
+<li><a href="Library.html#Library_std_string_view">std::string_view</a>
 <li><a href="Library.html#Library_std_vector">std::vector</a>
 <li><a href="Library.html#Library_stl_exceptions">STL exceptions</a>
 <li><a href="Library.html#Library_std_shared_ptr">shared_ptr smart pointer</a>
@@ -428,17 +458,22 @@
 <li><a href="Library.html#Library_shared_ptr_templates">shared_ptr and templates</a>
 <li><a href="Library.html#Library_shared_ptr_directors">shared_ptr and directors</a>
 </ul>
+<li><a href="Library.html#Library_std_unique_ptr">unique_ptr smart pointer</a>
 <li><a href="Library.html#Library_std_auto_ptr">auto_ptr smart pointer</a>
 </ul>
 <li><a href="Library.html#Library_nn16">Utility Libraries</a>
 <ul>
 <li><a href="Library.html#Library_nn17">exception.i</a>
+<li><a href="Library.html#Library_attributes">attribute.i</a>
+<ul>
+<li><a href="Library.html#Library_attribute_templates">%attribute and C++ templates</a>
+</ul>
 </ul>
 </ul>
 </div>
 <!-- INDEX -->
 
-<h3><a href="Arguments.html#Arguments">12 Argument Handling</a></h3>
+<h3><a href="Arguments.html#Arguments">13 Argument Handling</a></h3>
 
 <!-- INDEX -->
 <div class="sectiontoc">
@@ -461,7 +496,7 @@
 </div>
 <!-- INDEX -->
 
-<h3><a href="Typemaps.html#Typemaps">13 Typemaps</a></h3>
+<h3><a href="Typemaps.html#Typemaps">14 Typemaps</a></h3>
 
 <!-- INDEX -->
 <div class="sectiontoc">
@@ -503,6 +538,7 @@
 <ul>
 <li><a href="Typemaps.html#Typemaps_special_macro_descriptor">$descriptor(type)</a>
 <li><a href="Typemaps.html#Typemaps_special_macro_typemap">$typemap(method, typepattern)</a>
+<li><a href="Typemaps.html#Typemaps_special_macro_typemap_attribute">$typemap(method:attribute, typepattern)</a>
 </ul>
 <li><a href="Typemaps.html#Typemaps_special_variable_attributes">Special variables and typemap attributes</a>
 <li><a href="Typemaps.html#Typemaps_special_variables_and_macros">Special variables combined with special variable macros</a>
@@ -555,7 +591,7 @@
 </div>
 <!-- INDEX -->
 
-<h3><a href="Customization.html#Customization">14 Customization Features</a></h3>
+<h3><a href="Customization.html#Customization">15 Customization Features</a></h3>
 
 <!-- INDEX -->
 <div class="sectiontoc">
@@ -583,7 +619,7 @@
 </div>
 <!-- INDEX -->
 
-<h3><a href="Contract.html#Contract">15 Contracts</a></h3>
+<h3><a href="Contract.html#Contract">16 Contracts</a></h3>
 
 <!-- INDEX -->
 <div class="sectiontoc">
@@ -596,7 +632,7 @@
 </div>
 <!-- INDEX -->
 
-<h3><a href="Varargs.html#Varargs">16 Variable Length Arguments</a></h3>
+<h3><a href="Varargs.html#Varargs">17 Variable Length Arguments</a></h3>
 
 <!-- INDEX -->
 <div class="sectiontoc">
@@ -614,7 +650,7 @@
 </div>
 <!-- INDEX -->
 
-<h3><a href="Doxygen.html#Doxygen">17 SWIG and Doxygen Translation</a></h3>
+<h3><a href="Doxygen.html#Doxygen">18 SWIG and Doxygen Translation</a></h3>
 
 <!-- INDEX -->
 <div class="sectiontoc">
@@ -662,7 +698,7 @@
 </div>
 <!-- INDEX -->
 
-<h3><a href="Warnings.html#Warnings">18 Warning Messages</a></h3>
+<h3><a href="Warnings.html#Warnings">19 Warning Messages</a></h3>
 
 <!-- INDEX -->
 <div class="sectiontoc">
@@ -691,7 +727,7 @@
 </div>
 <!-- INDEX -->
 
-<h3><a href="Modules.html#Modules">19 Working with Modules</a></h3>
+<h3><a href="Modules.html#Modules">20 Working with Modules</a></h3>
 
 <!-- INDEX -->
 <div class="sectiontoc">
@@ -707,7 +743,7 @@
 </div>
 <!-- INDEX -->
 
-<h3><a href="CCache.html#CCache">20 Using SWIG with ccache - ccache-swig(1) manpage</a></h3>
+<h3><a href="CCache.html#CCache">21 Using SWIG with ccache - ccache-swig(1) manpage</a></h3>
 
 <!-- INDEX -->
 <div class="sectiontoc">
@@ -733,7 +769,7 @@
 </div>
 <!-- INDEX -->
 
-<h3><a href="Android.html#Android">21 SWIG and Android</a></h3>
+<h3><a href="Android.html#Android">22 SWIG and Android</a></h3>
 
 <!-- INDEX -->
 <div class="sectiontoc">
@@ -751,7 +787,7 @@
 </div>
 <!-- INDEX -->
 
-<h3><a href="CSharp.html#CSharp">22 SWIG and C#</a></h3>
+<h3><a href="CSharp.html#CSharp">23 SWIG and C#</a></h3>
 
 <!-- INDEX -->
 <div class="sectiontoc">
@@ -762,7 +798,12 @@
 <li><a href="CSharp.html#CSharp_commandline">Additional command line options</a>
 </ul>
 <li><a href="CSharp.html#CSharp_differences_java">Differences to the Java module</a>
+<li><a href="CSharp.html#CSharp_type_mapping">Type mapping</a>
+<ul>
+<li><a href="CSharp.html#CSharp_primitive_types">Primitive types</a>
+<li><a href="CSharp.html#CSharp_other_type_mappings">Other types</a>
 <li><a href="CSharp.html#CSharp_void_pointers">Void pointers</a>
+</ul>
 <li><a href="CSharp.html#CSharp_arrays">C# Arrays</a>
 <ul>
 <li><a href="CSharp.html#CSharp_arrays_swig_library">The SWIG C arrays library</a>
@@ -783,6 +824,7 @@
 <li><a href="CSharp.html#CSharp_director_caveats">Director caveats</a>
 </ul>
 <li><a href="CSharp.html#CSharp_multiple_modules">Multiple modules</a>
+<li><a href="CSharp.html#CSharp_named_arguments">C# named and optional arguments</a>
 <li><a href="CSharp.html#CSharp_typemap_examples">C# Typemap examples</a>
 <ul>
 <li><a href="CSharp.html#CSharp_memory_management_member_variables">Memory management when returning references to member variables</a>
@@ -799,7 +841,7 @@
 </div>
 <!-- INDEX -->
 
-<h3><a href="D.html#D">23 SWIG and D</a></h3>
+<h3><a href="D.html#D">24 SWIG and D</a></h3>
 
 <!-- INDEX -->
 <div class="sectiontoc">
@@ -816,7 +858,11 @@
 <li><a href="D.html#D_code_injection_typemaps">Code injection typemaps</a>
 <li><a href="D.html#D_special_variables">Special variable macros</a>
 </ul>
+<li><a href="D.html#D_other_code_control">Other D code control features</a>
+<ul>
+<li><a href="D.html#D_module">D begin</a>
 <li><a href="D.html#D_features">D and %feature</a>
+</ul>
 <li><a href="D.html#D_pragmas">Pragmas</a>
 <li><a href="D.html#D_exceptions">D Exceptions</a>
 <li><a href="D.html#D_directors">D Directors</a>
@@ -833,7 +879,7 @@
 </div>
 <!-- INDEX -->
 
-<h3><a href="Go.html#Go">24 SWIG and Go</a></h3>
+<h3><a href="Go.html#Go">25 SWIG and Go</a></h3>
 
 <!-- INDEX -->
 <div class="sectiontoc">
@@ -857,6 +903,8 @@
 <li><a href="Go.html#Go_class_inheritance">Go Class Inheritance</a>
 </ul>
 <li><a href="Go.html#Go_templates">Go Templates</a>
+<li><a href="Go.html#Go_threads">Go and C/C++ Threads</a>
+<li><a href="Go.html#Go_exceptions">Go and C++ Exceptions</a>
 <li><a href="Go.html#Go_director_classes">Go Director Classes</a>
 <ul>
 <li><a href="Go.html#Go_director_example_cpp_code">Example C++ code</a>
@@ -877,7 +925,7 @@
 </div>
 <!-- INDEX -->
 
-<h3><a href="Guile.html#Guile">25 SWIG and Guile</a></h3>
+<h3><a href="Guile.html#Guile">26 SWIG and Guile</a></h3>
 
 <!-- INDEX -->
 <div class="sectiontoc">
@@ -913,7 +961,7 @@
 </div>
 <!-- INDEX -->
 
-<h3><a href="Java.html#Java">26 SWIG and Java</a></h3>
+<h3><a href="Java.html#Java">27 SWIG and Java</a></h3>
 
 <!-- INDEX -->
 <div class="sectiontoc">
@@ -1014,6 +1062,7 @@
 <li><a href="Java.html#Java_proxycode">Class extension with %proxycode</a>
 <li><a href="Java.html#Java_exception_handling">Exception handling with %exception and %javaexception</a>
 <li><a href="Java.html#Java_method_access">Method access with %javamethodmodifiers</a>
+<li><a href="Java.html#Java_begin">Java begin</a>
 </ul>
 <li><a href="Java.html#Java_tips_techniques">Tips and techniques</a>
 <ul>
@@ -1067,7 +1116,7 @@
 </div>
 <!-- INDEX -->
 
-<h3><a href="Javascript.html#Javascript">27 SWIG and Javascript</a></h3>
+<h3><a href="Javascript.html#Javascript">28 SWIG and Javascript</a></h3>
 
 <!-- INDEX -->
 <div class="sectiontoc">
@@ -1083,6 +1132,7 @@
 <ul>
 <li><a href="Javascript.html#Javascript_node_extensions">Creating node.js Extensions</a>
 <ul>
+<li><a href="Javascript.html#Javascript_using_yeoman">Using <code>yeoman</code> to generate a Node-API skeleton</a>
 <li><a href="Javascript.html#Javascript_troubleshooting">Troubleshooting</a>
 </ul>
 <li><a href="Javascript.html#Javascript_embedded_webkit">Embedded Webkit</a>
@@ -1104,12 +1154,13 @@
 <li><a href="Javascript.html#Javascript_emitter">Emitter</a>
 <li><a href="Javascript.html#Javascript_emitter_states">Emitter states</a>
 <li><a href="Javascript.html#Javascript_jsc_exceptions">Handling Exceptions in JavascriptCore</a>
+<li><a href="Javascript.html#Javascript_napi_exceptions">Handling Exceptions in Node-API</a>
 </ul>
 </ul>
 </div>
 <!-- INDEX -->
 
-<h3><a href="Lua.html#Lua">28 SWIG and Lua</a></h3>
+<h3><a href="Lua.html#Lua">29 SWIG and Lua</a></h3>
 
 <!-- INDEX -->
 <div class="sectiontoc">
@@ -1177,7 +1228,7 @@
 </div>
 <!-- INDEX -->
 
-<h3><a href="Octave.html#Octave">29 SWIG and Octave</a></h3>
+<h3><a href="Octave.html#Octave">30 SWIG and Octave</a></h3>
 
 <!-- INDEX -->
 <div class="sectiontoc">
@@ -1217,7 +1268,7 @@
 </div>
 <!-- INDEX -->
 
-<h3><a href="Perl5.html#Perl5">30 SWIG and Perl5</a></h3>
+<h3><a href="Perl5.html#Perl5">31 SWIG and Perl5</a></h3>
 
 <!-- INDEX -->
 <div class="sectiontoc">
@@ -1293,7 +1344,7 @@
 </div>
 <!-- INDEX -->
 
-<h3><a href="Php.html#Php">31 SWIG and PHP</a></h3>
+<h3><a href="Php.html#Php">32 SWIG and PHP</a></h3>
 
 <!-- INDEX -->
 <div class="sectiontoc">
@@ -1317,6 +1368,7 @@
 <li><a href="Php.html#Php_nn2_6_3">Static Member Variables</a>
 <li><a href="Php.html#Php_nn2_6_4">Static Member Functions</a>
 <li><a href="Php.html#Php_nn2_6_5">Specifying Implemented Interfaces</a>
+<li><a href="Php.html#Php_nn2_6_6">Dynamic Properties</a>
 </ul>
 <li><a href="Php.html#Php_nn2_7">PHP Pragmas, Startup and Shutdown code</a>
 </ul>
@@ -1334,7 +1386,7 @@
 </div>
 <!-- INDEX -->
 
-<h3><a href="Python.html#Python">32 SWIG and Python</a></h3>
+<h3><a href="Python.html#Python">33 SWIG and Python</a></h3>
 
 <!-- INDEX -->
 <div class="sectiontoc">
@@ -1393,6 +1445,7 @@
 <li><a href="Python.html#Python_nn37">Overhead and code bloat</a>
 <li><a href="Python.html#Python_nn38">Typemaps</a>
 <li><a href="Python.html#Python_nn39">Miscellaneous</a>
+<li><a href="Python.html#Python_stable_abi">Stable ABI</a>
 </ul>
 <li><a href="Python.html#Python_nn40">Common customization features</a>
 <ul>
@@ -1422,7 +1475,7 @@
 </ul>
 <li><a href="Python.html#Python_nn58">Typemap Examples</a>
 <ul>
-<li><a href="Python.html#Python_nn59">Converting  Python list to a char ** </a>
+<li><a href="Python.html#Python_nn59">Converting a Python list to a char ** </a>
 <li><a href="Python.html#Python_nn60">Expanding a Python object into multiple arguments</a>
 <li><a href="Python.html#Python_nn61">Using typemaps to return arguments</a>
 <li><a href="Python.html#Python_nn62">Mapping Python tuples into small arrays</a>
@@ -1442,6 +1495,7 @@
 <li><a href="Python.html#Python_nn70">%feature("autodoc", "docstring")</a>
 </ul>
 <li><a href="Python.html#Python_nn71">%feature("docstring")</a>
+<li><a href="Python.html#Python_doxygen_docstrings">Doxygen comments</a>
 </ul>
 <li><a href="Python.html#Python_nn72">Python Packages</a>
 <ul>
@@ -1461,7 +1515,10 @@
 </ul>
 <li><a href="Python.html#Python_python3support">Python 3 Support</a>
 <ul>
-<li><a href="Python.html#Python_nn74">Function annotation</a>
+<li><a href="Python.html#Python_annotations">Python function annotations and variable annotations</a>
+<ul>
+<li><a href="Python.html#Python_annotations_c">C/C++ annotation types</a>
+</ul>
 <li><a href="Python.html#Python_nn75">Buffer interface</a>
 <li><a href="Python.html#Python_nn76">Abstract base classes</a>
 <li><a href="Python.html#Python_nn77">Byte string output conversion</a>
@@ -1476,7 +1533,7 @@
 </div>
 <!-- INDEX -->
 
-<h3><a href="R.html#R">33 SWIG and R</a></h3>
+<h3><a href="R.html#R">34 SWIG and R</a></h3>
 
 <!-- INDEX -->
 <div class="sectiontoc">
@@ -1495,7 +1552,7 @@
 </div>
 <!-- INDEX -->
 
-<h3><a href="Ruby.html#Ruby">34 SWIG and Ruby</a></h3>
+<h3><a href="Ruby.html#Ruby">35 SWIG and Ruby</a></h3>
 
 <!-- INDEX -->
 <div class="sectiontoc">
@@ -1633,7 +1690,7 @@
 </div>
 <!-- INDEX -->
 
-<h3><a href="Scilab.html#Scilab">35 SWIG and Scilab</a></h3>
+<h3><a href="Scilab.html#Scilab">36 SWIG and Scilab</a></h3>
 
 <!-- INDEX -->
 <div class="sectiontoc">
@@ -1696,13 +1753,14 @@
 <ul>
 <li><a href="Scilab.html#Scilab_generated_scripts_builder_script">Builder script</a>
 <li><a href="Scilab.html#Scilab_generated_scripts_loader_script">Loader script</a>
+<li><a href="Scilab.html#Scilab_generated_scripts_gateway">Gateway XML files</a>
 </ul>
 <li><a href="Scilab.html#Scilab_other_resources">Other resources</a>
 </ul>
 </div>
 <!-- INDEX -->
 
-<h3><a href="Tcl.html#Tcl">36 SWIG and Tcl</a></h3>
+<h3><a href="Tcl.html#Tcl">37 SWIG and Tcl</a></h3>
 
 <!-- INDEX -->
 <div class="sectiontoc">
@@ -1768,7 +1826,7 @@
 </div>
 <!-- INDEX -->
 
-<h3><a href="Mzscheme.html#Mzscheme">37 SWIG and MzScheme/Racket</a></h3>
+<h3><a href="Mzscheme.html#Mzscheme">38 SWIG and MzScheme/Racket</a></h3>
 
 <!-- INDEX -->
 <div class="sectiontoc">
@@ -1780,7 +1838,7 @@
 </div>
 <!-- INDEX -->
 
-<h3><a href="Ocaml.html#Ocaml">38 SWIG and OCaml</a></h3>
+<h3><a href="Ocaml.html#Ocaml">39 SWIG and OCaml</a></h3>
 
 <!-- INDEX -->
 <div class="sectiontoc">
@@ -1835,7 +1893,7 @@
 </div>
 <!-- INDEX -->
 
-<h3><a href="Extending.html#Extending">39 Extending SWIG to support new languages</a></h3>
+<h3><a href="Extending.html#Extending">40 Extending SWIG to support new languages</a></h3>
 
 <!-- INDEX -->
 <div class="sectiontoc">

Doc/Manual/Contract.html

@@ -7,7 +7,7 @@
 </head>
 
 <body bgcolor="#ffffff">
-<H1><a name="Contract">15 Contracts</a></H1>
+<H1><a name="Contract">16 Contracts</a></H1>
 <!-- INDEX -->
 <div class="sectiontoc">
 <ul>
@@ -39,7 +39,7 @@ When one of the rules is violated by a script, a runtime exception is
 generated rather than having the program continue to execute.
 </p>
 
-<H2><a name="Contract_nn2">15.1 The %contract directive</a></H2>
+<H2><a name="Contract_nn2">16.1 The %contract directive</a></H2>
 
 
 <p>
@@ -95,7 +95,7 @@ RuntimeError: Contract violation: require: (arg1&gt;=0)
 </pre>
 </div>
 
-<H2><a name="Contract_nn3">15.2 %contract and classes</a></H2>
+<H2><a name="Contract_nn3">16.2 %contract and classes</a></H2>
 
 
 <p>
@@ -174,7 +174,7 @@ specified for the derived class all must hold.  In the above example,
 this means that both the arguments to <tt>Spam::bar</tt> must be positive.
 </p>
 
-<H2><a name="Contract_nn4">15.3 Constant aggregation and %aggregate_check</a></H2>
+<H2><a name="Contract_nn4">16.3 Constant aggregation and %aggregate_check</a></H2>
 
 
 <p>
@@ -263,7 +263,7 @@ Regrettably, there is no automatic way to perform similar checks with enums valu
 release.
 </p>
 
-<H2><a name="Contract_nn5">15.4 Notes</a></H2>
+<H2><a name="Contract_nn5">16.4 Notes</a></H2>
 
 
 <p>

Doc/Manual/Customization.html

@@ -7,7 +7,7 @@
 </head>
 
 <body bgcolor="#ffffff">
-<H1><a name="Customization">14 Customization Features</a></H1>
+<H1><a name="Customization">15 Customization Features</a></H1>
 <!-- INDEX -->
 <div class="sectiontoc">
 <ul>
@@ -46,7 +46,7 @@ of exception handling is presented.  Then, a more general-purpose
 customization mechanism known as "features" is described.
 </p>
 
-<H2><a name="Customization_exception">14.1 Exception handling with %exception</a></H2>
+<H2><a name="Customization_exception">15.1 Exception handling with %exception</a></H2>
 
 
 <p>
@@ -95,13 +95,7 @@ or <tt>%noexception</tt> with no code. For example:
 %exception;   // Deletes any previously defined handler
 </pre></div>
 
-<p>
-<b>Compatibility note:</b>  Previous versions of SWIG used a special directive <tt>%except</tt>
-for exception handling.   That directive is deprecated--<tt>%exception</tt>
-provides the same functionality, but is substantially more flexible.
-</p>
-
-<H3><a name="Customization_nn3">14.1.1 Handling exceptions in C code</a></H3>
+<H3><a name="Customization_nn3">15.1.1 Handling exceptions in C code</a></H3>
 
 
 <p>
@@ -169,7 +163,7 @@ Each target language has its own approach to creating a runtime error/exception
 and for Perl it is the <tt>croak</tt> method shown above.
 </p>
 
-<H3><a name="Customization_nn4">14.1.2 Exception handling with longjmp()</a></H3>
+<H3><a name="Customization_nn4">15.1.2 Exception handling with longjmp()</a></H3>
 
 
 <p>
@@ -245,7 +239,7 @@ Note: This implementation is only intended to illustrate the general idea.  To m
 modify it to handle nested <tt>try</tt> declarations.
 </p>
 
-<H3><a name="Customization_nn5">14.1.3 Handling C++ exceptions</a></H3>
+<H3><a name="Customization_nn5">15.1.3 Handling C++ exceptions</a></H3>
 
 
 <p>
@@ -280,7 +274,7 @@ class OutOfMemory {};
 </pre>
 </div>
 
-<H3><a name="Customization_allowexcept">14.1.4 Exception handlers for variables</a></H3>
+<H3><a name="Customization_allowexcept">15.1.4 Exception handlers for variables</a></H3>
 
 
 <p>
@@ -305,7 +299,7 @@ The <tt>%allowexception</tt> feature works like any other feature and so can be
 </pre>
 </div>
 
-<H3><a name="Customization_nn6">14.1.5 Defining different exception handlers</a></H3>
+<H3><a name="Customization_nn6">15.1.5 Defining different exception handlers</a></H3>
 
 
 <p>
@@ -432,17 +426,7 @@ to attach exceptions to specific parts of a header file. For example:
 </pre>
 </div>
 
-<p>
-<b>Compatibility note:</b> The <tt>%exception</tt> directive replaces
-the functionality provided by the deprecated "except" typemap.
-The typemap would allow exceptions to be thrown in the target 
-language based on the return type of a function and 
-was intended to be a mechanism for pinpointing specific
-declarations.  However, it never really worked that well and the new
-%exception directive is much better.
-</p>
-
-<H3><a name="Customization_exception_special_variables">14.1.6 Special variables for %exception</a></H3>
+<H3><a name="Customization_exception_special_variables">15.1.6 Special variables for %exception</a></H3>
 
 
 <p>
@@ -545,7 +529,7 @@ Below shows the expansions for the 1st of the overloaded <tt>something</tt> wrap
 </pre></div>
 
 
-<H3><a name="Customization_nn7">14.1.7 Using The SWIG exception library</a></H3>
+<H3><a name="Customization_nn7">15.1.7 Using The SWIG exception library</a></H3>
 
 
 <p>
@@ -600,7 +584,7 @@ SWIG_NullReferenceError
 The <tt>SWIG_exception()</tt> function can also be used in typemaps.
 </p>
 
-<H2><a name="Customization_ownership">14.2 Object ownership and %newobject</a></H2>
+<H2><a name="Customization_ownership">15.2 Object ownership and %newobject</a></H2>
 
 
 <p>
@@ -668,7 +652,7 @@ results.  For example:
 
 <div class="code">
 <pre>
-%typemap(newfree) char * "free($1);";
+%typemap(newfree) char * "free($1);"
 ...
 %newobject strdup;
 ...
@@ -727,37 +711,7 @@ The use of <tt>%newobject</tt> is also integrated with reference counting and is
 <a href="SWIGPlus.html#SWIGPlus_ref_unref">C++ reference counted objects</a> section.
 </p>
 
-<p>
-<b>Compatibility note:</b>  Previous versions of SWIG had a special <tt>%new</tt> directive.  However, unlike <tt>%newobject</tt>,
-it only applied to the next declaration.  For example:
-</p>
-
-<div class="code">
-<pre>
-%new char *strdup(const char *s);
-</pre>
-</div>
-
-<p>
-For now this is still supported but is deprecated.  
-</p>
-
-<p>
-<b>How to shoot yourself in the foot:</b>  The <tt>%newobject</tt> directive is not a declaration modifier like the old
-<tt>%new</tt> directive.   Don't write code like this:
-</p>
-
-<div class="code">
-<pre>
-%newobject
-char *strdup(const char *s);
-</pre>
-</div>
-<p>
-The results might not be what you expect.
-</p>
-
-<H2><a name="Customization_features">14.3 Features and the %feature directive</a></H2>
+<H2><a name="Customization_features">15.3 Features and the %feature directive</a></H2>
 
 
 <p>
@@ -839,7 +793,7 @@ The following are all equivalent:
 The syntax in the first variation will generate the <tt>{ }</tt> delimiters used whereas the other variations will not.
 </p>
 
-<H3><a name="Customization_feature_attributes">14.3.1 Feature attributes</a></H3>
+<H3><a name="Customization_feature_attributes">15.3.1 Feature attributes</a></H3>
 
 
 <p>
@@ -880,7 +834,7 @@ In the following example, <tt>MyExceptionClass</tt> is the name of the Java clas
 Further details can be obtained from the <a href="Java.html#Java_exception_handling">Java exception handling</a> section.
 </p>
 
-<H3><a name="Customization_feature_flags">14.3.2 Feature flags</a></H3>
+<H3><a name="Customization_feature_flags">15.3.2 Feature flags</a></H3>
 
 
 <p>
@@ -978,7 +932,7 @@ in the <tt>swig.swg</tt> Library file. The following shows the alternative synta
 The concept of clearing features is discussed next.
 </p>
 
-<H3><a name="Customization_clearing_features">14.3.3 Clearing features</a></H3>
+<H3><a name="Customization_clearing_features">15.3.3 Clearing features</a></H3>
 
 
 <p>
@@ -1071,7 +1025,7 @@ The three macros below show this for the "except" feature:
 </pre>
 </div>
 
-<H3><a name="Customization_features_default_args">14.3.4 Features and default arguments</a></H3>
+<H3><a name="Customization_features_default_args">15.3.4 Features and default arguments</a></H3>
 
 
 <p>
@@ -1146,7 +1100,7 @@ specifying or not specifying default arguments in a feature is not applicable as
 in SWIG-1.3.23 when the approach to wrapping methods with default arguments was changed.
 </p>
 
-<H3><a name="Customization_features_example">14.3.5 Feature example</a></H3>
+<H3><a name="Customization_features_example">15.3.5 Feature example</a></H3>
 
 
 <p>

Doc/Manual/D.html

@@ -6,7 +6,7 @@
 <meta http-equiv="content-type" content="text/html; charset=UTF-8">
 </head>
 <body bgcolor="#FFFFFF">
-<H1><a name="D">23 SWIG and D</a></H1>
+<H1><a name="D">24 SWIG and D</a></H1>
 <!-- INDEX -->
 <div class="sectiontoc">
 <ul>
@@ -22,7 +22,11 @@
 <li><a href="#D_code_injection_typemaps">Code injection typemaps</a>
 <li><a href="#D_special_variables">Special variable macros</a>
 </ul>
+<li><a href="#D_other_code_control">Other D code control features</a>
+<ul>
+<li><a href="#D_module">D begin</a>
 <li><a href="#D_features">D and %feature</a>
+</ul>
 <li><a href="#D_pragmas">Pragmas</a>
 <li><a href="#D_exceptions">D Exceptions</a>
 <li><a href="#D_directors">D Directors</a>
@@ -41,19 +45,19 @@
 
 
 
-<H2><a name="D_introduction">23.1 Introduction</a></H2>
+<H2><a name="D_introduction">24.1 Introduction</a></H2>
 
 
-<p>From the <a href="http://www.digitalmars.com/d/">D Programming Language</a> web site: <em>D is a systems programming language. Its focus is on combining the power and high performance of C and C++ with the programmer productivity of modern languages like Ruby and Python. [...] The D language is statically typed and compiles directly to machine code.</em> As such, it is not very surprising that D is able to directly <a href="http://www.digitalmars.com/d/1.0/interfaceToC.html">interface with C libraries</a>. Why would a SWIG module for D be needed then in the first place?</p>
+<p>From the <a href="https://www.digitalmars.com/d/">D Programming Language</a> web site: <em>D is a systems programming language. Its focus is on combining the power and high performance of C and C++ with the programmer productivity of modern languages like Ruby and Python. [...] The D language is statically typed and compiles directly to machine code.</em> As such, it is not very surprising that D is able to directly <a href="https://www.digitalmars.com/d/1.0/interfaceToC.html">interface with C libraries</a>. Why would a SWIG module for D be needed then in the first place?</p>
 
 <p>Well, besides the obvious downside that the C header files have to be manually converted to D modules for this to work, there is one major inconvenience with this approach: D code usually is on a higher abstraction level than C, and many of the features that make D interesting are simply not available when dealing with C libraries, requiring you e.g. to manually convert strings between pointers to <tt>\0</tt>-terminated char arrays and D char arrays, making the algorithms from the D2 standard library unusable with C arrays and data structures, and so on.</p>
 
-<p>While these issues can be worked around relatively easy by hand-coding a thin wrapper layer around the C library in question, there is another issue where writing wrapper code per hand is not feasible: C++ libraries. D did not support interfacing to C++ in version 1 at all, and even if <tt>extern(C++)</tt> has been added to D2, the support is still very limited, and a custom wrapper layer is still required in many cases. </p>
+<p>While these issues can be worked around relatively easy by hand-coding a thin wrapper layer around the C library in question, there is another issue where writing wrapper code per hand is not feasible: C++ libraries. Support for C++ was added in D2 via <tt>extern(C++)</tt> but this support is still very limited, and a custom wrapper layer is still required in many cases. </p>
 
 <p>To help addressing these issues, the SWIG C# module has been forked to support D. Is has evolved quite a lot since then, but there are still many similarities, so if you do not find what you are looking for on this page, it might be worth having a look at the chapter on <a href="CSharp.html#CSharp">C#</a> (and also on <a href="Java.html#Java">Java</a>, since the C# module was in turn forked from it).</p>
 
 
-<H2><a name="D_command_line_invocation">23.2 Command line invocation</a></H2>
+<H2><a name="D_command_line_invocation">24.2 Command line invocation</a></H2>
 
 
 <p>To activate the D module, pass the <tt>-d</tt> option to SWIG at the command line. The same standard command line options as with any other language module are available, plus the following D specific ones:</p>
@@ -61,7 +65,7 @@
 <dl>
   <dt><tt>-d2</tt></dt>
   <dd>
-    <p>By default, SWIG generates code for D1/Tango. Use the <tt>-d2</tt> flag to target D2/Phobos instead.</p>
+    <p>Prior to SWIG 4.2.0, SWIG generated wrappers for D1/Tango by default and <tt>-d2</tt> could be used to generate D2/Phobos wrappers instead.  SWIG 4.2.0 dropped support for D1, and D2 wrappers are now produced by default.  This option is still recognised to allow existing build systems calling SWIG to work, but is now a no-op.</p>
   </dd>
 
   <dt><a name="D_splitproxy"></a><tt>-splitproxy</tt></dt>
@@ -83,10 +87,10 @@
 </dl>
 
 
-<H2><a name="D_typemaps">23.3 Typemaps</a></H2>
+<H2><a name="D_typemaps">24.3 Typemaps</a></H2>
 
 
-<H3><a name="D_typemap_name_comparison">23.3.1 C# &lt;-&gt; D name comparison</a></H3>
+<H3><a name="D_typemap_name_comparison">24.3.1 C# &lt;-&gt; D name comparison</a></H3>
 
 
 <p>If you already know the SWIG C# module, you might find the following name comparison table useful:</p>
@@ -112,7 +116,7 @@
 </pre></div>
 
 
-<H3><a name="D_ctype_imtype_dtype">23.3.2 ctype, imtype, dtype</a></H3>
+<H3><a name="D_ctype_imtype_dtype">24.3.2 ctype, imtype, dtype</a></H3>
 
 
 <p>Mapping of types between the C/C++ library, the C/C++ library wrapper exposing the C functions, the D wrapper module importing these functions and the D proxy code.</p>
@@ -120,7 +124,7 @@
 <p>The <tt>ctype</tt> typemap is used to determine the types to use in the C wrapper functions. The types from the <tt>imtype</tt> typemap are used in the extern(C) declarations of these functions in the intermediary D module. The <tt>dtype</tt> typemap contains the D types used in the D proxy module/class.</p>
 
 
-<H3><a name="D_in_out_directorin_direcetorout">23.3.3 in, out, directorin, directorout</a></H3>
+<H3><a name="D_in_out_directorin_direcetorout">24.3.3 in, out, directorin, directorout</a></H3>
 
 
 <p>Used for converting between the types for C/C++ and D when generating the code for the wrapper functions (on the C++ side).</p>
@@ -130,7 +134,7 @@
 <p>The <tt>directorin</tt> typemap is used to convert parameters to the type used in the D director callback function, its return value is processed by <tt>directorout</tt> (see below).</p>
 
 
-<H3><a name="D_din_dout_ddirectorin_ddirectorout">23.3.4 din, dout, ddirectorin, ddirectorout</a></H3>
+<H3><a name="D_din_dout_ddirectorin_ddirectorout">24.3.4 din, dout, ddirectorin, ddirectorout</a></H3>
 
 
 <p>Typemaps for code generation in D proxy and type wrapper classes.</p>
@@ -157,13 +161,13 @@
       dtype             DClass.method(dtype a)</pre></div>
 
 
-<H3><a name="D_typecheck_typemaps">23.3.5 typecheck typemaps</a></H3>
+<H3><a name="D_typecheck_typemaps">24.3.5 typecheck typemaps</a></H3>
 
 
 <p>Because, unlike many scripting languages supported by SWIG, D does not need any dynamic dispatch helper to access an overloaded function, the purpose of these is merely to issue a warning for overloaded C++ functions that cannot be overloaded in D (as more than one C++ type maps to a single D type).</p>
 
 
-<H3><a name="D_code_injection_typemaps">23.3.6 Code injection typemaps</a></H3>
+<H3><a name="D_code_injection_typemaps">24.3.6 Code injection typemaps</a></H3>
 
 
 <p>These typemaps are used for generating the skeleton of proxy classes for C++ types.</p>
@@ -178,7 +182,7 @@
 Code can also be injected into the D proxy class using <tt>%proxycode</tt>.
 </p>
 
-<H3><a name="D_special_variables">23.3.7 Special variable macros</a></H3>
+<H3><a name="D_special_variables">24.3.7 Special variable macros</a></H3>
 
 
 <p>The standard SWIG special variables are available for use within typemaps as described in the <a href="Typemaps.html#Typemaps">Typemaps documentation</a>, for example <tt>$1</tt>, <tt>$input</tt>, <tt>$result</tt> etc.</p>
@@ -267,12 +271,18 @@ SomeClass bar() {
 </pre></div>
   </dd>
 
+  <dt><tt>$imfuncname</tt></dt>
+  <dd><p>
+This special variable expands to the name of the function in the intermediary class that will be used in $imcall.
+Like, $imcall, this special variable is only expanded in the "dout" typemap.
+  </p></dd>
+
   <dt><a name="D_importtype"></a><tt>$importtype(SomeDType)</tt></dt>
   <dd>
     <p>This macro is used in the <tt>dimports</tt> typemap if a dependency on another D type generated by SWIG is added by a custom typemap.</p>
     <p>Consider the following code snippet:</p>
 <div class="code"><pre>
-%typemap(dinterfaces) SomeClass "AnInterface, AnotherInterface";
+%typemap(dinterfaces) SomeClass "AnInterface, AnotherInterface"
 </pre></div>
     <p>This causes SWIG to add <tt>AnInterface</tt> and <tt>AnotherInterface</tt> to the base class list of <tt>SomeClass</tt>:</p>
 <div class="targetlang"><pre>
@@ -299,7 +309,29 @@ $importtype(AnotherInterface)
 </dl>
 
 
-<H2><a name="D_features">23.4 D and %feature</a></H2>
+<H2><a name="D_other_code_control">24.4 Other D code control features</a></H2>
+
+
+<H3><a name="D_module">24.4.1 D begin</a></H3>
+
+
+<p>
+It is possible to add a common comment at the start of every generated D file.
+The <tt>%module</tt> directive supports the <tt>dbegin</tt> option for this.
+The provided text is generated at the very beginning of each generated D file.
+As it is generated before the D module statement, is only really useful for adding in
+a common comment into all generated D files. For example, copyright text for each file:
+</p>
+
+
+<div class="code">
+<pre>
+%module(dbegin="/* Common comment. Copyright (C) 2000 Mr Nobody. */\n") nobodymodule
+</pre>
+</div>
+
+
+<H3><a name="D_features">24.4.2 D and %feature</a></H3>
 
 
 <p>The D module defines a number of directives which modify the <a href="Customization.html#Customization_features">SWIG features</a> set globally or for a specific declaration:</p>
@@ -308,7 +340,7 @@ $importtype(AnotherInterface)
 <dl>
   <dt><tt>%dmanifestconst</tt> and <tt>%dconstvalue(value)</tt></dt>
   <dd>
-    <p>Out of the box, SWIG generates accessor methods for C <tt>#defines</tt> and C++ constants. The <tt>%dmanifestconst</tt> directive enables wrapping these constants as D manifest constants (<tt>const</tt> in D1, <tt>enum</tt> in D2).</p>
+    <p>Out of the box, SWIG generates accessor methods for C <tt>#defines</tt> and C++ constants. The <tt>%dmanifestconst</tt> directive enables wrapping these constants as D manifest constants (<tt>enum</tt> in D2).</p>
     <p>For this to work, the C/C++ code for the constant value must directly compile as D code, though. If this is not the case, you can manually override the expression written to the D proxy module using the <tt>%dconstvalue</tt> directive, passing the new value as parameter.</p>
     <p>For <tt>enum</tt>s, again <tt>%dconstvalue</tt> can be used to override the value of an enum item if the initializer should not compile in D.</p>
   </dd>
@@ -329,7 +361,7 @@ struct A {
 </dl>
 
 
-<H2><a name="D_pragmas">23.5 Pragmas</a></H2>
+<H2><a name="D_pragmas">24.5 Pragmas</a></H2>
 
 
 <p>There are a few SWIG pragmas specific to the D module, which you can use to influence the D code SWIG generates:</p>
@@ -368,7 +400,7 @@ struct A {
 </dl>
 
 
-<H2><a name="D_exceptions">23.6 D Exceptions</a></H2>
+<H2><a name="D_exceptions">24.6 D Exceptions</a></H2>
 
 
 <p>Out of the box, C++ exceptions are fundamentally incompatible to their equivalent in the D world and cannot simply be propagated to a calling D method. There is, however, an easy way to solve this problem: Just catch the exception in the C/C++ wrapper layer, pass the contents to D, and make the wrapper code rethrow the exception in the D world.</p>
@@ -378,7 +410,7 @@ struct A {
 <p>As this feature is implemented in exactly the same way it is for C#, please see the <a href="CSharp.html#CSharp_exceptions">C# documentation</a> for a more detailed explanation.</p>
 
 
-<H2><a name="D_directors">23.7 D Directors</a></H2>
+<H2><a name="D_directors">24.7 D Directors</a></H2>
 
 
 <p>When the directors feature is activated, SWIG generates extra code on both the C++ and the D side to enable cross-language polymorphism. Essentially, this means that if you subclass a proxy class in D, C++ code can access any overridden virtual methods just as if you created a derived class in C++.</p>
@@ -387,16 +419,16 @@ struct A {
 </p>
 
 
-<H2><a name="D_other_features">23.8 Other features</a></H2>
+<H2><a name="D_other_features">24.8 Other features</a></H2>
 
 
-<H3><a name="D_nspace">23.8.1 Extended namespace support (nspace)</a></H3>
+<H3><a name="D_nspace">24.8.1 Extended namespace support (nspace)</a></H3>
 
 
 <p>By default, SWIG flattens all C++ namespaces into a single target language namespace, but as for Java and C#, the <a href="SWIGPlus.html#SWIGPlus_nspace"><tt>nspace</tt></a> feature is supported for D. If it is active, C++ namespaces are mapped to D packages/modules. Note, however, that like for the other languages, <em>free</em> variables and functions are not supported yet; currently, they are all allows written to the main proxy D module.</p>
 
 
-<H3><a name="D_native_pointer_support">23.8.2 Native pointer support</a></H3>
+<H3><a name="D_native_pointer_support">24.8.2 Native pointer support</a></H3>
 
 
 <p>Contrary to many of the scripting languages supported by SWIG, D fully supports C-style pointers. The D module thus includes a custom mechanism to wrap C pointers directly as D pointers where applicable, that is, if the type that is pointed to is represented the same in C and D (on the bit-level), dubbed a <em>primitive type</em> below.</p>
@@ -408,34 +440,34 @@ struct A {
 <p>To determine if a type should be considered primitive, the <tt>cprimitive</tt> attribute on its <tt>dtype</tt> attribute is used. For example, the <tt>dtype</tt> typemap for <tt>float</tt> has <tt>cprimitive="1"</tt>, so the code from the <tt>nativepointer</tt> attribute is taken into account e.g. for <tt>float **</tt> or the function pointer <tt>float (*)(float *)</tt>.</p>
 
 
-<H3><a name="D_operator_overloading">23.8.3 Operator overloading</a></H3>
+<H3><a name="D_operator_overloading">24.8.3 Operator overloading</a></H3>
 
 
-<p>The D module comes with basic operator overloading support for both D1 and D2. There are, however, a few limitations arising from conceptual differences between C++ and D:</p>
+<p>The D module comes with basic operator overloading support. There are, however, a few limitations arising from conceptual differences between C++ and D:</p>
 
 <p>The first key difference is that C++ supports free functions as operators (along with argument-dependent lookup), while D requires operators to be member functions of the class they are operating on. SWIG can only automatically generate wrapping code for member function operators; if you want to use operators defined as free functions in D, you need to handle them manually.</p>
 
-<p>Another set of differences between C++ and D concerns individual operators. For example, there are quite a few operators which are overloadable in C++, but not in D, for example <tt>&amp;&amp;</tt> and <tt>||</tt>, but also <tt>!</tt>, and prefix increment/decrement operators in <a href="http://www.digitalmars.com/d/1.0/operatoroverloading.html">D1</a> resp. their postfix pendants in <a href="http://www.digitalmars.com/d/2.0/operatoroverloading.html">D2</a>.</p>
+<p>Another set of differences between C++ and D concerns individual operators. For example, there are quite a few operators which are overloadable in C++, but not in D, for example <tt>&amp;&amp;</tt> and <tt>||</tt>, but also <tt>!</tt>, and postfix increment/decrement operators (see the <a href="https://www.digitalmars.com/d/2.0/operatoroverloading.html">D documentation</a> for details).</p>
 
 <p>There are also some cases where the operators can be translated to D, but the differences in the implementation details are big enough that a rather involved scheme would be required for automatic wrapping them, which has not been implemented yet. This affects, for example, the array subscript operator, <tt>[]</tt>, in combination with assignments - while <tt>operator []</tt> in C++ simply returns a reference which is then written to, D resorts to a separate <tt>opIndexAssign</tt> method -, or implicit casting (which was introduced in D2 via <tt>alias this</tt>). Despite the lack of automatic support, manually handling these cases should be perfectly possible.</p>
 
 
-<H3><a name="D_test_suite">23.8.4 Running the test-suite</a></H3>
+<H3><a name="D_test_suite">24.8.4 Running the test-suite</a></H3>
 
 
-<p>As with any other language, the SWIG test-suite can be built for D using the <tt>*-d-test-suite</tt> targets of the top-level Makefile. By default, D1 is targeted, to build it with D2, use the optional <tt>D_VERSION</tt> variable, e.g. <tt>make check-d-test-suite D_VERSION=2</tt>.</p>
+<p>As with any other language, the SWIG test-suite can be built for D using the <tt>*-d-test-suite</tt> targets of the top-level Makefile.</p>
 
 <p>Note: If you want to use GDC on Linux or another platform which requires you to link <tt>libdl</tt> for dynamically loading the shared library, you might have to add <tt>-ldl</tt> manually to the <tt>d_compile</tt> target in <tt>Examples/Makefile</tt>, because GDC does not currently honor the <tt>pragma(lib, ...)</tt> statement.</p>
 
 
-<H2><a name="D_typemap_examples">23.9 D Typemap examples</a></H2>
+<H2><a name="D_typemap_examples">24.9 D Typemap examples</a></H2>
 
 
 <p>There are no D-specific typemap examples yet. However, with the above <a href="D.html#D_typemap_name_comparison">name comparison table</a>, you should be able to get an idea what can be done by looking at the <a href="CSharp.html#CSharp_typemap_examples">corresponding C# section</a>.</p>
 
 
 
-<H2><a name="D_planned_features">23.10 Work in progress and planned features</a></H2>
+<H2><a name="D_planned_features">24.10 Work in progress and planned features</a></H2>
 
 
 <p>There are a couple of features which are not implemented yet, but would be very useful and might be added in the near future:</p>

Doc/Manual/Doxygen.html

@@ -5,7 +5,7 @@
 <link rel="stylesheet" type="text/css" href="style.css">
 </head>
 <body bgcolor="#FFFFFF">
-<H1><a name="Doxygen">17 SWIG and Doxygen Translation</a></H1>
+<H1><a name="Doxygen">18 SWIG and Doxygen Translation</a></H1>
 <!-- INDEX -->
 <div class="sectiontoc">
 <ul>
@@ -61,13 +61,13 @@ documentation language.  Currently only Javadoc and Pydoc is
 supported.
 </p>
 
-<H2><a name="Doxygen_translation_overview">17.1 Doxygen translation overview</a></H2>
+<H2><a name="Doxygen_translation_overview">18.1 Doxygen translation overview</a></H2>
 
 
 <p>
 The Doxygen Translation module of SWIG adds an extra layer of
 functionality to SWIG, allowing automated translation of <a href=
-"http://www.doxygen.nl/manual/">Doxygen</a> formatted comments
+"https://www.doxygen.nl/manual/">Doxygen</a> formatted comments
 from input files into a documentation language more suited for the
 target language.  Currently this module only translates into Javadoc
 and Pydoc for the SWIG Java and Python modules.
@@ -77,20 +77,20 @@ a <a href="https://developers.google.com/open-source/gsoc/2008/">Google Summer o
 Code</a> proposal from Summer 2008.  
 </p>
 
-<H2><a name="Doxygen_file_preparation">17.2 Preparations</a></H2>
+<H2><a name="Doxygen_file_preparation">18.2 Preparations</a></H2>
 
 
 <p>
 To make use of the comment translation system, your documentation
 comments must be in properly formatted <a href=
-"http://www.doxygen.nl/manual/">Doxygen.</a> Doxygen comments can be
+"https://www.doxygen.nl/manual/">Doxygen.</a> Doxygen comments can be
 present in your main SWIG interface file or any header file that it
 imports.  You are advised to be validate that your comments compile
 properly with Doxygen before you try to translate them.  Doxygen
 itself is a more comprehensive tool and can provide you better feedback for
 correcting any syntax errors that may be present.  Please look at
 Doxygen's <a href=
-"http://www.doxygen.nl/manual/docblocks.html"> Documenting the
+"https://www.doxygen.nl/manual/docblocks.html"> Documenting the
 code</a> for the full comment format specifications.  However, SWIG's
 Doxygen parser will still report many errors and warnings found
 in comments (like unterminated strings or missing ending tags).
@@ -98,7 +98,7 @@ in comments (like unterminated strings or missing ending tags).
 
 <p>
 Currently, the whole subset of Doxygen comment styles is supported
-(See <a href="http://www.doxygen.nl/manual/docblocks.html">
+(See <a href="https://www.doxygen.nl/manual/docblocks.html">
 Documenting the code</a>). Here they are:
 </p>
 
@@ -181,7 +181,7 @@ or enum element comments:
 <div class="code"><pre>
 enum E_NUMBERS
 {
-    EN_ZERO, ///&lt; The first enum item, gets zero as it's value
+    EN_ZERO, ///&lt; The first enum item, gets zero as its value
     EN_ONE, ///&lt; The second, EN_ONE=1
     EN_THREE
 };
@@ -194,7 +194,7 @@ where the comments for a code item are not put directly before or after the code
 These structural commands are stripped out by SWIG and are not assigned to anything.
 </p>
 
-<H3><a name="Doxygen_running_swig">17.2.1 Enabling Doxygen translation</a></H3>
+<H3><a name="Doxygen_running_swig">18.2.1 Enabling Doxygen translation</a></H3>
 
 
 <p>
@@ -203,7 +203,7 @@ enabled using the command line <tt>-doxygen</tt> option for the languages that
 do support it (currently Java and Python).
 </p>
 
-<H3><a name="Doxygen_features">17.2.2 Doxygen-specific %feature directives</a></H3>
+<H3><a name="Doxygen_features">18.2.2 Doxygen-specific %feature directives</a></H3>
 
 
 <p>
@@ -211,7 +211,7 @@ Translation of Doxygen comments is influenced by the following <a
 href="Customization.html#Customization_features">%feature directives</a>:
 </p>
 
-<H4><a name="Doxygen_notranslate">17.2.2.1 doxygen:notranslate</a></H4>
+<H4><a name="Doxygen_notranslate">18.2.2.1 doxygen:notranslate</a></H4>
 
 
 <p>
@@ -223,7 +223,7 @@ instead of the corresponding language tool (<tt>javadoc</tt>, <tt>sphinx</tt>,
 </p>
 
 
-<H4><a name="Doxygen_alias">17.2.2.2 doxygen:alias:&lt;command-name&gt;</a></H4>
+<H4><a name="Doxygen_alias">18.2.2.2 doxygen:alias:&lt;command-name&gt;</a></H4>
 
 
 <p>
@@ -270,7 +270,7 @@ wrappers of the C++ API.
 </p>
 
 
-<H4><a name="Doxygen_ignore">17.2.2.3 doxygen:ignore:&lt;command-name&gt;</a></H4>
+<H4><a name="Doxygen_ignore">18.2.2.3 doxygen:ignore:&lt;command-name&gt;</a></H4>
 
 
 <p>
@@ -298,7 +298,7 @@ make much sense for the other languages without explicit ownership management.
 <p>
 Doxygen syntax is rather rich and, in addition to simple commands such as
 <tt>@transferfull</tt>, it is also possible to define commands with arguments.
-As explained in <a href="http://www.doxygen.nl/manual/commands.html">Doxygen documentation</a>,
+As explained in <a href="https://www.doxygen.nl/manual/commands.html">Doxygen documentation</a>,
 the arguments can have a range of a single word, everything until the end of
 line or everything until the end of the next paragraph. Currently, only the "end
 of line" case is supported using the <tt>range="line"</tt> argument of the
@@ -421,7 +421,7 @@ def func():
 </pre></div>
 
 
-<H4><a name="Doxygen_nolinktranslate">17.2.2.4 doxygen:nolinktranslate</a></H4>
+<H4><a name="Doxygen_nolinktranslate">18.2.2.4 doxygen:nolinktranslate</a></H4>
 
 
 <p>
@@ -430,7 +430,7 @@ This is only applicable to Java at the moment.
 </p>
 
 
-<H4><a name="Doxygen_nostripparams">17.2.2.5 doxygen:nostripparams</a></H4>
+<H4><a name="Doxygen_nostripparams">18.2.2.5 doxygen:nostripparams</a></H4>
 
 
 <p>
@@ -440,14 +440,14 @@ This is only applicable to Java at the moment.
 </p>
 
 
-<H3><a name="Doxygen_additional_options">17.2.3 Additional command line options</a></H3>
+<H3><a name="Doxygen_additional_options">18.2.3 Additional command line options</a></H3>
 
 
 <p>
 ALSO TO BE ADDED (Javadoc auto brief?)
 </p>
 
-<H2><a name="Doxygen_to_javadoc">17.3 Doxygen to Javadoc</a></H2>
+<H2><a name="Doxygen_to_javadoc">18.3 Doxygen to Javadoc</a></H2>
 
 
 <p>
@@ -456,7 +456,7 @@ automatically placed in the correct locations in the resulting module
 and proxy files.
 </p>
 
-<H3><a name="Doxygen_basic_example">17.3.1 Basic example</a></H3>
+<H3><a name="Doxygen_basic_example">18.3.1 Basic example</a></H3>
 
 
 <p>
@@ -563,7 +563,7 @@ Javadoc translator features summary
 directives</a>):
 </p>
 
-<H3><a name="Doxygen_javadoc_tags">17.3.2 Javadoc tags</a></H3>
+<H3><a name="Doxygen_javadoc_tags">18.3.2 Javadoc tags</a></H3>
 
 
 <p>
@@ -825,7 +825,7 @@ Here is the list of all Doxygen tags and the description of how they are transla
 </table>
 </div>
 
-<H3><a name="Doxygen_unsupported_tags">17.3.3 Unsupported tags</a></H3>
+<H3><a name="Doxygen_unsupported_tags">18.3.3 Unsupported tags</a></H3>
 
 
 <p>
@@ -992,14 +992,14 @@ comment, the whole comment block is ignored:
 
 
 
-<H3><a name="Doxygen_further_details">17.3.4 Further details</a></H3>
+<H3><a name="Doxygen_further_details">18.3.4 Further details</a></H3>
 
 
 <p>
 TO BE ADDED.
 </p>
 
-<H2><a name="Doxygen_to_pydoc">17.4 Doxygen to Pydoc</a></H2>
+<H2><a name="Doxygen_to_pydoc">18.4 Doxygen to Pydoc</a></H2>
 
 
 <p>
@@ -1010,7 +1010,7 @@ Doxygen or Javadoc, so most of Doxygen commands are translated by merely
 copying the appropriate command text.
 </p>
 
-<H3><a name="Doxygen_python_basic_example">17.4.1 Basic example</a></H3>
+<H3><a name="Doxygen_python_basic_example">18.4.1 Basic example</a></H3>
 
 
 <p>
@@ -1079,7 +1079,7 @@ class Shape(_object):
 <p>
 If any parameters of a function or a method are documented in the Doxygen comment,
 their description is copied into the generated output using
-<a href="http://sphinx-doc.org/">Sphinx </a> documentation conventions. For example
+<a href="https://www.sphinx-doc.org/">Sphinx </a> documentation conventions. For example
 </p>
 <div class="code"><pre>
 /**
@@ -1114,7 +1114,7 @@ name of the type with namespace scope delimiters (<tt>::</tt>) replaced with a d
 change this, you can define your own typemaps for the custom types, e.g:
 </p>
 <div class="code"><pre>
-%typemap(doctype) MyDate "datetime.date";
+%typemap(doctype) MyDate "datetime.date"
 </pre></div>
 
 <p>
@@ -1167,13 +1167,13 @@ completely (doxygen:notranslate feature).  Then SWIG will just copy
 the comments to the proxy file and reformat them if needed, but all
 the comment content will be left as is. As Doxygen doesn't support
 special commands in Python comments
-(see <a href="http://www.doxygen.nl/manual/docblocks.html#pythonblocks">Doxygen
+(see <a href="https://www.doxygen.nl/manual/docblocks.html#pythonblocks">Doxygen
 docs</a>), you may want to use some tool like doxypy
 (<a href="https://pypi.org/project/doxypy/">doxypy</a>)
 to do the work.
 </p>
 
-<H3><a name="Doxygen_pydoc_tags">17.4.2 Pydoc translator</a></H3>
+<H3><a name="Doxygen_pydoc_tags">18.4.2 Pydoc translator</a></H3>
 
 
 <p>
@@ -1354,7 +1354,7 @@ Here is the list of all Doxygen tags and the description of how they are transla
 </tr>
 <tr>
 <td>\throws</td>
-<td>replaced wih ':raises:'</td>
+<td>replaced with ':raises:'</td>
 </tr>
 <tr>
 <td>\todo</td>
@@ -1427,7 +1427,7 @@ Here is the list of all Doxygen tags and the description of how they are transla
 </table>
 </div>
 
-<H3><a name="Doxygen_python_unsupported_tags">17.4.3 Unsupported tags</a></H3>
+<H3><a name="Doxygen_python_unsupported_tags">18.4.3 Unsupported tags</a></H3>
 
 
 <p>
@@ -1543,14 +1543,14 @@ Here is the list of these tags:
   </ul>
 </div>
 
-<H3><a name="Doxygen_python_further_details">17.4.4 Further details</a></H3>
+<H3><a name="Doxygen_python_further_details">18.4.4 Further details</a></H3>
 
 
 <p>
 TO BE ADDED.
 </p>
 
-<H2><a name="Doxygen_troubleshooting">17.5 Troubleshooting</a></H2>
+<H2><a name="Doxygen_troubleshooting">18.5 Troubleshooting</a></H2>
 
 
 <p>
@@ -1572,7 +1572,7 @@ include the option and fix problems with Doxygen comments.
 </p>
 
 
-<H3><a name="troubleshooting_ifndef">17.5.1 Problem with conditional compilation</a></H3>
+<H3><a name="troubleshooting_ifndef">18.5.1 Problem with conditional compilation</a></H3>
 
 
 <p>
@@ -1612,14 +1612,14 @@ class A {
 </pre></div>
 
 
-<H2><a name="Doxygen_developer_details">17.6 Developer information</a></H2>
+<H2><a name="Doxygen_developer_details">18.6 Developer information</a></H2>
 
 
 <p>
 This section contains information for developers enhancing the Doxygen translator.
 </p>
 
-<H3><a name="Doxygen_translator_design">17.6.1 Doxygen translator design</a></H3>
+<H3><a name="Doxygen_translator_design">18.6.1 Doxygen translator design</a></H3>
 
 
 <p>
@@ -1645,7 +1645,7 @@ class for translation into the target documentation language.  For
 example, <tt>JavaDocConverter</tt> is the Javadoc module class.
 </p>
 
-<H3><a name="Doxygen_debugging_commands">17.6.2 Debugging the Doxygen parser and translator</a></H3>
+<H3><a name="Doxygen_debugging_commands">18.6.2 Debugging the Doxygen parser and translator</a></H3>
 
 
 <p>
@@ -1658,7 +1658,7 @@ detailed debug information printing.
   -debug-doxygen-translator - Display Doxygen translator module debugging information
 </pre></div>
 
-<H3><a name="Doxygen_tests">17.6.3 Tests</a></H3>
+<H3><a name="Doxygen_tests">18.6.3 Tests</a></H3>
 
 
 <p>
@@ -1710,7 +1710,7 @@ Runtime tests in Python are just plain string comparisons of the __doc__
 properties.
 </p>
 
-<H2><a name="Doxygen_language_extension">17.7 Extending to other languages</a></H2>
+<H2><a name="Doxygen_language_extension">18.7 Extending to other languages</a></H2>
 
 
 <p>

Doc/Manual/Extending.html

@@ -7,7 +7,7 @@
 </head>
 
 <body bgcolor="#ffffff">
-<H1><a name="Extending">39 Extending SWIG to support new languages</a></H1>
+<H1><a name="Extending">40 Extending SWIG to support new languages</a></H1>
 <!-- INDEX -->
 <div class="sectiontoc">
 <ul>
@@ -81,7 +81,7 @@
 
 
 
-<H2><a name="Extending_nn2">39.1 Introduction</a></H2>
+<H2><a name="Extending_nn2">40.1 Introduction</a></H2>
 
 
 <p>
@@ -97,7 +97,7 @@ Also, this chapter is not meant to be a hand-holding tutorial.  As a starting po
 you should probably look at one of SWIG's existing modules.
 </p>
 
-<H2><a name="Extending_nn3">39.2 Prerequisites</a></H2>
+<H2><a name="Extending_nn3">40.2 Prerequisites</a></H2>
 
 
 <p>
@@ -127,7 +127,7 @@ obvious, but almost all SWIG directives as well as the low-level generation of
 wrapper code are driven by C++ datatypes.
 </p>
 
-<H2><a name="Extending_nn4">39.3 The Big Picture</a></H2>
+<H2><a name="Extending_nn4">40.3 The Big Picture</a></H2>
 
 
 <p>
@@ -164,7 +164,7 @@ role in making the system work.  For example, both typemaps and declaration anno
 based on pattern matching and interact heavily with the underlying type system.
 </p>
 
-<H2><a name="Extending_nn5">39.4 Execution Model</a></H2>
+<H2><a name="Extending_nn5">40.4 Execution Model</a></H2>
 
 
 <p>
@@ -209,7 +209,7 @@ latter stage of compilation.
 The next few sections briefly describe some of these stages.
 </p>
 
-<H3><a name="Extending_nn6">39.4.1 Preprocessing</a></H3>
+<H3><a name="Extending_nn6">40.4.1 Preprocessing</a></H3>
 
 
 <p>
@@ -290,7 +290,7 @@ been expanded as well as everything else that goes into the low-level
 construction of the wrapper code.
 </p>
 
-<H3><a name="Extending_nn7">39.4.2 Parsing</a></H3>
+<H3><a name="Extending_nn7">40.4.2 Parsing</a></H3>
 
 
 <p>
@@ -391,7 +391,7 @@ returning a <tt>foo</tt> and taking types <tt>a</tt> and <tt>b</tt> as
 arguments).
 </p>
 
-<H3><a name="Extending_nn8">39.4.3 Parse Trees</a></H3>
+<H3><a name="Extending_nn8">40.4.3 Parse Trees</a></H3>
 
 
 <p>
@@ -462,191 +462,224 @@ the stage being processed.
 There are a number of other parse tree display options, for example, <tt>swig -debug-module &lt;n&gt;</tt> will
 avoid displaying system parse information and only display the parse tree pertaining to the user's module at
 stage <tt>n</tt> of processing.
+Adding the <tt>-debug-quiet</tt> option is recommended as it removes some noise which is not usually needed,
+that is, the display of many linked list pointers and symbol table pointers.
 </p>
 
 <div class="shell">
 <pre>
-$ swig -c++ -python -debug-module 4 example.i
-      +++ include ----------------------------------------
-      | name         - "example.i"
+$ swig -c++ -python -debug-module 1 -debug-quiet example.i
+debug-module stage 1
++++ module ----------------------------------------
+| name         - "example"
+| 
++++ insert ----------------------------------------
+| code         - "\n#include \"example.h\"\n"
+| 
++++ include ----------------------------------------
+| name         - "example.h"
 
-            +++ module ----------------------------------------
-            | name         - "example"
-            |
-            +++ insert ----------------------------------------
-            | code         - "\n#include \"example.h\"\n"
-            |
-            +++ include ----------------------------------------
-            | name         - "example.h"
+      +++ class ----------------------------------------
+      | abstracts    - 0x7f4f15182930
+      | allows_typedef - "1"
+      | kind         - "class"
+      | name         - "Shape"
+      | sym:name     - "Shape"
 
-                  +++ class ----------------------------------------
-                  | abstract     - "1"
-                  | sym:name     - "Shape"
-                  | name         - "Shape"
-                  | kind         - "class"
-                  | symtab       - 0x40194140
-                  | sym:symtab   - 0x40191078
+            +++ access ----------------------------------------
+            | kind         - "public"
+            | 
+            +++ constructor ----------------------------------------
+            | access       - "public"
+            | code         - "{\n    nshapes++;\n  }"
+            | decl         - "f()."
+            | feature:new  - "1"
+            | ismember     - "1"
+            | name         - "Shape"
+            | sym:name     - "Shape"
+            | 
+            +++ destructor ----------------------------------------
+            | access       - "public"
+            | code         - "{\n    nshapes--;\n  }"
+            | decl         - "f()."
+            | ismember     - "1"
+            | name         - "~Shape"
+            | storage      - "virtual"
+            | sym:name     - "~Shape"
+            | 
+            +++ cdecl ----------------------------------------
+            | access       - "public"
+            | decl         - ""
+            | ismember     - "1"
+            | kind         - "variable"
+            | name         - "x"
+            | sym:name     - "x"
+            | type         - "double"
+            | 
+            +++ cdecl ----------------------------------------
+            | access       - "public"
+            | decl         - ""
+            | ismember     - "1"
+            | kind         - "variable"
+            | name         - "y"
+            | sym:name     - "y"
+            | type         - "double"
+            | 
+            +++ cdecl ----------------------------------------
+            | access       - "public"
+            | decl         - "f(double,double)."
+            | ismember     - "1"
+            | kind         - "function"
+            | name         - "move"
+            | parms        - 'double dx,double dy'
+            | sym:name     - "move"
+            | type         - "void"
+            | 
+            +++ cdecl ----------------------------------------
+            | abstract     - "1"
+            | access       - "public"
+            | decl         - "f()."
+            | ismember     - "1"
+            | kind         - "function"
+            | name         - "area"
+            | storage      - "virtual"
+            | sym:name     - "area"
+            | type         - "double"
+            | value        - "0"
+            | valuetype    - "int"
+            | 
+            +++ cdecl ----------------------------------------
+            | abstract     - "1"
+            | access       - "public"
+            | decl         - "f()."
+            | ismember     - "1"
+            | kind         - "function"
+            | name         - "perimeter"
+            | storage      - "virtual"
+            | sym:name     - "perimeter"
+            | type         - "double"
+            | value        - "0"
+            | valuetype    - "int"
+            | 
+            +++ cdecl ----------------------------------------
+            | access       - "public"
+            | decl         - ""
+            | ismember     - "1"
+            | kind         - "variable"
+            | name         - "nshapes"
+            | storage      - "static"
+            | sym:name     - "nshapes"
+            | type         - "int"
+            | 
+      +++ class ----------------------------------------
+      | allows_typedef - "1"
+      | baselist     - 0x7f4f15182ad0
+      | kind         - "class"
+      | name         - "Circle"
+      | privatebaselist - 0x7f4f15182b10
+      | protectedbaselist - 0x7f4f15182af0
+      | sym:name     - "Circle"
 
-                        +++ access ----------------------------------------
-                        | kind         - "public"
-                        |
-                        +++ constructor ----------------------------------------
-                        | sym:name     - "Shape"
-                        | name         - "Shape"
-                        | decl         - "f()."
-                        | code         - "{\n    nshapes++;\n  }"
-                        | sym:symtab   - 0x40194140
-                        |
-                        +++ destructor ----------------------------------------
-                        | sym:name     - "~Shape"
-                        | name         - "~Shape"
-                        | storage      - "virtual"
-                        | code         - "{\n    nshapes--;\n  }"
-                        | sym:symtab   - 0x40194140
-                        |
-                        +++ cdecl ----------------------------------------
-                        | sym:name     - "x"
-                        | name         - "x"
-                        | decl         - ""
-                        | type         - "double"
-                        | sym:symtab   - 0x40194140
-                        |
-                        +++ cdecl ----------------------------------------
-                        | sym:name     - "y"
-                        | name         - "y"
-                        | decl         - ""
-                        | type         - "double"
-                        | sym:symtab   - 0x40194140
-                        |
-                        +++ cdecl ----------------------------------------
-                        | sym:name     - "move"
-                        | name         - "move"
-                        | decl         - "f(double, double)."
-                        | parms        - double, double
-                        | type         - "void"
-                        | sym:symtab   - 0x40194140
-                        |
-                        +++ cdecl ----------------------------------------
-                        | sym:name     - "area"
-                        | name         - "area"
-                        | decl         - "f(void)."
-                        | parms        - void
-                        | storage      - "virtual"
-                        | value        - "0"
-                        | type         - "double"
-                        | sym:symtab   - 0x40194140
-                        |
-                        +++ cdecl ----------------------------------------
-                        | sym:name     - "perimeter"
-                        | name         - "perimeter"
-                        | decl         - "f(void)."
-                        | parms        - void
-                        | storage      - "virtual"
-                        | value        - "0"
-                        | type         - "double"
-                        | sym:symtab   - 0x40194140
-                        |
-                        +++ cdecl ----------------------------------------
-                        | sym:name     - "nshapes"
-                        | name         - "nshapes"
-                        | decl         - ""
-                        | storage      - "static"
-                        | type         - "int"
-                        | sym:symtab   - 0x40194140
-                        |
-                  +++ class ----------------------------------------
-                  | sym:name     - "Circle"
-                  | name         - "Circle"
-                  | kind         - "class"
-                  | bases        - 0x40194510
-                  | symtab       - 0x40194538
-                  | sym:symtab   - 0x40191078
+            +++ access ----------------------------------------
+            | kind         - "private"
+            | 
+            +++ cdecl ----------------------------------------
+            | access       - "private"
+            | decl         - ""
+            | ismember     - "1"
+            | kind         - "variable"
+            | name         - "radius"
+            | type         - "double"
+            | 
+            +++ access ----------------------------------------
+            | kind         - "public"
+            | 
+            +++ constructor ----------------------------------------
+            | access       - "public"
+            | code         - "{ }"
+            | decl         - "f(double)."
+            | feature:new  - "1"
+            | ismember     - "1"
+            | name         - "Circle"
+            | parms        - 'double r'
+            | sym:name     - "Circle"
+            | 
+            +++ cdecl ----------------------------------------
+            | access       - "public"
+            | decl         - "f()."
+            | ismember     - "1"
+            | kind         - "function"
+            | name         - "area"
+            | storage      - "virtual"
+            | sym:name     - "area"
+            | type         - "double"
+            | 
+            +++ cdecl ----------------------------------------
+            | access       - "public"
+            | decl         - "f()."
+            | ismember     - "1"
+            | kind         - "function"
+            | name         - "perimeter"
+            | storage      - "virtual"
+            | sym:name     - "perimeter"
+            | type         - "double"
+            | 
+      +++ class ----------------------------------------
+      | allows_typedef - "1"
+      | baselist     - 0x7f4f15183830
+      | kind         - "class"
+      | name         - "Square"
+      | privatebaselist - 0x7f4f15183870
+      | protectedbaselist - 0x7f4f15183850
+      | sym:name     - "Square"
 
-                        +++ access ----------------------------------------
-                        | kind         - "private"
-                        |
-                        +++ cdecl ----------------------------------------
-                        | name         - "radius"
-                        | decl         - ""
-                        | type         - "double"
-                        |
-                        +++ access ----------------------------------------
-                        | kind         - "public"
-                        |
-                        +++ constructor ----------------------------------------
-                        | sym:name     - "Circle"
-                        | name         - "Circle"
-                        | parms        - double
-                        | decl         - "f(double)."
-                        | code         - "{ }"
-                        | sym:symtab   - 0x40194538
-                        |
-                        +++ cdecl ----------------------------------------
-                        | sym:name     - "area"
-                        | name         - "area"
-                        | decl         - "f(void)."
-                        | parms        - void
-                        | storage      - "virtual"
-                        | type         - "double"
-                        | sym:symtab   - 0x40194538
-                        |
-                        +++ cdecl ----------------------------------------
-                        | sym:name     - "perimeter"
-                        | name         - "perimeter"
-                        | decl         - "f(void)."
-                        | parms        - void
-                        | storage      - "virtual"
-                        | type         - "double"
-                        | sym:symtab   - 0x40194538
-                        |
-                  +++ class ----------------------------------------
-                  | sym:name     - "Square"
-                  | name         - "Square"
-                  | kind         - "class"
-                  | bases        - 0x40194760
-                  | symtab       - 0x40194788
-                  | sym:symtab   - 0x40191078
-
-                        +++ access ----------------------------------------
-                        | kind         - "private"
-                        |
-                        +++ cdecl ----------------------------------------
-                        | name         - "width"
-                        | decl         - ""
-                        | type         - "double"
-                        |
-                        +++ access ----------------------------------------
-                        | kind         - "public"
-                        |
-                        +++ constructor ----------------------------------------
-                        | sym:name     - "Square"
-                        | name         - "Square"
-                        | parms        - double
-                        | decl         - "f(double)."
-                        | code         - "{ }"
-                        | sym:symtab   - 0x40194788
-                        |
-                        +++ cdecl ----------------------------------------
-                        | sym:name     - "area"
-                        | name         - "area"
-                        | decl         - "f(void)."
-                        | parms        - void
-                        | storage      - "virtual"
-                        | type         - "double"
-                        | sym:symtab   - 0x40194788
-                        |
-                        +++ cdecl ----------------------------------------
-                        | sym:name     - "perimeter"
-                        | name         - "perimeter"
-                        | decl         - "f(void)."
-                        | parms        - void
-                        | storage      - "virtual"
-                        | type         - "double"
-                        | sym:symtab   - 0x40194788
+            +++ access ----------------------------------------
+            | kind         - "private"
+            | 
+            +++ cdecl ----------------------------------------
+            | access       - "private"
+            | decl         - ""
+            | ismember     - "1"
+            | kind         - "variable"
+            | name         - "width"
+            | type         - "double"
+            | 
+            +++ access ----------------------------------------
+            | kind         - "public"
+            | 
+            +++ constructor ----------------------------------------
+            | access       - "public"
+            | code         - "{ }"
+            | decl         - "f(double)."
+            | feature:new  - "1"
+            | ismember     - "1"
+            | name         - "Square"
+            | parms        - 'double w'
+            | sym:name     - "Square"
+            | 
+            +++ cdecl ----------------------------------------
+            | access       - "public"
+            | decl         - "f()."
+            | ismember     - "1"
+            | kind         - "function"
+            | name         - "area"
+            | storage      - "virtual"
+            | sym:name     - "area"
+            | type         - "double"
+            | 
+            +++ cdecl ----------------------------------------
+            | access       - "public"
+            | decl         - "f()."
+            | ismember     - "1"
+            | kind         - "function"
+            | name         - "perimeter"
+            | storage      - "virtual"
+            | sym:name     - "perimeter"
+            | type         - "double"
 </pre>
 </div>
 
-<H3><a name="Extending_nn9">39.4.4 Attribute namespaces</a></H3>
+<H3><a name="Extending_nn9">40.4.4 Attribute namespaces</a></H3>
 
 
 <p>
@@ -665,7 +698,7 @@ that matches the name of the target language.  For example, <tt>python:foo</tt>
 <tt>perl:foo</tt>.
 </p>
 
-<H3><a name="Extending_nn10">39.4.5 Symbol Tables</a></H3>
+<H3><a name="Extending_nn10">40.4.5 Symbol Tables</a></H3>
 
 
 <p>
@@ -698,31 +731,28 @@ The parse tree can be viewed after the final stage of processing by running SWIG
 
 <div class="shell">
 <pre>
-$ swig -debug-top 4 example.i
+$ swig -debug-top 1 -debug-quiet example.i
 ...
             +++ cdecl ----------------------------------------
-            | sym:name     - "foo_i"
-            | name         - "foo"
             | decl         - "f(int)."
+            | name         - "foo"
             | parms        - int
+            | sym:name     - "foo_i"
             | type         - "void"
-            | sym:symtab   - 0x40165078
             |
             +++ cdecl ----------------------------------------
-            | sym:name     - "foo_d"
-            | name         - "foo"
             | decl         - "f(double)."
+            | name         - "foo"
             | parms        - double
+            | sym:name     - "foo_d"
             | type         - "void"
-            | sym:symtab   - 0x40165078
             |
             +++ cdecl ----------------------------------------
-            | sym:name     - "foo"
-            | name         - "foo"
             | decl         - "f(p.Bar)."
+            | name         - "foo"
             | parms        - Bar *
+            | sym:name     - "foo"
             | type         - "void"
-            | sym:symtab   - 0x40165078
 </pre>
 </div>
 
@@ -756,7 +786,7 @@ example.i:5. Previous declaration is foo_i(int )
 </pre>
 </div>
 
-<H3><a name="Extending_nn11">39.4.6 The %feature directive</a></H3>
+<H3><a name="Extending_nn11">40.4.6 The %feature directive</a></H3>
 
 
 <p>
@@ -787,19 +817,18 @@ public:
 The behavior of <tt>%feature</tt> is very easy to describe--it simply
 attaches a new attribute to any parse tree node that matches the
 given prototype.   When a feature is added, it shows up as an attribute in the <tt>feature:</tt> namespace.
-You can see this when running with the <tt>-debug-top 4</tt> option.   For example:
+You can see this when running with the <tt>-debug-top 4 -debug-quiet</tt> option.   For example:
 </p>
 
 <div class="shell">
 <pre>
  +++ cdecl ----------------------------------------
- | sym:name     - "getitem"
- | name         - "getitem"
  | decl         - "f(int).p."
- | parms        - int
- | type         - "Object"
  | feature:except - "{\n    try {\n       $action\n    } catc..."
- | sym:symtab   - 0x40168ac8
+ | name         - "getitem"
+ | parms        - int
+ | sym:name     - "getitem"
+ | type         - "Object"
  |
 </pre>
 </div>
@@ -812,7 +841,7 @@ For example, the exception code above is simply
 stored without any modifications.
 </p>
 
-<H3><a name="Extending_nn12">39.4.7 Code Generation</a></H3>
+<H3><a name="Extending_nn12">40.4.7 Code Generation</a></H3>
 
 
 <p>
@@ -934,7 +963,7 @@ public :
 The role of these functions is described shortly.
 </p>
 
-<H3><a name="Extending_nn13">39.4.8 SWIG and XML</a></H3>
+<H3><a name="Extending_nn13">40.4.8 SWIG and XML</a></H3>
 
 
 <p>
@@ -947,7 +976,7 @@ internal data structures, it may be useful to keep XML in the back of
 your mind as a model.
 </p>
 
-<H2><a name="Extending_nn14">39.5 Primitive Data Structures</a></H2>
+<H2><a name="Extending_nn14">40.5 Primitive Data Structures</a></H2>
 
 
 <p>
@@ -993,7 +1022,7 @@ typedef Hash   Typetab;
 </pre>
 </div>
 
-<H3><a name="Extending_nn15">39.5.1 Strings</a></H3>
+<H3><a name="Extending_nn15">40.5.1 Strings</a></H3>
 
 
 <p>
@@ -1132,9 +1161,14 @@ DOH_REPLACE_FIRST     - Replace first occurrence only.
 Returns the number of replacements made (if any).
 </p>
 
+<p>
+At most one of <tt>DOH_REPLACE_ANY</tt> and <tt>DOH_REPLACE_FIRST</tt> should be specified.
+<tt>DOH_REPLACE_ANY</tt> is the default if neither is specified.
+</p>
+
 </div>
 
-<H3><a name="Extending_nn16">39.5.2 Hashes</a></H3>
+<H3><a name="Extending_nn16">40.5.2 Hashes</a></H3>
 
 
 <p>
@@ -1210,8 +1244,16 @@ if an object was removed, 0 otherwise.
 Returns the list of hash table keys.
 </div>
 
+<p>
+<b><tt>List *SortedKeys(Hash *h, int (*cmp) (const DOH *, const DOH *))</tt></b>
+</p>
 
-<H3><a name="Extending_nn17">39.5.3 Lists</a></H3>
+<div class="indent">
+Returns the list of sorted hash table keys.
+</div>
+
+
+<H3><a name="Extending_nn17">40.5.3 Lists</a></H3>
 
 
 <p>
@@ -1300,7 +1342,7 @@ If <tt>t</tt> is not a standard object, it is assumed to be a <tt>char *</tt>
 and is used to create a String object.
 </div>
 
-<H3><a name="Extending_nn18">39.5.4 Common operations</a></H3>
+<H3><a name="Extending_nn18">40.5.4 Common operations</a></H3>
 
 
 The following operations are applicable to all datatypes.
@@ -1355,7 +1397,7 @@ objects and report errors.
 Gets the line number associated with <tt>x</tt>.
 </div>
 
-<H3><a name="Extending_nn19">39.5.5 Iterating over Lists and Hashes</a></H3>
+<H3><a name="Extending_nn19">40.5.5 Iterating over Lists and Hashes</a></H3>
 
 
 To iterate over the elements of a list or a hash table, the following functions are used:
@@ -1400,7 +1442,7 @@ for (j = First(j); j.item; j= Next(j)) {
 
 </div>
 
-<H3><a name="Extending_nn20">39.5.6 I/O</a></H3>
+<H3><a name="Extending_nn20">40.5.6 I/O</a></H3>
 
 
 Special I/O functions are used for all internal I/O.  These operations
@@ -1534,7 +1576,7 @@ Printf(f, "%s\n", s);
 Similarly, the preprocessor and parser all operate on string-files.
 </p>
 
-<H2><a name="Extending_nn21">39.6 Navigating and manipulating parse trees</a></H2>
+<H2><a name="Extending_nn21">40.6 Navigating and manipulating parse trees</a></H2>
 
 
 Parse trees are built as collections of hash tables.   Each node is a hash table in which
@@ -1668,7 +1710,7 @@ Deletes a node from the parse tree.  Deletion reconnects siblings and properly u
 the parent so that sibling nodes are unaffected.
 </div>
 
-<H2><a name="Extending_nn22">39.7 Working with attributes</a></H2>
+<H2><a name="Extending_nn22">40.7 Working with attributes</a></H2>
 
 
 <p>
@@ -1785,7 +1827,7 @@ the attribute is optional.   <tt>Swig_restore()</tt> must always be called after
 function.
 </div>
 
-<H2><a name="Extending_nn23">39.8 Type system</a></H2>
+<H2><a name="Extending_nn23">40.8 Type system</a></H2>
 
 
 <p>
@@ -1794,7 +1836,7 @@ pointers, references, and pointers to members.   A detailed discussion of
 type theory is impossible here.   However, let's cover the highlights.
 </p>
 
-<H3><a name="Extending_nn24">39.8.1 String encoding of types</a></H3>
+<H3><a name="Extending_nn24">40.8.1 String encoding of types</a></H3>
 
 
 <p>
@@ -1895,7 +1937,7 @@ make the final type, the two parts are just joined together using
 string concatenation.
 </p>
 
-<H3><a name="Extending_nn25">39.8.2 Type construction</a></H3>
+<H3><a name="Extending_nn25">40.8.2 Type construction</a></H3>
 
 
 <p>
@@ -2064,7 +2106,7 @@ Returns the prefix of a type. For example, if <tt>ty</tt> is
 <tt>ty</tt> is unmodified.
 </div>
 
-<H3><a name="Extending_nn26">39.8.3 Type tests</a></H3>
+<H3><a name="Extending_nn26">40.8.3 Type tests</a></H3>
 
 
 <p>
@@ -2151,7 +2193,7 @@ Checks if <tt>ty</tt> is a varargs type.
 Checks if <tt>ty</tt> is a templatized type.
 </div>
 
-<H3><a name="Extending_nn27">39.8.4 Typedef and inheritance</a></H3>
+<H3><a name="Extending_nn27">40.8.4 Typedef and inheritance</a></H3>
 
 
 <p>
@@ -2253,7 +2295,7 @@ Fully reduces <tt>ty</tt> according to typedef rules.  Resulting datatype
 will consist only of primitive typenames.
 </div>
 
-<H3><a name="Extending_nn28">39.8.5 Lvalues</a></H3>
+<H3><a name="Extending_nn28">40.8.5 Lvalues</a></H3>
 
 
 <p>
@@ -2290,7 +2332,7 @@ Literal y;    // type = 'Literal', ltype='p.char'
 </pre>
 </div>
 
-<H3><a name="Extending_nn29">39.8.6 Output functions</a></H3>
+<H3><a name="Extending_nn29">40.8.6 Output functions</a></H3>
 
 
 <p>
@@ -2352,7 +2394,7 @@ SWIG, but is most commonly associated with type-descriptor objects
 that appear in wrappers (e.g., <tt>SWIGTYPE_p_double</tt>).
 </div>
 
-<H2><a name="Extending_nn30">39.9 Parameters</a></H2>
+<H2><a name="Extending_nn30">40.9 Parameters</a></H2>
 
 
 <p>
@@ -2451,7 +2493,7 @@ included.  Used to emit prototypes.
 Returns the number of required (non-optional) arguments in <tt>p</tt>.
 </div>
 
-<H2><a name="Extending_nn31">39.10 Writing a Language Module</a></H2>
+<H2><a name="Extending_nn31">40.10 Writing a Language Module</a></H2>
 
 
 <p>
@@ -2466,7 +2508,7 @@ describes the creation of a minimal Python module.   You should be able to extra
 this to other languages.
 </p>
 
-<H3><a name="Extending_nn32">39.10.1 Execution model</a></H3>
+<H3><a name="Extending_nn32">40.10.1 Execution model</a></H3>
 
 
 <p>
@@ -2476,7 +2518,7 @@ the parsing of command line options, all aspects of code generation are controll
 different methods of the <tt>Language</tt> that must be defined by your module.
 </p>
 
-<H3><a name="Extending_starting_out">39.10.2 Starting out</a></H3>
+<H3><a name="Extending_starting_out">40.10.2 Starting out</a></H3>
 
 
 <p>
@@ -2584,7 +2626,7 @@ that activates your module. For example, <tt>swig -python foo.i</tt>. The
 messages from your new module should appear.
 </p>
 
-<H3><a name="Extending_nn34">39.10.3 Command line options</a></H3>
+<H3><a name="Extending_nn34">40.10.3 Command line options</a></H3>
 
 
 <p>
@@ -2643,7 +2685,7 @@ to mark the option as valid.   If you forget to do this, SWIG will terminate wit
 unrecognized command line option error.
 </p>
 
-<H3><a name="Extending_nn35">39.10.4 Configuration and preprocessing</a></H3>
+<H3><a name="Extending_nn35">40.10.4 Configuration and preprocessing</a></H3>
 
 
 <p>
@@ -2692,7 +2734,7 @@ an implementation file <tt>python.cxx</tt> and a configuration file
 <tt>python.swg</tt>.
 </p>
 
-<H3><a name="Extending_nn36">39.10.5 Entry point to code generation</a></H3>
+<H3><a name="Extending_nn36">40.10.5 Entry point to code generation</a></H3>
 
 
 <p>
@@ -2750,7 +2792,7 @@ int Python::top(Node *n) {
 </pre>
 </div>
 
-<H3><a name="Extending_nn37">39.10.6 Module I/O and wrapper skeleton</a></H3>
+<H3><a name="Extending_nn37">40.10.6 Module I/O and wrapper skeleton</a></H3>
 
 
 <!-- please report bugs in this section to mgossage -->
@@ -2802,7 +2844,7 @@ int Python::top(Node *n) {
   f_begin = NewFile(outfile, "w", SWIG_output_files());
   if (!f_begin) {
     FileErrorDisplay(outfile);
-    SWIG_exit(EXIT_FAILURE);
+    Exit(EXIT_FAILURE);
   }
   f_runtime = NewString("");
   f_init = NewString("");
@@ -2898,7 +2940,7 @@ functionWrapper   : void Shape_y_set(Shape *self, double y)
 </pre>
 </div>
 
-<H3><a name="Extending_nn38">39.10.7 Low-level code generators</a></H3>
+<H3><a name="Extending_nn38">40.10.7 Low-level code generators</a></H3>
 
 
 <!-- please report bugs in this section to mgossage -->
@@ -2986,7 +3028,7 @@ virtual int functionWrapper(Node *n) {
   /* create the wrapper object */
   Wrapper *wrapper = NewWrapper();
 
-  /* create the functions wrappered name */
+  /* create the wrapper function's name */
   String *wname = Swig_name_wrapper(iname);
 
   /* deal with overloading */
@@ -2995,7 +3037,7 @@ virtual int functionWrapper(Node *n) {
   /* write the wrapper function definition */
   Printv(wrapper-&gt;def, "RETURN_TYPE ", wname, "(ARGS) {", NIL);
 
-  /* if any additional local variable needed, add them now */
+  /* if any additional local variables are needed, add them now */
   ...
 
   /* write the list of locals/arguments required */
@@ -3052,7 +3094,7 @@ but without the typemaps, there is still work to do.
 </p>
 
 
-<H3><a name="Extending_configuration_files">39.10.8 Configuration files</a></H3>
+<H3><a name="Extending_configuration_files">40.10.8 Configuration files</a></H3>
 
 
 <!-- please report bugs in this section to ttn -->
@@ -3107,7 +3149,7 @@ As you can see, most usages are direct.
 <dd> This file is processed by
 
 <p>
-<A HREF="http://www.gnu.org/software/autoconf/">autoconf</A>
+<A HREF="https://www.gnu.org/software/autoconf/">autoconf</A>
 to generate the <TT>configure</TT> script.  This is where you
 need to add shell script fragments and autoconf macros to detect the
 presence of whatever development support your language module requires,
@@ -3196,7 +3238,7 @@ politely displays the ignoring language message.
 </dl>
 
 
-<H3><a name="Extending_nn40">39.10.9 Runtime support</a></H3>
+<H3><a name="Extending_nn40">40.10.9 Runtime support</a></H3>
 
 
 <p>
@@ -3205,7 +3247,7 @@ Discuss the kinds of functions typically needed for SWIG runtime support (e.g.
 the SWIG files that implement those functions.
 </p>
 
-<H3><a name="Extending_nn41">39.10.10 Standard library files</a></H3>
+<H3><a name="Extending_nn41">40.10.10 Standard library files</a></H3>
 
 
 <p>
@@ -3224,7 +3266,7 @@ The following are the minimum that are usually supported:
 Please copy these and modify for any new language.
 </p>
 
-<H3><a name="Extending_nn42">39.10.11 User examples</a></H3>
+<H3><a name="Extending_nn42">40.10.11 User examples</a></H3>
 
 
 <p>
@@ -3253,7 +3295,7 @@ during this process, see the section on <a href="#Extending_configuration_files"
 files</a>.
 </p>
 
-<H3><a name="Extending_test_suite">39.10.12 Test driven development and the test-suite</a></H3>
+<H3><a name="Extending_test_suite">40.10.12 Test driven development and the test-suite</a></H3>
 
 
 <p>
@@ -3312,7 +3354,7 @@ It is therefore essential that the runtime tests are written in a manner that di
 but error/exception out with an error message on stderr on failure.
 </p>
 
-<H4><a name="Extending_running_test_suite">39.10.12.1 Running the test-suite</a></H4>
+<H4><a name="Extending_running_test_suite">40.10.12.1 Running the test-suite</a></H4>
 
 
 <p>
@@ -3455,7 +3497,7 @@ Advanced usage of the test-suite facilitates running tools on some of the five s
 The make variables <tt>SWIGTOOL</tt> and <tt>RUNTOOL</tt> are used to specify a tool to respectively, invoke SWIG 
 and the execution of the runtime test.
 You are advised to view the <tt>Examples/test-suite/common.mk</tt> file for details but for a short summary,
-the classic usage is to use <a href="http://valgrind.org/">Valgrind</a> for memory checking.
+the classic usage is to use <a href="https://valgrind.org/">Valgrind</a> for memory checking.
 For example, checking for memory leaks when running the runtime test in the target language interpreter:
 </p>
 
@@ -3504,7 +3546,7 @@ It can be run in the same way as the other language test-suites, replacing [lang
 The test cases used and the way it works is described in <tt>Examples/test-suite/errors/Makefile.in</tt>.
 </p>
 
-<H3><a name="Extending_nn43">39.10.13 Documentation</a></H3>
+<H3><a name="Extending_nn43">40.10.13 Documentation</a></H3>
 
 
 <p>
@@ -3536,7 +3578,7 @@ Some topics that you'll want to be sure to address include:
      if available.
 </ul>
 
-<H3><a name="Extending_coding_style_guidelines">39.10.14 Coding style guidelines</a></H3>
+<H3><a name="Extending_coding_style_guidelines">40.10.14 Coding style guidelines</a></H3>
 
 
 <p>
@@ -3561,7 +3603,7 @@ should be avoided as unlike the SWIG developers, users will never have consisten
 </p>
 
 
-<H3><a name="Extending_language_status">39.10.15 Target language status</a></H3>
+<H3><a name="Extending_language_status">40.10.15 Target language status</a></H3>
 
 
 <p>
@@ -3570,7 +3612,7 @@ the <a href="Introduction.html#Introduction_target_languages">Target language in
 This section provides more details on how this status is given.
 </p>
 
-<H4><a name="Extending_supported_status">39.10.15.1 Supported status</a></H4>
+<H4><a name="Extending_supported_status">40.10.15.1 Supported status</a></H4>
 
 
 <p>
@@ -3588,7 +3630,7 @@ A target language is given the 'Supported' status when
 <li>
   It passes all of the main SWIG test-suite.
   The main test-suite is defined by the tests in the C_TEST_CASES, CPP_TEST_CASES and MULTI_CPP_TEST_CASES lists in Examples/test-suite/common.mk.
-  The tests in CPP11_TEST_CASES will also be required in the near future.
+  All the newer C++ standard tests need to work and are grouped together, such as CPP11_TEST_CASES for C++11. These more 'modern' C++ standards are only tested though if the compiler is detected as supporting the given standard.
 </li>
 <li>
   The test-suite must also include at least twenty wide-ranging runtime tests.
@@ -3607,17 +3649,17 @@ A target language is given the 'Supported' status when
   A major or minor version is the first or second digit in the three digit version.
 </li>
 <li>
-  Fixing unintended regressions in the Supported languages will be given higher priority over experimental languages by the core SWIG developers.
+  Fixing unintended regressions in the Supported languages will be given higher priority over the Experimental languages by the core SWIG developers.
 </li>
 <li>
   Examples must be available and run successfully.
 </li>
 <li>
-  The examples and test-suite must be fully functioning on the Travis Continuous Integration platform.
+  The examples and test-suite must be fully functioning on the Github Actions Continuous Integration platform.
 </li>
 </ul>
 
-<H4><a name="Extending_experimental_status">39.10.15.2 Experimental status</a></H4>
+<H4><a name="Extending_experimental_status">40.10.15.2 Experimental status</a></H4>
 
 
 <p>
@@ -3660,9 +3702,9 @@ Some minimum requirements and notes about languages with the 'Experimental' stat
   The number of tests in these lists should be no greater than half of the number of tests in the full test-suite.
 </li>
 <li>
-  The examples and test-suite must also be fully functioning on the Travis Continuous Integration platform.
-  However, experimental languages will be set as 'allow_failures'.
-  This means that pull requests and normal development commits will not break the entire Travis build should an experimental language fail.
+  The examples and test-suite must also be fully functioning on the Github Actions Continuous Integration platform.
+  However, experimental languages will be flagged as 'continue-on-error'.
+  This means that pull requests and normal development commits will not break the entire Github Actions build should an experimental language fail.
 </li>
 <li>
   Any new failed tests will be fixed on a 'best effort' basis by core developers with no promises made.
@@ -3682,7 +3724,7 @@ Some minimum requirements and notes about languages with the 'Experimental' stat
 </li>
 </ul>
 
-<H3><a name="Extending_prerequisites">39.10.16 Prerequisites for adding a new language module to the SWIG distribution</a></H3>
+<H3><a name="Extending_prerequisites">40.10.16 Prerequisites for adding a new language module to the SWIG distribution</a></H3>
 
 
 <p>
@@ -3746,7 +3788,7 @@ the existing tests.
 </p>
 
 
-<H2><a name="Extending_debugging_options">39.11 Debugging Options</a></H2>
+<H2><a name="Extending_debugging_options">40.11 Debugging Options</a></H2>
 
 
 <p>
@@ -3760,6 +3802,7 @@ There are various command line options which can aid debugging a SWIG interface
 -debug-symbols    - Display target language symbols in the symbol tables
 -debug-csymbols   - Display C symbols in the symbol tables
 -debug-lsymbols   - Display target language layer symbols
+-debug-quiet      - Display less parse tree node debug info when using other -debug options
 -debug-tags       - Display information about the tags found in the interface
 -debug-template   - Display information for debugging templates
 -debug-top &lt;n&gt;    - Display entire parse tree at stages 1-4, &lt;n&gt; is a csv list of stages
@@ -3773,7 +3816,7 @@ There are various command line options which can aid debugging a SWIG interface
 The complete list of command line options for SWIG are available by running <tt>swig -help</tt>.
 </p>
 
-<H2><a name="Extending_nn46">39.12 Guide to parse tree nodes</a></H2>
+<H2><a name="Extending_nn46">40.12 Guide to parse tree nodes</a></H2>
 
 
 <p>
@@ -4181,7 +4224,7 @@ extern "X" { ... } declaration.
 </pre>
 </div>
 
-<H2><a name="Extending_further_info">39.13 Further Development Information</a></H2>
+<H2><a name="Extending_further_info">40.13 Further Development Information</a></H2>
 
 
 <p>

Doc/Manual/Go.html

@@ -6,7 +6,7 @@
 <meta http-equiv="content-type" content="text/html; charset=UTF-8">
 </head>
 <body bgcolor="#FFFFFF">
-<H1><a name="Go">24 SWIG and Go</a></H1>
+<H1><a name="Go">25 SWIG and Go</a></H1>
 <!-- INDEX -->
 <div class="sectiontoc">
 <ul>
@@ -29,6 +29,8 @@
 <li><a href="#Go_class_inheritance">Go Class Inheritance</a>
 </ul>
 <li><a href="#Go_templates">Go Templates</a>
+<li><a href="#Go_threads">Go and C/C++ Threads</a>
+<li><a href="#Go_exceptions">Go and C++ Exceptions</a>
 <li><a href="#Go_director_classes">Go Director Classes</a>
 <ul>
 <li><a href="#Go_director_example_cpp_code">Example C++ code</a>
@@ -54,10 +56,10 @@
 <p>
 This chapter describes SWIG's support of Go.  For more information on
 the Go programming language
-see <a href="http://golang.org/">golang.org</a>.
+see <a href="https://golang.org/">golang.org</a>.
 </p>
 
-<H2><a name="Go_overview">24.1 Overview</a></H2>
+<H2><a name="Go_overview">25.1 Overview</a></H2>
 
 
 <p>
@@ -71,6 +73,7 @@ code.  SWIG fills this gap.
 There are (at least) two different Go compilers.  The first is the gc compiler
 of the <a href="https://golang.org/doc/install">Go distribution</a>, normally
 invoked via the <a href="https://golang.org/cmd/go/">go tool</a>.
+SWIG supports the gc compiler version 1.2 or later.
 The second Go compiler is the <a href="https://golang.org/doc/install/gccgo">
 gccgo compiler</a>, which is a frontend to the GCC compiler suite.
 The interface to C/C++ code is completely different for the two Go compilers.
@@ -86,7 +89,7 @@ type-safe as well.  In case of type issues the build will fail and hence SWIG's
 are not used.
 </p>
 
-<H2><a name="Go_examples">24.2 Examples</a></H2>
+<H2><a name="Go_examples">25.2 Examples</a></H2>
 
 
 <p>
@@ -101,7 +104,7 @@ SWIG interface file extension for backwards compatibility with Go 1.
 </p>
 
 
-<H2><a name="Go_running_swig">24.3 Running SWIG with Go</a></H2>
+<H2><a name="Go_running_swig">25.3 Running SWIG with Go</a></H2>
 
 
 <p>
@@ -142,46 +145,8 @@ You will now have a Go package that you can import from other Go packages as
 usual.
 </p>
 
-<p>
-SWIG can be used without cgo, via the <tt>-no-cgo</tt> option, but
-more steps are required.  This only works with Go versions before 1.5.
-When using Go version 1.2 or later, or when using gccgo, the code
-generated by SWIG can be linked directly into the Go program.  A
-typical command sequence when using the Go compiler of the Go
-distribution would look like this:
-</p>
 
-<div class="code"><pre>
-% swig -go -no-cgo example.i
-% gcc -c code.c    # The C library being wrapped.
-% gcc -c example_wrap.c
-% go tool 6g example.go
-% go tool 6c example_gc.c
-% go tool pack grc example.a example.6 example_gc.6 code.o example_wrap.o
-% go tool 6g main.go
-% go tool 6l main.6
-</pre></div>
-
-<p>
-You can also put the wrapped code into a shared library, and when using the Go
-versions before 1.2 this is the only supported option.  A typical command
-sequence for this approach would look like this:
-</p>
-
-<div class="code"><pre>
-% swig -go -no-cgo -use-shlib example.i
-% gcc -c -fpic example.c
-% gcc -c -fpic example_wrap.c
-% gcc -shared example.o example_wrap.o -o example.so
-% go tool 6g example.go
-% go tool 6c example_gc.c
-% go tool pack grc example.a example.6 example_gc.6
-% go tool 6g main.go  # your code, not generated by SWIG
-% go tool 6l main.6
-</pre></div>
-
-
-<H3><a name="Go_commandline">24.3.1 Go-specific Commandline Options</a></H3>
+<H3><a name="Go_commandline">25.3.1 Go-specific Commandline Options</a></H3>
 
 
 <p>
@@ -206,19 +171,17 @@ swig -go -help
 
 <tr>
 <td>-no-cgo</td>
-<td>Generate files that can be used directly, rather than via the Go
-  cgo tool.  This option does not work with Go 1.5 or later.  It is
-  required for versions of Go before 1.2.</td>
+<td>This option is no longer supported.</td>
 </tr>
 
 <tr>
 <td>-intgosize &lt;s&gt;</td>
 <td>Set the size for the Go type <tt>int</tt>.  This controls the size
   that the C/C++ code expects to see.  The &lt;s&gt; argument should
-  be 32 or 64.  This option is currently required during the
+  be 32 or 64.  This option was required during the
   transition from Go 1.0 to Go 1.1, as the size of <tt>int</tt> on
-  64-bit x86 systems changes between those releases (from 32 bits to
-  64 bits).  In the future the option may become optional, and SWIG
+  64-bit x86 systems changed between those releases (from 32 bits to
+  64 bits).  It was made optional in SWIG 4.1.0 and if not specified SWIG
   will assume that the size of <tt>int</tt> is the size of a C
   pointer.</td>
 </tr>
@@ -276,16 +239,13 @@ swig -go -help
 </table>
 
 
-<H3><a name="Go_outputs">24.3.2 Generated Wrapper Files</a></H3>
+<H3><a name="Go_outputs">25.3.2 Generated Wrapper Files</a></H3>
 
 
-<p>There are two different approaches to generating wrapper files,
-  controlled by SWIG's <tt>-no-cgo</tt> option.  The <tt>-no-cgo</tt>
-  option only works with version of Go before 1.5.  It is required
-  when using versions of Go before 1.2.</p>
-
-<p>With or without the <tt>-no-cgo</tt> option, SWIG will generate the
-  following files when generating wrapper code:</p>
+<p>
+SWIG will generate the following files when generating wrapper
+code:
+</p>
 
 <ul>
 <li>
@@ -308,19 +268,8 @@ or C++ compiler.
 </li>
 </ul>
 
-<p>When the <tt>-no-cgo</tt> option is used, and the <tt>-gccgo</tt>
-  option is not used, SWIG will also generate an additional file:</p>
 
-<ul>
-<li>
-MODULE_gc.c will contain C code which should be compiled with the C
-compiler distributed as part of the gc compiler.  It should then be
-combined with the compiled MODULE.go using go tool pack.
-</li>
-</ul>
-
-
-<H2><a name="Go_basic_tour">24.4 A tour of basic C/C++ wrapping</a></H2>
+<H2><a name="Go_basic_tour">25.4 A tour of basic C/C++ wrapping</a></H2>
 
 
 <p>
@@ -330,7 +279,7 @@ modifications have to occur.  This section briefly covers the
 essential aspects of this wrapping.
 </p>
 
-<H3><a name="Go_package">24.4.1 Go Package Name</a></H3>
+<H3><a name="Go_package">25.4.1 Go Package Name</a></H3>
 
 
 <p>
@@ -340,7 +289,7 @@ directive.  You may override this by using SWIG's <tt>-package</tt>
 command line option.
 </p>
 
-<H3><a name="Go_names">24.4.2 Go Names</a></H3>
+<H3><a name="Go_names">25.4.2 Go Names</a></H3>
 
 
 <p>
@@ -372,7 +321,7 @@ followed by that name, and the destructor will be
 named <tt>Delete</tt> followed by that name.
 </p>
 
-<H3><a name="Go_constants">24.4.3 Go Constants</a></H3>
+<H3><a name="Go_constants">25.4.3 Go Constants</a></H3>
 
 
 <p>
@@ -380,7 +329,7 @@ C/C++ constants created via <tt>#define</tt> or the <tt>%constant</tt>
 directive become Go constants, declared with a <tt>const</tt>
 declaration.
 
-<H3><a name="Go_enumerations">24.4.4 Go Enumerations</a></H3>
+<H3><a name="Go_enumerations">25.4.4 Go Enumerations</a></H3>
 
 
 <p>
@@ -390,7 +339,7 @@ usual).  The values of the enumeration will become variables in Go;
 code should avoid modifying those variables.
 </p>
 
-<H3><a name="Go_classes">24.4.5 Go Classes</a></H3>
+<H3><a name="Go_classes">25.4.5 Go Classes</a></H3>
 
 
 <p>
@@ -468,7 +417,7 @@ returns a go interface.  If the returned pointer can be null, you can check
 for this by calling the Swigcptr() method.
 </p>
 
-<H4><a name="Go_class_memory">24.4.5.1 Go Class Memory Management</a></H4>
+<H4><a name="Go_class_memory">25.4.5.1 Go Class Memory Management</a></H4>
 
 
 <p>
@@ -547,10 +496,6 @@ The usage of Go finalizers is problematic with C++'s RAII idiom as it isn't
 predictable when the finalizer will run and this might require a Close or Delete
 method to be added the Go object that stores a C++ object to mitigate.
 </li>
-<li>
-The Go finalizer function typically runs in a different OS thread which can be
-problematic with C++ code that uses thread-local storage.
-</li>
 </ul>
 
 <p>
@@ -590,7 +535,7 @@ func (o *GoClassName) Close() {
 </pre>
 </div>
 
-<H4><a name="Go_class_inheritance">24.4.5.2 Go Class Inheritance</a></H4>
+<H4><a name="Go_class_inheritance">25.4.5.2 Go Class Inheritance</a></H4>
 
 
 <p>
@@ -602,7 +547,7 @@ Doing the reverse will require an explicit type assertion, which will
 be checked dynamically.
 </p>
 
-<H3><a name="Go_templates">24.4.6 Go Templates</a></H3>
+<H3><a name="Go_templates">25.4.6 Go Templates</a></H3>
 
 
 <p>
@@ -610,8 +555,37 @@ In order to use C++ templates in Go, you must tell SWIG to create
 wrappers for a particular template instantiation.  To do this, use
 the <tt>%template</tt> directive.
 
+<H3><a name="Go_threads">25.4.7 Go and C/C++ Threads</a></H3>
 
-<H3><a name="Go_director_classes">24.4.7 Go Director Classes</a></H3>
+
+<p>
+C and C++ code can use operating system threads and thread local
+storage.  Go code uses goroutines, which are multiplexed onto
+operating system threads.  This multiplexing means that Go code can
+change to run on a different thread at any time.  C/C++ code, on the
+other hand, may assume that it runs on a single thread; this is true
+in particular if the C/C++ code uses thread local storage.
+</p>
+
+<p>
+In order to use Go code with C/C++ code that expects to run on a
+single thread, the Go code must call
+the <a href="https://pkg.go.dev/runtime#LockOSThread"><code>runtime.LockOSThread</code></a>
+function to lock the goroutine onto a single thread.
+</p>
+
+<H3><a name="Go_exceptions">25.4.8 Go and C++ Exceptions</a></H3>
+
+
+<p>
+C++ exceptions do not interoperate with Go code.  Attempts to throw
+C++ exceptions through a Go caller are unreliable: in many cases the
+C++ exception handler will be unable to unwind the stack, and the
+program will crash.  The only safe way to handle C++ exceptions is to
+catch them in C++ before returning to Go.
+</p>
+
+<H3><a name="Go_director_classes">25.4.9 Go Director Classes</a></H3>
 
 
 <p>
@@ -629,7 +603,7 @@ completely to avoid common pitfalls with directors in Go.
 </p>
 
 
-<H4><a name="Go_director_example_cpp_code">24.4.7.1 Example C++ code</a></H4>
+<H4><a name="Go_director_example_cpp_code">25.4.9.1 Example C++ code</a></H4>
 
 
 <p>
@@ -701,7 +675,7 @@ be found in <a href="#Go_director_foobargo_class">the end of the guide</a>.
 </p>
 
 
-<H4><a name="Go_director_enable">24.4.7.2 Enable director feature</a></H4>
+<H4><a name="Go_director_enable">25.4.9.2 Enable director feature</a></H4>
 
 
 <p>
@@ -736,7 +710,7 @@ documentation on directors.
 </p>
 
 
-<H4><a name="Go_director_ctor_dtor">24.4.7.3 Constructor and destructor</a></H4>
+<H4><a name="Go_director_ctor_dtor">25.4.9.3 Constructor and destructor</a></H4>
 
 
 <p>
@@ -789,7 +763,7 @@ embedding</a>.
 </p>
 
 
-<H4><a name="Go_director_overriding">24.4.7.4 Override virtual methods</a></H4>
+<H4><a name="Go_director_overriding">25.4.9.4 Override virtual methods</a></H4>
 
 
 <p>
@@ -857,7 +831,7 @@ the Go methods.
 </p>
 
 
-<H4><a name="Go_director_base_methods">24.4.7.5 Call base methods</a></H4>
+<H4><a name="Go_director_base_methods">25.4.9.5 Call base methods</a></H4>
 
 
 <p>
@@ -894,7 +868,7 @@ be found in <a href="#Go_director_foobargo_class">the end of the guide</a>.
 </p>
 
 
-<H4><a name="Go_director_subclass">24.4.7.6 Subclass via embedding</a></H4>
+<H4><a name="Go_director_subclass">25.4.9.6 Subclass via embedding</a></H4>
 
 
 <p>
@@ -962,7 +936,7 @@ class.
 </p>
 
 
-<H4><a name="Go_director_finalizer">24.4.7.7 Memory management with runtime.SetFinalizer</a></H4>
+<H4><a name="Go_director_finalizer">25.4.9.7 Memory management with runtime.SetFinalizer</a></H4>
 
 
 <p>
@@ -1027,7 +1001,7 @@ before using <tt>runtime.SetFinalizer</tt> to know all of its gotchas.
 </p>
 
 
-<H4><a name="Go_director_foobargo_class">24.4.7.8 Complete FooBarGo example class</a></H4>
+<H4><a name="Go_director_foobargo_class">25.4.9.8 Complete FooBarGo example class</a></H4>
 
 
 <p>
@@ -1156,7 +1130,7 @@ SWIG/Examples/go/director/</a>.
 </p>
 
 
-<H3><a name="Go_primitive_type_mappings">24.4.8 Default Go primitive type mappings</a></H3>
+<H3><a name="Go_primitive_type_mappings">25.4.10 Default Go primitive type mappings</a></H3>
 
 
 <p>
@@ -1263,7 +1237,7 @@ that typemap, or add new values, to control how C/C++ types are mapped
 into Go types.
 </p>
 
-<H3><a name="Go_output_arguments">24.4.9 Output arguments</a></H3>
+<H3><a name="Go_output_arguments">25.4.11 Output arguments</a></H3>
 
 
 <p>Because of limitations in the way output arguments are processed in swig,
@@ -1316,7 +1290,7 @@ void f(char *output);
 </pre>
 </div>
 
-<H3><a name="Go_adding_additional_code">24.4.10 Adding additional go code</a></H3>
+<H3><a name="Go_adding_additional_code">25.4.12 Adding additional go code</a></H3>
 
 
 <p>Often the APIs generated by swig are not very natural in go, especially if
@@ -1411,7 +1385,7 @@ func bar() {
 </pre>
 </div>
 
-<H3><a name="Go_typemaps">24.4.11 Go typemaps</a></H3>
+<H3><a name="Go_typemaps">25.4.13 Go typemaps</a></H3>
 
 
 <p>
@@ -1450,7 +1424,7 @@ default as <a href="#Go_primitive_type_mappings">described above</a>.
 <td>
 An intermediate Go type used by the "goin", "goout", "godirectorin",
 and "godirectorout" typemaps.  If this typemap is not defined for a
-C/C++ type, the gotype typemape will be used.  This is useful when
+C/C++ type, the gotype typemap will be used.  This is useful when
 gotype is best converted to C/C++ using Go code.
 </td>
 </tr>

Doc/Manual/Guile.html

@@ -8,7 +8,7 @@
 
 <body bgcolor="#ffffff">
 
-<H1><a name="Guile">25 SWIG and Guile</a></H1>
+<H1><a name="Guile">26 SWIG and Guile</a></H1>
 <!-- INDEX -->
 <div class="sectiontoc">
 <ul>
@@ -48,21 +48,22 @@
 <p>
 This section details guile-specific support in SWIG.
 
-<H2><a name="Guile_nn1">25.1 Supported Guile Versions</a></H2>
+<H2><a name="Guile_nn1">26.1 Supported Guile Versions</a></H2>
 
 
 <p>
-SWIG works with Guile versions 1.8.x and 2.0.x. Support for version
-1.6.x has been dropped. The last version of SWIG that still works with
-Guile version 1.6.x is SWIG 2.0.9.
+SWIG is known to work with Guile versions 2.0.x, 2.2.x and 3.0.x (these are
+all tested via CI). SWIG probably still works with Guile 1.8.x but we're no
+longer able to regularly test this either in CI or by hand. Support for Guile
+1.6.x has been dropped (SWIG 2.0.9 was the last version of SWIG to support it).
 
 <p>
 Note that starting with guile 2.0, the guile sources can be compiled for
 improved performance. This is currently not tested with swig
 so your mileage may vary. To be safe set environment variable
-GUILE_AUTO_COMPILE to 0 when using swig generated guile code.
+<tt>GUILE_AUTO_COMPILE</tt> to 0 when using swig generated guile code.
 
-<H2><a name="Guile_nn2">25.2 Meaning of "Module"</a></H2>
+<H2><a name="Guile_nn2">26.2 Meaning of "Module"</a></H2>
 
 
 <p>
@@ -70,18 +71,18 @@ There are three different concepts of "module" involved, defined
 separately for SWIG, Guile, and Libtool.  To avoid horrible confusion,
 we explicitly prefix the context, e.g., "guile-module".
 
-<H2><a name="Guile_nn3">25.3 Old GH Guile API</a></H2>
+<H2><a name="Guile_nn3">26.3 Old GH Guile API</a></H2>
 
 
 <p>Guile 1.8 and older could be interfaced using two different api's, the SCM
 or the GH API. The GH interface to guile is deprecated.  Read more about why in the 
-<a href="http://www.gnu.org/software/guile/docs/docs-1.6/guile-ref/GH.html#GH">Guile manual</a>.
+<a href="https://www.gnu.org/software/guile/docs/docs-1.6/guile-ref/GH.html#GH">Guile manual</a>.
 
 <p>Support for the guile GH wrapper code generation has been dropped from SWIG. The last
 version of SWIG that can still generate guile GH wrapper code is 2.0.9. Please
 use that version if you really need the GH wrapper code.
 
-<H2><a name="Guile_nn4">25.4 Linkage</a></H2>
+<H2><a name="Guile_nn4">26.4 Linkage</a></H2>
 
 
 <p>
@@ -89,7 +90,7 @@ Guile support is complicated by a lack of user community cohesiveness,
 which manifests in multiple shared-library usage conventions.  A set of
 policies implementing a usage convention is called a <b>linkage</b>.
 
-<H3><a name="Guile_nn5">25.4.1 Simple Linkage</a></H3>
+<H3><a name="Guile_nn5">26.4.1 Simple Linkage</a></H3>
 
 
 <p>
@@ -183,7 +184,7 @@ information by including a directive like this in the interface file:
 </div>
 
 <p>
-(The <code>%scheme</code> directive allows to insert arbitrary Scheme
+(The <code>%scheme</code> directive allows inserting arbitrary Scheme
 code into the generated file <code><var>module.scm</var></code>; it is
 placed between the <code>define-module</code> form and the
 <code>export</code> form.)
@@ -194,7 +195,7 @@ placed between the <code>define-module</code> form and the
 <code>SWIG_init</code> via a preprocessor define to avoid symbol
 clashes. For this case, however, passive linkage is available.
 
-<H3><a name="Guile_nn6">25.4.2 Passive Linkage</a></H3>
+<H3><a name="Guile_nn6">26.4.2 Passive Linkage</a></H3>
 
 
 <p>Passive linkage is just like simple linkage, but it generates an
@@ -204,7 +205,7 @@ package name (see below).
 <p>You should use passive linkage rather than simple linkage when you
 are using multiple modules.
 
-<H3><a name="Guile_nn7">25.4.3 Native Guile Module Linkage</a></H3>
+<H3><a name="Guile_nn7">26.4.3 Native Guile Module Linkage</a></H3>
 
 
 <p>SWIG can also generate wrapper code that does all the Guile module
@@ -245,33 +246,16 @@ Newer Guile versions have a shorthand procedure for this:
 </div>
 </ul>
 
-<H3><a name="Guile_nn8">25.4.4 Old Auto-Loading Guile Module Linkage</a></H3>
+<H3><a name="Guile_nn8">26.4.4 Old Auto-Loading Guile Module Linkage</a></H3>
 
 
 <p>Guile used to support an autoloading facility for object-code
-modules. This support has been marked deprecated in version 1.4.1 and
-is going to disappear sooner or later. SWIG still supports building
-auto-loading modules if you pass it the <code>-Linkage ltdlmod</code>
-command-line option.
-
-<p>Auto-loading worked like this: Suppose a module with name <code>(my
-lib foo)</code> is required and not loaded yet.  Guile will then search
-all directories in its search path
-for a Scheme file <code>my/modules/foo.scm</code> or a shared library
-<code><var>my</var>/<var>modules</var>/lib<var>foo</var>.so</code> (or
-<code><var>my</var>/<var>modules</var>/lib<var>foo</var>.la</code>; 
-see the GNU libtool documentation). If a
-shared library is found that contains the symbol
-<code>scm_init_<var>my</var>_<var>modules</var>_<var>foo</var>_module</code>, 
-the library is loaded, and the function at that symbol is called with
-no arguments in order to initialize the module.
-
-<p>When invoked with the <code>-Linkage ltdlmod</code> command-line
-option, SWIG generates an exported module initialization function with
-an appropriate name. 
+modules, but this support was deprecated and removed in Guile version 1.4.1.
+SWIG supported this via option <code>-Linkage ltdlmod</code>, but this
+support is no longer useful and was removed in SWIG 4.2.0.
 
 
-<H3><a name="Guile_nn9">25.4.5 Hobbit4D Linkage</a></H3>
+<H3><a name="Guile_nn9">26.4.5 Hobbit4D Linkage</a></H3>
 
 
 <p>
@@ -296,19 +280,21 @@ my/lib/libfoo.so.X.Y.Z and friends.  This scheme is still very
 experimental; the (hobbit4d link) conventions are not well understood.
 </p>
 
-<H2><a name="Guile_nn10">25.5 Underscore Folding</a></H2>
+<H2><a name="Guile_nn10">26.5 Underscore Folding</a></H2>
 
 
 <p>
 Underscores are converted to dashes in identifiers.  Guile support may
 grow an option to inhibit this folding in the future, but no one has
 complained so far.
+</p>
 
-<p>You can use the SWIG directives <code>%name</code> and
-<code>%rename</code> to specify the Guile name of the wrapped
-functions and variables (see CHANGES).
+<p>You can use the <a href="SWIG.html#SWIG_rename_ignore">SWIG
+directive <code>%rename</code></a> to specify the Guile
+names of the wrapped functions and variables.
+</p>
 
-<H2><a name="Guile_nn11">25.6 Typemaps</a></H2>
+<H2><a name="Guile_nn11">26.6 Typemaps</a></H2>
 
 
 <p>
@@ -400,7 +386,7 @@ constant will appear as a scheme variable. See
 <a href="Customization.html#Customization_features">Features and the %feature directive</a>
 for info on how to apply the %feature.</p>
 
-<H2><a name="Guile_nn12">25.7 Representation of pointers as smobs</a></H2>
+<H2><a name="Guile_nn12">26.7 Representation of pointers as smobs</a></H2>
 
 
 <p>
@@ -421,7 +407,7 @@ representing the expected pointer type.  See also
 If the Scheme object passed was not a SWIG smob representing a compatible
 pointer, a <code>wrong-type-arg</code> exception is raised.
 
-<H3><a name="Guile_nn14">25.7.1 Smobs</a></H3>
+<H3><a name="Guile_nn14">26.7.1 Smobs</a></H3>
 
 
 <p>
@@ -440,7 +426,7 @@ structure describing this type.  If a generated GOOPS module has been loaded, sm
 the corresponding GOOPS class.</p>
 
 
-<H3><a name="Guile_nn15">25.7.2 Garbage Collection</a></H3>
+<H3><a name="Guile_nn15">26.7.2 Garbage Collection</a></H3>
 
 
 <p>Garbage collection is a feature of Guile since version 1.6. As SWIG now requires Guile &gt; 1.8,
@@ -454,14 +440,14 @@ is exactly like described in <a href="Customization.html#Customization_ownership
 Object ownership and %newobject</a> in the SWIG manual.  All typemaps use an $owner var, and
 the guile module replaces $owner with 0 or 1 depending on feature:new.</p>
 
-<H2><a name="Guile_nn16">25.8 Native Guile pointers</a></H2>
+<H2><a name="Guile_nn16">26.8 Native Guile pointers</a></H2>
 
 
 <p>
 In addition to SWIG smob pointers, <a href="https://www.gnu.org/software/guile/manual/html_node/Foreign-Pointers.html">Guile's native pointer type</a> are accepted as arguments to wrapped SWIG functions. This can be useful for passing <a href="https://www.gnu.org/software/guile/manual/html_node/Void-Pointers-and-Byte-Access.html#">pointers to bytevector data</a> to wrapped functions.
 </p>
 
-<H2><a name="Guile_nn17">25.9 Exception Handling</a></H2>
+<H2><a name="Guile_nn17">26.9 Exception Handling</a></H2>
 
 
 <p>
@@ -487,7 +473,7 @@ mapping:
 The default when not specified here is to use "swig-error".
 See Lib/exception.i for details.
 
-<H2><a name="Guile_nn18">25.10 Procedure documentation</a></H2>
+<H2><a name="Guile_nn18">26.10 Procedure documentation</a></H2>
 
 
 <p>If invoked with the command-line option <code>-procdoc
@@ -522,7 +508,7 @@ like this:
 typemap argument <code>doc</code>. See <code>Lib/guile/typemaps.i</code> for
 details.
 
-<H2><a name="Guile_nn19">25.11 Procedures with setters</a></H2>
+<H2><a name="Guile_nn19">26.11 Procedures with setters</a></H2>
 
 
 <p>For global variables, SWIG creates a single wrapper procedure
@@ -550,7 +536,7 @@ struct members, the procedures <code>(<var>struct</var>-<var>member</var>-get
 pointer)</code> and <code>(<var>struct-member</var>-set pointer
 value)</code> are <em>not</em> generated.
 
-<H2><a name="Guile_nn20">25.12 GOOPS Proxy Classes</a></H2>
+<H2><a name="Guile_nn20">26.12 GOOPS Proxy Classes</a></H2>
 
 
 <p>SWIG can also generate classes and generic functions for use with
@@ -696,7 +682,7 @@ Notice that &lt;Foo&gt; is used before it is defined.  The fix is to just put th
 <code>%import "foo.h"</code> before the <code>%inline</code> block.
 </p>
 
-<H3><a name="Guile_nn21">25.12.1 Naming Issues</a></H3>
+<H3><a name="Guile_nn21">26.12.1 Naming Issues</a></H3>
 
 
 <p>As you can see in the example above, there are potential naming conflicts.  The default exported
@@ -733,7 +719,7 @@ guile-modules.  For example,</p>
 (use-modules ((Test) #:renamer (symbol-prefix-proc 'goops:)))
 </pre></div>
 
-<H3><a name="Guile_nn22">25.12.2 Linking</a></H3>
+<H3><a name="Guile_nn22">26.12.2 Linking</a></H3>
 
 
 <p>The guile-modules generated above all need to be linked together.  GOOPS support requires

Doc/Manual/Introduction.html

@@ -172,7 +172,7 @@ This status is provided to indicate the level of maturity to expect when using a
 
 <p>
 The second part of the SWIG documentation contains a chapter for each target level language.
-Each chapter will state the status (Supported or Experimental) for that language.
+The target language chapters are under one of two sections indicating the status (Supported or Experimental) for that language.
 </p>
 
 <H3><a name="Introduction_supported_status">2.3.1 Supported status</a></H3>
@@ -416,6 +416,7 @@ major features include:
 Most of C++11 is also supported. Details are in the <a href="CPlusPlus11.html#CPlusPlus11">C++11</a> chapter.
 C++14 support is covered in the <a href="CPlusPlus14.html#CPlusPlus14">C++14</a> chapter.
 C++17 support is covered in the <a href="CPlusPlus17.html#CPlusPlus17">C++17</a> chapter.
+C++20 support is covered in the <a href="CPlusPlus20.html#CPlusPlus20">C++20</a> chapter.
 </p>
 
 <p>
@@ -452,14 +453,14 @@ Microsoft Visual Studio.
 
 <p>
 If you are using the GNU Autotools 
-(<a href="http://www.gnu.org/software/autoconf/">Autoconf</a>/
-<a href="http://www.gnu.org/software/automake/">Automake</a>/
-<a href="http://www.gnu.org/software/libtool/">Libtool</a>)
+(<a href="https://www.gnu.org/software/autoconf/">Autoconf</a>/
+<a href="https://www.gnu.org/software/automake/">Automake</a>/
+<a href="https://www.gnu.org/software/libtool/">Libtool</a>)
 to configure SWIG use in your project, the SWIG Autoconf macros can be used.
 The primary macro is <tt>ax_pkg_swig</tt>, see
-<a href="http://www.gnu.org/software/autoconf-archive/ax_pkg_swig.html#ax_pkg_swig">http://www.gnu.org/software/autoconf-archive/ax_pkg_swig.html#ax_pkg_swig</a>.
+<a href="https://www.gnu.org/software/autoconf-archive/ax_pkg_swig.html#ax_pkg_swig">http://www.gnu.org/software/autoconf-archive/ax_pkg_swig.html#ax_pkg_swig</a>.
 The <tt>ax_python_devel</tt> macro is also helpful for generating Python extensions. See the 
-<a href="http://www.gnu.org/software/autoconf-archive/">Autoconf Archive</a>
+<a href="https://www.gnu.org/software/autoconf-archive/">Autoconf Archive</a>
 for further information on this and other Autoconf macros.
 </p>
 

Doc/Manual/Javascript.html

@@ -7,7 +7,7 @@
 </head>
 <body>
 
-<H1><a name="Javascript">27 SWIG and Javascript</a></H1>
+<H1><a name="Javascript">28 SWIG and Javascript</a></H1>
 <!-- INDEX -->
 <div class="sectiontoc">
 <ul>
@@ -22,6 +22,7 @@
 <ul>
 <li><a href="#Javascript_node_extensions">Creating node.js Extensions</a>
 <ul>
+<li><a href="#Javascript_using_yeoman">Using <code>yeoman</code> to generate a Node-API skeleton</a>
 <li><a href="#Javascript_troubleshooting">Troubleshooting</a>
 </ul>
 <li><a href="#Javascript_embedded_webkit">Embedded Webkit</a>
@@ -43,6 +44,7 @@
 <li><a href="#Javascript_emitter">Emitter</a>
 <li><a href="#Javascript_emitter_states">Emitter states</a>
 <li><a href="#Javascript_jsc_exceptions">Handling Exceptions in JavascriptCore</a>
+<li><a href="#Javascript_napi_exceptions">Handling Exceptions in Node-API</a>
 </ul>
 </ul>
 </div>
@@ -52,7 +54,7 @@
 
 <p>This chapter describes SWIG's support of Javascript. It does not cover SWIG basics, but only information that is specific to this module.</p>
 
-<H2><a name="Javascript_overview">27.1 Overview</a></H2>
+<H2><a name="Javascript_overview">28.1 Overview</a></H2>
 
 
 <p>Javascript is a prototype-based scripting language that is dynamic, weakly typed and has first-class functions. Its arguably the most popular language for web development.
@@ -63,10 +65,10 @@ Javascript has gone beyond being a browser-based scripting language and with <a
 With <a href="https://github.com/rogerwang/node-webkit">node-webkit</a> there is a platform which uses Google's <code>Chromium</code> as Web-Browser widget and <code>node.js</code> for javascript extensions.
 </p>
 
-<H2><a name="Javascript_preliminaries">27.2 Preliminaries</a></H2>
+<H2><a name="Javascript_preliminaries">28.2 Preliminaries</a></H2>
 
 
-<H3><a name="Javascript_running_swig">27.2.1 Running SWIG</a></H3>
+<H3><a name="Javascript_running_swig">28.2.1 Running SWIG</a></H3>
 
 
 <p>Suppose that you defined a SWIG module such as the following:</p>
@@ -79,7 +81,7 @@ With <a href="https://github.com/rogerwang/node-webkit">node-webkit</a> there is
 int gcd(int x, int y);
 extern double Foo;</pre>
 </div>
-<p>To build a Javascript module, run SWIG using the <code>-javascript</code> option and a desired target engine <code>-jsc</code>, <code>-v8</code>, or <code>-node</code>. The generator for <code>node</code> is essentially delegating to the <code>v8</code> generator and adds some necessary preprocessor definitions.</p>
+<p>To build a Javascript module, run SWIG using the <code>-javascript</code> option and a desired target engine <code>-jsc</code>, <code>-v8</code>, <code>-node</code> or <code>-napi</code>. <code>-v8</code> allows for interfacing with a raw embedded version of V8. In this case, it is up to the user to implement a binary module loading protocol. There are two generators supporting Node.js. The older generator for <code>node</code> is essentially delegating to the <code>v8</code> generator and adds some necessary preprocessor definitions. The more recent <code>-napi</code> generator produces <code>node-addon-api</code> that interfaces to Node.js through Node-API. The V8 generator is more mature, while the Node-API generator offers a number of advantages such as binary stable ABI allowing for publishing of universal binary modules on npm, Electron support and automatic multi-threading.</p>
 <div class="shell">
 <pre>
 $ swig -javascript -jsc example.i</pre>
@@ -89,19 +91,14 @@ $ swig -javascript -jsc example.i</pre>
 <pre>
 $ swig -c++ -javascript -jsc example.i</pre>
 </div>
-<p>The V8 code that SWIG generates should work with most versions from 3.11.10 up to 3.29.14 and later.</p>
-<p>The API headers for V8 &gt;= 4.3.0 define constants which SWIG can use to
-determine the V8 version it is compiling for.  For versions &lt; 4.3.0, you
-need to specify the V8 version when running SWIG.  This is specified as a hex
-constant, but the constant is read as pairs of decimal digits, so for V8
-3.25.30 use constant 0x032530.  This scheme can't represent components &gt; 99,
-but this constant is only useful for V8 &lt; 4.3.0, and no V8 versions from
-that era had a component &gt; 99.  For example:</p>
-<div class="shell">
-<pre>
-$ swig -c++ -javascript -v8 -DV8_VERSION=0x032530 example.i</pre>
-</div>
-<p>If you're targeting V8 &gt;= 4.3.0, you would just run swig like so:</p>
+<p>The V8 code that SWIG generates requires at least V8 5.0. Keep in mind
+that this is the V8 version, not Node.js. To give some perspective, Node.js v6.0
+uses V8 5.0, v12.0 - 7.4, v14.0 - 8.1...</p>
+<p>The Node-API code that SWIG generates requires Node-API version 6.
+This Node-API is available starting from Node.js v10.20 on the v10.x branch,
+Node.js v12.17 on the v12.x branch and all versions starting from v14.0.
+</p>
+<p>To generate code for V8, you would run swig like so:</p>
 <div class="shell">
 <pre>
 $ swig -c++ -javascript -v8 example.i</pre>
@@ -121,7 +118,7 @@ void example_initialize(v8::Handle&lt;v8::Object&gt; exports)</pre>
 <b>Note</b>: be aware that <code>v8</code> has a C++ API, and thus, the generated modules must be compiled as C++.
 </p>
 
-<H3><a name="Javascript_running_tests_examples">27.2.2 Running Tests and Examples</a></H3>
+<H3><a name="Javascript_running_tests_examples">28.2.2 Running Tests and Examples</a></H3>
 
 
 <p>The configuration for tests and examples currently supports Linux and Mac only and not MinGW (Windows) yet.</p>
@@ -134,14 +131,19 @@ $ sudo apt-get install libjavascriptcoregtk-1.0-dev</pre>
 <p>Running with <code>V8</code> requires <code>libv8</code>:</p>
 <div class="shell">
 <pre>
-$ sudo apt-get install libv8-dev</pre>
+$ sudo apt-get install libnode-dev</pre>
+</div>
+<p>Running with Node-API requires <code>node-addon-api</code>:</p>
+<div class="shell">
+  <pre>
+$ sudo npm install -g node-addon-api</pre>
 </div>
 <p>Examples can be run using</p>
 <div class="shell">
 <pre>
 $ make check-javascript-examples ENGINE=jsc</pre>
 </div>
-<p><code>ENGINE</code> can be <code>node</code>, <code>jsc</code>, or <code>v8</code>.</p>
+<p><code>ENGINE</code> can be <code>node</code>, <code>jsc</code>, <code>v8</code>, or <code>napi</code>.</p>
 <p>The test-suite can be run using</p>
 <div class="shell">
 <pre>
@@ -153,28 +155,28 @@ $ make check-javascript-test-suite ENGINE=jsc</pre>
 $ make check-javascript-examples V8_VERSION=0x032530 ENGINE=v8</pre>
 </div>
 
-<H3><a name="Javascript_known_issues">27.2.3 Known Issues</a></H3>
+<H3><a name="Javascript_known_issues">28.2.3 Known Issues</a></H3>
 
 
 <p>At the moment, the Javascript generators pass all tests syntactically, i.e., the generated source code compiles. However, there are still remaining runtime issues.</p>
 
 <ul>
-    <li><p>Default optional arguments do not work for all targeted interpreters</p></li>
+    <li><p>Default optional arguments do not work for all targeted interpreters except Node-API</p></li>
     <li><p>Multiple output arguments do not work for JSC</p></li>
     <li><p>C89 incompatibility: the JSC generator might still generate C89 violating code</p></li>
-    <li><p><code>long long</code> is not supported</p></li>
+    <li><p><code>long long</code> is not supported except with Node-API</p></li>
     <li><p>Javascript callbacks are not supported</p></li>
     <li><p><code>instanceOf</code> does not work under JSC</p></li>
 </ul>
 
-<p>The primary development environment has been Linux (Ubuntu 12.04). Windows and Mac OS X have been tested sporadically. Therefore, the generators might have more issues on those platforms. Please report back any problem you observe to help us improving this module quickly.</p>
+<p>The primary development environment has been Linux (Ubuntu 22.04). Windows and Mac OS X have been tested sporadically. Therefore, the generators might have more issues on those platforms. Please report back any problem you observe to help us improving this module quickly.</p>
 
-<H2><a name="Javascript_integration">27.3 Integration</a></H2>
+<H2><a name="Javascript_integration">28.3 Integration</a></H2>
 
 
 <p>This chapter gives a short introduction how to use a native Javascript extension: as a <code>node.js</code> module, and as an extension for an embedded Webkit.</p>
 
-<H3><a name="Javascript_node_extensions">27.3.1 Creating node.js Extensions</a></H3>
+<H3><a name="Javascript_node_extensions">28.3.1 Creating node.js Extensions</a></H3>
 
 
 <p>To install <code>node.js</code> you can download an installer from their <a href="https://launchpad.net/~chris-lea/+archive/node.js">web-site</a> for Mac OS X and Windows. For Linux you can either build the source yourself and run <code>sudo checkinstall</code> or keep to the (probably stone-age) packaged version. For Ubuntu there is a <a href="https://launchpad.net/~chris-lea/+archive/ubuntu/node.js/">PPA</a> available.</p>
@@ -220,7 +222,27 @@ require("./build/Release/example")</pre>
 </div>
 <p>A more detailed explanation is given in the <a href="#Javascript_examples">Examples</a> section.</p>
 
-<H4><a name="Javascript_troubleshooting">27.3.1.1 Troubleshooting</a></H4>
+<H4><a name="Javascript_using_yeoman">28.3.1.1 Using <code>yeoman</code> to generate a Node-API skeleton</a></H4>
+
+
+<p>If targeting Node-API, the easiest way to bootstrap a project is by using the <code>yeoman</code> generator: </p>
+<div class="shell">
+<pre>
+$ sudo npm install -g yo
+$ sudo npm install -g generator-napi-module
+$ mkdir example
+$ cd example
+$ yo napi-module                     # the choice of template is irrelevant, SWIG will replace the C++ code
+$ npm install node-addon-api@latest  # the yeoman version is outdated
+$ swig -javascript -napi -c++ -o src/example.cc example.i
+$ node-gyp configure
+$ node-gyp build
+</pre>
+</div>
+<p>There is also the <a href="https://github.com/mmomtchev/node-magickwand"><code>node-magickwand</code></a> project that can be used as a tutorial for building and publishing a complex C++ library to
+  npm as a ready-to-use real-world binary module.</p>
+
+<H4><a name="Javascript_troubleshooting">28.3.1.2 Troubleshooting</a></H4>
 
 
 <ul>
@@ -232,12 +254,12 @@ require("./build/Release/example")</pre>
 $ sudo apt-get remove gyp</pre>
 </div>
 
-<H3><a name="Javascript_embedded_webkit">27.3.2 Embedded Webkit</a></H3>
+<H3><a name="Javascript_embedded_webkit">28.3.2 Embedded Webkit</a></H3>
 
 
 <p>Webkit is pre-installed on Mac OS X and available as a library for GTK.</p>
 
-<H4><a name="Javascript_osx">27.3.2.1 Mac OS X</a></H4>
+<H4><a name="Javascript_osx">28.3.2.1 Mac OS X</a></H4>
 
 
 <p>There is general information about programming with WebKit on <a href="https://developer.apple.com/library/mac/documentation/cocoa/conceptual/DisplayWebContent/DisplayWebContent.html">Apple Developer Documentation</a>. Details about <code>Cocoa</code> programming are not covered here.</p>
@@ -285,10 +307,10 @@ extern bool example_initialize(JSGlobalContextRef context, JSObjectRef* exports)
 @end</pre>
 </div>
 
-<H4><a name="Javascript_gtk">27.3.2.2 GTK</a></H4>
+<H4><a name="Javascript_gtk">28.3.2.2 GTK</a></H4>
 
 
-<p>There is general information about programming GTK at <a href="https://developer.gnome.org/gtk2/">GTK documentation</a> and in the <a href="https://developer.gnome.org/gtk-tutorial/">GTK tutorial</a>, and for Webkit there is a <a href="http://webkitgtk.org/reference/webkitgtk/stable/index.html">Webkit GTK+ API Reference</a>.</p>
+<p>There is general information about programming GTK at <a href="https://developer.gnome.org/gtk2/">GTK documentation</a> and in the <a href="https://developer.gnome.org/gtk-tutorial/">GTK tutorial</a>, and for Webkit there is a <a href="https://webkitgtk.org/reference/webkitgtk/stable/index.html">Webkit GTK+ API Reference</a>.</p>
 <p>An integration of a native extension 'example' would look like this:</p>
 <div class="code">
 <pre>
@@ -319,7 +341,7 @@ int main(int argc, char* argv[])
   ...
 
   // Load a web page into the browser instance
-  webkit_web_view_load_uri(webView, "http://www.webkitgtk.org/");
+  webkit_web_view_load_uri(webView, "https://www.webkitgtk.org/");
 
   ...
 
@@ -330,7 +352,7 @@ int main(int argc, char* argv[])
 }</pre>
 </div>
 
-<H3><a name="Javascript_applications_webkit">27.3.3 Creating Applications with node-webkit</a></H3>
+<H3><a name="Javascript_applications_webkit">28.3.3 Creating Applications with node-webkit</a></H3>
 
 
 <p>To get started with <code>node-webkit</code> there is a very informative set of <a href="https://github.com/rogerwang/node-webkit/wiki">wiki pages</a>.</p>
@@ -401,7 +423,7 @@ the main window.</p>
 
 <p>
 As known from <code>node.js</code> one can use <code>require</code> to load javascript modules.
-Additionally, <code>node-webkit</code> provides an API that allows to manipulate the window's menu,
+Additionally, <code>node-webkit</code> provides an API that allows manipulating the window's menu,
 open new windows, and many more things.
 </p>
 
@@ -421,12 +443,12 @@ open new windows, and many more things.
 };</pre>
 </div>
 
-<H2><a name="Javascript_examples">27.4 Examples</a></H2>
+<H2><a name="Javascript_examples">28.4 Examples</a></H2>
 
 
 <p>Some basic examples are shown here in more detail.</p>
 
-<H3><a name="Javascript_simple_example">27.4.1 Simple</a></H3>
+<H3><a name="Javascript_simple_example">28.4.1 Simple</a></H3>
 
 
 <p>The common example <code>simple</code> looks like this:</p>
@@ -474,9 +496,9 @@ example.Foo = 3.1415926;</pre>
 </div>
 <p>First the module <code>example</code> is loaded from the previously built extension. Global methods and variables are available in the scope of the module.</p>
 
-<p><b>Note</b>: ECMAScript 5, the currently implemented Javascript standard, does not have modules. <code>node.js</code> and other implementations provide this mechanism defined by the <a href="http://wiki.commonjs.org/wiki/CommonJS">CommonJS</a> group. For browsers this is provided by <a href="http://browserify.org">Browserify</a>, for instance.</p>
+<p><b>Note</b>: ECMAScript 5, the currently implemented Javascript standard, does not have modules. <code>node.js</code> and other implementations provide this mechanism defined by the <a href="https://wiki.commonjs.org/wiki/CommonJS">CommonJS</a> group. For browsers this is provided by <a href="https://browserify.org">Browserify</a>, for instance.</p>
 
-<H3><a name="Javascript_class_example">27.4.2 Class</a></H3>
+<H3><a name="Javascript_class_example">28.4.2 Class</a></H3>
 
 
 <p>The common example <code>class</code> defines three classes, <code>Shape</code>, <code>Circle</code>, and <code>Square</code>:</p>
@@ -606,15 +628,15 @@ at emitKey (readline.js:1095:12)</pre>
 <b>Note</b>: In ECMAScript 5 there is no concept for classes. Instead each function can be used as a constructor function which is executed by the 'new' operator. Furthermore, during construction the key property <code>prototype</code> of the constructor function is used to attach a prototype instance to the created object. A prototype is essentially an object itself that is the first-class delegate of a class used whenever the access to a property of an object fails. The very same prototype instance is shared among all instances of one type. Prototypal inheritance is explained in more detail on in <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain">Inheritance and the prototype chain</a>, for instance.
 </p>
 
-<H2><a name="Javascript_implementation">27.5 Implementation</a></H2>
+<H2><a name="Javascript_implementation">28.5 Implementation</a></H2>
 
 
 <p>The Javascript Module implementation has taken a very different approach compared to other language modules in order to support different Javascript interpreters.</p>
 
-<H3><a name="Javascript_source_code">27.5.1 Source Code</a></H3>
+<H3><a name="Javascript_source_code">28.5.1 Source Code</a></H3>
 
 
-<p>The Javascript module is implemented in <code>Source/Modules/javascript.cxx</code>. It dispatches the code generation to a <code>JSEmitter</code> instance, <code>V8Emitter</code> or <code>JSCEmitter</code>. Additionally there are some helpers: <code>Template</code>, for templated code generation, and <code>JSEmitterState</code>, which is used to manage state information during AST traversal. This rough map shall make it easier to find a way through this huge source file:</p>
+<p>The Javascript module is implemented in <code>Source/Modules/javascript.cxx</code>. It dispatches the code generation to a <code>JSEmitter</code> instance, <code>V8Emitter</code>, <code>JSCEmitter</code> or <code>NAPIEmitter</code>. Additionally there are some helpers: <code>Template</code>, for templated code generation, and <code>JSEmitterState</code>, which is used to manage state information during AST traversal. This rough map shall make it easier to find a way through this huge source file:</p>
 <div class="code">
 <pre>
 // module wide defines
@@ -638,6 +660,7 @@ class JSEmitter { ... };
 
 JSEmitter *swig_javascript_create_JSCEmitter();
 JSEmitter *swig_javascript_create_V8Emitter();
+JSEmitter *swig_javascript_create_NAPIEmitter();
 
 // ###############################
 // # Javascript module
@@ -712,10 +735,10 @@ Template::Template(const String *code_) { ... }
 ...</pre>
 </div>
 
-<H3><a name="Javascript_code_templates">27.5.2 Code Templates</a></H3>
+<H3><a name="Javascript_code_templates">28.5.2 Code Templates</a></H3>
 
 
-<p>All generated code is created on the basis of code templates. The templates for <em>JavascriptCore</em> can be found in <code>Lib/javascript/jsc/javascriptcode.swg</code>, for <em>v8</em> in <code>Lib/javascript/v8/javascriptcode.swg</code>.</p>
+<p>All generated code is created on the basis of code templates. The templates for <em>JavascriptCore</em> can be found in <code>Lib/javascript/jsc/javascriptcode.swg</code>, for <em>v8</em> in <code>Lib/javascript/v8/javascriptcode.swg</code> and for <em>Node-API</em> in <code>Lib/javascript/napi/javascriptcode.swg</code>.</p>
 <p>To track the originating code template for generated code you can run</p>
 <div class="shell">
 <pre>
@@ -751,7 +774,7 @@ t_register.replace("$jsparent", state.clazz(NAME_MANGLED))
 </div>
 <p><code>Template</code> creates a copy of that string and <code>Template::replace</code> uses Swig's <code>Replaceall</code> to replace variables in the template. <code>Template::trim</code> can be used to eliminate leading and trailing whitespaces. <code>Template::print</code> is used to write the final template string to a Swig <code>DOH</code> (based on <code>Printv</code>). All methods allow chaining.</p>
 
-<H3><a name="Javascript_emitter">27.5.3 Emitter</a></H3>
+<H3><a name="Javascript_emitter">28.5.3 Emitter</a></H3>
 
 
 <p>The Javascript module delegates code generation to a <code>JSEmitter</code> instance. The following extract shows the essential interface:</p>
@@ -870,7 +893,7 @@ int JAVASCRIPT::classHandler(Node *n) {
 </div>
 <p>In <code>enterClass</code> the emitter stores state information that is necessary when processing class members. In <code>exitClass</code> the wrapper code for the whole class is generated.</p>
 
-<H3><a name="Javascript_emitter_states">27.5.4 Emitter states</a></H3>
+<H3><a name="Javascript_emitter_states">28.5.4 Emitter states</a></H3>
 
 
 <p>For storing information during the AST traversal the emitter provides a <code>JSEmitterState</code> with different slots to store data representing the scopes global, class, function, and variable.</p>
@@ -914,7 +937,7 @@ state.clazz(NAME, Getattr(n, "sym:name"));</pre>
 <p>State information can be retrieved using <code>state.clazz(NAME)</code> or with <code>Getattr</code> on <code>state.clazz()</code> which actually returns a <code>Hash</code> instance.</p>
 
 
-<H3><a name="Javascript_jsc_exceptions">27.5.5 Handling Exceptions in JavascriptCore</a></H3>
+<H3><a name="Javascript_jsc_exceptions">28.5.5 Handling Exceptions in JavascriptCore</a></H3>
 
 
 <p>Applications with an embedded JavascriptCore should be able to present detailed exception messages that occur in the Javascript engine. Below is an example derived from code provided by Brian Barnes on how these exception details can be extracted.</p>
@@ -994,5 +1017,30 @@ if(js_exception)
 }</pre>
 </div>
 
+<H3><a name="Javascript_napi_exceptions">28.5.6 Handling Exceptions in Node-API</a></H3>
+
+
+<p>Node-API is the only generator that provides fully automatic conversion of C++ exceptions to JavaScript exceptions when building with C++ exceptions enabled in `binding.gyp`:</p>
+<div class="code">
+<pre>
+'conditions': [
+  ['OS=="mac"',
+    {
+      'xcode_settings': {
+        'GCC_ENABLE_CPP_RTTI': 'YES',
+        'GCC_ENABLE_CPP_EXCEPTIONS' : 'YES'
+      }
+    }
+  ],
+  ['OS=="linux" or OS=="freebsd" or OS=="openbsd" or OS=="solaris"',
+    {
+      'cflags!': [ '-fno-exceptions' ],
+      'cflags_cc!': [ '-fno-exceptions', '-fno-rtti' ]
+    }
+  ]
+]
+</pre>
+</div>
+<p>In this case, nothing else is needed for the C++ exceptions to be passed to JavaScript.</p>
 </body>
 </html>

Doc/Manual/Library.html

@@ -7,13 +7,14 @@
 </head>
 
 <body bgcolor="#ffffff">
-<H1><a name="Library">11 SWIG library</a></H1>
+<H1><a name="Library">12 SWIG library</a></H1>
 <!-- INDEX -->
 <div class="sectiontoc">
 <ul>
 <li><a href="#Library_nn2">The %include directive and library search path</a>
 <li><a href="#Library_nn3">C arrays and pointers</a>
 <ul>
+<li><a href="#Library_argcargv">argcargv.i</a>
 <li><a href="#Library_nn4">cpointer.i</a>
 <li><a href="#Library_carrays">carrays.i</a>
 <li><a href="#Library_nn6">cmalloc.i</a>
@@ -29,6 +30,7 @@
 <li><a href="#Library_stl_cpp_library">STL/C++ library</a>
 <ul>
 <li><a href="#Library_std_string">std::string</a>
+<li><a href="#Library_std_string_view">std::string_view</a>
 <li><a href="#Library_std_vector">std::vector</a>
 <li><a href="#Library_stl_exceptions">STL exceptions</a>
 <li><a href="#Library_std_shared_ptr">shared_ptr smart pointer</a>
@@ -39,11 +41,16 @@
 <li><a href="#Library_shared_ptr_templates">shared_ptr and templates</a>
 <li><a href="#Library_shared_ptr_directors">shared_ptr and directors</a>
 </ul>
+<li><a href="#Library_std_unique_ptr">unique_ptr smart pointer</a>
 <li><a href="#Library_std_auto_ptr">auto_ptr smart pointer</a>
 </ul>
 <li><a href="#Library_nn16">Utility Libraries</a>
 <ul>
 <li><a href="#Library_nn17">exception.i</a>
+<li><a href="#Library_attributes">attribute.i</a>
+<ul>
+<li><a href="#Library_attribute_templates">%attribute and C++ templates</a>
+</ul>
 </ul>
 </ul>
 </div>
@@ -67,7 +74,7 @@ Alternative libraries provide similar functionality.  Please read this chapter
 carefully if you used the old libraries.
 </p>
 
-<H2><a name="Library_nn2">11.1 The %include directive and library search path</a></H2>
+<H2><a name="Library_nn2">12.1 The %include directive and library search path</a></H2>
 
 
 <p>
@@ -99,7 +106,7 @@ Set the environment variable to hold an alternative library directory.
 The directories that are searched are displayed when using <tt>-verbose</tt> commandline option.
 </p>
 
-<H2><a name="Library_nn3">11.2 C arrays and pointers</a></H2>
+<H2><a name="Library_nn3">12.2 C arrays and pointers</a></H2>
 
 
 <p>
@@ -111,7 +118,48 @@ pointers as class-like objects.   Since these functions provide direct access to
 memory, their use is potentially unsafe and you should exercise caution.
 </p>
 
-<H3><a name="Library_nn4">11.2.1 cpointer.i</a></H3>
+<H3><a name="Library_argcargv">12.2.1 argcargv.i</a></H3>
+
+
+<p>
+The argcargv.i library is a simple library providing multi-argument typemaps for handling C
+argc argv command line argument C string arrays.
+The <tt>argc</tt> parameter contains the argument count and <tt>argv</tt> contains the argument vector array.
+</p>
+
+<p>
+This library provides the following multi-argument typemap:
+</p>
+
+<p>
+<b><tt>(int ARGC, char **ARGV)</tt></b>
+</p>
+
+<p>
+Apply this multi-argument typemap to your use case, for example:
+</p>
+
+<div class="code">
+<pre>
+%apply (int ARGC, char **ARGV) { (size_t argc, const char **argv) }
+
+int mainApp(size_t argc, const char **argv);
+</pre>
+</div>
+
+<p>
+then from Ruby:
+</p>
+
+<div class="targetlang">
+<pre>
+$args = ["myarg1", "myarg2"]
+mainApp(args);
+</pre>
+</div>
+
+
+<H3><a name="Library_nn4">12.2.2 cpointer.i</a></H3>
 
 
 <p>
@@ -327,7 +375,7 @@ In this example,  the function <tt>int_to_uint()</tt> would be used to cast type
 <b>Note:</b> When working with simple pointers, typemaps can often be used to provide more seamless operation.
 </p>
 
-<H3><a name="Library_carrays">11.2.2 carrays.i</a></H3>
+<H3><a name="Library_carrays">12.2.3 carrays.i</a></H3>
 
 
 <p>
@@ -345,7 +393,7 @@ raw C array data.
 <p>Creates four functions.</p>
 
 <p>
-<tt>type *new_name(int nelements)</tt>
+<tt>type *new_name(size_t nelements)</tt>
 </p>
 
 <div class="indent"><p>
@@ -362,7 +410,7 @@ Deletes an array. In C, <tt>free()</tt> is used.  In C++, <tt>delete []</tt> is
 </p></div>
 
 <p>
-<tt>type name_getitem(type *ary, int index)</tt>
+<tt>type name_getitem(type *ary, size_t index)</tt>
 </p>
 
 <div class="indent"><p>
@@ -370,7 +418,7 @@ Returns the value <tt>ary[index]</tt>.
 </p></div>
 
 <p>
-<tt>void name_setitem(type *ary, int index, type value)</tt>
+<tt>void name_setitem(type *ary, size_t index, type value)</tt>
 </p>
 
 <div class="indent"><p>
@@ -443,10 +491,10 @@ interface is as follows:
 <div class="code">
 <pre>
 struct name {
-  name(int nelements);                  // Create an array
+  name(size_t nelements);               // Create an array
   ~name();                              // Delete array
-  type getitem(int index);              // Return item
-  void setitem(int index, type value);  // Set item
+  type getitem(size_t index);           // Return item
+  void setitem(size_t index, type value);  // Set item
   type *cast();                         // Cast to original type
   static name *frompointer(type *);     // Create class wrapper from
                                         // existing pointer
@@ -506,7 +554,7 @@ used with types of <tt>char</tt> or <tt>char *</tt>.
 SWIG's default handling of these types is to handle them as character strings and the two macros do not do enough to change this.
 </p>
 
-<H3><a name="Library_nn6">11.2.3 cmalloc.i</a></H3>
+<H3><a name="Library_nn6">12.2.4 cmalloc.i</a></H3>
 
 
 <p>
@@ -667,7 +715,7 @@ Now, in a script:
 </pre>
 </div>
 
-<H3><a name="Library_nn7">11.2.4 cdata.i</a></H3>
+<H3><a name="Library_nn7">12.2.5 cdata.i</a></H3>
 
 
 <p>
@@ -769,7 +817,7 @@ char *cdata_<em>name</em>(type* ptr, int nitems)
 Clearly they are unsafe.
 </p>
 
-<H2><a name="Library_nn8">11.3 C string handling</a></H2>
+<H2><a name="Library_nn8">12.3 C string handling</a></H2>
 
 
 <p>
@@ -789,7 +837,7 @@ morality.  The modules in this section provide basic functionality
 for manipulating raw C strings.
 </p>
 
-<H3><a name="Library_nn9">11.3.1 Default string handling</a></H3>
+<H3><a name="Library_nn9">12.3.1 Default string handling</a></H3>
 
 
 <p>
@@ -830,7 +878,7 @@ interpreter and lead to a crash).  Furthermore, the default behavior does
 not work well with binary data. Instead, strings are assumed to be NULL-terminated.
 </p>
 
-<H3><a name="Library_nn10">11.3.2 Passing binary data</a></H3>
+<H3><a name="Library_nn10">12.3.2 Passing binary data</a></H3>
 
 
 <p>
@@ -872,7 +920,7 @@ In the wrapper function, the passed string will be expanded to a pointer and len
 The <tt>(char *STRING, int LENGTH)</tt> multi-argument typemap is also available in addition to <tt>(char *STRING, size_t LENGTH)</tt>.
 </p>
 
-<H3><a name="Library_nn11">11.3.3 Using %newobject to release memory</a></H3>
+<H3><a name="Library_nn11">12.3.3 Using %newobject to release memory</a></H3>
 
 
 <p>
@@ -913,7 +961,7 @@ however, you may need to provide your own "newfree" typemap for other types.
 See <a href="Customization.html#Customization_ownership">Object ownership and %newobject</a> for more details.
 </p>
 
-<H3><a name="Library_nn12">11.3.4 cstring.i</a></H3>
+<H3><a name="Library_nn12">12.3.4 cstring.i</a></H3>
 
 
 <p>
@@ -1373,7 +1421,7 @@ structure or class instead.
 </li>
 </ul>
 
-<H2><a name="Library_stl_cpp_library">11.4 STL/C++ library</a></H2>
+<H2><a name="Library_stl_cpp_library">12.4 STL/C++ library</a></H2>
 
 
 <p>
@@ -1403,14 +1451,15 @@ The following table shows which C++ classes are supported and the equivalent SWI
 <tr> <td>std::multiset (C++11)</td>           <td>multiset</td>             <td>std_multiset.i</td> </tr>
 <tr> <td>std::pair</td>           <td>utility</td>             <td>std_pair.i</td> </tr>
 <tr> <td>std::set</td>           <td>set</td>             <td>std_set.i</td> </tr>
+<tr> <td>std::shared_ptr (C++11)</td>           <td>shared_ptr</td>             <td>std_shared_ptr.i</td> </tr>
 <tr> <td>std::string</td>           <td>string</td>             <td>std_string.i</td> </tr>
+<tr> <td>std::string_view (C++17)</td>           <td>string_view</td>             <td>std_string_view.i</td> </tr>
 <tr> <td>std::unordered_map (C++11)</td>           <td>unordered_map</td>             <td>std_unordered_map.i</td> </tr>
 <tr> <td>std::unordered_multimap (C++11)</td>           <td>unordered_multimap</td>             <td>std_unordered_multimap.i</td> </tr>
 <tr> <td>std::unordered_multiset (C++11)</td>           <td>unordered_multiset</td>             <td>std_unordered_multiset.i</td> </tr>
 <tr> <td>std::unordered_set (C++11)</td>           <td>unordered_set</td>             <td>std_unordered_set.i</td> </tr>
 <tr> <td>std::vector</td>           <td>vector</td>             <td>std_vector.i</td> </tr>
 <tr> <td>std::wstring</td>           <td>wstring</td>             <td>std_wstring.i</td> </tr>
-<tr> <td>std::shared_ptr (C++11)</td>           <td>shared_ptr</td>             <td>std_shared_ptr.i</td> </tr>
 
 </table>
 
@@ -1420,7 +1469,7 @@ Please look for the library files in the appropriate language library directory.
 </p>
 
 
-<H3><a name="Library_std_string">11.4.1 std::string</a></H3>
+<H3><a name="Library_std_string">12.4.1 std::string</a></H3>
 
 
 <p>
@@ -1504,7 +1553,51 @@ void foo(string s, const String &amp;t);     // std_string typemaps still applie
 </pre>
 </div>
 
-<H3><a name="Library_std_vector">11.4.2 std::vector</a></H3>
+<H3><a name="Library_std_string_view">12.4.2 std::string_view</a></H3>
+
+
+<p>
+The <tt>std_string_view.i</tt> library provides typemaps for converting C++17 <tt>std::string_view</tt>
+objects to and from strings in the target scripting language.  For example:
+</p>
+
+<div class="code">
+<pre>
+%module example
+%include "std_string_view.i"
+
+std::string_view foo();
+void        bar(std::string_view x);
+</pre>
+</div>
+
+<p>
+In the target language:
+</p>
+
+<div class="targetlang">
+<pre>
+x = foo();                # Returns a string object
+bar("Hello World");       # Pass string as std::string_view
+</pre>
+</div>
+
+<p>
+For target languages for which SWIG supports directors, <tt>directorout</tt>
+typemaps are provided for <tt>std::string_view</tt>, but these require extra
+care to use safely.  The issue is that returning <tt>std::string_view</tt>
+effectively returns a pointer to string data but doesn't own the pointed to
+data.  For target languages where there isn't a native narrow string
+representation (e.g. C#, Java) a <tt>static std::string</tt> is used to cache
+the data, which works but isn't thread/reentrant safe.  For target languages
+where there is a native narrow string representation SWIG will return a
+<tt>std::string_view</tt> pointing to that data, so you need to store the
+string to return somewhere which will persist for the lifetime the caller
+needs (e.g. put it in a member variable) - you can't return a temporary target
+language string.  In both cases SWIG will issue a warning by default.
+</p>
+
+<H3><a name="Library_std_vector">12.4.3 std::vector</a></H3>
 
 
 <p>
@@ -1683,7 +1776,7 @@ if you want to make their head explode.
 details and the public API exposed to the interpreter vary.
 </p>
 
-<H3><a name="Library_stl_exceptions">11.4.3 STL exceptions</a></H3>
+<H3><a name="Library_stl_exceptions">12.4.4 STL exceptions</a></H3>
 
 
 <p>
@@ -1733,10 +1826,10 @@ The <tt>%exception</tt> directive can be used by placing the following code befo
 Any thrown STL exceptions will then be gracefully handled instead of causing a crash.
 </p>
 
-<H3><a name="Library_std_shared_ptr">11.4.4 shared_ptr smart pointer</a></H3>
+<H3><a name="Library_std_shared_ptr">12.4.5 shared_ptr smart pointer</a></H3>
 
 
-<H4><a name="Library_shared_ptr_basics">11.4.4.1 shared_ptr basics</a></H4>
+<H4><a name="Library_shared_ptr_basics">12.4.5.1 shared_ptr basics</a></H4>
 
 
 <p>
@@ -1779,7 +1872,7 @@ In order to use <tt>boost::shared_ptr</tt>, the <tt>boost_shared_ptr.i</tt> libr
 
 <p>
 You can only use one of these variants of shared_ptr in your interface file at a time.
-and all three variants must be used in conjunction with the <tt>%shared_ptr(T)</tt> macro,
+All three variants must be used in conjunction with the <tt>%shared_ptr(T)</tt> macro,
 where <tt>T</tt> is the underlying pointer type equating to usage <tt>shared_ptr&lt;T&gt;</tt>.
 The type <tt>T</tt> must be non-primitive.
 A simple example demonstrates usage:
@@ -1832,7 +1925,7 @@ System.out.println(val1 + " " + val2);
 </pre>
 </div>
 
-<H4><a name="Library_shared_ptr_inheritance">11.4.4.2 shared_ptr and inheritance</a></H4>
+<H4><a name="Library_shared_ptr_inheritance">12.4.5.2 shared_ptr and inheritance</a></H4>
 
 
 <p>
@@ -1923,7 +2016,7 @@ Adding the missing <tt>%shared_ptr</tt> macros will fix this:
 </pre>
 </div>
 
-<H4><a name="Library_shared_ptr_overloading">11.4.4.3 shared_ptr and method overloading</a></H4>
+<H4><a name="Library_shared_ptr_overloading">12.4.5.3 shared_ptr and method overloading</a></H4>
 
 
 <p>
@@ -1945,7 +2038,7 @@ SWIG will choose to wrap just the first method by default.
 For the interested reader, SWIG detects that they are equivalent types via the <a href=Typemaps.html#Typemaps_typecheck_pointer>typecheck typemaps</a> in the shared_ptr library.
 </p>
 
-<H4><a name="Library_shared_ptr_templates">11.4.4.4 shared_ptr and templates</a></H4>
+<H4><a name="Library_shared_ptr_templates">12.4.5.4 shared_ptr and templates</a></H4>
 
 
 <p>
@@ -1987,45 +2080,48 @@ The SWIG code below shows the required ordering:
 </pre>
 </div>
 
-<H4><a name="Library_shared_ptr_directors">11.4.4.5 shared_ptr and directors</a></H4>
+<H4><a name="Library_shared_ptr_directors">12.4.5.5 shared_ptr and directors</a></H4>
 
 
 <p>
 The languages that support shared_ptr also have support for using shared_ptr with directors.
 </p>
 
-
-<H3><a name="Library_std_auto_ptr">11.4.5 auto_ptr smart pointer</a></H3>
+<H3><a name="Library_std_unique_ptr">12.4.6 unique_ptr smart pointer</a></H3>
 
 
 <p>
-While <tt>std::auto_ptr</tt> is deprecated in C++11, some existing code may
-still be using it, so SWIG provides limited support for this class:
-<tt>std_auto_ptr.i</tt> defines the typemaps which apply to the functions
-returning objects of this type. Any other use of <tt>std_auto_ptr.i</tt> is not
-directly supported.
+The <tt>std_unique_ptr.i</tt> library file provides SWIG's unique_ptr support.
+It defines typemaps and a macro, <tt>%unique_ptr(T)</tt>, to use for handling
+<tt>std::unique_ptr&lt;T&gt;</tt> for a type <tt>T</tt>.
+The type <tt>T</tt> must be non-primitive.
+This macro should be used before any code declaring or using type <tt>T</tt>.
+Ordering requirements for using this smart pointer macro are the same as the
+equivalent <tt>%shared_ptr(T)</tt> macro covered in the previous section.
 </p>
 
 <p>
-A typical example of use would be
+Example usage of a <tt>std::unique_ptr</tt> being returned from a function is shown below.
 </p>
+
 <div class="code">
 <pre>
-%include &lt;std_auto_ptr.i&gt;
+%include &lt;std_unique_ptr.i&gt;
 
-%auto_ptr(Klass)
+%unique_ptr(Klass)
 %inline %{
+#include &lt;memory&gt;
 class Klass {
 public:
   // Factory function creating objects of this class:
-  static std::auto_ptr&lt;Klass&gt; Create(int value) {
-    return std::auto_ptr&lt;Klass&gt;(new Klass(value));
+  static std::unique_ptr&lt;Klass&gt; Create(int value) {
+    return std::unique_ptr&lt;Klass&gt;(new Klass(value));
   }
 
   int getValue() const { return m_value; }
 
 private:
-  DerivedIntValue(int value) : m_value(value) {}
+  Klass(int value) : m_value(value) {}
   int m_value;
 };
 %}
@@ -2044,10 +2140,148 @@ int value = k.getValue();
 </pre>
 </div>
 
-<H2><a name="Library_nn16">11.5 Utility Libraries</a></H2>
+<p>
+The implementation simply calls <tt>std::unique_ptr::release()</tt> to obtain
+the underlying raw pointer. The pointer is then used to create a target language
+proxy class in the same way that SWIG handles a C++ function returning a class by value.
+The target language proxy class then owns the memory pointed to by the raw pointer
+and memory handling is identical to normal SWIG proxy class handling of the underlying C++ memory.
+Note that an object returned by value is first copied/moved from the stack onto the heap in order to obtain
+a raw pointer on the heap, whereas the underlying raw pointer in <tt>std::unique_ptr</tt> already points to an object the heap.
+</p>
+
+<p>
+Note that the implementation is quite different to the <tt>std::shared_ptr</tt> smart pointer,
+where the proxy class manages the underlying C++ memory as a pointer to a shared_ptr instead of a plain raw pointer.
+</p>
+
+<p>
+A possibly less common usage of this smart pointer is as a parameter to a function.
+When used like this it indicates that memory usage of the object pointed to by the underlying pointer
+is transferred to the function being called.
+The code that SWIG generates assumes this happens.
+First, it is assumed that a proxy class already owns the underlying C++ object and is used to pass the object to the C++ function being called.
+Second, the ownership is transferred from the proxy class to the C++ function being called and
+lifetime is then controlled by the function.
+Finally, it is assumed the lifetime of the object may not last beyond returning from the C++ function
+and hence the proxy class can no longer be used.
+</p>
+
+<p>
+Consider expanding the example above with a function that takes a <tt>std::unique_ptr</tt> as follows:
+</p>
+
+<div class="code">
+<pre>
+void take(std::unique_ptr&lt;Klass&gt;);
+</pre>
+</div>
+
+<p>
+and use from C#:
+</p>
+
+<div class="targetlang">
+<pre>
+Klass k = Klass.Create(17); // create an instance of Klass any way you like
+int value = k.getValue();   // ok
+example.take(k);            // memory ownership passes from C# layer to C++ layer
+int v = k.getValue();       // don't do this - invalid use of k
+</pre>
+</div>
+
+<p>
+Attempts to use <tt>k</tt> after the ownership has been passed into the <tt>take</tt> function
+should not be attempted.
+The implementation sets the proxy class to an invalid state by setting the class's underlying
+C++ pointer to null after the return from the <tt>take</tt> function.
+Subsequent use of an invalid proxy class instance is very much dependent on the implementation
+in the target language and ranges from a segfault to giving a nice error.
+Consider implementing additional checks via the 'check' typemap.
+</p>
+
+<p>
+Attempts to pass ownership from a proxy class to a <tt>std::unique</tt> parameter more than once will result
+in a "Cannot release ownership as memory is not owned" exception. For example, if <tt>example.take(k)</tt> in the example above is called twice.
+</p>
+
+<p>
+<b>Compatibility note:</b> Support for <tt>std::unique_ptr</tt> was added in SWIG-4.1.0.
+</p>
+
+<H3><a name="Library_std_auto_ptr">12.4.7 auto_ptr smart pointer</a></H3>
 
 
-<H3><a name="Library_nn17">11.5.1 exception.i</a></H3>
+<p>
+While <tt>std::auto_ptr</tt> is deprecated in C++11, some existing code may
+still be using it. SWIG provides support for this class which is nearly identical
+to <tt>std::unique_ptr</tt>.
+</p>
+
+<p>
+The <tt>std_auto_ptr.i</tt> library file provides SWIG's auto_ptr support.
+It defines typemaps and a macro, <tt>%auto_ptr(T)</tt>, to use for handling
+<tt>std::auto_ptr&lt;T&gt;</tt> for a type <tt>T</tt>.
+The type <tt>T</tt> must be non-primitive.
+This macro should be used before any code declaring or using type <tt>T</tt>.
+Ordering requirements for using this smart pointer macro are the same as the
+equivalent <tt>%shared_ptr(T)</tt> and <tt>%unique_ptr</tt> macros covered in
+the previous two sections.
+</p>
+
+<p>
+Example usage of a <tt>std::auto_ptr</tt> being returned from a function is shown below.
+</p>
+
+<div class="code">
+<pre>
+%include &lt;std_auto_ptr.i&gt;
+
+%auto_ptr(Klass)
+%inline %{
+#include &lt;memory&gt;
+class Klass {
+public:
+  // Factory function creating objects of this class:
+  static std::auto_ptr&lt;Klass&gt; Create(int value) {
+    return std::auto_ptr&lt;Klass&gt;(new Klass(value));
+  }
+
+  int getValue() const { return m_value; }
+
+private:
+  Klass(int value) : m_value(value) {}
+  int m_value;
+};
+%}
+</pre>
+</div>
+
+<p>
+The returned objects can be used naturally from the target language, e.g. from
+C#:
+</p>
+
+<div class="targetlang">
+<pre>
+Klass k = Klass.Create(17);
+int value = k.getValue();
+</pre>
+</div>
+
+<p>
+The implementation simply calls <tt>std::auto_ptr::release()</tt> to obtain the underlying raw pointer.
+That is, it works the same way covered in the previous section for <tt>std::unique_ptr</tt>.
+</p>
+
+<p>
+Input parameters also work the same way as <tt>std::unique_ptr</tt> covered in the previous section.
+</p>
+
+<H2><a name="Library_nn16">12.5 Utility Libraries</a></H2>
+
+
+<H3><a name="Library_nn17">12.5.1 exception.i</a></H3>
 
 
 <p>
@@ -2108,5 +2342,244 @@ For example:
 </div>
 
 
+<H3><a name="Library_attributes">12.5.2 attribute.i</a></H3>
+
+
+<p>
+The attribute library contains a set of macros to convert a pair of set/get methods
+into a "native" attribute/property.
+</p>
+
+<p>
+Use <tt>%attribute</tt> when you have a pair of get/set methods to a
+primitive type like:
+</p>
+
+<div class="code">
+<pre>
+%include "attribute.i"
+%attribute(A, int, a, get_a, set_a);
+
+struct A {
+  int get_a() const;
+  void set_a(int aa);
+};
+</pre>
+</div>
+
+<p>
+and you want to provide that variable as an attribute in the target
+language. This example only works for primitive types, not derived
+types.
+Now you can use the attributes like so (in Python):
+</p>
+
+<div class="targetlang">
+<pre>
+x = A()
+x.a = 3        # calls A::set_a(3)
+print(x.a)     # calls A::get_a() const
+</pre>
+</div>
+
+<p>
+If you don't provide a 'set' method, a 'read-only' attribute
+is generated, ie, like:
+</p>
+
+<div class="code">
+<pre>
+%attribute(A, int, c, get_c);
+</pre>
+</div>
+
+<p>
+Use <tt>%attributeref</tt> when you have const/non-const reference
+access methods for primitive types or class/structs, like:
+</p>
+
+<div class="code">
+<pre>
+%attributeref(A, int, b);
+
+struct A {
+  const int &amp; b() const;
+  int &amp; b();
+};
+
+%attributeref(B, int, c);
+
+struct B {
+  int &amp; c();
+};
+</pre>
+</div>
+
+<p>
+Use the attributes like so (in Python):
+</p>
+
+<div class="targetlang">
+<pre>
+x = A()
+x.b = 3        # calls A::b()
+print(x.b)     # calls A::b() const
+</pre>
+</div>
+
+<p>
+You can also use
+</p>
+
+<div class="code">
+<pre>
+%attributeref(Class, AttributeType, AttributeName, AccessorMethod)
+</pre>
+</div>
+
+<p>
+if the internal C++ reference methods have a different name from the
+attribute you want, so
+</p>
+
+<div class="code">
+<pre>
+%attributeref(B, int, d, c);
+</pre>
+</div>
+
+<p>
+is the same as the last example, but instead of the attribute 'c' being
+called 'c', it is called 'd'.
+</p>
+
+<p>
+Use <tt>%attribute2</tt> instead of <tt>%attribute</tt> to indicate
+that reference-pointer translation is required.
+Use <tt>%attribute2</tt> instead of <tt>%attribute</tt> in cases like
+this:
+</p>
+
+<div class="code">
+<pre>
+%attribute2(MyClass, MyFoo, Foo, GetFoo, SetFoo);
+%inline %{
+  struct MyFoo {
+    int x;
+  };
+  class MyClass {
+    MyFoo foo;
+  public:
+    MyFoo &amp; GetFoo() { return foo; }
+    void SetFoo(const MyFoo &amp;other) { foo = other; }
+  };
+%}
+</pre>
+</div>
+
+<p>
+Here, the data type of the property is a wrapped type <tt>MyFoo</tt> and on
+the C++ side it is passed by reference. The problem is that the SWIG
+wrapper will pass around a pointer (MyFoo *) which is not compatible
+with the reference type of the accessors (MyFoo &amp;). Therefore, if you
+use <tt>%attribute</tt>, you'll get an error from your C/C++
+compiler. <tt>%attribute2</tt> translates between a pointer and a
+reference to eliminate the error. In case you're confused, let's make
+it simple: just use <tt>%attribute</tt> at first, but if the C/C++
+compiler gives an error while compiling the wrapper,
+try <tt>%attribute2</tt> instead.
+</p>
+
+<p>
+NOTE: remember that if the type contains commas, such as
+<tt>std::pair&lt;int, int&gt;</tt>, you need to use the macro like:
+</p>
+
+<div class="code">
+<pre>
+%attributeref(A, %arg(std::pair&lt;int, int&gt;), pval);
+</pre>
+</div>
+
+<p>
+where <tt>%arg()</tt> 'normalizes' the type to be understood as a single
+argument, otherwise the macro will get confused by the comma.
+</p>
+
+<p>
+The <tt>%attributeval</tt> is the same as <tt>%attribute</tt>, but
+should be used when the type is a class/struct (ie a non-primitive
+type) and when the get and set methods return/pass by value. The
+following is very similar to the above example, but note that the
+access is by value rather than reference.
+</p>
+
+<div class="code">
+<pre>
+%attributeval(MyClassVal, MyFoo, ReadWriteFoo, GetFoo, SetFoo);
+%attributeval(MyClassVal, MyFoo, ReadOnlyFoo, GetFoo);
+%inline %{
+  class MyClassVal {
+    MyFoo foo;
+  public:
+    MyFoo GetFoo() { return foo; }
+    void SetFoo(MyFoo other) { foo = other; }
+  };
+%}
+</pre>
+</div>
+
+<p>
+The <tt>%attributestring</tt> is the same as <tt>%attributeval</tt>,
+but should be used for string class types, which are unusual as they
+are a class on the C++ side, but normally an immutable/primitive type
+in the target language. Example usage for <tt>std::string</tt>:
+</p>
+
+<div class="code">
+<pre>
+%include &lt;std_string.i&gt;
+%attributestring(MyStringyClass, std::string, ReadWriteString, GetString, SetString);
+%attributestring(MyStringyClass, std::string, ReadOnlyString, GetString);
+%inline %{
+  class MyStringyClass {
+    std::string str;
+  public:
+    MyStringyClass(const std::string &amp;val) : str(val) {}
+    std::string GetString() { return str; }
+    void SetString(std::string other) { str = other; }
+  };
+%}
+</pre>
+</div>
+
+<p>
+The <tt>%attributestring</tt> also works for class types that
+have <tt>%naturalvar</tt> turned on and so is also useful for
+shared_ptr which has <tt>%naturalvar</tt> turned on in
+<tt>%shared_ptr</tt>.
+</p>
+
+<H4><a name="Library_attribute_templates">12.5.2.1 %attribute and C++ templates</a></H4>
+
+
+<p>
+  <tt>%attribute</tt> and friends have to be used on fully specified classes. For example
+</p>
+<div class="code">
+<pre>
+%attributeref(A&lt;int&gt;, int, a);
+%inline %{
+  template &lt;class T&gt; struct A {
+    T a() const;
+    void a(T &amp;);
+  };
+%}
+</pre>
+</div>
+<p>
+Note the use of a template-id (i.e., <tt>A&lt;int&gt;</tt> not <tt>A&lt;T&gt;</tt> or just <tt>A</tt>).
+This means that <tt>%attribute</tt> statements have to be repeated for any template-id that you want to use with <tt>%template</tt>.
+</p>
 </body>
 </html>

Doc/Manual/Lisp.html

@@ -1,604 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<title>SWIG and Common Lisp</title>
-<link rel="stylesheet" type="text/css" href="style.css">
-<meta http-equiv="content-type" content="text/html; charset=UTF-8">
-</head>
-
-<body bgcolor="#ffffff">
-<H1><a name="Lisp">29 SWIG and Common Lisp</a></H1>
-<!-- INDEX -->
-<div class="sectiontoc">
-<ul>
-<li><a href="#Lisp_nn3">Common Foreign Function Interface(CFFI)</a>
-<ul>
-<li><a href="#Lisp_nn4">Additional Commandline Options </a>
-<li><a href="#Lisp_nn5">Generating CFFI bindings</a>
-<li><a href="#Lisp_nn6">Generating CFFI bindings for C++ code</a>
-<li><a href="#Lisp_nn7">Inserting user code into generated files</a>
-</ul>
-<ul>
-<li><a href="#Lisp_nn9">Additional Commandline Options </a>
-</ul>
-</ul>
-</div>
-<!-- INDEX -->
-
-
-
-<p>
-      Common Lisp is a high-level, all-purpose, object-oriented,
-      dynamic, functional programming language with long history. 
-      Common Lisp is used in many fields, ranging from web development to
-      finance, and also common in computer science education.
-      There are more than 9 different implementations of common lisp which
-      are available, all have different foreign function
-      interfaces. SWIG currently supports the
-      Common Foreign Function Interface(CFFI).
-</p>
-
-<H2><a name="Lisp_nn3">29.2 Common Foreign Function Interface(CFFI)</a></H2>
-
-
-<p>
-      CFFI, the Common Foreign Function Interface, is a portable foreign
-      function interface for ANSI Common Lisp systems.
-      CFFI requires only a small set of
-      low-level functionality from the Lisp implementation, such as
-      calling a foreign function by name, allocating foreign memory,
-      and dereferencing pointers.  
-</p>
-
-<p>
-      To run the cffi module of SWIG requires very little effort, you
-      just need to run:
-</p>
-<div class="code"><pre>
-swig -cffi -module <i>module-name</i>   <i>file-name</i> 
-
-</pre></div>
-
-<p>
-      But a better was of using all the power of SWIG is to write SWIG
-      interface files. Below we will explain how to write interface
-      files and the various things which you can do with them.
-</p>
-
-<H3><a name="Lisp_nn4">29.2.1 Additional Commandline Options </a></H3>
-
-
-<table summary="CFFI specific options">
-<tr>
- <th> CFFI specific options</th>
-</tr>
-
-<tr>
-<td>-generate-typedef</td>
-<td>If this option is given then defctype will be used to generate<br/>
-      shortcuts according to the typedefs in the input.
-</td>
-</tr>
-
-<tr>
-<td>-[no]cwrap</td>
-<td>Turn on or turn off generation of an intermediate C file when<br/>
-    creating a C interface. By default this is only done for C++ code.
-</td>
-</tr>
-
-<tr>
-<td>-[no]swig-lisp</td>
-<td>Turns on or off generation of code for helper lisp macro, functions,
-      etc. which SWIG uses while generating wrappers. These macros, functions
-      may still be used by generated wrapper code.
-</td>
-</tr>
-
-</table>
-
-<H3><a name="Lisp_nn5">29.2.2 Generating CFFI bindings</a></H3>
-
-
-<p>
-
-As we mentioned earlier the ideal way to use SWIG is to use interface
-    files. To illustrate the use of it, let's assume that we have a
-    file named <i>test.h</i> with the following C code:
-</p>
-
-<div class="code"><pre>
-#define y 5
-#define x (y &gt;&gt;  1)
-
-typedef int days;
-
-struct bar {
-  short p, q;
-  char a, b;
-  int *z[1000];
-  struct bar * n;
-};
-  
-struct   bar * my_struct;
-
-struct foo {
-  int a;
-  struct foo * b[100];
-};
-
-int pointer_func(void (*ClosureFun)( void* _fun, void* _data, void* _evt ), int p);
-
-int func123(div_t * p, int **q[100], int r[][1000][10]);
-
-void lispsort_double (int n, double * array);
-
-enum color { RED, BLUE, GREEN};
-</pre></div>
-
-<p>
-Corresponding to this we will write a simple interface file:
-</p>
-
-<div class="code"><pre>
-%module test
-
-%include "test.h"
-
-</pre></div>
-
-<p>
-The generated SWIG Code will be:
-</p>
-
-<div class="targetlang"><pre>
-;;;SWIG wrapper code starts here
-
-(cl:defmacro defanonenum (&amp;body enums)
-   "Converts anonymous enums to defconstants."
-  `(cl:progn , @(cl:loop for value in enums
-                        for index = 0 then (cl:1+ index)
-                        when (cl:listp value) do (cl:setf index (cl:second value)
-                                                          value (cl:first value))
-                        collect `(cl:defconstant , value , index))))
-
-(cl:eval-when (:compile-toplevel :load-toplevel)
-  (cl:unless (cl:fboundp 'swig-lispify)
-    (cl:defun swig-lispify (name flag cl:&amp;optional (package cl:*package*))
-      (cl:labels ((helper (lst last rest cl:&amp;aux (c (cl:car lst)))
-                    (cl:cond
-                      ((cl:null lst)
-                       rest)
-                      ((cl:upper-case-p c)
-                       (helper (cl:cdr lst) 'upper
-                               (cl:case last
-                                 ((lower digit) (cl:list* c #\- rest))
-                                 (cl:t (cl:cons c rest)))))
-                      ((cl:lower-case-p c)
-                       (helper (cl:cdr lst) 'lower (cl:cons (cl:char-upcase c) rest)))
-                      ((cl:digit-char-p c)
-                       (helper (cl:cdr lst) 'digit 
-                               (cl:case last
-                                 ((upper lower) (cl:list* c #\- rest))
-                                 (cl:t (cl:cons c rest)))))
-                      ((cl:char-equal c #\_)
-                       (helper (cl:cdr lst) '_ (cl:cons #\- rest)))
-                      (cl:t
-                       (cl:error "Invalid character: ~A" c)))))
-        (cl:let ((fix (cl:case flag
-                        ((constant enumvalue) "+")
-                        (variable "*")
-                        (cl:t ""))))
-          (cl:intern
-           (cl:concatenate
-            'cl:string
-            fix
-            (cl:nreverse (helper (cl:concatenate 'cl:list name) cl:nil cl:nil))
-            fix)
-           package))))))
-
-;;;SWIG wrapper code ends here
-
-
-(cl:defconstant y 5)
-
-(cl:defconstant x (cl:ash 5 -1))
-
-(cffi:defcstruct bar
-        (p :short)
-        (q :short)
-        (a :char)
-        (b :char)
-        (z :pointer)
-        (n :pointer))
-
-(cffi:defcvar ("my_struct" my_struct)
- :pointer)
-
-(cffi:defcstruct foo
-        (a :int)
-        (b :pointer))
-
-(cffi:defcfun ("pointer_func" pointer_func) :int
-  (ClosureFun :pointer)
-  (p :int))
-
-(cffi:defcfun ("func123" func123) :int
-  (p :pointer)
-  (q :pointer)
-  (r :pointer))
-
-(cffi:defcfun ("lispsort_double" lispsort_double) :void
-  (n :int)
-  (array :pointer))
-
-(cffi:defcenum color
-        :RED
-        :BLUE
-        :GREEN)
-</pre></div>
-
-<p>
-   The <i>SWIG wrapper</i> code refers to the special code which SWIG
-    may need to use while wrapping C code. You can turn on/off the
-    generation of this code by using the <i>-[no]swig-lisp</i>
-    option. You must have noticed that SWIG goes one extra step to
-    ensure that CFFI does not do automatic lispification of the C
-    function names. The reason SWIG does this is because quite often
-    developers want to build a nice CLOS based lispy API, and this one
-    to one correspondence between C function names and lisp function
-    name helps.
-</p>
-   
-<p> Maybe you want to have your own convention for generating lisp
-      function names for corresponding C function names, or you just
-      want to lispify the names, also, before we forget you want to
-      export the generated lisp names. To do this, we will use the
-      SWIG <a
-        href="Customization.html#Customization_features">feature directive</a>. 
-Let's edit the interface file such that the C type "div_t*" is changed
-      to Lisp type ":my-pointer", we lispify all names, 
-      export everything, and do some more stuff.
-
-</p>
-<div class="code"><pre>
-%module test
-
-%typemap(cin) div_t* ":my-pointer";
-
-%feature("intern_function", "1");
-%feature("export");
-
-%feature("inline") lispsort_double;
-%feature("intern_function", "my-lispify") lispsort_double;
-%feature("export", package="'some-other-package") lispsort_double;
-
-%rename func123 renamed_cool_func;
-
-%ignore "pointer_func";
-
-%include "test.h"
-
-</pre></div>
-
-<p>
-The <i>typemap(cin)</i> ensures that for all arguments which are input
-    to C with the type "div_t*", the ":my-pointer" type be
-    used. Similarly  <i>typemap(cout)</i> are used for all types which
-    are returned from C.
-</p>
-<p>
-The feature <i>intern_function</i> ensures that all C names are
-      interned using the <b>swig-lispify</b> function. The "1" given
-      to the feature is optional. The use of feature like
-      <i>%feature("intern_function", "1");</i> globally enables
-      interning for everything. If you want to target a single
-      function, or declaration then use the targeted version of
-      feature, <i>%feature("intern_function", "my-lispify")
-        lispsort_double;</i>, here we are using an additional feature
-      which allows us to use our lispify function.
-</p>
-<p>The <i>export</i> feature allows us to export the symbols. If
-      the <i>package</i> argument is given, then the symbol will be exported to
-      the specified Lisp package. The <i>inline</i> feature declaims the
-      declared function as inline. The <i>rename</i> directive allows us to
-      change the name(it is useful when generating C wrapper code for handling
-      overloaded functions). The <i>ignore</i> directive ignores a certain
-      declaration.
-</p>
-<p>There are several other things which are possible, to see some
-      example of usage of SWIG look at the Lispbuilder and wxCL
-      projects. The generated code with 'noswig-lisp' option is:
-</p>
-
-<div class="targetlang"><pre>
-(cl:defconstant #.(swig-lispify "y" 'constant) 5)
-
-(cl:export '#.(swig-lispify "y" 'constant))
-
-(cl:defconstant #.(swig-lispify "x" 'constant) (cl:ash 5 -1))
-
-(cl:export '#.(swig-lispify "x" 'constant))
-
-(cffi:defcstruct #.(swig-lispify "bar" 'classname)
-        (#.(swig-lispify "p" 'slotname) :short)
-        (#.(swig-lispify "q" 'slotname) :short)
-        (#.(swig-lispify "a" 'slotname) :char)
-        (#.(swig-lispify "b" 'slotname) :char)
-        (#.(swig-lispify "z" 'slotname) :pointer)
-        (#.(swig-lispify "n" 'slotname) :pointer))
-
-(cl:export '#.(swig-lispify "bar" 'classname))
-
-(cl:export '#.(swig-lispify "p" 'slotname))
-
-(cl:export '#.(swig-lispify "q" 'slotname))
-
-(cl:export '#.(swig-lispify "a" 'slotname))
-
-(cl:export '#.(swig-lispify "b" 'slotname))
-
-(cl:export '#.(swig-lispify "z" 'slotname))
-
-(cl:export '#.(swig-lispify "n" 'slotname))
-
-(cffi:defcvar ("my_struct" #.(swig-lispify "my_struct" 'variable))
- :pointer)
-
-(cl:export '#.(swig-lispify "my_struct" 'variable))
-
-(cffi:defcstruct #.(swig-lispify "foo" 'classname)
-        (#.(swig-lispify "a" 'slotname) :int)
-        (#.(swig-lispify "b" 'slotname) :pointer))
-
-(cl:export '#.(swig-lispify "foo" 'classname))
-
-(cl:export '#.(swig-lispify "a" 'slotname))
-
-(cl:export '#.(swig-lispify "b" 'slotname))
-
-(cffi:defcfun ("renamed_cool_func" #.(swig-lispify "renamed_cool_func" 'function)) :int
-  (p :my-pointer)
-  (q :pointer)
-  (r :pointer))
-
-(cl:export '#.(swig-lispify "renamed_cool_func" 'function))
-
-(cl:declaim (cl:inline #.(my-lispify "lispsort_double" 'function)))
-
-(cffi:defcfun ("lispsort_double" #.(my-lispify "lispsort_double" 'function)) :void
-  (n :int)
-  (array :pointer))
-
-(cl:export '#.(my-lispify "lispsort_double" 'function) 'some-other-package)
-
-(cffi:defcenum #.(swig-lispify "color" 'enumname)
-        #.(swig-lispify "RED" 'enumvalue :keyword)
-        #.(swig-lispify "BLUE" 'enumvalue :keyword)
-        #.(swig-lispify "GREEN" 'enumvalue :keyword))
-
-(cl:export '#.(swig-lispify "color" 'enumname))
-
-</pre></div>
-
-<H3><a name="Lisp_nn6">29.2.3 Generating CFFI bindings for C++ code</a></H3>
-
-
-<p>This feature to SWIG (for CFFI) is very new and still far from
-    complete. Pitch in with your patches, bug reports and feature
-    requests to improve it.
-</p>
-<p> Generating bindings for C++ code, requires <i>-c++</i> option to be
-      present and it first generates C binding which will wrap the C++
-      code, and then generates the 
-      corresponding CFFI wrapper code. In the generated C wrapper
-      code, you will often want to put your own C code, such as the
-      code to include various files. This can be done by making use of
-      "%{" and "%}" as shown below.
-</p> 
-<div class="code"><pre>
-%{
- #include "Test/test.h"
-%}
-</pre></div>
-<p>
-Also, while parsing the C++ file and generating C wrapper code SWIG
-    may need to be able to understand various symbols used in other
-    header files. To help SWIG in doing this while ensuring that
-    wrapper code is generated for the target file, use the "import"
-    directive. The "include" directive specifies the target file for
-    which wrapper code will be generated.
-</p>
-<div class="code"><pre>
-
-%import "ancillary/header.h"
-
-%include "target/header.h"
-
-</pre></div>
-<p>
-Various features which were available for C headers can also be used
-    here. The target header which we are going to use here is:
-</p>
-<div class="code"><pre>
-namespace OpenDemo {
-  class Test
-  {
-    public:
-      float x;
-      // constructors
-      Test (void) {x = 0;}
-      Test (float X) {x = X;}
-
-      // vector addition
-      Test operator+ (const Test&amp; v) const {return Test (x+v.x);}
-
-      // length squared
-      float lengthSquared (void) const {return this-&gt;dot (*this);}
-
-      static float distance (const Test&amp; a, const Test&amp; b){return(a-b).length();}
-
-      inline Test parallelComponent (const Test&amp; unitBasis) const {
-        return unitBasis * projection;
-      }
-
-      Test setYtoZero (void) const {return Test (this-&gt;x);}
-
-      static const Test zero;
-  };
-
-  inline Test operator* (float s, const Test&amp; v) {return v*s;}
-
-  inline std::ostream&amp; operator&lt;&lt; (std::ostream&amp; o, const Test&amp; v)
-  {
-    return o &lt;&lt; "(" &lt;&lt; v.x &lt;&lt; ")";
-  }
-
-  inline Test RandomUnitVectorOnXZPlane (void)
-  {
-    return RandomVectorInUnitRadiusSphere().setYtoZero().normalize();
-  }
-}
-</pre></div>
-<p>The interface used is: </p>
-<div class="code"><pre>
-%module test
-%include "test.cpp"
-</pre></div>
-
-<p>
-SWIG generates 3 files, the first one is a C wrap which we don't show,
-    the second is the plain CFFI wrapper which is as shown below:
-</p>
-<div class="targetlang"><pre>
-(cffi:defcfun ("_wrap_Test_x_set" Test_x_set) :void
-  (self :pointer)
-  (x :float))
-
-(cffi:defcfun ("_wrap_Test_x_get" Test_x_get) :float
-  (self :pointer))
-
-(cffi:defcfun ("_wrap_new_Test__SWIG_0" new_Test) :pointer)
-
-(cffi:defcfun ("_wrap_new_Test__SWIG_1" new_Test) :pointer
-  (X :float))
-
-(cffi:defcfun ("_wrap_Test___add__" Test___add__) :pointer
-  (self :pointer)
-  (v :pointer))
-
-(cffi:defcfun ("_wrap_Test_lengthSquared" Test_lengthSquared) :float
-  (self :pointer))
-
-(cffi:defcfun ("_wrap_Test_distance" Test_distance) :float
-  (a :pointer)
-  (b :pointer))
-
-(cffi:defcfun ("_wrap_Test_parallelComponent" Test_parallelComponent) :pointer
-  (self :pointer)
-  (unitBasis :pointer))
-
-(cffi:defcfun ("_wrap_Test_setYtoZero" Test_setYtoZero) :pointer
-  (self :pointer))
-
-(cffi:defcvar ("Test_zero" Test_zero)
- :pointer)
-
-(cffi:defcfun ("_wrap_delete_Test" delete_Test) :void
-  (self :pointer))
-
-(cffi:defcfun ("_wrap___mul__" __mul__) :pointer
-  (s :float)
-  (v :pointer))
-
-(cffi:defcfun ("_wrap___lshift__" __lshift__) :pointer
-  (o :pointer)
-  (v :pointer))
-
-(cffi:defcfun ("_wrap_RandomUnitVectorOnXZPlane" RandomUnitVectorOnXZPlane) :pointer)
-</pre></div>
-
-<p>
-The output is pretty good but it fails in disambiguating overloaded
-    functions such as the constructor, in this case. One way of
-    resolving this problem is to make the interface use the rename
-    directiv, but hopefully there are better solutions.
- In addition SWIG also generates, a CLOS file
-</p>
-
-
-<div class="targetlang"><pre>
-(clos:defclass test()
-  ((ff :reader ff-pointer)))
-
-(clos:defmethod (cl:setf x) (arg0 (obj test))
-  (Test_x_set (ff-pointer obj) arg0))
-
-(clos:defmethod x ((obj test))
-  (Test_x_get (ff-pointer obj)))
-
-(cl:shadow "+")
-(clos:defmethod + ((obj test) (self test) (v test))
-  (Test___add__ (ff-pointer obj) (ff-pointer self) (ff-pointer v)))
-
-(clos:defmethod length-squared ((obj test) (self test))
-  (Test_lengthSquared (ff-pointer obj) (ff-pointer self)))
-
-(clos:defmethod parallel-component ((obj test) (self test) (unitBasis test))
-  (Test_parallelComponent (ff-pointer obj) (ff-pointer self) (ff-pointer unitBasis)))
-
-(clos:defmethod set-yto-zero ((obj test) (self test))
-  (Test_setYtoZero (ff-pointer obj) (ff-pointer self)))
-</pre></div>
-
-<p>I agree that the CFFI C++ module needs lot more work. But I hope it
-    provides a starting point, on which you can base your work of
-    importing C++ libraries to Lisp. 
-</p>
-<p>
-If you have any questions, suggestions, patches, etc., related to CFFI
-      module feel free to contact us on the SWIG mailing list, and
-      also please add a "[CFFI]" tag in the subject line.
-
-<H3><a name="Lisp_nn7">29.2.4 Inserting user code into generated files</a></H3>
-
-
-<p>
-It is often necessary to <a href="SWIG.html#SWIG_nn40">include user-defined code</a> 
-into the automatically generated interface files. For example, when building
-a C++ interface, example_wrap.cxx will likely not compile unless
-you add a <tt>#include "header.h"</tt> directive. This can be done
-using the SWIG <tt>%insert(section) %{ ...code... %}</tt> directive:
-</p>
-
-<div class="code">
-<pre>
-%module example
-
-%{
-#include "header.h"
-%}
-
-%include "header.h"
-
-int fact(int n);
-</pre>
-</div>
-
-<p>
-Additional sections have been added for inserting into the
-generated lisp interface file:
-</p>
-<ul>
-  <li><tt>lisphead</tt> - inserts before type declarations</li>
-  <li><tt>swiglisp</tt> - inserts after type declarations according to
-    where it appears in the .i file</li>
-</ul>
-<p>
-Note that the block <tt>%{ ... %}</tt> is effectively a shortcut for
-<tt>%insert("header") %{ ... %}</tt>.
-</p>
-
-
-</body>
-</html>

Doc/Manual/Lua.html

@@ -7,7 +7,7 @@
 </head>
 
 <body bgcolor="#ffffff">
-<H1><a name="Lua">28 SWIG and Lua</a></H1>
+<H1><a name="Lua">29 SWIG and Lua</a></H1>
 <!-- INDEX -->
 <div class="sectiontoc">
 <ul>
@@ -77,20 +77,20 @@
 
 
 <p>
-Lua is an extension programming language designed to support general procedural programming with data description facilities. It also offers good support for object-oriented programming, functional programming, and data-driven programming. Lua is intended to be used as a powerful, light-weight configuration language for any program that needs one. Lua is implemented as a library, written in clean C (that is, in the common subset of ISO C and C++). It's also a <em>really</em> tiny language, less than 6000 lines of code, which compiles to &lt;100 kilobytes of binary code. It can be found at <a href="http://www.lua.org">http://www.lua.org</a>
+Lua is an extension programming language designed to support general procedural programming with data description facilities. It also offers good support for object-oriented programming, functional programming, and data-driven programming. Lua is intended to be used as a powerful, light-weight configuration language for any program that needs one. Lua is implemented as a library, written in clean C (that is, in the common subset of ISO C and C++). It's also a <em>really</em> tiny language, less than 6000 lines of code, which compiles to &lt;100 kilobytes of binary code. It can be found at <a href="https://www.lua.org">https://www.lua.org</a>
 </p>
 <p>
 eLua stands for Embedded Lua (can be thought of as a flavor of Lua) and offers the full implementation of the Lua programming language to the embedded world, extending it with specific features for efficient and portable software embedded development. eLua runs on smaller devices like microcontrollers and provides the full features of the regular Lua desktop version. More information on eLua can be found here: <a href="http://www.eluaproject.net">http://www.eluaproject.net</a>
 </p>
 
-<H2><a name="Lua_nn2">28.1 Preliminaries</a></H2>
+<H2><a name="Lua_nn2">29.1 Preliminaries</a></H2>
 
 
 <p>
 The current SWIG implementation is designed to work with Lua 5.0.x, 5.1.x and 5.2.x. It should work with later versions of Lua, but certainly not with Lua 4.0 due to substantial API changes. It is possible to either static link or dynamic link a Lua module into the interpreter (normally Lua static links its libraries, as dynamic linking is not available on all platforms). SWIG also has support for eLua starting from eLua 0.8. Due to substantial changes between SWIG 2.x and SWIG 3.0 and unavailability of testing platform, eLua status was downgraded to 'experimental'.
 </p>
 
-<H2><a name="Lua_nn3">28.2 Running SWIG</a></H2>
+<H2><a name="Lua_nn3">29.2 Running SWIG</a></H2>
 
 
 <p>
@@ -138,7 +138,7 @@ $ swig -lua -eluac example.i
 The <tt>-elua</tt> option puts all the C function wrappers and variable get/set wrappers in rotables. It also generates a metatable which will control the access to these variables from eLua. It also offers a significant amount of module size compression. On the other hand, the <tt>-eluac</tt> option puts all the wrappers in a single rotable. With this option, no matter how huge the module, it will consume no additional microcontroller SRAM (crass compression). There is a catch though: Metatables are not generated with <tt>-eluac</tt>. To access any value from eLua, one must directly call the wrapper function associated with that value.
 </p>
 
-<H3><a name="Lua_commandline">28.2.1 Additional command line options</a></H3>
+<H3><a name="Lua_commandline">29.2.1 Additional command line options</a></H3>
 
 
 <p>
@@ -171,7 +171,8 @@ swig -lua -help
 
 <tr>
   <td>-no-old-metatable-bindings</td>
-  <td>Disable backward compatibility: old-style binding names generations and a few other things. Explanations are included in appropriate later sections.</td>
+  <td>Disable backward compatibility: old-style binding names generations and a few other things. Explanations are included in appropriate later sections.
+      This option is considered deprecated and will be removed in the near future.</td>
 </tr>
 <tr>
   <td>-squash-bases</td>
@@ -179,7 +180,7 @@ swig -lua -help
 </tr>
 </table>
 
-<H3><a name="Lua_nn4">28.2.2 Compiling and Linking and Interpreter</a></H3>
+<H3><a name="Lua_nn4">29.2.2 Compiling and Linking and Interpreter</a></H3>
 
 
 <p>
@@ -250,7 +251,7 @@ LUALIB_API int ( luaopen_mod )(lua_State *L );
 More information on building and configuring eLua can be found here: <a href="http://www.eluaproject.net/doc/v0.8/en_building.html">http://www.eluaproject.net/doc/v0.8/en_building.html</a>
 </p>
 
-<H3><a name="Lua_nn5">28.2.3 Compiling a dynamic module</a></H3>
+<H3><a name="Lua_nn5">29.2.3 Compiling a dynamic module</a></H3>
 
 
 <p>
@@ -318,7 +319,7 @@ Is quite obvious (Go back and consult the Lua documents on how to enable loadlib
 
 
 
-<H3><a name="Lua_nn6">28.2.4 Using your module</a></H3>
+<H3><a name="Lua_nn6">29.2.4 Using your module</a></H3>
 
 
 <p>
@@ -336,19 +337,19 @@ $ ./my_lua
 &gt;
 </pre></div>
 
-<H2><a name="Lua_nn7">28.3 A tour of basic C/C++ wrapping</a></H2>
+<H2><a name="Lua_nn7">29.3 A tour of basic C/C++ wrapping</a></H2>
 
 
 <p>
 By default, SWIG tries to build a very natural Lua interface to your C/C++ code. This section briefly covers the essential aspects of this wrapping.
 </p>
-<H3><a name="Lua_nn8">28.3.1 Modules</a></H3>
+<H3><a name="Lua_nn8">29.3.1 Modules</a></H3>
 
 
 <p>
 The SWIG module directive specifies the name of the Lua module. If you specify `module example', then everything is wrapped into a Lua table 'example' containing all the functions and variables. When choosing a module name, make sure you don't use the same name as a built-in Lua command or standard module name.
 </p>
-<H3><a name="Lua_nn9">28.3.2 Functions</a></H3>
+<H3><a name="Lua_nn9">29.3.2 Functions</a></H3>
 
 
 <p>
@@ -370,7 +371,6 @@ creates a built-in function <tt>example.fact(n)</tt> that works exactly like you
 To avoid name collisions, SWIG create a Lua table which keeps all the functions, constants, classes and global variables in.
 It is possible to copy the functions, constants and classes (but not variables) out of this and into the global environment with the following code.
 This can easily overwrite existing functions, so this must be used with care.
-This option is considered deprecated and will be removed in the near future.
 </p>
 <div class="targetlang"><pre>
 &gt; for k, v in pairs(example) do _G[k]=v end
@@ -389,7 +389,7 @@ It is also possible to rename the module with an assignment.
 24
 </pre></div>
 
-<H3><a name="Lua_nn10">28.3.3 Global variables</a></H3>
+<H3><a name="Lua_nn10">29.3.3 Global variables</a></H3>
 
 
 <p>
@@ -410,7 +410,7 @@ SWIG will effectively generate two functions <tt>example.Foo_set()</tt> and <tt>
 &gt; example.Foo=4
 &gt; print(c)
 3
-&gt; c=5 -- this will not effect the original example.Foo
+&gt; c=5 -- this will not affect the original example.Foo
 &gt; print(example.Foo, c)
 4    5
 </pre></div>
@@ -477,7 +477,7 @@ If you have used the <tt>-eluac</tt> option for your eLua module, you will have
 In general, functions of the form <tt>"variable_get()"</tt> and <tt>"variable_set()"</tt> are automatically generated by SWIG for use with <tt>-eluac</tt>.
 </p>
 
-<H3><a name="Lua_nn11">28.3.4 Constants and enums</a></H3>
+<H3><a name="Lua_nn11">29.3.4 Constants and enums</a></H3>
 
 
 <p>
@@ -512,7 +512,7 @@ If you're using eLua and have used <tt>-elua</tt> or <tt>-eluac</tt> to generate
 Hello World
 </pre></div>
 
-<H4><a name="Lua_nn13">28.3.4.1 Constants/enums and classes/structures</a></H4>
+<H4><a name="Lua_nn13">29.3.4.1 Constants/enums and classes/structures</a></H4>
 
 
 <p>
@@ -566,9 +566,9 @@ If the <tt>-no-old-metatable-bindings</tt> option is used, then these old-style
 </p>
 <p>
 It is worth mentioning, that <tt>example.Test.TEST1</tt> and <tt>example.Test_TEST1</tt> are different entities and changing one does not change the other. 
-Given the fact that these are constantes and they are not supposed to be changed, it is up to you to avoid such issues.
+Given the fact that these are constants and they are not supposed to be changed, it is up to you to avoid such issues.
 </p>
-<H3><a name="Lua_nn12">28.3.5 Pointers</a></H3>
+<H3><a name="Lua_nn12">29.3.5 Pointers</a></H3>
 
 
 <p>
@@ -606,7 +606,7 @@ Lua enforces the integrity of its userdata, so it is virtually impossible to cor
 nil
 </pre></div>
 
-<H3><a name="Lua_structures">28.3.6 Structures</a></H3>
+<H3><a name="Lua_structures">29.3.6 Structures</a></H3>
 
 
 <p>
@@ -710,7 +710,7 @@ For eLua with the <tt>-eluac</tt> option, structure manipulation has to be perfo
 In general, functions of the form <tt>"new_struct()"</tt>, <tt>"struct_member_get()"</tt>, <tt>"struct_member_set()"</tt> and <tt>"free_struct()"</tt> are automatically generated by SWIG for each structure defined in C. (Please note: This doesn't apply for modules generated with the <tt>-elua</tt> option)
 </p>
 
-<H3><a name="Lua_nn14">28.3.7 C++ classes</a></H3>
+<H3><a name="Lua_nn14">29.3.7 C++ classes</a></H3>
 
 
 <p>
@@ -786,7 +786,7 @@ Both style names are generated by default now.
 However, if the <tt>-no-old-metatable-bindings</tt> option is used, then the backward compatible names are not generated in addition to ordinary ones.
 </p>
 
-<H3><a name="Lua_nn15">28.3.8 C++ inheritance</a></H3>
+<H3><a name="Lua_nn15">29.3.8 C++ inheritance</a></H3>
 
 
 <p>
@@ -811,7 +811,7 @@ then the function <tt>spam()</tt> accepts a Foo pointer or a pointer to any clas
 <p>
 It is safe to use multiple inheritance with SWIG.
 </p>
-<H3><a name="Lua_nn16">28.3.9 Pointers, references, values, and arrays</a></H3>
+<H3><a name="Lua_nn16">29.3.9 Pointers, references, values, and arrays</a></H3>
 
 
 <p>
@@ -842,7 +842,7 @@ Foo  spam7();
 <p>
 then all three functions will return a pointer to some Foo object. Since the third function (spam7) returns a value, newly allocated memory is used to hold the result and a pointer is returned (Lua will release this memory when the return value is garbage collected). The other two are pointers which are assumed to be managed by the C code and so will not be garbage collected.
 </p>
-<H3><a name="Lua_nn17">28.3.10 C++ overloaded functions</a></H3>
+<H3><a name="Lua_nn17">29.3.10 C++ overloaded functions</a></H3>
 
 
 <p>
@@ -928,7 +928,7 @@ Please refer to the "SWIG and C++" chapter for more information about overloadin
 <p>
 Dealing with the Lua coercion mechanism, the priority is roughly (integers, floats, strings, userdata). But it is better to rename the functions rather than rely upon the ordering.
 </p>
-<H3><a name="Lua_nn18">28.3.11 C++ operators</a></H3>
+<H3><a name="Lua_nn18">29.3.11 C++ operators</a></H3>
 
 
 <p>
@@ -1062,7 +1062,7 @@ operators and pseudo-operators):</p>
 </ul>
 <p>No other lua metafunction is inherited. For example, __gc is not inherited and must be redefined in every class. <tt>__tostring</tt> is subject to a special handling. If absent in class and in class bases, a default one will be provided by SWIG.
 </p>
-<H3><a name="Lua_nn19">28.3.12 Class extension with %extend</a></H3>
+<H3><a name="Lua_nn19">29.3.12 Class extension with %extend</a></H3>
 
 
 <p>
@@ -1119,7 +1119,7 @@ true
 Extend works with both C and C++ code, on classes and structs. It does not modify the underlying object in any way---the extensions only show up in the Lua interface. The only item to take note of is the code has to use the '$self' instead of 'this', and that you cannot access protected/private members of the code (as you are not officially part of the class).
 </p>
 
-<H3><a name="Lua_nn20">28.3.13 Using %newobject to release memory</a></H3>
+<H3><a name="Lua_nn20">29.3.13 Using %newobject to release memory</a></H3>
 
 
 <p> If you have a function that allocates memory like this,</p>
@@ -1143,7 +1143,7 @@ char *foo();
 </div>
 <p> This will release the allocated memory.</p>
 
-<H3><a name="Lua_nn21">28.3.14 C++ templates</a></H3>
+<H3><a name="Lua_nn21">29.3.14 C++ templates</a></H3>
 
 
 <p>
@@ -1178,7 +1178,7 @@ In Lua:
 <p>
 Obviously, there is more to template wrapping than shown in this example. More details can be found in the SWIG and C++ chapter. Some more complicated examples will appear later.
 </p>
-<H3><a name="Lua_nn22">28.3.15 C++ Smart Pointers</a></H3>
+<H3><a name="Lua_nn22">29.3.15 C++ Smart Pointers</a></H3>
 
 
 <p>
@@ -1230,7 +1230,7 @@ If you ever need to access the underlying pointer returned by <tt>operator-&gt;(
 &gt; f = p:__deref__()     -- Returns underlying Foo *
 </pre></div>
 
-<H3><a name="Lua_nn23">28.3.16 C++ Exceptions</a></H3>
+<H3><a name="Lua_nn23">29.3.16 C++ Exceptions</a></H3>
 
 
 <p>
@@ -1373,7 +1373,7 @@ and the "<a href="Customization.html#Customization_exception">Exception handling
 add exception specification to functions or globally (respectively).
 </p>
 
-<H3><a name="Lua_namespaces">28.3.17 Namespaces </a></H3>
+<H3><a name="Lua_namespaces">29.3.17 Namespaces </a></H3>
 
 
 <p>
@@ -1424,7 +1424,7 @@ Now, from Lua usage is as follows:
 19
 &gt;
 </pre></div>
-<H4><a name="Lua_nn27">28.3.17.1 Compatibility Note </a></H4>
+<H4><a name="Lua_nn27">29.3.17.1 Compatibility Note </a></H4>
 
 
 <p>
@@ -1440,7 +1440,7 @@ If SWIG is running in a backwards compatible way, i.e. without the <tt>-no-old-m
 </pre></div>
 
 
-<H4><a name="Lua_nn29">28.3.17.2 Names </a></H4>
+<H4><a name="Lua_nn29">29.3.17.2 Names </a></H4>
 
 
 <p> If SWIG is launched without <tt>-no-old-metatable-bindings</tt> option, then it enters backward-compatible mode. While in this mode, it tries
@@ -1485,7 +1485,7 @@ surrounding scope without any prefixing. Pretending that Test2 is a struct, not
 &gt;
 </pre></div>
 
-<H4><a name="Lua_nn30">28.3.17.3 Inheritance </a></H4>
+<H4><a name="Lua_nn30">29.3.17.3 Inheritance </a></H4>
 
 
 <p> The internal organization of inheritance has changed. 
@@ -1520,7 +1520,7 @@ function
 nil
 &gt;
 </pre></div>
-<p> This behaviour was changed. Now unless -squash-bases option is provided, Derived store a list of it's bases and if some symbol is not found in it's own service tables
+<p> This behaviour was changed. Now unless -squash-bases option is provided, Derived stores a list of its bases and if some symbol is not found in its own service tables
 then its bases are searched for it. Option -squash-bases will effectively return old behaviour.
 </p>
 
@@ -1530,12 +1530,12 @@ function
 &gt;
 </pre></div>
 
-<H2><a name="Lua_nn24">28.4 Typemaps</a></H2>
+<H2><a name="Lua_nn24">29.4 Typemaps</a></H2>
 
 
 <p>This section explains what typemaps are and how to use them. The default wrapping behaviour of SWIG is enough in most cases. However sometimes SWIG may need a little additional assistance to know which typemap to apply to provide the best wrapping. This section will be explaining how to use typemaps to best effect</p>
 
-<H3><a name="Lua_nn25">28.4.1 What is a typemap?</a></H3>
+<H3><a name="Lua_nn25">29.4.1 What is a typemap?</a></H3>
 
 
 <p>A typemap is nothing more than a code generation rule that is attached to a specific C datatype. For example, to convert integers from Lua to C, you might define a typemap like this:</p>
@@ -1563,7 +1563,7 @@ Received an integer : 6
 720
 </pre></div>
 
-<H3><a name="Lua_nn26">28.4.2 Using typemaps</a></H3>
+<H3><a name="Lua_nn26">29.4.2 Using typemaps</a></H3>
 
 
 <p>There are many ready written typemaps built into SWIG for all common types (int, float, short, long, char*, enum and more), which SWIG uses automatically, with no effort required on your part.</p>
@@ -1616,7 +1616,7 @@ void swap(int *sx, int *sy);
 
 <p>Note: C++ references must be handled exactly the same way. However SWIG will automatically wrap a <tt>const int&amp;</tt>  as an input parameter (since that it obviously input).</p>
 
-<H3><a name="Lua_typemap_arrays">28.4.3 Typemaps and arrays</a></H3>
+<H3><a name="Lua_typemap_arrays">29.4.3 Typemaps and arrays</a></H3>
 
 
 <p>Arrays present a challenge for SWIG, because like pointers SWIG does not know whether these are input or output values, nor
@@ -1624,8 +1624,8 @@ does SWIG have any indication of how large an array should be. However with the
 arrays for convenient usage.</p>
 
 <p>Given the functions:</p>
-<div class="code"><pre>extern void sort_int(int* arr, int len);
-extern void sort_double(double* arr, int len);
+<div class="code"><pre>extern void sort_int(int* arr, size_t len);
+extern void sort_double(double* arr, size_t len);
 </pre></div>
 
 <p>There are basically two ways that SWIG can deal with this. The first way, uses the <tt>&lt;carrays.i&gt;</tt> library
@@ -1638,16 +1638,16 @@ More details can be found in the <a href="Library.html#Library_carrays">carrays.
 
 <div class="code"><pre>// using the C-array
 %include &lt;carrays.i&gt;
-// this declares a batch of function for manipulating C integer arrays
+// this declares a batch of functions for manipulating C integer arrays
 %array_functions(int, int)
 
-extern void sort_int(int* arr, int len); // the function to wrap
+extern void sort_int(int* arr, size_t len); // the function to wrap
 
 // using typemaps
 %include &lt;typemaps.i&gt;
-%apply (double *INOUT, int) {(double* arr, int len)};
+%apply (double *INOUT, int) {(double* arr, size_t len)};
 
-extern void sort_double(double* arr, int len); // the function to wrap
+extern void sort_double(double* arr, size_t len); // the function to wrap
 </pre></div>
 
 <p>Once wrapped, the functions can both be called, though with different ease of use:</p>
@@ -1680,7 +1680,7 @@ and Lua tables to be 1..N, (the indexing follows the norm for the language). In
 
 <p>Note: SWIG also can support arrays of pointers in a similar manner.</p>
 
-<H3><a name="Lua_typemaps_ptr_ptr_functions">28.4.4 Typemaps and pointer-pointer functions</a></H3>
+<H3><a name="Lua_typemaps_ptr_ptr_functions">29.4.4 Typemaps and pointer-pointer functions</a></H3>
 
 
 <p>Several C++ libraries use a pointer-pointer functions to create its objects. These functions require a pointer to a pointer which is then filled with the pointer to the new object. Microsoft's COM and DirectX as well as many other libraries have this kind of function. An example is given below:</p>
@@ -1714,7 +1714,7 @@ int Create_Math(iMath** pptr); // its creator (assume it mallocs)
 ptr=nil -- the iMath* will be GC'ed as normal
 </pre></div>
 
-<H2><a name="Lua_writing_typemaps">28.5 Writing typemaps</a></H2>
+<H2><a name="Lua_writing_typemaps">29.5 Writing typemaps</a></H2>
 
 
 <p>This section describes how you can modify SWIG's default wrapping behavior for various C/C++ datatypes using the <tt>%typemap</tt> directive. This is an advanced topic that assumes familiarity with the Lua C API as well as the material in the "<a href="Typemaps.html#Typemaps">Typemaps</a>" chapter.</p>
@@ -1723,7 +1723,7 @@ ptr=nil -- the iMath* will be GC'ed as normal
 
 <p>Before proceeding, you should read the previous section on using typemaps, and look at the existing typemaps found in luatypemaps.swg and typemaps.i. These are both well documented and fairly easy to read. You should not attempt to write your own typemaps until you have read and can understand both of these files (they may well also give you an idea to base your work on).</p>
 
-<H3><a name="Lua_typemaps_write">28.5.1 Typemaps you can write</a></H3>
+<H3><a name="Lua_typemaps_write">29.5.1 Typemaps you can write</a></H3>
 
 
 <p>There are many different types of typemap that can be written, the full list can be found in the "<a href="Typemaps.html#Typemaps">Typemaps</a>" chapter. However the following are the most commonly used ones.</p>
@@ -1736,7 +1736,7 @@ ptr=nil -- the iMath* will be GC'ed as normal
 (the syntax for the typecheck is different from the typemap, see typemaps for details).</li>
 </ul>
 
-<H3><a name="Lua_nn31">28.5.2 SWIG's Lua-C API</a></H3>
+<H3><a name="Lua_nn31">29.5.2 SWIG's Lua-C API</a></H3>
 
 
 <p>This section explains the SWIG specific Lua-C API. It does not cover the main Lua-C api, as this is well documented and not worth covering.</p>
@@ -1785,7 +1785,7 @@ This macro, when called within the context of a SWIG wrapped function, will disp
 <div class="indent">
 Similar to SWIG_fail_arg, except that it will display the swig_type_info information instead.</div>
 
-<H2><a name="Lua_nn32">28.6 Customization of your Bindings</a></H2>
+<H2><a name="Lua_nn32">29.6 Customization of your Bindings</a></H2>
 
 
 <p>
@@ -1794,7 +1794,7 @@ This section covers adding of some small extra bits to your module to add the la
 
 
 
-<H3><a name="Lua_nn33">28.6.1 Writing your own custom wrappers</a></H3>
+<H3><a name="Lua_nn33">29.6.1 Writing your own custom wrappers</a></H3>
 
 
 <p>
@@ -1813,7 +1813,7 @@ int native_function(lua_State*L) // my native code
 The <tt>%native</tt> directive in the above example, tells SWIG that there is a function <tt>int native_function(lua_State*L);</tt> which is to be added into the module under the name '<tt>my_func</tt>'. SWIG will not add any wrapper for this function, beyond adding it into the function table. How you write your code is entirely up to you.
 </p>
 
-<H3><a name="Lua_nn34">28.6.2 Adding additional Lua code</a></H3>
+<H3><a name="Lua_nn34">29.6.2 Adding additional Lua code</a></H3>
 
 
 <p>
@@ -1851,7 +1851,7 @@ Good uses for this feature is adding of new code, or writing helper functions to
 See Examples/lua/arrays for an example of this code.
 </p>
 
-<H2><a name="Lua_nn35">28.7 Details on the Lua binding</a></H2>
+<H2><a name="Lua_nn35">29.7 Details on the Lua binding</a></H2>
 
 
 <p>
@@ -1862,7 +1862,7 @@ See Examples/lua/arrays for an example of this code.
  </i>
 </p>
 
-<H3><a name="Lua_nn36">28.7.1 Binding global data into the module.</a></H3>
+<H3><a name="Lua_nn36">29.7.1 Binding global data into the module.</a></H3>
 
 
 <p>
@@ -1922,7 +1922,7 @@ end
 <p>
 That way when you call '<tt>a=example.Foo</tt>', the interpreter looks at the table 'example' sees that there is no field 'Foo' and calls __index. This will in turn check in '.get' table and find the existence of 'Foo' and then return the value of the C function call 'Foo_get()'. Similarly for the code '<tt>example.Foo=10</tt>', the interpreter will check the table, then call the __newindex which will then check the '.set' table and call the C function 'Foo_set(10)'.
 </p>
-<H3><a name="Lua_nn37">28.7.2 Userdata and Metatables</a></H3>
+<H3><a name="Lua_nn37">29.7.2 Userdata and Metatables</a></H3>
 
 
 <p>
@@ -1997,12 +1997,12 @@ So when 'p:Print()' is called, the __index looks on the object metatable for a '
 In theory, you can play with this usertable &amp; add new features, but remember that it is a shared table between all instances of one class, and you could very easily corrupt the functions in all the instances.
 </p>
 <p>
-Note: Both the opaque structures (like the FILE*) and normal wrapped classes/structs use the same 'swig_lua_userdata' structure. Though the opaque structures has do not have a metatable attached, or any information on how to dispose of them when the interpreter has finished with them.
+Note: Both the opaque structures (like the FILE*) and normal wrapped classes/structs use the same 'swig_lua_userdata' structure. Though the opaque structures do not have a metatable attached, or any information on how to dispose of them when the interpreter has finished with them.
 </p>
 <p>
-Note: Operator overloads are basically done in the same way, by adding functions such as '__add' &amp; '__call' to the class' metatable. The current implementation is a bit rough as it will add any member function beginning with '__' into the metatable too, assuming its an operator overload.
+Note: Operator overloads are basically done in the same way, by adding functions such as '__add' &amp; '__call' to the class' metatable. The current implementation is a bit rough as it will add any member function beginning with '__' into the metatable too, assuming it's an operator overload.
 </p>
-<H3><a name="Lua_nn38">28.7.3 Memory management</a></H3>
+<H3><a name="Lua_nn38">29.7.3 Memory management</a></H3>
 
 
 <p>

Doc/Manual/Makefile

@@ -1,7 +1,7 @@
 # Makefile for generating the SWIG documentation
 #
 # Note that the htmldoc package needs to be installed. wkhtmltopdf patched with qt is also required
-# and can be installed from http://wkhtmltopdf.org/downloads.html.
+# and the prebuilt binaries can be installed from https://wkhtmltopdf.org/downloads.html.
 #
 # The .html files are first processed and updated with chapter numbering and anchor names
 # are added to the HTML headings using the python scripts. The htmldoc program is then
@@ -43,8 +43,8 @@ check:
 #  3) <pre> <tt> <code> elements do not always select a fixed-width font - try installing the
 #     Courier font to fix - these have been added to style.css.
 generate: SWIGDocumentation.html
-	wkhtmltopdf --version | grep "with patched qt" || (echo "wkhtmltopdf is not the patched qt version and so cannot be used - download it from http://wkhtmltopdf.org/downloads.html" && false)
-	wkhtmltopdf --margin-top 20mm --margin-bottom 20mm --margin-left 10mm --margin-right 10mm --header-font-size 6 --footer-font-size 6 --header-spacing 6 --footer-spacing 6 --header-center '[doctitle]' --footer-left '[subsection]' --footer-right '[page]' SWIGDocumentation.html SWIGDocumentation.pdf
+	wkhtmltopdf --version | grep "with patched qt" || (echo "wkhtmltopdf is not the patched qt version and so cannot be used - download it from https://wkhtmltopdf.org/downloads.html" && false)
+	wkhtmltopdf --margin-top 20mm --margin-bottom 20mm --margin-left 10mm --margin-right 10mm --header-font-size 6 --footer-font-size 6 --header-spacing 6 --footer-spacing 6 --header-center '[doctitle]' --footer-left '[subsection]' --footer-right '[page]' --allow . SWIGDocumentation.html SWIGDocumentation.pdf
 
 SWIGDocumentation.html: swightml.book
 	htmldoc --batch swightml.book || true

Doc/Manual/Modula3.html

@@ -1,942 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<title>SWIG and Modula-3</title>
-<link rel="stylesheet" type="text/css" href="style.css">
-<meta http-equiv="content-type" content="text/html; charset=UTF-8">
-</head>
-<body bgcolor="#FFFFFF">
-<H1><a name="Modula3">31 SWIG and Modula-3</a></H1>
-<!-- INDEX -->
-<div class="sectiontoc">
-<ul>
-<li><a href="#Modula3_modula3_overview">Overview</a>
-<ul>
-<li><a href="#Modula3_motivation">Motivation</a>
-</ul>
-<li><a href="#Modula3_conception">Conception</a>
-<ul>
-<li><a href="#Modula3_cinterface">Interfaces to C libraries</a>
-<li><a href="#Modula3_cppinterface">Interfaces to C++ libraries</a>
-</ul>
-<li><a href="#Modula3_preliminaries">Preliminaries</a>
-<ul>
-<li><a href="#Modula3_compilers">Compilers</a>
-<li><a href="#Modula3_commandline">Additional Commandline Options</a>
-</ul>
-<li><a href="#Modula3_typemaps">Modula-3 typemaps</a>
-<ul>
-<li><a href="#Modula3_inoutparam">Inputs and outputs</a>
-<li><a href="#Modula3_ordinals">Subranges, Enumerations, Sets</a>
-<li><a href="#Modula3_class">Objects</a>
-<li><a href="#Modula3_imports">Imports</a>
-<li><a href="#Modula3_exceptions">Exceptions</a>
-<li><a href="#Modula3_typemap_example">Example</a>
-</ul>
-<li><a href="#Modula3_hints">More hints to the generator</a>
-<ul>
-<li><a href="#Modula3_features">Features</a>
-<li><a href="#Modula3_pragmas">Pragmas</a>
-</ul>
-<li><a href="#Modula3_remarks">Remarks</a>
-</ul>
-</div>
-<!-- INDEX -->
-
-
-
-<p>
-This chapter describes SWIG's support for
-<a href="http://modula3.org/">Modula-3</a>.
-You should be familiar with the
-<a href="SWIG.html#SWIG">basics</a>
-of SWIG,
-especially
-<a href="Typemaps.html#Typemaps">typemaps</a>.
-</p>
-
-<H2><a name="Modula3_modula3_overview">31.1 Overview</a></H2>
-
-
-<p>
-Modula-3 is a compiled language in the tradition of Niklaus Wirth's Modula 2,
-which is in turn a successor to Pascal.
-</p>
-
-<p>
-SWIG's Modula-3 support is currently very basic and highly experimental!
-Many features are still not designed satisfyingly
-and I need more discussion about the odds and ends.
-Don't rely on any feature, incompatible changes are likely in the future!
-However, the Modula-3 generator was already useful for interfacing
-to the libraries:
-</p>
-
-<ol>
-<li>
-<a href="http://www.elegosoft.com/cgi-bin/cvsweb.cgi/cm3/m3-libs/plplot/">
-PLPlot
-</a>
-</li>
-<li>
-<a href="http://www.elegosoft.com/cgi-bin/cvsweb.cgi/cm3/m3-libs/fftw/">
-FFTW
-</a>
-</li>
-</ol>
-
-<H3><a name="Modula3_motivation">31.1.1 Motivation</a></H3>
-
-
-<p>
-Although it is possible to write Modula-3 code that performs as well as C/C++
-most existing libraries are not written in Modula-3 but in C or C++, and
-even libraries in other languages may provide C header files.
-</p>
-
-<p>
-Fortunately Modula-3 can call C functions, but you have to write Modula-3
-interfaces to them, and to make things comfortable you will also need
-wrappers that convert between high-level features of Modula-3 (garbage
-collecting, exceptions) and the explicit tracking of allocated memory and
-exception codes used by C APIs.
-</p>
-
-<p>
-SWIG converts C headers to Modula-3 interfaces for you, and using typemaps
-you can pass <tt>TEXT</tt>s or open arrays, and convert error return codes
-into exceptions.
-</p>
-
-<p>
-If the library API is ill designed
-writing appropriate typemaps can still be time-consuming.
-E.g. C programmers are very creative to work-around
-missing data types like (real) enumerations and sets.
-You should turn such work-arounds back to the Modula-3 way
-otherwise you lose static safety and consistency.
-</p>
-
-<p>
-Without SWIG you would probably never consider trying to call C++ libraries
-from Modula-3, but with SWIG this is becomes feasible.
-SWIG can generate C wrappers to C++ functions and object methods
-that may throw exceptions, and then wrap these C wrappers for Modula-3.
-To make it complete you can then hide the C interface with Modula-3 classes and
-exceptions.
-</p>
-
-<p>
-SWIG allows you to call C and C++ libraries from Modula-3 (even with call back
-functions), but it doesn't allow you to easily integrate a Modula-3 module into
-a C/C++ project.
-</p>
-
-<H2><a name="Modula3_conception">31.2 Conception</a></H2>
-
-
-<H3><a name="Modula3_cinterface">31.2.1 Interfaces to C libraries</a></H3>
-
-
-<p>
-Modula-3 has integrated support for calling C functions.
-This is also extensively used by the standard Modula-3 libraries
-to call OS functions.
-The Modula-3 part of SWIG and the corresponding SWIG library
-modula3.swg
-contain code that uses these features.
-Because of the built-in support there is no need
-for calling the SWIG kernel to generate wrappers written in C.
-All conversion and argument checking can be done in Modula-3
-and the interfacing is quite efficient.
-All you have to do is to write pieces of Modula-3 code
-that SWIG puts together.
-</p>
-
-<table border summary="Modula-3 C library support">
-<tr><th colspan=2>C library support integrated in Modula-3<th></tr>
-<tr>
-<td>Pragma <tt>&lt;* EXTERNAL *&gt;</tt></td>
-<td>Precedes a declaration of a PROCEDURE that is implemented
-in an external library instead of a Modula-3 module.</td>
-</tr>
-<tr>
-<td>Pragma <tt>&lt;* CALLBACK *&gt;</tt></td>
-<td>Precedes a declaration of a PROCEDURE that should be called
-by external library code.</td>
-</tr>
-<tr>
-<td>Module <tt>Ctypes</tt></td>
-<td>Contains Modula-3 types that match some basic C types.</td>
-</tr>
-<tr>
-<td>Module <tt>M3toC</tt></td>
-<td>Contains routines that convert between Modula-3's <tt>TEXT</tt> type
-and C's <tt>char *</tt> type.</td>
-</tr>
-</table>
-
-<p>
-In each run of SWIG the Modula-3 part
-generates several files:
-</p>
-<table border summary="Modula-3 generated files">
-<tr>
-  <th>Module name scheme</th>
-  <th>Identifier for <tt>%insert</tt></th>
-  <th>Description</th>
-</tr>
-<tr>
-  <td>Module<tt>Raw.i3</tt></td>
-  <td><tt>m3rawintf</tt></td>
-  <td>Declaration of types that are equivalent to those of the C library,
-      <tt>EXTERNAL</tt> procedures as interface to the C library functions</td>
-</tr>
-<tr>
-  <td>Module<tt>Raw.m3</tt></td>
-  <td><tt>m3rawimpl</tt></td>
-  <td>Almost empty.</td>
-</tr>
-<tr>
-  <td>Module<tt>.i3</tt></td>
-  <td><tt>m3wrapintf</tt></td>
-  <td>Declaration of comfortable wrappers to the C library functions.</td>
-</tr>
-<tr>
-  <td>Module<tt>.m3</tt></td>
-  <td><tt>m3wrapimpl</tt></td>
-  <td>Implementation of the wrappers that
-      convert between Modula-3 and C types,
-      check for validity of values,
-      hand-over resource management to the garbage collector using <tt>WeakRef</tt>s
-      and raises exceptions.</td>
-</tr>
-<tr>
-  <td><tt>m3makefile</tt></td>
-  <td><tt>m3makefile</tt></td>
-  <td>Add the modules above to the Modula-3 project and
-      specify the name of the Modula-3 wrapper library
-      to be generated.
-
-    Today I'm not sure if it is a good idea
-    to create a <tt>m3makefile</tt> in each run,
-    because SWIG must be started for each Modula-3 module it creates.
-    Thus the m3makefile is overwritten each time. :-(
-  </td>
-</tr>
-</table>
-
-<p>
-Here's a scheme of how the function calls to Modula-3 wrappers
-are redirected to C library functions:
-</p>
-
-<table summary="Modula-3 C library">
-<tr>
-  <td align=center>
-    Modula-3 wrapper<br>
-    Module<tt>.i3</tt><br>
-    generated by Modula-3 part of SWIG
-  </td>
-  <td></td>
-  <td align=center></td>
-</tr>
-<tr>
-  <td align=center>
-    <!-- pre tag overrides centering -->
-    |<br>
-    v
-  </td>
-  <td></td>
-  <td align=center></td>
-</tr>
-<tr>
-  <td align=center>
-    Modula-3 interface to C<br>
-    Module<tt>Raw.i3</tt><br>
-    generated by Modula-3 part of SWIG
-  </td>
-  <td>--&gt;</td>
-  <td align=center>
-    C library
-  </td>
-</tr>
-</table>
-
-
-<p>
-I have still no good conception how one can split C library interfaces
-into type oriented interfaces.
-A Module in Modula-3 represents an Abstract DataType
-(or call it a static classes, i.e. a class without virtual methods).
-E.g. if you have a principal type, say <tt>Database</tt>,
-it is good Modula-3 style to set up one Module with the name <tt>Database</tt>
-where the database type is declared with the name <tt>T</tt>
-and where all functions are declared that operates on it.
-</p>
-
-<p>
-The normal operation of SWIG is to generate a fixed set of files per call.
-To generate multiple modules one has to write one SWIG interface
-(different SWIG interfaces can share common data) per module.
-Identifiers belonging to a different module may ignored (<tt>%ignore</tt>)
-and the principal type must be renamed (<tt>%typemap</tt>).
-</p>
-
-
-<H3><a name="Modula3_cppinterface">31.2.2 Interfaces to C++ libraries</a></H3>
-
-
-<p>
-Interfaces to C++ files are much more complicated and
-there are some more design decisions that are not made, yet.
-Modula-3 has no support for C++ functions
-but C++ compilers should support generating C++ functions
-with a C interface.
-</p>
-
-<p>
-Here's a scheme of how the function calls to Modula-3 wrappers
-are redirected to C library functions:
-</p>
-
-<table summary="Modula-3 C++ library">
-<tr>
-  <td align=center>
-    Modula-3 wrapper<br>
-    Module<tt>.i3</tt><br>
-    generated by Modula-3 part of SWIG
-  </td>
-  <td></td>
-  <td align=center>C++ library</td>
-</tr>
-<tr>
-  <td align=center>
-    <!-- pre tag overrides centering -->
-    |<br>
-    v
-  </td>
-  <td></td>
-  <td align=center>
-    ^<br>
-    |
-  </td>
-</tr>
-<tr>
-  <td align=center>
-    Modula-3 interface to C<br>
-    Module<tt>Raw.i3</tt><br>
-    generated by Modula-3 part of SWIG
-  </td>
-  <td>--&gt;</td>
-  <td align=center>
-    C interface to C++<br>
-    module<tt>_wrap.cxx</tt><br>
-    generated by the SWIG core
-  </td>
-</tr>
-</table>
-
-<p>
-Wrapping C++ libraries arises additional problems:
-</p>
-<ul>
-<li>
-Is it sensible to wrap C++ classes with Modula-3 classes?
-</li>
-<li>
-How to find the wrapping Modula-3 class
-for a class pointer that is returned by a C++ routine?
-</li>
-<li>
-How to deal with multiple inheritance
-which was neglected for Modula-3 for good reasons?
-</li>
-<li>
-Is it possible to sub-class C++ classes with Modula-3 code?
-This issue is addressed by directors,
-a feature that was experimentally added to some Language modules
-like
-<a href="Java.html#Java_directors">Java</a> and
-<a href="Python.html#Python_directors">Python</a>.
-</li>
-<li>
-How to manage storage with the garbage collector of Modula-3?
-Support for
-<a href="Customization.html#Customization_ownership">
-<tt>%newobject</tt> and <tt>%typemap(newfree)</tt></a>
-isn't implemented, yet.
-What's about resources that are managed by the garbage collector
-but shall be passed back to the storage management of the C++ library?
-This is a general issue which is not solved in a satisfying fashion
-as far as I know.
-</li>
-<li>
-How to turn C++ exceptions into Modula-3 exceptions?
-There's also no support for
-<a href="Customization.html#Customization_exception">
-<tt>%exception</tt></a>, yet.
-</li>
-</ul>
-
-<p>
-Be warned:
-There is no C++ library I wrote a SWIG interface for,
-so I'm not sure if this is possible or sensible, yet.
-</p>
-
-<H2><a name="Modula3_preliminaries">31.3 Preliminaries</a></H2>
-
-
-<H3><a name="Modula3_compilers">31.3.1 Compilers</a></H3>
-
-
-<p>
-There are different Modula-3 compilers around:
-cm3, pm3, ezm3, Klagenfurth Modula-3, Cambridge Modula-3.
-SWIG itself does not contain compiler specific code
-but the modula3.swg library file
-may do so.
-For testing examples I use Critical Mass cm3.
-</p>
-
-
-<H3><a name="Modula3_commandline">31.3.2 Additional Commandline Options</a></H3>
-
-
-<p>
-There are some experimental command line options
-that prevent SWIG from generating interface files.
-Instead files are emitted that may assist you
-when writing SWIG interface files.
-</p>
-
-<table border summary="Modula-3 specific options">
-<tr>
-<th>Modula-3 specific options</th>
-<th>Description</th>
-</tr>
-
-<tr>
-<td valign=top>-generateconst &lt;file&gt;</td>
-<td>
-Disable generation of interfaces and wrappers.
-Instead write code for computing numeric values of constants
-to the specified file.
-<br>
-C code may contain several constant definitions
-written as preprocessor macros.
-Other language modules of SWIG use
-compute-once-use-readonly variables or
-functions to wrap such definitions.
-All of them can invoke C code dynamically
-for computing the macro values.
-But if one wants to turn them into Modula-3
-integer constants, enumerations or set types,
-the values of these expressions has to be known statically.
-Although definitions like <tt>(1 &lt;&lt; FLAG_MAXIMIZEWINDOW)</tt>
-must be considered as good C style
-they are hard to convert to Modula-3
-since the value computation can use every feature of C.
-<br>
-Thus I implemented these switch
-to extract all constant definitions
-and write a C program that output the values of them.
-It works for numeric constants only
-and treats all of them as <tt>double</tt>.
-Future versions may generate a C++ program
-that can detect the type of the macros
-by overloaded output functions.
-Then strings can also be processed.
-</td>
-</tr>
-
-<tr>
-<td valign=top>-generaterename &lt;file&gt;</td>
-<td>
-Disable generation of interfaces and wrappers.
-Instead generate suggestions for <tt>%rename</tt>.
-<br>
-C libraries use a naming style
-that is neither homogeneous nor similar to that of Modula-3.
-C function names often contain a prefix denoting the library
-and some name components separated by underscores
-or capitalization changes.
-To get library interfaces that are really Modula-3 like
-you should rename the function names with the <tt>%rename</tt> directive.
-This switch outputs a list of such directives
-with a name suggestion generated by a simple heuristic.
-</td>
-</tr>
-
-<tr>
-<td valign=top>-generatetypemap &lt;file&gt;</td>
-<td>
-Disable generation of interfaces and wrappers.
-Instead generate templates for some basic typemaps.
-</td>
-</tr>
-</table>
-
-<H2><a name="Modula3_typemaps">31.4 Modula-3 typemaps</a></H2>
-
-
-<H3><a name="Modula3_inoutparam">31.4.1 Inputs and outputs</a></H3>
-
-
-<p>
-Each C procedure has a bunch of inputs and outputs.
-Inputs are passed as function arguments,
-outputs are updated referential arguments and
-the function value.
-</p>
-
-<p>
-Each C type can have several typemaps
-that apply only in case if a type is used
-for an input argument, for an output argument,
-or for a return value.
-A further typemap may specify
-the direction that is used for certain parameters.
-I have chosen this separation
-in order to be able to write general typemaps for the modula3.swg typemap library.
-In the library code the final usage of the type is not known.
-Using separate typemaps for each possible use
-allows appropriate definitions for each case.
-If these pre-definitions are fine
-then the direction of the function parameter
-is the only hint the user must give.
-</p>
-
-<p>
-The typemaps specific to Modula-3 have a common name scheme:
-A typemap name starts with "m3",
-followed by "raw" or "wrap"
-depending on whether it controls the generation
-of the Module<tt>Raw.i3</tt> or the Module<tt>.i3</tt>, respectively.
-It follows an "in" for typemaps applied to input argument,
-"out" for output arguments, "arg" for all kind of arguments,
-"ret" for returned values.
-</p>
-
-<p>
-The main task of SWIG is to build wrapper function,
-i.e. functions that convert values between C and Modula-3
-and call the corresponding C function.
-Modula-3 wrapper functions generated by SWIG
-consist of the following parts:
-</p>
-<ul>
-<li>Generate <tt>PROCEDURE</tt> signature.</li>
-<li>Declare local variables.</li>
-<li>Convert input values from Modula-3 to C.</li>
-<li>Check for input value integrity.</li>
-<li>Call the C function.</li>
-<li>Check returned values, e.g. error codes.</li>
-<li>Convert and write back values into Modula-3 records.</li>
-<li>Free temporary storage.</li>
-<li>Return values.</li>
-</ul>
-
-<table border summary="Modula-3 typemaps">
-<tr>
-  <th>Typemap</th>
-  <th>Example</th>
-  <th>Description</th>
-</tr>
-<tr>
-  <td>m3wrapargvar</td>
-  <td><tt>$1: INTEGER := $1_name;</tt></td>
-  <td>
-    Declaration of some variables needed for temporary results.
-  </td>
-</tr>
-<tr>
-  <td>m3wrapargconst</td>
-  <td><tt>$1 = "$1_name";</tt></td>
-  <td>
-    Declaration of some constant, maybe for debug purposes.
-  </td>
-</tr>
-<tr>
-  <td>m3wrapargraw</td>
-  <td><tt>ORD($1_name)</tt></td>
-  <td>
-    The expression that should be passed as argument to the raw Modula-3 interface function.
-  </td>
-</tr>
-<tr>
-  <td>m3wrapargdir</td>
-  <td><tt>out</tt></td>
-  <td>
-    Referential arguments can be used for input, output, update.
-    ???
-  </td>
-</tr>
-<tr>
-  <td>m3wrapinmode</td>
-  <td><tt>READONLY</tt></td>
-  <td>
-    One of Modula-3 parameter modes
-    <tt>VALUE</tt> (or empty),
-    <tt>VAR</tt>,
-    <tt>READONLY</tt>
-  </td>
-</tr>
-<tr>
-  <td>m3wrapinname</td>
-  <td></td>
-  <td>
-    New name of the input argument.
-  </td>
-</tr>
-<tr>
-  <td>m3wrapintype</td>
-  <td></td>
-  <td>
-    Modula-3 type of the input argument.
-  </td>
-</tr>
-<tr>
-  <td>m3wrapindefault</td>
-  <td></td>
-  <td>
-    Default value of the input argument
-  </td>
-</tr>
-<tr>
-  <td>m3wrapinconv</td>
-  <td><tt>$1 := M3toC.SharedTtoS($1_name);</tt></td>
-  <td>
-    Statement for converting the Modula-3 input value to C compliant value.
-  </td>
-</tr>
-<tr>
-  <td>m3wrapincheck</td>
-  <td><tt>IF Text.Length($1_name) &gt; 10 THEN RAISE E("str too long"); END;</tt></td>
-  <td>
-    Check the integrity of the input value.
-  </td>
-</tr>
-<tr>
-  <td>m3wrapoutname</td>
-  <td></td>
-  <td>
-    Name of the <tt>RECORD</tt> field to be used for returning multiple values.
-    This applies to referential output arguments that shall be turned
-    into return values.
-  </td>
-</tr>
-<tr>
-  <td>m3wrapouttype</td>
-  <td></td>
-  <td>
-    Type of the value that is returned instead of a referential output argument.
-  </td>
-</tr>
-<tr>
-  <td>m3wrapoutconv</td>
-  <td></td>
-  <td>
-  </td>
-</tr>
-<tr>
-  <td>m3wrapoutcheck</td>
-  <td></td>
-  <td>
-  </td>
-</tr>
-<tr>
-  <td>m3wrapretraw</td>
-  <td></td>
-  <td>
-  </td>
-</tr>
-<tr>
-  <td>m3wrapretname</td>
-  <td></td>
-  <td>
-  </td>
-</tr>
-<tr>
-  <td>m3wraprettype</td>
-  <td></td>
-  <td>
-  </td>
-</tr>
-<tr>
-  <td>m3wrapretvar</td>
-  <td></td>
-  <td>
-  </td>
-</tr>
-<tr>
-  <td>m3wrapretconv</td>
-  <td></td>
-  <td>
-  </td>
-</tr>
-<tr>
-  <td>m3wrapretcheck</td>
-  <td></td>
-  <td>
-  </td>
-</tr>
-<tr>
-  <td>m3wrapfreearg</td>
-  <td><tt>M3toC.FreeSharedS(str, arg1);</tt></td>
-  <td>
-    Free resources that were temporarily used in the wrapper.
-    Since this step should never be skipped,
-    SWIG will put it in the <tt>FINALLY</tt> branch
-    of a <tt>TRY .. FINALLY</tt> structure.
-  </td>
-</tr>
-</table>
-
-
-<H3><a name="Modula3_ordinals">31.4.2 Subranges, Enumerations, Sets</a></H3>
-
-
-<p>
-Subranges, enumerations, and sets are machine oriented types
-that make Modula very strong and expressive compared
-with the type systems of many other languages.
-</p>
-
-<ul>
-<li>
-Subranges are used for statically restricted choices of integers.
-</li>
-<li>
-Enumerations are used for named choices.
-</li>
-<li>
-Sets are commonly used for flag (option) sets.
-</li>
-</ul>
-
-<p>
-Using them extensively makes Modula code very safe and readable.
-</p>
-
-<p>
-C supports enumerations, too, but they are not as safe as the ones of Modula.
-Thus they are abused for many things:
-For named choices, for integer constant definitions, for sets.
-To make it complete every way of defining a value in C
-(<tt>#define</tt>, <tt>const int</tt>, <tt>enum</tt>)
-is somewhere used for defining something
-that must be handled completely different in Modula-3
-(<tt>INTEGER</tt>, enumeration, <tt>SET</tt>).
-</p>
-
-<p>
-I played around with several <tt>%feature</tt>s and <tt>%pragma</tt>s
-that split the task up into converting
-the C bit patterns (integer or bit set)
-into Modula-3 bit patterns (integer or bit set)
-and change the type as requested.
-See the corresponding example in the 
-Examples/modula3/enum/example.i file.
-This is quite messy and not satisfying.
-So the best what you can currently do is
-to rewrite constant definitions manually.
-Though this is a tedious work
-that I'd like to automate.
-</p>
-
-
-<H3><a name="Modula3_class">31.4.3 Objects</a></H3>
-
-
-<p>
-Declarations of C++ classes are mapped to <tt>OBJECT</tt> types
-while it is tried to retain the access hierarchy
-"public - protected - private" using partial revelation.
-Though the example in 
-Examples/modula3/class/example.i
-is not really useful, yet.
-</p>
-
-
-<H3><a name="Modula3_imports">31.4.4 Imports</a></H3>
-
-
-<p>
-Pieces of Modula-3 code provided by typemaps
-may contain identifiers from foreign modules.
-If the typemap <tt>m3wrapinconv</tt> for <tt>blah *</tt>
-contains code using the function <tt>M3toC.SharedTtoS</tt>
-you may declare <tt>%typemap("m3wrapinconv:import") blah * %{M3toC%}</tt>.
-Then the module <tt>M3toC</tt> is imported
-if the <tt>m3wrapinconv</tt> typemap for <tt>blah *</tt>
-is used at least once.
-Use <tt>%typemap("m3wrapinconv:import") blah * %{MyConversions AS M3toC%}</tt>
-if you need module renaming.
-Unqualified import is not supported.
-</p>
-
-<p>
-It is cumbersome to add this typemap to each piece of Modula-3 code.
-It is especially useful when writing general typemaps
-for the modula3.swg typemap library.
-For a monolithic module you might be better off
-if you add the imports directly:
-</p>
-
-<div class="code">
-<pre>
-%insert(m3rawintf) %{
-IMPORT M3toC;
-%}
-</pre></div>
-
-
-<H3><a name="Modula3_exceptions">31.4.5 Exceptions</a></H3>
-
-
-<p>
-Modula-3 provides another possibility
-of an output of a function: exceptions.
-</p>
-
-<p>
-Any piece of Modula-3 code that SWIG inserts
-due to a typemap can raise an exception.
-This way you can also convert an error code
-from a C function into a Modula-3 exception.
-</p>
-
-<p>
-The <tt>RAISES</tt> clause is controlled
-by typemaps with the <tt>throws</tt> extension.
-If the typemap <tt>m3wrapinconv</tt> for <tt>blah *</tt>
-contains code that may raise the exceptions <tt>OSError.E</tt>
-you should declare
-<tt>%typemap("m3wrapinconv:throws") blah * %{OSError.E%}</tt>.
-</p>
-
-<H3><a name="Modula3_typemap_example">31.4.6 Example</a></H3>
-
-
-<p>
-The generation of wrappers in Modula-3 needs very fine control
-to take advantage of the language features.
-Here is an example of a generated wrapper
-where almost everything is generated by a typemap:
-</p>
-
-<div class="code"><pre>
-<I>         (* %relabel  m3wrapinmode m3wrapinname m3wrapintype  m3wrapindefault *)</I>
-  PROCEDURE Name     (READONLY       str       :    TEXT    :=      ""       )
-<I>              (* m3wrapoutcheck:throws *)</I>
-     : NameResult RAISES {E} =
-    CONST
-      arg1name = "str";                  <I>(* m3wrapargconst *)</I>
-    VAR
-      arg0   : C.char_star;              <I>(* m3wrapretvar *)</I>
-      arg1   : C.char_star;              <I>(* m3wrapargvar *)</I>
-      arg2   : C.int;
-      result : RECORD
-<I>           (*m3wrapretname  m3wraprettype*)</I>
-                 unixPath : TEXT;
-<I>           (*m3wrapoutname  m3wrapouttype*)</I>
-                 checksum : CARDINAL;
-               END;
-    BEGIN
-      TRY
-        arg1 := M3toC.SharedTtoS(str);   <I>(* m3wrapinconv *)</I>
-        IF Text.Length(arg1) &gt; 10 THEN   <I>(* m3wrapincheck *)</I>
-          RAISE E("str too long");
-        END;
-<I> (* m3wrapretraw           m3wrapargraw *)</I>
-        arg0 := MessyToUnix  (arg1,   arg2);
-        result.unixPath := M3toC.CopyStoT(arg0);  <I>(* m3wrapretconv *)</I>
-        result.checksum := arg2;         <I>(* m3wrapoutconv *)</I>
-        IF result.checksum = 0 THEN      <I>(* m3wrapoutcheck *)</I>
-          RAISE E("invalid checksum");
-        END;
-      FINALLY
-        M3toC.FreeSharedS(str, arg1);     <I>(* m3wrapfreearg *)</I>
-      END;
-    END Name;
-</pre></div>
-
-
-<H2><a name="Modula3_hints">31.5 More hints to the generator</a></H2>
-
-
-<H3><a name="Modula3_features">31.5.1 Features</a></H3>
-
-
-<table border summary="Modula-3 features">
-<tr>
-  <th>Feature</th>
-  <th>Example</th>
-  <th>Description</th>
-</tr>
-<tr>
-  <td>multiretval</td>
-  <td><tt>%m3multiretval get_box;</tt> or
-      <tt>%feature("modula3:multiretval") get_box;</tt></td>
-  <td>Let the denoted function return a <tt>RECORD</tt>
-      rather than a plain value.
-      This <tt>RECORD</tt> contains all arguments with "out" direction
-      including the return value of the C function (if there is one).
-      If more than one argument is "out"
-      then the function <b>must</b> have the <tt>multiretval</tt> feature activated,
-      but it is explicitly requested from the user to prevent mistakes.</td>
-</tr>
-<tr>
-  <td>constnumeric</td>
-  <td><tt>%constnumeric(12) twelve;</tt> or
-      <tt>%feature("constnumeric", "12") twelve;</tt></td>
-  <td>This feature can be used to tell Modula-3's back-end of SWIG
-      the value of an identifier.
-      This is necessary in the cases
-      where it was defined by a non-trivial C expression.
-      This feature is used by the
-      <tt>-generateconst</tt> <a href="#Modula3_commandline">option</a>.
-      In future it may be generalized to other kind of values
-      such as strings.
-      </td>
-</tr>
-</table>
-
-<H3><a name="Modula3_pragmas">31.5.2 Pragmas</a></H3>
-
-
-<table border summary="Modula-3 pragmas">
-<tr>
-  <th>Pragma</th>
-  <th>Example</th>
-  <th>Description</th>
-</tr>
-<tr>
-  <td>unsafe</td>
-  <td><tt>%pragma(modula3) unsafe="true";</tt></td>
-  <td>Mark the raw interface modules as <tt>UNSAFE</tt>.
-      This will be necessary in many cases.</td>
-</tr>
-<tr>
-  <td>library</td>
-  <td><tt>%pragma(modula3) library="m3fftw";</tt></td>
-  <td>Specifies the library name for the wrapper library to be created.
-      It should be distinct from the name of the library to be wrapped.</td>
-</tr>
-</table>
-
-<H2><a name="Modula3_remarks">31.6 Remarks</a></H2>
-
-
-<ul>
-<li>
-The Modula-3 part of SWIG doesn't try to generate nicely formatted code.
-If you need to read the generated code, use <tt>m3pp</tt> to postprocess the
-Modula files.
-</li>
-</ul>
-
-</body>
-</html>

Doc/Manual/Modules.html

@@ -7,7 +7,7 @@
 </head>
 
 <body bgcolor="#ffffff">
-<H1><a name="Modules">19 Working with Modules</a></H1>
+<H1><a name="Modules">20 Working with Modules</a></H1>
 <!-- INDEX -->
 <div class="sectiontoc">
 <ul>
@@ -24,7 +24,7 @@
 
 
 
-<H2><a name="Modules_introduction">19.1 Modules Introduction</a></H2>
+<H2><a name="Modules_introduction">20.1 Modules Introduction</a></H2>
 
 
 <p>
@@ -78,7 +78,7 @@ where you want to create a collection of modules.
 Each module in the collection is created via separate invocations of SWIG.
 </p>
 
-<H2><a name="Modules_nn1">19.2 Basics</a></H2>
+<H2><a name="Modules_nn1">20.2 Basics</a></H2>
 
 
 <p>
@@ -119,6 +119,10 @@ public:
 // File: derived_module.i
 %module derived_module
 
+%{
+#include "base.h"
+%}
+
 %import "base_module.i"
 
 %inline %{
@@ -156,6 +160,10 @@ The <tt>derived_module.i</tt> file shown above could be replaced with the follow
 // File: derived_module.i
 %module derived_module
 
+%{
+#include "base.h"
+%}
+
 %import(module="base_module") "base.h"
 
 %inline %{
@@ -177,7 +185,7 @@ in parallel from multiple threads as SWIG provides no locking - for more on that
 issue, read on.
 </p>
 
-<H2><a name="Modules_nn2">19.3 The SWIG runtime code</a></H2>
+<H2><a name="Modules_nn2">20.3 The SWIG runtime code</a></H2>
 
 
 <p>
@@ -243,7 +251,7 @@ can peacefully coexist. So the type structures are separated by the
 is empty. Only modules compiled with the same pair will share type information.
 </p>
 
-<H2><a name="Modules_external_run_time">19.4 External access to the runtime</a></H2>
+<H2><a name="Modules_external_run_time">20.4 External access to the runtime</a></H2>
 
 
 <p>As described in <a href="Typemaps.html#Typemaps_runtime_type_checker">The run-time type checker</a>,
@@ -282,7 +290,7 @@ SWIG_TYPE_TABLE to be the same as the module whose types you are trying to
 access.
 </p>
 
-<H2><a name="Modules_nn4">19.5 A word of caution about static libraries</a></H2>
+<H2><a name="Modules_nn4">20.5 A word of caution about static libraries</a></H2>
 
 
 <p>
@@ -293,7 +301,7 @@ into it. This is very often <b>NOT</b> what you want and it can lead to unexpect
 behavior. When working with dynamically loadable modules, you should try to work exclusively with shared libraries.
 </p>
 
-<H2><a name="Modules_nn5">19.6 References</a></H2>
+<H2><a name="Modules_nn5">20.6 References</a></H2>
 
 
 <p>
@@ -301,7 +309,7 @@ Due to the complexity of working with shared libraries and multiple modules, it
 an outside reference.  John Levine's "Linkers and Loaders" is highly recommended.
 </p>
 
-<H2><a name="Modules_nn6">19.7 Reducing the wrapper file size</a></H2>
+<H2><a name="Modules_nn6">20.7 Reducing the wrapper file size</a></H2>
 
 
 <p>

Doc/Manual/Mzscheme.html

@@ -8,7 +8,7 @@
 
 <body bgcolor="#ffffff">
 
-<H1><a name="Mzscheme">37 SWIG and MzScheme/Racket</a></H1>
+<H1><a name="Mzscheme">38 SWIG and MzScheme/Racket</a></H1>
 <!-- INDEX -->
 <div class="sectiontoc">
 <ul>
@@ -22,9 +22,10 @@
 
 
 <p>
-This section contains information on SWIG's support of Racket, formally known as MzScheme.
+This section contains information on SWIG's support of Racket, formally known as MzScheme.  SWIG works with Racket versions &lt; 8 (Racket 8 switched to be based on a different scheme interpreter and SWIG hasn't been updated for this change).
+</p>
 
-<H2><a name="MzScheme_nn2">37.1 Creating native structures</a></H2>
+<H2><a name="MzScheme_nn2">38.1 Creating native structures</a></H2>
 
 
 <p>
@@ -65,7 +66,7 @@ Then in scheme, you can use regular struct access procedures like
 </pre>
 </div>
 
-<H2><a name="MzScheme_simple">37.2 Simple example</a></H2>
+<H2><a name="MzScheme_simple">38.2 Simple example</a></H2>
 
 
 <p>
@@ -166,7 +167,7 @@ Some points of interest:
   <li> The above requests mzc to create an extension using the CGC garbage-collector. The alternative -- the 3m collector -- has generally better performance, but work is still required for SWIG to emit code which is compatible with it.
 </ul>
 
-<H2><a name="MzScheme_external_docs">37.3 External documentation</a></H2>
+<H2><a name="MzScheme_external_docs">38.3 External documentation</a></H2>
 
 
 <p>

Doc/Manual/Ocaml.html

@@ -7,7 +7,7 @@
 </head>
 
 <body bgcolor="#ffffff">
-<H1><a name="Ocaml">38 SWIG and OCaml</a></H1>
+<H1><a name="Ocaml">39 SWIG and OCaml</a></H1>
 <!-- INDEX -->
 <div class="sectiontoc">
 <ul>
@@ -85,10 +85,10 @@ variants, functions, classes, etc.
 
 <p>
 If you're not familiar with the Objective Caml language, you can visit
-<a href="http://ocaml.org/">The Ocaml Website</a>.
+<a href="https://ocaml.org/">The Ocaml Website</a>.
 </p>
 
-<H2><a name="Ocaml_nn2">38.1 Preliminaries</a></H2>
+<H2><a name="Ocaml_nn2">39.1 Preliminaries</a></H2>
 
 
 <p>
@@ -106,7 +106,7 @@ file Examples/Makefile illustrate how to compile and link SWIG modules that
 will be loaded dynamically.  This has only been tested on Linux so far.
 </p>
 
-<H3><a name="Ocaml_nn3">38.1.1 Running SWIG</a></H3>
+<H3><a name="Ocaml_nn3">39.1.1 Running SWIG</a></H3>
 
 
 <p>
@@ -129,7 +129,7 @@ you will compile the file <tt>example_wrap.c</tt> with <tt>ocamlc</tt> or
 the resulting .ml and .mli files as well, and do the final link with -custom
 (not needed for native link).</p>
 
-<H3><a name="Ocaml_nn4">38.1.2 Compiling the code</a></H3>
+<H3><a name="Ocaml_nn4">39.1.2 Compiling the code</a></H3>
 
 
 <p>
@@ -166,7 +166,7 @@ in C++ mode, you must:</p>
 </pre>
 </div>
 
-<H3><a name="Ocaml_nn5">38.1.3 The camlp4 module</a></H3>
+<H3><a name="Ocaml_nn5">39.1.3 The camlp4 module</a></H3>
 
 
 <p>
@@ -242,7 +242,7 @@ let b = C_string (getenv "PATH")
 </td></tr>
 </table>
 
-<H3><a name="Ocaml_nn6">38.1.4 Using your module</a></H3>
+<H3><a name="Ocaml_nn6">39.1.4 Using your module</a></H3>
 
 
 <p>
@@ -256,7 +256,7 @@ option to build your functions into the primitive list. This
 option is not needed when you build native code.
 </p>
 
-<H3><a name="Ocaml_nn7">38.1.5 Compilation problems and compiling with C++</a></H3>
+<H3><a name="Ocaml_nn7">39.1.5 Compilation problems and compiling with C++</a></H3>
 
 
 <p>
@@ -267,7 +267,7 @@ liberal with pointer types may not compile under the C++ compiler.
 Most code meant to be compiled as C++ will not have problems.
 </p>
 
-<H2><a name="Ocaml_nn8">38.2 The low-level Ocaml/C interface</a></H2>
+<H2><a name="Ocaml_nn8">39.2 The low-level Ocaml/C interface</a></H2>
 
 
 <p>
@@ -367,7 +367,7 @@ value items pass through directly, but you must make your own type
 signature for a function that uses value in this way.
 </p>
 
-<H3><a name="Ocaml_nn9">38.2.1 The generated module</a></H3>
+<H3><a name="Ocaml_nn9">39.2.1 The generated module</a></H3>
 
 
 <p>
@@ -401,7 +401,7 @@ it describes the output SWIG will generate for class definitions.
 </td></tr>
 </table>
 
-<H3><a name="Ocaml_nn10">38.2.2 Enums</a></H3>
+<H3><a name="Ocaml_nn10">39.2.2 Enums</a></H3>
 
 
 <p>
@@ -464,7 +464,7 @@ val x : Enum_test.c_obj = C_enum `a
 </pre>
 </div>
 
-<H4><a name="Ocaml_nn11">38.2.2.1 Enum typing in Ocaml</a></H4>
+<H4><a name="Ocaml_nn11">39.2.2.1 Enum typing in Ocaml</a></H4>
 
 
 <p>
@@ -477,10 +477,10 @@ functions imported from different modules.  You must convert values to master
 values using the swig_val function before sharing them with another module.
 </p>
 
-<H3><a name="Ocaml_nn12">38.2.3 Arrays</a></H3>
+<H3><a name="Ocaml_nn12">39.2.3 Arrays</a></H3>
 
 
-<H4><a name="Ocaml_nn13">38.2.3.1 Simple types of bounded arrays</a></H4>
+<H4><a name="Ocaml_nn13">39.2.3.1 Simple types of bounded arrays</a></H4>
 
 
 <p>
@@ -501,7 +501,7 @@ arrays of simple types with known bounds in your code, but this only works
 for arrays whose bounds are completely specified.
 </p>
 
-<H4><a name="Ocaml_nn14">38.2.3.2 Complex and unbounded arrays</a></H4>
+<H4><a name="Ocaml_nn14">39.2.3.2 Complex and unbounded arrays</a></H4>
 
 
 <p>
@@ -514,7 +514,7 @@ SWIG can't predict which of these methods will be used in the array,
 so you have to specify it for yourself in the form of a typemap.
 </p>
 
-<H4><a name="Ocaml_nn15">38.2.3.3 Using an object</a></H4>
+<H4><a name="Ocaml_nn15">39.2.3.3 Using an object</a></H4>
 
 
 <p>
@@ -528,7 +528,7 @@ Consider writing an object when the ending condition of your array is complex,
 such as using a required sentinel, etc.
 </p>
 
-<H4><a name="Ocaml_nn16">38.2.3.4 Example typemap for a function taking float * and int</a></H4>
+<H4><a name="Ocaml_nn16">39.2.3.4 Example typemap for a function taking float * and int</a></H4>
 
 
 <p>
@@ -579,7 +579,7 @@ void printfloats( float *tab, int len );
 </pre></td></tr></table>
 
 
-<H3><a name="Ocaml_nn17">38.2.4 C++ Classes</a></H3>
+<H3><a name="Ocaml_nn17">39.2.4 C++ Classes</a></H3>
 
 
 <p>
@@ -622,7 +622,7 @@ the underlying pointer, so using create_[x]_from_ptr alters the
 returned value for the same object.
 </p>
 
-<H4><a name="Ocaml_nn18">38.2.4.1 STL vector and string Example</a></H4>
+<H4><a name="Ocaml_nn18">39.2.4.1 STL vector and string Example</a></H4>
 
 
 <p>
@@ -702,7 +702,7 @@ baz
 #
 </pre></div>
 
-<H4><a name="Ocaml_nn19">38.2.4.2 C++ Class Example</a></H4>
+<H4><a name="Ocaml_nn19">39.2.4.2 C++ Class Example</a></H4>
 
 
 <p>
@@ -720,7 +720,6 @@ Here's a simple example using Trolltech's Qt Library:
 class QApplication {
 public:
   QApplication( int argc, char **argv );
-  void setMainWidget( QWidget *widget );
   void exec();
 };
 
@@ -732,25 +731,24 @@ public:
 };
 </pre></td></tr></table>
 
-<H4><a name="Ocaml_nn20">38.2.4.3 Compiling the example</a></H4>
+<H4><a name="Ocaml_nn20">39.2.4.3 Compiling the example</a></H4>
 
 
 <div class="code"><pre>
-bash-2.05a$ QTPATH=/your/qt/path
-bash-2.05a$ for file in swig.mli swig.ml swigp4.ml ; do swig -ocaml -co $file ; done
-bash-2.05a$ ocamlc -c swig.mli ; ocamlc -c swig.ml
-bash-2.05a$ ocamlc -I `camlp4 -where` -pp "camlp4o pa_extend.cmo q_MLast.cmo" -c swigp4.ml
-bash-2.05a$ swig -ocaml -c++ -I$QTPATH/include qt.i
-bash-2.05a$ mv qt_wrap.cxx qt_wrap.c
-bash-2.05a$ ocamlc -c -ccopt -xc++ -ccopt -g -g -ccopt -I$QTPATH/include qt_wrap.c
-bash-2.05a$ ocamlc -c qt.mli
-bash-2.05a$ ocamlc -c qt.ml
-bash-2.05a$ ocamlmktop -custom swig.cmo -I `camlp4 -where` \
+$ QTPATH=/your/qt/path
+$ for file in swig.mli swig.ml swigp4.ml ; do swig -ocaml -co $file ; done
+$ ocamlc -c swig.mli ; ocamlc -c swig.ml
+$ ocamlc -I `camlp4 -where` -pp "camlp4o pa_extend.cmo q_MLast.cmo" -c swigp4.ml
+$ swig -ocaml -c++ -o qt_wrap.c qt.i
+$ ocamlc -c -ccopt -xc++ -ccopt -g -g -ccopt -I$QTPATH/include qt_wrap.c
+$ ocamlc -c qt.mli
+$ ocamlc -c qt.ml
+$ ocamlmktop -custom swig.cmo -I `camlp4 -where` \
   camlp4o.cma swigp4.cmo qt_wrap.o qt.cmo -o qt_top -cclib \
   -L$QTPATH/lib -cclib -lqt
 </pre></div>
 
-<H4><a name="Ocaml_nn21">38.2.4.4 Sample Session</a></H4>
+<H4><a name="Ocaml_nn21">39.2.4.4 Sample Session</a></H4>
 
 
 <div class="code"><pre>
@@ -777,10 +775,10 @@ Assuming you have a working installation of QT, you will see a window
 containing the string "hi" in a button.
 </p>
 
-<H3><a name="Ocaml_nn22">38.2.5 Director Classes</a></H3>
+<H3><a name="Ocaml_nn22">39.2.5 Director Classes</a></H3>
 
 
-<H4><a name="Ocaml_nn23">38.2.5.1 Director Introduction</a></H4>
+<H4><a name="Ocaml_nn23">39.2.5.1 Director Introduction</a></H4>
 
 
 <p>
@@ -807,7 +805,7 @@ class foo {
 };
 </pre></div>
 
-<H4><a name="Ocaml_nn24">38.2.5.2 Overriding Methods in Ocaml</a></H4>
+<H4><a name="Ocaml_nn24">39.2.5.2 Overriding Methods in Ocaml</a></H4>
 
 
 <p>
@@ -835,7 +833,7 @@ In this example, I'll examine the objective caml code involved in providing
 an overloaded class.  This example is contained in Examples/ocaml/shapes.
 </p>
 
-<H4><a name="Ocaml_nn25">38.2.5.3 Director Usage Example</a></H4>
+<H4><a name="Ocaml_nn25">39.2.5.3 Director Usage Example</a></H4>
 
 
 <table border="1" bgcolor="#dddddd" summary="Director usage example">
@@ -896,7 +894,7 @@ in a more effortless style in ocaml, while leaving the "engine" part of the
 program in C++.
 </p>
 
-<H4><a name="Ocaml_nn26">38.2.5.4 Creating director objects</a></H4>
+<H4><a name="Ocaml_nn26">39.2.5.4 Creating director objects</a></H4>
 
 
 <p>
@@ -937,7 +935,7 @@ object from causing a core dump, as long as the object is destroyed
 properly.
 </p>
 
-<H4><a name="Ocaml_nn27">38.2.5.5 Typemaps for directors, directorin, directorout, directorargout</a></H4>
+<H4><a name="Ocaml_nn27">39.2.5.5 Typemaps for directors, directorin, directorout, directorargout</a></H4>
 
 
 <p>
@@ -948,7 +946,7 @@ well as a function return value in the same way you provide function arguments,
 and to receive arguments the same way you normally receive function returns.
 </p>
 
-<H4><a name="Ocaml_nn28">38.2.5.6 directorin typemap</a></H4>
+<H4><a name="Ocaml_nn28">39.2.5.6 directorin typemap</a></H4>
 
 
 <p>
@@ -959,7 +957,7 @@ code receives when you are called.  In general, a simple <tt>directorin</tt> typ
 can use the same body as a simple <tt>out</tt> typemap.
 </p>
 
-<H4><a name="Ocaml_nn29">38.2.5.7 directorout typemap</a></H4>
+<H4><a name="Ocaml_nn29">39.2.5.7 directorout typemap</a></H4>
 
 
 <p>
@@ -970,7 +968,7 @@ for the same type, except when there are special requirements for object
 ownership, etc.
 </p>
 
-<H4><a name="Ocaml_nn30">38.2.5.8 directorargout typemap</a></H4>
+<H4><a name="Ocaml_nn30">39.2.5.8 directorargout typemap</a></H4>
 
 
 <p>
@@ -987,7 +985,7 @@ In the event that you don't specify all of the necessary values, integral
 values will read zero, and struct or object returns have undefined results.
 </p>
 
-<H3><a name="Ocaml_nn31">38.2.6 Exceptions</a></H3>
+<H3><a name="Ocaml_nn31">39.2.6 Exceptions</a></H3>
 
 
 <p>
@@ -1075,7 +1073,7 @@ The language-independent <tt>exception.i</tt> library file can also be used
 to raise exceptions.  See the <a href="Library.html#Library">SWIG Library</a> chapter.
 </p>
 
-<H2><a name="Ocaml_nn32">38.3 Documentation Features</a></H2>
+<H2><a name="Ocaml_nn32">39.3 Documentation Features</a></H2>
 
 
 <p>
@@ -1084,7 +1082,7 @@ comments (colloquially referred to as "docstrings") that can be read by
 <a href="https://caml.inria.fr/pub/docs/manual-ocaml/ocamldoc.html">OCamldoc</a>.
 </p>
 
-<H3><a name="Ocaml_nn33">38.3.1 Module docstring</a></H3>
+<H3><a name="Ocaml_nn33">39.3.1 Module docstring</a></H3>
 
 
 <p>

Doc/Manual/Octave.html

@@ -9,7 +9,7 @@
 
 <body bgcolor="#ffffff">
 
-<H1><a name="Octave">29 SWIG and Octave</a></H1>
+<H1><a name="Octave">30 SWIG and Octave</a></H1>
 <!-- INDEX -->
 <div class="sectiontoc">
 <ul>
@@ -52,7 +52,7 @@
 
 <p>
          Octave is a high-level language intended for numerical programming that is mostly compatible with MATLAB.
-More information can be found at <a href="http://www.gnu.org/software/octave/">Octave web site</a>. 
+More information can be found at <a href="https://www.gnu.org/software/octave/">Octave web site</a>.
 </p>
 
 <p>
@@ -60,7 +60,7 @@ This chapter is intended to give an introduction to using the module. You should
 Also, there are a dozen or so examples in the Examples/octave directory, and hundreds in the test suite (Examples/test-suite and Examples/test-suite/octave).
 </p>
 
-<H2><a name="Octave_nn2">29.1 Preliminaries</a></H2>
+<H2><a name="Octave_nn2">30.1 Preliminaries</a></H2>
 
 
 <p>
@@ -76,7 +76,7 @@ This cannot be guaranteed however, as in recent times new Octave releases have r
 The SWIG runtime exports the function <tt>swig_octave_prereq()</tt> for checking the version of Octave.
 </p>
 
-<H2><a name="Octave_nn3">29.2 Running SWIG</a></H2>
+<H2><a name="Octave_nn3">30.2 Running SWIG</a></H2>
 
 
 <p>
@@ -108,7 +108,7 @@ The <tt>-c++</tt> option is also required when wrapping C++ code:
 This creates a C++ source file "example_wrap.cpp". A C++ file is generated even when wrapping C code as Octave is itself written in C++ and requires wrapper code to be in the same language. The generated C++ source file contains the low-level wrappers that need to be compiled and linked with the rest of your C/C++ application (in this case, the gcd implementation) to create an extension module.
 </p>
 
-<H3><a name="Octave_nn4">29.2.1 Command-line options</a></H3>
+<H3><a name="Octave_nn4">30.2.1 Command-line options</a></H3>
 
 
 <p>
@@ -131,7 +131,7 @@ The special name "." loads C global variables into the module namespace, i.e. al
 The <em>-opprefix</em> options sets the prefix of the names of global/friend <a href="#Octave_nn18">operator</a> functions.
 </p>
 
-<H3><a name="Octave_nn5">29.2.2 Compiling a dynamic module</a></H3>
+<H3><a name="Octave_nn5">30.2.2 Compiling a dynamic module</a></H3>
 
 
 <p>
@@ -158,7 +158,7 @@ $ mkoctfile example_wrap.cpp example.c
 
           <div class="targetlang"><pre>octave:1&gt; swigexample</pre></div>
 
-<H3><a name="Octave_nn6">29.2.3 Using your module</a></H3>
+<H3><a name="Octave_nn6">30.2.3 Using your module</a></H3>
 
 
 <p>
@@ -176,10 +176,10 @@ octave:4&gt; swigexample.cvar.Foo=4;
 octave:5&gt; swigexample.cvar.Foo
 ans =  4 </pre></div>
 
-<H2><a name="Octave_nn7">29.3 A tour of basic C/C++ wrapping</a></H2>
+<H2><a name="Octave_nn7">30.3 A tour of basic C/C++ wrapping</a></H2>
 
 
-<H3><a name="Octave_nn8">29.3.1 Modules</a></H3>
+<H3><a name="Octave_nn8">30.3.1 Modules</a></H3>
 
 
 <p>
@@ -224,7 +224,7 @@ octave:4&gt; swigexample.gcd(4, 6)
 ans =  2
 </pre></div>
 
-<H3><a name="Octave_nn9">29.3.2 Functions</a></H3>
+<H3><a name="Octave_nn9">30.3.2 Functions</a></H3>
 
 
 <p>
@@ -241,7 +241,7 @@ int fact(int n); </pre></div>
     <div class="targetlang"><pre>octave:1&gt; swigexample.fact(4)
 24 </pre></div>
 
-<H3><a name="Octave_nn10">29.3.3 Global variables</a></H3>
+<H3><a name="Octave_nn10">30.3.3 Global variables</a></H3>
 
 
 <p>
@@ -294,7 +294,7 @@ octave:2&gt; swigexample.PI=3.142;
 octave:3&gt; swigexample.PI
 ans =  3.1420 </pre></div>
 
-<H3><a name="Octave_nn11">29.3.4 Constants and enums</a></H3>
+<H3><a name="Octave_nn11">30.3.4 Constants and enums</a></H3>
 
 
 <p>
@@ -316,7 +316,7 @@ swigexample.SCONST="Hello World"
 swigexample.SUNDAY=0
 .... </pre></div>
 
-<H3><a name="Octave_nn12">29.3.5 Pointers</a></H3>
+<H3><a name="Octave_nn12">30.3.5 Pointers</a></H3>
 
 
 <p>
@@ -363,7 +363,11 @@ octave:2&gt; f=swigexample.fopen("not there", "r");
 error: value on right hand side of assignment is undefined
 error: evaluating assignment expression near line 2, column 2 </pre></div>
 
-<H3><a name="Octave_nn13">29.3.6 Structures and C++ classes</a></H3>
+<p>
+NULL C/C++ pointers are represented by the Octave null matrix, <tt>[]</tt>.
+</p>
+
+<H3><a name="Octave_nn13">30.3.6 Structures and C++ classes</a></H3>
 
 
 <p>
@@ -498,7 +502,7 @@ ans =  1
 Depending on the ownership setting of a <tt>swig_ref</tt>, it may call C++ destructors when its reference count goes to zero. See the section on memory management below for details.
 </p>
 
-<H3><a name="Octave_nn15">29.3.7 C++ inheritance</a></H3>
+<H3><a name="Octave_nn15">30.3.7 C++ inheritance</a></H3>
 
 
 <p>
@@ -507,7 +511,7 @@ This information contains the full class hierarchy. When an indexing operation (
 the tree is walked to find a match in the current class as well as any of its bases. The lookup is then cached in the <tt>swig_ref</tt>.
 </p>
 
-<H3><a name="Octave_nn17">29.3.8 C++ overloaded functions</a></H3>
+<H3><a name="Octave_nn17">30.3.8 C++ overloaded functions</a></H3>
 
 
 <p>
@@ -517,7 +521,7 @@ The dispatch function selects which overload to call (if any) based on the passe
 <tt>typecheck</tt> typemaps are used to analyze each argument, as well as assign precedence. See the chapter on typemaps for details.
 </p>
 
-<H3><a name="Octave_nn18">29.3.9 C++ operators</a></H3>
+<H3><a name="Octave_nn18">30.3.9 C++ operators</a></H3>
 
 
 <p>
@@ -570,13 +574,13 @@ __mul__        a * b
 __div__        a / b
 __pow__        a ^ b
 __ldiv__       a \ b
-__lshift__     a << b
-__rshift__     a >> b
-__lt__         a < b
-__le__         a <= b
+__lshift__     a &lt;&lt; b
+__rshift__     a &gt;&gt; b
+__lt__         a &lt; b
+__le__         a &lt;= b
 __eq__         a == b
-__ge__         a >= b
-__gt__         a > b
+__ge__         a &gt;= b
+__gt__         a &gt; b
 __ne__         a != b
 __el_mul__     a .* b
 __el_div__     a ./ b
@@ -598,16 +602,16 @@ On the C++ side, the default mappings are as follows:
 %rename(__mul__)       *::operator*;
 %rename(__div__)       *::operator/;
 %rename(__mod__)       *::operator%;
-%rename(__lshift__)    *::operator<<;
-%rename(__rshift__)    *::operator>>;
+%rename(__lshift__)    *::operator&lt;&lt;;
+%rename(__rshift__)    *::operator&gt;&gt;;
 %rename(__el_and__)    *::operator&amp;&amp;;
 %rename(__el_or__)     *::operator||;
 %rename(__xor__)       *::operator^;
 %rename(__invert__)    *::operator~;
-%rename(__lt__)        *::operator<;
-%rename(__le__)        *::operator<=;
-%rename(__gt__)        *::operator>;
-%rename(__ge__)        *::operator>=;
+%rename(__lt__)        *::operator&lt;;
+%rename(__le__)        *::operator&lt;=;
+%rename(__gt__)        *::operator&gt;;
+%rename(__ge__)        *::operator&gt;=;
 %rename(__eq__)        *::operator==;
 %rename(__ne__)        *::operator!=;
 %rename(__not__)       *::operator!;
@@ -621,7 +625,17 @@ On the C++ side, the default mappings are as follows:
 Octave can also utilise friend (i.e. non-member) operators with a simple %rename: see the example in the Examples/octave/operator directory.
 </p>
 
-<H3><a name="Octave_nn19">29.3.10 Class extension with %extend</a></H3>
+<p>
+Octave has several operators for which no corresponding C++ operators exist. For example, the Octave code
+</p>
+<div class="targetlang"><pre>
+x=[a,b,c];
+</pre></div>
+<p>
+calls the Octave operator <tt>horzcat</tt> of the class of <tt>a</tt>. Hence, if <tt>a</tt> is of type <tt>swig_ref</tt> you can write an overload for this operator for your wrapped C++ class by placing a file <tt>@swig_ref/horzcat.m</tt> in the Octave load path (like for every Octave class, see <a href="https://docs.octave.org/latest/Creating-a-Class.html">Creating a Class</a>). This Octave function file is then called whenever the above Octave code is executed for a variable of type <tt>swig_ref</tt>.
+</p>
+
+<H3><a name="Octave_nn19">30.3.10 Class extension with %extend</a></H3>
 
 
 <p>
@@ -634,7 +648,7 @@ You can use it to define special behavior, like for example defining Octave oper
 %extend A {
 string __str__() {
   stringstream sout;
-  sout&lt;&lt;$self->value;
+  sout&lt;&lt;$self-&gt;value;
   return sout.str();
 }
 }
@@ -660,7 +674,7 @@ Similarly, Octave can use the <tt>__float__</tt> method to convert an object to
 Octave 3.8.0 and later versions will also map unary functions X() to the corresponding <tt>__X__</tt> method, where X includes: abs(), acos(), acosh(), angle(), arg(), asin(), asinh(), atan(), atanh(), cbrt(), ceil(), conj(), cos(), cosh(), dawson(), erf(), erfc(), erfcinv(), erfcx(), erfi(), erfinv(), exp(), expm1(), finite(), fix(), floor(), gamma(), imag(), isalnum(), isalpha(), isascii(), iscntrl(), isdigit(), isgraph(), isinf(), islower(), isna(), isnan(), isprint(), ispunct(), isspace(), isupper(), isxdigit(), lgamma(), log(), log10(), log1p(), log2(), real(), round(), roundb(), signbit(), signum(), sin(), sinh(), sqrt(), tan(), tanh(), toascii(), tolower(), toupper()
 </p>
 
-<H3><a name="Octave_nn20">29.3.11 C++ templates</a></H3>
+<H3><a name="Octave_nn20">30.3.11 C++ templates</a></H3>
 
 
 <p>
@@ -737,10 +751,10 @@ ans =
 </pre></div>
 
 
-<H3><a name="Octave_nn21">29.3.12 C++ Smart Pointers</a></H3>
+<H3><a name="Octave_nn21">30.3.12 C++ Smart Pointers</a></H3>
 
 
-<H4><a name="Octave_smart_pointers_shared_ptr">29.3.12.1 The shared_ptr Smart Pointer</a></H4>
+<H4><a name="Octave_smart_pointers_shared_ptr">30.3.12.1 The shared_ptr Smart Pointer</a></H4>
 
 
 <p>
@@ -751,14 +765,14 @@ in the <a href="Library.html#Library_std_shared_ptr">shared_ptr smart pointer</a
 </p>
 
 
-<H4><a name="Octave_smart_pointers_generic">29.3.12.2 Generic Smart Pointers</a></H4>
+<H4><a name="Octave_smart_pointers_generic">30.3.12.2 Generic Smart Pointers</a></H4>
 
 
 <p>
 C++ smart pointers are fully supported as in other modules.
 </p>
 
-<H3><a name="Octave_nn22">29.3.13 Directors (calling Octave from C++ code)</a></H3>
+<H3><a name="Octave_nn22">30.3.13 Directors (calling Octave from C++ code)</a></H3>
 
 
 <p>
@@ -839,14 +853,14 @@ c-side routine called
 octave-side routine called
 </pre></div>
 
-<H3><a name="Octave_nn23">29.3.14 Threads</a></H3>
+<H3><a name="Octave_nn23">30.3.14 Threads</a></H3>
 
 
 <p>
 The use of threads in wrapped Director code is not supported; i.e., an Octave-side implementation of a C++ class must be called from the Octave interpreter's thread. Anything fancier (apartment/queue model, whatever) is left to the user. Without anything fancier, this amounts to the limitation that Octave must drive the module... like, for example, an optimization package that calls Octave to evaluate an objective function.
 </p>
 
-<H3><a name="Octave_nn24">29.3.15 Memory management</a></H3>
+<H3><a name="Octave_nn24">30.3.15 Memory management</a></H3>
 
 
 <p>
@@ -880,14 +894,14 @@ The %newobject directive may be used to control this behavior for pointers retur
 In the case where one wishes for the C++ side to own an object that was created in Octave (especially a Director object), one can use the __disown() method to invert this logic. Then letting the Octave reference count go to zero will not destroy the object, but destroying the object will invalidate the Octave-side object if it still exists (and call destructors of other C++ bases in the case of multiple inheritance/<tt>subclass()</tt>'ing).
 </p>
 
-<H3><a name="Octave_nn25">29.3.16 STL support</a></H3>
+<H3><a name="Octave_nn25">30.3.16 STL support</a></H3>
 
 
 <p>
 Various STL library files are provided for wrapping STL containers.
 </p>
 
-<H3><a name="Octave_nn26">29.3.17 Matrix typemaps</a></H3>
+<H3><a name="Octave_nn26">30.3.17 Matrix typemaps</a></H3>
 
 
 <p>

Doc/Manual/Perl5.html

@@ -7,7 +7,7 @@
 </head>
 
 <body bgcolor="#ffffff">
-<H1><a name="Perl5">30 SWIG and Perl5</a></H1>
+<H1><a name="Perl5">31 SWIG and Perl5</a></H1>
 <!-- INDEX -->
 <div class="sectiontoc">
 <ul>
@@ -91,13 +91,13 @@
 <p>
 This chapter describes SWIG's support of Perl5. Although the Perl5
 module is one of the earliest SWIG modules, it has continued to evolve
-and has been improved greatly with the help of SWIG users. For the
-best results, it is recommended that SWIG be used with Perl 5.8 or
-later. We're no longer testing regularly with older versions, but
-Perl 5.6 seems to mostly work, while older versions don't.
+and has been improved greatly with the help of SWIG users. As of SWIG
+4.1.0, the minimum version of Perl we aim to support is Perl 5.8.0.
+We can no longer easily test with older versions, and they no longer
+seem to be in active use.
 </p>
 
-<H2><a name="Perl5_nn2">30.1 Overview</a></H2>
+<H2><a name="Perl5_nn2">31.1 Overview</a></H2>
 
 
 <p>
@@ -118,7 +118,7 @@ described.  Advanced customization features, typemaps, and other
 options are found near the end of the chapter.
 </p>
 
-<H2><a name="Perl5_nn3">30.2 Preliminaries</a></H2>
+<H2><a name="Perl5_nn3">31.2 Preliminaries</a></H2>
 
 
 <p>
@@ -143,7 +143,7 @@ To build the module, you will need to compile the file
 <tt>example_wrap.c</tt> and link it with the rest of your program.
 </p>
 
-<H3><a name="Perl5_nn4">30.2.1 Getting the right header files</a></H3>
+<H3><a name="Perl5_nn4">31.2.1 Getting the right header files</a></H3>
 
 
 <p>
@@ -175,7 +175,7 @@ $ perl -e 'use Config; print "$Config{archlib}\n";'
 </pre>
 </div>
 
-<H3><a name="Perl5_nn5">30.2.2 Compiling a dynamic module</a></H3>
+<H3><a name="Perl5_nn5">31.2.2 Compiling a dynamic module</a></H3>
 
 
 <p>
@@ -208,7 +208,7 @@ the target should be named `<tt>example.so</tt>',
 `<tt>example.sl</tt>', or the appropriate dynamic module name on your system.
 </p>
 
-<H3><a name="Perl5_nn6">30.2.3 Building a dynamic module with MakeMaker</a></H3>
+<H3><a name="Perl5_nn6">31.2.3 Building a dynamic module with MakeMaker</a></H3>
 
 
 <p>
@@ -242,7 +242,7 @@ the preferred approach to compilation.  More information about MakeMaker can be
 found in "Programming Perl, 2nd ed." by Larry Wall, Tom Christiansen,
 and Randal Schwartz.</p>
 
-<H3><a name="Perl5_nn7">30.2.4 Building a static version of Perl</a></H3>
+<H3><a name="Perl5_nn7">31.2.4 Building a static version of Perl</a></H3>
 
 
 <p>
@@ -311,7 +311,7 @@ added to it.  Depending on your machine, you may need to link with
 additional libraries such as <tt>-lsocket, -lnsl, -ldl</tt>, etc.
 </p>
 
-<H3><a name="Perl5_nn8">30.2.5 Using the module</a></H3>
+<H3><a name="Perl5_nn8">31.2.5 Using the module</a></H3>
 
 
 <p>
@@ -464,7 +464,7 @@ system configuration (this requires root access and you will need to
 read the man pages).
 </p>
 
-<H3><a name="Perl5_nn9">30.2.6 Compilation problems and compiling with C++</a></H3>
+<H3><a name="Perl5_nn9">31.2.6 Compilation problems and compiling with C++</a></H3>
 
 
 <p>
@@ -604,10 +604,10 @@ source has a list of macros that are known to conflict with either standard head
 other headers.  But if you get macro type conflicts from other macros not included
 in Lib/perl5/noembed.h while compiling the wrapper, you will
 have to find the macro that conflicts and add an #undef into the .i file.  Please report
-any conflicting macros you find to <a href="http://www.swig.org/mail.html">swig-user mailing list</a>.
+any conflicting macros you find to <a href="https://www.swig.org/mail.html">swig-user mailing list</a>.
 </p>
 
-<H3><a name="Perl5_nn10">30.2.7 Compiling for 64-bit platforms</a></H3>
+<H3><a name="Perl5_nn10">31.2.7 Compiling for 64-bit platforms</a></H3>
 
 
 <p>
@@ -634,7 +634,7 @@ also introduce problems on platforms that support more than one
 linking standard (e.g., -o32 and -n32 on Irix).
 </p>
 
-<H2><a name="Perl5_nn11">30.3 Building Perl Extensions under Windows</a></H2>
+<H2><a name="Perl5_nn11">31.3 Building Perl Extensions under Windows</a></H2>
 
 
 <p>
@@ -645,7 +645,7 @@ section assumes you are using SWIG with Microsoft Visual C++
 although the procedure may be similar with other compilers.  
 </p>
 
-<H3><a name="Perl5_nn12">30.3.1 Running SWIG from Developer Studio</a></H3>
+<H3><a name="Perl5_nn12">31.3.1 Running SWIG from Developer Studio</a></H3>
 
 
 <p>
@@ -680,7 +680,6 @@ files(s) field".
 installation under "Additional include directories".
 
 <li>Define the symbols WIN32 and MSWIN32 under preprocessor options.
-If using the ActiveWare port, also define the symbol PERL_OBJECT.
 Note that all extensions to the ActiveWare port must be compiled with
 the C++ compiler since Perl has been encapsulated in a C++ class.
 
@@ -708,7 +707,7 @@ print "$a\n";
 
 </pre></div>
 
-<H3><a name="Perl5_nn13">30.3.2 Using other compilers</a></H3>
+<H3><a name="Perl5_nn13">31.3.2 Using other compilers</a></H3>
 
 
 <p>
@@ -716,7 +715,7 @@ SWIG is known to work with Cygwin and may work with other compilers on Windows.
 For general hints and suggestions refer to the <a href="Windows.html#Windows">Windows</a> chapter.
 </p>
 
-<H2><a name="Perl5_nn14">30.4 The low-level interface</a></H2>
+<H2><a name="Perl5_nn14">31.4 The low-level interface</a></H2>
 
 
 <p>
@@ -726,7 +725,7 @@ can be used to control your application.  However, it is also used to
 construct more user-friendly proxy classes as described in the next section.
 </p>
 
-<H3><a name="Perl5_nn15">30.4.1 Functions</a></H3>
+<H3><a name="Perl5_nn15">31.4.1 Functions</a></H3>
 
 
 <p>
@@ -749,7 +748,7 @@ use example;
 $a = &amp;example::fact(2);
 </pre></div>
 
-<H3><a name="Perl5_nn16">30.4.2 Global variables</a></H3>
+<H3><a name="Perl5_nn16">31.4.2 Global variables</a></H3>
 
 
 <p>
@@ -819,7 +818,7 @@ extern char *path;       // Declared later in the input
 </pre>
 </div>
 
-<H3><a name="Perl5_nn17">30.4.3 Constants</a></H3>
+<H3><a name="Perl5_nn17">31.4.3 Constants</a></H3>
 
 
 <p>
@@ -859,7 +858,7 @@ print example::FOO, "\n";
 </pre>
 </div>
 
-<H3><a name="Perl5_nn18">30.4.4 Pointers</a></H3>
+<H3><a name="Perl5_nn18">31.4.4 Pointers</a></H3>
 
 
 <p>
@@ -968,7 +967,7 @@ as XS and <tt>xsubpp</tt>.  Given the advancement of the SWIG typesystem and the
 SWIG and XS, this is no longer supported.
 </p>
 
-<H3><a name="Perl5_nn19">30.4.5 Structures</a></H3>
+<H3><a name="Perl5_nn19">31.4.5 Structures</a></H3>
 
 
 <p>
@@ -1065,7 +1064,7 @@ int *Foo_x_get(Foo *self) {
 <p>
 If you want to set an array member, you will need to supply a "memberin" typemap
 described later in this chapter.  As a special case, SWIG does generate
-code to set array members of type <tt>char</tt> (allowing you to store a Python
+code to set array members of type <tt>char</tt> (allowing you to store a Perl
 string in the structure).
 </p>
 
@@ -1102,7 +1101,7 @@ void Bar_f_set(Bar *b, Foo *val) {
 </div>
 
 
-<H3><a name="Perl5_nn20">30.4.6 C++ classes</a></H3>
+<H3><a name="Perl5_nn20">31.4.6 C++ classes</a></H3>
 
 
 <p>
@@ -1167,7 +1166,7 @@ provides direct access to C++ objects.  A higher level interface using Perl prox
 can be built using these low-level accessors.  This is described shortly.
 </p>
 
-<H3><a name="Perl5_nn21">30.4.7 C++ classes and type-checking</a></H3>
+<H3><a name="Perl5_nn21">31.4.7 C++ classes and type-checking</a></H3>
 
 
 <p>
@@ -1203,7 +1202,7 @@ If necessary, the type-checker also adjusts the value of the pointer (as is nece
 multiple inheritance is used).
 </p>
 
-<H3><a name="Perl5_nn22">30.4.8 C++ overloaded functions</a></H3>
+<H3><a name="Perl5_nn22">31.4.8 C++ overloaded functions</a></H3>
 
 
 <p>
@@ -1247,7 +1246,7 @@ example::Spam_foo_d($s, 3.14);
 Please refer to the "SWIG Basics" chapter for more information. 
 </p>
 
-<H3><a name="Perl5_nn23">30.4.9 Operators</a></H3>
+<H3><a name="Perl5_nn23">31.4.9 Operators</a></H3>
 
 
     <p>
@@ -1274,7 +1273,7 @@ The following C++ operators are currently supported by the Perl module:
 <li>operator or  </li>
     </ul>
 
-<H3><a name="Perl5_nn24">30.4.10 Modules and packages</a></H3>
+<H3><a name="Perl5_nn24">31.4.10 Modules and packages</a></H3>
 
 
 <p>
@@ -1369,7 +1368,7 @@ print Foo::fact(4), "\n";        # Call a function in package FooBar
 </pre></div>
 -->
 
-<H2><a name="Perl5_nn25">30.5 Input and output parameters</a></H2>
+<H2><a name="Perl5_nn25">31.5 Input and output parameters</a></H2>
 
 
 <p>
@@ -1494,7 +1493,7 @@ as well as a special error code:
 <div class="code">
 <pre>
 /* send message, return number of bytes sent, along with success code */
-int send_message(char *text, int len, int *success);
+int send_message(char *text, int *success);
 </pre>
 </div>
 
@@ -1588,7 +1587,7 @@ print "$c\n";
 <b>Note:</b> The <tt>REFERENCE</tt> feature is only currently supported for numeric types (integers and floating point).
 </p>
 
-<H2><a name="Perl5_nn26">30.6 Exception handling</a></H2>
+<H2><a name="Perl5_nn26">31.6 Exception handling</a></H2>
 
 
 <p>
@@ -1730,29 +1729,7 @@ Since SWIG's exception handling is user-definable, you are not limited to C++ ex
 See the chapter on "<a href="Customization.html#Customization">Customization features</a>" for more examples.
 </p>
 
-<p>
-<b>Compatibility note:</b> In SWIG1.1, exceptions were defined using the older <tt>%except</tt> directive:
-</p>
-
-<div class="code">
-<pre>
-%except(python) {
-  try {
-    $function
-  }
-  catch (RangeError) {
-    croak("Array index out-of-bounds");
-  }
-}
-</pre>
-</div>
-
-<p>
-This is still supported, but it is deprecated.  The newer <tt>%exception</tt> directive provides the same
-functionality, but it has additional capabilities that make it more powerful.
-</p>
-
-<H2><a name="Perl5_nn27">30.7 Remapping datatypes with typemaps</a></H2>
+<H2><a name="Perl5_nn27">31.7 Remapping datatypes with typemaps</a></H2>
 
 
 <p>
@@ -1769,7 +1746,7 @@ Typemaps are only used if you want to change some aspect of the primitive
 C-Perl interface.
 </p>
 
-<H3><a name="Perl5_nn28">30.7.1 A simple typemap example</a></H3>
+<H3><a name="Perl5_nn28">31.7.1 A simple typemap example</a></H3>
 
 
 <p>
@@ -1873,7 +1850,7 @@ example::count("e", "Hello World");
 </div>
 
 
-<H3><a name="Perl5_nn29">30.7.2 Perl5 typemaps</a></H3>
+<H3><a name="Perl5_nn29">31.7.2 Perl5 typemaps</a></H3>
 
 
 <p>
@@ -1962,14 +1939,6 @@ Clean up return value from a function.
 Setting of C++ member data (all languages).
 </div>
 
-<p>
-<tt>%typemap(memberout)</tt>
-</p>
-
-<div class="indent">
-Return of C++ member data (all languages).
-</div>
-
 <p>
 <tt>%typemap(check)</tt>
 </p>
@@ -1978,7 +1947,7 @@ Return of C++ member data (all languages).
 Check value of input parameter.
 </div>
 
-<H3><a name="Perl5_nn30">30.7.3 Typemap variables</a></H3>
+<H3><a name="Perl5_nn30">31.7.3 Typemap variables</a></H3>
 
 
 <p>
@@ -2049,7 +2018,7 @@ properly assigned.
 The Perl name of the wrapper function being created.
 </div>
 
-<H3><a name="Perl5_nn31">30.7.4 Useful functions</a></H3>
+<H3><a name="Perl5_nn31">31.7.4 Useful functions</a></H3>
 
 
 <p>
@@ -2118,7 +2087,7 @@ int       sv_isa(SV *, char *0;
 </div>
 
 
-<H2><a name="Perl5_nn32">30.8 Typemap Examples</a></H2>
+<H2><a name="Perl5_nn32">31.8 Typemap Examples</a></H2>
 
 
 <p>
@@ -2127,7 +2096,7 @@ might look at the files "<tt>perl5.swg</tt>" and "<tt>typemaps.i</tt>" in
 the SWIG library.
 </p>
 
-<H3><a name="Perl5_nn33">30.8.1 Converting a Perl5 array to a char **</a></H3>
+<H3><a name="Perl5_nn33">31.8.1 Converting a Perl5 array to a char **</a></H3>
 
 
 <p>
@@ -2219,7 +2188,7 @@ print @$b, "\n";                                 # Print it out
 </pre></div>
 
 
-<H3><a name="Perl5_nn34">30.8.2 Return values</a></H3>
+<H3><a name="Perl5_nn34">31.8.2 Return values</a></H3>
 
 
 <p>
@@ -2243,12 +2212,12 @@ can be done using the <tt>EXTEND()</tt> macro as in:
     EXTEND(sp, 1);              /* Extend the stack by 1 object */
   }
   $result = sv_newmortal();
-  sv_setiv($target, (IV) *($1));
+  sv_setiv($result, (IV) *($1));
   argvi++;
 }
 </pre></div>
 
-<H3><a name="Perl5_nn35">30.8.3 Returning values from arguments</a></H3>
+<H3><a name="Perl5_nn35">31.8.3 Returning values from arguments</a></H3>
 
 
 <p>
@@ -2302,7 +2271,7 @@ print "multout(7, 13) = @r\n";
 ($x, $y) = multout(7, 13);
 </pre></div>
 
-<H3><a name="Perl5_nn36">30.8.4 Accessing array structure members</a></H3>
+<H3><a name="Perl5_nn36">31.8.4 Accessing array structure members</a></H3>
 
 
 <p>
@@ -2320,7 +2289,7 @@ typedef struct {
 
 <p>
 By default, SWIG doesn't know how to the handle the values structure
-member it's an array, not a pointer.  In this case, SWIG makes the array member
+member because it's an array, not a pointer.  In this case, SWIG makes the array member
 read-only.   Reading will simply return a pointer to the first item in the array.
 To make the member writable, a "memberin" typemap can be used.
 </p>
@@ -2365,7 +2334,7 @@ the "in" typemap in the previous section would be used to convert an
 to copy the converted array into a C data structure.
 </p>
 
-<H3><a name="Perl5_nn37">30.8.5 Turning Perl references into C pointers</a></H3>
+<H3><a name="Perl5_nn37">31.8.5 Turning Perl references into C pointers</a></H3>
 
 
 <p>
@@ -2430,7 +2399,7 @@ print "$c\n";
 
 </pre></div>
 
-<H3><a name="Perl5_nn38">30.8.6 Pointer handling</a></H3>
+<H3><a name="Perl5_nn38">31.8.6 Pointer handling</a></H3>
 
 
 <p>
@@ -2515,7 +2484,7 @@ For example:
 </pre>
 </div>
 
-<H2><a name="Perl5_nn39">30.9 Proxy classes</a></H2>
+<H2><a name="Perl5_nn39">31.9 Proxy classes</a></H2>
 
 
 <p>
@@ -2531,7 +2500,7 @@ to the underlying code.  This section describes the implementation
 details of the proxy interface.
 </p>
 
-<H3><a name="Perl5_nn40">30.9.1 Preliminaries</a></H3>
+<H3><a name="Perl5_nn40">31.9.1 Preliminaries</a></H3>
 
 
 <p>
@@ -2553,7 +2522,7 @@ SWIG creates a collection of high-level Perl wrappers.  In your scripts, you wil
 high level wrappers.  The wrappers, in turn, interact with the low-level procedural module.
 </p>
 
-<H3><a name="Perl5_nn41">30.9.2 Structure and class wrappers</a></H3>
+<H3><a name="Perl5_nn41">31.9.2 Structure and class wrappers</a></H3>
 
 
 <p>
@@ -2651,8 +2620,8 @@ constructors and destructors for the package and are always named
 "new" and "DESTROY".  The constructor always returns a tied hash
 table.  This hash table is used to access the member variables of a
 structure in addition to being able to invoke member functions.  The
-<tt>%OWNER</tt> and <tt>%BLESSEDMEMBERS</tt> hash tables are used
-internally and described shortly.
+<tt>%OWNER</tt> and <tt>%BLESSEDMEMBERS</tt> hash tables are
+implementation details used internally and described shortly.
 </p>
 
 <p>
@@ -2680,7 +2649,7 @@ $v-&gt;DESTROY();
 
 </pre></div>
 
-<H3><a name="Perl5_nn42">30.9.3 Object Ownership</a></H3>
+<H3><a name="Perl5_nn42">31.9.3 Object Ownership</a></H3>
 
 
 <p>
@@ -2740,8 +2709,15 @@ to a C function that remembers the object, and then destroy the
 corresponding Perl object (this situation turns out to come up
 frequently when constructing objects like linked lists and trees).
 When C takes possession of an object, you can change Perl's ownership
-by simply deleting the object from the <tt>%OWNER</tt> hash.  This is
-done using the <tt>DISOWN</tt> method.
+by calling the <tt>DISOWN</tt> method (which will delete the object
+from the internal <tt>%OWNER</tt> hash).
+</p>
+
+<p>
+The <tt>%OWNER</tt> hash is an implementation detail, discussed here
+only to help clarify the operation of <tt>ACQUIRE</tt> and <tt>DISOWN</tt>.
+You should not access <tt>%OWNER</tt> directly - the details of how it
+works (and possibly even its existence) may change in future SWIG versions.
 </p>
 
 <div class="targetlang"><pre>
@@ -2767,7 +2743,7 @@ counting, garbage collection, or advanced features one might find in
 sophisticated languages.
 </p>
 
-<H3><a name="Perl5_nn43">30.9.4 Nested Objects</a></H3>
+<H3><a name="Perl5_nn43">31.9.4 Nested Objects</a></H3>
 
 
 <p>
@@ -2820,7 +2796,7 @@ $p-&gt;{f}-&gt;{x} = 0.0;
 %${$p-&gt;{v}} = ( x=&gt;0, y=&gt;0, z=&gt;0);         
 </pre></div>
 
-<H3><a name="Perl5_nn44">30.9.5 Proxy Functions</a></H3>
+<H3><a name="Perl5_nn44">31.9.5 Proxy Functions</a></H3>
 
 
 <p>
@@ -2854,7 +2830,7 @@ This function replaces the original function, but operates in an
 identical manner.
 </p>
 
-<H3><a name="Perl5_nn45">30.9.6 Inheritance</a></H3>
+<H3><a name="Perl5_nn45">31.9.6 Inheritance</a></H3>
 
 
 <p>
@@ -2930,7 +2906,7 @@ particular, inheritance of data members is extremely tricky (and I'm
 not even sure if it really works).
 </p>
 
-<H3><a name="Perl5_nn46">30.9.7 Modifying the proxy methods</a></H3>
+<H3><a name="Perl5_nn46">31.9.7 Modifying the proxy methods</a></H3>
 
 
 <p>
@@ -2958,7 +2934,7 @@ public:
 };
 </pre></div>
 
-<H2><a name="Perl5_nn47">30.10 Adding additional Perl code</a></H2>
+<H2><a name="Perl5_nn47">31.10 Adding additional Perl code</a></H2>
 
 
 <p>
@@ -3009,7 +2985,7 @@ set_transform($im, $a);
 </pre>
 </div>
 
-<H2><a name="Perl5_directors">30.11 Cross language polymorphism</a></H2>
+<H2><a name="Perl5_directors">31.11 Cross language polymorphism</a></H2>
 
 
 <p>
@@ -3043,7 +3019,7 @@ proxy classes, director classes, and C wrapper functions takes care of
 all the cross-language method routing transparently.
 </p>
 
-<H3><a name="Perl5_nn48">30.11.1 Enabling directors</a></H3>
+<H3><a name="Perl5_nn48">31.11.1 Enabling directors</a></H3>
 
 
 <p>
@@ -3133,7 +3109,7 @@ sub one {
 </div>
 
 
-<H3><a name="Perl5_nn49">30.11.2 Director classes</a></H3>
+<H3><a name="Perl5_nn49">31.11.2 Director classes</a></H3>
 
 
  
@@ -3214,7 +3190,7 @@ so there is no need for the extra overhead involved with routing the
 calls through Perl.
 </p>
 
-<H3><a name="Perl5_nn50">30.11.3 Ownership and object destruction</a></H3>
+<H3><a name="Perl5_nn50">31.11.3 Ownership and object destruction</a></H3>
 
 
 <p>
@@ -3263,7 +3239,7 @@ sub DESTROY {
 </div>
 
 
-<H3><a name="Perl5_nn51">30.11.4 Exception unrolling</a></H3>
+<H3><a name="Perl5_nn51">31.11.4 Exception unrolling</a></H3>
 
 
 <p>
@@ -3319,7 +3295,7 @@ Swig::DirectorMethodException is thrown, Perl will register the
 exception as soon as the C wrapper function returns.
 </p>
 
-<H3><a name="Perl5_nn52">30.11.5 Overhead and code bloat</a></H3>
+<H3><a name="Perl5_nn52">31.11.5 Overhead and code bloat</a></H3>
 
 
 <p>
@@ -3353,7 +3329,7 @@ directive) for only those methods that are likely to be extended in
 Perl.
 </p>
 
-<H3><a name="Perl5_nn53">30.11.6 Typemaps</a></H3>
+<H3><a name="Perl5_nn53">31.11.6 Typemaps</a></H3>
 
 
 <p>

Doc/Manual/Php.html

@@ -7,7 +7,7 @@
 </head>
 
 <body bgcolor="#ffffff">
-<H1><a name="Php">31 SWIG and PHP</a></H1>
+<H1><a name="Php">32 SWIG and PHP</a></H1>
 <!-- INDEX -->
 <div class="sectiontoc">
 <ul>
@@ -30,6 +30,7 @@
 <li><a href="#Php_nn2_6_3">Static Member Variables</a>
 <li><a href="#Php_nn2_6_4">Static Member Functions</a>
 <li><a href="#Php_nn2_6_5">Specifying Implemented Interfaces</a>
+<li><a href="#Php_nn2_6_6">Dynamic Properties</a>
 </ul>
 <li><a href="#Php_nn2_7">PHP Pragmas, Startup and Shutdown code</a>
 </ul>
@@ -50,18 +51,20 @@
 
 
 <p>
-In this chapter, we discuss SWIG's support of PHP.  SWIG currently supports
-generating wrappers for PHP7.  Support for PHP5 was removed in SWIG 4.0.0
-and support for PHP4 was removed in SWIG 1.3.37.
+In this chapter, we discuss SWIG's support of PHP.  Currently any PHP8
+release should work.
 </p>
 
 <p>
-Currently any PHP7 release should work.
+Support for PHP8 was added in SWIG 4.1.0.
+Support for PHP7 was added in SWIG 3.0.11 and removed in 4.2.0.
+Support for PHP5 was removed in SWIG 4.0.0 and support for PHP4 was removed in
+SWIG 1.3.37.  There never was a PHP6 release.
 </p>
 
 <p>
 In order to use this module, you will need to have a copy of the PHP
-include files to compile the SWIG generated files.  If you installed
+include files to compile the SWIG generated C/C++ sources.  If you installed
 PHP from a binary package, you may need to install a "php-dev" or "php-devel"
 package for these to be installed.  You can find out where these files are
 by running <tt>php-config --includes</tt>.  To use the built PHP module you
@@ -70,30 +73,36 @@ your extension into php directly, you will need the complete PHP source tree
 available.
 </p>
 
-<H2><a name="Php_nn1">31.1 Generating PHP Extensions</a></H2>
+<H2><a name="Php_nn1">32.1 Generating PHP Extensions</a></H2>
 
 
 <p>
-To build a PHP extension, run swig using the <tt>-php7</tt> option as follows
-(<tt>-php</tt> is also supported and currently is an alias for <tt>-php7</tt>
-but prior to SWIG 4.0.0 it was an alias for <tt>-php5</tt>):
+To build a PHP extension, run swig using the <tt>-php</tt> option
+(you can also use <tt>-php7</tt> - PHP7 and PHP8 have a largely compatible C
+extension API, hence the same option name has been used for both).  For
+example:
 </p>
 
 <div class="code"><pre>
-swig -php7 example.i
+swig -php example.i
 </pre></div>
 
 <p>
-This will produce 3 files example_wrap.c, php_example.h and
-example.php. The first file, <tt>example_wrap.c</tt> contains all of
+This will produce 2 files: example_wrap.c and php_example.h.
+The first file, <tt>example_wrap.c</tt> contains all of
 the C code needed to build a PHP extension. The second file,
 <tt>php_example.h</tt> contains the header information needed if
 you wish to statically link the extension into the php interpreter.
-The third file,
-<tt>example.php</tt> can be included by PHP scripts.  It attempts to
-dynamically load the extension and contains extra php code specified
-in the interface file.  If wrapping C++ code with PHP classes, it will
-also contain PHP class wrappers.
+</p>
+
+<p>
+If the interface file uses <tt>%pragma(php) include=</tt>... or
+<tt>%pragma(php) code=</tt>... then SWIG will also generate a third file,
+<tt>example.php</tt> to contain what these specify.  In SWIG &lt; 4.1.0,
+this third file was always generated as it defined the PHP classes, etc
+(but this is now done via C code in <tt>example_wrap.c</tt>) and also
+contained code to dynamically load the extension (but this used the
+PHP <tt>dl()</tt> function, which isn't recommended nowadays).
 </p>
 
 <p>
@@ -119,7 +128,7 @@ and it doesn't play nicely with package system.  We don't recommend
 this approach, or provide explicit support for it.
 </p>
 
-<H3><a name="Php_nn1_1">31.1.1 Building a loadable extension</a></H3>
+<H3><a name="Php_nn1_1">32.1.1 Building a loadable extension</a></H3>
 
 
 <p>
@@ -134,13 +143,24 @@ least work for Linux though):
         gcc -shared example_wrap.o example.o -o example.so
 </pre></div>
 
-<H3><a name="Php_nn1_3">31.1.2 Using PHP Extensions</a></H3>
+<H3><a name="Php_nn1_3">32.1.2 Using PHP Extensions</a></H3>
 
 
 <p>
 To test the extension from a PHP script, you first need to tell PHP to
-load it.  To do this, add a line like this to the <tt>[PHP]</tt> section of
-<tt>php.ini</tt>:
+load it.  The recommended (and simplest!) way to do this is to copy it to
+PHP's default extension directory and add a line like this to the
+<tt>[PHP]</tt> section of <tt>php.ini</tt>:
+</p>
+
+<div class="code"><pre>
+        extension=modulename
+</pre></div>
+
+<p>
+If the module is not in PHP's default extension directory, you also need to
+specify the path, in which case you'll also need to deal with platform-specific
+naming - for example, on Linux:
 </p>
 
 <div class="code"><pre>
@@ -148,41 +168,35 @@ load it.  To do this, add a line like this to the <tt>[PHP]</tt> section of
 </pre></div>
 
 <p>
-If the module is in PHP's default extension directory, you can omit the path.
+but on Microsoft Windows you'd need to use:
 </p>
 
+<div class="code"><pre>
+        extension=/path/to/php_modulename.dll
+</pre></div>
+
 <p>
-For some SAPIs (for example, the CLI SAPI) you can instead use the
-<a href="https://www.php.net/manual/en/function.dl.php">dl() function</a> to load
-an extension at run time, by adding a line like this to the start of each
+If you're using the PHP CLI SAPI it's possible (but not recommended) to use the
+<a href="https://www.php.net/manual/en/function.dl.php">dl() function</a> to
+load an extension at run time, by adding a line like this to the start of each
 PHP script which uses your extension:
 </p>
 
 <div class="code"><pre>
-        dl("/path/to/modulename.so"); // Load the module
+        dl("modulename"); // Load the module
 </pre></div>
 
 <p>
-But note that <tt>dl()</tt> isn't supported when running PHP through a
-webserver - you'll need to use <tt>extension</tt> in <tt>php.ini</tt> as
-described above.
+Again, if the module isn't in PHP's default extension directory you'll also
+need to specify the path and deal with that varying by platform.
 </p>
 
 <p>
-The PHP module which SWIG generates will also attempt to do the <tt>dl()</tt>
-call for you if the extension isn't already loaded:
+For security reasons PHP no longer supports <tt>dl()</tt> when running PHP
+through a webserver, so this isn't an option there.
 </p>
 
-<div class="code"><pre>
-        include("example.php");
-</pre></div>
-
-<p>
-This PHP module also defines the PHP classes for the wrapped API, so you'll
-almost certainly want to include it anyway.
-</p>
-
-<H2><a name="Php_nn2">31.2 Basic PHP interface</a></H2>
+<H2><a name="Php_nn2">32.2 Basic PHP interface</a></H2>
 
 
 <p>
@@ -194,7 +208,7 @@ SWIG doesn't have support for generating wrappers which make use of PHP's
 namespace feature.
 </p>
 
-<H3><a name="Php_nn2_1">31.2.1 Constants</a></H3>
+<H3><a name="Php_nn2_1">32.2.1 Constants</a></H3>
 
 
 <p>
@@ -219,61 +233,13 @@ you can access the constants in your PHP script like this,
 </p>
 
 <div class="code"><pre>
-include("example.php");
-
 echo "PI = " . PI . "\n";
-
 echo "E = " . E . "\n";
-
 </pre>
 </div>
 
-<p>
-There's one peculiarity of how constants work in PHP which it is useful
-to note (this is not specific to SWIG though) - if you try to use an undeclared
-constant, PHP will emit a warning (or a notice in PHP 7.1 and earlier) and then
-expand the constant to a string version of the constant's name.  Unfortunately
-it is easy to miss the warning message if you're using PHP in a webserver as
-it will probably end up in error.log or similar.  Apparently this will throw
-an Error in a future version of PHP, but until then it's something to be
-aware of.
-</p>
 
-<p>
-For example,
-</p>
-
-<div class="code"><pre>
-%module example
-
-#define EASY_TO_MISPELL 0
-</pre>
-</div>
-
-<p>
-accessed incorrectly in PHP,
-</p>
-
-<div class="code">
-<pre>
-include("example.php");
-
-if(EASY_TO_MISPEL) {
-  ...
-} else {
-  ...
-}
-
-</pre>
-</div>
-
-<p>
-The mis-spelled constant will become the string 'EASY_TO_MISPEL', which
-is treated as true by the if test, when the value of the intended constant
-would be treated as false!
-</p>
-
-<H3><a name="Php_nn2_2">31.2.2 Global Variables</a></H3>
+<H3><a name="Php_nn2_2">32.2.2 Global Variables</a></H3>
 
 
 <p>
@@ -298,7 +264,6 @@ is accessed as follows:
 </p>
 
 <div class="code"><pre>
-include("example.php");
 print seki_get();
 seki_set( seki_get() * 2); # The C variable is now 4.
 print seki_get();
@@ -306,23 +271,24 @@ print seki_get();
 
 <p>
 SWIG supports global variables of all C datatypes including pointers
-and complex objects.  Additional types can be supported by using the
-<tt>varinit</tt> typemap.
+and complex objects.  To support additional types, you just need to
+supply the standard <tt>in</tt> and <tt>out</tt> typemaps, which get
+used because of the wrapping as <tt>_get()</tt> and <tt>_set()</tt>
+functions.
 </p>
 
 <p>
-SWIG honors the <tt>%immutable</tt> modifier by not generating code
-for the <tt>_set</tt> method.  This provides read-only access to the
-variable from the php script.  Attempting to access the <tt>_set</tt>
-method will result in a php fatal error because the function is
-undefined.
+SWIG honors the <tt>%immutable</tt> modifier by not generating a
+<tt>_set</tt> method (so attempting to call it will give a PHP fatal
+error).  A <tt>_get</tt> method is still generated so this provides read-only
+access to the variable from the PHP script.
 </p>
 
 <p>
 At this time SWIG does not support custom accessor methods.
 </p>
 
-<H3><a name="Php_nn2_3">31.2.3 Functions</a></H3>
+<H3><a name="Php_nn2_3">32.2.3 Functions</a></H3>
 
 
 <p>
@@ -342,13 +308,84 @@ Will be accessed in PHP like this :
 </p>
 
 <div class="code"><pre>
-include("example.php");
 $a = foo(2);
 $b = bar(3.5, -1.5);
 $c = bar(3.5);  # Use default argument for 2nd parameter
 
 </pre></div>
 
+<p>
+SWIG generates PHP type declarations for function parameters and return
+types for PHP 8 and later.
+</p>
+
+<p>
+You can control the generation of PHP type declarations using
+the "php:type" %feature.  This has three settings:
+</p>
+
+<ul>
+    <li> <p>If unset or set to "0" then no type declarations are generated, e.g.: <tt>%feature("php:type", "0");</tt>
+      </p>
+    </li>
+    <li> <p>If set to "1" then type declarations are generated for both parameters and return types, e.g.: <tt>%feature("php:type", "1");</tt>
+      </p></li>
+      <li> <p>The default setting is "compat", which is the same as "1" except no
+      return type declarations are generated for virtual methods for which
+      directors are enabled.  This provides better compatibility for PHP
+      subclasses of wrapped virtual methods in existing SWIG-generated bindings, e.g.: <tt>%feature("php:type", "compat");</tt>
+      </p></li>
+</ul>
+
+<p>
+If you have an existing PHP interface and are upgrading to SWIG &gt;= 4.1.0
+then the default "compat" setting should work well.
+</p>
+
+<p>
+If you're writing a new set of bindings and <b>only targeting PHP8 or newer</b>
+then enabling type declarations everywhere probably makes sense.  It will
+only actually make a difference if you enable directors and are wrapping C++
+classes with virtual methods, but doing it anyway means you won't forget to if
+the code you are wrapping later evolves to have such classes and methods.
+</p>
+
+<p>
+The type declaration information will make the generated source code and
+compiler extension module larger, so you might want to turn off type
+declarations if keeping these small is important to you.  If you find you
+need to turn off type declarations to fix a problem, please let us know
+via our github issue tracker.
+</p>
+
+<p>
+Note that being a SWIG feature this can be specified globally (like above) or
+per class, per method, etc.  See the <a
+href="Customization.html#Customization_features">%feature directives</a>
+section for full details of how to control at a fine-grained level.
+</p>
+
+<p>
+The PHP type information is specified via a "phptype" attribute on "in" and
+"out" typemaps, and these have been added for all the typemaps we supply for
+PHP.  We don't currently support this for "argout" templates, but probably
+will in a future version.
+</p>
+
+<p>
+If you have written custom SWIG typemaps for PHP and want to add PHP type
+declarations, then the syntax is very like how you'd specify the type in
+PHP code, e.g. <tt>%typemap(in, phptype="int|string|Foo")</tt> means the
+typemap accepts a PHP int or string or an object of class Foo,
+<tt>%typemap(in, phptype="?int")</tt> means a PHP int or NULL, etc.
+As well as the standard PHP type declaration types, SWIG also understands the
+special type "SWIGTYPE" as an entry in phptype, which means the PHP type
+corresponding to the type that this typemap matched on - for a object this
+will give you the PHP class for the object, and for a pointer to a non-class
+type it will give you the name of the PHP class SWIG created for that
+pointer type.
+</p>
+
 <!-- This isn't correct for 1.3.30 and needs rewriting to reflect reality
 <p>
 Because PHP is a dynamically typed language, the default typemaps
@@ -375,7 +412,7 @@ print $s;      # The value of $s was not changed.
 -->
 
 
-<H3><a name="Php_nn2_4">31.2.4 Overloading</a></H3>
+<H3><a name="Php_nn2_4">32.2.4 Overloading</a></H3>
 
 
 <p>
@@ -430,12 +467,15 @@ taking the integer argument.
 </p>
 -->
 
-<H3><a name="Php_nn2_5">31.2.5 Pointers and References</a></H3>
+<H3><a name="Php_nn2_5">32.2.5 Pointers and References</a></H3>
 
 
 <p>
-Pointers to C/C++ objects are represented
-as PHP resources, rather like MySQL connection handles.
+Since SWIG 4.1.0, SWIG wraps C/C++ classes directly with PHP objects.
+Pointers to other types are also wrapped as PHP objects - mostly this is an
+implementation detail, but it's visible from PHP via <tt>is_object()</tt> and
+similar.  In earlier SWIG versions, PHP resources were used to wrap both
+classes and pointers to other types.
 </p>
 
 <p>
@@ -467,8 +507,6 @@ This will result in the following usage in PHP:
 <div class="code"><pre>
 &lt;?php
 
-include("example.php");
-
 $in1=copy_intp(3);
 $in2=copy_intp(5);
 $result=new_intp();
@@ -476,7 +514,6 @@ $result=new_intp();
 add( $in1, $in2, $result );
 
 echo "The sum " . intp_value($in1) . " + " . intp_value($in2) . " = " . intp_value( $result) . "\n";
-?&gt;
 </pre></div>
 
 <p>
@@ -501,14 +538,11 @@ This will result in the following usage in PHP:
 <div class="code"><pre>
 &lt;?php
 
-include("example.php");
-
 $in1 = 3;
 $in2 = 5;
 $result= add($in1, $in2);  # Note using variables for the input is unnecessary.
 
 echo "The sum $in1 + $in2 = $result\n";
-?&gt;
 </pre></div>
 
 <p>
@@ -539,15 +573,12 @@ This will result in the following usage in PHP:
 <div class="code"><pre>
 &lt;?php
 
-include("example.php");
-
 $in1 = 3;
 $in2 = 5;
 $result = 0;
 add($in1, $in2, $result);
 
 echo "The sum $in1 + $in2 = $result\n";
-?&gt;
 </pre></div>
 
 <p>
@@ -568,15 +599,14 @@ PHP in a number of ways: by using <tt>unset</tt> on an existing
 variable, or assigning <tt>NULL</tt> to a variable.
 </p>
 
-<H3><a name="Php_nn2_6">31.2.6 Structures and C++ classes</a></H3>
+<H3><a name="Php_nn2_6">32.2.6 Structures and C++ classes</a></H3>
 
 
 <p>
-SWIG defaults to wrapping C++ structs and classes with PHP classes - this
-is done by generating a PHP wrapper script which defines proxy classes
-which calls a set of flat functions which actually wrap the C++ class.
-You can disable this wrapper layer by passing the command-line option
-"-noproxy" in which case you'll just get the flat functions.
+SWIG wraps C++ structs and classes with PHP classes.
+Since SWIG 4.1.0, this is done entirely via PHP's C API - earlier SWIG
+versions generated a PHP wrapper script which defined proxy classes
+which called a set of flat functions which actually wrapped the C++ class.
 </p>
 
 <p>
@@ -605,7 +635,6 @@ Would be used in the following way from PHP:
 
 <div class="code"><pre>
 &lt;?php
-  require "vector.php";
 
   $v = new Vector();
   $v-&gt;x = 3;
@@ -622,53 +651,34 @@ Would be used in the following way from PHP:
   $c-&gt;im = 0;
 
   # $c destructor called when $c goes out of scope.
-?&gt;
 </pre></div>
 
 <p>
 Member variables and methods are accessed using the <tt>-&gt;</tt> operator.
 </p>
 
-<H4><a name="Php_nn2_6_1">31.2.6.1 Using -noproxy</a></H4>
+<H4><a name="Php_nn2_6_1">32.2.6.1 Using -noproxy</a></H4>
 
 
 <p>
-The <tt>-noproxy</tt> option flattens the object structure and
-generates collections of named functions (these are the functions
-which the PHP class wrappers call).  The above example results
-in the following PHP functions:
+SWIG/PHP used to support a <tt>-noproxy</tt> option to flatten the class
+structure and generate collections of named flat functions.  This is no
+longer supported as of SWIG 4.1.0.
 </p>
 
-<div class="code"><pre>
-new_Vector();
-Vector_x_set($obj, $d);
-Vector_x_get($obj);
-Vector_y_set($obj, $d);
-Vector_y_get($obj);
-Vector_z_set($obj, $d);
-Vector_z_get($obj);
-Vector_magnitude($obj);
-new_Complex();
-Complex_re_set($obj, $d);
-Complex_re_get($obj);
-Complex_im_set($obj, $d);
-Complex_im_get($obj);
-</pre></div>
-
-<H4><a name="Php_nn2_6_2">31.2.6.2 Constructors and Destructors</a></H4>
+<H4><a name="Php_nn2_6_2">32.2.6.2 Constructors and Destructors</a></H4>
 
 
 <p>
-The constructor is called when <tt>new Object()</tt> (or
-<tt>new_Object()</tt> if using <tt>-noproxy</tt>) is used to create an
+The constructor is called when <tt>new Object()</tt> is used to create an
 instance of the object. If multiple constructors are defined for an
 object, function overloading will be used to determine which
 constructor to execute.
 </p>
 
 <p>
-Because PHP uses reference counting to manage resources, simple
-assignment of one variable to another such as:
+Because PHP uses reference counting, simple assignment of one variable to
+another such as:
 </p>
 
 <div class="code"><pre>
@@ -696,7 +706,7 @@ the programmer can either reassign the variable or call
 <tt>unset($v)</tt>
 </p>
 
-<H4><a name="Php_nn2_6_3">31.2.6.3 Static Member Variables</a></H4>
+<H4><a name="Php_nn2_6_3">32.2.6.3 Static Member Variables</a></H4>
 
 
 <p>
@@ -721,8 +731,6 @@ would be accessed in PHP as,
 </p>
 
 <div class="code"><pre>
-include("example.php");
-
 echo "There have now been " . Ko::threats() . " threats\n";
 
 </pre></div>
@@ -739,7 +747,7 @@ Ko::threats(10);
 echo "There have now been " . Ko::threats() . " threats\n";
 
 </pre></div>
-<H4><a name="Php_nn2_6_4">31.2.6.4 Static Member Functions</a></H4>
+<H4><a name="Php_nn2_6_4">32.2.6.4 Static Member Functions</a></H4>
 
 
 <p>
@@ -754,14 +762,16 @@ class Ko {
 };
 </pre></div>
 
-would be executed in PHP as,
+<p>
+would be executed in PHP as
+</p>
+
 <div class="code"><pre>
-include("example.php");
 Ko::threats();
 </pre></div>
 
 
-<H4><a name="Php_nn2_6_5">31.2.6.5 Specifying Implemented Interfaces</a></H4>
+<H4><a name="Php_nn2_6_5">32.2.6.5 Specifying Implemented Interfaces</a></H4>
 
 
 <p>
@@ -772,20 +782,73 @@ so:
 </p>
 
 <div class="code"><pre>
-%typemap("phpinterfaces") MyIterator "Iterator";
+%typemap("phpinterfaces") MyIterator "Iterator"
 </pre></div>
 
 <p>
 If there are multiple interfaces, just list them separated by commas.
 </p>
 
-<H3><a name="Php_nn2_7">31.2.7 PHP Pragmas, Startup and Shutdown code</a></H3>
+
+<H4><a name="Php_nn2_6_6">32.2.6.6 Dynamic Properties</a></H4>
 
 
 <p>
-To place PHP code in the generated "example.php" file one can use the
-<b>code</b> pragma. The code is inserted after loading the shared
-object.
+Historically PHP has supported dynamic class properties and SWIG
+has implemented them too (because we implement the magic <tt>__get()</tt>,
+<tt>__set()</tt> and <tt>__isset()</tt> methods we need to include explicit
+handling).
+</p>
+
+<p>
+PHP 8.2 <a
+href="https://wiki.php.net/rfc/deprecate_dynamic_properties">deprecates
+dynamic class properties</a> - initially they'll warn, and apparently they'll
+not work by default in PHP 9.0.
+</p>
+
+<p>
+In PHP code dynamic properties can be enabled for a class by
+marking that class with the attribute <tt>#[AllowDynamicProperties]</tt>.
+</p>
+
+<p>
+To follow this PHP change, as of SWIG 4.1.0 you now need enable dynamic
+properties for any classes you want to support them.  To enable for class
+<tt>Foo</tt>:
+</p>
+
+<div class="code"><pre>
+%feature("php:allowdynamicproperties", 1) Foo;
+</pre></div>
+
+<p>
+or to enable them for all wrapped classes:
+</p>
+
+<div class="code"><pre>
+%feature("php:allowdynamicproperties", 1);
+</pre></div>
+
+<p>
+Note that unknown features are ignored, so you can add use these
+unconditionally in your interface file and it'll work with older SWIG too.
+</p>
+
+<p>
+There was a bug in SWIG 4.1.0 where setting this feature to any value enabled
+it - SWIG 4.2.0 fixed this and you can now set it to 0 to turn it off (for
+example, you might want to enabled it for everything and then selectively turn
+it off for specific classes).
+</p>
+
+
+<H3><a name="Php_nn2_7">32.2.7 PHP Pragmas, Startup and Shutdown code</a></H3>
+
+
+<p>
+You can get SWIG to generate an "example.php" file by specifying
+the code to put in it using the <b>code</b> pragma.
 </p>
 
 <div class="code"><pre>
@@ -876,14 +939,14 @@ The <tt>%rinit</tt> and <tt>%rshutdown</tt> statements are very similar but inse
 into the request init (PHP_RINIT_FUNCTION) and request shutdown (PHP_RSHUTDOWN_FUNCTION) code respectively.
 </p>
 
-<H2><a name="Php_nn3">31.3 Cross language polymorphism</a></H2>
+<H2><a name="Php_nn3">32.3 Cross language polymorphism</a></H2>
 
 
 <p>
 Proxy classes provide a more natural, object-oriented way to access
 extension classes. As described above, each proxy instance has an
 associated C++ instance, and method calls to the proxy are passed to the
-C++ instance transparently via C wrapper functions.
+C++ instance transparently.
 </p>
 
 <p>
@@ -911,7 +974,7 @@ wrapper functions takes care of all the cross-language method routing
 transparently.
 </p>
 
-<H3><a name="Php_nn3_1">31.3.1 Enabling directors</a></H3>
+<H3><a name="Php_nn3_1">32.3.1 Enabling directors</a></H3>
 
 
 <p>
@@ -989,8 +1052,6 @@ then at the PHP side you can define
 
 <div class="targetlang">
 <pre>
-require("mymodule.php");
-
 class MyFoo extends Foo {
   function one() {
     print "one from php\n";
@@ -1000,7 +1061,7 @@ class MyFoo extends Foo {
 </div>
 
 
-<H3><a name="Php_nn3_2">31.3.2 Director classes</a></H3>
+<H3><a name="Php_nn3_2">32.3.2 Director classes</a></H3>
 
 
  
@@ -1012,8 +1073,8 @@ that derives from both the class in question and a special
 <tt>Swig::Director</tt> class. These new classes, referred to as director
 classes, can be loosely thought of as the C++ equivalent of the PHP
 proxy classes. The director classes store a pointer to their underlying
-PHP object.  Indeed, this is quite similar to the "_cPtr" and "thisown"
-members of the PHP proxy classes.
+PHP object.  Indeed, this is quite similar to <tt>struct swig_object_wrapper</tt>
+which is used to implement the PHP proxy classes.
 </p>
 
 <p>
@@ -1068,12 +1129,12 @@ infinite loop.
 <p>
 One more point needs to be made about the relationship between director
 classes and proxy classes. When a proxy class instance is created in
-PHP, SWIG creates an instance of the original C++ class and assigns it
-to <tt>-&gt;_cPtr</tt>. This is exactly what happens without directors
-and is true even if directors are enabled for the particular class in
-question. When a class <i>derived</i> from a proxy class is created,
-however, SWIG then creates an instance of the corresponding C++ director
-class. The reason for this difference is that user-defined subclasses
+PHP, SWIG creates an instance of the original C++ class and stores it
+in the <tt>struct swig_object_wrapper</tt>. This is true whether or not
+directors are enabled for the particular class in question. However
+when a class <i>derived</i> from a proxy class is created, SWIG instead
+creates an instance of the corresponding C++ director class.
+The reason for this difference is that user-defined subclasses
 may override or extend methods of the original class, so the director
 class is needed to route calls to these methods correctly. For
 unmodified proxy classes, all methods are ultimately implemented in C++
@@ -1081,7 +1142,7 @@ so there is no need for the extra overhead involved with routing the
 calls through PHP.
 </p>
 
-<H3><a name="Php_nn3_3">31.3.3 Ownership and object destruction</a></H3>
+<H3><a name="Php_nn3_3">32.3.3 Ownership and object destruction</a></H3>
 
 
 <p>
@@ -1137,7 +1198,7 @@ In this example, we are assuming that FooContainer will take care of
 deleting all the Foo pointers it contains at some point.
 </p>
 
-<H3><a name="Php_nn3_4">31.3.4 Exception unrolling</a></H3>
+<H3><a name="Php_nn3_4">32.3.4 Exception unrolling</a></H3>
 
 
 <p>
@@ -1161,13 +1222,32 @@ should suffice in most cases:
 <div class="code">
 <pre>
 %feature("director:except") {
-  if ($error == FAILURE) {
+#if SWIG_VERSION &gt;= 0x040100
+  if ($error != NULL)
+#else
+  if ($error == FAILURE)
+#endif
+  {
     throw Swig::DirectorMethodException();
   }
 }
 </pre>
 </div>
 
+<p>
+If you only need to support SWIG &gt;= 4.1.0, you can just use the
+<tt>($error != NULL)</tt> condition.
+</p>
+
+<p>
+In SWIG 4.1.0, <tt>$error</tt> was changed in the SWIG/PHP director
+implementation to make it work more like how it does for other languages.
+Previously, <tt>$error</tt> didn't actually indicate an exception, but instead
+was only set to <tt>FAILURE</tt> if there was a problem calling the PHP method.
+Now <tt>$error</tt> indicates if the PHP method threw a PHP exception, and
+directorout typemaps for PHP no longer need to be gated by <tt>if (EG(exception))</tt>.
+</p>
+
 <p>
 This code will check the PHP error state after each method call from a
 director into PHP, and throw a C++ exception if an error occurred.  This
@@ -1204,7 +1284,7 @@ Swig::DirectorMethodException is thrown, PHP will register the exception
 as soon as the C wrapper function returns.
 </p>
 
-<H3><a name="Php_nn3_5">31.3.5 Overhead and code bloat</a></H3>
+<H3><a name="Php_nn3_5">32.3.5 Overhead and code bloat</a></H3>
 
 
 <p>
@@ -1237,7 +1317,7 @@ optimized by selectively enabling director methods (using the %feature
 directive) for only those methods that are likely to be extended in PHP.
 </p>
 
-<H3><a name="Php_nn3_6">31.3.6 Typemaps</a></H3>
+<H3><a name="Php_nn3_6">32.3.6 Typemaps</a></H3>
 
 
 <p>
@@ -1251,7 +1331,7 @@ need to be supported.
 </p>
 
 
-<H3><a name="Php_nn3_7">31.3.7 Miscellaneous</a></H3>
+<H3><a name="Php_nn3_7">32.3.7 Miscellaneous</a></H3>
 
 
 <p> Director typemaps for STL classes are mostly in place, and hence you

Doc/Manual/Pike.html

@@ -1,246 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<title>SWIG and Pike</title>
-<link rel="stylesheet" type="text/css" href="style.css">
-<meta http-equiv="content-type" content="text/html; charset=UTF-8">
-</head>
-
-<body bgcolor="#ffffff">
-<H1><a name="Pike">37 SWIG and Pike</a></H1>
-<!-- INDEX -->
-<div class="sectiontoc">
-<ul>
-<li><a href="#Pike_nn2">Preliminaries</a>
-<ul>
-<li><a href="#Pike_nn3">Running SWIG</a>
-<li><a href="#Pike_nn4">Getting the right header files</a>
-<li><a href="#Pike_nn5">Using your module</a>
-</ul>
-<li><a href="#Pike_nn6">Basic C/C++ Mapping</a>
-<ul>
-<li><a href="#Pike_nn7">Modules</a>
-<li><a href="#Pike_nn8">Functions</a>
-<li><a href="#Pike_nn9">Global variables</a>
-<li><a href="#Pike_nn10">Constants and enumerated types</a>
-<li><a href="#Pike_nn11">Constructors and Destructors</a>
-<li><a href="#Pike_nn12">Static Members</a>
-</ul>
-</ul>
-</div>
-<!-- INDEX -->
-
-
-
-<p>
-This chapter describes SWIG support for Pike. As of this writing, the
-SWIG  Pike module is still under development and is not considered
-ready for prime  time. The Pike module is being developed against the
-Pike 7.4.10 release  and may not be compatible with previous versions
-of Pike.
-</p>
-
-<p>
-This chapter covers most SWIG features, but certain low-level details
-are  covered in less depth than in earlier chapters.  At the very
-least, make sure you read the "<a href="SWIG.html#SWIG">SWIG Basics</a>"
-chapter.<br>
-</p>
-
-<H2><a name="Pike_nn2">37.1 Preliminaries</a></H2>
-
-
-<H3><a name="Pike_nn3">37.1.1 Running SWIG</a></H3>
-
-
-<p>
-Suppose that you defined a SWIG module such as the following:
-</p>
-
-<div class="code">
-  <pre>%module example<br><br>%{<br>#include "example.h"<br>%}<br><br>int fact(int n);<br></pre>
-</div>
-
-<p>
-To build a C extension module for Pike, run SWIG using the <tt>-pike</tt> option :
-</p>
-
-<div class="code">
-  <pre>$ <b>swig -pike example.i</b><br></pre>
-</div>
-
-<p>
-If you're building a C++ extension, be sure to add the <tt>-c++</tt> option:
-</p>
-
-<div class="code">
-  <pre>$ <b>swig -c++ -pike example.i</b><br></pre>
-</div>
-
-<p>
-This creates a single source file named <tt>example_wrap.c</tt> (or <tt>example_wrap.cxx</tt>, if you
-ran SWIG with the <tt>-c++</tt> option).
-The SWIG-generated source file contains the low-level wrappers that need
-to be compiled and linked with the rest of your C/C++ application to
-create an extension module.
-</p>
-
-<p>
-The name of the wrapper file is derived from the name of the input
-file.  For example, if the input file is <tt>example.i</tt>, the name
-of the wrapper file is <tt>example_wrap.c</tt>. To change this, you
-can use the <tt>-o</tt> option:
-</p>
-
-<div class="code">
-  <pre>$ <b>swig -pike -o pseudonym.c example.i</b><br></pre>
-</div>
-<H3><a name="Pike_nn4">37.1.2 Getting the right header files</a></H3>
-
-
-<p>
-In order to compile the C/C++ wrappers, the compiler needs to know the
-path to the Pike header files. These files are usually contained in a
-directory such as
-</p>
-
-<div class="code">
-  <pre>/usr/local/pike/7.4.10/include/pike<br></pre>
-</div>
-
-<p>
-There doesn't seem to be any way to get Pike itself to reveal the
-location of these files, so you may need to hunt around for them.
-You're looking for files with the names <tt>global.h</tt>, <tt>program.h</tt>
-and so on.
-</p>
-
-<H3><a name="Pike_nn5">37.1.3 Using your module</a></H3>
-
-
-<p>
-To use your module, simply use Pike's <tt>import</tt> statement:
-</p>
-
-<div class="code"><pre>
-$ <b>pike</b>
-Pike v7.4 release 10 running Hilfe v3.5 (Incremental Pike Frontend)
-&gt; <b>import example;</b>
-&gt; <b>fact(4);</b>
-(1) Result: 24
-</pre></div>
-
-<H2><a name="Pike_nn6">37.2 Basic C/C++ Mapping</a></H2>
-
-
-<H3><a name="Pike_nn7">37.2.1 Modules</a></H3>
-
-
-<p>
-All of the code for a given SWIG module is wrapped into a single Pike
-module. Since the name of the shared library that implements your
-module ultimately determines the module's name (as far as Pike is
-concerned), SWIG's <tt>%module</tt> directive doesn't really have any
-significance.
-</p>
-
-<H3><a name="Pike_nn8">37.2.2 Functions</a></H3>
-
-
-<p>
-Global functions are wrapped as new Pike built-in functions. For
-example,
-</p>
-
-<div class="code"><pre>
-%module example
-
-int fact(int n);
-</pre></div>
-
-<p>
-creates a new built-in function <tt>example.fact(n)</tt> that works
-exactly as you'd expect it to:
-</p>
-
-<div class="code"><pre>
-&gt; <b>import example;</b>
-&gt; <b>fact(4);</b>
-(1) Result: 24
-</pre></div>
-
-<H3><a name="Pike_nn9">37.2.3 Global variables</a></H3>
-
-
-<p>
-Global variables are currently wrapped as a pair of functions, one to get
-the current value of the variable and another to set it. For example, the
-declaration
-</p>
-
-<div class="code"><pre>
-%module example
-
-double Foo;
-</pre></div>
-
-<p>
-will result in two functions, <tt>Foo_get()</tt> and <tt>Foo_set()</tt>:
-</p>
-
-<div class="code"><pre>
-&gt; <b>import example;</b>
-&gt; <b>Foo_get();</b>
-(1) Result: 3.000000
-&gt; <b>Foo_set(3.14159);</b>
-(2) Result: 0
-&gt; <b>Foo_get();</b>
-(3) Result: 3.141590
-</pre></div>
-
-<H3><a name="Pike_nn10">37.2.4 Constants and enumerated types</a></H3>
-
-
-<p>
-Enumerated types in C/C++ declarations are wrapped as Pike constants,
-not as Pike enums.
-</p>
-
-<H3><a name="Pike_nn11">37.2.5 Constructors and Destructors</a></H3>
-
-
-<p>
-Constructors are wrapped as <tt>create()</tt> methods, and destructors are
-wrapped as <tt>destroy()</tt> methods, for Pike classes.
-</p>
-
-<H3><a name="Pike_nn12">37.2.6 Static Members</a></H3>
-
-
-<p>
-Since Pike doesn't support static methods or data for Pike classes, static
-member functions in your C++ classes are wrapped as regular functions and
-static member variables are wrapped as pairs of functions (one to get the
-value of the static member variable, and another to set it). The names of
-these functions are prepended with the name of the class.
-For example, given this C++ class declaration:
-</p>
-
-<div class="code"><pre>
-class Shape
-{
-public:
-  static void print();
-  static int nshapes;
-};
-</pre></div>
-
-<p>
-SWIG will generate a <tt>Shape_print()</tt> method that invokes the static
-<tt>Shape::print()</tt> member function, as well as a pair of methods,
-<tt>Shape_nshapes_get()</tt> and <tt>Shape_nshapes_set()</tt>, to get and set
-the value of <tt>Shape::nshapes</tt>.
-</p>
-
-</body>
-</html>

Doc/Manual/Preface.html

@@ -80,7 +80,7 @@ Some target languages were disabled as part of a clean up and others were given
 <p>
 The LICENSE file shipped with SWIG in the top level directory contains the SWIG license.
 For further insight into the license including the license of SWIG's output code, please visit
-the SWIG legal page - <a href="http://www.swig.org/legal.html">http://www.swig.org/legal.html</a>.
+the SWIG legal page - <a href="https://www.swig.org/legal.html">https://www.swig.org/legal.html</a>.
 </p>
 
 <p>
@@ -98,7 +98,7 @@ The official location of SWIG related material is
 </p>
 
 <div class="shell"><pre>
-<a href="http://www.swig.org">http://www.swig.org</a>
+<a href="https://www.swig.org">https://www.swig.org</a>
 </pre></div>
 
 <p>
@@ -111,7 +111,7 @@ You can also subscribe to the swig-user mailing list by visiting the page
 </p>
 
 <div class="shell"><pre>
-<a href="http://www.swig.org/mail.html">http://www.swig.org/mail.html</a>
+<a href="https://www.swig.org/mail.html">https://www.swig.org/mail.html</a>
 </pre></div>
 
 <p>
@@ -125,7 +125,7 @@ about this can be obtained at:
 </p>
 
 <div class="shell"><pre>
-<a href="http://www.swig.org/svn.html">SWIG Bleeding Edge</a>
+<a href="https://www.swig.org/svn.html">SWIG Bleeding Edge</a>
 </pre></div>
 
 
@@ -231,7 +231,7 @@ detailed release notes for previous releases and summary release notes from SWIG
 SWIG is an unfunded project that would not be possible without the
 contributions of many people working in their spare time. 
 If you have benefitted from using SWIG, please consider
-<a href="http://www.swig.org/donate.html">Donating to SWIG</a> to keep development going.
+<a href="https://www.swig.org/donate.html">Donating to SWIG</a> to keep development going.
 There have been a large varied number of people
 who have made contributions at all levels over time. Contributors
 are mentioned either in the COPYRIGHT file or CHANGES files shipped with SWIG or in submitted bugs.
@@ -244,8 +244,8 @@ are mentioned either in the COPYRIGHT file or CHANGES files shipped with SWIG or
 Although every attempt has been made to make SWIG bug-free, we are also trying
 to make feature improvements that may introduce bugs.
 To report a bug, either send mail to the SWIG developer
-list at the <a href="http://www.swig.org/mail.html">swig-devel mailing list</a> or report a bug
-at the <a href="http://www.swig.org/bugs.html">SWIG bug tracker</a>. In your report, be as specific as
+list at the <a href="https://www.swig.org/mail.html">swig-devel mailing list</a> or report a bug
+at the <a href="https://www.swig.org/bugs.html">SWIG bug tracker</a>. In your report, be as specific as
 possible, including (if applicable), error messages, tracebacks (if a
 core dump occurred), corresponding portions of the SWIG interface file
 used, and any important pieces of the SWIG generated wrapper code.  We
@@ -273,20 +273,20 @@ the main SWIG distribution. There is no need to download anything else.
 These installation instructions are for using the distributed tarball,
 for example, <tt>swig-3.0.8.tar.gz</tt>.
 If you wish to build and install from source on Github, extra steps are required.
-Please see the <a href="http://swig.org/svn.html">Bleeding Edge</a> page on the SWIG website.
+Please see the <a href="https://swig.org/svn.html">Bleeding Edge</a> page on the SWIG website.
 </p>
 
 <p>
-You must use <a href="http://www.gnu.org/software/make/">GNU make</a> to build and install SWIG.
+You must use <a href="https://www.gnu.org/software/make/">GNU make</a> to build and install SWIG.
 </p>
 
 <p>
-<a href="http://www.pcre.org/">PCRE</a>
+<a href="https://www.pcre.org/">PCRE2</a>
 needs to be installed on your system to build SWIG, in particular
-pcre-config must be available. If you have PCRE headers and libraries but not
-pcre-config itself or, alternatively, wish to override the compiler or linker
-flags returned by pcre-config, you may set PCRE_LIBS and PCRE_CFLAGS variables
-to be used instead. And if you don't have PCRE at all, the configure script
+pcre2-config must be available. If you have PCRE2 headers and libraries but not
+pcre2-config itself or, alternatively, wish to override the compiler or linker
+flags returned by pcre2-config, you may set PCRE2_LIBS and PCRE2_CFLAGS variables
+to be used instead. And if you don't have PCRE2 at all, the configure script
 will provide instructions for obtaining it.
 </p>
 
@@ -357,7 +357,7 @@ Note:
 If you checked the code out via Git, you will have to run <tt>./autogen.sh</tt>
 before <tt>./configure</tt>.  In addition, a full build of SWIG requires
 a number of packages to be installed.  Full instructions at
-<a href="http://www.swig.org/svn.html">SWIG bleeding edge</a>.
+<a href="https://www.swig.org/svn.html">SWIG bleeding edge</a>.
 </li>
 </ul>
 

Doc/Manual/Preprocessor.html

@@ -7,7 +7,7 @@
 </head>
 
 <body bgcolor="#ffffff">
-<H1><a name="Preprocessor">10 Preprocessing</a></H1>
+<H1><a name="Preprocessor">11 Preprocessing</a></H1>
 <!-- INDEX -->
 <div class="sectiontoc">
 <ul>
@@ -38,7 +38,7 @@ However, a number of modifications and enhancements have been made.  This
 chapter describes some of these modifications.
 </p>
 
-<H2><a name="Preprocessor_nn2">10.1 File inclusion</a></H2>
+<H2><a name="Preprocessor_nn2">11.1 File inclusion</a></H2>
 
 
 <p>
@@ -48,7 +48,7 @@ like this:
 
 <div class="code">
 <pre>
-%include "pointer.i"
+%include "cpointer.i"
 </pre>
 </div>
 
@@ -64,7 +64,7 @@ By default, the <tt>#include</tt> is ignored unless you run SWIG with the
 is that you often don't want SWIG to try and wrap everything included
 in standard header system headers and auxiliary files.
 
-<H2><a name="Preprocessor_nn3">10.2 File imports</a></H2>
+<H2><a name="Preprocessor_nn3">11.2 File imports</a></H2>
 
 
 <p>
@@ -93,14 +93,29 @@ The <tt>-importall</tt> directive tells SWIG to follow all <tt>#include</tt> sta
 as imports.    This might be useful if you want to extract type definitions from system 
 header files without generating any wrappers.
 
-<H2><a name="Preprocessor_condition_compilation">10.3 Conditional Compilation</a></H2>
+<H2><a name="Preprocessor_condition_compilation">11.3 Conditional Compilation</a></H2>
 
 
 <p>
 SWIG fully supports the use of <tt>#if</tt>, <tt>#ifdef</tt>,
 <tt>#ifndef</tt>, <tt>#else</tt>, <tt>#endif</tt> to conditionally
-include parts of an interface.  The following symbols are predefined
-by SWIG when it is parsing the interface:
+include parts of an interface.
+</p>
+
+<p>
+SWIG's preprocessor conditionals support the standard C/C++ preprocessor
+integer expressions.  As a SWIG-specific extension, string equality and
+inequality tests are also supported, for example:
+</p>
+
+<div class="code">
+<pre>
+#if defined __cplusplus &amp;&amp; (#__VA_ARGS__ != "" || #TYPE == "void")
+</pre>
+</div>
+
+<p>
+The following symbols are predefined by SWIG when it is parsing the interface:
 </p>
 
 <div class="code"><pre>
@@ -117,13 +132,14 @@ SWIGJAVA                        Defined when using Java
 SWIGJAVASCRIPT                  Defined when using Javascript
 SWIG_JAVASCRIPT_JSC             Defined when using Javascript with -jsc
 SWIG_JAVASCRIPT_V8              Defined when using Javascript with -v8 or -node
+SWIG_JAVASCRIPT_NAPI            Defined when using Javascript with -napi
 SWIGLUA                         Defined when using Lua
 SWIGMZSCHEME                    Defined when using Mzscheme
 SWIGOCAML                       Defined when using OCaml
 SWIGOCTAVE                      Defined when using Octave
 SWIGPERL                        Defined when using Perl
 SWIGPHP                         Defined when using PHP (any version)
-SWIGPHP7                        Defined when using PHP7
+SWIGPHP7                        Defined when using PHP 7 or later (with a compatible C API)
 SWIGPYTHON                      Defined when using Python
 SWIGR                           Defined when using R
 SWIGRUBY                        Defined when using Ruby
@@ -132,6 +148,14 @@ SWIGTCL                         Defined when using Tcl
 SWIGXML                         Defined when using XML
 </pre></div>
 
+<p>
+SWIG also defines <tt>SWIG_VERSION</tt> and a target language macro in
+the generated wrapper file (since SWIG 4.1.0 - in older versions these
+were defined for some target languages but this wasn't consistent).  Best
+practice is to use SWIG-time conditional checks because that results in smaller
+generated wrapper sources.
+</p>
+
 <p>
 In addition, SWIG defines the following set of standard C/C++ macros:
 </p>
@@ -140,11 +164,44 @@ In addition, SWIG defines the following set of standard C/C++ macros:
 <pre>
 __LINE__                        Current line number
 __FILE__                        Current file name
-__STDC__                        Defined to indicate ISO C
-__cplusplus                     Defined when -c++ option used
+__STDC__                        Defined to indicate ISO C/C++
+__cplusplus                     Defined when -c++ option used, value controlled by <tt>-std=c++NN</tt>
+__STDC_VERSION__                May be defined when -c++ option is not used, value controlled by <tt>-std=cNN</tt>
 </pre>
 </div>
 
+<p>
+Since SWIG 4.2.0, <tt>__STDC__</tt> is defined to <tt>1</tt> to match
+the behaviour of ISO C/C++ compilers.  Before this SWIG defined it to
+have an empty value.
+</p>
+
+<p>
+Since SWIG 4.2.0, <tt>__cplusplus</tt> is defined to <tt>199711L</tt>
+(the value for C++98) by default. Before this SWIG always defined it to have
+the <b>value</b> <tt>__cplusplus</tt>.
+</p>
+
+<p>
+Since SWIG 4.2.0, SWIG supports command line options <tt>-std=cNN</tt> and
+<tt>-std=c++NN</tt> to specify the C/C++ standards version.  The only effect of
+these options is to set appropriate values for <tt>__STDC_VERSION__</tt> and
+<tt>__cplusplus</tt> respectively, which is useful if you're wrapping
+headers which have preprocessor checks based on their values.
+</p>
+
+<p>
+If your code requires these macros to be set to a version of the standard
+that is not a final official version, or one that SWIG is not yet aware of,
+you can simply redefine the appropriate macro to an alternative value at the
+top of your interface file, for example:
+</p>
+
+<div class="code"><pre>
+#undef __cplusplus
+#define __cplusplus 202211L
+</pre></div>
+
 <p>
 The following are language specific symbols that might be defined:
 </p>
@@ -154,7 +211,6 @@ SWIG_D_VERSION                  Unsigned integer target version when using D
 SWIGGO_CGO                      Defined when using Go for cgo
 SWIGGO_GCCGO                    Defined when using Go for gccgo
 SWIGGO_INTGO_SIZE               Size of the Go type int when using Go (32 or 64)
-SWIGPYTHON_PY3                  Defined when using Python with -py3
 SWIGPYTHON_BUILTIN              Defined when using Python with -builtin
 SWIG_RUBY_AUTORENAME            Defined when using Ruby with -autorename
 </pre></div>
@@ -165,7 +221,7 @@ way in which an interface is generated or to mix SWIG directives with
 C code.
 </p>
 
-<H2><a name="Preprocessor_nn5">10.4 Macro Expansion</a></H2>
+<H2><a name="Preprocessor_nn5">11.4 Macro Expansion</a></H2>
 
 
 <p>
@@ -175,15 +231,15 @@ is also used to try and detect constants.  Therefore, if you have something like
 
 <div class="code">
 <pre>
-#ifndef _FOO_H 1
-#define _FOO_H 1
+#ifndef FOO_H 1
+#define FOO_H 1
 ...
 #endif
 </pre>
 </div>
 
 <p>
-you may get some extra constants such as <tt>_FOO_H</tt> showing up in the scripting interface.
+you may get some extra constants such as <tt>FOO_H</tt> showing up in the scripting interface.
 </p>
 
 <p>
@@ -220,7 +276,7 @@ like <tt>#x</tt>.  This is a non-standard SWIG extension.
 </li>
 </ul>
 
-<H2><a name="Preprocessor_nn6">10.5 SWIG Macros</a></H2>
+<H2><a name="Preprocessor_nn6">11.5 SWIG Macros</a></H2>
 
 
 <p>
@@ -266,7 +322,7 @@ many of SWIG's advanced features and libraries are built using this mechanism (s
 support).
 </p>
 
-<H2><a name="Preprocessor_nn7">10.6 C99 and GNU Extensions</a></H2>
+<H2><a name="Preprocessor_nn7">11.6 C99 and GNU Extensions</a></H2>
 
 
 <p>
@@ -322,14 +378,14 @@ interface building.   However, they are used internally to implement a number of
 SWIG directives and are provided to make SWIG more compatible with C99 code.
 </p>
 
-<H2><a name="Preprocessor_delimiters">10.7 Preprocessing and delimiters</a></H2>
+<H2><a name="Preprocessor_delimiters">11.7 Preprocessing and delimiters</a></H2>
 
 
 <p>
 The preprocessor handles { }, " " and %{ %} delimiters differently.
 </p>
 
-<H3><a name="Preprocessor_nn8">10.7.1 Preprocessing and %{ ... %} &amp; " ... " delimiters</a></H3>
+<H3><a name="Preprocessor_nn8">11.7.1 Preprocessing and %{ ... %} &amp; " ... " delimiters</a></H3>
 
 
 <p>
@@ -354,7 +410,7 @@ the contents of the <tt>%{ ... %}</tt> block are copied without
 modification to the output (including all preprocessor directives).
 </p>
 
-<H3><a name="Preprocessor_nn9">10.7.2 Preprocessing and { ... } delimiters</a></H3>
+<H3><a name="Preprocessor_nn9">11.7.2 Preprocessing and { ... } delimiters</a></H3>
 
 
 <p>
@@ -396,7 +452,7 @@ to actually go into the wrapper file, prefix the preprocessor directives with <t
 SWIG will strip the extra <tt>%</tt> and leave the preprocessor directive in the code.
 </p>
 
-<H2><a name="Preprocessor_typemap_delimiters">10.8 Preprocessor and Typemaps</a></H2>
+<H2><a name="Preprocessor_typemap_delimiters">11.8 Preprocessor and Typemaps</a></H2>
 
 
 <p>
@@ -467,7 +523,7 @@ would generate
 </div>
 
 
-<H2><a name="Preprocessor_nn10">10.9 Viewing preprocessor output</a></H2>
+<H2><a name="Preprocessor_nn10">11.9 Viewing preprocessor output</a></H2>
 
 
 <p>
@@ -477,7 +533,7 @@ Instead the results after the preprocessor has run are displayed.
 This might be useful as an aid to debugging and viewing the results of macro expansions.
 </p>
 
-<H2><a name="Preprocessor_warning_error">10.10 The #error and #warning directives</a></H2>
+<H2><a name="Preprocessor_warning_error">11.10 The #error and #warning directives</a></H2>
 
 
 <p>

Doc/Manual/R.html

@@ -7,7 +7,7 @@
 </head>
 
 <body bgcolor="#ffffff">
-<H1><a name="R">33 SWIG and R</a></H1>
+<H1><a name="R">34 SWIG and R</a></H1>
 <!-- INDEX -->
 <div class="sectiontoc">
 <ul>
@@ -30,7 +30,7 @@
 <p>
 R is a GPL'ed open source statistical and plotting environment.
 Information about R can be found at <a
-href="http://www.r-project.org/">www.r-project.org</a>.
+href="https://www.r-project.org/">www.r-project.org</a>.
 </p>
 
 <p>
@@ -39,11 +39,11 @@ compile and run an R interface to QuantLib running on Mandriva Linux
 with gcc. They are also used to create the SimpleITK R package, which
 runs on Linux and MacOS. SWIG is used to create all wrapper
 interfaces
-to <a href="http://http://www.simpleitk.org/">SimpleITK</a>.  The R
+to <a href="https://www.simpleitk.org/">SimpleITK</a>.  The R
 bindings also work on Microsoft Windows using Visual C++.
 </p>
 
-<H2><a name="R_nn2">33.1 Bugs</a></H2>
+<H2><a name="R_nn2">34.1 Bugs</a></H2>
 
 
 <p>
@@ -57,7 +57,7 @@ Currently the following features are not implemented or broken:
 <li>C Array wrappings
 </ul>
 
-<H2><a name="R_nn3">33.2 Using R and SWIG</a></H2>
+<H2><a name="R_nn3">34.2 Using R and SWIG</a></H2>
 
 
 <p>
@@ -147,7 +147,7 @@ Error in .Call("R_swig_fact", s_arg1, as.logical(.copy), PACKAGE = "example") :
 <li>Make sure the architecture of the shared library(x64 for instance), matches the architecture of the R program you want to load your shared library into
 </ul>
 
-<H2><a name="R_nn4">33.3 Precompiling large R files</a></H2>
+<H2><a name="R_nn4">34.3 Precompiling large R files</a></H2>
 
 
 <p>
@@ -172,7 +172,7 @@ There is no need to precompile large R files if the SWIG-generated code is being
 in an R package. The package infrastructure provides this service during package installation.
 </p>
 
-<H2><a name="R_nn5">33.4 General policy</a></H2>
+<H2><a name="R_nn5">34.4 General policy</a></H2>
 
 
 <p>
@@ -181,7 +181,7 @@ wrapping over the underlying functions and rely on the R type system
 to provide R syntax.
 </p>
 
-<H2><a name="R_language_conventions">33.5 Language conventions</a></H2>
+<H2><a name="R_language_conventions">34.5 Language conventions</a></H2>
 
 
 <p>
@@ -190,13 +190,13 @@ and [ are overloaded to allow for R syntax (one based indices and
 slices)
 </p>
 
-<H2><a name="R_nn6">33.6 C++ classes</a></H2>
+<H2><a name="R_nn6">34.6 C++ classes</a></H2>
 
 
 <p>
 Wrapping of C++ classes for R works quite well. R has a special
 type, known as an external reference, that can be used as a pointer
-to arbitary things, including C++ classes. The proxy layers generated
+to arbitrary things, including C++ classes. The proxy layers generated
 for other classes are not required.
 </p>
 
@@ -217,7 +217,7 @@ The R interface has the following capabilities:
 <li> Variable accessors are automatically generated and called via the $, [, [[, $&lt;-,  [&lt;-, [[&lt;- operators.
 </ul>
 
-<H3><a name="R_class_examples">33.6.1 Examples</a></H3>
+<H3><a name="R_class_examples">34.6.1 Examples</a></H3>
 
 
 <p>
@@ -265,7 +265,7 @@ v2$Axles
 [1] 4
 v1$Available
 [1] FALSE
-# Set availabilty
+# Set availability
 v1$Available &lt;- TRUE
 v1$Available
 [1] TRUE
@@ -310,7 +310,7 @@ defined "_p_Vehicle"
 The names in the <tt>accessorFuns</tt> list correspond to class methods while names in the <tt>vaccessors</tt> section
 correspond to variables that may be modified.
 </p>
-<H2><a name="R_nn7">33.7 Enumerations</a></H2>
+<H2><a name="R_nn7">34.7 Enumerations</a></H2>
 
 
 <p>
@@ -321,7 +321,7 @@ and forth between integers.
 
 <p>
 The details of enumeration names and contents are stored in hidden R
-environments, which are named according the the enumeration name - for
+environments, which are named according to the enumeration name - for
 example, an enumeration colour:
 </p>
 

Doc/Manual/Ruby.html

@@ -8,7 +8,7 @@
 
 <body bgcolor="#ffffff">
 
-<H1><a name="Ruby">34 SWIG and Ruby</a></H1>
+<H1><a name="Ruby">35 SWIG and Ruby</a></H1>
 <!-- INDEX -->
 <div class="sectiontoc">
 <ul>
@@ -149,10 +149,10 @@
 
 <p>This chapter describes SWIG's support of Ruby.</p>
 
-<H2><a name="Ruby_nn2">34.1 Preliminaries</a></H2>
+<H2><a name="Ruby_nn2">35.1 Preliminaries</a></H2>
 
 
-<p> SWIG 4.0 is known to work with Ruby versions 1.9 and later.
+<p> SWIG 4.2 is known to work with Ruby versions 2.0 and later.
 Given the choice, you should use the latest stable version of Ruby. You
 should also determine if your system supports shared libraries and
 dynamic loading. SWIG will work with or without dynamic loading, but
@@ -164,7 +164,7 @@ read the "<a href="SWIG.html#SWIG">SWIG Basics</a>"
 chapter. It is also assumed that the reader has a basic understanding
 of Ruby. </p>
 
-<H3><a name="Ruby_nn3">34.1.1 Running SWIG</a></H3>
+<H3><a name="Ruby_nn3">35.1.1 Running SWIG</a></H3>
 
 
 <p> To build a Ruby module, run SWIG using the <tt>-ruby</tt>
@@ -188,7 +188,7 @@ if compiling a C++ extension) that contains all of the code needed to
 build a Ruby extension module. To finish building the module, you need
 to compile this file and link it with the rest of your program. </p>
 
-<H3><a name="Ruby_nn4">34.1.2 Getting the right header files</a></H3>
+<H3><a name="Ruby_nn4">35.1.2 Getting the right header files</a></H3>
 
 
 <p> In order to compile the wrapper code, the compiler needs the <tt>ruby.h</tt>
@@ -202,7 +202,7 @@ the compiler options needed to compile the code is to ask Ruby itself:</p>
 </pre>
 </div>
 
-<H3><a name="Ruby_nn5">34.1.3 Compiling a dynamic module</a></H3>
+<H3><a name="Ruby_nn5">35.1.3 Compiling a dynamic module</a></H3>
 
 
 <p> Ruby extension modules are typically compiled into shared
@@ -275,7 +275,7 @@ manual pages for your compiler and linker to determine the correct set
 of options. You might also check the <a href="https://github.com/swig/swig/wiki">SWIG Wiki</a>
 for additional information. </p>
 
-<H3><a name="Ruby_nn6">34.1.4 Using your module</a></H3>
+<H3><a name="Ruby_nn6">35.1.4 Using your module</a></H3>
 
 
 <p> Ruby <i>module</i> names must be capitalized,
@@ -305,7 +305,7 @@ begins with: </p>
 <p> will result in an extension module using the feature name
 "example" and Ruby module name "Example". </p>
 
-<H3><a name="Ruby_nn7">34.1.5 Static linking</a></H3>
+<H3><a name="Ruby_nn7">35.1.5 Static linking</a></H3>
 
 
 <p> An alternative approach to dynamic linking is to rebuild the
@@ -320,7 +320,7 @@ finding the Ruby source, adding an entry to the <tt>ext/Setup</tt>
 file, adding your directory to the list of extensions in the file, and
 finally rebuilding Ruby. </p>
 
-<H3><a name="Ruby_nn8">34.1.6 Compilation of C++ extensions</a></H3>
+<H3><a name="Ruby_nn8">35.1.6 Compilation of C++ extensions</a></H3>
 
 
 <p> On most machines, C++ extension modules should be linked
@@ -352,7 +352,7 @@ $libs = append_library($libs, "supc++")
 create_makefile('example')</pre>
 </div>
 
-<H2><a name="Ruby_nn9">34.2 Building Ruby Extensions under Windows 95/NT</a></H2>
+<H2><a name="Ruby_nn9">35.2 Building Ruby Extensions under Windows 95/NT</a></H2>
 
 
 <p> Building a SWIG extension to Ruby under Windows 95/NT is
@@ -377,7 +377,7 @@ order to build extensions, you may need to download the source
 distribution to the Ruby package, as you will need the Ruby header
 files. </p>
 
-<H3><a name="Ruby_nn10">34.2.1 Running SWIG from Developer Studio</a></H3>
+<H3><a name="Ruby_nn10">35.2.1 Running SWIG from Developer Studio</a></H3>
 
 
 <p> If you are developing your application within Microsoft
@@ -441,13 +441,13 @@ Foo = 3.0
 </pre>
 </div>
 
-<H2><a name="Ruby_nn11">34.3 The Ruby-to-C/C++ Mapping</a></H2>
+<H2><a name="Ruby_nn11">35.3 The Ruby-to-C/C++ Mapping</a></H2>
 
 
 <p> This section describes the basics of how SWIG maps C or C++
 declarations in your SWIG interface files to Ruby constructs. </p>
 
-<H3><a name="Ruby_nn12">34.3.1 Modules</a></H3>
+<H3><a name="Ruby_nn12">35.3.1 Modules</a></H3>
 
 
 <p> The SWIG <tt>%module</tt> directive specifies
@@ -519,7 +519,7 @@ option to wrap everything into the global module, take care that the
 names of your constants, classes and methods don't conflict with any of
 Ruby's built-in names. </p>
 
-<H3><a name="Ruby_nn13">34.3.2 Functions</a></H3>
+<H3><a name="Ruby_nn13">35.3.2 Functions</a></H3>
 
 
 <p> Global functions are wrapped as Ruby module methods. For
@@ -553,7 +553,7 @@ irb(main):002:0&gt; <b>Example.fact(4)</b>
 24</pre>
 </div>
 
-<H3><a name="Ruby_nn14">34.3.3 Variable Linking</a></H3>
+<H3><a name="Ruby_nn14">35.3.3 Variable Linking</a></H3>
 
 
 <p> C/C++ global variables are wrapped as a pair of singleton
@@ -633,7 +633,7 @@ irb(main):004:0&gt; <b>$Variable2</b>
 41.2</pre>
 </div>
 
-<H3><a name="Ruby_nn15">34.3.4 Constants</a></H3>
+<H3><a name="Ruby_nn15">35.3.4 Constants</a></H3>
 
 
 <p> C/C++ constants are wrapped as module constants initialized
@@ -661,7 +661,7 @@ irb(main):002:0&gt; <b>Example::PI</b>
 3.14159</pre>
 </div>
 
-<H3><a name="Ruby_nn16">34.3.5 Pointers</a></H3>
+<H3><a name="Ruby_nn16">35.3.5 Pointers</a></H3>
 
 
 <p> "Opaque" pointers to arbitrary C/C++ types (i.e. types that
@@ -685,7 +685,7 @@ returns an instance of an internally generated Ruby class: </p>
 <p> A <tt>NULL</tt> pointer is always represented by
 the Ruby <tt>nil</tt> object. </p>
 
-<H3><a name="Ruby_nn17">34.3.6 Structures</a></H3>
+<H3><a name="Ruby_nn17">35.3.6 Structures</a></H3>
 
 
 <p> C/C++ structs are wrapped as Ruby classes, with accessor
@@ -790,7 +790,7 @@ void Bar_f_set(Bar *b, Foo *val) {
 }</pre>
 </div>
 
-<H3><a name="Ruby_nn18">34.3.7 C++ classes</a></H3>
+<H3><a name="Ruby_nn18">35.3.7 C++ classes</a></H3>
 
 
 <p> Like structs, C++ classes are wrapped by creating a new Ruby
@@ -845,7 +845,7 @@ Ale
 3</pre>
 </div>
 
-<H3><a name="Ruby_nn19">34.3.8 C++ Inheritance</a></H3>
+<H3><a name="Ruby_nn19">35.3.8 C++ Inheritance</a></H3>
 
 
 <p> The SWIG type-checker is fully aware of C++ inheritance.
@@ -998,7 +998,7 @@ inherit from both <tt>Base1</tt> and <tt>Base2</tt>
 (i.e. they exhibit <a href="http://c2.com/cgi/wiki?DuckTyping">"Duck
 Typing"</a>). </p>
 
-<H3><a name="Ruby_nn20">34.3.9 C++ Overloaded Functions</a></H3>
+<H3><a name="Ruby_nn20">35.3.9 C++ Overloaded Functions</a></H3>
 
 
 <p> C++ overloaded functions, methods, and constructors are
@@ -1088,7 +1088,7 @@ arises--in this case, the first declaration takes precedence. </p>
 <p>Please refer to the <a href="SWIGPlus.html#SWIGPlus">"SWIG
 and C++"</a> chapter for more information about overloading. </p>
 
-<H3><a name="Ruby_nn21">34.3.10 C++ Operators</a></H3>
+<H3><a name="Ruby_nn21">35.3.10 C++ Operators</a></H3>
 
 
 <p> For the most part, overloaded operators are handled
@@ -1130,7 +1130,7 @@ c = Example.add_complex(a, b)</pre>
 is discussed in the <a href="#Ruby_operator_overloading">section
 on operator overloading</a>. </p>
 
-<H3><a name="Ruby_nn22">34.3.11 C++ namespaces</a></H3>
+<H3><a name="Ruby_nn22">35.3.11 C++ namespaces</a></H3>
 
 
 <p> SWIG is aware of C++ namespaces, but namespace names do not
@@ -1187,7 +1187,7 @@ and create extension modules for each namespace separately. If your
 program utilizes thousands of small deeply nested namespaces each with
 identical symbol names, well, then you get what you deserve. </p>
 
-<H3><a name="Ruby_nn23">34.3.12 C++ templates</a></H3>
+<H3><a name="Ruby_nn23">35.3.12 C++ templates</a></H3>
 
 
 <p> C++ templates don't present a huge problem for SWIG. However,
@@ -1229,7 +1229,7 @@ irb(main):004:0&gt; <b>p.second</b>
 4</pre>
 </div>
 
-<H3><a name="Ruby_nn23_1">34.3.13 C++ Standard Template Library (STL)</a></H3>
+<H3><a name="Ruby_nn23_1">35.3.13 C++ Standard Template Library (STL)</a></H3>
 
 
 <p> On a related note, the standard SWIG library contains a
@@ -1322,7 +1322,7 @@ puts v
 shown in these examples. More details can be found in the <a href="SWIGPlus.html#SWIGPlus">SWIG and C++</a>
 chapter.</p>
 
-<H3><a name="Ruby_C_STL_Functors">34.3.14 C++ STL Functors</a></H3>
+<H3><a name="Ruby_C_STL_Functors">35.3.14 C++ STL Functors</a></H3>
 
 
 <p>Some containers in the STL allow you to modify their default
@@ -1383,7 +1383,7 @@ b
 </pre>
 </div>
 
-<H3><a name="Ruby_C_Iterators">34.3.15 C++ STL Iterators</a></H3>
+<H3><a name="Ruby_C_Iterators">35.3.15 C++ STL Iterators</a></H3>
 
 
 <p>The STL is well known for the use of iterators. There
@@ -1466,10 +1466,10 @@ i
 
 <p>If you'd rather have STL classes without any iterators, you should define <tt>-DSWIG_NO_EXPORT_ITERATOR_METHODS</tt> when running swig.</p>
 
-<H3><a name="Ruby_nn24">34.3.16 C++ Smart Pointers</a></H3>
+<H3><a name="Ruby_nn24">35.3.16 C++ Smart Pointers</a></H3>
 
 
-<H4><a name="Ruby_smart_pointers_shared_ptr">34.3.16.1 The shared_ptr Smart Pointer</a></H4>
+<H4><a name="Ruby_smart_pointers_shared_ptr">35.3.16.1 The shared_ptr Smart Pointer</a></H4>
 
 
 <p>
@@ -1480,7 +1480,7 @@ in the <a href="Library.html#Library_std_shared_ptr">shared_ptr smart pointer</a
 </p>
 
 
-<H4><a name="Ruby_smart_pointers_generic">34.3.16.2 Generic Smart Pointers</a></H4>
+<H4><a name="Ruby_smart_pointers_generic">35.3.16.2 Generic Smart Pointers</a></H4>
 
 
 <p> In certain C++ programs, it is common to use classes that
@@ -1545,7 +1545,7 @@ method. For example: </p>
 <pre>irb(main):004:0&gt; <b>f = p.__deref__()</b> # Returns underlying Foo *</pre>
 </div>
 
-<H3><a name="Ruby_nn25">34.3.17 Cross-Language Polymorphism</a></H3>
+<H3><a name="Ruby_nn25">35.3.17 Cross-Language Polymorphism</a></H3>
 
 
 <p> SWIG's Ruby module supports cross-language polymorphism
@@ -1554,7 +1554,7 @@ module. Rather than duplicate the information presented in the <a href="Python.h
 section just notes the differences that you need to be aware of when
 using this feature with Ruby. </p>
 
-<H4><a name="Ruby_nn26">34.3.17.1 Exception Unrolling</a></H4>
+<H4><a name="Ruby_nn26">35.3.17.1 Exception Unrolling</a></H4>
 
 
 <p> Whenever a C++ director class routes one of its virtual
@@ -1577,7 +1577,7 @@ method is "wrapped" using the <tt>rb_rescue2()</tt>
 function from Ruby's C API. If any Ruby exception is raised, it will be
 caught here and a C++ exception is raised in its place. </p>
 
-<H2><a name="Ruby_nn27">34.4 Naming</a></H2>
+<H2><a name="Ruby_nn27">35.4 Naming</a></H2>
 
 
 <p>Ruby has several common naming conventions. Constants are
@@ -1615,7 +1615,7 @@ generated
 by SWIG, it is turned off by default in SWIG 1.3.28. However, it is
 planned to become the default option in future releases.</p>
 
-<H3><a name="Ruby_nn28">34.4.1 Defining Aliases</a></H3>
+<H3><a name="Ruby_nn28">35.4.1 Defining Aliases</a></H3>
 
 
 <p> It's a fairly common practice in the Ruby built-ins and
@@ -1685,7 +1685,7 @@ matching rules used for other kinds of features apply (see the chapter
 on <a href="Customization.html#Customization">"Customization
 Features"</a>) for more details).</p>
 
-<H3><a name="Ruby_nn29">34.4.2 Predicate Methods</a></H3>
+<H3><a name="Ruby_nn29">35.4.2 Predicate Methods</a></H3>
 
 
 <p> Ruby methods that return a boolean value and end in a
@@ -1707,7 +1707,7 @@ For example: </p>
 <div class="code">
 <pre>%rename("is_it_safe?") is_it_safe();
 
-%typemap(out) int is_it_safe "$result = ($1 != 0) ? Qtrue : Qfalse;";
+%typemap(out) int is_it_safe "$result = ($1 != 0) ? Qtrue : Qfalse;"
 
 int is_it_safe();</pre>
 </div>
@@ -1734,7 +1734,7 @@ using SWIG's "features" mechanism and so the same name matching rules
 used for other kinds of features apply (see the chapter on <a href="Customization.html#Customization">"Customization
 Features"</a>) for more details). </p>
 
-<H3><a name="Ruby_nn30">34.4.3 Bang Methods</a></H3>
+<H3><a name="Ruby_nn30">35.4.3 Bang Methods</a></H3>
 
 
 <p> Ruby methods that modify an object in-place and end in an
@@ -1766,7 +1766,7 @@ using SWIG's "features" mechanism and so the same name matching rules
 used for other kinds of features apply (see the chapter on <a href="Customization.html#Customization">"Customization
 Features"</a>) for more details). </p>
 
-<H3><a name="Ruby_nn31">34.4.4 Getters and Setters</a></H3>
+<H3><a name="Ruby_nn31">35.4.4 Getters and Setters</a></H3>
 
 
 <p> Often times a C++ library will expose properties through
@@ -1801,7 +1801,7 @@ irb(main):003:0&gt; <b>puts foo.value</b></pre>
 %rename("value=") Foo::setValue(int value);</pre>
 </div>
 
-<H2><a name="Ruby_nn32">34.5 Input and output parameters</a></H2>
+<H2><a name="Ruby_nn32">35.5 Input and output parameters</a></H2>
 
 
 <p> A common problem in some C programs is handling parameters
@@ -1940,10 +1940,10 @@ void get_dimensions(Matrix *m, int *rows, int*columns);</pre>
 <pre>r, c = Example.get_dimensions(m)</pre>
 </div>
 
-<H2><a name="Ruby_nn33">34.6 Exception handling </a></H2>
+<H2><a name="Ruby_nn33">35.6 Exception handling </a></H2>
 
 
-<H3><a name="Ruby_nn34">34.6.1 Using the %exception directive </a></H3>
+<H3><a name="Ruby_nn34">35.6.1 Using the %exception directive </a></H3>
 
 
 <p>The SWIG <tt>%exception</tt> directive can be
@@ -2052,7 +2052,7 @@ methods and functions named <tt>getitem</tt> and <tt>setitem</tt>.
 limited to C++ exception handling. See the chapter on <a href="Customization.html#Customization">Customization
 Features</a> for more examples.</p>
 
-<H3><a name="Ruby_nn34_2">34.6.2 Handling Ruby Blocks </a></H3>
+<H3><a name="Ruby_nn34_2">35.6.2 Handling Ruby Blocks </a></H3>
 
 
 <p>One of the highlights of Ruby and most of its standard library
@@ -2119,7 +2119,7 @@ a special in typemap, like:</p>
 
 <p>For more information on typemaps, see <a href="#Ruby_nn37">Typemaps</a>.</p>
 
-<H3><a name="Ruby_nn35">34.6.3 Raising exceptions </a></H3>
+<H3><a name="Ruby_nn35">35.6.3 Raising exceptions </a></H3>
 
 
 <p>There are three ways to raise exceptions from C++ code to
@@ -2276,7 +2276,7 @@ function. The first argument passed to <tt>rb_raise()</tt>
 is the exception type. You can raise a custom exception type or one of
 the built-in Ruby exception types.</p>
 
-<H3><a name="Ruby_nn36">34.6.4 Exception classes </a></H3>
+<H3><a name="Ruby_nn36">35.6.4 Exception classes </a></H3>
 
 
 <p>Starting with SWIG 1.3.28, the Ruby module supports the <tt>%exceptionclass</tt>
@@ -2313,7 +2313,7 @@ end </pre>
 <p>For another example look at swig/Examples/ruby/exception_class.
 </p>
 
-<H2><a name="Ruby_nn37">34.7 Typemaps</a></H2>
+<H2><a name="Ruby_nn37">35.7 Typemaps</a></H2>
 
 
 <p> This section describes how you can modify SWIG's default
@@ -2328,7 +2328,7 @@ a required part of using SWIG---the default wrapping behavior is enough
 in most cases. Typemaps are only used if you want to change some aspect
 of the primitive C-Ruby interface.</p>
 
-<H3><a name="Ruby_nn38">34.7.1 What is a typemap?</a></H3>
+<H3><a name="Ruby_nn38">35.7.1 What is a typemap?</a></H3>
 
 
 <p> A typemap is nothing more than a code generation rule that is
@@ -2485,7 +2485,7 @@ to be used as follows (notice how the length parameter is omitted): </p>
 2</pre>
 </div>
 
-<H3><a name="Ruby_Typemap_scope">34.7.2 Typemap scope</a></H3>
+<H3><a name="Ruby_Typemap_scope">35.7.2 Typemap scope</a></H3>
 
 
 <p> Once defined, a typemap remains in effect for all of the
@@ -2531,7 +2531,7 @@ where the class itself is defined. For example:</p>
 };</pre>
 </div>
 
-<H3><a name="Ruby_Copying_a_typemap">34.7.3 Copying a typemap</a></H3>
+<H3><a name="Ruby_Copying_a_typemap">35.7.3 Copying a typemap</a></H3>
 
 
 <p> A typemap is copied by using assignment. For example:</p>
@@ -2573,7 +2573,7 @@ rules as for <tt>
 %apply (char *buf, int len) { (char *buffer, int size) }; // Multiple arguments</pre>
 </div>
 
-<H3><a name="Ruby_Deleting_a_typemap">34.7.4 Deleting a typemap</a></H3>
+<H3><a name="Ruby_Deleting_a_typemap">35.7.4 Deleting a typemap</a></H3>
 
 
 <p> A typemap can be deleted by simply defining no code. For
@@ -2598,7 +2598,7 @@ defined by typemaps, clearing a fundamental type like <tt>int</tt>
 will make that type unusable unless you also define a new set of
 typemaps immediately after the clear operation.</p>
 
-<H3><a name="Ruby_Placement_of_typemaps">34.7.5 Placement of typemaps</a></H3>
+<H3><a name="Ruby_Placement_of_typemaps">35.7.5 Placement of typemaps</a></H3>
 
 
 <p> Typemap declarations can be declared in the global scope,
@@ -2669,13 +2669,13 @@ In this example, this is done using the class declaration <tt>class
 string</tt>
 .</p>
 
-<H3><a name="Ruby_nn39">34.7.6 Ruby typemaps</a></H3>
+<H3><a name="Ruby_nn39">35.7.6 Ruby typemaps</a></H3>
 
 
 <p>The following list details all of the typemap methods that
 can be used by the Ruby module: </p>
 
-<H4><a name="Ruby_in_typemap">34.7.6.1 "in" typemap</a></H4>
+<H4><a name="Ruby_in_typemap">35.7.6.1 "in" typemap</a></H4>
 
 
 <p>Converts Ruby objects to input
@@ -2742,7 +2742,7 @@ arguments to be specified. For example:</p>
 
 <p> At this time, only zero or one arguments may be converted.</p>
 
-<H4><a name="Ruby_typecheck_typemap">34.7.6.2 "typecheck" typemap</a></H4>
+<H4><a name="Ruby_typecheck_typemap">35.7.6.2 "typecheck" typemap</a></H4>
 
 
 <p> The "typecheck" typemap is used to support overloaded
@@ -2764,7 +2764,7 @@ program uses overloaded methods, you should also define a collection of
 "typecheck" typemaps. More details about this follow in a later section
 on "Typemaps and Overloading."</p>
 
-<H4><a name="Ruby_out_typemap">34.7.6.3 "out" typemap</a></H4>
+<H4><a name="Ruby_out_typemap">35.7.6.3 "out" typemap</a></H4>
 
 
 <p>Converts return value of a C function
@@ -2815,7 +2815,7 @@ version of the C datatype matched by the typemap.</td>
 </table>
 </div>
 
-<H4><a name="Ruby_arginit_typemap">34.7.6.4 "arginit" typemap</a></H4>
+<H4><a name="Ruby_arginit_typemap">35.7.6.4 "arginit" typemap</a></H4>
 
 
 <p> The "arginit" typemap is used to set the initial value of a
@@ -2830,7 +2830,7 @@ applications. For example:</p>
 }</pre>
 </div>
 
-<H4><a name="Ruby_default_typemap">34.7.6.5 "default" typemap</a></H4>
+<H4><a name="Ruby_default_typemap">35.7.6.5 "default" typemap</a></H4>
 
 
 <p> The "default" typemap is used to turn an argument into a
@@ -2855,7 +2855,7 @@ arguments that follow must have default values. See the <a href="SWIG.html#SWIG_
 Default/optional arguments</a> section for further information on
 default argument wrapping.</p>
 
-<H4><a name="Ruby_check_typemap">34.7.6.6 "check" typemap</a></H4>
+<H4><a name="Ruby_check_typemap">35.7.6.6 "check" typemap</a></H4>
 
 
 <p> The "check" typemap is used to supply value checking code
@@ -2870,7 +2870,7 @@ arguments have been converted. For example:</p>
 }</pre>
 </div>
 
-<H4><a name="Ruby_argout_typemap_">34.7.6.7 "argout" typemap</a></H4>
+<H4><a name="Ruby_argout_typemap_">35.7.6.7 "argout" typemap</a></H4>
 
 
 <p> The "argout" typemap is used to return values from arguments.
@@ -2924,7 +2924,7 @@ some function like SWIG_Ruby_AppendOutput.</p>
 
 <p> See the <tt>typemaps.i</tt> library for examples.</p>
 
-<H4><a name="Ruby_freearg_typemap_">34.7.6.8 "freearg" typemap</a></H4>
+<H4><a name="Ruby_freearg_typemap_">35.7.6.8 "freearg" typemap</a></H4>
 
 
 <p> The "freearg" typemap is used to cleanup argument data. It is
@@ -2951,7 +2951,7 @@ This code is also placed into a special variable <tt>$cleanup</tt>
 that may be used in other typemaps whenever a wrapper function needs to
 abort prematurely.</p>
 
-<H4><a name="Ruby_newfree_typemap">34.7.6.9 "newfree" typemap</a></H4>
+<H4><a name="Ruby_newfree_typemap">35.7.6.9 "newfree" typemap</a></H4>
 
 
 <p> The "newfree" typemap is used in conjunction with the <tt>%newobject</tt>
@@ -2975,7 +2975,7 @@ string *foo();</pre>
 <p> See <a href="Customization.html#Customization_ownership">Object
 ownership and %newobject</a> for further details.</p>
 
-<H4><a name="Ruby_memberin_typemap">34.7.6.10 "memberin" typemap</a></H4>
+<H4><a name="Ruby_memberin_typemap">35.7.6.10 "memberin" typemap</a></H4>
 
 
 <p> The "memberin" typemap is used to copy data from<em> an
@@ -2993,21 +2993,21 @@ example:</p>
 already provides a default implementation for arrays, strings, and
 other objects.</p>
 
-<H4><a name="Ruby_varin_typemap">34.7.6.11 "varin" typemap</a></H4>
+<H4><a name="Ruby_varin_typemap">35.7.6.11 "varin" typemap</a></H4>
 
 
 <p> The "varin" typemap is used to convert objects in the target
 language to C for the purposes of assigning to a C/C++ global variable.
 This is implementation specific.</p>
 
-<H4><a name="Ruby_varout_typemap_">34.7.6.12 "varout" typemap</a></H4>
+<H4><a name="Ruby_varout_typemap_">35.7.6.12 "varout" typemap</a></H4>
 
 
 <p> The "varout" typemap is used to convert a C/C++ object to an
 object in the target language when reading a C/C++ global variable.
 This is implementation specific.</p>
 
-<H4><a name="Ruby_throws_typemap">34.7.6.13 "throws" typemap</a></H4>
+<H4><a name="Ruby_throws_typemap">35.7.6.13 "throws" typemap</a></H4>
 
 
 <p> The "throws" typemap is only used when SWIG parses a C++
@@ -3048,7 +3048,7 @@ specification yet they do throw exceptions, SWIG cannot know how to
 deal with them. For a neat way to handle these, see the <a href="Customization.html#Customization_exception">Exception
 handling with %exception</a> section.</p>
 
-<H4><a name="Ruby_directorin_typemap">34.7.6.14 directorin typemap</a></H4>
+<H4><a name="Ruby_directorin_typemap">35.7.6.14 directorin typemap</a></H4>
 
 
 <p>Converts C++ objects in director
@@ -3107,7 +3107,7 @@ referring to the class itself.</td>
 </table>
 </div>
 
-<H4><a name="Ruby_directorout_typemap">34.7.6.15 directorout typemap</a></H4>
+<H4><a name="Ruby_directorout_typemap">35.7.6.15 directorout typemap</a></H4>
 
 
 <p>Converts Ruby objects in director
@@ -3180,7 +3180,7 @@ exception.
 
 </p>
 
-<H4><a name="Ruby_directorargout_typemap">34.7.6.16 directorargout typemap</a></H4>
+<H4><a name="Ruby_directorargout_typemap">35.7.6.16 directorargout typemap</a></H4>
 
 
 <p>Output argument processing in director
@@ -3238,19 +3238,19 @@ referring to the instance of the class itself</td>
 </table>
 </div>
 
-<H4><a name="Ruby_ret_typemap">34.7.6.17 ret typemap</a></H4>
+<H4><a name="Ruby_ret_typemap">35.7.6.17 ret typemap</a></H4>
 
 
 <p>Cleanup of function return values
 </p>
 
-<H4><a name="Ruby_globalin_typemap">34.7.6.18 globalin typemap</a></H4>
+<H4><a name="Ruby_globalin_typemap">35.7.6.18 globalin typemap</a></H4>
 
 
 <p>Setting of C global variables
 </p>
 
-<H3><a name="Ruby_nn40">34.7.7 Typemap variables</a></H3>
+<H3><a name="Ruby_nn40">35.7.7 Typemap variables</a></H3>
 
 
 <p>
@@ -3300,7 +3300,7 @@ so that their values can be properly assigned. </div>
 <div class="indent">The Ruby name of the wrapper function
 being created. </div>
 
-<H3><a name="Ruby_nn41">34.7.8 Useful Functions</a></H3>
+<H3><a name="Ruby_nn41">35.7.8 Useful Functions</a></H3>
 
 
 <p> When you write a typemap, you usually have to work directly
@@ -3315,7 +3315,7 @@ stick to the swig functions instead of the native Ruby functions.
 That should help you avoid having to rewrite a lot of typemaps
 across multiple languages.</p>
 
-<H4><a name="Ruby_nn42">34.7.8.1 C Datatypes to Ruby Objects</a></H4>
+<H4><a name="Ruby_nn42">35.7.8.1 C Datatypes to Ruby Objects</a></H4>
 
 
 <div class="diagram">
@@ -3357,7 +3357,7 @@ SWIG_From_float(float)</td>
 </table>
 </div>
 
-<H4><a name="Ruby_nn43">34.7.8.2 Ruby Objects to C Datatypes</a></H4>
+<H4><a name="Ruby_nn43">35.7.8.2 Ruby Objects to C Datatypes</a></H4>
 
 
 <p>Here, while the Ruby versions return the value directly, the SWIG
@@ -3411,7 +3411,7 @@ versions do not, but return a status value to indicate success (<tt>SWIG_OK</tt>
     </tr>
     <tr>
       <td>char * StringValuePtr(String)</td>
-      <td>SWIG_AsCharPtrAndSize(VALUE, char*, size_t, int* alloc)</td>
+      <td>SWIG_AsCharPtrAndSize(VALUE, char**, size_t*, int* alloc)</td>
     </tr>
     <tr>
       <td>char * rb_str2cstr(String, int*length)</td>
@@ -3425,7 +3425,7 @@ versions do not, but return a status value to indicate success (<tt>SWIG_OK</tt>
 </table>
 </div>
 
-<H4><a name="Ruby_nn44">34.7.8.3 Macros for VALUE</a></H4>
+<H4><a name="Ruby_nn44">35.7.8.3 Macros for VALUE</a></H4>
 
 
 <p> <tt>RSTRING_LEN(str)</tt> </p>
@@ -3448,7 +3448,7 @@ versions do not, but return a status value to indicate success (<tt>SWIG_OK</tt>
 
 <div class="indent">pointer to array storage</div>
 
-<H4><a name="Ruby_nn45">34.7.8.4 Exceptions</a></H4>
+<H4><a name="Ruby_nn45">35.7.8.4 Exceptions</a></H4>
 
 
 <p> <tt>void rb_raise(VALUE exception, const char *fmt,
@@ -3527,7 +3527,7 @@ message to standard error if Ruby was invoked with the <tt>-w</tt>
 flag. The given format string <i>fmt</i> and remaining
 arguments are interpreted as with <tt>printf()</tt>. </div>
 
-<H4><a name="Ruby_nn46">34.7.8.5 Iterators</a></H4>
+<H4><a name="Ruby_nn46">35.7.8.5 Iterators</a></H4>
 
 
 <p> <tt>void rb_iter_break()</tt> </p>
@@ -3573,14 +3573,14 @@ VALUE), VALUE value)</tt></p>
 <div class="indent"> Equivalent to Ruby's <tt>throw</tt>.
 </div>
 
-<H3><a name="Ruby_nn47">34.7.9 Typemap Examples</a></H3>
+<H3><a name="Ruby_nn47">35.7.9 Typemap Examples</a></H3>
 
 
 <p> This section includes a few examples of typemaps. For more
 examples, you might look at the examples in the <tt>Example/ruby</tt>
 directory. </p>
 
-<H3><a name="Ruby_nn48">34.7.10 Converting a Ruby array to a char **</a></H3>
+<H3><a name="Ruby_nn48">35.7.10 Converting a Ruby array to a char **</a></H3>
 
 
 <p> A common problem in many C programs is the processing of
@@ -3645,7 +3645,7 @@ array. Since dynamic memory allocation is used to allocate memory for
 the array, the "freearg" typemap is used to later release this memory
 after the execution of the C function. </p>
 
-<H3><a name="Ruby_nn49">34.7.11 Collecting arguments in a hash</a></H3>
+<H3><a name="Ruby_nn49">35.7.11 Collecting arguments in a hash</a></H3>
 
 
 <p> Ruby's solution to the "keyword arguments" capability of some
@@ -3859,7 +3859,7 @@ memory leak. Fortunately, this typemap is a lot easier to write: </p>
 program that uses the extension, can be found in the <tt>Examples/ruby/hashargs</tt>
 directory of the SWIG distribution. </p>
 
-<H3><a name="Ruby_nn50">34.7.12 Pointer handling</a></H3>
+<H3><a name="Ruby_nn50">35.7.12 Pointer handling</a></H3>
 
 
 <p> Occasionally, it might be necessary to convert pointer values
@@ -3918,7 +3918,7 @@ For example: </p>
 }</pre>
 </div>
 
-<H4><a name="Ruby_nn51">34.7.12.1 Ruby Datatype Wrapping</a></H4>
+<H4><a name="Ruby_nn51">35.7.12.1 Ruby Datatype Wrapping</a></H4>
 
 
 <p> <tt>VALUE Data_Wrap_Struct(VALUE class, void
@@ -3945,7 +3945,7 @@ as above. </div>
 type <i>c-type</i> from the data object <i>obj</i>
 and assigns that pointer to <i>ptr</i>. </div>
 
-<H3><a name="Ruby_nn52">34.7.13 Example: STL Vector to Ruby Array</a></H3>
+<H3><a name="Ruby_nn52">35.7.13 Example: STL Vector to Ruby Array</a></H3>
 
 
 <p>Another use for macros and type maps is to create a Ruby array
@@ -4037,7 +4037,7 @@ STL with ruby, you are advised to use the standard swig STL library,
 which does much more than this. Refer to the section called
 the<a href="#Ruby_nn23_1"> C++ Standard Template Library</a>.
 
-<H2><a name="Ruby_nn65">34.8 Docstring Features</a></H2>
+<H2><a name="Ruby_nn65">35.8 Docstring Features</a></H2>
 
 
 <p>
@@ -4071,7 +4071,7 @@ generate ri documentation from a c wrap file, you could do:</p>
 $ rdoc -r file_wrap.c
 </pre></div>
 
-<H3><a name="Ruby_nn66">34.8.1 Module docstring</a></H3>
+<H3><a name="Ruby_nn66">35.8.1 Module docstring</a></H3>
 
 
 <p>
@@ -4101,7 +4101,7 @@ layout of controls on a panel, etc. to be loaded from an XML file."
 %module(docstring=DOCSTRING) xrc</pre>
 </div>
 
-<H3><a name="Ruby_nn67">34.8.2 %feature("autodoc")</a></H3>
+<H3><a name="Ruby_nn67">35.8.2 %feature("autodoc")</a></H3>
 
 
 <p>Since SWIG does know everything about the function it wraps,
@@ -4122,7 +4122,7 @@ several options for autodoc controlled by the value given to the
 feature, described below.
 </p>
 
-<H4><a name="Ruby_nn68">34.8.2.1 %feature("autodoc", "0")</a></H4>
+<H4><a name="Ruby_nn68">35.8.2.1 %feature("autodoc", "0")</a></H4>
 
 
 <p>
@@ -4146,7 +4146,7 @@ Then Ruby code like this will be generated:
   ...</pre>
 </div>
 
-<H4><a name="Ruby_autodoc1">34.8.2.2 %feature("autodoc", "1")</a></H4>
+<H4><a name="Ruby_autodoc1">35.8.2.2 %feature("autodoc", "1")</a></H4>
 
 
 <p>
@@ -4166,7 +4166,7 @@ this:
   ...</pre>
 </div>
 
-<H4><a name="Ruby_autodoc2">34.8.2.3 %feature("autodoc", "2")</a></H4>
+<H4><a name="Ruby_autodoc2">35.8.2.3 %feature("autodoc", "2")</a></H4>
 
 
 <p>
@@ -4178,7 +4178,7 @@ parameter types with the "2" option will result in Ruby code like
 this:
 </p>
 
-<H4><a name="Ruby_feature_autodoc3">34.8.2.4 %feature("autodoc", "3")</a></H4>
+<H4><a name="Ruby_feature_autodoc3">35.8.2.4 %feature("autodoc", "3")</a></H4>
 
 
 <p>
@@ -4199,7 +4199,7 @@ Parameters:
         bar - Bar</pre>
 </div>
 
-<H4><a name="Ruby_nn70">34.8.2.5 %feature("autodoc", "docstring")</a></H4>
+<H4><a name="Ruby_nn70">35.8.2.5 %feature("autodoc", "docstring")</a></H4>
 
 
 <p>
@@ -4215,7 +4215,7 @@ generated string. For example:
 void GetPosition(int* OUTPUT, int* OUTPUT);</pre>
 </div>
 
-<H3><a name="Ruby_nn71">34.8.3 %feature("docstring")</a></H3>
+<H3><a name="Ruby_nn71">35.8.3 %feature("docstring")</a></H3>
 
 
 <p>
@@ -4226,10 +4226,10 @@ docstring associated with classes, function or methods are output.
 If an item already has an autodoc string then it is combined with the
 docstring and they are output together. </p>
 
-<H2><a name="Ruby_nn53">34.9 Advanced Topics</a></H2>
+<H2><a name="Ruby_nn53">35.9 Advanced Topics</a></H2>
 
 
-<H3><a name="Ruby_operator_overloading">34.9.1 Operator overloading</a></H3>
+<H3><a name="Ruby_operator_overloading">35.9.1 Operator overloading</a></H3>
 
 
 <p> SWIG allows operator overloading with, by using the <tt>%extend</tt>
@@ -4410,7 +4410,7 @@ separate method for handling <i>inequality</i> since Ruby
 parses the expression <i>a != b</i> as <i>!(a == b)</i>.
 </p>
 
-<H3><a name="Ruby_nn55">34.9.2 Creating Multi-Module Packages</a></H3>
+<H3><a name="Ruby_nn55">35.9.2 Creating Multi-Module Packages</a></H3>
 
 
 <p> The chapter on <a href="Modules.html#Modules">Working
@@ -4536,7 +4536,7 @@ irb(main):005:0&gt; <b>c.getX()</b>
 5.0</pre>
 </div>
 
-<H3><a name="Ruby_nn56">34.9.3 Specifying Mixin Modules</a></H3>
+<H3><a name="Ruby_nn56">35.9.3 Specifying Mixin Modules</a></H3>
 
 
 <p> The Ruby language doesn't support multiple inheritance, but
@@ -4603,7 +4603,7 @@ matching rules used for other kinds of features apply (see the chapter
 on <a href="Customization.html#Customization">"Customization
 Features"</a>) for more details). </p>
 
-<H2><a name="Ruby_nn57">34.10 Memory Management</a></H2>
+<H2><a name="Ruby_nn57">35.10 Memory Management</a></H2>
 
 
 <p>One of the most common issues in generating SWIG bindings for
@@ -4626,7 +4626,7 @@ to C++ (or vice versa) depending on what function or methods are
 invoked. Clearly, developing a SWIG wrapper requires a thorough
 understanding of how the underlying library manages memory.</p>
 
-<H3><a name="Ruby_nn58">34.10.1 Mark and Sweep Garbage Collector </a></H3>
+<H3><a name="Ruby_nn58">35.10.1 Mark and Sweep Garbage Collector </a></H3>
 
 
 <p>Ruby uses a mark and sweep garbage collector. When the garbage
@@ -4657,7 +4657,7 @@ any memory has been allocated in creating the underlying C struct or
 C++ struct, then a "free" function must be defined that deallocates
 this memory. </p>
 
-<H3><a name="Ruby_nn59">34.10.2 Object Ownership</a></H3>
+<H3><a name="Ruby_nn59">35.10.2 Object Ownership</a></H3>
 
 
 <p>As described above, memory management depends on clearly
@@ -4802,7 +4802,7 @@ public:
 
 <p> This code can be seen in swig/examples/ruby/tracking.</p>
 
-<H3><a name="Ruby_nn60">34.10.3 Object Tracking</a></H3>
+<H3><a name="Ruby_nn60">35.10.3 Object Tracking</a></H3>
 
 
 <p>The remaining parts of this section will use the class library
@@ -5028,7 +5028,7 @@ However, if you implement your own free functions (see below) you may
 also have to call the <tt>SWIG_RubyRemoveTracking</tt> and <tt>RubyUnlinkObjects</tt>
 methods.</p>
 
-<H3><a name="Ruby_nn61">34.10.4 Mark Functions</a></H3>
+<H3><a name="Ruby_nn61">35.10.4 Mark Functions</a></H3>
 
 
 <p>With a bit more testing, we see that our class library still
@@ -5157,7 +5157,7 @@ irb(main):016:0&gt;</pre>
 
 <p>This code can be seen in swig/examples/ruby/mark_function.</p>
 
-<H3><a name="Ruby_nn62">34.10.5 Free Functions</a></H3>
+<H3><a name="Ruby_nn62">35.10.5 Free Functions</a></H3>
 
 
 <p>By default, SWIG creates a "free" function that is called when
@@ -5325,7 +5325,7 @@ been freed, and thus raises a runtime exception.</p>
 
 <p>This code can be seen in swig/examples/ruby/free_function.</p>
 
-<H3><a name="Ruby_nn63">34.10.6 Embedded Ruby and the C++ Stack</a></H3>
+<H3><a name="Ruby_nn63">35.10.6 Embedded Ruby and the C++ Stack</a></H3>
 
 
 <p>As has been said, the Ruby GC runs and marks objects before

Doc/Manual/SWIG.html

@@ -47,6 +47,7 @@
 <li><a href="#SWIG_rename_ignore">Renaming and ignoring declarations</a>
 <ul>
 <li><a href="#SWIG_nn29">Simple renaming of specific identifiers</a>
+<li><a href="#SWIG_ignore">Ignoring identifiers</a>
 <li><a href="#SWIG_advanced_renaming">Advanced renaming support</a>
 <li><a href="#SWIG_limiting_renaming">Limiting global renaming rules</a>
 <li><a href="#SWIG_chosen_unignore">Ignoring everything then wrapping a few selected symbols</a>
@@ -127,7 +128,7 @@ Supported Target Language Options
      -lua            - Generate Lua wrappers
      -octave         - Generate Octave wrappers
      -perl5          - Generate Perl 5 wrappers
-     -php7           - Generate PHP 7 wrappers
+     -php7           - Generate PHP 8 or later wrappers
      -python         - Generate Python wrappers
      -r              - Generate R (aka GNU S) wrappers
      -ruby           - Generate Ruby wrappers
@@ -154,6 +155,7 @@ General Options
      -debug-symbols  - Display target language symbols in the symbol tables
      -debug-csymbols - Display C symbols in the symbol tables
      -debug-lsymbols - Display target language layer symbols
+     -debug-quiet    - Display less parse tree node debug info when using other -debug options
      -debug-tags     - Display information about the tags found in the interface
      -debug-template - Display information for debugging templates
      -debug-top &lt;n&gt;  - Display entire parse tree at stages 1-4, &lt;n&gt; is a csv list of stages
@@ -163,7 +165,7 @@ General Options
      -debug-tmused   - Display typemaps used debugging information
      -directors      - Turn on director mode for all the classes, mainly for testing
      -dirprot        - Turn on wrapping of protected members for director classes (default)
-     -D&lt;symbol&gt;      - Define a symbol &lt;symbol&gt; (for conditional compilation)
+     -D&lt;symbol&gt;[=&lt;value&gt;] - Define symbol &lt;symbol&gt; (for conditional compilation)
      -E              - Preprocess only, does not generate wrapper code
      -external-runtime [file] - Export the SWIG runtime stack
      -fakeversion &lt;v&gt;- Make SWIG fake the program version number to &lt;v&gt;
@@ -183,7 +185,6 @@ General Options
      -includeall     - Follow all #include statements
      -l&lt;ifile&gt;       - Include SWIG library file &lt;ifile&gt;
      -macroerrors    - Report errors inside macros
-     -makedefault    - Create default constructors/destructors (the default)
      -M              - List all dependencies
      -MD             - Is equivalent to `-M -MF &lt;file&gt;', except `-E' is not implied
      -MF &lt;file&gt;      - Generate dependencies into &lt;file&gt; and continue generating wrappers
@@ -194,7 +195,6 @@ General Options
      -MT &lt;target&gt;    - Set the target of the rule emitted by dependency generation
      -nocontract     - Turn off contract checking
      -nocpperraswarn - Do not treat the preprocessor #error statement as #warning
-     -nodefault      - Do not generate default constructors nor default destructors
      -nodefaultctor  - Do not generate implicit default constructors
      -nodefaultdtor  - Do not generate implicit default destructors
      -nodirprot      - Do not wrap director protected members
@@ -208,16 +208,18 @@ General Options
      -oh &lt;headfile&gt;  - Set name of C++ output header file for directors to &lt;headfile&gt;
      -outcurrentdir  - Set default output dir to current dir instead of input file's path
      -outdir &lt;dir&gt;   - Set language specific files output directory to &lt;dir&gt;
-     -pcreversion    - Display PCRE version information
+     -pcreversion    - Display PCRE2 version information
      -small          - Compile in virtual elimination and compact mode
+     -std=&lt;standard&gt; - Set the C or C++ language &lt;standard&gt; for inputs
      -swiglib        - Report location of SWIG library and exit
      -templatereduce - Reduce all the typedefs in templates
+     -U&lt;symbol&gt;      - Undefine symbol &lt;symbol&gt;
      -v              - Run in verbose mode
      -version        - Display SWIG version number
      -Wall           - Remove all warning suppression, also implies -Wextra
      -Wallkw         - Enable keyword warnings for all the supported languages
      -Werror         - Treat warnings as errors
-     -Wextra         - Adds the following additional warnings: 202,309,403,405,512,321,322
+     -Wextra         - Adds the following additional warnings: 309,403,405,512,321,322
      -w&lt;list&gt;        - Suppress/add warning messages, eg -w401,+321 - see Warnings.html
      -xmlout &lt;file&gt;  - Write XML version of the parse tree to &lt;file&gt; after normal processing
 </pre></div>
@@ -1469,14 +1471,14 @@ SWIG generates the following code:
 <pre>
 /* C mode */
 void foo_set(char *value) {
-  if (foo) free(foo);
+  free(foo);
   foo = (char *) malloc(strlen(value)+1);
   strcpy(foo, value);
 }
 
 /* C++ mode.  When -c++ option is used */
 void foo_set(char *value) {
-  if (foo) delete [] foo;
+  delete [] foo;
   foo = new char[strlen(value)+1];
   strcpy(foo, value);
 }
@@ -1778,13 +1780,6 @@ const int foo;               /* Read only variable */
 char * const version="1.0";  /* Read only variable */
 </pre></div>
 
-<p>
-<b>Compatibility note:</b> Read-only access used to be controlled by a pair of directives
-<tt>%readonly</tt> and <tt>%readwrite</tt>.   Although these directives still work, they
-generate a warning message.   Simply change the directives to <tt>%immutable;</tt> and
-<tt>%mutable;</tt> to silence the warning.  Don't forget the extra semicolon!
-</p>
-
 <H3><a name="SWIG_rename_ignore">5.4.7 Renaming and ignoring declarations</a></H3>
 
 
@@ -1841,6 +1836,25 @@ all to `output' by specifying :</p>
 %rename(output) print; // Rename all `print' functions to `output'
 </pre></div>
 
+<p>
+A new <tt>%rename</tt> for the same name will replace the current
+<tt>%rename</tt> for all uses after it in the file, and setting the
+new name to "" will remove the rename.  So, for instance, if you
+wanted to rename some things in one file and not in another, you could
+do:
+</p>
+
+<div class="code">
+<pre>
+  %rename(print1) print;
+  %include "header1.h" //Anything "print" in here will become "print1"
+  %rename(print2) print;
+  %include "header2.h" //Anything "print" in here will become "print2"
+  %rename("") print;
+  %include "header3.h" //Anything "print" in here will remain "print"
+</pre>
+</div>
+
 <p>
 SWIG does not normally perform any checks to see if the functions it wraps are
 already defined in the target scripting language. However, if you are
@@ -1857,6 +1871,9 @@ If you are using the <tt>%rename</tt> directive and C++, make sure you read the
 for method overloading and default arguments.
 </p>
 
+<H4><a name="SWIG_ignore">5.4.7.2 Ignoring identifiers</a></H4>
+
+
 <p>
 Closely related to <tt>%rename</tt> is the <tt>%ignore</tt> directive.  <tt>%ignore</tt> instructs SWIG
 to ignore declarations that match a given identifier.  For example:
@@ -1880,23 +1897,7 @@ to add conditional compilation to the header.   However, it should be stressed t
 declarations.  If you need to remove a whole section of problematic code, the SWIG preprocessor should be used instead.
 </p>
 
-<p>
-<b>Compatibility note: </b> Older versions of SWIG provided a special <tt>%name</tt> directive for renaming declarations.
-For example:
-</p>
-
-<div class="code">
-<pre>
-%name(output) extern void print(const char *);
-</pre>
-</div>
-
-<p>
-This directive is still supported, but it is deprecated and should probably be avoided.  The <tt>%rename</tt>
-directive is more powerful and better supports wrapping of raw header file information.
-</p>
-
-<H4><a name="SWIG_advanced_renaming">5.4.7.2 Advanced renaming support</a></H4>
+<H4><a name="SWIG_advanced_renaming">5.4.7.3 Advanced renaming support</a></H4>
 
 
 <p>
@@ -2020,10 +2021,10 @@ and a more descriptive one, but the two functions are otherwise equivalent:
 <tr>
     <td><span style="white-space: nowrap;"><tt>regex:/pattern/subst/</tt></span></td>
     <td>String after (Perl-like) regex substitution operation. This function
-    allows to apply arbitrary regular expressions to the identifier names. The
+    allows applying arbitrary regular expressions to the identifier names. The
     <i>pattern</i> part is a regular expression in Perl syntax (as supported
-    by the <a href="http://www.pcre.org/">Perl Compatible Regular Expressions (PCRE)</a>)
-    library and the <i>subst</i> string
+    by the <a href="https://www.pcre.org/">Perl Compatible Regular Expressions</a>)
+    (PCRE2 library) and the <i>subst</i> string
     can contain back-references of the form <tt>\N</tt> where <tt>N</tt> is a digit
     from 0 to 9, or one of the following escape sequences: <tt>\l</tt>, <tt>\L</tt>,
     <tt>\u</tt>, <tt>\U</tt> or <tt>\E</tt>. The back-references are replaced with the
@@ -2041,23 +2042,10 @@ and a more descriptive one, but the two functions are otherwise equivalent:
     <tt>%rename("regex:/(\\w+)_(.*)/\\u\\2/")</tt></td>
     <td><tt>prefix_print</tt></td><td><tt>Print</tt></td>
 </tr>
-<tr>
-    <td><tt>command:cmd</tt></td>
-    <td>Output of an external command <tt>cmd</tt> with the string passed to
-    it as input. Notice that this function is extremely slow compared to all
-    the other ones as it involves spawning a separate process and using it for
-    many declarations is not recommended. The <i>cmd</i> is not enclosed in
-    square brackets but must be terminated with a triple <tt>'&lt;'</tt> sign,
-    e.g. <tt>%rename("command:tr&nbsp;-d&nbsp;aeiou &lt;&lt;&lt;")</tt>
-    (nonsensical example removing all vowels)</td>
-    <td><tt>Print</tt></td><td><tt>Prnt</tt></td>
-</tr>
 </table>
 
 <p>
-The most general function of all of the above ones (not counting
-<tt>command</tt> which is even more powerful in principle but which should
-generally be avoided because of performance considerations) is the
+The most general function of all of the above ones is the
 <tt>regex</tt> one. Here are some more examples of its use:
 </p>
 
@@ -2105,7 +2093,7 @@ are exactly equivalent and <tt>%rename</tt> can be used to selectively ignore
 multiple declarations using the previously described matching possibilities.
 </p>
 
-<H4><a name="SWIG_limiting_renaming">5.4.7.3 Limiting global renaming rules</a></H4>
+<H4><a name="SWIG_limiting_renaming">5.4.7.4 Limiting global renaming rules</a></H4>
 
 
 <p>
@@ -2137,11 +2125,15 @@ the match to class declarations only (in C++) and <tt>match="enumitem"</tt>
 restricts it to the enum elements. SWIG also provides convenience macros for
 such match expressions, for example
 </p>
+
 <div class="code">
 <pre>
 %rename("%(title)s", %$isenumitem) "";
+// same as:
+%rename("%(title)s", match="enumitem") "";
 </pre>
 </div>
+
 <p>
 will capitalize the names of all the enum elements but not change the case of
 the other declarations. Similarly, <tt>%$isclass</tt>, <tt>%$isfunction</tt>,
@@ -2151,6 +2143,56 @@ documentation is not exhaustive, see the "%rename predicates" section in
 <tt>swig.swg</tt> for the full list of supported match expressions.
 </p>
 
+<p>
+A logical not is also possible by using <tt>notmatch</tt>.
+For example, <tt>notmatch="enumitem"</tt> will restrict the
+match to all items that are not enum elements.
+There is also a <tt>%$not</tt> macro which simply expands to "not".
+Be careful using this as some of the other macros in <tt>swig.swg</tt>
+are complex expressions and so it will only "notmatch" the first part
+of the expression.
+</p>
+
+<div class="code">
+<pre>
+%rename("%(title)s", %$not %$isenumitem) "";
+// same as:
+%rename("%(title)s", notmatch="enumitem") "";
+</pre>
+</div>
+
+<p>
+For a comprehensive understanding of how the matching works, the internal
+<a href="Extending.html#Extending_nn8">parse tree</a> needs to be examined using the
+command line option: <tt>-debug-module 1 -debug-quiet</tt>.
+A snippet of the resulting output might be:
+</p>
+
+<div class="shell">
+<pre>
+            +++ destructor ----------------------------------------
+            | access       - "public"
+            | decl         - "f()."
+            | ismember     - "1"
+            | name         - "~Shape"
+            | storage      - "virtual"
+            | sym:name     - "~Shape"
+</pre>
+</div>
+
+<p>
+Here the node type is a "destructor" and in order to match all destructor nodes, use
+<tt>match="destructor"</tt>. To match one of the listed attributes in the node,
+such as when the storage is virtual, use <tt>match$storage="virtual"</tt>.
+This will match all nodes that have a storage attribute set to "virtual".
+To match only virtual destructors, combine them and use <tt>match="destructor", match$storage="virtual"</tt>.
+</p>
+
+<p>
+While the vast majority of these internal parse tree nodes are unlikely to change from one version of
+SWIG to the next, <b>use these matching rules at your own risk</b> as there are no guarantees that they will not change.
+</p>
+
 <p>
 In addition to literally matching some string with <tt>match</tt> you can
 also use <tt>regexmatch</tt> or <tt>notregexmatch</tt> to match a string
@@ -2203,7 +2245,7 @@ wrap C++ overloaded functions and methods or C++ methods which use default argum
 </p>
 
 
-<H4><a name="SWIG_chosen_unignore">5.4.7.4 Ignoring everything then wrapping a few selected symbols</a></H4>
+<H4><a name="SWIG_chosen_unignore">5.4.7.5 Ignoring everything then wrapping a few selected symbols</a></H4>
 
 
 <p>
@@ -2227,6 +2269,23 @@ the following approach could be taken:
 %rename("%s") Star::shine; // named method
 
 %include "myheader.h"
+
+%rename("%s") ""; // Undo the %ignore
+</pre>
+</div>
+
+<p>
+If <tt>Star</tt> was in the <tt>Galaxy</tt> namespace, you would need
+to unignore the namespace, too, and add the namespace to all the
+renames:
+</p>
+
+<div class="code">
+<pre>
+%rename("%s") Galaxy;
+%rename("%s") Galaxy::Star;
+%rename("%s") Galaxy::Star::Star;
+...
 </pre>
 </div>
 
@@ -2241,6 +2300,7 @@ members of the class, so when the chosen class is unignored, all of its methods
 %rename($ignore, %$isclass) ""; // Only ignore all classes
 %rename("%s") Star; // Unignore 'Star'
 %include "myheader.h"
+%rename("%s", %$isclass) ""; // Stop ignoring all classes
 </pre>
 </div>
 
@@ -2445,6 +2505,46 @@ This section describes the behavior of SWIG when processing ISO C structures and
 handle C++ are described in the next section.
 </p>
 
+<p>
+ISO C has a separate tag name space in which the names of structures,
+unions and enumerated types are put, which is separate from the
+name space for ordinary identifiers (function names, object names,
+typedef names, enumeration constants).  For example, this is valid
+ISO C because <tt>Foo</tt> the struct tag and <tt>Foo</tt> the function
+name are in different name spaces:
+</p>
+
+<div class="code"><pre>
+struct Foo {
+  int bar;
+};
+
+int Foo(void) { return 42; }
+</pre></div>
+
+<p>
+SWIG doesn't currently implement this separate tag name space and
+for the above example you'll get:
+</p>
+
+<div class="code"><pre>
+foo.i:5: Warning 302: Redefinition of identifier 'Foo' as Foo(void) ignored,
+foo.i:1: Warning 302: previous definition of 'Foo'.
+
+</pre></div>
+
+<p>
+In practice this rarely actually causes problems, particular because
+SWIG has special handling for <tt>typedef</tt> so cases such as this
+work:
+</p>
+
+<div class="code"><pre>
+typedef struct Foo {
+  int bar;
+} Foo;
+</pre></div>
+
 <p>
 If SWIG encounters the definition of a structure or union, it
 creates a set of accessor functions. Although SWIG does not need
@@ -2456,8 +2556,7 @@ to an individual member. For example, the declaration :</p>
 <div class="code"><pre>
 struct Vector {
   double x, y, z;
-}
-
+};
 </pre></div>
 
 <p>
@@ -2594,8 +2693,7 @@ char *Foo_name_get(Foo *obj) {
 }
 
 char *Foo_name_set(Foo *obj, char *c) {
-  if (obj-&gt;name)
-    free(obj-&gt;name);
+  free(obj-&gt;name);
   obj-&gt;name = (char *) malloc(strlen(c)+1);
   strcpy(obj-&gt;name, c);
   return obj-&gt;name;
@@ -2733,6 +2831,11 @@ void Foo_w_set(FOO *f, WORD value) {
 </pre>
 </div>
 
+<p>
+If you have accessor methods that you want to use as attributes in the
+target language, you can make them appear as data members using
+<a href="Library.html#Library_attributes">attributes.i</a>.
+</p>
 
 <p>
 <b>Compatibility Note:</b>  SWIG-1.3.11 and earlier releases transformed all non-primitive member datatypes
@@ -2817,14 +2920,14 @@ struct Bar {              // Default destructor generated.
 
 <p>
 <b>Compatibility note:</b> Prior to SWIG-1.3.7, SWIG did not generate default constructors
-or destructors unless you explicitly turned them on using <tt>-make_default</tt>. 
+or destructors unless you explicitly turned them on.
 However, it appears that most users want to have constructor and destructor functions so it
 has now been enabled as the default behavior.
 </p>
 
 <p>
-<b>Note:</b> There are also the <tt>-nodefault</tt> option and
-<tt>%nodefault</tt> directive, which disable both the default or
+<b>Note:</b> There is also the
+<tt>%nodefault</tt> directive, which disables both the default or
 implicit destructor generation. This could lead to memory leaks across 
 the target languages, and it is highly recommended you don't use them.
 </p>
@@ -2976,6 +3079,11 @@ typedef struct Vector {
 </pre>
 </div>
 
+<p>
+You'll also need to use these names if you want to directly call methods added
+using <tt>%extend</tt> from other C/C++ code.
+</p>
+
 <p>
 The name used for %extend should be the name of the struct and not the name of any typedef to the struct.
 For example:
@@ -3096,13 +3204,6 @@ the allocation of additional storage in the object (e.g., their values must
 be entirely synthesized from existing attributes of the structure or obtained elsewhere).
 </p>
 
-<p>
-<b>Compatibility note:</b>  The <tt>%extend</tt> directive is a new
-name for the <tt>%addmethods</tt> directive.  Since <tt>%addmethods</tt> could
-be used to extend a structure with more than just methods, a more suitable
-directive name has been chosen.
-</p>
-
 <H3><a name="SWIG_nested_structs">5.5.7 Nested structures</a></H3>
 
 
@@ -3223,7 +3324,7 @@ the following function is generated instead:
 <pre>
 static int
 _wrap_Vector_x_get(ClientData clientData, Tcl_Interp *interp, 
-                   int objc, Tcl_Obj *CONST objv[]) {
+                   int objc, Tcl_Obj *const objv[]) {
   struct Vector *arg1 ;
   double result ;
 
@@ -3534,8 +3635,8 @@ In the process of building an interface, SWIG may encounter syntax errors or
 other problems.  The best way to deal with this is to simply copy the offending
 code into a separate interface file and edit it.   However, the SWIG developers
 have worked very hard to improve the SWIG parser--you should report parsing errors
-to the <a href="http://www.swig.org/mail.html">swig-devel mailing list</a> or to the 
-<a href="http://www.swig.org/bugs.html">SWIG bug tracker</a>.
+to the <a href="https://www.swig.org/mail.html">swig-devel mailing list</a> or to the
+<a href="https://www.swig.org/bugs.html">SWIG bug tracker</a>.
 </p>
 
 <H3><a name="SWIG_nn47">5.7.2 The SWIG interface file</a></H3>

Doc/Manual/SWIGPlus.html

@@ -48,12 +48,16 @@
 </ul>
 <li><a href="#SWIGPlus_nn28">Overloaded operators</a>
 <li><a href="#SWIGPlus_class_extension">Class extension</a>
+<ul>
+<li><a href="#SWIGPlus_replacing_methods">Replacing class methods</a>
+</ul>
 <li><a href="#SWIGPlus_nn30">Templates</a>
 <ul>
 <li><a href="#SWIGPlus_template_directive">The %template directive</a>
 <li><a href="#SWIGPlus_template_functions">Function templates</a>
 <li><a href="#SWIGPlus_template_classes">Default template arguments</a>
 <li><a href="#SWIGPlus_template_class_inheritance">Template base classes</a>
+<li><a href="#SWIGPlus_template_empty">Empty template instantiation</a>
 <li><a href="#SWIGPlus_template_specialization">Template specialization</a>
 <li><a href="#SWIGPlus_template_member">Member templates</a>
 <li><a href="#SWIGPlus_template_scoping">Scoping and templates</a>
@@ -91,6 +95,7 @@ For additions to the original C++ standard, please read the
 <a href="CPlusPlus11.html#CPlusPlus11">SWIG and C++11</a>,
 <a href="CPlusPlus14.html#CPlusPlus14">SWIG and C++14</a> and
 <a href="CPlusPlus17.html#CPlusPlus17">SWIG and C++17</a> chapters.
+<a href="CPlusPlus20.html#CPlusPlus20">SWIG and C++20</a> chapters.
 As a prerequisite,
 you should first read the chapter <a href="SWIG.html#SWIG">SWIG Basics</a> to see
 how SWIG wraps ISO C.  Support for C++ builds upon ISO C
@@ -250,7 +255,7 @@ details.  The SWIG Wiki also has further details.
 </p>
 
 <b>Compatibility Note:</b> Early versions of SWIG generated just a flattened low-level C style API to C++ classes by default.
-The <tt>-noproxy</tt> commandline option is recognised by many target languages and will generate just this
+The <tt>-noproxy</tt> commandline option is recognised by some target languages and will generate just this
 interface as in earlier versions.
 
 <H2><a name="SWIGPlus_nn38">6.5 Proxy classes</a></H2>
@@ -580,7 +585,7 @@ automatically generate a wrapper for one.
 
 <li>
 If a C++ class does not declare an explicit copy constructor, SWIG will
-automatically generate a wrapper for one if the <tt>%copyctor</tt> is used.
+automatically generate a wrapper for one if <tt>%copyctor</tt> is used.
 </li>
 
 <li>
@@ -687,8 +692,7 @@ class Foo {           // No destructor is generated, unless one is declared
 <b>Compatibility Note:</b> The generation of default
 constructors/implicit destructors was made the default behavior in SWIG
 1.3.7. This may break certain older modules, but the old behavior can
-be easily restored using <tt>%nodefault</tt> or the
-<tt>-nodefault</tt> command line option.  Furthermore, in order for
+be easily restored using <tt>%nodefault</tt>.  Furthermore, in order for
 SWIG to properly generate (or not generate) default constructors, it
 must be able to gather information from both the <tt>private</tt> and
 <tt>protected</tt> sections (specifically, it needs to know if a private or
@@ -702,9 +706,9 @@ those sections in the interface or using <tt>%nodefault</tt> to fix the problem.
 
 <p>
 <b>Note:</b> The <tt>%nodefault</tt>
-directive/<tt>-nodefault</tt> options described above, which disable both the default
+directive described above, which disables both the default
 constructor and the implicit destructors, could lead to memory
-leaks, and so it is strongly recommended to not use them.
+leaks, and so it is strongly recommended to not use it.
 </p>
 
 
@@ -870,10 +874,12 @@ could be wrapped, but they had to be renamed.  For example:
 
 <div class="code">
 <pre>
+%rename(CopyFoo) Foo::Foo(const Foo &amp;);
+
 class Foo {
 public:
   Foo();
-  %name(CopyFoo) Foo(const Foo &amp;);
+  Foo(const Foo &amp;);
   ...
 };
 </pre>
@@ -1083,13 +1089,6 @@ However, any use of <tt>%feature("naturalvar")</tt> will override the global set
 typemaps, eg <tt>%apply const std::string &amp; { std::string * }</tt>, but this example would also apply the typemaps to methods taking a <tt>std::string</tt> pointer.
 </p>
 
-<p>
-<b>Compatibility note:</b> Read-only access used to be controlled by a pair of directives
-<tt>%readonly</tt> and <tt>%readwrite</tt>.   Although these directives still work, they
-generate a warning message.   Simply change the directives to <tt>%immutable;</tt> and
-<tt>%mutable;</tt> to silence the warning.  Don't forget the extra semicolon!
-</p>
-
 <p>
 <b>Compatibility note:</b> Prior to SWIG-1.3.12, all members of unknown type were
 wrapped into accessor functions using pointers.  For example, if you had a structure
@@ -1121,7 +1120,7 @@ customization features.
 <p>
  SWIG wraps class members that are public following the C++
  conventions, i.e., by explicit public declaration or by the use of
- the <tt>using</tt> directive. In general, anything specified in a
+ <tt>using</tt> declarations. In general, anything specified in a
  private or protected section will be ignored, although the internal
  code generator sometimes looks at the contents of the private and
  protected sections so that it can properly generate code for default
@@ -1348,16 +1347,19 @@ following:
 <div class="code">
 <pre>
 Vector *wrap_cross_product(Vector *a, Vector *b) {
-  Vector x = *a;
-  Vector y = *b;
-  Vector r = cross_product(x, y);
+  Vector x;
+  Vector y;
+  Vector r;
+  x = *a;
+  y = *b;
+  r = cross_product(x, y);
   return new Vector(r);
 }</pre>
 </div>
 
 <p>
-In order for the wrapper code to compile, <tt>Vector</tt> must define a copy constructor and a 
-default constructor.
+In order for the wrapper code to compile, <tt>Vector</tt> must define a default constructor, copy assignment operator (and/or a move assignment operator for C++11 and later).
+The <a href="CPlusPlus11.html#CPlusPlus11_move_only">Movable and move-only types</a> section should be read regarding C++11 move semantics and return by value.
 </p>
 
 <p>
@@ -1370,9 +1372,12 @@ called the "Fulton Transform".  This produces a wrapper that looks like this:
 <div class="code">
 <pre>
 Vector cross_product(Vector *a, Vector *b) {
-  SwigValueWrapper&lt;Vector&gt; x = *a;
-  SwigValueWrapper&lt;Vector&gt; y = *b;
-  SwigValueWrapper&lt;Vector&gt; r = cross_product(x, y);
+  SwigValueWrapper&lt;Vector&gt; x;
+  SwigValueWrapper&lt;Vector&gt; y;
+  SwigValueWrapper&lt;Vector&gt; r;
+  x = *a;
+  y = *b;
+  r = cross_product(x, y);
   return new Vector(r);
 }
 </pre>
@@ -1798,6 +1803,11 @@ See the <a href="Typemaps.html#Typemaps_overloading">Typemaps and overloading</a
 use the <tt>compactdefaultargs</tt> feature flag as mentioned below.
 </p>
 
+<p>
+For C# please see the <a href="CSharp.html#CSharp_named_arguments">C# named and optional arguments</a> section for information on special
+handling of default arguments available specifically for C#.
+</p>
+
 <p>
 <b>Compatibility note:</b> Versions of SWIG prior to SWIG-1.3.23 wrapped default arguments slightly differently.
 Instead a single wrapper method was generated and the default values were copied into the C++ wrappers
@@ -1824,6 +1834,7 @@ such as C# and Java,
 which don't have optional arguments in the language, 
 Another restriction of this feature is that it cannot handle default arguments that are not public.
 The following example illustrates this:
+
 </p>
 
 <div class="code">
@@ -2079,7 +2090,6 @@ or for statically typed languages like Java:
 <pre>
 example.i:4: Warning 516: Overloaded method foo(long) ignored,
 example.i:3: Warning 516: using foo(int) instead.
-at example.i:3 used.
 </pre>
 </div>
 
@@ -2138,7 +2148,7 @@ This error means that the target language module supports overloading,
 but for some reason there is no type-checking rule that can be used to
 generate a working dispatch function.  The resulting behavior is then
 undefined.  You should report this as a bug to the
-<a href="http://www.swig.org/bugs.html">SWIG bug tracking database</a>
+<a href="https://www.swig.org/bugs.html">SWIG bug tracking database</a>
 if this is due to one of the typemaps supplied with SWIG.
 </p>
 
@@ -2315,7 +2325,7 @@ members (of all classes):
 Note: the <tt>*::</tt> syntax is non-standard C++, but the '*' is meant to be a
 wildcard that matches any class name (we couldn't think of a better
 alternative so if you have a better idea, send email to
-the <a href="http://www.swig.org/mail.html">swig-devel mailing list</a>.
+the <a href="https://www.swig.org/mail.html">swig-devel mailing list</a>.
 </p>
 
 <p>
@@ -2326,8 +2336,8 @@ also apply to <tt>%ignore</tt>.  For example:
 <div class="code">
 <pre>
 %ignore foo(double);          // Ignore all foo(double)
-%ignore Spam::foo;            // Ignore foo in class Spam
-%ignore Spam::foo(double);    // Ignore foo(double) in class Spam
+%ignore Spam::foo;            // Ignore foo in class Spam (and foo in any derived classes)
+%ignore Spam::foo(double);    // Ignore foo(double) in class Spam (and foo in any derived classes)
 %ignore *::foo(double);       // Ignore foo(double) in all classes
 </pre>
 </div>
@@ -2382,6 +2392,53 @@ global scope (e.g., a renaming of <tt>Spam::foo</tt> takes precedence
 over a renaming of <tt>foo(int)</tt>).</p>
 </li>
 
+<li><p>
+Renaming a class member, using an unparameterized but qualified name, such as <tt>Spam::foo</tt>, also applies to members in all derived classes
+that have members with the same name.
+This can be used to simply rename a method, across an entire class hierarchy for all overloaded and non-overloaded methods.
+This also applies to methods introduced via <tt>using</tt> declarations, see
+<a href="#SWIGPlus_nn35">Using declarations and inheritance</a>.
+For example:
+</p>
+
+<div class="code">
+<pre>
+%rename(foo_new) Spam::foo;
+
+class Spam {
+public:
+  virtual void foo(int);      // Renamed to foo_new
+};
+
+class Bar : public Spam {
+public:
+  virtual void foo(int);      // Renamed to foo_new
+  void foo(bool, short, int); // Renamed to foo_new
+};
+
+class Grok : public Bar {
+public:
+  virtual void foo(int);      // Renamed to foo_new
+  void foo(bool, int);        // Renamed to foo_new
+  void foo(const char *);     // Renamed to foo_new
+  void foo(Bar *);            // Renamed to foo_new
+};
+
+class Spok : public Grok {
+public:
+  void foo();                 // Renamed to foo_new
+};
+
+class Knock : public Spok {
+public:
+  using Grok::foo;            // Introduced methods renamed to foo_new
+};
+</pre>
+</div>
+
+</li>
+
+
 <li><p>
 The order in which <tt>%rename</tt> directives are defined does not matter
 as long as they appear before the declarations to be renamed.  Thus, there is no difference
@@ -2936,13 +2993,59 @@ as its use with C structures. Please refer to the <a href="SWIG.html#SWIG_adding
 section for further details.
 </p>
 
+<H3><a name="SWIGPlus_replacing_methods">6.17.1 Replacing class methods</a></H3>
+
+
 <p>
-<b>Compatibility note:</b>  The <tt>%extend</tt> directive is a new
-name for the <tt>%addmethods</tt> directive in SWIG1.1.  Since <tt>%addmethods</tt> could
-be used to extend a structure with more than just methods, a more suitable
-directive name has been chosen.
+Suppose there is a method in a class that you need to replace and keep the method name the same.
+This can be achieved combining the <tt>%extend</tt> and <tt>%ignore</tt> directives covered earlier.
+Here is an example to replace the <tt>MyClass::mymethod()</tt>:
+
+<div class="code">
+<pre>
+%extend MyClass {
+  void mymethod() {
+    std::cout &lt;&lt; "swig mymethod" &lt;&lt; std::endl;
+  }
+}
+
+%ignore MyClass::mymethod;
+
+%inline %{
+class MyClass {
+public:
+  void mymethod() {
+    std::cout &lt;&lt; "class mymethod" &lt;&lt; std::endl;
+  }
+};
+%}
+</pre>
+</div>
+
+<p>
+Or if your code organization makes more sense to put
+the <tt>%extend</tt> after the class definition, you would need the following:
 </p>
 
+<div class="code">
+<pre>
+%rename("") MyClass::mymethod; // unignores the method
+</pre>
+</div>
+
+<p>
+before the <tt>%extend</tt> or SWIG will continue to ignore
+<tt>mymethod()</tt>, even in an <tt>%extend</tt>.
+</p>
+
+<p>
+Note that you can call the class method from the method
+in <tt>%extend</tt>, just use <tt>self-&gt;mymethod()</tt> and it will call
+the class method, not the one in <tt>%extend</tt>.
+</p>
+
+
+
 <H2><a name="SWIGPlus_nn30">6.18 Templates</a></H2>
 
 
@@ -2954,22 +3057,24 @@ is expected in an interface file.  For example:
 <div class="code">
 <pre>
 void foo(vector&lt;int&gt; *a, int n);
-void bar(list&lt;int, 100&gt; *x);
+void bar(std::array&lt;int, 100&gt; *x);
 </pre>
 </div>
 
 <p>
 There are some restrictions on the use of non-type arguments.  Simple literals
-are supported, and so are some constant expressions.  However, use of '&lt;'
-and '&gt;' within a constant expressions currently is not supported by SWIG
-('&lt;=' and '&gt;=' are though).  For example:
+are supported, and so are most constant expressions.  However, there are some
+limitations on the use of '&lt;' and '&gt;' in constant expressions (but note
+that '&lt;=' and '&gt;=' are fully supported).  For example:
 </p>
 
 <div class="code">
 <pre>
-void bar(list&lt;int, 100&gt; *x);                // OK
-void bar(list&lt;int, 2*50&gt; *x);               // OK
-void bar(list&lt;int, (2&gt;1 ? 100 : 50)&gt; *x)    // Not supported
+void bar(std::array&lt;int, 100&gt; *x);                // OK
+void bar(std::array&lt;int, 2*50&gt; *x);               // OK
+void bar(std::array&lt;int, (1&lt;2 ? 100 : 50)&gt; *x)    // OK
+void bar(std::array&lt;int, 1&lt;2 ? 100 : 50&gt; *x)      // Not supported
+void bar(std::array&lt;int, (2&gt;1 ? 100 : 50)&gt; *x)    // Not supported
 </pre>
 </div>
 
@@ -3150,10 +3255,28 @@ void foo(List&lt;Integer&gt; *x);
 In this case, <tt>List&lt;Integer&gt;</tt> is exactly the same type as
 <tt>List&lt;int&gt;</tt>.  Any use of <tt>List&lt;Integer&gt;</tt> is mapped back to the 
 instantiation of <tt>List&lt;int&gt;</tt> created earlier.  Therefore, it is
-not necessary to instantiate a new class for the type <tt>Integer</tt> (doing so is
-redundant and will simply result in code bloat).
+not correct to instantiate a new class for the type <tt>Integer</tt>.
+An attempt to do so such as:
 </p>
 
+<div class="code">
+<pre>
+%template(intList) List&lt;int&gt;;
+%template(IntegerList) List&lt;Integer&gt;;   // Ignored
+</pre>
+</div>
+
+<p>
+will result in the duplicate instantiation being ignored with a warning:
+</p>
+
+<div class="shell">
+<pre>
+example.i:48: Warning 404: Duplicate template instantiation of 'List&lt; Integer &gt;' with name 'IntegerList' ignored,
+example.i:47: Warning 404: previous instantiation of 'List&lt; int &gt;' with name 'intList'.
+</pre>
+</div>
+
 <p>
 The template provided to <tt>%template</tt> for instantiation must be the actual template and not a typedef to a template.
 </p>
@@ -3222,36 +3345,49 @@ original template definition.  Template default arguments are supported.  For ex
 
 <div class="code">
 <pre>
-template vector&lt;typename T, int max=100&gt; class vector {
+template &lt;typename T, int max=100&gt; class vector {
 ...
 };
 
-%template(intvec) vector&lt;int&gt;;           // OK
+%template(intvec) vector&lt;int&gt;;            // OK
 %template(vec1000) vector&lt;int, 1000&gt;;     // OK
 </pre>
 </div>
 
 <p>
 The <tt>%template</tt> directive should not be used to wrap the same
-template instantiation more than once in the same scope.  This will
-generate an error.  For example:
+template instantiation more than once. This also applies to default parameters
+where a template parameter specified in the instantiation is the same as the default parameter.
+For example:
 </p>
 
 <div class="code">
 <pre>
-%template(intList) List&lt;int&gt;;
-%template(Listint) List&lt;int&gt;;    // Error.   Template already wrapped.
+%template(vec) vector&lt;double&gt;;            // OK
+%template(vec100) vector&lt;double, 100&gt;;    // Ignored
 </pre>
 </div>
 
 <p>
-This error is caused because the template expansion results in two
-identical classes with the same name.  This generates a symbol table
-conflict.  Besides, it probably more efficient to only wrap a specific
-instantiation only once in order to reduce the potential for code
-bloat.
+will warn:
 </p>
 
+<div class="shell">
+<pre>
+example.i:59: Warning 404: Duplicate template instantiation of 'vector&lt; double,100 &gt;' with name 'vec100' ignored,
+example.i:58: Warning 404: previous instantiation of 'vector&lt; double &gt;' with name 'vec'.
+</pre>
+</div>
+
+<p>
+If this was not ignored, the template expansion would result in two identical classes.
+An identical instantiation is only wrapped once in order to reduce code bloat.
+</p>
+
+<p>
+<b>Compatibility Note</b>:  Versions prior to SWIG-4.2.0 would sometimes not detect and prevent duplicate
+instantiations, such as when the wrapped name was different.
+</p>
 <H3><a name="SWIGPlus_template_class_inheritance">6.18.4 Template base classes</a></H3>
 
 
@@ -3318,20 +3454,6 @@ code (and base classes need to be wrapped before derived classes).
 Don't worry--if you get the order wrong, SWIG should generate a warning message.
 </p>
 
-<p>
-Occasionally, you may need to tell SWIG about base classes that are defined by templates,
-but which aren't supposed to be wrapped.  Since SWIG is not able to automatically
-instantiate templates for this purpose, you must do it manually.  To do this, simply
-use the empty template instantiation, that is, <tt>%template</tt> with no name.  For example:
-</p>
-
-<div class="code">
-<pre>
-// Instantiate traits&lt;double, double&gt;, but don't wrap it.
-%template() traits&lt;double, double&gt;;
-</pre>
-</div>
-
 <p>
 If you have to instantiate a lot of different classes for many different types,
 you might consider writing a SWIG macro.  For example:
@@ -3357,7 +3479,66 @@ TEMPLATE_WRAP(PairStringInt, std::pair&lt;string, int&gt;)
 Note the use of a vararg macro for the type T. If this wasn't used, the comma in the templated type in the last example would not be possible.
 </p>
 
-<H3><a name="SWIGPlus_template_specialization">6.18.5 Template specialization</a></H3>
+<H3><a name="SWIGPlus_template_empty">6.18.5 Empty template instantiation</a></H3>
+
+
+<p>
+Occasionally, you may need to tell SWIG about classes that are defined by templates,
+but which aren't supposed to be wrapped.  Since SWIG is not able to automatically
+instantiate templates for this purpose, you must do it manually.  To do this, simply
+use <tt>%template()</tt>, that is the empty template instantiation that omits providing a name.  For example:
+</p>
+
+<div class="code">
+<pre>
+template&lt;typename T&gt; struct Traits {
+  typedef T type;
+};
+%}
+
+%template() Traits&lt;int&gt;; // instantiate Traits&lt;int&gt;, but don't wrap it
+
+void traitor(Traits&lt;int&gt;::type val);
+</pre>
+</div>
+
+<p>
+Without a template instantiation, SWIG does not know that the first parameter to the <tt>traitor</tt>
+function is type int and passing an integer to this function from any target language won't work.
+The empty template instantiation adds the appropriate type information into SWIG's type system, without
+forcing one to wrap the <tt>Traits</tt> class.
+</p>
+
+<p>
+Duplicate template instantiation are not allowed, as described in the
+<a href="#SWIGPlus_template_classes">Default template arguments</a> section above.
+There is one exception where a named template instantiation can be followed by an empty template instantiation.
+Duplicate empty template instantiations are silently ignored, unlike duplicate named template instantiations.
+</p>
+
+<p>
+Unlike template class instantiations, template function instantiations must have a name.
+Consider the following:
+</p>
+
+<div class="code">
+<pre>
+template&lt;class T&gt; T tfunc(T x) { };
+%template() tfunc&lt;double&gt;;
+</pre>
+</div>
+
+<p>
+The empty template instantiation will be ignored with:
+</p>
+
+<div class="shell">
+<pre>
+example.i:9: Warning 519: %template() contains no name. Template method ignored: tfunc&lt; double &gt;(double)
+</pre>
+</div>
+
+<H3><a name="SWIGPlus_template_specialization">6.18.6 Template specialization</a></H3>
 
 
 <p>
@@ -3447,7 +3628,7 @@ SWIG implements template argument deduction so that the following partial specia
 </pre>
 </div>
 
-<H3><a name="SWIGPlus_template_member">6.18.6 Member templates</a></H3>
+<H3><a name="SWIGPlus_template_member">6.18.7 Member templates</a></H3>
 
 
 <p>
@@ -3631,7 +3812,7 @@ Alternatively, you could expand the constructor template in selected instantiati
 
 // Create default and conversion constructors 
 %extend pair&lt;double, double&gt; {
-  %template(paird) pair&lt;double, dobule&gt;;   // Default constructor
+  %template(paird) pair&lt;double, double&gt;;   // Default constructor
   %template(pairc) pair&lt;int, int&gt;;         // Conversion constructor
 };
 </pre>
@@ -3646,7 +3827,7 @@ instead:
 <pre>
 // Create default and conversion constructors 
 %extend pair&lt;double, double&gt; {
-  %template(pair) pair&lt;double, dobule&gt;;   // Default constructor
+  %template(pair) pair&lt;double, double&gt;;   // Default constructor
   %template(pair) pair&lt;int, int&gt;;         // Conversion constructor
 };
 </pre>
@@ -3659,7 +3840,7 @@ constructor, that will dispatch the proper call depending on the argument
 type.
 </p>
 
-<H3><a name="SWIGPlus_template_scoping">6.18.7 Scoping and templates</a></H3>
+<H3><a name="SWIGPlus_template_scoping">6.18.8 Scoping and templates</a></H3>
 
 
 <p>
@@ -3760,7 +3941,7 @@ template class C&lt;int&gt;;
 </p>
 
  
-<H3><a name="SWIGPlus_template_more">6.18.8 More on templates</a></H3>
+<H3><a name="SWIGPlus_template_more">6.18.9 More on templates</a></H3>
 
 
 <p>
@@ -4016,23 +4197,23 @@ math::Complex c;
 <p>
 At this level, namespaces are relatively easy to manage.  However, things start to get 
 very ugly when you throw in the other ways a namespace can be used.  For example,
-selective symbols can be exported from a namespace with <tt>using</tt>.
+selective symbols can be exported from a namespace with a <tt>using</tt> declaration:
 </p>
 
 <div class="code">
 <pre>
-using math::Complex;
+using math::Complex;                // Using declaration
 double magnitude(Complex *c);       // Namespace prefix stripped
 </pre>
 </div>
 
 <p>
-Similarly, the contents of an entire namespace can be made available like this:
+Similarly, the contents of an entire namespace can be made available via a <tt>using</tt> directive:
 </p>
 
 <div class="code">
 <pre>
-using namespace math;
+using namespace math;               // Using directive
 double x = sin(1.0);
 double magnitude(Complex *c);
 </pre>
@@ -4189,9 +4370,11 @@ Similarly, <tt>%ignore</tt> can be used to ignore declarations.
 </p>
 
 <p>
-<tt>using</tt> declarations do not have any effect on the generated wrapper
-code. They are ignored by SWIG language modules and they do not result in any
-code.  However, these declarations <em>are</em> used by the internal type
+C++ <tt>using</tt> directives and <tt>using</tt> declarations
+do not add any code to the generated wrapper code.
+However, there is an exception in one context, see <a href="#SWIGPlus_nn35">Using declarations and inheritance</a>
+for introducing members of a base class into a derived class definition.
+C++ <tt>using</tt> declarations and directives <em>are</em> used by the internal type
 system to track type-names. Therefore, if you have code like this:
 </p>
 
@@ -5115,7 +5298,7 @@ exit              # 'a' is released, SWIG unref 'a' called in the destructor wra
 
 
 <p>
-<tt>using</tt> declarations are sometimes used to adjust access to members of
+C++ <tt>using</tt> declarations are sometimes used to introduce members of
 base classes.  For example:
 </p>
 
@@ -5123,7 +5306,7 @@ base classes.  For example:
 <pre>
 class Foo {
 public:
-  int  blah(int x);
+  int blah(int x);
 };
 
 class Bar {
@@ -5171,7 +5354,13 @@ you wrap this code in Python, the module works just like you would expect:
 </div>
 
 <p>
-<tt>using</tt> declarations can also be used to change access when applicable.  For example:
+The C++11 standard supports using declarations for inheriting constructors and this is covered in
+<a href="CPlusPlus11_object_construction_improvement">Object construction improvement</a>.
+</p>
+
+<p>
+C++ <tt>using</tt> declarations can also be used to change access when applicable.
+For example, protected methods in a base class can be made public in a derived class:
 </p>
 
 <div class="code">
@@ -5204,15 +5393,15 @@ ignored in a base class, it will also be ignored by a <tt>using</tt> declaration
 
 <p>
 Because a <tt>using</tt> declaration does not provide fine-grained
-control over the declarations that get imported, it may be difficult
+control over the declarations that get imported, because a single <tt>using</tt> declaration
+may introduce multiple methods, it may be difficult
 to manage such declarations in applications that make heavy use of
 SWIG customization features.  If you can't get <tt>using</tt> to work
-correctly, you can always change the interface to the following:
+correctly, you can always modify the C++ code to handle SWIG differently such as:
 </p>
 
 <div class="code">
 <pre>
-
 class FooBar : public Foo, public Bar {
 public:
 #ifndef SWIG
@@ -5228,13 +5417,36 @@ public:
 </pre>
 </div>
 
+<p>
+If the C++ code being wrapped cannot be changed, make judicious usage of <tt>%extend</tt> and <tt>%rename</tt>
+to ignore and unignore declarations. The example below is effectively the same as above:
+</p>
+
+<div class="code">
+<pre>
+%extend FooBar {
+  int blah(int x) { return $self-&gt;Foo::blah(x); }
+  double blah(double x) { return $self-&gt;Bar::blah(x); }
+}
+%ignore FooBar::blah; // ignore all FooBar::blah below
+%rename("") FooBar::blah(const char *x); // parameterized unignore
+
+class FooBar : public Foo, public Bar {
+public:
+  using Foo::blah;
+  using Bar::blah;
+  char *blah(const char *x);
+};
+</pre>
+</div>
+
 <p>
 <b>Notes:</b>
 </p>
 
 <ul>
-<li><p>If a derived class redefines a method defined in a base class, then a <tt>using</tt> declaration
-won't cause a conflict.  For example:</p>
+<li><p>If a derived class introduces a method defined in a base class via a <tt>using</tt> declaration,
+there won't be a conflict due to incorrect additional methods.  For example:</p>
 
 <div class="code">
 <pre>
@@ -5246,14 +5458,14 @@ public:
 
 class Bar : public Foo {
 public:
-  using Foo::blah;    // Only imports blah(double);
+  using Foo::blah;    // Only introduces blah(double);
   int blah(int);
 };
 </pre>
 </div>
 
-<li><p>Resolving ambiguity in overloading may prevent declarations from being
-imported by <tt>using</tt>.  For example:
+<li><p>Renaming methods may prevent methods from being
+introduced into the derived class via <tt>using</tt> declarations.  For example:
 </p>
 
 <div class="code">
@@ -5267,11 +5479,38 @@ public:
 
 class Bar : public Foo {
 public:
-  using Foo::blah;     // Only imports blah(int)
+  using Foo::blah;     // Only introduces blah(int)
   double blah(double x);
 };
 </pre>
 </div>
+
+<p>
+The problem here is <tt>Foo::blah</tt> is renamed to <tt>blah_long</tt> in the target language, but
+the <tt>using</tt> declaration in Bar is not renamed in the target language and thinks all introduced methods should simply
+be called <tt>blah</tt>.
+It is not clear what target language names should be used in Bar and so the conflicting names are effectively ignored
+as they are not introduced into the derived class for the target language wrappers.
+In such situations SWIG will emit a warning:
+</p>
+
+<div class="shell">
+<pre>
+example.i:15: Warning 526: Using declaration Foo::blah, with name 'blah', is not actually using
+example.i:10: Warning 526: the method from Foo::blah(long), with name 'blah_long', as the names are different.
+</pre>
+</div>
+
+<p>
+<b>Compatibility Note:</b>
+This warning message was introduced in SWIG-4.1.0.
+Prior versions also effectively ignored the using declaration for the same reasons, but were silent about it.
+</p>
+
+<p>
+If methods really need different names, please use of combinations of <tt>%rename</tt>, <tt>%ignore</tt> and <tt>%extend</tt> to achieve the desired outcome.
+</p>
+
 </ul>
 
 <H2><a name="SWIGPlus_nested_classes">6.27 Nested classes</a></H2>

Doc/Manual/Scilab.html

@@ -9,7 +9,7 @@
 
 <body bgcolor="#ffffff">
 
-<H1><a name="Scilab">35 SWIG and Scilab</a></H1>
+<H1><a name="Scilab">36 SWIG and Scilab</a></H1>
 <!-- INDEX -->
 <div class="sectiontoc">
 <ul>
@@ -71,6 +71,7 @@
 <ul>
 <li><a href="#Scilab_generated_scripts_builder_script">Builder script</a>
 <li><a href="#Scilab_generated_scripts_loader_script">Loader script</a>
+<li><a href="#Scilab_generated_scripts_gateway">Gateway XML files</a>
 </ul>
 <li><a href="#Scilab_other_resources">Other resources</a>
 </ul>
@@ -80,7 +81,7 @@
 
 
 <p>
-Scilab is a scientific software package for numerical computations providing a powerful open computing environment for engineering and scientific applications that is mostly compatible with MATLAB. More information can be found at <a href="http://www.scilab.org">www.scilab.org</a>.
+Scilab is a scientific software package for numerical computations providing a powerful open computing environment for engineering and scientific applications that is mostly compatible with MATLAB. More information can be found at <a href="https://www.scilab.org">www.scilab.org</a>.
 </p>
 
 <p>
@@ -88,7 +89,7 @@ This chapter explains how to use SWIG for Scilab. After this introduction, you s
 </p>
 
 
-<H2><a name="Scilab_preliminaries">35.1 Preliminaries</a></H2>
+<H2><a name="Scilab_preliminaries">36.1 Preliminaries</a></H2>
 
 
 <p>
@@ -96,8 +97,7 @@ SWIG for Scilab supports Linux. Other operating systems haven't been tested.
 </p>
 
 <p>
-Scilab is supported from version 5.3.3 onwards.
-The forthcoming version 6, as of January 2015, is also supported.
+Scilab is supported from version 5.3.3 onwards, the SWIG generated code is supported on both Scilab 5, Scilab 6 and more recent versions.
 </p>
 
 <p>
@@ -105,7 +105,7 @@ SWIG for Scilab supports C language. C++ is partially supported. See <a href="#S
 </p>
 
 
-<H2><a name="Scilab_running_swig">35.2 Running SWIG</a></H2>
+<H2><a name="Scilab_running_swig">36.2 Running SWIG</a></H2>
 
 
 <p>
@@ -139,7 +139,7 @@ Note: a code in an <tt>%inline</tt> section is both parsed and wrapped by SWIG,
 </p>
 
 
-<H3><a name="Scilab_running_swig_generating_module">35.2.1 Generating the module</a></H3>
+<H3><a name="Scilab_running_swig_generating_module">36.2.1 Generating the module</a></H3>
 
 
 <p>
@@ -182,7 +182,7 @@ The <tt>swig</tt> executable has several other command line options you can use.
 </p>
 
 
-<H3><a name="Scilab_running_swig_building_module">35.2.2 Building the module</a></H3>
+<H3><a name="Scilab_running_swig_building_module">36.2.2 Building the module</a></H3>
 
 
 <p>
@@ -202,7 +202,7 @@ $ gcc -shared example_wrap.o -o libexample.so
 Note: we supposed in this example that the path to the Scilab include directory is <tt>/usr/local/include/scilab</tt> (which is the case in a Debian environment), this should be changed for another environment.
 </p>
 
-<H3><a name="Scilab_running_swig_loading_module">35.2.3 Loading the module</a></H3>
+<H3><a name="Scilab_running_swig_loading_module">36.2.3 Loading the module</a></H3>
 
 
 <p>
@@ -226,7 +226,7 @@ Link done.
 which means that Scilab has successfully loaded the shared library. The module functions and other symbols are now available in Scilab.
 </p>
 
-<H3><a name="Scilab_running_swig_using_module">35.2.4 Using the module</a></H3>
+<H3><a name="Scilab_running_swig_using_module">36.2.4 Using the module</a></H3>
 
 
 <p>
@@ -260,7 +260,7 @@ ans  =
 Note: for conciseness, we assume in the subsequent Scilab code examples that the modules have been beforehand built and loaded in Scilab.
 </p>
 
-<H3><a name="Scilab_running_swig_options">35.2.5 Scilab command line options</a></H3>
+<H3><a name="Scilab_running_swig_options">36.2.5 Scilab command line options</a></H3>
 
 
 <p>
@@ -305,8 +305,8 @@ The following table lists the Scilab specific command line options in addition t
 </tr>
 
 <tr>
-<td><tt>-targetversion</tt></td>
-<td>Generate for Scilab target (major) version</td>
+<td><tt>-gatewayxml6</tt></td>
+<td>Generate a gateway XML file compatible with Scilab 6</td>
 </tr>
 
 </table>
@@ -320,10 +320,10 @@ $ swig -scilab -help
 </pre></div>
 
 
-<H2><a name="Scilab_wrapping">35.3 A basic tour of C/C++ wrapping</a></H2>
+<H2><a name="Scilab_wrapping">36.3 A basic tour of C/C++ wrapping</a></H2>
 
 
-<H3><a name="Scilab_wrapping_overview">35.3.1 Overview</a></H3>
+<H3><a name="Scilab_wrapping_overview">36.3.1 Overview</a></H3>
 
 
 <p>
@@ -332,7 +332,7 @@ This means that functions, structs, classes, variables, etc... are interfaced th
 There are a few exceptions, such as constants and enumerations, which can be wrapped directly as Scilab variables.
 </p>
 
-<H3><a name="Scilab_wrapping_identifiers">35.3.2 Identifiers</a></H3>
+<H3><a name="Scilab_wrapping_identifiers">36.3.2 Identifiers</a></H3>
 
 
 <p>
@@ -343,11 +343,7 @@ In Scilab 5.x, identifier names are composed of 24 characters maximum (this limi
 In these cases, the <a href="SWIG.html#SWIG_rename_ignore">%rename directive</a> can be used to choose a different Scilab name.
 </p>
 
-<p>
-Note: truncations can be disabled by specifying the target version 6 of Scilab in the <tt>targetversion</tt> argument (i.e. <tt>-targetversion 6</tt>).
-</p>
-
-<H3><a name="Scilab_wrapping_functions">35.3.3 Functions</a></H3>
+<H3><a name="Scilab_wrapping_functions">36.3.3 Functions</a></H3>
 
 
 <p>
@@ -378,7 +374,7 @@ ans  =
     24.
 </pre></div>
 
-<H4><a name="Scilab_nn13">35.3.3.1 Argument passing</a></H4>
+<H4><a name="Scilab_nn13">36.3.3.1 Argument passing</a></H4>
 
 
 <p>
@@ -431,7 +427,7 @@ In Scilab, parameters are passed by value. The output (and inout) parameters are
     7.
 </pre></div>
 
-<H4><a name="Scilab_nn14">35.3.3.2 Multiple output arguments</a></H4>
+<H4><a name="Scilab_nn14">36.3.3.2 Multiple output arguments</a></H4>
 
 
 <p>
@@ -480,7 +476,7 @@ int divide(int n, int d, int *OUTPUT, int *OUTPUT);
 </pre></div>
 
 
-<H3><a name="Scilab_wrapping_global_variables">35.3.4 Global variables</a></H3>
+<H3><a name="Scilab_wrapping_global_variables">36.3.4 Global variables</a></H3>
 
 
 <p>
@@ -549,10 +545,10 @@ It works the same:</p>
 </pre></div>
 
 
-<H3><a name="Scilab_wrapping_constants_and_enums">35.3.5 Constants and enumerations</a></H3>
+<H3><a name="Scilab_wrapping_constants_and_enums">36.3.5 Constants and enumerations</a></H3>
 
 
-<H4><a name="Scilab_wrapping_constants">35.3.5.1 Constants</a></H4>
+<H4><a name="Scilab_wrapping_constants">36.3.5.1 Constants</a></H4>
 
 
 <p>
@@ -693,7 +689,7 @@ are mapped to Scilab variables, with the same name:
     3.14
 </pre></div>
 
-<H4><a name="Scilab_wrapping_enums">35.3.5.2 Enumerations</a></H4>
+<H4><a name="Scilab_wrapping_enums">36.3.5.2 Enumerations</a></H4>
 
 
 <p>
@@ -758,7 +754,7 @@ typedef enum { RED, BLUE, GREEN } color;
 
 </pre></div>
 
-<H3><a name="Scilab_wrapping_pointers">35.3.6 Pointers</a></H3>
+<H3><a name="Scilab_wrapping_pointers">36.3.6 Pointers</a></H3>
 
 
 <p>
@@ -768,7 +764,7 @@ Pointers are supported by SWIG. A pointer can be returned from a wrapped C/C++ f
 Also, thanks to the SWIG runtime which stores information about types, pointer types are tracked between exchanges Scilab and the native code. Indeed pointer types are stored alongside the pointer address.
 A pointer is mapped to a Scilab structure (<a href="https://help.scilab.org/docs/5.5.2/en_US/tlist.html">tlist</a>), which contains as fields the pointer address and the pointer type (in fact a pointer to the type information structure in the SWIG runtime).
 <br>
-Why a native pointer is not mapped to a Scilab pointer (type name: "pointer", type ID: 128) ? The big advantage of mapping to a <tt>tlist</tt> is that it exposes a new type for the pointer in Scilab, type which can be acessed in Scilab with the <a href="https://help.scilab.org/docs/5.5.2/en_US/typeof.html">typeof</a> function, and manipulated using the <a href="https://help.scilab.org/docs/5.5.2/en_US/overloading.html">overloading</a> mechanism.
+Why a native pointer is not mapped to a Scilab pointer (type name: "pointer", type ID: 128) ? The big advantage of mapping to a <tt>tlist</tt> is that it exposes a new type for the pointer in Scilab, type which can be accessed in Scilab with the <a href="https://help.scilab.org/docs/5.5.2/en_US/typeof.html">typeof</a> function, and manipulated using the <a href="https://help.scilab.org/docs/5.5.2/en_US/overloading.html">overloading</a> mechanism.
 </p>
 
 <p>
@@ -776,7 +772,7 @@ Notes:
 </p>
 <ul>
 <li>type tracking needs the SWIG runtime to be first initialized with the appropriate function (see the <a href="#Scilab_module_initialization">Module initialization</a> section).</li>
-<li>for any reason, if a wrapped pointer type is unknown (or if the SWIG runtime is not initialized), SWIG maps it to a Scilab pointer. Also, a Scilab pointer is always accepted as a pointer argument of a wrapped function. The drawaback is that pointer type is lost.</li>
+<li>for any reason, if a wrapped pointer type is unknown (or if the SWIG runtime is not initialized), SWIG maps it to a Scilab pointer. Also, a Scilab pointer is always accepted as a pointer argument of a wrapped function. The drawback is that pointer type is lost.</li>
 </ul>
 
 <p>
@@ -820,7 +816,7 @@ Note: the type name <tt>_p_FILE</tt> which means "pointer to FILE".
 The user of a pointer is responsible for freeing it or, like in the example, closing any resources associated with it (just as is required in a C program).
 </p>
 
-<H4><a name="Scilab_wrapping_pointers_utility_functions">35.3.6.1 Utility functions</a></H4>
+<H4><a name="Scilab_wrapping_pointers_utility_functions">36.3.6.1 Utility functions</a></H4>
 
 
 <p>
@@ -861,7 +857,7 @@ ans  =
 </pre></div>
 
 
-<H4><a name="Scilab_wrapping_pointers_null_pointers">35.3.6.2 Null pointers:</a></H4>
+<H4><a name="Scilab_wrapping_pointers_null_pointers">36.3.6.2 Null pointers:</a></H4>
 
 
 <p>
@@ -877,7 +873,7 @@ Using the previous <tt>SWIG_this()</tt> and <tt>SWIG_ptr()</tt>, it is possible
 </pre></div>
 
 
-<H3><a name="Scilab_wrapping_structs">35.3.7 Structures</a></H3>
+<H3><a name="Scilab_wrapping_structs">36.3.7 Structures</a></H3>
 
 
 <p>
@@ -986,7 +982,7 @@ Note: the pointer to the struct works as described in <a href="#Scilab_wrapping_
 --&gt; delete_Bar(b);
 </pre></div>
 
-<H3><a name="Scilab_wrapping_cpp_classes">35.3.8 C++ classes</a></H3>
+<H3><a name="Scilab_wrapping_cpp_classes">36.3.8 C++ classes</a></H3>
 
 
 <p>
@@ -1054,7 +1050,7 @@ Note: like structs, class pointers are mapped as described in <a href="#Scilab_w
 --&gt; delete_Point(p);
 </pre></div>
 
-<H3><a name="Scilab_wrapping_cpp_inheritance">35.3.9 C++ inheritance</a></H3>
+<H3><a name="Scilab_wrapping_cpp_inheritance">36.3.9 C++ inheritance</a></H3>
 
 
 <p>
@@ -1129,7 +1125,7 @@ But we can use either use the <tt>get_perimeter()</tt> function of the parent cl
     18.84
 </pre></div>
 
-<H3><a name="Scilab_wrapping_cpp_overloading">35.3.10 C++ overloading</a></H3>
+<H3><a name="Scilab_wrapping_cpp_overloading">36.3.10 C++ overloading</a></H3>
 
 
 <p>
@@ -1169,7 +1165,7 @@ void magnify(Circle *circle, double factor) {
 </pre></div>
 
 
-<H3><a name="Scilab_wrapping_pointers_references_values_arrays">35.3.11 Pointers, references, values, and arrays</a></H3>
+<H3><a name="Scilab_wrapping_pointers_references_values_arrays">36.3.11 Pointers, references, values, and arrays</a></H3>
 
 
 <p>
@@ -1227,7 +1223,7 @@ All these functions will return a pointer to an instance of <tt>Foo</tt>.
 As the function <tt>spam7</tt> returns a value, new instance of <tt>Foo</tt> has to be allocated, and a pointer on this instance is returned.
 </p>
 
-<H3><a name="Scilab_wrapping_cpp_templates">35.3.12 C++ templates</a></H3>
+<H3><a name="Scilab_wrapping_cpp_templates">36.3.12 C++ templates</a></H3>
 
 
 <p>
@@ -1286,7 +1282,7 @@ Then in Scilab:
 More details on template support can be found in the <a href="SWIGPlus.html#SWIGPlus_nn30">templates</a> documentation.
 </p>
 
-<H3><a name="Scilab_wrapping_cpp_operators">35.3.13 C++ operators</a></H3>
+<H3><a name="Scilab_wrapping_cpp_operators">36.3.13 C++ operators</a></H3>
 
 
 <p>
@@ -1339,7 +1335,7 @@ private:
 </pre></div>
 
 
-<H3><a name="Scilab_wrapping_cpp_namespaces">35.3.14 C++ namespaces</a></H3>
+<H3><a name="Scilab_wrapping_cpp_namespaces">36.3.14 C++ namespaces</a></H3>
 
 
 <p>
@@ -1417,7 +1413,7 @@ Note: the <a href="SWIGPlus.html#SWIGPlus_nspace">nspace</a> feature is not supp
 </p>
 
 
-<H3><a name="Scilab_wrapping_cpp_exceptions">35.3.15 C++ exceptions</a></H3>
+<H3><a name="Scilab_wrapping_cpp_exceptions">36.3.15 C++ exceptions</a></H3>
 
 
 <p>
@@ -1500,17 +1496,17 @@ More complex or custom exception types require specific exception typemaps to be
 See the <a href="SWIGPlus.html#SWIGPlus">SWIG C++ documentation</a> for more details.
 </p>
 
-<H3><a name="Scilab_wrapping_cpp_stl">35.3.16 C++ STL</a></H3>
+<H3><a name="Scilab_wrapping_cpp_stl">36.3.16 C++ STL</a></H3>
 
 
 <p>
 The Standard Template Library (STL) is partially supported. See <a href="#Scilab_typemaps_stl">STL</a> for more details.
 </p>
 
-<H2><a name="Scilab_typemaps">35.4 Type mappings and libraries</a></H2>
+<H2><a name="Scilab_typemaps">36.4 Type mappings and libraries</a></H2>
 
 
-<H3><a name="Scilab_typemaps_primitive_types">35.4.1 Default primitive type mappings</a></H3>
+<H3><a name="Scilab_typemaps_primitive_types">36.4.1 Default primitive type mappings</a></H3>
 
 
 <p>
@@ -1561,7 +1557,7 @@ The default behaviour is for SWIG to generate code that will give a runtime erro
 
 
 
-<H3><a name="Scilab_typemaps_arrays">35.4.2 Arrays</a></H3>
+<H3><a name="Scilab_typemaps_arrays">36.4.2 Arrays</a></H3>
 
 
 <p>
@@ -1616,7 +1612,7 @@ void printArray(int values[], int len) {
 [ 0  1  2  3 ]
 </pre></div>
 
-<H3><a name="Scilab_typemaps_pointer-to-pointers">35.4.3 Pointer-to-pointers</a></H3>
+<H3><a name="Scilab_typemaps_pointer-to-pointers">36.4.3 Pointer-to-pointers</a></H3>
 
 
 <p>
@@ -1689,7 +1685,7 @@ void print_matrix(double **M, int nbRows, int nbCols) {
 </pre></div>
 
 
-<H3><a name="Scilab_typemaps_matrices">35.4.4 Matrices</a></H3>
+<H3><a name="Scilab_typemaps_matrices">36.4.4 Matrices</a></H3>
 
 
 <p>
@@ -1782,7 +1778,7 @@ The remarks made earlier for arrays also apply here:
 <li>There is no control while converting <tt>double</tt> values to integers, <tt>double</tt> values are truncated without any checking or warning.</li>
 </ul>
 
-<H3><a name="Scilab_typemaps_stl">35.4.5 STL</a></H3>
+<H3><a name="Scilab_typemaps_stl">36.4.5 STL</a></H3>
 
 
 <p>
@@ -1982,7 +1978,7 @@ ans  =
 --&gt; delete_PersonPtrSet(p);
 </pre></div>
 
-<H2><a name="Scilab_module_initialization">35.5 Module initialization</a></H2>
+<H2><a name="Scilab_module_initialization">36.5 Module initialization</a></H2>
 
 
 <p>
@@ -2006,7 +2002,7 @@ For example, to initialize the module <tt>example</tt>:
 --&gt; example_Init();
 </pre></div>
 
-<H2><a name="Scilab_building_modes">35.6 Building modes</a></H2>
+<H2><a name="Scilab_building_modes">36.6 Building modes</a></H2>
 
 
 <p>
@@ -2021,7 +2017,7 @@ To produce a dynamic module, when generating the wrapper, there are two possibil
 <li>the <tt>builder</tt> mode. In this mode, Scilab is responsible of building.
 </ul>
 
-<H3><a name="Scilab_building_modes_nobuilder_mode">35.6.1 No-builder mode</a></H3>
+<H3><a name="Scilab_building_modes_nobuilder_mode">36.6.1 No-builder mode</a></H3>
 
 
 <p>
@@ -2034,7 +2030,7 @@ This mode is the best option to use when you have to integrate the module build
 </p>
 
 
-<H3><a name="Scilab_building_modes_builder_mode">35.6.2 Builder mode</a></H3>
+<H3><a name="Scilab_building_modes_builder_mode">36.6.2 Builder mode</a></H3>
 
 
 <p>
@@ -2074,14 +2070,14 @@ The command is:
 $ swig -scilab -builder -buildercflags -I/opt/foo/include -builderldflags "-L/opt/foo/lib -lfoo" -buildersources baa1.cxx, baa2.cxx example.i
 </pre></div>
 
-<H2><a name="Scilab_generated_scripts">35.7 Generated scripts</a></H2>
+<H2><a name="Scilab_generated_scripts">36.7 Generated scripts</a></H2>
 
 
 <p>
 In this part we give some details about the generated Scilab scripts.
 </p>
 
-<H3><a name="Scilab_generated_scripts_builder_script">35.7.1 Builder script</a></H3>
+<H3><a name="Scilab_generated_scripts_builder_script">36.7.1 Builder script</a></H3>
 
 
 <p>
@@ -2106,7 +2102,7 @@ ilib_build(ilib_name, table, files, libs);
 <li><tt><b>table</b></tt>: two column string matrix containing a table of pairs of 'scilab function name', 'C function name'.</li>
 </ul>
 
-<H3><a name="Scilab_generated_scripts_loader_script">35.7.2 Loader script</a></H3>
+<H3><a name="Scilab_generated_scripts_loader_script">36.7.2 Loader script</a></H3>
 
 
 <p>
@@ -2144,14 +2140,29 @@ clear get_file_path;
 <li><tt><b>fcts</b></tt>: vector of character strings. The name of new Scilab function.</li>
 </ul>
 
+<H3><a name="Scilab_generated_scripts_gateway">36.7.3 Gateway XML files</a></H3>
 
-<H2><a name="Scilab_other_resources">35.8 Other resources</a></H2>
+
+<p>If you need to post-process the entry points, Scilab gateway files are XML files that can be used to retrieve all SWIG-generated entry points. With these XML files you can write your own <tt>builder_swig.sce</tt> file to add custom Scilab for building or linking the generated code. Documentation stubs can also be generated thanks to these function listings.</p>
+<p>As an example, for a SWIG <a href="Modules.html">module</a> named <tt>fmuswig</tt> the Scilab code below can be used to store all SWIG-generated functions in a variable named <tt>funs</tt>.</p>
+<div class="code"><pre>
+  // src_swig_path is a path to the directory containing the fmuswig.i file
+
+  doc = xmlRead(src_swig_path + "/fmuswig_gateway.xml");
+  names = xmlAsText(xmlXPath(doc, "//gateway/@name"));
+  funs = xmlAsText(xmlXPath(doc, "//gateway/@function"));
+  xmlDelete(doc);
+
+</pre></div>
+
+
+<H2><a name="Scilab_other_resources">36.8 Other resources</a></H2>
 
 
 <ul>
 <li>Example use cases can be found in the <tt>Examples/scilab</tt> directory.</li>
 <li>The test suite in the <tt>Examples/test-suite/scilab</tt> can be another source of useful use cases.</li>
-<li>The <a href="http://help.scilab.org/docs/5.5.0/en_US/api_scilab.html">Scilab API</a> is used in the generated code and is a useful reference when examining the output.</li>
-<li>This <a href="http://wiki.scilab.org/howto/Create%20a%20toolbox">guide</a> describes the Scilab external modules structure and files, in particular the files that are generated by SWIG for Scilab.</li>
+<li>The <a href="https://help.scilab.org/api_scilab.html">Scilab API</a> is used in the generated code and is a useful reference when examining the output.</li>
+<li>This <a href="https://wiki.scilab.org/howto/Create%20a%20toolbox">guide</a> describes the Scilab external modules structure and files, in particular the files that are generated by SWIG for Scilab.</li>
 </ul>
 

Doc/Manual/Sections.html

@@ -1,14 +1,14 @@
 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
 <html>
 <head>
-<title>SWIG-4.0 Documentation</title>
+<title>SWIG-4.2 Documentation</title>
 <meta http-equiv="content-type" content="text/html; charset=UTF-8">
 </head>
 <body bgcolor="#ffffff">
-<H1><a name="Sections">SWIG-4.0 Documentation</a></H1>
+<H1><a name="Sections">SWIG-4.2 Documentation</a></H1>
 
 <p>
-Last update : SWIG-4.0.2 (8 Jun 2020)
+Last update : SWIG-4.2.0 (30 Dec 2023)
 </p>
 
 <H2><a name="Sections_Sections">Sections</a></H2>
@@ -24,6 +24,7 @@ Last update : SWIG-4.0.2 (8 Jun 2020)
 <li><a href="CPlusPlus11.html#CPlusPlus11">SWIG and C++11</a></li>
 <li><a href="CPlusPlus14.html#CPlusPlus14">SWIG and C++14</a></li>
 <li><a href="CPlusPlus17.html#CPlusPlus17">SWIG and C++17</a></li>
+<li><a href="CPlusPlus20.html#CPlusPlus20">SWIG and C++20</a></li>
 <li><a href="Preprocessor.html#Preprocessor">The SWIG preprocessor</a></li>
 <li><a href="Library.html#Library">The SWIG library</a></li>
 <li><a href="Arguments.html#Arguments">Argument handling</a></li>

Doc/Manual/Tcl.html

@@ -7,7 +7,7 @@
 </head>
 
 <body bgcolor="#ffffff">
-<H1><a name="Tcl">36 SWIG and Tcl</a></H1>
+<H1><a name="Tcl">37 SWIG and Tcl</a></H1>
 <!-- INDEX -->
 <div class="sectiontoc">
 <ul>
@@ -79,12 +79,12 @@
 </p>
 
 <p>
-This chapter discusses SWIG's support of Tcl. SWIG currently requires
-Tcl 8.0 or a later release.   Earlier releases of SWIG supported Tcl 7.x, but
-this is no longer supported.
+This chapter discusses SWIG's support of Tcl. Since SWIG 4.1.0, Tcl 8.4 or a
+later release is required.  Prior to that earlier Tcl 8.x releases were also
+supported.
 </p>
 
-<H2><a name="Tcl_nn2">36.1 Preliminaries</a></H2>
+<H2><a name="Tcl_nn2">37.1 Preliminaries</a></H2>
 
 
 <p>
@@ -110,7 +110,7 @@ build a Tcl extension module.  To finish building the module, you
 need to compile this file and link it with the rest of your program.
 </p>
 
-<H3><a name="Tcl_nn3">36.1.1 Getting the right header files</a></H3>
+<H3><a name="Tcl_nn3">37.1.1 Getting the right header files</a></H3>
 
 
 <p>
@@ -128,7 +128,7 @@ this is the case, you should probably make a symbolic link so that <tt>tcl.h</tt
 header file.
 </p>
 
-<H3><a name="Tcl_nn4">36.1.2 Compiling a dynamic module</a></H3>
+<H3><a name="Tcl_nn4">37.1.2 Compiling a dynamic module</a></H3>
 
 
 <p>
@@ -164,7 +164,7 @@ The name of the module is specified using the <tt>%module</tt> directive or the
  <tt>-module</tt> command line option.
 </p>
 
-<H3><a name="Tcl_nn5">36.1.3 Static linking</a></H3>
+<H3><a name="Tcl_nn5">37.1.3 Static linking</a></H3>
 
 
 <p>
@@ -230,7 +230,7 @@ minimal in most situations (and quite frankly not worth the extra
 hassle in the opinion of this author). 
 </p>
 
-<H3><a name="Tcl_nn6">36.1.4 Using your module</a></H3>
+<H3><a name="Tcl_nn6">37.1.4 Using your module</a></H3>
 
 
 <p>
@@ -358,7 +358,7 @@ to the default system configuration (this requires root access and you will need
 the man pages). 
 </p>
 
-<H3><a name="Tcl_nn7">36.1.5 Compilation of C++ extensions</a></H3>
+<H3><a name="Tcl_nn7">37.1.5 Compilation of C++ extensions</a></H3>
 
 
 <p>
@@ -441,7 +441,7 @@ erratic program behavior.   If working with lots of software components, you
 might want to investigate using a more formal standard such as COM.
 </p>
 
-<H3><a name="Tcl_nn8">36.1.6 Compiling for 64-bit platforms</a></H3>
+<H3><a name="Tcl_nn8">37.1.6 Compiling for 64-bit platforms</a></H3>
 
 
 <p>
@@ -468,7 +468,7 @@ also introduce problems on platforms that support more than one
 linking standard (e.g., -o32 and -n32 on Irix).
 </p>
 
-<H3><a name="Tcl_nn9">36.1.7 Setting a package prefix</a></H3>
+<H3><a name="Tcl_nn9">37.1.7 Setting a package prefix</a></H3>
 
 
 <p>
@@ -487,7 +487,7 @@ option will append the prefix to the name when creating a command and
 call it "<tt>Foo_bar</tt>".
 </p>
 
-<H3><a name="Tcl_nn10">36.1.8 Using namespaces</a></H3>
+<H3><a name="Tcl_nn10">37.1.8 Using namespaces</a></H3>
 
 
 <p>
@@ -509,7 +509,7 @@ When the <tt>-namespace</tt> option is used, objects in the module
 are always accessed with the namespace name such as <tt>Foo::bar</tt>.
 </p>
 
-<H2><a name="Tcl_nn11">36.2 Building Tcl/Tk Extensions under Windows 95/NT</a></H2>
+<H2><a name="Tcl_nn11">37.2 Building Tcl/Tk Extensions under Windows 95/NT</a></H2>
 
 
 <p>
@@ -520,7 +520,7 @@ covers the process of using SWIG with Microsoft Visual C++.
 although the procedure may be similar with other compilers.
 </p>
 
-<H3><a name="Tcl_nn12">36.2.1 Running SWIG from Developer Studio</a></H3>
+<H3><a name="Tcl_nn12">37.2.1 Running SWIG from Developer Studio</a></H3>
 
 
 <p>
@@ -578,7 +578,7 @@ MSDOS &gt; tclsh80
 %
 </pre></div>
 
-<H3><a name="Tcl_nn13">36.2.2 Using NMAKE</a></H3>
+<H3><a name="Tcl_nn13">37.2.2 Using NMAKE</a></H3>
 
 
 <p>
@@ -636,12 +636,12 @@ tcl:
 
 <p>
 To build the extension, run NMAKE (you may need to run vcvars32
-first).  This is a pretty minimal Makefile, but hopefully its enough
+first).  This is a pretty minimal Makefile, but hopefully it's enough
 to get you started.  With a little practice, you'll be making lots of
 Tcl extensions.
 </p>
 
-<H2><a name="Tcl_nn14">36.3 A tour of basic C/C++ wrapping</a></H2>
+<H2><a name="Tcl_nn14">37.3 A tour of basic C/C++ wrapping</a></H2>
 
 
 <p>
@@ -652,7 +652,7 @@ classes.  This section briefly covers the essential aspects of this
 wrapping.
 </p>
 
-<H3><a name="Tcl_nn15">36.3.1 Modules</a></H3>
+<H3><a name="Tcl_nn15">37.3.1 Modules</a></H3>
 
 
 <p>
@@ -686,7 +686,7 @@ To fix this, supply an extra argument to <tt>load</tt> like this:
 </pre>
 </div>
 
-<H3><a name="Tcl_nn16">36.3.2 Functions</a></H3>
+<H3><a name="Tcl_nn16">37.3.2 Functions</a></H3>
 
 
 <p>
@@ -711,7 +711,7 @@ like you think it does:
 %
 </pre></div>
 
-<H3><a name="Tcl_nn17">36.3.3 Global variables</a></H3>
+<H3><a name="Tcl_nn17">37.3.3 Global variables</a></H3>
 
 
 <p>
@@ -791,7 +791,7 @@ extern char *path;      // Read-only (due to %immutable)
 </pre>
 </div>
 
-<H3><a name="Tcl_nn18">36.3.4 Constants and enums</a></H3>
+<H3><a name="Tcl_nn18">37.3.4 Constants and enums</a></H3>
 
 
 <p>
@@ -826,7 +826,7 @@ are not wrapped as constants.   For further discussion about this, see the <a hr
 
 <p>
 Constants are not guaranteed to remain constant in Tcl---the value
-of the constant could be accidentally reassigned.You will just have to be careful.
+of the constant could be accidentally reassigned. You will just have to be careful.
 </p>
 
 <p>
@@ -843,39 +843,7 @@ proc blah {} {
 </pre>
 </div>
 
-<p>
-If a program relies on a lot of constants, this can be extremely annoying.  To fix the problem, consider using the
-following typemap rule:
-</p>
-
-<div class="code">
-<pre>
-%apply int CONSTANT { int x };
-#define FOO 42
-...
-void bar(int x);
-</pre>
-</div>
-
-<p>
-When applied to an input argument, the <tt>CONSTANT</tt> rule allows a constant to be passed to a function using
-its actual value or a symbolic identifier name.  For example:
-</p>
-
-<div class="code">
-<pre>
-proc blah {} {
-  bar FOO
-}
-</pre>
-</div>
-
-<p>
-When an identifier name is given, it is used to perform an implicit hash-table lookup of the value during argument 
-conversion.  This allows the <tt>global</tt> statement to be omitted.
-</p>
-
-<H3><a name="Tcl_nn19">36.3.5 Pointers</a></H3>
+<H3><a name="Tcl_nn19">37.3.5 Pointers</a></H3>
 
 
 <p>
@@ -971,7 +939,7 @@ C-style cast may return a bogus result whereas as the C++-style cast will return
 <tt>None</tt> if the conversion can't be performed.
 </p>
 
-<H3><a name="Tcl_nn20">36.3.6 Structures</a></H3>
+<H3><a name="Tcl_nn20">37.3.6 Structures</a></H3>
 
 
 <p>
@@ -1227,7 +1195,15 @@ _108fea88_p_Bar
 
 <p>
 Finally, to destroy objects created from Tcl, you can either let the object
-name go out of scope or you can explicitly delete the object.  For example:
+name go out of scope or you can explicitly delete the object as shown below.
+Objects won't get automatically destroyed when the Tcl program exits, so if
+it's important that the C++ destructor is called for a class you'll need to
+make sure that you explicitly do this for objects of that class before program
+exit.
+</p>
+
+<p>
+For example:
 </p>
 
 <div class="code">
@@ -1253,7 +1229,7 @@ Note: Tcl only destroys the underlying object if it has ownership.  See the
 memory management section that appears shortly.
 </p>
 
-<H3><a name="Tcl_nn21">36.3.7 C++ classes</a></H3>
+<H3><a name="Tcl_nn21">37.3.7 C++ classes</a></H3>
 
 
 <p>
@@ -1319,7 +1295,7 @@ In Tcl, the static member is accessed as follows:
 </pre>
 </div>
 
-<H3><a name="Tcl_nn22">36.3.8 C++ inheritance</a></H3>
+<H3><a name="Tcl_nn22">37.3.8 C++ inheritance</a></H3>
 
 
 <p>
@@ -1368,7 +1344,7 @@ For instance:
 It is safe to use multiple inheritance with SWIG.
 </p>
 
-<H3><a name="Tcl_nn23">36.3.9 Pointers, references, values, and arrays</a></H3>
+<H3><a name="Tcl_nn23">37.3.9 Pointers, references, values, and arrays</a></H3>
 
 
 <p>
@@ -1422,7 +1398,7 @@ to hold the result and a pointer is returned (Tcl will release this memory
 when the return value is garbage collected).
 </p>
 
-<H3><a name="Tcl_nn24">36.3.10 C++ overloaded functions</a></H3>
+<H3><a name="Tcl_nn24">37.3.10 C++ overloaded functions</a></H3>
 
 
 <p>
@@ -1545,7 +1521,7 @@ first declaration takes precedence.
 Please refer to the "SWIG and C++" chapter for more information about overloading. 
 </p>
 
-<H3><a name="Tcl_nn25">36.3.11 C++ operators</a></H3>
+<H3><a name="Tcl_nn25">37.3.11 C++ operators</a></H3>
 
 
 <p>
@@ -1647,7 +1623,7 @@ There are ways to make this operator appear as part of the class using the <tt>%
 Keep reading.
 </p>
 
-<H3><a name="Tcl_nn26">36.3.12 C++ namespaces</a></H3>
+<H3><a name="Tcl_nn26">37.3.12 C++ namespaces</a></H3>
 
 
 <p>
@@ -1711,7 +1687,7 @@ utilizes thousands of small deeply nested namespaces each with
 identical symbol names, well, then you get what you deserve.
 </p>
 
-<H3><a name="Tcl_nn27">36.3.13 C++ templates</a></H3>
+<H3><a name="Tcl_nn27">37.3.13 C++ templates</a></H3>
 
 
 <p>
@@ -1763,7 +1739,7 @@ More details can be found in the <a href="SWIGPlus.html#SWIGPlus">SWIG and C++</
 examples will appear later.
 </p>
 
-<H3><a name="Tcl_nn28">36.3.14 C++ Smart Pointers</a></H3>
+<H3><a name="Tcl_nn28">37.3.14 C++ Smart Pointers</a></H3>
 
 
 <p>
@@ -1847,7 +1823,7 @@ simply use the <tt>__deref__()</tt> method.  For example:
 </pre>
 </div>
 
-<H2><a name="Tcl_nn29">36.4 Further details on the Tcl class interface</a></H2>
+<H2><a name="Tcl_nn29">37.4 Further details on the Tcl class interface</a></H2>
 
 
 <p>
@@ -1860,7 +1836,7 @@ of low-level details were omitted.  This section provides a brief overview
 of how the proxy classes work.
 </p>
 
-<H3><a name="Tcl_nn30">36.4.1 Proxy classes</a></H3>
+<H3><a name="Tcl_nn30">37.4.1 Proxy classes</a></H3>
 
 
 <p>
@@ -1925,7 +1901,7 @@ function.   This allows objects to be encapsulated objects that look a lot like
 as shown in the last section.
 </p>
 
-<H3><a name="Tcl_nn31">36.4.2 Memory management</a></H3>
+<H3><a name="Tcl_nn31">37.4.2 Memory management</a></H3>
 
 
 <p>
@@ -2113,7 +2089,7 @@ typemaps--an advanced topic discussed later.
 </p>
 
 
-<H2><a name="Tcl_nn32">36.5 Input and output parameters</a></H2>
+<H2><a name="Tcl_nn32">37.5 Input and output parameters</a></H2>
 
 
 <p>
@@ -2235,7 +2211,7 @@ as well as a special error code:
 <div class="code">
 <pre>
 /* send message, return number of bytes sent, along with success code */
-int send_message(char *text, int len, int *success);
+int send_message(char *text, int *success);
 </pre>
 </div>
 
@@ -2301,7 +2277,7 @@ set c  [lindex $dim 1]
 </pre>
 </div>
 
-<H2><a name="Tcl_nn33">36.6 Exception handling </a></H2>
+<H2><a name="Tcl_nn33">37.6 Exception handling </a></H2>
 
 
 <p>
@@ -2435,7 +2411,7 @@ Since SWIG's exception handling is user-definable, you are not limited to C++ ex
 See the chapter on "<a href="Customization.html#Customization">Customization Features</a>" for more examples.
 </p>
 
-<H2><a name="Tcl_nn34">36.7 Typemaps</a></H2>
+<H2><a name="Tcl_nn34">37.7 Typemaps</a></H2>
 
 
 <p>
@@ -2452,7 +2428,7 @@ Typemaps are only used if you want to change some aspect of the primitive
 C-Tcl interface.
 </p>
 
-<H3><a name="Tcl_nn35">36.7.1 What is a typemap?</a></H3>
+<H3><a name="Tcl_nn35">37.7.1 What is a typemap?</a></H3>
 
 
 <p>
@@ -2572,7 +2548,7 @@ parameter is omitted):
 </pre>
 </div>
 
-<H3><a name="Tcl_nn36">36.7.2 Tcl typemaps</a></H3>
+<H3><a name="Tcl_nn36">37.7.2 Tcl typemaps</a></H3>
 
 
 <p>
@@ -2710,7 +2686,7 @@ Initialize an argument to a value before any conversions occur.
 Examples of these methods will appear shortly.
 </p>
 
-<H3><a name="Tcl_nn37">36.7.3 Typemap variables</a></H3>
+<H3><a name="Tcl_nn37">37.7.3 Typemap variables</a></H3>
 
 
 <p>
@@ -2781,7 +2757,7 @@ properly assigned.
 The Tcl name of the wrapper function being created.
 </div>
 
-<H3><a name="Tcl_nn38">36.7.4 Converting  a Tcl list to a char ** </a></H3>
+<H3><a name="Tcl_nn38">37.7.4 Converting  a Tcl list to a char ** </a></H3>
 
 
 <p>
@@ -2804,16 +2780,14 @@ used as a <tt>char **</tt> object.
   }
   $1 = (char **) malloc((nitems+1)*sizeof(char *));
   for (i = 0; i &lt; nitems; i++) {
-    $1[i] = Tcl_GetStringFromObj(listobjv[i], 0);
+    $1[i] = Tcl_GetString(listobjv[i]);
   }
   $1[i] = 0;
 }
 
 // This gives SWIG some cleanup code that will get called after the function call
 %typemap(freearg) char ** {
-  if ($1) {
-    free($1);
-  }
+  free($1);
 }
 
 // Now a test functions
@@ -2843,7 +2817,7 @@ argv[2] = Larry
 3
 </pre></div>
 
-<H3><a name="Tcl_nn39">36.7.5 Returning values in arguments</a></H3>
+<H3><a name="Tcl_nn39">37.7.5 Returning values in arguments</a></H3>
 
 
 <p>
@@ -2885,7 +2859,7 @@ result, a Tcl function using these typemaps will work like this :
 %
 </pre></div>
 
-<H3><a name="Tcl_nn40">36.7.6 Useful functions</a></H3>
+<H3><a name="Tcl_nn40">37.7.6 Useful functions</a></H3>
 
 
 <p>
@@ -2961,7 +2935,7 @@ int      Tcl_IsShared(Tcl_Obj *obj);
 </pre>
 </div>
 
-<H3><a name="Tcl_nn41">36.7.7 Standard  typemaps</a></H3>
+<H3><a name="Tcl_nn41">37.7.7 Standard  typemaps</a></H3>
 
 
 <p>
@@ -3045,7 +3019,7 @@ work)
 </pre>
 </div>
 
-<H3><a name="Tcl_nn42">36.7.8 Pointer handling</a></H3>
+<H3><a name="Tcl_nn42">37.7.8 Pointer handling</a></H3>
 
 
 <p>
@@ -3127,13 +3101,12 @@ For example:
 </pre>
 </div>
 
-<H2><a name="Tcl_nn43">36.8 Turning a SWIG module into a Tcl Package.</a></H2>
+<H2><a name="Tcl_nn43">37.8 Turning a SWIG module into a Tcl Package.</a></H2>
 
 
 <p>
-Tcl 7.4 introduced the idea of an extension package.  By default, SWIG
-generates all of the code necessary to create a package. To set the package version,
-simply use the <tt>-pkgversion</tt> option. For example:
+SWIG generates all of the code necessary to create a Tcl extension package.
+To set the package version use the <tt>-pkgversion</tt> option. For example:
 </p>
 
 <div class="code">
@@ -3144,7 +3117,7 @@ simply use the <tt>-pkgversion</tt> option. For example:
 
 <p>
 After building the SWIG generated module, you need to execute
-the "<tt>pkg_mkIndex</tt>" command inside tclsh.  For example :
+the <tt>pkg_mkIndex</tt> command inside tclsh.  For example :
 </p>
 
 <div class="code"><pre>
@@ -3199,7 +3172,7 @@ As a final note, most SWIG examples do not yet use the
 to use the <tt>load</tt> command instead.
 </p>
 
-<H2><a name="Tcl_nn44">36.9 Building new kinds of Tcl interfaces (in Tcl)</a></H2>
+<H2><a name="Tcl_nn44">37.9 Building new kinds of Tcl interfaces (in Tcl)</a></H2>
 
 
 <p>
@@ -3298,7 +3271,7 @@ danger of blowing something up (although it is easily accomplished
 with an out of bounds array access).
 </p>
 
-<H3><a name="Tcl_nn45">36.9.1 Proxy classes</a></H3>
+<H3><a name="Tcl_nn45">37.9.1 Proxy classes</a></H3>
 
 
 <p>
@@ -3419,12 +3392,12 @@ short, but clever Tcl script can be combined with SWIG to do many
 interesting things.
 </p>
 
-<H2><a name="Tcl_nn46">36.10 Tcl/Tk Stubs</a></H2>
+<H2><a name="Tcl_nn46">37.10 Tcl/Tk Stubs</a></H2>
 
 
 <p>
 For background information about the Tcl Stubs feature, see
-<a href="http://www.tcl.tk/doc/howto/stubs.html">http://www.tcl.tk/doc/howto/stubs.html</a>.
+<a href="https://www.tcl.tk/doc/howto/stubs.html">https://www.tcl.tk/doc/howto/stubs.html</a>.
 </p>
 
 <p>
@@ -3434,11 +3407,17 @@ feature if compiled with <tt>-DUSE_TCL_STUBS</tt>.
 
 <p>
 As of SWIG 1.3.40, the generated C/C++ wrapper will use the Tk Stubs
-feature if compiled with <tt>-DUSE_TK_STUBS</tt>.  Also, you can override
-the minimum version to support which is passed to <tt>Tcl_InitStubs()</tt>
-and <tt>Tk_InitStubs()</tt> with <tt>-DSWIG_TCL_STUBS_VERSION="8.3"</tt>
-or the version being compiled with using
-<tt>-DSWIG_TCL_STUBS_VERSION=TCL_VERSION</tt>.
+feature if compiled with <tt>-DUSE_TK_STUBS</tt>.
+</p>
+
+<p>
+By default SWIG sets the minimum Tcl version to support to the 8.4
+as that's the minimum Tcl version we aim to support (since SWIG 4.1.0; before
+this SWIG set it to 8.1, which was the first Tcl version with the stubs
+mechanism). This minimum version is passed to <tt>Tcl_InitStubs()</tt> and
+<tt>Tk_InitStubs()</tt>. You can override with a specific version using
+<tt>-DSWIG_TCL_STUBS_VERSION="8.5"</tt> or set it to the Tcl version being
+compiled with using <tt>-DSWIG_TCL_STUBS_VERSION=TCL_VERSION</tt>.
 </p>
 
 </body>

Doc/Manual/Typemaps.html

@@ -7,7 +7,7 @@
 </head>
 
 <body bgcolor="#ffffff">
-<H1><a name="Typemaps">13 Typemaps</a></H1>
+<H1><a name="Typemaps">14 Typemaps</a></H1>
 <!-- INDEX -->
 <div class="sectiontoc">
 <ul>
@@ -48,6 +48,7 @@
 <ul>
 <li><a href="#Typemaps_special_macro_descriptor">$descriptor(type)</a>
 <li><a href="#Typemaps_special_macro_typemap">$typemap(method, typepattern)</a>
+<li><a href="#Typemaps_special_macro_typemap_attribute">$typemap(method:attribute, typepattern)</a>
 </ul>
 <li><a href="#Typemaps_special_variable_attributes">Special variables and typemap attributes</a>
 <li><a href="#Typemaps_special_variables_and_macros">Special variables combined with special variable macros</a>
@@ -102,7 +103,7 @@
 
 
 
-<H2><a name="Typemaps_nn2">13.1 Introduction</a></H2>
+<H2><a name="Typemaps_nn2">14.1 Introduction</a></H2>
 
 
 <p>
@@ -119,7 +120,7 @@ to re-read the earlier chapters if you have found your way to this
 chapter with only a vague idea of what SWIG already does by default.
 </p>
 
-<H3><a name="Typemaps_nn3">13.1.1 Type conversion</a></H3>
+<H3><a name="Typemaps_nn3">14.1.1 Type conversion</a></H3>
 
 
 <p>
@@ -212,7 +213,7 @@ to read the extension documentation for your favorite language to know
 how it works (an exercise left to the reader).
 </p>
 
-<H3><a name="Typemaps_nn4">13.1.2 Typemaps</a></H3>
+<H3><a name="Typemaps_nn4">14.1.2 Typemaps</a></H3>
 
 
 <p>
@@ -313,7 +314,7 @@ parts of the generated wrapper functions.   Because arbitrary code can be insert
 possible to completely change the way in which values are converted.
 </p>
 
-<H3><a name="Typemaps_nn5">13.1.3 Pattern matching</a></H3>
+<H3><a name="Typemaps_nn5">14.1.3 Pattern matching</a></H3>
 
 
 <p>
@@ -415,7 +416,7 @@ In this case, a single input object is expanded into a pair of C arguments.  Thi
 provides a hint to the unusual variable naming scheme involving <tt>$1</tt>, <tt>$2</tt>, and so forth.
 </p>
 
-<H3><a name="Typemaps_nn6">13.1.4 Reusing typemaps</a></H3>
+<H3><a name="Typemaps_nn6">14.1.4 Reusing typemaps</a></H3>
 
 
 <p>
@@ -493,7 +494,7 @@ typedef int size_t;
 then SWIG already knows that the <tt>int</tt> typemaps apply.  You don't have to do anything.
 </p>
 
-<H3><a name="Typemaps_nn7">13.1.5 What can be done with typemaps?</a></H3>
+<H3><a name="Typemaps_nn7">14.1.5 What can be done with typemaps?</a></H3>
 
 
 <p>
@@ -605,7 +606,7 @@ typemaps that expand upon this list.  For example, the Java module defines a var
 aspects of the Java bindings.  Consult language specific documentation for further details.
 </p>
 
-<H3><a name="Typemaps_nn8">13.1.6 What can't be done with typemaps?</a></H3>
+<H3><a name="Typemaps_nn8">14.1.6 What can't be done with typemaps?</a></H3>
 
 
 <p>
@@ -668,7 +669,7 @@ void wrap_foo(char *s, int x) {
 </pre>
 </div>
 
-<H3><a name="Typemaps_aspects">13.1.7 Similarities to Aspect Oriented Programming</a></H3>
+<H3><a name="Typemaps_aspects">14.1.7 Similarities to Aspect Oriented Programming</a></H3>
 
 
 <p>
@@ -686,7 +687,7 @@ SWIG can also be viewed as has having a second set of aspects based around <a hr
 Features such as <tt>%exception</tt> are also cross-cutting concerns as they encapsulate code that can be used to add logging or exception handling to any function.
 </p>
 
-<H3><a name="Typemaps_nn9">13.1.8 The rest of this chapter</a></H3>
+<H3><a name="Typemaps_nn9">14.1.8 The rest of this chapter</a></H3>
 
 
 <p>
@@ -706,14 +707,14 @@ of "The C Programming Language" by Kernighan and Ritchie or
 "The C++ Programming Language" by Stroustrup before going any further.
 </p>
 
-<H2><a name="Typemaps_nn10">13.2 Typemap specifications</a></H2>
+<H2><a name="Typemaps_nn10">14.2 Typemap specifications</a></H2>
 
 
 <p>
 This section describes the behavior of the <tt>%typemap</tt> directive itself.
 </p>
 
-<H3><a name="Typemaps_defining">13.2.1 Defining a typemap</a></H3>
+<H3><a name="Typemaps_defining">14.2.1 Defining a typemap</a></H3>
 
 
 <p>
@@ -786,7 +787,7 @@ Here are some examples of valid typemap specifications:
 %typemap(in) int {
   $1 = PyInt_AsLong($input);
 }
-%typemap(in) int "$1 = PyInt_AsLong($input);";
+%typemap(in) int "$1 = PyInt_AsLong($input);"
 %typemap(in) int %{ 
   $1 = PyInt_AsLong($input);
 %}
@@ -802,7 +803,7 @@ Here are some examples of valid typemap specifications:
 }
 
 /* Typemap with modifiers */
-%typemap(in, doc="integer") int "$1 = scm_to_int($input);";
+%typemap(in, doc="integer") int "$1 = scm_to_int($input);"
 
 /* Typemap applied to patterns of multiple arguments */
 %typemap(in) (char *str, int len),
@@ -826,7 +827,7 @@ Admittedly, it's not the most readable syntax at first glance.  However, the pur
 individual pieces will become clear.
 </p>
 
-<H3><a name="Typemaps_nn12">13.2.2 Typemap scope</a></H3>
+<H3><a name="Typemaps_nn12">14.2.2 Typemap scope</a></H3>
 
 
 <p>
@@ -876,7 +877,7 @@ class Foo {
 </pre>
 </div>
 
-<H3><a name="Typemaps_nn13">13.2.3 Copying a typemap</a></H3>
+<H3><a name="Typemaps_nn13">14.2.3 Copying a typemap</a></H3>
 
 
 <p>
@@ -934,7 +935,7 @@ The patterns for <tt>%apply</tt> follow the same rules as for <tt>%typemap</tt>.
 </pre>
 </div>
 
-<H3><a name="Typemaps_nn14">13.2.4 Deleting a typemap</a></H3>
+<H3><a name="Typemaps_nn14">14.2.4 Deleting a typemap</a></H3>
 
 
 <p>
@@ -968,7 +969,7 @@ For example:
 after the clear operation.
 </p>
 
-<H3><a name="Typemaps_nn15">13.2.5 Placement of typemaps</a></H3>
+<H3><a name="Typemaps_nn15">14.2.5 Placement of typemaps</a></H3>
 
 
 <p>
@@ -1048,7 +1049,7 @@ It should be noted that for scoping to work, SWIG has to know that <tt>string</t
 within a particular namespace.  In this example, this is done using the forward class declaration <tt>class string</tt>.
 </p>
 
-<H2><a name="Typemaps_pattern_matching">13.3 Pattern matching rules</a></H2>
+<H2><a name="Typemaps_pattern_matching">14.3 Pattern matching rules</a></H2>
 
 
 <p>
@@ -1056,13 +1057,15 @@ The section describes the pattern matching rules by which C/C++ datatypes are as
 The matching rules can be observed in practice by using the debugging options also described.
 </p>
 
-<H3><a name="Typemaps_nn17">13.3.1 Basic matching rules</a></H3>
+<H3><a name="Typemaps_nn17">14.3.1 Basic matching rules</a></H3>
 
 
 <p>
-Typemaps are matched using both a type and a name (typically the name of a argument).  For a given
-<tt>TYPE NAME</tt> pair, the following rules are applied, in order, to find a match.  The first typemap found
-is used.
+Typemaps are matched using both a type and a name (typically the name of an
+argument, but in the case of <tt>out</tt> typemaps, the name of a function,
+qualified by the class name if it's a class method).  For a given <tt>TYPE
+NAME</tt> pair, the following rules are applied, in order, to find a match.
+The first typemap found is used.
 </p>
 
 <ul>
@@ -1155,7 +1158,7 @@ void F(int x[1000]);   // int [ANY] rule    (typemap 5)
 stripped all qualifiers in one step.
 </p>
 
-<H3><a name="Typemaps_typedef_reductions">13.3.2 Typedef reductions matching</a></H3>
+<H3><a name="Typemaps_typedef_reductions">14.3.2 Typedef reductions matching</a></H3>
 
 
 <p>
@@ -1330,7 +1333,7 @@ void go(Struct aStruct);
 </pre>
 </div>
 
-<H3><a name="Typemaps_nn19">13.3.3 Default typemap matching rules</a></H3>
+<H3><a name="Typemaps_nn19">14.3.3 Default typemap matching rules</a></H3>
 
 
 <p>
@@ -1353,13 +1356,13 @@ const reference are written like this:
 
 <div class="code">
 <pre>
-%typemap(in) int           "... convert to int ...";
-%typemap(in) short         "... convert to short ...";
-%typemap(in) float         "... convert to float ...";
+%typemap(in) int           "... convert to int ..."
+%typemap(in) short         "... convert to short ..."
+%typemap(in) float         "... convert to float ..."
 ...
-%typemap(in) const int &amp;   "... convert ...";
-%typemap(in) const short &amp; "... convert ...";
-%typemap(in) const float &amp; "... convert ...";
+%typemap(in) const int &amp;   "... convert ..."
+%typemap(in) const short &amp; "... convert ..."
+%typemap(in) const float &amp; "... convert ..."
 ...
 </pre>
 </div>
@@ -1379,16 +1382,16 @@ Below is a list of the typical default types supplied by language modules, showi
 
 <div class="code">
 <pre>
-%typemap(in) SWIGTYPE &amp;            { ... default reference handling ...                       };
-%typemap(in) SWIGTYPE *            { ... default pointer handling ...                         };
-%typemap(in) SWIGTYPE *const       { ... default pointer const handling ...                   };
-%typemap(in) SWIGTYPE *const&amp;      { ... default pointer const reference handling ...         };
-%typemap(in) SWIGTYPE[ANY]         { ... 1D fixed size arrays handling ...                    };
-%typemap(in) SWIGTYPE []           { ... unknown sized array handling ...                     };
-%typemap(in) enum SWIGTYPE         { ... default handling for enum values ...                 };
-%typemap(in) const enum SWIGTYPE &amp; { ... default handling for const enum reference values ... };
-%typemap(in) SWIGTYPE (CLASS::*)   { ... default pointer member handling ...                  };
-%typemap(in) SWIGTYPE              { ... simple default handling ...                          };
+%typemap(in) SWIGTYPE &amp;            { ... default reference handling ...                       }
+%typemap(in) SWIGTYPE *            { ... default pointer handling ...                         }
+%typemap(in) SWIGTYPE *const       { ... default pointer const handling ...                   }
+%typemap(in) SWIGTYPE *const&amp;      { ... default pointer const reference handling ...         }
+%typemap(in) SWIGTYPE[ANY]         { ... 1D fixed size arrays handling ...                    }
+%typemap(in) SWIGTYPE []           { ... unknown sized array handling ...                     }
+%typemap(in) enum SWIGTYPE         { ... default handling for enum values ...                 }
+%typemap(in) const enum SWIGTYPE &amp; { ... default handling for const enum reference values ... }
+%typemap(in) SWIGTYPE (CLASS::*)   { ... default pointer member handling ...                  }
+%typemap(in) SWIGTYPE              { ... simple default handling ...                          }
 </pre>
 </div>
 
@@ -1468,7 +1471,7 @@ Finally the best way to view the typemap matching rules in action is via the <a
 simpler scheme to match the current C++ class template partial specialization matching rules.
 </p>
 
-<H3><a name="Typemaps_multi_argument_typemaps_patterns">13.3.4 Multi-arguments typemaps</a></H3>
+<H3><a name="Typemaps_multi_argument_typemaps_patterns">14.3.4 Multi-arguments typemaps</a></H3>
 
 
 <p>
@@ -1498,7 +1501,7 @@ but all subsequent arguments must match exactly.
 </p>
 
 
-<H3><a name="Typemaps_matching_template_comparison">13.3.5 Matching rules compared to C++ templates</a></H3>
+<H3><a name="Typemaps_matching_template_comparison">14.3.5 Matching rules compared to C++ templates</a></H3>
 
 
 <p>
@@ -1657,7 +1660,7 @@ are similar to those for specialized template handling.
 </p>
 
 
-<H3><a name="Typemaps_debugging_search">13.3.6 Debugging typemap pattern matching</a></H3>
+<H3><a name="Typemaps_debugging_search">14.3.6 Debugging typemap pattern matching</a></H3>
 
 
 <p>
@@ -1870,7 +1873,7 @@ Also the types may be displayed slightly differently - <tt>char const *</tt> and
 </li>
 </ul>
 
-<H2><a name="Typemaps_nn21">13.4 Code generation rules</a></H2>
+<H2><a name="Typemaps_nn21">14.4 Code generation rules</a></H2>
 
 
 <p>
@@ -1878,7 +1881,7 @@ This section describes rules by which typemap code is inserted into
 the generated wrapper code.
 </p>
 
-<H3><a name="Typemaps_nn22">13.4.1 Scope</a></H3>
+<H3><a name="Typemaps_nn22">14.4.1 Scope</a></H3>
 
 
 <p>
@@ -1940,7 +1943,7 @@ Occasionally, typemap code will be specified using a few alternative forms.  For
 
 <div class="code">
 <pre>
-%typemap(in) int "$1 = PyInt_AsLong($input);";
+%typemap(in) int "$1 = PyInt_AsLong($input);"
 %typemap(in) int %{
 $1 = PyInt_AsLong($input);
 %}
@@ -1956,7 +1959,7 @@ a block scope when it is emitted.   This sometimes results in a less complicated
 Note that only the third of the three typemaps have the typemap code passed through the SWIG preprocessor.
 </p>
 
-<H3><a name="Typemaps_nn23">13.4.2 Declaring new local variables</a></H3>
+<H3><a name="Typemaps_nn23">14.4.2 Declaring new local variables</a></H3>
 
 
 <p>
@@ -2123,7 +2126,7 @@ each type must have its own local variable declaration.
 </div>
 
 
-<H3><a name="Typemaps_special_variables">13.4.3 Special variables</a></H3>
+<H3><a name="Typemaps_special_variables">14.4.3 Special variables</a></H3>
 
 
 <p>
@@ -2375,7 +2378,7 @@ Another approach, which only works for arrays is to use the <tt>$1_basetype</tt>
 </pre>
 </div>
 
-<H3><a name="Typemaps_special_variable_macros">13.4.4 Special variable macros</a></H3>
+<H3><a name="Typemaps_special_variable_macros">14.4.4 Special variable macros</a></H3>
 
 
 <p>
@@ -2387,7 +2390,7 @@ it is done during the SWIG parsing/compilation stages.
 The following special variable macros are available across all language modules.
 </p>
 
-<H4><a name="Typemaps_special_macro_descriptor">13.4.4.1 $descriptor(type)</a></H4>
+<H4><a name="Typemaps_special_macro_descriptor">14.4.4.1 $descriptor(type)</a></H4>
 
 
 <p>
@@ -2398,7 +2401,7 @@ For example, <tt>$descriptor(std::vector&lt;int&gt; *)</tt> will expand into <tt
 This macro is mostly used in the scripting target languages and is demonstrated later in the <a href="#Typemaps_runtime_type_checker_usage">Run-time type checker usage</a> section.
 </p>
 
-<H4><a name="Typemaps_special_macro_typemap">13.4.4.2 $typemap(method, typepattern)</a></H4>
+<H4><a name="Typemaps_special_macro_typemap">14.4.4.2 $typemap(method, typepattern)</a></H4>
 
 
 <p>
@@ -2455,8 +2458,43 @@ The result is the following expansion
 </pre>
 </div>
 
+<H4><a name="Typemaps_special_macro_typemap_attribute">14.4.4.3 $typemap(method:attribute, typepattern)</a></H4>
 
-<H3><a name="Typemaps_special_variable_attributes">13.4.5 Special variables and typemap attributes</a></H3>
+
+<p>
+An enhanced version of <tt>$typemap</tt> provides access to typemap attributes by
+appending a colon and the attribute name after the method name. In the example below,
+"cstype" is the typemap method and "out" is the typemap attribute.
+</p>
+
+<div class="code">
+<pre>
+%typemap(cstype, out="object") XClass "XClass"
+%typemap(cscode) BarClass %{
+  $typemap(cstype:out, XClass) bar()
+  {
+    return null;
+  }
+</pre>
+</div>
+<p>
+which expands to
+</p>
+<div class="code">
+<pre>
+  object bar()
+  {
+    return null;
+  }
+</pre>
+</div>
+
+<p>
+<b>Compatibility note: </b> Support for typemap attributes in <tt>$typemap</tt>
+was introduced in SWIG-4.1.0.
+</p>
+
+<H3><a name="Typemaps_special_variable_attributes">14.4.5 Special variables and typemap attributes</a></H3>
 
 
 <p>
@@ -2483,7 +2521,7 @@ is equivalent to the following as <tt>$*1_ltype</tt> expands to <tt>unsigned int
 </pre>
 </div>
 
-<H3><a name="Typemaps_special_variables_and_macros">13.4.6 Special variables combined with special variable macros</a></H3>
+<H3><a name="Typemaps_special_variables_and_macros">14.4.6 Special variables combined with special variable macros</a></H3>
 
 
 <p>
@@ -2525,7 +2563,7 @@ which then expands to:
 </div>
 
 
-<H2><a name="Typemaps_nn25">13.5 Common typemap methods</a></H2>
+<H2><a name="Typemaps_nn25">14.5 Common typemap methods</a></H2>
 
 
 <p>
@@ -2533,7 +2571,7 @@ The family of typemaps recognized by a language module may vary.  However,
 the following typemap methods are nearly universal:
 </p>
 
-<H3><a name="Typemaps_nn26">13.5.1 "in" typemap</a></H3>
+<H3><a name="Typemaps_nn26">14.5.1 "in" typemap</a></H3>
 
 
 <p>
@@ -2588,12 +2626,7 @@ Usually <tt>numinputs</tt> is not specified, whereupon the default value is 1, t
 <a href="#Typemaps_multi_argument_typemaps">Multi-argument typemaps</a> provide a similar concept where the number of arguments mapped from the target language to C/C++ can be changed for multiple adjacent C/C++ arguments.
 </p>
 
-<p>
-<b>Compatibility note: </b> Specifying <tt>numinputs=0</tt>
-is the same as the old "ignore" typemap.
-</p>
-
-<H3><a name="Typemaps_nn27">13.5.2 "typecheck" typemap</a></H3>
+<H3><a name="Typemaps_nn27">14.5.2 "typecheck" typemap</a></H3>
 
 
 <p>
@@ -2620,7 +2653,7 @@ If you define new "in" typemaps <em>and</em> your program uses overloaded method
 "typecheck" typemaps.  More details about this follow in the <a href="#Typemaps_overloading">Typemaps and overloading</a> section.
 </p>
 
-<H3><a name="Typemaps_nn28">13.5.3 "out" typemap</a></H3>
+<H3><a name="Typemaps_nn28">14.5.3 "out" typemap</a></H3>
 
 
 <p>
@@ -2651,7 +2684,7 @@ $symname          - Name of function/method being wrapped
 The "out" typemap supports an optional attribute flag called "optimal". This is for code optimisation and is detailed in the <a href="#Typemaps_optimal">Optimal code generation when returning by value</a> section.
 </p>
 
-<H3><a name="Typemaps_nn29">13.5.4 "arginit" typemap</a></H3>
+<H3><a name="Typemaps_nn29">14.5.4 "arginit" typemap</a></H3>
 
 
 <p>
@@ -2670,7 +2703,7 @@ For example:
 </pre>
 </div>
 
-<H3><a name="Typemaps_nn30">13.5.5 "default" typemap</a></H3>
+<H3><a name="Typemaps_nn30">14.5.5 "default" typemap</a></H3>
 
 
 <p>
@@ -2703,7 +2736,7 @@ See the <a href="SWIG.html#SWIG_default_args">Default/optional arguments</a> sec
 for further information on default argument wrapping.
 </p>
 
-<H3><a name="Typemaps_nn31">13.5.6 "check" typemap</a></H3>
+<H3><a name="Typemaps_nn31">14.5.6 "check" typemap</a></H3>
 
 
 <p>
@@ -2722,7 +2755,7 @@ converted.  For example:
 </pre>
 </div>
 
-<H3><a name="Typemaps_nn32">13.5.7 "argout" typemap</a></H3>
+<H3><a name="Typemaps_nn32">14.5.7 "argout" typemap</a></H3>
 
 
 <p>
@@ -2768,7 +2801,7 @@ return values are often appended to return value of the function.
 See the <tt>typemaps.i</tt> library file for examples.
 </p>
 
-<H3><a name="Typemaps_nn33">13.5.8 "freearg" typemap</a></H3>
+<H3><a name="Typemaps_nn33">14.5.8 "freearg" typemap</a></H3>
 
 
 <p>
@@ -2801,7 +2834,7 @@ be used in other typemaps whenever a wrapper function needs to abort
 prematurely.
 </p>
 
-<H3><a name="Typemaps_nn34">13.5.9 "newfree" typemap</a></H3>
+<H3><a name="Typemaps_nn34">14.5.9 "newfree" typemap</a></H3>
 
 
 <p>
@@ -2830,7 +2863,7 @@ string *foo();
 See <a href="Customization.html#Customization_ownership">Object ownership and %newobject</a> for further details.
 </p>
 
-<H3><a name="Typemaps_ret">13.5.10 "ret" typemap</a></H3>
+<H3><a name="Typemaps_ret">14.5.10 "ret" typemap</a></H3>
 
 
 <p>
@@ -2869,7 +2902,7 @@ This approach is an alternative to using the "newfree" typemap and <tt>%newobjec
 is no need to list all the functions that require the memory cleanup, it is purely done on types.
 </p>
 
-<H3><a name="Typemaps_nn35">13.5.11 "memberin" typemap</a></H3>
+<H3><a name="Typemaps_nn35">14.5.11 "memberin" typemap</a></H3>
 
 
 <p>
@@ -2891,7 +2924,7 @@ It is rarely necessary to write "memberin" typemaps---SWIG already provides
 a default implementation for arrays, strings, and other objects.
 </p>
 
-<H3><a name="Typemaps_nn36">13.5.12 "varin" typemap</a></H3>
+<H3><a name="Typemaps_nn36">14.5.12 "varin" typemap</a></H3>
 
 
 <p>
@@ -2899,7 +2932,7 @@ The "varin" typemap is used to convert objects in the target language to C for t
 purposes of assigning to a C/C++ global variable.    This is implementation specific.
 </p>
 
-<H3><a name="Typemaps_nn37">13.5.13 "varout" typemap</a></H3>
+<H3><a name="Typemaps_nn37">14.5.13 "varout" typemap</a></H3>
 
 
 <p>
@@ -2907,7 +2940,7 @@ The "varout" typemap is used to convert a C/C++ object to an object in the targe
 language when reading a C/C++ global variable.  This is implementation specific.
 </p>
 
-<H3><a name="Typemaps_throws_typemap">13.5.14 "throws" typemap</a></H3>
+<H3><a name="Typemaps_throws_typemap">14.5.14 "throws" typemap</a></H3>
 
 
 <p>
@@ -2957,7 +2990,7 @@ Note that if your methods do not have an exception specification but they do thr
 Please also see the <a href="Customization.html#Customization_exception">Exception handling with %exception</a> section for another way to handle exceptions.
 </p>
 
-<H2><a name="Typemaps_nn39">13.6 Some typemap examples</a></H2>
+<H2><a name="Typemaps_nn39">14.6 Some typemap examples</a></H2>
 
 
 <p>
@@ -2965,7 +2998,7 @@ This section contains a few examples.  Consult language module documentation
 for more examples.
 </p>
 
-<H3><a name="Typemaps_nn40">13.6.1 Typemaps for arrays</a></H3>
+<H3><a name="Typemaps_nn40">14.6.1 Typemaps for arrays</a></H3>
 
 
 <p>
@@ -3103,7 +3136,7 @@ as shown.   To work with heap allocated data, the following technique can be use
   }
 }
 %typemap(freearg) float value[ANY] {
-  if ($1) free($1);
+  free($1);
 }
 </pre>
 </div>
@@ -3224,7 +3257,7 @@ Now, you will find that member access is quite nice:
 useless and has since been eliminated.   To return structure members, simply use the "out" typemap.
 </p>
 
-<H3><a name="Typemaps_nn41">13.6.2 Implementing constraints with typemaps</a></H3>
+<H3><a name="Typemaps_nn41">14.6.2 Implementing constraints with typemaps</a></H3>
 
 
 <p>
@@ -3272,7 +3305,7 @@ a NULL pointer. As a result, SWIG can often prevent a potential
 segmentation faults or other run-time problems by raising an exception
 rather than blindly passing values to the underlying C/C++ program.</p>
 
-<H2><a name="Typemaps_nn43">13.7 Typemaps for multiple target languages</a></H2>
+<H2><a name="Typemaps_nn43">14.7 Typemaps for multiple target languages</a></H2>
 
 
 <p>
@@ -3298,11 +3331,11 @@ The example above also shows a common approach of issuing a warning for an as ye
 </p>
 
 <p>
-<b>Compatibility note: </b> In SWIG-1.1 different languages could be distinguished with the language name being put within the <tt>%typemap</tt> directive, for example, <br>
+<b>Compatibility note: </b> In SWIG-1.1 different languages could be distinguished with the language name being put within the <tt>%typemap</tt> directive, but this was deprecated in SWIG 1.3.28 and support finally dropped completely in SWIG 4.1.0 so you'll need to update any remaining uses to use the approach above.  For example, <br>
 <tt>%typemap(ruby, in) int "$1 = NUM2INT($input);"</tt>.
 </p>
 
-<H2><a name="Typemaps_optimal">13.8 Optimal code generation when returning by value</a></H2>
+<H2><a name="Typemaps_optimal">14.8 Optimal code generation when returning by value</a></H2>
 
 
 <p>
@@ -3326,7 +3359,7 @@ Consider running the following code through SWIG:
 <div class="code">
 <pre>
 %typemap(out) SWIGTYPE %{
-  $result = new $1_ltype((const $1_ltype &amp;)$1);
+  $result = new $1_ltype($1);
 %}
 
 %inline %{
@@ -3376,7 +3409,7 @@ If the typemap code is kept the same and just the "optimal" attribute specified
 <div class="code">
 <pre>
 %typemap(out, optimal="1") SWIGTYPE %{
-  $result = new $1_ltype((const $1_ltype &amp;)$1);
+  $result = new $1_ltype($1);
 %}
 </pre>
 </div>
@@ -3403,7 +3436,7 @@ SWIGEXPORT void * SWIGSTDCALL CSharp_XX_create() {
   void * jresult ;
   XX result;
   result = XX::create();
-  jresult = new XX((const XX &amp;)result);
+  jresult = new XX(result);
   return jresult;
 }
 
@@ -3418,7 +3451,7 @@ With the "optimal" attribute, the code is:
 <pre>
 SWIGEXPORT void * SWIGSTDCALL CSharp_XX_create() {
   void * jresult ;
-  jresult = new XX((const XX &amp;)XX::create());
+  jresult = new XX(XX::create());
   return jresult;
 }
 </pre>
@@ -3475,7 +3508,7 @@ It should be clear that the above code cannot be used as the argument to the cop
 </p>
 
 <p>
-Secondly, if the typemaps uses <tt>$1</tt> more than once, then multiple calls to the wrapped function
+Secondly, if the typemap uses <tt>$1</tt> more than once, then multiple calls to the wrapped function
 will be made. Obviously that is not very optimal.
 In fact SWIG attempts to detect this and will issue a warning something like:
 </p>
@@ -3491,7 +3524,7 @@ example.i:7: Warning 475: optimal attribute usage in the out typemap.
 However, it doesn't always get it right, for example when <tt>$1</tt> is within some commented out code.
 </p>
 
-<H2><a name="Typemaps_multi_argument_typemaps">13.9 Multi-argument typemaps</a></H2>
+<H2><a name="Typemaps_multi_argument_typemaps">14.9 Multi-argument typemaps</a></H2>
 
 
 <p>
@@ -3556,7 +3589,7 @@ maps perform the conversion described for the above example:
 }
 
 %typemap(freearg) (int argc, char *argv[]) {
-  if ($2) free($2);
+  free($2);
 }
 
 /* Required for C++ method overloading */
@@ -3768,7 +3801,7 @@ with non-consecutive C/C++ arguments; a workaround such as a helper function re-
 the arguments to make them consecutive will need to be written.
 </p>
 
-<H2><a name="Typemaps_warnings">13.10 Typemap warnings</a></H2>
+<H2><a name="Typemaps_warnings">14.10 Typemap warnings</a></H2>
 
 
 <p>
@@ -3777,7 +3810,7 @@ See the information in the <a href="Warnings.html#Warnings_nn5">issuing warnings
 </p>
 
 
-<H2><a name="Typemaps_fragments">13.11 Typemap fragments</a></H2>
+<H2><a name="Typemaps_fragments">14.11 Typemap fragments</a></H2>
 
 
 <p>
@@ -3835,7 +3868,7 @@ To eliminate this, define a fragment that includes the common marshalling code:
 
 <p>
 When the "in" or "varin" typemaps for MyClass are required, the
-contents of the fragment called "AsMyClass" is added to the "header" section within the generated code, and then the
+contents of the fragment called "AsMyClass" are added to the "header" section within the generated code, and then the
 typemap code is emitted. Hence, the method <tt>AsMyClass</tt> will be
 generated into the wrapper code before any typemap code that calls it.
 </p>
@@ -3983,19 +4016,34 @@ inclusion of the other fragments.
 
 <li>
 <p>
-A typemap can also use more than one fragment, but since the
-syntax is different, you need to specify the dependent fragments in a comma separated
-list. Consider:
+A typemap can also use more than one fragment:
 </p>
-
 <div class="code">
 <pre>
-%typemap(in, fragment="frag1, frag2, frag3") {...}
+%typemap("in", fragment="frag1", fragment="frag2", fragment="frag3") {...}
 </pre>
 </div>
 
 <p>
-which is equivalent to:
+<b>Compatibility note: </b> The ability to use multiple
+<tt>fragment</tt> keys as shown above was introduced in SWIG-4.1.0.
+</p>
+
+<p>
+Multiple fragments can alternatively be specified as a comma
+separated list value in a single <tt>fragment</tt> key.
+Note that no whitespace is allowed within this comma separated list.
+The following is the equivalent to the above:
+</p>
+
+<div class="code">
+<pre>
+%typemap(in, fragment="frag1,frag2,frag3") {...}
+</pre>
+</div>
+
+<p>
+which in turn is functionally equivalent to:
 </p>
 
 <div class="code">
@@ -4113,7 +4161,7 @@ fragment usage unless a desire to really get to grips
 with some powerful but tricky macro and fragment usage that is used in parts of the SWIG typemap library.
 </p>
 
-<H3><a name="Typemaps_fragment_type_specialization">13.11.1 Fragment type specialization</a></H3>
+<H3><a name="Typemaps_fragment_type_specialization">14.11.1 Fragment type specialization</a></H3>
 
 
 <p>
@@ -4146,7 +4194,7 @@ struct A {
 </pre>
 </div>
 
-<H3><a name="Typemaps_automatic_specialization">13.11.2 Fragments and automatic typemap specialization</a></H3>
+<H3><a name="Typemaps_automatic_specialization">14.11.2 Fragments and automatic typemap specialization</a></H3>
 
 
 <p>
@@ -4192,7 +4240,7 @@ The interested (or very brave) reader can take a look at the fragments.swg file
 </p>
 
 
-<H2><a name="Typemaps_runtime_type_checker">13.12 The run-time type checker</a></H2>
+<H2><a name="Typemaps_runtime_type_checker">14.12 The run-time type checker</a></H2>
 
 
 <p>
@@ -4218,7 +4266,7 @@ language modules.</li>
 <li>Modules can be unloaded from the type system.</li>
 </ul>
 
-<H3><a name="Typemaps_nn45">13.12.1 Implementation</a></H3>
+<H3><a name="Typemaps_nn45">14.12.1 Implementation</a></H3>
 
 
 <p>
@@ -4412,7 +4460,7 @@ structures rather than creating new ones.  These <tt>swig_module_info</tt>
 structures are chained together in a circularly linked list.
 </p>
 
-<H3><a name="Typemaps_runtime_type_checker_usage">13.12.2 Usage</a></H3>
+<H3><a name="Typemaps_runtime_type_checker_usage">14.12.2 Usage</a></H3>
 
 
 <p>This section covers how to use these functions from typemaps.  To learn how to
@@ -4508,7 +4556,7 @@ probably just look at the output of SWIG to get a better sense for how types are
 managed.
 </p>
 
-<H2><a name="Typemaps_overloading">13.13 Typemaps and overloading</a></H2>
+<H2><a name="Typemaps_overloading">14.13 Typemaps and overloading</a></H2>
 
 
 <p>
@@ -4847,7 +4895,7 @@ Subsequent "in" typemaps would then perform more extensive type-checking.
 </li>
 </ul>
 
-<H3><a name="Typemaps_typecheck_pointer">13.13.1 SWIG_TYPECHECK_POINTER precedence level and the typecheck typemap</a></H3>
+<H3><a name="Typemaps_typecheck_pointer">14.13.1 SWIG_TYPECHECK_POINTER precedence level and the typecheck typemap</a></H3>
 
 
 <p>
@@ -4949,7 +4997,7 @@ Otherwise both can be wrapped by removing the overloading name ambiguity by rena
 The 'equivalent' attribute is used in the implementation for the <a href="Library.html#Library_std_shared_ptr">shared_ptr smart pointer</a> library.
 </p>
 
-<H2><a name="Typemaps_nn48">13.14 More about %apply and %clear</a></H2>
+<H2><a name="Typemaps_nn48">14.14 More about %apply and %clear</a></H2>
 
 
 <p>
@@ -5054,7 +5102,7 @@ will delete the typemaps for all the typemap methods; namely "in", "check" and "
 </pre>
 </div>
 
-<H2><a name="Typemaps_nn47">13.15 Passing data between typemaps</a></H2>
+<H2><a name="Typemaps_nn47">14.15 Passing data between typemaps</a></H2>
 
 
 <p>
@@ -5091,7 +5139,7 @@ sure that the typemaps sharing information have exactly the same types and names
 </p>
 
 
-<H2><a name="Typemaps_nn52">13.16 C++ "this" pointer</a></H2>
+<H2><a name="Typemaps_nn52">14.16 C++ "this" pointer</a></H2>
 
 
 <p>
@@ -5151,7 +5199,7 @@ will also match the typemap.  One work around is to create an interface file tha
 the method, but gives the argument a name other than <tt>self</tt>.
 </p>
 
-<H2><a name="Typemaps_nn51">13.17 Where to go for more information?</a></H2>
+<H2><a name="Typemaps_nn51">14.17 Where to go for more information?</a></H2>
 
 
 <p>

Doc/Manual/Varargs.html

@@ -7,7 +7,7 @@
 </head>
 
 <body bgcolor="#ffffff">
-<H1><a name="Varargs">16 Variable Length Arguments</a></H1>
+<H1><a name="Varargs">17 Variable Length Arguments</a></H1>
 <!-- INDEX -->
 <div class="sectiontoc">
 <ul>
@@ -43,7 +43,7 @@ added in SWIG-1.3.12.  Most other wrapper generation tools have
 wisely chosen to avoid this issue.
 </p>
 
-<H2><a name="Varargs_nn2">16.1 Introduction</a></H2>
+<H2><a name="Varargs_nn2">17.1 Introduction</a></H2>
 
 
 <p>
@@ -140,7 +140,7 @@ List make_list(const char *s, ...) {
 </pre>
 </div>
 
-<H2><a name="Varargs_nn3">16.2 The Problem</a></H2>
+<H2><a name="Varargs_nn3">17.2 The Problem</a></H2>
 
 
 <p>
@@ -233,7 +233,7 @@ can also support real varargs wrapping (with stack-frame manipulation) if you
 are willing to get hands dirty.  Keep reading.
 </p>
 
-<H2><a name="Varargs_nn4">16.3 Default varargs support</a></H2>
+<H2><a name="Varargs_nn4">17.3 Default varargs support</a></H2>
 
 
 <p>
@@ -302,7 +302,7 @@ Read on for further solutions.
 </p>
 
 
-<H2><a name="Varargs_nn5">16.4 Argument replacement using %varargs</a></H2>
+<H2><a name="Varargs_nn5">17.4 Argument replacement using %varargs</a></H2>
 
 
 <p>
@@ -413,7 +413,7 @@ mixed argument types such as <tt>printf()</tt>.  Providing general purpose
 wrappers to such functions presents special problems (covered shortly).  
 </p>
 
-<H2><a name="Varargs_nn6">16.5 Varargs and typemaps</a></H2>
+<H2><a name="Varargs_nn6">17.5 Varargs and typemaps</a></H2>
 
 
 <p>
@@ -512,7 +512,7 @@ like this:
 <pre>
 %typemap(in) (...)(char *vargs[10]) {
   int i;
-  int argc;
+  Py_ssize_t argc;
   for (i = 0; i &lt; 10; i++) vargs[i] = 0;
   argc = PyTuple_Size(varargs);
   if (argc &gt; 10) {
@@ -523,6 +523,7 @@ like this:
     PyObject *pyobj = PyTuple_GetItem(varargs, i);
     char *str = 0;
 %#if PY_VERSION_HEX&gt;=0x03000000
+    const char *strtmp = 0;
     PyObject *pystr;
     if (!PyUnicode_Check(pyobj)) {
       PyErr_SetString(PyExc_ValueError, "Expected a string");
@@ -532,7 +533,10 @@ like this:
     if (!pystr) {
       SWIG_fail;
     }
-    str = strdup(PyBytes_AsString(pystr));
+    strtmp = PyBytes_AsString(pystr);
+    str = (char *)malloc(strlen(strtmp) + 1);
+    if (str)
+      strcpy(str, strtmp);
     Py_DECREF(pystr);
 %#else  
     if (!PyString_Check(pyobj)) {
@@ -593,7 +597,7 @@ really want to elevate your guru status and increase your job
 security, continue to the next section.
 </p>
 
-<H2><a name="Varargs_nn7">16.6 Varargs wrapping with libffi</a></H2>
+<H2><a name="Varargs_nn7">17.6 Varargs wrapping with libffi</a></H2>
 
 
 <p>
@@ -609,7 +613,7 @@ you need to bring out some bigger guns.
 <p>
 One way to do this is to use a special purpose library such as libffi
 (<a
-href="http://www.sourceware.org/libffi/">http://www.sourceware.org/libffi/</a>).
+href="https://www.sourceware.org/libffi/">https://www.sourceware.org/libffi/</a>).
 libffi is a library that allows you to dynamically construct
 call-stacks and invoke procedures in a relatively platform independent
 manner.  Details about the library can be found in the libffi
@@ -845,7 +849,7 @@ provide an argument number for the first extra argument.  This can be used to in
 values.   Please consult the chapter on each language module for more details.
 </p>
 
-<H2><a name="Varargs_nn8">16.7 Wrapping of va_list</a></H2>
+<H2><a name="Varargs_nn8">17.7 Wrapping of va_list</a></H2>
 
 
 <p>
@@ -899,7 +903,7 @@ int my_vprintf(const char *fmt, ...) {
 </pre>
 </div>
 
-<H2><a name="Varargs_nn9">16.8 C++ Issues</a></H2>
+<H2><a name="Varargs_nn9">17.8 C++ Issues</a></H2>
 
 
 <p>
@@ -968,7 +972,7 @@ design or to provide an alternative interface using a helper function than it is
 fully general wrapper to a varargs C++ member function.
 </p>
 
-<H2><a name="Varargs_nn10">16.9 Discussion</a></H2>
+<H2><a name="Varargs_nn10">17.9 Discussion</a></H2>
 
 
 <p>

Doc/Manual/Warnings.html

@@ -7,7 +7,7 @@
 </head>
 
 <body bgcolor="#ffffff">
-<H1><a name="Warnings">18 Warning Messages</a></H1>
+<H1><a name="Warnings">19 Warning Messages</a></H1>
 <!-- INDEX -->
 <div class="sectiontoc">
 <ul>
@@ -37,7 +37,7 @@
 
 
 
-<H2><a name="Warnings_nn2">18.1 Introduction</a></H2>
+<H2><a name="Warnings_nn2">19.1 Introduction</a></H2>
 
 
 <p>
@@ -57,7 +57,7 @@ where the generated wrapper code will probably compile, but it may not
 work like you expect.
 </p>
 
-<H2><a name="Warnings_suppression">18.2 Warning message suppression</a></H2>
+<H2><a name="Warnings_suppression">19.2 Warning message suppression</a></H2>
 
 
 <p>
@@ -149,7 +149,7 @@ your interface.  Ignore the warning messages at your own peril.
 </p>
 
 
-<H2><a name="Warnings_nn4">18.3 Enabling extra warnings</a></H2>
+<H2><a name="Warnings_nn4">19.3 Enabling extra warnings</a></H2>
 
 
 <p>
@@ -164,6 +164,15 @@ to provide additional diagnostics.  These warnings can be turned on using the
 </pre>
 </div>
 
+<p>
+Preprocessor warning 202 ("Could not evaluate expression <em>expr</em>.") was
+formally off by default and enabled by <tt>-Wextra</tt>, but since SWIG 4.1.0
+this warning is on by default because suppressing it tends to hide genuine
+problems.  If you really don't want to see it, you can suppress it with
+<tt>-w202</tt> or using <tt>%warnfilter</tt> as described below. Both will work
+with older versions of SWIG too.
+</p>
+
 <p>
 To selectively turn on extra warning messages, you can use the directives and options in the
 previous section--simply add a "+" to all warning numbers.  For example:
@@ -211,7 +220,7 @@ You can of course also enable all warnings and suppress a select few, for exampl
 </div>
 
 <p>
-The warnings on the right take precedence over the warnings on the left, so in the above example <tt>-Wextra</tt> adds numerous warnings including 452, but then <tt>-w309,452</tt> overrides this and so 452 is suppressesed.
+The warnings on the right take precedence over the warnings on the left, so in the above example <tt>-Wextra</tt> adds numerous warnings including 452, but then <tt>-w309,452</tt> overrides this and so 452 is suppressed.
 </p>
 
 <p>
@@ -222,7 +231,7 @@ that is, any warnings suppressed or added in <tt>%warnfilter</tt>, <tt>#pragma S
 or the <tt>-w</tt> option.
 </p>
 
-<H2><a name="Warnings_nn5">18.4 Issuing a warning message</a></H2>
+<H2><a name="Warnings_nn5">19.4 Issuing a warning message</a></H2>
 
 
 <p>
@@ -276,7 +285,7 @@ example.i:24: Warning 901: You are really going to regret this usage of blah * s
 </pre>
 </div>
 
-<H2><a name="Warnings_symbolic_symbols">18.5 Symbolic symbols</a></H2>
+<H2><a name="Warnings_symbolic_symbols">19.5 Symbolic symbols</a></H2>
 
 
 <p>
@@ -311,7 +320,7 @@ or
 </pre>
 </div>
 
-<H2><a name="Warnings_nn6">18.6 Commentary</a></H2>
+<H2><a name="Warnings_nn6">19.6 Commentary</a></H2>
 
 
 <p>
@@ -328,7 +337,7 @@ no obvious recovery.  There is no mechanism for suppressing error
 messages.
 </p>
 
-<H2><a name="Warnings_nn7">18.7 Warnings as errors</a></H2>
+<H2><a name="Warnings_nn7">19.7 Warnings as errors</a></H2>
 
 
 <p>
@@ -337,7 +346,7 @@ option. This will cause SWIG to exit with a non successful exit code if a
 warning is encountered.
 </p>
 
-<H2><a name="Warnings_nn8">18.8 Message output format</a></H2>
+<H2><a name="Warnings_nn8">19.8 Message output format</a></H2>
 
 
 <p>
@@ -356,38 +365,17 @@ $ swig -python -Fmicrosoft example.i
 example.i(4) : Syntax error in input(1).
 </pre></div>
 
-<H2><a name="Warnings_nn9">18.9 Warning number reference</a></H2>
+<H2><a name="Warnings_nn9">19.9 Warning number reference</a></H2>
 
 
-<H3><a name="Warnings_nn10">18.9.1 Deprecated features (100-199)</a></H3>
+<H3><a name="Warnings_nn10">19.9.1 Deprecated features (100-199)</a></H3>
 
 
 <ul>
-<li>101. Deprecated <tt>%extern</tt> directive.
-<li>102. Deprecated <tt>%val</tt> directive.
-<li>103. Deprecated <tt>%out</tt> directive.
-<li>104. Deprecated <tt>%disabledoc</tt> directive.
-<li>105. Deprecated <tt>%enabledoc</tt> directive.
-<li>106. Deprecated <tt>%doconly</tt> directive.
-<li>107. Deprecated <tt>%style</tt> directive.
-<li>108. Deprecated <tt>%localstyle</tt> directive.
-<li>109. Deprecated <tt>%title</tt> directive.
-<li>110. Deprecated <tt>%section</tt> directive.
-<li>111. Deprecated <tt>%subsection</tt> directive.
-<li>112. Deprecated <tt>%subsubsection</tt> directive.
-<li>113. Deprecated <tt>%addmethods</tt> directive.
-<li>114. Deprecated <tt>%readonly</tt> directive.
-<li>115. Deprecated <tt>%readwrite</tt> directive.
-<li>116. Deprecated <tt>%except</tt> directive.
-<li>117. Deprecated <tt>%new</tt> directive.
-<li>118. Deprecated <tt>%typemap(except)</tt>.
-<li>119. Deprecated <tt>%typemap(ignore)</tt>.
-<li>120. Deprecated command line option (-runtime, -noruntime).
-<li>121. Deprecated <tt>%name</tt> directive.
 <li>126. The 'nestedworkaround' feature is deprecated.
 </ul>
 
-<H3><a name="Warnings_nn11">18.9.2 Preprocessor (200-299)</a></H3>
+<H3><a name="Warnings_nn11">19.9.2 Preprocessor (200-299)</a></H3>
 
 
 <ul>
@@ -399,17 +387,15 @@ example.i(4) : Syntax error in input(1).
 <li>206. Unexpected tokens after #<em>directive</em> directive.
 </ul>
 
-<H3><a name="Warnings_nn12">18.9.3 C/C++ Parser (300-399)</a></H3>
+<H3><a name="Warnings_nn12">19.9.3 C/C++ Parser (300-399)</a></H3>
 
 
 <ul>
 <li>301. <tt>class</tt> keyword used, but not in C++ mode.
-<li>302. Identifier '<em>name</em>' redefined (ignored).
+<li>302. Redefinition of identifier '<em>name</em>' as <em>decl</em> ignored.
 <li>303. <tt>%extend</tt> defined for an undeclared class '<em>name</em>'.
-<li>304. Unsupported constant value (ignored).
 <li>305. Bad constant value (ignored).
 <li>306. '<em>identifier</em>' is private in this context.
-<li>307. Can't set default argument value (ignored)
 <li>308. Namespace alias '<em>name</em>' not allowed here. Assuming '<em>name</em>'
 <li>309. [private | protected] inheritance ignored.
 <li>310. Template '<em>name</em>' was already wrapped as '<em>name</em>' (ignored)
@@ -423,11 +409,16 @@ example.i(4) : Syntax error in input(1).
 <li>319. No access specifier given for base class <em>name</em> (ignored).
 <li>320. Explicit template instantiation ignored.
 <li>321. <em>identifier</em> conflicts with a built-in name.
-<li>322. Redundant redeclaration of '<em>name</em>'.
+<li>322. Redundant redeclaration of identifier '<em>name</em>' as <em>decl</em> ignored.
 <li>323. Recursive scope inheritance of '<em>name</em>'.
 <li>324. Named nested template instantiations not supported. Processing as if no name was given to %template().
 <li>325. Nested <em>kind</em> not currently supported (<em>name</em> ignored).
 <li>326. Deprecated %extend name used - the <em>kind</em> name '<em>name</em>' should be used instead of the typedef name '<em>name</em>'.
+<li>327. Extern template ignored.
+<li>340. Lambda expressions and closures are not fully supported yet.
+<li>344. Unable to deduce decltype for '<em>expr</em>'.
+<li>345. Unable to deduce auto return type for '<em>name</em>' (ignored).
+<li>346. Unable to deduce auto type for variable '<em>name</em>' (ignored).
 <li>350. operator new ignored.
 <li>351. operator delete ignored.
 <li>352. operator+ ignored.
@@ -476,14 +467,15 @@ example.i(4) : Syntax error in input(1).
 <li>395. operator delete[] ignored.
 </ul>
 
-<H3><a name="Warnings_nn13">18.9.4 Types and typemaps (400-499) </a></H3>
+<H3><a name="Warnings_nn13">19.9.4 Types and typemaps (400-499) </a></H3>
 
 
 <ul>
 <li>401. Nothing known about class 'name'. Ignored.
 <li>402. Base class 'name' is incomplete.
 <li>403. Class 'name' might be abstract.
-<li>450. Deprecated typemap feature ($source/$target).
+<li>404. Duplicate template instantiation of '<em>type</em>' with name '<em>name</em>' ignored, previous instantiation of '<em>type</em>' with name '<em>name</em>'.
+<li>450. Reserved
 <li>451. Setting const char * variable may leak memory.
 <li>452. Reserved
 <li>453. Can't apply (pattern). No typemaps are defined.
@@ -499,6 +491,8 @@ example.i(4) : Syntax error in input(1).
 <li>469. No or improper directorin typemap defined for <em>type</em>
 <li>470. Thread/reentrant unsafe wrapping, consider returning by value instead.
 <li>471. Unable to use return type <em>type</em> in director method
+<li>472. Overloaded method <em>method</em> with no explicit typecheck typemap for arg <em>number</em> of type '<em>type</em>'
+<li>473. Returning a reference, pointer or pointer wrapper in a director method is not recommended.
 <li>474. Method <em>method</em> usage of the optimal attribute ignored in the out typemap as the following cannot be used to generate optimal code: <em>code</em>
 <li>475. Multiple calls to <em>method</em> might be generated due to optimal attribute usage in the out typemap.
 <li>476. Initialization using std::initializer_list.
@@ -507,7 +501,7 @@ example.i(4) : Syntax error in input(1).
 
 
 
-<H3><a name="Warnings_nn14">18.9.5 Code generation (500-559)</a></H3>
+<H3><a name="Warnings_nn14">19.9.5 Code generation (500-559)</a></H3>
 
 
 <ul>
@@ -536,9 +530,10 @@ example.i(4) : Syntax error in input(1).
 <li>523. Use of an illegal destructor name '<em>name</em>' in %extend is deprecated, the destructor name should be '<em>name</em>'.
 <li>524. Experimental target language. Target language <em>language</em> specified by <em>lang</em> is an experimental language. Please read about SWIG experimental languages, <em>htmllink</em>.
 <li>525. Destructor <em>declaration</em> is final, <em>name</em> cannot be a director class.
+<li>526. Using declaration <em>declaration</em>, with name '<em>name</em>', is not actually using the method from <em>declaration</em>, with name '<em>name</em>', as the names are different.
 </ul>
 
-<H3><a name="Warnings_doxygen">18.9.6 Doxygen comments (560-599)</a></H3>
+<H3><a name="Warnings_doxygen">19.9.6 Doxygen comments (560-599)</a></H3>
 
 
 <ul>
@@ -549,7 +544,7 @@ example.i(4) : Syntax error in input(1).
   <li>564: Error parsing Doxygen command <em>command</em>: <em>error text</em>. Command ignored."</li>
 </ul>
 
-<H3><a name="Warnings_nn15">18.9.7 Language module specific (700-899) </a></H3>
+<H3><a name="Warnings_nn15">19.9.7 Language module specific (700-899) </a></H3>
 
 
 <ul>
@@ -600,14 +595,14 @@ example.i(4) : Syntax error in input(1).
 <li>871. Unrecognized pragma <em>pragma</em>.   (Php).
 </ul>
 
-<H3><a name="Warnings_nn16">18.9.8 User defined (900-999)</a></H3>
+<H3><a name="Warnings_nn16">19.9.8 User defined (900-999)</a></H3>
 
 
 <p>
 These numbers can be used by your own application.
 </p>
 
-<H2><a name="Warnings_nn17">18.10 History</a></H2>
+<H2><a name="Warnings_nn17">19.10 History</a></H2>
 
 
 <p>

Doc/Manual/Windows.html

@@ -29,16 +29,16 @@
 </ul>
 <li><a href="#Windows_other_compilers">Instructions for using the Examples with other compilers</a>
 </ul>
-<li><a href="#Windows_cygwin_mingw">SWIG on Cygwin and MinGW</a>
-<ul>
 <li><a href="#Windows_swig_exe">Building swig.exe on Windows</a>
 <ul>
+<li><a href="#Windows_cmake">Building swig.exe using CMake</a>
+<li><a href="#Windows_msys2">Building swig.exe using MSYS2</a>
 <li><a href="#Windows_mingw_msys">Building swig.exe using MinGW and MSYS</a>
 <li><a href="#Windows_cygwin">Building swig.exe using Cygwin</a>
-<li><a href="#Windows_building_alternatives">Building swig.exe alternatives</a>
-</ul>
+<ul>
 <li><a href="#Windows_examples_cygwin">Running the examples on Windows using Cygwin</a>
 </ul>
+</ul>
 <li><a href="#Windows_interface_file">Microsoft extensions and other Windows quirks</a>
 </ul>
 </div>
@@ -60,7 +60,7 @@ Usage within the Unix like environments MinGW and Cygwin is also detailed.
 SWIG does not come with the usual Windows type installation program, however it is quite easy to get started. The main steps are:
 </p>
 <ul>
-        <li>Download the swigwin zip package from the <a href="http://www.swig.org">SWIG website</a> and unzip into a directory. This is all that needs downloading for the Windows platform.
+        <li>Download the swigwin zip package from the <a href="https://www.swig.org">SWIG website</a> and unzip into a directory. This is all that needs downloading for the Windows platform.
         <li>Set environment variables as described in the <a href="#Windows_examples">SWIG Windows Examples</a> section in order to run examples using Visual C++.
 </ul>
 
@@ -77,10 +77,10 @@ If you want to build your own swig.exe have a look at <a href="#Windows_swig_exe
 
 
 <p>
-Using Microsoft Visual C++ is the most common approach to compiling and linking SWIG's output. 
+Microsoft Visual C++ is the most commonly used compiler for compiling and linking SWIG's output on Windows.
 The Examples directory has a few Visual C++ project files (.dsp files). 
 These were produced by Visual C++ 6.
-Newer versions of Visual Studio should be able to open and convert these project files.
+Newer versions of Visual Studio are able to open and convert these project files.
 Each C# example comes with a Visual Studio 2005 solution and associated project files instead of Visual C++ 6 project files.
 The project files have been set up to execute SWIG in a custom build rule for the SWIG interface (.i) file. 
 Alternatively run the <a href="#Windows_examples_cygwin">examples using Cygwin</a>.
@@ -95,9 +95,11 @@ More information on each of the examples is available with the examples distribu
 Ensure the SWIG executable is as supplied in the SWIG root directory in order for the examples to work. 
 Most languages require some environment variables to be set <b>before</b> running Visual C++. 
 Note that Visual C++ must be re-started to pick up any changes in environment variables. 
-Open up an example .dsp file, Visual C++ will create a workspace for you (.dsw file). 
-Ensure the Release build is selected then do a Rebuild All from the Build menu.
-The required environment variables are displayed with their current values.
+Open up an example .dsp file, Visual C++ will prompt you to upgrade the project and convert
+it into an MSBuild project (.vcxproj file) and Solution (.sln file).
+Note that older versions of Visual C++ will simply create a workspace for you (.dsw file).
+Ensure the Release build is selected then do a Rebuild Solution from the Build menu.
+The required environment variables are displayed with their current values during the build.
 </p>
 <p>
 The list of required environment variables for each module language is also listed below.
@@ -111,7 +113,7 @@ If you are interested in how the project files are set up there is explanatory i
 
 <p>
 The C# examples do not require any environment variables to be set as a C# project file is included.
-Just open up the .sln solution file in Visual Studio .NET 2003 or later, select Release Build, and do a Rebuild All from the Build menu.
+Just open up the .sln solution file in Visual Studio 2005 or later, select Release Build, and do a Rebuild Solution from the Build menu.
 The accompanying C# and C++ project files are automatically used by the solution file.
 </p>
 
@@ -207,38 +209,171 @@ RUBY_LIB: D:\ruby\lib\mswin32-ruby16.lib<br>
 If you do not have access to Visual C++ you will have to set up project files / Makefiles for your chosen compiler. There is a section in each of the language modules detailing what needs setting up using Visual C++ which may be of some guidance. Alternatively you may want to use Cygwin as described in the following section.
 </p>
 
-<H2><a name="Windows_cygwin_mingw">3.3 SWIG on Cygwin and MinGW</a></H2>
+<H2><a name="Windows_swig_exe">3.3 Building swig.exe on Windows</a></H2>
 
 
 <p>
-SWIG can also be compiled and run using <a href="http://www.cygwin.com">Cygwin</a> or <a href="http://www.mingw.org">MinGW</a> which provides a Unix like front end to Windows and comes free with gcc, an ISO C/C++ compiler. However, this is not a recommended approach as the prebuilt executable is supplied. 
+The SWIG distribution provides a pre-built swig.exe and so it is not necessary for users to build the SWIG executable.
+However, this section is provided for those that want to modify the SWIG source code in a Windows environment. 
+Normally this is not needed, so most people will want to ignore this section.
 </p>
 
-<H3><a name="Windows_swig_exe">3.3.1 Building swig.exe on Windows</a></H3>
+<p>
+There are various ways to build the SWIG executable including <a href="https://cmake.org/">CMake</a> which is able to generate project files for building with Visual Studio.
+SWIG can also be compiled and run using <a href="https://www.msys2.org/">MSYS2</a>, <a href="https://www.cygwin.com">Cygwin</a> or <a href="https://osdn.net/projects/mingw/">MinGW</a>, all of which provide a Unix like front end to Windows and comes free with the gcc C/C++ compiler.
+</p>
+
+
+<H3><a name="Windows_cmake">3.3.1 Building swig.exe using CMake</a></H3>
 
 
 <p>
-If you want to replicate the build of swig.exe that comes with the download, follow the MinGW instructions below.
-This is not necessary to use the supplied swig.exe. 
-This information is provided for those that want to modify the SWIG source code in a Windows environment. 
-Normally this is not needed, so most people will want to ignore this section. 
+SWIG can be built using <a href="https://cmake.org/">CMake</a> and Visual Studio rather than autotools. As with the other approaches to 
+building SWIG the dependencies need to be installed. The steps below are one of a number of ways of installing the dependencies without requiring Cygwin or MinGW.
+For fully working build steps always check the Continuous Integration (CI) setups currently detailed in the <a href="https://github.com/swig/swig/tree/master/.github/workflows/nuget.yml">GitHub Actions YAML file</a>.
 </p>
 
-<H4><a name="Windows_mingw_msys">3.3.1.1 Building swig.exe using MinGW and MSYS</a></H4>
+<ol>
+    <li>
+        Install Nuget from <a href="https://www.nuget.org/downloads">https://www.nuget.org/downloads</a> (v6.0.0 is used in this example, and installed to <tt>C:\Tools</tt>). Nuget is the package manager
+        for .NET, but allows us to easily install <a href="https://cmake.org/">CMake</a> and other dependencies required by SWIG.
+    </li>
+    <li>
+        Install <a href="https://www.nuget.org/packages/CMake-win64/">CMake-win64 Nuget package</a> using the following command: <pre>C:\Tools\nuget install CMake-win64 -Version 3.15.5 -OutputDirectory C:\Tools\CMake</pre>
+        Using PowerShell the equivalent syntax is: <pre>&amp; "C:\Tools\nuget" install CMake-win64 -Version 3.15.5 -OutputDirectory C:\Tools\CMake</pre>
+        Alternatively you can download CMake from <a href="https://cmake.org/download/">https://cmake.org/download/</a>.
+    </li>
+    <li>
+        Install the <a href="https://www.nuget.org/packages/bison/">Bison Nuget package</a> using the following command: <pre>C:\Tools\nuget install Bison -Version 3.7.4 -OutputDirectory C:\Tools\bison</pre>
+        Alternatively download Bison from <a href="https://sourceforge.net/projects/winflexbison/files/">https://sourceforge.net/projects/winflexbison/files/</a> (Bison 3.7.4 is used in this example)
+        and save to a folder e.g. <tt>C:\Tools\Bison</tt>
+    </li>
+    <li>
+        Install the <a href="https://www.nuget.org/packages/pcre2/">PCRE2 Nuget package</a> using the following command: <pre>C:\Tools\nuget install PCRE2 -Version 10.39 -OutputDirectory C:\Tools\pcre2</pre>
+        Note this is a x64 build, if this is not suitable PCRE2 can be built from source using <a href="https://github.com/PhilipHazel/pcre2/">https://github.com/PhilipHazel/pcre2/</a>.
+        Alternatively, set <tt>WITH_PCRE=OFF</tt> to disable PCRE2 support if you are sure you do not require it. 
+    </li>
+    <li>
+        We will also need the SWIG source code. Either download a zipped archive from GitHub, or if git is installed clone the latest codebase
+        using: <pre>git clone https://github.com/swig/swig.git</pre>
+        In this example we are assuming the source code is available at <tt>C:\swig</tt>
+    </li>
+    <li>
+    <p>
+        Now we have all the required dependencies we can build SWIG using PowerShell and the commands below. We are assuming Visual Studio 2019 is installed. For other versions of Visual Studio change <tt>"Visual Studio 16 2019 -A x64"</tt> to the relevant
+        <a href="https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html#visual-studio-generators">Visual Studio Generator</a> and
+        architecture. We add the required build tools to the system PATH, and then
+        build a Release version of SWIG. If all runs successfully a new swig.exe should be generated in the <tt>C:/swig/install2/bin</tt> folder.
+    </p>
+    </li>
+</ol>
+<div class="shell"><pre>
+cd C:\swig
 
+$env:PATH="C:\Tools\CMake\CMake-win64.3.15.5\bin;C:\Tools\bison\Bison.3.7.4\bin;" + $env:PATH
+$PCRE_ROOT="C:\Tools\pcre2\PCRE2.10.39.0"
+$PCRE_PLATFORM="x64"
+
+cmake -G "Visual Studio 16 2019" -A "x64" `
+-DCMAKE_INSTALL_PREFIX="C:/swig/install2" `
+-DCMAKE_C_FLAGS="/DPCRE2_STATIC" `
+-DCMAKE_CXX_FLAGS="/DPCRE2_STATIC" `
+-DPCRE2_INCLUDE_DIR="$PCRE_ROOT/include" `
+-DPCRE2_LIBRARY="$PCRE_ROOT/lib/pcre2-8-static.lib" `
+-S . -B build
+
+cmake --build build --config Release
+cmake --install build --config Release
+
+# to test the exe built correctly
+cd install2/bin
+./swig.exe -version
+./swig.exe -help
+</pre></div>
+
+<p>
+    In addition to Release builds you can create a Debug build using:
+</p>
+<div class="shell">
+    <pre>cmake --build build --config Debug</pre>
+</div>
+<p>
+    A Visual Studio solution file should be generated named swig.sln. This can be opened and debugged by running the swig project and setting <tt>Properties &gt; Debugging &gt; Command Arguments</tt>. For example to debug one of the test-suite .i files included with the SWIG source use the following:
+</p>
+<div class="shell">
+    <pre>-python -c++ -o C:\Temp\doxygen_parsing.cpp C:\swig\Examples\test-suite\doxygen_parsing.i</pre>
+</div>
+
+<H3><a name="Windows_msys2">3.3.2 Building swig.exe using MSYS2</a></H3>
+
+
+<p>
+Download and install MSYS2 from <a href="https://www.msys2.org/">www.msys2.org</a> (tested with version msys2-x86_64-20201109).
+Launch the MSYS2 shell.
+</p>
+<p>
+Install the packages needed to build swig:<br>
+</p>
+
+<div class="shell">
+<pre>
+pacman -S git autoconf automake bison gcc make pcre2-devel
+</pre>
+</div>
+
+<p>
+Clone the repository to /usr/src/:
+</p>
+
+<div class="shell">
+<pre>
+mkdir /usr/src/
+cd /usr/src/
+git clone https://github.com/swig/swig.git
+</pre>
+</div>
+
+<p>
+Configure and build:
+</p>
+
+<div class="shell">
+<pre>
+cd /usr/src/swig
+./autogen.sh
+./configure
+make
+</pre>
+</div>
+
+<p>
+Finally you may also want to install SWIG:
+</p>
+
+<div class="shell">
+<pre>
+make install
+</pre>
+</div>
+
+<H3><a name="Windows_mingw_msys">3.3.3 Building swig.exe using MinGW and MSYS</a></H3>
+
+
+<p>Warning: These instructions were added in 2006 and have barely changed since
+so are unlikely to work exactly as written.</p>
 
 <p>
 The short abbreviated instructions follow...
 </p>
 
 <ul>
-    <li>Install MinGW and MSYS from the <a href="http://www.mingw.org">MinGW</a> site. This provides a Unix environment on Windows.
+    <li>Install MinGW and MSYS from the <a href="https://osdn.net/projects/mingw/">MinGW</a> site. This provides a Unix environment on Windows.
     <li>Follow the usual Unix instructions in the README file in the SWIG root directory to build swig.exe from the MinGW command prompt.
 </ul>
 
 <p>
 The step by step instructions to download and install MinGW and MSYS, then download and build the latest version of SWIG from Github follow...
-Note that the instructions for obtaining SWIG from Github are also online at <a href="http://www.swig.org/svn.html">SWIG Bleeding Edge</a>.
+Note that the instructions for obtaining SWIG from Github are also online at <a href="https://www.swig.org/svn.html">SWIG Bleeding Edge</a>.
 </p>
 
 <p>
@@ -248,8 +383,7 @@ Execute the steps in the order shown and don't use spaces in path names. In fact
 
 <ol>
   <li>
-  Download the following packages from the <a href="http://www.mingw.org/download.shtml">MinGW download page</a>
-  or <a href="https://sourceforge.net/projects/mingw/files/">MinGW SourceForge download page</a>.
+  Download the following packages from the <a href="https://osdn.net/projects/mingw/releases/">MinGW download page</a>.
   Note that at the time of writing, the majority of these are in the Current
   release list and some are in the Snapshot or Previous release list.
   <ul>
@@ -319,10 +453,10 @@ the autotools will fail miserably on those.
   </li>
 
   <li>
-The PCRE third party library needs to be built next. 
-Download the latest PCRE source tarball, such as <tt>pcre-8.10.tar.bz2</tt>, from 
-<a href=http://www.pcre.org>PCRE</a> and place in the <tt>/usr/src/swig</tt> directory.
-Build PCRE as a static library using the Tools/pcre-build.sh script as follows:
+The PCRE2 third party library needs to be built next.
+Download the latest PCRE2 source tarball, such as <tt>pcre2-10.39.tar.bz2</tt>, from
+<a href=https://www.pcre.org>www.pcre.org</a> and place in the <tt>/usr/src/swig</tt> directory.
+Build PCRE2 as a static library using the Tools/pcre-build.sh script as follows:
 
 <div class="shell"><pre>
 cd /usr/src/swig
@@ -342,7 +476,7 @@ make
 </ol>
 
 
-<H4><a name="Windows_cygwin">3.3.1.2 Building swig.exe using Cygwin</a></H4>
+<H3><a name="Windows_cygwin">3.3.4 Building swig.exe using Cygwin</a></H3>
 
 
 <p>
@@ -353,17 +487,8 @@ Note that the Cygwin environment will also allow one to regenerate the autotool
 These files are generated using the <tt>autogen.sh</tt> script and will only need regenerating in circumstances such as changing the build system.
 </p>
 
-<H4><a name="Windows_building_alternatives">3.3.1.3 Building swig.exe alternatives</a></H4>
 
-
-<p>
-If you don't want to install Cygwin or MinGW, use a different compiler to build 
-SWIG. For example, all the source code files can be added to a Visual C++ project 
-file in order to build swig.exe from the Visual C++ IDE.
-</p>
-
-
-<H3><a name="Windows_examples_cygwin">3.3.2 Running the examples on Windows using Cygwin</a></H3>
+<H4><a name="Windows_examples_cygwin">3.3.4.1 Running the examples on Windows using Cygwin</a></H4>
 
 
 <p>

Doc/Manual/chapters

@@ -7,6 +7,7 @@ SWIGPlus.html
 CPlusPlus11.html
 CPlusPlus14.html
 CPlusPlus17.html
+CPlusPlus20.html
 Preprocessor.html
 Library.html
 Arguments.html

Doc/Manual/index.html

@@ -1,11 +1,11 @@
 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
 <html>
 <head>
-<title>SWIG-4.0 Documentation</title>
+<title>SWIG Documentation</title>
 <meta http-equiv="content-type" content="text/html; charset=UTF-8">
 </head>
 <body bgcolor="#ffffff">
-<H1><a name="index">SWIG-4.0 Documentation</a></H1>
+<H1><a name="index">SWIG Documentation</a></H1>
 
 The SWIG documentation is available in one of the following formats.
 <ul>

Doc/Manual/makechap.py

@@ -11,10 +11,8 @@
 # then change the heading link name to something that does not look like an
 # autogenerated link name.
 ###############################################################################
-
 import sys
 import re
-import string
 
 ###############################################################################
 # Functions
@@ -58,11 +56,11 @@ def getheadingtext(m, s):
 ###############################################################################
 
 if len(sys.argv) != 3:
-    print "usage: makechap.py filename num"
+    print("usage: makechap.py filename num")
     sys.exit(1)
 
 filename = sys.argv[1]
-filenamebase = string.split(filename,".")[0]
+filenamebase = filename.split(".")[0]
 num      = int(sys.argv[2])
 
 section = 0
@@ -223,6 +221,6 @@ open(filename,"w").write(data)
 # Print the TOC data to stdout correcting the anchor links for external referencing
 
 index = index.replace("<li><a href=\"#","<li><a href=\"%s#" % filename)
-print """<h3><a href="%s#%s">%d %s</a></h3>\n""" % (filename,filenamebase,num,name)
-print index
+print("""<h3><a href="%s#%s">%d %s</a></h3>\n""" % (filename,filenamebase,num,name))
+print(index)
 

Doc/Manual/maketoc.py

@@ -5,7 +5,7 @@ import os
 chs = open("chapters").readlines()
 
 f = open("Contents.html","w")
-print >>f, """
+f.write("""
 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
 <HTML>
 <HEAD>
@@ -17,7 +17,8 @@ print >>f, """
 <H1><a name="Contents"></a>SWIG Users Manual</H1>
 
 <p>
-"""
+
+""")
 
 f.close()
 
@@ -25,15 +26,16 @@ num = 1
 
 for c in chs:
     c = c.strip()
-    print "Processing %s" % c
+    print("Processing " + c)
     if c:
         os.system("python makechap.py %s %d >> Contents.html" % (c,num))
     num += 1
-    
+
 f = open("Contents.html","a")
-print >>f, """
+f.write("""
 </BODY>
 </HTML>
-"""
+
+""")
 
 

Doc/Manual/swightml.book

@@ -10,6 +10,7 @@ SWIGPlus.html
 CPlusPlus11.html
 CPlusPlus14.html
 CPlusPlus17.html
+CPlusPlus20.html
 Preprocessor.html
 Library.html
 Arguments.html

Examples/chicken/README

@@ -1,12 +0,0 @@
-This directory contains examples for CHICKEN.
-
-class       -- illustrates the proxy class C++ interface
-constants   -- handling #define and %constant literals
-egg         -- examples of building chicken extension libraries
-multimap    -- typemaps with multiple sub-types
-overload    -- C++ function overloading
-simple      -- the simple example from the user manual
-zlib        -- a wrapping of the zlib compression library
-
-You should be able to run make in each of the examples.  By default, a shared
-library will be built.  Run make check to execute the test.

Examples/chicken/check.list

@@ -1,6 +0,0 @@
-# see top-level Makefile.in
-class
-constants
-multimap
-overload
-simple

Examples/chicken/class/Makefile

@@ -1,40 +0,0 @@
-TOP        = ../..
-SWIGEXE    = $(TOP)/../swig
-SWIG_LIB_DIR = $(TOP)/../$(TOP_BUILDDIR_TO_TOP_SRCDIR)Lib
-INTERFACE  = example.i
-SRCS       =
-CXXSRCS    = example.cxx
-TARGET     = class
-INCLUDE    =
-SWIGOPT    =
-VARIANT    =
-
-# uncomment the following lines to build a static exe (only pick one of the CHICKEN_MAIN lines)
-#CHICKEN_MAIN = runme-lowlevel.scm
-#CHICKEN_MAIN = runme-tinyclos.scm
-#VARIANT    = _static
-
-check: build
-	$(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' CHICKEN_SCRIPT='runme-lowlevel.scm' chicken_run
-	$(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' CHICKEN_SCRIPT='runme-tinyclos.scm' chicken_run
-
-build: $(TARGET) $(TARGET)_proxy
-
-$(TARGET): $(INTERFACE) $(SRCS)
-	$(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' \
-	SRCS='$(SRCS)' CXXSRCS='$(CXXSRCS)' CHICKEN_MAIN='$(CHICKEN_MAIN)' \
-	SWIG_LIB_DIR='$(SWIG_LIB_DIR)' SWIGEXE='$(SWIGEXE)' \
-	INCLUDE='$(INCLUDE)' SWIGOPT='$(SWIGOPT)' TARGET='$(TARGET)' \
-	INTERFACE='$(INTERFACE)' CHICKENOPTS='$(CHICKENOPTS)' chicken$(VARIANT)_cpp
-
-$(TARGET)_proxy: $(INTERFACE) $(SRCS)
-	$(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' \
-	SRCS='$(SRCS)' CXXSRCS='$(CXXSRCS)' CHICKEN_MAIN='$(CHICKEN_MAIN)' \
-	SWIG_LIB_DIR='$(SWIG_LIB_DIR)' SWIGEXE='$(SWIGEXE)' \
-	INCLUDE='$(INCLUDE)' SWIGOPT='$(SWIGOPT) -proxy' TARGET='$(TARGET)_proxy' \
-	INTERFACE='$(INTERFACE)' CHICKENOPTS='$(CHICKENOPTS)' chicken$(VARIANT)_cpp
-
-clean:
-	$(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' chicken_clean
-	rm -f example.scm
-	rm -f $(TARGET)

Examples/chicken/class/example.cxx

@@ -1,28 +0,0 @@
-/* File : example.cxx */
-
-#include "example.h"
-#define M_PI 3.14159265358979323846
-
-/* Move the shape to a new location */
-void Shape::move(double dx, double dy) {
-  x += dx;
-  y += dy;
-}
-
-int Shape::nshapes = 0;
-
-double Circle::area() {
-  return M_PI*radius*radius;
-}
-
-double Circle::perimeter() {
-  return 2*M_PI*radius;
-}
-
-double Square::area() {
-  return width*width;
-}
-
-double Square::perimeter() {
-  return 4*width;
-}

Examples/chicken/class/example.h

@@ -1,41 +0,0 @@
-/* File : example.h */
-
-class Shape {
-public:
-  Shape() {
-    nshapes++;
-  }
-  virtual ~Shape() {
-    nshapes--;
-  }
-  double  x, y;
-  void    move(double dx, double dy);
-  virtual double area() = 0;
-  virtual double perimeter() = 0;
-  static  int nshapes;
-
-  enum SomeEnum {
-    First = 0,
-    Second,
-    Third,
-    Last = 1000
-  };
-};
-
-class Circle : public Shape {
-private:
-  double radius;
-public:
-  Circle(double r) : radius(r) { }
-  virtual double area();
-  virtual double perimeter();
-};
-
-class Square : public Shape {
-private:
-  double width;
-public:
-  Square(double w) : width(w) { }
-  virtual double area();
-  virtual double perimeter();
-};

Examples/chicken/class/example.i

@@ -1,9 +0,0 @@
-/* File : example.i */
-%module example
-
-%{
-#include "example.h"
-%}
-
-/* Let's just grab the original header file here */
-%include "example.h"

Examples/chicken/class/runme-lowlevel.scm

@@ -1,76 +0,0 @@
-;; This file illustrates the low-level C++ interface generated
-;; by SWIG.
-
-(load-library 'example "class.so")
-(declare (uses example))
-
-;; ----- Object creation -----
-
-(display "Creating some objects:\n")
-(define c (new-Circle 10.0))
-(display "    Created circle ")
-(display c)
-(display "\n")
-(define s (new-Square 10.0))
-(display "    Created square ")
-(display s)
-(display "\n")
-
-;; ----- Access a static member -----
-
-(display "\nA total of ")
-(display (Shape-nshapes))
-(display " shapes were created\n")
-
-;; ----- Member data access -----
-
-;; Set the location of the object
-
-(Shape-x-set c 20.0)
-(Shape-y-set c 30.0)
-
-(Shape-x-set s -10.0)
-(Shape-y-set s 5.0)
-
-(display "\nHere is their current position:\n")
-(display "    Circle = (")
-(display (Shape-x-get c))
-(display ", ")
-(display (Shape-y-get c))
-(display ")\n")
-(display "    Square = (")
-(display (Shape-x-get s))
-(display ", ")
-(display (Shape-y-get s))
-(display ")\n")
-
-;; ----- Call some methods -----
-
-(display "\nHere are some properties of the shapes:\n")
-(let
-    ((disp (lambda (o)
-             (display "   ")
-             (display o)
-             (display "\n")
-             (display "        area      = ")
-             (display (Shape-area o))
-             (display "\n")
-             (display "        perimeter = ")
-             (display (Shape-perimeter o))
-             (display "\n"))))
-  (disp c)
-  (disp s))
-
-(display "\nGuess I'll clean up now\n")
-
-;; Note: this invokes the virtual destructor
-(set! c #f)
-(set! s #f)
-(gc #t)
-
-(set! s 3)
-(display (Shape-nshapes))
-(display " shapes remain\n")
-(display "Goodbye\n")
-
-(exit)

Examples/chicken/class/runme-tinyclos.scm

@@ -1,76 +0,0 @@
-;; This file illustrates the proxy C++ interface generated
-;; by SWIG.
-
-(load-library 'example "class_proxy.so")
-(declare (uses example))
-(declare (uses tinyclos))
-
-;; ----- Object creation -----
-
-(display "Creating some objects:\n")
-(define c (make <Circle> 10.0))
-(display "    Created circle ")
-(display c)
-(display "\n")
-(define s (make <Square> 10.0))
-(display "    Created square ")
-(display s)
-(display "\n")
-
-;; ----- Access a static member -----
-
-(display "\nA total of ")
-(display (Shape-nshapes))
-(display " shapes were created\n")
-
-;; ----- Member data access -----
-
-;; Set the location of the object
-
-(slot-set! c 'x 20.0)
-(slot-set! c 'y 30.0)
-
-(slot-set! s 'x -10.0)
-(slot-set! s 'y 5.0)
-
-(display "\nHere is their current position:\n")
-(display "    Circle = (")
-(display (slot-ref c 'x))
-(display ", ")
-(display (slot-ref c 'y))
-(display ")\n")
-(display "    Square = (")
-(display (slot-ref s 'x))
-(display ", ")
-(display (slot-ref s 'y))
-(display ")\n")
-
-;; ----- Call some methods -----
-
-(display "\nHere are some properties of the shapes:\n")
-(let
-    ((disp (lambda (o)
-             (display "   ")
-             (display o)
-             (display "\n")
-             (display "        area      = ")
-             (display (area o))
-             (display "\n")
-             (display "        perimeter = ")
-             (display (perimeter o))
-             (display "\n"))))
-  (disp c)
-  (disp s))
-
-(display "\nGuess I'll clean up now\n")
-
-;; Note: Invoke the virtual destructors by forcing garbage collection
-(set! c 77)
-(set! s 88)
-(gc #t)
-
-(display (Shape-nshapes))
-(display " shapes remain\n")
-(display "Goodbye\n")
-
-(exit)

Examples/chicken/constants/Makefile

@@ -1,31 +0,0 @@
-TOP        = ../..
-SWIGEXE    = $(TOP)/../swig
-SWIG_LIB_DIR = $(TOP)/../$(TOP_BUILDDIR_TO_TOP_SRCDIR)Lib
-INTERFACE  = example.i
-SRCS       =
-CXXSRCS    =
-TARGET     = constants
-INCLUDE    =
-SWIGOPT    =
-VARIANT    =
-
-# uncomment the following two lines to build a static exe
-#CHICKEN_MAIN = runme.scm
-#VARIANT      = _static
-
-check: build
-	$(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' chicken_run
-
-build: $(TARGET)
-
-$(TARGET): $(INTERFACE) $(SRCS)
-	$(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' \
-	SRCS='$(SRCS)' CXXSRCS='$(CXXSRCS)' CHICKEN_MAIN='$(CHICKEN_MAIN)' \
-	SWIG_LIB_DIR='$(SWIG_LIB_DIR)' SWIGEXE='$(SWIGEXE)' \
-	INCLUDE='$(INCLUDE)' SWIGOPT='$(SWIGOPT)' TARGET='$(TARGET)' \
-	INTERFACE='$(INTERFACE)' CHICKENOPTS='$(CHICKENOPTS)' chicken$(VARIANT)
-
-clean:
-	$(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' chicken_clean
-	rm -f example.scm
-	rm -f $(TARGET)

Examples/chicken/constants/example.i

@@ -1,27 +0,0 @@
-/* File : example.i */
-%module example
-
-/* A few preprocessor macros */
-
-#define    ICONST      42
-#define    FCONST      2.1828
-#define    CCONST      'x'
-#define    CCONST2     '\n'
-#define    SCONST      "Hello World"
-#define    SCONST2     "\"Hello World\""
-
-/* This should work just fine */
-#define    EXPR        ICONST + 3*(FCONST)
-
-/* This shouldn't do anything */
-#define    EXTERN      extern
-
-/* Neither should this (BAR isn't defined) */
-#define    FOO         (ICONST + BAR)
-
-/* The following directives also produce constants.  Remember that
-   CHICKEN is normally case-insensitive, so don't rely on differing
-   case to differentiate variable names */
-
-%constant int iconstX = 37;
-%constant double fconstX = 3.14;

Examples/chicken/constants/runme.scm

@@ -1,16 +0,0 @@
-;; feel free to uncomment and comment sections
-
-(load-library 'example "./constants.so")
-
-(display "starting test ... you will see 'finished' if successful.\n")
-(or (= (ICONST) 42) (exit 1))
-(or (< (abs (- (FCONST) 2.1828)) 0.00001) (exit 1))
-(or (char=? (CCONST) #\x) (exit 1))
-(or (char=? (CCONST2) #\newline) (exit 1))
-(or (string=? (SCONST) "Hello World") (exit 1))
-(or (string=? (SCONST2) "\"Hello World\"") (exit 1))
-(or (< (abs (- (EXPR) (+ (ICONST) (* 3 (FCONST))))) 0.00001) (exit 1))
-(or (= (iconstX) 37) (exit 1))
-(or (< (abs (- (fconstX) 3.14)) 0.00001) (exit 1))
-(display "finished test.\n")
-(exit 0)

Examples/chicken/egg/Makefile

@@ -1,41 +0,0 @@
-TOP        = ../..
-SWIGEXE    = $(TOP)/../swig
-SWIG_LIB_DIR = $(TOP)/../$(TOP_BUILDDIR_TO_TOP_SRCDIR)Lib
-
-check: build
-	cd eggs/install && csi ../../test.scm
-
-build: single multi
-
-# This creates an egg which contains only the single module.  Any additional implementation files
-# that implement the interface being wrapped should also be added to this egg
-single: single_wrap.cxx
-	mkdir -p eggs
-	tar czf eggs/single.egg single.setup single.scm single_wrap.cxx
-	rm -f single.scm single_wrap.cxx
-
-# compile the single module with -nounit
-single_wrap.cxx: single.i
-	$(SWIGEXE) -chicken -c++ -proxy -nounit single.i
-
-# Now build both mod1 and mod2 into a single egg
-multi: mod1_wrap.cxx mod2_wrap.cxx
-	mkdir -p eggs
-	tar czf eggs/multi.egg multi.setup multi_init.scm mod1.scm mod1_wrap.cxx mod2.scm mod2_wrap.cxx
-	rm -f mod1.scm mod1_wrap.cxx mod2.scm mod2_wrap.cxx
-
-mod1_wrap.cxx: mod1.i
-	$(SWIGEXE) -chicken -c++ -proxy mod1.i
-
-mod2_wrap.cxx: mod2.i
-	$(SWIGEXE) -chicken -c++ -proxy mod2.i
-
-clean:
-	rm -rf eggs
-
-# this part is for testing...
-setup:
-	cd eggs && \
-	mkdir -p install && \
-	chicken-setup -repository `pwd`/install single.egg && \
-	chicken-setup -repository `pwd`/install multi.egg

Examples/chicken/egg/README

@@ -1,19 +0,0 @@
-These examples show how to build a chicken extension module in the form of an
-egg.  There are two eggs that get built, single.egg which contains a single
-module which is built with -nounit and multi.egg, which contains two modules
-mod1 and mod2.  These are built normally, and multi_init.scm loads them both.
-Read section "17.4.2 Building chicken extension libraries" in the manual
-for a description of these two techniques.
-
-To build:
-
-$ make
-$ make setup
-$ make run
-
-$ make clean
-
-The eggs are built into an eggs subdirectory, because chicken-setup has
-problems installing eggs when there are other files named similar in
-the same directory.  The make setup step runs chicken-setup to install
-the eggs into the eggs/install directory.

Examples/chicken/egg/mod1.i

@@ -1,8 +0,0 @@
-%module mod1
-
-%inline %{
-class Bar {
-  public:
-    int b;
-};
-%}

Examples/chicken/egg/mod2.i

@@ -1,17 +0,0 @@
-%module mod2
-
-%import "mod1.i"
-
-%{
-class Bar {
-  public:
-    int b;
-};
-%}
-
-%inline %{
-  class Bar2 : public Bar {
-    public:
-      int c;
-  };
-%}

Examples/chicken/egg/multi.setup

@@ -1,2 +0,0 @@
-(run (csc -s -o multi.so multi_init.scm mod1.scm mod1_wrap.cxx mod2.scm mod2_wrap.cxx))
-(install-extension 'multi '("multi.so"))

Examples/chicken/egg/multi_init.scm

@@ -1,2 +0,0 @@
-(declare (uses mod1))
-(declare (uses mod2))

Examples/chicken/egg/single.i

@@ -1,8 +0,0 @@
-%module single
-
-%inline %{
-class Foo {
-  public:
-    int a;
-};
-%}

Examples/chicken/egg/single.setup

@@ -1,2 +0,0 @@
-(run (csc -s -o single.so single.scm single_wrap.cxx))
-(install-extension 'single '("single.so"))

Examples/chicken/egg/test.scm

@@ -1,18 +0,0 @@
-(require-extension single)
-(require-extension multi)
-
-(define f (make <Foo>))
-(slot-set! f 'a 3)
-(print (slot-ref f 'a))
-
-(define b (make <Bar>))
-(slot-set! b 'b 2)
-(print (slot-ref b 'b))
-
-(define b2 (make <Bar2>))
-(slot-set! b2 'b 4)
-(slot-set! b2 'c 6)
-(print (slot-ref b2 'b))
-(print (slot-ref b2 'c))
-
-(exit 0)

Examples/chicken/multimap/Makefile

@@ -1,31 +0,0 @@
-TOP        = ../..
-SWIGEXE    = $(TOP)/../swig
-SWIG_LIB_DIR = $(TOP)/../$(TOP_BUILDDIR_TO_TOP_SRCDIR)Lib
-INTERFACE  = example.i
-SRCS       = example.c
-CXXSRCS    =
-TARGET     = multimap
-INCLUDE    =
-SWIGOPT    =
-VARIANT    =
-
-# uncomment the following two lines to build a static exe
-#CHICKEN_MAIN = runme.scm
-#VARIANT    = _static
-
-check: build
-	$(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' chicken_run
-
-build: $(TARGET)
-
-$(TARGET): $(INTERFACE) $(SRCS)
-	$(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' \
-	SRCS='$(SRCS)' CXXSRCS='$(CXXSRCS)' CHICKEN_MAIN='$(CHICKEN_MAIN)' \
-	SWIG_LIB_DIR='$(SWIG_LIB_DIR)' SWIGEXE='$(SWIGEXE)' \
-	INCLUDE='$(INCLUDE)' SWIGOPT='$(SWIGOPT)' TARGET='$(TARGET)' \
-	INTERFACE='$(INTERFACE)' CHICKENOPTS='$(CHICKENOPTS)' chicken$(VARIANT)
-
-clean:
-	$(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' chicken_clean
-	rm -f example.scm
-	rm -f $(TARGET)