SWIG-4.2 Documentation

Table of Contents

• Sections
  • SWIG Core Documentation
  • Supported Language Modules Documentation
  • Experimental Language Modules Documentation
  • Developer Documentation

• 1.1 Introduction
• 1.2 SWIG Versions
• 1.3 SWIG License
• 1.4 SWIG resources
• 1.5 Prerequisites
• 1.6 Organization of this manual
• 1.7 How to avoid reading the manual
• 1.8 Backwards compatibility
• 1.9 Release notes
• 1.10 Credits
• 1.11 Bug reports
• 1.12 Installation
  • 1.12.1 Windows installation
  • 1.12.2 Unix installation
  • 1.12.3 Macintosh OS X installation
  • 1.12.4 Testing
  • 1.12.5 Examples

• 2.1 What is SWIG?
• 2.2 Why use SWIG?
• 2.3 Target languages
  • 2.3.1 Supported status
  • 2.3.2 Experimental status
• 2.4 A SWIG example
  • 2.4.1 SWIG interface file
  • 2.4.2 The swig command
  • 2.4.3 Building a Perl5 module
  • 2.4.4 Building a Python module
  • 2.4.5 Shortcuts
• 2.5 Supported C/C++ language features
• 2.6 Non-intrusive interface building
• 2.7 Incorporating SWIG into a build system
• 2.8 Hands off code generation
• 2.9 SWIG and freedom

• 3.1 Installation on Windows
  • 3.1.1 Windows Executable
• 3.2 SWIG Windows Examples
  • 3.2.1 Instructions for using the Examples with Visual Studio
    • 3.2.1.1 C#
    • 3.2.1.2 Java
    • 3.2.1.3 Perl
    • 3.2.1.4 Python
    • 3.2.1.5 TCL
    • 3.2.1.6 R
    • 3.2.1.7 Ruby
  • 3.2.2 Instructions for using the Examples with other compilers
• 3.3 Building swig.exe on Windows
  • 3.3.1 Building swig.exe using CMake
  • 3.3.2 Building swig.exe using MSYS2
  • 3.3.3 Building swig.exe using MinGW and MSYS
  • 3.3.4 Building swig.exe using Cygwin
    • 3.3.4.1 Running the examples on Windows using Cygwin
• 3.4 Microsoft extensions and other Windows quirks

• 4.1 The two language view of the world
• 4.2 How does a scripting language talk to C?
  • 4.2.1 Wrapper functions
  • 4.2.2 Variable linking
  • 4.2.3 Constants
  • 4.2.4 Structures and classes
  • 4.2.5 Proxy classes
• 4.3 Building scripting language extensions
  • 4.3.1 Shared libraries and dynamic loading
  • 4.3.2 Linking with shared libraries
  • 4.3.3 Static linking

• 5.1 Running SWIG
  • 5.1.1 Input format
  • 5.1.2 SWIG Output
  • 5.1.3 Comments
  • 5.1.4 C Preprocessor
  • 5.1.5 SWIG Directives
  • 5.1.6 Parser Limitations
• 5.2 Wrapping Simple C Declarations
  • 5.2.1 Basic Type Handling
  • 5.2.2 Global Variables
  • 5.2.3 Constants
  • 5.2.4 A brief word about const
  • 5.2.5 A cautionary tale of char *
• 5.3 Pointers and complex objects
  • 5.3.1 Simple pointers
  • 5.3.2 Run time pointer type checking
  • 5.3.3 Derived types, structs, and classes
  • 5.3.4 Undefined datatypes
  • 5.3.5 Typedef
• 5.4 Other Practicalities
  • 5.4.1 Passing structures by value
  • 5.4.2 Return by value
  • 5.4.3 Linking to structure variables
  • 5.4.4 Linking to char *
  • 5.4.5 Arrays
  • 5.4.6 Creating read-only variables
  • 5.4.7 Renaming and ignoring declarations
    • 5.4.7.1 Simple renaming of specific identifiers
    • 5.4.7.2 Ignoring identifiers
    • 5.4.7.3 Advanced renaming support
    • 5.4.7.4 Limiting global renaming rules
    • 5.4.7.5 Ignoring everything then wrapping a few selected symbols
  • 5.4.8 Default/optional arguments
  • 5.4.9 Pointers to functions and callbacks
• 5.5 Structures and unions
  • 5.5.1 Typedef and structures
  • 5.5.2 Character strings and structures
  • 5.5.3 Array members
  • 5.5.4 Structure data members
  • 5.5.5 C constructors and destructors
  • 5.5.6 Adding member functions to C structures
  • 5.5.7 Nested structures
  • 5.5.8 Other things to note about structure wrapping
• 5.6 Code Insertion
  • 5.6.1 The output of SWIG
  • 5.6.2 Code insertion blocks
  • 5.6.3 Inlined code blocks
  • 5.6.4 Initialization blocks
• 5.7 An Interface Building Strategy
  • 5.7.1 Preparing a C program for SWIG
  • 5.7.2 The SWIG interface file
  • 5.7.3 Why use separate interface files?
  • 5.7.4 Getting the right header files
  • 5.7.5 What to do with main()

• 6.1 Comments on C++ Wrapping
• 6.2 Approach
• 6.3 Supported C++ features
• 6.4 Command line options and compilation
• 6.5 Proxy classes
  • 6.5.1 Construction of proxy classes
  • 6.5.2 Resource management in proxies
  • 6.5.3 Language specific details
• 6.6 Simple C++ wrapping
  • 6.6.1 Constructors and destructors
  • 6.6.2 Default constructors, copy constructors and implicit destructors
  • 6.6.3 When constructor wrappers aren't created
  • 6.6.4 Copy constructors
  • 6.6.5 Member functions
  • 6.6.6 Static members
  • 6.6.7 Member data
• 6.7 Protection
• 6.8 Enums and constants
• 6.9 Friends
  • 6.9.1 Friend classes
  • 6.9.2 Friend function definitions
  • 6.9.3 Friend function declarations
  • 6.9.4 Unqualified friend functions
• 6.10 References and pointers
• 6.11 Pass and return by value
• 6.12 Inheritance
• 6.13 A brief discussion of multiple inheritance, pointers, and type checking
• 6.14 Default arguments
• 6.15 Overloaded functions and methods
  • 6.15.1 Dispatch function generation
  • 6.15.2 Ambiguity in overloading
  • 6.15.3 Renaming and ambiguity resolution
  • 6.15.4 Comments on overloading
• 6.16 Overloaded operators
• 6.17 Class extension
  • 6.17.1 Replacing class methods
• 6.18 Templates
  • 6.18.1 The %template directive
  • 6.18.2 Function templates
  • 6.18.3 Default template arguments
  • 6.18.4 Template base classes
  • 6.18.5 Empty template instantiation
  • 6.18.6 Template specialization
  • 6.18.7 Member templates
  • 6.18.8 Scoping and templates
  • 6.18.9 More on templates
• 6.19 Namespaces
  • 6.19.1 The nspace feature for namespaces
• 6.20 Renaming templated types in namespaces
• 6.21 Exception specifications
• 6.22 Exception handling with %catches
• 6.23 Pointers to Members
• 6.24 Smart pointers and operator->()
• 6.25 C++ reference counted objects - ref/unref feature
• 6.26 Using declarations and inheritance
• 6.27 Nested classes
• 6.28 A brief rant about const-correctness
• 6.29 Callbacks to the target language
  • 6.29.1 Introduction to director classes
  • 6.29.2 Using directors and target language callbacks
• 6.30 Where to go for more information

• 7.1 Introduction
• 7.2 Core language changes
  • 7.2.1 Rvalue reference and move semantics
    • 7.2.1.1 Rvalue reference inputs
    • 7.2.1.2 Rvalue reference outputs
    • 7.2.1.3 Movable and move-only types by value
  • 7.2.2 Generalized constant expressions
  • 7.2.3 Extern template
  • 7.2.4 Initializer lists
  • 7.2.5 Uniform initialization
  • 7.2.6 Type inference
  • 7.2.7 Range-based for-loop
  • 7.2.8 Lambda functions and expressions
  • 7.2.9 Alternate function syntax
  • 7.2.10 Object construction improvement
  • 7.2.11 Explicit overrides and final
  • 7.2.12 Null pointer constant
  • 7.2.13 Strongly typed enumerations
  • 7.2.14 Double angle brackets
  • 7.2.15 Explicit conversion operators
  • 7.2.16 Type alias and alias templates
  • 7.2.17 Unrestricted unions
  • 7.2.18 Variadic templates
  • 7.2.19 New character literals
  • 7.2.20 New string literals
  • 7.2.21 User-defined literals
  • 7.2.22 Thread-local storage
  • 7.2.23 Explicitly defaulted functions and deleted functions
  • 7.2.24 Type long long int
  • 7.2.25 Static assertions
  • 7.2.26 Allow sizeof to work on members of classes without an explicit object
  • 7.2.27 Exception specifications and noexcept
  • 7.2.28 Control and query object alignment
  • 7.2.29 Attributes
  • 7.2.30 Methods with ref-qualifiers
• 7.3 Standard library changes
  • 7.3.1 Threading facilities
  • 7.3.2 Tuple types
  • 7.3.3 Hash tables
  • 7.3.4 Regular expressions
  • 7.3.5 General-purpose smart pointers
  • 7.3.6 Extensible random number facility
  • 7.3.7 Wrapper reference
  • 7.3.8 Polymorphic wrappers for function objects
  • 7.3.9 Type traits for metaprogramming
  • 7.3.10 Uniform method for computing return type of function objects

• 8.1 Introduction
• 8.2 Core language changes
  • 8.2.1 Binary integer literals
  • 8.2.2 Return type deduction
• 8.3 Standard library changes

• 9.1 Introduction
• 9.2 Core language changes
  • 9.2.1 Nested namespace definitions
  • 9.2.2 UTF-8 character literals
  • 9.2.3 Hexadecimal floating literals
• 9.3 Standard library changes

• 10.1 Introduction
• 10.2 Core language changes
  • 10.2.1 Spaceship operator
  • 10.2.2 Lambda templates
  • 10.2.3 Constexpr destructors
• 10.3 Standard library changes

• 11.1 File inclusion
• 11.2 File imports
• 11.3 Conditional Compilation
• 11.4 Macro Expansion
• 11.5 SWIG Macros
• 11.6 C99 and GNU Extensions
• 11.7 Preprocessing and delimiters
  • 11.7.1 Preprocessing and %{ ... %} & " ... " delimiters
  • 11.7.2 Preprocessing and { ... } delimiters
• 11.8 Preprocessor and Typemaps
• 11.9 Viewing preprocessor output
• 11.10 The #error and #warning directives

• 12.1 The %include directive and library search path
• 12.2 C arrays and pointers
  • 12.2.1 argcargv.i
  • 12.2.2 cpointer.i
  • 12.2.3 carrays.i
  • 12.2.4 cmalloc.i
  • 12.2.5 cdata.i
• 12.3 C string handling
  • 12.3.1 Default string handling
  • 12.3.2 Passing binary data
  • 12.3.3 Using %newobject to release memory
  • 12.3.4 cstring.i
• 12.4 STL/C++ library
  • 12.4.1 std::string
  • 12.4.2 std::string_view
  • 12.4.3 std::vector
  • 12.4.4 STL exceptions
  • 12.4.5 shared_ptr smart pointer
    • 12.4.5.1 shared_ptr basics
    • 12.4.5.2 shared_ptr and inheritance
    • 12.4.5.3 shared_ptr and method overloading
    • 12.4.5.4 shared_ptr and templates
    • 12.4.5.5 shared_ptr and directors
  • 12.4.6 unique_ptr smart pointer
  • 12.4.7 auto_ptr smart pointer
• 12.5 Utility Libraries
  • 12.5.1 exception.i
  • 12.5.2 attribute.i
    • 12.5.2.1 %attribute and C++ templates

• 13.1 The typemaps.i library
  • 13.1.1 Introduction
  • 13.1.2 Input parameters
  • 13.1.3 Output parameters
  • 13.1.4 Input/Output parameters
  • 13.1.5 Using different names
• 13.2 Applying constraints to input values
  • 13.2.1 Simple constraint example
  • 13.2.2 Constraint methods
  • 13.2.3 Applying constraints to new datatypes

• 14.1 Introduction
  • 14.1.1 Type conversion
  • 14.1.2 Typemaps
  • 14.1.3 Pattern matching
  • 14.1.4 Reusing typemaps
  • 14.1.5 What can be done with typemaps?
  • 14.1.6 What can't be done with typemaps?
  • 14.1.7 Similarities to Aspect Oriented Programming
  • 14.1.8 The rest of this chapter
• 14.2 Typemap specifications
  • 14.2.1 Defining a typemap
  • 14.2.2 Typemap scope
  • 14.2.3 Copying a typemap
  • 14.2.4 Deleting a typemap
  • 14.2.5 Placement of typemaps
• 14.3 Pattern matching rules
  • 14.3.1 Basic matching rules
  • 14.3.2 Typedef reductions matching
  • 14.3.3 Default typemap matching rules
  • 14.3.4 Multi-arguments typemaps
  • 14.3.5 Matching rules compared to C++ templates
  • 14.3.6 Debugging typemap pattern matching
• 14.4 Code generation rules
  • 14.4.1 Scope
  • 14.4.2 Declaring new local variables
  • 14.4.3 Special variables
  • 14.4.4 Special variable macros
    • 14.4.4.1 $descriptor(type)
    • 14.4.4.2 $typemap(method, typepattern)
    • 14.4.4.3 $typemap(method:attribute, typepattern)
  • 14.4.5 Special variables and typemap attributes
  • 14.4.6 Special variables combined with special variable macros
• 14.5 Common typemap methods
  • 14.5.1 "in" typemap
  • 14.5.2 "typecheck" typemap
  • 14.5.3 "out" typemap
  • 14.5.4 "arginit" typemap
  • 14.5.5 "default" typemap
  • 14.5.6 "check" typemap
  • 14.5.7 "argout" typemap
  • 14.5.8 "freearg" typemap
  • 14.5.9 "newfree" typemap
  • 14.5.10 "ret" typemap
  • 14.5.11 "memberin" typemap
  • 14.5.12 "varin" typemap
  • 14.5.13 "varout" typemap
  • 14.5.14 "throws" typemap
• 14.6 Some typemap examples
  • 14.6.1 Typemaps for arrays
  • 14.6.2 Implementing constraints with typemaps
• 14.7 Typemaps for multiple target languages
• 14.8 Optimal code generation when returning by value
• 14.9 Multi-argument typemaps
• 14.10 Typemap warnings
• 14.11 Typemap fragments
  • 14.11.1 Fragment type specialization
  • 14.11.2 Fragments and automatic typemap specialization
• 14.12 The run-time type checker
  • 14.12.1 Implementation
  • 14.12.2 Usage
• 14.13 Typemaps and overloading
  • 14.13.1 SWIG_TYPECHECK_POINTER precedence level and the typecheck typemap
• 14.14 More about %apply and %clear
• 14.15 Passing data between typemaps
• 14.16 C++ "this" pointer
• 14.17 Where to go for more information?

• 15.1 Exception handling with %exception
  • 15.1.1 Handling exceptions in C code
  • 15.1.2 Exception handling with longjmp()
  • 15.1.3 Handling C++ exceptions
  • 15.1.4 Exception handlers for variables
  • 15.1.5 Defining different exception handlers
  • 15.1.6 Special variables for %exception
  • 15.1.7 Using The SWIG exception library
• 15.2 Object ownership and %newobject
• 15.3 Features and the %feature directive
  • 15.3.1 Feature attributes
  • 15.3.2 Feature flags
  • 15.3.3 Clearing features
  • 15.3.4 Features and default arguments
  • 15.3.5 Feature example

• 16.1 The %contract directive
• 16.2 %contract and classes
• 16.3 Constant aggregation and %aggregate_check
• 16.4 Notes

• 17.1 Introduction
• 17.2 The Problem
• 17.3 Default varargs support
• 17.4 Argument replacement using %varargs
• 17.5 Varargs and typemaps
• 17.6 Varargs wrapping with libffi
• 17.7 Wrapping of va_list
• 17.8 C++ Issues
• 17.9 Discussion

• 18.1 Doxygen translation overview
• 18.2 Preparations
  • 18.2.1 Enabling Doxygen translation
  • 18.2.2 Doxygen-specific %feature directives
    • 18.2.2.1 doxygen:notranslate
    • 18.2.2.2 doxygen:alias:<command-name>
    • 18.2.2.3 doxygen:ignore:<command-name>
    • 18.2.2.4 doxygen:nolinktranslate
    • 18.2.2.5 doxygen:nostripparams
  • 18.2.3 Additional command line options
• 18.3 Doxygen to Javadoc
  • 18.3.1 Basic example
  • 18.3.2 Javadoc tags
  • 18.3.3 Unsupported tags
  • 18.3.4 Further details
• 18.4 Doxygen to Pydoc
  • 18.4.1 Basic example
  • 18.4.2 Pydoc translator
  • 18.4.3 Unsupported tags
  • 18.4.4 Further details
• 18.5 Troubleshooting
  • 18.5.1 Problem with conditional compilation
• 18.6 Developer information
  • 18.6.1 Doxygen translator design
  • 18.6.2 Debugging the Doxygen parser and translator
  • 18.6.3 Tests
• 18.7 Extending to other languages

• 19.1 Introduction
• 19.2 Warning message suppression
• 19.3 Enabling extra warnings
• 19.4 Issuing a warning message
• 19.5 Symbolic symbols
• 19.6 Commentary
• 19.7 Warnings as errors
• 19.8 Message output format
• 19.9 Warning number reference
  • 19.9.1 Deprecated features (100-199)
  • 19.9.2 Preprocessor (200-299)
  • 19.9.3 C/C++ Parser (300-399)
  • 19.9.4 Types and typemaps (400-499)
  • 19.9.5 Code generation (500-559)
  • 19.9.6 Doxygen comments (560-599)
  • 19.9.7 Language module specific (700-899)
  • 19.9.8 User defined (900-999)
• 19.10 History

• 20.1 Modules Introduction
• 20.2 Basics
• 20.3 The SWIG runtime code
• 20.4 External access to the runtime
• 20.5 A word of caution about static libraries
• 20.6 References
• 20.7 Reducing the wrapper file size

• 21.1 NAME
• 21.2 SYNOPSIS
• 21.3 DESCRIPTION
• 21.4 OPTIONS SUMMARY
• 21.5 OPTIONS
• 21.6 INSTALLATION
• 21.7 EXTRA OPTIONS
• 21.8 ENVIRONMENT VARIABLES
• 21.9 CACHE SIZE MANAGEMENT
• 21.10 CACHE COMPRESSION
• 21.11 HOW IT WORKS
• 21.12 USING CCACHE WITH DISTCC
• 21.13 SHARING A CACHE
• 21.14 HISTORY
• 21.15 DIFFERENCES FROM COMPILERCACHE
• 21.16 CREDITS
• 21.17 AUTHOR

• 22.1 Overview
• 22.2 Android examples
  • 22.2.1 Examples introduction
  • 22.2.2 Simple C example
  • 22.2.3 C++ class example
  • 22.2.4 Other examples
• 22.3 C++ STL

• 23.1 Introduction
  • 23.1.1 SWIG 2 Compatibility
  • 23.1.2 Additional command line options
• 23.2 Differences to the Java module
• 23.3 Type mapping
  • 23.3.1 Primitive types
  • 23.3.2 Other types
  • 23.3.3 Void pointers
• 23.4 C# Arrays
  • 23.4.1 The SWIG C arrays library
  • 23.4.2 Managed arrays using P/Invoke default array marshalling
  • 23.4.3 Managed arrays using pinning
• 23.5 C# Exceptions
  • 23.5.1 C# exception example using "check" typemap
  • 23.5.2 C# exception example using %exception
  • 23.5.3 C# exception example using exception specifications
  • 23.5.4 Custom C# ApplicationException example
• 23.6 C# Directors
  • 23.6.1 Directors example
  • 23.6.2 Directors implementation
  • 23.6.3 Director caveats
• 23.7 Multiple modules
• 23.8 C# named and optional arguments
• 23.9 C# Typemap examples
  • 23.9.1 Memory management when returning references to member variables
  • 23.9.2 Memory management for objects passed to the C++ layer
  • 23.9.3 Date marshalling using the csin typemap and associated attributes
  • 23.9.4 A date example demonstrating marshalling of C# properties
  • 23.9.5 Date example demonstrating the 'pre' and 'post' typemap attributes for directors
  • 23.9.6 Turning proxy classes into partial classes
  • 23.9.7 Turning proxy classes into sealed classes
  • 23.9.8 Extending proxy classes with additional C# code
  • 23.9.9 Underlying type for enums

• 24.1 Introduction
• 24.2 Command line invocation
• 24.3 Typemaps
  • 24.3.1 C# <-> D name comparison
  • 24.3.2 ctype, imtype, dtype
  • 24.3.3 in, out, directorin, directorout
  • 24.3.4 din, dout, ddirectorin, ddirectorout
  • 24.3.5 typecheck typemaps
  • 24.3.6 Code injection typemaps
  • 24.3.7 Special variable macros
• 24.4 Other D code control features
  • 24.4.1 D begin
  • 24.4.2 D and %feature
• 24.5 Pragmas
• 24.6 D Exceptions
• 24.7 D Directors
• 24.8 Other features
  • 24.8.1 Extended namespace support (nspace)
  • 24.8.2 Native pointer support
  • 24.8.3 Operator overloading
  • 24.8.4 Running the test-suite
• 24.9 D Typemap examples
• 24.10 Work in progress and planned features

• 25.1 Overview
• 25.2 Examples
• 25.3 Running SWIG with Go
  • 25.3.1 Go-specific Commandline Options
  • 25.3.2 Generated Wrapper Files
• 25.4 A tour of basic C/C++ wrapping
  • 25.4.1 Go Package Name
  • 25.4.2 Go Names
  • 25.4.3 Go Constants
  • 25.4.4 Go Enumerations
  • 25.4.5 Go Classes
    • 25.4.5.1 Go Class Memory Management
    • 25.4.5.2 Go Class Inheritance
  • 25.4.6 Go Templates
  • 25.4.7 Go and C/C++ Threads
  • 25.4.8 Go and C++ Exceptions
  • 25.4.9 Go Director Classes
    • 25.4.9.1 Example C++ code
    • 25.4.9.2 Enable director feature
    • 25.4.9.3 Constructor and destructor
    • 25.4.9.4 Override virtual methods
    • 25.4.9.5 Call base methods
    • 25.4.9.6 Subclass via embedding
    • 25.4.9.7 Memory management with runtime.SetFinalizer
    • 25.4.9.8 Complete FooBarGo example class
  • 25.4.10 Default Go primitive type mappings
  • 25.4.11 Output arguments
  • 25.4.12 Adding additional go code
  • 25.4.13 Go typemaps

• 26.1 Supported Guile Versions
• 26.2 Meaning of "Module"
• 26.3 Old GH Guile API
• 26.4 Linkage
  • 26.4.1 Simple Linkage
  • 26.4.2 Passive Linkage
  • 26.4.3 Native Guile Module Linkage
  • 26.4.4 Old Auto-Loading Guile Module Linkage
  • 26.4.5 Hobbit4D Linkage
• 26.5 Underscore Folding
• 26.6 Typemaps
• 26.7 Representation of pointers as smobs
  • 26.7.1 Smobs
  • 26.7.2 Garbage Collection
• 26.8 Native Guile pointers
• 26.9 Exception Handling
• 26.10 Procedure documentation
• 26.11 Procedures with setters
• 26.12 GOOPS Proxy Classes
  • 26.12.1 Naming Issues
  • 26.12.2 Linking

• 27.1 Overview
• 27.2 Preliminaries
  • 27.2.1 Running SWIG
  • 27.2.2 Additional Commandline Options
  • 27.2.3 Getting the right header files
  • 27.2.4 Compiling a dynamic module
  • 27.2.5 Using your module
  • 27.2.6 Dynamic linking problems
  • 27.2.7 Compilation problems and compiling with C++
  • 27.2.8 Building on Windows
    • 27.2.8.1 Running SWIG from Visual Studio
    • 27.2.8.2 Using NMAKE
• 27.3 A tour of basic C/C++ wrapping
  • 27.3.1 Modules, packages and generated Java classes
  • 27.3.2 Functions
  • 27.3.3 Global variables
  • 27.3.4 Constants
  • 27.3.5 Enumerations
    • 27.3.5.1 Anonymous enums
    • 27.3.5.2 Typesafe enums
    • 27.3.5.3 Proper Java enums
    • 27.3.5.4 Type unsafe enums
    • 27.3.5.5 Simple enums
  • 27.3.6 Pointers
  • 27.3.7 Structures
  • 27.3.8 C++ classes
  • 27.3.9 C++ inheritance
  • 27.3.10 Pointers, references, arrays and pass by value
    • 27.3.10.1 Null pointers
  • 27.3.11 C++ overloaded functions
  • 27.3.12 C++ default arguments
  • 27.3.13 C++ namespaces
  • 27.3.14 C++ templates
  • 27.3.15 C++ Smart Pointers
    • 27.3.15.1 The shared_ptr Smart Pointer
    • 27.3.15.2 Generic Smart Pointers
• 27.4 Further details on the generated Java classes
  • 27.4.1 The intermediary JNI class
    • 27.4.1.1 The intermediary JNI class pragmas
  • 27.4.2 The Java module class
    • 27.4.2.1 The Java module class pragmas
  • 27.4.3 Java proxy classes
    • 27.4.3.1 Memory management
    • 27.4.3.2 Inheritance
    • 27.4.3.3 Proxy classes and garbage collection
    • 27.4.3.4 The premature garbage collection prevention parameter for proxy class marshalling
    • 27.4.3.5 Single threaded applications and thread safety
  • 27.4.4 Type wrapper classes
  • 27.4.5 Enum classes
    • 27.4.5.1 Typesafe enum classes
    • 27.4.5.2 Proper Java enum classes
    • 27.4.5.3 Type unsafe enum classes
  • 27.4.6 Interfaces
• 27.5 Cross language polymorphism using directors
  • 27.5.1 Enabling directors
  • 27.5.2 Director classes
  • 27.5.3 Overhead and code bloat
  • 27.5.4 Simple directors example
  • 27.5.5 Director threading issues
  • 27.5.6 Director performance tuning
  • 27.5.7 Java exceptions from directors
    • 27.5.7.1 Customizing director exceptions
• 27.6 Accessing protected members
• 27.7 Common customization features
  • 27.7.1 C/C++ helper functions
  • 27.7.2 Class extension with %extend
  • 27.7.3 Class extension with %proxycode
  • 27.7.4 Exception handling with %exception and %javaexception
  • 27.7.5 Method access with %javamethodmodifiers
  • 27.7.6 Java begin
• 27.8 Tips and techniques
  • 27.8.1 Input and output parameters using primitive pointers and references
  • 27.8.2 Simple pointers
  • 27.8.3 Wrapping C arrays with Java arrays
  • 27.8.4 Unbounded C Arrays
  • 27.8.5 Binary data vs Strings
  • 27.8.6 Overriding new and delete to allocate from Java heap
• 27.9 Java typemaps
  • 27.9.1 Default primitive type mappings
  • 27.9.2 Default typemaps for non-primitive types
  • 27.9.3 Sixty four bit JVMs
  • 27.9.4 What is a typemap?
  • 27.9.5 Typemaps for mapping C/C++ types to Java types
  • 27.9.6 Java typemap attributes
  • 27.9.7 Java special variables
  • 27.9.8 Typemaps for both C and C++ compilation
  • 27.9.9 Java code typemaps
  • 27.9.10 Director specific typemaps
• 27.10 Typemap Examples
  • 27.10.1 Simpler Java enums for enums without initializers
  • 27.10.2 Handling C++ exception specifications as Java exceptions
  • 27.10.3 NaN Exception - exception handling for a particular type
  • 27.10.4 Converting Java String arrays to char **
  • 27.10.5 Expanding a Java object to multiple arguments
  • 27.10.6 Using typemaps to return arguments
  • 27.10.7 Adding Java downcasts to polymorphic return types
  • 27.10.8 Adding an equals method to the Java classes
  • 27.10.9 Void pointers and a common Java base class
  • 27.10.10 Struct pointer to pointer
  • 27.10.11 Memory management when returning references to member variables
  • 27.10.12 Memory management for objects passed to the C++ layer
  • 27.10.13 Date marshalling using the javain typemap and associated attributes
• 27.11 Living with Java Directors
• 27.12 Odds and ends
  • 27.12.1 JavaDoc comments
  • 27.12.2 Functional interface without proxy classes
  • 27.12.3 Using your own JNI functions
  • 27.12.4 Performance concerns and hints
  • 27.12.5 Debugging
• 27.13 Java Examples

• 28.1 Overview
• 28.2 Preliminaries
  • 28.2.1 Running SWIG
  • 28.2.2 Running Tests and Examples
  • 28.2.3 Known Issues
• 28.3 Integration
  • 28.3.1 Creating node.js Extensions
    • 28.3.1.1 Using yeoman to generate a Node-API skeleton
    • 28.3.1.2 Troubleshooting
  • 28.3.2 Embedded Webkit
    • 28.3.2.1 Mac OS X
    • 28.3.2.2 GTK
  • 28.3.3 Creating Applications with node-webkit
• 28.4 Examples
  • 28.4.1 Simple
  • 28.4.2 Class
• 28.5 Implementation
  • 28.5.1 Source Code
  • 28.5.2 Code Templates
  • 28.5.3 Emitter
  • 28.5.4 Emitter states
  • 28.5.5 Handling Exceptions in JavascriptCore
  • 28.5.6 Handling Exceptions in Node-API

• 29.1 Preliminaries
• 29.2 Running SWIG
  • 29.2.1 Additional command line options
  • 29.2.2 Compiling and Linking and Interpreter
  • 29.2.3 Compiling a dynamic module
  • 29.2.4 Using your module
• 29.3 A tour of basic C/C++ wrapping
  • 29.3.1 Modules
  • 29.3.2 Functions
  • 29.3.3 Global variables
  • 29.3.4 Constants and enums
    • 29.3.4.1 Constants/enums and classes/structures
  • 29.3.5 Pointers
  • 29.3.6 Structures
  • 29.3.7 C++ classes
  • 29.3.8 C++ inheritance
  • 29.3.9 Pointers, references, values, and arrays
  • 29.3.10 C++ overloaded functions
  • 29.3.11 C++ operators
  • 29.3.12 Class extension with %extend
  • 29.3.13 Using %newobject to release memory
  • 29.3.14 C++ templates
  • 29.3.15 C++ Smart Pointers
  • 29.3.16 C++ Exceptions
  • 29.3.17 Namespaces
    • 29.3.17.1 Compatibility Note
    • 29.3.17.2 Names
    • 29.3.17.3 Inheritance
• 29.4 Typemaps
  • 29.4.1 What is a typemap?
  • 29.4.2 Using typemaps
  • 29.4.3 Typemaps and arrays
  • 29.4.4 Typemaps and pointer-pointer functions
• 29.5 Writing typemaps
  • 29.5.1 Typemaps you can write
  • 29.5.2 SWIG's Lua-C API
• 29.6 Customization of your Bindings
  • 29.6.1 Writing your own custom wrappers
  • 29.6.2 Adding additional Lua code
• 29.7 Details on the Lua binding
  • 29.7.1 Binding global data into the module.
  • 29.7.2 Userdata and Metatables
  • 29.7.3 Memory management

• 30.1 Preliminaries
• 30.2 Running SWIG
  • 30.2.1 Command-line options
  • 30.2.2 Compiling a dynamic module
  • 30.2.3 Using your module
• 30.3 A tour of basic C/C++ wrapping
  • 30.3.1 Modules
  • 30.3.2 Functions
  • 30.3.3 Global variables
  • 30.3.4 Constants and enums
  • 30.3.5 Pointers
  • 30.3.6 Structures and C++ classes
  • 30.3.7 C++ inheritance
  • 30.3.8 C++ overloaded functions
  • 30.3.9 C++ operators
  • 30.3.10 Class extension with %extend
  • 30.3.11 C++ templates
  • 30.3.12 C++ Smart Pointers
    • 30.3.12.1 The shared_ptr Smart Pointer
    • 30.3.12.2 Generic Smart Pointers
  • 30.3.13 Directors (calling Octave from C++ code)
  • 30.3.14 Threads
  • 30.3.15 Memory management
  • 30.3.16 STL support
  • 30.3.17 Matrix typemaps

• 31.1 Overview
• 31.2 Preliminaries
  • 31.2.1 Getting the right header files
  • 31.2.2 Compiling a dynamic module
  • 31.2.3 Building a dynamic module with MakeMaker
  • 31.2.4 Building a static version of Perl
  • 31.2.5 Using the module
  • 31.2.6 Compilation problems and compiling with C++
  • 31.2.7 Compiling for 64-bit platforms
• 31.3 Building Perl Extensions under Windows
  • 31.3.1 Running SWIG from Developer Studio
  • 31.3.2 Using other compilers
• 31.4 The low-level interface
  • 31.4.1 Functions
  • 31.4.2 Global variables
  • 31.4.3 Constants
  • 31.4.4 Pointers
  • 31.4.5 Structures
  • 31.4.6 C++ classes
  • 31.4.7 C++ classes and type-checking
  • 31.4.8 C++ overloaded functions
  • 31.4.9 Operators
  • 31.4.10 Modules and packages
• 31.5 Input and output parameters
• 31.6 Exception handling
• 31.7 Remapping datatypes with typemaps
  • 31.7.1 A simple typemap example
  • 31.7.2 Perl5 typemaps
  • 31.7.3 Typemap variables
  • 31.7.4 Useful functions
• 31.8 Typemap Examples
  • 31.8.1 Converting a Perl5 array to a char **
  • 31.8.2 Return values
  • 31.8.3 Returning values from arguments
  • 31.8.4 Accessing array structure members
  • 31.8.5 Turning Perl references into C pointers
  • 31.8.6 Pointer handling
• 31.9 Proxy classes
  • 31.9.1 Preliminaries
  • 31.9.2 Structure and class wrappers
  • 31.9.3 Object Ownership
  • 31.9.4 Nested Objects
  • 31.9.5 Proxy Functions
  • 31.9.6 Inheritance
  • 31.9.7 Modifying the proxy methods
• 31.10 Adding additional Perl code
• 31.11 Cross language polymorphism
  • 31.11.1 Enabling directors
  • 31.11.2 Director classes
  • 31.11.3 Ownership and object destruction
  • 31.11.4 Exception unrolling
  • 31.11.5 Overhead and code bloat
  • 31.11.6 Typemaps

• 32.1 Generating PHP Extensions
  • 32.1.1 Building a loadable extension
  • 32.1.2 Using PHP Extensions
• 32.2 Basic PHP interface
  • 32.2.1 Constants
  • 32.2.2 Global Variables
  • 32.2.3 Functions
  • 32.2.4 Overloading
  • 32.2.5 Pointers and References
  • 32.2.6 Structures and C++ classes
    • 32.2.6.1 Using -noproxy
    • 32.2.6.2 Constructors and Destructors
    • 32.2.6.3 Static Member Variables
    • 32.2.6.4 Static Member Functions
    • 32.2.6.5 Specifying Implemented Interfaces
    • 32.2.6.6 Dynamic Properties
  • 32.2.7 PHP Pragmas, Startup and Shutdown code
• 32.3 Cross language polymorphism
  • 32.3.1 Enabling directors
  • 32.3.2 Director classes
  • 32.3.3 Ownership and object destruction
  • 32.3.4 Exception unrolling
  • 32.3.5 Overhead and code bloat
  • 32.3.6 Typemaps
  • 32.3.7 Miscellaneous

• 33.1 Overview
• 33.2 Preliminaries
  • 33.2.1 Running SWIG
  • 33.2.2 Using distutils
  • 33.2.3 Hand compiling a dynamic module
  • 33.2.4 Static linking
  • 33.2.5 Using your module
  • 33.2.6 Compilation of C++ extensions
  • 33.2.7 Compiling for 64-bit platforms
  • 33.2.8 Building Python extensions under Windows
  • 33.2.9 Additional Python commandline options
• 33.3 A tour of basic C/C++ wrapping
  • 33.3.1 Modules
  • 33.3.2 Functions
  • 33.3.3 Global variables
  • 33.3.4 Constants and enums
  • 33.3.5 Pointers
  • 33.3.6 Structures
  • 33.3.7 C++ classes
  • 33.3.8 C++ inheritance
  • 33.3.9 Pointers, references, values, and arrays
  • 33.3.10 C++ overloaded functions
  • 33.3.11 C++ operators
  • 33.3.12 C++ namespaces
  • 33.3.13 C++ templates
  • 33.3.14 C++ Smart Pointers
    • 33.3.14.1 The shared_ptr Smart Pointer
    • 33.3.14.2 Generic Smart Pointers
  • 33.3.15 C++ reference counted objects
• 33.4 Further details on the Python class interface
  • 33.4.1 Proxy classes
  • 33.4.2 Built-in Types
    • 33.4.2.1 Limitations
    • 33.4.2.2 Operator overloads and slots -- use them!
  • 33.4.3 Memory management
• 33.5 Cross language polymorphism
  • 33.5.1 Enabling directors
  • 33.5.2 Director classes
  • 33.5.3 Ownership and object destruction
  • 33.5.4 Exception unrolling
  • 33.5.5 Overhead and code bloat
  • 33.5.6 Typemaps
  • 33.5.7 Miscellaneous
  • 33.5.8 Stable ABI
• 33.6 Common customization features
  • 33.6.1 C/C++ helper functions
  • 33.6.2 Adding additional Python code
  • 33.6.3 Class extension with %extend
  • 33.6.4 Exception handling with %exception
  • 33.6.5 Optimization options
    • 33.6.5.1 -fastproxy
• 33.7 Tips and techniques
  • 33.7.1 Input and output parameters
  • 33.7.2 Simple pointers
  • 33.7.3 Unbounded C Arrays
  • 33.7.4 String handling
  • 33.7.5 Default arguments
• 33.8 Typemaps
  • 33.8.1 What is a typemap?
  • 33.8.2 Python typemaps
  • 33.8.3 Typemap variables
  • 33.8.4 Useful Python Functions
• 33.9 Typemap Examples
  • 33.9.1 Converting a Python list to a char **
  • 33.9.2 Expanding a Python object into multiple arguments
  • 33.9.3 Using typemaps to return arguments
  • 33.9.4 Mapping Python tuples into small arrays
  • 33.9.5 Mapping sequences to C arrays
  • 33.9.6 Pointer handling
  • 33.9.7 Memory management when returning references to member variables
• 33.10 Docstring Features
  • 33.10.1 Module docstring
  • 33.10.2 %feature("autodoc")
    • 33.10.2.1 %feature("autodoc", "0")
    • 33.10.2.2 %feature("autodoc", "1")
    • 33.10.2.3 %feature("autodoc", "2")
    • 33.10.2.4 %feature("autodoc", "3")
    • 33.10.2.5 %feature("autodoc", "docstring")
  • 33.10.3 %feature("docstring")
  • 33.10.4 Doxygen comments
• 33.11 Python Packages
  • 33.11.1 Setting the Python package
  • 33.11.2 Absolute and relative imports
  • 33.11.3 Enforcing absolute import semantics
  • 33.11.4 Importing from __init__.py
  • 33.11.5 Implicit namespace packages
  • 33.11.6 Location of modules
    • 33.11.6.1 Both modules in the same package
    • 33.11.6.2 Both modules are global
    • 33.11.6.3 Split modules custom configuration
    • 33.11.6.4 More on customizing the module import code
    • 33.11.6.5 Statically linked C modules
• 33.12 Python 3 Support
  • 33.12.1 Python function annotations and variable annotations
    • 33.12.1.1 C/C++ annotation types
  • 33.12.2 Buffer interface
  • 33.12.3 Abstract base classes
  • 33.12.4 Byte string output conversion
  • 33.12.5 Python 2 Unicode
• 33.13 Support for Multithreaded Applications
  • 33.13.1 UI for Enabling Multithreading Support
  • 33.13.2 Multithread Performance

• 34.1 Bugs
• 34.2 Using R and SWIG
• 34.3 Precompiling large R files
• 34.4 General policy
• 34.5 Language conventions
• 34.6 C++ classes
  • 34.6.1 Examples
• 34.7 Enumerations

• 35.1 Preliminaries
  • 35.1.1 Running SWIG
  • 35.1.2 Getting the right header files
  • 35.1.3 Compiling a dynamic module
  • 35.1.4 Using your module
  • 35.1.5 Static linking
  • 35.1.6 Compilation of C++ extensions
• 35.2 Building Ruby Extensions under Windows 95/NT
  • 35.2.1 Running SWIG from Developer Studio
• 35.3 The Ruby-to-C/C++ Mapping
  • 35.3.1 Modules
  • 35.3.2 Functions
  • 35.3.3 Variable Linking
  • 35.3.4 Constants
  • 35.3.5 Pointers
  • 35.3.6 Structures
  • 35.3.7 C++ classes
  • 35.3.8 C++ Inheritance
  • 35.3.9 C++ Overloaded Functions
  • 35.3.10 C++ Operators
  • 35.3.11 C++ namespaces
  • 35.3.12 C++ templates
  • 35.3.13 C++ Standard Template Library (STL)
  • 35.3.14 C++ STL Functors
  • 35.3.15 C++ STL Iterators
  • 35.3.16 C++ Smart Pointers
    • 35.3.16.1 The shared_ptr Smart Pointer
    • 35.3.16.2 Generic Smart Pointers
  • 35.3.17 Cross-Language Polymorphism
    • 35.3.17.1 Exception Unrolling
• 35.4 Naming
  • 35.4.1 Defining Aliases
  • 35.4.2 Predicate Methods
  • 35.4.3 Bang Methods
  • 35.4.4 Getters and Setters
• 35.5 Input and output parameters
• 35.6 Exception handling
  • 35.6.1 Using the %exception directive
  • 35.6.2 Handling Ruby Blocks
  • 35.6.3 Raising exceptions
  • 35.6.4 Exception classes
• 35.7 Typemaps
  • 35.7.1 What is a typemap?
  • 35.7.2 Typemap scope
  • 35.7.3 Copying a typemap
  • 35.7.4 Deleting a typemap
  • 35.7.5 Placement of typemaps
  • 35.7.6 Ruby typemaps
    • 35.7.6.1 "in" typemap
    • 35.7.6.2 "typecheck" typemap
    • 35.7.6.3 "out" typemap
    • 35.7.6.4 "arginit" typemap
    • 35.7.6.5 "default" typemap
    • 35.7.6.6 "check" typemap
    • 35.7.6.7 "argout" typemap
    • 35.7.6.8 "freearg" typemap
    • 35.7.6.9 "newfree" typemap
    • 35.7.6.10 "memberin" typemap
    • 35.7.6.11 "varin" typemap
    • 35.7.6.12 "varout" typemap
    • 35.7.6.13 "throws" typemap
    • 35.7.6.14 directorin typemap
    • 35.7.6.15 directorout typemap
    • 35.7.6.16 directorargout typemap
    • 35.7.6.17 ret typemap
    • 35.7.6.18 globalin typemap
  • 35.7.7 Typemap variables
  • 35.7.8 Useful Functions
    • 35.7.8.1 C Datatypes to Ruby Objects
    • 35.7.8.2 Ruby Objects to C Datatypes
    • 35.7.8.3 Macros for VALUE
    • 35.7.8.4 Exceptions
    • 35.7.8.5 Iterators
  • 35.7.9 Typemap Examples
  • 35.7.10 Converting a Ruby array to a char **
  • 35.7.11 Collecting arguments in a hash
  • 35.7.12 Pointer handling
    • 35.7.12.1 Ruby Datatype Wrapping
  • 35.7.13 Example: STL Vector to Ruby Array
• 35.8 Docstring Features
  • 35.8.1 Module docstring
  • 35.8.2 %feature("autodoc")
    • 35.8.2.1 %feature("autodoc", "0")
    • 35.8.2.2 %feature("autodoc", "1")
    • 35.8.2.3 %feature("autodoc", "2")
    • 35.8.2.4 %feature("autodoc", "3")
    • 35.8.2.5 %feature("autodoc", "docstring")
  • 35.8.3 %feature("docstring")
• 35.9 Advanced Topics
  • 35.9.1 Operator overloading
  • 35.9.2 Creating Multi-Module Packages
  • 35.9.3 Specifying Mixin Modules
• 35.10 Memory Management
  • 35.10.1 Mark and Sweep Garbage Collector
  • 35.10.2 Object Ownership
  • 35.10.3 Object Tracking
  • 35.10.4 Mark Functions
  • 35.10.5 Free Functions
  • 35.10.6 Embedded Ruby and the C++ Stack

• 36.1 Preliminaries
• 36.2 Running SWIG
  • 36.2.1 Generating the module
  • 36.2.2 Building the module
  • 36.2.3 Loading the module
  • 36.2.4 Using the module
  • 36.2.5 Scilab command line options
• 36.3 A basic tour of C/C++ wrapping
  • 36.3.1 Overview
  • 36.3.2 Identifiers
  • 36.3.3 Functions
    • 36.3.3.1 Argument passing
    • 36.3.3.2 Multiple output arguments
  • 36.3.4 Global variables
  • 36.3.5 Constants and enumerations
    • 36.3.5.1 Constants
    • 36.3.5.2 Enumerations
  • 36.3.6 Pointers
    • 36.3.6.1 Utility functions
    • 36.3.6.2 Null pointers:
  • 36.3.7 Structures
  • 36.3.8 C++ classes
  • 36.3.9 C++ inheritance
  • 36.3.10 C++ overloading
  • 36.3.11 Pointers, references, values, and arrays
  • 36.3.12 C++ templates
  • 36.3.13 C++ operators
  • 36.3.14 C++ namespaces
  • 36.3.15 C++ exceptions
  • 36.3.16 C++ STL
• 36.4 Type mappings and libraries
  • 36.4.1 Default primitive type mappings
  • 36.4.2 Arrays
  • 36.4.3 Pointer-to-pointers
  • 36.4.4 Matrices
  • 36.4.5 STL
• 36.5 Module initialization
• 36.6 Building modes
  • 36.6.1 No-builder mode
  • 36.6.2 Builder mode
• 36.7 Generated scripts
  • 36.7.1 Builder script
  • 36.7.2 Loader script
  • 36.7.3 Gateway XML files
• 36.8 Other resources

• 37.1 Preliminaries
  • 37.1.1 Getting the right header files
  • 37.1.2 Compiling a dynamic module
  • 37.1.3 Static linking
  • 37.1.4 Using your module
  • 37.1.5 Compilation of C++ extensions
  • 37.1.6 Compiling for 64-bit platforms
  • 37.1.7 Setting a package prefix
  • 37.1.8 Using namespaces
• 37.2 Building Tcl/Tk Extensions under Windows 95/NT
  • 37.2.1 Running SWIG from Developer Studio
  • 37.2.2 Using NMAKE
• 37.3 A tour of basic C/C++ wrapping
  • 37.3.1 Modules
  • 37.3.2 Functions
  • 37.3.3 Global variables
  • 37.3.4 Constants and enums
  • 37.3.5 Pointers
  • 37.3.6 Structures
  • 37.3.7 C++ classes
  • 37.3.8 C++ inheritance
  • 37.3.9 Pointers, references, values, and arrays
  • 37.3.10 C++ overloaded functions
  • 37.3.11 C++ operators
  • 37.3.12 C++ namespaces
  • 37.3.13 C++ templates
  • 37.3.14 C++ Smart Pointers
• 37.4 Further details on the Tcl class interface
  • 37.4.1 Proxy classes
  • 37.4.2 Memory management
• 37.5 Input and output parameters
• 37.6 Exception handling
• 37.7 Typemaps
  • 37.7.1 What is a typemap?
  • 37.7.2 Tcl typemaps
  • 37.7.3 Typemap variables
  • 37.7.4 Converting a Tcl list to a char **
  • 37.7.5 Returning values in arguments
  • 37.7.6 Useful functions
  • 37.7.7 Standard typemaps
  • 37.7.8 Pointer handling
• 37.8 Turning a SWIG module into a Tcl Package.
• 37.9 Building new kinds of Tcl interfaces (in Tcl)
  • 37.9.1 Proxy classes
• 37.10 Tcl/Tk Stubs

• 38.1 Creating native structures
• 38.2 Simple example
• 38.3 External documentation

• 39.1 Preliminaries
  • 39.1.1 Running SWIG
  • 39.1.2 Compiling the code
  • 39.1.3 The camlp4 module
  • 39.1.4 Using your module
  • 39.1.5 Compilation problems and compiling with C++
• 39.2 The low-level Ocaml/C interface
  • 39.2.1 The generated module
  • 39.2.2 Enums
    • 39.2.2.1 Enum typing in Ocaml
  • 39.2.3 Arrays
    • 39.2.3.1 Simple types of bounded arrays
    • 39.2.3.2 Complex and unbounded arrays
    • 39.2.3.3 Using an object
    • 39.2.3.4 Example typemap for a function taking float * and int
  • 39.2.4 C++ Classes
    • 39.2.4.1 STL vector and string Example
    • 39.2.4.2 C++ Class Example
    • 39.2.4.3 Compiling the example
    • 39.2.4.4 Sample Session
  • 39.2.5 Director Classes
    • 39.2.5.1 Director Introduction
    • 39.2.5.2 Overriding Methods in Ocaml
    • 39.2.5.3 Director Usage Example
    • 39.2.5.4 Creating director objects
    • 39.2.5.5 Typemaps for directors, directorin, directorout, directorargout
    • 39.2.5.6 directorin typemap
    • 39.2.5.7 directorout typemap
    • 39.2.5.8 directorargout typemap
  • 39.2.6 Exceptions
• 39.3 Documentation Features
  • 39.3.1 Module docstring

• 40.1 Introduction
• 40.2 Prerequisites
• 40.3 The Big Picture
• 40.4 Execution Model
  • 40.4.1 Preprocessing
  • 40.4.2 Parsing
  • 40.4.3 Parse Trees
  • 40.4.4 Attribute namespaces
  • 40.4.5 Symbol Tables
  • 40.4.6 The %feature directive
  • 40.4.7 Code Generation
  • 40.4.8 SWIG and XML
• 40.5 Primitive Data Structures
  • 40.5.1 Strings
  • 40.5.2 Hashes
  • 40.5.3 Lists
  • 40.5.4 Common operations
  • 40.5.5 Iterating over Lists and Hashes
  • 40.5.6 I/O
• 40.6 Navigating and manipulating parse trees
• 40.7 Working with attributes
• 40.8 Type system
  • 40.8.1 String encoding of types
  • 40.8.2 Type construction
  • 40.8.3 Type tests
  • 40.8.4 Typedef and inheritance
  • 40.8.5 Lvalues
  • 40.8.6 Output functions
• 40.9 Parameters
• 40.10 Writing a Language Module
  • 40.10.1 Execution model
  • 40.10.2 Starting out
  • 40.10.3 Command line options
  • 40.10.4 Configuration and preprocessing
  • 40.10.5 Entry point to code generation
  • 40.10.6 Module I/O and wrapper skeleton
  • 40.10.7 Low-level code generators
  • 40.10.8 Configuration files
  • 40.10.9 Runtime support
  • 40.10.10 Standard library files
  • 40.10.11 User examples
  • 40.10.12 Test driven development and the test-suite
    • 40.10.12.1 Running the test-suite
  • 40.10.13 Documentation
  • 40.10.14 Coding style guidelines
  • 40.10.15 Target language status
    • 40.10.15.1 Supported status
    • 40.10.15.2 Experimental status
  • 40.10.16 Prerequisites for adding a new language module to the SWIG distribution
• 40.11 Debugging Options
• 40.12 Guide to parse tree nodes
• 40.13 Further Development Information

SWIG-4.2 Documentation

Last update : SWIG-4.2.1 (24 Feb 2024)

Sections

SWIG Core Documentation

• Preface
• Introduction
• Getting started on Windows
• Scripting
• SWIG Basics (Read this!)
• SWIG and C++
• SWIG and C++11
• SWIG and C++14
• SWIG and C++17
• SWIG and C++20
• The SWIG preprocessor
• The SWIG library
• Argument handling
• Typemaps
• Customization features
• Contracts
• Variable length arguments
• Doxygen documentation comments
• Warning messages
• Working with Modules
• Using SWIG with ccache

Supported Language Modules Documentation

• Android support
• C# support
• D support
• Go support
• Guile support
• Java support
• Javascript support
• Lua support
• Octave support
• Perl5 support
• PHP support
• Python support
• R support
• Ruby support
• Scilab support
• Tcl support

Experimental Language Modules Documentation

• MzScheme/Racket support
• OCaml support

Developer Documentation

• Extending SWIG

1 Preface

1.1 Introduction

SWIG (Simplified Wrapper and Interface Generator) is a software development tool for building scripting language interfaces to C and C++ programs. Originally developed in 1995, SWIG was first used by scientists in the Theoretical Physics Division at Los Alamos National Laboratory for building user interfaces to simulation codes running on the Connection Machine 5 supercomputer. In this environment, scientists needed to work with huge amounts of simulation data, complex hardware, and a constantly changing code base. The use of a scripting language interface provided a simple yet highly flexible foundation for solving these types of problems. SWIG simplifies development by largely automating the task of scripting language integration--allowing developers and users to focus on more important problems.

Although SWIG was originally developed for scientific applications, it has since evolved into a general purpose tool that is used in a wide variety of applications--in fact almost anything where C/C++ programming is involved.

1.2 SWIG Versions

In the late 1990's, the most stable version of SWIG was release 1.1p5. Versions 1.3.x were officially development versions and these were released over a period of 10 years starting from the year 2000. The final version in the 1.3.x series was 1.3.40, but in truth the 1.3.x series had been stable for many years. An official stable version was released along with the decision to make SWIG license changes and this gave rise to version 2.0.0 in 2010. Version 3.0.0 was released in 2014 focusing on adding C++11 support and C++ nested classes. Version 4.0.0 was released in 2019 to add in Doxygen support. Some target languages were disabled as part of a clean up and others were given a new status of either 'Supported' or 'Experimental'.

1.3 SWIG License

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 - https://www.swig.org/legal.html.

The license was clarified in version 2.0.0 so that the code that SWIG generated could be distributed under license terms of the user's choice/requirements and at the same time the SWIG source was placed under the GNU General Public License version 3.

1.4 SWIG resources

The official location of SWIG related material is

https://www.swig.org

This site contains the latest version of the software, users guide, and information regarding bugs, installation problems, and implementation tricks.

You can also subscribe to the swig-user mailing list by visiting the page

https://www.swig.org/mail.html

The mailing list often discusses some of the more technical aspects of SWIG along with information about beta releases and future work.

Git and Subversion access to the latest version of SWIG is also available. More information about this can be obtained at:

SWIG Bleeding Edge

1.5 Prerequisites

This manual assumes that you know how to write C/C++ programs and that you have at least heard of scripting languages such as Tcl, Python, and Perl. A detailed knowledge of these scripting languages is not required although some familiarity won't hurt. No prior experience with building C extensions to these languages is required---after all, this is what SWIG does automatically. However, you should be reasonably familiar with the use of compilers, linkers, and makefiles since making scripting language extensions is somewhat more complicated than writing a normal C program.

Over time SWIG releases have become significantly more capable in their C++ handling--especially support for advanced features like namespaces, overloaded operators, and templates. Whenever possible, this manual tries to cover the technicalities of this interface. However, this isn't meant to be a tutorial on C++ programming. For many of the gory details, you will almost certainly want to consult a good C++ reference. If you don't program in C++, you may just want to skip those parts of the manual.

1.6 Organization of this manual

The first few chapters of this manual describe SWIG in general and provide an overview of its capabilities. The remaining chapters are devoted to specific SWIG language modules and are self contained. Thus, if you are using SWIG to build Python interfaces, you can probably skip to that chapter and find almost everything you need to know.

1.7 How to avoid reading the manual

If you hate reading manuals, glance at the "Introduction" which contains a few simple examples. These examples contain about 95% of everything you need to know to use SWIG. After that, simply use the language-specific chapters as a reference. The SWIG distribution also comes with a large directory of examples that illustrate different topics.

1.8 Backwards compatibility

If you are a previous user of SWIG, don't expect SWIG to provide complete backwards compatibility. Although the developers strive to the utmost to keep backwards compatibility, this isn't always possible as the primary goal over time is to make SWIG better---a process that would simply be impossible if the developers are constantly bogged down with backwards compatibility issues. Potential incompatibilities are clearly marked in the detailed release notes.

If you need to work with different versions of SWIG and backwards compatibility is an issue, you can use the SWIG_VERSION preprocessor symbol which holds the version of SWIG being executed. SWIG_VERSION is a hexadecimal integer such as 0x010311 (corresponding to SWIG-1.3.11). This can be used in an interface file to define different typemaps, take advantage of different features etc:

#if SWIG_VERSION >= 0x010311
/* Use some fancy new feature */
#endif

Note: The version symbol is not defined in the generated SWIG wrapper file. The SWIG preprocessor has defined SWIG_VERSION since SWIG-1.3.11.

1.9 Release notes

The CHANGES.current, CHANGES and RELEASENOTES files shipped with SWIG in the top level directory contain, respectively, detailed release notes for the current version, detailed release notes for previous releases and summary release notes from SWIG-1.3.22 onwards.

1.10 Credits

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 Donating to SWIG 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.

1.11 Bug reports

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 swig-devel mailing list or report a bug at the SWIG bug tracker. 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 can only fix bugs if we know about them.

1.12 Installation

1.12.1 Windows installation

Please see the dedicated Windows chapter for instructions on installing SWIG on Windows and running the examples. The Windows distribution is called swigwin and includes a prebuilt SWIG executable, swig.exe, included in the top level directory. Otherwise it is exactly the same as the main SWIG distribution. There is no need to download anything else.

1.12.2 Unix installation

These installation instructions are for using the distributed tarball, for example, swig-3.0.8.tar.gz. If you wish to build and install from source on Github, extra steps are required. Please see the Bleeding Edge page on the SWIG website.

You must use GNU make to build and install SWIG.

PCRE2 needs to be installed on your system to build SWIG, in particular 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.

To build and install SWIG, simply type the following:

$ ./configure
$ make
$ make install

By default SWIG installs itself in /usr/local. If you need to install SWIG in a different location or in your home directory, use the --prefix option to ./configure. For example:

$ ./configure --prefix=/home/yourname/projects
$ make
$ make install

Note: the directory given to --prefix must be an absolute pathname. Do not use the ~ shell-escape to refer to your home directory. SWIG won't work properly if you do this.

The INSTALL file shipped in the top level directory details more about using configure. Also try

$ ./configure --help.

The configure script will attempt to locate various packages on your machine including Tcl, Perl5, Python and all the other target languages that SWIG supports. Don't panic if you get 'not found' messages -- SWIG does not need these packages to compile or run. The configure script is actually looking for these packages so that you can try out the SWIG examples contained in the 'Examples' directory without having to hack Makefiles. Note that the --without-xxx options, where xxx is a target language, have minimal effect. All they do is reduce the amount of testing done with 'make check'. The SWIG executable and library files installed cannot currently be configured with a subset of target languages.

SWIG used to include a set of runtime libraries for some languages for working with multiple modules. These are no longer built during the installation stage. However, users can build them just like any wrapper module as described in the Modules chapter. The CHANGES file shipped with SWIG in the top level directory also lists some examples which build the runtime library.

Note:

• If you checked the code out via Git, you will have to run ./autogen.sh before ./configure. In addition, a full build of SWIG requires a number of packages to be installed. Full instructions at SWIG bleeding edge.

1.12.3 Macintosh OS X installation

SWIG is known to work on various flavors of OS X. Follow the Unix installation instructions above. However, as of this writing, there is still great deal of inconsistency with how shared libraries are handled by various scripting languages on OS X.

Users of OS X should be aware that Darwin handles shared libraries and linking in a radically different way than most Unix systems. In order to test SWIG and run the examples, SWIG configures itself to use flat namespaces and to allow undefined symbols (-flat_namespace -undefined suppress). This mostly closely follows the Unix model and makes it more likely that the SWIG examples will work with whatever installation of software you might have. However, this is generally not the recommended technique for building larger extension modules. Instead, you should utilize Darwin's two-level namespaces. Some details about this can be found here Understanding Two-Level Namespaces.

Needless to say, you might have to experiment a bit to get things working at first.

1.12.4 Testing

If you want to test SWIG after building it, a check can be performed on Unix operating systems. Type the following:

    $ make -k check

This step can be performed either before or after installation. The check requires at least one of the target languages to be installed. If it fails, it may mean that you have an uninstalled language module or that the file 'Examples/Makefile' has been incorrectly configured. It may also fail due to compiler issues such as a broken C++ compiler. Even if the check fails, there is a pretty good chance SWIG still works correctly --- you will just have to mess around with one of the examples and some makefiles to get it to work. Some tests may also fail due to missing dependency packages, eg PCRE or Boost, but this will require careful analysis of the configure output done during configuration.

The test suite executed by the check is designed to stress-test many parts of the implementation including obscure corner cases. If some of these tests fail or generate warning messages, there is no reason for alarm --- the test may be related to some new SWIG feature or a difficult bug that we're trying to resolve. Chances are that SWIG will work just fine for you. Note that if you have more than one CPU/core, then you can use parallel make to speed up the check as it does take quite some time to run, for example:

    $ make -j2 -k check

Also, SWIG's support for C++ is sufficiently advanced that certain tests may fail on older C++ compilers (for instance if your compiler does not support member templates). These errors are harmless if you don't intend to use these features in your own programs.

Note: The test-suite currently contains over 600 tests. If you have many different target languages installed and a slow machine, it might take more than an hour to run the test-suite.

1.12.5 Examples

The Examples directory contains a variety of examples of using SWIG and it has some browsable documentation. Simply point your browser to the file "Example/index.html".

The Examples directory also includes Visual C++ project 6 (.dsp) files for building some of the examples on Windows. Later versions of Visual Studio will convert these old style project files into a current solution file.

2 Introduction

2.1 What is SWIG?

SWIG is a software development tool that simplifies the task of interfacing different languages to C and C++ programs. In a nutshell, SWIG is a compiler that takes C/C++ declarations and creates the wrappers needed to access those declarations from other languages including Perl, Python, Tcl, Ruby, Guile, and Java. SWIG normally requires no modifications to existing code and can often be used to build a usable interface in only a few minutes. Possible applications of SWIG include:

• Building interpreted interfaces to existing C programs.
• Rapid prototyping and application development.
• Interactive debugging.
• Reengineering or refactoring of legacy software into scripting language components.
• Making a graphical user interface (using Tk for example).
• Testing of C libraries and programs (using scripts).
• Building high performance C modules for scripting languages.
• Making C programming more enjoyable (or tolerable depending on your point of view).
• Impressing your friends.
• Obtaining vast sums of research funding (although obviously not applicable to the author).

SWIG was originally designed to make it extremely easy for scientists and engineers to build extensible scientific software without having to get a degree in software engineering. Because of this, the use of SWIG tends to be somewhat informal and ad-hoc (e.g., SWIG does not require users to provide formal interface specifications as you would find in a dedicated IDL compiler). Although this style of development isn't appropriate for every project, it is particularly well suited to software development in the small; especially the research and development work that is commonly found in scientific and engineering projects. However, nowadays SWIG is known to be used in many large open source and commercial projects.

2.2 Why use SWIG?

As stated in the previous section, the primary purpose of SWIG is to simplify the task of integrating C/C++ with other programming languages. However, why would anyone want to do that? To answer that question, it is useful to list a few strengths of C/C++ programming:

• Excellent support for writing programming libraries.
• High performance (number crunching, data processing, graphics, etc.).
• Systems programming and systems integration.
• Large user community and software base.

Next, let's list a few problems with C/C++ programming

• Writing a user interface is rather painful (i.e., consider programming with MFC, X11, GTK, or any number of other libraries).
• Testing is time consuming (the compile/debug cycle).
• Not easy to reconfigure or customize without recompilation.
• Modularization can be tricky.
• Security concerns (buffer overflows for instance).

To address these limitations, many programmers have arrived at the conclusion that it is much easier to use different programming languages for different tasks. For instance, writing a graphical user interface may be significantly easier in a scripting language like Python or Tcl (consider the reasons why millions of programmers have used languages like Visual Basic if you need more proof). An interactive interpreter might also serve as a useful debugging and testing tool. Other languages like Java might greatly simplify the task of writing distributed computing software. The key point is that different programming languages offer different strengths and weaknesses. Moreover, it is extremely unlikely that any programming is ever going to be perfect. Therefore, by combining languages together, you can utilize the best features of each language and greatly simplify certain aspects of software development.

From the standpoint of C/C++, a lot of people use SWIG because they want to break out of the traditional monolithic C programming model which usually results in programs that resemble this:

• A collection of functions and variables that do something useful.
• A main() program that starts everything.
• A horrible collection of hacks that form some kind of user interface (but which no-one really wants to touch).

Instead of going down that route, incorporating C/C++ into a higher level language often results in a more modular design, less code, better flexibility, and increased programmer productivity.

SWIG tries to make the problem of C/C++ integration as painless as possible. This allows you to focus on the underlying C program and using the high-level language interface, but not the tedious and complex chore of making the two languages talk to each other. At the same time, SWIG recognizes that all applications are different. Therefore, it provides a wide variety of customization features that let you change almost every aspect of the language bindings. This is the main reason why SWIG has such a large user manual ;-).

2.3 Target languages

SWIG in essence is a tool to generate code for making C/C++ code available to various other programming languages. These higher level programming languages are the target languages for the SWIG code generator and C or C++ are the input languages. A single target language must be specified when SWIG is run. This results in generating code for C/C++ and the specified target language to interface with each other. SWIG can be invoked multiple times, but with a different target language specified on each invocation. This ability to interface C/C++ to many different target languages is one of SWIG's core strengths and features.

SWIG is very broadly composed of two components. A core component creates a parse tree from the input ISO C/C++ and SWIG directives (extensions to the C/C++ standards). The parse tree is then passed to a second component, one of the target language modules for generating code specific to a higher level language. SWIG supports many different target languages. These target languages are given a status of either Supported or Experimental. This status is provided to indicate the level of maturity to expect when using a particular target language as not all target languages are fully developed.

The second part of the SWIG documentation contains a chapter for each target level language. The target language chapters are under one of two sections indicating the status (Supported or Experimental) for that language.

2.3.1 Supported status

A target language is given the 'Supported' status when

• It is in a mature, well functioning state.
• It has its own comprehensive chapter in the documentation.
• It passes all of the main SWIG test-suite and has a range of working examples.
• It supports the vast majority of SWIG features.
• It provides strong backwards compatibility between releases.

The above is a short summary and further details are outlined in the Supported status section in the Extending chapter. The good news is that all the well-known and most popular languages have this status.

2.3.2 Experimental status

A target language is given the 'Experimental' status when

• It is of sub-standard quality, failing to meet the above 'Supported' status.
• It is somewhere between the mid to mature stage of development.
• It does not guarantee any backwards compatibility between releases.
• It is in need of help to finish development.

Anyone using an experimental target language is strongly urged to assist with development of the target language module if they wish to use it.

SWIG displays a warning when an experimental target language is used in order to set expectations and emphasize the experimental status of the target language. The usual warning suppression techniques can be used if required.

The above is a short summary and further details are outlined in the Experimental status section in the Extending chapter.

2.4 A SWIG example

The best way to illustrate SWIG is with a simple example. Consider the following C code:

/* File : example.c */

double My_variable = 3.0;

/* Compute factorial of n */
int fact(int n) {
  if (n <= 1)
    return 1;
  else
    return n*fact(n-1);
}

/* Compute n mod m */
int my_mod(int n, int m) {
  return(n % m);
}

Suppose that you wanted to access these functions and the global variable My_variable from Tcl. You start by making a SWIG interface file as shown below (by convention, these files carry a .i suffix) :

2.4.1 SWIG interface file

/* File : example.i */
%module example
%{
/* Put headers and other declarations here */
extern double My_variable;
extern int    fact(int);
extern int    my_mod(int n, int m);
%}

extern double My_variable;
extern int    fact(int);
extern int    my_mod(int n, int m);

The interface file contains ISO C function prototypes and variable declarations. The %module directive defines the name of the module that will be created by SWIG. The %{ %} block provides a location for inserting additional code, such as C header files or additional C declarations, into the generated C wrapper code.

2.4.2 The swig command

SWIG is invoked using the swig command. We can use this to build a Tcl module (under Linux) as follows :

unix > swig -tcl example.i
unix > gcc -c -fpic example.c example_wrap.c -I/usr/local/include
unix > gcc -shared example.o example_wrap.o -o example.so
unix > tclsh
% load ./example.so
% fact 4
24
% my_mod 23 7
2
% expr $My_variable + 4.5
7.5
%

The swig command produced a new file called example_wrap.c that should be compiled along with the example.c file. Most operating systems and scripting languages now support dynamic loading of modules. In our example, our Tcl module has been compiled into a shared library that can be loaded into Tcl. When loaded, Tcl can now access the functions and variables declared in the SWIG interface. A look at the file example_wrap.c reveals a hideous mess. However, you almost never need to worry about it.

2.4.3 Building a Perl5 module

Now, let's turn these functions into a Perl5 module. Without making any changes type the following (shown for Solaris):

unix > swig -perl5 example.i
unix > gcc -c example.c example_wrap.c \
        -I/usr/local/lib/perl5/sun4-solaris/5.003/CORE
unix > ld -G example.o example_wrap.o -o example.so # This is for Solaris
unix > perl5.003
use example;
print example::fact(4), "\n";
print example::my_mod(23, 7), "\n";
print $example::My_variable + 4.5, "\n";
<ctrl-d>
24
2
7.5
unix >

2.4.4 Building a Python module

Finally, let's build a module for Python (shown for Irix).

unix > swig -python example.i
unix > gcc -c -fpic example.c example_wrap.c -I/usr/local/include/python2.0
unix > gcc -shared example.o example_wrap.o -o _example.so
unix > python
Python 2.0 (#6, Feb 21 2001, 13:29:45)
[GCC egcs-2.91.66 19990314/Linux (egcs-1.1.2 release)] on linux2
Type "copyright", "credits" or "license" for more information.     
>>> import example
>>> example.fact(4)
24
>>> example.my_mod(23, 7)
2
>>> example.cvar.My_variable + 4.5
7.5

2.4.5 Shortcuts

To the truly lazy programmer, one may wonder why we needed the extra interface file at all. As it turns out, you can often do without it. For example, you could also build a Perl5 module by just running SWIG on the C header file and specifying a module name as follows

unix > swig -perl5 -module example example.h
unix > gcc -c example.c example_wrap.c \
        -I/usr/local/lib/perl5/sun4-solaris/5.003/CORE
unix > ld -G example.o example_wrap.o -o example.so
unix > perl5.003
use example;
print example::fact(4), "\n";
print example::my_mod(23, 7), "\n";
print $example::My_variable + 4.5, "\n";
<ctrl-d>
24
2
7.5

2.5 Supported C/C++ language features

A primary goal of the SWIG project is to make the language binding process extremely easy. Although a few simple examples have been shown, SWIG is quite capable in supporting most of C++. Some of the major features include:

• Full C99 preprocessing.
• All ISO C and C++ datatypes.
• Functions, variables, and constants.
• Classes.
• Single and multiple inheritance.
• Overloaded functions and methods.
• Overloaded operators.
• C++ templates (including member templates, specialization, and partial specialization).
• Namespaces.
• Variable length arguments.
• C++ smart pointers.

Most of C++11 is also supported. Details are in the C++11 chapter. C++14 support is covered in the C++14 chapter. C++17 support is covered in the C++17 chapter. C++20 support is covered in the C++20 chapter.

It is important to stress that SWIG is not a simplistic C++ lexing tool like several apparently similar wrapper generation tools. SWIG not only parses C++, it implements the full C++ type system and it is able to understand C++ semantics. SWIG generates its wrappers with full knowledge of this information. As a result, you will find SWIG to be just as capable of dealing with nasty corner cases as it is in wrapping simple C++ code. In fact, SWIG is able to handle C++ code that stresses the very limits of many C++ compilers.

2.6 Non-intrusive interface building

When used as intended, SWIG requires minimal (if any) modification to existing C or C++ code. This makes SWIG extremely easy to use with existing packages and promotes software reuse and modularity. By making the C/C++ code independent of the high level interface, you can change the interface and reuse the code in other applications. It is also possible to support different types of interfaces depending on the application.

2.7 Incorporating SWIG into a build system

SWIG is a command line tool and as such can be incorporated into any build system that supports invoking external tools/compilers. SWIG is most commonly invoked from within a Makefile, but is also known to be invoked from popular IDEs such as Microsoft Visual Studio.

If you are using the GNU Autotools ( Autoconf/ Automake / Libtool) to configure SWIG use in your project, the SWIG Autoconf macros can be used. The primary macro is ax_pkg_swig, see http://www.gnu.org/software/autoconf-archive/ax_pkg_swig.html#ax_pkg_swig . The ax_python_devel macro is also helpful for generating Python extensions. See the Autoconf Archive for further information on this and other Autoconf macros.

There is growing support for SWIG in some build tools, for example CMake is a cross-platform, open-source build manager with built in support for SWIG. CMake can detect the SWIG executable and many of the target language libraries for linking against. CMake knows how to build shared libraries and loadable modules on many different operating systems. This allows easy cross platform SWIG development. It can also generate the custom commands necessary for driving SWIG from IDEs and makefiles. All of this can be done from a single cross platform input file. The following example is a CMake input file for creating a Python wrapper for the SWIG interface file, example.i:

# This is a CMake example for Python

FIND_PACKAGE(SWIG REQUIRED)
INCLUDE(${SWIG_USE_FILE})

FIND_PACKAGE(PythonLibs)
INCLUDE_DIRECTORIES(${PYTHON_INCLUDE_PATH})

INCLUDE_DIRECTORIES(${CMAKE_CURRENT_SOURCE_DIR})

SET(CMAKE_SWIG_FLAGS "")

SET_SOURCE_FILES_PROPERTIES(example.i PROPERTIES CPLUSPLUS ON)
SET_SOURCE_FILES_PROPERTIES(example.i PROPERTIES SWIG_FLAGS "-includeall")
SWIG_ADD_MODULE(example python example.i example.cxx)
SWIG_LINK_LIBRARIES(example ${PYTHON_LIBRARIES})

The above example will generate native build files such as makefiles, nmake files and Visual Studio projects which will invoke SWIG and compile the generated C++ files into _example.so (UNIX) or _example.pyd (Windows). For other target languages on Windows a dll, instead of a .pyd file, is usually generated.

2.8 Hands off code generation

SWIG is designed to produce working code that needs no hand-modification (in fact, if you look at the output, you probably won't want to modify it). You should think of your target language interface being defined entirely by the input to SWIG, not the resulting output file. While this approach may limit flexibility for hard-core hackers, it allows others to forget about the low-level implementation details.

2.9 SWIG and freedom

No, this isn't a special section on the sorry state of world politics. However, it may be useful to know that SWIG was written with a certain "philosophy" about programming---namely that programmers are smart and that tools should just stay out of their way. Because of that, you will find that SWIG is extremely permissive in what it lets you get away with. In fact, you can use SWIG to go well beyond "shooting yourself in the foot" if dangerous programming is your goal. On the other hand, this kind of freedom may be exactly what is needed to work with complicated and unusual C/C++ applications.

Ironically, the freedom that SWIG provides is countered by an extremely conservative approach to code generation. At its core, SWIG tries to distill even the most advanced C++ code down to a small well-defined set of interface building techniques based on ISO C programming. Because of this, you will find that SWIG interfaces can be easily compiled by virtually every C/C++ compiler and that they can be used on any platform. Again, this is an important part of staying out of the programmer's way----the last thing any developer wants to do is to spend their time debugging the output of a tool that relies on non-portable or unreliable programming features. Dependencies are often a source of incompatibilities and problems and so additional third party libraries are not used in the generated code. SWIG will also generally avoid generating code that introduces a dependency on the C++ Standard Template Library (STL). SWIG will generate code that depends on the C libraries though.

3 Getting started on Windows

This chapter describes SWIG usage on Microsoft Windows. Installing SWIG and running the examples is covered as well as building the SWIG executable. Usage within the Unix like environments MinGW and Cygwin is also detailed.

3.1 Installation on Windows

SWIG does not come with the usual Windows type installation program, however it is quite easy to get started. The main steps are:

• Download the swigwin zip package from the SWIG website and unzip into a directory. This is all that needs downloading for the Windows platform.
• Set environment variables as described in the SWIG Windows Examples section in order to run examples using Visual C++.

3.1.1 Windows Executable

The swigwin distribution contains the SWIG Windows 32-bit executable, swig.exe, which will run on both 32-bit and 64-bit versions of Windows. If you want to build your own swig.exe have a look at Building swig.exe on Windows.

3.2 SWIG Windows Examples

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 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 examples using Cygwin.

More information on each of the examples is available with the examples distributed with SWIG (Examples/index.html).

3.2.1 Instructions for using the Examples with Visual Studio

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

The list of required environment variables for each module language is also listed below. They are usually set from the Control Panel and System properties, but this depends on which flavour of Windows you are running. If you don't want to use environment variables then change all occurrences of the environment variables in the .dsp files with hard coded values. If you are interested in how the project files are set up there is explanatory information in some of the language module's documentation.

3.2.1.1 C#

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

3.2.1.2 Java

JAVA_INCLUDE : Set this to the directory containing jni.h
JAVA_BIN : Set this to the bin directory containing javac.exe

Example using JDK1.3:
JAVA_INCLUDE: D:\jdk1.3\include
JAVA_BIN: D:\jdk1.3\bin

3.2.1.3 Perl

PERL5_INCLUDE : Set this to the directory containing perl.h
PERL5_LIB : Set this to the Perl library including path for linking

Example using nsPerl 5.004_04:

PERL5_INCLUDE: D:\nsPerl5.004_04\lib\CORE
PERL5_LIB: D:\nsPerl5.004_04\lib\CORE\perl.lib

3.2.1.4 Python

PYTHON_INCLUDE : Set this to the directory that contains Python.h
PYTHON_LIB : Set this to the Python library including path for linking

Example using Python 2.1.1:
PYTHON_INCLUDE: D:\python21\include
PYTHON_LIB: D:\python21\libs\python21.lib

3.2.1.5 TCL

TCL_INCLUDE : Set this to the directory containing tcl.h
TCL_LIB : Set this to the TCL library including path for linking

Example using ActiveTcl 8.3.3.3
TCL_INCLUDE: D:\tcl\include
TCL_LIB: D:\tcl\lib\tcl83.lib

3.2.1.6 R

R_INCLUDE : Set this to the directory containing R.h
R_LIB : Set this to the R library (Rdll.lib) including path for linking. The library needs to be built as described in the R README.packages file (the pexports.exe approach is the easiest).

Example using R 2.5.1:
R_INCLUDE: C:\Program Files\R\R-2.5.1\include
R_LIB: C:\Program Files\R\R-2.5.1\bin\Rdll.lib

3.2.1.7 Ruby

RUBY_INCLUDE : Set this to the directory containing ruby.h
RUBY_LIB : Set this to the ruby library including path for linking

Example using Ruby 1.6.4:
RUBY_INCLUDE: D:\ruby\lib\ruby\1.6\i586-mswin32
RUBY_LIB: D:\ruby\lib\mswin32-ruby16.lib

3.2.2 Instructions for using the Examples with other compilers

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.

3.3 Building swig.exe on Windows

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.

There are various ways to build the SWIG executable including CMake which is able to generate project files for building with Visual Studio. SWIG can also be compiled and run using MSYS2, Cygwin or MinGW, all of which provide a Unix like front end to Windows and comes free with the gcc C/C++ compiler.

3.3.1 Building swig.exe using CMake

SWIG can be built using CMake 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 GitHub Actions YAML file.

1. Install Nuget from https://www.nuget.org/downloads (v6.0.0 is used in this example, and installed to C:\Tools). Nuget is the package manager for .NET, but allows us to easily install CMake and other dependencies required by SWIG.
2. Install CMake-win64 Nuget package using the following command:

   C:\Tools\nuget install CMake-win64 -Version 3.15.5 -OutputDirectory C:\Tools\CMake

   Using PowerShell the equivalent syntax is:

   & "C:\Tools\nuget" install CMake-win64 -Version 3.15.5 -OutputDirectory C:\Tools\CMake

   Alternatively you can download CMake from https://cmake.org/download/.
3. Install the Bison Nuget package using the following command:

   C:\Tools\nuget install Bison -Version 3.7.4 -OutputDirectory C:\Tools\bison

   Alternatively download Bison from https://sourceforge.net/projects/winflexbison/files/ (Bison 3.7.4 is used in this example) and save to a folder e.g. C:\Tools\Bison
4. Install the PCRE2 Nuget package using the following command:

   C:\Tools\nuget install PCRE2 -Version 10.39 -OutputDirectory C:\Tools\pcre2

   Note this is a x64 build, if this is not suitable PCRE2 can be built from source using https://github.com/PhilipHazel/pcre2/. Alternatively, set WITH_PCRE=OFF to disable PCRE2 support if you are sure you do not require it.
5. 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:

   git clone https://github.com/swig/swig.git

   In this example we are assuming the source code is available at C:\swig

6. 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 "Visual Studio 16 2019 -A x64" to the relevant Visual Studio Generator 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 C:/swig/install2/bin folder.

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

In addition to Release builds you can create a Debug build using:

cmake --build build --config Debug

A Visual Studio solution file should be generated named swig.sln. This can be opened and debugged by running the swig project and setting Properties > Debugging > Command Arguments. For example to debug one of the test-suite .i files included with the SWIG source use the following:

-python -c++ -o C:\Temp\doxygen_parsing.cpp C:\swig\Examples\test-suite\doxygen_parsing.i

3.3.2 Building swig.exe using MSYS2

Download and install MSYS2 from www.msys2.org (tested with version msys2-x86_64-20201109). Launch the MSYS2 shell.

Install the packages needed to build swig:

pacman -S git autoconf automake bison gcc make pcre2-devel

Clone the repository to /usr/src/:

mkdir /usr/src/
cd /usr/src/
git clone https://github.com/swig/swig.git

Configure and build:

cd /usr/src/swig
./autogen.sh
./configure
make

Finally you may also want to install SWIG:

make install

3.3.3 Building swig.exe using MinGW and MSYS

Warning: These instructions were added in 2006 and have barely changed since so are unlikely to work exactly as written.

The short abbreviated instructions follow...

• Install MinGW and MSYS from the MinGW site. This provides a Unix environment on Windows.
• Follow the usual Unix instructions in the README file in the SWIG root directory to build swig.exe from the MinGW command prompt.

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 SWIG Bleeding Edge.

Pitfall note: Execute the steps in the order shown and don't use spaces in path names. In fact it is best to use the default installation directories.

1. Download the following packages from the MinGW download page. 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.
   • MinGW-3.1.0-1.exe
   • MSYS-1.0.11-2004.04.30-1.exe
   • msysDTK-1.0.1.exe
   • bison-2.0-MSYS.tar.gz
   • msys-autoconf-2.59.tar.bz2
   • msys-automake-1.8.2.tar.bz2
2. Install MinGW-3.1.0-1.exe (C:\MinGW is default location.)
3. Install MSYS-1.0.11-2004.04.30-1.exe. Make sure you install it on the same windows drive letter as MinGW (C:\msys\1.0 is default). In the post install script,
   • Answer y to the "do you wish to continue with the post install?"
   • Answer y to the "do you have MinGW installed?"
   • Type in the folder in which you installed MinGW (C:/MinGW is default)
4. Install msysDTK-1.0.1.exe to the same folder that you installed MSYS (C:\msys\1.0 is default).
5. Copy the following to the MSYS install folder (C:\msys\1.0 is default):
   • msys-automake-1.8.2.tar.bz2
   • msys-autoconf-2.59.tar.bz2
   • bison-2.0-MSYS.tar.gz
6. Start the MSYS command prompt and execute:

   cd /
   tar -jxf msys-automake-1.8.2.tar.bz2
   tar -jxf msys-autoconf-2.59.tar.bz2
   tar -zxf bison-2.0-MSYS.tar.gz
   

7. The very latest development version of SWIG is available from SWIG on Github and can be downloaded as a zip file or if you have Git installed, via Git. Either download the latest Zip file snapshot and unzip and rename the top level folder to /usr/src/swig. Otherwise if using Git, type in the following:

   mkdir /usr/src
   cd /usr/src
   git clone https://github.com/swig/swig.git
   

   Pitfall note: If you want to place SWIG in a different folder to the proposed /usr/src/swig, do not use MSYS emulated windows drive letters, because the autotools will fail miserably on those.
8. The PCRE2 third party library needs to be built next. Download the latest PCRE2 source tarball, such as pcre2-10.39.tar.bz2, from www.pcre.org and place in the /usr/src/swig directory. Build PCRE2 as a static library using the Tools/pcre-build.sh script as follows:

   cd /usr/src/swig
   Tools/pcre-build.sh
   

9. You are now ready to build SWIG. Execute the following commands to build swig.exe:

   cd /usr/src/swig
   ./autogen.sh
   ./configure
   make
   

3.3.4 Building swig.exe using Cygwin

Note that SWIG can also be built using Cygwin. However, SWIG will then require the Cygwin DLL when executing. Follow the Unix instructions in the README file in the SWIG root directory. Note that the Cygwin environment will also allow one to regenerate the autotool generated files which are supplied with the release distribution. These files are generated using the autogen.sh script and will only need regenerating in circumstances such as changing the build system.

3.3.4.1 Running the examples on Windows using Cygwin

The examples and test-suite work as successfully on Cygwin as on any other Unix operating system. The modules which are known to work are Python, Tcl, Perl, Ruby, Java and C#. Follow the Unix instructions in the README file in the SWIG root directory to build the examples.

3.4 Microsoft extensions and other Windows quirks

A common problem when using SWIG on Windows are the Microsoft function calling conventions which are not in the C++ standard. SWIG parses ISO C/C++ so cannot deal with proprietary conventions such as __declspec(dllimport), __stdcall etc. There is a Windows interface file, windows.i, to deal with these calling conventions though. The file also contains typemaps for handling commonly used Windows specific types such as __int64, BOOL , DWORD etc. Include it like you would any other interface file, for example:

%include <windows.i>

__declspec(dllexport) ULONG __stdcall foo(DWORD, __int32);

Note that if you follow Microsoft's recommendation of wrapping the __declspec calls in a preprocessor definition, you will need to make sure that the definition is included by SWIG as well, by either defining it manually or via a header. For example, if you have specified the preprocessor definition in a header named export_lib.h and include other headers which depend on it, you should use the %include directive to include the definition explicitly. For example, if you had a header file, bar.h, which depended on export_lib.h, your SWIG definition file might look like:

// bar.i
%module bar
%include <windows.i>
%include "export_lib.h"
%include "bar.h"

where export_lib.h may contain:

// export_lib.h
#define BAR_API __declspec(dllexport)

and bar.h may look like:

// bar.h
#include "export_lib.h"
BAR_API void bar_function(int, double);

Using the preprocessor to remove BAR_API is a popular simpler solution:

// bar.i
%module bar
#define BAR_API
%include "bar.h"

4 Scripting Languages

This chapter provides a brief overview of scripting language extension programming and the mechanisms by which scripting language interpreters access C and C++ code.

4.1 The two language view of the world

When a scripting language is used to control a C program, the resulting system tends to look as follows:

In this programming model, the scripting language interpreter is used for high level control whereas the underlying functionality of the C/C++ program is accessed through special scripting language "commands." If you have ever tried to write your own simple command interpreter, you might view the scripting language approach to be a highly advanced implementation of that. Likewise, If you have ever used a package such as MATLAB or IDL, it is a very similar model--the interpreter executes user commands and scripts. However, most of the underlying functionality is written in a low-level language like C or Fortran.

The two-language model of computing is extremely powerful because it exploits the strengths of each language. C/C++ can be used for maximal performance and complicated systems programming tasks. Scripting languages can be used for rapid prototyping, interactive debugging, scripting, and access to high-level data structures such associative arrays.

4.2 How does a scripting language talk to C?

Scripting languages are built around a parser that knows how to execute commands and scripts. Within this parser, there is a mechanism for executing commands and accessing variables. Normally, this is used to implement the builtin features of the language. However, by extending the interpreter, it is usually possible to add new commands and variables. To do this, most languages define a special API for adding new commands. Furthermore, a special foreign function interface defines how these new commands are supposed to hook into the interpreter.

Typically, when you add a new command to a scripting interpreter you need to do two things; first you need to write a special "wrapper" function that serves as the glue between the interpreter and the underlying C function. Then you need to give the interpreter information about the wrapper by providing details about the name of the function, arguments, and so forth. The next few sections illustrate the process.

4.2.1 Wrapper functions

Suppose you have an ordinary C function like this :

int fact(int n) {
  if (n <= 1)
    return 1;
  else
    return n*fact(n-1);
}

In order to access this function from a scripting language, it is necessary to write a special "wrapper" function that serves as the glue between the scripting language and the underlying C function. A wrapper function must do three things :

• Gather function arguments and make sure they are valid.
• Call the C function.
• Convert the return value into a form recognized by the scripting language.

As an example, the Tcl wrapper function for the fact() function above example might look like the following :

int wrap_fact(ClientData clientData, Tcl_Interp *interp, int argc, char *argv[]) {
  int result;
  int arg0;
  if (argc != 2) {
    interp->result = "wrong # args";
    return TCL_ERROR;
  }
  arg0 = atoi(argv[1]);
  result = fact(arg0);
  sprintf(interp->result, "%d", result);
  return TCL_OK;
}

Once you have created a wrapper function, the final step is to tell the scripting language about the new function. This is usually done in an initialization function called by the language when the module is loaded. For example, adding the above function to the Tcl interpreter requires code like the following :

int Wrap_Init(Tcl_Interp *interp) {
  Tcl_CreateCommand(interp, "fact", wrap_fact, (ClientData) NULL,
                    (Tcl_CmdDeleteProc *) NULL);
  return TCL_OK;
}

When executed, Tcl will now have a new command called "fact " that you can use like any other Tcl command.

Although the process of adding a new function to Tcl has been illustrated, the procedure is almost identical for Perl and Python. Both require special wrappers to be written and both need additional initialization code. Only the specific details are different.

4.2.2 Variable linking

Variable linking refers to the problem of mapping a C/C++ global variable to a variable in the scripting language interpreter. For example, suppose you had the following variable:

double Foo = 3.5;

It might be nice to access it from a script as follows (shown for Perl):

$a = $Foo * 2.3;   # Evaluation
$Foo = $a + 2.0;   # Assignment

To provide such access, variables are commonly manipulated using a pair of get/set functions. For example, whenever the value of a variable is read, a "get" function is invoked. Similarly, whenever the value of a variable is changed, a "set" function is called.

In many languages, calls to the get/set functions can be attached to evaluation and assignment operators. Therefore, evaluating a variable such as $Foo might implicitly call the get function. Similarly, typing $Foo = 4 would call the underlying set function to change the value.

4.2.3 Constants

In many cases, a C program or library may define a large collection of constants. For example:

#define RED   0xff0000
#define BLUE  0x0000ff
#define GREEN 0x00ff00

To make constants available, their values can be stored in scripting language variables such as $RED, $BLUE, and $GREEN. Virtually all scripting languages provide C functions for creating variables so installing constants is usually a trivial exercise.

4.2.4 Structures and classes

Although scripting languages have no trouble accessing simple functions and variables, accessing C/C++ structures and classes present a different problem. This is because the implementation of structures is largely related to the problem of data representation and layout. Furthermore, certain language features are difficult to map to an interpreter. For instance, what does C++ inheritance mean in a Perl interface?

The most straightforward technique for handling structures is to implement a collection of accessor functions that hide the underlying representation of a structure. For example,

struct Vector {
  Vector();
  ~Vector();
  double x, y, z;
};

can be transformed into the following set of functions :

Vector *new_Vector();
void delete_Vector(Vector *v);
double Vector_x_get(Vector *v);
double Vector_y_get(Vector *v);
double Vector_z_get(Vector *v);
void Vector_x_set(Vector *v, double x);
void Vector_y_set(Vector *v, double y);
void Vector_z_set(Vector *v, double z);

Now, from an interpreter these function might be used as follows:

% set v [new_Vector]
% Vector_x_set $v 3.5
% Vector_y_get $v
% delete_Vector $v
% ...

Since accessor functions provide a mechanism for accessing the internals of an object, the interpreter does not need to know anything about the actual representation of a Vector.

4.2.5 Proxy classes

In certain cases, it is possible to use the low-level accessor functions to create a proxy class, also known as a shadow class. A proxy class is a special kind of object that gets created in a scripting language to access a C/C++ class (or struct) in a way that looks like the original structure (that is, it proxies the real C++ class). For example, if you have the following C++ definition :

class Vector {
public:
  Vector();
  ~Vector();
  double x, y, z;
};

A proxy classing mechanism would allow you to access the structure in a more natural manner from the interpreter. For example, in Python, you might want to do this:

>>> v = Vector()
>>> v.x = 3
>>> v.y = 4
>>> v.z = -13
>>> ...
>>> del v

Similarly, in Perl5 you may want the interface to work like this:

$v = new Vector;
$v->{x} = 3;
$v->{y} = 4;
$v->{z} = -13;

Finally, in Tcl :

Vector v
v configure -x 3 -y 4 -z -13

When proxy classes are used, two objects are really at work--one in the scripting language, and an underlying C/C++ object. Operations affect both objects equally and for all practical purposes, it appears as if you are simply manipulating a C/C++ object.

4.3 Building scripting language extensions

The final step in using a scripting language with your C/C++ application is adding your extensions to the scripting language itself. There are two primary approaches for doing this. The preferred technique is to build a dynamically loadable extension in the form of a shared library. Alternatively, you can recompile the scripting language interpreter with your extensions added to it.

4.3.1 Shared libraries and dynamic loading

To create a shared library or DLL, you often need to look at the manual pages for your compiler and linker. However, the procedure for a few common platforms is shown below:

# Build a shared library for Solaris
gcc -fpic -c example.c example_wrap.c -I/usr/local/include
ld -G example.o example_wrap.o -o example.so

# Build a shared library for Linux
gcc -fpic -c example.c example_wrap.c -I/usr/local/include
gcc -shared example.o example_wrap.o -o example.so

To use your shared library, you simply use the corresponding command in the scripting language (load, import, use, etc...). This will import your module and allow you to start using it. For example:

% load ./example.so
% fact 4
24
%

When working with C++ codes, the process of building shared libraries may be more complicated--primarily due to the fact that C++ modules may need additional code in order to operate correctly. On many machines, you can build a shared C++ module by following the above procedures, but changing the link line to the following :

c++ -shared example.o example_wrap.o -o example.so

4.3.2 Linking with shared libraries

When building extensions as shared libraries, it is not uncommon for your extension to rely upon other shared libraries on your machine. In order for the extension to work, it needs to be able to find all of these libraries at run-time. Otherwise, you may get an error such as the following :

>>> import graph
Traceback (innermost last):
  File "<stdin>", line 1, in ?
  File "/home/sci/data1/beazley/graph/graph.py", line 2, in ?
    import graphc
ImportError:  1101:/home/sci/data1/beazley/bin/python: rld: Fatal Error: cannot 
successfully map soname 'libgraph.so' under any of the filenames /usr/lib/libgraph.so:/
lib/libgraph.so:/lib/cmplrs/cc/libgraph.so:/usr/lib/cmplrs/cc/libgraph.so:
>>>

What this error means is that the extension module created by SWIG depends upon a shared library called "libgraph.so" that the system was unable to locate. To fix this problem, there are a few approaches you can take.

• Link your extension and explicitly tell the linker where the required libraries are located. Often times, this can be done with a special linker flag such as -R, -rpath, etc. This is not implemented in a standard manner so read the man pages for your linker to find out more about how to set the search path for shared libraries.
• Put shared libraries in the same directory as the executable. This technique is sometimes required for correct operation on non-Unix platforms.
• Set the UNIX environment variable LD_LIBRARY_PATH to the directory where shared libraries are located before running Python. Although this is an easy solution, it is not recommended. Consider setting the path using linker options instead.

4.3.3 Static linking

With static linking, you rebuild the scripting language interpreter with extensions. The process usually involves compiling a short main program that adds your customized commands to the language and starts the interpreter. You then link your program with a library to produce a new scripting language executable.

Although static linking is supported on all platforms, this is not the preferred technique for building scripting language extensions. In fact, there are very few practical reasons for doing this--consider using shared libraries instead.

5 SWIG Basics

This chapter describes the basic operation of SWIG, the structure of its input files, and how it handles standard ISO C declarations. C++ support is described in the next chapter. However, C++ programmers should still read this chapter to understand the basics. Specific details about each target language are described in later chapters.

5.1 Running SWIG

To run SWIG, use the swig command with options and a filename like this:

swig [ options ] filename

where filename is a SWIG interface file or a C/C++ header file. Full help can be seen by running swig -help. Below is the common set of options that can be used. Additional options are also defined for each target language. A full list can be obtained by running swig -<lang> -help for language <lang> specific options, for example, swig -ruby -help for Ruby.

Supported Target Language Options
     -csharp         - Generate C# wrappers
     -d              - Generate D wrappers
     -go             - Generate Go wrappers
     -guile          - Generate Guile wrappers
     -java           - Generate Java wrappers
     -javascript     - Generate Javascript wrappers
     -lua            - Generate Lua wrappers
     -octave         - Generate Octave wrappers
     -perl5          - Generate Perl 5 wrappers
     -php7           - Generate PHP 8 or later wrappers
     -python         - Generate Python wrappers
     -r              - Generate R (aka GNU S) wrappers
     -ruby           - Generate Ruby wrappers
     -scilab         - Generate Scilab wrappers
     -tcl8           - Generate Tcl 8 wrappers
     -xml            - Generate XML wrappers

Experimental Target Language Options
     -mzscheme       - Generate MzScheme/Racket wrappers
     -ocaml          - Generate OCaml wrappers

General Options
     -addextern      - Add extra extern declarations
     -c++            - Enable C++ processing
     -co <file>      - Check <file> out of the SWIG library
     -copyctor       - Automatically generate copy constructors wherever possible
     -cpperraswarn   - Treat the preprocessor #error statement as #warning (default)
     -cppext <ext>   - Change file extension of generated C++ files to <ext>
                       (default is cxx)
     -copyright      - Display copyright notices
     -debug-classes  - Display information about the classes found in the interface
     -debug-module <n>- Display module parse tree at stages 1-4, <n> is a csv list of stages
     -debug-symtabs  - Display symbol tables information
     -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 <n>  - Display entire parse tree at stages 1-4, <n> is a csv list of stages
     -debug-typedef  - Display information about the types and typedefs in the interface
     -debug-typemap  - Display typemap debugging information
     -debug-tmsearch - Display typemap search debugging information
     -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<symbol>[=<value>] - Define symbol <symbol> (for conditional compilation)
     -E              - Preprocess only, does not generate wrapper code
     -external-runtime [file] - Export the SWIG runtime stack
     -fakeversion <v>- Make SWIG fake the program version number to <v>
     -fcompact       - Compile in compact mode
     -features <list>- Set global features, where <list> is a comma separated list of
                       features, eg -features directors,autodoc=1
                       If no explicit value is given to the feature, a default of 1 is used
     -fastdispatch   - Enable fast dispatch mode to produce faster overload dispatcher code
     -Fmicrosoft     - Display error/warning messages in Microsoft format
     -Fstandard      - Display error/warning messages in commonly used format
     -fvirtual       - Compile in virtual elimination mode
     -help           - Display help
     -I-             - Don't search the current directory
     -I<dir>         - Look for SWIG files in directory <dir>
     -ignoremissing  - Ignore missing include files
     -importall      - Follow all #include statements as imports
     -includeall     - Follow all #include statements
     -l<ifile>       - Include SWIG library file <ifile>
     -macroerrors    - Report errors inside macros
     -M              - List all dependencies
     -MD             - Is equivalent to `-M -MF <file>', except `-E' is not implied
     -MF <file>      - Generate dependencies into <file> and continue generating wrappers
     -MM             - List dependencies, but omit files in SWIG library
     -MMD            - Like `-MD', but omit files in SWIG library
     -module <name>  - Set module name to <name>
     -MP             - Generate phony targets for all dependencies
     -MT <target>    - 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
     -nodefaultctor  - Do not generate implicit default constructors
     -nodefaultdtor  - Do not generate implicit default destructors
     -nodirprot      - Do not wrap director protected members
     -noexcept       - Do not wrap exception specifiers
     -nofastdispatch - Disable fast dispatch mode (default)
     -nopreprocess   - Skip the preprocessor step
     -notemplatereduce - Disable reduction of the typedefs in templates
     -O              - Enable the optimization options:
                        -fastdispatch -fvirtual
     -o <outfile>    - Set name of C/C++ output file to <outfile>
     -oh <headfile>  - Set name of C++ output header file for directors to <headfile>
     -outcurrentdir  - Set default output dir to current dir instead of input file's path
     -outdir <dir>   - Set language specific files output directory to <dir>
     -pcreversion    - Display PCRE2 version information
     -small          - Compile in virtual elimination and compact mode
     -std=<standard> - Set the C or C++ language <standard> for inputs
     -swiglib        - Report location of SWIG library and exit
     -templatereduce - Reduce all the typedefs in templates
     -U<symbol>      - Undefine symbol <symbol>
     -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: 309,403,405,512,321,322
     -w<list>        - Suppress/add warning messages, eg -w401,+321 - see Warnings.html
     -xmlout <file>  - Write XML version of the parse tree to <file> after normal processing

Arguments may also be passed in a command-line options file (also known as a response file) which is useful if they exceed the system command line length limit. To do this, put the arguments in a file, then provide the file name prefixed with @ like so:

swig @file

The options read from the file are inserted in place of the file option. If the file does not exist, or cannot be read, then the option will be treated literally and not removed.

Options in the file are separated by whitespace. A whitespace character may be included in an option by surrounding the entire option in either single or double quotes. Any character (including a backslash) may be included by prefixing the character to be included with a backslash. The file may itself contain additional @file options; any such options will be processed recursively.

5.1.1 Input format

As input, SWIG expects a file containing ISO C/C++ declarations and special SWIG directives. More often than not, this is a special SWIG interface file which is usually denoted with a special .i or .swg suffix. In certain cases, SWIG can be used directly on raw header files or source files. However, this is not the most typical case and there are several reasons why you might not want to do this (described later).

The most common format of a SWIG interface is as follows:

%module mymodule 
%{
#include "myheader.h"
%}
// Now list ISO C/C++ declarations
int foo;
int bar(int x);
...

The module name is supplied using the special %module directive. Modules are described further in the Modules Introduction section.

Everything in the %{ ... %} block is simply copied verbatim to the resulting wrapper file created by SWIG. This section is almost always used to include header files and other declarations that are required to make the generated wrapper code compile. It is important to emphasize that just because you include a declaration in a SWIG input file, that declaration does not automatically appear in the generated wrapper code---therefore you need to make sure you include the proper header files in the %{ ... %} section. It should be noted that the text enclosed in %{ ... %} is not parsed or interpreted by SWIG. The %{...%} syntax and semantics in SWIG is analogous to that of the declarations section used in input files to parser generation tools such as yacc or bison.

5.1.2 SWIG Output

The output of SWIG is a C/C++ file that contains all of the wrapper code needed to build an extension module. SWIG may generate some additional files depending on the target language. By default, an input file with the name file.i is transformed into a file file_wrap.c or file_wrap.cxx (depending on whether or not the -c++ option has been used). The name of the output C/C++ file can be changed using the -o option. In certain cases, file suffixes are used by the compiler to determine the source language (C, C++, etc.). Therefore, you have to use the -o option to change the suffix of the SWIG-generated wrapper file if you want something different than the default. For example:

$ swig -c++ -python -o example_wrap.cpp example.i

The C/C++ output file created by SWIG often contains everything that is needed to construct an extension module for the target scripting language. SWIG is not a stub compiler nor is it usually necessary to edit the output file (and if you look at the output, you probably won't want to). To build the final extension module, the SWIG output file is compiled and linked with the rest of your C/C++ program to create a shared library.

For many target languages SWIG will also generate proxy class files in the target language. The default output directory for these language specific files is the same directory as the generated C/C++ file. This can be modified using the -outdir option. For example:

$ swig -c++ -python -outdir pyfiles -o cppfiles/example_wrap.cpp example.i

If the directories cppfiles and pyfiles exist, the following will be generated:

cppfiles/example_wrap.cpp
pyfiles/example.py

If the -outcurrentdir option is used (without -o) then SWIG behaves like a typical C/C++ compiler and the default output directory is then the current directory. Without this option the default output directory is the path to the input file. If -o and -outcurrentdir are used together, -outcurrentdir is effectively ignored as the output directory for the language files is the same directory as the generated C/C++ file if not overridden with -outdir.

5.1.3 Comments

C and C++ style comments may appear anywhere in interface files. In previous versions of SWIG, comments were used to generate documentation files. However, this feature is currently under repair and will reappear in a later SWIG release.

5.1.4 C Preprocessor

Like C, SWIG preprocesses all input files through an enhanced version of the C preprocessor. All standard preprocessor features are supported including file inclusion, conditional compilation and macros. However, #include statements are ignored unless the -includeall command line option has been supplied. The reason for disabling includes is that SWIG is sometimes used to process raw C header files. In this case, you usually only want the extension module to include functions in the supplied header file rather than everything that might be included by that header file (i.e., system headers, C library functions, etc.).

It should also be noted that the SWIG preprocessor skips all text enclosed inside a %{...%} block. In addition, the preprocessor includes a number of macro handling enhancements that make it more powerful than the normal C preprocessor. These extensions are described in the "Preprocessor" chapter.

5.1.5 SWIG Directives

Most of SWIG's operation is controlled by special directives that are always preceded by a "%" to distinguish them from normal C declarations. These directives are used to give SWIG hints or to alter SWIG's parsing behavior in some manner.

Since SWIG directives are not legal C syntax, it is generally not possible to include them in header files. However, SWIG directives can be included in C header files using conditional compilation like this:

/* header.h  --- Some header file */

/* SWIG directives -- only seen if SWIG is running */ 
#ifdef SWIG
%module foo
#endif

SWIG is a special preprocessing symbol defined by SWIG when it is parsing an input file.

5.1.6 Parser Limitations

Although SWIG can parse most C/C++ declarations, it does not provide a complete C/C++ parser implementation. Most of these limitations pertain to very complicated type declarations and certain advanced C++ features. Specifically, the following features are not currently supported:

• Non-conventional type declarations. For example, SWIG does not support declarations such as the following (even though this is legal C):

  /* Non-conventional placement of storage specifier (extern) */
  const int extern Number;
  
  /* Extra declarator grouping */
  Matrix (foo);    // A global variable
  
  /* Extra declarator grouping in parameters */
  void bar(Spam (Grok)(Doh));
  
  

  In practice, few (if any) C programmers actually write code like this since this style is never featured in programming books. However, if you're feeling particularly obfuscated, you can certainly break SWIG (although why would you want to?).

• Running SWIG on C++ source files (the code in a .C, .cpp or .cxx file) is not recommended. The usual approach is to feed SWIG header files for parsing C++ definitions and declarations. The main reason is if SWIG parses a scoped definition or declaration (as is normal for C++ source files), it is ignored, unless a declaration for the symbol was parsed earlier. For example

  /* bar not wrapped unless foo has been defined and 
     the declaration of bar within foo has already been parsed */
  int foo::bar(int) {
    ... whatever ...
  }
  

• Certain advanced features of C++ such as nested classes are not yet fully supported. Please see the C++ Nested classes section for more information.

In the event of a parsing error, conditional compilation can be used to skip offending code. For example:

#ifndef SWIG
... some bad declarations ...
#endif

Alternatively, you can just delete the offending code from the interface file.

One of the reasons why SWIG does not provide a full C++ parser implementation is that it has been designed to work with incomplete specifications and to be very permissive in its handling of C/C++ datatypes (e.g., SWIG can generate interfaces even when there are missing class declarations or opaque datatypes). Unfortunately, this approach makes it extremely difficult to implement certain parts of a C/C++ parser as most compilers use type information to assist in the parsing of more complex declarations (for the truly curious, the primary complication in the implementation is that the SWIG parser does not utilize a separate typedef-name terminal symbol as described on p. 234 of K&R).

5.2 Wrapping Simple C Declarations

SWIG wraps simple C declarations by creating an interface that closely matches the way in which the declarations would be used in a C program. For example, consider the following interface file:

%module example

%inline %{
extern double sin(double x);
extern int strcmp(const char *, const char *);
extern int Foo;
%}
#define STATUS 50
#define VERSION "1.1"

In this file, there are two functions sin() and strcmp(), a global variable Foo, and two constants STATUS and VERSION. When SWIG creates an extension module, these declarations are accessible as scripting language functions, variables, and constants respectively. For example, in Tcl:

% sin 3
5.2335956
% strcmp Dave Mike
-1
% puts $Foo
42
% puts $STATUS
50
% puts $VERSION
1.1

Or in Python:

>>> example.sin(3)
5.2335956
>>> example.strcmp('Dave', 'Mike')
-1
>>> print example.cvar.Foo
42
>>> print example.STATUS
50
>>> print example.VERSION
1.1

Whenever possible, SWIG creates an interface that closely matches the underlying C/C++ code. However, due to subtle differences between languages, run-time environments, and semantics, it is not always possible to do so. The next few sections describe various aspects of this mapping.

5.2.1 Basic Type Handling

In order to build an interface, SWIG has to convert C/C++ datatypes to equivalent types in the target language. Generally, scripting languages provide a more limited set of primitive types than C. Therefore, this conversion process involves a certain amount of type coercion.

Most scripting languages provide a single integer type that is implemented using the int or long datatype in C. The following list shows all of the C datatypes that SWIG will convert to and from integers in the target language:

int
short
long
unsigned
signed
unsigned short
unsigned long
unsigned char
signed char
bool

When an integral value is converted from C, a cast is used to convert it to the representation in the target language. Thus, a 16 bit short in C may be promoted to a 32 bit integer. When integers are converted in the other direction, the value is cast back into the original C type. If the value is too large to fit, it is silently truncated.

unsigned char and signed char are special cases that are handled as small 8-bit integers. Normally, the char datatype is mapped as a one-character ASCII string.

The bool datatype is cast to and from an integer value of 0 and 1 unless the target language provides a special boolean type.

Some care is required when working with large integer values. Most scripting languages use 32-bit integers so mapping a 64-bit long integer may lead to truncation errors. Similar problems may arise with 32 bit unsigned integers (which may appear as large negative numbers). As a rule of thumb, the int datatype and all variations of char and short datatypes are safe to use. For unsigned int and long datatypes, you will need to carefully check the correct operation of your program after it has been wrapped with SWIG.

Although the SWIG parser supports the long long datatype, not all language modules support it. This is because long long usually exceeds the integer precision available in the target language. In certain modules such as Tcl and Perl5, long long integers are encoded as strings. This allows the full range of these numbers to be represented. However, it does not allow long long values to be used in arithmetic expressions. It should also be noted that although long long is part of the ISO C99 standard, it is not universally supported by all C compilers. Make sure you are using a compiler that supports long long before trying to use this type with SWIG.

SWIG recognizes the following floating point types :

float
double

Floating point numbers are mapped to and from the natural representation of floats in the target language. This is almost always a C double. The rarely used datatype of long double is not supported by SWIG.

The char datatype is mapped into a NULL terminated ASCII string with a single character. When used in a scripting language it shows up as a tiny string containing the character value. When converting the value back into C, SWIG takes a character string from the scripting language and strips off the first character as the char value. Thus if the value "foo" is assigned to a char datatype, it gets the value `f'.

The char * datatype is handled as a NULL-terminated ASCII string. SWIG maps this into a 8-bit character string in the target scripting language. SWIG converts character strings in the target language to NULL terminated strings before passing them into C/C++. The default handling of these strings does not allow them to have embedded NULL bytes. Therefore, the char * datatype is not generally suitable for passing binary data. However, it is possible to change this behavior by defining a SWIG typemap. See the chapter on Typemaps for details about this.

At this time, SWIG provides limited support for Unicode and wide-character strings (the C wchar_t type). Some languages provide typemaps for wchar_t, but bear in mind these might not be portable across different operating systems. This is a delicate topic that is poorly understood by many programmers and not implemented in a consistent manner across languages. For those scripting languages that provide Unicode support, Unicode strings are often available in an 8-bit representation such as UTF-8 that can be mapped to the char * type (in which case the SWIG interface will probably work). If the program you are wrapping uses Unicode, there is no guarantee that Unicode characters in the target language will use the same internal representation (e.g., UCS-2 vs. UCS-4). You may need to write some special conversion functions.

5.2.2 Global Variables

Whenever possible, SWIG maps C/C++ global variables into scripting language variables. For example,

%module example
double foo;

results in a scripting language variable like this:

# Tcl
set foo [3.5]                   ;# Set foo to 3.5
puts $foo                       ;# Print the value of foo

# Python
cvar.foo = 3.5                  # Set foo to 3.5
print cvar.foo                  # Print value of foo

# Perl
$foo = 3.5;                     # Set foo to 3.5
print $foo, "\n";               # Print value of foo

# Ruby
Module.foo = 3.5               # Set foo to 3.5
print Module.foo, "\n"         # Print value of foo

Whenever the scripting language variable is used, the underlying C global variable is accessed. Although SWIG makes every attempt to make global variables work like scripting language variables, it is not always possible to do so. For instance, in Python, all global variables must be accessed through a special variable object known as cvar (shown above). In Ruby, variables are accessed as attributes of the module. Other languages may convert variables to a pair of accessor functions. For example, the Java module generates a pair of functions double get_foo() and set_foo(double val) that are used to manipulate the value.

Finally, if a global variable has been declared as const, it only supports read-only access. Note: this behavior is new to SWIG-1.3. Earlier versions of SWIG incorrectly handled const and created constants instead.

5.2.3 Constants

Constants can be created using #define, enumerations, or a special %constant directive. The following interface file shows a few valid constant declarations :

#define I_CONST       5               // An integer constant
#define PI            3.14159         // A Floating point constant
#define S_CONST       "hello world"   // A string constant
#define NEWLINE       '\n'            // Character constant

enum boolean {NO=0, YES=1};
enum months {JAN, FEB, MAR, APR, MAY, JUN, JUL, AUG,
             SEP, OCT, NOV, DEC};
%constant double BLAH = 42.37;
#define PI_4 PI/4
#define FLAGS 0x04 | 0x08 | 0x40

In #define declarations, the type of a constant is inferred by syntax. For example, a number with a decimal point is assumed to be floating point. In addition, SWIG must be able to fully resolve all of the symbols used in a #define in order for a constant to actually be created. This restriction is necessary because #define is also used to define preprocessor macros that are definitely not meant to be part of the scripting language interface. For example:

#define EXTERN extern

EXTERN void foo();

In this case, you probably don't want to create a constant called EXTERN (what would the value be?). In general, SWIG will not create constants for macros unless the value can be completely determined by the preprocessor. For instance, in the above example, the declaration

#define PI_4  PI/4

defines a constant because PI was already defined as a constant and the value is known. However, for the same conservative reasons even a constant with a simple cast will be ignored, such as

#define F_CONST (double) 5            // A floating point constant with cast

This logic can lead to false attempts at converting #define into %constant though. For example the following case does not have any undefined symbols within the macro:

// For indicating pure virtual functions such as: virtual void f() PURE;
#define PURE = 0

A warning is issued:

pure.h:1: Warning 305: Bad constant value (ignored).

In such cases simply ignore the warning or suppress it using the normal warning suppression techniques.

The use of constant expressions is allowed, but SWIG does not evaluate them. Rather, it passes them through to the output file and lets the C compiler perform the final evaluation (SWIG does perform a limited form of type-checking however).

For enumerations, it is critical that the original enum definition be included somewhere in the interface file (either in a header file or in the %{ %} block). SWIG only translates the enumeration into code needed to add the constants to a scripting language. It needs the original enumeration declaration in order to get the correct enum values as assigned by the C compiler.

The %constant directive is used to more precisely create constants corresponding to different C datatypes. Although it is not usually needed for simple values, it is more useful when working with pointers and other more complex datatypes. Typically, %constant is only used when you want to add constants to the scripting language interface that are not defined in the original header file.

5.2.4 A brief word about const

A common confusion with C programming is the semantic meaning of the const qualifier in declarations--especially when it is mixed with pointers and other type modifiers. In fact, previous versions of SWIG handled const incorrectly--a situation that SWIG-1.3.7 and newer releases have fixed.

Starting with SWIG-1.3, all variable declarations, regardless of any use of const, are wrapped as global variables. If a declaration happens to be declared as const, it is wrapped as a read-only variable. To tell if a variable is const or not, you need to look at the right-most occurrence of the const qualifier (that appears before the variable name). If the right-most const occurs after all other type modifiers (such as pointers), then the variable is const. Otherwise, it is not.

Here are some examples of const declarations.

const char a;           // A constant character
char const b;           // A constant character (the same)
char *const c;          // A constant pointer to a character
const char *const d;    // A constant pointer to a constant character

Here is an example of a declaration that is not const:

const char *e;          // A pointer to a constant character.  The pointer
                        // may be modified.

In this case, the pointer e can change---it's only the value being pointed to that is read-only.

Please note that for const parameters or return types used in a function, SWIG pretty much ignores the fact that these are const, see the section on const-correctness for more information.

Compatibility Note: One reason for changing SWIG to handle const declarations as read-only variables is that there are many situations where the value of a const variable might change. For example, a library might export a symbol as const in its public API to discourage modification, but still allow the value to change through some other kind of internal mechanism. Furthermore, programmers often overlook the fact that with a constant declaration like char *const, the underlying data being pointed to can be modified--it's only the pointer itself that is constant. In an embedded system, a const declaration might refer to a read-only memory address such as the location of a memory-mapped I/O device port (where the value changes, but writing to the port is not supported by the hardware). Rather than trying to build a bunch of special cases into the const qualifier, the new interpretation of const as "read-only" is simple and exactly matches the actual semantics of const in C/C++. If you really want to create a constant as in older versions of SWIG, use the %constant directive instead. For example:

%constant double PI = 3.14159;

or

#ifdef SWIG
#define const %constant
#endif
const double foo = 3.4;
const double bar = 23.4;
const int    spam = 42;
#ifdef SWIG
#undef const
#endif
...

5.2.5 A cautionary tale of char *

Before going any further, there is one bit of caution involving char * that must now be mentioned. When strings are passed from a scripting language to a C char *, the pointer usually points to string data stored inside the interpreter. It is almost always a really bad idea to modify this data. Furthermore, some languages may explicitly disallow it. For instance, in Python, strings are supposed to be immutable. If you violate this, you will probably receive a vast amount of wrath when you unleash your module on the world.

The primary source of problems are functions that might modify string data in place. A classic example would be a function like this:

char *strcat(char *s, const char *t)

Although SWIG will certainly generate a wrapper for this, its behavior will be undefined. In fact, it will probably cause your application to crash with a segmentation fault or other memory related problem. This is because s refers to some internal data in the target language---data that you shouldn't be touching.

The bottom line: don't rely on char * for anything other than read-only input values. However, it must be noted that you could change the behavior of SWIG using typemaps.

5.3 Pointers and complex objects

Most C programs manipulate arrays, structures, and other types of objects. This section discusses the handling of these datatypes.

5.3.1 Simple pointers

Pointers to primitive C datatypes such as

int *
double ***
char **

are fully supported by SWIG. Rather than trying to convert the data being pointed to into a scripting representation, SWIG simply encodes the pointer itself into a representation that contains the actual value of the pointer and a type-tag. Thus, the SWIG representation of the above pointers (in Tcl), might look like this:

_10081012_p_int
_1008e124_ppp_double
_f8ac_pp_char

A NULL pointer is represented by the string "NULL" or the value 0 encoded with type information.

All pointers are treated as opaque objects by SWIG. Thus, a pointer may be returned by a function and passed around to other C functions as needed. For all practical purposes, the scripting language interface works in exactly the same way as you would use the pointer in a C program. The only difference is that there is no mechanism for dereferencing the pointer since this would require the target language to understand the memory layout of the underlying object.

The scripting language representation of a pointer value should never be manipulated directly. Even though the values shown look like hexadecimal addresses, the numbers used may differ from the actual machine address (e.g., on little-endian machines, the digits may appear in reverse order). Furthermore, SWIG does not normally map pointers into high-level objects such as associative arrays or lists (for example, converting an int * into an list of integers). There are several reasons why SWIG does not do this:

• There is not enough information in a C declaration to properly map pointers into higher level constructs. For example, an int * may indeed be an array of integers, but if it contains ten million elements, converting it into a list object is probably a bad idea.
• The underlying semantics associated with a pointer is not known by SWIG. For instance, an int * might not be an array at all--perhaps it is an output value!
• By handling all pointers in a consistent manner, the implementation of SWIG is greatly simplified and less prone to error.

5.3.2 Run time pointer type checking

By allowing pointers to be manipulated from a scripting language, extension modules effectively bypass compile-time type checking in the C/C++ compiler. To prevent errors, a type signature is encoded into all pointer values and is used to perform run-time type checking. This type-checking process is an integral part of SWIG and can not be disabled or modified without using typemaps (described in later chapters).

Like C, void * matches any kind of pointer. Furthermore, NULL pointers can be passed to any function that expects to receive a pointer. Although this has the potential to cause a crash, NULL pointers are also sometimes used as sentinel values or to denote a missing/empty value. Therefore, SWIG leaves NULL pointer checking up to the application.

5.3.3 Derived types, structs, and classes

For everything else (structs, classes, arrays, etc...) SWIG applies a very simple rule :

In other words, SWIG manipulates everything else by reference. This model makes sense because most C/C++ programs make heavy use of pointers and SWIG can use the type-checked pointer mechanism already present for handling pointers to basic datatypes.

Although this probably sounds complicated, it's really quite simple. Suppose you have an interface file like this :

%module fileio
FILE *fopen(char *, char *);
int fclose(FILE *);
unsigned fread(void *ptr, unsigned size, unsigned nobj, FILE *);
unsigned fwrite(void *ptr, unsigned size, unsigned nobj, FILE *);
void *malloc(int nbytes);
void free(void *);

In this file, SWIG doesn't know what a FILE is, but since it's used as a pointer, so it doesn't really matter what it is. If you wrapped this module into Python, you can use the functions just like you expect :

# Copy a file 
def filecopy(source, target):
    f1 = fopen(source, "r")
    f2 = fopen(target, "w")
    buffer = malloc(8192)
    nbytes = fread(buffer, 8192, 1, f1)
    while (nbytes > 0):
        fwrite(buffer, 8192, 1, f2)
            nbytes = fread(buffer, 8192, 1, f1)
    free(buffer)

In this case f1, f2, and buffer are all opaque objects containing C pointers. It doesn't matter what value they contain--our program works just fine without this knowledge.

5.3.4 Undefined datatypes

When SWIG encounters an undeclared datatype, it automatically assumes that it is a structure or class. For example, suppose the following function appeared in a SWIG input file:

void matrix_multiply(Matrix *a, Matrix *b, Matrix *c);

SWIG has no idea what a "Matrix" is. However, it is obviously a pointer to something so SWIG generates a wrapper using its generic pointer handling code.

Unlike C or C++, SWIG does not actually care whether Matrix has been previously defined in the interface file or not. This allows SWIG to generate interfaces from only partial or limited information. In some cases, you may not care what a Matrix really is as long as you can pass an opaque reference to one around in the scripting language interface.

An important detail to mention is that SWIG will gladly generate wrappers for an interface when there are unspecified type names. However, all unspecified types are internally handled as pointers to structures or classes! For example, consider the following declaration:

void foo(size_t num);

If size_t is undeclared, SWIG generates wrappers that expect to receive a type of size_t * (this mapping is described shortly). As a result, the scripting interface might behave strangely. For example:

foo(40);
TypeError: expected a _p_size_t.

The only way to fix this problem is to make sure you properly declare type names using typedef.

5.3.5 Typedef

Like C, typedef can be used to define new type names in SWIG. For example:

typedef unsigned int size_t;

typedef definitions appearing in a SWIG interface are not propagated to the generated wrapper code. Therefore, they either need to be defined in an included header file or placed in the declarations section like this:

%{
/* Include in the generated wrapper file */
typedef unsigned int size_t;
%}
/* Tell SWIG about it */
typedef unsigned int size_t;

or

%inline %{
typedef unsigned int size_t;
%}

In certain cases, you might be able to include other header files to collect type information. For example:

%module example
%import "sys/types.h"

In this case, you might run SWIG as follows:

$ swig -I/usr/include -includeall example.i

It should be noted that your mileage will vary greatly here. System headers are notoriously complicated and may rely upon a variety of non-standard C coding extensions (e.g., such as special directives to GCC). Unless you exactly specify the right include directories and preprocessor symbols, this may not work correctly (you will have to experiment).

SWIG tracks typedef declarations and uses this information for run-time type checking. For instance, if you use the above typedef and had the following function declaration:

void foo(unsigned int *ptr);

The corresponding wrapper function will accept arguments of type unsigned int * or size_t *.

5.4 Other Practicalities

So far, this chapter has presented almost everything you need to know to use SWIG for simple interfaces. However, some C programs use idioms that are somewhat more difficult to map to a scripting language interface. This section describes some of these issues.

5.4.1 Passing structures by value

Sometimes a C function takes structure parameters that are passed by value. For example, consider the following function:

double dot_product(Vector a, Vector b);

To deal with this, SWIG transforms the function to use pointers by creating a wrapper equivalent to the following:

double wrap_dot_product(Vector *a, Vector *b) {
  Vector x = *a;
  Vector y = *b;
  return dot_product(x, y);
}

In the target language, the dot_product() function now accepts pointers to Vectors instead of Vectors. For the most part, this transformation is transparent so you might not notice.

5.4.2 Return by value

C functions that return structures or classes datatypes by value are more difficult to handle. Consider the following function:

Vector cross_product(Vector v1, Vector v2);

This function wants to return Vector, but SWIG only really supports pointers. As a result, SWIG creates a wrapper like this:

Vector *wrap_cross_product(Vector *v1, Vector *v2) {
  Vector x = *v1;
  Vector y = *v2;
  Vector *result;
  result = (Vector *) malloc(sizeof(Vector));
  *(result) = cross(x, y);
  return result;
}

or if SWIG was run with the -c++ option:

Vector *wrap_cross(Vector *v1, Vector *v2) {
  Vector x = *v1;
  Vector y = *v2;
  Vector *result = new Vector(cross(x, y)); // Uses default copy constructor
  return result;
}

In both cases, SWIG allocates a new object and returns a reference to it. It is up to the user to delete the returned object when it is no longer in use. Clearly, this will leak memory if you are unaware of the implicit memory allocation and don't take steps to free the result. That said, it should be noted that some language modules can now automatically track newly created objects and reclaim memory for you. Consult the documentation for each language module for more details.

It should also be noted that the handling of pass/return by value in C++ has some special cases. For example, the above code fragments don't work correctly if Vector doesn't define a default constructor. The section on SWIG and C++ has more information about this case.

5.4.3 Linking to structure variables

When global variables or class members involving structures are encountered, SWIG handles them as pointers. For example, a global variable like this

Vector unit_i;

gets mapped to an underlying pair of set/get functions like this :

Vector *unit_i_get() {
  return &unit_i;
}
void unit_i_set(Vector *value) {
  unit_i = *value;
}

Again some caution is in order. A global variable created in this manner will show up as a pointer in the target scripting language. It would be an extremely bad idea to free or destroy such a pointer. Also, C++ classes must supply a properly defined copy constructor in order for assignment to work correctly.

5.4.4 Linking to char *

When a global variable of type char * appears, SWIG uses malloc() or new to allocate memory for the new value. Specifically, if you have a variable like this

char *foo;

SWIG generates the following code:

/* C mode */
void foo_set(char *value) {
  free(foo);
  foo = (char *) malloc(strlen(value)+1);
  strcpy(foo, value);
}

/* C++ mode.  When -c++ option is used */
void foo_set(char *value) {
  delete [] foo;
  foo = new char[strlen(value)+1];
  strcpy(foo, value);
}

If this is not the behavior that you want, consider making the variable read-only using the %immutable directive. Alternatively, you might write a short assist-function to set the value exactly like you want. For example:

%inline %{
  void set_foo(char *value) {
    strncpy(foo, value, 50);
  }
%}

Note: If you write an assist function like this, you will have to call it as a function from the target scripting language (it does not work like a variable). For example, in Python you will have to write:

>>> set_foo("Hello World")

A common mistake with char * variables is to link to a variable declared like this:

char *VERSION = "1.0";

In this case, the variable will be readable, but any attempt to change the value results in a segmentation or general protection fault. This is due to the fact that SWIG is trying to release the old value using free or delete when the string literal value currently assigned to the variable wasn't allocated using malloc() or new. To fix this behavior, you can either mark the variable as read-only, write a typemap (as described in Chapter 6), or write a special set function as shown. Another alternative is to declare the variable as an array:

char VERSION[64] = "1.0";

When variables of type const char * are declared, SWIG still generates functions for setting and getting the value. However, the default behavior does not release the previous contents (resulting in a possible memory leak). In fact, you may get a warning message such as this when wrapping such a variable:

example.i:20. Typemap warning. Setting const char * variable may leak memory

The reason for this behavior is that const char * variables are often used to point to string literals. For example:

const char *foo = "Hello World\n";

Therefore, it's a really bad idea to call free() on such a pointer. On the other hand, it is legal to change the pointer to point to some other value. When setting a variable of this type, SWIG allocates a new string (using malloc or new) and changes the pointer to point to the new value. However, repeated modifications of the value will result in a memory leak since the old value is not released.

5.4.5 Arrays

Arrays are fully supported by SWIG, but they are always handled as pointers instead of mapping them to a special array object or list in the target language. Thus, the following declarations :

int foobar(int a[40]);
void grok(char *argv[]);
void transpose(double a[20][20]);

are processed as if they were really declared like this:

int foobar(int *a);
void grok(char **argv);
void transpose(double (*a)[20]);

Like C, SWIG does not perform array bounds checking. It is up to the user to make sure the pointer points to a suitably allocated region of memory.

Multi-dimensional arrays are transformed into a pointer to an array of one less dimension. For example:

int [10];         // Maps to int *
int [10][20];     // Maps to int (*)[20]
int [10][20][30]; // Maps to int (*)[20][30]

It is important to note that in the C type system, a multidimensional array a[][] is NOT equivalent to a single pointer *a or a double pointer such as **a. Instead, a pointer to an array is used (as shown above) where the actual value of the pointer is the starting memory location of the array. The reader is strongly advised to dust off their C book and re-read the section on arrays before using them with SWIG.

Array variables are supported, but are read-only by default. For example:

int   a[100][200];

In this case, reading the variable 'a' returns a pointer of type int (*)[200] that points to the first element of the array &a[0][0]. Trying to modify 'a' results in an error. This is because SWIG does not know how to copy data from the target language into the array. To work around this limitation, you may want to write a few simple assist functions like this:

%inline %{
void a_set(int i, int j, int val) {
  a[i][j] = val;
}
int a_get(int i, int j) {
  return a[i][j];
}
%}

To dynamically create arrays of various sizes and shapes, it may be useful to write some helper functions in your interface. For example:

// Some array helpers
%inline %{
  /* Create any sort of [size] array */
  int *int_array(int size) {
    return (int *) malloc(size*sizeof(int));
  }
  /* Create a two-dimension array [size][10] */
  int (*int_array_10(int size))[10] {
    return (int (*)[10]) malloc(size*10*sizeof(int));
  }
%}

Arrays of char are handled as a special case by SWIG. In this case, strings in the target language can be stored in the array. For example, if you have a declaration like this,

char pathname[256];

SWIG generates functions for both getting and setting the value that are equivalent to the following code:

char *pathname_get() {
  return pathname;
}
void pathname_set(char *value) {
  strncpy(pathname, value, 256);
}

In the target language, the value can be set like a normal variable.

5.4.6 Creating read-only variables

A read-only variable can be created by using the %immutable directive as shown :

// File : interface.i

int a;       // Can read/write
%immutable;
int b, c, d;   // Read only variables
%mutable;
double x, y;  // read/write

The %immutable directive enables read-only mode until it is explicitly disabled using the %mutable directive. As an alternative to turning read-only mode off and on like this, individual declarations can also be tagged as immutable. For example:

%immutable x;                   // Make x read-only
...
double x;                       // Read-only (from earlier %immutable directive)
double y;                       // Read-write
...

The %mutable and %immutable directives are actually %feature directives defined like this:

#define %immutable   %feature("immutable")
#define %mutable     %feature("immutable", "")

If you wanted to make all wrapped variables read-only, barring one or two, it might be easier to take this approach:

%immutable;                     // Make all variables read-only
%feature("immutable", "0") x;   // except, make x read/write
...
double x;
double y;
double z;
...

Read-only variables are also created when declarations are declared as const. For example:

const int foo;               /* Read only variable */
char * const version="1.0";  /* Read only variable */

5.4.7 Renaming and ignoring declarations

5.4.7.1 Simple renaming of specific identifiers

Normally, the name of a C declaration is used when that declaration is wrapped into the target language. However, this may generate a conflict with a keyword or already existing function in the scripting language. To resolve a name conflict, you can use the %rename directive as shown :

// interface.i

%rename(my_print) print;
extern void print(const char *);

%rename(foo) a_really_long_and_annoying_name;
extern int a_really_long_and_annoying_name;

SWIG still calls the correct C function, but in this case the function print() will really be called "my_print()" in the target language.

The placement of the %rename directive is arbitrary as long as it appears before the declarations to be renamed. A common technique is to write code for wrapping a header file like this:

// interface.i

%rename(my_print) print;
%rename(foo) a_really_long_and_annoying_name;

%include "header.h"

%rename applies a renaming operation to all future occurrences of a name. The renaming applies to functions, variables, class and structure names, member functions, and member data. For example, if you had two-dozen C++ classes, all with a member function named `print' (which is a keyword in Python), you could rename them all to `output' by specifying :

%rename(output) print; // Rename all `print' functions to `output'

A new %rename for the same name will replace the current %rename 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:

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

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 careful about namespaces and your use of modules, you can usually avoid these problems.

When wrapping C code, simple use of identifiers/symbols with %rename usually suffices. When wrapping C++ code, simple use of simple identifiers/symbols with %rename might be too limiting when using C++ features such as function overloading, default arguments, namespaces, template specialization etc. If you are using the %rename directive and C++, make sure you read the SWIG and C++ chapter and in particular the section on Renaming and ambiguity resolution for method overloading and default arguments.

5.4.7.2 Ignoring identifiers

Closely related to %rename is the %ignore directive. %ignore instructs SWIG to ignore declarations that match a given identifier. For example:

%ignore print;         // Ignore all declarations named print
%ignore MYMACRO;       // Ignore a macro
...
#define MYMACRO 123
void print(const char *);
...

Any function, variable etc which matches %ignore will not be wrapped and therefore will not be available from the target language. A common usage of %ignore is to selectively remove certain declarations from a header file without having to add conditional compilation to the header. However, it should be stressed that this only works for simple declarations. If you need to remove a whole section of problematic code, the SWIG preprocessor should be used instead.

5.4.7.3 Advanced renaming support

While writing %rename for specific declarations is simple enough, sometimes the same renaming rule needs to be applied to many, maybe all, identifiers in the SWIG input. For example, it may be necessary to apply some transformation to all the names in the target language to better follow its naming conventions, like adding a specific prefix to all wrapped functions. Doing it individually for each function is impractical so SWIG supports applying a renaming rule to all declarations if the name of the identifier to be renamed is not specified:

%rename("myprefix_%s") ""; // print -> myprefix_print

This also shows that the argument of %rename doesn't have to be a literal string but can be a printf()-like format string. In the simplest form, "%s" is replaced with the name of the original declaration, as shown above. However this is not always enough and SWIG provides extensions to the usual format string syntax to allow applying a (SWIG-defined) function to the argument. For example, to wrap all C functions do_something_long() as more Java-like doSomethingLong() you can use the "lowercamelcase" extended format specifier like this:

%rename("%(lowercamelcase)s") ""; // foo_bar -> fooBar; FooBar -> fooBar

Some functions can be parametrized, for example the "strip" one strips the provided prefix from its argument. The prefix is specified as part of the format string, following a colon after the function name:

%rename("%(strip:[wx])s") ""; // wxHello -> Hello; FooBar -> FooBar

Below is the table summarizing all currently defined functions with an example of applying each one. Note that some of them have two names, a shorter one and a more descriptive one, but the two functions are otherwise equivalent:

The most general function of all of the above ones is the regex one. Here are some more examples of its use:

// Strip the wx prefix from all identifiers except those starting with wxEVT
%rename("%(regex:/wx(?!EVT)(.*)/\\1/)s") ""; // wxSomeWidget -> SomeWidget
                                             // wxEVT_PAINT -> wxEVT_PAINT

// Apply a rule for renaming the enum elements to avoid the common prefixes
// which are redundant in C#/Java
%rename("%(regex:/^([A-Z][a-z]+)+_(.*)/\\2/)s", %$isenumitem) ""; // Colour_Red -> Red

// Remove all "Set/Get" prefixes.
%rename("%(regex:/^(Set|Get)(.*)/\\2/)s") ""; // SetValue -> Value
                                              // GetValue -> Value

As before, everything that was said above about %rename also applies to %ignore. In fact, the latter is just a special case of the former and ignoring an identifier is the same as renaming it to the special "$ignore" value. So the following snippets

%ignore print;

and

%rename("$ignore") print;

are exactly equivalent and %rename can be used to selectively ignore multiple declarations using the previously described matching possibilities.

5.4.7.4 Limiting global renaming rules

As explained in the previous sections, it is possible to either rename individual declarations or apply a rename rule to all of them at once. In practice, the latter is however rarely appropriate as there are always some exceptions to the general rules. To deal with them, the scope of an unnamed %rename can be limited using subsequent match parameters. They can be applied to any of the attributes associated by SWIG with the declarations appearing in its input. For example:

%rename("foo", match$name="bar") "";

can be used to achieve the same effect as the simpler

%rename("foo") bar;

and so is not very interesting on its own. However match can also be applied to the declaration type, for example match="class" restricts the match to class declarations only (in C++) and match="enumitem" restricts it to the enum elements. SWIG also provides convenience macros for such match expressions, for example

%rename("%(title)s", %$isenumitem) "";
// same as:
%rename("%(title)s", match="enumitem") "";

will capitalize the names of all the enum elements but not change the case of the other declarations. Similarly, %$isclass, %$isfunction, %$isconstructor, %$isunion, %$istemplate, and %$isvariable can be used. Many other checks are possible and this documentation is not exhaustive, see the "%rename predicates" section in swig.swg for the full list of supported match expressions.

A logical not is also possible by using notmatch. For example, notmatch="enumitem" will restrict the match to all items that are not enum elements. There is also a %$not macro which simply expands to "not". Be careful using this as some of the other macros in swig.swg are complex expressions and so it will only "notmatch" the first part of the expression.

%rename("%(title)s", %$not %$isenumitem) "";
// same as:
%rename("%(title)s", notmatch="enumitem") "";

For a comprehensive understanding of how the matching works, the internal parse tree needs to be examined using the command line option: -debug-module 1 -debug-quiet. A snippet of the resulting output might be:

            +++ destructor ----------------------------------------
            | access       - "public"
            | decl         - "f()."
            | ismember     - "1"
            | name         - "~Shape"
            | storage      - "virtual"
            | sym:name     - "~Shape"

Here the node type is a "destructor" and in order to match all destructor nodes, use match="destructor". To match one of the listed attributes in the node, such as when the storage is virtual, use match$storage="virtual". This will match all nodes that have a storage attribute set to "virtual". To match only virtual destructors, combine them and use match="destructor", match$storage="virtual" .

While the vast majority of these internal parse tree nodes are unlikely to change from one version of SWIG to the next, use these matching rules at your own risk as there are no guarantees that they will not change.

In addition to literally matching some string with match you can also use regexmatch or notregexmatch to match a string against a regular expression. For example, to ignore all functions having "Old" as a suffix you could use

%rename("$ignore", regexmatch$name="Old$") "";

For simple cases like this, specifying the regular expression for the declaration name directly can be preferable and can also be done using regextarget:

%rename("$ignore", regextarget=1) "Old$";

Notice that the check is done only against the name of the declaration itself, if you need to match the full name of a C++ declaration you must use fullname attribute:

%rename("$ignore", regextarget=1, fullname=1) "NameSpace::ClassName::.*Old$";

As for notregexmatch, it restricts the match only to the strings not matching the specified regular expression. So to rename all declarations to lower case except those consisting of capital letters only:

%rename("$(lower)s", notregexmatch$name="^[A-Z]+$") "";

Finally, variants of %rename and %ignore directives can be used to help wrap C++ overloaded functions and methods or C++ methods which use default arguments. This is described in the Renaming and ambiguity resolution section in the C++ chapter.

5.4.7.5 Ignoring everything then wrapping a few selected symbols

Using the techniques described above it is possible to ignore everything in a header and then selectively wrap a few chosen methods or classes. For example, consider a header, myheader.h which has many classes in it and just the one class called Star is wanted within this header, the following approach could be taken:

%ignore ""; // Ignore everything

// Unignore chosen class 'Star'
%rename("%s") Star;

// As the ignore everything will include the constructor, destructor, methods etc
// in the class, these have to be explicitly unignored too:
%rename("%s") Star::Star;
%rename("%s") Star::~Star;
%rename("%s") Star::shine; // named method

%include "myheader.h"

%rename("%s") ""; // Undo the %ignore

If Star was in the Galaxy namespace, you would need to unignore the namespace, too, and add the namespace to all the renames:

%rename("%s") Galaxy;
%rename("%s") Galaxy::Star;
%rename("%s") Galaxy::Star::Star;
...

Another approach which might be more suitable as it does not require naming all the methods in the chosen class is to begin by ignoring just the classes. This does not add an explicit ignore to any members of the class, so when the chosen class is unignored, all of its methods will be wrapped.

%rename($ignore, %$isclass) ""; // Only ignore all classes
%rename("%s") Star; // Unignore 'Star'
%include "myheader.h"
%rename("%s", %$isclass) ""; // Stop ignoring all classes

5.4.8 Default/optional arguments

SWIG supports default arguments in both C and C++ code. For example:

int plot(double x, double y, int color=WHITE);

In this case, SWIG generates wrapper code where the default arguments are optional in the target language. For example, this function could be used in Tcl as follows :

% plot -3.4 7.5    # Use default value
% plot -3.4 7.5 10 # set color to 10 instead

Although the ISO C standard does not allow default arguments, default arguments specified in a SWIG interface work with both C and C++.

Note: There is a subtle semantic issue concerning the use of default arguments and the SWIG generated wrapper code. When default arguments are used in C code, the default values are emitted into the wrappers and the function is invoked with a full set of arguments. This is different to when wrapping C++ where an overloaded wrapper method is generated for each defaulted argument. Please refer to the section on default arguments in the C++ chapter for further details.

5.4.9 Pointers to functions and callbacks

Occasionally, a C library may include functions that expect to receive pointers to functions--possibly to serve as callbacks. SWIG provides full support for function pointers when the callback functions are defined in C and not in the target language. For example, consider a function like this:

int binary_op(int a, int b, int (*op)(int, int));

When you first wrap something like this into an extension module, you may find the function to be impossible to use. For instance, in Python:

>>> def add(x, y):
...     return x+y
...
>>> binary_op(3, 4, add)
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
TypeError: Type error. Expected _p_f_int_int__int
>>>

The reason for this error is that SWIG doesn't know how to map a scripting language function into a C callback. However, existing C functions can be used as arguments provided you install them as constants. One way to do this is to use the %constant directive like this:

/* Function with a callback */
int binary_op(int a, int b, int (*op)(int, int));

/* Some callback functions */
%constant int add(int, int);
%constant int sub(int, int);
%constant int mul(int, int);

In this case, add, sub, and mul become function pointer constants in the target scripting language. This allows you to use them as follows:

>>> binary_op(3, 4, add)
7
>>> binary_op(3, 4, mul)
12
>>>

Unfortunately, by declaring the callback functions as constants, they are no longer accessible as functions. For example:

>>> add(3, 4)
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
TypeError: object is not callable: '_ff020efc_p_f_int_int__int'
>>>

If you want to make a function available as both a callback function and a function, you can use the %callback and %nocallback directives like this:

/* Function with a callback */
int binary_op(int a, int b, int (*op)(int, int));

/* Some callback functions */
%callback("%s_cb");
int add(int, int);
int sub(int, int);
int mul(int, int);
%nocallback;

The argument to %callback is a printf-style format string that specifies the naming convention for the callback constants (%s gets replaced by the function name). The callback mode remains in effect until it is explicitly disabled using %nocallback. When you do this, the interface now works as follows:

>>> binary_op(3, 4, add_cb)
7
>>> binary_op(3, 4, mul_cb)
12
>>> add(3, 4)
7
>>> mul(3, 4)
12

Notice that when the function is used as a callback, special names such as add_cb are used instead. To call the function normally, just use the original function name such as add().

SWIG provides a number of extensions to standard C printf formatting that may be useful in this context. For instance, the following variation installs the callbacks as all upper case constants such as ADD, SUB, and MUL:

/* Some callback functions */
%callback("%(uppercase)s");
int add(int, int);
int sub(int, int);
int mul(int, int);
%nocallback;

A format string of "%(lowercase)s" converts all characters to lower case. A string of "%(title)s" capitalizes the first character and converts the rest to lower case.

And now, a final note about function pointer support. Although SWIG does not normally allow callback functions to be written in the target language, this can be accomplished with the use of typemaps and other advanced SWIG features. See the Typemaps chapter for more about typemaps and individual target language chapters for more on callbacks. The 'director' feature can be used to make callbacks from C/C++ into the target language, see Callbacks to the target language.

5.5 Structures and unions

This section describes the behavior of SWIG when processing ISO C structures and union declarations. Extensions to handle C++ are described in the next section.

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 Foo the struct tag and Foo the function name are in different name spaces:

struct Foo {
  int bar;
};

int Foo(void) { return 42; }

SWIG doesn't currently implement this separate tag name space and for the above example you'll get:

foo.i:5: Warning 302: Redefinition of identifier 'Foo' as Foo(void) ignored,
foo.i:1: Warning 302: previous definition of 'Foo'.

In practice this rarely actually causes problems, particular because SWIG has special handling for typedef so cases such as this work:

typedef struct Foo {
  int bar;
} Foo;

If SWIG encounters the definition of a structure or union, it creates a set of accessor functions. Although SWIG does not need structure definitions to build an interface, providing definitions makes it possible to access structure members. The accessor functions generated by SWIG simply take a pointer to an object and allow access to an individual member. For example, the declaration :

struct Vector {
  double x, y, z;
};

gets transformed into the following set of accessor functions :

double Vector_x_get(struct Vector *obj) {
  return obj->x;
}
double Vector_y_get(struct Vector *obj) { 
  return obj->y;
}
double Vector_z_get(struct Vector *obj) { 
  return obj->z;
}
void Vector_x_set(struct Vector *obj, double value) {
  obj->x = value;
}
void Vector_y_set(struct Vector *obj, double value) {
  obj->y = value;
}
void Vector_z_set(struct Vector *obj, double value) {
  obj->z = value;
}

In addition, SWIG creates default constructor and destructor functions if none are defined in the interface. For example:

struct Vector *new_Vector() {
  return (Vector *) calloc(1, sizeof(struct Vector));
}
void delete_Vector(struct Vector *obj) {
  free(obj);
}

Using these low-level accessor functions, an object can be minimally manipulated from the target language using code like this:

v = new_Vector()
Vector_x_set(v, 2)
Vector_y_set(v, 10)
Vector_z_set(v, -5)
...
delete_Vector(v)

However, most of SWIG's language modules also provide a high-level interface that is more convenient. Keep reading.

5.5.1 Typedef and structures

SWIG supports the following construct which is quite common in C programs :

typedef struct {
  double x, y, z;
} Vector;

When encountered, SWIG assumes that the name of the object is `Vector' and creates accessor functions like before. The only difference is that the use of typedef allows SWIG to drop the struct keyword on its generated code. For example:

double Vector_x_get(Vector *obj) {
  return obj->x;
}

If two different names are used like this :

typedef struct vector_struct {
  double x, y, z;
} Vector;

the name Vector is used instead of vector_struct since this is more typical C programming style. If declarations defined later in the interface use the type struct vector_struct, SWIG knows that this is the same as Vector and it generates the appropriate type-checking code.

5.5.2 Character strings and structures

Structures involving character strings require some care. SWIG assumes that all members of type char * have been dynamically allocated using malloc() and that they are NULL-terminated ASCII strings. When such a member is modified, the previous contents will be released, and the new contents allocated. For example :

%module mymodule
...
struct Foo {
  char *name;
  ...
}

This results in the following accessor functions :

char *Foo_name_get(Foo *obj) {
  return Foo->name;
}

char *Foo_name_set(Foo *obj, char *c) {
  free(obj->name);
  obj->name = (char *) malloc(strlen(c)+1);
  strcpy(obj->name, c);
  return obj->name;
}

If this behavior differs from what you need in your applications, the SWIG "memberin" typemap can be used to change it. See the typemaps chapter for further details.

Note: If the -c++ option is used, new and delete are used to perform memory allocation.

5.5.3 Array members

Arrays may appear as the members of structures, but they will be read-only. SWIG will write an accessor function that returns the pointer to the first element of the array, but will not write a function to change the contents of the array itself. When this situation is detected, SWIG may generate a warning message such as the following :

interface.i:116. Warning. Array member will be read-only

To eliminate the warning message, typemaps can be used, but this is discussed in a later chapter. In many cases, the warning message is harmless.

5.5.4 Structure data members

Occasionally, a structure will contain data members that are themselves structures. For example:

typedef struct Foo {
  int x;
} Foo;

typedef struct Bar {
  int y;
  Foo f;           /* struct member */
} Bar;

When a structure member is wrapped, it is handled as a pointer, unless the %naturalvar directive is used where it is handled more like a C++ reference (see C++ Member data). The accessors to the member variable as a pointer are effectively wrapped as follows:

Foo *Bar_f_get(Bar *b) {
  return &b->f;
}
void Bar_f_set(Bar *b, Foo *value) {
  b->f = *value;
}

The reasons for this are somewhat subtle but have to do with the problem of modifying and accessing data inside the data member. For example, suppose you wanted to modify the value of f.x of a Bar object like this:

Bar *b;
b->f.x = 37;

Translating this assignment to function calls (as would be used inside the scripting language interface) results in the following code:

Bar *b;
Foo_x_set(Bar_f_get(b), 37);

In this code, if the Bar_f_get() function were to return a Foo instead of a Foo *, then the resulting modification would be applied to a copy of f and not the data member f itself. Clearly that's not what you want!

It should be noted that this transformation to pointers only occurs if SWIG knows that a data member is a structure or class. For instance, if you had a structure like this,

struct Foo {
  WORD   w;
};

and nothing was known about WORD, then SWIG will generate more normal accessor functions like this:

WORD Foo_w_get(Foo *f) {
  return f->w;
}
void Foo_w_set(FOO *f, WORD value) {
  f->w = value;
}

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

Compatibility Note: SWIG-1.3.11 and earlier releases transformed all non-primitive member datatypes to pointers. Starting in SWIG-1.3.12, this transformation only occurs if a datatype is known to be a structure, class, or union. This is unlikely to break existing code. However, if you need to tell SWIG that an undeclared datatype is really a struct, simply use a forward struct declaration such as "struct Foo;".

5.5.5 C constructors and destructors

When wrapping structures, it is generally useful to have a mechanism for creating and destroying objects. If you don't do anything, SWIG will automatically generate functions for creating and destroying objects using malloc() and free(). Note: the use of malloc() only applies when SWIG is used on C code (i.e., when the -c++ option is not supplied on the command line). C++ is handled differently.

If you don't want SWIG to generate default constructors for your interfaces, you can use the %nodefaultctor directive or the -nodefaultctor command line option. For example:

swig -nodefaultctor example.i 

or

%module foo
...
%nodefaultctor;        // Don't create default constructors
... declarations ...
%clearnodefaultctor;   // Re-enable default constructors

If you need more precise control, %nodefaultctor can selectively target individual structure definitions. For example:

%nodefaultctor Foo;      // No default constructor for Foo
...
struct Foo {             // No default constructor generated.
};

struct Bar {             // Default constructor generated.
};

Since ignoring the implicit or default destructors most of the time produces memory leaks, SWIG will always try to generate them. If needed, however, you can selectively disable the generation of the default/implicit destructor by using %nodefaultdtor

%nodefaultdtor Foo; // No default/implicit destructor for Foo
...
struct Foo {              // No default destructor is generated.
};

struct Bar {              // Default destructor generated.
};

Compatibility note: Prior to SWIG-1.3.7, SWIG did not generate default constructors 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.

Note: There is also the %nodefault 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.

5.5.6 Adding member functions to C structures

Most languages provide a mechanism for creating classes and supporting object oriented programming. From a C standpoint, object oriented programming really just boils down to the process of attaching functions to structures. These functions normally operate on an instance of the structure (or object). Although there is a natural mapping of C++ to such a scheme, there is no direct mechanism for utilizing it with C code. However, SWIG provides a special %extend directive that makes it possible to attach methods to C structures for purposes of building an object oriented interface. Suppose you have a C header file with the following declaration :

/* file : vector.h */
...
typedef struct Vector {
  double x, y, z;
} Vector;

You can make a Vector look a lot like a class by writing a SWIG interface like this:

// file : vector.i
%module mymodule
%{
#include "vector.h"
%}

%include "vector.h"          // Just grab original C header file
%extend Vector {             // Attach these functions to struct Vector
  Vector(double x, double y, double z) {
    Vector *v;
    v = (Vector *) malloc(sizeof(Vector));
    v->x = x;
    v->y = y;
    v->z = z;
    return v;
  }
  ~Vector() {
    free($self);
  }
  double magnitude() {
    return sqrt($self->x*$self->x+$self->y*$self->y+$self->z*$self->z);
  }
  void print() {
    printf("Vector [%g, %g, %g]\n", $self->x, $self->y, $self->z);
  }
};

Note the usage of the $self special variable. Its usage is identical to a C++ 'this' pointer and should be used whenever access to the struct instance is required. Also note that C++ constructor and destructor syntax has been used to simulate a constructor and destructor, even for C code. There is one subtle difference to a normal C++ constructor implementation though and that is although the constructor declaration is as per a normal C++ constructor, the newly constructed object must be returned as if the constructor declaration had a return value, a Vector * in this case.

Now, when used with proxy classes in Python, you can do things like this :

>>> v = Vector(3, 4, 0)                 # Create a new vector
>>> print v.magnitude()                # Print magnitude
5.0
>>> v.print()                  # Print it out
[ 3, 4, 0 ]
>>> del v                      # Destroy it

The %extend directive can also be used inside the definition of the Vector structure. For example:

// file : vector.i
%module mymodule
%{
#include "vector.h"
%}

typedef struct Vector {
  double x, y, z;
  %extend {
    Vector(double x, double y, double z) { ... }
    ~Vector() { ... }
    ...
  }
} Vector;

Note that %extend can be used to access externally written functions provided they follow the naming convention used in this example :

/* File : vector.c */
/* Vector methods */
#include "vector.h"
Vector *new_Vector(double x, double y, double z) {
  Vector *v;
  v = (Vector *) malloc(sizeof(Vector));
  v->x = x;
  v->y = y;
  v->z = z;
  return v;
}
void delete_Vector(Vector *v) {
  free(v);
}

double Vector_magnitude(Vector *v) {
  return sqrt(v->x*v->x+v->y*v->y+v->z*v->z);
}

// File : vector.i
// Interface file
%module mymodule
%{
#include "vector.h"
%}

typedef struct Vector {
  double x, y, z;
  %extend {
    Vector(int, int, int); // This calls new_Vector()
    ~Vector();           // This calls delete_Vector()
    double magnitude();  // This will call Vector_magnitude()
    ...
  }
} Vector;

You'll also need to use these names if you want to directly call methods added using %extend from other C/C++ code.

The name used for %extend should be the name of the struct and not the name of any typedef to the struct. For example:

typedef struct Integer {
  int value;
} Int;
%extend Integer { ...  } /* Correct name */
%extend Int { ...  } /* Incorrect name */

struct Float {
  float value;
};
typedef struct Float FloatValue;
%extend Float { ...  } /* Correct name */
%extend FloatValue { ...  } /* Incorrect name */

There is one exception to this rule and that is when the struct is anonymously named such as:

typedef struct {
  double value;
} Double;
%extend Double { ...  } /* Okay */

A little known feature of the %extend directive is that it can also be used to add synthesized attributes or to modify the behavior of existing data attributes. For example, suppose you wanted to make magnitude a read-only attribute of Vector instead of a method. To do this, you might write some code like this:

// Add a new attribute to Vector
%extend Vector {
  const double magnitude;
}
// Now supply the implementation of the Vector_magnitude_get function
%{
const double Vector_magnitude_get(Vector *v) {
  return (const double) sqrt(v->x*v->x+v->y*v->y+v->z*v->z);
}
%}

Now, for all practical purposes, magnitude will appear like an attribute of the object.

A similar technique can also be used to work with data members that you want to process. For example, consider this interface:

typedef struct Person {
  char name[50];
  ...
} Person;

Say you wanted to ensure name was always upper case, you can rewrite the interface as follows to ensure this occurs whenever a name is read or written to:

typedef struct Person {
  %extend {
    char name[50];
  }
  ...
} Person;

%{
#include <string.h>
#include <ctype.h>

void make_upper(char *name) {
  char *c;
  for (c = name; *c; ++c)
    *c = (char)toupper((int)*c);
}

/* Specific implementation of set/get functions forcing capitalization */

char *Person_name_get(Person *p) {
  make_upper(p->name);
  return p->name;
}

void Person_name_set(Person *p, char *val) {
  strncpy(p->name, val, 50);
  make_upper(p->name);
}
%}

Finally, it should be stressed that even though %extend can be used to add new data members, these new members can not require 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).

5.5.7 Nested structures

Occasionally, a C program will involve structures like this :

typedef struct Object {
  int objtype;
  union {
    int ivalue;
    double dvalue;
    char *strvalue;
    void *ptrvalue;
  } intRep;
} Object;

When SWIG encounters this, it performs a structure splitting operation that transforms the declaration into the equivalent of the following:

typedef union {
  int ivalue;
  double dvalue;
  char *strvalue;
  void *ptrvalue;
} Object_intRep;

typedef struct Object {
  int objType;
  Object_intRep intRep;
} Object;

SWIG will then create an Object_intRep structure for use inside the interface file. Accessor functions will be created for both structures. In this case, functions like this would be created :

Object_intRep *Object_intRep_get(Object *o) {
  return (Object_intRep *) &o->intRep;
}
int Object_intRep_ivalue_get(Object_intRep *o) {
  return o->ivalue;
}
int Object_intRep_ivalue_set(Object_intRep *o, int value) {
  return (o->ivalue = value);
}
double Object_intRep_dvalue_get(Object_intRep *o) {
  return o->dvalue;
}
... etc ...

Although this process is a little hairy, it works like you would expect in the target scripting language--especially when proxy classes are used. For instance, in Perl:

# Perl5 script for accessing nested member
$o = CreateObject();                    # Create an object somehow
$o->{intRep}->{ivalue} = 7              # Change value of o.intRep.ivalue

If you have a lot of nested structure declarations, it is advisable to double-check them after running SWIG. Although, there is a good chance that they will work, you may have to modify the interface file in certain cases.

Finally, note that nesting is handled differently in C++ mode, see Nested classes.

5.5.8 Other things to note about structure wrapping

SWIG doesn't care if the declaration of a structure in a .i file exactly matches that used in the underlying C code (except in the case of nested structures). For this reason, there are no problems omitting problematic members or simply omitting the structure definition altogether. If you are happy passing pointers around, this can be done without ever giving SWIG a structure definition.

Starting with SWIG1.3, a number of improvements have been made to SWIG's code generator. Specifically, even though structure access has been described in terms of high-level accessor functions such as this,

double Vector_x_get(Vector *v) {
  return v->x;
}

most of the generated code is actually inlined directly into wrapper functions. Therefore, no function Vector_x_get() actually exists in the generated wrapper file. For example, when creating a Tcl module, the following function is generated instead:

static int
_wrap_Vector_x_get(ClientData clientData, Tcl_Interp *interp, 
                   int objc, Tcl_Obj *const objv[]) {
  struct Vector *arg1 ;
  double result ;

  if (SWIG_GetArgs(interp, objc, objv, "p:Vector_x_get self ", &arg0,
                   SWIGTYPE_p_Vector) == TCL_ERROR)
    return TCL_ERROR;
  result = (double ) (arg1->x);
  Tcl_SetObjResult(interp, Tcl_NewDoubleObj((double) result));
  return TCL_OK;
}

The only exception to this rule are methods defined with %extend . In this case, the added code is contained in a separate function.

Finally, it is important to note that most language modules may choose to build a more advanced interface. Although you may never use the low-level interface described here, most of SWIG's language modules use it in some way or another.

5.6 Code Insertion

Sometimes it is necessary to insert special code into the resulting wrapper file generated by SWIG. For example, you may want to include additional C code to perform initialization or other operations. There are four common ways to insert code, but it's useful to know how the output of SWIG is structured first.

5.6.1 The output of SWIG

When SWIG creates its output C/C++ file, it is broken up into five sections corresponding to runtime code, headers, wrapper functions, and module initialization code (in that order).

• Begin section.
  A placeholder for users to put code at the beginning of the C/C++ wrapper file. This is most often used to define preprocessor macros that are used in later sections.
• Runtime code.
  This code is internal to SWIG and is used to include type-checking and other support functions that are used by the rest of the module.
• Header section.
  This is user-defined support code that has been included by the %{ ... %} directive. Usually this consists of header files and other helper functions.
• Wrapper code.
  These are the wrappers generated automatically by SWIG.
• Module initialization.
  The function generated by SWIG to initialize the module upon loading.

5.6.2 Code insertion blocks

The %insert directive enables inserting blocks of code into a given section of the generated code. It can be used in one of two ways:

%insert("section") "filename"
%insert("section") %{ ... %}

The first will dump the contents of the file in the given filename into the named section. The second inserts the code between the braces into the named section. For example, the following adds code into the runtime section:

%insert("runtime") %{
  ... code in runtime section ...
%}

There are the 5 sections, however, some target languages add in additional sections and some of these result in code being generated into a target language file instead of the C/C++ wrapper file. These are documented when available in the target language chapters. Macros named after the code sections are available as additional directives and these macro directives are normally used instead of %insert . For example, %runtime is used instead of %insert("runtime"). The valid sections and order of the sections in the generated C/C++ wrapper file is as shown:

%begin %{
  ... code in begin section ...
%}

%runtime %{
  ... code in runtime section ...
%}

%header %{
  ... code in header section ...
%}

%wrapper %{
  ... code in wrapper section ...
%}

%init %{
  ... code in init section ...
%}

The bare %{ ... %} directive is a shortcut that is the same as %header %{ ... %}.

The %begin section is effectively empty as it just contains the SWIG banner by default. This section is provided as a way for users to insert code at the top of the wrapper file before any other code is generated. Everything in a code insertion block is copied verbatim into the output file and is not parsed by SWIG. Most SWIG input files have at least one such block to include header files and support C code. Additional code blocks may be placed anywhere in a SWIG file as needed.

%module mymodule
%{
#include "my_header.h"
%}
... Declare functions here
%{

void some_extra_function() {
  ...
}
%}

A common use for code blocks is to write "helper" functions. These are functions that are used specifically for the purpose of building an interface, but which are generally not visible to the normal C program. For example :

%{
/* Create a new vector */
static Vector *new_Vector() {
  return (Vector *) malloc(sizeof(Vector));
}

%}
// Now wrap it 
Vector *new_Vector();

5.6.3 Inlined code blocks

Since the process of writing helper functions is fairly common, there is a special inlined form of code block that is used as follows :

%inline %{
/* Create a new vector */
Vector *new_Vector() {
  return (Vector *) malloc(sizeof(Vector));
}
%}

This is the same as writing:

%{
/* Create a new vector */
Vector *new_Vector() {
  return (Vector *) malloc(sizeof(Vector));
}
%}

/* Create a new vector */
Vector *new_Vector() {
  return (Vector *) malloc(sizeof(Vector));
}

In other words, the %inline directive inserts all of the code that follows verbatim into the header portion of an interface file. The code is then parsed by both the SWIG preprocessor and parser. Thus, the above example creates a new command new_Vector using only one declaration. Since the code inside an %inline %{ ... %} block is given to both the C compiler and SWIG, it is illegal to include any SWIG directives inside a %{ ... %} block.

Note: The usual SWIG C preprocessor rules apply to code in %apply blocks when SWIG parses this code. For example, as mentioned earlier, SWIG's C Preprocessor does not follow #include directives by default.

5.6.4 Initialization blocks

When code is included in the %init section, it is copied directly into the module initialization function. For example, if you needed to perform some extra initialization on module loading, you could write this:

%init %{
  init_variables();
%}

Please note that some language backends (e.g. C# or Java) don't have any initialization function, hence you should define a global object performing the necessary initialization for them instead:

%init %{
  static struct MyInit { MyInit() { init_variables(); } } myInit;
%}

5.7 An Interface Building Strategy

This section describes the general approach for building interfaces with SWIG. The specifics related to a particular scripting language are found in later chapters.

5.7.1 Preparing a C program for SWIG

SWIG doesn't require modifications to your C code, but if you feed it a collection of raw C header files or source code, the results might not be what you expect---in fact, they might be awful. Here's a series of steps you can follow to make an interface for a C program :

• Identify the functions that you want to wrap. It's probably not necessary to access every single function of a C program--thus, a little forethought can dramatically simplify the resulting scripting language interface. C header files are a particularly good source for finding things to wrap.
• Create a new interface file to describe the scripting language interface to your program.
• Copy the appropriate declarations into the interface file or use SWIG's %include directive to process an entire C source/header file.
• Make sure everything in the interface file uses ISO C/C++ syntax.
• Make sure all necessary `typedef' declarations and type-information is available in the interface file. In particular, ensure that the type information is specified in the correct order as required by a C/C++ compiler. Most importantly, define a type before it is used! A C compiler will tell you if the full type information is not available if it is needed, whereas SWIG will usually not warn or error out as it is designed to work without full type information. However, if type information is not specified correctly, the wrappers can be sub-optimal and even result in uncompilable C/C++ code.
• If your program has a main() function, you may need to rename it (read on).
• Run SWIG and compile.

Although this may sound complicated, the process turns out to be fairly easy once you get the hang of it.

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 swig-devel mailing list or to the SWIG bug tracker.

5.7.2 The SWIG interface file

The preferred method of using SWIG is to generate a separate interface file. Suppose you have the following C header file :

/* File : header.h */

#include <stdio.h>
#include <math.h>

extern int foo(double);
extern double bar(int, int);
extern void dump(FILE *f);

A typical SWIG interface file for this header file would look like the following :

/* File : interface.i */
%module mymodule
%{
#include "header.h"
%}
extern int foo(double);
extern double bar(int, int);
extern void dump(FILE *f);

Of course, in this case, our header file is pretty simple so we could use a simpler approach and use an interface file like this:

/* File : interface.i */
%module mymodule
%{
#include "header.h"
%}
%include "header.h"

The main advantage of this approach is minimal maintenance of an interface file for when the header file changes in the future. In more complex projects, an interface file containing numerous %include and #include statements like this is one of the most common approaches to interface file design due to lower maintenance overhead.

5.7.3 Why use separate interface files?

Although SWIG can parse many header files, it is more common to write a special .i file defining the interface to a package. There are several reasons why you might want to do this:

• It is rarely necessary to access every single function in a large package. Many C functions might have little or no use in a scripted environment. Therefore, why wrap them?
• Separate interface files provide an opportunity to provide more precise rules about how an interface is to be constructed.
• Interface files can provide more structure and organization.
• SWIG can't parse certain definitions that appear in header files. Having a separate file allows you to eliminate or work around these problems.
• Interface files provide a more precise definition of what the interface is. Users wanting to extend the system can go to the interface file and immediately see what is available without having to dig it out of header files.

5.7.4 Getting the right header files

Sometimes, it is necessary to use certain header files in order for the code generated by SWIG to compile properly. Make sure you include certain header files by using a %{ %} block like this:

%module graphics
%{
#include <GL/gl.h>
#include <GL/glu.h>
%}

// Put the rest of the declarations here
...

5.7.5 What to do with main()

If your program defines a main() function, you may need to get rid of it or rename it in order to use a scripting language. Most scripting languages define their own main() procedure that is called instead. main() also makes no sense when working with dynamic loading. There are a few approaches to solving the main() conflict :

• Get rid of main() entirely.
• Rename main() to something else. You can do this by compiling your C program with an option like -Dmain=oldmain.
• Use conditional compilation to only include main() when not using a scripting language.

Getting rid of main() may cause potential initialization problems of a program. To handle this problem, you may consider writing a special function called program_init() that initializes your program upon startup. This function could then be called either from the scripting language as the first operation, or when the SWIG generated module is loaded.

As a general note, many C programs only use the main() function to parse command line options and to set parameters. However, by using a scripting language, you are probably trying to create a program that is more interactive. In many cases, the old main() program can be completely replaced by a Perl, Python, or Tcl script.

Note: In some cases, you might be inclined to create a scripting language wrapper for main(). If you do this, the compilation will probably work and your module might even load correctly. The only trouble is that when you call your main() wrapper, you will find that it actually invokes the main() of the scripting language interpreter itself! This behavior is a side effect of the symbol binding mechanism used in the dynamic linker. The bottom line: don't do this.

6 SWIG and C++

This chapter describes SWIG's support for wrapping C++. It is mostly concerned about C++ as defined by the C++ 98 and 03 standards. For additions to the original C++ standard, please read the SWIG and C++11, SWIG and C++14, SWIG and C++17 and SWIG and C++20 chapters. As a prerequisite, you should first read the chapter SWIG Basics to see how SWIG wraps ISO C. Support for C++ builds upon ISO C wrapping and that material will be useful in understanding this chapter.

6.1 Comments on C++ Wrapping

Because of its complexity and the fact that C++ can be difficult to integrate with itself let alone other languages, SWIG only provides support for a subset of C++ features. Fortunately, this is now a rather large subset.

In part, the problem with C++ wrapping is that there is no semantically obvious (or automatic ) way to map many of its advanced features into other languages. As a simple example, consider the problem of wrapping C++ multiple inheritance to a target language with no such support. Similarly, the use of overloaded operators and overloaded functions can be problematic when no such capability exists in a target language.

A more subtle issue with C++ has to do with the way that some C++ programmers think about programming libraries. In the world of SWIG, you are really trying to create binary-level software components for use in other languages. In order for this to work, a "component" has to contain real executable instructions and there has to be some kind of binary linking mechanism for accessing its functionality. In contrast, C++ has increasingly relied upon generic programming and templates for much of its functionality. Although templates are a powerful feature, they are largely orthogonal to the whole notion of binary components and libraries. For example, an STL vector does not define any kind of binary object for which SWIG can just create a wrapper. To further complicate matters, these libraries often utilize a lot of behind the scenes magic in which the semantics of seemingly basic operations (e.g., pointer dereferencing, procedure call, etc.) can be changed in dramatic and sometimes non-obvious ways. Although this "magic" may present few problems in a C++-only universe, it greatly complicates the problem of crossing language boundaries and provides many opportunities to shoot yourself in the foot. You will just have to be careful.

6.2 Approach

To wrap C++, SWIG uses a layered approach to code generation. At the lowest level, SWIG generates a collection of procedural ISO C style wrappers. These wrappers take care of basic type conversion, type checking, error handling, and other low-level details of the C++ binding. These wrappers are also sufficient to bind C++ into any target language that supports built-in procedures. In some sense, you might view this layer of wrapping as providing a C library interface to C++. On top of the low-level procedural (flattened) interface, SWIG generates proxy classes that provide a natural object-oriented (OO) interface to the underlying code. The proxy classes are typically written in the target language itself. For instance, in Python, a real Python class is used to provide a wrapper around the underlying C++ object.

It is important to emphasize that SWIG takes a deliberately conservative and non-intrusive approach to C++ wrapping. SWIG does not encapsulate C++ classes inside a special C++ adaptor, it does not rely upon templates, nor does it add in additional C++ inheritance when generating wrappers. The last thing that most C++ programs need is even more compiler magic. Therefore, SWIG tries to maintain a very strict and clean separation between the implementation of your C++ application and the resulting wrapper code. You might say that SWIG has been written to follow the principle of least surprise--it does not play sneaky tricks with the C++ type system, it doesn't mess with your class hierarchies, and it doesn't introduce new semantics. Although this approach might not provide the most seamless integration with C++, it is safe, simple, portable, and debuggable.

Some of this chapter focuses on the low-level procedural interface to C++ that is used as the foundation for all language modules. Keep in mind that the target languages also provide the high-level OO interface via proxy classes. More detailed coverage can be found in the documentation for each target language.

6.3 Supported C++ features

SWIG currently supports most C++ features including the following:

• Classes
• Constructors and destructors
• Virtual functions
• Public inheritance (including multiple inheritance)
• Static functions
• Function and method overloading
• Operator overloading for many standard operators
• References
• Templates (including specialization and member templates)
• Pointers to members
• Namespaces
• Default parameters
• Smart pointers

The following C++ features are not currently supported:

• Overloaded versions of certain operators (new, delete, etc.)

As a rule of thumb, SWIG should not be used on raw C++ source files, use header files only.

SWIG's C++ support is an ongoing project so some of these limitations may be lifted in future releases. However, we make no promises. Also, submitting a bug report is a very good way to get problems fixed (wink).

6.4 Command line options and compilation

When wrapping C++ code, it is critical that SWIG be called with the `-c++' option. This changes the way a number of critical features such as memory management are handled. It also enables the recognition of C++ keywords. Without the -c++ flag, SWIG will either issue a warning or a large number of syntax errors if it encounters C++ code in an interface file.

When compiling and linking the resulting wrapper file, it is normal to use the C++ compiler. For example:

$ swig -c++ -tcl example.i
$ c++ -fPIC -c example_wrap.cxx 
$ c++ example_wrap.o $(OBJS) -o example.so

Unfortunately, the process varies slightly on each platform. Make sure you refer to the documentation on each target language for further details. The SWIG Wiki also has further details.

6.5 Proxy classes

In order to provide a natural mapping from C++ classes to the target language classes, SWIG's target languages mostly wrap C++ classes with special proxy classes. These proxy classes are typically implemented in the target language itself. For example, if you're building a Python module, each C++ class is wrapped by a Python proxy class. Or if you're building a Java module, each C++ class is wrapped by a Java proxy class.

6.5.1 Construction of proxy classes

Proxy classes are always constructed as an extra layer of wrapping that uses low-level accessor functions. To illustrate, suppose you had a C++ class like this:

class Foo {
  public:
    Foo();
    ~Foo();
    int  bar(int x);
    int  x;
};

Using C++ as pseudocode, a proxy class looks something like this:

class FooProxy {
  private:
    Foo    *self;
  public:
    FooProxy() {
      self = new_Foo();
    }
    ~FooProxy() {
      delete_Foo(self);
    }
    int bar(int x) {
      return Foo_bar(self, x);
    }
    int x_get() {
      return Foo_x_get(self);
    }
    void x_set(int x) {
      Foo_x_set(self, x);
    }
};

Of course, always keep in mind that the real proxy class is written in the target language. For example, in Python, the proxy might look roughly like this:

class Foo:
    def __init__(self):
        self.this = new_Foo()
    def __del__(self):
        delete_Foo(self.this)
    def bar(self, x):
        return Foo_bar(self.this, x)
    def __getattr__(self, name):
        if name == 'x':
            return Foo_x_get(self.this)
        ...
    def __setattr__(self, name, value):
        if name == 'x':
            Foo_x_set(self.this, value)
        ...

Again, it's important to emphasize that the low-level accessor functions are always used by the proxy classes. Whenever possible, proxies try to take advantage of language features that are similar to C++. This might include operator overloading, exception handling, and other features.

6.5.2 Resource management in proxies

A major issue with proxies concerns the memory management of wrapped objects. Consider the following C++ code:

class Foo {
public:
  Foo();
  ~Foo();
  int bar(int x);
  int x;
};

class Spam {
public:
  Foo *value;
  ...
};

Consider some script code that uses these classes:

f = Foo()               # Creates a new Foo
s = Spam()              # Creates a new Spam
s.value = f             # Stores a reference to f inside s
g = s.value             # Returns stored reference
g = 4                   # Reassign g to some other value
del f                   # Destroy f 

Now, ponder the resulting memory management issues. When objects are created in the script, the objects are wrapped by newly created proxy classes. That is, there is both a new proxy class instance and a new instance of the underlying C++ class. In this example, both f and s are created in this way. However, the statement s.value is rather curious---when executed, a pointer to f is stored inside another object. This means that the scripting proxy class AND another C++ class share a reference to the same object. To make matters even more interesting, consider the statement g = s.value. When executed, this creates a new proxy class g that provides a wrapper around the C++ object stored in s.value . In general, there is no way to know where this object came from---it could have been created by the script, but it could also have been generated internally. In this particular example, the assignment of g results in a second proxy class for f. In other words, a reference to f is now shared by two proxy classes and a C++ class.

Finally, consider what happens when objects are destroyed. In the statement, g=4, the variable g is reassigned. In many languages, this makes the old value of g available for garbage collection. Therefore, this causes one of the proxy classes to be destroyed. Later on, the statement del f destroys the other proxy class. Of course, there is still a reference to the original object stored inside another C++ object. What happens to it? Is the object still valid?

To deal with memory management problems, proxy classes provide an API for controlling ownership. In C++ pseudocode, ownership control might look roughly like this:

class FooProxy {
  public:
    Foo    *self;
    int     thisown;

    FooProxy() {
      self = new_Foo();
      thisown = 1;       // Newly created object
    }
    ~FooProxy() {
      if (thisown) delete_Foo(self);
    }
    ...
    // Ownership control API
    void disown() {
      thisown = 0;
    }
    void acquire() {
      thisown = 1;
    }
};

class FooPtrProxy: public FooProxy {
public:
  FooPtrProxy(Foo *s) {
    self = s;
    thisown = 0;
  }
};

class SpamProxy {
  ...
  FooProxy *value_get() {
    return FooPtrProxy(Spam_value_get(self));
  }
  void value_set(FooProxy *v) {
    Spam_value_set(self, v->self);
    v->disown();
  }
  ...
};

Looking at this code, there are a few central features:

• Each proxy class keeps an extra flag to indicate ownership. C++ objects are only destroyed if the ownership flag is set.
• When new objects are created in the target language, the ownership flag is set.
• When a reference to an internal C++ object is returned, it is wrapped by a proxy class, but the proxy class does not have ownership.
• In certain cases, ownership is adjusted. For instance, when a value is assigned to the member of a class, ownership is lost.
• Manual ownership control is provided by special disown() and acquire() methods.

Given the tricky nature of C++ memory management, it is impossible for proxy classes to automatically handle every possible memory management problem. However, proxies do provide a mechanism for manual control that can be used (if necessary) to address some of the more tricky memory management problems.

6.5.3 Language specific details

Language specific details on proxy classes are contained in the chapters describing each target language. This chapter has merely introduced the topic in a very general way.

6.6 Simple C++ wrapping

The following code shows a SWIG interface file for a simple C++ class.

%module list
%{
#include "list.h"
%}

// Very simple C++ example for linked list

class List {
public:
  List();
  ~List();
  int  search(char *value);
  void insert(char *);
  void remove(char *);
  char *get(int n);
  int  length;
static void print(List *l);
};

To generate wrappers for this class, SWIG first reduces the class to a collection of low-level C-style accessor functions which are then used by the proxy classes.

6.6.1 Constructors and destructors

C++ constructors and destructors are translated into accessor functions such as the following :

List * new_List(void) {
  return new List;
}
void delete_List(List *l) {
  delete l;
}

6.6.2 Default constructors, copy constructors and implicit destructors

Following the C++ rules for implicit constructor and destructors, SWIG will automatically assume there is one even when they are not explicitly declared in the class interface.

In general then:

• If a C++ class does not declare any explicit constructor, SWIG will automatically generate a wrapper for one.
• If a C++ class does not declare an explicit copy constructor, SWIG will automatically generate a wrapper for one if %copyctor is used.
• If a C++ class does not declare an explicit destructor, SWIG will automatically generate a wrapper for one.

And as in C++, a few rules that alters the previous behavior:

• A default constructor is not created if a class already defines a constructor with arguments.
• Default constructors are not generated for classes with pure virtual methods or for classes that inherit from an abstract class, but don't provide definitions for all of the pure methods.
• A default constructor is not created unless all base classes support a default constructor.
• Default constructors and implicit destructors are not created if a class defines them in a private or protected section.
• Default constructors and implicit destructors are not created if any base class defines a non-public default constructor or destructor.

SWIG should never generate a default constructor, copy constructor or default destructor wrapper for a class in which it is illegal to do so. In some cases, however, it could be necessary (if the complete class declaration is not visible from SWIG, and one of the above rules is violated) or desired (to reduce the size of the final interface) by manually disabling the implicit constructor/destructor generation.

To manually disable these, the %nodefaultctor and %nodefaultdtor feature flag directives can be used. Note that these directives only affects the implicit generation, and they have no effect if the default/copy constructors or destructor are explicitly declared in the class interface.

For example:

%nodefaultctor Foo;  // Disable the default constructor for class Foo.
class Foo {          // No default constructor is generated, unless one is declared
...
};
class Bar {          // A default constructor is generated, if possible
...
};

The directive %nodefaultctor can also be applied "globally", as in:

%nodefaultctor; // Disable creation of default constructors
class Foo {     // No default constructor is generated, unless one is declared
...
};
class Bar {   
public:
  Bar();        // The default constructor is generated, since one is declared
};
%clearnodefaultctor; // Enable the creation of default constructors again

The corresponding %nodefaultdtor directive can be used to disable the generation of the default or implicit destructor, if needed. Be aware, however, that this could lead to memory leaks in the target language. Hence, it is recommended to use this directive only in well known cases. For example:

%nodefaultdtor Foo;   // Disable the implicit/default destructor for class Foo.
class Foo {           // No destructor is generated, unless one is declared
...
};

Compatibility Note: 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 %nodefault. Furthermore, in order for SWIG to properly generate (or not generate) default constructors, it must be able to gather information from both the private and protected sections (specifically, it needs to know if a private or protected constructor/destructor is defined). In older versions of SWIG, it was fairly common to simply remove or comment out the private and protected sections of a class due to parser limitations. However, this removal may now cause SWIG to erroneously generate constructors for classes that define a constructor in those sections. Consider restoring those sections in the interface or using %nodefault to fix the problem.

Note: The %nodefault 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 it.

6.6.3 When constructor wrappers aren't created

If a class defines a constructor, SWIG normally tries to generate a wrapper for it. However, SWIG will not generate a constructor wrapper if it thinks that it will result in illegal wrapper code. There are really two cases where this might show up.

First, SWIG won't generate wrappers for protected or private constructors. For example:

class Foo {
protected:
  Foo();         // Not wrapped.
public:
  ...
};

Next, SWIG won't generate wrappers for a class if it appears to be abstract--that is, it has undefined pure virtual methods. Here are some examples:

class Bar {
public:
  Bar();               // Not wrapped.  Bar is abstract.
  virtual void spam(void) = 0;
};

class Grok : public Bar {
public:
  Grok();              // Not wrapped. No implementation of abstract spam().
};

Some users are surprised (or confused) to find missing constructor wrappers in their interfaces. In almost all cases, this is caused when classes are determined to be abstract. To see if this is the case, run SWIG with all of its warnings turned on:

% swig -Wall -python module.i

In this mode, SWIG will issue a warning for all abstract classes. It is possible to force a class to be non-abstract using this:

%feature("notabstract") Foo;

class Foo : public Bar {
public:
  Foo();    // Generated no matter what---not abstract.
  ...
};

More information about %feature can be found in the Customization features chapter.

6.6.4 Copy constructors

If a class defines more than one constructor, its behavior depends on the capabilities of the target language. If overloading is supported, the copy constructor is accessible using the normal constructor function. For example, if you have this:

class List {
public:
  List();    
  List(const List &);      // Copy constructor
  ...
};

then the copy constructor can be used as follows:

x = List()               # Create a list
y = List(x)              # Copy list x

If the target language does not support overloading, then the copy constructor is available through a special function like this:

List *copy_List(List *f) {
  return new List(*f);
}

Note: For a class X, SWIG only treats a constructor as a copy constructor if it can be applied to an object of type X or X *. If more than one copy constructor is defined, only the first definition that appears is used as the copy constructor--other definitions will result in a name-clash. Constructors such as X(const X &), X(X &), and X(X *) are handled as copy constructors in SWIG.

Note: SWIG does not generate a copy constructor wrapper unless one is explicitly declared in the class. This differs from the treatment of default constructors and destructors. However, copy constructor wrappers can be generated if using the copyctor feature flag. For example:

%copyctor List;

class List {
public:
  List();    
};

Will generate a copy constructor wrapper for List.

Compatibility note: Special support for copy constructors was not added until SWIG-1.3.12. In previous versions, copy constructors could be wrapped, but they had to be renamed. For example:

%rename(CopyFoo) Foo::Foo(const Foo &);

class Foo {
public:
  Foo();
  Foo(const Foo &);
  ...
};

For backwards compatibility, SWIG does not perform any special copy-constructor handling if the constructor has been manually renamed. For instance, in the above example, the name of the constructor is set to new_CopyFoo(). This is the same as in older versions.

6.6.5 Member functions

All member functions are roughly translated into accessor functions like this :

int List_search(List *obj, char *value) {
  return obj->search(value);
}

This translation is the same even if the member function has been declared as virtual.

It should be noted that SWIG does not actually create a C accessor function in the code it generates. Instead, member access such as obj->search(value) is directly inlined into the generated wrapper functions. However, the name and calling convention of the low-level procedural wrappers match the accessor function prototype described above.

6.6.6 Static members

Static member functions are called directly without making any special transformations. For example, the static member function print(List *l) directly invokes List::print(List *l) in the generated wrapper code.

6.6.7 Member data

Member data is handled in exactly the same manner as for C structures. A pair of accessor functions are effectively created. For example :

int List_length_get(List *obj) {
  return obj->length;
}
int List_length_set(List *obj, int value) {
  obj->length = value;
  return value;
}

A read-only member can be created using the %immutable and %mutable feature flag directive. For example, we probably wouldn't want the user to change the length of a list so we could do the following to make the value available, but read-only.

class List {
public:
...
%immutable;
  int length;
%mutable;
...
};

Alternatively, you can specify an immutable member in advance like this:

%immutable List::length;
...
class List {
  ...
  int length;         // Immutable by above directive
  ...
};

Similarly, all data attributes declared as const are wrapped as read-only members.

By default, SWIG uses the const reference typemaps for members that are primitive types. There are some subtle issues when wrapping data members that are not primitive types, such as classes. For instance, if you had another class like this,

class Foo {
public:
  List items;
  ...

then the low-level accessor to the items member actually uses pointers. For example:

List *Foo_items_get(Foo *self) {
  return &self->items;
}
void Foo_items_set(Foo *self, List *value) {
  self->items = *value;
}

More information about this can be found in the SWIG Basics chapter, Structure data members section.

The wrapper code to generate the accessors for classes comes from the pointer typemaps. This can be somewhat unnatural for some types. For example, a user would expect the STL std::string class member variables to be wrapped as a string in the target language, rather than a pointer to this class. The const reference typemaps offer this type of marshalling, so there is a feature to tell SWIG to use the const reference typemaps rather than the pointer typemaps. It is the naturalvar feature and can be used to effectively change the way accessors are generated to the following:

const List &Foo_items_get(Foo *self) {
  return self->items;
}
void Foo_items_set(Foo *self, const List &value) {
  self->items = value;
}

The %naturalvar directive is a macro for, and hence equivalent to, %feature("naturalvar"). It can be used as follows:

// All List variables will use const List& typemaps
%naturalvar List;

// Only Foo::myList will use const List& typemaps
%naturalvar Foo::myList;
struct Foo {
  List myList;
};

// All non-primitive types will use const reference typemaps
%naturalvar;

The observant reader will notice that %naturalvar works like any other feature flag directive but with some extra flexibility. The first of the example usages above shows %naturalvar attaching to the myList 's variable type, that is the List class. The second usage shows %naturalvar attaching to the variable name. Hence the naturalvar feature can be used on either the variable's name or type. Note that using the naturalvar feature on a variable's name overrides any naturalvar feature attached to the variable's type.

It is generally a good idea to use this feature globally as the reference typemaps have extra NULL checking compared to the pointer typemaps. A pointer can be NULL, whereas a reference cannot, so the extra checking ensures that the target language user does not pass in a value that translates to a NULL pointer and thereby preventing any potential NULL pointer dereferences. The %naturalvar feature will apply to global variables in addition to member variables in some language modules, eg C# and Java.

The naturalvar behavior can also be turned on as a global setting via the -naturalvar commandline option or the module mode option, %module(naturalvar=1). However, any use of %feature("naturalvar") will override the global setting.

Compatibility note: The %naturalvar feature was introduced in SWIG-1.3.28, prior to which it was necessary to manually apply the const reference typemaps, eg %apply const std::string & { std::string * }, but this example would also apply the typemaps to methods taking a std::string pointer.

Compatibility note: 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 like this

struct Foo {
  size_t  len;
};

and nothing was known about size_t, then accessors would be written to work with size_t *. Starting in SWIG-1.3.12, this behavior has been modified. Specifically, pointers will only be used if SWIG knows that a datatype corresponds to a structure or class. Therefore, the above code would be wrapped into accessors involving size_t. This change is subtle, but it smooths over a few problems related to structure wrapping and some of SWIG's customization features.

6.7 Protection

SWIG wraps class members that are public following the C++ conventions, i.e., by explicit public declaration or by the use of using 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 constructors and destructors. Directors could also modify the way non-public virtual protected members are treated.

By default, members of a class definition are assumed to be private until you explicitly give a `public:' declaration (This is the same convention used by C++).

6.8 Enums and constants

Enumerations and constants are handled differently by the different language modules and are described in detail in the appropriate language chapter. However, many languages map enums and constants in a class definition into constants with the classname as a prefix. For example :

class Swig {
public:
  enum {ALE, LAGER, PORTER, STOUT};
};

Generates the following set of constants in the target scripting language :

Swig_ALE = Swig::ALE
Swig_LAGER = Swig::LAGER
Swig_PORTER = Swig::PORTER
Swig_STOUT = Swig::STOUT

Members declared as const are wrapped as read-only members and do not create constants.

6.9 Friends

6.9.1 Friend classes

Friend classes are a C++ feature that do not affect SWIG wrappers. SWIG simply parses the friend class declarations, but they are effectively ignored as they have no meaningful effect for wrappers. An example of friend classes:

class X;
class Y;
class C {
  // Friend classes have no effect on generated wrappers
  friend class X;
  friend Y;
  ...
};

6.9.2 Friend function definitions

A friend function definition in a C++ class defines a non-member function of the class and simultaneously makes it a friend of the class. For example, if you have this code:

class Buddy {
  int val;
  friend int blah(Buddy *b) { return b->val; }
public:
  ...
};

then the friend function definition results in wrapper code equivalent to one generated for the following:

class Buddy {
  int val;
  friend int blah(Buddy *b);
public:
  ...
};

int blah(Buddy *b) { return b->val; }

Access from target languages is thus as if blah was wrapped as a non-member function. The function is available and wrapped even if the friend is defined with private or protected access.

A friend definition, as in C++, is understood to be in the same scope that the class is defined in, hence the scoping required for SWIG directives, such as %ignore, is as follows:

%ignore bar::blah(Buddy *b);
// Not: %ignore bar::Buddy::blah(Buddy *b);

namespace bar {
  class Buddy {
    int val;
    friend int blah(Buddy *b) { return b->val; }
  public:
    ...
  };
}

and a wrapper for blah will not be generated.

6.9.3 Friend function declarations

A C++ class can specify friends via friend function declarations. These functions are allowed access to the private and protected members of a class. This is pure C++ functionality and these friend function declarations are hence quietly ignored by SWIG and do not result in any wrappers. Well, not always! The C++ rules for friends that SWIG needs to follow are not that simple. Technically, only qualified function declarations are silently ignored by SWIG. Below are some examples of qualified friend declarations in A that are quietly ignored:

struct B {
  int f();
  B();
  ~B();
  ...
};

int g();

class A {
public:
  // The following friend function-declarations are silently ignored (including constructor and destructor friends)
  friend B::B();
  friend B::~B();
  friend int B::f();
  friend int ::g();
  ...
};

In the example above, if SWIG parses the struct B and global function g(), then they are of course wrapped as normal.

6.9.4 Unqualified friend functions

Further clarification is required regarding both friend function definitions and declarations. In C++, friend function definitions can only be unqualified, whereas, friend function declarations can be either unqualified or qualified. Qualified friend function declarations are silently ignored by SWIG as covered in the previous section. SWIG does generate wrappers for any unqualified friend functions that it parses. This section goes through some of the complexities of wrapping unqualified friend functions.

Consider an unqualified friend function definition:

class Chum {
  int val;
  friend int blah() { Chum c; c.private_function(); return c.val; }
  void private_function();
public:
  ...
};

The Chum::blah() friend is very similar to the Buddy::blah(Buddy *) friend presented earlier. However, the generated code to call blah() may not compile unlike the code to call blah(Buddy *). The compiler error will be something like:

error: 'blah' was not declared in this scope

The reason one works and the other doesn't is due to the rules around unqualified friend definitions/declarations. Broadly, friends are not visible for lookup except via argument dependent lookup that considers the class that the friend is defined/declared in, unless there is a matching declaration at namespace scope. This will probably only make sense if you are conversant with this C++ concept, which is covered quite well at Argument-dependent lookup. In our examples, blah(Buddy *) is visible via argument dependent lookup, but blah() is not. The solution is thus to provide a matching declaration in order to make the function visible to the compiler. Simply add:

int blah();

SWIG does not have to parse it. In all likelihood, your code already has the matching declaration as it is required in order for the friend function definition to be usable from pure C++ code.

The same potential problem applies to unqualified friend function declarations, such as:

class Mate {
  int val;
  friend int blah(); // Unqualified friend function declaration
  void private_function();
public:
  ...
};

Again, the actual function declaration needs to be visible to the compiler. Or just the actual function definition as shown below. This must be defined in the same scope as Mate. Of course the function definition is necessary in order to avoid linking issues too.

int blah() { Mate m; m.private_function(); return m.val; }

6.10 References and pointers

C++ references are supported, but SWIG transforms them back into pointers. For example, a declaration like this :

class Foo {
public:
  double bar(double &a);
}

has a low-level accessor

double Foo_bar(Foo *obj, double *a) {
  obj->bar(*a);
}

As a special case, most language modules pass const references to primitive datatypes (int, short, float, etc.) by value instead of pointers. For example, if you have a function like this,

void foo(const int &x);

it is called from a script as follows:

foo(3)              # Notice pass by value

Functions that return a reference are remapped to return a pointer instead. For example:

class Bar {
public:
  Foo &spam();
};

Generates an accessor like this:

Foo *Bar_spam(Bar *obj) {
  Foo &result = obj->spam();
  return &result;
}

However, functions that return const references to primitive datatypes (int, short, etc.) normally return the result as a value rather than a pointer. For example, a function like this,

const int &bar();

will return integers such as 37 or 42 in the target scripting language rather than a pointer to an integer.

Don't return references to objects allocated as local variables on the stack. SWIG doesn't make a copy of the objects so this will probably cause your program to crash.

Note: The special treatment for references to primitive datatypes is necessary to provide more seamless integration with more advanced C++ wrapping applications---especially related to templates and the STL. This was first added in SWIG-1.3.12.

6.11 Pass and return by value

Occasionally, a C++ program will pass and return class objects by value. For example, a function like this might appear:

Vector cross_product(Vector a, Vector b);

If no information is supplied about Vector, SWIG creates a wrapper function similar to the following:

Vector *wrap_cross_product(Vector *a, Vector *b) {
  Vector x;
  Vector y;
  Vector r;
  x = *a;
  y = *b;
  r = cross_product(x, y);
  return new Vector(r);
}

In order for the wrapper code to compile, Vector must define a default constructor, copy assignment operator (and/or a move assignment operator for C++11 and later). The Movable and move-only types section should be read regarding C++11 move semantics and return by value.

If Vector is defined as a class in the interface, but it does not support a default constructor, SWIG changes the wrapper code by encapsulating the arguments inside a special C++ template wrapper class, through a process called the "Fulton Transform". This produces a wrapper that looks like this:

Vector cross_product(Vector *a, Vector *b) {
  SwigValueWrapper<Vector> x;
  SwigValueWrapper<Vector> y;
  SwigValueWrapper<Vector> r;
  x = *a;
  y = *b;
  r = cross_product(x, y);
  return new Vector(r);
}

This transformation is a little sneaky, but it provides support for pass-by-value even when a class does not provide a default constructor and it makes it possible to properly support a number of SWIG's customization options. The definition of SwigValueWrapper can be found by reading the SWIG wrapper code. This class is really nothing more than a thin wrapper around a pointer.

Although SWIG usually detects the classes to which the Fulton Transform should be applied, in some situations it's necessary to override it. That's done with %feature("valuewrapper") to ensure it is used and %feature("novaluewrapper") to ensure it is not used:

%feature("novaluewrapper") A;    
class A;

%feature("valuewrapper") B;
struct B { 
  B();
  // ....
};   

It is well worth considering turning this feature on for classes that do have a default constructor. It will remove a redundant constructor call at the point of the variable declaration in the wrapper, so will generate notably better performance for large objects or for classes with expensive construction. Alternatively consider returning a reference or a pointer.

Note: this transformation has no effect on typemaps or any other part of SWIG---it should be transparent except that you may see this code when reading the SWIG output file.

Note: This template transformation is new in SWIG-1.3.11 and may be refined in future SWIG releases. In practice, it is only absolutely necessary to do this for classes that don't define a default constructor.

Note: The use of this template only occurs when objects are passed or returned by value. It is not used for C++ pointers or references.

6.12 Inheritance

SWIG supports C++ inheritance of classes and allows both single and multiple inheritance, as limited or allowed by the target language. The SWIG type-checker knows about the relationship between base and derived classes and allows pointers to any object of a derived class to be used in functions of a base class. The type-checker properly casts pointer values and is safe to use with multiple inheritance.

SWIG treats private or protected inheritance as close to the C++ spirit, and target language capabilities, as possible. In most cases, this means that SWIG will parse the non-public inheritance declarations, but that will have no effect in the generated code, besides the implicit policies derived for constructors and destructors.

The following example shows how SWIG handles inheritance. For clarity, the full C++ code has been omitted.

// shapes.i
%module shapes
%{
#include "shapes.h"
%}

class Shape {
public:
  double x, y;
  virtual double area() = 0;
  virtual double perimeter() = 0;
  void    set_location(double x, double y);
};
class Circle : public Shape {
public:
  Circle(double radius);
  ~Circle();
  double area();
  double perimeter();
};
class Square : public Shape {
public:
  Square(double size);
  ~Square();
  double area();
  double perimeter();
}

When wrapped into Python, we can perform the following operations (shown using the low level Python accessors):

$ python
>>> import shapes
>>> circle = shapes.new_Circle(7)
>>> square = shapes.new_Square(10)
>>> print shapes.Circle_area(circle)
153.93804004599999757
>>> print shapes.Shape_area(circle)
153.93804004599999757
>>> print shapes.Shape_area(square)
100.00000000000000000
>>> shapes.Shape_set_location(square, 2, -3)
>>> print shapes.Shape_perimeter(square)
40.00000000000000000
>>>

In this example, Circle and Square objects have been created. Member functions can be invoked on each object by making calls to Circle_area, Square_area, and so on. However, the same results can be accomplished by simply using the Shape_area function on either object.

One important point concerning inheritance is that the low-level accessor functions are only generated for classes in which they are actually declared. For instance, in the above example, the method set_location() is only accessible as Shape_set_location() and not as Circle_set_location() or Square_set_location() . Of course, the Shape_set_location() function will accept any kind of object derived from Shape. Similarly, accessor functions for the attributes x and y are generated as Shape_x_get(), Shape_x_set(), Shape_y_get(), and Shape_y_set(). Functions such as Circle_x_get() are not available--instead you should use Shape_x_get().

Note that there is a one to one correlation between the low-level accessor functions and the proxy methods and therefore there is also a one to one correlation between the C++ class methods and the generated proxy class methods.

Note: For the best results, SWIG requires all base classes to be defined in an interface. Otherwise, you may get a warning message like this:

example.i:18: Warning 401: Nothing known about base class 'Foo'. Ignored.

If any base class is undefined, SWIG still generates correct type relationships. For instance, a function accepting a Foo * will accept any object derived from Foo regardless of whether or not SWIG actually wrapped the Foo class. If you really don't want to generate wrappers for the base class, but you want to silence the warning, you might consider using the %import directive to include the file that defines Foo. %import simply gathers type information, but doesn't generate wrappers. Alternatively, you could just define Foo as an empty class in the SWIG interface or use warning suppression .

Note: typedef-names can be used as base classes. For example:

class Foo {
...
};

typedef Foo FooObj;
class Bar : public FooObj {     // Ok.  Base class is Foo
...
};

Similarly, typedef allows unnamed structures to be used as base classes. For example:

typedef struct {
  ...
} Foo;

class Bar : public Foo {    // Ok. 
...
};

Compatibility Note: Starting in version 1.3.7, SWIG only generates low-level accessor wrappers for the declarations that are actually defined in each class. This differs from SWIG1.1 which used to inherit all of the declarations defined in base classes and regenerate specialized accessor functions such as Circle_x_get(), Square_x_get(), Circle_set_location(), and Square_set_location(). This behavior resulted in huge amounts of replicated code for large class hierarchies and made it awkward to build applications spread across multiple modules (since accessor functions are duplicated in every single module). It is also unnecessary to have such wrappers when advanced features like proxy classes are used. Note: Further optimizations are enabled when using the -fvirtual option, which avoids the regenerating of wrapper functions for virtual members that are already defined in a base class.

6.13 A brief discussion of multiple inheritance, pointers, and type checking

When a target scripting language refers to a C++ object, it normally uses a tagged pointer object that contains both the value of the pointer and a type string. For example, in Tcl, a C++ pointer might be encoded as a string like this:

_808fea88_p_Circle

A somewhat common question is whether or not the type-tag could be safely removed from the pointer. For instance, to get better performance, could you strip all type tags and just use simple integers instead?

In general, the answer to this question is no. In the wrappers, all pointers are converted into a common data representation in the target language. Typically this is the equivalent of casting a pointer to void *. This means that any C++ type information associated with the pointer is lost in the conversion.

The problem with losing type information is that it is needed to properly support many advanced C++ features--especially multiple inheritance. For example, suppose you had code like this:

class A {
public:
  int x;
};

class B {
public:
  int y;
};

class C : public A, public B {
};

int A_function(A *a) {
  return a->x;
}

int B_function(B *b) {
  return b->y;
}

Now, consider the following code that uses void *.

C *c = new C();
void *p = (void *) c;
...
int x = A_function((A *) p);
int y = B_function((B *) p);

In this code, both A_function() and B_function() may legally accept an object of type C * (via inheritance). However, one of the functions will always return the wrong result when used as shown. The reason for this is that even though p points to an object of type C, the casting operation doesn't work like you would expect. Internally, this has to do with the data representation of C. With multiple inheritance, the data from each base class is stacked together. For example:

             ------------    <--- (C *),  (A *)
            |     A      |
            |------------|   <--- (B *)
            |     B      |
             ------------   

Because of this stacking, a pointer of type C * may change value when it is converted to a A * or B *. However, this adjustment does not occur if you are converting from a void *.

The use of type tags marks all pointers with the real type of the underlying object. This extra information is then used by SWIG generated wrappers to correctly cast pointer values under inheritance (avoiding the above problem).

Some of the language modules are able to solve the problem by storing multiple instances of the pointer, for example, A *, in the A proxy class as well as C * in the C proxy class. The correct cast can then be made by choosing the correct void * pointer to use and is guaranteed to work as the cast to a void pointer and back to the same type does not lose any type information:

C *c = new C();
void *p = (void *) c;
void *pA = (void *) c;
void *pB = (void *) c;
...
int x = A_function((A *) pA);
int y = B_function((B *) pB);

In practice, the pointer is held as an integral number in the target language proxy class.

6.14 Default arguments

SWIG will wrap all types of functions that have default arguments. For example member functions:

class Foo {
public:
  void bar(int x, int y = 3, int z = 4);
};

SWIG handles default arguments by generating an extra overloaded method for each defaulted argument. SWIG is effectively handling methods with default arguments as if it was wrapping the equivalent overloaded methods. Thus for the example above, it is as if we had instead given the following to SWIG:

class Foo {
public:
  void bar(int x, int y, int z);
  void bar(int x, int y);
  void bar(int x);
};

The wrappers produced are exactly the same as if the above code was instead fed into SWIG. Details of this are covered in the next section Overloaded functions and methods . This approach allows SWIG to wrap all possible default arguments, but can be verbose. For example if a method has ten default arguments, then eleven wrapper methods are generated.

Please see the Features and default arguments section for more information on using %feature with functions with default arguments. The Renaming and ambiguity resolution section also deals with using %rename and %ignore on methods with default arguments. If you are writing your own typemaps for types used in methods with default arguments, you may also need to write a typecheck typemap. See the Typemaps and overloading section for details or otherwise use the compactdefaultargs feature flag as mentioned below.

For C# please see the C# named and optional arguments section for information on special handling of default arguments available specifically for C#.

Compatibility note: 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 so that the method being wrapped was then called with all the arguments specified. If the size of the wrappers are a concern then this approach to wrapping methods with default arguments can be re-activated by using the compactdefaultargs feature flag.

%feature("compactdefaultargs") Foo::bar;
class Foo {
public:
  void bar(int x, int y = 3, int z = 4);
};

This is great for reducing the size of the wrappers, but the caveat is it does not work for the statically typed languages, 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:

class Foo {
private:
  static const int spam;
public:
  void bar(int x, int y = spam);   // Won't work with %feature("compactdefaultargs") -
                                   // private default value
};

This produces uncompilable wrapper code because default values in C++ are evaluated in the same scope as the member function whereas SWIG evaluates them in the scope of a wrapper function (meaning that the values have to be public).

The compactdefaultargs feature is automatically turned on when wrapping C code with default arguments. Some target languages will also automatically turn on this feature if the keyword arguments feature (kwargs) is specified for either C or C++ functions, and the target language supports kwargs, the compactdefaultargs feature is also automatically turned on. Keyword arguments are a language feature of some scripting languages, for example Ruby and Python. SWIG is unable to support kwargs when wrapping overloaded methods, so the default approach cannot be used.

6.15 Overloaded functions and methods

In many language modules, SWIG provides partial support for overloaded functions, methods, and constructors. For example, if you supply SWIG with overloaded functions like this:

void foo(int x) {
  printf("x is %d\n", x);
}
void foo(char *x) {
  printf("x is '%s'\n", x);
}

The function is used in a completely natural way. For example:

>>> foo(3)
x is 3
>>> foo("hello")
x is 'hello'
>>>

Overloading works in a similar manner for methods and constructors. For example if you have this code,

class Foo {
public:
  Foo();
  Foo(const Foo &);   // Copy constructor
  void bar(int x);
  void bar(char *s, int y);
};

it might be used like this

>>> f = Foo()          # Create a Foo
>>> f.bar(3)
>>> g = Foo(f)         # Copy Foo
>>> f.bar("hello", 2)

6.15.1 Dispatch function generation

The implementation of overloaded functions and methods is somewhat complicated due to the dynamic nature of scripting languages. Unlike C++, which binds overloaded methods at compile time, SWIG must determine the proper function as a runtime check for scripting language targets. This check is further complicated by the typeless nature of certain scripting languages. For instance, in Tcl, all types are simply strings. Therefore, if you have two overloaded functions like this,

void foo(char *x);
void foo(int x);

the order in which the arguments are checked plays a rather critical role.

For statically typed languages, SWIG uses the language's method overloading mechanism. To implement overloading for the scripting languages, SWIG generates a dispatch function that checks the number of passed arguments and their types. To create this function, SWIG first examines all of the overloaded methods and ranks them according to the following rules:

1. Number of required arguments. Methods are sorted by increasing number of required arguments.

2. Argument type precedence. All C++ datatypes are assigned a numeric type precedence value (which is determined by the language module).

   Type              Precedence
   ----------------  ----------
   TYPE *            0     (High)
   void *            20
   Integers          40
   Floating point    60
   char              80
   Strings           100   (Low)
   

   Using these precedence values, overloaded methods with the same number of required arguments are sorted in increased order of precedence values.

This may sound very confusing, but an example will help. Consider the following collection of overloaded methods:

void foo(double);
void foo(int);
void foo(Bar *);
void foo();
void foo(int x, int y, int z, int w);
void foo(int x, int y, int z = 3);
void foo(double x, double y);
void foo(double x, Bar *z);

The first rule simply ranks the functions by required argument count. This would produce the following list:

rank
-----
[0]   foo()
[1]   foo(double);
[2]   foo(int);
[3]   foo(Bar *);
[4]   foo(int x, int y, int z = 3);
[5]   foo(double x, double y)
[6]   foo(double x, Bar *z)
[7]   foo(int x, int y, int z, int w);

The second rule, simply refines the ranking by looking at argument type precedence values.

rank
-----
[0]   foo()
[1]   foo(Bar *);
[2]   foo(int);
[3]   foo(double);
[4]   foo(int x, int y, int z = 3);
[5]   foo(double x, Bar *z)
[6]   foo(double x, double y)
[7]   foo(int x, int y, int z, int w);

Finally, to generate the dispatch function, the arguments passed to an overloaded method are simply checked in the same order as they appear in this ranking.

If you're still confused, don't worry about it---SWIG is probably doing the right thing.

6.15.2 Ambiguity in overloading

Regrettably, SWIG is not able to support every possible use of valid C++ overloading. Consider the following example:

void foo(int x);
void foo(long x);

In C++, this is perfectly legal. However, in a scripting language, there is generally only one kind of integer object. Therefore, which one of these functions do you pick? Clearly, there is no way to truly make a distinction just by looking at the value of the integer itself ( int and long may even be the same precision). Therefore, when SWIG encounters this situation, it may generate a warning message like this for scripting languages:

example.i:4: Warning 509: Overloaded method foo(long) effectively ignored,
example.i:3: Warning 509: as it is shadowed by foo(int).

or for statically typed languages like Java:

example.i:4: Warning 516: Overloaded method foo(long) ignored,
example.i:3: Warning 516: using foo(int) instead.

This means that the second overloaded function will be inaccessible from a scripting interface or the method won't be wrapped at all. This is done as SWIG does not know how to disambiguate it from an earlier method.

Ambiguity problems are known to arise in the following situations:

• Integer conversions. Datatypes such as int, long, and short cannot be disambiguated in some languages. Shown above.
• Floating point conversion. float and double can not be disambiguated in some languages.
• Pointers and references. For example, Foo * and Foo & .
• Pointers and arrays. For example, Foo * and Foo [4] .
• Pointers and instances. For example, Foo and Foo * . Note: SWIG converts all instances to pointers.
• Qualifiers. For example, const Foo * and Foo *.
• Default vs. non default arguments. For example, foo(int a, int b) and foo(int a, int b = 3).

When an ambiguity arises, methods are checked in the same order as they appear in the interface file. Therefore, earlier methods will shadow methods that appear later.

When wrapping an overloaded function, there is a chance that you will get a warning message like this:

example.i:3: Warning 467: Overloaded foo(int) not supported (incomplete type checking rule - 
no precedence level in typecheck typemap for 'int').

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 SWIG bug tracking database if this is due to one of the typemaps supplied with SWIG.

If you get an error message such as the following,

foo.i:6. Overloaded declaration ignored.  Spam::foo(double )
foo.i:5. Previous declaration is Spam::foo(int )
foo.i:7. Overloaded declaration ignored.  Spam::foo(Bar *, Spam *, int )
foo.i:5. Previous declaration is Spam::foo(int )

it means that the target language module has not yet implemented support for overloaded functions and methods. The only way to fix the problem is to read the next section.

6.15.3 Renaming and ambiguity resolution

If an ambiguity in overload resolution occurs or if a module doesn't allow overloading, there are a few strategies for dealing with the problem. First, you can tell SWIG to ignore one of the methods. This is easy---simply use the %ignore directive. For example:

%ignore foo(long);

void foo(int);
void foo(long);       // Ignored.  Oh well.

The other alternative is to rename one of the methods. This can be done using %rename. For example:

%rename("foo_short") foo(short);
%rename(foo_long) foo(long);

void foo(int);
void foo(short);      // Accessed as foo_short()
void foo(long);       // Accessed as foo_long()

Note that the quotes around the new name are optional, however, should the new name be a C/C++ keyword they would be essential in order to avoid a parsing error. The %ignore and %rename directives are both rather powerful in their ability to match declarations. When used in their simple form, they apply to both global functions and methods. For example:

/* Forward renaming declarations */
%rename(foo_i) foo(int); 
%rename(foo_d) foo(double);
...
void foo(int);           // Becomes 'foo_i'
void foo(char *c);       // Stays 'foo' (not renamed)

class Spam {
public:
  void foo(int);      // Becomes 'foo_i'
  void foo(double);   // Becomes 'foo_d'
  ...
};

If you only want the renaming to apply to a certain scope, the C++ scope resolution operator (::) can be used. For example:

%rename(foo_i) ::foo(int);      // Only rename foo(int) in the global scope.
                                // (will not rename class members)

%rename(foo_i) Spam::foo(int);  // Only rename foo(int) in class Spam

When a renaming operator is applied to a class as in Spam::foo(int), it is applied to that class and all derived classes. This can be used to apply a consistent renaming across an entire class hierarchy with only a few declarations. For example:

%rename(foo_i) Spam::foo(int);
%rename(foo_d) Spam::foo(double);

class Spam {
public:
  virtual void foo(int);      // Renamed to foo_i
  virtual void foo(double);   // Renamed to foo_d
  ...
};

class Bar : public Spam {
public:
  virtual void foo(int);      // Renamed to foo_i
  virtual void foo(double);   // Renamed to foo_d
  ...
};

class Grok : public Bar {
public:
  virtual void foo(int);      // Renamed to foo_i
  virtual void foo(double);   // Renamed to foo_d
  ...
};

It is also possible to include %rename specifications in the class definition itself. For example:

class Spam {
  %rename(foo_i) foo(int);
  %rename(foo_d) foo(double);
public:
  virtual void foo(int);      // Renamed to foo_i
  virtual void foo(double);   // Renamed to foo_d
  ...
};

class Bar : public Spam {
public:
  virtual void foo(int);      // Renamed to foo_i
  virtual void foo(double);   // Renamed to foo_d
...
};

In this case, the %rename directives still get applied across the entire inheritance hierarchy, but it's no longer necessary to explicitly specify the class prefix Spam::.

A special form of %rename can be used to apply a renaming just to class members (of all classes):

%rename(foo_i) *::foo(int);   // Only rename foo(int) if it appears in a class.

Note: the *:: 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 swig-devel mailing list.

Although this discussion has primarily focused on %rename all of the same rules also apply to %ignore. For example:

%ignore foo(double);          // Ignore all foo(double)
%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

When applied to a base class, %ignore forces all definitions in derived classes to disappear. For example, %ignore Spam::foo(double) will eliminate foo(double) in Spam and all classes derived from Spam.

Notes on %rename and %ignore:

• Since, the %rename declaration is used to declare a renaming in advance, it can be placed at the start of an interface file. This makes it possible to apply a consistent name resolution without having to modify header files. For example:

  %module foo
  
  /* Rename these overloaded functions */
  %rename(foo_i) foo(int); 
  %rename(foo_d) foo(double);
  
  %include "header.h"
  

• The scope qualifier (::) can also be used on simple names. For example:

  %rename(bar) ::foo;       // Rename foo to bar in global scope only
  %rename(bar) Spam::foo;   // Rename foo to bar in class Spam only
  %rename(bar) *::foo;      // Rename foo in classes only
  

• Name matching tries to find the most specific match that is defined. A qualified name such as Spam::foo always has higher precedence than an unqualified name foo. Spam::foo has higher precedence than *::foo and *::foo has higher precedence than foo. A parameterized name has higher precedence than an unparameterized name within the same scope level. However, an unparameterized name with a scope qualifier has higher precedence than a parameterized name in global scope (e.g., a renaming of Spam::foo takes precedence over a renaming of foo(int) ).

• Renaming a class member, using an unparameterized but qualified name, such as Spam::foo, 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 using declarations, see Using declarations and inheritance. For example:

  %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
  };
  

• The order in which %rename directives are defined does not matter as long as they appear before the declarations to be renamed. Thus, there is no difference between saying:

  %rename(bar) foo;
  %rename(foo_i) Spam::foo(int);
  %rename(Foo) Spam::foo;
  

  and this

  %rename(Foo) Spam::foo;
  %rename(bar) foo;
  %rename(foo_i) Spam::foo(int);
  

  (the declarations are not stored in a linked list and order has no importance). Of course, a repeated %rename directive will change the setting for a previous %rename directive if exactly the same name, scope, and parameters are supplied.

• For multiple inheritance where renaming rules are defined for multiple base classes, the first renaming rule found on a depth-first traversal of the class hierarchy is used.

• The name matching rules strictly follow member qualifier rules. For example, if you have a class and member with a member that is const qualified like this:

  class Spam {
  public:
    ...
    void bar() const;
    ...
  };
  

  the declaration

  %rename(name) Spam::bar();
  

  will not apply as there is no unqualified member bar(). The following will apply the rename as the qualifier matches correctly:

  %rename(name) Spam::bar() const;
  

  Similarly for combinations of cv-qualifiers and ref-qualifiers, all the qualifiers must be specified to match correctly:

  %rename(name) Jam::bar();          // will not match
  %rename(name) Jam::bar() &;        // will not match
  %rename(name) Jam::bar() const;    // will not match
  %rename(name) Jam::bar() const &;  // ok, will match
  
  class Jam {
  public:
    ...
    void bar() const &;
    ...
  };
  

  An often overlooked C++ feature is that classes can define two different overloaded members that differ only in their qualifiers, like this:

  class Spam {
  public:
    ...
    void bar();         // Unqualified member
    void bar() const;   // Qualified member
    ...
  };
  

  %rename can then be used to target each of the overloaded methods individually. For example we can give them separate names in the target language:

  %rename(name1) Spam::bar();
  %rename(name2) Spam::bar() const;
  

  Similarly, if you merely wanted to ignore one of the declarations, use %ignore with the full qualifier. For example, the following directive would tell SWIG to ignore the const version of bar() above:

  %ignore Spam::bar() const;   // Ignore bar() const, but leave other bar() alone
  

• Currently no resolution is performed in order to match function parameters. This means function parameter types must match exactly. For example, namespace qualifiers and typedefs will not work. The following usage of typedefs demonstrates this:

  typedef int Integer;
  
  %rename(foo_i) foo(int);
  
  class Spam {
  public:
    void foo(Integer);  // Stays 'foo' (not renamed)
  };
  class Ham {
  public:
    void foo(int);      // Renamed to foo_i
  };
  

• The name matching rules also use default arguments for finer control when wrapping methods that have default arguments. Recall that methods with default arguments are wrapped as if the equivalent overloaded methods had been parsed (Default arguments section). Let's consider the following example class:

  class Spam {
  public:
    ...
    void bar(int i=-1, double d=0.0);
    ...
  };
  

  The following %rename will match exactly and apply to all the target language overloaded methods because the declaration with the default arguments exactly matches the wrapped method:

  %rename(newbar) Spam::bar(int i=-1, double d=0.0);
  

  The C++ method can then be called from the target language with the new name no matter how many arguments are specified, for example: newbar(2, 2.0), newbar(2) or newbar(). However, if the %rename does not contain the default arguments:

  %rename(newbar) Spam::bar(int i, double d);
  

  then only one of the three equivalent overloaded methods will be renamed and wrapped as if SWIG parsed:

  void Spam::newbar(int i, double d);
  void Spam::bar(int i);
  void Spam::bar();
  

  The C++ method must then be called from the target language with the new name newbar(2, 2.0) when both arguments are supplied or with the original name as bar(2) (one argument) or bar() (no arguments).

  In fact it is possible to use %rename on the equivalent overloaded methods, to rename all the equivalent overloaded methods:

  %rename(bar_2args)   Spam::bar(int i, double d);
  %rename(bar_1arg)    Spam::bar(int i);
  %rename(bar_default) Spam::bar();
  

  Similarly, the extra overloaded methods can be selectively ignored using %ignore.

  Compatibility note: The %rename directive introduced the default argument matching rules in SWIG-1.3.23 at the same time as the changes to wrapping methods with default arguments was introduced.

6.15.4 Comments on overloading

Support for overloaded methods was first added in SWIG-1.3.14. The implementation is somewhat unusual when compared to similar tools. For instance, the order in which declarations appear is largely irrelevant in SWIG. Furthermore, SWIG does not rely upon trial execution or exception handling to figure out which method to invoke.

Internally, the overloading mechanism is completely configurable by the target language module. Therefore, the degree of overloading support may vary from language to language. As a general rule, statically typed languages like Java are able to provide more support than dynamically typed languages like Perl, Python, Ruby, and Tcl.

6.16 Overloaded operators

C++ overloaded operator declarations can be wrapped. For example, consider a class like this:

class Complex {
private:
  double rpart, ipart;
public:
  Complex(double r = 0, double i = 0) : rpart(r), ipart(i) { }
  Complex(const Complex &c) : rpart(c.rpart), ipart(c.ipart) { }
  Complex &operator=(const Complex &c) {
    rpart = c.rpart;
    ipart = c.ipart;
    return *this;
  }
  Complex operator+(const Complex &c) const {
    return Complex(rpart+c.rpart, ipart+c.ipart);
  }
  Complex operator-(const Complex &c) const {
    return Complex(rpart-c.rpart, ipart-c.ipart);
  }
  Complex operator*(const Complex &c) const {
    return Complex(rpart*c.rpart - ipart*c.ipart,
                   rpart*c.ipart + c.rpart*ipart);
  }
  Complex operator-() const {
    return Complex(-rpart, -ipart);
  }
  double re() const { return rpart; }
  double im() const { return ipart; }
};

When operator declarations appear, they are handled in exactly the same manner as regular methods. However, the names of these methods are set to strings like "operator +" or "operator -". The problem with these names is that they are illegal identifiers in most scripting languages. For instance, you can't just create a method called "operator +" in Python--there won't be any way to call it.

Some language modules already know how to automatically handle certain operators (mapping them into operators in the target language). However, the underlying implementation of this is really managed in a very general way using the %rename directive. For example, in Python a declaration similar to this is used:

%rename(__add__) Complex::operator+;

This binds the + operator to a method called __add__ (which is conveniently the same name used to implement the Python + operator). Internally, the generated wrapper code for a wrapped operator will look something like this pseudocode:

_wrap_Complex___add__(args) {
  ... get args ...
  obj->operator+(args);
  ...
}

When used in the target language, it may now be possible to use the overloaded operator normally. For example:

>>> a = Complex(3, 4)
>>> b = Complex(5, 2)
>>> c = a + b           # Invokes __add__ method

It is important to realize that there is nothing magical happening here. The %rename directive really only picks a valid method name. If you wrote this:

%rename(add) operator+;

The resulting scripting interface might work like this:

a = Complex(3, 4)
b = Complex(5, 2)
c = a.add(b)      # Call a.operator+(b)

All of the techniques described to deal with overloaded functions also apply to operators. For example:

%ignore Complex::operator=;             // Ignore = in class Complex
%ignore *::operator=;                   // Ignore = in all classes
%ignore operator=;                      // Ignore = everywhere.

%rename(__sub__) Complex::operator-; 
%rename(__neg__) Complex::operator-();  // Unary - 

The last part of this example illustrates how multiple definitions of the operator- method might be handled.

Handling operators in this manner is mostly straightforward. However, there are a few subtle issues to keep in mind:

• In C++, it is fairly common to define different versions of the operators to account for different types. For example, a class might also include a friend function like this:

  class Complex {
  public:
    friend Complex operator+(Complex &, double);
  };
  Complex operator+(Complex &, double);
  

  SWIG simply ignores all friend declarations. Furthermore, it doesn't know how to associate the associated operator+ with the class (because it's not a member of the class).

  It's still possible to make a wrapper for this operator, but you'll have to handle it like a normal function. For example:

  %rename(add_complex_double) operator+(Complex &, double);
  

• Certain operators are ignored by default. For instance, new and delete operators are ignored as well as conversion and index operators. A warning such as the one below is shown:

  example.i:12: Warning 503: Can't wrap 'operator []' unless renamed to a valid identifier.
  

• The index operator, operator[], is particularly difficult to overload due to differences in C++ implementations. Specifically, the get and set operators in other languages typically are separated into two methods such that additional logic can be packed into the operations; C# uses this[type key] { get { ... } set { ... }}, Python uses __getitem__ and __setitem__, etc. In C++ if the return type of operator[] is a reference and the method is const, it is often indicative of the setter, and the getter is usually a const function return an object by value. In the absence of any hard and fast rules and the fact that there may be multiple index operators, it is up to the user to choose the getter and setter to use by using %rename as shown earlier.

• The semantics of certain C++ operators may not match those in the target language.

6.17 Class extension

New methods can be added to a class using the %extend directive. This directive is primarily used in conjunction with proxy classes to add additional functionality to an existing class. For example :

%module vector
%{
#include "vector.h"
%}

class Vector {
public:
  double x, y, z;
  Vector();
  ~Vector();
  ... bunch of C++ methods ...
  %extend {
    char *__str__() {
      static char temp[256];
      sprintf(temp, "[ %g, %g, %g ]", $self->x, $self->y, $self->z);
      return &temp[0];
    }
  }
};

This code adds a __str__ method to our class for producing a string representation of the object. In Python, such a method would allow us to print the value of an object using the print command.

>>>
>>> v = Vector();
>>> v.x = 3
>>> v.y = 4
>>> v.z = 0
>>> print(v)
[ 3.0, 4.0, 0.0 ]
>>>

The C++ 'this' pointer is often needed to access member variables, methods etc. The $self special variable should be used wherever you could use 'this'. The example above demonstrates this for accessing member variables. Note that the members dereferenced by $self must be public members as the code is ultimately generated into a global function and so will not have any access to non-public members. The implicit 'this' pointer that is present in C++ methods is not present in %extend methods. In order to access anything in the extended class or its base class, an explicit 'this' is required. The following example shows how one could access base class members:

struct Base {
  virtual void method(int v) {
    ...
  }
  int value;
};
struct Derived : Base {
};
%extend Derived {
  virtual void method(int v) {
    $self->Base::method(v); // akin to this->Base::method(v);
    $self->value = v;       // akin to this->value = v;
    ...
  }
}

The following special variables are expanded if used within a %extend block: $name, $symname, $overname, $decl, $fulldecl, $parentclassname and $parentclasssymname. The Special variables section provides more information each of these special variables.

The %extend directive follows all of the same conventions as its use with C structures. Please refer to the Adding member functions to C structures section for further details.

6.17.1 Replacing class methods

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 %extend and %ignore directives covered earlier. Here is an example to replace the MyClass::mymethod():

%extend MyClass {
  void mymethod() {
    std::cout << "swig mymethod" << std::endl;
  }
}

%ignore MyClass::mymethod;

%inline %{
class MyClass {
public:
  void mymethod() {
    std::cout << "class mymethod" << std::endl;
  }
};
%}

Or if your code organization makes more sense to put the %extend after the class definition, you would need the following:

%rename("") MyClass::mymethod; // unignores the method

before the %extend or SWIG will continue to ignore mymethod(), even in an %extend.

Note that you can call the class method from the method in %extend, just use self->mymethod() and it will call the class method, not the one in %extend.

6.18 Templates

Template type names may appear anywhere a type is expected in an interface file. For example:

void foo(vector<int> *a, int n);
void bar(std::array<int, 100> *x);

There are some restrictions on the use of non-type arguments. Simple literals are supported, and so are most constant expressions. However, there are some limitations on the use of '<' and '>' in constant expressions (but note that '<=' and '>=' are fully supported). For example:

void bar(std::array<int, 100> *x);                // OK
void bar(std::array<int, 2*50> *x);               // OK
void bar(std::array<int, (1<2 ? 100 : 50)> *x)    // OK
void bar(std::array<int, 1<2 ? 100 : 50> *x)      // Not supported
void bar(std::array<int, (2>1 ? 100 : 50)> *x)    // Not supported

The type system is smart enough to figure out clever games you might try to play with typedef. For instance, consider this code:

typedef int Integer;
void foo(vector<int> *x, vector<Integer> *y);

In this case, vector<Integer> is exactly the same type as vector<int>. The wrapper for foo() will accept either variant.

6.18.1 The %template directive

There are a couple of important points about template wrapping. First, a bare C++ template does not define any sort of runnable object-code for which SWIG can normally create a wrapper. Therefore, in order to wrap a template, you need to give SWIG information about a particular template instantiation (e.g., vector<int>, array<double>, etc.). Second, an instantiation name such as vector<int> is generally not a valid identifier name in most target languages. Thus, you will need to give the template instantiation a more suitable name such as intvector.

To illustrate, consider the following class template definition:

template<class T> class List {
private:
  T *data;
  int nitems;
  int maxitems;
public:
  List(int max) {
    data = new T [max];
    nitems = 0;
    maxitems = max;
  }
  ~List() {
    delete [] data;
  };
  void append(T obj) {
    if (nitems < maxitems) {
      data[nitems++] = obj;
    }
  }
  int length() {
    return nitems;
  }
  T get(int n) {
    return data[n];
  }
};

By itself, this class template is useless--SWIG simply ignores it because it doesn't know how to generate any code unless a definition of T is provided. The %template directive is required to instantiate the template for use in a target language. The directive requires an identifier name for use in the target language plus the template for instantiation. The example below instantiates List<int> for use as a class named intList:

%template(intList) List<int>;

The instantiation expands the template code as a C++ compiler would do and then makes it available under the given identifier name. Essentially it is the same as wrapping the following concept code where the class template definition has T expanded to int (note that this is not entirely valid syntax):

%rename(intList) List<int>;       // Rename to a suitable identifier
class List<int> {
private:
  int *data;
  int nitems;
  int maxitems;
public:
  List(int max);
  ~List();
  void append(int obj);
  int length();
  int get(int n);
};

The argument to %template() is the name of the instantiation in the target language. The name you choose should not conflict with any other declarations in the interface file with one exception---it is okay for the template name to match that of a typedef declaration. For example:

%template(intList) List<int>;
...
typedef List<int> intList;    // OK

The %template directive must always appear after the definition of the template to be expanded, so the following will work:

template<class T> class List { ... };
%template(intList) List<int>;

but if %template is used before the template definition, such as:

%template(intList) List<int>;
template<class T> class List { ... };

SWIG will generate an error:

example.i:3: Error: Template 'List' undefined.

Since the type system knows how to handle typedef, it is generally not necessary to instantiate different versions of a template for typenames that are equivalent. For instance, consider this code:

%template(intList) List<int>;
typedef int Integer;
...
void foo(List<Integer> *x);

In this case, List<Integer> is exactly the same type as List<int>. Any use of List<Integer> is mapped back to the instantiation of List<int> created earlier. Therefore, it is not correct to instantiate a new class for the type Integer. An attempt to do so such as:

%template(intList) List<int>;
%template(IntegerList) List<Integer>;   // Ignored

will result in the duplicate instantiation being ignored with a warning:

example.i:48: Warning 404: Duplicate template instantiation of 'List< Integer >' with name 'IntegerList' ignored,
example.i:47: Warning 404: previous instantiation of 'List< int >' with name 'intList'.

The template provided to %template for instantiation must be the actual template and not a typedef to a template.

typedef List<int> ListOfInt;

%template(intList) List<int>; // ok
%template(intList) ListOfInt; // illegal - Syntax error

6.18.2 Function templates

SWIG can also generate wrappers for function templates using a similar technique to that shown above for class templates. For example:

// Function template
template<class T> T max(T a, T b) { return a > b ? a : b; }

// Make some different versions of this function
%template(maxint) max<int>;
%template(maxdouble) max<double>;

In this case, maxint and maxdouble become unique names for specific instantiations of the function.

SWIG even supports overloaded templated functions. As usual the %template directive is used to wrap templated functions. For example:

template<class T> void foo(T x) { };
template<class T> void foo(T x, T y) { };

%template(foo) foo<int>;

This will generate two overloaded wrapper methods, the first will take a single integer as an argument and the second will take two integer arguments.

6.18.3 Default template arguments

The number of arguments supplied to %template should match that in the original template definition. Template default arguments are supported. For example:

template <typename T, int max=100> class vector {
...
};

%template(intvec) vector<int>;            // OK
%template(vec1000) vector<int, 1000>;     // OK

The %template directive should not be used to wrap the same 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:

%template(vec) vector<double>;            // OK
%template(vec100) vector<double, 100>;    // Ignored

will warn:

example.i:59: Warning 404: Duplicate template instantiation of 'vector< double,100 >' with name 'vec100' ignored,
example.i:58: Warning 404: previous instantiation of 'vector< double >' with name 'vec'.

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.

Compatibility Note: Versions prior to SWIG-4.2.0 would sometimes not detect and prevent duplicate instantiations, such as when the wrapped name was different.

6.18.4 Template base classes

When a template is instantiated using %template, information about that class is saved by SWIG and used elsewhere in the program. For example, if you wrote code like this,

...
%template(intList) List<int>;
...
class UltraList : public List<int> {
  ...
};

then SWIG knows that List<int> was already wrapped as a class called intList and arranges to handle the inheritance correctly. If, on the other hand, nothing is known about List<int> , you will get a warning message similar to this:

example.h:42: Warning 401. Nothing known about class 'List< int >'. Ignored. 
example.h:42: Warning 401. Maybe you forgot to instantiate 'List< int >' using %template. 

If a class template inherits from another class template, you need to make sure that base classes are instantiated before derived classes. For example:

template<class T> class Foo {
...
};

template<class T> class Bar : public Foo<T> {
...
};

// Instantiate base classes first 
%template(intFoo) Foo<int>;
%template(doubleFoo) Foo<double>;

// Now instantiate derived classes
%template(intBar) Bar<int>;
%template(doubleBar) Bar<double>;

The order is important since SWIG uses the instantiation names to properly set up the inheritance hierarchy in the resulting wrapper 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.

If you have to instantiate a lot of different classes for many different types, you might consider writing a SWIG macro. For example:

%define TEMPLATE_WRAP(prefix, T...) 
%template(prefix ## Foo) Foo<T >;
%template(prefix ## Bar) Bar<T >;
...
%enddef

TEMPLATE_WRAP(int, int)
TEMPLATE_WRAP(double, double)
TEMPLATE_WRAP(String, char *)
TEMPLATE_WRAP(PairStringInt, std::pair<string, int>)
...

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.

6.18.5 Empty template instantiation

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 %template(), that is the empty template instantiation that omits providing a name. For example:

template<typename T> struct Traits {
  typedef T type;
};
%}

%template() Traits<int>; // instantiate Traits<int>, but don't wrap it

void traitor(Traits<int>::type val);

Without a template instantiation, SWIG does not know that the first parameter to the traitor 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 Traits class.

Duplicate template instantiation are not allowed, as described in the Default template arguments 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.

Unlike template class instantiations, template function instantiations must have a name. Consider the following:

template<class T> T tfunc(T x) { };
%template() tfunc<double>;

The empty template instantiation will be ignored with:

example.i:9: Warning 519: %template() contains no name. Template method ignored: tfunc< double >(double)

6.18.6 Template specialization

The SWIG template mechanism does support specialization. For instance, if you define a class like this,

template<> class List<int> {
private:
  int *data;
  int nitems;
  int maxitems;
public:
  List(int max);
  ~List();
  void append(int obj);
  int length();
  int get(int n);
};

then SWIG will use this code whenever the user expands List<int> . In practice, this may have very little effect on the underlying wrapper code since specialization is often used to provide slightly modified method bodies (which are ignored by SWIG). However, special SWIG directives such as %typemap, %extend, and so forth can be attached to a specialization to provide customization for specific types.

Partial template specialization is partially supported by SWIG. For example, this code defines a template that is applied when the template argument is a pointer.

template<class T> class List<T*> {
private:
  T *data;
  int nitems;
  int maxitems;
public:
  List(int max);
  ~List();
  void append(T obj);
  int length();
  T get(int n);
};

SWIG supports both template explicit specialization and partial specialization. Consider:

template<class T1, class T2> class Foo { };                     // (1) primary template
template<>                   class Foo<double *, int *> { };    // (2) explicit specialization
template<class T1, class T2> class Foo<T1, T2 *> { };           // (3) partial specialization

SWIG is able to properly match explicit instantiations:

Foo<double *, int *>     // explicit specialization matching (2)

SWIG implements template argument deduction so that the following partial specialization examples work just like they would with a C++ compiler:

Foo<int *, int *>        // partial specialization matching (3)
Foo<int *, const int *>  // partial specialization matching (3)
Foo<int *, int **>       // partial specialization matching (3)

6.18.7 Member templates

Member templates are supported. The underlying principle is the same as for normal templates--SWIG can't create a wrapper unless you provide more information about types. For example, a class with a member function template might look like this:

class Foo {
public:
  template<class T> void bar(T x, T y) { ... };
  ...
};

To expand the template, simply use %template inside the class.

class Foo {
public:
  template<class T> void bar(T x, T y) { ... };
  ...
  %template(barint)    bar<int>;
  %template(bardouble) bar<double>;
};

Or, if you want to leave the original class definition alone, just do this:

class Foo {
public:
  template<class T> void bar(T x, T y) { ... };
  ...
};
...
%extend Foo {
  %template(barint)    bar<int>;
  %template(bardouble) bar<double>;
};

or simply

class Foo {
public:
  template<class T> void bar(T x, T y) { ... };
  ...
};
...

%template(bari) Foo::bar<int>;
%template(bard) Foo::bar<double>;

In this case, the %extend directive is not needed, and %template does exactly the same job, i.e., it adds two new methods to the Foo class.

Now, if your target language supports overloading, you can even try

%template(bar) Foo::bar<int>;
%template(bar) Foo::bar<double>;

and since the two new wrapped methods have the same name 'bar', they will be overloaded, and when called, the correct method will be dispatched depending on the argument type.

When used with members, the %template directive may be placed in another class template. Here is a slightly perverse example:

// A template
template<class T> class Foo {
public:
  // A member template
  template<class S> T bar(S x, S y) { ... };
  ...
};

// Expand a few member templates
%extend Foo {
  %template(bari) bar<int>;
  %template(bard) bar<double>;
}

// Create some wrappers for the template
%template(Fooi) Foo<int>;
%template(Food) Foo<double>;

Miraculously, you will find that each expansion of Foo has member functions bari() and bard() added.

A common use of member templates is to define constructors for copies and conversions. For example:

template<class T1, class T2> struct pair {
  T1 first;
  T2 second;
  pair() : first(T1()), second(T2()) { }
  pair(const T1 &x, const T2 &y) : first(x), second(y) { }
  template<class U1, class U2> pair(const pair<U1, U2> &x)
                                       : first(x.first), second(x.second) { }
};

This declaration is perfectly acceptable to SWIG, but the constructor template will be ignored unless you explicitly expand it. To do that, you could expand a few versions of the constructor in the class template itself. For example:

%extend pair {
  %template(pair) pair<T1, T2>;        // Generate default copy constructor
};

When using %extend in this manner, notice how you can still use the template parameters in the original template definition.

Alternatively, you could expand the constructor template in selected instantiations. For example:

// Instantiate a few versions
%template(pairii) pair<int, int>;
%template(pairdd) pair<double, double>;

// Create a default constructor only 
%extend pair<int, int> {
  %template(paird) pair<int, int>;         // Default constructor
};

// Create default and conversion constructors 
%extend pair<double, double> {
  %template(paird) pair<double, double>;   // Default constructor
  %template(pairc) pair<int, int>;         // Conversion constructor
};

And if your target language supports overloading, then you can try instead:

// Create default and conversion constructors 
%extend pair<double, double> {
  %template(pair) pair<double, double>;   // Default constructor
  %template(pair) pair<int, int>;         // Conversion constructor
};

In this case, the default and conversion constructors have the same name. Hence, SWIG will overload them and define an unique visible constructor, that will dispatch the proper call depending on the argument type.

6.18.8 Scoping and templates

The %template directive for a class template is the equivalent to an explicit instantiation of a C++ class template. The scope for a valid %template instantiation is the same as the scope required for a valid explicit instantiation of a C++ template. A definition of the template for the explicit instantiation must be in scope where the instantiation is declared and must not be enclosed within a different namespace.

For example, a few %template instantiations and C++ explicit instantiations are shown below:

namespace N {
  template<typename T> class C {};
}

// valid
%template(cin) N::C<int>;
template class N::C<int>;

// valid
namespace N {
  %template(cin) C<int>;
  template class C<int>;
}

// valid
using namespace N;
%template(cin) C<int>;
template class C<int>;

// valid
using N::C;
%template(cin) C<int>;
template class C<int>;

// ill-formed
namespace unrelated {
  using N::C;
  %template(cin) C<int>;
  template class C<int>;
}

// ill-formed
namespace unrelated {
  using namespace N;
  %template(cin) C<int>;
  template class C<int>;
}

// ill-formed
namespace unrelated {
  namespace N {
    %template(cin) C<int>;
    template class C<int>;
  }
}

// ill-formed
namespace unrelated {
  %template(cin) N::C<int>;
  template class N::C<int>;
}

When the scope is incorrect, such as for the ill-formed examples above, an error occurs:

cpp_template_scope.i:34: Error: 'C' resolves to 'N::C' and was incorrectly instantiated
in scope 'unrelated' instead of within scope 'N'.

A note for the C++ standard geeks out there; a valid instantiation is one which conforms to the C++03 standard as C++11 made a change to disallow using declarations and using directives to find a template.

// valid C++03, ill-formed C++11
using N::C;
template class C<int>;

Compatibility Note: Versions prior to SWIG-4.0.0 did not error out with incorrectly scoped %template declarations, but this led to numerous subtle template scope problems.

6.18.9 More on templates

If all of this isn't quite enough and you really want to make someone's head explode, SWIG directives such as %rename, %extend, and %typemap can be included directly in template definitions. For example:

// File : list.h
template<class T> class List {
  ...
public:
  %rename(__getitem__) get(int);
  List(int max);
  ~List();
  ...
  T get(int index);
  %extend {
    char *__str__() {
      /* Make a string representation */
      ...
    }
  }
};

In this example, the extra SWIG directives are propagated to every template instantiation.

It is also possible to separate these declarations from the class template. For example:

%rename(__getitem__) List::get;
%extend List {
  char *__str__() {
    /* Make a string representation */
    ...
  }
  /* Make a copy */
  T *__copy__() {
    return new List<T>(*$self);
  }
};

...
template<class T> class List {
  ...
  public:
  List() { }
  T get(int index);
  ...
};

When %extend is decoupled from the class definition, it is legal to use the same template parameters as provided in the class definition. These are replaced when the template is expanded. In addition, the %extend directive can be used to add additional methods to a specific instantiation. For example:

%template(intList) List<int>;

%extend List<int> {
  void blah() {
    printf("Hey, I'm an List<int>!\n");
  }
};

It is even possible to extend a class via %extend with template methods, for example:

%include <std_string.i>

%inline %{
class ExtendMe {
public:
  template <typename T>
  T do_stuff_impl(int a, T b, double d) {
    return b;
  }
};
%}

%extend ExtendMe {
  template<typename T>
  T do_overloaded_stuff(T b) {
    return $self->do_stuff_impl(0, b, 4.0);
  }
}
%template(do_overloaded_stuff) ExtendMe::do_overloaded_stuff<std::string>;
%template(do_overloaded_stuff) ExtendMe::do_overloaded_stuff<double>;

The wrapped ExtendMe class will then have two (overloaded) methods called do_overloaded_stuff.

Compatibility Note: Extending a class with template methods was added in version 3.0.12

Needless to say, SWIG's template support provides plenty of opportunities to break the universe. That said, an important final point is that SWIG does not perform extensive error checking of templates! Specifically, SWIG does not perform type checking nor does it check to see if the actual contents of the template declaration make any sense. Since the C++ compiler checks this when it compiles the resulting wrapper file, there is no practical reason for SWIG to duplicate this functionality.

As SWIG's template support does not perform type checking %template can be used as early as after a template declaration. You can, and rarely have to, use %template before the template parameters have been declared. For example:

template <class T> class OuterTemplateClass {};

// The nested class OuterClass::InnerClass inherits from the class template
// OuterTemplateClass<OuterClass::InnerStruct> and thus the template needs
// to be expanded with %template before the OuterClass declaration.
%template(OuterTemplateClass_OuterClass__InnerStruct)
  OuterTemplateClass<OuterClass::InnerStruct>


// Don't forget to use %feature("flatnested") for OuterClass::InnerStruct and
// OuterClass::InnerClass if the target language doesn't support nested classes.
class OuterClass {
  public:
    // Forward declarations:
    struct InnerStruct;
    class InnerClass;
};

struct OuterClass::InnerStruct {};

// Expanding the template at this point with %template is too late as the
// OuterClass::InnerClass declaration is processed inside OuterClass.

class OuterClass::InnerClass : public OuterTemplateClass<InnerStruct> {};

Compatibility Note: The first implementation of template support relied heavily on macro expansion in the preprocessor. Templates have been more tightly integrated into the parser and type system in SWIG-1.3.12 and the preprocessor is no longer used. Code that relied on preprocessing features in template expansion will no longer work. However, SWIG still allows the # operator to be used to generate a string from a template argument.

Compatibility Note: In earlier versions of SWIG, the %template directive introduced a new class name. This name could then be used with other directives. For example:

%template(vectori) vector<int>;
%extend vectori {
  void somemethod() { }
};

This behavior is no longer supported. Instead, you should use the original template name as the class name. For example:

%template(vectori) vector<int>;
%extend vector<int> {
  void somemethod() { }
};

Similar changes apply to typemaps and other customization features.

6.19 Namespaces

Support for C++ namespaces is comprehensive, but by default simple, however, some target languages can turn on more advanced namespace support via the nspace feature, described later. Code within unnamed namespaces is ignored as there is no external access to symbols declared within the unnamed namespace. Before detailing the default implementation for named namespaces, it is worth noting that the semantics of C++ namespaces is extremely non-trivial--especially with regard to the C++ type system and class machinery. At a most basic level, namespaces are sometimes used to encapsulate common functionality. For example:

namespace math {
  double sin(double);
  double cos(double);

  class Complex {
    double im, re;
  public:
    ...
  };
  ...
};

Members of the namespace are accessed in C++ by prepending the namespace prefix to names. For example:

double x = math::sin(1.0);
double magnitude(math::Complex *c);
math::Complex c;
...

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 a using declaration:

using math::Complex;                // Using declaration
double magnitude(Complex *c);       // Namespace prefix stripped

Similarly, the contents of an entire namespace can be made available via a using directive:

using namespace math;               // Using directive
double x = sin(1.0);
double magnitude(Complex *c);

Alternatively, a namespace can be aliased:

namespace M = math;
double x = M::sin(1.0);
double magnitude(M::Complex *c);

Using combinations of these features, it is possible to write head-exploding code like this:

namespace A {
  class Foo {
  };
}

namespace B {
  namespace C {
    using namespace A;
  }
  typedef C::Foo FooClass;
}

namespace BIGB = B;

namespace D {
  using BIGB::FooClass;
  class Bar : public FooClass {
  }
};

class Spam : public D::Bar {
};

void evil(A::Foo *a, B::FooClass *b, B::C::Foo *c, BIGB::FooClass *d,
          BIGB::C::Foo *e, D::FooClass *f);

Given the possibility for such perversion, it's hard to imagine how every C++ programmer might want such code wrapped into the target language. Clearly this code defines three different classes. However, one of those classes is accessible under at least six different names!

SWIG fully supports C++ namespaces in its internal type system and class handling code. If you feed SWIG the above code, it will be parsed correctly, it will generate compilable wrapper code, and it will produce a working scripting language module. However, the default wrapping behavior is to flatten namespaces in the target language. This means that the contents of all namespaces are merged together in the resulting scripting language module. For example, if you have code like this,

%module foo
namespace foo {
  void bar(int);
  void spam();
}

namespace bar {
  void blah();
}

then SWIG simply creates three wrapper functions bar(), spam(), and blah() in the target language. SWIG does not prepend the names with a namespace prefix nor are the functions packaged in any kind of nested scope. Note that the default handling of flattening all the namespace scopes in the target language can be changed via the nspace feature.

There is some rationale for taking this approach. Since C++ namespaces are often used to define modules in C++, there is a natural correlation between the likely contents of a SWIG module and the contents of a namespace. For instance, it would not be unreasonable to assume that a programmer might make a separate extension module for each C++ namespace. In this case, it would be redundant to prepend everything with an additional namespace prefix when the module itself already serves as a namespace in the target language. Or put another way, if you want SWIG to keep namespaces separate, simply wrap each namespace with its own SWIG interface.

Because namespaces are flattened, it is possible for symbols defined in different namespaces to generate a name conflict in the target language. For example:

namespace A {
  void foo(int);
}
namespace B {
  void foo(double);
}

When this conflict occurs, you will get an error message that resembles this:

example.i:26: Error: 'foo' is multiply defined in the generated target language module.
example.i:23: Error: Previous declaration of 'foo'

To resolve this error, simply use %rename to disambiguate the declarations. For example:

%rename(B_foo) B::foo;
...
namespace A {
  void foo(int);
}
namespace B {
  void foo(double);     // Gets renamed to B_foo
}

Similarly, %ignore can be used to ignore declarations.

C++ using directives and using declarations do not add any code to the generated wrapper code. However, there is an exception in one context, see Using declarations and inheritance for introducing members of a base class into a derived class definition. C++ using declarations and directives are used by the internal type system to track type-names. Therefore, if you have code like this:

namespace A {
  typedef int Integer;
}
using namespace A;
void foo(Integer x);

SWIG knows that Integer is the same as A::Integer which is the same as int.

Namespaces may be combined with templates. If necessary, the %template directive can be used to expand a template defined in a different namespace. For example:

namespace foo {
  template<typename T> T max(T a, T b) { return a > b ? a : b; }
}

using foo::max;

%template(maxint)   max<int>;           // Okay.
%template(maxfloat) foo::max<float>;    // Okay (qualified name).

namespace bar {
  using namespace foo;
  %template(maxdouble)  max<double>;    // Okay.
}

The combination of namespaces and other SWIG directives may introduce subtle scope-related problems. The key thing to keep in mind is that all SWIG generated wrappers are produced in the global namespace. Symbols from other namespaces are always accessed using fully qualified names---names are never imported into the global space unless the interface happens to do so with a using declaration. In almost all cases, SWIG adjusts typenames and symbols to be fully qualified. However, this is not done in code fragments such as function bodies, typemaps, exception handlers, and so forth. For example, consider the following:

namespace foo {
  typedef int Integer;
  class bar {
    public:
    ...
  };
}

%extend foo::bar {
  Integer add(Integer x, Integer y) {
    Integer r = x + y;        // Error. Integer not defined in this scope
    return r;
  }
};

In this case, SWIG correctly resolves the added method parameters and return type to foo::Integer. However, since function bodies aren't parsed and such code is emitted in the global namespace, this code produces a compiler error about Integer. To fix the problem, make sure you use fully qualified names. For example:

%extend foo::bar {
  Integer add(Integer x, Integer y) {
    foo::Integer r = x + y;        // Ok.
    return r;
  }
};

Note: SWIG does not propagate using declarations to the resulting wrapper code. If these declarations appear in an interface, they should also appear in any header files that might have been included in a %{ ... %} section. In other words, don't insert extra using declarations into a SWIG interface unless they also appear in the underlying C++ code.

Note: Code inclusion directives such as %{ ... %} or %inline %{ ... %} should not be placed inside a namespace declaration. The code emitted by these directives will not be enclosed in a namespace and you may get very strange results. If you need to use namespaces with these directives, consider the following:

// Good version
%inline %{
namespace foo {
  void bar(int) { ... }
  ...
}
%}

// Bad version.  Emitted code not placed in namespace.
namespace foo {
%inline %{
  void bar(int) { ... }   /* I'm bad */
  ...
  %}
}

Note: When the %extend directive is used inside a namespace, the namespace name is included in the generated functions. For example, if you have code like this,

namespace foo {
  class bar {
    public:
      %extend {
        int blah(int x);
      };
  };
}

the added method blah() is mapped to a function int foo_bar_blah(foo::bar *self, int x). This function resides in the global namespace.

Note: Although namespaces are flattened in the target language, the SWIG generated wrapper code observes the same namespace conventions as used in the input file. Thus, if there are no symbol conflicts in the input, there will be no conflicts in the generated code.

Note: In the same way that no resolution is performed on parameters, a conversion operator name must match exactly to how it is defined. Do not change the qualification of the operator. For example, suppose you had an interface like this:

namespace foo {
  class bar;
  class spam {
    public:
    ...
    operator bar();      // Conversion of spam -> bar
    ...
  };
}

The following is how the feature is expected to be written for a successful match:

%rename(tofoo) foo::spam::operator bar();

The following does not work as no namespace resolution is performed in the matching of conversion operator names:

%rename(tofoo) foo::spam::operator foo::bar();

Note, however, that if the operator is defined using a qualifier in its name, then the feature must use it too...

%rename(tofoo) foo::spam::operator bar();      // will not match
%rename(tofoo) foo::spam::operator foo::bar(); // will match
namespace foo {
  class bar;
  class spam {
    public:
    ...
    operator foo::bar();
    ...
  };
}

Compatibility Note: Versions of SWIG prior to 1.3.32 were inconsistent in this approach. A fully qualified name was usually required, but would not work in some situations.

Note: The flattening of namespaces is only intended to serve as a basic namespace implementation. More advanced handling of namespaces is discussed next.

6.19.1 The nspace feature for namespaces

Some target languages provide support for the nspace feature. The feature can be applied to any class, struct, union or enum declared within a named namespace. The feature wraps the type within the target language specific concept of a namespace, for example, a Java package or C# namespace. Please see the language specific sections to see if the target language you are interested in supports the nspace feature.

The feature is demonstrated below for C# using the following example:

%feature("nspace") MyWorld::Material::Color;
%nspace MyWorld::Wrapping::Color; // %nspace is a macro for %feature("nspace")

namespace MyWorld {
  namespace Material {
    class Color {
    ...
    };
  }
  namespace Wrapping {
    class Color {
    ...
    };
  }
}

Without the nspace feature directives above or %rename , you would get the following warning resulting in just one of the Color classes being available for use from the target language:

example.i:9: Error: 'Color' is multiply defined in the generated target language module.
example.i:5: Error: Previous declaration of 'Color'

With the nspace feature the two Color classes are wrapped into the equivalent C# namespaces. A fully qualified constructor call of each these two types in C# is then:

MyWorld.Material.Color materialColor = new MyWorld.Material.Color();
MyWorld.Wrapping.Color wrappingColor = new MyWorld.Wrapping.Color();

Note that the nspace feature does not apply to variables and functions simply declared in a namespace. For example, the following symbols cannot co-exist in the target language without renaming. This may change in a future version.

namespace MyWorld {
  namespace Material {
    int quantity;
    void dispatch();
  }
  namespace Wrapping {
    int quantity;
    void dispatch();
  }
}

Compatibility Note: The nspace feature was first introduced in SWIG-2.0.0.

6.20 Renaming templated types in namespaces

As has been mentioned, when %rename includes parameters, the parameter types must match exactly (no typedef or namespace resolution is performed). SWIG treats templated types slightly differently and has an additional matching rule so unlike non-templated types, an exact match is not always required. If the fully qualified templated type is specified, it will have a higher precedence over the generic template type. In the example below, the generic template type is used to rename to bbb and the fully qualified type is used to rename to ccc.

%rename(bbb) Space::ABC::aaa(T t);                     // will match but with lower precedence than ccc
%rename(ccc) Space::ABC<Space::XYZ>::aaa(Space::XYZ t);// will match but with higher precedence
                                                       // than bbb

namespace Space {
  class XYZ {};
  template<typename T> struct ABC {
    void aaa(T t) {}
  };
}
%template(ABCXYZ) Space::ABC<Space::XYZ>;

It should now be apparent that there are many ways to achieve a renaming with %rename. This is demonstrated by the following two examples, which are effectively the same as the above example. Below shows how %rename can be placed inside a namespace.

namespace Space {
  %rename(bbb) ABC::aaa(T t);                     // will match but with lower precedence than ccc
  %rename(ccc) ABC<Space::XYZ>::aaa(Space::XYZ t);// will match but with higher precedence than bbb
  %rename(ddd) ABC<Space::XYZ>::aaa(XYZ t);       // will not match
}

namespace Space {
  class XYZ {};
  template<typename T> struct ABC {
    void aaa(T t) {}
  };
}
%template(ABCXYZ) Space::ABC<Space::XYZ>;

Note that ddd does not match as there is no namespace resolution for parameter types and the fully qualified type must be specified for template type expansion. The following example shows how %rename can be placed within %extend.

namespace Space {
  %extend ABC {
    %rename(bbb) aaa(T t);         // will match but with lower precedence than ccc
  }
  %extend ABC<Space::XYZ> {
    %rename(ccc) aaa(Space::XYZ t);// will match but with higher precedence than bbb
    %rename(ddd) aaa(XYZ t);       // will not match
  }
}

namespace Space {
  class XYZ {};
  template<typename T> struct ABC {
    void aaa(T t) {}
  };
}
%template(ABCXYZ) Space::ABC<Space::XYZ>;

6.21 Exception specifications

When C++ programs utilize exceptions, exceptional behavior is sometimes specified as part of a function or method declaration. For example:

class Error { };

class Foo {
public:
  ...
  void blah() throw(Error);
  ...
};

If an exception specification is used, SWIG automatically generates wrapper code for catching the indicated exception and, when possible, rethrowing it into the target language, or converting it into an error in the target language otherwise. For example, in Python, you can write code like this:

f = Foo()
try:
    f.blah()
except Error, e:
    # e is a wrapped instance of "Error"

Details of how to tailor code for handling the caught C++ exception and converting it into the target language's exception/error handling mechanism is outlined in the "throws" typemap section.

Since exception specifications are sometimes only used sparingly, this alone may not be enough to properly handle C++ exceptions. To do that, a different set of special SWIG directives are used. Consult the "Exception handling with %exception " section for details. The next section details a way of simulating an exception specification or replacing an existing one.

6.22 Exception handling with %catches

Exceptions are automatically handled for methods with an exception specification. Similar handling can be achieved for methods without exception specifications through the %catches feature. It is also possible to replace any declared exception specification using the %catches feature. In fact, %catches uses the same "throws" typemaps that SWIG uses for exception specifications in handling exceptions. The %catches feature must contain a list of possible types that can be thrown. For each type that is in the list, SWIG will generate a catch handler, in the same way that it would for types declared in the exception specification. Note that the list can also include the catch all specification "...". For example,

struct EBase { virtual ~EBase(); };
struct Error1 : EBase { };
struct Error2 : EBase { };
struct Error3 : EBase { };
struct Error4 : EBase { };

%catches(Error1, Error2, ...) Foo::bar();
%catches(EBase) Foo::blah();

class Foo {
public:
  ...
  void bar();
  void blah() throw(Error1, Error2, Error3, Error4);
  ...
};

For the Foo::bar() method, which can throw anything, SWIG will generate catch handlers for Error1, Error2 as well as a catch all handler (...). Each catch handler will convert the caught exception and convert it into a target language error/exception. The catch all handler will convert the caught exception into an unknown error/exception.

Without the %catches feature being attached to Foo::blah(), SWIG will generate catch handlers for all of the types in the exception specification, that is, Error1, Error2, Error3, Error4. However, with the %catches feature above, just a single catch handler for the base class, EBase will be generated to convert the C++ exception into a target language error/exception.

6.23 Pointers to Members

Starting with SWIG-1.3.7, there is limited parsing support for pointers to C++ class members. For example:

double do_op(Object *o, double (Object::*callback)(double, double));
extern double (Object::*fooptr)(double, double);
%constant double (Object::*FOO)(double, double) = &Object::foo;

Although these kinds of pointers can be parsed and represented by the SWIG type system, few language modules know how to handle them due to implementation differences from standard C pointers. Readers are strongly advised to consult an advanced text such as the "The Annotated C++ Manual" for specific details.

When pointers to members are supported, the pointer value might appear as a special string like this:

>>> print example.FOO
_ff0d54a800000000_m_Object__f_double_double__double
>>>

In this case, the hexadecimal digits represent the entire value of the pointer which is usually the contents of a small C++ structure on most machines.

SWIG's type-checking mechanism is also more limited when working with member pointers. Normally SWIG tries to keep track of inheritance when checking types. However, no such support is currently provided for member pointers.

6.24 Smart pointers and operator->()

In some C++ programs, objects are often encapsulated by smart-pointers or proxy classes. This is sometimes done to implement automatic memory management (reference counting) or persistence. Typically a smart-pointer is defined by a class template where the -> operator has been overloaded. This class is then wrapped around some other class. For example:

// Smart-pointer class
template<class T> class SmartPtr {
  T *pointee;
public:
  SmartPtr(T *p) : pointee(p) { ... }
  T *operator->() {
    return pointee;
  }
  ...
};

// Ordinary class
class Foo_Impl {
public:
  int x;
  virtual void bar();
  ...
};

// Smart-pointer wrapper
typedef SmartPtr<Foo_Impl> Foo;

// Create smart pointer Foo
Foo make_Foo() {
  return SmartPtr<Foo_Impl>(new Foo_Impl());
}

// Do something with smart pointer Foo
void do_something(Foo f) {
  printf("x = %d\n", f->x);
  f->bar();
}

// Call the wrapped smart pointer proxy class in the target language 'Foo'
%template(Foo) SmartPtr<Foo_Impl>;

A key feature of this approach is that by defining operator-> the methods and attributes of the object wrapped by a smart pointer are transparently accessible. For example, expressions such as these (from the previous example),

f->x
f->bar()

are transparently mapped to the following

(f.operator->())->x;
(f.operator->())->bar();

When generating wrappers, SWIG tries to emulate this functionality to the extent that it is possible. To do this, whenever operator->() is encountered in a class, SWIG looks at its returned type and uses it to generate wrappers for accessing attributes of the underlying object. For example, wrapping the above code produces wrappers like this:

int Foo_x_get(Foo *f) {
  return (*f)->x;
}
void Foo_x_set(Foo *f, int value) {
  (*f)->x = value;
}
void Foo_bar(Foo *f) {
  (*f)->bar();
}

These wrappers take a smart-pointer instance as an argument, but dereference it in a way to gain access to the object returned by operator->(). You should carefully compare these wrappers to those in the first part of this chapter (they are slightly different).

The end result is that access looks very similar to C++. For example, you could do this in Python:

>>> f = make_Foo()
>>> print f.x
0
>>> f.bar()
>>>

When generating wrappers through a smart-pointer, SWIG tries to generate wrappers for all methods and attributes that might be accessible through operator->(). This includes any methods that might be accessible through inheritance. However, there are a number of restrictions:

• Member variables and methods are wrapped through a smart pointer. Enumerations, constructors, and destructors are not wrapped.

• If the smart-pointer class and the underlying object both define a method or variable of the same name, then the smart-pointer version has precedence. For example, if you have this code

  class Foo {
  public:
    int x;
  };
  
  class Bar {
  public:
    int x;       
    Foo *operator->();
  };
  

  then the wrapper for Bar::x accesses the x defined in Bar, and not the x defined in Foo.

If your intent is to only expose the smart-pointer class in the interface, it is not necessary to wrap both the smart-pointer class and the class for the underlying object. However, you must still tell SWIG about both classes if you want the technique described in this section to work. To only generate wrappers for the smart-pointer class, you can use the %ignore directive. For example:

%ignore Foo;
class Foo {       // Ignored
};

class Bar {
public:
  Foo *operator->();
  ...
};

Alternatively, you can import the definition of Foo from a separate file using %import.

Note: When a class defines operator->(), the operator itself is wrapped as a method __deref__(). For example:

f = Foo()               # Smart-pointer
p = f.__deref__()       # Raw pointer from operator->

Note: To disable the smart-pointer behavior, use %ignore to ignore operator->(). For example:

%ignore Bar::operator->;

Note: Smart pointer support was first added in SWIG-1.3.14.

6.25 C++ reference counted objects - ref/unref feature

Another similar idiom in C++ is the use of reference counted objects. Consider for example:

class RCObj  {
  // implement the ref counting mechanism
  int add_ref();
  int del_ref();
  int ref_count();

public:
  virtual ~RCObj() = 0;

  int ref() const {
    return add_ref();
  }

  int unref() const {
    if (ref_count() == 0 || del_ref() == 0 ) {
      delete this;
      return 0;
    }
    return ref_count();
  }
};


class A : RCObj {
public:
  A();
  int foo();
};


class B {
  A *_a;

public:
  B(A *a) : _a(a) { 
    a->ref(); 
  }

  ~B() { 
    a->unref(); 
  }
};

int main() {
  A *a  = new A();       // (count: 0)
  a->ref();           // 'a' ref here (count: 1)

  B *b1 = new B(a);   // 'a' ref here (count: 2)
  if (1 + 1 == 2) {
    B *b2 = new B(a); // 'a' ref here (count: 3)
    delete b2;        // 'a' unref, but not deleted (count: 2)
  }

  delete b1;          // 'a' unref, but not deleted (count: 1)
  a->unref();         // 'a' unref and deleted (count: 0)
}

In the example above, the 'A' class instance 'a' is a reference counted object, which can't be deleted arbitrarily since it is shared between the objects 'b1' and 'b2'. 'A' is derived from a Reference Counted Object 'RCObj', which implements the ref/unref idiom.

To tell SWIG that 'RCObj' and all its derived classes are reference counted objects, use the "ref" and "unref" features. These are also available as %refobject and %unrefobject, respectively. For example:

%module example
...

%feature("ref")   RCObj "$this->ref();"
%feature("unref") RCObj "$this->unref();"

%include "rcobj.h"
%include "A.h"
...

where the code passed to the "ref" and "unref" features will be executed as needed whenever a new object is passed to Python, or when Python tries to release the proxy object instance, respectively.

On the Python side, the use of a reference counted object is no different to any other regular instance:

def create_A():
    a = A()         # SWIG ref 'a' - new object is passed to Python (count: 1)
    b1 = B(a)       # C++ ref 'a (count: 2)
    if 1 + 1 == 2:
        b2 = B(a)   # C++ ref 'a' (count: 3)
    return a        # 'b1' and 'b2' are released and deleted, C++ unref 'a' twice (count: 1)

a = create_A()      # (count: 1)
exit                # 'a' is released, SWIG unref 'a' called in the destructor wrapper (count: 0)

Note that the user doesn't explicitly need to call 'a->ref()' nor 'a->unref()' (and neither 'delete a'). Instead, SWIG takes cares of executing the "ref" and "unref" calls as needed. If the user doesn't specify the "ref/unref" feature for a type, SWIG will produce code equivalent to defining these features:

%feature("ref")   ""
%feature("unref") "delete $this;"

In other words, SWIG will not do anything special when a new object is passed to Python, and it will always 'delete' the underlying object when Python releases the proxy instance.

The %newobject feature is designed to indicate to the target language that it should take ownership of the returned object. When used in conjunction with a type that has the "ref" feature associated with it, it additionally emits the code in the "ref" feature into the C++ wrapper. Consider wrapping the following factory function in addition to the above:

%newobject AFactory;
A *AFactory() {
  return new A();
}

The AFactory function now acts much like a call to the A constructor with respect to memory handling:

a = AFactory()    # SWIG ref 'a' due to %newobject (count: 1)
exit              # 'a' is released, SWIG unref 'a' called in the destructor wrapper (count: 0)

6.26 Using declarations and inheritance

C++ using declarations are sometimes used to introduce members of base classes. For example:

class Foo {
public:
  int blah(int x);
};

class Bar {
public:
  double blah(double x);
};

class FooBar : public Foo, public Bar {
public:
  using Foo::blah;
  using Bar::blah;
  char *blah(const char *x);
};

In this example, the using declarations make different versions of the overloaded blah() method accessible from the derived class. For example:

FooBar *f;
f->blah(3);         // Ok. Invokes Foo::blah(int)
f->blah(3.5);       // Ok. Invokes Bar::blah(double)
f->blah("hello");   // Ok. Invokes FooBar::blah(const char *);

SWIG emulates the same functionality when creating wrappers. For example, if you wrap this code in Python, the module works just like you would expect:

>>> import example
>>> f = example.FooBar()
>>> f.blah(3)
>>> f.blah(3.5)
>>> f.blah("hello")

The C++11 standard supports using declarations for inheriting constructors and this is covered in Object construction improvement.

C++ using 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:

class Foo {
protected:
  int x;
  int blah(int x);
};

class Bar : public Foo {
public:
  using Foo::x;       // Make x public
  using Foo::blah;    // Make blah public
};

This also works in SWIG---the exposed declarations will be wrapped normally.

When using declarations are used as shown in these examples, declarations from the base classes are copied into the derived class and wrapped normally. When copied, the declarations retain any properties that might have been attached using %rename , %ignore, or %feature. Thus, if a method is ignored in a base class, it will also be ignored by a using declaration.

Because a using declaration does not provide fine-grained control over the declarations that get imported, because a single using 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 using to work correctly, you can always modify the C++ code to handle SWIG differently such as:

class FooBar : public Foo, public Bar {
public:
#ifndef SWIG
  using Foo::blah;
  using Bar::blah;
#else
  int blah(int x);         // explicitly tell SWIG about other declarations
  double blah(double x);
#endif

  char *blah(const char *x);
};

If the C++ code being wrapped cannot be changed, make judicious usage of %extend and %rename to ignore and unignore declarations. The example below is effectively the same as above:

%extend FooBar {
  int blah(int x) { return $self->Foo::blah(x); }
  double blah(double x) { return $self->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);
};

Notes:

• If a derived class introduces a method defined in a base class via a using declaration, there won't be a conflict due to incorrect additional methods. For example:

  class Foo {
  public:
    int blah(int );
    double blah(double);
  };
  
  class Bar : public Foo {
  public:
    using Foo::blah;    // Only introduces blah(double);
    int blah(int);
  };
  

• Renaming methods may prevent methods from being introduced into the derived class via using declarations. For example:

  %rename(blah_long) Foo::blah(long);
  class Foo {
  public:
    int blah(int);
    long blah(long);  // Renamed to blah_long
  };
  
  class Bar : public Foo {
  public:
    using Foo::blah;     // Only introduces blah(int)
    double blah(double x);
  };
  

  The problem here is Foo::blah is renamed to blah_long in the target language, but the using declaration in Bar is not renamed in the target language and thinks all introduced methods should simply be called blah. 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:

  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.
  

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

  If methods really need different names, please use of combinations of %rename, %ignore and %extend to achieve the desired outcome.

6.27 Nested classes

If the target language supports the nested classes concept (like Java), the nested C++ classes are wrapped as nested target language proxy classes. (In case of Java - "static" nested classes.) Only public nested classes are wrapped. Otherwise there is little difference between nested and normal classes.

If the target language doesn't support nested classes directly, or the support is not implemented in the language module (like for Python currently), then the visible nested classes are moved to the same name space as the containing class (nesting hierarchy is "flattened"). The same behaviour may be turned on for C# and Java by the %feature ("flatnested"); If there is a class with the same name in the outer namespace the inner class (or the global one) may be renamed or ignored:

%rename (Bar_Foo) Bar::Foo;
class Foo {};
class Bar {
  public:
  class Foo {};
};

If a nested class, within an outer class, has to be used as a template parameter within the outer class, then the template will have to be instantiated with %template before the beginning of the outer class. An example can be found in the Templates section.

Compatibility Note: Prior to SWIG-3.0.0, there was limited nested class support. Nested classes were treated as opaque pointers. However, there was a workaround for nested class support in these older versions requiring the user to replicate the nested class in the global scope, adding in a typedef for the nested class in the global scope and using the "nestedworkaround" feature on the nested class. This resulted in approximately the same behaviour as the "flatnested" feature. With proper nested class support now available in SWIG-3.0.0, this feature has been deprecated and no longer works requiring code changes. If you see the following warning:

example.i:8: Warning 126: The nestedworkaround feature is deprecated

consider using the "flatnested" feature discussed above which generates a non-nested proxy class, like the "nestedworkaround" feature did. Alternatively, use the default nested class code generation, which may generate an equivalent to a nested proxy class in the target language, depending on the target language support.

SWIG-1.3.40 and earlier versions did not have the nestedworkaround feature and the generated code resulting from parsing nested classes did not always compile. Nested class warnings could also not be suppressed using %warnfilter.

6.28 A brief rant about const-correctness

A common issue when working with C++ programs is dealing with all possible ways in which the const qualifier (or lack thereof) will break your program, all programs linked against your program, and all programs linked against those programs.

Although SWIG knows how to correctly deal with const in its internal type system and it knows how to generate wrappers that are free of const-related warnings, SWIG does not make any attempt to preserve const-correctness in the target language. Thus, it is possible to pass const qualified objects to non-const methods and functions. For example, consider the following code in C++:

const Object * foo();
void bar(Object *);

...
// C++ code
void blah() {
  bar(foo());         // Error: bar discards const
};

Now, consider the behavior when wrapped into a Python module:

>>> bar(foo())         # Okay
>>> 

Although this is clearly a violation of the C++ type-system, fixing the problem doesn't seem to be worth the added implementation complexity that would be required to support it in the SWIG run-time type system. There are no plans to change this in future releases (although we'll never rule anything out entirely).

The bottom line is that this particular issue does not appear to be a problem for most SWIG projects. Of course, you might want to consider using another tool if maintaining constness is the most important part of your project.

6.29 Callbacks to the target language

C/C++ function pointers are often used for callbacks and this is discussed in the Pointers to functions and callbacks section. The callback techniques described therein provide a way to control callbacks to a C/C++ function but not callbacks into the target language. The techniques described below show how the director feature can be used to support callbacks from C/C++ to the target language.

6.29.1 Introduction to director classes

The director feature enables the ability for a target language class to derive from a wrapped C++ class. The target language can override virtual methods of a wrapped C++ class, thereby supporting cross-language polymorphism. Code can 'call up' from C++ into the target language by simply calling a virtual method overridden in a derived class in the target language. The wrapped C++ classes that have this ability are termed 'director' classes. The director feature is documented individually in each target language and the reader should locate and read this to obtain a full understanding of directors.

6.29.2 Using directors and target language callbacks

SWIG's primary goal is to make it possible to call C/C++ code from a target language, however, the director feature enables the reverse. While there isn't simple direct support for calling target language code from C, the director feature makes this possible. It does require some work and additional wrapper code to be provided by the user. The additional code required must be C++ and not C code and hence may introduce a small dependency on C++ if using a pure C project. In a nutshell, the user must create a C++ base class and turn it into a director class. A virtual method in the director base class is required. SWIG generates the code to call up into the target language when wrapping the director virtual method.

Let's look at some details next. Consider the same function pointer for a callback called binary_op from the Pointers to functions and callbacks section. For completeness, the code required for the module and director feature is also shown:

%module(directors="1") example

%{
int binary_op(int a, int b, int (*op)(int, int)) {
  return op(a, b);
}
%}

The goal is to have a target language function that gets called by binary_op. The target language function should have the equivalent signature as the C/C++ function pointer int (*op)(int, int). As we are using directors, we need a C++ virtual method with this signature, so let's define the C++ class and pure virtual method first and make it a director class via the director feature:

%feature("director") BinaryOp;

%inline %{
struct BinaryOp {
  virtual int handle(int a, int b) = 0;
  virtual ~BinaryOp() {}
};
%}

The following handler_helper function and binary_op_wrapper function completes the code needed in the C++/SWIG layer. The binary_op_wrapper function is wrapped by SWIG and is very similar to the binary_op function, however, it takes a pointer to the director base class BinaryOp instead of a C/C++ function pointer.

%{
static BinaryOp *handler_ptr = NULL;
static int handler_helper(int a, int b) {
  // Make the call up to the target language when handler_ptr
  // is an instance of a target language director class
  return handler_ptr->handle(a, b);
}
// If desired, handler_ptr above could be changed to a thread-local variable in order to make thread-safe
%}

%inline %{
int binary_op_wrapper(int a, int b, BinaryOp *handler) {
  handler_ptr = handler;
  int result = binary_op(a, b, &handler_helper);
  handler = NULL;
  return result;
}
%}

On the target language side, we need to derive a class from BinaryOp and override the handle method. In Python this could be as simple as:

import example

# PythonBinaryOp class is defined and derived from C++ class BinaryOp
class PythonBinaryOp(example.BinaryOp):

    # Define Python class 'constructor'
    def __init__(self):
        # Call C++ base class constructor
        example.BinaryOp.__init__(self)

    # Override C++ method: virtual int handle(int a, int b) = 0;
    def handle(self, a, b):
        # Return the product
        return a * b

For this to work from Python, an instance of the PythonBinaryOp class is created and then passed to binary_op_wrapper. The net result is the binary_op function will in turn be called which will call handler_helper which will call the virtual handle method, that is, the Python method handle in the PythonBinaryOp class. The result will be the product of 10 and 20 and make its way back to Python and hence 200 will be printed with the following code:

handler = PythonBinaryOp()
result = example.binary_op_wrapper(10, 20, handler)
print result

This has thus demonstrated a C/C++ function pointer calling back into a target language function. The code could be made a little more user friendly by using %rename to provide the original binary_op name from the target language instead of binary_op_wrapper. A C++ functor base class and Python functor class could also be used instead, but these are left as exercises for the reader.

6.30 Where to go for more information

If you're wrapping serious C++ code, you might want to pick up a copy of "The Annotated C++ Reference Manual" by Ellis and Stroustrup. This is the reference document we use to guide a lot of SWIG's C++ support.

7 SWIG and C++11

7.1 Introduction

This chapter gives you a brief overview about the SWIG implementation of the C++11 standard.

SWIG supports the new C++ syntax changes with some minor limitations in some areas such as decltype expressions and variadic templates. Wrappers for the new STL types (unordered_ containers, result_of, tuples) are incomplete. The wrappers for the new containers would work much like the C++03 containers and users are welcome to help by adapting the existing container interface files and submitting them as a patch for inclusion in future versions of SWIG.

7.2 Core language changes

7.2.1 Rvalue reference and move semantics

SWIG correctly parses the rvalue reference syntax '&&', for example the typical usage of it in the move constructor and move assignment operator below:

class MyClass {
...
  std::vector<int> numbers;
public:
  MyClass() : numbers() {}
  MyClass(MyClass &&other) : numbers(std::move(other.numbers)) {}
  MyClass & operator=(MyClass &&other) {
    numbers = std::move(other.numbers);
    return *this;
  }
};

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 %ignore. For example, ignore the move constructor:

%ignore MyClass::MyClass(MyClass &&);

7.2.1.1 Rvalue reference inputs

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.

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.

In this way, the SWIG proxy class works much like an exclusively owned smart pointer (think of std::unique_ptr), passing ownership to the called C++ function/constructor. Let's consider an example in Java using the wrapped proxy class from above:

MyClass mc = new MyClass();
MyClass mc1 = new MyClass(mc); // move constructor
MyClass mc2 = new MyClass(mc); // move constructor fails

The second call to the move constructor will fail as the mc 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:

Exception in thread "main" java.lang.RuntimeException: Cannot release ownership as memory is not owned
        at MyClass.swigRelease(MyClass.java:27)
        at MyClass.<init>(MyClass.java:55)
        at runme.main(runme.java:18)

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:

example.i:18: Warning 503: Can't wrap 'operator =' unless renamed to a valid identifier.

Using a %rename will remove the warning and also makes the move assignment operator available from the target language:

%rename(MoveAssign) MyClass::operator=(MyClass &&);

You can then use it, but like the move constructor example above, you cannot use a proxy class once it has already been moved:

MyClass mc = new MyClass();
MyClass mc2 = mc.MoveAssign(mc);
MyClass mc3 = mc.MoveAssign(mc); // Use of mc again will fail

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.

Compatibility note: 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.

7.2.1.2 Rvalue reference outputs

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.

Using MyClass from earlier and this C++ code:

void use(MyClass &&mc);
MyClass && get1();
MyClass & get2();

SWIG wraps the get1 and get2 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:

use(get1());
use(std::move(get2()));

An attempt to call the equivalent use(get1()) from one of the target languages will result in the ownership failure mentioned in the previous section as the object being passed to the use 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!

7.2.1.3 Movable and move-only types by value

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.

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.

The support for function return values is generically implemented in the "out" SWIGTYPE 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:

%typemap(out) SWIGTYPE %{
  $result = new $1_ltype($1);
%}

The above typemap is for C# and when used to wrap a move-only type such as:

struct MoveOnly {
  int  val;
  MoveOnly(): val(0)  {}

  MoveOnly(const MoveOnly &) = delete;
  MoveOnly(MoveOnly &&) = default;

  MoveOnly & operator=(const MoveOnly &) = delete;
  MoveOnly & operator=(MoveOnly &&) = default;

  static MoveOnly create() { return MoveOnly(); }
  static void take(MoveOnly mo);
};

will generate wrapper code for the create factory method:

SWIGEXPORT void * SWIGSTDCALL CSharp_MoveOnly_create() {
  void * jresult ;
  SwigValueWrapper< MoveOnly > result;

  result = MoveOnly::create();
  jresult = new MoveOnly(result);
  return jresult;
}

SwigValueWrapper is covered in Pass and return by value. Note that the generated code could be optimised further using the "optimal" attribute in the "out" typemap, so if the above typemap is customised as follows (note that this is C# specific):

%typemap(out, optimal="1") MoveOnly %{
  $result = new $1_ltype($1);
%}

then the generated code will result in the object being optimally moved:

SWIGEXPORT void * SWIGSTDCALL CSharp_MoveOnly_create() {
  void * jresult ;
  jresult = new MoveOnly(MoveOnly::create());
  return jresult;
}

Now let's consider passing by value. We'll consider three cases; namely types that are:

1. Copyable and not movable - CopyOnly.
2. Copyable and movable - MovableCopyable.
3. Movable and not copyable - MoveOnly.

and for clarification, define these two additional types as follows:

struct CopyOnly {
  int  val;
  CopyOnly(): val(0)  {}

  CopyOnly(const CopyOnly &) = default;
  CopyOnly & operator=(const CopyOnly &) = default;

  static CopyOnly create() { return CopyOnly(); }
  static void take(CopyOnly co);
};

struct MovableCopyable {
  int  val;
  MovableCopyable(): val(0)  {}

  MovableCopyable(const MovableCopyable &) = default;
  MovableCopyable(MovableCopyable &&) = default;
  MovableCopyable & operator=(const MovableCopyable &) = default;
  MovableCopyable & operator=(MovableCopyable &&) = default;

  static MovableCopyable create() { return MovableCopyable(); }
  static void take(MovableCopyable mc);
};

The generated code is shown below for CopyOnly::take (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.

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
}

Note that SWIG_STD_MOVE is a macro defined as shown below to use std::move which is only available from C++11 onwards:

#if __cplusplus >=201103L
# define SWIG_STD_MOVE(OBJ) std::move(OBJ)
#else
# define SWIG_STD_MOVE(OBJ) OBJ
#endif

Also note: (c) Copy constructor. 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!

The generated code for MovableCopyable::take is the same as for CopyOnly::take, however, the C++ compiler will choose the move constructor this time where commented (c) Move constructor:

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
}

There are two optimisation opportunities available.

1. Remove the default constructor call with the %feature("valuewrapper") covered in Pass and return by value and replace it with SwigValueWrapper.
2. 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 SwigValueWrapper::reset , which works much like std::unique_ptr::reset. These typemaps could alternatively have replaced the copy assignment with a move assignment, but this is not maximally optimal.

Simply add the following before the MovableCopyable::take method is parsed:

%valuewrapper MovableCopyable;
%include <swigmove.i>
%apply SWIGTYPE MOVE { MovableCopyable }

will result in this optimal code where just one move constructor is invoked:

SWIGEXPORT void SWIGSTDCALL CSharp_MovableCopyable_take(void * jarg1) {
  SwigValueWrapper< MovableCopyable > arg1 ; // (a) No constructors invoked
  MovableCopyable *argp1 ;
  
  argp1 = (MovableCopyable *)jarg1;
  if (!argp1) {
    SWIG_CSharpSetPendingExceptionArgument(SWIG_CSharpArgumentNullException, "Attempt to dereference null MovableCopyable", 0);
    return ;
  }
  SwigValueWrapper< MovableCopyable >::reset(arg1, argp1);  // (b) No constructor or assignment operator invoked
  MovableCopyable::take(SWIG_STD_MOVE(arg1)); // (c) Move constructor
}

Note that SwigValueWrapper will call the destructor for the pointer passed to it in the reset 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 rvalue reference parameter discussed earlier.

Lastly, let's consider the MoveOnly::take function defined earlier. By default the generated code fails to compile as MoveOnly 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 %feature("valuewrapper") 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 MoveOnly::take is parsed, which results in the same optimal code shown above for MovableCopyable:

%include <swigmove.i>
%apply SWIGTYPE MOVE { MoveOnly }

Compatibility note: SWIG-4.1.0 introduced support for taking advantage of types with move semantics and making it possible to easily use move only types.

7.2.2 Generalized constant expressions

SWIG parses and identifies the keyword constexpr, but cannot fully utilise it. These C++ compile time constants are usable as runtime constants from the target languages. Below shows example usage for assigning a C++ compile time constant from a compile time constant function:

constexpr int XXX() { return 10; }
constexpr int YYY = XXX() + 100;

When either of these is used from a target language, a runtime call is made to obtain the underlying constant.

7.2.3 Extern template

SWIG correctly parses extern template 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 %template for instantiating and wrapping templates. Consider the class template below:

// Class template
template class std::vector<int>;        // C++03 template explicit instantiation definition in C++
extern template class std::vector<int>; // C++11 template explicit instantiation declaration (extern template)
%template(VectorInt) std::vector<int>;  // SWIG template instantiation

The above result in warnings:

example.i:2: Warning 320: Explicit template instantiation ignored.
example.i:3: Warning 327: Extern template ignored.

Similarly for the function template below:

// Function template
template void Func<int>();              // C++03 template explicit instantiation definition in C++
extern template void Func<int>();       // C++11 template explicit instantiation declaration (extern template)
%template(FuncInt) Func<int>;           // SWIG template instantiation

7.2.4 Initializer lists

Initializer lists are very much a C++ compiler construct and are not very accessible from wrappers as they are intended for compile time initialization of classes using the special std::initializer_list type. SWIG detects usage of initializer lists and will emit a special informative warning each time one is used:

example.i:33: Warning 476: Initialization using std::initializer_list.

Initializer lists usually appear in constructors but can appear in any function or method. They often appear in constructors which are overloaded with alternative approaches to initializing a class, such as the std container's push_back method for adding elements to a container. The recommended approach then is to simply ignore the initializer-list constructor, for example:

%ignore Container::Container(std::initializer_list<int>);
class Container {
public:
  Container(std::initializer_list<int>); // initializer-list constructor
  Container();
  void push_back(const int &);
  ...
};

Alternatively you could modify the class and add another constructor for initialization by some other means, for example by a std::vector:

%include <std_vector.i>
class Container {
public:
  Container(const std::vector<int> &);
  Container(std::initializer_list<int>); // initializer-list constructor
  Container();
  void push_back(const int &);
  ...
};

And then call this constructor from your target language, for example, in Python, the following will call the constructor taking the std::vector:

>>> c = Container( [1, 2, 3, 4] )

If you are unable to modify the class being wrapped, consider ignoring the initializer-list constructor and using %extend to add in an alternative constructor:

%include <std_vector.i>
%extend Container {
  Container(const std::vector<int> &elements) {
    Container *c = new Container();
    for (int element : elements)
      c->push_back(element);
    return c;
  }
}

%ignore Container::Container(std::initializer_list<int>);

class Container {
public:
  Container(std::initializer_list<int>); // initializer-list constructor
  Container();
  void push_back(const int &);
  ...
};

The above makes the wrappers look is as if the class had been declared as follows:

%include <std_vector.i>
class Container {
public:
  Container(const std::vector<int> &);
//  Container(std::initializer_list<int>); // initializer-list constructor (ignored)
  Container();
  void push_back(const int &);
  ...
};

std::initializer_list is simply a container that can only be initialized at compile time. As it is just a C++ type, it is possible to write typemaps for a target language container to map onto std::initializer_list. However, this can only be done for a fixed number of elements as initializer lists are not designed to be constructed with a variable number of arguments at runtime. The example below is a very simple approach which ignores any parameters passed in and merely initializes with a fixed list of fixed integer values chosen at compile time:

%typemap(in) std::initializer_list<int> {
  $1 = {10, 20, 30, 40, 50};
}
class Container {
public:
  Container(std::initializer_list<int>); // initializer-list constructor
  Container();
  void push_back(const int &);
  ...
};

Any attempt at passing in values from the target language will be ignored and be replaced by {10, 20, 30, 40, 50}. Needless to say, this approach is very limited, but could be improved upon, but only slightly. A typemap could be written to map a fixed number of elements on to the std::initializer_list, but with values decided at runtime. The typemaps would be target language specific.

Note that the default typemap for std::initializer_list does nothing but issue the warning and hence any user supplied typemaps will override it and suppress the warning.

7.2.5 Uniform initialization

The curly brackets {} for member initialization are fully supported by SWIG:

struct BasicStruct {
 int x;
 double y;
};
 
struct AltStruct {
  AltStruct(int x, double y) : x_{x}, y_{y} {}
 
  int x_;
  double y_;
};

BasicStruct var1{5, 3.2}; // only fills the struct components
AltStruct var2{2, 4.3};   // calls the constructor

Uniform initialization does not affect usage from the target language, for example in Python:

>>> a = AltStruct(10, 142.15)
>>> a.x_
10
>>> a.y_
142.15

7.2.6 Type inference

decltype() 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

int i;
decltype(i) j;
decltype(i+j) k;

SWIG is able to deduce that the variable i and the expression i+j both have type int.

Using an expression for the decltype which SWIG can't handle results in a warning:

int foo(int);
decltype(foo(0)) k;  // Warning 344: Unable to deduce decltype for 'foo(0)'.

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 decltype and perhaps additionally suppress the warning as follows:

#pragma SWIG nowarn=SWIGWARN_CPP11_DECLTYPE
%ignore k;

If an ignore is not acceptable, a workaround is to redefine the symbol with the actual type, for example:

int k; // define k with the actual type
%ignore k; // ignore the real definition of k

You would typically put one of these workarounds in your interface file before using %include to get SWIG to parse the header which defines k.

SWIG supports auto as a type specifier for variables (with the same limitations for actually deducing the type as for decltype()), and for specifying the return type of lambdas and functions.

7.2.7 Range-based for-loop

This feature is part of the implementation block only. SWIG ignores it.

7.2.8 Lambda functions and expressions

SWIG correctly parses most of the Lambda functions syntax. For example:

auto val = [] { return something; };
auto sum = [](int x, int y) { return x+y; };
auto sum = [](int x, int y) -> int { return x+y; };

The lambda functions are removed from the wrappers for now, because of the lack of support for closures (scope of the lambda functions) in the target languages.

Lambda functions used to create variables can also be parsed, but due to limited support of auto when the type is deduced from the expression, the variables are simply ignored.

auto six = [](int x, int y) { return x+y; }(4, 2);

Better support should be available in a later release.

7.2.9 Alternate function syntax

SWIG fully supports the new definition of functions. For example:

struct SomeStruct {
  int FuncName(int x, int y);
};

can now be written as in C++11:

struct SomeStruct {
  auto FuncName(int x, int y) -> int;
};
 
auto SomeStruct::FuncName(int x, int y) -> int {
  return x + y;
}

The usage in the target languages remains the same, for example in Python:

>>> a = SomeStruct()
>>> a.FuncName(10, 5)
15

SWIG will also deal with type inference for the return type, as per the limitations described earlier. For example:

auto square(float a, float b) -> decltype(a);

7.2.10 Object construction improvement

There are three parts to object construction improvement. The first improvement is constructor delegation such as the following:

class A {
public:
  int a;
  int b;
  int c;

  A() : A(10) {}
  A(int aa) : A(aa, 20) {}
  A(int aa, int bb) : A(aa, bb, 30) {}
  A(int aa, int bb, int cc) { a=aa; b=bb; c=cc; }
};

where peer constructors can be called. SWIG handles this without any issue.

The second improvement is constructor inheritance via a using declaration. The extra constructors provided by the using declaration will add the appropriate constructors into the target language proxy derived classes. In the example below a wrapper for the DerivedClass(int) constructor is added to DerivedClass:

class BaseClass {
public:
  BaseClass(int iValue);
};

class DerivedClass: public BaseClass {
  public:
  using BaseClass::BaseClass; // Adds DerivedClass(int) constructor
};

Compatibility note: SWIG-4.2.0 was the first version to generate wrappers for constructors inherited via using declarations.

The final part is member initialization at the site of the declaration. This kind of initialization is handled by SWIG.

class SomeClass {
public:
  SomeClass() {}
  explicit SomeClass(int new_value) : value(new_value) {}

  int value = 5;
};

7.2.11 Explicit overrides and final

The special identifiers final and override can be used on methods and destructors, such as in the following example:

struct BaseStruct {
  virtual void ab() const = 0;
  virtual void cd();
  virtual void ef();
  virtual ~BaseStruct();
};
struct DerivedStruct : BaseStruct {
  virtual void ab() const override;
  virtual void cd() final;
  virtual void ef() final override;
  virtual ~DerivedStruct() override;
};

Classes can also be marked as final, such as

struct FinalDerivedStruct final : BaseStruct {
  virtual void ab() const override;
};

Compatibility note: Final methods were supported much earlier than final classes. SWIG-4.1.0 was the first version to support classes marked as final.

7.2.12 Null pointer constant

The nullptr constant is mostly unimportant in wrappers. In the few places it has an effect, it is treated like NULL.

7.2.13 Strongly typed enumerations

SWIG supports strongly typed enumerations and parses the new enum class syntax and forward declarator for the enums, such as:

enum class MyEnum : unsigned int;

Strongly typed enums are often used to avoid name clashes such as the following:

struct Color {
  enum class RainbowColors : unsigned int {
    Red, Orange, Yellow, Green, Blue, Indigo, Violet
  };
  
  enum class WarmColors {
    Yellow, Orange, Red
  };

  // Note normal enum
  enum PrimeColors {
    Red=100, Green, Blue
  };
};

There are various ways that the target languages handle enums, so it is not possible to precisely state how they are handled in this section. However, generally, most scripting languages mangle in the strongly typed enumeration's class name, but do not use any additional mangling for normal enumerations. For example, in Python, the following code

print Color.RainbowColors_Red, Color.WarmColors_Red, Color.Red

results in

0 2 100

The strongly typed languages often wrap normal enums into an enum class and so treat normal enums and strongly typed enums the same. The equivalent in Java is:

System.out.println(Color.RainbowColors.Red.swigValue() + " " + Color.WarmColors.Red.swigValue() + " " + Color.PrimeColors.Red.swigValue());

The C++11 enum base type, such as unsigned int, 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# uint to specify the underlying C# enumeration type as follows:

  public enum RainbowColors : uint {
    Red,
    Orange,
    Yellow,
    Green,
    Blue,
    Indigo,
    Violet
  }

7.2.14 Double angle brackets

SWIG correctly parses the symbols >> as closing the template block, if found inside it at the top level, or as the right shift operator >> otherwise.

std::vector<std::vector<int>> myIntTable;

7.2.15 Explicit conversion operators

SWIG correctly parses the keyword explicit for operators in addition to constructors now. For example:

class U {
public:
  int u;
};

class V {
public:
  int v;
};

class TestClass {
public:
  //implicit converting constructor
  TestClass(U const &val) { t=val.u; }

  // explicit constructor
  explicit TestClass(V const &val) { t=val.v; }

  int t;
};

struct Testable {
  // explicit conversion operator
  explicit operator bool() const {
    return false;
  }
};

The effect of explicit constructors and operators has little relevance for the proxy classes as target languages don't have the same concepts of implicit conversions as C++. Conversion operators either with or without explicit need renaming to a valid identifier name in order to make them available as a normal proxy method.

7.2.16 Type alias and alias templates

A type alias is a statement of the form:

using PFD = void (*)(double); // New introduced syntax

which is equivalent to the old style typedef:

typedef void (*PFD)(double);  // The old style

The following is an example of an alias template:

template< typename T1, typename T2, int N >
class SomeType {
public:
  T1 a;
  T2 b;
};

template< typename T2 >
using TypedefName = SomeType<char*, T2, 5>;

SWIG supports both type aliasing and alias templates. However, in order to use an alias template, two %template directives must be used:

%template(SomeTypeBool) SomeType<char*, bool, 5>;
%template() TypedefName<bool>;

Firstly, the actual template is instantiated with a name to be used by the target language, as per any template being wrapped. Secondly, the empty template instantiation, %template(), is required for the alias template. This second requirement is necessary to add the appropriate instantiated template type into the type system as SWIG does not automatically instantiate templates. See the Templates section for more general information on wrapping templates.

7.2.17 Unrestricted unions

SWIG fully supports any type inside a union even if it does not define a trivial constructor. For example, the wrapper for the following code correctly provides access to all members in the union:

struct point {
  point() {}
  point(int x, int y) : x_(x), y_(y) {}
  int x_, y_;
};

#include <new> // For placement 'new' in the constructor below
union P {
  int z;
  double w;
  point p; // Illegal in C++03; legal in C++11.
  // Due to the point member, a constructor definition is required.
  P() {
    new(&p) point();
  }
} p1;

7.2.18 Variadic templates

SWIG supports the variadic templates including the <> variadic class inheritance, variadic methods, variadic constructors and initializers. Example:

template <typename... BaseClasses> class ClassName : public BaseClasses... {
public:
  ClassName(BaseClasses &&... baseClasses) : BaseClasses(baseClasses)... {}
  void InstanceMethod(const BaseClasses&... baseClasses) {}
};

The %template directive works as expected for variable template parameters.

struct A {
  virtual void amethod();
  virtual ~A();
};
struct B {
  virtual void bmethod();
  virtual ~B();
};
%template(ClassName0) ClassName<>
%template(ClassName1) ClassName<A>
%template(ClassName2) ClassName<A, B>

Example usage from say Python:

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

Support for the variadic sizeof() function also works:

const int SIZE = sizeof...(ClassName<A, B>);

In the above example SIZE is of course wrapped as a constant.

Compatibility note: 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.

7.2.19 New character literals

C++11 adds support for UCS-2 and UCS-4 character literals. These character literals are preceded by either 'u' or 'U'.

char16_t a = u'a';
char32_t b = U'b';

Compatibility note: SWIG-4.0.0 was the first version to support these Universal Coded Character Set (UCS) character literals.

7.2.20 New string literals

SWIG supports wide string and Unicode string constants and raw string literals.

// New string literals
wstring         aa =  L"Wide string";
const char     *bb = u8"UTF-8 string";
const char16_t *cc =  u"UTF-16 string";
const char32_t *dd =  U"UTF-32 string";

// Raw string literals
const char      *xx =        ")I'm an \"ascii\" \\ string.";
const char      *ee =   R"XXX()I'm an "ascii" \ string.)XXX"; // same as xx
wstring          ff =  LR"XXX(I'm a "raw wide" \ string.)XXX";
const char      *gg = u8R"XXX(I'm a "raw UTF-8" \ string.)XXX";
const char16_t  *hh =  uR"XXX(I'm a "raw UTF-16" \ string.)XXX";
const char32_t  *ii =  UR"XXX(I'm a "raw UTF-32" \ string.)XXX";

Non-ASCII string support varies quite a bit among the various target languages though.

Note: There is a bug currently where SWIG's preprocessor incorrectly parses an odd number of double quotes inside raw string literals.

7.2.21 User-defined literals

SWIG parses the declaration of user-defined literals, that is, the operator "" _mysuffix() function syntax.

Some examples are the raw literal:

OutputType operator "" _myRawLiteral(const char * value);

numeric cooked literals:

OutputType operator "" _mySuffixIntegral(unsigned long long);
OutputType operator "" _mySuffixFloat(long double);

and cooked string literals:

OutputType operator "" _mySuffix(const char * string_values, size_t num_chars);
OutputType operator "" _mySuffix(const wchar_t * string_values, size_t num_chars);
OutputType operator "" _mySuffix(const char16_t * string_values, size_t num_chars);
OutputType operator "" _mySuffix(const char32_t * string_values, size_t num_chars);

Like other operators that SWIG parses, a warning is given about renaming the operator in order for it to be wrapped:

example.i:27: Warning 503: Can't wrap 'operator "" _myRawLiteral' unless renamed to a valid identifier.

If %rename is used, then it can be called like any other wrapped method. Currently you need to specify the full declaration including parameters for %rename:

%rename(MyRawLiteral)  operator"" _myRawLiteral(const char * value);

Or if you just wish to ignore it altogether:

%ignore operator "" _myRawLiteral(const char * value);

Note that use of user-defined literals such as the following still give a syntax error:

OutputType var1 = "1234"_suffix;
OutputType var2 = 1234_suffix;
OutputType var3 = 3.1416_suffix;

7.2.22 Thread-local storage

SWIG correctly parses the thread_local keyword. For example, variables reachable by the current thread can be defined as:

struct A {
  static thread_local int val;
};
thread_local int global_val;

The use of the thread_local storage specifier does not affect the wrapping process; it does not modify the wrapper code compared to when it is not specified. A variable will be thread local if accessed from different threads from the target language in the same way that it will be thread local if accessed from C++ code.

7.2.23 Explicitly defaulted functions and deleted functions

SWIG handles explicitly defaulted functions, that is, = default added to a function declaration. Deleted definitions, which are also called deleted functions, have = delete added to the function declaration. For example:

struct NonCopyable {
  NonCopyable & operator=(const NonCopyable &) = delete; /* Removes operator= */
  NonCopyable(const NonCopyable &) = delete;             /* Removes copy constructor */
  NonCopyable() = default;                               /* Explicitly allows the empty constructor */
};

Wrappers for deleted functions will not be available in the target language. Wrappers for defaulted functions will of course be available in the target language. Explicitly defaulted functions have no direct effect for SWIG wrapping as the declaration is handled much like any other method declaration parsed by SWIG.

Deleted functions are also designed to prevent implicit conversions when calling the function. For example, the C++ compiler will not compile any code which attempts to use an int as the type of the parameter passed to f below:

struct NoInt {
  void f(double i);
  void f(int) = delete;
};

This is a C++ compile time check and SWIG does not make any attempt to detect if the target language is using an int instead of a double though, so in this case it is entirely possible to pass an int instead of a double to f from Java, Python etc.

7.2.24 Type long long int

SWIG correctly parses and uses the new long long type already introduced in C99 some time ago.

7.2.25 Static assertions

SWIG correctly parses the new static_assert declarations (though 3.0.12 and earlier had a bug which meant this wasn't accepted at file scope). This is a C++ compile time directive so there isn't anything useful that SWIG can do with it.

template <typename T>
struct Check {
  static_assert(sizeof(int) <= sizeof(T), "not big enough");
};

7.2.26 Allow sizeof to work on members of classes without an explicit object

SWIG can parse the new sizeof() on types as well as on objects. For example:

struct A {
  int member;
};

const int SIZE = sizeof(A::member); // does not work with C++03. Okay with C++11

In Python:

>>> SIZE
8

7.2.27 Exception specifications and noexcept

C++11 added in the noexcept specification to exception specifications to indicate that a function simply may or may not throw an exception, without actually naming any exception. SWIG understands these, although there isn't any useful way that this information can be taken advantage of by target languages, so it is as good as ignored during the wrapping process. Below are some examples of noexcept in function declarations:

static void noex1() noexcept;
int noex2(int) noexcept(true);
int noex3(int, bool) noexcept(false);

7.2.28 Control and query object alignment

An alignof operator is used mostly within C++ to return alignment in number of bytes, but could be used to initialize a variable as shown below. The variable's value will be available for access by the target language as any other variable's compile time initialised value.

const int align1 = alignof(A::member);

The alignas specifier for variable alignment is not yet supported. Example usage:

struct alignas(16) S {
  int num;
};
alignas(double) unsigned char c[sizeof(double)];

Use the preprocessor to work around this for now:

#define alignas(T)

7.2.29 Attributes

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.

int [[attr1]] i [[attr2, attr3]];

[[noreturn, nothrow]] void f [[noreturn]] ();

7.2.30 Methods with ref-qualifiers

C++11 non-static member functions can be declared with ref-qualifiers. Member functions declared with a & lvalue ref-qualifiers are wrapped like any other function without ref-qualifiers. Member functions declared with a && rvalue ref-qualifiers are ignored by default as they are unlikely to be required from non-C++ languages where the concept of rvalue-ness for the implied *this pointer does not apply. The warning is hidden by default, but can be displayed as described in the section on Enabling extra warnings.

Consider:

struct RQ {
  void m1(int x) &;
  void m2(int x) &&;
};

The only wrapped method will be the lvalue ref-qualified method m1 and if SWIG is run with the -Wextra command-line option, the following warning will be issued indicating m2 is not wrapped:

example.i:7: Warning 405: Method with rvalue ref-qualifier m2(int) && ignored.

If you unignore the method as follows, wrappers for m2 will be generated:

%feature("ignore", "0") RQ::m2(int x) &&;
struct RQ {
  void m1(int x) &;
  void m2(int x) &&;
};

Inspection of the generated C++ code, will show that std::move is used on the instance of the RQ * class:

  RQ *arg1 = (RQ *) 0 ;
  int arg2 ;

  arg1 = ...marshalled from target language...
  arg2 = ...marshalled from target language...

  std::move(*arg1).m2(arg2);

This will compile but when run, the move effects may not be what you want. As stated earlier, rvalue ref-qualifiers aren't really applicable outside the world of C++. However, if you really know what you are doing, full control over the call to the method is possible via the low-level "action" feature. This feature completely replaces the call to the underlying function, that is, the last line in the snippet of code above.

%feature("ignore", "0") RQ::m2(int x) &&;
%feature("action") RQ::m2(int x) && %{
  RQ().m2(arg2);
%}
struct RQ {
  void m1(int x) &;
  void m2(int x) &&;
};

resulting in:

  RQ *arg1 = (RQ *) 0 ;
  int arg2 ;

  arg1 = ...marshalled from target language...
  arg2 = ...marshalled from target language...

  RQ().m2(arg2);

Compatibility note: SWIG-4.0.0 was the first version to support ref-qualifiers.

7.3 Standard library changes

7.3.1 Threading facilities

SWIG does not currently wrap or use any of the new threading classes introduced (thread, mutex, locks, condition variables, task). The main reason is that SWIG target languages offer their own threading facilities so there is limited use for them.

7.3.2 Tuple types

SWIG does not provide library files for the new tuple types yet. Variadic template support requires further work to provide substantial tuple wrappers.

7.3.3 Hash tables

The new hash tables in the STL are unordered_set, unordered_multiset, unordered_map, unordered_multimap . These are not available in all target languages. Any missing support can in principle be easily implemented by adapting the current STL containers.

7.3.4 Regular expressions

While SWIG could provide wrappers for the new C++11 regular expressions classes, there is little need as the target languages have their own regular expression facilities.

7.3.5 General-purpose smart pointers

SWIG provides special smart pointer handling for std::shared_ptr in the same way it has support for boost::shared_ptr. Please see the shared_ptr smart pointer and unique_ptr smart pointer library sections. There is no special smart pointer handling available for std::weak_ptr.

7.3.6 Extensible random number facility

This feature extends and standardizes the standard library only and does not affect the C++ language nor SWIG.

7.3.7 Wrapper reference

Wrapper references are similar to normal C++ references but are copy-constructible and copy-assignable. They could conceivably be used in public APIs. There is no special support for std::reference_wrapper in SWIG though. Users would need to write their own typemaps if wrapper references are being used and these would be similar to the plain C++ reference typemaps.

7.3.8 Polymorphic wrappers for function objects

SWIG supports functor classes in a few languages in a very natural way. However nothing is provided yet for the new std::function template. SWIG will parse usage of the template like any other template.

%rename(__call__) Test::operator(); // Default renaming used for Python

struct Test {
  bool operator()(int x, int y); // function object
};

#include <functional>
std::function<void (int, int)> pF = Test;   // function template wrapper

Example of supported usage of the plain functor from Python is shown below. It does not involve std::function.

t = Test()
b = t(1, 2) # invoke C++ function object

7.3.9 Type traits for metaprogramming

The type_traits functions to support C++ metaprogramming is useful at compile time and is aimed specifically at C++ development:

#include <type_traits>

// First way of operating.
template< bool B > struct algorithm {
  template< class T1, class T2 > static int do_it(T1 &, T2 &)  { /*...*/ return 1; }
};

// Second way of operating.
template<> struct algorithm<true> {
  template< class T1, class T2 > static int do_it(T1, T2)  { /*...*/ return 2; }
};

// Instantiating 'elaborate' will automatically instantiate the correct way to operate, depending on the types used.
template< class T1, class T2 > int elaborate(T1 A, T2 B) {
  // Use the second way only if 'T1' is an integer and if 'T2' is a floating point,
  // otherwise use the first way.
  return algorithm< std::is_integral<T1>::value && std::is_floating_point<T2>::value >::do_it(A, B);
}

SWIG correctly parses the template specialization, template types etc. However, metaprogramming and the additional support in the type_traits header is really for compile time and is not much use at runtime for the target languages. For example, as SWIG requires explicit instantiation of templates via %template, there isn't much that std::is_integral<int> is going to provide by itself. However, template functions using such metaprogramming techniques might be useful to wrap. For example, the following instantiations could be made:

%template(Elaborate) elaborate<int, int>;
%template(Elaborate) elaborate<int, double>;

Then the appropriate algorithm can be called for the subset of types given by the above %template instantiations from a target language, such as Python:

>>> Elaborate(0, 0)
1
>>> Elaborate(0, 0.0)
2

7.3.10 Uniform method for computing return type of function objects

The new std::result_of class introduced in the <functional> header provides a generic way to obtain the return type of a function type via std::result_of::type. There isn't any library interface file to support this type. With a bit of work, SWIG will deduce the return type of functions when used in std::result_of using the approach shown below. The technique basically forward declares the std::result_of template class, then partially specializes it for the function types of interest. SWIG will use the partial specialization and hence correctly use the std::result_of::type provided in the partial specialization.

%inline %{
#include <functional>
typedef double(*fn_ptr)(double);
%}

namespace std {
  // Forward declaration of result_of
  template<typename Func> struct result_of;
  // Add in a partial specialization of result_of
  template<> struct result_of< fn_ptr(double) > {
    typedef double type;
  };
}

%template() std::result_of< fn_ptr(double) >;

%inline %{

double square(double x) {
  return (x * x);
}

template<class Fun, class Arg>
typename std::result_of<Fun(Arg)>::type test_result_impl(Fun fun, Arg arg) {
  return fun(arg);
}
%}

%template(test_result) test_result_impl< fn_ptr, double >;
%constant double (*SQUARE)(double) = square;

Note the first use of %template which SWIG requires to instantiate the template. The empty template instantiation suffices as no proxy class is required for std::result_of<Fun(Arg)>::type as this type is really just a double. The second %template instantiates the template function which is being wrapped for use as a callback. The %constant can then be used for any callback function as described in Pointers to functions and callbacks.

Example usage from Python should give the not too surprising result:

>>> test_result(SQUARE, 5.0)
25.0

Phew, that is a lot of hard work to get a callback working. You could just go with the more attractive option of just using double as the return type in the function declaration instead of result_of !

8 SWIG and C++14

8.1 Introduction

This chapter gives you a brief overview about the SWIG implementation of the C++14 standard. There isn't much in C++14 that affects SWIG, however, work has only just begun on adding C++14 support.

Compatibility note: SWIG-4.0.0 is the first version to support any C++14 features.

8.2 Core language changes

8.2.1 Binary integer literals

C++14 added binary integer literals and SWIG supports these. Example:

int b = 0b101011;

8.2.2 Return type deduction

C++14 added the ability to specify auto 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 auto for the return type).

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.

The trick for specifying the return type is to use %ignore 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:

std::tuple<int, int> va_static_cast();
%ignore va_static_cast();
#pragma SWIG nowarn=SWIGWARN_CPP14_AUTO

%inline %{
#include <tuple>

auto va_static_cast() {
    return std::make_tuple(0, 0);
}
%}

For member methods the trick is to use %extend to redeclare the method and call it as follows:

%extend X {
  const char * a() const { return $self->a(); }
}
%inline %{
struct X {
  auto a() const {
    return "a string";
  }
};
%}

Compatibility note: SWIG-4.2.0 first introduced support for functions declared with an auto return without a trailing return type.

8.3 Standard library changes

9 SWIG and C++17

9.1 Introduction

This chapter gives you a brief overview about the SWIG implementation of the C++17 standard. There isn't much in C++17 that affects SWIG, however, work has only just begun on adding C++17 support.

Compatibility note: SWIG-4.0.0 is the first version to support any C++17 features.

9.2 Core language changes

9.2.1 Nested namespace definitions

C++17 offers a more concise syntax for defining namespaces. SWIG has support for nested namespace definitions such as:

namespace A::B::C {
  ...
}

This is the equivalent to the C++98 namespace definitions:

namespace A {
  namespace B {
    namespace C {
      ...
    }
  }
}

9.2.2 UTF-8 character literals

C++17 added UTF-8 (u8) character literals. These are of type char. Example:

char a = u8'a';

9.2.3 Hexadecimal floating literals

C++17 added hexadecimal floating literals. For example:

double f = 0xF.68p2;

9.3 Standard library changes

10 SWIG and C++20

10.1 Introduction

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.

Compatibility note: SWIG-4.1.0 is the first version to support any C++20 features.

10.2 Core language changes

10.2.1 Spaceship operator

SWIG supports the spaceship operator <=> in constant expressions. To simplify handling of the return value type, it is currently treated as an integer rather than std::strong_ordering , etc. In practice we think that should do the right thing in most cases.

SWIG also recognises operator<=> 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.

10.2.2 Lambda templates

SWIG should parse lambda templates, but like non-templated lambdas they aren't currently wrapped.

10.2.3 Constexpr destructors

Destructors that are declared constexpr are parsed and handled like any other constructor. For example:

class DtorA {
public:
  constexpr ~DtorA() {}
};

10.3 Standard library changes

11 Preprocessing

SWIG includes its own enhanced version of the C preprocessor. The preprocessor supports the standard preprocessor directives and macro expansion rules. However, a number of modifications and enhancements have been made. This chapter describes some of these modifications.

11.1 File inclusion

To include another file into a SWIG interface, use the %include directive like this:

%include "cpointer.i"

Unlike, #include, %include includes each file once (and will not reload the file on subsequent %include declarations). Therefore, it is not necessary to use include-guards in SWIG interfaces.

By default, the #include is ignored unless you run SWIG with the -includeall option. The reason for ignoring traditional includes is that you often don't want SWIG to try and wrap everything included in standard header system headers and auxiliary files.

11.2 File imports

SWIG provides another file inclusion directive with the %import directive. For example:

%import "foo.i"

The purpose of %import is to collect certain information from another SWIG interface file or a header file without actually generating any wrapper code. Such information generally includes type declarations (e.g., typedef) as well as C++ classes that might be used as base-classes for class declarations in the interface. The use of %import is also important when SWIG is used to generate extensions as a collection of related modules. This is an advanced topic and is described in later in the Working with Modules chapter.

The -importall directive tells SWIG to follow all #include statements as imports. This might be useful if you want to extract type definitions from system header files without generating any wrappers.

11.3 Conditional Compilation

SWIG fully supports the use of #if, #ifdef, #ifndef, #else, #endif to conditionally include parts of an interface.

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:

#if defined __cplusplus && (#__VA_ARGS__ != "" || #TYPE == "void")

The following symbols are predefined by SWIG when it is parsing the interface:

SWIG                            Always defined when SWIG is processing a file
SWIGIMPORTED                    Defined when SWIG is importing a file with %import
SWIG_VERSION                    Hexadecimal (binary-coded decimal) number containing SWIG version,
                                such as 0x010311 (corresponding to SWIG-1.3.11).

SWIGCSHARP                      Defined when using C#
SWIGD                           Defined when using D
SWIGGO                          Defined when using Go
SWIGGUILE                       Defined when using Guile
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 PHP 7 or later (with a compatible C API)
SWIGPYTHON                      Defined when using Python
SWIGR                           Defined when using R
SWIGRUBY                        Defined when using Ruby
SWIGSCILAB                      Defined when using Scilab
SWIGTCL                         Defined when using Tcl
SWIGXML                         Defined when using XML

SWIG also defines SWIG_VERSION 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.

In addition, SWIG defines the following set of standard C/C++ macros:

__LINE__                        Current line number
__FILE__                        Current file name
__STDC__                        Defined to indicate ISO C/C++
__cplusplus                     Defined when -c++ option used, value controlled by -std=c++NN
__STDC_VERSION__                May be defined when -c++ option is not used, value controlled by -std=cNN

Since SWIG 4.2.0, __STDC__ is defined to 1 to match the behaviour of ISO C/C++ compilers. Before this SWIG defined it to have an empty value.

Since SWIG 4.2.0, __cplusplus is defined to 199711L (the value for C++98) by default. Before this SWIG always defined it to have the value __cplusplus.

Since SWIG 4.2.0, SWIG supports command line options -std=cNN and -std=c++NN to specify the C/C++ standards version. The only effect of these options is to set appropriate values for __STDC_VERSION__ and __cplusplus respectively, which is useful if you're wrapping headers which have preprocessor checks based on their values.

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:

#undef __cplusplus
#define __cplusplus 202211L

The following are language specific symbols that might be defined:

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_BUILTIN              Defined when using Python with -builtin
SWIG_RUBY_AUTORENAME            Defined when using Ruby with -autorename

Interface files can look at these symbols as necessary to change the way in which an interface is generated or to mix SWIG directives with C code.

11.4 Macro Expansion

Traditional preprocessor macros can be used in SWIG interfaces. Be aware that the #define statement is also used to try and detect constants. Therefore, if you have something like this in your file,

#ifndef FOO_H 1
#define FOO_H 1
...
#endif

you may get some extra constants such as FOO_H showing up in the scripting interface.

More complex macros can be defined in the standard way. For example:

#define EXTERN extern
#ifdef __STDC__
#define ISOC_(args)   (args)
#else
#define ISOC_(args) ()
#endif

The following operators can appear in macro definitions:

• #x
  Converts macro argument x to a string surrounded by double quotes ("x").
• x ## y
  Concatenates x and y together to form xy.
• `x`
  If x is a string surrounded by double quotes, do nothing. Otherwise, turn into a string like #x. This is a non-standard SWIG extension.

11.5 SWIG Macros

SWIG provides an enhanced macro capability with the %define and %enddef directives. For example:

%define ARRAYHELPER(type, name)
%inline %{
type *new_ ## name (int nitems) {
  return (type *) malloc(sizeof(type)*nitems);
}
void delete_ ## name(type *t) {
  free(t);
}
type name ## _get(type *t, int index) {
  return t[index];
}
void name ## _set(type *t, int index, type val) {
  t[index] = val;
}
%}
%enddef

ARRAYHELPER(int, IntArray)
ARRAYHELPER(double, DoubleArray)

The primary purpose of %define is to define large macros of code. Unlike normal C preprocessor macros, it is not necessary to terminate each line with a continuation character (\)--the macro definition extends to the first occurrence of %enddef. Furthermore, when such macros are expanded, they are reparsed through the C preprocessor. Thus, SWIG macros can contain all other preprocessor directives except for nested %define statements.

The SWIG macro capability is a very quick and easy way to generate large amounts of code. In fact, many of SWIG's advanced features and libraries are built using this mechanism (such as C++ template support).

11.6 C99 and GNU Extensions

SWIG-1.3.12 and newer releases support variadic preprocessor macros. For example:

#define DEBUGF(fmt, ...)   fprintf(stderr, fmt, __VA_ARGS__)

When used, any extra arguments to ... are placed into the special variable __VA_ARGS__. This also works with special SWIG macros defined using %define.

SWIG allows a variable number of arguments to be empty. However, this often results in an extra comma (, ) and syntax error in the resulting expansion. For example:

DEBUGF("hello");   --> fprintf(stderr, "hello", );

To get rid of the extra comma, use ## like this:

#define DEBUGF(fmt, ...)   fprintf(stderr, fmt, ##__VA_ARGS__)

SWIG also supports GNU-style variadic macros. For example:

#define DEBUGF(fmt, args...)  fprintf(stdout, fmt, args)

Comment: It's not entirely clear how variadic macros might be useful to 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.

11.7 Preprocessing and delimiters

The preprocessor handles { }, " " and %{ %} delimiters differently.

11.7.1 Preprocessing and %{ ... %} & " ... " delimiters

The SWIG preprocessor does not process any text enclosed in a code block %{ ... %}. Therefore, if you write code like this,

%{
#ifdef NEED_BLAH
int blah() {
  ...
}
#endif
%}

the contents of the %{ ... %} block are copied without modification to the output (including all preprocessor directives).

11.7.2 Preprocessing and { ... } delimiters

SWIG always runs the preprocessor on text appearing inside { ... }. However, sometimes it is desirable to make a preprocessor directive pass through to the output file. For example:

%extend Foo {
  void bar() {
    #ifdef DEBUG
      printf("I'm in bar\n");
    #endif
  }
}

By default, SWIG will interpret the #ifdef DEBUG statement. However, if you really wanted that code to actually go into the wrapper file, prefix the preprocessor directives with % like this:

%extend Foo {
  void bar() {
    %#ifdef DEBUG
      printf("I'm in bar\n");
    %#endif
  }
}

SWIG will strip the extra % and leave the preprocessor directive in the code.

11.8 Preprocessor and Typemaps

Typemaps support a special attribute called noblock where the { ... } delimiters can be used, but the delimiters are not actually generated into the code. The effect is then similar to using "" or %{ %} delimiters but the code is run through the preprocessor. For example:

#define SWIG_macro(CAST) (CAST)$input
%typemap(in) Int {$1= SWIG_macro(int);}

might generate

  {
    arg1=(int)jarg1;
  }

whereas

#define SWIG_macro(CAST) (CAST)$input
%typemap(in, noblock=1) Int {$1= SWIG_macro(int);}

might generate

  arg1=(int)jarg1;

and

#define SWIG_macro(CAST) (CAST)$input
%typemap(in) Int %{$1=SWIG_macro(int);%}

would generate

  arg1=SWIG_macro(int);

11.9 Viewing preprocessor output

Like many compilers, SWIG supports a -E command line option to display the output from the preprocessor. When the -E option is used, SWIG will not generate any wrappers. 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.

11.10 The #error and #warning directives

SWIG supports the commonly used #warning and #error preprocessor directives. The #warning directive will cause SWIG to issue a warning then continue processing. The #error directive will cause SWIG to exit with a fatal error. Example usage:

#error "This is a fatal error message"
#warning "This is a warning message"

The #error behaviour can be made to work like #warning if the -cpperraswarn commandline option is used. Alternatively, the #pragma directive can be used to the same effect, for example:

  /* Modified behaviour: #error does not cause SWIG to exit with error */
  #pragma SWIG cpperraswarn=1
  /* Normal behaviour: #error does cause SWIG to exit with error */
  #pragma SWIG cpperraswarn=0

12 SWIG library

To help build extension modules, SWIG is packaged with a library of support files that you can include in your own interfaces. These files often define new SWIG directives or provide utility functions that can be used to access parts of the standard C and C++ libraries. This chapter provides a reference to the current set of supported library files.

Compatibility note: Older versions of SWIG included a number of library files for manipulating pointers, arrays, and other structures. Most these files are now deprecated and have been removed from the distribution. Alternative libraries provide similar functionality. Please read this chapter carefully if you used the old libraries.

12.1 The %include directive and library search path

Library files are included using the %include directive. When searching for files, directories are searched in the following order:

1. The current directory
2. Directories specified with the -I command line option
3. ./swig_lib
4. SWIG library install location as reported by swig -swiglib, for example /usr/local/share/swig/1.3.30
5. On Windows, a directory Lib relative to the location of swig.exe is also searched.

Within directories mentioned in points 3-5, SWIG first looks for a subdirectory corresponding to a target language (e.g., python, tcl, etc.). If found, SWIG will search the language specific directory first. This allows for language-specific implementations of library files.

You can ignore the installed SWIG library by setting the SWIG_LIB environment variable. Set the environment variable to hold an alternative library directory.

The directories that are searched are displayed when using -verbose commandline option.

12.2 C arrays and pointers

This section describes library modules for manipulating low-level C arrays and pointers. The primary use of these modules is in supporting C declarations that manipulate bare pointers such as int *, double *, or void *. The modules can be used to allocate memory, manufacture pointers, dereference memory, and wrap pointers as class-like objects. Since these functions provide direct access to memory, their use is potentially unsafe and you should exercise caution.

12.2.1 argcargv.i

The argcargv.i library is a simple library providing multi-argument typemaps for handling C argc argv command line argument C string arrays. The argc parameter contains the argument count and argv contains the argument vector array.

This library provides the following multi-argument typemap:

(int ARGC, char **ARGV)

Apply this multi-argument typemap to your use case, for example:

%apply (int ARGC, char **ARGV) { (size_t argc, const char **argv) }

int mainApp(size_t argc, const char **argv);

then from Ruby:

$args = ["myarg1", "myarg2"]
mainApp(args);

12.2.2 cpointer.i

The cpointer.i module defines macros that can be used to used to generate wrappers around simple C pointers. The primary use of this module is in generating pointers to primitive datatypes such as int and double.

%pointer_functions(type, name)