SWIG-1.3 Documentation

Table of Contents

• Sections
• SWIG Core Documentation
• Language Module Documentation
• Developer Documentation
• Documentation that has not yet been updated

• 1.1 Introduction
• 1.2 Special Introduction for Version 1.3
• 1.3 SWIG Versions
• 1.4 SWIG resources
• 1.5 Prerequisites
• 1.6 Organization of this manual
• 1.7 How to avoid reading the manual
• 1.8 Backwards Coattach_header(char *hstr); In the target language:

  >>> make_upper("hello world")
  'HELLO WORLD'
  >>> attach_header("Hello world")
  'header: Hello world'
  >>>
  

  This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

  %cstring_output_maxsize(parm, maxparm)

  This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

  %cstring_output_maxsize(char *path, int maxpath);
  ...
  void get_path(char *path, int maxpath);
  

  In the target language:

  >>> get_path(1024)
  '/home/beazley/Packages/Foo/Bar'
  >>>
  

  This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

  %cstring_output_withsize(parm, maxparm)

  This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

  %cstring_output_withsize(char *data, int *maxdata);
  ...
  void get_data(char *data, int *maxdata);
  

  In the target language:

  >>> get_data(1024)
  'x627388912'
  >>> get_data(1024)
  'xyzzy'
  >>>
  

  This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

  %cstring_output_allocate(parm, release)

  This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

  void foo(char **s) {
      *s = (char *) malloc(64);
      sprintf(*s, "Hello world\n");
  }
  

  The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

  %cstring_output_allocate(char **s, free(*$1));
  ...
  void foo(char **s);
  

  In the target language:

  >>> foo()
  'Hello world\n'
  >>>
  

  %cstring_output_allocate_size(parm, szparm, release)

  This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

  void foo(char **s, int *sz) {
      *s = (char *) malloc(64);
      *sz = 64;
      // Write some binary data
      ...
  }
  

  The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

  %cstring_output_allocate_size(char **s, int *slen, free(*$1));
  ...
  void foo(char **s, int *slen);
  

  In the target language:

  >>> foo()
  '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
  >>>
  

  This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

  char  *get_data(int *len);
  

  You could wrap it with a function like this:

  void my_get_data(char **result, int *len) {
     *result = get_data(len);
  }
  

  Comments:
  • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
  • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
  • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
  • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

  8.4 C++ Library

  The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

  8.4.1 std_string.i

  The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

  %module example
  %include "std_string.i"
  
  std::string foo();
  void        bar(const std::string &x);
  

  In the target language:

  x = foo();                # Returns a string object
  bar("Hello World");       # Pass string as std::string
  

  This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

  This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

  %module example
  %include "std_string.i"
  
  using namespace std;
  typedef std::string String;
  ...
  void foo(string s, const String &t);     // std_string typemaps still applied
  

  Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

  8.4.2 std_vector.i

  The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

  %module example
  %include "std_vector.i"
  
  namespace std {
     %template(vectori) vector<int>;
     %template(vectord) vector<double>;
  };
  

  When a template vector<X> is instantiated a number of things happen:
  • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
  • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
  • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
  • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
  • An exception handler for std::out_of_range is defined.
  • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
  To illustrate the use of this library, consider the following functions:

  /* File : example.h */
  
  #include <vector>
  #include <algorithm>
  #include <functional>
  #include <numeric>
  
  double average(std::vector<int> v) {
      return std::accumulate(v.begin(),v.end(),0.0)/v.size();
  }
  
  std::vector<double> half(const std::vector<double>& v) {
      std::vector<double> w(v);
      for (unsigned int i=0; i<w.size(); i++)
          w[i] /= 2.0;
      return w;
  }
  
  void halve_in_place(std::vector<double>& v) {
      std::transform(v.begin(),v.end(),v.begin(),
                     std::bind2nd(std::divides<double>(),2.0));
  }
  

  To wrap with SWIG, you might write the following:

  %module example
  %{
  #include "example.h"
  %}
  
  %include "std_vector.i"
  // Instantiate templates used by example
  namespace std {
     %template(IntVector) vector<int>;
     %template(DoubleVector) vector<double>;
  }
  
  // Include the header file with above prototypes
  %include "example.h"
  

  Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

  >>> from example import *
  >>> iv = IntVector(4)         # Create an vector<int>
  >>> for i in range(0,4):
  ...      iv[i] = i
  >>> average(iv)               # Call method
  1.5
  >>> average([0,1,2,3])        # Call with list
  1.5
  >>> half([1,2,3])             # Half a list
  (0.5,1.0,1.5)
  >>> halve_in_place([1,2,3])   # Oops
  Traceback (most recent call last):
    File "<stdin>", line 1, in ?
  TypeError: Type error. Expected _p_std__vectorTdouble_t
  >>> dv = DoubleVector(4)
  >>> for i in range(0,4):
  ...       dv[i] = i
  >>> halve_in_place(dv)       # Ok
  >>> for i in dv:
  ...       print i
  ...
  0.0
  0.5
  1.0
  1.5
  >>> dv[20] = 4.5
  Traceback (most recent call last):
    File "<stdin>", line 1, in ?
    File "example.py", line 81, in __setitem__
      def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
  IndexError: vector index out of range
  >>>
  

  This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

  %include "std_vector.i"
  
  namespace std {
      %template(IntVector) vector<int>;
  }
  
  using namespace std;
  typedef std::vector Vector;
  
  void foo(vector<int> *x, const Vector &x);
  

  Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

  Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

  Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

  8.5 Utility Libraries

  8.5.1 exception.i

  The exception.i library provides a language-independent function for raising a run-time exception in the target language.

  SWIG_exception(int code, const char *message)

  Raises an exception in the target language. code is one of the following symbolic constants:

  SWIG_MemoryError
  SWIG_IOError
  SWIG_RuntimeError
  SWIG_IndexError
  SWIG_TypeError
  SWIG_DivisionByZero
  SWIG_OverflowError
  SWIG_SyntaxError
  SWIG_ValueError
  SWIG_SystemError
  

  message is a string indicating more information about the problem.

  The primary use of this module is in writing language-independent exception handlers. For example:

  %include "exception.i"
  %exception std::vector::getitem {
      try {
          $action
      } catch (std::out_of_range& e) {
          SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
      }
  }
  

  ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
  

  SWIG-1.3 Documentation

  
  

  ---

  Table of Contents

  
  
  SWIG-1.3 Development Documentation
  • Sections
  • SWIG Core Documentation
  • Language Module Documentation
  • Developer Documentation
  • Documentation that has not yet been updated
  1 Preface
  • 1.1 Introduction
  • 1.2 Special Introduction for Version 1.3
  • 1.3 SWIG Versions
  • 1.4 SWIG resources
  • 1.5 Prerequisites
  • 1.6 Organization of this manual
  • 1.7 How to avoid reading the manual
  • 1.8 Backwards Coattach_header(char *hstr); In the target language:

    >>> make_upper("hello world")
    'HELLO WORLD'
    >>> attach_header("Hello world")
    'header: Hello world'
    >>>
    

    This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

    %cstring_output_maxsize(parm, maxparm)

    This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

    %cstring_output_maxsize(char *path, int maxpath);
    ...
    void get_path(char *path, int maxpath);
    

    In the target language:

    >>> get_path(1024)
    '/home/beazley/Packages/Foo/Bar'
    >>>
    

    This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

    %cstring_output_withsize(parm, maxparm)

    This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

    %cstring_output_withsize(char *data, int *maxdata);
    ...
    void get_data(char *data, int *maxdata);
    

    In the target language:

    >>> get_data(1024)
    'x627388912'
    >>> get_data(1024)
    'xyzzy'
    >>>
    

    This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

    %cstring_output_allocate(parm, release)

    This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

    void foo(char **s) {
        *s = (char *) malloc(64);
        sprintf(*s, "Hello world\n");
    }
    

    The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

    %cstring_output_allocate(char **s, free(*$1));
    ...
    void foo(char **s);
    

    In the target language:

    >>> foo()
    'Hello world\n'
    >>>
    

    %cstring_output_allocate_size(parm, szparm, release)

    This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

    void foo(char **s, int *sz) {
        *s = (char *) malloc(64);
        *sz = 64;
        // Write some binary data
        ...
    }
    

    The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

    %cstring_output_allocate_size(char **s, int *slen, free(*$1));
    ...
    void foo(char **s, int *slen);
    

    In the target language:

    >>> foo()
    '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
    >>>
    

    This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

    char  *get_data(int *len);
    

    You could wrap it with a function like this:

    void my_get_data(char **result, int *len) {
       *result = get_data(len);
    }
    

    Comments:
    • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
    • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
    • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
    • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

    8.4 C++ Library

    The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

    8.4.1 std_string.i

    The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

    %module example
    %include "std_string.i"
    
    std::string foo();
    void        bar(const std::string &x);
    

    In the target language:

    x = foo();                # Returns a string object
    bar("Hello World");       # Pass string as std::string
    

    This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

    This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

    %module example
    %include "std_string.i"
    
    using namespace std;
    typedef std::string String;
    ...
    void foo(string s, const String &t);     // std_string typemaps still applied
    

    Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

    8.4.2 std_vector.i

    The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

    %module example
    %include "std_vector.i"
    
    namespace std {
       %template(vectori) vector<int>;
       %template(vectord) vector<double>;
    };
    

    When a template vector<X> is instantiated a number of things happen:
    • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
    • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
    • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
    • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
    • An exception handler for std::out_of_range is defined.
    • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
    To illustrate the use of this library, consider the following functions:

    /* File : example.h */
    
    #include <vector>
    #include <algorithm>
    #include <functional>
    #include <numeric>
    
    double average(std::vector<int> v) {
        return std::accumulate(v.begin(),v.end(),0.0)/v.size();
    }
    
    std::vector<double> half(const std::vector<double>& v) {
        std::vector<double> w(v);
        for (unsigned int i=0; i<w.size(); i++)
            w[i] /= 2.0;
        return w;
    }
    
    void halve_in_place(std::vector<double>& v) {
        std::transform(v.begin(),v.end(),v.begin(),
                       std::bind2nd(std::divides<double>(),2.0));
    }
    

    To wrap with SWIG, you might write the following:

    %module example
    %{
    #include "example.h"
    %}
    
    %include "std_vector.i"
    // Instantiate templates used by example
    namespace std {
       %template(IntVector) vector<int>;
       %template(DoubleVector) vector<double>;
    }
    
    // Include the header file with above prototypes
    %include "example.h"
    

    Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

    >>> from example import *
    >>> iv = IntVector(4)         # Create an vector<int>
    >>> for i in range(0,4):
    ...      iv[i] = i
    >>> average(iv)               # Call method
    1.5
    >>> average([0,1,2,3])        # Call with list
    1.5
    >>> half([1,2,3])             # Half a list
    (0.5,1.0,1.5)
    >>> halve_in_place([1,2,3])   # Oops
    Traceback (most recent call last):
      File "<stdin>", line 1, in ?
    TypeError: Type error. Expected _p_std__vectorTdouble_t
    >>> dv = DoubleVector(4)
    >>> for i in range(0,4):
    ...       dv[i] = i
    >>> halve_in_place(dv)       # Ok
    >>> for i in dv:
    ...       print i
    ...
    0.0
    0.5
    1.0
    1.5
    >>> dv[20] = 4.5
    Traceback (most recent call last):
      File "<stdin>", line 1, in ?
      File "example.py", line 81, in __setitem__
        def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
    IndexError: vector index out of range
    >>>
    

    This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

    %include "std_vector.i"
    
    namespace std {
        %template(IntVector) vector<int>;
    }
    
    using namespace std;
    typedef std::vector Vector;
    
    void foo(vector<int> *x, const Vector &x);
    

    Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

    Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

    Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

    8.5 Utility Libraries

    8.5.1 exception.i

    The exception.i library provides a language-independent function for raising a run-time exception in the target language.

    SWIG_exception(int code, const char *message)

    Raises an exception in the target language. code is one of the following symbolic constants:

    SWIG_MemoryError
    SWIG_IOError
    SWIG_RuntimeError
    SWIG_IndexError
    SWIG_TypeError
    SWIG_DivisionByZero
    SWIG_OverflowError
    SWIG_SyntaxError
    SWIG_ValueError
    SWIG_SystemError
    

    message is a string indicating more information about the problem.

    The primary use of this module is in writing language-independent exception handlers. For example:

    %include "exception.i"
    %exception std::vector::getitem {
        try {
            $action
        } catch (std::out_of_range& e) {
            SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
        }
    }
    

    ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
    

    SWIG-1.3 Documentation

    
    

    ---

    Table of Contents

    
    
    SWIG-1.3 Development Documentation
    • Sections
    • SWIG Core Documentation
    • Language Module Documentation
    • Developer Documentation
    • Documentation that has not yet been updated
    1 Preface
    • 1.1 Introduction
    • 1.2 Special Introduction for Version 1.3
    • 1.3 SWIG Versions
    • 1.4 SWIG resources
    • 1.5 Prerequisites
    • 1.6 Organization of this manual
    • 1.7 How to avoid reading the manual
    • 1.8 Backwards Coattach_header(char *hstr); In the target language:

      >>> make_upper("hello world")
      'HELLO WORLD'
      >>> attach_header("Hello world")
      'header: Hello world'
      >>>
      

      This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

      %cstring_output_maxsize(parm, maxparm)

      This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

      %cstring_output_maxsize(char *path, int maxpath);
      ...
      void get_path(char *path, int maxpath);
      

      In the target language:

      >>> get_path(1024)
      '/home/beazley/Packages/Foo/Bar'
      >>>
      

      This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

      %cstring_output_withsize(parm, maxparm)

      This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

      %cstring_output_withsize(char *data, int *maxdata);
      ...
      void get_data(char *data, int *maxdata);
      

      In the target language:

      >>> get_data(1024)
      'x627388912'
      >>> get_data(1024)
      'xyzzy'
      >>>
      

      This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

      %cstring_output_allocate(parm, release)

      This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

      void foo(char **s) {
          *s = (char *) malloc(64);
          sprintf(*s, "Hello world\n");
      }
      

      The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

      %cstring_output_allocate(char **s, free(*$1));
      ...
      void foo(char **s);
      

      In the target language:

      >>> foo()
      'Hello world\n'
      >>>
      

      %cstring_output_allocate_size(parm, szparm, release)

      This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

      void foo(char **s, int *sz) {
          *s = (char *) malloc(64);
          *sz = 64;
          // Write some binary data
          ...
      }
      

      The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

      %cstring_output_allocate_size(char **s, int *slen, free(*$1));
      ...
      void foo(char **s, int *slen);
      

      In the target language:

      >>> foo()
      '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
      >>>
      

      This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

      char  *get_data(int *len);
      

      You could wrap it with a function like this:

      void my_get_data(char **result, int *len) {
         *result = get_data(len);
      }
      

      Comments:
      • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
      • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
      • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
      • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

      8.4 C++ Library

      The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

      8.4.1 std_string.i

      The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

      %module example
      %include "std_string.i"
      
      std::string foo();
      void        bar(const std::string &x);
      

      In the target language:

      x = foo();                # Returns a string object
      bar("Hello World");       # Pass string as std::string
      

      This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

      This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

      %module example
      %include "std_string.i"
      
      using namespace std;
      typedef std::string String;
      ...
      void foo(string s, const String &t);     // std_string typemaps still applied
      

      Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

      8.4.2 std_vector.i

      The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

      %module example
      %include "std_vector.i"
      
      namespace std {
         %template(vectori) vector<int>;
         %template(vectord) vector<double>;
      };
      

      When a template vector<X> is instantiated a number of things happen:
      • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
      • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
      • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
      • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
      • An exception handler for std::out_of_range is defined.
      • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
      To illustrate the use of this library, consider the following functions:

      /* File : example.h */
      
      #include <vector>
      #include <algorithm>
      #include <functional>
      #include <numeric>
      
      double average(std::vector<int> v) {
          return std::accumulate(v.begin(),v.end(),0.0)/v.size();
      }
      
      std::vector<double> half(const std::vector<double>& v) {
          std::vector<double> w(v);
          for (unsigned int i=0; i<w.size(); i++)
              w[i] /= 2.0;
          return w;
      }
      
      void halve_in_place(std::vector<double>& v) {
          std::transform(v.begin(),v.end(),v.begin(),
                         std::bind2nd(std::divides<double>(),2.0));
      }
      

      To wrap with SWIG, you might write the following:

      %module example
      %{
      #include "example.h"
      %}
      
      %include "std_vector.i"
      // Instantiate templates used by example
      namespace std {
         %template(IntVector) vector<int>;
         %template(DoubleVector) vector<double>;
      }
      
      // Include the header file with above prototypes
      %include "example.h"
      

      Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

      >>> from example import *
      >>> iv = IntVector(4)         # Create an vector<int>
      >>> for i in range(0,4):
      ...      iv[i] = i
      >>> average(iv)               # Call method
      1.5
      >>> average([0,1,2,3])        # Call with list
      1.5
      >>> half([1,2,3])             # Half a list
      (0.5,1.0,1.5)
      >>> halve_in_place([1,2,3])   # Oops
      Traceback (most recent call last):
        File "<stdin>", line 1, in ?
      TypeError: Type error. Expected _p_std__vectorTdouble_t
      >>> dv = DoubleVector(4)
      >>> for i in range(0,4):
      ...       dv[i] = i
      >>> halve_in_place(dv)       # Ok
      >>> for i in dv:
      ...       print i
      ...
      0.0
      0.5
      1.0
      1.5
      >>> dv[20] = 4.5
      Traceback (most recent call last):
        File "<stdin>", line 1, in ?
        File "example.py", line 81, in __setitem__
          def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
      IndexError: vector index out of range
      >>>
      

      This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

      %include "std_vector.i"
      
      namespace std {
          %template(IntVector) vector<int>;
      }
      
      using namespace std;
      typedef std::vector Vector;
      
      void foo(vector<int> *x, const Vector &x);
      

      Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

      Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

      Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

      8.5 Utility Libraries

      8.5.1 exception.i

      The exception.i library provides a language-independent function for raising a run-time exception in the target language.

      SWIG_exception(int code, const char *message)

      Raises an exception in the target language. code is one of the following symbolic constants:

      SWIG_MemoryError
      SWIG_IOError
      SWIG_RuntimeError
      SWIG_IndexError
      SWIG_TypeError
      SWIG_DivisionByZero
      SWIG_OverflowError
      SWIG_SyntaxError
      SWIG_ValueError
      SWIG_SystemError
      

      message is a string indicating more information about the problem.

      The primary use of this module is in writing language-independent exception handlers. For example:

      %include "exception.i"
      %exception std::vector::getitem {
          try {
              $action
          } catch (std::out_of_range& e) {
              SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
          }
      }
      

      ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
      

      SWIG-1.3 Documentation

      
      

      ---

      Table of Contents

      
      
      SWIG-1.3 Development Documentation
      • Sections
      • SWIG Core Documentation
      • Language Module Documentation
      • Developer Documentation
      • Documentation that has not yet been updated
      1 Preface
      • 1.1 Introduction
      • 1.2 Special Introduction for Version 1.3
      • 1.3 SWIG Versions
      • 1.4 SWIG resources
      • 1.5 Prerequisites
      • 1.6 Organization of this manual
      • 1.7 How to avoid reading the manual
      • 1.8 Backwards Coattach_header(char *hstr); In the target language:

        >>> make_upper("hello world")
        'HELLO WORLD'
        >>> attach_header("Hello world")
        'header: Hello world'
        >>>
        

        This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

        %cstring_output_maxsize(parm, maxparm)

        This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

        %cstring_output_maxsize(char *path, int maxpath);
        ...
        void get_path(char *path, int maxpath);
        

        In the target language:

        >>> get_path(1024)
        '/home/beazley/Packages/Foo/Bar'
        >>>
        

        This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

        %cstring_output_withsize(parm, maxparm)

        This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

        %cstring_output_withsize(char *data, int *maxdata);
        ...
        void get_data(char *data, int *maxdata);
        

        In the target language:

        >>> get_data(1024)
        'x627388912'
        >>> get_data(1024)
        'xyzzy'
        >>>
        

        This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

        %cstring_output_allocate(parm, release)

        This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

        void foo(char **s) {
            *s = (char *) malloc(64);
            sprintf(*s, "Hello world\n");
        }
        

        The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

        %cstring_output_allocate(char **s, free(*$1));
        ...
        void foo(char **s);
        

        In the target language:

        >>> foo()
        'Hello world\n'
        >>>
        

        %cstring_output_allocate_size(parm, szparm, release)

        This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

        void foo(char **s, int *sz) {
            *s = (char *) malloc(64);
            *sz = 64;
            // Write some binary data
            ...
        }
        

        The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

        %cstring_output_allocate_size(char **s, int *slen, free(*$1));
        ...
        void foo(char **s, int *slen);
        

        In the target language:

        >>> foo()
        '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
        >>>
        

        This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

        char  *get_data(int *len);
        

        You could wrap it with a function like this:

        void my_get_data(char **result, int *len) {
           *result = get_data(len);
        }
        

        Comments:
        • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
        • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
        • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
        • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

        8.4 C++ Library

        The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

        8.4.1 std_string.i

        The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

        %module example
        %include "std_string.i"
        
        std::string foo();
        void        bar(const std::string &x);
        

        In the target language:

        x = foo();                # Returns a string object
        bar("Hello World");       # Pass string as std::string
        

        This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

        This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

        %module example
        %include "std_string.i"
        
        using namespace std;
        typedef std::string String;
        ...
        void foo(string s, const String &t);     // std_string typemaps still applied
        

        Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

        8.4.2 std_vector.i

        The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

        %module example
        %include "std_vector.i"
        
        namespace std {
           %template(vectori) vector<int>;
           %template(vectord) vector<double>;
        };
        

        When a template vector<X> is instantiated a number of things happen:
        • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
        • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
        • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
        • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
        • An exception handler for std::out_of_range is defined.
        • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
        To illustrate the use of this library, consider the following functions:

        /* File : example.h */
        
        #include <vector>
        #include <algorithm>
        #include <functional>
        #include <numeric>
        
        double average(std::vector<int> v) {
            return std::accumulate(v.begin(),v.end(),0.0)/v.size();
        }
        
        std::vector<double> half(const std::vector<double>& v) {
            std::vector<double> w(v);
            for (unsigned int i=0; i<w.size(); i++)
                w[i] /= 2.0;
            return w;
        }
        
        void halve_in_place(std::vector<double>& v) {
            std::transform(v.begin(),v.end(),v.begin(),
                           std::bind2nd(std::divides<double>(),2.0));
        }
        

        To wrap with SWIG, you might write the following:

        %module example
        %{
        #include "example.h"
        %}
        
        %include "std_vector.i"
        // Instantiate templates used by example
        namespace std {
           %template(IntVector) vector<int>;
           %template(DoubleVector) vector<double>;
        }
        
        // Include the header file with above prototypes
        %include "example.h"
        

        Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

        >>> from example import *
        >>> iv = IntVector(4)         # Create an vector<int>
        >>> for i in range(0,4):
        ...      iv[i] = i
        >>> average(iv)               # Call method
        1.5
        >>> average([0,1,2,3])        # Call with list
        1.5
        >>> half([1,2,3])             # Half a list
        (0.5,1.0,1.5)
        >>> halve_in_place([1,2,3])   # Oops
        Traceback (most recent call last):
          File "<stdin>", line 1, in ?
        TypeError: Type error. Expected _p_std__vectorTdouble_t
        >>> dv = DoubleVector(4)
        >>> for i in range(0,4):
        ...       dv[i] = i
        >>> halve_in_place(dv)       # Ok
        >>> for i in dv:
        ...       print i
        ...
        0.0
        0.5
        1.0
        1.5
        >>> dv[20] = 4.5
        Traceback (most recent call last):
          File "<stdin>", line 1, in ?
          File "example.py", line 81, in __setitem__
            def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
        IndexError: vector index out of range
        >>>
        

        This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

        %include "std_vector.i"
        
        namespace std {
            %template(IntVector) vector<int>;
        }
        
        using namespace std;
        typedef std::vector Vector;
        
        void foo(vector<int> *x, const Vector &x);
        

        Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

        Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

        Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

        8.5 Utility Libraries

        8.5.1 exception.i

        The exception.i library provides a language-independent function for raising a run-time exception in the target language.

        SWIG_exception(int code, const char *message)

        Raises an exception in the target language. code is one of the following symbolic constants:

        SWIG_MemoryError
        SWIG_IOError
        SWIG_RuntimeError
        SWIG_IndexError
        SWIG_TypeError
        SWIG_DivisionByZero
        SWIG_OverflowError
        SWIG_SyntaxError
        SWIG_ValueError
        SWIG_SystemError
        

        message is a string indicating more information about the problem.

        The primary use of this module is in writing language-independent exception handlers. For example:

        %include "exception.i"
        %exception std::vector::getitem {
            try {
                $action
            } catch (std::out_of_range& e) {
                SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
            }
        }
        

        ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
        

        SWIG-1.3 Documentation

        
        

        ---

        Table of Contents

        
        
        SWIG-1.3 Development Documentation
        • Sections
        • SWIG Core Documentation
        • Language Module Documentation
        • Developer Documentation
        • Documentation that has not yet been updated
        1 Preface
        • 1.1 Introduction
        • 1.2 Special Introduction for Version 1.3
        • 1.3 SWIG Versions
        • 1.4 SWIG resources
        • 1.5 Prerequisites
        • 1.6 Organization of this manual
        • 1.7 How to avoid reading the manual
        • 1.8 Backwards Coattach_header(char *hstr); In the target language:

          >>> make_upper("hello world")
          'HELLO WORLD'
          >>> attach_header("Hello world")
          'header: Hello world'
          >>>
          

          This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

          %cstring_output_maxsize(parm, maxparm)

          This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

          %cstring_output_maxsize(char *path, int maxpath);
          ...
          void get_path(char *path, int maxpath);
          

          In the target language:

          >>> get_path(1024)
          '/home/beazley/Packages/Foo/Bar'
          >>>
          

          This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

          %cstring_output_withsize(parm, maxparm)

          This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

          %cstring_output_withsize(char *data, int *maxdata);
          ...
          void get_data(char *data, int *maxdata);
          

          In the target language:

          >>> get_data(1024)
          'x627388912'
          >>> get_data(1024)
          'xyzzy'
          >>>
          

          This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

          %cstring_output_allocate(parm, release)

          This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

          void foo(char **s) {
              *s = (char *) malloc(64);
              sprintf(*s, "Hello world\n");
          }
          

          The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

          %cstring_output_allocate(char **s, free(*$1));
          ...
          void foo(char **s);
          

          In the target language:

          >>> foo()
          'Hello world\n'
          >>>
          

          %cstring_output_allocate_size(parm, szparm, release)

          This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

          void foo(char **s, int *sz) {
              *s = (char *) malloc(64);
              *sz = 64;
              // Write some binary data
              ...
          }
          

          The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

          %cstring_output_allocate_size(char **s, int *slen, free(*$1));
          ...
          void foo(char **s, int *slen);
          

          In the target language:

          >>> foo()
          '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
          >>>
          

          This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

          char  *get_data(int *len);
          

          You could wrap it with a function like this:

          void my_get_data(char **result, int *len) {
             *result = get_data(len);
          }
          

          Comments:
          • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
          • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
          • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
          • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

          8.4 C++ Library

          The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

          8.4.1 std_string.i

          The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

          %module example
          %include "std_string.i"
          
          std::string foo();
          void        bar(const std::string &x);
          

          In the target language:

          x = foo();                # Returns a string object
          bar("Hello World");       # Pass string as std::string
          

          This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

          This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

          %module example
          %include "std_string.i"
          
          using namespace std;
          typedef std::string String;
          ...
          void foo(string s, const String &t);     // std_string typemaps still applied
          

          Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

          8.4.2 std_vector.i

          The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

          %module example
          %include "std_vector.i"
          
          namespace std {
             %template(vectori) vector<int>;
             %template(vectord) vector<double>;
          };
          

          When a template vector<X> is instantiated a number of things happen:
          • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
          • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
          • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
          • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
          • An exception handler for std::out_of_range is defined.
          • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
          To illustrate the use of this library, consider the following functions:

          /* File : example.h */
          
          #include <vector>
          #include <algorithm>
          #include <functional>
          #include <numeric>
          
          double average(std::vector<int> v) {
              return std::accumulate(v.begin(),v.end(),0.0)/v.size();
          }
          
          std::vector<double> half(const std::vector<double>& v) {
              std::vector<double> w(v);
              for (unsigned int i=0; i<w.size(); i++)
                  w[i] /= 2.0;
              return w;
          }
          
          void halve_in_place(std::vector<double>& v) {
              std::transform(v.begin(),v.end(),v.begin(),
                             std::bind2nd(std::divides<double>(),2.0));
          }
          

          To wrap with SWIG, you might write the following:

          %module example
          %{
          #include "example.h"
          %}
          
          %include "std_vector.i"
          // Instantiate templates used by example
          namespace std {
             %template(IntVector) vector<int>;
             %template(DoubleVector) vector<double>;
          }
          
          // Include the header file with above prototypes
          %include "example.h"
          

          Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

          >>> from example import *
          >>> iv = IntVector(4)         # Create an vector<int>
          >>> for i in range(0,4):
          ...      iv[i] = i
          >>> average(iv)               # Call method
          1.5
          >>> average([0,1,2,3])        # Call with list
          1.5
          >>> half([1,2,3])             # Half a list
          (0.5,1.0,1.5)
          >>> halve_in_place([1,2,3])   # Oops
          Traceback (most recent call last):
            File "<stdin>", line 1, in ?
          TypeError: Type error. Expected _p_std__vectorTdouble_t
          >>> dv = DoubleVector(4)
          >>> for i in range(0,4):
          ...       dv[i] = i
          >>> halve_in_place(dv)       # Ok
          >>> for i in dv:
          ...       print i
          ...
          0.0
          0.5
          1.0
          1.5
          >>> dv[20] = 4.5
          Traceback (most recent call last):
            File "<stdin>", line 1, in ?
            File "example.py", line 81, in __setitem__
              def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
          IndexError: vector index out of range
          >>>
          

          This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

          %include "std_vector.i"
          
          namespace std {
              %template(IntVector) vector<int>;
          }
          
          using namespace std;
          typedef std::vector Vector;
          
          void foo(vector<int> *x, const Vector &x);
          

          Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

          Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

          Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

          8.5 Utility Libraries

          8.5.1 exception.i

          The exception.i library provides a language-independent function for raising a run-time exception in the target language.

          SWIG_exception(int code, const char *message)

          Raises an exception in the target language. code is one of the following symbolic constants:

          SWIG_MemoryError
          SWIG_IOError
          SWIG_RuntimeError
          SWIG_IndexError
          SWIG_TypeError
          SWIG_DivisionByZero
          SWIG_OverflowError
          SWIG_SyntaxError
          SWIG_ValueError
          SWIG_SystemError
          

          message is a string indicating more information about the problem.

          The primary use of this module is in writing language-independent exception handlers. For example:

          %include "exception.i"
          %exception std::vector::getitem {
              try {
                  $action
              } catch (std::out_of_range& e) {
                  SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
              }
          }
          

          ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
          

          SWIG-1.3 Documentation

          
          

          ---

          Table of Contents

          
          
          SWIG-1.3 Development Documentation
          • Sections
          • SWIG Core Documentation
          • Language Module Documentation
          • Developer Documentation
          • Documentation that has not yet been updated
          1 Preface
          • 1.1 Introduction
          • 1.2 Special Introduction for Version 1.3
          • 1.3 SWIG Versions
          • 1.4 SWIG resources
          • 1.5 Prerequisites
          • 1.6 Organization of this manual
          • 1.7 How to avoid reading the manual
          • 1.8 Backwards Coattach_header(char *hstr); In the target language:

            >>> make_upper("hello world")
            'HELLO WORLD'
            >>> attach_header("Hello world")
            'header: Hello world'
            >>>
            

            This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

            %cstring_output_maxsize(parm, maxparm)

            This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

            %cstring_output_maxsize(char *path, int maxpath);
            ...
            void get_path(char *path, int maxpath);
            

            In the target language:

            >>> get_path(1024)
            '/home/beazley/Packages/Foo/Bar'
            >>>
            

            This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

            %cstring_output_withsize(parm, maxparm)

            This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

            %cstring_output_withsize(char *data, int *maxdata);
            ...
            void get_data(char *data, int *maxdata);
            

            In the target language:

            >>> get_data(1024)
            'x627388912'
            >>> get_data(1024)
            'xyzzy'
            >>>
            

            This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

            %cstring_output_allocate(parm, release)

            This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

            void foo(char **s) {
                *s = (char *) malloc(64);
                sprintf(*s, "Hello world\n");
            }
            

            The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

            %cstring_output_allocate(char **s, free(*$1));
            ...
            void foo(char **s);
            

            In the target language:

            >>> foo()
            'Hello world\n'
            >>>
            

            %cstring_output_allocate_size(parm, szparm, release)

            This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

            void foo(char **s, int *sz) {
                *s = (char *) malloc(64);
                *sz = 64;
                // Write some binary data
                ...
            }
            

            The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

            %cstring_output_allocate_size(char **s, int *slen, free(*$1));
            ...
            void foo(char **s, int *slen);
            

            In the target language:

            >>> foo()
            '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
            >>>
            

            This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

            char  *get_data(int *len);
            

            You could wrap it with a function like this:

            void my_get_data(char **result, int *len) {
               *result = get_data(len);
            }
            

            Comments:
            • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
            • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
            • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
            • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

            8.4 C++ Library

            The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

            8.4.1 std_string.i

            The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

            %module example
            %include "std_string.i"
            
            std::string foo();
            void        bar(const std::string &x);
            

            In the target language:

            x = foo();                # Returns a string object
            bar("Hello World");       # Pass string as std::string
            

            This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

            This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

            %module example
            %include "std_string.i"
            
            using namespace std;
            typedef std::string String;
            ...
            void foo(string s, const String &t);     // std_string typemaps still applied
            

            Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

            8.4.2 std_vector.i

            The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

            %module example
            %include "std_vector.i"
            
            namespace std {
               %template(vectori) vector<int>;
               %template(vectord) vector<double>;
            };
            

            When a template vector<X> is instantiated a number of things happen:
            • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
            • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
            • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
            • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
            • An exception handler for std::out_of_range is defined.
            • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
            To illustrate the use of this library, consider the following functions:

            /* File : example.h */
            
            #include <vector>
            #include <algorithm>
            #include <functional>
            #include <numeric>
            
            double average(std::vector<int> v) {
                return std::accumulate(v.begin(),v.end(),0.0)/v.size();
            }
            
            std::vector<double> half(const std::vector<double>& v) {
                std::vector<double> w(v);
                for (unsigned int i=0; i<w.size(); i++)
                    w[i] /= 2.0;
                return w;
            }
            
            void halve_in_place(std::vector<double>& v) {
                std::transform(v.begin(),v.end(),v.begin(),
                               std::bind2nd(std::divides<double>(),2.0));
            }
            

            To wrap with SWIG, you might write the following:

            %module example
            %{
            #include "example.h"
            %}
            
            %include "std_vector.i"
            // Instantiate templates used by example
            namespace std {
               %template(IntVector) vector<int>;
               %template(DoubleVector) vector<double>;
            }
            
            // Include the header file with above prototypes
            %include "example.h"
            

            Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

            >>> from example import *
            >>> iv = IntVector(4)         # Create an vector<int>
            >>> for i in range(0,4):
            ...      iv[i] = i
            >>> average(iv)               # Call method
            1.5
            >>> average([0,1,2,3])        # Call with list
            1.5
            >>> half([1,2,3])             # Half a list
            (0.5,1.0,1.5)
            >>> halve_in_place([1,2,3])   # Oops
            Traceback (most recent call last):
              File "<stdin>", line 1, in ?
            TypeError: Type error. Expected _p_std__vectorTdouble_t
            >>> dv = DoubleVector(4)
            >>> for i in range(0,4):
            ...       dv[i] = i
            >>> halve_in_place(dv)       # Ok
            >>> for i in dv:
            ...       print i
            ...
            0.0
            0.5
            1.0
            1.5
            >>> dv[20] = 4.5
            Traceback (most recent call last):
              File "<stdin>", line 1, in ?
              File "example.py", line 81, in __setitem__
                def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
            IndexError: vector index out of range
            >>>
            

            This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

            %include "std_vector.i"
            
            namespace std {
                %template(IntVector) vector<int>;
            }
            
            using namespace std;
            typedef std::vector Vector;
            
            void foo(vector<int> *x, const Vector &x);
            

            Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

            Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

            Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

            8.5 Utility Libraries

            8.5.1 exception.i

            The exception.i library provides a language-independent function for raising a run-time exception in the target language.

            SWIG_exception(int code, const char *message)

            Raises an exception in the target language. code is one of the following symbolic constants:

            SWIG_MemoryError
            SWIG_IOError
            SWIG_RuntimeError
            SWIG_IndexError
            SWIG_TypeError
            SWIG_DivisionByZero
            SWIG_OverflowError
            SWIG_SyntaxError
            SWIG_ValueError
            SWIG_SystemError
            

            message is a string indicating more information about the problem.

            The primary use of this module is in writing language-independent exception handlers. For example:

            %include "exception.i"
            %exception std::vector::getitem {
                try {
                    $action
                } catch (std::out_of_range& e) {
                    SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                }
            }
            

            ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
            

            SWIG-1.3 Documentation

            
            

            ---

            Table of Contents

            
            
            SWIG-1.3 Development Documentation
            • Sections
            • SWIG Core Documentation
            • Language Module Documentation
            • Developer Documentation
            • Documentation that has not yet been updated
            1 Preface
            • 1.1 Introduction
            • 1.2 Special Introduction for Version 1.3
            • 1.3 SWIG Versions
            • 1.4 SWIG resources
            • 1.5 Prerequisites
            • 1.6 Organization of this manual
            • 1.7 How to avoid reading the manual
            • 1.8 Backwards Coattach_header(char *hstr); In the target language:

              >>> make_upper("hello world")
              'HELLO WORLD'
              >>> attach_header("Hello world")
              'header: Hello world'
              >>>
              

              This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

              %cstring_output_maxsize(parm, maxparm)

              This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

              %cstring_output_maxsize(char *path, int maxpath);
              ...
              void get_path(char *path, int maxpath);
              

              In the target language:

              >>> get_path(1024)
              '/home/beazley/Packages/Foo/Bar'
              >>>
              

              This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

              %cstring_output_withsize(parm, maxparm)

              This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

              %cstring_output_withsize(char *data, int *maxdata);
              ...
              void get_data(char *data, int *maxdata);
              

              In the target language:

              >>> get_data(1024)
              'x627388912'
              >>> get_data(1024)
              'xyzzy'
              >>>
              

              This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

              %cstring_output_allocate(parm, release)

              This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

              void foo(char **s) {
                  *s = (char *) malloc(64);
                  sprintf(*s, "Hello world\n");
              }
              

              The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

              %cstring_output_allocate(char **s, free(*$1));
              ...
              void foo(char **s);
              

              In the target language:

              >>> foo()
              'Hello world\n'
              >>>
              

              %cstring_output_allocate_size(parm, szparm, release)

              This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

              void foo(char **s, int *sz) {
                  *s = (char *) malloc(64);
                  *sz = 64;
                  // Write some binary data
                  ...
              }
              

              The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

              %cstring_output_allocate_size(char **s, int *slen, free(*$1));
              ...
              void foo(char **s, int *slen);
              

              In the target language:

              >>> foo()
              '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
              >>>
              

              This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

              char  *get_data(int *len);
              

              You could wrap it with a function like this:

              void my_get_data(char **result, int *len) {
                 *result = get_data(len);
              }
              

              Comments:
              • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
              • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
              • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
              • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

              8.4 C++ Library

              The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

              8.4.1 std_string.i

              The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

              %module example
              %include "std_string.i"
              
              std::string foo();
              void        bar(const std::string &x);
              

              In the target language:

              x = foo();                # Returns a string object
              bar("Hello World");       # Pass string as std::string
              

              This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

              This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

              %module example
              %include "std_string.i"
              
              using namespace std;
              typedef std::string String;
              ...
              void foo(string s, const String &t);     // std_string typemaps still applied
              

              Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

              8.4.2 std_vector.i

              The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

              %module example
              %include "std_vector.i"
              
              namespace std {
                 %template(vectori) vector<int>;
                 %template(vectord) vector<double>;
              };
              

              When a template vector<X> is instantiated a number of things happen:
              • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
              • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
              • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
              • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
              • An exception handler for std::out_of_range is defined.
              • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
              To illustrate the use of this library, consider the following functions:

              /* File : example.h */
              
              #include <vector>
              #include <algorithm>
              #include <functional>
              #include <numeric>
              
              double average(std::vector<int> v) {
                  return std::accumulate(v.begin(),v.end(),0.0)/v.size();
              }
              
              std::vector<double> half(const std::vector<double>& v) {
                  std::vector<double> w(v);
                  for (unsigned int i=0; i<w.size(); i++)
                      w[i] /= 2.0;
                  return w;
              }
              
              void halve_in_place(std::vector<double>& v) {
                  std::transform(v.begin(),v.end(),v.begin(),
                                 std::bind2nd(std::divides<double>(),2.0));
              }
              

              To wrap with SWIG, you might write the following:

              %module example
              %{
              #include "example.h"
              %}
              
              %include "std_vector.i"
              // Instantiate templates used by example
              namespace std {
                 %template(IntVector) vector<int>;
                 %template(DoubleVector) vector<double>;
              }
              
              // Include the header file with above prototypes
              %include "example.h"
              

              Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

              >>> from example import *
              >>> iv = IntVector(4)         # Create an vector<int>
              >>> for i in range(0,4):
              ...      iv[i] = i
              >>> average(iv)               # Call method
              1.5
              >>> average([0,1,2,3])        # Call with list
              1.5
              >>> half([1,2,3])             # Half a list
              (0.5,1.0,1.5)
              >>> halve_in_place([1,2,3])   # Oops
              Traceback (most recent call last):
                File "<stdin>", line 1, in ?
              TypeError: Type error. Expected _p_std__vectorTdouble_t
              >>> dv = DoubleVector(4)
              >>> for i in range(0,4):
              ...       dv[i] = i
              >>> halve_in_place(dv)       # Ok
              >>> for i in dv:
              ...       print i
              ...
              0.0
              0.5
              1.0
              1.5
              >>> dv[20] = 4.5
              Traceback (most recent call last):
                File "<stdin>", line 1, in ?
                File "example.py", line 81, in __setitem__
                  def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
              IndexError: vector index out of range
              >>>
              

              This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

              %include "std_vector.i"
              
              namespace std {
                  %template(IntVector) vector<int>;
              }
              
              using namespace std;
              typedef std::vector Vector;
              
              void foo(vector<int> *x, const Vector &x);
              

              Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

              Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

              Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

              8.5 Utility Libraries

              8.5.1 exception.i

              The exception.i library provides a language-independent function for raising a run-time exception in the target language.

              SWIG_exception(int code, const char *message)

              Raises an exception in the target language. code is one of the following symbolic constants:

              SWIG_MemoryError
              SWIG_IOError
              SWIG_RuntimeError
              SWIG_IndexError
              SWIG_TypeError
              SWIG_DivisionByZero
              SWIG_OverflowError
              SWIG_SyntaxError
              SWIG_ValueError
              SWIG_SystemError
              

              message is a string indicating more information about the problem.

              The primary use of this module is in writing language-independent exception handlers. For example:

              %include "exception.i"
              %exception std::vector::getitem {
                  try {
                      $action
                  } catch (std::out_of_range& e) {
                      SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                  }
              }
              

              ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
              

              SWIG-1.3 Documentation

              
              

              ---

              Table of Contents

              
              
              SWIG-1.3 Development Documentation
              • Sections
              • SWIG Core Documentation
              • Language Module Documentation
              • Developer Documentation
              • Documentation that has not yet been updated
              1 Preface
              • 1.1 Introduction
              • 1.2 Special Introduction for Version 1.3
              • 1.3 SWIG Versions
              • 1.4 SWIG resources
              • 1.5 Prerequisites
              • 1.6 Organization of this manual
              • 1.7 How to avoid reading the manual
              • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                >>> make_upper("hello world")
                'HELLO WORLD'
                >>> attach_header("Hello world")
                'header: Hello world'
                >>>
                

                This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                %cstring_output_maxsize(parm, maxparm)

                This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                %cstring_output_maxsize(char *path, int maxpath);
                ...
                void get_path(char *path, int maxpath);
                

                In the target language:

                >>> get_path(1024)
                '/home/beazley/Packages/Foo/Bar'
                >>>
                

                This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                %cstring_output_withsize(parm, maxparm)

                This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                %cstring_output_withsize(char *data, int *maxdata);
                ...
                void get_data(char *data, int *maxdata);
                

                In the target language:

                >>> get_data(1024)
                'x627388912'
                >>> get_data(1024)
                'xyzzy'
                >>>
                

                This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                %cstring_output_allocate(parm, release)

                This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                void foo(char **s) {
                    *s = (char *) malloc(64);
                    sprintf(*s, "Hello world\n");
                }
                

                The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                %cstring_output_allocate(char **s, free(*$1));
                ...
                void foo(char **s);
                

                In the target language:

                >>> foo()
                'Hello world\n'
                >>>
                

                %cstring_output_allocate_size(parm, szparm, release)

                This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                void foo(char **s, int *sz) {
                    *s = (char *) malloc(64);
                    *sz = 64;
                    // Write some binary data
                    ...
                }
                

                The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                ...
                void foo(char **s, int *slen);
                

                In the target language:

                >>> foo()
                '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                >>>
                

                This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                char  *get_data(int *len);
                

                You could wrap it with a function like this:

                void my_get_data(char **result, int *len) {
                   *result = get_data(len);
                }
                

                Comments:
                • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                8.4 C++ Library

                The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                8.4.1 std_string.i

                The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                %module example
                %include "std_string.i"
                
                std::string foo();
                void        bar(const std::string &x);
                

                In the target language:

                x = foo();                # Returns a string object
                bar("Hello World");       # Pass string as std::string
                

                This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                %module example
                %include "std_string.i"
                
                using namespace std;
                typedef std::string String;
                ...
                void foo(string s, const String &t);     // std_string typemaps still applied
                

                Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                8.4.2 std_vector.i

                The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                %module example
                %include "std_vector.i"
                
                namespace std {
                   %template(vectori) vector<int>;
                   %template(vectord) vector<double>;
                };
                

                When a template vector<X> is instantiated a number of things happen:
                • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                • An exception handler for std::out_of_range is defined.
                • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                To illustrate the use of this library, consider the following functions:

                /* File : example.h */
                
                #include <vector>
                #include <algorithm>
                #include <functional>
                #include <numeric>
                
                double average(std::vector<int> v) {
                    return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                }
                
                std::vector<double> half(const std::vector<double>& v) {
                    std::vector<double> w(v);
                    for (unsigned int i=0; i<w.size(); i++)
                        w[i] /= 2.0;
                    return w;
                }
                
                void halve_in_place(std::vector<double>& v) {
                    std::transform(v.begin(),v.end(),v.begin(),
                                   std::bind2nd(std::divides<double>(),2.0));
                }
                

                To wrap with SWIG, you might write the following:

                %module example
                %{
                #include "example.h"
                %}
                
                %include "std_vector.i"
                // Instantiate templates used by example
                namespace std {
                   %template(IntVector) vector<int>;
                   %template(DoubleVector) vector<double>;
                }
                
                // Include the header file with above prototypes
                %include "example.h"
                

                Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                >>> from example import *
                >>> iv = IntVector(4)         # Create an vector<int>
                >>> for i in range(0,4):
                ...      iv[i] = i
                >>> average(iv)               # Call method
                1.5
                >>> average([0,1,2,3])        # Call with list
                1.5
                >>> half([1,2,3])             # Half a list
                (0.5,1.0,1.5)
                >>> halve_in_place([1,2,3])   # Oops
                Traceback (most recent call last):
                  File "<stdin>", line 1, in ?
                TypeError: Type error. Expected _p_std__vectorTdouble_t
                >>> dv = DoubleVector(4)
                >>> for i in range(0,4):
                ...       dv[i] = i
                >>> halve_in_place(dv)       # Ok
                >>> for i in dv:
                ...       print i
                ...
                0.0
                0.5
                1.0
                1.5
                >>> dv[20] = 4.5
                Traceback (most recent call last):
                  File "<stdin>", line 1, in ?
                  File "example.py", line 81, in __setitem__
                    def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                IndexError: vector index out of range
                >>>
                

                This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                %include "std_vector.i"
                
                namespace std {
                    %template(IntVector) vector<int>;
                }
                
                using namespace std;
                typedef std::vector Vector;
                
                void foo(vector<int> *x, const Vector &x);
                

                Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                8.5 Utility Libraries

                8.5.1 exception.i

                The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                SWIG_exception(int code, const char *message)

                Raises an exception in the target language. code is one of the following symbolic constants:

                SWIG_MemoryError
                SWIG_IOError
                SWIG_RuntimeError
                SWIG_IndexError
                SWIG_TypeError
                SWIG_DivisionByZero
                SWIG_OverflowError
                SWIG_SyntaxError
                SWIG_ValueError
                SWIG_SystemError
                

                message is a string indicating more information about the problem.

                The primary use of this module is in writing language-independent exception handlers. For example:

                %include "exception.i"
                %exception std::vector::getitem {
                    try {
                        $action
                    } catch (std::out_of_range& e) {
                        SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                    }
                }
                

                ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                

                SWIG-1.3 Documentation

                
                

                ---

                Table of Contents

                
                
                SWIG-1.3 Development Documentation
                • Sections
                • SWIG Core Documentation
                • Language Module Documentation
                • Developer Documentation
                • Documentation that has not yet been updated
                1 Preface
                • 1.1 Introduction
                • 1.2 Special Introduction for Version 1.3
                • 1.3 SWIG Versions
                • 1.4 SWIG resources
                • 1.5 Prerequisites
                • 1.6 Organization of this manual
                • 1.7 How to avoid reading the manual
                • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                  >>> make_upper("hello world")
                  'HELLO WORLD'
                  >>> attach_header("Hello world")
                  'header: Hello world'
                  >>>
                  

                  This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                  %cstring_output_maxsize(parm, maxparm)

                  This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                  %cstring_output_maxsize(char *path, int maxpath);
                  ...
                  void get_path(char *path, int maxpath);
                  

                  In the target language:

                  >>> get_path(1024)
                  '/home/beazley/Packages/Foo/Bar'
                  >>>
                  

                  This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                  %cstring_output_withsize(parm, maxparm)

                  This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                  %cstring_output_withsize(char *data, int *maxdata);
                  ...
                  void get_data(char *data, int *maxdata);
                  

                  In the target language:

                  >>> get_data(1024)
                  'x627388912'
                  >>> get_data(1024)
                  'xyzzy'
                  >>>
                  

                  This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                  %cstring_output_allocate(parm, release)

                  This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                  void foo(char **s) {
                      *s = (char *) malloc(64);
                      sprintf(*s, "Hello world\n");
                  }
                  

                  The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                  %cstring_output_allocate(char **s, free(*$1));
                  ...
                  void foo(char **s);
                  

                  In the target language:

                  >>> foo()
                  'Hello world\n'
                  >>>
                  

                  %cstring_output_allocate_size(parm, szparm, release)

                  This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                  void foo(char **s, int *sz) {
                      *s = (char *) malloc(64);
                      *sz = 64;
                      // Write some binary data
                      ...
                  }
                  

                  The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                  %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                  ...
                  void foo(char **s, int *slen);
                  

                  In the target language:

                  >>> foo()
                  '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                  >>>
                  

                  This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                  char  *get_data(int *len);
                  

                  You could wrap it with a function like this:

                  void my_get_data(char **result, int *len) {
                     *result = get_data(len);
                  }
                  

                  Comments:
                  • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                  • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                  • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                  • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                  8.4 C++ Library

                  The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                  8.4.1 std_string.i

                  The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                  %module example
                  %include "std_string.i"
                  
                  std::string foo();
                  void        bar(const std::string &x);
                  

                  In the target language:

                  x = foo();                # Returns a string object
                  bar("Hello World");       # Pass string as std::string
                  

                  This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                  This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                  %module example
                  %include "std_string.i"
                  
                  using namespace std;
                  typedef std::string String;
                  ...
                  void foo(string s, const String &t);     // std_string typemaps still applied
                  

                  Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                  8.4.2 std_vector.i

                  The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                  %module example
                  %include "std_vector.i"
                  
                  namespace std {
                     %template(vectori) vector<int>;
                     %template(vectord) vector<double>;
                  };
                  

                  When a template vector<X> is instantiated a number of things happen:
                  • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                  • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                  • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                  • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                  • An exception handler for std::out_of_range is defined.
                  • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                  To illustrate the use of this library, consider the following functions:

                  /* File : example.h */
                  
                  #include <vector>
                  #include <algorithm>
                  #include <functional>
                  #include <numeric>
                  
                  double average(std::vector<int> v) {
                      return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                  }
                  
                  std::vector<double> half(const std::vector<double>& v) {
                      std::vector<double> w(v);
                      for (unsigned int i=0; i<w.size(); i++)
                          w[i] /= 2.0;
                      return w;
                  }
                  
                  void halve_in_place(std::vector<double>& v) {
                      std::transform(v.begin(),v.end(),v.begin(),
                                     std::bind2nd(std::divides<double>(),2.0));
                  }
                  

                  To wrap with SWIG, you might write the following:

                  %module example
                  %{
                  #include "example.h"
                  %}
                  
                  %include "std_vector.i"
                  // Instantiate templates used by example
                  namespace std {
                     %template(IntVector) vector<int>;
                     %template(DoubleVector) vector<double>;
                  }
                  
                  // Include the header file with above prototypes
                  %include "example.h"
                  

                  Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                  >>> from example import *
                  >>> iv = IntVector(4)         # Create an vector<int>
                  >>> for i in range(0,4):
                  ...      iv[i] = i
                  >>> average(iv)               # Call method
                  1.5
                  >>> average([0,1,2,3])        # Call with list
                  1.5
                  >>> half([1,2,3])             # Half a list
                  (0.5,1.0,1.5)
                  >>> halve_in_place([1,2,3])   # Oops
                  Traceback (most recent call last):
                    File "<stdin>", line 1, in ?
                  TypeError: Type error. Expected _p_std__vectorTdouble_t
                  >>> dv = DoubleVector(4)
                  >>> for i in range(0,4):
                  ...       dv[i] = i
                  >>> halve_in_place(dv)       # Ok
                  >>> for i in dv:
                  ...       print i
                  ...
                  0.0
                  0.5
                  1.0
                  1.5
                  >>> dv[20] = 4.5
                  Traceback (most recent call last):
                    File "<stdin>", line 1, in ?
                    File "example.py", line 81, in __setitem__
                      def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                  IndexError: vector index out of range
                  >>>
                  

                  This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                  %include "std_vector.i"
                  
                  namespace std {
                      %template(IntVector) vector<int>;
                  }
                  
                  using namespace std;
                  typedef std::vector Vector;
                  
                  void foo(vector<int> *x, const Vector &x);
                  

                  Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                  Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                  Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                  8.5 Utility Libraries

                  8.5.1 exception.i

                  The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                  SWIG_exception(int code, const char *message)

                  Raises an exception in the target language. code is one of the following symbolic constants:

                  SWIG_MemoryError
                  SWIG_IOError
                  SWIG_RuntimeError
                  SWIG_IndexError
                  SWIG_TypeError
                  SWIG_DivisionByZero
                  SWIG_OverflowError
                  SWIG_SyntaxError
                  SWIG_ValueError
                  SWIG_SystemError
                  

                  message is a string indicating more information about the problem.

                  The primary use of this module is in writing language-independent exception handlers. For example:

                  %include "exception.i"
                  %exception std::vector::getitem {
                      try {
                          $action
                      } catch (std::out_of_range& e) {
                          SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                      }
                  }
                  

                  ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                  

                  SWIG-1.3 Documentation

                  
                  

                  ---

                  Table of Contents

                  
                  
                  SWIG-1.3 Development Documentation
                  • Sections
                  • SWIG Core Documentation
                  • Language Module Documentation
                  • Developer Documentation
                  • Documentation that has not yet been updated
                  1 Preface
                  • 1.1 Introduction
                  • 1.2 Special Introduction for Version 1.3
                  • 1.3 SWIG Versions
                  • 1.4 SWIG resources
                  • 1.5 Prerequisites
                  • 1.6 Organization of this manual
                  • 1.7 How to avoid reading the manual
                  • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                    >>> make_upper("hello world")
                    'HELLO WORLD'
                    >>> attach_header("Hello world")
                    'header: Hello world'
                    >>>
                    

                    This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                    %cstring_output_maxsize(parm, maxparm)

                    This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                    %cstring_output_maxsize(char *path, int maxpath);
                    ...
                    void get_path(char *path, int maxpath);
                    

                    In the target language:

                    >>> get_path(1024)
                    '/home/beazley/Packages/Foo/Bar'
                    >>>
                    

                    This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                    %cstring_output_withsize(parm, maxparm)

                    This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                    %cstring_output_withsize(char *data, int *maxdata);
                    ...
                    void get_data(char *data, int *maxdata);
                    

                    In the target language:

                    >>> get_data(1024)
                    'x627388912'
                    >>> get_data(1024)
                    'xyzzy'
                    >>>
                    

                    This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                    %cstring_output_allocate(parm, release)

                    This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                    void foo(char **s) {
                        *s = (char *) malloc(64);
                        sprintf(*s, "Hello world\n");
                    }
                    

                    The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                    %cstring_output_allocate(char **s, free(*$1));
                    ...
                    void foo(char **s);
                    

                    In the target language:

                    >>> foo()
                    'Hello world\n'
                    >>>
                    

                    %cstring_output_allocate_size(parm, szparm, release)

                    This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                    void foo(char **s, int *sz) {
                        *s = (char *) malloc(64);
                        *sz = 64;
                        // Write some binary data
                        ...
                    }
                    

                    The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                    %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                    ...
                    void foo(char **s, int *slen);
                    

                    In the target language:

                    >>> foo()
                    '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                    >>>
                    

                    This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                    char  *get_data(int *len);
                    

                    You could wrap it with a function like this:

                    void my_get_data(char **result, int *len) {
                       *result = get_data(len);
                    }
                    

                    Comments:
                    • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                    • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                    • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                    • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                    8.4 C++ Library

                    The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                    8.4.1 std_string.i

                    The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                    %module example
                    %include "std_string.i"
                    
                    std::string foo();
                    void        bar(const std::string &x);
                    

                    In the target language:

                    x = foo();                # Returns a string object
                    bar("Hello World");       # Pass string as std::string
                    

                    This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                    This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                    %module example
                    %include "std_string.i"
                    
                    using namespace std;
                    typedef std::string String;
                    ...
                    void foo(string s, const String &t);     // std_string typemaps still applied
                    

                    Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                    8.4.2 std_vector.i

                    The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                    %module example
                    %include "std_vector.i"
                    
                    namespace std {
                       %template(vectori) vector<int>;
                       %template(vectord) vector<double>;
                    };
                    

                    When a template vector<X> is instantiated a number of things happen:
                    • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                    • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                    • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                    • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                    • An exception handler for std::out_of_range is defined.
                    • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                    To illustrate the use of this library, consider the following functions:

                    /* File : example.h */
                    
                    #include <vector>
                    #include <algorithm>
                    #include <functional>
                    #include <numeric>
                    
                    double average(std::vector<int> v) {
                        return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                    }
                    
                    std::vector<double> half(const std::vector<double>& v) {
                        std::vector<double> w(v);
                        for (unsigned int i=0; i<w.size(); i++)
                            w[i] /= 2.0;
                        return w;
                    }
                    
                    void halve_in_place(std::vector<double>& v) {
                        std::transform(v.begin(),v.end(),v.begin(),
                                       std::bind2nd(std::divides<double>(),2.0));
                    }
                    

                    To wrap with SWIG, you might write the following:

                    %module example
                    %{
                    #include "example.h"
                    %}
                    
                    %include "std_vector.i"
                    // Instantiate templates used by example
                    namespace std {
                       %template(IntVector) vector<int>;
                       %template(DoubleVector) vector<double>;
                    }
                    
                    // Include the header file with above prototypes
                    %include "example.h"
                    

                    Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                    >>> from example import *
                    >>> iv = IntVector(4)         # Create an vector<int>
                    >>> for i in range(0,4):
                    ...      iv[i] = i
                    >>> average(iv)               # Call method
                    1.5
                    >>> average([0,1,2,3])        # Call with list
                    1.5
                    >>> half([1,2,3])             # Half a list
                    (0.5,1.0,1.5)
                    >>> halve_in_place([1,2,3])   # Oops
                    Traceback (most recent call last):
                      File "<stdin>", line 1, in ?
                    TypeError: Type error. Expected _p_std__vectorTdouble_t
                    >>> dv = DoubleVector(4)
                    >>> for i in range(0,4):
                    ...       dv[i] = i
                    >>> halve_in_place(dv)       # Ok
                    >>> for i in dv:
                    ...       print i
                    ...
                    0.0
                    0.5
                    1.0
                    1.5
                    >>> dv[20] = 4.5
                    Traceback (most recent call last):
                      File "<stdin>", line 1, in ?
                      File "example.py", line 81, in __setitem__
                        def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                    IndexError: vector index out of range
                    >>>
                    

                    This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                    %include "std_vector.i"
                    
                    namespace std {
                        %template(IntVector) vector<int>;
                    }
                    
                    using namespace std;
                    typedef std::vector Vector;
                    
                    void foo(vector<int> *x, const Vector &x);
                    

                    Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                    Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                    Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                    8.5 Utility Libraries

                    8.5.1 exception.i

                    The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                    SWIG_exception(int code, const char *message)

                    Raises an exception in the target language. code is one of the following symbolic constants:

                    SWIG_MemoryError
                    SWIG_IOError
                    SWIG_RuntimeError
                    SWIG_IndexError
                    SWIG_TypeError
                    SWIG_DivisionByZero
                    SWIG_OverflowError
                    SWIG_SyntaxError
                    SWIG_ValueError
                    SWIG_SystemError
                    

                    message is a string indicating more information about the problem.

                    The primary use of this module is in writing language-independent exception handlers. For example:

                    %include "exception.i"
                    %exception std::vector::getitem {
                        try {
                            $action
                        } catch (std::out_of_range& e) {
                            SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                        }
                    }
                    

                    ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                    

                    SWIG-1.3 Documentation

                    
                    

                    ---

                    Table of Contents

                    
                    
                    SWIG-1.3 Development Documentation
                    • Sections
                    • SWIG Core Documentation
                    • Language Module Documentation
                    • Developer Documentation
                    • Documentation that has not yet been updated
                    1 Preface
                    • 1.1 Introduction
                    • 1.2 Special Introduction for Version 1.3
                    • 1.3 SWIG Versions
                    • 1.4 SWIG resources
                    • 1.5 Prerequisites
                    • 1.6 Organization of this manual
                    • 1.7 How to avoid reading the manual
                    • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                      >>> make_upper("hello world")
                      'HELLO WORLD'
                      >>> attach_header("Hello world")
                      'header: Hello world'
                      >>>
                      

                      This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                      %cstring_output_maxsize(parm, maxparm)

                      This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                      %cstring_output_maxsize(char *path, int maxpath);
                      ...
                      void get_path(char *path, int maxpath);
                      

                      In the target language:

                      >>> get_path(1024)
                      '/home/beazley/Packages/Foo/Bar'
                      >>>
                      

                      This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                      %cstring_output_withsize(parm, maxparm)

                      This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                      %cstring_output_withsize(char *data, int *maxdata);
                      ...
                      void get_data(char *data, int *maxdata);
                      

                      In the target language:

                      >>> get_data(1024)
                      'x627388912'
                      >>> get_data(1024)
                      'xyzzy'
                      >>>
                      

                      This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                      %cstring_output_allocate(parm, release)

                      This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                      void foo(char **s) {
                          *s = (char *) malloc(64);
                          sprintf(*s, "Hello world\n");
                      }
                      

                      The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                      %cstring_output_allocate(char **s, free(*$1));
                      ...
                      void foo(char **s);
                      

                      In the target language:

                      >>> foo()
                      'Hello world\n'
                      >>>
                      

                      %cstring_output_allocate_size(parm, szparm, release)

                      This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                      void foo(char **s, int *sz) {
                          *s = (char *) malloc(64);
                          *sz = 64;
                          // Write some binary data
                          ...
                      }
                      

                      The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                      %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                      ...
                      void foo(char **s, int *slen);
                      

                      In the target language:

                      >>> foo()
                      '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                      >>>
                      

                      This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                      char  *get_data(int *len);
                      

                      You could wrap it with a function like this:

                      void my_get_data(char **result, int *len) {
                         *result = get_data(len);
                      }
                      

                      Comments:
                      • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                      • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                      • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                      • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                      8.4 C++ Library

                      The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                      8.4.1 std_string.i

                      The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                      %module example
                      %include "std_string.i"
                      
                      std::string foo();
                      void        bar(const std::string &x);
                      

                      In the target language:

                      x = foo();                # Returns a string object
                      bar("Hello World");       # Pass string as std::string
                      

                      This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                      This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                      %module example
                      %include "std_string.i"
                      
                      using namespace std;
                      typedef std::string String;
                      ...
                      void foo(string s, const String &t);     // std_string typemaps still applied
                      

                      Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                      8.4.2 std_vector.i

                      The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                      %module example
                      %include "std_vector.i"
                      
                      namespace std {
                         %template(vectori) vector<int>;
                         %template(vectord) vector<double>;
                      };
                      

                      When a template vector<X> is instantiated a number of things happen:
                      • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                      • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                      • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                      • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                      • An exception handler for std::out_of_range is defined.
                      • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                      To illustrate the use of this library, consider the following functions:

                      /* File : example.h */
                      
                      #include <vector>
                      #include <algorithm>
                      #include <functional>
                      #include <numeric>
                      
                      double average(std::vector<int> v) {
                          return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                      }
                      
                      std::vector<double> half(const std::vector<double>& v) {
                          std::vector<double> w(v);
                          for (unsigned int i=0; i<w.size(); i++)
                              w[i] /= 2.0;
                          return w;
                      }
                      
                      void halve_in_place(std::vector<double>& v) {
                          std::transform(v.begin(),v.end(),v.begin(),
                                         std::bind2nd(std::divides<double>(),2.0));
                      }
                      

                      To wrap with SWIG, you might write the following:

                      %module example
                      %{
                      #include "example.h"
                      %}
                      
                      %include "std_vector.i"
                      // Instantiate templates used by example
                      namespace std {
                         %template(IntVector) vector<int>;
                         %template(DoubleVector) vector<double>;
                      }
                      
                      // Include the header file with above prototypes
                      %include "example.h"
                      

                      Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                      >>> from example import *
                      >>> iv = IntVector(4)         # Create an vector<int>
                      >>> for i in range(0,4):
                      ...      iv[i] = i
                      >>> average(iv)               # Call method
                      1.5
                      >>> average([0,1,2,3])        # Call with list
                      1.5
                      >>> half([1,2,3])             # Half a list
                      (0.5,1.0,1.5)
                      >>> halve_in_place([1,2,3])   # Oops
                      Traceback (most recent call last):
                        File "<stdin>", line 1, in ?
                      TypeError: Type error. Expected _p_std__vectorTdouble_t
                      >>> dv = DoubleVector(4)
                      >>> for i in range(0,4):
                      ...       dv[i] = i
                      >>> halve_in_place(dv)       # Ok
                      >>> for i in dv:
                      ...       print i
                      ...
                      0.0
                      0.5
                      1.0
                      1.5
                      >>> dv[20] = 4.5
                      Traceback (most recent call last):
                        File "<stdin>", line 1, in ?
                        File "example.py", line 81, in __setitem__
                          def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                      IndexError: vector index out of range
                      >>>
                      

                      This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                      %include "std_vector.i"
                      
                      namespace std {
                          %template(IntVector) vector<int>;
                      }
                      
                      using namespace std;
                      typedef std::vector Vector;
                      
                      void foo(vector<int> *x, const Vector &x);
                      

                      Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                      Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                      Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                      8.5 Utility Libraries

                      8.5.1 exception.i

                      The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                      SWIG_exception(int code, const char *message)

                      Raises an exception in the target language. code is one of the following symbolic constants:

                      SWIG_MemoryError
                      SWIG_IOError
                      SWIG_RuntimeError
                      SWIG_IndexError
                      SWIG_TypeError
                      SWIG_DivisionByZero
                      SWIG_OverflowError
                      SWIG_SyntaxError
                      SWIG_ValueError
                      SWIG_SystemError
                      

                      message is a string indicating more information about the problem.

                      The primary use of this module is in writing language-independent exception handlers. For example:

                      %include "exception.i"
                      %exception std::vector::getitem {
                          try {
                              $action
                          } catch (std::out_of_range& e) {
                              SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                          }
                      }
                      

                      ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                      

                      SWIG-1.3 Documentation

                      
                      

                      ---

                      Table of Contents

                      
                      
                      SWIG-1.3 Development Documentation
                      • Sections
                      • SWIG Core Documentation
                      • Language Module Documentation
                      • Developer Documentation
                      • Documentation that has not yet been updated
                      1 Preface
                      • 1.1 Introduction
                      • 1.2 Special Introduction for Version 1.3
                      • 1.3 SWIG Versions
                      • 1.4 SWIG resources
                      • 1.5 Prerequisites
                      • 1.6 Organization of this manual
                      • 1.7 How to avoid reading the manual
                      • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                        >>> make_upper("hello world")
                        'HELLO WORLD'
                        >>> attach_header("Hello world")
                        'header: Hello world'
                        >>>
                        

                        This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                        %cstring_output_maxsize(parm, maxparm)

                        This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                        %cstring_output_maxsize(char *path, int maxpath);
                        ...
                        void get_path(char *path, int maxpath);
                        

                        In the target language:

                        >>> get_path(1024)
                        '/home/beazley/Packages/Foo/Bar'
                        >>>
                        

                        This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                        %cstring_output_withsize(parm, maxparm)

                        This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                        %cstring_output_withsize(char *data, int *maxdata);
                        ...
                        void get_data(char *data, int *maxdata);
                        

                        In the target language:

                        >>> get_data(1024)
                        'x627388912'
                        >>> get_data(1024)
                        'xyzzy'
                        >>>
                        

                        This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                        %cstring_output_allocate(parm, release)

                        This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                        void foo(char **s) {
                            *s = (char *) malloc(64);
                            sprintf(*s, "Hello world\n");
                        }
                        

                        The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                        %cstring_output_allocate(char **s, free(*$1));
                        ...
                        void foo(char **s);
                        

                        In the target language:

                        >>> foo()
                        'Hello world\n'
                        >>>
                        

                        %cstring_output_allocate_size(parm, szparm, release)

                        This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                        void foo(char **s, int *sz) {
                            *s = (char *) malloc(64);
                            *sz = 64;
                            // Write some binary data
                            ...
                        }
                        

                        The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                        %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                        ...
                        void foo(char **s, int *slen);
                        

                        In the target language:

                        >>> foo()
                        '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                        >>>
                        

                        This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                        char  *get_data(int *len);
                        

                        You could wrap it with a function like this:

                        void my_get_data(char **result, int *len) {
                           *result = get_data(len);
                        }
                        

                        Comments:
                        • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                        • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                        • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                        • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                        8.4 C++ Library

                        The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                        8.4.1 std_string.i

                        The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                        %module example
                        %include "std_string.i"
                        
                        std::string foo();
                        void        bar(const std::string &x);
                        

                        In the target language:

                        x = foo();                # Returns a string object
                        bar("Hello World");       # Pass string as std::string
                        

                        This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                        This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                        %module example
                        %include "std_string.i"
                        
                        using namespace std;
                        typedef std::string String;
                        ...
                        void foo(string s, const String &t);     // std_string typemaps still applied
                        

                        Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                        8.4.2 std_vector.i

                        The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                        %module example
                        %include "std_vector.i"
                        
                        namespace std {
                           %template(vectori) vector<int>;
                           %template(vectord) vector<double>;
                        };
                        

                        When a template vector<X> is instantiated a number of things happen:
                        • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                        • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                        • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                        • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                        • An exception handler for std::out_of_range is defined.
                        • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                        To illustrate the use of this library, consider the following functions:

                        /* File : example.h */
                        
                        #include <vector>
                        #include <algorithm>
                        #include <functional>
                        #include <numeric>
                        
                        double average(std::vector<int> v) {
                            return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                        }
                        
                        std::vector<double> half(const std::vector<double>& v) {
                            std::vector<double> w(v);
                            for (unsigned int i=0; i<w.size(); i++)
                                w[i] /= 2.0;
                            return w;
                        }
                        
                        void halve_in_place(std::vector<double>& v) {
                            std::transform(v.begin(),v.end(),v.begin(),
                                           std::bind2nd(std::divides<double>(),2.0));
                        }
                        

                        To wrap with SWIG, you might write the following:

                        %module example
                        %{
                        #include "example.h"
                        %}
                        
                        %include "std_vector.i"
                        // Instantiate templates used by example
                        namespace std {
                           %template(IntVector) vector<int>;
                           %template(DoubleVector) vector<double>;
                        }
                        
                        // Include the header file with above prototypes
                        %include "example.h"
                        

                        Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                        >>> from example import *
                        >>> iv = IntVector(4)         # Create an vector<int>
                        >>> for i in range(0,4):
                        ...      iv[i] = i
                        >>> average(iv)               # Call method
                        1.5
                        >>> average([0,1,2,3])        # Call with list
                        1.5
                        >>> half([1,2,3])             # Half a list
                        (0.5,1.0,1.5)
                        >>> halve_in_place([1,2,3])   # Oops
                        Traceback (most recent call last):
                          File "<stdin>", line 1, in ?
                        TypeError: Type error. Expected _p_std__vectorTdouble_t
                        >>> dv = DoubleVector(4)
                        >>> for i in range(0,4):
                        ...       dv[i] = i
                        >>> halve_in_place(dv)       # Ok
                        >>> for i in dv:
                        ...       print i
                        ...
                        0.0
                        0.5
                        1.0
                        1.5
                        >>> dv[20] = 4.5
                        Traceback (most recent call last):
                          File "<stdin>", line 1, in ?
                          File "example.py", line 81, in __setitem__
                            def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                        IndexError: vector index out of range
                        >>>
                        

                        This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                        %include "std_vector.i"
                        
                        namespace std {
                            %template(IntVector) vector<int>;
                        }
                        
                        using namespace std;
                        typedef std::vector Vector;
                        
                        void foo(vector<int> *x, const Vector &x);
                        

                        Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                        Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                        Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                        8.5 Utility Libraries

                        8.5.1 exception.i

                        The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                        SWIG_exception(int code, const char *message)

                        Raises an exception in the target language. code is one of the following symbolic constants:

                        SWIG_MemoryError
                        SWIG_IOError
                        SWIG_RuntimeError
                        SWIG_IndexError
                        SWIG_TypeError
                        SWIG_DivisionByZero
                        SWIG_OverflowError
                        SWIG_SyntaxError
                        SWIG_ValueError
                        SWIG_SystemError
                        

                        message is a string indicating more information about the problem.

                        The primary use of this module is in writing language-independent exception handlers. For example:

                        %include "exception.i"
                        %exception std::vector::getitem {
                            try {
                                $action
                            } catch (std::out_of_range& e) {
                                SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                            }
                        }
                        

                        ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                        

                        SWIG-1.3 Documentation

                        
                        

                        ---

                        Table of Contents

                        
                        
                        SWIG-1.3 Development Documentation
                        • Sections
                        • SWIG Core Documentation
                        • Language Module Documentation
                        • Developer Documentation
                        • Documentation that has not yet been updated
                        1 Preface
                        • 1.1 Introduction
                        • 1.2 Special Introduction for Version 1.3
                        • 1.3 SWIG Versions
                        • 1.4 SWIG resources
                        • 1.5 Prerequisites
                        • 1.6 Organization of this manual
                        • 1.7 How to avoid reading the manual
                        • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                          >>> make_upper("hello world")
                          'HELLO WORLD'
                          >>> attach_header("Hello world")
                          'header: Hello world'
                          >>>
                          

                          This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                          %cstring_output_maxsize(parm, maxparm)

                          This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                          %cstring_output_maxsize(char *path, int maxpath);
                          ...
                          void get_path(char *path, int maxpath);
                          

                          In the target language:

                          >>> get_path(1024)
                          '/home/beazley/Packages/Foo/Bar'
                          >>>
                          

                          This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                          %cstring_output_withsize(parm, maxparm)

                          This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                          %cstring_output_withsize(char *data, int *maxdata);
                          ...
                          void get_data(char *data, int *maxdata);
                          

                          In the target language:

                          >>> get_data(1024)
                          'x627388912'
                          >>> get_data(1024)
                          'xyzzy'
                          >>>
                          

                          This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                          %cstring_output_allocate(parm, release)

                          This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                          void foo(char **s) {
                              *s = (char *) malloc(64);
                              sprintf(*s, "Hello world\n");
                          }
                          

                          The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                          %cstring_output_allocate(char **s, free(*$1));
                          ...
                          void foo(char **s);
                          

                          In the target language:

                          >>> foo()
                          'Hello world\n'
                          >>>
                          

                          %cstring_output_allocate_size(parm, szparm, release)

                          This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                          void foo(char **s, int *sz) {
                              *s = (char *) malloc(64);
                              *sz = 64;
                              // Write some binary data
                              ...
                          }
                          

                          The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                          %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                          ...
                          void foo(char **s, int *slen);
                          

                          In the target language:

                          >>> foo()
                          '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                          >>>
                          

                          This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                          char  *get_data(int *len);
                          

                          You could wrap it with a function like this:

                          void my_get_data(char **result, int *len) {
                             *result = get_data(len);
                          }
                          

                          Comments:
                          • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                          • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                          • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                          • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                          8.4 C++ Library

                          The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                          8.4.1 std_string.i

                          The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                          %module example
                          %include "std_string.i"
                          
                          std::string foo();
                          void        bar(const std::string &x);
                          

                          In the target language:

                          x = foo();                # Returns a string object
                          bar("Hello World");       # Pass string as std::string
                          

                          This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                          This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                          %module example
                          %include "std_string.i"
                          
                          using namespace std;
                          typedef std::string String;
                          ...
                          void foo(string s, const String &t);     // std_string typemaps still applied
                          

                          Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                          8.4.2 std_vector.i

                          The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                          %module example
                          %include "std_vector.i"
                          
                          namespace std {
                             %template(vectori) vector<int>;
                             %template(vectord) vector<double>;
                          };
                          

                          When a template vector<X> is instantiated a number of things happen:
                          • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                          • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                          • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                          • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                          • An exception handler for std::out_of_range is defined.
                          • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                          To illustrate the use of this library, consider the following functions:

                          /* File : example.h */
                          
                          #include <vector>
                          #include <algorithm>
                          #include <functional>
                          #include <numeric>
                          
                          double average(std::vector<int> v) {
                              return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                          }
                          
                          std::vector<double> half(const std::vector<double>& v) {
                              std::vector<double> w(v);
                              for (unsigned int i=0; i<w.size(); i++)
                                  w[i] /= 2.0;
                              return w;
                          }
                          
                          void halve_in_place(std::vector<double>& v) {
                              std::transform(v.begin(),v.end(),v.begin(),
                                             std::bind2nd(std::divides<double>(),2.0));
                          }
                          

                          To wrap with SWIG, you might write the following:

                          %module example
                          %{
                          #include "example.h"
                          %}
                          
                          %include "std_vector.i"
                          // Instantiate templates used by example
                          namespace std {
                             %template(IntVector) vector<int>;
                             %template(DoubleVector) vector<double>;
                          }
                          
                          // Include the header file with above prototypes
                          %include "example.h"
                          

                          Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                          >>> from example import *
                          >>> iv = IntVector(4)         # Create an vector<int>
                          >>> for i in range(0,4):
                          ...      iv[i] = i
                          >>> average(iv)               # Call method
                          1.5
                          >>> average([0,1,2,3])        # Call with list
                          1.5
                          >>> half([1,2,3])             # Half a list
                          (0.5,1.0,1.5)
                          >>> halve_in_place([1,2,3])   # Oops
                          Traceback (most recent call last):
                            File "<stdin>", line 1, in ?
                          TypeError: Type error. Expected _p_std__vectorTdouble_t
                          >>> dv = DoubleVector(4)
                          >>> for i in range(0,4):
                          ...       dv[i] = i
                          >>> halve_in_place(dv)       # Ok
                          >>> for i in dv:
                          ...       print i
                          ...
                          0.0
                          0.5
                          1.0
                          1.5
                          >>> dv[20] = 4.5
                          Traceback (most recent call last):
                            File "<stdin>", line 1, in ?
                            File "example.py", line 81, in __setitem__
                              def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                          IndexError: vector index out of range
                          >>>
                          

                          This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                          %include "std_vector.i"
                          
                          namespace std {
                              %template(IntVector) vector<int>;
                          }
                          
                          using namespace std;
                          typedef std::vector Vector;
                          
                          void foo(vector<int> *x, const Vector &x);
                          

                          Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                          Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                          Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                          8.5 Utility Libraries

                          8.5.1 exception.i

                          The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                          SWIG_exception(int code, const char *message)

                          Raises an exception in the target language. code is one of the following symbolic constants:

                          SWIG_MemoryError
                          SWIG_IOError
                          SWIG_RuntimeError
                          SWIG_IndexError
                          SWIG_TypeError
                          SWIG_DivisionByZero
                          SWIG_OverflowError
                          SWIG_SyntaxError
                          SWIG_ValueError
                          SWIG_SystemError
                          

                          message is a string indicating more information about the problem.

                          The primary use of this module is in writing language-independent exception handlers. For example:

                          %include "exception.i"
                          %exception std::vector::getitem {
                              try {
                                  $action
                              } catch (std::out_of_range& e) {
                                  SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                              }
                          }
                          

                          ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                          

                          SWIG-1.3 Documentation

                          
                          

                          ---

                          Table of Contents

                          
                          
                          SWIG-1.3 Development Documentation
                          • Sections
                          • SWIG Core Documentation
                          • Language Module Documentation
                          • Developer Documentation
                          • Documentation that has not yet been updated
                          1 Preface
                          • 1.1 Introduction
                          • 1.2 Special Introduction for Version 1.3
                          • 1.3 SWIG Versions
                          • 1.4 SWIG resources
                          • 1.5 Prerequisites
                          • 1.6 Organization of this manual
                          • 1.7 How to avoid reading the manual
                          • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                            >>> make_upper("hello world")
                            'HELLO WORLD'
                            >>> attach_header("Hello world")
                            'header: Hello world'
                            >>>
                            

                            This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                            %cstring_output_maxsize(parm, maxparm)

                            This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                            %cstring_output_maxsize(char *path, int maxpath);
                            ...
                            void get_path(char *path, int maxpath);
                            

                            In the target language:

                            >>> get_path(1024)
                            '/home/beazley/Packages/Foo/Bar'
                            >>>
                            

                            This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                            %cstring_output_withsize(parm, maxparm)

                            This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                            %cstring_output_withsize(char *data, int *maxdata);
                            ...
                            void get_data(char *data, int *maxdata);
                            

                            In the target language:

                            >>> get_data(1024)
                            'x627388912'
                            >>> get_data(1024)
                            'xyzzy'
                            >>>
                            

                            This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                            %cstring_output_allocate(parm, release)

                            This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                            void foo(char **s) {
                                *s = (char *) malloc(64);
                                sprintf(*s, "Hello world\n");
                            }
                            

                            The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                            %cstring_output_allocate(char **s, free(*$1));
                            ...
                            void foo(char **s);
                            

                            In the target language:

                            >>> foo()
                            'Hello world\n'
                            >>>
                            

                            %cstring_output_allocate_size(parm, szparm, release)

                            This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                            void foo(char **s, int *sz) {
                                *s = (char *) malloc(64);
                                *sz = 64;
                                // Write some binary data
                                ...
                            }
                            

                            The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                            %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                            ...
                            void foo(char **s, int *slen);
                            

                            In the target language:

                            >>> foo()
                            '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                            >>>
                            

                            This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                            char  *get_data(int *len);
                            

                            You could wrap it with a function like this:

                            void my_get_data(char **result, int *len) {
                               *result = get_data(len);
                            }
                            

                            Comments:
                            • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                            • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                            • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                            • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                            8.4 C++ Library

                            The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                            8.4.1 std_string.i

                            The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                            %module example
                            %include "std_string.i"
                            
                            std::string foo();
                            void        bar(const std::string &x);
                            

                            In the target language:

                            x = foo();                # Returns a string object
                            bar("Hello World");       # Pass string as std::string
                            

                            This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                            This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                            %module example
                            %include "std_string.i"
                            
                            using namespace std;
                            typedef std::string String;
                            ...
                            void foo(string s, const String &t);     // std_string typemaps still applied
                            

                            Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                            8.4.2 std_vector.i

                            The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                            %module example
                            %include "std_vector.i"
                            
                            namespace std {
                               %template(vectori) vector<int>;
                               %template(vectord) vector<double>;
                            };
                            

                            When a template vector<X> is instantiated a number of things happen:
                            • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                            • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                            • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                            • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                            • An exception handler for std::out_of_range is defined.
                            • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                            To illustrate the use of this library, consider the following functions:

                            /* File : example.h */
                            
                            #include <vector>
                            #include <algorithm>
                            #include <functional>
                            #include <numeric>
                            
                            double average(std::vector<int> v) {
                                return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                            }
                            
                            std::vector<double> half(const std::vector<double>& v) {
                                std::vector<double> w(v);
                                for (unsigned int i=0; i<w.size(); i++)
                                    w[i] /= 2.0;
                                return w;
                            }
                            
                            void halve_in_place(std::vector<double>& v) {
                                std::transform(v.begin(),v.end(),v.begin(),
                                               std::bind2nd(std::divides<double>(),2.0));
                            }
                            

                            To wrap with SWIG, you might write the following:

                            %module example
                            %{
                            #include "example.h"
                            %}
                            
                            %include "std_vector.i"
                            // Instantiate templates used by example
                            namespace std {
                               %template(IntVector) vector<int>;
                               %template(DoubleVector) vector<double>;
                            }
                            
                            // Include the header file with above prototypes
                            %include "example.h"
                            

                            Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                            >>> from example import *
                            >>> iv = IntVector(4)         # Create an vector<int>
                            >>> for i in range(0,4):
                            ...      iv[i] = i
                            >>> average(iv)               # Call method
                            1.5
                            >>> average([0,1,2,3])        # Call with list
                            1.5
                            >>> half([1,2,3])             # Half a list
                            (0.5,1.0,1.5)
                            >>> halve_in_place([1,2,3])   # Oops
                            Traceback (most recent call last):
                              File "<stdin>", line 1, in ?
                            TypeError: Type error. Expected _p_std__vectorTdouble_t
                            >>> dv = DoubleVector(4)
                            >>> for i in range(0,4):
                            ...       dv[i] = i
                            >>> halve_in_place(dv)       # Ok
                            >>> for i in dv:
                            ...       print i
                            ...
                            0.0
                            0.5
                            1.0
                            1.5
                            >>> dv[20] = 4.5
                            Traceback (most recent call last):
                              File "<stdin>", line 1, in ?
                              File "example.py", line 81, in __setitem__
                                def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                            IndexError: vector index out of range
                            >>>
                            

                            This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                            %include "std_vector.i"
                            
                            namespace std {
                                %template(IntVector) vector<int>;
                            }
                            
                            using namespace std;
                            typedef std::vector Vector;
                            
                            void foo(vector<int> *x, const Vector &x);
                            

                            Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                            Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                            Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                            8.5 Utility Libraries

                            8.5.1 exception.i

                            The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                            SWIG_exception(int code, const char *message)

                            Raises an exception in the target language. code is one of the following symbolic constants:

                            SWIG_MemoryError
                            SWIG_IOError
                            SWIG_RuntimeError
                            SWIG_IndexError
                            SWIG_TypeError
                            SWIG_DivisionByZero
                            SWIG_OverflowError
                            SWIG_SyntaxError
                            SWIG_ValueError
                            SWIG_SystemError
                            

                            message is a string indicating more information about the problem.

                            The primary use of this module is in writing language-independent exception handlers. For example:

                            %include "exception.i"
                            %exception std::vector::getitem {
                                try {
                                    $action
                                } catch (std::out_of_range& e) {
                                    SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                }
                            }
                            

                            ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                            

                            SWIG-1.3 Documentation

                            
                            

                            ---

                            Table of Contents

                            
                            
                            SWIG-1.3 Development Documentation
                            • Sections
                            • SWIG Core Documentation
                            • Language Module Documentation
                            • Developer Documentation
                            • Documentation that has not yet been updated
                            1 Preface
                            • 1.1 Introduction
                            • 1.2 Special Introduction for Version 1.3
                            • 1.3 SWIG Versions
                            • 1.4 SWIG resources
                            • 1.5 Prerequisites
                            • 1.6 Organization of this manual
                            • 1.7 How to avoid reading the manual
                            • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                              >>> make_upper("hello world")
                              'HELLO WORLD'
                              >>> attach_header("Hello world")
                              'header: Hello world'
                              >>>
                              

                              This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                              %cstring_output_maxsize(parm, maxparm)

                              This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                              %cstring_output_maxsize(char *path, int maxpath);
                              ...
                              void get_path(char *path, int maxpath);
                              

                              In the target language:

                              >>> get_path(1024)
                              '/home/beazley/Packages/Foo/Bar'
                              >>>
                              

                              This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                              %cstring_output_withsize(parm, maxparm)

                              This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                              %cstring_output_withsize(char *data, int *maxdata);
                              ...
                              void get_data(char *data, int *maxdata);
                              

                              In the target language:

                              >>> get_data(1024)
                              'x627388912'
                              >>> get_data(1024)
                              'xyzzy'
                              >>>
                              

                              This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                              %cstring_output_allocate(parm, release)

                              This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                              void foo(char **s) {
                                  *s = (char *) malloc(64);
                                  sprintf(*s, "Hello world\n");
                              }
                              

                              The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                              %cstring_output_allocate(char **s, free(*$1));
                              ...
                              void foo(char **s);
                              

                              In the target language:

                              >>> foo()
                              'Hello world\n'
                              >>>
                              

                              %cstring_output_allocate_size(parm, szparm, release)

                              This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                              void foo(char **s, int *sz) {
                                  *s = (char *) malloc(64);
                                  *sz = 64;
                                  // Write some binary data
                                  ...
                              }
                              

                              The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                              %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                              ...
                              void foo(char **s, int *slen);
                              

                              In the target language:

                              >>> foo()
                              '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                              >>>
                              

                              This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                              char  *get_data(int *len);
                              

                              You could wrap it with a function like this:

                              void my_get_data(char **result, int *len) {
                                 *result = get_data(len);
                              }
                              

                              Comments:
                              • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                              • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                              • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                              • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                              8.4 C++ Library

                              The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                              8.4.1 std_string.i

                              The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                              %module example
                              %include "std_string.i"
                              
                              std::string foo();
                              void        bar(const std::string &x);
                              

                              In the target language:

                              x = foo();                # Returns a string object
                              bar("Hello World");       # Pass string as std::string
                              

                              This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                              This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                              %module example
                              %include "std_string.i"
                              
                              using namespace std;
                              typedef std::string String;
                              ...
                              void foo(string s, const String &t);     // std_string typemaps still applied
                              

                              Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                              8.4.2 std_vector.i

                              The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                              %module example
                              %include "std_vector.i"
                              
                              namespace std {
                                 %template(vectori) vector<int>;
                                 %template(vectord) vector<double>;
                              };
                              

                              When a template vector<X> is instantiated a number of things happen:
                              • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                              • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                              • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                              • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                              • An exception handler for std::out_of_range is defined.
                              • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                              To illustrate the use of this library, consider the following functions:

                              /* File : example.h */
                              
                              #include <vector>
                              #include <algorithm>
                              #include <functional>
                              #include <numeric>
                              
                              double average(std::vector<int> v) {
                                  return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                              }
                              
                              std::vector<double> half(const std::vector<double>& v) {
                                  std::vector<double> w(v);
                                  for (unsigned int i=0; i<w.size(); i++)
                                      w[i] /= 2.0;
                                  return w;
                              }
                              
                              void halve_in_place(std::vector<double>& v) {
                                  std::transform(v.begin(),v.end(),v.begin(),
                                                 std::bind2nd(std::divides<double>(),2.0));
                              }
                              

                              To wrap with SWIG, you might write the following:

                              %module example
                              %{
                              #include "example.h"
                              %}
                              
                              %include "std_vector.i"
                              // Instantiate templates used by example
                              namespace std {
                                 %template(IntVector) vector<int>;
                                 %template(DoubleVector) vector<double>;
                              }
                              
                              // Include the header file with above prototypes
                              %include "example.h"
                              

                              Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                              >>> from example import *
                              >>> iv = IntVector(4)         # Create an vector<int>
                              >>> for i in range(0,4):
                              ...      iv[i] = i
                              >>> average(iv)               # Call method
                              1.5
                              >>> average([0,1,2,3])        # Call with list
                              1.5
                              >>> half([1,2,3])             # Half a list
                              (0.5,1.0,1.5)
                              >>> halve_in_place([1,2,3])   # Oops
                              Traceback (most recent call last):
                                File "<stdin>", line 1, in ?
                              TypeError: Type error. Expected _p_std__vectorTdouble_t
                              >>> dv = DoubleVector(4)
                              >>> for i in range(0,4):
                              ...       dv[i] = i
                              >>> halve_in_place(dv)       # Ok
                              >>> for i in dv:
                              ...       print i
                              ...
                              0.0
                              0.5
                              1.0
                              1.5
                              >>> dv[20] = 4.5
                              Traceback (most recent call last):
                                File "<stdin>", line 1, in ?
                                File "example.py", line 81, in __setitem__
                                  def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                              IndexError: vector index out of range
                              >>>
                              

                              This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                              %include "std_vector.i"
                              
                              namespace std {
                                  %template(IntVector) vector<int>;
                              }
                              
                              using namespace std;
                              typedef std::vector Vector;
                              
                              void foo(vector<int> *x, const Vector &x);
                              

                              Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                              Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                              Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                              8.5 Utility Libraries

                              8.5.1 exception.i

                              The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                              SWIG_exception(int code, const char *message)

                              Raises an exception in the target language. code is one of the following symbolic constants:

                              SWIG_MemoryError
                              SWIG_IOError
                              SWIG_RuntimeError
                              SWIG_IndexError
                              SWIG_TypeError
                              SWIG_DivisionByZero
                              SWIG_OverflowError
                              SWIG_SyntaxError
                              SWIG_ValueError
                              SWIG_SystemError
                              

                              message is a string indicating more information about the problem.

                              The primary use of this module is in writing language-independent exception handlers. For example:

                              %include "exception.i"
                              %exception std::vector::getitem {
                                  try {
                                      $action
                                  } catch (std::out_of_range& e) {
                                      SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                  }
                              }
                              

                              ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                              

                              SWIG-1.3 Documentation

                              
                              

                              ---

                              Table of Contents

                              
                              
                              SWIG-1.3 Development Documentation
                              • Sections
                              • SWIG Core Documentation
                              • Language Module Documentation
                              • Developer Documentation
                              • Documentation that has not yet been updated
                              1 Preface
                              • 1.1 Introduction
                              • 1.2 Special Introduction for Version 1.3
                              • 1.3 SWIG Versions
                              • 1.4 SWIG resources
                              • 1.5 Prerequisites
                              • 1.6 Organization of this manual
                              • 1.7 How to avoid reading the manual
                              • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                >>> make_upper("hello world")
                                'HELLO WORLD'
                                >>> attach_header("Hello world")
                                'header: Hello world'
                                >>>
                                

                                This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                %cstring_output_maxsize(parm, maxparm)

                                This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                %cstring_output_maxsize(char *path, int maxpath);
                                ...
                                void get_path(char *path, int maxpath);
                                

                                In the target language:

                                >>> get_path(1024)
                                '/home/beazley/Packages/Foo/Bar'
                                >>>
                                

                                This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                %cstring_output_withsize(parm, maxparm)

                                This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                %cstring_output_withsize(char *data, int *maxdata);
                                ...
                                void get_data(char *data, int *maxdata);
                                

                                In the target language:

                                >>> get_data(1024)
                                'x627388912'
                                >>> get_data(1024)
                                'xyzzy'
                                >>>
                                

                                This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                %cstring_output_allocate(parm, release)

                                This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                void foo(char **s) {
                                    *s = (char *) malloc(64);
                                    sprintf(*s, "Hello world\n");
                                }
                                

                                The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                %cstring_output_allocate(char **s, free(*$1));
                                ...
                                void foo(char **s);
                                

                                In the target language:

                                >>> foo()
                                'Hello world\n'
                                >>>
                                

                                %cstring_output_allocate_size(parm, szparm, release)

                                This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                void foo(char **s, int *sz) {
                                    *s = (char *) malloc(64);
                                    *sz = 64;
                                    // Write some binary data
                                    ...
                                }
                                

                                The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                ...
                                void foo(char **s, int *slen);
                                

                                In the target language:

                                >>> foo()
                                '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                >>>
                                

                                This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                char  *get_data(int *len);
                                

                                You could wrap it with a function like this:

                                void my_get_data(char **result, int *len) {
                                   *result = get_data(len);
                                }
                                

                                Comments:
                                • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                8.4 C++ Library

                                The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                8.4.1 std_string.i

                                The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                %module example
                                %include "std_string.i"
                                
                                std::string foo();
                                void        bar(const std::string &x);
                                

                                In the target language:

                                x = foo();                # Returns a string object
                                bar("Hello World");       # Pass string as std::string
                                

                                This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                %module example
                                %include "std_string.i"
                                
                                using namespace std;
                                typedef std::string String;
                                ...
                                void foo(string s, const String &t);     // std_string typemaps still applied
                                

                                Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                8.4.2 std_vector.i

                                The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                %module example
                                %include "std_vector.i"
                                
                                namespace std {
                                   %template(vectori) vector<int>;
                                   %template(vectord) vector<double>;
                                };
                                

                                When a template vector<X> is instantiated a number of things happen:
                                • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                • An exception handler for std::out_of_range is defined.
                                • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                To illustrate the use of this library, consider the following functions:

                                /* File : example.h */
                                
                                #include <vector>
                                #include <algorithm>
                                #include <functional>
                                #include <numeric>
                                
                                double average(std::vector<int> v) {
                                    return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                }
                                
                                std::vector<double> half(const std::vector<double>& v) {
                                    std::vector<double> w(v);
                                    for (unsigned int i=0; i<w.size(); i++)
                                        w[i] /= 2.0;
                                    return w;
                                }
                                
                                void halve_in_place(std::vector<double>& v) {
                                    std::transform(v.begin(),v.end(),v.begin(),
                                                   std::bind2nd(std::divides<double>(),2.0));
                                }
                                

                                To wrap with SWIG, you might write the following:

                                %module example
                                %{
                                #include "example.h"
                                %}
                                
                                %include "std_vector.i"
                                // Instantiate templates used by example
                                namespace std {
                                   %template(IntVector) vector<int>;
                                   %template(DoubleVector) vector<double>;
                                }
                                
                                // Include the header file with above prototypes
                                %include "example.h"
                                

                                Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                >>> from example import *
                                >>> iv = IntVector(4)         # Create an vector<int>
                                >>> for i in range(0,4):
                                ...      iv[i] = i
                                >>> average(iv)               # Call method
                                1.5
                                >>> average([0,1,2,3])        # Call with list
                                1.5
                                >>> half([1,2,3])             # Half a list
                                (0.5,1.0,1.5)
                                >>> halve_in_place([1,2,3])   # Oops
                                Traceback (most recent call last):
                                  File "<stdin>", line 1, in ?
                                TypeError: Type error. Expected _p_std__vectorTdouble_t
                                >>> dv = DoubleVector(4)
                                >>> for i in range(0,4):
                                ...       dv[i] = i
                                >>> halve_in_place(dv)       # Ok
                                >>> for i in dv:
                                ...       print i
                                ...
                                0.0
                                0.5
                                1.0
                                1.5
                                >>> dv[20] = 4.5
                                Traceback (most recent call last):
                                  File "<stdin>", line 1, in ?
                                  File "example.py", line 81, in __setitem__
                                    def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                IndexError: vector index out of range
                                >>>
                                

                                This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                %include "std_vector.i"
                                
                                namespace std {
                                    %template(IntVector) vector<int>;
                                }
                                
                                using namespace std;
                                typedef std::vector Vector;
                                
                                void foo(vector<int> *x, const Vector &x);
                                

                                Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                8.5 Utility Libraries

                                8.5.1 exception.i

                                The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                SWIG_exception(int code, const char *message)

                                Raises an exception in the target language. code is one of the following symbolic constants:

                                SWIG_MemoryError
                                SWIG_IOError
                                SWIG_RuntimeError
                                SWIG_IndexError
                                SWIG_TypeError
                                SWIG_DivisionByZero
                                SWIG_OverflowError
                                SWIG_SyntaxError
                                SWIG_ValueError
                                SWIG_SystemError
                                

                                message is a string indicating more information about the problem.

                                The primary use of this module is in writing language-independent exception handlers. For example:

                                %include "exception.i"
                                %exception std::vector::getitem {
                                    try {
                                        $action
                                    } catch (std::out_of_range& e) {
                                        SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                    }
                                }
                                

                                ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                

                                SWIG-1.3 Documentation

                                
                                

                                ---

                                Table of Contents

                                
                                
                                SWIG-1.3 Development Documentation
                                • Sections
                                • SWIG Core Documentation
                                • Language Module Documentation
                                • Developer Documentation
                                • Documentation that has not yet been updated
                                1 Preface
                                • 1.1 Introduction
                                • 1.2 Special Introduction for Version 1.3
                                • 1.3 SWIG Versions
                                • 1.4 SWIG resources
                                • 1.5 Prerequisites
                                • 1.6 Organization of this manual
                                • 1.7 How to avoid reading the manual
                                • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                  >>> make_upper("hello world")
                                  'HELLO WORLD'
                                  >>> attach_header("Hello world")
                                  'header: Hello world'
                                  >>>
                                  

                                  This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                  %cstring_output_maxsize(parm, maxparm)

                                  This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                  %cstring_output_maxsize(char *path, int maxpath);
                                  ...
                                  void get_path(char *path, int maxpath);
                                  

                                  In the target language:

                                  >>> get_path(1024)
                                  '/home/beazley/Packages/Foo/Bar'
                                  >>>
                                  

                                  This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                  %cstring_output_withsize(parm, maxparm)

                                  This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                  %cstring_output_withsize(char *data, int *maxdata);
                                  ...
                                  void get_data(char *data, int *maxdata);
                                  

                                  In the target language:

                                  >>> get_data(1024)
                                  'x627388912'
                                  >>> get_data(1024)
                                  'xyzzy'
                                  >>>
                                  

                                  This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                  %cstring_output_allocate(parm, release)

                                  This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                  void foo(char **s) {
                                      *s = (char *) malloc(64);
                                      sprintf(*s, "Hello world\n");
                                  }
                                  

                                  The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                  %cstring_output_allocate(char **s, free(*$1));
                                  ...
                                  void foo(char **s);
                                  

                                  In the target language:

                                  >>> foo()
                                  'Hello world\n'
                                  >>>
                                  

                                  %cstring_output_allocate_size(parm, szparm, release)

                                  This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                  void foo(char **s, int *sz) {
                                      *s = (char *) malloc(64);
                                      *sz = 64;
                                      // Write some binary data
                                      ...
                                  }
                                  

                                  The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                  %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                  ...
                                  void foo(char **s, int *slen);
                                  

                                  In the target language:

                                  >>> foo()
                                  '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                  >>>
                                  

                                  This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                  char  *get_data(int *len);
                                  

                                  You could wrap it with a function like this:

                                  void my_get_data(char **result, int *len) {
                                     *result = get_data(len);
                                  }
                                  

                                  Comments:
                                  • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                  • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                  • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                  • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                  8.4 C++ Library

                                  The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                  8.4.1 std_string.i

                                  The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                  %module example
                                  %include "std_string.i"
                                  
                                  std::string foo();
                                  void        bar(const std::string &x);
                                  

                                  In the target language:

                                  x = foo();                # Returns a string object
                                  bar("Hello World");       # Pass string as std::string
                                  

                                  This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                  This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                  %module example
                                  %include "std_string.i"
                                  
                                  using namespace std;
                                  typedef std::string String;
                                  ...
                                  void foo(string s, const String &t);     // std_string typemaps still applied
                                  

                                  Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                  8.4.2 std_vector.i

                                  The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                  %module example
                                  %include "std_vector.i"
                                  
                                  namespace std {
                                     %template(vectori) vector<int>;
                                     %template(vectord) vector<double>;
                                  };
                                  

                                  When a template vector<X> is instantiated a number of things happen:
                                  • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                  • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                  • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                  • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                  • An exception handler for std::out_of_range is defined.
                                  • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                  To illustrate the use of this library, consider the following functions:

                                  /* File : example.h */
                                  
                                  #include <vector>
                                  #include <algorithm>
                                  #include <functional>
                                  #include <numeric>
                                  
                                  double average(std::vector<int> v) {
                                      return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                  }
                                  
                                  std::vector<double> half(const std::vector<double>& v) {
                                      std::vector<double> w(v);
                                      for (unsigned int i=0; i<w.size(); i++)
                                          w[i] /= 2.0;
                                      return w;
                                  }
                                  
                                  void halve_in_place(std::vector<double>& v) {
                                      std::transform(v.begin(),v.end(),v.begin(),
                                                     std::bind2nd(std::divides<double>(),2.0));
                                  }
                                  

                                  To wrap with SWIG, you might write the following:

                                  %module example
                                  %{
                                  #include "example.h"
                                  %}
                                  
                                  %include "std_vector.i"
                                  // Instantiate templates used by example
                                  namespace std {
                                     %template(IntVector) vector<int>;
                                     %template(DoubleVector) vector<double>;
                                  }
                                  
                                  // Include the header file with above prototypes
                                  %include "example.h"
                                  

                                  Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                  >>> from example import *
                                  >>> iv = IntVector(4)         # Create an vector<int>
                                  >>> for i in range(0,4):
                                  ...      iv[i] = i
                                  >>> average(iv)               # Call method
                                  1.5
                                  >>> average([0,1,2,3])        # Call with list
                                  1.5
                                  >>> half([1,2,3])             # Half a list
                                  (0.5,1.0,1.5)
                                  >>> halve_in_place([1,2,3])   # Oops
                                  Traceback (most recent call last):
                                    File "<stdin>", line 1, in ?
                                  TypeError: Type error. Expected _p_std__vectorTdouble_t
                                  >>> dv = DoubleVector(4)
                                  >>> for i in range(0,4):
                                  ...       dv[i] = i
                                  >>> halve_in_place(dv)       # Ok
                                  >>> for i in dv:
                                  ...       print i
                                  ...
                                  0.0
                                  0.5
                                  1.0
                                  1.5
                                  >>> dv[20] = 4.5
                                  Traceback (most recent call last):
                                    File "<stdin>", line 1, in ?
                                    File "example.py", line 81, in __setitem__
                                      def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                  IndexError: vector index out of range
                                  >>>
                                  

                                  This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                  %include "std_vector.i"
                                  
                                  namespace std {
                                      %template(IntVector) vector<int>;
                                  }
                                  
                                  using namespace std;
                                  typedef std::vector Vector;
                                  
                                  void foo(vector<int> *x, const Vector &x);
                                  

                                  Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                  Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                  Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                  8.5 Utility Libraries

                                  8.5.1 exception.i

                                  The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                  SWIG_exception(int code, const char *message)

                                  Raises an exception in the target language. code is one of the following symbolic constants:

                                  SWIG_MemoryError
                                  SWIG_IOError
                                  SWIG_RuntimeError
                                  SWIG_IndexError
                                  SWIG_TypeError
                                  SWIG_DivisionByZero
                                  SWIG_OverflowError
                                  SWIG_SyntaxError
                                  SWIG_ValueError
                                  SWIG_SystemError
                                  

                                  message is a string indicating more information about the problem.

                                  The primary use of this module is in writing language-independent exception handlers. For example:

                                  %include "exception.i"
                                  %exception std::vector::getitem {
                                      try {
                                          $action
                                      } catch (std::out_of_range& e) {
                                          SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                      }
                                  }
                                  

                                  ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                  

                                  SWIG-1.3 Documentation

                                  
                                  

                                  ---

                                  Table of Contents

                                  
                                  
                                  SWIG-1.3 Development Documentation
                                  • Sections
                                  • SWIG Core Documentation
                                  • Language Module Documentation
                                  • Developer Documentation
                                  • Documentation that has not yet been updated
                                  1 Preface
                                  • 1.1 Introduction
                                  • 1.2 Special Introduction for Version 1.3
                                  • 1.3 SWIG Versions
                                  • 1.4 SWIG resources
                                  • 1.5 Prerequisites
                                  • 1.6 Organization of this manual
                                  • 1.7 How to avoid reading the manual
                                  • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                    >>> make_upper("hello world")
                                    'HELLO WORLD'
                                    >>> attach_header("Hello world")
                                    'header: Hello world'
                                    >>>
                                    

                                    This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                    %cstring_output_maxsize(parm, maxparm)

                                    This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                    %cstring_output_maxsize(char *path, int maxpath);
                                    ...
                                    void get_path(char *path, int maxpath);
                                    

                                    In the target language:

                                    >>> get_path(1024)
                                    '/home/beazley/Packages/Foo/Bar'
                                    >>>
                                    

                                    This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                    %cstring_output_withsize(parm, maxparm)

                                    This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                    %cstring_output_withsize(char *data, int *maxdata);
                                    ...
                                    void get_data(char *data, int *maxdata);
                                    

                                    In the target language:

                                    >>> get_data(1024)
                                    'x627388912'
                                    >>> get_data(1024)
                                    'xyzzy'
                                    >>>
                                    

                                    This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                    %cstring_output_allocate(parm, release)

                                    This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                    void foo(char **s) {
                                        *s = (char *) malloc(64);
                                        sprintf(*s, "Hello world\n");
                                    }
                                    

                                    The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                    %cstring_output_allocate(char **s, free(*$1));
                                    ...
                                    void foo(char **s);
                                    

                                    In the target language:

                                    >>> foo()
                                    'Hello world\n'
                                    >>>
                                    

                                    %cstring_output_allocate_size(parm, szparm, release)

                                    This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                    void foo(char **s, int *sz) {
                                        *s = (char *) malloc(64);
                                        *sz = 64;
                                        // Write some binary data
                                        ...
                                    }
                                    

                                    The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                    %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                    ...
                                    void foo(char **s, int *slen);
                                    

                                    In the target language:

                                    >>> foo()
                                    '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                    >>>
                                    

                                    This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                    char  *get_data(int *len);
                                    

                                    You could wrap it with a function like this:

                                    void my_get_data(char **result, int *len) {
                                       *result = get_data(len);
                                    }
                                    

                                    Comments:
                                    • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                    • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                    • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                    • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                    8.4 C++ Library

                                    The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                    8.4.1 std_string.i

                                    The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                    %module example
                                    %include "std_string.i"
                                    
                                    std::string foo();
                                    void        bar(const std::string &x);
                                    

                                    In the target language:

                                    x = foo();                # Returns a string object
                                    bar("Hello World");       # Pass string as std::string
                                    

                                    This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                    This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                    %module example
                                    %include "std_string.i"
                                    
                                    using namespace std;
                                    typedef std::string String;
                                    ...
                                    void foo(string s, const String &t);     // std_string typemaps still applied
                                    

                                    Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                    8.4.2 std_vector.i

                                    The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                    %module example
                                    %include "std_vector.i"
                                    
                                    namespace std {
                                       %template(vectori) vector<int>;
                                       %template(vectord) vector<double>;
                                    };
                                    

                                    When a template vector<X> is instantiated a number of things happen:
                                    • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                    • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                    • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                    • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                    • An exception handler for std::out_of_range is defined.
                                    • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                    To illustrate the use of this library, consider the following functions:

                                    /* File : example.h */
                                    
                                    #include <vector>
                                    #include <algorithm>
                                    #include <functional>
                                    #include <numeric>
                                    
                                    double average(std::vector<int> v) {
                                        return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                    }
                                    
                                    std::vector<double> half(const std::vector<double>& v) {
                                        std::vector<double> w(v);
                                        for (unsigned int i=0; i<w.size(); i++)
                                            w[i] /= 2.0;
                                        return w;
                                    }
                                    
                                    void halve_in_place(std::vector<double>& v) {
                                        std::transform(v.begin(),v.end(),v.begin(),
                                                       std::bind2nd(std::divides<double>(),2.0));
                                    }
                                    

                                    To wrap with SWIG, you might write the following:

                                    %module example
                                    %{
                                    #include "example.h"
                                    %}
                                    
                                    %include "std_vector.i"
                                    // Instantiate templates used by example
                                    namespace std {
                                       %template(IntVector) vector<int>;
                                       %template(DoubleVector) vector<double>;
                                    }
                                    
                                    // Include the header file with above prototypes
                                    %include "example.h"
                                    

                                    Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                    >>> from example import *
                                    >>> iv = IntVector(4)         # Create an vector<int>
                                    >>> for i in range(0,4):
                                    ...      iv[i] = i
                                    >>> average(iv)               # Call method
                                    1.5
                                    >>> average([0,1,2,3])        # Call with list
                                    1.5
                                    >>> half([1,2,3])             # Half a list
                                    (0.5,1.0,1.5)
                                    >>> halve_in_place([1,2,3])   # Oops
                                    Traceback (most recent call last):
                                      File "<stdin>", line 1, in ?
                                    TypeError: Type error. Expected _p_std__vectorTdouble_t
                                    >>> dv = DoubleVector(4)
                                    >>> for i in range(0,4):
                                    ...       dv[i] = i
                                    >>> halve_in_place(dv)       # Ok
                                    >>> for i in dv:
                                    ...       print i
                                    ...
                                    0.0
                                    0.5
                                    1.0
                                    1.5
                                    >>> dv[20] = 4.5
                                    Traceback (most recent call last):
                                      File "<stdin>", line 1, in ?
                                      File "example.py", line 81, in __setitem__
                                        def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                    IndexError: vector index out of range
                                    >>>
                                    

                                    This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                    %include "std_vector.i"
                                    
                                    namespace std {
                                        %template(IntVector) vector<int>;
                                    }
                                    
                                    using namespace std;
                                    typedef std::vector Vector;
                                    
                                    void foo(vector<int> *x, const Vector &x);
                                    

                                    Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                    Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                    Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                    8.5 Utility Libraries

                                    8.5.1 exception.i

                                    The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                    SWIG_exception(int code, const char *message)

                                    Raises an exception in the target language. code is one of the following symbolic constants:

                                    SWIG_MemoryError
                                    SWIG_IOError
                                    SWIG_RuntimeError
                                    SWIG_IndexError
                                    SWIG_TypeError
                                    SWIG_DivisionByZero
                                    SWIG_OverflowError
                                    SWIG_SyntaxError
                                    SWIG_ValueError
                                    SWIG_SystemError
                                    

                                    message is a string indicating more information about the problem.

                                    The primary use of this module is in writing language-independent exception handlers. For example:

                                    %include "exception.i"
                                    %exception std::vector::getitem {
                                        try {
                                            $action
                                        } catch (std::out_of_range& e) {
                                            SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                        }
                                    }
                                    

                                    ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                    

                                    SWIG-1.3 Documentation

                                    
                                    

                                    ---

                                    Table of Contents

                                    
                                    
                                    SWIG-1.3 Development Documentation
                                    • Sections
                                    • SWIG Core Documentation
                                    • Language Module Documentation
                                    • Developer Documentation
                                    • Documentation that has not yet been updated
                                    1 Preface
                                    • 1.1 Introduction
                                    • 1.2 Special Introduction for Version 1.3
                                    • 1.3 SWIG Versions
                                    • 1.4 SWIG resources
                                    • 1.5 Prerequisites
                                    • 1.6 Organization of this manual
                                    • 1.7 How to avoid reading the manual
                                    • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                      >>> make_upper("hello world")
                                      'HELLO WORLD'
                                      >>> attach_header("Hello world")
                                      'header: Hello world'
                                      >>>
                                      

                                      This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                      %cstring_output_maxsize(parm, maxparm)

                                      This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                      %cstring_output_maxsize(char *path, int maxpath);
                                      ...
                                      void get_path(char *path, int maxpath);
                                      

                                      In the target language:

                                      >>> get_path(1024)
                                      '/home/beazley/Packages/Foo/Bar'
                                      >>>
                                      

                                      This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                      %cstring_output_withsize(parm, maxparm)

                                      This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                      %cstring_output_withsize(char *data, int *maxdata);
                                      ...
                                      void get_data(char *data, int *maxdata);
                                      

                                      In the target language:

                                      >>> get_data(1024)
                                      'x627388912'
                                      >>> get_data(1024)
                                      'xyzzy'
                                      >>>
                                      

                                      This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                      %cstring_output_allocate(parm, release)

                                      This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                      void foo(char **s) {
                                          *s = (char *) malloc(64);
                                          sprintf(*s, "Hello world\n");
                                      }
                                      

                                      The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                      %cstring_output_allocate(char **s, free(*$1));
                                      ...
                                      void foo(char **s);
                                      

                                      In the target language:

                                      >>> foo()
                                      'Hello world\n'
                                      >>>
                                      

                                      %cstring_output_allocate_size(parm, szparm, release)

                                      This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                      void foo(char **s, int *sz) {
                                          *s = (char *) malloc(64);
                                          *sz = 64;
                                          // Write some binary data
                                          ...
                                      }
                                      

                                      The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                      %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                      ...
                                      void foo(char **s, int *slen);
                                      

                                      In the target language:

                                      >>> foo()
                                      '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                      >>>
                                      

                                      This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                      char  *get_data(int *len);
                                      

                                      You could wrap it with a function like this:

                                      void my_get_data(char **result, int *len) {
                                         *result = get_data(len);
                                      }
                                      

                                      Comments:
                                      • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                      • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                      • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                      • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                      8.4 C++ Library

                                      The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                      8.4.1 std_string.i

                                      The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                      %module example
                                      %include "std_string.i"
                                      
                                      std::string foo();
                                      void        bar(const std::string &x);
                                      

                                      In the target language:

                                      x = foo();                # Returns a string object
                                      bar("Hello World");       # Pass string as std::string
                                      

                                      This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                      This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                      %module example
                                      %include "std_string.i"
                                      
                                      using namespace std;
                                      typedef std::string String;
                                      ...
                                      void foo(string s, const String &t);     // std_string typemaps still applied
                                      

                                      Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                      8.4.2 std_vector.i

                                      The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                      %module example
                                      %include "std_vector.i"
                                      
                                      namespace std {
                                         %template(vectori) vector<int>;
                                         %template(vectord) vector<double>;
                                      };
                                      

                                      When a template vector<X> is instantiated a number of things happen:
                                      • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                      • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                      • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                      • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                      • An exception handler for std::out_of_range is defined.
                                      • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                      To illustrate the use of this library, consider the following functions:

                                      /* File : example.h */
                                      
                                      #include <vector>
                                      #include <algorithm>
                                      #include <functional>
                                      #include <numeric>
                                      
                                      double average(std::vector<int> v) {
                                          return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                      }
                                      
                                      std::vector<double> half(const std::vector<double>& v) {
                                          std::vector<double> w(v);
                                          for (unsigned int i=0; i<w.size(); i++)
                                              w[i] /= 2.0;
                                          return w;
                                      }
                                      
                                      void halve_in_place(std::vector<double>& v) {
                                          std::transform(v.begin(),v.end(),v.begin(),
                                                         std::bind2nd(std::divides<double>(),2.0));
                                      }
                                      

                                      To wrap with SWIG, you might write the following:

                                      %module example
                                      %{
                                      #include "example.h"
                                      %}
                                      
                                      %include "std_vector.i"
                                      // Instantiate templates used by example
                                      namespace std {
                                         %template(IntVector) vector<int>;
                                         %template(DoubleVector) vector<double>;
                                      }
                                      
                                      // Include the header file with above prototypes
                                      %include "example.h"
                                      

                                      Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                      >>> from example import *
                                      >>> iv = IntVector(4)         # Create an vector<int>
                                      >>> for i in range(0,4):
                                      ...      iv[i] = i
                                      >>> average(iv)               # Call method
                                      1.5
                                      >>> average([0,1,2,3])        # Call with list
                                      1.5
                                      >>> half([1,2,3])             # Half a list
                                      (0.5,1.0,1.5)
                                      >>> halve_in_place([1,2,3])   # Oops
                                      Traceback (most recent call last):
                                        File "<stdin>", line 1, in ?
                                      TypeError: Type error. Expected _p_std__vectorTdouble_t
                                      >>> dv = DoubleVector(4)
                                      >>> for i in range(0,4):
                                      ...       dv[i] = i
                                      >>> halve_in_place(dv)       # Ok
                                      >>> for i in dv:
                                      ...       print i
                                      ...
                                      0.0
                                      0.5
                                      1.0
                                      1.5
                                      >>> dv[20] = 4.5
                                      Traceback (most recent call last):
                                        File "<stdin>", line 1, in ?
                                        File "example.py", line 81, in __setitem__
                                          def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                      IndexError: vector index out of range
                                      >>>
                                      

                                      This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                      %include "std_vector.i"
                                      
                                      namespace std {
                                          %template(IntVector) vector<int>;
                                      }
                                      
                                      using namespace std;
                                      typedef std::vector Vector;
                                      
                                      void foo(vector<int> *x, const Vector &x);
                                      

                                      Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                      Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                      Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                      8.5 Utility Libraries

                                      8.5.1 exception.i

                                      The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                      SWIG_exception(int code, const char *message)

                                      Raises an exception in the target language. code is one of the following symbolic constants:

                                      SWIG_MemoryError
                                      SWIG_IOError
                                      SWIG_RuntimeError
                                      SWIG_IndexError
                                      SWIG_TypeError
                                      SWIG_DivisionByZero
                                      SWIG_OverflowError
                                      SWIG_SyntaxError
                                      SWIG_ValueError
                                      SWIG_SystemError
                                      

                                      message is a string indicating more information about the problem.

                                      The primary use of this module is in writing language-independent exception handlers. For example:

                                      %include "exception.i"
                                      %exception std::vector::getitem {
                                          try {
                                              $action
                                          } catch (std::out_of_range& e) {
                                              SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                          }
                                      }
                                      

                                      ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                      

                                      SWIG-1.3 Documentation

                                      
                                      

                                      ---

                                      Table of Contents

                                      
                                      
                                      SWIG-1.3 Development Documentation
                                      • Sections
                                      • SWIG Core Documentation
                                      • Language Module Documentation
                                      • Developer Documentation
                                      • Documentation that has not yet been updated
                                      1 Preface
                                      • 1.1 Introduction
                                      • 1.2 Special Introduction for Version 1.3
                                      • 1.3 SWIG Versions
                                      • 1.4 SWIG resources
                                      • 1.5 Prerequisites
                                      • 1.6 Organization of this manual
                                      • 1.7 How to avoid reading the manual
                                      • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                        >>> make_upper("hello world")
                                        'HELLO WORLD'
                                        >>> attach_header("Hello world")
                                        'header: Hello world'
                                        >>>
                                        

                                        This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                        %cstring_output_maxsize(parm, maxparm)

                                        This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                        %cstring_output_maxsize(char *path, int maxpath);
                                        ...
                                        void get_path(char *path, int maxpath);
                                        

                                        In the target language:

                                        >>> get_path(1024)
                                        '/home/beazley/Packages/Foo/Bar'
                                        >>>
                                        

                                        This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                        %cstring_output_withsize(parm, maxparm)

                                        This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                        %cstring_output_withsize(char *data, int *maxdata);
                                        ...
                                        void get_data(char *data, int *maxdata);
                                        

                                        In the target language:

                                        >>> get_data(1024)
                                        'x627388912'
                                        >>> get_data(1024)
                                        'xyzzy'
                                        >>>
                                        

                                        This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                        %cstring_output_allocate(parm, release)

                                        This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                        void foo(char **s) {
                                            *s = (char *) malloc(64);
                                            sprintf(*s, "Hello world\n");
                                        }
                                        

                                        The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                        %cstring_output_allocate(char **s, free(*$1));
                                        ...
                                        void foo(char **s);
                                        

                                        In the target language:

                                        >>> foo()
                                        'Hello world\n'
                                        >>>
                                        

                                        %cstring_output_allocate_size(parm, szparm, release)

                                        This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                        void foo(char **s, int *sz) {
                                            *s = (char *) malloc(64);
                                            *sz = 64;
                                            // Write some binary data
                                            ...
                                        }
                                        

                                        The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                        %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                        ...
                                        void foo(char **s, int *slen);
                                        

                                        In the target language:

                                        >>> foo()
                                        '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                        >>>
                                        

                                        This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                        char  *get_data(int *len);
                                        

                                        You could wrap it with a function like this:

                                        void my_get_data(char **result, int *len) {
                                           *result = get_data(len);
                                        }
                                        

                                        Comments:
                                        • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                        • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                        • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                        • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                        8.4 C++ Library

                                        The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                        8.4.1 std_string.i

                                        The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                        %module example
                                        %include "std_string.i"
                                        
                                        std::string foo();
                                        void        bar(const std::string &x);
                                        

                                        In the target language:

                                        x = foo();                # Returns a string object
                                        bar("Hello World");       # Pass string as std::string
                                        

                                        This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                        This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                        %module example
                                        %include "std_string.i"
                                        
                                        using namespace std;
                                        typedef std::string String;
                                        ...
                                        void foo(string s, const String &t);     // std_string typemaps still applied
                                        

                                        Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                        8.4.2 std_vector.i

                                        The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                        %module example
                                        %include "std_vector.i"
                                        
                                        namespace std {
                                           %template(vectori) vector<int>;
                                           %template(vectord) vector<double>;
                                        };
                                        

                                        When a template vector<X> is instantiated a number of things happen:
                                        • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                        • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                        • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                        • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                        • An exception handler for std::out_of_range is defined.
                                        • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                        To illustrate the use of this library, consider the following functions:

                                        /* File : example.h */
                                        
                                        #include <vector>
                                        #include <algorithm>
                                        #include <functional>
                                        #include <numeric>
                                        
                                        double average(std::vector<int> v) {
                                            return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                        }
                                        
                                        std::vector<double> half(const std::vector<double>& v) {
                                            std::vector<double> w(v);
                                            for (unsigned int i=0; i<w.size(); i++)
                                                w[i] /= 2.0;
                                            return w;
                                        }
                                        
                                        void halve_in_place(std::vector<double>& v) {
                                            std::transform(v.begin(),v.end(),v.begin(),
                                                           std::bind2nd(std::divides<double>(),2.0));
                                        }
                                        

                                        To wrap with SWIG, you might write the following:

                                        %module example
                                        %{
                                        #include "example.h"
                                        %}
                                        
                                        %include "std_vector.i"
                                        // Instantiate templates used by example
                                        namespace std {
                                           %template(IntVector) vector<int>;
                                           %template(DoubleVector) vector<double>;
                                        }
                                        
                                        // Include the header file with above prototypes
                                        %include "example.h"
                                        

                                        Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                        >>> from example import *
                                        >>> iv = IntVector(4)         # Create an vector<int>
                                        >>> for i in range(0,4):
                                        ...      iv[i] = i
                                        >>> average(iv)               # Call method
                                        1.5
                                        >>> average([0,1,2,3])        # Call with list
                                        1.5
                                        >>> half([1,2,3])             # Half a list
                                        (0.5,1.0,1.5)
                                        >>> halve_in_place([1,2,3])   # Oops
                                        Traceback (most recent call last):
                                          File "<stdin>", line 1, in ?
                                        TypeError: Type error. Expected _p_std__vectorTdouble_t
                                        >>> dv = DoubleVector(4)
                                        >>> for i in range(0,4):
                                        ...       dv[i] = i
                                        >>> halve_in_place(dv)       # Ok
                                        >>> for i in dv:
                                        ...       print i
                                        ...
                                        0.0
                                        0.5
                                        1.0
                                        1.5
                                        >>> dv[20] = 4.5
                                        Traceback (most recent call last):
                                          File "<stdin>", line 1, in ?
                                          File "example.py", line 81, in __setitem__
                                            def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                        IndexError: vector index out of range
                                        >>>
                                        

                                        This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                        %include "std_vector.i"
                                        
                                        namespace std {
                                            %template(IntVector) vector<int>;
                                        }
                                        
                                        using namespace std;
                                        typedef std::vector Vector;
                                        
                                        void foo(vector<int> *x, const Vector &x);
                                        

                                        Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                        Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                        Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                        8.5 Utility Libraries

                                        8.5.1 exception.i

                                        The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                        SWIG_exception(int code, const char *message)

                                        Raises an exception in the target language. code is one of the following symbolic constants:

                                        SWIG_MemoryError
                                        SWIG_IOError
                                        SWIG_RuntimeError
                                        SWIG_IndexError
                                        SWIG_TypeError
                                        SWIG_DivisionByZero
                                        SWIG_OverflowError
                                        SWIG_SyntaxError
                                        SWIG_ValueError
                                        SWIG_SystemError
                                        

                                        message is a string indicating more information about the problem.

                                        The primary use of this module is in writing language-independent exception handlers. For example:

                                        %include "exception.i"
                                        %exception std::vector::getitem {
                                            try {
                                                $action
                                            } catch (std::out_of_range& e) {
                                                SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                            }
                                        }
                                        

                                        ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                        

                                        SWIG-1.3 Documentation

                                        
                                        

                                        ---

                                        Table of Contents

                                        
                                        
                                        SWIG-1.3 Development Documentation
                                        • Sections
                                        • SWIG Core Documentation
                                        • Language Module Documentation
                                        • Developer Documentation
                                        • Documentation that has not yet been updated
                                        1 Preface
                                        • 1.1 Introduction
                                        • 1.2 Special Introduction for Version 1.3
                                        • 1.3 SWIG Versions
                                        • 1.4 SWIG resources
                                        • 1.5 Prerequisites
                                        • 1.6 Organization of this manual
                                        • 1.7 How to avoid reading the manual
                                        • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                          >>> make_upper("hello world")
                                          'HELLO WORLD'
                                          >>> attach_header("Hello world")
                                          'header: Hello world'
                                          >>>
                                          

                                          This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                          %cstring_output_maxsize(parm, maxparm)

                                          This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                          %cstring_output_maxsize(char *path, int maxpath);
                                          ...
                                          void get_path(char *path, int maxpath);
                                          

                                          In the target language:

                                          >>> get_path(1024)
                                          '/home/beazley/Packages/Foo/Bar'
                                          >>>
                                          

                                          This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                          %cstring_output_withsize(parm, maxparm)

                                          This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                          %cstring_output_withsize(char *data, int *maxdata);
                                          ...
                                          void get_data(char *data, int *maxdata);
                                          

                                          In the target language:

                                          >>> get_data(1024)
                                          'x627388912'
                                          >>> get_data(1024)
                                          'xyzzy'
                                          >>>
                                          

                                          This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                          %cstring_output_allocate(parm, release)

                                          This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                          void foo(char **s) {
                                              *s = (char *) malloc(64);
                                              sprintf(*s, "Hello world\n");
                                          }
                                          

                                          The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                          %cstring_output_allocate(char **s, free(*$1));
                                          ...
                                          void foo(char **s);
                                          

                                          In the target language:

                                          >>> foo()
                                          'Hello world\n'
                                          >>>
                                          

                                          %cstring_output_allocate_size(parm, szparm, release)

                                          This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                          void foo(char **s, int *sz) {
                                              *s = (char *) malloc(64);
                                              *sz = 64;
                                              // Write some binary data
                                              ...
                                          }
                                          

                                          The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                          %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                          ...
                                          void foo(char **s, int *slen);
                                          

                                          In the target language:

                                          >>> foo()
                                          '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                          >>>
                                          

                                          This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                          char  *get_data(int *len);
                                          

                                          You could wrap it with a function like this:

                                          void my_get_data(char **result, int *len) {
                                             *result = get_data(len);
                                          }
                                          

                                          Comments:
                                          • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                          • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                          • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                          • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                          8.4 C++ Library

                                          The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                          8.4.1 std_string.i

                                          The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                          %module example
                                          %include "std_string.i"
                                          
                                          std::string foo();
                                          void        bar(const std::string &x);
                                          

                                          In the target language:

                                          x = foo();                # Returns a string object
                                          bar("Hello World");       # Pass string as std::string
                                          

                                          This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                          This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                          %module example
                                          %include "std_string.i"
                                          
                                          using namespace std;
                                          typedef std::string String;
                                          ...
                                          void foo(string s, const String &t);     // std_string typemaps still applied
                                          

                                          Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                          8.4.2 std_vector.i

                                          The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                          %module example
                                          %include "std_vector.i"
                                          
                                          namespace std {
                                             %template(vectori) vector<int>;
                                             %template(vectord) vector<double>;
                                          };
                                          

                                          When a template vector<X> is instantiated a number of things happen:
                                          • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                          • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                          • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                          • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                          • An exception handler for std::out_of_range is defined.
                                          • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                          To illustrate the use of this library, consider the following functions:

                                          /* File : example.h */
                                          
                                          #include <vector>
                                          #include <algorithm>
                                          #include <functional>
                                          #include <numeric>
                                          
                                          double average(std::vector<int> v) {
                                              return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                          }
                                          
                                          std::vector<double> half(const std::vector<double>& v) {
                                              std::vector<double> w(v);
                                              for (unsigned int i=0; i<w.size(); i++)
                                                  w[i] /= 2.0;
                                              return w;
                                          }
                                          
                                          void halve_in_place(std::vector<double>& v) {
                                              std::transform(v.begin(),v.end(),v.begin(),
                                                             std::bind2nd(std::divides<double>(),2.0));
                                          }
                                          

                                          To wrap with SWIG, you might write the following:

                                          %module example
                                          %{
                                          #include "example.h"
                                          %}
                                          
                                          %include "std_vector.i"
                                          // Instantiate templates used by example
                                          namespace std {
                                             %template(IntVector) vector<int>;
                                             %template(DoubleVector) vector<double>;
                                          }
                                          
                                          // Include the header file with above prototypes
                                          %include "example.h"
                                          

                                          Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                          >>> from example import *
                                          >>> iv = IntVector(4)         # Create an vector<int>
                                          >>> for i in range(0,4):
                                          ...      iv[i] = i
                                          >>> average(iv)               # Call method
                                          1.5
                                          >>> average([0,1,2,3])        # Call with list
                                          1.5
                                          >>> half([1,2,3])             # Half a list
                                          (0.5,1.0,1.5)
                                          >>> halve_in_place([1,2,3])   # Oops
                                          Traceback (most recent call last):
                                            File "<stdin>", line 1, in ?
                                          TypeError: Type error. Expected _p_std__vectorTdouble_t
                                          >>> dv = DoubleVector(4)
                                          >>> for i in range(0,4):
                                          ...       dv[i] = i
                                          >>> halve_in_place(dv)       # Ok
                                          >>> for i in dv:
                                          ...       print i
                                          ...
                                          0.0
                                          0.5
                                          1.0
                                          1.5
                                          >>> dv[20] = 4.5
                                          Traceback (most recent call last):
                                            File "<stdin>", line 1, in ?
                                            File "example.py", line 81, in __setitem__
                                              def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                          IndexError: vector index out of range
                                          >>>
                                          

                                          This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                          %include "std_vector.i"
                                          
                                          namespace std {
                                              %template(IntVector) vector<int>;
                                          }
                                          
                                          using namespace std;
                                          typedef std::vector Vector;
                                          
                                          void foo(vector<int> *x, const Vector &x);
                                          

                                          Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                          Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                          Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                          8.5 Utility Libraries

                                          8.5.1 exception.i

                                          The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                          SWIG_exception(int code, const char *message)

                                          Raises an exception in the target language. code is one of the following symbolic constants:

                                          SWIG_MemoryError
                                          SWIG_IOError
                                          SWIG_RuntimeError
                                          SWIG_IndexError
                                          SWIG_TypeError
                                          SWIG_DivisionByZero
                                          SWIG_OverflowError
                                          SWIG_SyntaxError
                                          SWIG_ValueError
                                          SWIG_SystemError
                                          

                                          message is a string indicating more information about the problem.

                                          The primary use of this module is in writing language-independent exception handlers. For example:

                                          %include "exception.i"
                                          %exception std::vector::getitem {
                                              try {
                                                  $action
                                              } catch (std::out_of_range& e) {
                                                  SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                              }
                                          }
                                          

                                          ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                          

                                          SWIG-1.3 Documentation

                                          
                                          

                                          ---

                                          Table of Contents

                                          
                                          
                                          SWIG-1.3 Development Documentation
                                          • Sections
                                          • SWIG Core Documentation
                                          • Language Module Documentation
                                          • Developer Documentation
                                          • Documentation that has not yet been updated
                                          1 Preface
                                          • 1.1 Introduction
                                          • 1.2 Special Introduction for Version 1.3
                                          • 1.3 SWIG Versions
                                          • 1.4 SWIG resources
                                          • 1.5 Prerequisites
                                          • 1.6 Organization of this manual
                                          • 1.7 How to avoid reading the manual
                                          • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                            >>> make_upper("hello world")
                                            'HELLO WORLD'
                                            >>> attach_header("Hello world")
                                            'header: Hello world'
                                            >>>
                                            

                                            This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                            %cstring_output_maxsize(parm, maxparm)

                                            This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                            %cstring_output_maxsize(char *path, int maxpath);
                                            ...
                                            void get_path(char *path, int maxpath);
                                            

                                            In the target language:

                                            >>> get_path(1024)
                                            '/home/beazley/Packages/Foo/Bar'
                                            >>>
                                            

                                            This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                            %cstring_output_withsize(parm, maxparm)

                                            This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                            %cstring_output_withsize(char *data, int *maxdata);
                                            ...
                                            void get_data(char *data, int *maxdata);
                                            

                                            In the target language:

                                            >>> get_data(1024)
                                            'x627388912'
                                            >>> get_data(1024)
                                            'xyzzy'
                                            >>>
                                            

                                            This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                            %cstring_output_allocate(parm, release)

                                            This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                            void foo(char **s) {
                                                *s = (char *) malloc(64);
                                                sprintf(*s, "Hello world\n");
                                            }
                                            

                                            The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                            %cstring_output_allocate(char **s, free(*$1));
                                            ...
                                            void foo(char **s);
                                            

                                            In the target language:

                                            >>> foo()
                                            'Hello world\n'
                                            >>>
                                            

                                            %cstring_output_allocate_size(parm, szparm, release)

                                            This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                            void foo(char **s, int *sz) {
                                                *s = (char *) malloc(64);
                                                *sz = 64;
                                                // Write some binary data
                                                ...
                                            }
                                            

                                            The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                            %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                            ...
                                            void foo(char **s, int *slen);
                                            

                                            In the target language:

                                            >>> foo()
                                            '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                            >>>
                                            

                                            This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                            char  *get_data(int *len);
                                            

                                            You could wrap it with a function like this:

                                            void my_get_data(char **result, int *len) {
                                               *result = get_data(len);
                                            }
                                            

                                            Comments:
                                            • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                            • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                            • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                            • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                            8.4 C++ Library

                                            The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                            8.4.1 std_string.i

                                            The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                            %module example
                                            %include "std_string.i"
                                            
                                            std::string foo();
                                            void        bar(const std::string &x);
                                            

                                            In the target language:

                                            x = foo();                # Returns a string object
                                            bar("Hello World");       # Pass string as std::string
                                            

                                            This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                            This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                            %module example
                                            %include "std_string.i"
                                            
                                            using namespace std;
                                            typedef std::string String;
                                            ...
                                            void foo(string s, const String &t);     // std_string typemaps still applied
                                            

                                            Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                            8.4.2 std_vector.i

                                            The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                            %module example
                                            %include "std_vector.i"
                                            
                                            namespace std {
                                               %template(vectori) vector<int>;
                                               %template(vectord) vector<double>;
                                            };
                                            

                                            When a template vector<X> is instantiated a number of things happen:
                                            • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                            • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                            • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                            • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                            • An exception handler for std::out_of_range is defined.
                                            • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                            To illustrate the use of this library, consider the following functions:

                                            /* File : example.h */
                                            
                                            #include <vector>
                                            #include <algorithm>
                                            #include <functional>
                                            #include <numeric>
                                            
                                            double average(std::vector<int> v) {
                                                return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                            }
                                            
                                            std::vector<double> half(const std::vector<double>& v) {
                                                std::vector<double> w(v);
                                                for (unsigned int i=0; i<w.size(); i++)
                                                    w[i] /= 2.0;
                                                return w;
                                            }
                                            
                                            void halve_in_place(std::vector<double>& v) {
                                                std::transform(v.begin(),v.end(),v.begin(),
                                                               std::bind2nd(std::divides<double>(),2.0));
                                            }
                                            

                                            To wrap with SWIG, you might write the following:

                                            %module example
                                            %{
                                            #include "example.h"
                                            %}
                                            
                                            %include "std_vector.i"
                                            // Instantiate templates used by example
                                            namespace std {
                                               %template(IntVector) vector<int>;
                                               %template(DoubleVector) vector<double>;
                                            }
                                            
                                            // Include the header file with above prototypes
                                            %include "example.h"
                                            

                                            Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                            >>> from example import *
                                            >>> iv = IntVector(4)         # Create an vector<int>
                                            >>> for i in range(0,4):
                                            ...      iv[i] = i
                                            >>> average(iv)               # Call method
                                            1.5
                                            >>> average([0,1,2,3])        # Call with list
                                            1.5
                                            >>> half([1,2,3])             # Half a list
                                            (0.5,1.0,1.5)
                                            >>> halve_in_place([1,2,3])   # Oops
                                            Traceback (most recent call last):
                                              File "<stdin>", line 1, in ?
                                            TypeError: Type error. Expected _p_std__vectorTdouble_t
                                            >>> dv = DoubleVector(4)
                                            >>> for i in range(0,4):
                                            ...       dv[i] = i
                                            >>> halve_in_place(dv)       # Ok
                                            >>> for i in dv:
                                            ...       print i
                                            ...
                                            0.0
                                            0.5
                                            1.0
                                            1.5
                                            >>> dv[20] = 4.5
                                            Traceback (most recent call last):
                                              File "<stdin>", line 1, in ?
                                              File "example.py", line 81, in __setitem__
                                                def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                            IndexError: vector index out of range
                                            >>>
                                            

                                            This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                            %include "std_vector.i"
                                            
                                            namespace std {
                                                %template(IntVector) vector<int>;
                                            }
                                            
                                            using namespace std;
                                            typedef std::vector Vector;
                                            
                                            void foo(vector<int> *x, const Vector &x);
                                            

                                            Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                            Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                            Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                            8.5 Utility Libraries

                                            8.5.1 exception.i

                                            The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                            SWIG_exception(int code, const char *message)

                                            Raises an exception in the target language. code is one of the following symbolic constants:

                                            SWIG_MemoryError
                                            SWIG_IOError
                                            SWIG_RuntimeError
                                            SWIG_IndexError
                                            SWIG_TypeError
                                            SWIG_DivisionByZero
                                            SWIG_OverflowError
                                            SWIG_SyntaxError
                                            SWIG_ValueError
                                            SWIG_SystemError
                                            

                                            message is a string indicating more information about the problem.

                                            The primary use of this module is in writing language-independent exception handlers. For example:

                                            %include "exception.i"
                                            %exception std::vector::getitem {
                                                try {
                                                    $action
                                                } catch (std::out_of_range& e) {
                                                    SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                }
                                            }
                                            

                                            ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                            

                                            SWIG-1.3 Documentation

                                            
                                            

                                            ---

                                            Table of Contents

                                            
                                            
                                            SWIG-1.3 Development Documentation
                                            • Sections
                                            • SWIG Core Documentation
                                            • Language Module Documentation
                                            • Developer Documentation
                                            • Documentation that has not yet been updated
                                            1 Preface
                                            • 1.1 Introduction
                                            • 1.2 Special Introduction for Version 1.3
                                            • 1.3 SWIG Versions
                                            • 1.4 SWIG resources
                                            • 1.5 Prerequisites
                                            • 1.6 Organization of this manual
                                            • 1.7 How to avoid reading the manual
                                            • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                              >>> make_upper("hello world")
                                              'HELLO WORLD'
                                              >>> attach_header("Hello world")
                                              'header: Hello world'
                                              >>>
                                              

                                              This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                              %cstring_output_maxsize(parm, maxparm)

                                              This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                              %cstring_output_maxsize(char *path, int maxpath);
                                              ...
                                              void get_path(char *path, int maxpath);
                                              

                                              In the target language:

                                              >>> get_path(1024)
                                              '/home/beazley/Packages/Foo/Bar'
                                              >>>
                                              

                                              This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                              %cstring_output_withsize(parm, maxparm)

                                              This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                              %cstring_output_withsize(char *data, int *maxdata);
                                              ...
                                              void get_data(char *data, int *maxdata);
                                              

                                              In the target language:

                                              >>> get_data(1024)
                                              'x627388912'
                                              >>> get_data(1024)
                                              'xyzzy'
                                              >>>
                                              

                                              This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                              %cstring_output_allocate(parm, release)

                                              This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                              void foo(char **s) {
                                                  *s = (char *) malloc(64);
                                                  sprintf(*s, "Hello world\n");
                                              }
                                              

                                              The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                              %cstring_output_allocate(char **s, free(*$1));
                                              ...
                                              void foo(char **s);
                                              

                                              In the target language:

                                              >>> foo()
                                              'Hello world\n'
                                              >>>
                                              

                                              %cstring_output_allocate_size(parm, szparm, release)

                                              This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                              void foo(char **s, int *sz) {
                                                  *s = (char *) malloc(64);
                                                  *sz = 64;
                                                  // Write some binary data
                                                  ...
                                              }
                                              

                                              The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                              %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                              ...
                                              void foo(char **s, int *slen);
                                              

                                              In the target language:

                                              >>> foo()
                                              '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                              >>>
                                              

                                              This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                              char  *get_data(int *len);
                                              

                                              You could wrap it with a function like this:

                                              void my_get_data(char **result, int *len) {
                                                 *result = get_data(len);
                                              }
                                              

                                              Comments:
                                              • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                              • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                              • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                              • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                              8.4 C++ Library

                                              The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                              8.4.1 std_string.i

                                              The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                              %module example
                                              %include "std_string.i"
                                              
                                              std::string foo();
                                              void        bar(const std::string &x);
                                              

                                              In the target language:

                                              x = foo();                # Returns a string object
                                              bar("Hello World");       # Pass string as std::string
                                              

                                              This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                              This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                              %module example
                                              %include "std_string.i"
                                              
                                              using namespace std;
                                              typedef std::string String;
                                              ...
                                              void foo(string s, const String &t);     // std_string typemaps still applied
                                              

                                              Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                              8.4.2 std_vector.i

                                              The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                              %module example
                                              %include "std_vector.i"
                                              
                                              namespace std {
                                                 %template(vectori) vector<int>;
                                                 %template(vectord) vector<double>;
                                              };
                                              

                                              When a template vector<X> is instantiated a number of things happen:
                                              • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                              • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                              • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                              • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                              • An exception handler for std::out_of_range is defined.
                                              • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                              To illustrate the use of this library, consider the following functions:

                                              /* File : example.h */
                                              
                                              #include <vector>
                                              #include <algorithm>
                                              #include <functional>
                                              #include <numeric>
                                              
                                              double average(std::vector<int> v) {
                                                  return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                              }
                                              
                                              std::vector<double> half(const std::vector<double>& v) {
                                                  std::vector<double> w(v);
                                                  for (unsigned int i=0; i<w.size(); i++)
                                                      w[i] /= 2.0;
                                                  return w;
                                              }
                                              
                                              void halve_in_place(std::vector<double>& v) {
                                                  std::transform(v.begin(),v.end(),v.begin(),
                                                                 std::bind2nd(std::divides<double>(),2.0));
                                              }
                                              

                                              To wrap with SWIG, you might write the following:

                                              %module example
                                              %{
                                              #include "example.h"
                                              %}
                                              
                                              %include "std_vector.i"
                                              // Instantiate templates used by example
                                              namespace std {
                                                 %template(IntVector) vector<int>;
                                                 %template(DoubleVector) vector<double>;
                                              }
                                              
                                              // Include the header file with above prototypes
                                              %include "example.h"
                                              

                                              Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                              >>> from example import *
                                              >>> iv = IntVector(4)         # Create an vector<int>
                                              >>> for i in range(0,4):
                                              ...      iv[i] = i
                                              >>> average(iv)               # Call method
                                              1.5
                                              >>> average([0,1,2,3])        # Call with list
                                              1.5
                                              >>> half([1,2,3])             # Half a list
                                              (0.5,1.0,1.5)
                                              >>> halve_in_place([1,2,3])   # Oops
                                              Traceback (most recent call last):
                                                File "<stdin>", line 1, in ?
                                              TypeError: Type error. Expected _p_std__vectorTdouble_t
                                              >>> dv = DoubleVector(4)
                                              >>> for i in range(0,4):
                                              ...       dv[i] = i
                                              >>> halve_in_place(dv)       # Ok
                                              >>> for i in dv:
                                              ...       print i
                                              ...
                                              0.0
                                              0.5
                                              1.0
                                              1.5
                                              >>> dv[20] = 4.5
                                              Traceback (most recent call last):
                                                File "<stdin>", line 1, in ?
                                                File "example.py", line 81, in __setitem__
                                                  def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                              IndexError: vector index out of range
                                              >>>
                                              

                                              This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                              %include "std_vector.i"
                                              
                                              namespace std {
                                                  %template(IntVector) vector<int>;
                                              }
                                              
                                              using namespace std;
                                              typedef std::vector Vector;
                                              
                                              void foo(vector<int> *x, const Vector &x);
                                              

                                              Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                              Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                              Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                              8.5 Utility Libraries

                                              8.5.1 exception.i

                                              The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                              SWIG_exception(int code, const char *message)

                                              Raises an exception in the target language. code is one of the following symbolic constants:

                                              SWIG_MemoryError
                                              SWIG_IOError
                                              SWIG_RuntimeError
                                              SWIG_IndexError
                                              SWIG_TypeError
                                              SWIG_DivisionByZero
                                              SWIG_OverflowError
                                              SWIG_SyntaxError
                                              SWIG_ValueError
                                              SWIG_SystemError
                                              

                                              message is a string indicating more information about the problem.

                                              The primary use of this module is in writing language-independent exception handlers. For example:

                                              %include "exception.i"
                                              %exception std::vector::getitem {
                                                  try {
                                                      $action
                                                  } catch (std::out_of_range& e) {
                                                      SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                  }
                                              }
                                              

                                              ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                              

                                              SWIG-1.3 Documentation

                                              
                                              

                                              ---

                                              Table of Contents

                                              
                                              
                                              SWIG-1.3 Development Documentation
                                              • Sections
                                              • SWIG Core Documentation
                                              • Language Module Documentation
                                              • Developer Documentation
                                              • Documentation that has not yet been updated
                                              1 Preface
                                              • 1.1 Introduction
                                              • 1.2 Special Introduction for Version 1.3
                                              • 1.3 SWIG Versions
                                              • 1.4 SWIG resources
                                              • 1.5 Prerequisites
                                              • 1.6 Organization of this manual
                                              • 1.7 How to avoid reading the manual
                                              • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                                >>> make_upper("hello world")
                                                'HELLO WORLD'
                                                >>> attach_header("Hello world")
                                                'header: Hello world'
                                                >>>
                                                

                                                This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                                %cstring_output_maxsize(parm, maxparm)

                                                This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                                %cstring_output_maxsize(char *path, int maxpath);
                                                ...
                                                void get_path(char *path, int maxpath);
                                                

                                                In the target language:

                                                >>> get_path(1024)
                                                '/home/beazley/Packages/Foo/Bar'
                                                >>>
                                                

                                                This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                                %cstring_output_withsize(parm, maxparm)

                                                This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                                %cstring_output_withsize(char *data, int *maxdata);
                                                ...
                                                void get_data(char *data, int *maxdata);
                                                

                                                In the target language:

                                                >>> get_data(1024)
                                                'x627388912'
                                                >>> get_data(1024)
                                                'xyzzy'
                                                >>>
                                                

                                                This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                                %cstring_output_allocate(parm, release)

                                                This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                                void foo(char **s) {
                                                    *s = (char *) malloc(64);
                                                    sprintf(*s, "Hello world\n");
                                                }
                                                

                                                The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                %cstring_output_allocate(char **s, free(*$1));
                                                ...
                                                void foo(char **s);
                                                

                                                In the target language:

                                                >>> foo()
                                                'Hello world\n'
                                                >>>
                                                

                                                %cstring_output_allocate_size(parm, szparm, release)

                                                This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                                void foo(char **s, int *sz) {
                                                    *s = (char *) malloc(64);
                                                    *sz = 64;
                                                    // Write some binary data
                                                    ...
                                                }
                                                

                                                The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                                ...
                                                void foo(char **s, int *slen);
                                                

                                                In the target language:

                                                >>> foo()
                                                '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                                >>>
                                                

                                                This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                                char  *get_data(int *len);
                                                

                                                You could wrap it with a function like this:

                                                void my_get_data(char **result, int *len) {
                                                   *result = get_data(len);
                                                }
                                                

                                                Comments:
                                                • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                                • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                                • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                                • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                                8.4 C++ Library

                                                The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                                8.4.1 std_string.i

                                                The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                                %module example
                                                %include "std_string.i"
                                                
                                                std::string foo();
                                                void        bar(const std::string &x);
                                                

                                                In the target language:

                                                x = foo();                # Returns a string object
                                                bar("Hello World");       # Pass string as std::string
                                                

                                                This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                                This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                                %module example
                                                %include "std_string.i"
                                                
                                                using namespace std;
                                                typedef std::string String;
                                                ...
                                                void foo(string s, const String &t);     // std_string typemaps still applied
                                                

                                                Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                                8.4.2 std_vector.i

                                                The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                                %module example
                                                %include "std_vector.i"
                                                
                                                namespace std {
                                                   %template(vectori) vector<int>;
                                                   %template(vectord) vector<double>;
                                                };
                                                

                                                When a template vector<X> is instantiated a number of things happen:
                                                • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                                • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                                • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                                • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                                • An exception handler for std::out_of_range is defined.
                                                • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                                To illustrate the use of this library, consider the following functions:

                                                /* File : example.h */
                                                
                                                #include <vector>
                                                #include <algorithm>
                                                #include <functional>
                                                #include <numeric>
                                                
                                                double average(std::vector<int> v) {
                                                    return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                                }
                                                
                                                std::vector<double> half(const std::vector<double>& v) {
                                                    std::vector<double> w(v);
                                                    for (unsigned int i=0; i<w.size(); i++)
                                                        w[i] /= 2.0;
                                                    return w;
                                                }
                                                
                                                void halve_in_place(std::vector<double>& v) {
                                                    std::transform(v.begin(),v.end(),v.begin(),
                                                                   std::bind2nd(std::divides<double>(),2.0));
                                                }
                                                

                                                To wrap with SWIG, you might write the following:

                                                %module example
                                                %{
                                                #include "example.h"
                                                %}
                                                
                                                %include "std_vector.i"
                                                // Instantiate templates used by example
                                                namespace std {
                                                   %template(IntVector) vector<int>;
                                                   %template(DoubleVector) vector<double>;
                                                }
                                                
                                                // Include the header file with above prototypes
                                                %include "example.h"
                                                

                                                Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                                >>> from example import *
                                                >>> iv = IntVector(4)         # Create an vector<int>
                                                >>> for i in range(0,4):
                                                ...      iv[i] = i
                                                >>> average(iv)               # Call method
                                                1.5
                                                >>> average([0,1,2,3])        # Call with list
                                                1.5
                                                >>> half([1,2,3])             # Half a list
                                                (0.5,1.0,1.5)
                                                >>> halve_in_place([1,2,3])   # Oops
                                                Traceback (most recent call last):
                                                  File "<stdin>", line 1, in ?
                                                TypeError: Type error. Expected _p_std__vectorTdouble_t
                                                >>> dv = DoubleVector(4)
                                                >>> for i in range(0,4):
                                                ...       dv[i] = i
                                                >>> halve_in_place(dv)       # Ok
                                                >>> for i in dv:
                                                ...       print i
                                                ...
                                                0.0
                                                0.5
                                                1.0
                                                1.5
                                                >>> dv[20] = 4.5
                                                Traceback (most recent call last):
                                                  File "<stdin>", line 1, in ?
                                                  File "example.py", line 81, in __setitem__
                                                    def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                                IndexError: vector index out of range
                                                >>>
                                                

                                                This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                                %include "std_vector.i"
                                                
                                                namespace std {
                                                    %template(IntVector) vector<int>;
                                                }
                                                
                                                using namespace std;
                                                typedef std::vector Vector;
                                                
                                                void foo(vector<int> *x, const Vector &x);
                                                

                                                Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                                Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                                Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                                8.5 Utility Libraries

                                                8.5.1 exception.i

                                                The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                                SWIG_exception(int code, const char *message)

                                                Raises an exception in the target language. code is one of the following symbolic constants:

                                                SWIG_MemoryError
                                                SWIG_IOError
                                                SWIG_RuntimeError
                                                SWIG_IndexError
                                                SWIG_TypeError
                                                SWIG_DivisionByZero
                                                SWIG_OverflowError
                                                SWIG_SyntaxError
                                                SWIG_ValueError
                                                SWIG_SystemError
                                                

                                                message is a string indicating more information about the problem.

                                                The primary use of this module is in writing language-independent exception handlers. For example:

                                                %include "exception.i"
                                                %exception std::vector::getitem {
                                                    try {
                                                        $action
                                                    } catch (std::out_of_range& e) {
                                                        SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                    }
                                                }
                                                

                                                ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                                

                                                SWIG-1.3 Documentation

                                                
                                                

                                                ---

                                                Table of Contents

                                                
                                                
                                                SWIG-1.3 Development Documentation
                                                • Sections
                                                • SWIG Core Documentation
                                                • Language Module Documentation
                                                • Developer Documentation
                                                • Documentation that has not yet been updated
                                                1 Preface
                                                • 1.1 Introduction
                                                • 1.2 Special Introduction for Version 1.3
                                                • 1.3 SWIG Versions
                                                • 1.4 SWIG resources
                                                • 1.5 Prerequisites
                                                • 1.6 Organization of this manual
                                                • 1.7 How to avoid reading the manual
                                                • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                                  >>> make_upper("hello world")
                                                  'HELLO WORLD'
                                                  >>> attach_header("Hello world")
                                                  'header: Hello world'
                                                  >>>
                                                  

                                                  This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                                  %cstring_output_maxsize(parm, maxparm)

                                                  This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                                  %cstring_output_maxsize(char *path, int maxpath);
                                                  ...
                                                  void get_path(char *path, int maxpath);
                                                  

                                                  In the target language:

                                                  >>> get_path(1024)
                                                  '/home/beazley/Packages/Foo/Bar'
                                                  >>>
                                                  

                                                  This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                                  %cstring_output_withsize(parm, maxparm)

                                                  This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                                  %cstring_output_withsize(char *data, int *maxdata);
                                                  ...
                                                  void get_data(char *data, int *maxdata);
                                                  

                                                  In the target language:

                                                  >>> get_data(1024)
                                                  'x627388912'
                                                  >>> get_data(1024)
                                                  'xyzzy'
                                                  >>>
                                                  

                                                  This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                                  %cstring_output_allocate(parm, release)

                                                  This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                                  void foo(char **s) {
                                                      *s = (char *) malloc(64);
                                                      sprintf(*s, "Hello world\n");
                                                  }
                                                  

                                                  The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                  %cstring_output_allocate(char **s, free(*$1));
                                                  ...
                                                  void foo(char **s);
                                                  

                                                  In the target language:

                                                  >>> foo()
                                                  'Hello world\n'
                                                  >>>
                                                  

                                                  %cstring_output_allocate_size(parm, szparm, release)

                                                  This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                                  void foo(char **s, int *sz) {
                                                      *s = (char *) malloc(64);
                                                      *sz = 64;
                                                      // Write some binary data
                                                      ...
                                                  }
                                                  

                                                  The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                  %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                                  ...
                                                  void foo(char **s, int *slen);
                                                  

                                                  In the target language:

                                                  >>> foo()
                                                  '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                                  >>>
                                                  

                                                  This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                                  char  *get_data(int *len);
                                                  

                                                  You could wrap it with a function like this:

                                                  void my_get_data(char **result, int *len) {
                                                     *result = get_data(len);
                                                  }
                                                  

                                                  Comments:
                                                  • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                                  • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                                  • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                                  • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                                  8.4 C++ Library

                                                  The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                                  8.4.1 std_string.i

                                                  The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                                  %module example
                                                  %include "std_string.i"
                                                  
                                                  std::string foo();
                                                  void        bar(const std::string &x);
                                                  

                                                  In the target language:

                                                  x = foo();                # Returns a string object
                                                  bar("Hello World");       # Pass string as std::string
                                                  

                                                  This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                                  This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                                  %module example
                                                  %include "std_string.i"
                                                  
                                                  using namespace std;
                                                  typedef std::string String;
                                                  ...
                                                  void foo(string s, const String &t);     // std_string typemaps still applied
                                                  

                                                  Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                                  8.4.2 std_vector.i

                                                  The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                                  %module example
                                                  %include "std_vector.i"
                                                  
                                                  namespace std {
                                                     %template(vectori) vector<int>;
                                                     %template(vectord) vector<double>;
                                                  };
                                                  

                                                  When a template vector<X> is instantiated a number of things happen:
                                                  • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                                  • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                                  • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                                  • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                                  • An exception handler for std::out_of_range is defined.
                                                  • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                                  To illustrate the use of this library, consider the following functions:

                                                  /* File : example.h */
                                                  
                                                  #include <vector>
                                                  #include <algorithm>
                                                  #include <functional>
                                                  #include <numeric>
                                                  
                                                  double average(std::vector<int> v) {
                                                      return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                                  }
                                                  
                                                  std::vector<double> half(const std::vector<double>& v) {
                                                      std::vector<double> w(v);
                                                      for (unsigned int i=0; i<w.size(); i++)
                                                          w[i] /= 2.0;
                                                      return w;
                                                  }
                                                  
                                                  void halve_in_place(std::vector<double>& v) {
                                                      std::transform(v.begin(),v.end(),v.begin(),
                                                                     std::bind2nd(std::divides<double>(),2.0));
                                                  }
                                                  

                                                  To wrap with SWIG, you might write the following:

                                                  %module example
                                                  %{
                                                  #include "example.h"
                                                  %}
                                                  
                                                  %include "std_vector.i"
                                                  // Instantiate templates used by example
                                                  namespace std {
                                                     %template(IntVector) vector<int>;
                                                     %template(DoubleVector) vector<double>;
                                                  }
                                                  
                                                  // Include the header file with above prototypes
                                                  %include "example.h"
                                                  

                                                  Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                                  >>> from example import *
                                                  >>> iv = IntVector(4)         # Create an vector<int>
                                                  >>> for i in range(0,4):
                                                  ...      iv[i] = i
                                                  >>> average(iv)               # Call method
                                                  1.5
                                                  >>> average([0,1,2,3])        # Call with list
                                                  1.5
                                                  >>> half([1,2,3])             # Half a list
                                                  (0.5,1.0,1.5)
                                                  >>> halve_in_place([1,2,3])   # Oops
                                                  Traceback (most recent call last):
                                                    File "<stdin>", line 1, in ?
                                                  TypeError: Type error. Expected _p_std__vectorTdouble_t
                                                  >>> dv = DoubleVector(4)
                                                  >>> for i in range(0,4):
                                                  ...       dv[i] = i
                                                  >>> halve_in_place(dv)       # Ok
                                                  >>> for i in dv:
                                                  ...       print i
                                                  ...
                                                  0.0
                                                  0.5
                                                  1.0
                                                  1.5
                                                  >>> dv[20] = 4.5
                                                  Traceback (most recent call last):
                                                    File "<stdin>", line 1, in ?
                                                    File "example.py", line 81, in __setitem__
                                                      def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                                  IndexError: vector index out of range
                                                  >>>
                                                  

                                                  This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                                  %include "std_vector.i"
                                                  
                                                  namespace std {
                                                      %template(IntVector) vector<int>;
                                                  }
                                                  
                                                  using namespace std;
                                                  typedef std::vector Vector;
                                                  
                                                  void foo(vector<int> *x, const Vector &x);
                                                  

                                                  Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                                  Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                                  Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                                  8.5 Utility Libraries

                                                  8.5.1 exception.i

                                                  The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                                  SWIG_exception(int code, const char *message)

                                                  Raises an exception in the target language. code is one of the following symbolic constants:

                                                  SWIG_MemoryError
                                                  SWIG_IOError
                                                  SWIG_RuntimeError
                                                  SWIG_IndexError
                                                  SWIG_TypeError
                                                  SWIG_DivisionByZero
                                                  SWIG_OverflowError
                                                  SWIG_SyntaxError
                                                  SWIG_ValueError
                                                  SWIG_SystemError
                                                  

                                                  message is a string indicating more information about the problem.

                                                  The primary use of this module is in writing language-independent exception handlers. For example:

                                                  %include "exception.i"
                                                  %exception std::vector::getitem {
                                                      try {
                                                          $action
                                                      } catch (std::out_of_range& e) {
                                                          SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                      }
                                                  }
                                                  

                                                  ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                                  

                                                  SWIG-1.3 Documentation

                                                  
                                                  

                                                  ---

                                                  Table of Contents

                                                  
                                                  
                                                  SWIG-1.3 Development Documentation
                                                  • Sections
                                                  • SWIG Core Documentation
                                                  • Language Module Documentation
                                                  • Developer Documentation
                                                  • Documentation that has not yet been updated
                                                  1 Preface
                                                  • 1.1 Introduction
                                                  • 1.2 Special Introduction for Version 1.3
                                                  • 1.3 SWIG Versions
                                                  • 1.4 SWIG resources
                                                  • 1.5 Prerequisites
                                                  • 1.6 Organization of this manual
                                                  • 1.7 How to avoid reading the manual
                                                  • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                                    >>> make_upper("hello world")
                                                    'HELLO WORLD'
                                                    >>> attach_header("Hello world")
                                                    'header: Hello world'
                                                    >>>
                                                    

                                                    This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                                    %cstring_output_maxsize(parm, maxparm)

                                                    This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                                    %cstring_output_maxsize(char *path, int maxpath);
                                                    ...
                                                    void get_path(char *path, int maxpath);
                                                    

                                                    In the target language:

                                                    >>> get_path(1024)
                                                    '/home/beazley/Packages/Foo/Bar'
                                                    >>>
                                                    

                                                    This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                                    %cstring_output_withsize(parm, maxparm)

                                                    This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                                    %cstring_output_withsize(char *data, int *maxdata);
                                                    ...
                                                    void get_data(char *data, int *maxdata);
                                                    

                                                    In the target language:

                                                    >>> get_data(1024)
                                                    'x627388912'
                                                    >>> get_data(1024)
                                                    'xyzzy'
                                                    >>>
                                                    

                                                    This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                                    %cstring_output_allocate(parm, release)

                                                    This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                                    void foo(char **s) {
                                                        *s = (char *) malloc(64);
                                                        sprintf(*s, "Hello world\n");
                                                    }
                                                    

                                                    The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                    %cstring_output_allocate(char **s, free(*$1));
                                                    ...
                                                    void foo(char **s);
                                                    

                                                    In the target language:

                                                    >>> foo()
                                                    'Hello world\n'
                                                    >>>
                                                    

                                                    %cstring_output_allocate_size(parm, szparm, release)

                                                    This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                                    void foo(char **s, int *sz) {
                                                        *s = (char *) malloc(64);
                                                        *sz = 64;
                                                        // Write some binary data
                                                        ...
                                                    }
                                                    

                                                    The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                    %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                                    ...
                                                    void foo(char **s, int *slen);
                                                    

                                                    In the target language:

                                                    >>> foo()
                                                    '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                                    >>>
                                                    

                                                    This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                                    char  *get_data(int *len);
                                                    

                                                    You could wrap it with a function like this:

                                                    void my_get_data(char **result, int *len) {
                                                       *result = get_data(len);
                                                    }
                                                    

                                                    Comments:
                                                    • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                                    • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                                    • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                                    • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                                    8.4 C++ Library

                                                    The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                                    8.4.1 std_string.i

                                                    The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                                    %module example
                                                    %include "std_string.i"
                                                    
                                                    std::string foo();
                                                    void        bar(const std::string &x);
                                                    

                                                    In the target language:

                                                    x = foo();                # Returns a string object
                                                    bar("Hello World");       # Pass string as std::string
                                                    

                                                    This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                                    This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                                    %module example
                                                    %include "std_string.i"
                                                    
                                                    using namespace std;
                                                    typedef std::string String;
                                                    ...
                                                    void foo(string s, const String &t);     // std_string typemaps still applied
                                                    

                                                    Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                                    8.4.2 std_vector.i

                                                    The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                                    %module example
                                                    %include "std_vector.i"
                                                    
                                                    namespace std {
                                                       %template(vectori) vector<int>;
                                                       %template(vectord) vector<double>;
                                                    };
                                                    

                                                    When a template vector<X> is instantiated a number of things happen:
                                                    • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                                    • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                                    • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                                    • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                                    • An exception handler for std::out_of_range is defined.
                                                    • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                                    To illustrate the use of this library, consider the following functions:

                                                    /* File : example.h */
                                                    
                                                    #include <vector>
                                                    #include <algorithm>
                                                    #include <functional>
                                                    #include <numeric>
                                                    
                                                    double average(std::vector<int> v) {
                                                        return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                                    }
                                                    
                                                    std::vector<double> half(const std::vector<double>& v) {
                                                        std::vector<double> w(v);
                                                        for (unsigned int i=0; i<w.size(); i++)
                                                            w[i] /= 2.0;
                                                        return w;
                                                    }
                                                    
                                                    void halve_in_place(std::vector<double>& v) {
                                                        std::transform(v.begin(),v.end(),v.begin(),
                                                                       std::bind2nd(std::divides<double>(),2.0));
                                                    }
                                                    

                                                    To wrap with SWIG, you might write the following:

                                                    %module example
                                                    %{
                                                    #include "example.h"
                                                    %}
                                                    
                                                    %include "std_vector.i"
                                                    // Instantiate templates used by example
                                                    namespace std {
                                                       %template(IntVector) vector<int>;
                                                       %template(DoubleVector) vector<double>;
                                                    }
                                                    
                                                    // Include the header file with above prototypes
                                                    %include "example.h"
                                                    

                                                    Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                                    >>> from example import *
                                                    >>> iv = IntVector(4)         # Create an vector<int>
                                                    >>> for i in range(0,4):
                                                    ...      iv[i] = i
                                                    >>> average(iv)               # Call method
                                                    1.5
                                                    >>> average([0,1,2,3])        # Call with list
                                                    1.5
                                                    >>> half([1,2,3])             # Half a list
                                                    (0.5,1.0,1.5)
                                                    >>> halve_in_place([1,2,3])   # Oops
                                                    Traceback (most recent call last):
                                                      File "<stdin>", line 1, in ?
                                                    TypeError: Type error. Expected _p_std__vectorTdouble_t
                                                    >>> dv = DoubleVector(4)
                                                    >>> for i in range(0,4):
                                                    ...       dv[i] = i
                                                    >>> halve_in_place(dv)       # Ok
                                                    >>> for i in dv:
                                                    ...       print i
                                                    ...
                                                    0.0
                                                    0.5
                                                    1.0
                                                    1.5
                                                    >>> dv[20] = 4.5
                                                    Traceback (most recent call last):
                                                      File "<stdin>", line 1, in ?
                                                      File "example.py", line 81, in __setitem__
                                                        def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                                    IndexError: vector index out of range
                                                    >>>
                                                    

                                                    This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                                    %include "std_vector.i"
                                                    
                                                    namespace std {
                                                        %template(IntVector) vector<int>;
                                                    }
                                                    
                                                    using namespace std;
                                                    typedef std::vector Vector;
                                                    
                                                    void foo(vector<int> *x, const Vector &x);
                                                    

                                                    Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                                    Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                                    Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                                    8.5 Utility Libraries

                                                    8.5.1 exception.i

                                                    The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                                    SWIG_exception(int code, const char *message)

                                                    Raises an exception in the target language. code is one of the following symbolic constants:

                                                    SWIG_MemoryError
                                                    SWIG_IOError
                                                    SWIG_RuntimeError
                                                    SWIG_IndexError
                                                    SWIG_TypeError
                                                    SWIG_DivisionByZero
                                                    SWIG_OverflowError
                                                    SWIG_SyntaxError
                                                    SWIG_ValueError
                                                    SWIG_SystemError
                                                    

                                                    message is a string indicating more information about the problem.

                                                    The primary use of this module is in writing language-independent exception handlers. For example:

                                                    %include "exception.i"
                                                    %exception std::vector::getitem {
                                                        try {
                                                            $action
                                                        } catch (std::out_of_range& e) {
                                                            SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                        }
                                                    }
                                                    

                                                    ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                                    

                                                    SWIG-1.3 Documentation

                                                    
                                                    

                                                    ---

                                                    Table of Contents

                                                    
                                                    
                                                    SWIG-1.3 Development Documentation
                                                    • Sections
                                                    • SWIG Core Documentation
                                                    • Language Module Documentation
                                                    • Developer Documentation
                                                    • Documentation that has not yet been updated
                                                    1 Preface
                                                    • 1.1 Introduction
                                                    • 1.2 Special Introduction for Version 1.3
                                                    • 1.3 SWIG Versions
                                                    • 1.4 SWIG resources
                                                    • 1.5 Prerequisites
                                                    • 1.6 Organization of this manual
                                                    • 1.7 How to avoid reading the manual
                                                    • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                                      >>> make_upper("hello world")
                                                      'HELLO WORLD'
                                                      >>> attach_header("Hello world")
                                                      'header: Hello world'
                                                      >>>
                                                      

                                                      This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                                      %cstring_output_maxsize(parm, maxparm)

                                                      This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                                      %cstring_output_maxsize(char *path, int maxpath);
                                                      ...
                                                      void get_path(char *path, int maxpath);
                                                      

                                                      In the target language:

                                                      >>> get_path(1024)
                                                      '/home/beazley/Packages/Foo/Bar'
                                                      >>>
                                                      

                                                      This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                                      %cstring_output_withsize(parm, maxparm)

                                                      This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                                      %cstring_output_withsize(char *data, int *maxdata);
                                                      ...
                                                      void get_data(char *data, int *maxdata);
                                                      

                                                      In the target language:

                                                      >>> get_data(1024)
                                                      'x627388912'
                                                      >>> get_data(1024)
                                                      'xyzzy'
                                                      >>>
                                                      

                                                      This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                                      %cstring_output_allocate(parm, release)

                                                      This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                                      void foo(char **s) {
                                                          *s = (char *) malloc(64);
                                                          sprintf(*s, "Hello world\n");
                                                      }
                                                      

                                                      The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                      %cstring_output_allocate(char **s, free(*$1));
                                                      ...
                                                      void foo(char **s);
                                                      

                                                      In the target language:

                                                      >>> foo()
                                                      'Hello world\n'
                                                      >>>
                                                      

                                                      %cstring_output_allocate_size(parm, szparm, release)

                                                      This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                                      void foo(char **s, int *sz) {
                                                          *s = (char *) malloc(64);
                                                          *sz = 64;
                                                          // Write some binary data
                                                          ...
                                                      }
                                                      

                                                      The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                      %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                                      ...
                                                      void foo(char **s, int *slen);
                                                      

                                                      In the target language:

                                                      >>> foo()
                                                      '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                                      >>>
                                                      

                                                      This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                                      char  *get_data(int *len);
                                                      

                                                      You could wrap it with a function like this:

                                                      void my_get_data(char **result, int *len) {
                                                         *result = get_data(len);
                                                      }
                                                      

                                                      Comments:
                                                      • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                                      • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                                      • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                                      • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                                      8.4 C++ Library

                                                      The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                                      8.4.1 std_string.i

                                                      The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                                      %module example
                                                      %include "std_string.i"
                                                      
                                                      std::string foo();
                                                      void        bar(const std::string &x);
                                                      

                                                      In the target language:

                                                      x = foo();                # Returns a string object
                                                      bar("Hello World");       # Pass string as std::string
                                                      

                                                      This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                                      This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                                      %module example
                                                      %include "std_string.i"
                                                      
                                                      using namespace std;
                                                      typedef std::string String;
                                                      ...
                                                      void foo(string s, const String &t);     // std_string typemaps still applied
                                                      

                                                      Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                                      8.4.2 std_vector.i

                                                      The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                                      %module example
                                                      %include "std_vector.i"
                                                      
                                                      namespace std {
                                                         %template(vectori) vector<int>;
                                                         %template(vectord) vector<double>;
                                                      };
                                                      

                                                      When a template vector<X> is instantiated a number of things happen:
                                                      • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                                      • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                                      • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                                      • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                                      • An exception handler for std::out_of_range is defined.
                                                      • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                                      To illustrate the use of this library, consider the following functions:

                                                      /* File : example.h */
                                                      
                                                      #include <vector>
                                                      #include <algorithm>
                                                      #include <functional>
                                                      #include <numeric>
                                                      
                                                      double average(std::vector<int> v) {
                                                          return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                                      }
                                                      
                                                      std::vector<double> half(const std::vector<double>& v) {
                                                          std::vector<double> w(v);
                                                          for (unsigned int i=0; i<w.size(); i++)
                                                              w[i] /= 2.0;
                                                          return w;
                                                      }
                                                      
                                                      void halve_in_place(std::vector<double>& v) {
                                                          std::transform(v.begin(),v.end(),v.begin(),
                                                                         std::bind2nd(std::divides<double>(),2.0));
                                                      }
                                                      

                                                      To wrap with SWIG, you might write the following:

                                                      %module example
                                                      %{
                                                      #include "example.h"
                                                      %}
                                                      
                                                      %include "std_vector.i"
                                                      // Instantiate templates used by example
                                                      namespace std {
                                                         %template(IntVector) vector<int>;
                                                         %template(DoubleVector) vector<double>;
                                                      }
                                                      
                                                      // Include the header file with above prototypes
                                                      %include "example.h"
                                                      

                                                      Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                                      >>> from example import *
                                                      >>> iv = IntVector(4)         # Create an vector<int>
                                                      >>> for i in range(0,4):
                                                      ...      iv[i] = i
                                                      >>> average(iv)               # Call method
                                                      1.5
                                                      >>> average([0,1,2,3])        # Call with list
                                                      1.5
                                                      >>> half([1,2,3])             # Half a list
                                                      (0.5,1.0,1.5)
                                                      >>> halve_in_place([1,2,3])   # Oops
                                                      Traceback (most recent call last):
                                                        File "<stdin>", line 1, in ?
                                                      TypeError: Type error. Expected _p_std__vectorTdouble_t
                                                      >>> dv = DoubleVector(4)
                                                      >>> for i in range(0,4):
                                                      ...       dv[i] = i
                                                      >>> halve_in_place(dv)       # Ok
                                                      >>> for i in dv:
                                                      ...       print i
                                                      ...
                                                      0.0
                                                      0.5
                                                      1.0
                                                      1.5
                                                      >>> dv[20] = 4.5
                                                      Traceback (most recent call last):
                                                        File "<stdin>", line 1, in ?
                                                        File "example.py", line 81, in __setitem__
                                                          def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                                      IndexError: vector index out of range
                                                      >>>
                                                      

                                                      This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                                      %include "std_vector.i"
                                                      
                                                      namespace std {
                                                          %template(IntVector) vector<int>;
                                                      }
                                                      
                                                      using namespace std;
                                                      typedef std::vector Vector;
                                                      
                                                      void foo(vector<int> *x, const Vector &x);
                                                      

                                                      Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                                      Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                                      Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                                      8.5 Utility Libraries

                                                      8.5.1 exception.i

                                                      The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                                      SWIG_exception(int code, const char *message)

                                                      Raises an exception in the target language. code is one of the following symbolic constants:

                                                      SWIG_MemoryError
                                                      SWIG_IOError
                                                      SWIG_RuntimeError
                                                      SWIG_IndexError
                                                      SWIG_TypeError
                                                      SWIG_DivisionByZero
                                                      SWIG_OverflowError
                                                      SWIG_SyntaxError
                                                      SWIG_ValueError
                                                      SWIG_SystemError
                                                      

                                                      message is a string indicating more information about the problem.

                                                      The primary use of this module is in writing language-independent exception handlers. For example:

                                                      %include "exception.i"
                                                      %exception std::vector::getitem {
                                                          try {
                                                              $action
                                                          } catch (std::out_of_range& e) {
                                                              SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                          }
                                                      }
                                                      

                                                      ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                                      

                                                      SWIG-1.3 Documentation

                                                      
                                                      

                                                      ---

                                                      Table of Contents

                                                      
                                                      
                                                      SWIG-1.3 Development Documentation
                                                      • Sections
                                                      • SWIG Core Documentation
                                                      • Language Module Documentation
                                                      • Developer Documentation
                                                      • Documentation that has not yet been updated
                                                      1 Preface
                                                      • 1.1 Introduction
                                                      • 1.2 Special Introduction for Version 1.3
                                                      • 1.3 SWIG Versions
                                                      • 1.4 SWIG resources
                                                      • 1.5 Prerequisites
                                                      • 1.6 Organization of this manual
                                                      • 1.7 How to avoid reading the manual
                                                      • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                                        >>> make_upper("hello world")
                                                        'HELLO WORLD'
                                                        >>> attach_header("Hello world")
                                                        'header: Hello world'
                                                        >>>
                                                        

                                                        This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                                        %cstring_output_maxsize(parm, maxparm)

                                                        This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                                        %cstring_output_maxsize(char *path, int maxpath);
                                                        ...
                                                        void get_path(char *path, int maxpath);
                                                        

                                                        In the target language:

                                                        >>> get_path(1024)
                                                        '/home/beazley/Packages/Foo/Bar'
                                                        >>>
                                                        

                                                        This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                                        %cstring_output_withsize(parm, maxparm)

                                                        This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                                        %cstring_output_withsize(char *data, int *maxdata);
                                                        ...
                                                        void get_data(char *data, int *maxdata);
                                                        

                                                        In the target language:

                                                        >>> get_data(1024)
                                                        'x627388912'
                                                        >>> get_data(1024)
                                                        'xyzzy'
                                                        >>>
                                                        

                                                        This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                                        %cstring_output_allocate(parm, release)

                                                        This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                                        void foo(char **s) {
                                                            *s = (char *) malloc(64);
                                                            sprintf(*s, "Hello world\n");
                                                        }
                                                        

                                                        The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                        %cstring_output_allocate(char **s, free(*$1));
                                                        ...
                                                        void foo(char **s);
                                                        

                                                        In the target language:

                                                        >>> foo()
                                                        'Hello world\n'
                                                        >>>
                                                        

                                                        %cstring_output_allocate_size(parm, szparm, release)

                                                        This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                                        void foo(char **s, int *sz) {
                                                            *s = (char *) malloc(64);
                                                            *sz = 64;
                                                            // Write some binary data
                                                            ...
                                                        }
                                                        

                                                        The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                        %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                                        ...
                                                        void foo(char **s, int *slen);
                                                        

                                                        In the target language:

                                                        >>> foo()
                                                        '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                                        >>>
                                                        

                                                        This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                                        char  *get_data(int *len);
                                                        

                                                        You could wrap it with a function like this:

                                                        void my_get_data(char **result, int *len) {
                                                           *result = get_data(len);
                                                        }
                                                        

                                                        Comments:
                                                        • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                                        • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                                        • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                                        • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                                        8.4 C++ Library

                                                        The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                                        8.4.1 std_string.i

                                                        The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                                        %module example
                                                        %include "std_string.i"
                                                        
                                                        std::string foo();
                                                        void        bar(const std::string &x);
                                                        

                                                        In the target language:

                                                        x = foo();                # Returns a string object
                                                        bar("Hello World");       # Pass string as std::string
                                                        

                                                        This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                                        This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                                        %module example
                                                        %include "std_string.i"
                                                        
                                                        using namespace std;
                                                        typedef std::string String;
                                                        ...
                                                        void foo(string s, const String &t);     // std_string typemaps still applied
                                                        

                                                        Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                                        8.4.2 std_vector.i

                                                        The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                                        %module example
                                                        %include "std_vector.i"
                                                        
                                                        namespace std {
                                                           %template(vectori) vector<int>;
                                                           %template(vectord) vector<double>;
                                                        };
                                                        

                                                        When a template vector<X> is instantiated a number of things happen:
                                                        • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                                        • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                                        • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                                        • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                                        • An exception handler for std::out_of_range is defined.
                                                        • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                                        To illustrate the use of this library, consider the following functions:

                                                        /* File : example.h */
                                                        
                                                        #include <vector>
                                                        #include <algorithm>
                                                        #include <functional>
                                                        #include <numeric>
                                                        
                                                        double average(std::vector<int> v) {
                                                            return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                                        }
                                                        
                                                        std::vector<double> half(const std::vector<double>& v) {
                                                            std::vector<double> w(v);
                                                            for (unsigned int i=0; i<w.size(); i++)
                                                                w[i] /= 2.0;
                                                            return w;
                                                        }
                                                        
                                                        void halve_in_place(std::vector<double>& v) {
                                                            std::transform(v.begin(),v.end(),v.begin(),
                                                                           std::bind2nd(std::divides<double>(),2.0));
                                                        }
                                                        

                                                        To wrap with SWIG, you might write the following:

                                                        %module example
                                                        %{
                                                        #include "example.h"
                                                        %}
                                                        
                                                        %include "std_vector.i"
                                                        // Instantiate templates used by example
                                                        namespace std {
                                                           %template(IntVector) vector<int>;
                                                           %template(DoubleVector) vector<double>;
                                                        }
                                                        
                                                        // Include the header file with above prototypes
                                                        %include "example.h"
                                                        

                                                        Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                                        >>> from example import *
                                                        >>> iv = IntVector(4)         # Create an vector<int>
                                                        >>> for i in range(0,4):
                                                        ...      iv[i] = i
                                                        >>> average(iv)               # Call method
                                                        1.5
                                                        >>> average([0,1,2,3])        # Call with list
                                                        1.5
                                                        >>> half([1,2,3])             # Half a list
                                                        (0.5,1.0,1.5)
                                                        >>> halve_in_place([1,2,3])   # Oops
                                                        Traceback (most recent call last):
                                                          File "<stdin>", line 1, in ?
                                                        TypeError: Type error. Expected _p_std__vectorTdouble_t
                                                        >>> dv = DoubleVector(4)
                                                        >>> for i in range(0,4):
                                                        ...       dv[i] = i
                                                        >>> halve_in_place(dv)       # Ok
                                                        >>> for i in dv:
                                                        ...       print i
                                                        ...
                                                        0.0
                                                        0.5
                                                        1.0
                                                        1.5
                                                        >>> dv[20] = 4.5
                                                        Traceback (most recent call last):
                                                          File "<stdin>", line 1, in ?
                                                          File "example.py", line 81, in __setitem__
                                                            def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                                        IndexError: vector index out of range
                                                        >>>
                                                        

                                                        This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                                        %include "std_vector.i"
                                                        
                                                        namespace std {
                                                            %template(IntVector) vector<int>;
                                                        }
                                                        
                                                        using namespace std;
                                                        typedef std::vector Vector;
                                                        
                                                        void foo(vector<int> *x, const Vector &x);
                                                        

                                                        Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                                        Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                                        Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                                        8.5 Utility Libraries

                                                        8.5.1 exception.i

                                                        The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                                        SWIG_exception(int code, const char *message)

                                                        Raises an exception in the target language. code is one of the following symbolic constants:

                                                        SWIG_MemoryError
                                                        SWIG_IOError
                                                        SWIG_RuntimeError
                                                        SWIG_IndexError
                                                        SWIG_TypeError
                                                        SWIG_DivisionByZero
                                                        SWIG_OverflowError
                                                        SWIG_SyntaxError
                                                        SWIG_ValueError
                                                        SWIG_SystemError
                                                        

                                                        message is a string indicating more information about the problem.

                                                        The primary use of this module is in writing language-independent exception handlers. For example:

                                                        %include "exception.i"
                                                        %exception std::vector::getitem {
                                                            try {
                                                                $action
                                                            } catch (std::out_of_range& e) {
                                                                SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                            }
                                                        }
                                                        

                                                        ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                                        

                                                        SWIG-1.3 Documentation

                                                        
                                                        

                                                        ---

                                                        Table of Contents

                                                        
                                                        
                                                        SWIG-1.3 Development Documentation
                                                        • Sections
                                                        • SWIG Core Documentation
                                                        • Language Module Documentation
                                                        • Developer Documentation
                                                        • Documentation that has not yet been updated
                                                        1 Preface
                                                        • 1.1 Introduction
                                                        • 1.2 Special Introduction for Version 1.3
                                                        • 1.3 SWIG Versions
                                                        • 1.4 SWIG resources
                                                        • 1.5 Prerequisites
                                                        • 1.6 Organization of this manual
                                                        • 1.7 How to avoid reading the manual
                                                        • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                                          >>> make_upper("hello world")
                                                          'HELLO WORLD'
                                                          >>> attach_header("Hello world")
                                                          'header: Hello world'
                                                          >>>
                                                          

                                                          This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                                          %cstring_output_maxsize(parm, maxparm)

                                                          This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                                          %cstring_output_maxsize(char *path, int maxpath);
                                                          ...
                                                          void get_path(char *path, int maxpath);
                                                          

                                                          In the target language:

                                                          >>> get_path(1024)
                                                          '/home/beazley/Packages/Foo/Bar'
                                                          >>>
                                                          

                                                          This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                                          %cstring_output_withsize(parm, maxparm)

                                                          This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                                          %cstring_output_withsize(char *data, int *maxdata);
                                                          ...
                                                          void get_data(char *data, int *maxdata);
                                                          

                                                          In the target language:

                                                          >>> get_data(1024)
                                                          'x627388912'
                                                          >>> get_data(1024)
                                                          'xyzzy'
                                                          >>>
                                                          

                                                          This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                                          %cstring_output_allocate(parm, release)

                                                          This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                                          void foo(char **s) {
                                                              *s = (char *) malloc(64);
                                                              sprintf(*s, "Hello world\n");
                                                          }
                                                          

                                                          The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                          %cstring_output_allocate(char **s, free(*$1));
                                                          ...
                                                          void foo(char **s);
                                                          

                                                          In the target language:

                                                          >>> foo()
                                                          'Hello world\n'
                                                          >>>
                                                          

                                                          %cstring_output_allocate_size(parm, szparm, release)

                                                          This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                                          void foo(char **s, int *sz) {
                                                              *s = (char *) malloc(64);
                                                              *sz = 64;
                                                              // Write some binary data
                                                              ...
                                                          }
                                                          

                                                          The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                          %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                                          ...
                                                          void foo(char **s, int *slen);
                                                          

                                                          In the target language:

                                                          >>> foo()
                                                          '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                                          >>>
                                                          

                                                          This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                                          char  *get_data(int *len);
                                                          

                                                          You could wrap it with a function like this:

                                                          void my_get_data(char **result, int *len) {
                                                             *result = get_data(len);
                                                          }
                                                          

                                                          Comments:
                                                          • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                                          • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                                          • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                                          • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                                          8.4 C++ Library

                                                          The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                                          8.4.1 std_string.i

                                                          The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                                          %module example
                                                          %include "std_string.i"
                                                          
                                                          std::string foo();
                                                          void        bar(const std::string &x);
                                                          

                                                          In the target language:

                                                          x = foo();                # Returns a string object
                                                          bar("Hello World");       # Pass string as std::string
                                                          

                                                          This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                                          This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                                          %module example
                                                          %include "std_string.i"
                                                          
                                                          using namespace std;
                                                          typedef std::string String;
                                                          ...
                                                          void foo(string s, const String &t);     // std_string typemaps still applied
                                                          

                                                          Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                                          8.4.2 std_vector.i

                                                          The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                                          %module example
                                                          %include "std_vector.i"
                                                          
                                                          namespace std {
                                                             %template(vectori) vector<int>;
                                                             %template(vectord) vector<double>;
                                                          };
                                                          

                                                          When a template vector<X> is instantiated a number of things happen:
                                                          • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                                          • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                                          • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                                          • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                                          • An exception handler for std::out_of_range is defined.
                                                          • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                                          To illustrate the use of this library, consider the following functions:

                                                          /* File : example.h */
                                                          
                                                          #include <vector>
                                                          #include <algorithm>
                                                          #include <functional>
                                                          #include <numeric>
                                                          
                                                          double average(std::vector<int> v) {
                                                              return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                                          }
                                                          
                                                          std::vector<double> half(const std::vector<double>& v) {
                                                              std::vector<double> w(v);
                                                              for (unsigned int i=0; i<w.size(); i++)
                                                                  w[i] /= 2.0;
                                                              return w;
                                                          }
                                                          
                                                          void halve_in_place(std::vector<double>& v) {
                                                              std::transform(v.begin(),v.end(),v.begin(),
                                                                             std::bind2nd(std::divides<double>(),2.0));
                                                          }
                                                          

                                                          To wrap with SWIG, you might write the following:

                                                          %module example
                                                          %{
                                                          #include "example.h"
                                                          %}
                                                          
                                                          %include "std_vector.i"
                                                          // Instantiate templates used by example
                                                          namespace std {
                                                             %template(IntVector) vector<int>;
                                                             %template(DoubleVector) vector<double>;
                                                          }
                                                          
                                                          // Include the header file with above prototypes
                                                          %include "example.h"
                                                          

                                                          Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                                          >>> from example import *
                                                          >>> iv = IntVector(4)         # Create an vector<int>
                                                          >>> for i in range(0,4):
                                                          ...      iv[i] = i
                                                          >>> average(iv)               # Call method
                                                          1.5
                                                          >>> average([0,1,2,3])        # Call with list
                                                          1.5
                                                          >>> half([1,2,3])             # Half a list
                                                          (0.5,1.0,1.5)
                                                          >>> halve_in_place([1,2,3])   # Oops
                                                          Traceback (most recent call last):
                                                            File "<stdin>", line 1, in ?
                                                          TypeError: Type error. Expected _p_std__vectorTdouble_t
                                                          >>> dv = DoubleVector(4)
                                                          >>> for i in range(0,4):
                                                          ...       dv[i] = i
                                                          >>> halve_in_place(dv)       # Ok
                                                          >>> for i in dv:
                                                          ...       print i
                                                          ...
                                                          0.0
                                                          0.5
                                                          1.0
                                                          1.5
                                                          >>> dv[20] = 4.5
                                                          Traceback (most recent call last):
                                                            File "<stdin>", line 1, in ?
                                                            File "example.py", line 81, in __setitem__
                                                              def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                                          IndexError: vector index out of range
                                                          >>>
                                                          

                                                          This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                                          %include "std_vector.i"
                                                          
                                                          namespace std {
                                                              %template(IntVector) vector<int>;
                                                          }
                                                          
                                                          using namespace std;
                                                          typedef std::vector Vector;
                                                          
                                                          void foo(vector<int> *x, const Vector &x);
                                                          

                                                          Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                                          Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                                          Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                                          8.5 Utility Libraries

                                                          8.5.1 exception.i

                                                          The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                                          SWIG_exception(int code, const char *message)

                                                          Raises an exception in the target language. code is one of the following symbolic constants:

                                                          SWIG_MemoryError
                                                          SWIG_IOError
                                                          SWIG_RuntimeError
                                                          SWIG_IndexError
                                                          SWIG_TypeError
                                                          SWIG_DivisionByZero
                                                          SWIG_OverflowError
                                                          SWIG_SyntaxError
                                                          SWIG_ValueError
                                                          SWIG_SystemError
                                                          

                                                          message is a string indicating more information about the problem.

                                                          The primary use of this module is in writing language-independent exception handlers. For example:

                                                          %include "exception.i"
                                                          %exception std::vector::getitem {
                                                              try {
                                                                  $action
                                                              } catch (std::out_of_range& e) {
                                                                  SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                              }
                                                          }
                                                          

                                                          ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                                          

                                                          SWIG-1.3 Documentation

                                                          
                                                          

                                                          ---

                                                          Table of Contents

                                                          
                                                          
                                                          SWIG-1.3 Development Documentation
                                                          • Sections
                                                          • SWIG Core Documentation
                                                          • Language Module Documentation
                                                          • Developer Documentation
                                                          • Documentation that has not yet been updated
                                                          1 Preface
                                                          • 1.1 Introduction
                                                          • 1.2 Special Introduction for Version 1.3
                                                          • 1.3 SWIG Versions
                                                          • 1.4 SWIG resources
                                                          • 1.5 Prerequisites
                                                          • 1.6 Organization of this manual
                                                          • 1.7 How to avoid reading the manual
                                                          • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                                            >>> make_upper("hello world")
                                                            'HELLO WORLD'
                                                            >>> attach_header("Hello world")
                                                            'header: Hello world'
                                                            >>>
                                                            

                                                            This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                                            %cstring_output_maxsize(parm, maxparm)

                                                            This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                                            %cstring_output_maxsize(char *path, int maxpath);
                                                            ...
                                                            void get_path(char *path, int maxpath);
                                                            

                                                            In the target language:

                                                            >>> get_path(1024)
                                                            '/home/beazley/Packages/Foo/Bar'
                                                            >>>
                                                            

                                                            This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                                            %cstring_output_withsize(parm, maxparm)

                                                            This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                                            %cstring_output_withsize(char *data, int *maxdata);
                                                            ...
                                                            void get_data(char *data, int *maxdata);
                                                            

                                                            In the target language:

                                                            >>> get_data(1024)
                                                            'x627388912'
                                                            >>> get_data(1024)
                                                            'xyzzy'
                                                            >>>
                                                            

                                                            This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                                            %cstring_output_allocate(parm, release)

                                                            This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                                            void foo(char **s) {
                                                                *s = (char *) malloc(64);
                                                                sprintf(*s, "Hello world\n");
                                                            }
                                                            

                                                            The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                            %cstring_output_allocate(char **s, free(*$1));
                                                            ...
                                                            void foo(char **s);
                                                            

                                                            In the target language:

                                                            >>> foo()
                                                            'Hello world\n'
                                                            >>>
                                                            

                                                            %cstring_output_allocate_size(parm, szparm, release)

                                                            This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                                            void foo(char **s, int *sz) {
                                                                *s = (char *) malloc(64);
                                                                *sz = 64;
                                                                // Write some binary data
                                                                ...
                                                            }
                                                            

                                                            The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                            %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                                            ...
                                                            void foo(char **s, int *slen);
                                                            

                                                            In the target language:

                                                            >>> foo()
                                                            '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                                            >>>
                                                            

                                                            This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                                            char  *get_data(int *len);
                                                            

                                                            You could wrap it with a function like this:

                                                            void my_get_data(char **result, int *len) {
                                                               *result = get_data(len);
                                                            }
                                                            

                                                            Comments:
                                                            • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                                            • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                                            • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                                            • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                                            8.4 C++ Library

                                                            The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                                            8.4.1 std_string.i

                                                            The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                                            %module example
                                                            %include "std_string.i"
                                                            
                                                            std::string foo();
                                                            void        bar(const std::string &x);
                                                            

                                                            In the target language:

                                                            x = foo();                # Returns a string object
                                                            bar("Hello World");       # Pass string as std::string
                                                            

                                                            This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                                            This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                                            %module example
                                                            %include "std_string.i"
                                                            
                                                            using namespace std;
                                                            typedef std::string String;
                                                            ...
                                                            void foo(string s, const String &t);     // std_string typemaps still applied
                                                            

                                                            Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                                            8.4.2 std_vector.i

                                                            The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                                            %module example
                                                            %include "std_vector.i"
                                                            
                                                            namespace std {
                                                               %template(vectori) vector<int>;
                                                               %template(vectord) vector<double>;
                                                            };
                                                            

                                                            When a template vector<X> is instantiated a number of things happen:
                                                            • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                                            • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                                            • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                                            • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                                            • An exception handler for std::out_of_range is defined.
                                                            • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                                            To illustrate the use of this library, consider the following functions:

                                                            /* File : example.h */
                                                            
                                                            #include <vector>
                                                            #include <algorithm>
                                                            #include <functional>
                                                            #include <numeric>
                                                            
                                                            double average(std::vector<int> v) {
                                                                return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                                            }
                                                            
                                                            std::vector<double> half(const std::vector<double>& v) {
                                                                std::vector<double> w(v);
                                                                for (unsigned int i=0; i<w.size(); i++)
                                                                    w[i] /= 2.0;
                                                                return w;
                                                            }
                                                            
                                                            void halve_in_place(std::vector<double>& v) {
                                                                std::transform(v.begin(),v.end(),v.begin(),
                                                                               std::bind2nd(std::divides<double>(),2.0));
                                                            }
                                                            

                                                            To wrap with SWIG, you might write the following:

                                                            %module example
                                                            %{
                                                            #include "example.h"
                                                            %}
                                                            
                                                            %include "std_vector.i"
                                                            // Instantiate templates used by example
                                                            namespace std {
                                                               %template(IntVector) vector<int>;
                                                               %template(DoubleVector) vector<double>;
                                                            }
                                                            
                                                            // Include the header file with above prototypes
                                                            %include "example.h"
                                                            

                                                            Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                                            >>> from example import *
                                                            >>> iv = IntVector(4)         # Create an vector<int>
                                                            >>> for i in range(0,4):
                                                            ...      iv[i] = i
                                                            >>> average(iv)               # Call method
                                                            1.5
                                                            >>> average([0,1,2,3])        # Call with list
                                                            1.5
                                                            >>> half([1,2,3])             # Half a list
                                                            (0.5,1.0,1.5)
                                                            >>> halve_in_place([1,2,3])   # Oops
                                                            Traceback (most recent call last):
                                                              File "<stdin>", line 1, in ?
                                                            TypeError: Type error. Expected _p_std__vectorTdouble_t
                                                            >>> dv = DoubleVector(4)
                                                            >>> for i in range(0,4):
                                                            ...       dv[i] = i
                                                            >>> halve_in_place(dv)       # Ok
                                                            >>> for i in dv:
                                                            ...       print i
                                                            ...
                                                            0.0
                                                            0.5
                                                            1.0
                                                            1.5
                                                            >>> dv[20] = 4.5
                                                            Traceback (most recent call last):
                                                              File "<stdin>", line 1, in ?
                                                              File "example.py", line 81, in __setitem__
                                                                def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                                            IndexError: vector index out of range
                                                            >>>
                                                            

                                                            This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                                            %include "std_vector.i"
                                                            
                                                            namespace std {
                                                                %template(IntVector) vector<int>;
                                                            }
                                                            
                                                            using namespace std;
                                                            typedef std::vector Vector;
                                                            
                                                            void foo(vector<int> *x, const Vector &x);
                                                            

                                                            Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                                            Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                                            Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                                            8.5 Utility Libraries

                                                            8.5.1 exception.i

                                                            The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                                            SWIG_exception(int code, const char *message)

                                                            Raises an exception in the target language. code is one of the following symbolic constants:

                                                            SWIG_MemoryError
                                                            SWIG_IOError
                                                            SWIG_RuntimeError
                                                            SWIG_IndexError
                                                            SWIG_TypeError
                                                            SWIG_DivisionByZero
                                                            SWIG_OverflowError
                                                            SWIG_SyntaxError
                                                            SWIG_ValueError
                                                            SWIG_SystemError
                                                            

                                                            message is a string indicating more information about the problem.

                                                            The primary use of this module is in writing language-independent exception handlers. For example:

                                                            %include "exception.i"
                                                            %exception std::vector::getitem {
                                                                try {
                                                                    $action
                                                                } catch (std::out_of_range& e) {
                                                                    SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                                }
                                                            }
                                                            

                                                            ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                                            

                                                            SWIG-1.3 Documentation

                                                            
                                                            

                                                            ---

                                                            Table of Contents

                                                            
                                                            
                                                            SWIG-1.3 Development Documentation
                                                            • Sections
                                                            • SWIG Core Documentation
                                                            • Language Module Documentation
                                                            • Developer Documentation
                                                            • Documentation that has not yet been updated
                                                            1 Preface
                                                            • 1.1 Introduction
                                                            • 1.2 Special Introduction for Version 1.3
                                                            • 1.3 SWIG Versions
                                                            • 1.4 SWIG resources
                                                            • 1.5 Prerequisites
                                                            • 1.6 Organization of this manual
                                                            • 1.7 How to avoid reading the manual
                                                            • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                                              >>> make_upper("hello world")
                                                              'HELLO WORLD'
                                                              >>> attach_header("Hello world")
                                                              'header: Hello world'
                                                              >>>
                                                              

                                                              This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                                              %cstring_output_maxsize(parm, maxparm)

                                                              This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                                              %cstring_output_maxsize(char *path, int maxpath);
                                                              ...
                                                              void get_path(char *path, int maxpath);
                                                              

                                                              In the target language:

                                                              >>> get_path(1024)
                                                              '/home/beazley/Packages/Foo/Bar'
                                                              >>>
                                                              

                                                              This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                                              %cstring_output_withsize(parm, maxparm)

                                                              This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                                              %cstring_output_withsize(char *data, int *maxdata);
                                                              ...
                                                              void get_data(char *data, int *maxdata);
                                                              

                                                              In the target language:

                                                              >>> get_data(1024)
                                                              'x627388912'
                                                              >>> get_data(1024)
                                                              'xyzzy'
                                                              >>>
                                                              

                                                              This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                                              %cstring_output_allocate(parm, release)

                                                              This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                                              void foo(char **s) {
                                                                  *s = (char *) malloc(64);
                                                                  sprintf(*s, "Hello world\n");
                                                              }
                                                              

                                                              The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                              %cstring_output_allocate(char **s, free(*$1));
                                                              ...
                                                              void foo(char **s);
                                                              

                                                              In the target language:

                                                              >>> foo()
                                                              'Hello world\n'
                                                              >>>
                                                              

                                                              %cstring_output_allocate_size(parm, szparm, release)

                                                              This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                                              void foo(char **s, int *sz) {
                                                                  *s = (char *) malloc(64);
                                                                  *sz = 64;
                                                                  // Write some binary data
                                                                  ...
                                                              }
                                                              

                                                              The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                              %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                                              ...
                                                              void foo(char **s, int *slen);
                                                              

                                                              In the target language:

                                                              >>> foo()
                                                              '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                                              >>>
                                                              

                                                              This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                                              char  *get_data(int *len);
                                                              

                                                              You could wrap it with a function like this:

                                                              void my_get_data(char **result, int *len) {
                                                                 *result = get_data(len);
                                                              }
                                                              

                                                              Comments:
                                                              • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                                              • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                                              • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                                              • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                                              8.4 C++ Library

                                                              The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                                              8.4.1 std_string.i

                                                              The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                                              %module example
                                                              %include "std_string.i"
                                                              
                                                              std::string foo();
                                                              void        bar(const std::string &x);
                                                              

                                                              In the target language:

                                                              x = foo();                # Returns a string object
                                                              bar("Hello World");       # Pass string as std::string
                                                              

                                                              This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                                              This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                                              %module example
                                                              %include "std_string.i"
                                                              
                                                              using namespace std;
                                                              typedef std::string String;
                                                              ...
                                                              void foo(string s, const String &t);     // std_string typemaps still applied
                                                              

                                                              Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                                              8.4.2 std_vector.i

                                                              The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                                              %module example
                                                              %include "std_vector.i"
                                                              
                                                              namespace std {
                                                                 %template(vectori) vector<int>;
                                                                 %template(vectord) vector<double>;
                                                              };
                                                              

                                                              When a template vector<X> is instantiated a number of things happen:
                                                              • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                                              • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                                              • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                                              • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                                              • An exception handler for std::out_of_range is defined.
                                                              • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                                              To illustrate the use of this library, consider the following functions:

                                                              /* File : example.h */
                                                              
                                                              #include <vector>
                                                              #include <algorithm>
                                                              #include <functional>
                                                              #include <numeric>
                                                              
                                                              double average(std::vector<int> v) {
                                                                  return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                                              }
                                                              
                                                              std::vector<double> half(const std::vector<double>& v) {
                                                                  std::vector<double> w(v);
                                                                  for (unsigned int i=0; i<w.size(); i++)
                                                                      w[i] /= 2.0;
                                                                  return w;
                                                              }
                                                              
                                                              void halve_in_place(std::vector<double>& v) {
                                                                  std::transform(v.begin(),v.end(),v.begin(),
                                                                                 std::bind2nd(std::divides<double>(),2.0));
                                                              }
                                                              

                                                              To wrap with SWIG, you might write the following:

                                                              %module example
                                                              %{
                                                              #include "example.h"
                                                              %}
                                                              
                                                              %include "std_vector.i"
                                                              // Instantiate templates used by example
                                                              namespace std {
                                                                 %template(IntVector) vector<int>;
                                                                 %template(DoubleVector) vector<double>;
                                                              }
                                                              
                                                              // Include the header file with above prototypes
                                                              %include "example.h"
                                                              

                                                              Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                                              >>> from example import *
                                                              >>> iv = IntVector(4)         # Create an vector<int>
                                                              >>> for i in range(0,4):
                                                              ...      iv[i] = i
                                                              >>> average(iv)               # Call method
                                                              1.5
                                                              >>> average([0,1,2,3])        # Call with list
                                                              1.5
                                                              >>> half([1,2,3])             # Half a list
                                                              (0.5,1.0,1.5)
                                                              >>> halve_in_place([1,2,3])   # Oops
                                                              Traceback (most recent call last):
                                                                File "<stdin>", line 1, in ?
                                                              TypeError: Type error. Expected _p_std__vectorTdouble_t
                                                              >>> dv = DoubleVector(4)
                                                              >>> for i in range(0,4):
                                                              ...       dv[i] = i
                                                              >>> halve_in_place(dv)       # Ok
                                                              >>> for i in dv:
                                                              ...       print i
                                                              ...
                                                              0.0
                                                              0.5
                                                              1.0
                                                              1.5
                                                              >>> dv[20] = 4.5
                                                              Traceback (most recent call last):
                                                                File "<stdin>", line 1, in ?
                                                                File "example.py", line 81, in __setitem__
                                                                  def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                                              IndexError: vector index out of range
                                                              >>>
                                                              

                                                              This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                                              %include "std_vector.i"
                                                              
                                                              namespace std {
                                                                  %template(IntVector) vector<int>;
                                                              }
                                                              
                                                              using namespace std;
                                                              typedef std::vector Vector;
                                                              
                                                              void foo(vector<int> *x, const Vector &x);
                                                              

                                                              Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                                              Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                                              Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                                              8.5 Utility Libraries

                                                              8.5.1 exception.i

                                                              The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                                              SWIG_exception(int code, const char *message)

                                                              Raises an exception in the target language. code is one of the following symbolic constants:

                                                              SWIG_MemoryError
                                                              SWIG_IOError
                                                              SWIG_RuntimeError
                                                              SWIG_IndexError
                                                              SWIG_TypeError
                                                              SWIG_DivisionByZero
                                                              SWIG_OverflowError
                                                              SWIG_SyntaxError
                                                              SWIG_ValueError
                                                              SWIG_SystemError
                                                              

                                                              message is a string indicating more information about the problem.

                                                              The primary use of this module is in writing language-independent exception handlers. For example:

                                                              %include "exception.i"
                                                              %exception std::vector::getitem {
                                                                  try {
                                                                      $action
                                                                  } catch (std::out_of_range& e) {
                                                                      SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                                  }
                                                              }
                                                              

                                                              ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                                              

                                                              SWIG-1.3 Documentation

                                                              
                                                              

                                                              ---

                                                              Table of Contents

                                                              
                                                              
                                                              SWIG-1.3 Development Documentation
                                                              • Sections
                                                              • SWIG Core Documentation
                                                              • Language Module Documentation
                                                              • Developer Documentation
                                                              • Documentation that has not yet been updated
                                                              1 Preface
                                                              • 1.1 Introduction
                                                              • 1.2 Special Introduction for Version 1.3
                                                              • 1.3 SWIG Versions
                                                              • 1.4 SWIG resources
                                                              • 1.5 Prerequisites
                                                              • 1.6 Organization of this manual
                                                              • 1.7 How to avoid reading the manual
                                                              • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                                                >>> make_upper("hello world")
                                                                'HELLO WORLD'
                                                                >>> attach_header("Hello world")
                                                                'header: Hello world'
                                                                >>>
                                                                

                                                                This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                                                %cstring_output_maxsize(parm, maxparm)

                                                                This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                                                %cstring_output_maxsize(char *path, int maxpath);
                                                                ...
                                                                void get_path(char *path, int maxpath);
                                                                

                                                                In the target language:

                                                                >>> get_path(1024)
                                                                '/home/beazley/Packages/Foo/Bar'
                                                                >>>
                                                                

                                                                This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                                                %cstring_output_withsize(parm, maxparm)

                                                                This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                                                %cstring_output_withsize(char *data, int *maxdata);
                                                                ...
                                                                void get_data(char *data, int *maxdata);
                                                                

                                                                In the target language:

                                                                >>> get_data(1024)
                                                                'x627388912'
                                                                >>> get_data(1024)
                                                                'xyzzy'
                                                                >>>
                                                                

                                                                This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                                                %cstring_output_allocate(parm, release)

                                                                This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                                                void foo(char **s) {
                                                                    *s = (char *) malloc(64);
                                                                    sprintf(*s, "Hello world\n");
                                                                }
                                                                

                                                                The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                %cstring_output_allocate(char **s, free(*$1));
                                                                ...
                                                                void foo(char **s);
                                                                

                                                                In the target language:

                                                                >>> foo()
                                                                'Hello world\n'
                                                                >>>
                                                                

                                                                %cstring_output_allocate_size(parm, szparm, release)

                                                                This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                                                void foo(char **s, int *sz) {
                                                                    *s = (char *) malloc(64);
                                                                    *sz = 64;
                                                                    // Write some binary data
                                                                    ...
                                                                }
                                                                

                                                                The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                                                ...
                                                                void foo(char **s, int *slen);
                                                                

                                                                In the target language:

                                                                >>> foo()
                                                                '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                                                >>>
                                                                

                                                                This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                                                char  *get_data(int *len);
                                                                

                                                                You could wrap it with a function like this:

                                                                void my_get_data(char **result, int *len) {
                                                                   *result = get_data(len);
                                                                }
                                                                

                                                                Comments:
                                                                • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                                                • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                                                • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                                                • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                                                8.4 C++ Library

                                                                The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                                                8.4.1 std_string.i

                                                                The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                                                %module example
                                                                %include "std_string.i"
                                                                
                                                                std::string foo();
                                                                void        bar(const std::string &x);
                                                                

                                                                In the target language:

                                                                x = foo();                # Returns a string object
                                                                bar("Hello World");       # Pass string as std::string
                                                                

                                                                This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                                                This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                                                %module example
                                                                %include "std_string.i"
                                                                
                                                                using namespace std;
                                                                typedef std::string String;
                                                                ...
                                                                void foo(string s, const String &t);     // std_string typemaps still applied
                                                                

                                                                Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                                                8.4.2 std_vector.i

                                                                The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                                                %module example
                                                                %include "std_vector.i"
                                                                
                                                                namespace std {
                                                                   %template(vectori) vector<int>;
                                                                   %template(vectord) vector<double>;
                                                                };
                                                                

                                                                When a template vector<X> is instantiated a number of things happen:
                                                                • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                                                • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                                                • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                                                • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                                                • An exception handler for std::out_of_range is defined.
                                                                • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                                                To illustrate the use of this library, consider the following functions:

                                                                /* File : example.h */
                                                                
                                                                #include <vector>
                                                                #include <algorithm>
                                                                #include <functional>
                                                                #include <numeric>
                                                                
                                                                double average(std::vector<int> v) {
                                                                    return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                                                }
                                                                
                                                                std::vector<double> half(const std::vector<double>& v) {
                                                                    std::vector<double> w(v);
                                                                    for (unsigned int i=0; i<w.size(); i++)
                                                                        w[i] /= 2.0;
                                                                    return w;
                                                                }
                                                                
                                                                void halve_in_place(std::vector<double>& v) {
                                                                    std::transform(v.begin(),v.end(),v.begin(),
                                                                                   std::bind2nd(std::divides<double>(),2.0));
                                                                }
                                                                

                                                                To wrap with SWIG, you might write the following:

                                                                %module example
                                                                %{
                                                                #include "example.h"
                                                                %}
                                                                
                                                                %include "std_vector.i"
                                                                // Instantiate templates used by example
                                                                namespace std {
                                                                   %template(IntVector) vector<int>;
                                                                   %template(DoubleVector) vector<double>;
                                                                }
                                                                
                                                                // Include the header file with above prototypes
                                                                %include "example.h"
                                                                

                                                                Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                                                >>> from example import *
                                                                >>> iv = IntVector(4)         # Create an vector<int>
                                                                >>> for i in range(0,4):
                                                                ...      iv[i] = i
                                                                >>> average(iv)               # Call method
                                                                1.5
                                                                >>> average([0,1,2,3])        # Call with list
                                                                1.5
                                                                >>> half([1,2,3])             # Half a list
                                                                (0.5,1.0,1.5)
                                                                >>> halve_in_place([1,2,3])   # Oops
                                                                Traceback (most recent call last):
                                                                  File "<stdin>", line 1, in ?
                                                                TypeError: Type error. Expected _p_std__vectorTdouble_t
                                                                >>> dv = DoubleVector(4)
                                                                >>> for i in range(0,4):
                                                                ...       dv[i] = i
                                                                >>> halve_in_place(dv)       # Ok
                                                                >>> for i in dv:
                                                                ...       print i
                                                                ...
                                                                0.0
                                                                0.5
                                                                1.0
                                                                1.5
                                                                >>> dv[20] = 4.5
                                                                Traceback (most recent call last):
                                                                  File "<stdin>", line 1, in ?
                                                                  File "example.py", line 81, in __setitem__
                                                                    def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                                                IndexError: vector index out of range
                                                                >>>
                                                                

                                                                This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                                                %include "std_vector.i"
                                                                
                                                                namespace std {
                                                                    %template(IntVector) vector<int>;
                                                                }
                                                                
                                                                using namespace std;
                                                                typedef std::vector Vector;
                                                                
                                                                void foo(vector<int> *x, const Vector &x);
                                                                

                                                                Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                                                Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                                                Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                                                8.5 Utility Libraries

                                                                8.5.1 exception.i

                                                                The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                                                SWIG_exception(int code, const char *message)

                                                                Raises an exception in the target language. code is one of the following symbolic constants:

                                                                SWIG_MemoryError
                                                                SWIG_IOError
                                                                SWIG_RuntimeError
                                                                SWIG_IndexError
                                                                SWIG_TypeError
                                                                SWIG_DivisionByZero
                                                                SWIG_OverflowError
                                                                SWIG_SyntaxError
                                                                SWIG_ValueError
                                                                SWIG_SystemError
                                                                

                                                                message is a string indicating more information about the problem.

                                                                The primary use of this module is in writing language-independent exception handlers. For example:

                                                                %include "exception.i"
                                                                %exception std::vector::getitem {
                                                                    try {
                                                                        $action
                                                                    } catch (std::out_of_range& e) {
                                                                        SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                                    }
                                                                }
                                                                

                                                                ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                                                

                                                                SWIG-1.3 Documentation

                                                                
                                                                

                                                                ---

                                                                Table of Contents

                                                                
                                                                
                                                                SWIG-1.3 Development Documentation
                                                                • Sections
                                                                • SWIG Core Documentation
                                                                • Language Module Documentation
                                                                • Developer Documentation
                                                                • Documentation that has not yet been updated
                                                                1 Preface
                                                                • 1.1 Introduction
                                                                • 1.2 Special Introduction for Version 1.3
                                                                • 1.3 SWIG Versions
                                                                • 1.4 SWIG resources
                                                                • 1.5 Prerequisites
                                                                • 1.6 Organization of this manual
                                                                • 1.7 How to avoid reading the manual
                                                                • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                                                  >>> make_upper("hello world")
                                                                  'HELLO WORLD'
                                                                  >>> attach_header("Hello world")
                                                                  'header: Hello world'
                                                                  >>>
                                                                  

                                                                  This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                                                  %cstring_output_maxsize(parm, maxparm)

                                                                  This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                                                  %cstring_output_maxsize(char *path, int maxpath);
                                                                  ...
                                                                  void get_path(char *path, int maxpath);
                                                                  

                                                                  In the target language:

                                                                  >>> get_path(1024)
                                                                  '/home/beazley/Packages/Foo/Bar'
                                                                  >>>
                                                                  

                                                                  This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                                                  %cstring_output_withsize(parm, maxparm)

                                                                  This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                                                  %cstring_output_withsize(char *data, int *maxdata);
                                                                  ...
                                                                  void get_data(char *data, int *maxdata);
                                                                  

                                                                  In the target language:

                                                                  >>> get_data(1024)
                                                                  'x627388912'
                                                                  >>> get_data(1024)
                                                                  'xyzzy'
                                                                  >>>
                                                                  

                                                                  This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                                                  %cstring_output_allocate(parm, release)

                                                                  This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                                                  void foo(char **s) {
                                                                      *s = (char *) malloc(64);
                                                                      sprintf(*s, "Hello world\n");
                                                                  }
                                                                  

                                                                  The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                  %cstring_output_allocate(char **s, free(*$1));
                                                                  ...
                                                                  void foo(char **s);
                                                                  

                                                                  In the target language:

                                                                  >>> foo()
                                                                  'Hello world\n'
                                                                  >>>
                                                                  

                                                                  %cstring_output_allocate_size(parm, szparm, release)

                                                                  This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                                                  void foo(char **s, int *sz) {
                                                                      *s = (char *) malloc(64);
                                                                      *sz = 64;
                                                                      // Write some binary data
                                                                      ...
                                                                  }
                                                                  

                                                                  The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                  %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                                                  ...
                                                                  void foo(char **s, int *slen);
                                                                  

                                                                  In the target language:

                                                                  >>> foo()
                                                                  '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                                                  >>>
                                                                  

                                                                  This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                                                  char  *get_data(int *len);
                                                                  

                                                                  You could wrap it with a function like this:

                                                                  void my_get_data(char **result, int *len) {
                                                                     *result = get_data(len);
                                                                  }
                                                                  

                                                                  Comments:
                                                                  • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                                                  • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                                                  • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                                                  • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                                                  8.4 C++ Library

                                                                  The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                                                  8.4.1 std_string.i

                                                                  The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                                                  %module example
                                                                  %include "std_string.i"
                                                                  
                                                                  std::string foo();
                                                                  void        bar(const std::string &x);
                                                                  

                                                                  In the target language:

                                                                  x = foo();                # Returns a string object
                                                                  bar("Hello World");       # Pass string as std::string
                                                                  

                                                                  This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                                                  This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                                                  %module example
                                                                  %include "std_string.i"
                                                                  
                                                                  using namespace std;
                                                                  typedef std::string String;
                                                                  ...
                                                                  void foo(string s, const String &t);     // std_string typemaps still applied
                                                                  

                                                                  Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                                                  8.4.2 std_vector.i

                                                                  The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                                                  %module example
                                                                  %include "std_vector.i"
                                                                  
                                                                  namespace std {
                                                                     %template(vectori) vector<int>;
                                                                     %template(vectord) vector<double>;
                                                                  };
                                                                  

                                                                  When a template vector<X> is instantiated a number of things happen:
                                                                  • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                                                  • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                                                  • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                                                  • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                                                  • An exception handler for std::out_of_range is defined.
                                                                  • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                                                  To illustrate the use of this library, consider the following functions:

                                                                  /* File : example.h */
                                                                  
                                                                  #include <vector>
                                                                  #include <algorithm>
                                                                  #include <functional>
                                                                  #include <numeric>
                                                                  
                                                                  double average(std::vector<int> v) {
                                                                      return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                                                  }
                                                                  
                                                                  std::vector<double> half(const std::vector<double>& v) {
                                                                      std::vector<double> w(v);
                                                                      for (unsigned int i=0; i<w.size(); i++)
                                                                          w[i] /= 2.0;
                                                                      return w;
                                                                  }
                                                                  
                                                                  void halve_in_place(std::vector<double>& v) {
                                                                      std::transform(v.begin(),v.end(),v.begin(),
                                                                                     std::bind2nd(std::divides<double>(),2.0));
                                                                  }
                                                                  

                                                                  To wrap with SWIG, you might write the following:

                                                                  %module example
                                                                  %{
                                                                  #include "example.h"
                                                                  %}
                                                                  
                                                                  %include "std_vector.i"
                                                                  // Instantiate templates used by example
                                                                  namespace std {
                                                                     %template(IntVector) vector<int>;
                                                                     %template(DoubleVector) vector<double>;
                                                                  }
                                                                  
                                                                  // Include the header file with above prototypes
                                                                  %include "example.h"
                                                                  

                                                                  Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                                                  >>> from example import *
                                                                  >>> iv = IntVector(4)         # Create an vector<int>
                                                                  >>> for i in range(0,4):
                                                                  ...      iv[i] = i
                                                                  >>> average(iv)               # Call method
                                                                  1.5
                                                                  >>> average([0,1,2,3])        # Call with list
                                                                  1.5
                                                                  >>> half([1,2,3])             # Half a list
                                                                  (0.5,1.0,1.5)
                                                                  >>> halve_in_place([1,2,3])   # Oops
                                                                  Traceback (most recent call last):
                                                                    File "<stdin>", line 1, in ?
                                                                  TypeError: Type error. Expected _p_std__vectorTdouble_t
                                                                  >>> dv = DoubleVector(4)
                                                                  >>> for i in range(0,4):
                                                                  ...       dv[i] = i
                                                                  >>> halve_in_place(dv)       # Ok
                                                                  >>> for i in dv:
                                                                  ...       print i
                                                                  ...
                                                                  0.0
                                                                  0.5
                                                                  1.0
                                                                  1.5
                                                                  >>> dv[20] = 4.5
                                                                  Traceback (most recent call last):
                                                                    File "<stdin>", line 1, in ?
                                                                    File "example.py", line 81, in __setitem__
                                                                      def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                                                  IndexError: vector index out of range
                                                                  >>>
                                                                  

                                                                  This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                                                  %include "std_vector.i"
                                                                  
                                                                  namespace std {
                                                                      %template(IntVector) vector<int>;
                                                                  }
                                                                  
                                                                  using namespace std;
                                                                  typedef std::vector Vector;
                                                                  
                                                                  void foo(vector<int> *x, const Vector &x);
                                                                  

                                                                  Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                                                  Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                                                  Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                                                  8.5 Utility Libraries

                                                                  8.5.1 exception.i

                                                                  The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                                                  SWIG_exception(int code, const char *message)

                                                                  Raises an exception in the target language. code is one of the following symbolic constants:

                                                                  SWIG_MemoryError
                                                                  SWIG_IOError
                                                                  SWIG_RuntimeError
                                                                  SWIG_IndexError
                                                                  SWIG_TypeError
                                                                  SWIG_DivisionByZero
                                                                  SWIG_OverflowError
                                                                  SWIG_SyntaxError
                                                                  SWIG_ValueError
                                                                  SWIG_SystemError
                                                                  

                                                                  message is a string indicating more information about the problem.

                                                                  The primary use of this module is in writing language-independent exception handlers. For example:

                                                                  %include "exception.i"
                                                                  %exception std::vector::getitem {
                                                                      try {
                                                                          $action
                                                                      } catch (std::out_of_range& e) {
                                                                          SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                                      }
                                                                  }
                                                                  

                                                                  ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                                                  

                                                                  SWIG-1.3 Documentation

                                                                  
                                                                  

                                                                  ---

                                                                  Table of Contents

                                                                  
                                                                  
                                                                  SWIG-1.3 Development Documentation
                                                                  • Sections
                                                                  • SWIG Core Documentation
                                                                  • Language Module Documentation
                                                                  • Developer Documentation
                                                                  • Documentation that has not yet been updated
                                                                  1 Preface
                                                                  • 1.1 Introduction
                                                                  • 1.2 Special Introduction for Version 1.3
                                                                  • 1.3 SWIG Versions
                                                                  • 1.4 SWIG resources
                                                                  • 1.5 Prerequisites
                                                                  • 1.6 Organization of this manual
                                                                  • 1.7 How to avoid reading the manual
                                                                  • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                                                    >>> make_upper("hello world")
                                                                    'HELLO WORLD'
                                                                    >>> attach_header("Hello world")
                                                                    'header: Hello world'
                                                                    >>>
                                                                    

                                                                    This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                                                    %cstring_output_maxsize(parm, maxparm)

                                                                    This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                                                    %cstring_output_maxsize(char *path, int maxpath);
                                                                    ...
                                                                    void get_path(char *path, int maxpath);
                                                                    

                                                                    In the target language:

                                                                    >>> get_path(1024)
                                                                    '/home/beazley/Packages/Foo/Bar'
                                                                    >>>
                                                                    

                                                                    This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                                                    %cstring_output_withsize(parm, maxparm)

                                                                    This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                                                    %cstring_output_withsize(char *data, int *maxdata);
                                                                    ...
                                                                    void get_data(char *data, int *maxdata);
                                                                    

                                                                    In the target language:

                                                                    >>> get_data(1024)
                                                                    'x627388912'
                                                                    >>> get_data(1024)
                                                                    'xyzzy'
                                                                    >>>
                                                                    

                                                                    This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                                                    %cstring_output_allocate(parm, release)

                                                                    This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                                                    void foo(char **s) {
                                                                        *s = (char *) malloc(64);
                                                                        sprintf(*s, "Hello world\n");
                                                                    }
                                                                    

                                                                    The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                    %cstring_output_allocate(char **s, free(*$1));
                                                                    ...
                                                                    void foo(char **s);
                                                                    

                                                                    In the target language:

                                                                    >>> foo()
                                                                    'Hello world\n'
                                                                    >>>
                                                                    

                                                                    %cstring_output_allocate_size(parm, szparm, release)

                                                                    This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                                                    void foo(char **s, int *sz) {
                                                                        *s = (char *) malloc(64);
                                                                        *sz = 64;
                                                                        // Write some binary data
                                                                        ...
                                                                    }
                                                                    

                                                                    The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                    %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                                                    ...
                                                                    void foo(char **s, int *slen);
                                                                    

                                                                    In the target language:

                                                                    >>> foo()
                                                                    '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                                                    >>>
                                                                    

                                                                    This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                                                    char  *get_data(int *len);
                                                                    

                                                                    You could wrap it with a function like this:

                                                                    void my_get_data(char **result, int *len) {
                                                                       *result = get_data(len);
                                                                    }
                                                                    

                                                                    Comments:
                                                                    • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                                                    • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                                                    • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                                                    • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                                                    8.4 C++ Library

                                                                    The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                                                    8.4.1 std_string.i

                                                                    The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                                                    %module example
                                                                    %include "std_string.i"
                                                                    
                                                                    std::string foo();
                                                                    void        bar(const std::string &x);
                                                                    

                                                                    In the target language:

                                                                    x = foo();                # Returns a string object
                                                                    bar("Hello World");       # Pass string as std::string
                                                                    

                                                                    This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                                                    This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                                                    %module example
                                                                    %include "std_string.i"
                                                                    
                                                                    using namespace std;
                                                                    typedef std::string String;
                                                                    ...
                                                                    void foo(string s, const String &t);     // std_string typemaps still applied
                                                                    

                                                                    Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                                                    8.4.2 std_vector.i

                                                                    The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                                                    %module example
                                                                    %include "std_vector.i"
                                                                    
                                                                    namespace std {
                                                                       %template(vectori) vector<int>;
                                                                       %template(vectord) vector<double>;
                                                                    };
                                                                    

                                                                    When a template vector<X> is instantiated a number of things happen:
                                                                    • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                                                    • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                                                    • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                                                    • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                                                    • An exception handler for std::out_of_range is defined.
                                                                    • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                                                    To illustrate the use of this library, consider the following functions:

                                                                    /* File : example.h */
                                                                    
                                                                    #include <vector>
                                                                    #include <algorithm>
                                                                    #include <functional>
                                                                    #include <numeric>
                                                                    
                                                                    double average(std::vector<int> v) {
                                                                        return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                                                    }
                                                                    
                                                                    std::vector<double> half(const std::vector<double>& v) {
                                                                        std::vector<double> w(v);
                                                                        for (unsigned int i=0; i<w.size(); i++)
                                                                            w[i] /= 2.0;
                                                                        return w;
                                                                    }
                                                                    
                                                                    void halve_in_place(std::vector<double>& v) {
                                                                        std::transform(v.begin(),v.end(),v.begin(),
                                                                                       std::bind2nd(std::divides<double>(),2.0));
                                                                    }
                                                                    

                                                                    To wrap with SWIG, you might write the following:

                                                                    %module example
                                                                    %{
                                                                    #include "example.h"
                                                                    %}
                                                                    
                                                                    %include "std_vector.i"
                                                                    // Instantiate templates used by example
                                                                    namespace std {
                                                                       %template(IntVector) vector<int>;
                                                                       %template(DoubleVector) vector<double>;
                                                                    }
                                                                    
                                                                    // Include the header file with above prototypes
                                                                    %include "example.h"
                                                                    

                                                                    Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                                                    >>> from example import *
                                                                    >>> iv = IntVector(4)         # Create an vector<int>
                                                                    >>> for i in range(0,4):
                                                                    ...      iv[i] = i
                                                                    >>> average(iv)               # Call method
                                                                    1.5
                                                                    >>> average([0,1,2,3])        # Call with list
                                                                    1.5
                                                                    >>> half([1,2,3])             # Half a list
                                                                    (0.5,1.0,1.5)
                                                                    >>> halve_in_place([1,2,3])   # Oops
                                                                    Traceback (most recent call last):
                                                                      File "<stdin>", line 1, in ?
                                                                    TypeError: Type error. Expected _p_std__vectorTdouble_t
                                                                    >>> dv = DoubleVector(4)
                                                                    >>> for i in range(0,4):
                                                                    ...       dv[i] = i
                                                                    >>> halve_in_place(dv)       # Ok
                                                                    >>> for i in dv:
                                                                    ...       print i
                                                                    ...
                                                                    0.0
                                                                    0.5
                                                                    1.0
                                                                    1.5
                                                                    >>> dv[20] = 4.5
                                                                    Traceback (most recent call last):
                                                                      File "<stdin>", line 1, in ?
                                                                      File "example.py", line 81, in __setitem__
                                                                        def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                                                    IndexError: vector index out of range
                                                                    >>>
                                                                    

                                                                    This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                                                    %include "std_vector.i"
                                                                    
                                                                    namespace std {
                                                                        %template(IntVector) vector<int>;
                                                                    }
                                                                    
                                                                    using namespace std;
                                                                    typedef std::vector Vector;
                                                                    
                                                                    void foo(vector<int> *x, const Vector &x);
                                                                    

                                                                    Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                                                    Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                                                    Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                                                    8.5 Utility Libraries

                                                                    8.5.1 exception.i

                                                                    The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                                                    SWIG_exception(int code, const char *message)

                                                                    Raises an exception in the target language. code is one of the following symbolic constants:

                                                                    SWIG_MemoryError
                                                                    SWIG_IOError
                                                                    SWIG_RuntimeError
                                                                    SWIG_IndexError
                                                                    SWIG_TypeError
                                                                    SWIG_DivisionByZero
                                                                    SWIG_OverflowError
                                                                    SWIG_SyntaxError
                                                                    SWIG_ValueError
                                                                    SWIG_SystemError
                                                                    

                                                                    message is a string indicating more information about the problem.

                                                                    The primary use of this module is in writing language-independent exception handlers. For example:

                                                                    %include "exception.i"
                                                                    %exception std::vector::getitem {
                                                                        try {
                                                                            $action
                                                                        } catch (std::out_of_range& e) {
                                                                            SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                                        }
                                                                    }
                                                                    

                                                                    ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                                                    

                                                                    SWIG-1.3 Documentation

                                                                    
                                                                    

                                                                    ---

                                                                    Table of Contents

                                                                    
                                                                    
                                                                    SWIG-1.3 Development Documentation
                                                                    • Sections
                                                                    • SWIG Core Documentation
                                                                    • Language Module Documentation
                                                                    • Developer Documentation
                                                                    • Documentation that has not yet been updated
                                                                    1 Preface
                                                                    • 1.1 Introduction
                                                                    • 1.2 Special Introduction for Version 1.3
                                                                    • 1.3 SWIG Versions
                                                                    • 1.4 SWIG resources
                                                                    • 1.5 Prerequisites
                                                                    • 1.6 Organization of this manual
                                                                    • 1.7 How to avoid reading the manual
                                                                    • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                                                      >>> make_upper("hello world")
                                                                      'HELLO WORLD'
                                                                      >>> attach_header("Hello world")
                                                                      'header: Hello world'
                                                                      >>>
                                                                      

                                                                      This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                                                      %cstring_output_maxsize(parm, maxparm)

                                                                      This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                                                      %cstring_output_maxsize(char *path, int maxpath);
                                                                      ...
                                                                      void get_path(char *path, int maxpath);
                                                                      

                                                                      In the target language:

                                                                      >>> get_path(1024)
                                                                      '/home/beazley/Packages/Foo/Bar'
                                                                      >>>
                                                                      

                                                                      This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                                                      %cstring_output_withsize(parm, maxparm)

                                                                      This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                                                      %cstring_output_withsize(char *data, int *maxdata);
                                                                      ...
                                                                      void get_data(char *data, int *maxdata);
                                                                      

                                                                      In the target language:

                                                                      >>> get_data(1024)
                                                                      'x627388912'
                                                                      >>> get_data(1024)
                                                                      'xyzzy'
                                                                      >>>
                                                                      

                                                                      This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                                                      %cstring_output_allocate(parm, release)

                                                                      This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                                                      void foo(char **s) {
                                                                          *s = (char *) malloc(64);
                                                                          sprintf(*s, "Hello world\n");
                                                                      }
                                                                      

                                                                      The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                      %cstring_output_allocate(char **s, free(*$1));
                                                                      ...
                                                                      void foo(char **s);
                                                                      

                                                                      In the target language:

                                                                      >>> foo()
                                                                      'Hello world\n'
                                                                      >>>
                                                                      

                                                                      %cstring_output_allocate_size(parm, szparm, release)

                                                                      This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                                                      void foo(char **s, int *sz) {
                                                                          *s = (char *) malloc(64);
                                                                          *sz = 64;
                                                                          // Write some binary data
                                                                          ...
                                                                      }
                                                                      

                                                                      The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                      %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                                                      ...
                                                                      void foo(char **s, int *slen);
                                                                      

                                                                      In the target language:

                                                                      >>> foo()
                                                                      '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                                                      >>>
                                                                      

                                                                      This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                                                      char  *get_data(int *len);
                                                                      

                                                                      You could wrap it with a function like this:

                                                                      void my_get_data(char **result, int *len) {
                                                                         *result = get_data(len);
                                                                      }
                                                                      

                                                                      Comments:
                                                                      • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                                                      • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                                                      • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                                                      • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                                                      8.4 C++ Library

                                                                      The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                                                      8.4.1 std_string.i

                                                                      The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                                                      %module example
                                                                      %include "std_string.i"
                                                                      
                                                                      std::string foo();
                                                                      void        bar(const std::string &x);
                                                                      

                                                                      In the target language:

                                                                      x = foo();                # Returns a string object
                                                                      bar("Hello World");       # Pass string as std::string
                                                                      

                                                                      This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                                                      This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                                                      %module example
                                                                      %include "std_string.i"
                                                                      
                                                                      using namespace std;
                                                                      typedef std::string String;
                                                                      ...
                                                                      void foo(string s, const String &t);     // std_string typemaps still applied
                                                                      

                                                                      Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                                                      8.4.2 std_vector.i

                                                                      The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                                                      %module example
                                                                      %include "std_vector.i"
                                                                      
                                                                      namespace std {
                                                                         %template(vectori) vector<int>;
                                                                         %template(vectord) vector<double>;
                                                                      };
                                                                      

                                                                      When a template vector<X> is instantiated a number of things happen:
                                                                      • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                                                      • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                                                      • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                                                      • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                                                      • An exception handler for std::out_of_range is defined.
                                                                      • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                                                      To illustrate the use of this library, consider the following functions:

                                                                      /* File : example.h */
                                                                      
                                                                      #include <vector>
                                                                      #include <algorithm>
                                                                      #include <functional>
                                                                      #include <numeric>
                                                                      
                                                                      double average(std::vector<int> v) {
                                                                          return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                                                      }
                                                                      
                                                                      std::vector<double> half(const std::vector<double>& v) {
                                                                          std::vector<double> w(v);
                                                                          for (unsigned int i=0; i<w.size(); i++)
                                                                              w[i] /= 2.0;
                                                                          return w;
                                                                      }
                                                                      
                                                                      void halve_in_place(std::vector<double>& v) {
                                                                          std::transform(v.begin(),v.end(),v.begin(),
                                                                                         std::bind2nd(std::divides<double>(),2.0));
                                                                      }
                                                                      

                                                                      To wrap with SWIG, you might write the following:

                                                                      %module example
                                                                      %{
                                                                      #include "example.h"
                                                                      %}
                                                                      
                                                                      %include "std_vector.i"
                                                                      // Instantiate templates used by example
                                                                      namespace std {
                                                                         %template(IntVector) vector<int>;
                                                                         %template(DoubleVector) vector<double>;
                                                                      }
                                                                      
                                                                      // Include the header file with above prototypes
                                                                      %include "example.h"
                                                                      

                                                                      Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                                                      >>> from example import *
                                                                      >>> iv = IntVector(4)         # Create an vector<int>
                                                                      >>> for i in range(0,4):
                                                                      ...      iv[i] = i
                                                                      >>> average(iv)               # Call method
                                                                      1.5
                                                                      >>> average([0,1,2,3])        # Call with list
                                                                      1.5
                                                                      >>> half([1,2,3])             # Half a list
                                                                      (0.5,1.0,1.5)
                                                                      >>> halve_in_place([1,2,3])   # Oops
                                                                      Traceback (most recent call last):
                                                                        File "<stdin>", line 1, in ?
                                                                      TypeError: Type error. Expected _p_std__vectorTdouble_t
                                                                      >>> dv = DoubleVector(4)
                                                                      >>> for i in range(0,4):
                                                                      ...       dv[i] = i
                                                                      >>> halve_in_place(dv)       # Ok
                                                                      >>> for i in dv:
                                                                      ...       print i
                                                                      ...
                                                                      0.0
                                                                      0.5
                                                                      1.0
                                                                      1.5
                                                                      >>> dv[20] = 4.5
                                                                      Traceback (most recent call last):
                                                                        File "<stdin>", line 1, in ?
                                                                        File "example.py", line 81, in __setitem__
                                                                          def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                                                      IndexError: vector index out of range
                                                                      >>>
                                                                      

                                                                      This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                                                      %include "std_vector.i"
                                                                      
                                                                      namespace std {
                                                                          %template(IntVector) vector<int>;
                                                                      }
                                                                      
                                                                      using namespace std;
                                                                      typedef std::vector Vector;
                                                                      
                                                                      void foo(vector<int> *x, const Vector &x);
                                                                      

                                                                      Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                                                      Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                                                      Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                                                      8.5 Utility Libraries

                                                                      8.5.1 exception.i

                                                                      The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                                                      SWIG_exception(int code, const char *message)

                                                                      Raises an exception in the target language. code is one of the following symbolic constants:

                                                                      SWIG_MemoryError
                                                                      SWIG_IOError
                                                                      SWIG_RuntimeError
                                                                      SWIG_IndexError
                                                                      SWIG_TypeError
                                                                      SWIG_DivisionByZero
                                                                      SWIG_OverflowError
                                                                      SWIG_SyntaxError
                                                                      SWIG_ValueError
                                                                      SWIG_SystemError
                                                                      

                                                                      message is a string indicating more information about the problem.

                                                                      The primary use of this module is in writing language-independent exception handlers. For example:

                                                                      %include "exception.i"
                                                                      %exception std::vector::getitem {
                                                                          try {
                                                                              $action
                                                                          } catch (std::out_of_range& e) {
                                                                              SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                                          }
                                                                      }
                                                                      

                                                                      ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                                                      

                                                                      SWIG-1.3 Documentation

                                                                      
                                                                      

                                                                      ---

                                                                      Table of Contents

                                                                      
                                                                      
                                                                      SWIG-1.3 Development Documentation
                                                                      • Sections
                                                                      • SWIG Core Documentation
                                                                      • Language Module Documentation
                                                                      • Developer Documentation
                                                                      • Documentation that has not yet been updated
                                                                      1 Preface
                                                                      • 1.1 Introduction
                                                                      • 1.2 Special Introduction for Version 1.3
                                                                      • 1.3 SWIG Versions
                                                                      • 1.4 SWIG resources
                                                                      • 1.5 Prerequisites
                                                                      • 1.6 Organization of this manual
                                                                      • 1.7 How to avoid reading the manual
                                                                      • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                                                        >>> make_upper("hello world")
                                                                        'HELLO WORLD'
                                                                        >>> attach_header("Hello world")
                                                                        'header: Hello world'
                                                                        >>>
                                                                        

                                                                        This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                                                        %cstring_output_maxsize(parm, maxparm)

                                                                        This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                                                        %cstring_output_maxsize(char *path, int maxpath);
                                                                        ...
                                                                        void get_path(char *path, int maxpath);
                                                                        

                                                                        In the target language:

                                                                        >>> get_path(1024)
                                                                        '/home/beazley/Packages/Foo/Bar'
                                                                        >>>
                                                                        

                                                                        This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                                                        %cstring_output_withsize(parm, maxparm)

                                                                        This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                                                        %cstring_output_withsize(char *data, int *maxdata);
                                                                        ...
                                                                        void get_data(char *data, int *maxdata);
                                                                        

                                                                        In the target language:

                                                                        >>> get_data(1024)
                                                                        'x627388912'
                                                                        >>> get_data(1024)
                                                                        'xyzzy'
                                                                        >>>
                                                                        

                                                                        This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                                                        %cstring_output_allocate(parm, release)

                                                                        This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                                                        void foo(char **s) {
                                                                            *s = (char *) malloc(64);
                                                                            sprintf(*s, "Hello world\n");
                                                                        }
                                                                        

                                                                        The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                        %cstring_output_allocate(char **s, free(*$1));
                                                                        ...
                                                                        void foo(char **s);
                                                                        

                                                                        In the target language:

                                                                        >>> foo()
                                                                        'Hello world\n'
                                                                        >>>
                                                                        

                                                                        %cstring_output_allocate_size(parm, szparm, release)

                                                                        This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                                                        void foo(char **s, int *sz) {
                                                                            *s = (char *) malloc(64);
                                                                            *sz = 64;
                                                                            // Write some binary data
                                                                            ...
                                                                        }
                                                                        

                                                                        The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                        %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                                                        ...
                                                                        void foo(char **s, int *slen);
                                                                        

                                                                        In the target language:

                                                                        >>> foo()
                                                                        '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                                                        >>>
                                                                        

                                                                        This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                                                        char  *get_data(int *len);
                                                                        

                                                                        You could wrap it with a function like this:

                                                                        void my_get_data(char **result, int *len) {
                                                                           *result = get_data(len);
                                                                        }
                                                                        

                                                                        Comments:
                                                                        • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                                                        • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                                                        • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                                                        • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                                                        8.4 C++ Library

                                                                        The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                                                        8.4.1 std_string.i

                                                                        The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                                                        %module example
                                                                        %include "std_string.i"
                                                                        
                                                                        std::string foo();
                                                                        void        bar(const std::string &x);
                                                                        

                                                                        In the target language:

                                                                        x = foo();                # Returns a string object
                                                                        bar("Hello World");       # Pass string as std::string
                                                                        

                                                                        This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                                                        This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                                                        %module example
                                                                        %include "std_string.i"
                                                                        
                                                                        using namespace std;
                                                                        typedef std::string String;
                                                                        ...
                                                                        void foo(string s, const String &t);     // std_string typemaps still applied
                                                                        

                                                                        Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                                                        8.4.2 std_vector.i

                                                                        The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                                                        %module example
                                                                        %include "std_vector.i"
                                                                        
                                                                        namespace std {
                                                                           %template(vectori) vector<int>;
                                                                           %template(vectord) vector<double>;
                                                                        };
                                                                        

                                                                        When a template vector<X> is instantiated a number of things happen:
                                                                        • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                                                        • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                                                        • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                                                        • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                                                        • An exception handler for std::out_of_range is defined.
                                                                        • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                                                        To illustrate the use of this library, consider the following functions:

                                                                        /* File : example.h */
                                                                        
                                                                        #include <vector>
                                                                        #include <algorithm>
                                                                        #include <functional>
                                                                        #include <numeric>
                                                                        
                                                                        double average(std::vector<int> v) {
                                                                            return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                                                        }
                                                                        
                                                                        std::vector<double> half(const std::vector<double>& v) {
                                                                            std::vector<double> w(v);
                                                                            for (unsigned int i=0; i<w.size(); i++)
                                                                                w[i] /= 2.0;
                                                                            return w;
                                                                        }
                                                                        
                                                                        void halve_in_place(std::vector<double>& v) {
                                                                            std::transform(v.begin(),v.end(),v.begin(),
                                                                                           std::bind2nd(std::divides<double>(),2.0));
                                                                        }
                                                                        

                                                                        To wrap with SWIG, you might write the following:

                                                                        %module example
                                                                        %{
                                                                        #include "example.h"
                                                                        %}
                                                                        
                                                                        %include "std_vector.i"
                                                                        // Instantiate templates used by example
                                                                        namespace std {
                                                                           %template(IntVector) vector<int>;
                                                                           %template(DoubleVector) vector<double>;
                                                                        }
                                                                        
                                                                        // Include the header file with above prototypes
                                                                        %include "example.h"
                                                                        

                                                                        Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                                                        >>> from example import *
                                                                        >>> iv = IntVector(4)         # Create an vector<int>
                                                                        >>> for i in range(0,4):
                                                                        ...      iv[i] = i
                                                                        >>> average(iv)               # Call method
                                                                        1.5
                                                                        >>> average([0,1,2,3])        # Call with list
                                                                        1.5
                                                                        >>> half([1,2,3])             # Half a list
                                                                        (0.5,1.0,1.5)
                                                                        >>> halve_in_place([1,2,3])   # Oops
                                                                        Traceback (most recent call last):
                                                                          File "<stdin>", line 1, in ?
                                                                        TypeError: Type error. Expected _p_std__vectorTdouble_t
                                                                        >>> dv = DoubleVector(4)
                                                                        >>> for i in range(0,4):
                                                                        ...       dv[i] = i
                                                                        >>> halve_in_place(dv)       # Ok
                                                                        >>> for i in dv:
                                                                        ...       print i
                                                                        ...
                                                                        0.0
                                                                        0.5
                                                                        1.0
                                                                        1.5
                                                                        >>> dv[20] = 4.5
                                                                        Traceback (most recent call last):
                                                                          File "<stdin>", line 1, in ?
                                                                          File "example.py", line 81, in __setitem__
                                                                            def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                                                        IndexError: vector index out of range
                                                                        >>>
                                                                        

                                                                        This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                                                        %include "std_vector.i"
                                                                        
                                                                        namespace std {
                                                                            %template(IntVector) vector<int>;
                                                                        }
                                                                        
                                                                        using namespace std;
                                                                        typedef std::vector Vector;
                                                                        
                                                                        void foo(vector<int> *x, const Vector &x);
                                                                        

                                                                        Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                                                        Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                                                        Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                                                        8.5 Utility Libraries

                                                                        8.5.1 exception.i

                                                                        The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                                                        SWIG_exception(int code, const char *message)

                                                                        Raises an exception in the target language. code is one of the following symbolic constants:

                                                                        SWIG_MemoryError
                                                                        SWIG_IOError
                                                                        SWIG_RuntimeError
                                                                        SWIG_IndexError
                                                                        SWIG_TypeError
                                                                        SWIG_DivisionByZero
                                                                        SWIG_OverflowError
                                                                        SWIG_SyntaxError
                                                                        SWIG_ValueError
                                                                        SWIG_SystemError
                                                                        

                                                                        message is a string indicating more information about the problem.

                                                                        The primary use of this module is in writing language-independent exception handlers. For example:

                                                                        %include "exception.i"
                                                                        %exception std::vector::getitem {
                                                                            try {
                                                                                $action
                                                                            } catch (std::out_of_range& e) {
                                                                                SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                                            }
                                                                        }
                                                                        

                                                                        ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                                                        

                                                                        SWIG-1.3 Documentation

                                                                        
                                                                        

                                                                        ---

                                                                        Table of Contents

                                                                        
                                                                        
                                                                        SWIG-1.3 Development Documentation
                                                                        • Sections
                                                                        • SWIG Core Documentation
                                                                        • Language Module Documentation
                                                                        • Developer Documentation
                                                                        • Documentation that has not yet been updated
                                                                        1 Preface
                                                                        • 1.1 Introduction
                                                                        • 1.2 Special Introduction for Version 1.3
                                                                        • 1.3 SWIG Versions
                                                                        • 1.4 SWIG resources
                                                                        • 1.5 Prerequisites
                                                                        • 1.6 Organization of this manual
                                                                        • 1.7 How to avoid reading the manual
                                                                        • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                                                          >>> make_upper("hello world")
                                                                          'HELLO WORLD'
                                                                          >>> attach_header("Hello world")
                                                                          'header: Hello world'
                                                                          >>>
                                                                          

                                                                          This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                                                          %cstring_output_maxsize(parm, maxparm)

                                                                          This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                                                          %cstring_output_maxsize(char *path, int maxpath);
                                                                          ...
                                                                          void get_path(char *path, int maxpath);
                                                                          

                                                                          In the target language:

                                                                          >>> get_path(1024)
                                                                          '/home/beazley/Packages/Foo/Bar'
                                                                          >>>
                                                                          

                                                                          This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                                                          %cstring_output_withsize(parm, maxparm)

                                                                          This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                                                          %cstring_output_withsize(char *data, int *maxdata);
                                                                          ...
                                                                          void get_data(char *data, int *maxdata);
                                                                          

                                                                          In the target language:

                                                                          >>> get_data(1024)
                                                                          'x627388912'
                                                                          >>> get_data(1024)
                                                                          'xyzzy'
                                                                          >>>
                                                                          

                                                                          This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                                                          %cstring_output_allocate(parm, release)

                                                                          This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                                                          void foo(char **s) {
                                                                              *s = (char *) malloc(64);
                                                                              sprintf(*s, "Hello world\n");
                                                                          }
                                                                          

                                                                          The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                          %cstring_output_allocate(char **s, free(*$1));
                                                                          ...
                                                                          void foo(char **s);
                                                                          

                                                                          In the target language:

                                                                          >>> foo()
                                                                          'Hello world\n'
                                                                          >>>
                                                                          

                                                                          %cstring_output_allocate_size(parm, szparm, release)

                                                                          This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                                                          void foo(char **s, int *sz) {
                                                                              *s = (char *) malloc(64);
                                                                              *sz = 64;
                                                                              // Write some binary data
                                                                              ...
                                                                          }
                                                                          

                                                                          The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                          %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                                                          ...
                                                                          void foo(char **s, int *slen);
                                                                          

                                                                          In the target language:

                                                                          >>> foo()
                                                                          '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                                                          >>>
                                                                          

                                                                          This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                                                          char  *get_data(int *len);
                                                                          

                                                                          You could wrap it with a function like this:

                                                                          void my_get_data(char **result, int *len) {
                                                                             *result = get_data(len);
                                                                          }
                                                                          

                                                                          Comments:
                                                                          • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                                                          • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                                                          • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                                                          • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                                                          8.4 C++ Library

                                                                          The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                                                          8.4.1 std_string.i

                                                                          The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                                                          %module example
                                                                          %include "std_string.i"
                                                                          
                                                                          std::string foo();
                                                                          void        bar(const std::string &x);
                                                                          

                                                                          In the target language:

                                                                          x = foo();                # Returns a string object
                                                                          bar("Hello World");       # Pass string as std::string
                                                                          

                                                                          This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                                                          This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                                                          %module example
                                                                          %include "std_string.i"
                                                                          
                                                                          using namespace std;
                                                                          typedef std::string String;
                                                                          ...
                                                                          void foo(string s, const String &t);     // std_string typemaps still applied
                                                                          

                                                                          Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                                                          8.4.2 std_vector.i

                                                                          The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                                                          %module example
                                                                          %include "std_vector.i"
                                                                          
                                                                          namespace std {
                                                                             %template(vectori) vector<int>;
                                                                             %template(vectord) vector<double>;
                                                                          };
                                                                          

                                                                          When a template vector<X> is instantiated a number of things happen:
                                                                          • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                                                          • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                                                          • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                                                          • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                                                          • An exception handler for std::out_of_range is defined.
                                                                          • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                                                          To illustrate the use of this library, consider the following functions:

                                                                          /* File : example.h */
                                                                          
                                                                          #include <vector>
                                                                          #include <algorithm>
                                                                          #include <functional>
                                                                          #include <numeric>
                                                                          
                                                                          double average(std::vector<int> v) {
                                                                              return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                                                          }
                                                                          
                                                                          std::vector<double> half(const std::vector<double>& v) {
                                                                              std::vector<double> w(v);
                                                                              for (unsigned int i=0; i<w.size(); i++)
                                                                                  w[i] /= 2.0;
                                                                              return w;
                                                                          }
                                                                          
                                                                          void halve_in_place(std::vector<double>& v) {
                                                                              std::transform(v.begin(),v.end(),v.begin(),
                                                                                             std::bind2nd(std::divides<double>(),2.0));
                                                                          }
                                                                          

                                                                          To wrap with SWIG, you might write the following:

                                                                          %module example
                                                                          %{
                                                                          #include "example.h"
                                                                          %}
                                                                          
                                                                          %include "std_vector.i"
                                                                          // Instantiate templates used by example
                                                                          namespace std {
                                                                             %template(IntVector) vector<int>;
                                                                             %template(DoubleVector) vector<double>;
                                                                          }
                                                                          
                                                                          // Include the header file with above prototypes
                                                                          %include "example.h"
                                                                          

                                                                          Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                                                          >>> from example import *
                                                                          >>> iv = IntVector(4)         # Create an vector<int>
                                                                          >>> for i in range(0,4):
                                                                          ...      iv[i] = i
                                                                          >>> average(iv)               # Call method
                                                                          1.5
                                                                          >>> average([0,1,2,3])        # Call with list
                                                                          1.5
                                                                          >>> half([1,2,3])             # Half a list
                                                                          (0.5,1.0,1.5)
                                                                          >>> halve_in_place([1,2,3])   # Oops
                                                                          Traceback (most recent call last):
                                                                            File "<stdin>", line 1, in ?
                                                                          TypeError: Type error. Expected _p_std__vectorTdouble_t
                                                                          >>> dv = DoubleVector(4)
                                                                          >>> for i in range(0,4):
                                                                          ...       dv[i] = i
                                                                          >>> halve_in_place(dv)       # Ok
                                                                          >>> for i in dv:
                                                                          ...       print i
                                                                          ...
                                                                          0.0
                                                                          0.5
                                                                          1.0
                                                                          1.5
                                                                          >>> dv[20] = 4.5
                                                                          Traceback (most recent call last):
                                                                            File "<stdin>", line 1, in ?
                                                                            File "example.py", line 81, in __setitem__
                                                                              def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                                                          IndexError: vector index out of range
                                                                          >>>
                                                                          

                                                                          This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                                                          %include "std_vector.i"
                                                                          
                                                                          namespace std {
                                                                              %template(IntVector) vector<int>;
                                                                          }
                                                                          
                                                                          using namespace std;
                                                                          typedef std::vector Vector;
                                                                          
                                                                          void foo(vector<int> *x, const Vector &x);
                                                                          

                                                                          Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                                                          Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                                                          Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                                                          8.5 Utility Libraries

                                                                          8.5.1 exception.i

                                                                          The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                                                          SWIG_exception(int code, const char *message)

                                                                          Raises an exception in the target language. code is one of the following symbolic constants:

                                                                          SWIG_MemoryError
                                                                          SWIG_IOError
                                                                          SWIG_RuntimeError
                                                                          SWIG_IndexError
                                                                          SWIG_TypeError
                                                                          SWIG_DivisionByZero
                                                                          SWIG_OverflowError
                                                                          SWIG_SyntaxError
                                                                          SWIG_ValueError
                                                                          SWIG_SystemError
                                                                          

                                                                          message is a string indicating more information about the problem.

                                                                          The primary use of this module is in writing language-independent exception handlers. For example:

                                                                          %include "exception.i"
                                                                          %exception std::vector::getitem {
                                                                              try {
                                                                                  $action
                                                                              } catch (std::out_of_range& e) {
                                                                                  SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                                              }
                                                                          }
                                                                          

                                                                          ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                                                          

                                                                          SWIG-1.3 Documentation

                                                                          
                                                                          

                                                                          ---

                                                                          Table of Contents

                                                                          
                                                                          
                                                                          SWIG-1.3 Development Documentation
                                                                          • Sections
                                                                          • SWIG Core Documentation
                                                                          • Language Module Documentation
                                                                          • Developer Documentation
                                                                          • Documentation that has not yet been updated
                                                                          1 Preface
                                                                          • 1.1 Introduction
                                                                          • 1.2 Special Introduction for Version 1.3
                                                                          • 1.3 SWIG Versions
                                                                          • 1.4 SWIG resources
                                                                          • 1.5 Prerequisites
                                                                          • 1.6 Organization of this manual
                                                                          • 1.7 How to avoid reading the manual
                                                                          • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                                                            >>> make_upper("hello world")
                                                                            'HELLO WORLD'
                                                                            >>> attach_header("Hello world")
                                                                            'header: Hello world'
                                                                            >>>
                                                                            

                                                                            This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                                                            %cstring_output_maxsize(parm, maxparm)

                                                                            This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                                                            %cstring_output_maxsize(char *path, int maxpath);
                                                                            ...
                                                                            void get_path(char *path, int maxpath);
                                                                            

                                                                            In the target language:

                                                                            >>> get_path(1024)
                                                                            '/home/beazley/Packages/Foo/Bar'
                                                                            >>>
                                                                            

                                                                            This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                                                            %cstring_output_withsize(parm, maxparm)

                                                                            This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                                                            %cstring_output_withsize(char *data, int *maxdata);
                                                                            ...
                                                                            void get_data(char *data, int *maxdata);
                                                                            

                                                                            In the target language:

                                                                            >>> get_data(1024)
                                                                            'x627388912'
                                                                            >>> get_data(1024)
                                                                            'xyzzy'
                                                                            >>>
                                                                            

                                                                            This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                                                            %cstring_output_allocate(parm, release)

                                                                            This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                                                            void foo(char **s) {
                                                                                *s = (char *) malloc(64);
                                                                                sprintf(*s, "Hello world\n");
                                                                            }
                                                                            

                                                                            The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                            %cstring_output_allocate(char **s, free(*$1));
                                                                            ...
                                                                            void foo(char **s);
                                                                            

                                                                            In the target language:

                                                                            >>> foo()
                                                                            'Hello world\n'
                                                                            >>>
                                                                            

                                                                            %cstring_output_allocate_size(parm, szparm, release)

                                                                            This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                                                            void foo(char **s, int *sz) {
                                                                                *s = (char *) malloc(64);
                                                                                *sz = 64;
                                                                                // Write some binary data
                                                                                ...
                                                                            }
                                                                            

                                                                            The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                            %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                                                            ...
                                                                            void foo(char **s, int *slen);
                                                                            

                                                                            In the target language:

                                                                            >>> foo()
                                                                            '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                                                            >>>
                                                                            

                                                                            This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                                                            char  *get_data(int *len);
                                                                            

                                                                            You could wrap it with a function like this:

                                                                            void my_get_data(char **result, int *len) {
                                                                               *result = get_data(len);
                                                                            }
                                                                            

                                                                            Comments:
                                                                            • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                                                            • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                                                            • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                                                            • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                                                            8.4 C++ Library

                                                                            The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                                                            8.4.1 std_string.i

                                                                            The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                                                            %module example
                                                                            %include "std_string.i"
                                                                            
                                                                            std::string foo();
                                                                            void        bar(const std::string &x);
                                                                            

                                                                            In the target language:

                                                                            x = foo();                # Returns a string object
                                                                            bar("Hello World");       # Pass string as std::string
                                                                            

                                                                            This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                                                            This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                                                            %module example
                                                                            %include "std_string.i"
                                                                            
                                                                            using namespace std;
                                                                            typedef std::string String;
                                                                            ...
                                                                            void foo(string s, const String &t);     // std_string typemaps still applied
                                                                            

                                                                            Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                                                            8.4.2 std_vector.i

                                                                            The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                                                            %module example
                                                                            %include "std_vector.i"
                                                                            
                                                                            namespace std {
                                                                               %template(vectori) vector<int>;
                                                                               %template(vectord) vector<double>;
                                                                            };
                                                                            

                                                                            When a template vector<X> is instantiated a number of things happen:
                                                                            • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                                                            • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                                                            • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                                                            • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                                                            • An exception handler for std::out_of_range is defined.
                                                                            • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                                                            To illustrate the use of this library, consider the following functions:

                                                                            /* File : example.h */
                                                                            
                                                                            #include <vector>
                                                                            #include <algorithm>
                                                                            #include <functional>
                                                                            #include <numeric>
                                                                            
                                                                            double average(std::vector<int> v) {
                                                                                return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                                                            }
                                                                            
                                                                            std::vector<double> half(const std::vector<double>& v) {
                                                                                std::vector<double> w(v);
                                                                                for (unsigned int i=0; i<w.size(); i++)
                                                                                    w[i] /= 2.0;
                                                                                return w;
                                                                            }
                                                                            
                                                                            void halve_in_place(std::vector<double>& v) {
                                                                                std::transform(v.begin(),v.end(),v.begin(),
                                                                                               std::bind2nd(std::divides<double>(),2.0));
                                                                            }
                                                                            

                                                                            To wrap with SWIG, you might write the following:

                                                                            %module example
                                                                            %{
                                                                            #include "example.h"
                                                                            %}
                                                                            
                                                                            %include "std_vector.i"
                                                                            // Instantiate templates used by example
                                                                            namespace std {
                                                                               %template(IntVector) vector<int>;
                                                                               %template(DoubleVector) vector<double>;
                                                                            }
                                                                            
                                                                            // Include the header file with above prototypes
                                                                            %include "example.h"
                                                                            

                                                                            Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                                                            >>> from example import *
                                                                            >>> iv = IntVector(4)         # Create an vector<int>
                                                                            >>> for i in range(0,4):
                                                                            ...      iv[i] = i
                                                                            >>> average(iv)               # Call method
                                                                            1.5
                                                                            >>> average([0,1,2,3])        # Call with list
                                                                            1.5
                                                                            >>> half([1,2,3])             # Half a list
                                                                            (0.5,1.0,1.5)
                                                                            >>> halve_in_place([1,2,3])   # Oops
                                                                            Traceback (most recent call last):
                                                                              File "<stdin>", line 1, in ?
                                                                            TypeError: Type error. Expected _p_std__vectorTdouble_t
                                                                            >>> dv = DoubleVector(4)
                                                                            >>> for i in range(0,4):
                                                                            ...       dv[i] = i
                                                                            >>> halve_in_place(dv)       # Ok
                                                                            >>> for i in dv:
                                                                            ...       print i
                                                                            ...
                                                                            0.0
                                                                            0.5
                                                                            1.0
                                                                            1.5
                                                                            >>> dv[20] = 4.5
                                                                            Traceback (most recent call last):
                                                                              File "<stdin>", line 1, in ?
                                                                              File "example.py", line 81, in __setitem__
                                                                                def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                                                            IndexError: vector index out of range
                                                                            >>>
                                                                            

                                                                            This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                                                            %include "std_vector.i"
                                                                            
                                                                            namespace std {
                                                                                %template(IntVector) vector<int>;
                                                                            }
                                                                            
                                                                            using namespace std;
                                                                            typedef std::vector Vector;
                                                                            
                                                                            void foo(vector<int> *x, const Vector &x);
                                                                            

                                                                            Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                                                            Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                                                            Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                                                            8.5 Utility Libraries

                                                                            8.5.1 exception.i

                                                                            The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                                                            SWIG_exception(int code, const char *message)

                                                                            Raises an exception in the target language. code is one of the following symbolic constants:

                                                                            SWIG_MemoryError
                                                                            SWIG_IOError
                                                                            SWIG_RuntimeError
                                                                            SWIG_IndexError
                                                                            SWIG_TypeError
                                                                            SWIG_DivisionByZero
                                                                            SWIG_OverflowError
                                                                            SWIG_SyntaxError
                                                                            SWIG_ValueError
                                                                            SWIG_SystemError
                                                                            

                                                                            message is a string indicating more information about the problem.

                                                                            The primary use of this module is in writing language-independent exception handlers. For example:

                                                                            %include "exception.i"
                                                                            %exception std::vector::getitem {
                                                                                try {
                                                                                    $action
                                                                                } catch (std::out_of_range& e) {
                                                                                    SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                                                }
                                                                            }
                                                                            

                                                                            ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                                                            

                                                                            SWIG-1.3 Documentation

                                                                            
                                                                            

                                                                            ---

                                                                            Table of Contents

                                                                            
                                                                            
                                                                            SWIG-1.3 Development Documentation
                                                                            • Sections
                                                                            • SWIG Core Documentation
                                                                            • Language Module Documentation
                                                                            • Developer Documentation
                                                                            • Documentation that has not yet been updated
                                                                            1 Preface
                                                                            • 1.1 Introduction
                                                                            • 1.2 Special Introduction for Version 1.3
                                                                            • 1.3 SWIG Versions
                                                                            • 1.4 SWIG resources
                                                                            • 1.5 Prerequisites
                                                                            • 1.6 Organization of this manual
                                                                            • 1.7 How to avoid reading the manual
                                                                            • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                                                              >>> make_upper("hello world")
                                                                              'HELLO WORLD'
                                                                              >>> attach_header("Hello world")
                                                                              'header: Hello world'
                                                                              >>>
                                                                              

                                                                              This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                                                              %cstring_output_maxsize(parm, maxparm)

                                                                              This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                                                              %cstring_output_maxsize(char *path, int maxpath);
                                                                              ...
                                                                              void get_path(char *path, int maxpath);
                                                                              

                                                                              In the target language:

                                                                              >>> get_path(1024)
                                                                              '/home/beazley/Packages/Foo/Bar'
                                                                              >>>
                                                                              

                                                                              This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                                                              %cstring_output_withsize(parm, maxparm)

                                                                              This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                                                              %cstring_output_withsize(char *data, int *maxdata);
                                                                              ...
                                                                              void get_data(char *data, int *maxdata);
                                                                              

                                                                              In the target language:

                                                                              >>> get_data(1024)
                                                                              'x627388912'
                                                                              >>> get_data(1024)
                                                                              'xyzzy'
                                                                              >>>
                                                                              

                                                                              This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                                                              %cstring_output_allocate(parm, release)

                                                                              This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                                                              void foo(char **s) {
                                                                                  *s = (char *) malloc(64);
                                                                                  sprintf(*s, "Hello world\n");
                                                                              }
                                                                              

                                                                              The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                              %cstring_output_allocate(char **s, free(*$1));
                                                                              ...
                                                                              void foo(char **s);
                                                                              

                                                                              In the target language:

                                                                              >>> foo()
                                                                              'Hello world\n'
                                                                              >>>
                                                                              

                                                                              %cstring_output_allocate_size(parm, szparm, release)

                                                                              This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                                                              void foo(char **s, int *sz) {
                                                                                  *s = (char *) malloc(64);
                                                                                  *sz = 64;
                                                                                  // Write some binary data
                                                                                  ...
                                                                              }
                                                                              

                                                                              The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                              %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                                                              ...
                                                                              void foo(char **s, int *slen);
                                                                              

                                                                              In the target language:

                                                                              >>> foo()
                                                                              '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                                                              >>>
                                                                              

                                                                              This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                                                              char  *get_data(int *len);
                                                                              

                                                                              You could wrap it with a function like this:

                                                                              void my_get_data(char **result, int *len) {
                                                                                 *result = get_data(len);
                                                                              }
                                                                              

                                                                              Comments:
                                                                              • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                                                              • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                                                              • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                                                              • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                                                              8.4 C++ Library

                                                                              The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                                                              8.4.1 std_string.i

                                                                              The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                                                              %module example
                                                                              %include "std_string.i"
                                                                              
                                                                              std::string foo();
                                                                              void        bar(const std::string &x);
                                                                              

                                                                              In the target language:

                                                                              x = foo();                # Returns a string object
                                                                              bar("Hello World");       # Pass string as std::string
                                                                              

                                                                              This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                                                              This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                                                              %module example
                                                                              %include "std_string.i"
                                                                              
                                                                              using namespace std;
                                                                              typedef std::string String;
                                                                              ...
                                                                              void foo(string s, const String &t);     // std_string typemaps still applied
                                                                              

                                                                              Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                                                              8.4.2 std_vector.i

                                                                              The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                                                              %module example
                                                                              %include "std_vector.i"
                                                                              
                                                                              namespace std {
                                                                                 %template(vectori) vector<int>;
                                                                                 %template(vectord) vector<double>;
                                                                              };
                                                                              

                                                                              When a template vector<X> is instantiated a number of things happen:
                                                                              • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                                                              • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                                                              • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                                                              • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                                                              • An exception handler for std::out_of_range is defined.
                                                                              • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                                                              To illustrate the use of this library, consider the following functions:

                                                                              /* File : example.h */
                                                                              
                                                                              #include <vector>
                                                                              #include <algorithm>
                                                                              #include <functional>
                                                                              #include <numeric>
                                                                              
                                                                              double average(std::vector<int> v) {
                                                                                  return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                                                              }
                                                                              
                                                                              std::vector<double> half(const std::vector<double>& v) {
                                                                                  std::vector<double> w(v);
                                                                                  for (unsigned int i=0; i<w.size(); i++)
                                                                                      w[i] /= 2.0;
                                                                                  return w;
                                                                              }
                                                                              
                                                                              void halve_in_place(std::vector<double>& v) {
                                                                                  std::transform(v.begin(),v.end(),v.begin(),
                                                                                                 std::bind2nd(std::divides<double>(),2.0));
                                                                              }
                                                                              

                                                                              To wrap with SWIG, you might write the following:

                                                                              %module example
                                                                              %{
                                                                              #include "example.h"
                                                                              %}
                                                                              
                                                                              %include "std_vector.i"
                                                                              // Instantiate templates used by example
                                                                              namespace std {
                                                                                 %template(IntVector) vector<int>;
                                                                                 %template(DoubleVector) vector<double>;
                                                                              }
                                                                              
                                                                              // Include the header file with above prototypes
                                                                              %include "example.h"
                                                                              

                                                                              Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                                                              >>> from example import *
                                                                              >>> iv = IntVector(4)         # Create an vector<int>
                                                                              >>> for i in range(0,4):
                                                                              ...      iv[i] = i
                                                                              >>> average(iv)               # Call method
                                                                              1.5
                                                                              >>> average([0,1,2,3])        # Call with list
                                                                              1.5
                                                                              >>> half([1,2,3])             # Half a list
                                                                              (0.5,1.0,1.5)
                                                                              >>> halve_in_place([1,2,3])   # Oops
                                                                              Traceback (most recent call last):
                                                                                File "<stdin>", line 1, in ?
                                                                              TypeError: Type error. Expected _p_std__vectorTdouble_t
                                                                              >>> dv = DoubleVector(4)
                                                                              >>> for i in range(0,4):
                                                                              ...       dv[i] = i
                                                                              >>> halve_in_place(dv)       # Ok
                                                                              >>> for i in dv:
                                                                              ...       print i
                                                                              ...
                                                                              0.0
                                                                              0.5
                                                                              1.0
                                                                              1.5
                                                                              >>> dv[20] = 4.5
                                                                              Traceback (most recent call last):
                                                                                File "<stdin>", line 1, in ?
                                                                                File "example.py", line 81, in __setitem__
                                                                                  def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                                                              IndexError: vector index out of range
                                                                              >>>
                                                                              

                                                                              This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                                                              %include "std_vector.i"
                                                                              
                                                                              namespace std {
                                                                                  %template(IntVector) vector<int>;
                                                                              }
                                                                              
                                                                              using namespace std;
                                                                              typedef std::vector Vector;
                                                                              
                                                                              void foo(vector<int> *x, const Vector &x);
                                                                              

                                                                              Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                                                              Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                                                              Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                                                              8.5 Utility Libraries

                                                                              8.5.1 exception.i

                                                                              The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                                                              SWIG_exception(int code, const char *message)

                                                                              Raises an exception in the target language. code is one of the following symbolic constants:

                                                                              SWIG_MemoryError
                                                                              SWIG_IOError
                                                                              SWIG_RuntimeError
                                                                              SWIG_IndexError
                                                                              SWIG_TypeError
                                                                              SWIG_DivisionByZero
                                                                              SWIG_OverflowError
                                                                              SWIG_SyntaxError
                                                                              SWIG_ValueError
                                                                              SWIG_SystemError
                                                                              

                                                                              message is a string indicating more information about the problem.

                                                                              The primary use of this module is in writing language-independent exception handlers. For example:

                                                                              %include "exception.i"
                                                                              %exception std::vector::getitem {
                                                                                  try {
                                                                                      $action
                                                                                  } catch (std::out_of_range& e) {
                                                                                      SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                                                  }
                                                                              }
                                                                              

                                                                              ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                                                              

                                                                              SWIG-1.3 Documentation

                                                                              
                                                                              

                                                                              ---

                                                                              Table of Contents

                                                                              
                                                                              
                                                                              SWIG-1.3 Development Documentation
                                                                              • Sections
                                                                              • SWIG Core Documentation
                                                                              • Language Module Documentation
                                                                              • Developer Documentation
                                                                              • Documentation that has not yet been updated
                                                                              1 Preface
                                                                              • 1.1 Introduction
                                                                              • 1.2 Special Introduction for Version 1.3
                                                                              • 1.3 SWIG Versions
                                                                              • 1.4 SWIG resources
                                                                              • 1.5 Prerequisites
                                                                              • 1.6 Organization of this manual
                                                                              • 1.7 How to avoid reading the manual
                                                                              • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                                                                >>> make_upper("hello world")
                                                                                'HELLO WORLD'
                                                                                >>> attach_header("Hello world")
                                                                                'header: Hello world'
                                                                                >>>
                                                                                

                                                                                This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                                                                %cstring_output_maxsize(parm, maxparm)

                                                                                This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                                                                %cstring_output_maxsize(char *path, int maxpath);
                                                                                ...
                                                                                void get_path(char *path, int maxpath);
                                                                                

                                                                                In the target language:

                                                                                >>> get_path(1024)
                                                                                '/home/beazley/Packages/Foo/Bar'
                                                                                >>>
                                                                                

                                                                                This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                                                                %cstring_output_withsize(parm, maxparm)

                                                                                This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                                                                %cstring_output_withsize(char *data, int *maxdata);
                                                                                ...
                                                                                void get_data(char *data, int *maxdata);
                                                                                

                                                                                In the target language:

                                                                                >>> get_data(1024)
                                                                                'x627388912'
                                                                                >>> get_data(1024)
                                                                                'xyzzy'
                                                                                >>>
                                                                                

                                                                                This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                                                                %cstring_output_allocate(parm, release)

                                                                                This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                                                                void foo(char **s) {
                                                                                    *s = (char *) malloc(64);
                                                                                    sprintf(*s, "Hello world\n");
                                                                                }
                                                                                

                                                                                The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                %cstring_output_allocate(char **s, free(*$1));
                                                                                ...
                                                                                void foo(char **s);
                                                                                

                                                                                In the target language:

                                                                                >>> foo()
                                                                                'Hello world\n'
                                                                                >>>
                                                                                

                                                                                %cstring_output_allocate_size(parm, szparm, release)

                                                                                This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                                                                void foo(char **s, int *sz) {
                                                                                    *s = (char *) malloc(64);
                                                                                    *sz = 64;
                                                                                    // Write some binary data
                                                                                    ...
                                                                                }
                                                                                

                                                                                The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                                                                ...
                                                                                void foo(char **s, int *slen);
                                                                                

                                                                                In the target language:

                                                                                >>> foo()
                                                                                '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                                                                >>>
                                                                                

                                                                                This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                                                                char  *get_data(int *len);
                                                                                

                                                                                You could wrap it with a function like this:

                                                                                void my_get_data(char **result, int *len) {
                                                                                   *result = get_data(len);
                                                                                }
                                                                                

                                                                                Comments:
                                                                                • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                                                                • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                                                                • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                                                                • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                                                                8.4 C++ Library

                                                                                The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                                                                8.4.1 std_string.i

                                                                                The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                                                                %module example
                                                                                %include "std_string.i"
                                                                                
                                                                                std::string foo();
                                                                                void        bar(const std::string &x);
                                                                                

                                                                                In the target language:

                                                                                x = foo();                # Returns a string object
                                                                                bar("Hello World");       # Pass string as std::string
                                                                                

                                                                                This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                                                                This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                                                                %module example
                                                                                %include "std_string.i"
                                                                                
                                                                                using namespace std;
                                                                                typedef std::string String;
                                                                                ...
                                                                                void foo(string s, const String &t);     // std_string typemaps still applied
                                                                                

                                                                                Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                                                                8.4.2 std_vector.i

                                                                                The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                                                                %module example
                                                                                %include "std_vector.i"
                                                                                
                                                                                namespace std {
                                                                                   %template(vectori) vector<int>;
                                                                                   %template(vectord) vector<double>;
                                                                                };
                                                                                

                                                                                When a template vector<X> is instantiated a number of things happen:
                                                                                • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                                                                • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                                                                • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                                                                • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                                                                • An exception handler for std::out_of_range is defined.
                                                                                • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                                                                To illustrate the use of this library, consider the following functions:

                                                                                /* File : example.h */
                                                                                
                                                                                #include <vector>
                                                                                #include <algorithm>
                                                                                #include <functional>
                                                                                #include <numeric>
                                                                                
                                                                                double average(std::vector<int> v) {
                                                                                    return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                                                                }
                                                                                
                                                                                std::vector<double> half(const std::vector<double>& v) {
                                                                                    std::vector<double> w(v);
                                                                                    for (unsigned int i=0; i<w.size(); i++)
                                                                                        w[i] /= 2.0;
                                                                                    return w;
                                                                                }
                                                                                
                                                                                void halve_in_place(std::vector<double>& v) {
                                                                                    std::transform(v.begin(),v.end(),v.begin(),
                                                                                                   std::bind2nd(std::divides<double>(),2.0));
                                                                                }
                                                                                

                                                                                To wrap with SWIG, you might write the following:

                                                                                %module example
                                                                                %{
                                                                                #include "example.h"
                                                                                %}
                                                                                
                                                                                %include "std_vector.i"
                                                                                // Instantiate templates used by example
                                                                                namespace std {
                                                                                   %template(IntVector) vector<int>;
                                                                                   %template(DoubleVector) vector<double>;
                                                                                }
                                                                                
                                                                                // Include the header file with above prototypes
                                                                                %include "example.h"
                                                                                

                                                                                Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                                                                >>> from example import *
                                                                                >>> iv = IntVector(4)         # Create an vector<int>
                                                                                >>> for i in range(0,4):
                                                                                ...      iv[i] = i
                                                                                >>> average(iv)               # Call method
                                                                                1.5
                                                                                >>> average([0,1,2,3])        # Call with list
                                                                                1.5
                                                                                >>> half([1,2,3])             # Half a list
                                                                                (0.5,1.0,1.5)
                                                                                >>> halve_in_place([1,2,3])   # Oops
                                                                                Traceback (most recent call last):
                                                                                  File "<stdin>", line 1, in ?
                                                                                TypeError: Type error. Expected _p_std__vectorTdouble_t
                                                                                >>> dv = DoubleVector(4)
                                                                                >>> for i in range(0,4):
                                                                                ...       dv[i] = i
                                                                                >>> halve_in_place(dv)       # Ok
                                                                                >>> for i in dv:
                                                                                ...       print i
                                                                                ...
                                                                                0.0
                                                                                0.5
                                                                                1.0
                                                                                1.5
                                                                                >>> dv[20] = 4.5
                                                                                Traceback (most recent call last):
                                                                                  File "<stdin>", line 1, in ?
                                                                                  File "example.py", line 81, in __setitem__
                                                                                    def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                                                                IndexError: vector index out of range
                                                                                >>>
                                                                                

                                                                                This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                                                                %include "std_vector.i"
                                                                                
                                                                                namespace std {
                                                                                    %template(IntVector) vector<int>;
                                                                                }
                                                                                
                                                                                using namespace std;
                                                                                typedef std::vector Vector;
                                                                                
                                                                                void foo(vector<int> *x, const Vector &x);
                                                                                

                                                                                Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                                                                Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                                                                Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                                                                8.5 Utility Libraries

                                                                                8.5.1 exception.i

                                                                                The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                                                                SWIG_exception(int code, const char *message)

                                                                                Raises an exception in the target language. code is one of the following symbolic constants:

                                                                                SWIG_MemoryError
                                                                                SWIG_IOError
                                                                                SWIG_RuntimeError
                                                                                SWIG_IndexError
                                                                                SWIG_TypeError
                                                                                SWIG_DivisionByZero
                                                                                SWIG_OverflowError
                                                                                SWIG_SyntaxError
                                                                                SWIG_ValueError
                                                                                SWIG_SystemError
                                                                                

                                                                                message is a string indicating more information about the problem.

                                                                                The primary use of this module is in writing language-independent exception handlers. For example:

                                                                                %include "exception.i"
                                                                                %exception std::vector::getitem {
                                                                                    try {
                                                                                        $action
                                                                                    } catch (std::out_of_range& e) {
                                                                                        SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                                                    }
                                                                                }
                                                                                

                                                                                ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                                                                

                                                                                SWIG-1.3 Documentation

                                                                                
                                                                                

                                                                                ---

                                                                                Table of Contents

                                                                                
                                                                                
                                                                                SWIG-1.3 Development Documentation
                                                                                • Sections
                                                                                • SWIG Core Documentation
                                                                                • Language Module Documentation
                                                                                • Developer Documentation
                                                                                • Documentation that has not yet been updated
                                                                                1 Preface
                                                                                • 1.1 Introduction
                                                                                • 1.2 Special Introduction for Version 1.3
                                                                                • 1.3 SWIG Versions
                                                                                • 1.4 SWIG resources
                                                                                • 1.5 Prerequisites
                                                                                • 1.6 Organization of this manual
                                                                                • 1.7 How to avoid reading the manual
                                                                                • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                                                                  >>> make_upper("hello world")
                                                                                  'HELLO WORLD'
                                                                                  >>> attach_header("Hello world")
                                                                                  'header: Hello world'
                                                                                  >>>
                                                                                  

                                                                                  This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                                                                  %cstring_output_maxsize(parm, maxparm)

                                                                                  This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                                                                  %cstring_output_maxsize(char *path, int maxpath);
                                                                                  ...
                                                                                  void get_path(char *path, int maxpath);
                                                                                  

                                                                                  In the target language:

                                                                                  >>> get_path(1024)
                                                                                  '/home/beazley/Packages/Foo/Bar'
                                                                                  >>>
                                                                                  

                                                                                  This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                                                                  %cstring_output_withsize(parm, maxparm)

                                                                                  This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                                                                  %cstring_output_withsize(char *data, int *maxdata);
                                                                                  ...
                                                                                  void get_data(char *data, int *maxdata);
                                                                                  

                                                                                  In the target language:

                                                                                  >>> get_data(1024)
                                                                                  'x627388912'
                                                                                  >>> get_data(1024)
                                                                                  'xyzzy'
                                                                                  >>>
                                                                                  

                                                                                  This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                                                                  %cstring_output_allocate(parm, release)

                                                                                  This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                                                                  void foo(char **s) {
                                                                                      *s = (char *) malloc(64);
                                                                                      sprintf(*s, "Hello world\n");
                                                                                  }
                                                                                  

                                                                                  The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                  %cstring_output_allocate(char **s, free(*$1));
                                                                                  ...
                                                                                  void foo(char **s);
                                                                                  

                                                                                  In the target language:

                                                                                  >>> foo()
                                                                                  'Hello world\n'
                                                                                  >>>
                                                                                  

                                                                                  %cstring_output_allocate_size(parm, szparm, release)

                                                                                  This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                                                                  void foo(char **s, int *sz) {
                                                                                      *s = (char *) malloc(64);
                                                                                      *sz = 64;
                                                                                      // Write some binary data
                                                                                      ...
                                                                                  }
                                                                                  

                                                                                  The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                  %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                                                                  ...
                                                                                  void foo(char **s, int *slen);
                                                                                  

                                                                                  In the target language:

                                                                                  >>> foo()
                                                                                  '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                                                                  >>>
                                                                                  

                                                                                  This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                                                                  char  *get_data(int *len);
                                                                                  

                                                                                  You could wrap it with a function like this:

                                                                                  void my_get_data(char **result, int *len) {
                                                                                     *result = get_data(len);
                                                                                  }
                                                                                  

                                                                                  Comments:
                                                                                  • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                                                                  • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                                                                  • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                                                                  • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                                                                  8.4 C++ Library

                                                                                  The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                                                                  8.4.1 std_string.i

                                                                                  The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                                                                  %module example
                                                                                  %include "std_string.i"
                                                                                  
                                                                                  std::string foo();
                                                                                  void        bar(const std::string &x);
                                                                                  

                                                                                  In the target language:

                                                                                  x = foo();                # Returns a string object
                                                                                  bar("Hello World");       # Pass string as std::string
                                                                                  

                                                                                  This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                                                                  This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                                                                  %module example
                                                                                  %include "std_string.i"
                                                                                  
                                                                                  using namespace std;
                                                                                  typedef std::string String;
                                                                                  ...
                                                                                  void foo(string s, const String &t);     // std_string typemaps still applied
                                                                                  

                                                                                  Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                                                                  8.4.2 std_vector.i

                                                                                  The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                                                                  %module example
                                                                                  %include "std_vector.i"
                                                                                  
                                                                                  namespace std {
                                                                                     %template(vectori) vector<int>;
                                                                                     %template(vectord) vector<double>;
                                                                                  };
                                                                                  

                                                                                  When a template vector<X> is instantiated a number of things happen:
                                                                                  • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                                                                  • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                                                                  • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                                                                  • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                                                                  • An exception handler for std::out_of_range is defined.
                                                                                  • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                                                                  To illustrate the use of this library, consider the following functions:

                                                                                  /* File : example.h */
                                                                                  
                                                                                  #include <vector>
                                                                                  #include <algorithm>
                                                                                  #include <functional>
                                                                                  #include <numeric>
                                                                                  
                                                                                  double average(std::vector<int> v) {
                                                                                      return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                                                                  }
                                                                                  
                                                                                  std::vector<double> half(const std::vector<double>& v) {
                                                                                      std::vector<double> w(v);
                                                                                      for (unsigned int i=0; i<w.size(); i++)
                                                                                          w[i] /= 2.0;
                                                                                      return w;
                                                                                  }
                                                                                  
                                                                                  void halve_in_place(std::vector<double>& v) {
                                                                                      std::transform(v.begin(),v.end(),v.begin(),
                                                                                                     std::bind2nd(std::divides<double>(),2.0));
                                                                                  }
                                                                                  

                                                                                  To wrap with SWIG, you might write the following:

                                                                                  %module example
                                                                                  %{
                                                                                  #include "example.h"
                                                                                  %}
                                                                                  
                                                                                  %include "std_vector.i"
                                                                                  // Instantiate templates used by example
                                                                                  namespace std {
                                                                                     %template(IntVector) vector<int>;
                                                                                     %template(DoubleVector) vector<double>;
                                                                                  }
                                                                                  
                                                                                  // Include the header file with above prototypes
                                                                                  %include "example.h"
                                                                                  

                                                                                  Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                                                                  >>> from example import *
                                                                                  >>> iv = IntVector(4)         # Create an vector<int>
                                                                                  >>> for i in range(0,4):
                                                                                  ...      iv[i] = i
                                                                                  >>> average(iv)               # Call method
                                                                                  1.5
                                                                                  >>> average([0,1,2,3])        # Call with list
                                                                                  1.5
                                                                                  >>> half([1,2,3])             # Half a list
                                                                                  (0.5,1.0,1.5)
                                                                                  >>> halve_in_place([1,2,3])   # Oops
                                                                                  Traceback (most recent call last):
                                                                                    File "<stdin>", line 1, in ?
                                                                                  TypeError: Type error. Expected _p_std__vectorTdouble_t
                                                                                  >>> dv = DoubleVector(4)
                                                                                  >>> for i in range(0,4):
                                                                                  ...       dv[i] = i
                                                                                  >>> halve_in_place(dv)       # Ok
                                                                                  >>> for i in dv:
                                                                                  ...       print i
                                                                                  ...
                                                                                  0.0
                                                                                  0.5
                                                                                  1.0
                                                                                  1.5
                                                                                  >>> dv[20] = 4.5
                                                                                  Traceback (most recent call last):
                                                                                    File "<stdin>", line 1, in ?
                                                                                    File "example.py", line 81, in __setitem__
                                                                                      def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                                                                  IndexError: vector index out of range
                                                                                  >>>
                                                                                  

                                                                                  This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                                                                  %include "std_vector.i"
                                                                                  
                                                                                  namespace std {
                                                                                      %template(IntVector) vector<int>;
                                                                                  }
                                                                                  
                                                                                  using namespace std;
                                                                                  typedef std::vector Vector;
                                                                                  
                                                                                  void foo(vector<int> *x, const Vector &x);
                                                                                  

                                                                                  Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                                                                  Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                                                                  Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                                                                  8.5 Utility Libraries

                                                                                  8.5.1 exception.i

                                                                                  The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                                                                  SWIG_exception(int code, const char *message)

                                                                                  Raises an exception in the target language. code is one of the following symbolic constants:

                                                                                  SWIG_MemoryError
                                                                                  SWIG_IOError
                                                                                  SWIG_RuntimeError
                                                                                  SWIG_IndexError
                                                                                  SWIG_TypeError
                                                                                  SWIG_DivisionByZero
                                                                                  SWIG_OverflowError
                                                                                  SWIG_SyntaxError
                                                                                  SWIG_ValueError
                                                                                  SWIG_SystemError
                                                                                  

                                                                                  message is a string indicating more information about the problem.

                                                                                  The primary use of this module is in writing language-independent exception handlers. For example:

                                                                                  %include "exception.i"
                                                                                  %exception std::vector::getitem {
                                                                                      try {
                                                                                          $action
                                                                                      } catch (std::out_of_range& e) {
                                                                                          SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                                                      }
                                                                                  }
                                                                                  

                                                                                  ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                                                                  

                                                                                  SWIG-1.3 Documentation

                                                                                  
                                                                                  

                                                                                  ---

                                                                                  Table of Contents

                                                                                  
                                                                                  
                                                                                  SWIG-1.3 Development Documentation
                                                                                  • Sections
                                                                                  • SWIG Core Documentation
                                                                                  • Language Module Documentation
                                                                                  • Developer Documentation
                                                                                  • Documentation that has not yet been updated
                                                                                  1 Preface
                                                                                  • 1.1 Introduction
                                                                                  • 1.2 Special Introduction for Version 1.3
                                                                                  • 1.3 SWIG Versions
                                                                                  • 1.4 SWIG resources
                                                                                  • 1.5 Prerequisites
                                                                                  • 1.6 Organization of this manual
                                                                                  • 1.7 How to avoid reading the manual
                                                                                  • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                                                                    >>> make_upper("hello world")
                                                                                    'HELLO WORLD'
                                                                                    >>> attach_header("Hello world")
                                                                                    'header: Hello world'
                                                                                    >>>
                                                                                    

                                                                                    This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                                                                    %cstring_output_maxsize(parm, maxparm)

                                                                                    This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                                                                    %cstring_output_maxsize(char *path, int maxpath);
                                                                                    ...
                                                                                    void get_path(char *path, int maxpath);
                                                                                    

                                                                                    In the target language:

                                                                                    >>> get_path(1024)
                                                                                    '/home/beazley/Packages/Foo/Bar'
                                                                                    >>>
                                                                                    

                                                                                    This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                                                                    %cstring_output_withsize(parm, maxparm)

                                                                                    This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                                                                    %cstring_output_withsize(char *data, int *maxdata);
                                                                                    ...
                                                                                    void get_data(char *data, int *maxdata);
                                                                                    

                                                                                    In the target language:

                                                                                    >>> get_data(1024)
                                                                                    'x627388912'
                                                                                    >>> get_data(1024)
                                                                                    'xyzzy'
                                                                                    >>>
                                                                                    

                                                                                    This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                                                                    %cstring_output_allocate(parm, release)

                                                                                    This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                                                                    void foo(char **s) {
                                                                                        *s = (char *) malloc(64);
                                                                                        sprintf(*s, "Hello world\n");
                                                                                    }
                                                                                    

                                                                                    The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                    %cstring_output_allocate(char **s, free(*$1));
                                                                                    ...
                                                                                    void foo(char **s);
                                                                                    

                                                                                    In the target language:

                                                                                    >>> foo()
                                                                                    'Hello world\n'
                                                                                    >>>
                                                                                    

                                                                                    %cstring_output_allocate_size(parm, szparm, release)

                                                                                    This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                                                                    void foo(char **s, int *sz) {
                                                                                        *s = (char *) malloc(64);
                                                                                        *sz = 64;
                                                                                        // Write some binary data
                                                                                        ...
                                                                                    }
                                                                                    

                                                                                    The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                    %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                                                                    ...
                                                                                    void foo(char **s, int *slen);
                                                                                    

                                                                                    In the target language:

                                                                                    >>> foo()
                                                                                    '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                                                                    >>>
                                                                                    

                                                                                    This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                                                                    char  *get_data(int *len);
                                                                                    

                                                                                    You could wrap it with a function like this:

                                                                                    void my_get_data(char **result, int *len) {
                                                                                       *result = get_data(len);
                                                                                    }
                                                                                    

                                                                                    Comments:
                                                                                    • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                                                                    • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                                                                    • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                                                                    • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                                                                    8.4 C++ Library

                                                                                    The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                                                                    8.4.1 std_string.i

                                                                                    The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                                                                    %module example
                                                                                    %include "std_string.i"
                                                                                    
                                                                                    std::string foo();
                                                                                    void        bar(const std::string &x);
                                                                                    

                                                                                    In the target language:

                                                                                    x = foo();                # Returns a string object
                                                                                    bar("Hello World");       # Pass string as std::string
                                                                                    

                                                                                    This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                                                                    This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                                                                    %module example
                                                                                    %include "std_string.i"
                                                                                    
                                                                                    using namespace std;
                                                                                    typedef std::string String;
                                                                                    ...
                                                                                    void foo(string s, const String &t);     // std_string typemaps still applied
                                                                                    

                                                                                    Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                                                                    8.4.2 std_vector.i

                                                                                    The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                                                                    %module example
                                                                                    %include "std_vector.i"
                                                                                    
                                                                                    namespace std {
                                                                                       %template(vectori) vector<int>;
                                                                                       %template(vectord) vector<double>;
                                                                                    };
                                                                                    

                                                                                    When a template vector<X> is instantiated a number of things happen:
                                                                                    • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                                                                    • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                                                                    • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                                                                    • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                                                                    • An exception handler for std::out_of_range is defined.
                                                                                    • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                                                                    To illustrate the use of this library, consider the following functions:

                                                                                    /* File : example.h */
                                                                                    
                                                                                    #include <vector>
                                                                                    #include <algorithm>
                                                                                    #include <functional>
                                                                                    #include <numeric>
                                                                                    
                                                                                    double average(std::vector<int> v) {
                                                                                        return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                                                                    }
                                                                                    
                                                                                    std::vector<double> half(const std::vector<double>& v) {
                                                                                        std::vector<double> w(v);
                                                                                        for (unsigned int i=0; i<w.size(); i++)
                                                                                            w[i] /= 2.0;
                                                                                        return w;
                                                                                    }
                                                                                    
                                                                                    void halve_in_place(std::vector<double>& v) {
                                                                                        std::transform(v.begin(),v.end(),v.begin(),
                                                                                                       std::bind2nd(std::divides<double>(),2.0));
                                                                                    }
                                                                                    

                                                                                    To wrap with SWIG, you might write the following:

                                                                                    %module example
                                                                                    %{
                                                                                    #include "example.h"
                                                                                    %}
                                                                                    
                                                                                    %include "std_vector.i"
                                                                                    // Instantiate templates used by example
                                                                                    namespace std {
                                                                                       %template(IntVector) vector<int>;
                                                                                       %template(DoubleVector) vector<double>;
                                                                                    }
                                                                                    
                                                                                    // Include the header file with above prototypes
                                                                                    %include "example.h"
                                                                                    

                                                                                    Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                                                                    >>> from example import *
                                                                                    >>> iv = IntVector(4)         # Create an vector<int>
                                                                                    >>> for i in range(0,4):
                                                                                    ...      iv[i] = i
                                                                                    >>> average(iv)               # Call method
                                                                                    1.5
                                                                                    >>> average([0,1,2,3])        # Call with list
                                                                                    1.5
                                                                                    >>> half([1,2,3])             # Half a list
                                                                                    (0.5,1.0,1.5)
                                                                                    >>> halve_in_place([1,2,3])   # Oops
                                                                                    Traceback (most recent call last):
                                                                                      File "<stdin>", line 1, in ?
                                                                                    TypeError: Type error. Expected _p_std__vectorTdouble_t
                                                                                    >>> dv = DoubleVector(4)
                                                                                    >>> for i in range(0,4):
                                                                                    ...       dv[i] = i
                                                                                    >>> halve_in_place(dv)       # Ok
                                                                                    >>> for i in dv:
                                                                                    ...       print i
                                                                                    ...
                                                                                    0.0
                                                                                    0.5
                                                                                    1.0
                                                                                    1.5
                                                                                    >>> dv[20] = 4.5
                                                                                    Traceback (most recent call last):
                                                                                      File "<stdin>", line 1, in ?
                                                                                      File "example.py", line 81, in __setitem__
                                                                                        def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                                                                    IndexError: vector index out of range
                                                                                    >>>
                                                                                    

                                                                                    This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                                                                    %include "std_vector.i"
                                                                                    
                                                                                    namespace std {
                                                                                        %template(IntVector) vector<int>;
                                                                                    }
                                                                                    
                                                                                    using namespace std;
                                                                                    typedef std::vector Vector;
                                                                                    
                                                                                    void foo(vector<int> *x, const Vector &x);
                                                                                    

                                                                                    Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                                                                    Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                                                                    Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                                                                    8.5 Utility Libraries

                                                                                    8.5.1 exception.i

                                                                                    The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                                                                    SWIG_exception(int code, const char *message)

                                                                                    Raises an exception in the target language. code is one of the following symbolic constants:

                                                                                    SWIG_MemoryError
                                                                                    SWIG_IOError
                                                                                    SWIG_RuntimeError
                                                                                    SWIG_IndexError
                                                                                    SWIG_TypeError
                                                                                    SWIG_DivisionByZero
                                                                                    SWIG_OverflowError
                                                                                    SWIG_SyntaxError
                                                                                    SWIG_ValueError
                                                                                    SWIG_SystemError
                                                                                    

                                                                                    message is a string indicating more information about the problem.

                                                                                    The primary use of this module is in writing language-independent exception handlers. For example:

                                                                                    %include "exception.i"
                                                                                    %exception std::vector::getitem {
                                                                                        try {
                                                                                            $action
                                                                                        } catch (std::out_of_range& e) {
                                                                                            SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                                                        }
                                                                                    }
                                                                                    

                                                                                    ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                                                                    

                                                                                    SWIG-1.3 Documentation

                                                                                    
                                                                                    

                                                                                    ---

                                                                                    Table of Contents

                                                                                    
                                                                                    
                                                                                    SWIG-1.3 Development Documentation
                                                                                    • Sections
                                                                                    • SWIG Core Documentation
                                                                                    • Language Module Documentation
                                                                                    • Developer Documentation
                                                                                    • Documentation that has not yet been updated
                                                                                    1 Preface
                                                                                    • 1.1 Introduction
                                                                                    • 1.2 Special Introduction for Version 1.3
                                                                                    • 1.3 SWIG Versions
                                                                                    • 1.4 SWIG resources
                                                                                    • 1.5 Prerequisites
                                                                                    • 1.6 Organization of this manual
                                                                                    • 1.7 How to avoid reading the manual
                                                                                    • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                                                                      >>> make_upper("hello world")
                                                                                      'HELLO WORLD'
                                                                                      >>> attach_header("Hello world")
                                                                                      'header: Hello world'
                                                                                      >>>
                                                                                      

                                                                                      This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                                                                      %cstring_output_maxsize(parm, maxparm)

                                                                                      This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                                                                      %cstring_output_maxsize(char *path, int maxpath);
                                                                                      ...
                                                                                      void get_path(char *path, int maxpath);
                                                                                      

                                                                                      In the target language:

                                                                                      >>> get_path(1024)
                                                                                      '/home/beazley/Packages/Foo/Bar'
                                                                                      >>>
                                                                                      

                                                                                      This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                                                                      %cstring_output_withsize(parm, maxparm)

                                                                                      This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                                                                      %cstring_output_withsize(char *data, int *maxdata);
                                                                                      ...
                                                                                      void get_data(char *data, int *maxdata);
                                                                                      

                                                                                      In the target language:

                                                                                      >>> get_data(1024)
                                                                                      'x627388912'
                                                                                      >>> get_data(1024)
                                                                                      'xyzzy'
                                                                                      >>>
                                                                                      

                                                                                      This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                                                                      %cstring_output_allocate(parm, release)

                                                                                      This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                                                                      void foo(char **s) {
                                                                                          *s = (char *) malloc(64);
                                                                                          sprintf(*s, "Hello world\n");
                                                                                      }
                                                                                      

                                                                                      The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                      %cstring_output_allocate(char **s, free(*$1));
                                                                                      ...
                                                                                      void foo(char **s);
                                                                                      

                                                                                      In the target language:

                                                                                      >>> foo()
                                                                                      'Hello world\n'
                                                                                      >>>
                                                                                      

                                                                                      %cstring_output_allocate_size(parm, szparm, release)

                                                                                      This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                                                                      void foo(char **s, int *sz) {
                                                                                          *s = (char *) malloc(64);
                                                                                          *sz = 64;
                                                                                          // Write some binary data
                                                                                          ...
                                                                                      }
                                                                                      

                                                                                      The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                      %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                                                                      ...
                                                                                      void foo(char **s, int *slen);
                                                                                      

                                                                                      In the target language:

                                                                                      >>> foo()
                                                                                      '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                                                                      >>>
                                                                                      

                                                                                      This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                                                                      char  *get_data(int *len);
                                                                                      

                                                                                      You could wrap it with a function like this:

                                                                                      void my_get_data(char **result, int *len) {
                                                                                         *result = get_data(len);
                                                                                      }
                                                                                      

                                                                                      Comments:
                                                                                      • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                                                                      • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                                                                      • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                                                                      • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                                                                      8.4 C++ Library

                                                                                      The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                                                                      8.4.1 std_string.i

                                                                                      The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                                                                      %module example
                                                                                      %include "std_string.i"
                                                                                      
                                                                                      std::string foo();
                                                                                      void        bar(const std::string &x);
                                                                                      

                                                                                      In the target language:

                                                                                      x = foo();                # Returns a string object
                                                                                      bar("Hello World");       # Pass string as std::string
                                                                                      

                                                                                      This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                                                                      This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                                                                      %module example
                                                                                      %include "std_string.i"
                                                                                      
                                                                                      using namespace std;
                                                                                      typedef std::string String;
                                                                                      ...
                                                                                      void foo(string s, const String &t);     // std_string typemaps still applied
                                                                                      

                                                                                      Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                                                                      8.4.2 std_vector.i

                                                                                      The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                                                                      %module example
                                                                                      %include "std_vector.i"
                                                                                      
                                                                                      namespace std {
                                                                                         %template(vectori) vector<int>;
                                                                                         %template(vectord) vector<double>;
                                                                                      };
                                                                                      

                                                                                      When a template vector<X> is instantiated a number of things happen:
                                                                                      • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                                                                      • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                                                                      • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                                                                      • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                                                                      • An exception handler for std::out_of_range is defined.
                                                                                      • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                                                                      To illustrate the use of this library, consider the following functions:

                                                                                      /* File : example.h */
                                                                                      
                                                                                      #include <vector>
                                                                                      #include <algorithm>
                                                                                      #include <functional>
                                                                                      #include <numeric>
                                                                                      
                                                                                      double average(std::vector<int> v) {
                                                                                          return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                                                                      }
                                                                                      
                                                                                      std::vector<double> half(const std::vector<double>& v) {
                                                                                          std::vector<double> w(v);
                                                                                          for (unsigned int i=0; i<w.size(); i++)
                                                                                              w[i] /= 2.0;
                                                                                          return w;
                                                                                      }
                                                                                      
                                                                                      void halve_in_place(std::vector<double>& v) {
                                                                                          std::transform(v.begin(),v.end(),v.begin(),
                                                                                                         std::bind2nd(std::divides<double>(),2.0));
                                                                                      }
                                                                                      

                                                                                      To wrap with SWIG, you might write the following:

                                                                                      %module example
                                                                                      %{
                                                                                      #include "example.h"
                                                                                      %}
                                                                                      
                                                                                      %include "std_vector.i"
                                                                                      // Instantiate templates used by example
                                                                                      namespace std {
                                                                                         %template(IntVector) vector<int>;
                                                                                         %template(DoubleVector) vector<double>;
                                                                                      }
                                                                                      
                                                                                      // Include the header file with above prototypes
                                                                                      %include "example.h"
                                                                                      

                                                                                      Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                                                                      >>> from example import *
                                                                                      >>> iv = IntVector(4)         # Create an vector<int>
                                                                                      >>> for i in range(0,4):
                                                                                      ...      iv[i] = i
                                                                                      >>> average(iv)               # Call method
                                                                                      1.5
                                                                                      >>> average([0,1,2,3])        # Call with list
                                                                                      1.5
                                                                                      >>> half([1,2,3])             # Half a list
                                                                                      (0.5,1.0,1.5)
                                                                                      >>> halve_in_place([1,2,3])   # Oops
                                                                                      Traceback (most recent call last):
                                                                                        File "<stdin>", line 1, in ?
                                                                                      TypeError: Type error. Expected _p_std__vectorTdouble_t
                                                                                      >>> dv = DoubleVector(4)
                                                                                      >>> for i in range(0,4):
                                                                                      ...       dv[i] = i
                                                                                      >>> halve_in_place(dv)       # Ok
                                                                                      >>> for i in dv:
                                                                                      ...       print i
                                                                                      ...
                                                                                      0.0
                                                                                      0.5
                                                                                      1.0
                                                                                      1.5
                                                                                      >>> dv[20] = 4.5
                                                                                      Traceback (most recent call last):
                                                                                        File "<stdin>", line 1, in ?
                                                                                        File "example.py", line 81, in __setitem__
                                                                                          def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                                                                      IndexError: vector index out of range
                                                                                      >>>
                                                                                      

                                                                                      This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                                                                      %include "std_vector.i"
                                                                                      
                                                                                      namespace std {
                                                                                          %template(IntVector) vector<int>;
                                                                                      }
                                                                                      
                                                                                      using namespace std;
                                                                                      typedef std::vector Vector;
                                                                                      
                                                                                      void foo(vector<int> *x, const Vector &x);
                                                                                      

                                                                                      Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                                                                      Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                                                                      Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                                                                      8.5 Utility Libraries

                                                                                      8.5.1 exception.i

                                                                                      The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                                                                      SWIG_exception(int code, const char *message)

                                                                                      Raises an exception in the target language. code is one of the following symbolic constants:

                                                                                      SWIG_MemoryError
                                                                                      SWIG_IOError
                                                                                      SWIG_RuntimeError
                                                                                      SWIG_IndexError
                                                                                      SWIG_TypeError
                                                                                      SWIG_DivisionByZero
                                                                                      SWIG_OverflowError
                                                                                      SWIG_SyntaxError
                                                                                      SWIG_ValueError
                                                                                      SWIG_SystemError
                                                                                      

                                                                                      message is a string indicating more information about the problem.

                                                                                      The primary use of this module is in writing language-independent exception handlers. For example:

                                                                                      %include "exception.i"
                                                                                      %exception std::vector::getitem {
                                                                                          try {
                                                                                              $action
                                                                                          } catch (std::out_of_range& e) {
                                                                                              SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                                                          }
                                                                                      }
                                                                                      

                                                                                      ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                                                                      

                                                                                      SWIG-1.3 Documentation

                                                                                      
                                                                                      

                                                                                      ---

                                                                                      Table of Contents

                                                                                      
                                                                                      
                                                                                      SWIG-1.3 Development Documentation
                                                                                      • Sections
                                                                                      • SWIG Core Documentation
                                                                                      • Language Module Documentation
                                                                                      • Developer Documentation
                                                                                      • Documentation that has not yet been updated
                                                                                      1 Preface
                                                                                      • 1.1 Introduction
                                                                                      • 1.2 Special Introduction for Version 1.3
                                                                                      • 1.3 SWIG Versions
                                                                                      • 1.4 SWIG resources
                                                                                      • 1.5 Prerequisites
                                                                                      • 1.6 Organization of this manual
                                                                                      • 1.7 How to avoid reading the manual
                                                                                      • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                                                                        >>> make_upper("hello world")
                                                                                        'HELLO WORLD'
                                                                                        >>> attach_header("Hello world")
                                                                                        'header: Hello world'
                                                                                        >>>
                                                                                        

                                                                                        This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                                                                        %cstring_output_maxsize(parm, maxparm)

                                                                                        This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                                                                        %cstring_output_maxsize(char *path, int maxpath);
                                                                                        ...
                                                                                        void get_path(char *path, int maxpath);
                                                                                        

                                                                                        In the target language:

                                                                                        >>> get_path(1024)
                                                                                        '/home/beazley/Packages/Foo/Bar'
                                                                                        >>>
                                                                                        

                                                                                        This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                                                                        %cstring_output_withsize(parm, maxparm)

                                                                                        This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                                                                        %cstring_output_withsize(char *data, int *maxdata);
                                                                                        ...
                                                                                        void get_data(char *data, int *maxdata);
                                                                                        

                                                                                        In the target language:

                                                                                        >>> get_data(1024)
                                                                                        'x627388912'
                                                                                        >>> get_data(1024)
                                                                                        'xyzzy'
                                                                                        >>>
                                                                                        

                                                                                        This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                                                                        %cstring_output_allocate(parm, release)

                                                                                        This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                                                                        void foo(char **s) {
                                                                                            *s = (char *) malloc(64);
                                                                                            sprintf(*s, "Hello world\n");
                                                                                        }
                                                                                        

                                                                                        The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                        %cstring_output_allocate(char **s, free(*$1));
                                                                                        ...
                                                                                        void foo(char **s);
                                                                                        

                                                                                        In the target language:

                                                                                        >>> foo()
                                                                                        'Hello world\n'
                                                                                        >>>
                                                                                        

                                                                                        %cstring_output_allocate_size(parm, szparm, release)

                                                                                        This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                                                                        void foo(char **s, int *sz) {
                                                                                            *s = (char *) malloc(64);
                                                                                            *sz = 64;
                                                                                            // Write some binary data
                                                                                            ...
                                                                                        }
                                                                                        

                                                                                        The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                        %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                                                                        ...
                                                                                        void foo(char **s, int *slen);
                                                                                        

                                                                                        In the target language:

                                                                                        >>> foo()
                                                                                        '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                                                                        >>>
                                                                                        

                                                                                        This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                                                                        char  *get_data(int *len);
                                                                                        

                                                                                        You could wrap it with a function like this:

                                                                                        void my_get_data(char **result, int *len) {
                                                                                           *result = get_data(len);
                                                                                        }
                                                                                        

                                                                                        Comments:
                                                                                        • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                                                                        • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                                                                        • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                                                                        • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                                                                        8.4 C++ Library

                                                                                        The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                                                                        8.4.1 std_string.i

                                                                                        The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                                                                        %module example
                                                                                        %include "std_string.i"
                                                                                        
                                                                                        std::string foo();
                                                                                        void        bar(const std::string &x);
                                                                                        

                                                                                        In the target language:

                                                                                        x = foo();                # Returns a string object
                                                                                        bar("Hello World");       # Pass string as std::string
                                                                                        

                                                                                        This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                                                                        This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                                                                        %module example
                                                                                        %include "std_string.i"
                                                                                        
                                                                                        using namespace std;
                                                                                        typedef std::string String;
                                                                                        ...
                                                                                        void foo(string s, const String &t);     // std_string typemaps still applied
                                                                                        

                                                                                        Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                                                                        8.4.2 std_vector.i

                                                                                        The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                                                                        %module example
                                                                                        %include "std_vector.i"
                                                                                        
                                                                                        namespace std {
                                                                                           %template(vectori) vector<int>;
                                                                                           %template(vectord) vector<double>;
                                                                                        };
                                                                                        

                                                                                        When a template vector<X> is instantiated a number of things happen:
                                                                                        • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                                                                        • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                                                                        • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                                                                        • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                                                                        • An exception handler for std::out_of_range is defined.
                                                                                        • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                                                                        To illustrate the use of this library, consider the following functions:

                                                                                        /* File : example.h */
                                                                                        
                                                                                        #include <vector>
                                                                                        #include <algorithm>
                                                                                        #include <functional>
                                                                                        #include <numeric>
                                                                                        
                                                                                        double average(std::vector<int> v) {
                                                                                            return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                                                                        }
                                                                                        
                                                                                        std::vector<double> half(const std::vector<double>& v) {
                                                                                            std::vector<double> w(v);
                                                                                            for (unsigned int i=0; i<w.size(); i++)
                                                                                                w[i] /= 2.0;
                                                                                            return w;
                                                                                        }
                                                                                        
                                                                                        void halve_in_place(std::vector<double>& v) {
                                                                                            std::transform(v.begin(),v.end(),v.begin(),
                                                                                                           std::bind2nd(std::divides<double>(),2.0));
                                                                                        }
                                                                                        

                                                                                        To wrap with SWIG, you might write the following:

                                                                                        %module example
                                                                                        %{
                                                                                        #include "example.h"
                                                                                        %}
                                                                                        
                                                                                        %include "std_vector.i"
                                                                                        // Instantiate templates used by example
                                                                                        namespace std {
                                                                                           %template(IntVector) vector<int>;
                                                                                           %template(DoubleVector) vector<double>;
                                                                                        }
                                                                                        
                                                                                        // Include the header file with above prototypes
                                                                                        %include "example.h"
                                                                                        

                                                                                        Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                                                                        >>> from example import *
                                                                                        >>> iv = IntVector(4)         # Create an vector<int>
                                                                                        >>> for i in range(0,4):
                                                                                        ...      iv[i] = i
                                                                                        >>> average(iv)               # Call method
                                                                                        1.5
                                                                                        >>> average([0,1,2,3])        # Call with list
                                                                                        1.5
                                                                                        >>> half([1,2,3])             # Half a list
                                                                                        (0.5,1.0,1.5)
                                                                                        >>> halve_in_place([1,2,3])   # Oops
                                                                                        Traceback (most recent call last):
                                                                                          File "<stdin>", line 1, in ?
                                                                                        TypeError: Type error. Expected _p_std__vectorTdouble_t
                                                                                        >>> dv = DoubleVector(4)
                                                                                        >>> for i in range(0,4):
                                                                                        ...       dv[i] = i
                                                                                        >>> halve_in_place(dv)       # Ok
                                                                                        >>> for i in dv:
                                                                                        ...       print i
                                                                                        ...
                                                                                        0.0
                                                                                        0.5
                                                                                        1.0
                                                                                        1.5
                                                                                        >>> dv[20] = 4.5
                                                                                        Traceback (most recent call last):
                                                                                          File "<stdin>", line 1, in ?
                                                                                          File "example.py", line 81, in __setitem__
                                                                                            def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                                                                        IndexError: vector index out of range
                                                                                        >>>
                                                                                        

                                                                                        This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                                                                        %include "std_vector.i"
                                                                                        
                                                                                        namespace std {
                                                                                            %template(IntVector) vector<int>;
                                                                                        }
                                                                                        
                                                                                        using namespace std;
                                                                                        typedef std::vector Vector;
                                                                                        
                                                                                        void foo(vector<int> *x, const Vector &x);
                                                                                        

                                                                                        Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                                                                        Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                                                                        Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                                                                        8.5 Utility Libraries

                                                                                        8.5.1 exception.i

                                                                                        The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                                                                        SWIG_exception(int code, const char *message)

                                                                                        Raises an exception in the target language. code is one of the following symbolic constants:

                                                                                        SWIG_MemoryError
                                                                                        SWIG_IOError
                                                                                        SWIG_RuntimeError
                                                                                        SWIG_IndexError
                                                                                        SWIG_TypeError
                                                                                        SWIG_DivisionByZero
                                                                                        SWIG_OverflowError
                                                                                        SWIG_SyntaxError
                                                                                        SWIG_ValueError
                                                                                        SWIG_SystemError
                                                                                        

                                                                                        message is a string indicating more information about the problem.

                                                                                        The primary use of this module is in writing language-independent exception handlers. For example:

                                                                                        %include "exception.i"
                                                                                        %exception std::vector::getitem {
                                                                                            try {
                                                                                                $action
                                                                                            } catch (std::out_of_range& e) {
                                                                                                SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                                                            }
                                                                                        }
                                                                                        

                                                                                        ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                                                                        

                                                                                        SWIG-1.3 Documentation

                                                                                        
                                                                                        

                                                                                        ---

                                                                                        Table of Contents

                                                                                        
                                                                                        
                                                                                        SWIG-1.3 Development Documentation
                                                                                        • Sections
                                                                                        • SWIG Core Documentation
                                                                                        • Language Module Documentation
                                                                                        • Developer Documentation
                                                                                        • Documentation that has not yet been updated
                                                                                        1 Preface
                                                                                        • 1.1 Introduction
                                                                                        • 1.2 Special Introduction for Version 1.3
                                                                                        • 1.3 SWIG Versions
                                                                                        • 1.4 SWIG resources
                                                                                        • 1.5 Prerequisites
                                                                                        • 1.6 Organization of this manual
                                                                                        • 1.7 How to avoid reading the manual
                                                                                        • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                                                                          >>> make_upper("hello world")
                                                                                          'HELLO WORLD'
                                                                                          >>> attach_header("Hello world")
                                                                                          'header: Hello world'
                                                                                          >>>
                                                                                          

                                                                                          This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                                                                          %cstring_output_maxsize(parm, maxparm)

                                                                                          This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                                                                          %cstring_output_maxsize(char *path, int maxpath);
                                                                                          ...
                                                                                          void get_path(char *path, int maxpath);
                                                                                          

                                                                                          In the target language:

                                                                                          >>> get_path(1024)
                                                                                          '/home/beazley/Packages/Foo/Bar'
                                                                                          >>>
                                                                                          

                                                                                          This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                                                                          %cstring_output_withsize(parm, maxparm)

                                                                                          This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                                                                          %cstring_output_withsize(char *data, int *maxdata);
                                                                                          ...
                                                                                          void get_data(char *data, int *maxdata);
                                                                                          

                                                                                          In the target language:

                                                                                          >>> get_data(1024)
                                                                                          'x627388912'
                                                                                          >>> get_data(1024)
                                                                                          'xyzzy'
                                                                                          >>>
                                                                                          

                                                                                          This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                                                                          %cstring_output_allocate(parm, release)

                                                                                          This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                                                                          void foo(char **s) {
                                                                                              *s = (char *) malloc(64);
                                                                                              sprintf(*s, "Hello world\n");
                                                                                          }
                                                                                          

                                                                                          The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                          %cstring_output_allocate(char **s, free(*$1));
                                                                                          ...
                                                                                          void foo(char **s);
                                                                                          

                                                                                          In the target language:

                                                                                          >>> foo()
                                                                                          'Hello world\n'
                                                                                          >>>
                                                                                          

                                                                                          %cstring_output_allocate_size(parm, szparm, release)

                                                                                          This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                                                                          void foo(char **s, int *sz) {
                                                                                              *s = (char *) malloc(64);
                                                                                              *sz = 64;
                                                                                              // Write some binary data
                                                                                              ...
                                                                                          }
                                                                                          

                                                                                          The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                          %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                                                                          ...
                                                                                          void foo(char **s, int *slen);
                                                                                          

                                                                                          In the target language:

                                                                                          >>> foo()
                                                                                          '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                                                                          >>>
                                                                                          

                                                                                          This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                                                                          char  *get_data(int *len);
                                                                                          

                                                                                          You could wrap it with a function like this:

                                                                                          void my_get_data(char **result, int *len) {
                                                                                             *result = get_data(len);
                                                                                          }
                                                                                          

                                                                                          Comments:
                                                                                          • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                                                                          • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                                                                          • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                                                                          • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                                                                          8.4 C++ Library

                                                                                          The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                                                                          8.4.1 std_string.i

                                                                                          The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                                                                          %module example
                                                                                          %include "std_string.i"
                                                                                          
                                                                                          std::string foo();
                                                                                          void        bar(const std::string &x);
                                                                                          

                                                                                          In the target language:

                                                                                          x = foo();                # Returns a string object
                                                                                          bar("Hello World");       # Pass string as std::string
                                                                                          

                                                                                          This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                                                                          This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                                                                          %module example
                                                                                          %include "std_string.i"
                                                                                          
                                                                                          using namespace std;
                                                                                          typedef std::string String;
                                                                                          ...
                                                                                          void foo(string s, const String &t);     // std_string typemaps still applied
                                                                                          

                                                                                          Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                                                                          8.4.2 std_vector.i

                                                                                          The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                                                                          %module example
                                                                                          %include "std_vector.i"
                                                                                          
                                                                                          namespace std {
                                                                                             %template(vectori) vector<int>;
                                                                                             %template(vectord) vector<double>;
                                                                                          };
                                                                                          

                                                                                          When a template vector<X> is instantiated a number of things happen:
                                                                                          • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                                                                          • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                                                                          • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                                                                          • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                                                                          • An exception handler for std::out_of_range is defined.
                                                                                          • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                                                                          To illustrate the use of this library, consider the following functions:

                                                                                          /* File : example.h */
                                                                                          
                                                                                          #include <vector>
                                                                                          #include <algorithm>
                                                                                          #include <functional>
                                                                                          #include <numeric>
                                                                                          
                                                                                          double average(std::vector<int> v) {
                                                                                              return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                                                                          }
                                                                                          
                                                                                          std::vector<double> half(const std::vector<double>& v) {
                                                                                              std::vector<double> w(v);
                                                                                              for (unsigned int i=0; i<w.size(); i++)
                                                                                                  w[i] /= 2.0;
                                                                                              return w;
                                                                                          }
                                                                                          
                                                                                          void halve_in_place(std::vector<double>& v) {
                                                                                              std::transform(v.begin(),v.end(),v.begin(),
                                                                                                             std::bind2nd(std::divides<double>(),2.0));
                                                                                          }
                                                                                          

                                                                                          To wrap with SWIG, you might write the following:

                                                                                          %module example
                                                                                          %{
                                                                                          #include "example.h"
                                                                                          %}
                                                                                          
                                                                                          %include "std_vector.i"
                                                                                          // Instantiate templates used by example
                                                                                          namespace std {
                                                                                             %template(IntVector) vector<int>;
                                                                                             %template(DoubleVector) vector<double>;
                                                                                          }
                                                                                          
                                                                                          // Include the header file with above prototypes
                                                                                          %include "example.h"
                                                                                          

                                                                                          Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                                                                          >>> from example import *
                                                                                          >>> iv = IntVector(4)         # Create an vector<int>
                                                                                          >>> for i in range(0,4):
                                                                                          ...      iv[i] = i
                                                                                          >>> average(iv)               # Call method
                                                                                          1.5
                                                                                          >>> average([0,1,2,3])        # Call with list
                                                                                          1.5
                                                                                          >>> half([1,2,3])             # Half a list
                                                                                          (0.5,1.0,1.5)
                                                                                          >>> halve_in_place([1,2,3])   # Oops
                                                                                          Traceback (most recent call last):
                                                                                            File "<stdin>", line 1, in ?
                                                                                          TypeError: Type error. Expected _p_std__vectorTdouble_t
                                                                                          >>> dv = DoubleVector(4)
                                                                                          >>> for i in range(0,4):
                                                                                          ...       dv[i] = i
                                                                                          >>> halve_in_place(dv)       # Ok
                                                                                          >>> for i in dv:
                                                                                          ...       print i
                                                                                          ...
                                                                                          0.0
                                                                                          0.5
                                                                                          1.0
                                                                                          1.5
                                                                                          >>> dv[20] = 4.5
                                                                                          Traceback (most recent call last):
                                                                                            File "<stdin>", line 1, in ?
                                                                                            File "example.py", line 81, in __setitem__
                                                                                              def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                                                                          IndexError: vector index out of range
                                                                                          >>>
                                                                                          

                                                                                          This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                                                                          %include "std_vector.i"
                                                                                          
                                                                                          namespace std {
                                                                                              %template(IntVector) vector<int>;
                                                                                          }
                                                                                          
                                                                                          using namespace std;
                                                                                          typedef std::vector Vector;
                                                                                          
                                                                                          void foo(vector<int> *x, const Vector &x);
                                                                                          

                                                                                          Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                                                                          Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                                                                          Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                                                                          8.5 Utility Libraries

                                                                                          8.5.1 exception.i

                                                                                          The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                                                                          SWIG_exception(int code, const char *message)

                                                                                          Raises an exception in the target language. code is one of the following symbolic constants:

                                                                                          SWIG_MemoryError
                                                                                          SWIG_IOError
                                                                                          SWIG_RuntimeError
                                                                                          SWIG_IndexError
                                                                                          SWIG_TypeError
                                                                                          SWIG_DivisionByZero
                                                                                          SWIG_OverflowError
                                                                                          SWIG_SyntaxError
                                                                                          SWIG_ValueError
                                                                                          SWIG_SystemError
                                                                                          

                                                                                          message is a string indicating more information about the problem.

                                                                                          The primary use of this module is in writing language-independent exception handlers. For example:

                                                                                          %include "exception.i"
                                                                                          %exception std::vector::getitem {
                                                                                              try {
                                                                                                  $action
                                                                                              } catch (std::out_of_range& e) {
                                                                                                  SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                                                              }
                                                                                          }
                                                                                          

                                                                                          ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                                                                          

                                                                                          SWIG-1.3 Documentation

                                                                                          
                                                                                          

                                                                                          ---

                                                                                          Table of Contents

                                                                                          
                                                                                          
                                                                                          SWIG-1.3 Development Documentation
                                                                                          • Sections
                                                                                          • SWIG Core Documentation
                                                                                          • Language Module Documentation
                                                                                          • Developer Documentation
                                                                                          • Documentation that has not yet been updated
                                                                                          1 Preface
                                                                                          • 1.1 Introduction
                                                                                          • 1.2 Special Introduction for Version 1.3
                                                                                          • 1.3 SWIG Versions
                                                                                          • 1.4 SWIG resources
                                                                                          • 1.5 Prerequisites
                                                                                          • 1.6 Organization of this manual
                                                                                          • 1.7 How to avoid reading the manual
                                                                                          • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                                                                            >>> make_upper("hello world")
                                                                                            'HELLO WORLD'
                                                                                            >>> attach_header("Hello world")
                                                                                            'header: Hello world'
                                                                                            >>>
                                                                                            

                                                                                            This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                                                                            %cstring_output_maxsize(parm, maxparm)

                                                                                            This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                                                                            %cstring_output_maxsize(char *path, int maxpath);
                                                                                            ...
                                                                                            void get_path(char *path, int maxpath);
                                                                                            

                                                                                            In the target language:

                                                                                            >>> get_path(1024)
                                                                                            '/home/beazley/Packages/Foo/Bar'
                                                                                            >>>
                                                                                            

                                                                                            This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                                                                            %cstring_output_withsize(parm, maxparm)

                                                                                            This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                                                                            %cstring_output_withsize(char *data, int *maxdata);
                                                                                            ...
                                                                                            void get_data(char *data, int *maxdata);
                                                                                            

                                                                                            In the target language:

                                                                                            >>> get_data(1024)
                                                                                            'x627388912'
                                                                                            >>> get_data(1024)
                                                                                            'xyzzy'
                                                                                            >>>
                                                                                            

                                                                                            This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                                                                            %cstring_output_allocate(parm, release)

                                                                                            This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                                                                            void foo(char **s) {
                                                                                                *s = (char *) malloc(64);
                                                                                                sprintf(*s, "Hello world\n");
                                                                                            }
                                                                                            

                                                                                            The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                            %cstring_output_allocate(char **s, free(*$1));
                                                                                            ...
                                                                                            void foo(char **s);
                                                                                            

                                                                                            In the target language:

                                                                                            >>> foo()
                                                                                            'Hello world\n'
                                                                                            >>>
                                                                                            

                                                                                            %cstring_output_allocate_size(parm, szparm, release)

                                                                                            This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                                                                            void foo(char **s, int *sz) {
                                                                                                *s = (char *) malloc(64);
                                                                                                *sz = 64;
                                                                                                // Write some binary data
                                                                                                ...
                                                                                            }
                                                                                            

                                                                                            The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                            %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                                                                            ...
                                                                                            void foo(char **s, int *slen);
                                                                                            

                                                                                            In the target language:

                                                                                            >>> foo()
                                                                                            '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                                                                            >>>
                                                                                            

                                                                                            This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                                                                            char  *get_data(int *len);
                                                                                            

                                                                                            You could wrap it with a function like this:

                                                                                            void my_get_data(char **result, int *len) {
                                                                                               *result = get_data(len);
                                                                                            }
                                                                                            

                                                                                            Comments:
                                                                                            • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                                                                            • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                                                                            • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                                                                            • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                                                                            8.4 C++ Library

                                                                                            The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                                                                            8.4.1 std_string.i

                                                                                            The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                                                                            %module example
                                                                                            %include "std_string.i"
                                                                                            
                                                                                            std::string foo();
                                                                                            void        bar(const std::string &x);
                                                                                            

                                                                                            In the target language:

                                                                                            x = foo();                # Returns a string object
                                                                                            bar("Hello World");       # Pass string as std::string
                                                                                            

                                                                                            This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                                                                            This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                                                                            %module example
                                                                                            %include "std_string.i"
                                                                                            
                                                                                            using namespace std;
                                                                                            typedef std::string String;
                                                                                            ...
                                                                                            void foo(string s, const String &t);     // std_string typemaps still applied
                                                                                            

                                                                                            Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                                                                            8.4.2 std_vector.i

                                                                                            The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                                                                            %module example
                                                                                            %include "std_vector.i"
                                                                                            
                                                                                            namespace std {
                                                                                               %template(vectori) vector<int>;
                                                                                               %template(vectord) vector<double>;
                                                                                            };
                                                                                            

                                                                                            When a template vector<X> is instantiated a number of things happen:
                                                                                            • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                                                                            • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                                                                            • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                                                                            • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                                                                            • An exception handler for std::out_of_range is defined.
                                                                                            • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                                                                            To illustrate the use of this library, consider the following functions:

                                                                                            /* File : example.h */
                                                                                            
                                                                                            #include <vector>
                                                                                            #include <algorithm>
                                                                                            #include <functional>
                                                                                            #include <numeric>
                                                                                            
                                                                                            double average(std::vector<int> v) {
                                                                                                return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                                                                            }
                                                                                            
                                                                                            std::vector<double> half(const std::vector<double>& v) {
                                                                                                std::vector<double> w(v);
                                                                                                for (unsigned int i=0; i<w.size(); i++)
                                                                                                    w[i] /= 2.0;
                                                                                                return w;
                                                                                            }
                                                                                            
                                                                                            void halve_in_place(std::vector<double>& v) {
                                                                                                std::transform(v.begin(),v.end(),v.begin(),
                                                                                                               std::bind2nd(std::divides<double>(),2.0));
                                                                                            }
                                                                                            

                                                                                            To wrap with SWIG, you might write the following:

                                                                                            %module example
                                                                                            %{
                                                                                            #include "example.h"
                                                                                            %}
                                                                                            
                                                                                            %include "std_vector.i"
                                                                                            // Instantiate templates used by example
                                                                                            namespace std {
                                                                                               %template(IntVector) vector<int>;
                                                                                               %template(DoubleVector) vector<double>;
                                                                                            }
                                                                                            
                                                                                            // Include the header file with above prototypes
                                                                                            %include "example.h"
                                                                                            

                                                                                            Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                                                                            >>> from example import *
                                                                                            >>> iv = IntVector(4)         # Create an vector<int>
                                                                                            >>> for i in range(0,4):
                                                                                            ...      iv[i] = i
                                                                                            >>> average(iv)               # Call method
                                                                                            1.5
                                                                                            >>> average([0,1,2,3])        # Call with list
                                                                                            1.5
                                                                                            >>> half([1,2,3])             # Half a list
                                                                                            (0.5,1.0,1.5)
                                                                                            >>> halve_in_place([1,2,3])   # Oops
                                                                                            Traceback (most recent call last):
                                                                                              File "<stdin>", line 1, in ?
                                                                                            TypeError: Type error. Expected _p_std__vectorTdouble_t
                                                                                            >>> dv = DoubleVector(4)
                                                                                            >>> for i in range(0,4):
                                                                                            ...       dv[i] = i
                                                                                            >>> halve_in_place(dv)       # Ok
                                                                                            >>> for i in dv:
                                                                                            ...       print i
                                                                                            ...
                                                                                            0.0
                                                                                            0.5
                                                                                            1.0
                                                                                            1.5
                                                                                            >>> dv[20] = 4.5
                                                                                            Traceback (most recent call last):
                                                                                              File "<stdin>", line 1, in ?
                                                                                              File "example.py", line 81, in __setitem__
                                                                                                def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                                                                            IndexError: vector index out of range
                                                                                            >>>
                                                                                            

                                                                                            This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                                                                            %include "std_vector.i"
                                                                                            
                                                                                            namespace std {
                                                                                                %template(IntVector) vector<int>;
                                                                                            }
                                                                                            
                                                                                            using namespace std;
                                                                                            typedef std::vector Vector;
                                                                                            
                                                                                            void foo(vector<int> *x, const Vector &x);
                                                                                            

                                                                                            Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                                                                            Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                                                                            Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                                                                            8.5 Utility Libraries

                                                                                            8.5.1 exception.i

                                                                                            The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                                                                            SWIG_exception(int code, const char *message)

                                                                                            Raises an exception in the target language. code is one of the following symbolic constants:

                                                                                            SWIG_MemoryError
                                                                                            SWIG_IOError
                                                                                            SWIG_RuntimeError
                                                                                            SWIG_IndexError
                                                                                            SWIG_TypeError
                                                                                            SWIG_DivisionByZero
                                                                                            SWIG_OverflowError
                                                                                            SWIG_SyntaxError
                                                                                            SWIG_ValueError
                                                                                            SWIG_SystemError
                                                                                            

                                                                                            message is a string indicating more information about the problem.

                                                                                            The primary use of this module is in writing language-independent exception handlers. For example:

                                                                                            %include "exception.i"
                                                                                            %exception std::vector::getitem {
                                                                                                try {
                                                                                                    $action
                                                                                                } catch (std::out_of_range& e) {
                                                                                                    SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                                                                }
                                                                                            }
                                                                                            

                                                                                            ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                                                                            

                                                                                            SWIG-1.3 Documentation

                                                                                            
                                                                                            

                                                                                            ---

                                                                                            Table of Contents

                                                                                            
                                                                                            
                                                                                            SWIG-1.3 Development Documentation
                                                                                            • Sections
                                                                                            • SWIG Core Documentation
                                                                                            • Language Module Documentation
                                                                                            • Developer Documentation
                                                                                            • Documentation that has not yet been updated
                                                                                            1 Preface
                                                                                            • 1.1 Introduction
                                                                                            • 1.2 Special Introduction for Version 1.3
                                                                                            • 1.3 SWIG Versions
                                                                                            • 1.4 SWIG resources
                                                                                            • 1.5 Prerequisites
                                                                                            • 1.6 Organization of this manual
                                                                                            • 1.7 How to avoid reading the manual
                                                                                            • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                                                                              >>> make_upper("hello world")
                                                                                              'HELLO WORLD'
                                                                                              >>> attach_header("Hello world")
                                                                                              'header: Hello world'
                                                                                              >>>
                                                                                              

                                                                                              This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                                                                              %cstring_output_maxsize(parm, maxparm)

                                                                                              This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                                                                              %cstring_output_maxsize(char *path, int maxpath);
                                                                                              ...
                                                                                              void get_path(char *path, int maxpath);
                                                                                              

                                                                                              In the target language:

                                                                                              >>> get_path(1024)
                                                                                              '/home/beazley/Packages/Foo/Bar'
                                                                                              >>>
                                                                                              

                                                                                              This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                                                                              %cstring_output_withsize(parm, maxparm)

                                                                                              This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                                                                              %cstring_output_withsize(char *data, int *maxdata);
                                                                                              ...
                                                                                              void get_data(char *data, int *maxdata);
                                                                                              

                                                                                              In the target language:

                                                                                              >>> get_data(1024)
                                                                                              'x627388912'
                                                                                              >>> get_data(1024)
                                                                                              'xyzzy'
                                                                                              >>>
                                                                                              

                                                                                              This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                                                                              %cstring_output_allocate(parm, release)

                                                                                              This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                                                                              void foo(char **s) {
                                                                                                  *s = (char *) malloc(64);
                                                                                                  sprintf(*s, "Hello world\n");
                                                                                              }
                                                                                              

                                                                                              The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                              %cstring_output_allocate(char **s, free(*$1));
                                                                                              ...
                                                                                              void foo(char **s);
                                                                                              

                                                                                              In the target language:

                                                                                              >>> foo()
                                                                                              'Hello world\n'
                                                                                              >>>
                                                                                              

                                                                                              %cstring_output_allocate_size(parm, szparm, release)

                                                                                              This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                                                                              void foo(char **s, int *sz) {
                                                                                                  *s = (char *) malloc(64);
                                                                                                  *sz = 64;
                                                                                                  // Write some binary data
                                                                                                  ...
                                                                                              }
                                                                                              

                                                                                              The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                              %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                                                                              ...
                                                                                              void foo(char **s, int *slen);
                                                                                              

                                                                                              In the target language:

                                                                                              >>> foo()
                                                                                              '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                                                                              >>>
                                                                                              

                                                                                              This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                                                                              char  *get_data(int *len);
                                                                                              

                                                                                              You could wrap it with a function like this:

                                                                                              void my_get_data(char **result, int *len) {
                                                                                                 *result = get_data(len);
                                                                                              }
                                                                                              

                                                                                              Comments:
                                                                                              • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                                                                              • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                                                                              • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                                                                              • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                                                                              8.4 C++ Library

                                                                                              The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                                                                              8.4.1 std_string.i

                                                                                              The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                                                                              %module example
                                                                                              %include "std_string.i"
                                                                                              
                                                                                              std::string foo();
                                                                                              void        bar(const std::string &x);
                                                                                              

                                                                                              In the target language:

                                                                                              x = foo();                # Returns a string object
                                                                                              bar("Hello World");       # Pass string as std::string
                                                                                              

                                                                                              This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                                                                              This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                                                                              %module example
                                                                                              %include "std_string.i"
                                                                                              
                                                                                              using namespace std;
                                                                                              typedef std::string String;
                                                                                              ...
                                                                                              void foo(string s, const String &t);     // std_string typemaps still applied
                                                                                              

                                                                                              Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                                                                              8.4.2 std_vector.i

                                                                                              The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                                                                              %module example
                                                                                              %include "std_vector.i"
                                                                                              
                                                                                              namespace std {
                                                                                                 %template(vectori) vector<int>;
                                                                                                 %template(vectord) vector<double>;
                                                                                              };
                                                                                              

                                                                                              When a template vector<X> is instantiated a number of things happen:
                                                                                              • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                                                                              • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                                                                              • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                                                                              • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                                                                              • An exception handler for std::out_of_range is defined.
                                                                                              • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                                                                              To illustrate the use of this library, consider the following functions:

                                                                                              /* File : example.h */
                                                                                              
                                                                                              #include <vector>
                                                                                              #include <algorithm>
                                                                                              #include <functional>
                                                                                              #include <numeric>
                                                                                              
                                                                                              double average(std::vector<int> v) {
                                                                                                  return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                                                                              }
                                                                                              
                                                                                              std::vector<double> half(const std::vector<double>& v) {
                                                                                                  std::vector<double> w(v);
                                                                                                  for (unsigned int i=0; i<w.size(); i++)
                                                                                                      w[i] /= 2.0;
                                                                                                  return w;
                                                                                              }
                                                                                              
                                                                                              void halve_in_place(std::vector<double>& v) {
                                                                                                  std::transform(v.begin(),v.end(),v.begin(),
                                                                                                                 std::bind2nd(std::divides<double>(),2.0));
                                                                                              }
                                                                                              

                                                                                              To wrap with SWIG, you might write the following:

                                                                                              %module example
                                                                                              %{
                                                                                              #include "example.h"
                                                                                              %}
                                                                                              
                                                                                              %include "std_vector.i"
                                                                                              // Instantiate templates used by example
                                                                                              namespace std {
                                                                                                 %template(IntVector) vector<int>;
                                                                                                 %template(DoubleVector) vector<double>;
                                                                                              }
                                                                                              
                                                                                              // Include the header file with above prototypes
                                                                                              %include "example.h"
                                                                                              

                                                                                              Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                                                                              >>> from example import *
                                                                                              >>> iv = IntVector(4)         # Create an vector<int>
                                                                                              >>> for i in range(0,4):
                                                                                              ...      iv[i] = i
                                                                                              >>> average(iv)               # Call method
                                                                                              1.5
                                                                                              >>> average([0,1,2,3])        # Call with list
                                                                                              1.5
                                                                                              >>> half([1,2,3])             # Half a list
                                                                                              (0.5,1.0,1.5)
                                                                                              >>> halve_in_place([1,2,3])   # Oops
                                                                                              Traceback (most recent call last):
                                                                                                File "<stdin>", line 1, in ?
                                                                                              TypeError: Type error. Expected _p_std__vectorTdouble_t
                                                                                              >>> dv = DoubleVector(4)
                                                                                              >>> for i in range(0,4):
                                                                                              ...       dv[i] = i
                                                                                              >>> halve_in_place(dv)       # Ok
                                                                                              >>> for i in dv:
                                                                                              ...       print i
                                                                                              ...
                                                                                              0.0
                                                                                              0.5
                                                                                              1.0
                                                                                              1.5
                                                                                              >>> dv[20] = 4.5
                                                                                              Traceback (most recent call last):
                                                                                                File "<stdin>", line 1, in ?
                                                                                                File "example.py", line 81, in __setitem__
                                                                                                  def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                                                                              IndexError: vector index out of range
                                                                                              >>>
                                                                                              

                                                                                              This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                                                                              %include "std_vector.i"
                                                                                              
                                                                                              namespace std {
                                                                                                  %template(IntVector) vector<int>;
                                                                                              }
                                                                                              
                                                                                              using namespace std;
                                                                                              typedef std::vector Vector;
                                                                                              
                                                                                              void foo(vector<int> *x, const Vector &x);
                                                                                              

                                                                                              Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                                                                              Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                                                                              Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                                                                              8.5 Utility Libraries

                                                                                              8.5.1 exception.i

                                                                                              The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                                                                              SWIG_exception(int code, const char *message)

                                                                                              Raises an exception in the target language. code is one of the following symbolic constants:

                                                                                              SWIG_MemoryError
                                                                                              SWIG_IOError
                                                                                              SWIG_RuntimeError
                                                                                              SWIG_IndexError
                                                                                              SWIG_TypeError
                                                                                              SWIG_DivisionByZero
                                                                                              SWIG_OverflowError
                                                                                              SWIG_SyntaxError
                                                                                              SWIG_ValueError
                                                                                              SWIG_SystemError
                                                                                              

                                                                                              message is a string indicating more information about the problem.

                                                                                              The primary use of this module is in writing language-independent exception handlers. For example:

                                                                                              %include "exception.i"
                                                                                              %exception std::vector::getitem {
                                                                                                  try {
                                                                                                      $action
                                                                                                  } catch (std::out_of_range& e) {
                                                                                                      SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                                                                  }
                                                                                              }
                                                                                              

                                                                                              ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                                                                              

                                                                                              SWIG-1.3 Documentation

                                                                                              
                                                                                              

                                                                                              ---

                                                                                              Table of Contents

                                                                                              
                                                                                              
                                                                                              SWIG-1.3 Development Documentation
                                                                                              • Sections
                                                                                              • SWIG Core Documentation
                                                                                              • Language Module Documentation
                                                                                              • Developer Documentation
                                                                                              • Documentation that has not yet been updated
                                                                                              1 Preface
                                                                                              • 1.1 Introduction
                                                                                              • 1.2 Special Introduction for Version 1.3
                                                                                              • 1.3 SWIG Versions
                                                                                              • 1.4 SWIG resources
                                                                                              • 1.5 Prerequisites
                                                                                              • 1.6 Organization of this manual
                                                                                              • 1.7 How to avoid reading the manual
                                                                                              • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                                                                                >>> make_upper("hello world")
                                                                                                'HELLO WORLD'
                                                                                                >>> attach_header("Hello world")
                                                                                                'header: Hello world'
                                                                                                >>>
                                                                                                

                                                                                                This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                                                                                %cstring_output_maxsize(parm, maxparm)

                                                                                                This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                                                                                %cstring_output_maxsize(char *path, int maxpath);
                                                                                                ...
                                                                                                void get_path(char *path, int maxpath);
                                                                                                

                                                                                                In the target language:

                                                                                                >>> get_path(1024)
                                                                                                '/home/beazley/Packages/Foo/Bar'
                                                                                                >>>
                                                                                                

                                                                                                This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                                                                                %cstring_output_withsize(parm, maxparm)

                                                                                                This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                                                                                %cstring_output_withsize(char *data, int *maxdata);
                                                                                                ...
                                                                                                void get_data(char *data, int *maxdata);
                                                                                                

                                                                                                In the target language:

                                                                                                >>> get_data(1024)
                                                                                                'x627388912'
                                                                                                >>> get_data(1024)
                                                                                                'xyzzy'
                                                                                                >>>
                                                                                                

                                                                                                This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                                                                                %cstring_output_allocate(parm, release)

                                                                                                This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                                                                                void foo(char **s) {
                                                                                                    *s = (char *) malloc(64);
                                                                                                    sprintf(*s, "Hello world\n");
                                                                                                }
                                                                                                

                                                                                                The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                %cstring_output_allocate(char **s, free(*$1));
                                                                                                ...
                                                                                                void foo(char **s);
                                                                                                

                                                                                                In the target language:

                                                                                                >>> foo()
                                                                                                'Hello world\n'
                                                                                                >>>
                                                                                                

                                                                                                %cstring_output_allocate_size(parm, szparm, release)

                                                                                                This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                                                                                void foo(char **s, int *sz) {
                                                                                                    *s = (char *) malloc(64);
                                                                                                    *sz = 64;
                                                                                                    // Write some binary data
                                                                                                    ...
                                                                                                }
                                                                                                

                                                                                                The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                                                                                ...
                                                                                                void foo(char **s, int *slen);
                                                                                                

                                                                                                In the target language:

                                                                                                >>> foo()
                                                                                                '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                                                                                >>>
                                                                                                

                                                                                                This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                                                                                char  *get_data(int *len);
                                                                                                

                                                                                                You could wrap it with a function like this:

                                                                                                void my_get_data(char **result, int *len) {
                                                                                                   *result = get_data(len);
                                                                                                }
                                                                                                

                                                                                                Comments:
                                                                                                • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                                                                                • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                                                                                • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                                                                                • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                                                                                8.4 C++ Library

                                                                                                The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                                                                                8.4.1 std_string.i

                                                                                                The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                                                                                %module example
                                                                                                %include "std_string.i"
                                                                                                
                                                                                                std::string foo();
                                                                                                void        bar(const std::string &x);
                                                                                                

                                                                                                In the target language:

                                                                                                x = foo();                # Returns a string object
                                                                                                bar("Hello World");       # Pass string as std::string
                                                                                                

                                                                                                This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                                                                                This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                                                                                %module example
                                                                                                %include "std_string.i"
                                                                                                
                                                                                                using namespace std;
                                                                                                typedef std::string String;
                                                                                                ...
                                                                                                void foo(string s, const String &t);     // std_string typemaps still applied
                                                                                                

                                                                                                Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                                                                                8.4.2 std_vector.i

                                                                                                The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                                                                                %module example
                                                                                                %include "std_vector.i"
                                                                                                
                                                                                                namespace std {
                                                                                                   %template(vectori) vector<int>;
                                                                                                   %template(vectord) vector<double>;
                                                                                                };
                                                                                                

                                                                                                When a template vector<X> is instantiated a number of things happen:
                                                                                                • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                                                                                • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                                                                                • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                                                                                • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                                                                                • An exception handler for std::out_of_range is defined.
                                                                                                • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                                                                                To illustrate the use of this library, consider the following functions:

                                                                                                /* File : example.h */
                                                                                                
                                                                                                #include <vector>
                                                                                                #include <algorithm>
                                                                                                #include <functional>
                                                                                                #include <numeric>
                                                                                                
                                                                                                double average(std::vector<int> v) {
                                                                                                    return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                                                                                }
                                                                                                
                                                                                                std::vector<double> half(const std::vector<double>& v) {
                                                                                                    std::vector<double> w(v);
                                                                                                    for (unsigned int i=0; i<w.size(); i++)
                                                                                                        w[i] /= 2.0;
                                                                                                    return w;
                                                                                                }
                                                                                                
                                                                                                void halve_in_place(std::vector<double>& v) {
                                                                                                    std::transform(v.begin(),v.end(),v.begin(),
                                                                                                                   std::bind2nd(std::divides<double>(),2.0));
                                                                                                }
                                                                                                

                                                                                                To wrap with SWIG, you might write the following:

                                                                                                %module example
                                                                                                %{
                                                                                                #include "example.h"
                                                                                                %}
                                                                                                
                                                                                                %include "std_vector.i"
                                                                                                // Instantiate templates used by example
                                                                                                namespace std {
                                                                                                   %template(IntVector) vector<int>;
                                                                                                   %template(DoubleVector) vector<double>;
                                                                                                }
                                                                                                
                                                                                                // Include the header file with above prototypes
                                                                                                %include "example.h"
                                                                                                

                                                                                                Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                                                                                >>> from example import *
                                                                                                >>> iv = IntVector(4)         # Create an vector<int>
                                                                                                >>> for i in range(0,4):
                                                                                                ...      iv[i] = i
                                                                                                >>> average(iv)               # Call method
                                                                                                1.5
                                                                                                >>> average([0,1,2,3])        # Call with list
                                                                                                1.5
                                                                                                >>> half([1,2,3])             # Half a list
                                                                                                (0.5,1.0,1.5)
                                                                                                >>> halve_in_place([1,2,3])   # Oops
                                                                                                Traceback (most recent call last):
                                                                                                  File "<stdin>", line 1, in ?
                                                                                                TypeError: Type error. Expected _p_std__vectorTdouble_t
                                                                                                >>> dv = DoubleVector(4)
                                                                                                >>> for i in range(0,4):
                                                                                                ...       dv[i] = i
                                                                                                >>> halve_in_place(dv)       # Ok
                                                                                                >>> for i in dv:
                                                                                                ...       print i
                                                                                                ...
                                                                                                0.0
                                                                                                0.5
                                                                                                1.0
                                                                                                1.5
                                                                                                >>> dv[20] = 4.5
                                                                                                Traceback (most recent call last):
                                                                                                  File "<stdin>", line 1, in ?
                                                                                                  File "example.py", line 81, in __setitem__
                                                                                                    def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                                                                                IndexError: vector index out of range
                                                                                                >>>
                                                                                                

                                                                                                This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                                                                                %include "std_vector.i"
                                                                                                
                                                                                                namespace std {
                                                                                                    %template(IntVector) vector<int>;
                                                                                                }
                                                                                                
                                                                                                using namespace std;
                                                                                                typedef std::vector Vector;
                                                                                                
                                                                                                void foo(vector<int> *x, const Vector &x);
                                                                                                

                                                                                                Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                                                                                Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                                                                                Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                                                                                8.5 Utility Libraries

                                                                                                8.5.1 exception.i

                                                                                                The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                                                                                SWIG_exception(int code, const char *message)

                                                                                                Raises an exception in the target language. code is one of the following symbolic constants:

                                                                                                SWIG_MemoryError
                                                                                                SWIG_IOError
                                                                                                SWIG_RuntimeError
                                                                                                SWIG_IndexError
                                                                                                SWIG_TypeError
                                                                                                SWIG_DivisionByZero
                                                                                                SWIG_OverflowError
                                                                                                SWIG_SyntaxError
                                                                                                SWIG_ValueError
                                                                                                SWIG_SystemError
                                                                                                

                                                                                                message is a string indicating more information about the problem.

                                                                                                The primary use of this module is in writing language-independent exception handlers. For example:

                                                                                                %include "exception.i"
                                                                                                %exception std::vector::getitem {
                                                                                                    try {
                                                                                                        $action
                                                                                                    } catch (std::out_of_range& e) {
                                                                                                        SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                                                                    }
                                                                                                }
                                                                                                

                                                                                                ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                                                                                

                                                                                                SWIG-1.3 Documentation

                                                                                                
                                                                                                

                                                                                                ---

                                                                                                Table of Contents

                                                                                                
                                                                                                
                                                                                                SWIG-1.3 Development Documentation
                                                                                                • Sections
                                                                                                • SWIG Core Documentation
                                                                                                • Language Module Documentation
                                                                                                • Developer Documentation
                                                                                                • Documentation that has not yet been updated
                                                                                                1 Preface
                                                                                                • 1.1 Introduction
                                                                                                • 1.2 Special Introduction for Version 1.3
                                                                                                • 1.3 SWIG Versions
                                                                                                • 1.4 SWIG resources
                                                                                                • 1.5 Prerequisites
                                                                                                • 1.6 Organization of this manual
                                                                                                • 1.7 How to avoid reading the manual
                                                                                                • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                                                                                  >>> make_upper("hello world")
                                                                                                  'HELLO WORLD'
                                                                                                  >>> attach_header("Hello world")
                                                                                                  'header: Hello world'
                                                                                                  >>>
                                                                                                  

                                                                                                  This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                                                                                  %cstring_output_maxsize(parm, maxparm)

                                                                                                  This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                                                                                  %cstring_output_maxsize(char *path, int maxpath);
                                                                                                  ...
                                                                                                  void get_path(char *path, int maxpath);
                                                                                                  

                                                                                                  In the target language:

                                                                                                  >>> get_path(1024)
                                                                                                  '/home/beazley/Packages/Foo/Bar'
                                                                                                  >>>
                                                                                                  

                                                                                                  This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                                                                                  %cstring_output_withsize(parm, maxparm)

                                                                                                  This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                                                                                  %cstring_output_withsize(char *data, int *maxdata);
                                                                                                  ...
                                                                                                  void get_data(char *data, int *maxdata);
                                                                                                  

                                                                                                  In the target language:

                                                                                                  >>> get_data(1024)
                                                                                                  'x627388912'
                                                                                                  >>> get_data(1024)
                                                                                                  'xyzzy'
                                                                                                  >>>
                                                                                                  

                                                                                                  This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                                                                                  %cstring_output_allocate(parm, release)

                                                                                                  This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                                                                                  void foo(char **s) {
                                                                                                      *s = (char *) malloc(64);
                                                                                                      sprintf(*s, "Hello world\n");
                                                                                                  }
                                                                                                  

                                                                                                  The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                  %cstring_output_allocate(char **s, free(*$1));
                                                                                                  ...
                                                                                                  void foo(char **s);
                                                                                                  

                                                                                                  In the target language:

                                                                                                  >>> foo()
                                                                                                  'Hello world\n'
                                                                                                  >>>
                                                                                                  

                                                                                                  %cstring_output_allocate_size(parm, szparm, release)

                                                                                                  This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                                                                                  void foo(char **s, int *sz) {
                                                                                                      *s = (char *) malloc(64);
                                                                                                      *sz = 64;
                                                                                                      // Write some binary data
                                                                                                      ...
                                                                                                  }
                                                                                                  

                                                                                                  The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                  %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                                                                                  ...
                                                                                                  void foo(char **s, int *slen);
                                                                                                  

                                                                                                  In the target language:

                                                                                                  >>> foo()
                                                                                                  '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                                                                                  >>>
                                                                                                  

                                                                                                  This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                                                                                  char  *get_data(int *len);
                                                                                                  

                                                                                                  You could wrap it with a function like this:

                                                                                                  void my_get_data(char **result, int *len) {
                                                                                                     *result = get_data(len);
                                                                                                  }
                                                                                                  

                                                                                                  Comments:
                                                                                                  • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                                                                                  • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                                                                                  • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                                                                                  • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                                                                                  8.4 C++ Library

                                                                                                  The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                                                                                  8.4.1 std_string.i

                                                                                                  The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                                                                                  %module example
                                                                                                  %include "std_string.i"
                                                                                                  
                                                                                                  std::string foo();
                                                                                                  void        bar(const std::string &x);
                                                                                                  

                                                                                                  In the target language:

                                                                                                  x = foo();                # Returns a string object
                                                                                                  bar("Hello World");       # Pass string as std::string
                                                                                                  

                                                                                                  This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                                                                                  This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                                                                                  %module example
                                                                                                  %include "std_string.i"
                                                                                                  
                                                                                                  using namespace std;
                                                                                                  typedef std::string String;
                                                                                                  ...
                                                                                                  void foo(string s, const String &t);     // std_string typemaps still applied
                                                                                                  

                                                                                                  Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                                                                                  8.4.2 std_vector.i

                                                                                                  The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                                                                                  %module example
                                                                                                  %include "std_vector.i"
                                                                                                  
                                                                                                  namespace std {
                                                                                                     %template(vectori) vector<int>;
                                                                                                     %template(vectord) vector<double>;
                                                                                                  };
                                                                                                  

                                                                                                  When a template vector<X> is instantiated a number of things happen:
                                                                                                  • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                                                                                  • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                                                                                  • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                                                                                  • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                                                                                  • An exception handler for std::out_of_range is defined.
                                                                                                  • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                                                                                  To illustrate the use of this library, consider the following functions:

                                                                                                  /* File : example.h */
                                                                                                  
                                                                                                  #include <vector>
                                                                                                  #include <algorithm>
                                                                                                  #include <functional>
                                                                                                  #include <numeric>
                                                                                                  
                                                                                                  double average(std::vector<int> v) {
                                                                                                      return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                                                                                  }
                                                                                                  
                                                                                                  std::vector<double> half(const std::vector<double>& v) {
                                                                                                      std::vector<double> w(v);
                                                                                                      for (unsigned int i=0; i<w.size(); i++)
                                                                                                          w[i] /= 2.0;
                                                                                                      return w;
                                                                                                  }
                                                                                                  
                                                                                                  void halve_in_place(std::vector<double>& v) {
                                                                                                      std::transform(v.begin(),v.end(),v.begin(),
                                                                                                                     std::bind2nd(std::divides<double>(),2.0));
                                                                                                  }
                                                                                                  

                                                                                                  To wrap with SWIG, you might write the following:

                                                                                                  %module example
                                                                                                  %{
                                                                                                  #include "example.h"
                                                                                                  %}
                                                                                                  
                                                                                                  %include "std_vector.i"
                                                                                                  // Instantiate templates used by example
                                                                                                  namespace std {
                                                                                                     %template(IntVector) vector<int>;
                                                                                                     %template(DoubleVector) vector<double>;
                                                                                                  }
                                                                                                  
                                                                                                  // Include the header file with above prototypes
                                                                                                  %include "example.h"
                                                                                                  

                                                                                                  Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                                                                                  >>> from example import *
                                                                                                  >>> iv = IntVector(4)         # Create an vector<int>
                                                                                                  >>> for i in range(0,4):
                                                                                                  ...      iv[i] = i
                                                                                                  >>> average(iv)               # Call method
                                                                                                  1.5
                                                                                                  >>> average([0,1,2,3])        # Call with list
                                                                                                  1.5
                                                                                                  >>> half([1,2,3])             # Half a list
                                                                                                  (0.5,1.0,1.5)
                                                                                                  >>> halve_in_place([1,2,3])   # Oops
                                                                                                  Traceback (most recent call last):
                                                                                                    File "<stdin>", line 1, in ?
                                                                                                  TypeError: Type error. Expected _p_std__vectorTdouble_t
                                                                                                  >>> dv = DoubleVector(4)
                                                                                                  >>> for i in range(0,4):
                                                                                                  ...       dv[i] = i
                                                                                                  >>> halve_in_place(dv)       # Ok
                                                                                                  >>> for i in dv:
                                                                                                  ...       print i
                                                                                                  ...
                                                                                                  0.0
                                                                                                  0.5
                                                                                                  1.0
                                                                                                  1.5
                                                                                                  >>> dv[20] = 4.5
                                                                                                  Traceback (most recent call last):
                                                                                                    File "<stdin>", line 1, in ?
                                                                                                    File "example.py", line 81, in __setitem__
                                                                                                      def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                                                                                  IndexError: vector index out of range
                                                                                                  >>>
                                                                                                  

                                                                                                  This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                                                                                  %include "std_vector.i"
                                                                                                  
                                                                                                  namespace std {
                                                                                                      %template(IntVector) vector<int>;
                                                                                                  }
                                                                                                  
                                                                                                  using namespace std;
                                                                                                  typedef std::vector Vector;
                                                                                                  
                                                                                                  void foo(vector<int> *x, const Vector &x);
                                                                                                  

                                                                                                  Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                                                                                  Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                                                                                  Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                                                                                  8.5 Utility Libraries

                                                                                                  8.5.1 exception.i

                                                                                                  The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                                                                                  SWIG_exception(int code, const char *message)

                                                                                                  Raises an exception in the target language. code is one of the following symbolic constants:

                                                                                                  SWIG_MemoryError
                                                                                                  SWIG_IOError
                                                                                                  SWIG_RuntimeError
                                                                                                  SWIG_IndexError
                                                                                                  SWIG_TypeError
                                                                                                  SWIG_DivisionByZero
                                                                                                  SWIG_OverflowError
                                                                                                  SWIG_SyntaxError
                                                                                                  SWIG_ValueError
                                                                                                  SWIG_SystemError
                                                                                                  

                                                                                                  message is a string indicating more information about the problem.

                                                                                                  The primary use of this module is in writing language-independent exception handlers. For example:

                                                                                                  %include "exception.i"
                                                                                                  %exception std::vector::getitem {
                                                                                                      try {
                                                                                                          $action
                                                                                                      } catch (std::out_of_range& e) {
                                                                                                          SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                                                                      }
                                                                                                  }
                                                                                                  

                                                                                                  ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                                                                                  

                                                                                                  SWIG-1.3 Documentation

                                                                                                  
                                                                                                  

                                                                                                  ---

                                                                                                  Table of Contents

                                                                                                  
                                                                                                  
                                                                                                  SWIG-1.3 Development Documentation
                                                                                                  • Sections
                                                                                                  • SWIG Core Documentation
                                                                                                  • Language Module Documentation
                                                                                                  • Developer Documentation
                                                                                                  • Documentation that has not yet been updated
                                                                                                  1 Preface
                                                                                                  • 1.1 Introduction
                                                                                                  • 1.2 Special Introduction for Version 1.3
                                                                                                  • 1.3 SWIG Versions
                                                                                                  • 1.4 SWIG resources
                                                                                                  • 1.5 Prerequisites
                                                                                                  • 1.6 Organization of this manual
                                                                                                  • 1.7 How to avoid reading the manual
                                                                                                  • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                                                                                    >>> make_upper("hello world")
                                                                                                    'HELLO WORLD'
                                                                                                    >>> attach_header("Hello world")
                                                                                                    'header: Hello world'
                                                                                                    >>>
                                                                                                    

                                                                                                    This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                                                                                    %cstring_output_maxsize(parm, maxparm)

                                                                                                    This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                                                                                    %cstring_output_maxsize(char *path, int maxpath);
                                                                                                    ...
                                                                                                    void get_path(char *path, int maxpath);
                                                                                                    

                                                                                                    In the target language:

                                                                                                    >>> get_path(1024)
                                                                                                    '/home/beazley/Packages/Foo/Bar'
                                                                                                    >>>
                                                                                                    

                                                                                                    This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                                                                                    %cstring_output_withsize(parm, maxparm)

                                                                                                    This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                                                                                    %cstring_output_withsize(char *data, int *maxdata);
                                                                                                    ...
                                                                                                    void get_data(char *data, int *maxdata);
                                                                                                    

                                                                                                    In the target language:

                                                                                                    >>> get_data(1024)
                                                                                                    'x627388912'
                                                                                                    >>> get_data(1024)
                                                                                                    'xyzzy'
                                                                                                    >>>
                                                                                                    

                                                                                                    This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                                                                                    %cstring_output_allocate(parm, release)

                                                                                                    This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                                                                                    void foo(char **s) {
                                                                                                        *s = (char *) malloc(64);
                                                                                                        sprintf(*s, "Hello world\n");
                                                                                                    }
                                                                                                    

                                                                                                    The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                    %cstring_output_allocate(char **s, free(*$1));
                                                                                                    ...
                                                                                                    void foo(char **s);
                                                                                                    

                                                                                                    In the target language:

                                                                                                    >>> foo()
                                                                                                    'Hello world\n'
                                                                                                    >>>
                                                                                                    

                                                                                                    %cstring_output_allocate_size(parm, szparm, release)

                                                                                                    This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                                                                                    void foo(char **s, int *sz) {
                                                                                                        *s = (char *) malloc(64);
                                                                                                        *sz = 64;
                                                                                                        // Write some binary data
                                                                                                        ...
                                                                                                    }
                                                                                                    

                                                                                                    The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                    %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                                                                                    ...
                                                                                                    void foo(char **s, int *slen);
                                                                                                    

                                                                                                    In the target language:

                                                                                                    >>> foo()
                                                                                                    '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                                                                                    >>>
                                                                                                    

                                                                                                    This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                                                                                    char  *get_data(int *len);
                                                                                                    

                                                                                                    You could wrap it with a function like this:

                                                                                                    void my_get_data(char **result, int *len) {
                                                                                                       *result = get_data(len);
                                                                                                    }
                                                                                                    

                                                                                                    Comments:
                                                                                                    • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                                                                                    • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                                                                                    • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                                                                                    • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                                                                                    8.4 C++ Library

                                                                                                    The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                                                                                    8.4.1 std_string.i

                                                                                                    The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                                                                                    %module example
                                                                                                    %include "std_string.i"
                                                                                                    
                                                                                                    std::string foo();
                                                                                                    void        bar(const std::string &x);
                                                                                                    

                                                                                                    In the target language:

                                                                                                    x = foo();                # Returns a string object
                                                                                                    bar("Hello World");       # Pass string as std::string
                                                                                                    

                                                                                                    This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                                                                                    This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                                                                                    %module example
                                                                                                    %include "std_string.i"
                                                                                                    
                                                                                                    using namespace std;
                                                                                                    typedef std::string String;
                                                                                                    ...
                                                                                                    void foo(string s, const String &t);     // std_string typemaps still applied
                                                                                                    

                                                                                                    Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                                                                                    8.4.2 std_vector.i

                                                                                                    The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                                                                                    %module example
                                                                                                    %include "std_vector.i"
                                                                                                    
                                                                                                    namespace std {
                                                                                                       %template(vectori) vector<int>;
                                                                                                       %template(vectord) vector<double>;
                                                                                                    };
                                                                                                    

                                                                                                    When a template vector<X> is instantiated a number of things happen:
                                                                                                    • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                                                                                    • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                                                                                    • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                                                                                    • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                                                                                    • An exception handler for std::out_of_range is defined.
                                                                                                    • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                                                                                    To illustrate the use of this library, consider the following functions:

                                                                                                    /* File : example.h */
                                                                                                    
                                                                                                    #include <vector>
                                                                                                    #include <algorithm>
                                                                                                    #include <functional>
                                                                                                    #include <numeric>
                                                                                                    
                                                                                                    double average(std::vector<int> v) {
                                                                                                        return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                                                                                    }
                                                                                                    
                                                                                                    std::vector<double> half(const std::vector<double>& v) {
                                                                                                        std::vector<double> w(v);
                                                                                                        for (unsigned int i=0; i<w.size(); i++)
                                                                                                            w[i] /= 2.0;
                                                                                                        return w;
                                                                                                    }
                                                                                                    
                                                                                                    void halve_in_place(std::vector<double>& v) {
                                                                                                        std::transform(v.begin(),v.end(),v.begin(),
                                                                                                                       std::bind2nd(std::divides<double>(),2.0));
                                                                                                    }
                                                                                                    

                                                                                                    To wrap with SWIG, you might write the following:

                                                                                                    %module example
                                                                                                    %{
                                                                                                    #include "example.h"
                                                                                                    %}
                                                                                                    
                                                                                                    %include "std_vector.i"
                                                                                                    // Instantiate templates used by example
                                                                                                    namespace std {
                                                                                                       %template(IntVector) vector<int>;
                                                                                                       %template(DoubleVector) vector<double>;
                                                                                                    }
                                                                                                    
                                                                                                    // Include the header file with above prototypes
                                                                                                    %include "example.h"
                                                                                                    

                                                                                                    Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                                                                                    >>> from example import *
                                                                                                    >>> iv = IntVector(4)         # Create an vector<int>
                                                                                                    >>> for i in range(0,4):
                                                                                                    ...      iv[i] = i
                                                                                                    >>> average(iv)               # Call method
                                                                                                    1.5
                                                                                                    >>> average([0,1,2,3])        # Call with list
                                                                                                    1.5
                                                                                                    >>> half([1,2,3])             # Half a list
                                                                                                    (0.5,1.0,1.5)
                                                                                                    >>> halve_in_place([1,2,3])   # Oops
                                                                                                    Traceback (most recent call last):
                                                                                                      File "<stdin>", line 1, in ?
                                                                                                    TypeError: Type error. Expected _p_std__vectorTdouble_t
                                                                                                    >>> dv = DoubleVector(4)
                                                                                                    >>> for i in range(0,4):
                                                                                                    ...       dv[i] = i
                                                                                                    >>> halve_in_place(dv)       # Ok
                                                                                                    >>> for i in dv:
                                                                                                    ...       print i
                                                                                                    ...
                                                                                                    0.0
                                                                                                    0.5
                                                                                                    1.0
                                                                                                    1.5
                                                                                                    >>> dv[20] = 4.5
                                                                                                    Traceback (most recent call last):
                                                                                                      File "<stdin>", line 1, in ?
                                                                                                      File "example.py", line 81, in __setitem__
                                                                                                        def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                                                                                    IndexError: vector index out of range
                                                                                                    >>>
                                                                                                    

                                                                                                    This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                                                                                    %include "std_vector.i"
                                                                                                    
                                                                                                    namespace std {
                                                                                                        %template(IntVector) vector<int>;
                                                                                                    }
                                                                                                    
                                                                                                    using namespace std;
                                                                                                    typedef std::vector Vector;
                                                                                                    
                                                                                                    void foo(vector<int> *x, const Vector &x);
                                                                                                    

                                                                                                    Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                                                                                    Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                                                                                    Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                                                                                    8.5 Utility Libraries

                                                                                                    8.5.1 exception.i

                                                                                                    The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                                                                                    SWIG_exception(int code, const char *message)

                                                                                                    Raises an exception in the target language. code is one of the following symbolic constants:

                                                                                                    SWIG_MemoryError
                                                                                                    SWIG_IOError
                                                                                                    SWIG_RuntimeError
                                                                                                    SWIG_IndexError
                                                                                                    SWIG_TypeError
                                                                                                    SWIG_DivisionByZero
                                                                                                    SWIG_OverflowError
                                                                                                    SWIG_SyntaxError
                                                                                                    SWIG_ValueError
                                                                                                    SWIG_SystemError
                                                                                                    

                                                                                                    message is a string indicating more information about the problem.

                                                                                                    The primary use of this module is in writing language-independent exception handlers. For example:

                                                                                                    %include "exception.i"
                                                                                                    %exception std::vector::getitem {
                                                                                                        try {
                                                                                                            $action
                                                                                                        } catch (std::out_of_range& e) {
                                                                                                            SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                                                                        }
                                                                                                    }
                                                                                                    

                                                                                                    ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                                                                                    

                                                                                                    SWIG-1.3 Documentation

                                                                                                    
                                                                                                    

                                                                                                    ---

                                                                                                    Table of Contents

                                                                                                    
                                                                                                    
                                                                                                    SWIG-1.3 Development Documentation
                                                                                                    • Sections
                                                                                                    • SWIG Core Documentation
                                                                                                    • Language Module Documentation
                                                                                                    • Developer Documentation
                                                                                                    • Documentation that has not yet been updated
                                                                                                    1 Preface
                                                                                                    • 1.1 Introduction
                                                                                                    • 1.2 Special Introduction for Version 1.3
                                                                                                    • 1.3 SWIG Versions
                                                                                                    • 1.4 SWIG resources
                                                                                                    • 1.5 Prerequisites
                                                                                                    • 1.6 Organization of this manual
                                                                                                    • 1.7 How to avoid reading the manual
                                                                                                    • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                                                                                      >>> make_upper("hello world")
                                                                                                      'HELLO WORLD'
                                                                                                      >>> attach_header("Hello world")
                                                                                                      'header: Hello world'
                                                                                                      >>>
                                                                                                      

                                                                                                      This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                                                                                      %cstring_output_maxsize(parm, maxparm)

                                                                                                      This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                                                                                      %cstring_output_maxsize(char *path, int maxpath);
                                                                                                      ...
                                                                                                      void get_path(char *path, int maxpath);
                                                                                                      

                                                                                                      In the target language:

                                                                                                      >>> get_path(1024)
                                                                                                      '/home/beazley/Packages/Foo/Bar'
                                                                                                      >>>
                                                                                                      

                                                                                                      This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                                                                                      %cstring_output_withsize(parm, maxparm)

                                                                                                      This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                                                                                      %cstring_output_withsize(char *data, int *maxdata);
                                                                                                      ...
                                                                                                      void get_data(char *data, int *maxdata);
                                                                                                      

                                                                                                      In the target language:

                                                                                                      >>> get_data(1024)
                                                                                                      'x627388912'
                                                                                                      >>> get_data(1024)
                                                                                                      'xyzzy'
                                                                                                      >>>
                                                                                                      

                                                                                                      This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                                                                                      %cstring_output_allocate(parm, release)

                                                                                                      This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                                                                                      void foo(char **s) {
                                                                                                          *s = (char *) malloc(64);
                                                                                                          sprintf(*s, "Hello world\n");
                                                                                                      }
                                                                                                      

                                                                                                      The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                      %cstring_output_allocate(char **s, free(*$1));
                                                                                                      ...
                                                                                                      void foo(char **s);
                                                                                                      

                                                                                                      In the target language:

                                                                                                      >>> foo()
                                                                                                      'Hello world\n'
                                                                                                      >>>
                                                                                                      

                                                                                                      %cstring_output_allocate_size(parm, szparm, release)

                                                                                                      This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                                                                                      void foo(char **s, int *sz) {
                                                                                                          *s = (char *) malloc(64);
                                                                                                          *sz = 64;
                                                                                                          // Write some binary data
                                                                                                          ...
                                                                                                      }
                                                                                                      

                                                                                                      The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                      %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                                                                                      ...
                                                                                                      void foo(char **s, int *slen);
                                                                                                      

                                                                                                      In the target language:

                                                                                                      >>> foo()
                                                                                                      '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                                                                                      >>>
                                                                                                      

                                                                                                      This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                                                                                      char  *get_data(int *len);
                                                                                                      

                                                                                                      You could wrap it with a function like this:

                                                                                                      void my_get_data(char **result, int *len) {
                                                                                                         *result = get_data(len);
                                                                                                      }
                                                                                                      

                                                                                                      Comments:
                                                                                                      • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                                                                                      • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                                                                                      • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                                                                                      • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                                                                                      8.4 C++ Library

                                                                                                      The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                                                                                      8.4.1 std_string.i

                                                                                                      The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                                                                                      %module example
                                                                                                      %include "std_string.i"
                                                                                                      
                                                                                                      std::string foo();
                                                                                                      void        bar(const std::string &x);
                                                                                                      

                                                                                                      In the target language:

                                                                                                      x = foo();                # Returns a string object
                                                                                                      bar("Hello World");       # Pass string as std::string
                                                                                                      

                                                                                                      This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                                                                                      This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                                                                                      %module example
                                                                                                      %include "std_string.i"
                                                                                                      
                                                                                                      using namespace std;
                                                                                                      typedef std::string String;
                                                                                                      ...
                                                                                                      void foo(string s, const String &t);     // std_string typemaps still applied
                                                                                                      

                                                                                                      Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                                                                                      8.4.2 std_vector.i

                                                                                                      The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                                                                                      %module example
                                                                                                      %include "std_vector.i"
                                                                                                      
                                                                                                      namespace std {
                                                                                                         %template(vectori) vector<int>;
                                                                                                         %template(vectord) vector<double>;
                                                                                                      };
                                                                                                      

                                                                                                      When a template vector<X> is instantiated a number of things happen:
                                                                                                      • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                                                                                      • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                                                                                      • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                                                                                      • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                                                                                      • An exception handler for std::out_of_range is defined.
                                                                                                      • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                                                                                      To illustrate the use of this library, consider the following functions:

                                                                                                      /* File : example.h */
                                                                                                      
                                                                                                      #include <vector>
                                                                                                      #include <algorithm>
                                                                                                      #include <functional>
                                                                                                      #include <numeric>
                                                                                                      
                                                                                                      double average(std::vector<int> v) {
                                                                                                          return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                                                                                      }
                                                                                                      
                                                                                                      std::vector<double> half(const std::vector<double>& v) {
                                                                                                          std::vector<double> w(v);
                                                                                                          for (unsigned int i=0; i<w.size(); i++)
                                                                                                              w[i] /= 2.0;
                                                                                                          return w;
                                                                                                      }
                                                                                                      
                                                                                                      void halve_in_place(std::vector<double>& v) {
                                                                                                          std::transform(v.begin(),v.end(),v.begin(),
                                                                                                                         std::bind2nd(std::divides<double>(),2.0));
                                                                                                      }
                                                                                                      

                                                                                                      To wrap with SWIG, you might write the following:

                                                                                                      %module example
                                                                                                      %{
                                                                                                      #include "example.h"
                                                                                                      %}
                                                                                                      
                                                                                                      %include "std_vector.i"
                                                                                                      // Instantiate templates used by example
                                                                                                      namespace std {
                                                                                                         %template(IntVector) vector<int>;
                                                                                                         %template(DoubleVector) vector<double>;
                                                                                                      }
                                                                                                      
                                                                                                      // Include the header file with above prototypes
                                                                                                      %include "example.h"
                                                                                                      

                                                                                                      Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                                                                                      >>> from example import *
                                                                                                      >>> iv = IntVector(4)         # Create an vector<int>
                                                                                                      >>> for i in range(0,4):
                                                                                                      ...      iv[i] = i
                                                                                                      >>> average(iv)               # Call method
                                                                                                      1.5
                                                                                                      >>> average([0,1,2,3])        # Call with list
                                                                                                      1.5
                                                                                                      >>> half([1,2,3])             # Half a list
                                                                                                      (0.5,1.0,1.5)
                                                                                                      >>> halve_in_place([1,2,3])   # Oops
                                                                                                      Traceback (most recent call last):
                                                                                                        File "<stdin>", line 1, in ?
                                                                                                      TypeError: Type error. Expected _p_std__vectorTdouble_t
                                                                                                      >>> dv = DoubleVector(4)
                                                                                                      >>> for i in range(0,4):
                                                                                                      ...       dv[i] = i
                                                                                                      >>> halve_in_place(dv)       # Ok
                                                                                                      >>> for i in dv:
                                                                                                      ...       print i
                                                                                                      ...
                                                                                                      0.0
                                                                                                      0.5
                                                                                                      1.0
                                                                                                      1.5
                                                                                                      >>> dv[20] = 4.5
                                                                                                      Traceback (most recent call last):
                                                                                                        File "<stdin>", line 1, in ?
                                                                                                        File "example.py", line 81, in __setitem__
                                                                                                          def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                                                                                      IndexError: vector index out of range
                                                                                                      >>>
                                                                                                      

                                                                                                      This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                                                                                      %include "std_vector.i"
                                                                                                      
                                                                                                      namespace std {
                                                                                                          %template(IntVector) vector<int>;
                                                                                                      }
                                                                                                      
                                                                                                      using namespace std;
                                                                                                      typedef std::vector Vector;
                                                                                                      
                                                                                                      void foo(vector<int> *x, const Vector &x);
                                                                                                      

                                                                                                      Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                                                                                      Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                                                                                      Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                                                                                      8.5 Utility Libraries

                                                                                                      8.5.1 exception.i

                                                                                                      The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                                                                                      SWIG_exception(int code, const char *message)

                                                                                                      Raises an exception in the target language. code is one of the following symbolic constants:

                                                                                                      SWIG_MemoryError
                                                                                                      SWIG_IOError
                                                                                                      SWIG_RuntimeError
                                                                                                      SWIG_IndexError
                                                                                                      SWIG_TypeError
                                                                                                      SWIG_DivisionByZero
                                                                                                      SWIG_OverflowError
                                                                                                      SWIG_SyntaxError
                                                                                                      SWIG_ValueError
                                                                                                      SWIG_SystemError
                                                                                                      

                                                                                                      message is a string indicating more information about the problem.

                                                                                                      The primary use of this module is in writing language-independent exception handlers. For example:

                                                                                                      %include "exception.i"
                                                                                                      %exception std::vector::getitem {
                                                                                                          try {
                                                                                                              $action
                                                                                                          } catch (std::out_of_range& e) {
                                                                                                              SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                                                                          }
                                                                                                      }
                                                                                                      

                                                                                                      ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                                                                                      

                                                                                                      SWIG-1.3 Documentation

                                                                                                      
                                                                                                      

                                                                                                      ---

                                                                                                      Table of Contents

                                                                                                      
                                                                                                      
                                                                                                      SWIG-1.3 Development Documentation
                                                                                                      • Sections
                                                                                                      • SWIG Core Documentation
                                                                                                      • Language Module Documentation
                                                                                                      • Developer Documentation
                                                                                                      • Documentation that has not yet been updated
                                                                                                      1 Preface
                                                                                                      • 1.1 Introduction
                                                                                                      • 1.2 Special Introduction for Version 1.3
                                                                                                      • 1.3 SWIG Versions
                                                                                                      • 1.4 SWIG resources
                                                                                                      • 1.5 Prerequisites
                                                                                                      • 1.6 Organization of this manual
                                                                                                      • 1.7 How to avoid reading the manual
                                                                                                      • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                                                                                        >>> make_upper("hello world")
                                                                                                        'HELLO WORLD'
                                                                                                        >>> attach_header("Hello world")
                                                                                                        'header: Hello world'
                                                                                                        >>>
                                                                                                        

                                                                                                        This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                                                                                        %cstring_output_maxsize(parm, maxparm)

                                                                                                        This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                                                                                        %cstring_output_maxsize(char *path, int maxpath);
                                                                                                        ...
                                                                                                        void get_path(char *path, int maxpath);
                                                                                                        

                                                                                                        In the target language:

                                                                                                        >>> get_path(1024)
                                                                                                        '/home/beazley/Packages/Foo/Bar'
                                                                                                        >>>
                                                                                                        

                                                                                                        This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                                                                                        %cstring_output_withsize(parm, maxparm)

                                                                                                        This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                                                                                        %cstring_output_withsize(char *data, int *maxdata);
                                                                                                        ...
                                                                                                        void get_data(char *data, int *maxdata);
                                                                                                        

                                                                                                        In the target language:

                                                                                                        >>> get_data(1024)
                                                                                                        'x627388912'
                                                                                                        >>> get_data(1024)
                                                                                                        'xyzzy'
                                                                                                        >>>
                                                                                                        

                                                                                                        This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                                                                                        %cstring_output_allocate(parm, release)

                                                                                                        This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                                                                                        void foo(char **s) {
                                                                                                            *s = (char *) malloc(64);
                                                                                                            sprintf(*s, "Hello world\n");
                                                                                                        }
                                                                                                        

                                                                                                        The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                        %cstring_output_allocate(char **s, free(*$1));
                                                                                                        ...
                                                                                                        void foo(char **s);
                                                                                                        

                                                                                                        In the target language:

                                                                                                        >>> foo()
                                                                                                        'Hello world\n'
                                                                                                        >>>
                                                                                                        

                                                                                                        %cstring_output_allocate_size(parm, szparm, release)

                                                                                                        This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                                                                                        void foo(char **s, int *sz) {
                                                                                                            *s = (char *) malloc(64);
                                                                                                            *sz = 64;
                                                                                                            // Write some binary data
                                                                                                            ...
                                                                                                        }
                                                                                                        

                                                                                                        The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                        %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                                                                                        ...
                                                                                                        void foo(char **s, int *slen);
                                                                                                        

                                                                                                        In the target language:

                                                                                                        >>> foo()
                                                                                                        '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                                                                                        >>>
                                                                                                        

                                                                                                        This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                                                                                        char  *get_data(int *len);
                                                                                                        

                                                                                                        You could wrap it with a function like this:

                                                                                                        void my_get_data(char **result, int *len) {
                                                                                                           *result = get_data(len);
                                                                                                        }
                                                                                                        

                                                                                                        Comments:
                                                                                                        • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                                                                                        • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                                                                                        • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                                                                                        • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                                                                                        8.4 C++ Library

                                                                                                        The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                                                                                        8.4.1 std_string.i

                                                                                                        The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                                                                                        %module example
                                                                                                        %include "std_string.i"
                                                                                                        
                                                                                                        std::string foo();
                                                                                                        void        bar(const std::string &x);
                                                                                                        

                                                                                                        In the target language:

                                                                                                        x = foo();                # Returns a string object
                                                                                                        bar("Hello World");       # Pass string as std::string
                                                                                                        

                                                                                                        This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                                                                                        This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                                                                                        %module example
                                                                                                        %include "std_string.i"
                                                                                                        
                                                                                                        using namespace std;
                                                                                                        typedef std::string String;
                                                                                                        ...
                                                                                                        void foo(string s, const String &t);     // std_string typemaps still applied
                                                                                                        

                                                                                                        Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                                                                                        8.4.2 std_vector.i

                                                                                                        The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                                                                                        %module example
                                                                                                        %include "std_vector.i"
                                                                                                        
                                                                                                        namespace std {
                                                                                                           %template(vectori) vector<int>;
                                                                                                           %template(vectord) vector<double>;
                                                                                                        };
                                                                                                        

                                                                                                        When a template vector<X> is instantiated a number of things happen:
                                                                                                        • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                                                                                        • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                                                                                        • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                                                                                        • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                                                                                        • An exception handler for std::out_of_range is defined.
                                                                                                        • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                                                                                        To illustrate the use of this library, consider the following functions:

                                                                                                        /* File : example.h */
                                                                                                        
                                                                                                        #include <vector>
                                                                                                        #include <algorithm>
                                                                                                        #include <functional>
                                                                                                        #include <numeric>
                                                                                                        
                                                                                                        double average(std::vector<int> v) {
                                                                                                            return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                                                                                        }
                                                                                                        
                                                                                                        std::vector<double> half(const std::vector<double>& v) {
                                                                                                            std::vector<double> w(v);
                                                                                                            for (unsigned int i=0; i<w.size(); i++)
                                                                                                                w[i] /= 2.0;
                                                                                                            return w;
                                                                                                        }
                                                                                                        
                                                                                                        void halve_in_place(std::vector<double>& v) {
                                                                                                            std::transform(v.begin(),v.end(),v.begin(),
                                                                                                                           std::bind2nd(std::divides<double>(),2.0));
                                                                                                        }
                                                                                                        

                                                                                                        To wrap with SWIG, you might write the following:

                                                                                                        %module example
                                                                                                        %{
                                                                                                        #include "example.h"
                                                                                                        %}
                                                                                                        
                                                                                                        %include "std_vector.i"
                                                                                                        // Instantiate templates used by example
                                                                                                        namespace std {
                                                                                                           %template(IntVector) vector<int>;
                                                                                                           %template(DoubleVector) vector<double>;
                                                                                                        }
                                                                                                        
                                                                                                        // Include the header file with above prototypes
                                                                                                        %include "example.h"
                                                                                                        

                                                                                                        Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                                                                                        >>> from example import *
                                                                                                        >>> iv = IntVector(4)         # Create an vector<int>
                                                                                                        >>> for i in range(0,4):
                                                                                                        ...      iv[i] = i
                                                                                                        >>> average(iv)               # Call method
                                                                                                        1.5
                                                                                                        >>> average([0,1,2,3])        # Call with list
                                                                                                        1.5
                                                                                                        >>> half([1,2,3])             # Half a list
                                                                                                        (0.5,1.0,1.5)
                                                                                                        >>> halve_in_place([1,2,3])   # Oops
                                                                                                        Traceback (most recent call last):
                                                                                                          File "<stdin>", line 1, in ?
                                                                                                        TypeError: Type error. Expected _p_std__vectorTdouble_t
                                                                                                        >>> dv = DoubleVector(4)
                                                                                                        >>> for i in range(0,4):
                                                                                                        ...       dv[i] = i
                                                                                                        >>> halve_in_place(dv)       # Ok
                                                                                                        >>> for i in dv:
                                                                                                        ...       print i
                                                                                                        ...
                                                                                                        0.0
                                                                                                        0.5
                                                                                                        1.0
                                                                                                        1.5
                                                                                                        >>> dv[20] = 4.5
                                                                                                        Traceback (most recent call last):
                                                                                                          File "<stdin>", line 1, in ?
                                                                                                          File "example.py", line 81, in __setitem__
                                                                                                            def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                                                                                        IndexError: vector index out of range
                                                                                                        >>>
                                                                                                        

                                                                                                        This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                                                                                        %include "std_vector.i"
                                                                                                        
                                                                                                        namespace std {
                                                                                                            %template(IntVector) vector<int>;
                                                                                                        }
                                                                                                        
                                                                                                        using namespace std;
                                                                                                        typedef std::vector Vector;
                                                                                                        
                                                                                                        void foo(vector<int> *x, const Vector &x);
                                                                                                        

                                                                                                        Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                                                                                        Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                                                                                        Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                                                                                        8.5 Utility Libraries

                                                                                                        8.5.1 exception.i

                                                                                                        The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                                                                                        SWIG_exception(int code, const char *message)

                                                                                                        Raises an exception in the target language. code is one of the following symbolic constants:

                                                                                                        SWIG_MemoryError
                                                                                                        SWIG_IOError
                                                                                                        SWIG_RuntimeError
                                                                                                        SWIG_IndexError
                                                                                                        SWIG_TypeError
                                                                                                        SWIG_DivisionByZero
                                                                                                        SWIG_OverflowError
                                                                                                        SWIG_SyntaxError
                                                                                                        SWIG_ValueError
                                                                                                        SWIG_SystemError
                                                                                                        

                                                                                                        message is a string indicating more information about the problem.

                                                                                                        The primary use of this module is in writing language-independent exception handlers. For example:

                                                                                                        %include "exception.i"
                                                                                                        %exception std::vector::getitem {
                                                                                                            try {
                                                                                                                $action
                                                                                                            } catch (std::out_of_range& e) {
                                                                                                                SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                                                                            }
                                                                                                        }
                                                                                                        

                                                                                                        ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                                                                                        

                                                                                                        SWIG-1.3 Documentation

                                                                                                        
                                                                                                        

                                                                                                        ---

                                                                                                        Table of Contents

                                                                                                        
                                                                                                        
                                                                                                        SWIG-1.3 Development Documentation
                                                                                                        • Sections
                                                                                                        • SWIG Core Documentation
                                                                                                        • Language Module Documentation
                                                                                                        • Developer Documentation
                                                                                                        • Documentation that has not yet been updated
                                                                                                        1 Preface
                                                                                                        • 1.1 Introduction
                                                                                                        • 1.2 Special Introduction for Version 1.3
                                                                                                        • 1.3 SWIG Versions
                                                                                                        • 1.4 SWIG resources
                                                                                                        • 1.5 Prerequisites
                                                                                                        • 1.6 Organization of this manual
                                                                                                        • 1.7 How to avoid reading the manual
                                                                                                        • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                                                                                          >>> make_upper("hello world")
                                                                                                          'HELLO WORLD'
                                                                                                          >>> attach_header("Hello world")
                                                                                                          'header: Hello world'
                                                                                                          >>>
                                                                                                          

                                                                                                          This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                                                                                          %cstring_output_maxsize(parm, maxparm)

                                                                                                          This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                                                                                          %cstring_output_maxsize(char *path, int maxpath);
                                                                                                          ...
                                                                                                          void get_path(char *path, int maxpath);
                                                                                                          

                                                                                                          In the target language:

                                                                                                          >>> get_path(1024)
                                                                                                          '/home/beazley/Packages/Foo/Bar'
                                                                                                          >>>
                                                                                                          

                                                                                                          This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                                                                                          %cstring_output_withsize(parm, maxparm)

                                                                                                          This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                                                                                          %cstring_output_withsize(char *data, int *maxdata);
                                                                                                          ...
                                                                                                          void get_data(char *data, int *maxdata);
                                                                                                          

                                                                                                          In the target language:

                                                                                                          >>> get_data(1024)
                                                                                                          'x627388912'
                                                                                                          >>> get_data(1024)
                                                                                                          'xyzzy'
                                                                                                          >>>
                                                                                                          

                                                                                                          This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                                                                                          %cstring_output_allocate(parm, release)

                                                                                                          This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                                                                                          void foo(char **s) {
                                                                                                              *s = (char *) malloc(64);
                                                                                                              sprintf(*s, "Hello world\n");
                                                                                                          }
                                                                                                          

                                                                                                          The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                          %cstring_output_allocate(char **s, free(*$1));
                                                                                                          ...
                                                                                                          void foo(char **s);
                                                                                                          

                                                                                                          In the target language:

                                                                                                          >>> foo()
                                                                                                          'Hello world\n'
                                                                                                          >>>
                                                                                                          

                                                                                                          %cstring_output_allocate_size(parm, szparm, release)

                                                                                                          This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                                                                                          void foo(char **s, int *sz) {
                                                                                                              *s = (char *) malloc(64);
                                                                                                              *sz = 64;
                                                                                                              // Write some binary data
                                                                                                              ...
                                                                                                          }
                                                                                                          

                                                                                                          The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                          %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                                                                                          ...
                                                                                                          void foo(char **s, int *slen);
                                                                                                          

                                                                                                          In the target language:

                                                                                                          >>> foo()
                                                                                                          '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                                                                                          >>>
                                                                                                          

                                                                                                          This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                                                                                          char  *get_data(int *len);
                                                                                                          

                                                                                                          You could wrap it with a function like this:

                                                                                                          void my_get_data(char **result, int *len) {
                                                                                                             *result = get_data(len);
                                                                                                          }
                                                                                                          

                                                                                                          Comments:
                                                                                                          • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                                                                                          • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                                                                                          • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                                                                                          • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                                                                                          8.4 C++ Library

                                                                                                          The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                                                                                          8.4.1 std_string.i

                                                                                                          The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                                                                                          %module example
                                                                                                          %include "std_string.i"
                                                                                                          
                                                                                                          std::string foo();
                                                                                                          void        bar(const std::string &x);
                                                                                                          

                                                                                                          In the target language:

                                                                                                          x = foo();                # Returns a string object
                                                                                                          bar("Hello World");       # Pass string as std::string
                                                                                                          

                                                                                                          This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                                                                                          This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                                                                                          %module example
                                                                                                          %include "std_string.i"
                                                                                                          
                                                                                                          using namespace std;
                                                                                                          typedef std::string String;
                                                                                                          ...
                                                                                                          void foo(string s, const String &t);     // std_string typemaps still applied
                                                                                                          

                                                                                                          Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                                                                                          8.4.2 std_vector.i

                                                                                                          The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                                                                                          %module example
                                                                                                          %include "std_vector.i"
                                                                                                          
                                                                                                          namespace std {
                                                                                                             %template(vectori) vector<int>;
                                                                                                             %template(vectord) vector<double>;
                                                                                                          };
                                                                                                          

                                                                                                          When a template vector<X> is instantiated a number of things happen:
                                                                                                          • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                                                                                          • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                                                                                          • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                                                                                          • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                                                                                          • An exception handler for std::out_of_range is defined.
                                                                                                          • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                                                                                          To illustrate the use of this library, consider the following functions:

                                                                                                          /* File : example.h */
                                                                                                          
                                                                                                          #include <vector>
                                                                                                          #include <algorithm>
                                                                                                          #include <functional>
                                                                                                          #include <numeric>
                                                                                                          
                                                                                                          double average(std::vector<int> v) {
                                                                                                              return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                                                                                          }
                                                                                                          
                                                                                                          std::vector<double> half(const std::vector<double>& v) {
                                                                                                              std::vector<double> w(v);
                                                                                                              for (unsigned int i=0; i<w.size(); i++)
                                                                                                                  w[i] /= 2.0;
                                                                                                              return w;
                                                                                                          }
                                                                                                          
                                                                                                          void halve_in_place(std::vector<double>& v) {
                                                                                                              std::transform(v.begin(),v.end(),v.begin(),
                                                                                                                             std::bind2nd(std::divides<double>(),2.0));
                                                                                                          }
                                                                                                          

                                                                                                          To wrap with SWIG, you might write the following:

                                                                                                          %module example
                                                                                                          %{
                                                                                                          #include "example.h"
                                                                                                          %}
                                                                                                          
                                                                                                          %include "std_vector.i"
                                                                                                          // Instantiate templates used by example
                                                                                                          namespace std {
                                                                                                             %template(IntVector) vector<int>;
                                                                                                             %template(DoubleVector) vector<double>;
                                                                                                          }
                                                                                                          
                                                                                                          // Include the header file with above prototypes
                                                                                                          %include "example.h"
                                                                                                          

                                                                                                          Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                                                                                          >>> from example import *
                                                                                                          >>> iv = IntVector(4)         # Create an vector<int>
                                                                                                          >>> for i in range(0,4):
                                                                                                          ...      iv[i] = i
                                                                                                          >>> average(iv)               # Call method
                                                                                                          1.5
                                                                                                          >>> average([0,1,2,3])        # Call with list
                                                                                                          1.5
                                                                                                          >>> half([1,2,3])             # Half a list
                                                                                                          (0.5,1.0,1.5)
                                                                                                          >>> halve_in_place([1,2,3])   # Oops
                                                                                                          Traceback (most recent call last):
                                                                                                            File "<stdin>", line 1, in ?
                                                                                                          TypeError: Type error. Expected _p_std__vectorTdouble_t
                                                                                                          >>> dv = DoubleVector(4)
                                                                                                          >>> for i in range(0,4):
                                                                                                          ...       dv[i] = i
                                                                                                          >>> halve_in_place(dv)       # Ok
                                                                                                          >>> for i in dv:
                                                                                                          ...       print i
                                                                                                          ...
                                                                                                          0.0
                                                                                                          0.5
                                                                                                          1.0
                                                                                                          1.5
                                                                                                          >>> dv[20] = 4.5
                                                                                                          Traceback (most recent call last):
                                                                                                            File "<stdin>", line 1, in ?
                                                                                                            File "example.py", line 81, in __setitem__
                                                                                                              def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                                                                                          IndexError: vector index out of range
                                                                                                          >>>
                                                                                                          

                                                                                                          This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                                                                                          %include "std_vector.i"
                                                                                                          
                                                                                                          namespace std {
                                                                                                              %template(IntVector) vector<int>;
                                                                                                          }
                                                                                                          
                                                                                                          using namespace std;
                                                                                                          typedef std::vector Vector;
                                                                                                          
                                                                                                          void foo(vector<int> *x, const Vector &x);
                                                                                                          

                                                                                                          Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                                                                                          Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                                                                                          Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                                                                                          8.5 Utility Libraries

                                                                                                          8.5.1 exception.i

                                                                                                          The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                                                                                          SWIG_exception(int code, const char *message)

                                                                                                          Raises an exception in the target language. code is one of the following symbolic constants:

                                                                                                          SWIG_MemoryError
                                                                                                          SWIG_IOError
                                                                                                          SWIG_RuntimeError
                                                                                                          SWIG_IndexError
                                                                                                          SWIG_TypeError
                                                                                                          SWIG_DivisionByZero
                                                                                                          SWIG_OverflowError
                                                                                                          SWIG_SyntaxError
                                                                                                          SWIG_ValueError
                                                                                                          SWIG_SystemError
                                                                                                          

                                                                                                          message is a string indicating more information about the problem.

                                                                                                          The primary use of this module is in writing language-independent exception handlers. For example:

                                                                                                          %include "exception.i"
                                                                                                          %exception std::vector::getitem {
                                                                                                              try {
                                                                                                                  $action
                                                                                                              } catch (std::out_of_range& e) {
                                                                                                                  SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                                                                              }
                                                                                                          }
                                                                                                          

                                                                                                          ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                                                                                          

                                                                                                          SWIG-1.3 Documentation

                                                                                                          
                                                                                                          

                                                                                                          ---

                                                                                                          Table of Contents

                                                                                                          
                                                                                                          
                                                                                                          SWIG-1.3 Development Documentation
                                                                                                          • Sections
                                                                                                          • SWIG Core Documentation
                                                                                                          • Language Module Documentation
                                                                                                          • Developer Documentation
                                                                                                          • Documentation that has not yet been updated
                                                                                                          1 Preface
                                                                                                          • 1.1 Introduction
                                                                                                          • 1.2 Special Introduction for Version 1.3
                                                                                                          • 1.3 SWIG Versions
                                                                                                          • 1.4 SWIG resources
                                                                                                          • 1.5 Prerequisites
                                                                                                          • 1.6 Organization of this manual
                                                                                                          • 1.7 How to avoid reading the manual
                                                                                                          • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                                                                                            >>> make_upper("hello world")
                                                                                                            'HELLO WORLD'
                                                                                                            >>> attach_header("Hello world")
                                                                                                            'header: Hello world'
                                                                                                            >>>
                                                                                                            

                                                                                                            This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                                                                                            %cstring_output_maxsize(parm, maxparm)

                                                                                                            This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                                                                                            %cstring_output_maxsize(char *path, int maxpath);
                                                                                                            ...
                                                                                                            void get_path(char *path, int maxpath);
                                                                                                            

                                                                                                            In the target language:

                                                                                                            >>> get_path(1024)
                                                                                                            '/home/beazley/Packages/Foo/Bar'
                                                                                                            >>>
                                                                                                            

                                                                                                            This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                                                                                            %cstring_output_withsize(parm, maxparm)

                                                                                                            This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                                                                                            %cstring_output_withsize(char *data, int *maxdata);
                                                                                                            ...
                                                                                                            void get_data(char *data, int *maxdata);
                                                                                                            

                                                                                                            In the target language:

                                                                                                            >>> get_data(1024)
                                                                                                            'x627388912'
                                                                                                            >>> get_data(1024)
                                                                                                            'xyzzy'
                                                                                                            >>>
                                                                                                            

                                                                                                            This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                                                                                            %cstring_output_allocate(parm, release)

                                                                                                            This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                                                                                            void foo(char **s) {
                                                                                                                *s = (char *) malloc(64);
                                                                                                                sprintf(*s, "Hello world\n");
                                                                                                            }
                                                                                                            

                                                                                                            The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                            %cstring_output_allocate(char **s, free(*$1));
                                                                                                            ...
                                                                                                            void foo(char **s);
                                                                                                            

                                                                                                            In the target language:

                                                                                                            >>> foo()
                                                                                                            'Hello world\n'
                                                                                                            >>>
                                                                                                            

                                                                                                            %cstring_output_allocate_size(parm, szparm, release)

                                                                                                            This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                                                                                            void foo(char **s, int *sz) {
                                                                                                                *s = (char *) malloc(64);
                                                                                                                *sz = 64;
                                                                                                                // Write some binary data
                                                                                                                ...
                                                                                                            }
                                                                                                            

                                                                                                            The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                            %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                                                                                            ...
                                                                                                            void foo(char **s, int *slen);
                                                                                                            

                                                                                                            In the target language:

                                                                                                            >>> foo()
                                                                                                            '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                                                                                            >>>
                                                                                                            

                                                                                                            This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                                                                                            char  *get_data(int *len);
                                                                                                            

                                                                                                            You could wrap it with a function like this:

                                                                                                            void my_get_data(char **result, int *len) {
                                                                                                               *result = get_data(len);
                                                                                                            }
                                                                                                            

                                                                                                            Comments:
                                                                                                            • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                                                                                            • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                                                                                            • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                                                                                            • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                                                                                            8.4 C++ Library

                                                                                                            The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                                                                                            8.4.1 std_string.i

                                                                                                            The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                                                                                            %module example
                                                                                                            %include "std_string.i"
                                                                                                            
                                                                                                            std::string foo();
                                                                                                            void        bar(const std::string &x);
                                                                                                            

                                                                                                            In the target language:

                                                                                                            x = foo();                # Returns a string object
                                                                                                            bar("Hello World");       # Pass string as std::string
                                                                                                            

                                                                                                            This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                                                                                            This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                                                                                            %module example
                                                                                                            %include "std_string.i"
                                                                                                            
                                                                                                            using namespace std;
                                                                                                            typedef std::string String;
                                                                                                            ...
                                                                                                            void foo(string s, const String &t);     // std_string typemaps still applied
                                                                                                            

                                                                                                            Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                                                                                            8.4.2 std_vector.i

                                                                                                            The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                                                                                            %module example
                                                                                                            %include "std_vector.i"
                                                                                                            
                                                                                                            namespace std {
                                                                                                               %template(vectori) vector<int>;
                                                                                                               %template(vectord) vector<double>;
                                                                                                            };
                                                                                                            

                                                                                                            When a template vector<X> is instantiated a number of things happen:
                                                                                                            • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                                                                                            • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                                                                                            • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                                                                                            • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                                                                                            • An exception handler for std::out_of_range is defined.
                                                                                                            • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                                                                                            To illustrate the use of this library, consider the following functions:

                                                                                                            /* File : example.h */
                                                                                                            
                                                                                                            #include <vector>
                                                                                                            #include <algorithm>
                                                                                                            #include <functional>
                                                                                                            #include <numeric>
                                                                                                            
                                                                                                            double average(std::vector<int> v) {
                                                                                                                return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                                                                                            }
                                                                                                            
                                                                                                            std::vector<double> half(const std::vector<double>& v) {
                                                                                                                std::vector<double> w(v);
                                                                                                                for (unsigned int i=0; i<w.size(); i++)
                                                                                                                    w[i] /= 2.0;
                                                                                                                return w;
                                                                                                            }
                                                                                                            
                                                                                                            void halve_in_place(std::vector<double>& v) {
                                                                                                                std::transform(v.begin(),v.end(),v.begin(),
                                                                                                                               std::bind2nd(std::divides<double>(),2.0));
                                                                                                            }
                                                                                                            

                                                                                                            To wrap with SWIG, you might write the following:

                                                                                                            %module example
                                                                                                            %{
                                                                                                            #include "example.h"
                                                                                                            %}
                                                                                                            
                                                                                                            %include "std_vector.i"
                                                                                                            // Instantiate templates used by example
                                                                                                            namespace std {
                                                                                                               %template(IntVector) vector<int>;
                                                                                                               %template(DoubleVector) vector<double>;
                                                                                                            }
                                                                                                            
                                                                                                            // Include the header file with above prototypes
                                                                                                            %include "example.h"
                                                                                                            

                                                                                                            Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                                                                                            >>> from example import *
                                                                                                            >>> iv = IntVector(4)         # Create an vector<int>
                                                                                                            >>> for i in range(0,4):
                                                                                                            ...      iv[i] = i
                                                                                                            >>> average(iv)               # Call method
                                                                                                            1.5
                                                                                                            >>> average([0,1,2,3])        # Call with list
                                                                                                            1.5
                                                                                                            >>> half([1,2,3])             # Half a list
                                                                                                            (0.5,1.0,1.5)
                                                                                                            >>> halve_in_place([1,2,3])   # Oops
                                                                                                            Traceback (most recent call last):
                                                                                                              File "<stdin>", line 1, in ?
                                                                                                            TypeError: Type error. Expected _p_std__vectorTdouble_t
                                                                                                            >>> dv = DoubleVector(4)
                                                                                                            >>> for i in range(0,4):
                                                                                                            ...       dv[i] = i
                                                                                                            >>> halve_in_place(dv)       # Ok
                                                                                                            >>> for i in dv:
                                                                                                            ...       print i
                                                                                                            ...
                                                                                                            0.0
                                                                                                            0.5
                                                                                                            1.0
                                                                                                            1.5
                                                                                                            >>> dv[20] = 4.5
                                                                                                            Traceback (most recent call last):
                                                                                                              File "<stdin>", line 1, in ?
                                                                                                              File "example.py", line 81, in __setitem__
                                                                                                                def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                                                                                            IndexError: vector index out of range
                                                                                                            >>>
                                                                                                            

                                                                                                            This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                                                                                            %include "std_vector.i"
                                                                                                            
                                                                                                            namespace std {
                                                                                                                %template(IntVector) vector<int>;
                                                                                                            }
                                                                                                            
                                                                                                            using namespace std;
                                                                                                            typedef std::vector Vector;
                                                                                                            
                                                                                                            void foo(vector<int> *x, const Vector &x);
                                                                                                            

                                                                                                            Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                                                                                            Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                                                                                            Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                                                                                            8.5 Utility Libraries

                                                                                                            8.5.1 exception.i

                                                                                                            The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                                                                                            SWIG_exception(int code, const char *message)

                                                                                                            Raises an exception in the target language. code is one of the following symbolic constants:

                                                                                                            SWIG_MemoryError
                                                                                                            SWIG_IOError
                                                                                                            SWIG_RuntimeError
                                                                                                            SWIG_IndexError
                                                                                                            SWIG_TypeError
                                                                                                            SWIG_DivisionByZero
                                                                                                            SWIG_OverflowError
                                                                                                            SWIG_SyntaxError
                                                                                                            SWIG_ValueError
                                                                                                            SWIG_SystemError
                                                                                                            

                                                                                                            message is a string indicating more information about the problem.

                                                                                                            The primary use of this module is in writing language-independent exception handlers. For example:

                                                                                                            %include "exception.i"
                                                                                                            %exception std::vector::getitem {
                                                                                                                try {
                                                                                                                    $action
                                                                                                                } catch (std::out_of_range& e) {
                                                                                                                    SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                                                                                }
                                                                                                            }
                                                                                                            

                                                                                                            ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                                                                                            

                                                                                                            SWIG-1.3 Documentation

                                                                                                            
                                                                                                            

                                                                                                            ---

                                                                                                            Table of Contents

                                                                                                            
                                                                                                            
                                                                                                            SWIG-1.3 Development Documentation
                                                                                                            • Sections
                                                                                                            • SWIG Core Documentation
                                                                                                            • Language Module Documentation
                                                                                                            • Developer Documentation
                                                                                                            • Documentation that has not yet been updated
                                                                                                            1 Preface
                                                                                                            • 1.1 Introduction
                                                                                                            • 1.2 Special Introduction for Version 1.3
                                                                                                            • 1.3 SWIG Versions
                                                                                                            • 1.4 SWIG resources
                                                                                                            • 1.5 Prerequisites
                                                                                                            • 1.6 Organization of this manual
                                                                                                            • 1.7 How to avoid reading the manual
                                                                                                            • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                                                                                              >>> make_upper("hello world")
                                                                                                              'HELLO WORLD'
                                                                                                              >>> attach_header("Hello world")
                                                                                                              'header: Hello world'
                                                                                                              >>>
                                                                                                              

                                                                                                              This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                                                                                              %cstring_output_maxsize(parm, maxparm)

                                                                                                              This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                                                                                              %cstring_output_maxsize(char *path, int maxpath);
                                                                                                              ...
                                                                                                              void get_path(char *path, int maxpath);
                                                                                                              

                                                                                                              In the target language:

                                                                                                              >>> get_path(1024)
                                                                                                              '/home/beazley/Packages/Foo/Bar'
                                                                                                              >>>
                                                                                                              

                                                                                                              This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                                                                                              %cstring_output_withsize(parm, maxparm)

                                                                                                              This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                                                                                              %cstring_output_withsize(char *data, int *maxdata);
                                                                                                              ...
                                                                                                              void get_data(char *data, int *maxdata);
                                                                                                              

                                                                                                              In the target language:

                                                                                                              >>> get_data(1024)
                                                                                                              'x627388912'
                                                                                                              >>> get_data(1024)
                                                                                                              'xyzzy'
                                                                                                              >>>
                                                                                                              

                                                                                                              This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                                                                                              %cstring_output_allocate(parm, release)

                                                                                                              This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                                                                                              void foo(char **s) {
                                                                                                                  *s = (char *) malloc(64);
                                                                                                                  sprintf(*s, "Hello world\n");
                                                                                                              }
                                                                                                              

                                                                                                              The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                              %cstring_output_allocate(char **s, free(*$1));
                                                                                                              ...
                                                                                                              void foo(char **s);
                                                                                                              

                                                                                                              In the target language:

                                                                                                              >>> foo()
                                                                                                              'Hello world\n'
                                                                                                              >>>
                                                                                                              

                                                                                                              %cstring_output_allocate_size(parm, szparm, release)

                                                                                                              This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                                                                                              void foo(char **s, int *sz) {
                                                                                                                  *s = (char *) malloc(64);
                                                                                                                  *sz = 64;
                                                                                                                  // Write some binary data
                                                                                                                  ...
                                                                                                              }
                                                                                                              

                                                                                                              The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                              %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                                                                                              ...
                                                                                                              void foo(char **s, int *slen);
                                                                                                              

                                                                                                              In the target language:

                                                                                                              >>> foo()
                                                                                                              '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                                                                                              >>>
                                                                                                              

                                                                                                              This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                                                                                              char  *get_data(int *len);
                                                                                                              

                                                                                                              You could wrap it with a function like this:

                                                                                                              void my_get_data(char **result, int *len) {
                                                                                                                 *result = get_data(len);
                                                                                                              }
                                                                                                              

                                                                                                              Comments:
                                                                                                              • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                                                                                              • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                                                                                              • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                                                                                              • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                                                                                              8.4 C++ Library

                                                                                                              The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                                                                                              8.4.1 std_string.i

                                                                                                              The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                                                                                              %module example
                                                                                                              %include "std_string.i"
                                                                                                              
                                                                                                              std::string foo();
                                                                                                              void        bar(const std::string &x);
                                                                                                              

                                                                                                              In the target language:

                                                                                                              x = foo();                # Returns a string object
                                                                                                              bar("Hello World");       # Pass string as std::string
                                                                                                              

                                                                                                              This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                                                                                              This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                                                                                              %module example
                                                                                                              %include "std_string.i"
                                                                                                              
                                                                                                              using namespace std;
                                                                                                              typedef std::string String;
                                                                                                              ...
                                                                                                              void foo(string s, const String &t);     // std_string typemaps still applied
                                                                                                              

                                                                                                              Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                                                                                              8.4.2 std_vector.i

                                                                                                              The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                                                                                              %module example
                                                                                                              %include "std_vector.i"
                                                                                                              
                                                                                                              namespace std {
                                                                                                                 %template(vectori) vector<int>;
                                                                                                                 %template(vectord) vector<double>;
                                                                                                              };
                                                                                                              

                                                                                                              When a template vector<X> is instantiated a number of things happen:
                                                                                                              • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                                                                                              • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                                                                                              • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                                                                                              • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                                                                                              • An exception handler for std::out_of_range is defined.
                                                                                                              • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                                                                                              To illustrate the use of this library, consider the following functions:

                                                                                                              /* File : example.h */
                                                                                                              
                                                                                                              #include <vector>
                                                                                                              #include <algorithm>
                                                                                                              #include <functional>
                                                                                                              #include <numeric>
                                                                                                              
                                                                                                              double average(std::vector<int> v) {
                                                                                                                  return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                                                                                              }
                                                                                                              
                                                                                                              std::vector<double> half(const std::vector<double>& v) {
                                                                                                                  std::vector<double> w(v);
                                                                                                                  for (unsigned int i=0; i<w.size(); i++)
                                                                                                                      w[i] /= 2.0;
                                                                                                                  return w;
                                                                                                              }
                                                                                                              
                                                                                                              void halve_in_place(std::vector<double>& v) {
                                                                                                                  std::transform(v.begin(),v.end(),v.begin(),
                                                                                                                                 std::bind2nd(std::divides<double>(),2.0));
                                                                                                              }
                                                                                                              

                                                                                                              To wrap with SWIG, you might write the following:

                                                                                                              %module example
                                                                                                              %{
                                                                                                              #include "example.h"
                                                                                                              %}
                                                                                                              
                                                                                                              %include "std_vector.i"
                                                                                                              // Instantiate templates used by example
                                                                                                              namespace std {
                                                                                                                 %template(IntVector) vector<int>;
                                                                                                                 %template(DoubleVector) vector<double>;
                                                                                                              }
                                                                                                              
                                                                                                              // Include the header file with above prototypes
                                                                                                              %include "example.h"
                                                                                                              

                                                                                                              Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                                                                                              >>> from example import *
                                                                                                              >>> iv = IntVector(4)         # Create an vector<int>
                                                                                                              >>> for i in range(0,4):
                                                                                                              ...      iv[i] = i
                                                                                                              >>> average(iv)               # Call method
                                                                                                              1.5
                                                                                                              >>> average([0,1,2,3])        # Call with list
                                                                                                              1.5
                                                                                                              >>> half([1,2,3])             # Half a list
                                                                                                              (0.5,1.0,1.5)
                                                                                                              >>> halve_in_place([1,2,3])   # Oops
                                                                                                              Traceback (most recent call last):
                                                                                                                File "<stdin>", line 1, in ?
                                                                                                              TypeError: Type error. Expected _p_std__vectorTdouble_t
                                                                                                              >>> dv = DoubleVector(4)
                                                                                                              >>> for i in range(0,4):
                                                                                                              ...       dv[i] = i
                                                                                                              >>> halve_in_place(dv)       # Ok
                                                                                                              >>> for i in dv:
                                                                                                              ...       print i
                                                                                                              ...
                                                                                                              0.0
                                                                                                              0.5
                                                                                                              1.0
                                                                                                              1.5
                                                                                                              >>> dv[20] = 4.5
                                                                                                              Traceback (most recent call last):
                                                                                                                File "<stdin>", line 1, in ?
                                                                                                                File "example.py", line 81, in __setitem__
                                                                                                                  def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                                                                                              IndexError: vector index out of range
                                                                                                              >>>
                                                                                                              

                                                                                                              This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                                                                                              %include "std_vector.i"
                                                                                                              
                                                                                                              namespace std {
                                                                                                                  %template(IntVector) vector<int>;
                                                                                                              }
                                                                                                              
                                                                                                              using namespace std;
                                                                                                              typedef std::vector Vector;
                                                                                                              
                                                                                                              void foo(vector<int> *x, const Vector &x);
                                                                                                              

                                                                                                              Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                                                                                              Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                                                                                              Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                                                                                              8.5 Utility Libraries

                                                                                                              8.5.1 exception.i

                                                                                                              The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                                                                                              SWIG_exception(int code, const char *message)

                                                                                                              Raises an exception in the target language. code is one of the following symbolic constants:

                                                                                                              SWIG_MemoryError
                                                                                                              SWIG_IOError
                                                                                                              SWIG_RuntimeError
                                                                                                              SWIG_IndexError
                                                                                                              SWIG_TypeError
                                                                                                              SWIG_DivisionByZero
                                                                                                              SWIG_OverflowError
                                                                                                              SWIG_SyntaxError
                                                                                                              SWIG_ValueError
                                                                                                              SWIG_SystemError
                                                                                                              

                                                                                                              message is a string indicating more information about the problem.

                                                                                                              The primary use of this module is in writing language-independent exception handlers. For example:

                                                                                                              %include "exception.i"
                                                                                                              %exception std::vector::getitem {
                                                                                                                  try {
                                                                                                                      $action
                                                                                                                  } catch (std::out_of_range& e) {
                                                                                                                      SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                                                                                  }
                                                                                                              }
                                                                                                              

                                                                                                              ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                                                                                              

                                                                                                              SWIG-1.3 Documentation

                                                                                                              
                                                                                                              

                                                                                                              ---

                                                                                                              Table of Contents

                                                                                                              
                                                                                                              
                                                                                                              SWIG-1.3 Development Documentation
                                                                                                              • Sections
                                                                                                              • SWIG Core Documentation
                                                                                                              • Language Module Documentation
                                                                                                              • Developer Documentation
                                                                                                              • Documentation that has not yet been updated
                                                                                                              1 Preface
                                                                                                              • 1.1 Introduction
                                                                                                              • 1.2 Special Introduction for Version 1.3
                                                                                                              • 1.3 SWIG Versions
                                                                                                              • 1.4 SWIG resources
                                                                                                              • 1.5 Prerequisites
                                                                                                              • 1.6 Organization of this manual
                                                                                                              • 1.7 How to avoid reading the manual
                                                                                                              • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                                                                                                >>> make_upper("hello world")
                                                                                                                'HELLO WORLD'
                                                                                                                >>> attach_header("Hello world")
                                                                                                                'header: Hello world'
                                                                                                                >>>
                                                                                                                

                                                                                                                This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                                                                                                %cstring_output_maxsize(parm, maxparm)

                                                                                                                This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                                                                                                %cstring_output_maxsize(char *path, int maxpath);
                                                                                                                ...
                                                                                                                void get_path(char *path, int maxpath);
                                                                                                                

                                                                                                                In the target language:

                                                                                                                >>> get_path(1024)
                                                                                                                '/home/beazley/Packages/Foo/Bar'
                                                                                                                >>>
                                                                                                                

                                                                                                                This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                                                                                                %cstring_output_withsize(parm, maxparm)

                                                                                                                This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                                                                                                %cstring_output_withsize(char *data, int *maxdata);
                                                                                                                ...
                                                                                                                void get_data(char *data, int *maxdata);
                                                                                                                

                                                                                                                In the target language:

                                                                                                                >>> get_data(1024)
                                                                                                                'x627388912'
                                                                                                                >>> get_data(1024)
                                                                                                                'xyzzy'
                                                                                                                >>>
                                                                                                                

                                                                                                                This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                                                                                                %cstring_output_allocate(parm, release)

                                                                                                                This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                                                                                                void foo(char **s) {
                                                                                                                    *s = (char *) malloc(64);
                                                                                                                    sprintf(*s, "Hello world\n");
                                                                                                                }
                                                                                                                

                                                                                                                The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                                %cstring_output_allocate(char **s, free(*$1));
                                                                                                                ...
                                                                                                                void foo(char **s);
                                                                                                                

                                                                                                                In the target language:

                                                                                                                >>> foo()
                                                                                                                'Hello world\n'
                                                                                                                >>>
                                                                                                                

                                                                                                                %cstring_output_allocate_size(parm, szparm, release)

                                                                                                                This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                                                                                                void foo(char **s, int *sz) {
                                                                                                                    *s = (char *) malloc(64);
                                                                                                                    *sz = 64;
                                                                                                                    // Write some binary data
                                                                                                                    ...
                                                                                                                }
                                                                                                                

                                                                                                                The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                                %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                                                                                                ...
                                                                                                                void foo(char **s, int *slen);
                                                                                                                

                                                                                                                In the target language:

                                                                                                                >>> foo()
                                                                                                                '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                                                                                                >>>
                                                                                                                

                                                                                                                This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                                                                                                char  *get_data(int *len);
                                                                                                                

                                                                                                                You could wrap it with a function like this:

                                                                                                                void my_get_data(char **result, int *len) {
                                                                                                                   *result = get_data(len);
                                                                                                                }
                                                                                                                

                                                                                                                Comments:
                                                                                                                • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                                                                                                • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                                                                                                • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                                                                                                • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                                                                                                8.4 C++ Library

                                                                                                                The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                                                                                                8.4.1 std_string.i

                                                                                                                The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                                                                                                %module example
                                                                                                                %include "std_string.i"
                                                                                                                
                                                                                                                std::string foo();
                                                                                                                void        bar(const std::string &x);
                                                                                                                

                                                                                                                In the target language:

                                                                                                                x = foo();                # Returns a string object
                                                                                                                bar("Hello World");       # Pass string as std::string
                                                                                                                

                                                                                                                This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                                                                                                This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                                                                                                %module example
                                                                                                                %include "std_string.i"
                                                                                                                
                                                                                                                using namespace std;
                                                                                                                typedef std::string String;
                                                                                                                ...
                                                                                                                void foo(string s, const String &t);     // std_string typemaps still applied
                                                                                                                

                                                                                                                Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                                                                                                8.4.2 std_vector.i

                                                                                                                The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                                                                                                %module example
                                                                                                                %include "std_vector.i"
                                                                                                                
                                                                                                                namespace std {
                                                                                                                   %template(vectori) vector<int>;
                                                                                                                   %template(vectord) vector<double>;
                                                                                                                };
                                                                                                                

                                                                                                                When a template vector<X> is instantiated a number of things happen:
                                                                                                                • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                                                                                                • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                                                                                                • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                                                                                                • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                                                                                                • An exception handler for std::out_of_range is defined.
                                                                                                                • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                                                                                                To illustrate the use of this library, consider the following functions:

                                                                                                                /* File : example.h */
                                                                                                                
                                                                                                                #include <vector>
                                                                                                                #include <algorithm>
                                                                                                                #include <functional>
                                                                                                                #include <numeric>
                                                                                                                
                                                                                                                double average(std::vector<int> v) {
                                                                                                                    return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                                                                                                }
                                                                                                                
                                                                                                                std::vector<double> half(const std::vector<double>& v) {
                                                                                                                    std::vector<double> w(v);
                                                                                                                    for (unsigned int i=0; i<w.size(); i++)
                                                                                                                        w[i] /= 2.0;
                                                                                                                    return w;
                                                                                                                }
                                                                                                                
                                                                                                                void halve_in_place(std::vector<double>& v) {
                                                                                                                    std::transform(v.begin(),v.end(),v.begin(),
                                                                                                                                   std::bind2nd(std::divides<double>(),2.0));
                                                                                                                }
                                                                                                                

                                                                                                                To wrap with SWIG, you might write the following:

                                                                                                                %module example
                                                                                                                %{
                                                                                                                #include "example.h"
                                                                                                                %}
                                                                                                                
                                                                                                                %include "std_vector.i"
                                                                                                                // Instantiate templates used by example
                                                                                                                namespace std {
                                                                                                                   %template(IntVector) vector<int>;
                                                                                                                   %template(DoubleVector) vector<double>;
                                                                                                                }
                                                                                                                
                                                                                                                // Include the header file with above prototypes
                                                                                                                %include "example.h"
                                                                                                                

                                                                                                                Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                                                                                                >>> from example import *
                                                                                                                >>> iv = IntVector(4)         # Create an vector<int>
                                                                                                                >>> for i in range(0,4):
                                                                                                                ...      iv[i] = i
                                                                                                                >>> average(iv)               # Call method
                                                                                                                1.5
                                                                                                                >>> average([0,1,2,3])        # Call with list
                                                                                                                1.5
                                                                                                                >>> half([1,2,3])             # Half a list
                                                                                                                (0.5,1.0,1.5)
                                                                                                                >>> halve_in_place([1,2,3])   # Oops
                                                                                                                Traceback (most recent call last):
                                                                                                                  File "<stdin>", line 1, in ?
                                                                                                                TypeError: Type error. Expected _p_std__vectorTdouble_t
                                                                                                                >>> dv = DoubleVector(4)
                                                                                                                >>> for i in range(0,4):
                                                                                                                ...       dv[i] = i
                                                                                                                >>> halve_in_place(dv)       # Ok
                                                                                                                >>> for i in dv:
                                                                                                                ...       print i
                                                                                                                ...
                                                                                                                0.0
                                                                                                                0.5
                                                                                                                1.0
                                                                                                                1.5
                                                                                                                >>> dv[20] = 4.5
                                                                                                                Traceback (most recent call last):
                                                                                                                  File "<stdin>", line 1, in ?
                                                                                                                  File "example.py", line 81, in __setitem__
                                                                                                                    def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                                                                                                IndexError: vector index out of range
                                                                                                                >>>
                                                                                                                

                                                                                                                This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                                                                                                %include "std_vector.i"
                                                                                                                
                                                                                                                namespace std {
                                                                                                                    %template(IntVector) vector<int>;
                                                                                                                }
                                                                                                                
                                                                                                                using namespace std;
                                                                                                                typedef std::vector Vector;
                                                                                                                
                                                                                                                void foo(vector<int> *x, const Vector &x);
                                                                                                                

                                                                                                                Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                                                                                                Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                                                                                                Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                                                                                                8.5 Utility Libraries

                                                                                                                8.5.1 exception.i

                                                                                                                The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                                                                                                SWIG_exception(int code, const char *message)

                                                                                                                Raises an exception in the target language. code is one of the following symbolic constants:

                                                                                                                SWIG_MemoryError
                                                                                                                SWIG_IOError
                                                                                                                SWIG_RuntimeError
                                                                                                                SWIG_IndexError
                                                                                                                SWIG_TypeError
                                                                                                                SWIG_DivisionByZero
                                                                                                                SWIG_OverflowError
                                                                                                                SWIG_SyntaxError
                                                                                                                SWIG_ValueError
                                                                                                                SWIG_SystemError
                                                                                                                

                                                                                                                message is a string indicating more information about the problem.

                                                                                                                The primary use of this module is in writing language-independent exception handlers. For example:

                                                                                                                %include "exception.i"
                                                                                                                %exception std::vector::getitem {
                                                                                                                    try {
                                                                                                                        $action
                                                                                                                    } catch (std::out_of_range& e) {
                                                                                                                        SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                                                                                    }
                                                                                                                }
                                                                                                                

                                                                                                                ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                                                                                                

                                                                                                                SWIG-1.3 Documentation

                                                                                                                
                                                                                                                

                                                                                                                ---

                                                                                                                Table of Contents

                                                                                                                
                                                                                                                
                                                                                                                SWIG-1.3 Development Documentation
                                                                                                                • Sections
                                                                                                                • SWIG Core Documentation
                                                                                                                • Language Module Documentation
                                                                                                                • Developer Documentation
                                                                                                                • Documentation that has not yet been updated
                                                                                                                1 Preface
                                                                                                                • 1.1 Introduction
                                                                                                                • 1.2 Special Introduction for Version 1.3
                                                                                                                • 1.3 SWIG Versions
                                                                                                                • 1.4 SWIG resources
                                                                                                                • 1.5 Prerequisites
                                                                                                                • 1.6 Organization of this manual
                                                                                                                • 1.7 How to avoid reading the manual
                                                                                                                • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                                                                                                  >>> make_upper("hello world")
                                                                                                                  'HELLO WORLD'
                                                                                                                  >>> attach_header("Hello world")
                                                                                                                  'header: Hello world'
                                                                                                                  >>>
                                                                                                                  

                                                                                                                  This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                                                                                                  %cstring_output_maxsize(parm, maxparm)

                                                                                                                  This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                                                                                                  %cstring_output_maxsize(char *path, int maxpath);
                                                                                                                  ...
                                                                                                                  void get_path(char *path, int maxpath);
                                                                                                                  

                                                                                                                  In the target language:

                                                                                                                  >>> get_path(1024)
                                                                                                                  '/home/beazley/Packages/Foo/Bar'
                                                                                                                  >>>
                                                                                                                  

                                                                                                                  This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                                                                                                  %cstring_output_withsize(parm, maxparm)

                                                                                                                  This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                                                                                                  %cstring_output_withsize(char *data, int *maxdata);
                                                                                                                  ...
                                                                                                                  void get_data(char *data, int *maxdata);
                                                                                                                  

                                                                                                                  In the target language:

                                                                                                                  >>> get_data(1024)
                                                                                                                  'x627388912'
                                                                                                                  >>> get_data(1024)
                                                                                                                  'xyzzy'
                                                                                                                  >>>
                                                                                                                  

                                                                                                                  This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                                                                                                  %cstring_output_allocate(parm, release)

                                                                                                                  This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                                                                                                  void foo(char **s) {
                                                                                                                      *s = (char *) malloc(64);
                                                                                                                      sprintf(*s, "Hello world\n");
                                                                                                                  }
                                                                                                                  

                                                                                                                  The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                                  %cstring_output_allocate(char **s, free(*$1));
                                                                                                                  ...
                                                                                                                  void foo(char **s);
                                                                                                                  

                                                                                                                  In the target language:

                                                                                                                  >>> foo()
                                                                                                                  'Hello world\n'
                                                                                                                  >>>
                                                                                                                  

                                                                                                                  %cstring_output_allocate_size(parm, szparm, release)

                                                                                                                  This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                                                                                                  void foo(char **s, int *sz) {
                                                                                                                      *s = (char *) malloc(64);
                                                                                                                      *sz = 64;
                                                                                                                      // Write some binary data
                                                                                                                      ...
                                                                                                                  }
                                                                                                                  

                                                                                                                  The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                                  %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                                                                                                  ...
                                                                                                                  void foo(char **s, int *slen);
                                                                                                                  

                                                                                                                  In the target language:

                                                                                                                  >>> foo()
                                                                                                                  '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                                                                                                  >>>
                                                                                                                  

                                                                                                                  This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                                                                                                  char  *get_data(int *len);
                                                                                                                  

                                                                                                                  You could wrap it with a function like this:

                                                                                                                  void my_get_data(char **result, int *len) {
                                                                                                                     *result = get_data(len);
                                                                                                                  }
                                                                                                                  

                                                                                                                  Comments:
                                                                                                                  • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                                                                                                  • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                                                                                                  • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                                                                                                  • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                                                                                                  8.4 C++ Library

                                                                                                                  The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                                                                                                  8.4.1 std_string.i

                                                                                                                  The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                                                                                                  %module example
                                                                                                                  %include "std_string.i"
                                                                                                                  
                                                                                                                  std::string foo();
                                                                                                                  void        bar(const std::string &x);
                                                                                                                  

                                                                                                                  In the target language:

                                                                                                                  x = foo();                # Returns a string object
                                                                                                                  bar("Hello World");       # Pass string as std::string
                                                                                                                  

                                                                                                                  This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                                                                                                  This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                                                                                                  %module example
                                                                                                                  %include "std_string.i"
                                                                                                                  
                                                                                                                  using namespace std;
                                                                                                                  typedef std::string String;
                                                                                                                  ...
                                                                                                                  void foo(string s, const String &t);     // std_string typemaps still applied
                                                                                                                  

                                                                                                                  Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                                                                                                  8.4.2 std_vector.i

                                                                                                                  The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                                                                                                  %module example
                                                                                                                  %include "std_vector.i"
                                                                                                                  
                                                                                                                  namespace std {
                                                                                                                     %template(vectori) vector<int>;
                                                                                                                     %template(vectord) vector<double>;
                                                                                                                  };
                                                                                                                  

                                                                                                                  When a template vector<X> is instantiated a number of things happen:
                                                                                                                  • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                                                                                                  • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                                                                                                  • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                                                                                                  • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                                                                                                  • An exception handler for std::out_of_range is defined.
                                                                                                                  • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                                                                                                  To illustrate the use of this library, consider the following functions:

                                                                                                                  /* File : example.h */
                                                                                                                  
                                                                                                                  #include <vector>
                                                                                                                  #include <algorithm>
                                                                                                                  #include <functional>
                                                                                                                  #include <numeric>
                                                                                                                  
                                                                                                                  double average(std::vector<int> v) {
                                                                                                                      return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                                                                                                  }
                                                                                                                  
                                                                                                                  std::vector<double> half(const std::vector<double>& v) {
                                                                                                                      std::vector<double> w(v);
                                                                                                                      for (unsigned int i=0; i<w.size(); i++)
                                                                                                                          w[i] /= 2.0;
                                                                                                                      return w;
                                                                                                                  }
                                                                                                                  
                                                                                                                  void halve_in_place(std::vector<double>& v) {
                                                                                                                      std::transform(v.begin(),v.end(),v.begin(),
                                                                                                                                     std::bind2nd(std::divides<double>(),2.0));
                                                                                                                  }
                                                                                                                  

                                                                                                                  To wrap with SWIG, you might write the following:

                                                                                                                  %module example
                                                                                                                  %{
                                                                                                                  #include "example.h"
                                                                                                                  %}
                                                                                                                  
                                                                                                                  %include "std_vector.i"
                                                                                                                  // Instantiate templates used by example
                                                                                                                  namespace std {
                                                                                                                     %template(IntVector) vector<int>;
                                                                                                                     %template(DoubleVector) vector<double>;
                                                                                                                  }
                                                                                                                  
                                                                                                                  // Include the header file with above prototypes
                                                                                                                  %include "example.h"
                                                                                                                  

                                                                                                                  Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                                                                                                  >>> from example import *
                                                                                                                  >>> iv = IntVector(4)         # Create an vector<int>
                                                                                                                  >>> for i in range(0,4):
                                                                                                                  ...      iv[i] = i
                                                                                                                  >>> average(iv)               # Call method
                                                                                                                  1.5
                                                                                                                  >>> average([0,1,2,3])        # Call with list
                                                                                                                  1.5
                                                                                                                  >>> half([1,2,3])             # Half a list
                                                                                                                  (0.5,1.0,1.5)
                                                                                                                  >>> halve_in_place([1,2,3])   # Oops
                                                                                                                  Traceback (most recent call last):
                                                                                                                    File "<stdin>", line 1, in ?
                                                                                                                  TypeError: Type error. Expected _p_std__vectorTdouble_t
                                                                                                                  >>> dv = DoubleVector(4)
                                                                                                                  >>> for i in range(0,4):
                                                                                                                  ...       dv[i] = i
                                                                                                                  >>> halve_in_place(dv)       # Ok
                                                                                                                  >>> for i in dv:
                                                                                                                  ...       print i
                                                                                                                  ...
                                                                                                                  0.0
                                                                                                                  0.5
                                                                                                                  1.0
                                                                                                                  1.5
                                                                                                                  >>> dv[20] = 4.5
                                                                                                                  Traceback (most recent call last):
                                                                                                                    File "<stdin>", line 1, in ?
                                                                                                                    File "example.py", line 81, in __setitem__
                                                                                                                      def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                                                                                                  IndexError: vector index out of range
                                                                                                                  >>>
                                                                                                                  

                                                                                                                  This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                                                                                                  %include "std_vector.i"
                                                                                                                  
                                                                                                                  namespace std {
                                                                                                                      %template(IntVector) vector<int>;
                                                                                                                  }
                                                                                                                  
                                                                                                                  using namespace std;
                                                                                                                  typedef std::vector Vector;
                                                                                                                  
                                                                                                                  void foo(vector<int> *x, const Vector &x);
                                                                                                                  

                                                                                                                  Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                                                                                                  Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                                                                                                  Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                                                                                                  8.5 Utility Libraries

                                                                                                                  8.5.1 exception.i

                                                                                                                  The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                                                                                                  SWIG_exception(int code, const char *message)

                                                                                                                  Raises an exception in the target language. code is one of the following symbolic constants:

                                                                                                                  SWIG_MemoryError
                                                                                                                  SWIG_IOError
                                                                                                                  SWIG_RuntimeError
                                                                                                                  SWIG_IndexError
                                                                                                                  SWIG_TypeError
                                                                                                                  SWIG_DivisionByZero
                                                                                                                  SWIG_OverflowError
                                                                                                                  SWIG_SyntaxError
                                                                                                                  SWIG_ValueError
                                                                                                                  SWIG_SystemError
                                                                                                                  

                                                                                                                  message is a string indicating more information about the problem.

                                                                                                                  The primary use of this module is in writing language-independent exception handlers. For example:

                                                                                                                  %include "exception.i"
                                                                                                                  %exception std::vector::getitem {
                                                                                                                      try {
                                                                                                                          $action
                                                                                                                      } catch (std::out_of_range& e) {
                                                                                                                          SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                                                                                      }
                                                                                                                  }
                                                                                                                  

                                                                                                                  ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                                                                                                  

                                                                                                                  SWIG-1.3 Documentation

                                                                                                                  
                                                                                                                  

                                                                                                                  ---

                                                                                                                  Table of Contents

                                                                                                                  
                                                                                                                  
                                                                                                                  SWIG-1.3 Development Documentation
                                                                                                                  • Sections
                                                                                                                  • SWIG Core Documentation
                                                                                                                  • Language Module Documentation
                                                                                                                  • Developer Documentation
                                                                                                                  • Documentation that has not yet been updated
                                                                                                                  1 Preface
                                                                                                                  • 1.1 Introduction
                                                                                                                  • 1.2 Special Introduction for Version 1.3
                                                                                                                  • 1.3 SWIG Versions
                                                                                                                  • 1.4 SWIG resources
                                                                                                                  • 1.5 Prerequisites
                                                                                                                  • 1.6 Organization of this manual
                                                                                                                  • 1.7 How to avoid reading the manual
                                                                                                                  • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                                                                                                    >>> make_upper("hello world")
                                                                                                                    'HELLO WORLD'
                                                                                                                    >>> attach_header("Hello world")
                                                                                                                    'header: Hello world'
                                                                                                                    >>>
                                                                                                                    

                                                                                                                    This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                                                                                                    %cstring_output_maxsize(parm, maxparm)

                                                                                                                    This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                                                                                                    %cstring_output_maxsize(char *path, int maxpath);
                                                                                                                    ...
                                                                                                                    void get_path(char *path, int maxpath);
                                                                                                                    

                                                                                                                    In the target language:

                                                                                                                    >>> get_path(1024)
                                                                                                                    '/home/beazley/Packages/Foo/Bar'
                                                                                                                    >>>
                                                                                                                    

                                                                                                                    This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                                                                                                    %cstring_output_withsize(parm, maxparm)

                                                                                                                    This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                                                                                                    %cstring_output_withsize(char *data, int *maxdata);
                                                                                                                    ...
                                                                                                                    void get_data(char *data, int *maxdata);
                                                                                                                    

                                                                                                                    In the target language:

                                                                                                                    >>> get_data(1024)
                                                                                                                    'x627388912'
                                                                                                                    >>> get_data(1024)
                                                                                                                    'xyzzy'
                                                                                                                    >>>
                                                                                                                    

                                                                                                                    This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                                                                                                    %cstring_output_allocate(parm, release)

                                                                                                                    This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                                                                                                    void foo(char **s) {
                                                                                                                        *s = (char *) malloc(64);
                                                                                                                        sprintf(*s, "Hello world\n");
                                                                                                                    }
                                                                                                                    

                                                                                                                    The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                                    %cstring_output_allocate(char **s, free(*$1));
                                                                                                                    ...
                                                                                                                    void foo(char **s);
                                                                                                                    

                                                                                                                    In the target language:

                                                                                                                    >>> foo()
                                                                                                                    'Hello world\n'
                                                                                                                    >>>
                                                                                                                    

                                                                                                                    %cstring_output_allocate_size(parm, szparm, release)

                                                                                                                    This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                                                                                                    void foo(char **s, int *sz) {
                                                                                                                        *s = (char *) malloc(64);
                                                                                                                        *sz = 64;
                                                                                                                        // Write some binary data
                                                                                                                        ...
                                                                                                                    }
                                                                                                                    

                                                                                                                    The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                                    %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                                                                                                    ...
                                                                                                                    void foo(char **s, int *slen);
                                                                                                                    

                                                                                                                    In the target language:

                                                                                                                    >>> foo()
                                                                                                                    '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                                                                                                    >>>
                                                                                                                    

                                                                                                                    This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                                                                                                    char  *get_data(int *len);
                                                                                                                    

                                                                                                                    You could wrap it with a function like this:

                                                                                                                    void my_get_data(char **result, int *len) {
                                                                                                                       *result = get_data(len);
                                                                                                                    }
                                                                                                                    

                                                                                                                    Comments:
                                                                                                                    • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                                                                                                    • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                                                                                                    • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                                                                                                    • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                                                                                                    8.4 C++ Library

                                                                                                                    The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                                                                                                    8.4.1 std_string.i

                                                                                                                    The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                                                                                                    %module example
                                                                                                                    %include "std_string.i"
                                                                                                                    
                                                                                                                    std::string foo();
                                                                                                                    void        bar(const std::string &x);
                                                                                                                    

                                                                                                                    In the target language:

                                                                                                                    x = foo();                # Returns a string object
                                                                                                                    bar("Hello World");       # Pass string as std::string
                                                                                                                    

                                                                                                                    This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                                                                                                    This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                                                                                                    %module example
                                                                                                                    %include "std_string.i"
                                                                                                                    
                                                                                                                    using namespace std;
                                                                                                                    typedef std::string String;
                                                                                                                    ...
                                                                                                                    void foo(string s, const String &t);     // std_string typemaps still applied
                                                                                                                    

                                                                                                                    Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                                                                                                    8.4.2 std_vector.i

                                                                                                                    The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                                                                                                    %module example
                                                                                                                    %include "std_vector.i"
                                                                                                                    
                                                                                                                    namespace std {
                                                                                                                       %template(vectori) vector<int>;
                                                                                                                       %template(vectord) vector<double>;
                                                                                                                    };
                                                                                                                    

                                                                                                                    When a template vector<X> is instantiated a number of things happen:
                                                                                                                    • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                                                                                                    • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                                                                                                    • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                                                                                                    • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                                                                                                    • An exception handler for std::out_of_range is defined.
                                                                                                                    • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                                                                                                    To illustrate the use of this library, consider the following functions:

                                                                                                                    /* File : example.h */
                                                                                                                    
                                                                                                                    #include <vector>
                                                                                                                    #include <algorithm>
                                                                                                                    #include <functional>
                                                                                                                    #include <numeric>
                                                                                                                    
                                                                                                                    double average(std::vector<int> v) {
                                                                                                                        return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                                                                                                    }
                                                                                                                    
                                                                                                                    std::vector<double> half(const std::vector<double>& v) {
                                                                                                                        std::vector<double> w(v);
                                                                                                                        for (unsigned int i=0; i<w.size(); i++)
                                                                                                                            w[i] /= 2.0;
                                                                                                                        return w;
                                                                                                                    }
                                                                                                                    
                                                                                                                    void halve_in_place(std::vector<double>& v) {
                                                                                                                        std::transform(v.begin(),v.end(),v.begin(),
                                                                                                                                       std::bind2nd(std::divides<double>(),2.0));
                                                                                                                    }
                                                                                                                    

                                                                                                                    To wrap with SWIG, you might write the following:

                                                                                                                    %module example
                                                                                                                    %{
                                                                                                                    #include "example.h"
                                                                                                                    %}
                                                                                                                    
                                                                                                                    %include "std_vector.i"
                                                                                                                    // Instantiate templates used by example
                                                                                                                    namespace std {
                                                                                                                       %template(IntVector) vector<int>;
                                                                                                                       %template(DoubleVector) vector<double>;
                                                                                                                    }
                                                                                                                    
                                                                                                                    // Include the header file with above prototypes
                                                                                                                    %include "example.h"
                                                                                                                    

                                                                                                                    Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                                                                                                    >>> from example import *
                                                                                                                    >>> iv = IntVector(4)         # Create an vector<int>
                                                                                                                    >>> for i in range(0,4):
                                                                                                                    ...      iv[i] = i
                                                                                                                    >>> average(iv)               # Call method
                                                                                                                    1.5
                                                                                                                    >>> average([0,1,2,3])        # Call with list
                                                                                                                    1.5
                                                                                                                    >>> half([1,2,3])             # Half a list
                                                                                                                    (0.5,1.0,1.5)
                                                                                                                    >>> halve_in_place([1,2,3])   # Oops
                                                                                                                    Traceback (most recent call last):
                                                                                                                      File "<stdin>", line 1, in ?
                                                                                                                    TypeError: Type error. Expected _p_std__vectorTdouble_t
                                                                                                                    >>> dv = DoubleVector(4)
                                                                                                                    >>> for i in range(0,4):
                                                                                                                    ...       dv[i] = i
                                                                                                                    >>> halve_in_place(dv)       # Ok
                                                                                                                    >>> for i in dv:
                                                                                                                    ...       print i
                                                                                                                    ...
                                                                                                                    0.0
                                                                                                                    0.5
                                                                                                                    1.0
                                                                                                                    1.5
                                                                                                                    >>> dv[20] = 4.5
                                                                                                                    Traceback (most recent call last):
                                                                                                                      File "<stdin>", line 1, in ?
                                                                                                                      File "example.py", line 81, in __setitem__
                                                                                                                        def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                                                                                                    IndexError: vector index out of range
                                                                                                                    >>>
                                                                                                                    

                                                                                                                    This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                                                                                                    %include "std_vector.i"
                                                                                                                    
                                                                                                                    namespace std {
                                                                                                                        %template(IntVector) vector<int>;
                                                                                                                    }
                                                                                                                    
                                                                                                                    using namespace std;
                                                                                                                    typedef std::vector Vector;
                                                                                                                    
                                                                                                                    void foo(vector<int> *x, const Vector &x);
                                                                                                                    

                                                                                                                    Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                                                                                                    Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                                                                                                    Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                                                                                                    8.5 Utility Libraries

                                                                                                                    8.5.1 exception.i

                                                                                                                    The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                                                                                                    SWIG_exception(int code, const char *message)

                                                                                                                    Raises an exception in the target language. code is one of the following symbolic constants:

                                                                                                                    SWIG_MemoryError
                                                                                                                    SWIG_IOError
                                                                                                                    SWIG_RuntimeError
                                                                                                                    SWIG_IndexError
                                                                                                                    SWIG_TypeError
                                                                                                                    SWIG_DivisionByZero
                                                                                                                    SWIG_OverflowError
                                                                                                                    SWIG_SyntaxError
                                                                                                                    SWIG_ValueError
                                                                                                                    SWIG_SystemError
                                                                                                                    

                                                                                                                    message is a string indicating more information about the problem.

                                                                                                                    The primary use of this module is in writing language-independent exception handlers. For example:

                                                                                                                    %include "exception.i"
                                                                                                                    %exception std::vector::getitem {
                                                                                                                        try {
                                                                                                                            $action
                                                                                                                        } catch (std::out_of_range& e) {
                                                                                                                            SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                                                                                        }
                                                                                                                    }
                                                                                                                    

                                                                                                                    ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                                                                                                    

                                                                                                                    SWIG-1.3 Documentation

                                                                                                                    
                                                                                                                    

                                                                                                                    ---

                                                                                                                    Table of Contents

                                                                                                                    
                                                                                                                    
                                                                                                                    SWIG-1.3 Development Documentation
                                                                                                                    • Sections
                                                                                                                    • SWIG Core Documentation
                                                                                                                    • Language Module Documentation
                                                                                                                    • Developer Documentation
                                                                                                                    • Documentation that has not yet been updated
                                                                                                                    1 Preface
                                                                                                                    • 1.1 Introduction
                                                                                                                    • 1.2 Special Introduction for Version 1.3
                                                                                                                    • 1.3 SWIG Versions
                                                                                                                    • 1.4 SWIG resources
                                                                                                                    • 1.5 Prerequisites
                                                                                                                    • 1.6 Organization of this manual
                                                                                                                    • 1.7 How to avoid reading the manual
                                                                                                                    • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                                                                                                      >>> make_upper("hello world")
                                                                                                                      'HELLO WORLD'
                                                                                                                      >>> attach_header("Hello world")
                                                                                                                      'header: Hello world'
                                                                                                                      >>>
                                                                                                                      

                                                                                                                      This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                                                                                                      %cstring_output_maxsize(parm, maxparm)

                                                                                                                      This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                                                                                                      %cstring_output_maxsize(char *path, int maxpath);
                                                                                                                      ...
                                                                                                                      void get_path(char *path, int maxpath);
                                                                                                                      

                                                                                                                      In the target language:

                                                                                                                      >>> get_path(1024)
                                                                                                                      '/home/beazley/Packages/Foo/Bar'
                                                                                                                      >>>
                                                                                                                      

                                                                                                                      This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                                                                                                      %cstring_output_withsize(parm, maxparm)

                                                                                                                      This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                                                                                                      %cstring_output_withsize(char *data, int *maxdata);
                                                                                                                      ...
                                                                                                                      void get_data(char *data, int *maxdata);
                                                                                                                      

                                                                                                                      In the target language:

                                                                                                                      >>> get_data(1024)
                                                                                                                      'x627388912'
                                                                                                                      >>> get_data(1024)
                                                                                                                      'xyzzy'
                                                                                                                      >>>
                                                                                                                      

                                                                                                                      This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                                                                                                      %cstring_output_allocate(parm, release)

                                                                                                                      This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                                                                                                      void foo(char **s) {
                                                                                                                          *s = (char *) malloc(64);
                                                                                                                          sprintf(*s, "Hello world\n");
                                                                                                                      }
                                                                                                                      

                                                                                                                      The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                                      %cstring_output_allocate(char **s, free(*$1));
                                                                                                                      ...
                                                                                                                      void foo(char **s);
                                                                                                                      

                                                                                                                      In the target language:

                                                                                                                      >>> foo()
                                                                                                                      'Hello world\n'
                                                                                                                      >>>
                                                                                                                      

                                                                                                                      %cstring_output_allocate_size(parm, szparm, release)

                                                                                                                      This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                                                                                                      void foo(char **s, int *sz) {
                                                                                                                          *s = (char *) malloc(64);
                                                                                                                          *sz = 64;
                                                                                                                          // Write some binary data
                                                                                                                          ...
                                                                                                                      }
                                                                                                                      

                                                                                                                      The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                                      %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                                                                                                      ...
                                                                                                                      void foo(char **s, int *slen);
                                                                                                                      

                                                                                                                      In the target language:

                                                                                                                      >>> foo()
                                                                                                                      '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                                                                                                      >>>
                                                                                                                      

                                                                                                                      This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                                                                                                      char  *get_data(int *len);
                                                                                                                      

                                                                                                                      You could wrap it with a function like this:

                                                                                                                      void my_get_data(char **result, int *len) {
                                                                                                                         *result = get_data(len);
                                                                                                                      }
                                                                                                                      

                                                                                                                      Comments:
                                                                                                                      • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                                                                                                      • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                                                                                                      • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                                                                                                      • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                                                                                                      8.4 C++ Library

                                                                                                                      The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                                                                                                      8.4.1 std_string.i

                                                                                                                      The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                                                                                                      %module example
                                                                                                                      %include "std_string.i"
                                                                                                                      
                                                                                                                      std::string foo();
                                                                                                                      void        bar(const std::string &x);
                                                                                                                      

                                                                                                                      In the target language:

                                                                                                                      x = foo();                # Returns a string object
                                                                                                                      bar("Hello World");       # Pass string as std::string
                                                                                                                      

                                                                                                                      This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                                                                                                      This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                                                                                                      %module example
                                                                                                                      %include "std_string.i"
                                                                                                                      
                                                                                                                      using namespace std;
                                                                                                                      typedef std::string String;
                                                                                                                      ...
                                                                                                                      void foo(string s, const String &t);     // std_string typemaps still applied
                                                                                                                      

                                                                                                                      Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                                                                                                      8.4.2 std_vector.i

                                                                                                                      The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                                                                                                      %module example
                                                                                                                      %include "std_vector.i"
                                                                                                                      
                                                                                                                      namespace std {
                                                                                                                         %template(vectori) vector<int>;
                                                                                                                         %template(vectord) vector<double>;
                                                                                                                      };
                                                                                                                      

                                                                                                                      When a template vector<X> is instantiated a number of things happen:
                                                                                                                      • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                                                                                                      • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                                                                                                      • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                                                                                                      • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                                                                                                      • An exception handler for std::out_of_range is defined.
                                                                                                                      • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                                                                                                      To illustrate the use of this library, consider the following functions:

                                                                                                                      /* File : example.h */
                                                                                                                      
                                                                                                                      #include <vector>
                                                                                                                      #include <algorithm>
                                                                                                                      #include <functional>
                                                                                                                      #include <numeric>
                                                                                                                      
                                                                                                                      double average(std::vector<int> v) {
                                                                                                                          return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                                                                                                      }
                                                                                                                      
                                                                                                                      std::vector<double> half(const std::vector<double>& v) {
                                                                                                                          std::vector<double> w(v);
                                                                                                                          for (unsigned int i=0; i<w.size(); i++)
                                                                                                                              w[i] /= 2.0;
                                                                                                                          return w;
                                                                                                                      }
                                                                                                                      
                                                                                                                      void halve_in_place(std::vector<double>& v) {
                                                                                                                          std::transform(v.begin(),v.end(),v.begin(),
                                                                                                                                         std::bind2nd(std::divides<double>(),2.0));
                                                                                                                      }
                                                                                                                      

                                                                                                                      To wrap with SWIG, you might write the following:

                                                                                                                      %module example
                                                                                                                      %{
                                                                                                                      #include "example.h"
                                                                                                                      %}
                                                                                                                      
                                                                                                                      %include "std_vector.i"
                                                                                                                      // Instantiate templates used by example
                                                                                                                      namespace std {
                                                                                                                         %template(IntVector) vector<int>;
                                                                                                                         %template(DoubleVector) vector<double>;
                                                                                                                      }
                                                                                                                      
                                                                                                                      // Include the header file with above prototypes
                                                                                                                      %include "example.h"
                                                                                                                      

                                                                                                                      Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                                                                                                      >>> from example import *
                                                                                                                      >>> iv = IntVector(4)         # Create an vector<int>
                                                                                                                      >>> for i in range(0,4):
                                                                                                                      ...      iv[i] = i
                                                                                                                      >>> average(iv)               # Call method
                                                                                                                      1.5
                                                                                                                      >>> average([0,1,2,3])        # Call with list
                                                                                                                      1.5
                                                                                                                      >>> half([1,2,3])             # Half a list
                                                                                                                      (0.5,1.0,1.5)
                                                                                                                      >>> halve_in_place([1,2,3])   # Oops
                                                                                                                      Traceback (most recent call last):
                                                                                                                        File "<stdin>", line 1, in ?
                                                                                                                      TypeError: Type error. Expected _p_std__vectorTdouble_t
                                                                                                                      >>> dv = DoubleVector(4)
                                                                                                                      >>> for i in range(0,4):
                                                                                                                      ...       dv[i] = i
                                                                                                                      >>> halve_in_place(dv)       # Ok
                                                                                                                      >>> for i in dv:
                                                                                                                      ...       print i
                                                                                                                      ...
                                                                                                                      0.0
                                                                                                                      0.5
                                                                                                                      1.0
                                                                                                                      1.5
                                                                                                                      >>> dv[20] = 4.5
                                                                                                                      Traceback (most recent call last):
                                                                                                                        File "<stdin>", line 1, in ?
                                                                                                                        File "example.py", line 81, in __setitem__
                                                                                                                          def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                                                                                                      IndexError: vector index out of range
                                                                                                                      >>>
                                                                                                                      

                                                                                                                      This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                                                                                                      %include "std_vector.i"
                                                                                                                      
                                                                                                                      namespace std {
                                                                                                                          %template(IntVector) vector<int>;
                                                                                                                      }
                                                                                                                      
                                                                                                                      using namespace std;
                                                                                                                      typedef std::vector Vector;
                                                                                                                      
                                                                                                                      void foo(vector<int> *x, const Vector &x);
                                                                                                                      

                                                                                                                      Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                                                                                                      Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                                                                                                      Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                                                                                                      8.5 Utility Libraries

                                                                                                                      8.5.1 exception.i

                                                                                                                      The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                                                                                                      SWIG_exception(int code, const char *message)

                                                                                                                      Raises an exception in the target language. code is one of the following symbolic constants:

                                                                                                                      SWIG_MemoryError
                                                                                                                      SWIG_IOError
                                                                                                                      SWIG_RuntimeError
                                                                                                                      SWIG_IndexError
                                                                                                                      SWIG_TypeError
                                                                                                                      SWIG_DivisionByZero
                                                                                                                      SWIG_OverflowError
                                                                                                                      SWIG_SyntaxError
                                                                                                                      SWIG_ValueError
                                                                                                                      SWIG_SystemError
                                                                                                                      

                                                                                                                      message is a string indicating more information about the problem.

                                                                                                                      The primary use of this module is in writing language-independent exception handlers. For example:

                                                                                                                      %include "exception.i"
                                                                                                                      %exception std::vector::getitem {
                                                                                                                          try {
                                                                                                                              $action
                                                                                                                          } catch (std::out_of_range& e) {
                                                                                                                              SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                                                                                          }
                                                                                                                      }
                                                                                                                      

                                                                                                                      ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                                                                                                      

                                                                                                                      SWIG-1.3 Documentation

                                                                                                                      
                                                                                                                      

                                                                                                                      ---

                                                                                                                      Table of Contents

                                                                                                                      
                                                                                                                      
                                                                                                                      SWIG-1.3 Development Documentation
                                                                                                                      • Sections
                                                                                                                      • SWIG Core Documentation
                                                                                                                      • Language Module Documentation
                                                                                                                      • Developer Documentation
                                                                                                                      • Documentation that has not yet been updated
                                                                                                                      1 Preface
                                                                                                                      • 1.1 Introduction
                                                                                                                      • 1.2 Special Introduction for Version 1.3
                                                                                                                      • 1.3 SWIG Versions
                                                                                                                      • 1.4 SWIG resources
                                                                                                                      • 1.5 Prerequisites
                                                                                                                      • 1.6 Organization of this manual
                                                                                                                      • 1.7 How to avoid reading the manual
                                                                                                                      • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                                                                                                        >>> make_upper("hello world")
                                                                                                                        'HELLO WORLD'
                                                                                                                        >>> attach_header("Hello world")
                                                                                                                        'header: Hello world'
                                                                                                                        >>>
                                                                                                                        

                                                                                                                        This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                                                                                                        %cstring_output_maxsize(parm, maxparm)

                                                                                                                        This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                                                                                                        %cstring_output_maxsize(char *path, int maxpath);
                                                                                                                        ...
                                                                                                                        void get_path(char *path, int maxpath);
                                                                                                                        

                                                                                                                        In the target language:

                                                                                                                        >>> get_path(1024)
                                                                                                                        '/home/beazley/Packages/Foo/Bar'
                                                                                                                        >>>
                                                                                                                        

                                                                                                                        This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                                                                                                        %cstring_output_withsize(parm, maxparm)

                                                                                                                        This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                                                                                                        %cstring_output_withsize(char *data, int *maxdata);
                                                                                                                        ...
                                                                                                                        void get_data(char *data, int *maxdata);
                                                                                                                        

                                                                                                                        In the target language:

                                                                                                                        >>> get_data(1024)
                                                                                                                        'x627388912'
                                                                                                                        >>> get_data(1024)
                                                                                                                        'xyzzy'
                                                                                                                        >>>
                                                                                                                        

                                                                                                                        This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                                                                                                        %cstring_output_allocate(parm, release)

                                                                                                                        This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                                                                                                        void foo(char **s) {
                                                                                                                            *s = (char *) malloc(64);
                                                                                                                            sprintf(*s, "Hello world\n");
                                                                                                                        }
                                                                                                                        

                                                                                                                        The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                                        %cstring_output_allocate(char **s, free(*$1));
                                                                                                                        ...
                                                                                                                        void foo(char **s);
                                                                                                                        

                                                                                                                        In the target language:

                                                                                                                        >>> foo()
                                                                                                                        'Hello world\n'
                                                                                                                        >>>
                                                                                                                        

                                                                                                                        %cstring_output_allocate_size(parm, szparm, release)

                                                                                                                        This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                                                                                                        void foo(char **s, int *sz) {
                                                                                                                            *s = (char *) malloc(64);
                                                                                                                            *sz = 64;
                                                                                                                            // Write some binary data
                                                                                                                            ...
                                                                                                                        }
                                                                                                                        

                                                                                                                        The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                                        %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                                                                                                        ...
                                                                                                                        void foo(char **s, int *slen);
                                                                                                                        

                                                                                                                        In the target language:

                                                                                                                        >>> foo()
                                                                                                                        '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                                                                                                        >>>
                                                                                                                        

                                                                                                                        This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                                                                                                        char  *get_data(int *len);
                                                                                                                        

                                                                                                                        You could wrap it with a function like this:

                                                                                                                        void my_get_data(char **result, int *len) {
                                                                                                                           *result = get_data(len);
                                                                                                                        }
                                                                                                                        

                                                                                                                        Comments:
                                                                                                                        • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                                                                                                        • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                                                                                                        • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                                                                                                        • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                                                                                                        8.4 C++ Library

                                                                                                                        The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                                                                                                        8.4.1 std_string.i

                                                                                                                        The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                                                                                                        %module example
                                                                                                                        %include "std_string.i"
                                                                                                                        
                                                                                                                        std::string foo();
                                                                                                                        void        bar(const std::string &x);
                                                                                                                        

                                                                                                                        In the target language:

                                                                                                                        x = foo();                # Returns a string object
                                                                                                                        bar("Hello World");       # Pass string as std::string
                                                                                                                        

                                                                                                                        This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                                                                                                        This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                                                                                                        %module example
                                                                                                                        %include "std_string.i"
                                                                                                                        
                                                                                                                        using namespace std;
                                                                                                                        typedef std::string String;
                                                                                                                        ...
                                                                                                                        void foo(string s, const String &t);     // std_string typemaps still applied
                                                                                                                        

                                                                                                                        Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                                                                                                        8.4.2 std_vector.i

                                                                                                                        The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                                                                                                        %module example
                                                                                                                        %include "std_vector.i"
                                                                                                                        
                                                                                                                        namespace std {
                                                                                                                           %template(vectori) vector<int>;
                                                                                                                           %template(vectord) vector<double>;
                                                                                                                        };
                                                                                                                        

                                                                                                                        When a template vector<X> is instantiated a number of things happen:
                                                                                                                        • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                                                                                                        • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                                                                                                        • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                                                                                                        • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                                                                                                        • An exception handler for std::out_of_range is defined.
                                                                                                                        • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                                                                                                        To illustrate the use of this library, consider the following functions:

                                                                                                                        /* File : example.h */
                                                                                                                        
                                                                                                                        #include <vector>
                                                                                                                        #include <algorithm>
                                                                                                                        #include <functional>
                                                                                                                        #include <numeric>
                                                                                                                        
                                                                                                                        double average(std::vector<int> v) {
                                                                                                                            return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                                                                                                        }
                                                                                                                        
                                                                                                                        std::vector<double> half(const std::vector<double>& v) {
                                                                                                                            std::vector<double> w(v);
                                                                                                                            for (unsigned int i=0; i<w.size(); i++)
                                                                                                                                w[i] /= 2.0;
                                                                                                                            return w;
                                                                                                                        }
                                                                                                                        
                                                                                                                        void halve_in_place(std::vector<double>& v) {
                                                                                                                            std::transform(v.begin(),v.end(),v.begin(),
                                                                                                                                           std::bind2nd(std::divides<double>(),2.0));
                                                                                                                        }
                                                                                                                        

                                                                                                                        To wrap with SWIG, you might write the following:

                                                                                                                        %module example
                                                                                                                        %{
                                                                                                                        #include "example.h"
                                                                                                                        %}
                                                                                                                        
                                                                                                                        %include "std_vector.i"
                                                                                                                        // Instantiate templates used by example
                                                                                                                        namespace std {
                                                                                                                           %template(IntVector) vector<int>;
                                                                                                                           %template(DoubleVector) vector<double>;
                                                                                                                        }
                                                                                                                        
                                                                                                                        // Include the header file with above prototypes
                                                                                                                        %include "example.h"
                                                                                                                        

                                                                                                                        Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                                                                                                        >>> from example import *
                                                                                                                        >>> iv = IntVector(4)         # Create an vector<int>
                                                                                                                        >>> for i in range(0,4):
                                                                                                                        ...      iv[i] = i
                                                                                                                        >>> average(iv)               # Call method
                                                                                                                        1.5
                                                                                                                        >>> average([0,1,2,3])        # Call with list
                                                                                                                        1.5
                                                                                                                        >>> half([1,2,3])             # Half a list
                                                                                                                        (0.5,1.0,1.5)
                                                                                                                        >>> halve_in_place([1,2,3])   # Oops
                                                                                                                        Traceback (most recent call last):
                                                                                                                          File "<stdin>", line 1, in ?
                                                                                                                        TypeError: Type error. Expected _p_std__vectorTdouble_t
                                                                                                                        >>> dv = DoubleVector(4)
                                                                                                                        >>> for i in range(0,4):
                                                                                                                        ...       dv[i] = i
                                                                                                                        >>> halve_in_place(dv)       # Ok
                                                                                                                        >>> for i in dv:
                                                                                                                        ...       print i
                                                                                                                        ...
                                                                                                                        0.0
                                                                                                                        0.5
                                                                                                                        1.0
                                                                                                                        1.5
                                                                                                                        >>> dv[20] = 4.5
                                                                                                                        Traceback (most recent call last):
                                                                                                                          File "<stdin>", line 1, in ?
                                                                                                                          File "example.py", line 81, in __setitem__
                                                                                                                            def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                                                                                                        IndexError: vector index out of range
                                                                                                                        >>>
                                                                                                                        

                                                                                                                        This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                                                                                                        %include "std_vector.i"
                                                                                                                        
                                                                                                                        namespace std {
                                                                                                                            %template(IntVector) vector<int>;
                                                                                                                        }
                                                                                                                        
                                                                                                                        using namespace std;
                                                                                                                        typedef std::vector Vector;
                                                                                                                        
                                                                                                                        void foo(vector<int> *x, const Vector &x);
                                                                                                                        

                                                                                                                        Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                                                                                                        Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                                                                                                        Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                                                                                                        8.5 Utility Libraries

                                                                                                                        8.5.1 exception.i

                                                                                                                        The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                                                                                                        SWIG_exception(int code, const char *message)

                                                                                                                        Raises an exception in the target language. code is one of the following symbolic constants:

                                                                                                                        SWIG_MemoryError
                                                                                                                        SWIG_IOError
                                                                                                                        SWIG_RuntimeError
                                                                                                                        SWIG_IndexError
                                                                                                                        SWIG_TypeError
                                                                                                                        SWIG_DivisionByZero
                                                                                                                        SWIG_OverflowError
                                                                                                                        SWIG_SyntaxError
                                                                                                                        SWIG_ValueError
                                                                                                                        SWIG_SystemError
                                                                                                                        

                                                                                                                        message is a string indicating more information about the problem.

                                                                                                                        The primary use of this module is in writing language-independent exception handlers. For example:

                                                                                                                        %include "exception.i"
                                                                                                                        %exception std::vector::getitem {
                                                                                                                            try {
                                                                                                                                $action
                                                                                                                            } catch (std::out_of_range& e) {
                                                                                                                                SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                                                                                            }
                                                                                                                        }
                                                                                                                        

                                                                                                                        ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                                                                                                        

                                                                                                                        SWIG-1.3 Documentation

                                                                                                                        
                                                                                                                        

                                                                                                                        ---

                                                                                                                        Table of Contents

                                                                                                                        
                                                                                                                        
                                                                                                                        SWIG-1.3 Development Documentation
                                                                                                                        • Sections
                                                                                                                        • SWIG Core Documentation
                                                                                                                        • Language Module Documentation
                                                                                                                        • Developer Documentation
                                                                                                                        • Documentation that has not yet been updated
                                                                                                                        1 Preface
                                                                                                                        • 1.1 Introduction
                                                                                                                        • 1.2 Special Introduction for Version 1.3
                                                                                                                        • 1.3 SWIG Versions
                                                                                                                        • 1.4 SWIG resources
                                                                                                                        • 1.5 Prerequisites
                                                                                                                        • 1.6 Organization of this manual
                                                                                                                        • 1.7 How to avoid reading the manual
                                                                                                                        • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                                                                                                          >>> make_upper("hello world")
                                                                                                                          'HELLO WORLD'
                                                                                                                          >>> attach_header("Hello world")
                                                                                                                          'header: Hello world'
                                                                                                                          >>>
                                                                                                                          

                                                                                                                          This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                                                                                                          %cstring_output_maxsize(parm, maxparm)

                                                                                                                          This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                                                                                                          %cstring_output_maxsize(char *path, int maxpath);
                                                                                                                          ...
                                                                                                                          void get_path(char *path, int maxpath);
                                                                                                                          

                                                                                                                          In the target language:

                                                                                                                          >>> get_path(1024)
                                                                                                                          '/home/beazley/Packages/Foo/Bar'
                                                                                                                          >>>
                                                                                                                          

                                                                                                                          This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                                                                                                          %cstring_output_withsize(parm, maxparm)

                                                                                                                          This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                                                                                                          %cstring_output_withsize(char *data, int *maxdata);
                                                                                                                          ...
                                                                                                                          void get_data(char *data, int *maxdata);
                                                                                                                          

                                                                                                                          In the target language:

                                                                                                                          >>> get_data(1024)
                                                                                                                          'x627388912'
                                                                                                                          >>> get_data(1024)
                                                                                                                          'xyzzy'
                                                                                                                          >>>
                                                                                                                          

                                                                                                                          This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                                                                                                          %cstring_output_allocate(parm, release)

                                                                                                                          This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                                                                                                          void foo(char **s) {
                                                                                                                              *s = (char *) malloc(64);
                                                                                                                              sprintf(*s, "Hello world\n");
                                                                                                                          }
                                                                                                                          

                                                                                                                          The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                                          %cstring_output_allocate(char **s, free(*$1));
                                                                                                                          ...
                                                                                                                          void foo(char **s);
                                                                                                                          

                                                                                                                          In the target language:

                                                                                                                          >>> foo()
                                                                                                                          'Hello world\n'
                                                                                                                          >>>
                                                                                                                          

                                                                                                                          %cstring_output_allocate_size(parm, szparm, release)

                                                                                                                          This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                                                                                                          void foo(char **s, int *sz) {
                                                                                                                              *s = (char *) malloc(64);
                                                                                                                              *sz = 64;
                                                                                                                              // Write some binary data
                                                                                                                              ...
                                                                                                                          }
                                                                                                                          

                                                                                                                          The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                                          %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                                                                                                          ...
                                                                                                                          void foo(char **s, int *slen);
                                                                                                                          

                                                                                                                          In the target language:

                                                                                                                          >>> foo()
                                                                                                                          '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                                                                                                          >>>
                                                                                                                          

                                                                                                                          This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                                                                                                          char  *get_data(int *len);
                                                                                                                          

                                                                                                                          You could wrap it with a function like this:

                                                                                                                          void my_get_data(char **result, int *len) {
                                                                                                                             *result = get_data(len);
                                                                                                                          }
                                                                                                                          

                                                                                                                          Comments:
                                                                                                                          • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                                                                                                          • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                                                                                                          • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                                                                                                          • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                                                                                                          8.4 C++ Library

                                                                                                                          The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                                                                                                          8.4.1 std_string.i

                                                                                                                          The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                                                                                                          %module example
                                                                                                                          %include "std_string.i"
                                                                                                                          
                                                                                                                          std::string foo();
                                                                                                                          void        bar(const std::string &x);
                                                                                                                          

                                                                                                                          In the target language:

                                                                                                                          x = foo();                # Returns a string object
                                                                                                                          bar("Hello World");       # Pass string as std::string
                                                                                                                          

                                                                                                                          This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                                                                                                          This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                                                                                                          %module example
                                                                                                                          %include "std_string.i"
                                                                                                                          
                                                                                                                          using namespace std;
                                                                                                                          typedef std::string String;
                                                                                                                          ...
                                                                                                                          void foo(string s, const String &t);     // std_string typemaps still applied
                                                                                                                          

                                                                                                                          Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                                                                                                          8.4.2 std_vector.i

                                                                                                                          The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                                                                                                          %module example
                                                                                                                          %include "std_vector.i"
                                                                                                                          
                                                                                                                          namespace std {
                                                                                                                             %template(vectori) vector<int>;
                                                                                                                             %template(vectord) vector<double>;
                                                                                                                          };
                                                                                                                          

                                                                                                                          When a template vector<X> is instantiated a number of things happen:
                                                                                                                          • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                                                                                                          • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                                                                                                          • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                                                                                                          • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                                                                                                          • An exception handler for std::out_of_range is defined.
                                                                                                                          • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                                                                                                          To illustrate the use of this library, consider the following functions:

                                                                                                                          /* File : example.h */
                                                                                                                          
                                                                                                                          #include <vector>
                                                                                                                          #include <algorithm>
                                                                                                                          #include <functional>
                                                                                                                          #include <numeric>
                                                                                                                          
                                                                                                                          double average(std::vector<int> v) {
                                                                                                                              return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                                                                                                          }
                                                                                                                          
                                                                                                                          std::vector<double> half(const std::vector<double>& v) {
                                                                                                                              std::vector<double> w(v);
                                                                                                                              for (unsigned int i=0; i<w.size(); i++)
                                                                                                                                  w[i] /= 2.0;
                                                                                                                              return w;
                                                                                                                          }
                                                                                                                          
                                                                                                                          void halve_in_place(std::vector<double>& v) {
                                                                                                                              std::transform(v.begin(),v.end(),v.begin(),
                                                                                                                                             std::bind2nd(std::divides<double>(),2.0));
                                                                                                                          }
                                                                                                                          

                                                                                                                          To wrap with SWIG, you might write the following:

                                                                                                                          %module example
                                                                                                                          %{
                                                                                                                          #include "example.h"
                                                                                                                          %}
                                                                                                                          
                                                                                                                          %include "std_vector.i"
                                                                                                                          // Instantiate templates used by example
                                                                                                                          namespace std {
                                                                                                                             %template(IntVector) vector<int>;
                                                                                                                             %template(DoubleVector) vector<double>;
                                                                                                                          }
                                                                                                                          
                                                                                                                          // Include the header file with above prototypes
                                                                                                                          %include "example.h"
                                                                                                                          

                                                                                                                          Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                                                                                                          >>> from example import *
                                                                                                                          >>> iv = IntVector(4)         # Create an vector<int>
                                                                                                                          >>> for i in range(0,4):
                                                                                                                          ...      iv[i] = i
                                                                                                                          >>> average(iv)               # Call method
                                                                                                                          1.5
                                                                                                                          >>> average([0,1,2,3])        # Call with list
                                                                                                                          1.5
                                                                                                                          >>> half([1,2,3])             # Half a list
                                                                                                                          (0.5,1.0,1.5)
                                                                                                                          >>> halve_in_place([1,2,3])   # Oops
                                                                                                                          Traceback (most recent call last):
                                                                                                                            File "<stdin>", line 1, in ?
                                                                                                                          TypeError: Type error. Expected _p_std__vectorTdouble_t
                                                                                                                          >>> dv = DoubleVector(4)
                                                                                                                          >>> for i in range(0,4):
                                                                                                                          ...       dv[i] = i
                                                                                                                          >>> halve_in_place(dv)       # Ok
                                                                                                                          >>> for i in dv:
                                                                                                                          ...       print i
                                                                                                                          ...
                                                                                                                          0.0
                                                                                                                          0.5
                                                                                                                          1.0
                                                                                                                          1.5
                                                                                                                          >>> dv[20] = 4.5
                                                                                                                          Traceback (most recent call last):
                                                                                                                            File "<stdin>", line 1, in ?
                                                                                                                            File "example.py", line 81, in __setitem__
                                                                                                                              def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                                                                                                          IndexError: vector index out of range
                                                                                                                          >>>
                                                                                                                          

                                                                                                                          This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                                                                                                          %include "std_vector.i"
                                                                                                                          
                                                                                                                          namespace std {
                                                                                                                              %template(IntVector) vector<int>;
                                                                                                                          }
                                                                                                                          
                                                                                                                          using namespace std;
                                                                                                                          typedef std::vector Vector;
                                                                                                                          
                                                                                                                          void foo(vector<int> *x, const Vector &x);
                                                                                                                          

                                                                                                                          Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                                                                                                          Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                                                                                                          Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                                                                                                          8.5 Utility Libraries

                                                                                                                          8.5.1 exception.i

                                                                                                                          The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                                                                                                          SWIG_exception(int code, const char *message)

                                                                                                                          Raises an exception in the target language. code is one of the following symbolic constants:

                                                                                                                          SWIG_MemoryError
                                                                                                                          SWIG_IOError
                                                                                                                          SWIG_RuntimeError
                                                                                                                          SWIG_IndexError
                                                                                                                          SWIG_TypeError
                                                                                                                          SWIG_DivisionByZero
                                                                                                                          SWIG_OverflowError
                                                                                                                          SWIG_SyntaxError
                                                                                                                          SWIG_ValueError
                                                                                                                          SWIG_SystemError
                                                                                                                          

                                                                                                                          message is a string indicating more information about the problem.

                                                                                                                          The primary use of this module is in writing language-independent exception handlers. For example:

                                                                                                                          %include "exception.i"
                                                                                                                          %exception std::vector::getitem {
                                                                                                                              try {
                                                                                                                                  $action
                                                                                                                              } catch (std::out_of_range& e) {
                                                                                                                                  SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                                                                                              }
                                                                                                                          }
                                                                                                                          

                                                                                                                          ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                                                                                                          

                                                                                                                          SWIG-1.3 Documentation

                                                                                                                          
                                                                                                                          

                                                                                                                          ---

                                                                                                                          Table of Contents

                                                                                                                          
                                                                                                                          
                                                                                                                          SWIG-1.3 Development Documentation
                                                                                                                          • Sections
                                                                                                                          • SWIG Core Documentation
                                                                                                                          • Language Module Documentation
                                                                                                                          • Developer Documentation
                                                                                                                          • Documentation that has not yet been updated
                                                                                                                          1 Preface
                                                                                                                          • 1.1 Introduction
                                                                                                                          • 1.2 Special Introduction for Version 1.3
                                                                                                                          • 1.3 SWIG Versions
                                                                                                                          • 1.4 SWIG resources
                                                                                                                          • 1.5 Prerequisites
                                                                                                                          • 1.6 Organization of this manual
                                                                                                                          • 1.7 How to avoid reading the manual
                                                                                                                          • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                                                                                                            >>> make_upper("hello world")
                                                                                                                            'HELLO WORLD'
                                                                                                                            >>> attach_header("Hello world")
                                                                                                                            'header: Hello world'
                                                                                                                            >>>
                                                                                                                            

                                                                                                                            This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                                                                                                            %cstring_output_maxsize(parm, maxparm)

                                                                                                                            This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                                                                                                            %cstring_output_maxsize(char *path, int maxpath);
                                                                                                                            ...
                                                                                                                            void get_path(char *path, int maxpath);
                                                                                                                            

                                                                                                                            In the target language:

                                                                                                                            >>> get_path(1024)
                                                                                                                            '/home/beazley/Packages/Foo/Bar'
                                                                                                                            >>>
                                                                                                                            

                                                                                                                            This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                                                                                                            %cstring_output_withsize(parm, maxparm)

                                                                                                                            This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                                                                                                            %cstring_output_withsize(char *data, int *maxdata);
                                                                                                                            ...
                                                                                                                            void get_data(char *data, int *maxdata);
                                                                                                                            

                                                                                                                            In the target language:

                                                                                                                            >>> get_data(1024)
                                                                                                                            'x627388912'
                                                                                                                            >>> get_data(1024)
                                                                                                                            'xyzzy'
                                                                                                                            >>>
                                                                                                                            

                                                                                                                            This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                                                                                                            %cstring_output_allocate(parm, release)

                                                                                                                            This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                                                                                                            void foo(char **s) {
                                                                                                                                *s = (char *) malloc(64);
                                                                                                                                sprintf(*s, "Hello world\n");
                                                                                                                            }
                                                                                                                            

                                                                                                                            The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                                            %cstring_output_allocate(char **s, free(*$1));
                                                                                                                            ...
                                                                                                                            void foo(char **s);
                                                                                                                            

                                                                                                                            In the target language:

                                                                                                                            >>> foo()
                                                                                                                            'Hello world\n'
                                                                                                                            >>>
                                                                                                                            

                                                                                                                            %cstring_output_allocate_size(parm, szparm, release)

                                                                                                                            This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                                                                                                            void foo(char **s, int *sz) {
                                                                                                                                *s = (char *) malloc(64);
                                                                                                                                *sz = 64;
                                                                                                                                // Write some binary data
                                                                                                                                ...
                                                                                                                            }
                                                                                                                            

                                                                                                                            The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                                            %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                                                                                                            ...
                                                                                                                            void foo(char **s, int *slen);
                                                                                                                            

                                                                                                                            In the target language:

                                                                                                                            >>> foo()
                                                                                                                            '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                                                                                                            >>>
                                                                                                                            

                                                                                                                            This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                                                                                                            char  *get_data(int *len);
                                                                                                                            

                                                                                                                            You could wrap it with a function like this:

                                                                                                                            void my_get_data(char **result, int *len) {
                                                                                                                               *result = get_data(len);
                                                                                                                            }
                                                                                                                            

                                                                                                                            Comments:
                                                                                                                            • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                                                                                                            • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                                                                                                            • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                                                                                                            • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                                                                                                            8.4 C++ Library

                                                                                                                            The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                                                                                                            8.4.1 std_string.i

                                                                                                                            The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                                                                                                            %module example
                                                                                                                            %include "std_string.i"
                                                                                                                            
                                                                                                                            std::string foo();
                                                                                                                            void        bar(const std::string &x);
                                                                                                                            

                                                                                                                            In the target language:

                                                                                                                            x = foo();                # Returns a string object
                                                                                                                            bar("Hello World");       # Pass string as std::string
                                                                                                                            

                                                                                                                            This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                                                                                                            This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                                                                                                            %module example
                                                                                                                            %include "std_string.i"
                                                                                                                            
                                                                                                                            using namespace std;
                                                                                                                            typedef std::string String;
                                                                                                                            ...
                                                                                                                            void foo(string s, const String &t);     // std_string typemaps still applied
                                                                                                                            

                                                                                                                            Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                                                                                                            8.4.2 std_vector.i

                                                                                                                            The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                                                                                                            %module example
                                                                                                                            %include "std_vector.i"
                                                                                                                            
                                                                                                                            namespace std {
                                                                                                                               %template(vectori) vector<int>;
                                                                                                                               %template(vectord) vector<double>;
                                                                                                                            };
                                                                                                                            

                                                                                                                            When a template vector<X> is instantiated a number of things happen:
                                                                                                                            • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                                                                                                            • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                                                                                                            • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                                                                                                            • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                                                                                                            • An exception handler for std::out_of_range is defined.
                                                                                                                            • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                                                                                                            To illustrate the use of this library, consider the following functions:

                                                                                                                            /* File : example.h */
                                                                                                                            
                                                                                                                            #include <vector>
                                                                                                                            #include <algorithm>
                                                                                                                            #include <functional>
                                                                                                                            #include <numeric>
                                                                                                                            
                                                                                                                            double average(std::vector<int> v) {
                                                                                                                                return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                                                                                                            }
                                                                                                                            
                                                                                                                            std::vector<double> half(const std::vector<double>& v) {
                                                                                                                                std::vector<double> w(v);
                                                                                                                                for (unsigned int i=0; i<w.size(); i++)
                                                                                                                                    w[i] /= 2.0;
                                                                                                                                return w;
                                                                                                                            }
                                                                                                                            
                                                                                                                            void halve_in_place(std::vector<double>& v) {
                                                                                                                                std::transform(v.begin(),v.end(),v.begin(),
                                                                                                                                               std::bind2nd(std::divides<double>(),2.0));
                                                                                                                            }
                                                                                                                            

                                                                                                                            To wrap with SWIG, you might write the following:

                                                                                                                            %module example
                                                                                                                            %{
                                                                                                                            #include "example.h"
                                                                                                                            %}
                                                                                                                            
                                                                                                                            %include "std_vector.i"
                                                                                                                            // Instantiate templates used by example
                                                                                                                            namespace std {
                                                                                                                               %template(IntVector) vector<int>;
                                                                                                                               %template(DoubleVector) vector<double>;
                                                                                                                            }
                                                                                                                            
                                                                                                                            // Include the header file with above prototypes
                                                                                                                            %include "example.h"
                                                                                                                            

                                                                                                                            Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                                                                                                            >>> from example import *
                                                                                                                            >>> iv = IntVector(4)         # Create an vector<int>
                                                                                                                            >>> for i in range(0,4):
                                                                                                                            ...      iv[i] = i
                                                                                                                            >>> average(iv)               # Call method
                                                                                                                            1.5
                                                                                                                            >>> average([0,1,2,3])        # Call with list
                                                                                                                            1.5
                                                                                                                            >>> half([1,2,3])             # Half a list
                                                                                                                            (0.5,1.0,1.5)
                                                                                                                            >>> halve_in_place([1,2,3])   # Oops
                                                                                                                            Traceback (most recent call last):
                                                                                                                              File "<stdin>", line 1, in ?
                                                                                                                            TypeError: Type error. Expected _p_std__vectorTdouble_t
                                                                                                                            >>> dv = DoubleVector(4)
                                                                                                                            >>> for i in range(0,4):
                                                                                                                            ...       dv[i] = i
                                                                                                                            >>> halve_in_place(dv)       # Ok
                                                                                                                            >>> for i in dv:
                                                                                                                            ...       print i
                                                                                                                            ...
                                                                                                                            0.0
                                                                                                                            0.5
                                                                                                                            1.0
                                                                                                                            1.5
                                                                                                                            >>> dv[20] = 4.5
                                                                                                                            Traceback (most recent call last):
                                                                                                                              File "<stdin>", line 1, in ?
                                                                                                                              File "example.py", line 81, in __setitem__
                                                                                                                                def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                                                                                                            IndexError: vector index out of range
                                                                                                                            >>>
                                                                                                                            

                                                                                                                            This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                                                                                                            %include "std_vector.i"
                                                                                                                            
                                                                                                                            namespace std {
                                                                                                                                %template(IntVector) vector<int>;
                                                                                                                            }
                                                                                                                            
                                                                                                                            using namespace std;
                                                                                                                            typedef std::vector Vector;
                                                                                                                            
                                                                                                                            void foo(vector<int> *x, const Vector &x);
                                                                                                                            

                                                                                                                            Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                                                                                                            Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                                                                                                            Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                                                                                                            8.5 Utility Libraries

                                                                                                                            8.5.1 exception.i

                                                                                                                            The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                                                                                                            SWIG_exception(int code, const char *message)

                                                                                                                            Raises an exception in the target language. code is one of the following symbolic constants:

                                                                                                                            SWIG_MemoryError
                                                                                                                            SWIG_IOError
                                                                                                                            SWIG_RuntimeError
                                                                                                                            SWIG_IndexError
                                                                                                                            SWIG_TypeError
                                                                                                                            SWIG_DivisionByZero
                                                                                                                            SWIG_OverflowError
                                                                                                                            SWIG_SyntaxError
                                                                                                                            SWIG_ValueError
                                                                                                                            SWIG_SystemError
                                                                                                                            

                                                                                                                            message is a string indicating more information about the problem.

                                                                                                                            The primary use of this module is in writing language-independent exception handlers. For example:

                                                                                                                            %include "exception.i"
                                                                                                                            %exception std::vector::getitem {
                                                                                                                                try {
                                                                                                                                    $action
                                                                                                                                } catch (std::out_of_range& e) {
                                                                                                                                    SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                                                                                                }
                                                                                                                            }
                                                                                                                            

                                                                                                                            ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                                                                                                            

                                                                                                                            SWIG-1.3 Documentation

                                                                                                                            
                                                                                                                            

                                                                                                                            ---

                                                                                                                            Table of Contents

                                                                                                                            
                                                                                                                            
                                                                                                                            SWIG-1.3 Development Documentation
                                                                                                                            • Sections
                                                                                                                            • SWIG Core Documentation
                                                                                                                            • Language Module Documentation
                                                                                                                            • Developer Documentation
                                                                                                                            • Documentation that has not yet been updated
                                                                                                                            1 Preface
                                                                                                                            • 1.1 Introduction
                                                                                                                            • 1.2 Special Introduction for Version 1.3
                                                                                                                            • 1.3 SWIG Versions
                                                                                                                            • 1.4 SWIG resources
                                                                                                                            • 1.5 Prerequisites
                                                                                                                            • 1.6 Organization of this manual
                                                                                                                            • 1.7 How to avoid reading the manual
                                                                                                                            • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                                                                                                              >>> make_upper("hello world")
                                                                                                                              'HELLO WORLD'
                                                                                                                              >>> attach_header("Hello world")
                                                                                                                              'header: Hello world'
                                                                                                                              >>>
                                                                                                                              

                                                                                                                              This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                                                                                                              %cstring_output_maxsize(parm, maxparm)

                                                                                                                              This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                                                                                                              %cstring_output_maxsize(char *path, int maxpath);
                                                                                                                              ...
                                                                                                                              void get_path(char *path, int maxpath);
                                                                                                                              

                                                                                                                              In the target language:

                                                                                                                              >>> get_path(1024)
                                                                                                                              '/home/beazley/Packages/Foo/Bar'
                                                                                                                              >>>
                                                                                                                              

                                                                                                                              This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                                                                                                              %cstring_output_withsize(parm, maxparm)

                                                                                                                              This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                                                                                                              %cstring_output_withsize(char *data, int *maxdata);
                                                                                                                              ...
                                                                                                                              void get_data(char *data, int *maxdata);
                                                                                                                              

                                                                                                                              In the target language:

                                                                                                                              >>> get_data(1024)
                                                                                                                              'x627388912'
                                                                                                                              >>> get_data(1024)
                                                                                                                              'xyzzy'
                                                                                                                              >>>
                                                                                                                              

                                                                                                                              This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                                                                                                              %cstring_output_allocate(parm, release)

                                                                                                                              This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                                                                                                              void foo(char **s) {
                                                                                                                                  *s = (char *) malloc(64);
                                                                                                                                  sprintf(*s, "Hello world\n");
                                                                                                                              }
                                                                                                                              

                                                                                                                              The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                                              %cstring_output_allocate(char **s, free(*$1));
                                                                                                                              ...
                                                                                                                              void foo(char **s);
                                                                                                                              

                                                                                                                              In the target language:

                                                                                                                              >>> foo()
                                                                                                                              'Hello world\n'
                                                                                                                              >>>
                                                                                                                              

                                                                                                                              %cstring_output_allocate_size(parm, szparm, release)

                                                                                                                              This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                                                                                                              void foo(char **s, int *sz) {
                                                                                                                                  *s = (char *) malloc(64);
                                                                                                                                  *sz = 64;
                                                                                                                                  // Write some binary data
                                                                                                                                  ...
                                                                                                                              }
                                                                                                                              

                                                                                                                              The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                                              %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                                                                                                              ...
                                                                                                                              void foo(char **s, int *slen);
                                                                                                                              

                                                                                                                              In the target language:

                                                                                                                              >>> foo()
                                                                                                                              '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                                                                                                              >>>
                                                                                                                              

                                                                                                                              This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                                                                                                              char  *get_data(int *len);
                                                                                                                              

                                                                                                                              You could wrap it with a function like this:

                                                                                                                              void my_get_data(char **result, int *len) {
                                                                                                                                 *result = get_data(len);
                                                                                                                              }
                                                                                                                              

                                                                                                                              Comments:
                                                                                                                              • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                                                                                                              • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                                                                                                              • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                                                                                                              • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                                                                                                              8.4 C++ Library

                                                                                                                              The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                                                                                                              8.4.1 std_string.i

                                                                                                                              The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                                                                                                              %module example
                                                                                                                              %include "std_string.i"
                                                                                                                              
                                                                                                                              std::string foo();
                                                                                                                              void        bar(const std::string &x);
                                                                                                                              

                                                                                                                              In the target language:

                                                                                                                              x = foo();                # Returns a string object
                                                                                                                              bar("Hello World");       # Pass string as std::string
                                                                                                                              

                                                                                                                              This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                                                                                                              This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                                                                                                              %module example
                                                                                                                              %include "std_string.i"
                                                                                                                              
                                                                                                                              using namespace std;
                                                                                                                              typedef std::string String;
                                                                                                                              ...
                                                                                                                              void foo(string s, const String &t);     // std_string typemaps still applied
                                                                                                                              

                                                                                                                              Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                                                                                                              8.4.2 std_vector.i

                                                                                                                              The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                                                                                                              %module example
                                                                                                                              %include "std_vector.i"
                                                                                                                              
                                                                                                                              namespace std {
                                                                                                                                 %template(vectori) vector<int>;
                                                                                                                                 %template(vectord) vector<double>;
                                                                                                                              };
                                                                                                                              

                                                                                                                              When a template vector<X> is instantiated a number of things happen:
                                                                                                                              • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                                                                                                              • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                                                                                                              • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                                                                                                              • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                                                                                                              • An exception handler for std::out_of_range is defined.
                                                                                                                              • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                                                                                                              To illustrate the use of this library, consider the following functions:

                                                                                                                              /* File : example.h */
                                                                                                                              
                                                                                                                              #include <vector>
                                                                                                                              #include <algorithm>
                                                                                                                              #include <functional>
                                                                                                                              #include <numeric>
                                                                                                                              
                                                                                                                              double average(std::vector<int> v) {
                                                                                                                                  return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                                                                                                              }
                                                                                                                              
                                                                                                                              std::vector<double> half(const std::vector<double>& v) {
                                                                                                                                  std::vector<double> w(v);
                                                                                                                                  for (unsigned int i=0; i<w.size(); i++)
                                                                                                                                      w[i] /= 2.0;
                                                                                                                                  return w;
                                                                                                                              }
                                                                                                                              
                                                                                                                              void halve_in_place(std::vector<double>& v) {
                                                                                                                                  std::transform(v.begin(),v.end(),v.begin(),
                                                                                                                                                 std::bind2nd(std::divides<double>(),2.0));
                                                                                                                              }
                                                                                                                              

                                                                                                                              To wrap with SWIG, you might write the following:

                                                                                                                              %module example
                                                                                                                              %{
                                                                                                                              #include "example.h"
                                                                                                                              %}
                                                                                                                              
                                                                                                                              %include "std_vector.i"
                                                                                                                              // Instantiate templates used by example
                                                                                                                              namespace std {
                                                                                                                                 %template(IntVector) vector<int>;
                                                                                                                                 %template(DoubleVector) vector<double>;
                                                                                                                              }
                                                                                                                              
                                                                                                                              // Include the header file with above prototypes
                                                                                                                              %include "example.h"
                                                                                                                              

                                                                                                                              Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                                                                                                              >>> from example import *
                                                                                                                              >>> iv = IntVector(4)         # Create an vector<int>
                                                                                                                              >>> for i in range(0,4):
                                                                                                                              ...      iv[i] = i
                                                                                                                              >>> average(iv)               # Call method
                                                                                                                              1.5
                                                                                                                              >>> average([0,1,2,3])        # Call with list
                                                                                                                              1.5
                                                                                                                              >>> half([1,2,3])             # Half a list
                                                                                                                              (0.5,1.0,1.5)
                                                                                                                              >>> halve_in_place([1,2,3])   # Oops
                                                                                                                              Traceback (most recent call last):
                                                                                                                                File "<stdin>", line 1, in ?
                                                                                                                              TypeError: Type error. Expected _p_std__vectorTdouble_t
                                                                                                                              >>> dv = DoubleVector(4)
                                                                                                                              >>> for i in range(0,4):
                                                                                                                              ...       dv[i] = i
                                                                                                                              >>> halve_in_place(dv)       # Ok
                                                                                                                              >>> for i in dv:
                                                                                                                              ...       print i
                                                                                                                              ...
                                                                                                                              0.0
                                                                                                                              0.5
                                                                                                                              1.0
                                                                                                                              1.5
                                                                                                                              >>> dv[20] = 4.5
                                                                                                                              Traceback (most recent call last):
                                                                                                                                File "<stdin>", line 1, in ?
                                                                                                                                File "example.py", line 81, in __setitem__
                                                                                                                                  def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                                                                                                              IndexError: vector index out of range
                                                                                                                              >>>
                                                                                                                              

                                                                                                                              This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                                                                                                              %include "std_vector.i"
                                                                                                                              
                                                                                                                              namespace std {
                                                                                                                                  %template(IntVector) vector<int>;
                                                                                                                              }
                                                                                                                              
                                                                                                                              using namespace std;
                                                                                                                              typedef std::vector Vector;
                                                                                                                              
                                                                                                                              void foo(vector<int> *x, const Vector &x);
                                                                                                                              

                                                                                                                              Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                                                                                                              Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                                                                                                              Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                                                                                                              8.5 Utility Libraries

                                                                                                                              8.5.1 exception.i

                                                                                                                              The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                                                                                                              SWIG_exception(int code, const char *message)

                                                                                                                              Raises an exception in the target language. code is one of the following symbolic constants:

                                                                                                                              SWIG_MemoryError
                                                                                                                              SWIG_IOError
                                                                                                                              SWIG_RuntimeError
                                                                                                                              SWIG_IndexError
                                                                                                                              SWIG_TypeError
                                                                                                                              SWIG_DivisionByZero
                                                                                                                              SWIG_OverflowError
                                                                                                                              SWIG_SyntaxError
                                                                                                                              SWIG_ValueError
                                                                                                                              SWIG_SystemError
                                                                                                                              

                                                                                                                              message is a string indicating more information about the problem.

                                                                                                                              The primary use of this module is in writing language-independent exception handlers. For example:

                                                                                                                              %include "exception.i"
                                                                                                                              %exception std::vector::getitem {
                                                                                                                                  try {
                                                                                                                                      $action
                                                                                                                                  } catch (std::out_of_range& e) {
                                                                                                                                      SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                                                                                                  }
                                                                                                                              }
                                                                                                                              

                                                                                                                              ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                                                                                                              

                                                                                                                              SWIG-1.3 Documentation

                                                                                                                              
                                                                                                                              

                                                                                                                              ---

                                                                                                                              Table of Contents

                                                                                                                              
                                                                                                                              
                                                                                                                              SWIG-1.3 Development Documentation
                                                                                                                              • Sections
                                                                                                                              • SWIG Core Documentation
                                                                                                                              • Language Module Documentation
                                                                                                                              • Developer Documentation
                                                                                                                              • Documentation that has not yet been updated
                                                                                                                              1 Preface
                                                                                                                              • 1.1 Introduction
                                                                                                                              • 1.2 Special Introduction for Version 1.3
                                                                                                                              • 1.3 SWIG Versions
                                                                                                                              • 1.4 SWIG resources
                                                                                                                              • 1.5 Prerequisites
                                                                                                                              • 1.6 Organization of this manual
                                                                                                                              • 1.7 How to avoid reading the manual
                                                                                                                              • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                                                                                                                >>> make_upper("hello world")
                                                                                                                                'HELLO WORLD'
                                                                                                                                >>> attach_header("Hello world")
                                                                                                                                'header: Hello world'
                                                                                                                                >>>
                                                                                                                                

                                                                                                                                This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                                                                                                                %cstring_output_maxsize(parm, maxparm)

                                                                                                                                This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                                                                                                                %cstring_output_maxsize(char *path, int maxpath);
                                                                                                                                ...
                                                                                                                                void get_path(char *path, int maxpath);
                                                                                                                                

                                                                                                                                In the target language:

                                                                                                                                >>> get_path(1024)
                                                                                                                                '/home/beazley/Packages/Foo/Bar'
                                                                                                                                >>>
                                                                                                                                

                                                                                                                                This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                                                                                                                %cstring_output_withsize(parm, maxparm)

                                                                                                                                This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                                                                                                                %cstring_output_withsize(char *data, int *maxdata);
                                                                                                                                ...
                                                                                                                                void get_data(char *data, int *maxdata);
                                                                                                                                

                                                                                                                                In the target language:

                                                                                                                                >>> get_data(1024)
                                                                                                                                'x627388912'
                                                                                                                                >>> get_data(1024)
                                                                                                                                'xyzzy'
                                                                                                                                >>>
                                                                                                                                

                                                                                                                                This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                                                                                                                %cstring_output_allocate(parm, release)

                                                                                                                                This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                                                                                                                void foo(char **s) {
                                                                                                                                    *s = (char *) malloc(64);
                                                                                                                                    sprintf(*s, "Hello world\n");
                                                                                                                                }
                                                                                                                                

                                                                                                                                The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                                                %cstring_output_allocate(char **s, free(*$1));
                                                                                                                                ...
                                                                                                                                void foo(char **s);
                                                                                                                                

                                                                                                                                In the target language:

                                                                                                                                >>> foo()
                                                                                                                                'Hello world\n'
                                                                                                                                >>>
                                                                                                                                

                                                                                                                                %cstring_output_allocate_size(parm, szparm, release)

                                                                                                                                This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                                                                                                                void foo(char **s, int *sz) {
                                                                                                                                    *s = (char *) malloc(64);
                                                                                                                                    *sz = 64;
                                                                                                                                    // Write some binary data
                                                                                                                                    ...
                                                                                                                                }
                                                                                                                                

                                                                                                                                The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                                                %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                                                                                                                ...
                                                                                                                                void foo(char **s, int *slen);
                                                                                                                                

                                                                                                                                In the target language:

                                                                                                                                >>> foo()
                                                                                                                                '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                                                                                                                >>>
                                                                                                                                

                                                                                                                                This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                                                                                                                char  *get_data(int *len);
                                                                                                                                

                                                                                                                                You could wrap it with a function like this:

                                                                                                                                void my_get_data(char **result, int *len) {
                                                                                                                                   *result = get_data(len);
                                                                                                                                }
                                                                                                                                

                                                                                                                                Comments:
                                                                                                                                • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                                                                                                                • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                                                                                                                • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                                                                                                                • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                                                                                                                8.4 C++ Library

                                                                                                                                The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                                                                                                                8.4.1 std_string.i

                                                                                                                                The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                                                                                                                %module example
                                                                                                                                %include "std_string.i"
                                                                                                                                
                                                                                                                                std::string foo();
                                                                                                                                void        bar(const std::string &x);
                                                                                                                                

                                                                                                                                In the target language:

                                                                                                                                x = foo();                # Returns a string object
                                                                                                                                bar("Hello World");       # Pass string as std::string
                                                                                                                                

                                                                                                                                This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                                                                                                                This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                                                                                                                %module example
                                                                                                                                %include "std_string.i"
                                                                                                                                
                                                                                                                                using namespace std;
                                                                                                                                typedef std::string String;
                                                                                                                                ...
                                                                                                                                void foo(string s, const String &t);     // std_string typemaps still applied
                                                                                                                                

                                                                                                                                Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                                                                                                                8.4.2 std_vector.i

                                                                                                                                The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                                                                                                                %module example
                                                                                                                                %include "std_vector.i"
                                                                                                                                
                                                                                                                                namespace std {
                                                                                                                                   %template(vectori) vector<int>;
                                                                                                                                   %template(vectord) vector<double>;
                                                                                                                                };
                                                                                                                                

                                                                                                                                When a template vector<X> is instantiated a number of things happen:
                                                                                                                                • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                                                                                                                • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                                                                                                                • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                                                                                                                • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                                                                                                                • An exception handler for std::out_of_range is defined.
                                                                                                                                • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                                                                                                                To illustrate the use of this library, consider the following functions:

                                                                                                                                /* File : example.h */
                                                                                                                                
                                                                                                                                #include <vector>
                                                                                                                                #include <algorithm>
                                                                                                                                #include <functional>
                                                                                                                                #include <numeric>
                                                                                                                                
                                                                                                                                double average(std::vector<int> v) {
                                                                                                                                    return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                                                                                                                }
                                                                                                                                
                                                                                                                                std::vector<double> half(const std::vector<double>& v) {
                                                                                                                                    std::vector<double> w(v);
                                                                                                                                    for (unsigned int i=0; i<w.size(); i++)
                                                                                                                                        w[i] /= 2.0;
                                                                                                                                    return w;
                                                                                                                                }
                                                                                                                                
                                                                                                                                void halve_in_place(std::vector<double>& v) {
                                                                                                                                    std::transform(v.begin(),v.end(),v.begin(),
                                                                                                                                                   std::bind2nd(std::divides<double>(),2.0));
                                                                                                                                }
                                                                                                                                

                                                                                                                                To wrap with SWIG, you might write the following:

                                                                                                                                %module example
                                                                                                                                %{
                                                                                                                                #include "example.h"
                                                                                                                                %}
                                                                                                                                
                                                                                                                                %include "std_vector.i"
                                                                                                                                // Instantiate templates used by example
                                                                                                                                namespace std {
                                                                                                                                   %template(IntVector) vector<int>;
                                                                                                                                   %template(DoubleVector) vector<double>;
                                                                                                                                }
                                                                                                                                
                                                                                                                                // Include the header file with above prototypes
                                                                                                                                %include "example.h"
                                                                                                                                

                                                                                                                                Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                                                                                                                >>> from example import *
                                                                                                                                >>> iv = IntVector(4)         # Create an vector<int>
                                                                                                                                >>> for i in range(0,4):
                                                                                                                                ...      iv[i] = i
                                                                                                                                >>> average(iv)               # Call method
                                                                                                                                1.5
                                                                                                                                >>> average([0,1,2,3])        # Call with list
                                                                                                                                1.5
                                                                                                                                >>> half([1,2,3])             # Half a list
                                                                                                                                (0.5,1.0,1.5)
                                                                                                                                >>> halve_in_place([1,2,3])   # Oops
                                                                                                                                Traceback (most recent call last):
                                                                                                                                  File "<stdin>", line 1, in ?
                                                                                                                                TypeError: Type error. Expected _p_std__vectorTdouble_t
                                                                                                                                >>> dv = DoubleVector(4)
                                                                                                                                >>> for i in range(0,4):
                                                                                                                                ...       dv[i] = i
                                                                                                                                >>> halve_in_place(dv)       # Ok
                                                                                                                                >>> for i in dv:
                                                                                                                                ...       print i
                                                                                                                                ...
                                                                                                                                0.0
                                                                                                                                0.5
                                                                                                                                1.0
                                                                                                                                1.5
                                                                                                                                >>> dv[20] = 4.5
                                                                                                                                Traceback (most recent call last):
                                                                                                                                  File "<stdin>", line 1, in ?
                                                                                                                                  File "example.py", line 81, in __setitem__
                                                                                                                                    def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                                                                                                                IndexError: vector index out of range
                                                                                                                                >>>
                                                                                                                                

                                                                                                                                This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                                                                                                                %include "std_vector.i"
                                                                                                                                
                                                                                                                                namespace std {
                                                                                                                                    %template(IntVector) vector<int>;
                                                                                                                                }
                                                                                                                                
                                                                                                                                using namespace std;
                                                                                                                                typedef std::vector Vector;
                                                                                                                                
                                                                                                                                void foo(vector<int> *x, const Vector &x);
                                                                                                                                

                                                                                                                                Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                                                                                                                Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                                                                                                                Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                                                                                                                8.5 Utility Libraries

                                                                                                                                8.5.1 exception.i

                                                                                                                                The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                                                                                                                SWIG_exception(int code, const char *message)

                                                                                                                                Raises an exception in the target language. code is one of the following symbolic constants:

                                                                                                                                SWIG_MemoryError
                                                                                                                                SWIG_IOError
                                                                                                                                SWIG_RuntimeError
                                                                                                                                SWIG_IndexError
                                                                                                                                SWIG_TypeError
                                                                                                                                SWIG_DivisionByZero
                                                                                                                                SWIG_OverflowError
                                                                                                                                SWIG_SyntaxError
                                                                                                                                SWIG_ValueError
                                                                                                                                SWIG_SystemError
                                                                                                                                

                                                                                                                                message is a string indicating more information about the problem.

                                                                                                                                The primary use of this module is in writing language-independent exception handlers. For example:

                                                                                                                                %include "exception.i"
                                                                                                                                %exception std::vector::getitem {
                                                                                                                                    try {
                                                                                                                                        $action
                                                                                                                                    } catch (std::out_of_range& e) {
                                                                                                                                        SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                                                                                                    }
                                                                                                                                }
                                                                                                                                

                                                                                                                                ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                                                                                                                

                                                                                                                                SWIG-1.3 Documentation

                                                                                                                                
                                                                                                                                

                                                                                                                                ---

                                                                                                                                Table of Contents

                                                                                                                                
                                                                                                                                
                                                                                                                                SWIG-1.3 Development Documentation
                                                                                                                                • Sections
                                                                                                                                • SWIG Core Documentation
                                                                                                                                • Language Module Documentation
                                                                                                                                • Developer Documentation
                                                                                                                                • Documentation that has not yet been updated
                                                                                                                                1 Preface
                                                                                                                                • 1.1 Introduction
                                                                                                                                • 1.2 Special Introduction for Version 1.3
                                                                                                                                • 1.3 SWIG Versions
                                                                                                                                • 1.4 SWIG resources
                                                                                                                                • 1.5 Prerequisites
                                                                                                                                • 1.6 Organization of this manual
                                                                                                                                • 1.7 How to avoid reading the manual
                                                                                                                                • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                                                                                                                  >>> make_upper("hello world")
                                                                                                                                  'HELLO WORLD'
                                                                                                                                  >>> attach_header("Hello world")
                                                                                                                                  'header: Hello world'
                                                                                                                                  >>>
                                                                                                                                  

                                                                                                                                  This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                                                                                                                  %cstring_output_maxsize(parm, maxparm)

                                                                                                                                  This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                                                                                                                  %cstring_output_maxsize(char *path, int maxpath);
                                                                                                                                  ...
                                                                                                                                  void get_path(char *path, int maxpath);
                                                                                                                                  

                                                                                                                                  In the target language:

                                                                                                                                  >>> get_path(1024)
                                                                                                                                  '/home/beazley/Packages/Foo/Bar'
                                                                                                                                  >>>
                                                                                                                                  

                                                                                                                                  This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                                                                                                                  %cstring_output_withsize(parm, maxparm)

                                                                                                                                  This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                                                                                                                  %cstring_output_withsize(char *data, int *maxdata);
                                                                                                                                  ...
                                                                                                                                  void get_data(char *data, int *maxdata);
                                                                                                                                  

                                                                                                                                  In the target language:

                                                                                                                                  >>> get_data(1024)
                                                                                                                                  'x627388912'
                                                                                                                                  >>> get_data(1024)
                                                                                                                                  'xyzzy'
                                                                                                                                  >>>
                                                                                                                                  

                                                                                                                                  This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                                                                                                                  %cstring_output_allocate(parm, release)

                                                                                                                                  This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                                                                                                                  void foo(char **s) {
                                                                                                                                      *s = (char *) malloc(64);
                                                                                                                                      sprintf(*s, "Hello world\n");
                                                                                                                                  }
                                                                                                                                  

                                                                                                                                  The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                                                  %cstring_output_allocate(char **s, free(*$1));
                                                                                                                                  ...
                                                                                                                                  void foo(char **s);
                                                                                                                                  

                                                                                                                                  In the target language:

                                                                                                                                  >>> foo()
                                                                                                                                  'Hello world\n'
                                                                                                                                  >>>
                                                                                                                                  

                                                                                                                                  %cstring_output_allocate_size(parm, szparm, release)

                                                                                                                                  This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                                                                                                                  void foo(char **s, int *sz) {
                                                                                                                                      *s = (char *) malloc(64);
                                                                                                                                      *sz = 64;
                                                                                                                                      // Write some binary data
                                                                                                                                      ...
                                                                                                                                  }
                                                                                                                                  

                                                                                                                                  The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                                                  %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                                                                                                                  ...
                                                                                                                                  void foo(char **s, int *slen);
                                                                                                                                  

                                                                                                                                  In the target language:

                                                                                                                                  >>> foo()
                                                                                                                                  '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                                                                                                                  >>>
                                                                                                                                  

                                                                                                                                  This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                                                                                                                  char  *get_data(int *len);
                                                                                                                                  

                                                                                                                                  You could wrap it with a function like this:

                                                                                                                                  void my_get_data(char **result, int *len) {
                                                                                                                                     *result = get_data(len);
                                                                                                                                  }
                                                                                                                                  

                                                                                                                                  Comments:
                                                                                                                                  • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                                                                                                                  • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                                                                                                                  • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                                                                                                                  • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                                                                                                                  8.4 C++ Library

                                                                                                                                  The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                                                                                                                  8.4.1 std_string.i

                                                                                                                                  The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                                                                                                                  %module example
                                                                                                                                  %include "std_string.i"
                                                                                                                                  
                                                                                                                                  std::string foo();
                                                                                                                                  void        bar(const std::string &x);
                                                                                                                                  

                                                                                                                                  In the target language:

                                                                                                                                  x = foo();                # Returns a string object
                                                                                                                                  bar("Hello World");       # Pass string as std::string
                                                                                                                                  

                                                                                                                                  This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                                                                                                                  This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                                                                                                                  %module example
                                                                                                                                  %include "std_string.i"
                                                                                                                                  
                                                                                                                                  using namespace std;
                                                                                                                                  typedef std::string String;
                                                                                                                                  ...
                                                                                                                                  void foo(string s, const String &t);     // std_string typemaps still applied
                                                                                                                                  

                                                                                                                                  Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                                                                                                                  8.4.2 std_vector.i

                                                                                                                                  The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                                                                                                                  %module example
                                                                                                                                  %include "std_vector.i"
                                                                                                                                  
                                                                                                                                  namespace std {
                                                                                                                                     %template(vectori) vector<int>;
                                                                                                                                     %template(vectord) vector<double>;
                                                                                                                                  };
                                                                                                                                  

                                                                                                                                  When a template vector<X> is instantiated a number of things happen:
                                                                                                                                  • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                                                                                                                  • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                                                                                                                  • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                                                                                                                  • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                                                                                                                  • An exception handler for std::out_of_range is defined.
                                                                                                                                  • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                                                                                                                  To illustrate the use of this library, consider the following functions:

                                                                                                                                  /* File : example.h */
                                                                                                                                  
                                                                                                                                  #include <vector>
                                                                                                                                  #include <algorithm>
                                                                                                                                  #include <functional>
                                                                                                                                  #include <numeric>
                                                                                                                                  
                                                                                                                                  double average(std::vector<int> v) {
                                                                                                                                      return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                                                                                                                  }
                                                                                                                                  
                                                                                                                                  std::vector<double> half(const std::vector<double>& v) {
                                                                                                                                      std::vector<double> w(v);
                                                                                                                                      for (unsigned int i=0; i<w.size(); i++)
                                                                                                                                          w[i] /= 2.0;
                                                                                                                                      return w;
                                                                                                                                  }
                                                                                                                                  
                                                                                                                                  void halve_in_place(std::vector<double>& v) {
                                                                                                                                      std::transform(v.begin(),v.end(),v.begin(),
                                                                                                                                                     std::bind2nd(std::divides<double>(),2.0));
                                                                                                                                  }
                                                                                                                                  

                                                                                                                                  To wrap with SWIG, you might write the following:

                                                                                                                                  %module example
                                                                                                                                  %{
                                                                                                                                  #include "example.h"
                                                                                                                                  %}
                                                                                                                                  
                                                                                                                                  %include "std_vector.i"
                                                                                                                                  // Instantiate templates used by example
                                                                                                                                  namespace std {
                                                                                                                                     %template(IntVector) vector<int>;
                                                                                                                                     %template(DoubleVector) vector<double>;
                                                                                                                                  }
                                                                                                                                  
                                                                                                                                  // Include the header file with above prototypes
                                                                                                                                  %include "example.h"
                                                                                                                                  

                                                                                                                                  Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                                                                                                                  >>> from example import *
                                                                                                                                  >>> iv = IntVector(4)         # Create an vector<int>
                                                                                                                                  >>> for i in range(0,4):
                                                                                                                                  ...      iv[i] = i
                                                                                                                                  >>> average(iv)               # Call method
                                                                                                                                  1.5
                                                                                                                                  >>> average([0,1,2,3])        # Call with list
                                                                                                                                  1.5
                                                                                                                                  >>> half([1,2,3])             # Half a list
                                                                                                                                  (0.5,1.0,1.5)
                                                                                                                                  >>> halve_in_place([1,2,3])   # Oops
                                                                                                                                  Traceback (most recent call last):
                                                                                                                                    File "<stdin>", line 1, in ?
                                                                                                                                  TypeError: Type error. Expected _p_std__vectorTdouble_t
                                                                                                                                  >>> dv = DoubleVector(4)
                                                                                                                                  >>> for i in range(0,4):
                                                                                                                                  ...       dv[i] = i
                                                                                                                                  >>> halve_in_place(dv)       # Ok
                                                                                                                                  >>> for i in dv:
                                                                                                                                  ...       print i
                                                                                                                                  ...
                                                                                                                                  0.0
                                                                                                                                  0.5
                                                                                                                                  1.0
                                                                                                                                  1.5
                                                                                                                                  >>> dv[20] = 4.5
                                                                                                                                  Traceback (most recent call last):
                                                                                                                                    File "<stdin>", line 1, in ?
                                                                                                                                    File "example.py", line 81, in __setitem__
                                                                                                                                      def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                                                                                                                  IndexError: vector index out of range
                                                                                                                                  >>>
                                                                                                                                  

                                                                                                                                  This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                                                                                                                  %include "std_vector.i"
                                                                                                                                  
                                                                                                                                  namespace std {
                                                                                                                                      %template(IntVector) vector<int>;
                                                                                                                                  }
                                                                                                                                  
                                                                                                                                  using namespace std;
                                                                                                                                  typedef std::vector Vector;
                                                                                                                                  
                                                                                                                                  void foo(vector<int> *x, const Vector &x);
                                                                                                                                  

                                                                                                                                  Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                                                                                                                  Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                                                                                                                  Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                                                                                                                  8.5 Utility Libraries

                                                                                                                                  8.5.1 exception.i

                                                                                                                                  The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                                                                                                                  SWIG_exception(int code, const char *message)

                                                                                                                                  Raises an exception in the target language. code is one of the following symbolic constants:

                                                                                                                                  SWIG_MemoryError
                                                                                                                                  SWIG_IOError
                                                                                                                                  SWIG_RuntimeError
                                                                                                                                  SWIG_IndexError
                                                                                                                                  SWIG_TypeError
                                                                                                                                  SWIG_DivisionByZero
                                                                                                                                  SWIG_OverflowError
                                                                                                                                  SWIG_SyntaxError
                                                                                                                                  SWIG_ValueError
                                                                                                                                  SWIG_SystemError
                                                                                                                                  

                                                                                                                                  message is a string indicating more information about the problem.

                                                                                                                                  The primary use of this module is in writing language-independent exception handlers. For example:

                                                                                                                                  %include "exception.i"
                                                                                                                                  %exception std::vector::getitem {
                                                                                                                                      try {
                                                                                                                                          $action
                                                                                                                                      } catch (std::out_of_range& e) {
                                                                                                                                          SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                                                                                                      }
                                                                                                                                  }
                                                                                                                                  

                                                                                                                                  ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                                                                                                                  

                                                                                                                                  SWIG-1.3 Documentation

                                                                                                                                  
                                                                                                                                  

                                                                                                                                  ---

                                                                                                                                  Table of Contents

                                                                                                                                  
                                                                                                                                  
                                                                                                                                  SWIG-1.3 Development Documentation
                                                                                                                                  • Sections
                                                                                                                                  • SWIG Core Documentation
                                                                                                                                  • Language Module Documentation
                                                                                                                                  • Developer Documentation
                                                                                                                                  • Documentation that has not yet been updated
                                                                                                                                  1 Preface
                                                                                                                                  • 1.1 Introduction
                                                                                                                                  • 1.2 Special Introduction for Version 1.3
                                                                                                                                  • 1.3 SWIG Versions
                                                                                                                                  • 1.4 SWIG resources
                                                                                                                                  • 1.5 Prerequisites
                                                                                                                                  • 1.6 Organization of this manual
                                                                                                                                  • 1.7 How to avoid reading the manual
                                                                                                                                  • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                                                                                                                    >>> make_upper("hello world")
                                                                                                                                    'HELLO WORLD'
                                                                                                                                    >>> attach_header("Hello world")
                                                                                                                                    'header: Hello world'
                                                                                                                                    >>>
                                                                                                                                    

                                                                                                                                    This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                                                                                                                    %cstring_output_maxsize(parm, maxparm)

                                                                                                                                    This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                                                                                                                    %cstring_output_maxsize(char *path, int maxpath);
                                                                                                                                    ...
                                                                                                                                    void get_path(char *path, int maxpath);
                                                                                                                                    

                                                                                                                                    In the target language:

                                                                                                                                    >>> get_path(1024)
                                                                                                                                    '/home/beazley/Packages/Foo/Bar'
                                                                                                                                    >>>
                                                                                                                                    

                                                                                                                                    This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                                                                                                                    %cstring_output_withsize(parm, maxparm)

                                                                                                                                    This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                                                                                                                    %cstring_output_withsize(char *data, int *maxdata);
                                                                                                                                    ...
                                                                                                                                    void get_data(char *data, int *maxdata);
                                                                                                                                    

                                                                                                                                    In the target language:

                                                                                                                                    >>> get_data(1024)
                                                                                                                                    'x627388912'
                                                                                                                                    >>> get_data(1024)
                                                                                                                                    'xyzzy'
                                                                                                                                    >>>
                                                                                                                                    

                                                                                                                                    This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                                                                                                                    %cstring_output_allocate(parm, release)

                                                                                                                                    This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                                                                                                                    void foo(char **s) {
                                                                                                                                        *s = (char *) malloc(64);
                                                                                                                                        sprintf(*s, "Hello world\n");
                                                                                                                                    }
                                                                                                                                    

                                                                                                                                    The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                                                    %cstring_output_allocate(char **s, free(*$1));
                                                                                                                                    ...
                                                                                                                                    void foo(char **s);
                                                                                                                                    

                                                                                                                                    In the target language:

                                                                                                                                    >>> foo()
                                                                                                                                    'Hello world\n'
                                                                                                                                    >>>
                                                                                                                                    

                                                                                                                                    %cstring_output_allocate_size(parm, szparm, release)

                                                                                                                                    This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                                                                                                                    void foo(char **s, int *sz) {
                                                                                                                                        *s = (char *) malloc(64);
                                                                                                                                        *sz = 64;
                                                                                                                                        // Write some binary data
                                                                                                                                        ...
                                                                                                                                    }
                                                                                                                                    

                                                                                                                                    The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                                                    %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                                                                                                                    ...
                                                                                                                                    void foo(char **s, int *slen);
                                                                                                                                    

                                                                                                                                    In the target language:

                                                                                                                                    >>> foo()
                                                                                                                                    '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                                                                                                                    >>>
                                                                                                                                    

                                                                                                                                    This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                                                                                                                    char  *get_data(int *len);
                                                                                                                                    

                                                                                                                                    You could wrap it with a function like this:

                                                                                                                                    void my_get_data(char **result, int *len) {
                                                                                                                                       *result = get_data(len);
                                                                                                                                    }
                                                                                                                                    

                                                                                                                                    Comments:
                                                                                                                                    • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                                                                                                                    • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                                                                                                                    • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                                                                                                                    • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                                                                                                                    8.4 C++ Library

                                                                                                                                    The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                                                                                                                    8.4.1 std_string.i

                                                                                                                                    The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                                                                                                                    %module example
                                                                                                                                    %include "std_string.i"
                                                                                                                                    
                                                                                                                                    std::string foo();
                                                                                                                                    void        bar(const std::string &x);
                                                                                                                                    

                                                                                                                                    In the target language:

                                                                                                                                    x = foo();                # Returns a string object
                                                                                                                                    bar("Hello World");       # Pass string as std::string
                                                                                                                                    

                                                                                                                                    This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                                                                                                                    This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                                                                                                                    %module example
                                                                                                                                    %include "std_string.i"
                                                                                                                                    
                                                                                                                                    using namespace std;
                                                                                                                                    typedef std::string String;
                                                                                                                                    ...
                                                                                                                                    void foo(string s, const String &t);     // std_string typemaps still applied
                                                                                                                                    

                                                                                                                                    Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                                                                                                                    8.4.2 std_vector.i

                                                                                                                                    The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                                                                                                                    %module example
                                                                                                                                    %include "std_vector.i"
                                                                                                                                    
                                                                                                                                    namespace std {
                                                                                                                                       %template(vectori) vector<int>;
                                                                                                                                       %template(vectord) vector<double>;
                                                                                                                                    };
                                                                                                                                    

                                                                                                                                    When a template vector<X> is instantiated a number of things happen:
                                                                                                                                    • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                                                                                                                    • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                                                                                                                    • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                                                                                                                    • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                                                                                                                    • An exception handler for std::out_of_range is defined.
                                                                                                                                    • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                                                                                                                    To illustrate the use of this library, consider the following functions:

                                                                                                                                    /* File : example.h */
                                                                                                                                    
                                                                                                                                    #include <vector>
                                                                                                                                    #include <algorithm>
                                                                                                                                    #include <functional>
                                                                                                                                    #include <numeric>
                                                                                                                                    
                                                                                                                                    double average(std::vector<int> v) {
                                                                                                                                        return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                                                                                                                    }
                                                                                                                                    
                                                                                                                                    std::vector<double> half(const std::vector<double>& v) {
                                                                                                                                        std::vector<double> w(v);
                                                                                                                                        for (unsigned int i=0; i<w.size(); i++)
                                                                                                                                            w[i] /= 2.0;
                                                                                                                                        return w;
                                                                                                                                    }
                                                                                                                                    
                                                                                                                                    void halve_in_place(std::vector<double>& v) {
                                                                                                                                        std::transform(v.begin(),v.end(),v.begin(),
                                                                                                                                                       std::bind2nd(std::divides<double>(),2.0));
                                                                                                                                    }
                                                                                                                                    

                                                                                                                                    To wrap with SWIG, you might write the following:

                                                                                                                                    %module example
                                                                                                                                    %{
                                                                                                                                    #include "example.h"
                                                                                                                                    %}
                                                                                                                                    
                                                                                                                                    %include "std_vector.i"
                                                                                                                                    // Instantiate templates used by example
                                                                                                                                    namespace std {
                                                                                                                                       %template(IntVector) vector<int>;
                                                                                                                                       %template(DoubleVector) vector<double>;
                                                                                                                                    }
                                                                                                                                    
                                                                                                                                    // Include the header file with above prototypes
                                                                                                                                    %include "example.h"
                                                                                                                                    

                                                                                                                                    Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                                                                                                                    >>> from example import *
                                                                                                                                    >>> iv = IntVector(4)         # Create an vector<int>
                                                                                                                                    >>> for i in range(0,4):
                                                                                                                                    ...      iv[i] = i
                                                                                                                                    >>> average(iv)               # Call method
                                                                                                                                    1.5
                                                                                                                                    >>> average([0,1,2,3])        # Call with list
                                                                                                                                    1.5
                                                                                                                                    >>> half([1,2,3])             # Half a list
                                                                                                                                    (0.5,1.0,1.5)
                                                                                                                                    >>> halve_in_place([1,2,3])   # Oops
                                                                                                                                    Traceback (most recent call last):
                                                                                                                                      File "<stdin>", line 1, in ?
                                                                                                                                    TypeError: Type error. Expected _p_std__vectorTdouble_t
                                                                                                                                    >>> dv = DoubleVector(4)
                                                                                                                                    >>> for i in range(0,4):
                                                                                                                                    ...       dv[i] = i
                                                                                                                                    >>> halve_in_place(dv)       # Ok
                                                                                                                                    >>> for i in dv:
                                                                                                                                    ...       print i
                                                                                                                                    ...
                                                                                                                                    0.0
                                                                                                                                    0.5
                                                                                                                                    1.0
                                                                                                                                    1.5
                                                                                                                                    >>> dv[20] = 4.5
                                                                                                                                    Traceback (most recent call last):
                                                                                                                                      File "<stdin>", line 1, in ?
                                                                                                                                      File "example.py", line 81, in __setitem__
                                                                                                                                        def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                                                                                                                    IndexError: vector index out of range
                                                                                                                                    >>>
                                                                                                                                    

                                                                                                                                    This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                                                                                                                    %include "std_vector.i"
                                                                                                                                    
                                                                                                                                    namespace std {
                                                                                                                                        %template(IntVector) vector<int>;
                                                                                                                                    }
                                                                                                                                    
                                                                                                                                    using namespace std;
                                                                                                                                    typedef std::vector Vector;
                                                                                                                                    
                                                                                                                                    void foo(vector<int> *x, const Vector &x);
                                                                                                                                    

                                                                                                                                    Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                                                                                                                    Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                                                                                                                    Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                                                                                                                    8.5 Utility Libraries

                                                                                                                                    8.5.1 exception.i

                                                                                                                                    The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                                                                                                                    SWIG_exception(int code, const char *message)

                                                                                                                                    Raises an exception in the target language. code is one of the following symbolic constants:

                                                                                                                                    SWIG_MemoryError
                                                                                                                                    SWIG_IOError
                                                                                                                                    SWIG_RuntimeError
                                                                                                                                    SWIG_IndexError
                                                                                                                                    SWIG_TypeError
                                                                                                                                    SWIG_DivisionByZero
                                                                                                                                    SWIG_OverflowError
                                                                                                                                    SWIG_SyntaxError
                                                                                                                                    SWIG_ValueError
                                                                                                                                    SWIG_SystemError
                                                                                                                                    

                                                                                                                                    message is a string indicating more information about the problem.

                                                                                                                                    The primary use of this module is in writing language-independent exception handlers. For example:

                                                                                                                                    %include "exception.i"
                                                                                                                                    %exception std::vector::getitem {
                                                                                                                                        try {
                                                                                                                                            $action
                                                                                                                                        } catch (std::out_of_range& e) {
                                                                                                                                            SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                                                                                                        }
                                                                                                                                    }
                                                                                                                                    

                                                                                                                                    ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                                                                                                                    

                                                                                                                                    SWIG-1.3 Documentation

                                                                                                                                    
                                                                                                                                    

                                                                                                                                    ---

                                                                                                                                    Table of Contents

                                                                                                                                    
                                                                                                                                    
                                                                                                                                    SWIG-1.3 Development Documentation
                                                                                                                                    • Sections
                                                                                                                                    • SWIG Core Documentation
                                                                                                                                    • Language Module Documentation
                                                                                                                                    • Developer Documentation
                                                                                                                                    • Documentation that has not yet been updated
                                                                                                                                    1 Preface
                                                                                                                                    • 1.1 Introduction
                                                                                                                                    • 1.2 Special Introduction for Version 1.3
                                                                                                                                    • 1.3 SWIG Versions
                                                                                                                                    • 1.4 SWIG resources
                                                                                                                                    • 1.5 Prerequisites
                                                                                                                                    • 1.6 Organization of this manual
                                                                                                                                    • 1.7 How to avoid reading the manual
                                                                                                                                    • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                                                                                                                      >>> make_upper("hello world")
                                                                                                                                      'HELLO WORLD'
                                                                                                                                      >>> attach_header("Hello world")
                                                                                                                                      'header: Hello world'
                                                                                                                                      >>>
                                                                                                                                      

                                                                                                                                      This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                                                                                                                      %cstring_output_maxsize(parm, maxparm)

                                                                                                                                      This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                                                                                                                      %cstring_output_maxsize(char *path, int maxpath);
                                                                                                                                      ...
                                                                                                                                      void get_path(char *path, int maxpath);
                                                                                                                                      

                                                                                                                                      In the target language:

                                                                                                                                      >>> get_path(1024)
                                                                                                                                      '/home/beazley/Packages/Foo/Bar'
                                                                                                                                      >>>
                                                                                                                                      

                                                                                                                                      This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                                                                                                                      %cstring_output_withsize(parm, maxparm)

                                                                                                                                      This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                                                                                                                      %cstring_output_withsize(char *data, int *maxdata);
                                                                                                                                      ...
                                                                                                                                      void get_data(char *data, int *maxdata);
                                                                                                                                      

                                                                                                                                      In the target language:

                                                                                                                                      >>> get_data(1024)
                                                                                                                                      'x627388912'
                                                                                                                                      >>> get_data(1024)
                                                                                                                                      'xyzzy'
                                                                                                                                      >>>
                                                                                                                                      

                                                                                                                                      This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                                                                                                                      %cstring_output_allocate(parm, release)

                                                                                                                                      This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                                                                                                                      void foo(char **s) {
                                                                                                                                          *s = (char *) malloc(64);
                                                                                                                                          sprintf(*s, "Hello world\n");
                                                                                                                                      }
                                                                                                                                      

                                                                                                                                      The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                                                      %cstring_output_allocate(char **s, free(*$1));
                                                                                                                                      ...
                                                                                                                                      void foo(char **s);
                                                                                                                                      

                                                                                                                                      In the target language:

                                                                                                                                      >>> foo()
                                                                                                                                      'Hello world\n'
                                                                                                                                      >>>
                                                                                                                                      

                                                                                                                                      %cstring_output_allocate_size(parm, szparm, release)

                                                                                                                                      This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                                                                                                                      void foo(char **s, int *sz) {
                                                                                                                                          *s = (char *) malloc(64);
                                                                                                                                          *sz = 64;
                                                                                                                                          // Write some binary data
                                                                                                                                          ...
                                                                                                                                      }
                                                                                                                                      

                                                                                                                                      The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                                                      %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                                                                                                                      ...
                                                                                                                                      void foo(char **s, int *slen);
                                                                                                                                      

                                                                                                                                      In the target language:

                                                                                                                                      >>> foo()
                                                                                                                                      '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                                                                                                                      >>>
                                                                                                                                      

                                                                                                                                      This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                                                                                                                      char  *get_data(int *len);
                                                                                                                                      

                                                                                                                                      You could wrap it with a function like this:

                                                                                                                                      void my_get_data(char **result, int *len) {
                                                                                                                                         *result = get_data(len);
                                                                                                                                      }
                                                                                                                                      

                                                                                                                                      Comments:
                                                                                                                                      • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                                                                                                                      • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                                                                                                                      • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                                                                                                                      • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                                                                                                                      8.4 C++ Library

                                                                                                                                      The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                                                                                                                      8.4.1 std_string.i

                                                                                                                                      The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                                                                                                                      %module example
                                                                                                                                      %include "std_string.i"
                                                                                                                                      
                                                                                                                                      std::string foo();
                                                                                                                                      void        bar(const std::string &x);
                                                                                                                                      

                                                                                                                                      In the target language:

                                                                                                                                      x = foo();                # Returns a string object
                                                                                                                                      bar("Hello World");       # Pass string as std::string
                                                                                                                                      

                                                                                                                                      This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                                                                                                                      This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                                                                                                                      %module example
                                                                                                                                      %include "std_string.i"
                                                                                                                                      
                                                                                                                                      using namespace std;
                                                                                                                                      typedef std::string String;
                                                                                                                                      ...
                                                                                                                                      void foo(string s, const String &t);     // std_string typemaps still applied
                                                                                                                                      

                                                                                                                                      Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                                                                                                                      8.4.2 std_vector.i

                                                                                                                                      The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                                                                                                                      %module example
                                                                                                                                      %include "std_vector.i"
                                                                                                                                      
                                                                                                                                      namespace std {
                                                                                                                                         %template(vectori) vector<int>;
                                                                                                                                         %template(vectord) vector<double>;
                                                                                                                                      };
                                                                                                                                      

                                                                                                                                      When a template vector<X> is instantiated a number of things happen:
                                                                                                                                      • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                                                                                                                      • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                                                                                                                      • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                                                                                                                      • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                                                                                                                      • An exception handler for std::out_of_range is defined.
                                                                                                                                      • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                                                                                                                      To illustrate the use of this library, consider the following functions:

                                                                                                                                      /* File : example.h */
                                                                                                                                      
                                                                                                                                      #include <vector>
                                                                                                                                      #include <algorithm>
                                                                                                                                      #include <functional>
                                                                                                                                      #include <numeric>
                                                                                                                                      
                                                                                                                                      double average(std::vector<int> v) {
                                                                                                                                          return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                                                                                                                      }
                                                                                                                                      
                                                                                                                                      std::vector<double> half(const std::vector<double>& v) {
                                                                                                                                          std::vector<double> w(v);
                                                                                                                                          for (unsigned int i=0; i<w.size(); i++)
                                                                                                                                              w[i] /= 2.0;
                                                                                                                                          return w;
                                                                                                                                      }
                                                                                                                                      
                                                                                                                                      void halve_in_place(std::vector<double>& v) {
                                                                                                                                          std::transform(v.begin(),v.end(),v.begin(),
                                                                                                                                                         std::bind2nd(std::divides<double>(),2.0));
                                                                                                                                      }
                                                                                                                                      

                                                                                                                                      To wrap with SWIG, you might write the following:

                                                                                                                                      %module example
                                                                                                                                      %{
                                                                                                                                      #include "example.h"
                                                                                                                                      %}
                                                                                                                                      
                                                                                                                                      %include "std_vector.i"
                                                                                                                                      // Instantiate templates used by example
                                                                                                                                      namespace std {
                                                                                                                                         %template(IntVector) vector<int>;
                                                                                                                                         %template(DoubleVector) vector<double>;
                                                                                                                                      }
                                                                                                                                      
                                                                                                                                      // Include the header file with above prototypes
                                                                                                                                      %include "example.h"
                                                                                                                                      

                                                                                                                                      Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                                                                                                                      >>> from example import *
                                                                                                                                      >>> iv = IntVector(4)         # Create an vector<int>
                                                                                                                                      >>> for i in range(0,4):
                                                                                                                                      ...      iv[i] = i
                                                                                                                                      >>> average(iv)               # Call method
                                                                                                                                      1.5
                                                                                                                                      >>> average([0,1,2,3])        # Call with list
                                                                                                                                      1.5
                                                                                                                                      >>> half([1,2,3])             # Half a list
                                                                                                                                      (0.5,1.0,1.5)
                                                                                                                                      >>> halve_in_place([1,2,3])   # Oops
                                                                                                                                      Traceback (most recent call last):
                                                                                                                                        File "<stdin>", line 1, in ?
                                                                                                                                      TypeError: Type error. Expected _p_std__vectorTdouble_t
                                                                                                                                      >>> dv = DoubleVector(4)
                                                                                                                                      >>> for i in range(0,4):
                                                                                                                                      ...       dv[i] = i
                                                                                                                                      >>> halve_in_place(dv)       # Ok
                                                                                                                                      >>> for i in dv:
                                                                                                                                      ...       print i
                                                                                                                                      ...
                                                                                                                                      0.0
                                                                                                                                      0.5
                                                                                                                                      1.0
                                                                                                                                      1.5
                                                                                                                                      >>> dv[20] = 4.5
                                                                                                                                      Traceback (most recent call last):
                                                                                                                                        File "<stdin>", line 1, in ?
                                                                                                                                        File "example.py", line 81, in __setitem__
                                                                                                                                          def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                                                                                                                      IndexError: vector index out of range
                                                                                                                                      >>>
                                                                                                                                      

                                                                                                                                      This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                                                                                                                      %include "std_vector.i"
                                                                                                                                      
                                                                                                                                      namespace std {
                                                                                                                                          %template(IntVector) vector<int>;
                                                                                                                                      }
                                                                                                                                      
                                                                                                                                      using namespace std;
                                                                                                                                      typedef std::vector Vector;
                                                                                                                                      
                                                                                                                                      void foo(vector<int> *x, const Vector &x);
                                                                                                                                      

                                                                                                                                      Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                                                                                                                      Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                                                                                                                      Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                                                                                                                      8.5 Utility Libraries

                                                                                                                                      8.5.1 exception.i

                                                                                                                                      The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                                                                                                                      SWIG_exception(int code, const char *message)

                                                                                                                                      Raises an exception in the target language. code is one of the following symbolic constants:

                                                                                                                                      SWIG_MemoryError
                                                                                                                                      SWIG_IOError
                                                                                                                                      SWIG_RuntimeError
                                                                                                                                      SWIG_IndexError
                                                                                                                                      SWIG_TypeError
                                                                                                                                      SWIG_DivisionByZero
                                                                                                                                      SWIG_OverflowError
                                                                                                                                      SWIG_SyntaxError
                                                                                                                                      SWIG_ValueError
                                                                                                                                      SWIG_SystemError
                                                                                                                                      

                                                                                                                                      message is a string indicating more information about the problem.

                                                                                                                                      The primary use of this module is in writing language-independent exception handlers. For example:

                                                                                                                                      %include "exception.i"
                                                                                                                                      %exception std::vector::getitem {
                                                                                                                                          try {
                                                                                                                                              $action
                                                                                                                                          } catch (std::out_of_range& e) {
                                                                                                                                              SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                                                                                                          }
                                                                                                                                      }
                                                                                                                                      

                                                                                                                                      ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                                                                                                                      

                                                                                                                                      SWIG-1.3 Documentation

                                                                                                                                      
                                                                                                                                      

                                                                                                                                      ---

                                                                                                                                      Table of Contents

                                                                                                                                      
                                                                                                                                      
                                                                                                                                      SWIG-1.3 Development Documentation
                                                                                                                                      • Sections
                                                                                                                                      • SWIG Core Documentation
                                                                                                                                      • Language Module Documentation
                                                                                                                                      • Developer Documentation
                                                                                                                                      • Documentation that has not yet been updated
                                                                                                                                      1 Preface
                                                                                                                                      • 1.1 Introduction
                                                                                                                                      • 1.2 Special Introduction for Version 1.3
                                                                                                                                      • 1.3 SWIG Versions
                                                                                                                                      • 1.4 SWIG resources
                                                                                                                                      • 1.5 Prerequisites
                                                                                                                                      • 1.6 Organization of this manual
                                                                                                                                      • 1.7 How to avoid reading the manual
                                                                                                                                      • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                                                                                                                        >>> make_upper("hello world")
                                                                                                                                        'HELLO WORLD'
                                                                                                                                        >>> attach_header("Hello world")
                                                                                                                                        'header: Hello world'
                                                                                                                                        >>>
                                                                                                                                        

                                                                                                                                        This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                                                                                                                        %cstring_output_maxsize(parm, maxparm)

                                                                                                                                        This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                                                                                                                        %cstring_output_maxsize(char *path, int maxpath);
                                                                                                                                        ...
                                                                                                                                        void get_path(char *path, int maxpath);
                                                                                                                                        

                                                                                                                                        In the target language:

                                                                                                                                        >>> get_path(1024)
                                                                                                                                        '/home/beazley/Packages/Foo/Bar'
                                                                                                                                        >>>
                                                                                                                                        

                                                                                                                                        This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                                                                                                                        %cstring_output_withsize(parm, maxparm)

                                                                                                                                        This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                                                                                                                        %cstring_output_withsize(char *data, int *maxdata);
                                                                                                                                        ...
                                                                                                                                        void get_data(char *data, int *maxdata);
                                                                                                                                        

                                                                                                                                        In the target language:

                                                                                                                                        >>> get_data(1024)
                                                                                                                                        'x627388912'
                                                                                                                                        >>> get_data(1024)
                                                                                                                                        'xyzzy'
                                                                                                                                        >>>
                                                                                                                                        

                                                                                                                                        This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                                                                                                                        %cstring_output_allocate(parm, release)

                                                                                                                                        This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                                                                                                                        void foo(char **s) {
                                                                                                                                            *s = (char *) malloc(64);
                                                                                                                                            sprintf(*s, "Hello world\n");
                                                                                                                                        }
                                                                                                                                        

                                                                                                                                        The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                                                        %cstring_output_allocate(char **s, free(*$1));
                                                                                                                                        ...
                                                                                                                                        void foo(char **s);
                                                                                                                                        

                                                                                                                                        In the target language:

                                                                                                                                        >>> foo()
                                                                                                                                        'Hello world\n'
                                                                                                                                        >>>
                                                                                                                                        

                                                                                                                                        %cstring_output_allocate_size(parm, szparm, release)

                                                                                                                                        This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                                                                                                                        void foo(char **s, int *sz) {
                                                                                                                                            *s = (char *) malloc(64);
                                                                                                                                            *sz = 64;
                                                                                                                                            // Write some binary data
                                                                                                                                            ...
                                                                                                                                        }
                                                                                                                                        

                                                                                                                                        The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                                                        %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                                                                                                                        ...
                                                                                                                                        void foo(char **s, int *slen);
                                                                                                                                        

                                                                                                                                        In the target language:

                                                                                                                                        >>> foo()
                                                                                                                                        '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                                                                                                                        >>>
                                                                                                                                        

                                                                                                                                        This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                                                                                                                        char  *get_data(int *len);
                                                                                                                                        

                                                                                                                                        You could wrap it with a function like this:

                                                                                                                                        void my_get_data(char **result, int *len) {
                                                                                                                                           *result = get_data(len);
                                                                                                                                        }
                                                                                                                                        

                                                                                                                                        Comments:
                                                                                                                                        • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                                                                                                                        • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                                                                                                                        • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                                                                                                                        • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                                                                                                                        8.4 C++ Library

                                                                                                                                        The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                                                                                                                        8.4.1 std_string.i

                                                                                                                                        The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                                                                                                                        %module example
                                                                                                                                        %include "std_string.i"
                                                                                                                                        
                                                                                                                                        std::string foo();
                                                                                                                                        void        bar(const std::string &x);
                                                                                                                                        

                                                                                                                                        In the target language:

                                                                                                                                        x = foo();                # Returns a string object
                                                                                                                                        bar("Hello World");       # Pass string as std::string
                                                                                                                                        

                                                                                                                                        This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                                                                                                                        This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                                                                                                                        %module example
                                                                                                                                        %include "std_string.i"
                                                                                                                                        
                                                                                                                                        using namespace std;
                                                                                                                                        typedef std::string String;
                                                                                                                                        ...
                                                                                                                                        void foo(string s, const String &t);     // std_string typemaps still applied
                                                                                                                                        

                                                                                                                                        Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                                                                                                                        8.4.2 std_vector.i

                                                                                                                                        The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                                                                                                                        %module example
                                                                                                                                        %include "std_vector.i"
                                                                                                                                        
                                                                                                                                        namespace std {
                                                                                                                                           %template(vectori) vector<int>;
                                                                                                                                           %template(vectord) vector<double>;
                                                                                                                                        };
                                                                                                                                        

                                                                                                                                        When a template vector<X> is instantiated a number of things happen:
                                                                                                                                        • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                                                                                                                        • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                                                                                                                        • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                                                                                                                        • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                                                                                                                        • An exception handler for std::out_of_range is defined.
                                                                                                                                        • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                                                                                                                        To illustrate the use of this library, consider the following functions:

                                                                                                                                        /* File : example.h */
                                                                                                                                        
                                                                                                                                        #include <vector>
                                                                                                                                        #include <algorithm>
                                                                                                                                        #include <functional>
                                                                                                                                        #include <numeric>
                                                                                                                                        
                                                                                                                                        double average(std::vector<int> v) {
                                                                                                                                            return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                                                                                                                        }
                                                                                                                                        
                                                                                                                                        std::vector<double> half(const std::vector<double>& v) {
                                                                                                                                            std::vector<double> w(v);
                                                                                                                                            for (unsigned int i=0; i<w.size(); i++)
                                                                                                                                                w[i] /= 2.0;
                                                                                                                                            return w;
                                                                                                                                        }
                                                                                                                                        
                                                                                                                                        void halve_in_place(std::vector<double>& v) {
                                                                                                                                            std::transform(v.begin(),v.end(),v.begin(),
                                                                                                                                                           std::bind2nd(std::divides<double>(),2.0));
                                                                                                                                        }
                                                                                                                                        

                                                                                                                                        To wrap with SWIG, you might write the following:

                                                                                                                                        %module example
                                                                                                                                        %{
                                                                                                                                        #include "example.h"
                                                                                                                                        %}
                                                                                                                                        
                                                                                                                                        %include "std_vector.i"
                                                                                                                                        // Instantiate templates used by example
                                                                                                                                        namespace std {
                                                                                                                                           %template(IntVector) vector<int>;
                                                                                                                                           %template(DoubleVector) vector<double>;
                                                                                                                                        }
                                                                                                                                        
                                                                                                                                        // Include the header file with above prototypes
                                                                                                                                        %include "example.h"
                                                                                                                                        

                                                                                                                                        Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                                                                                                                        >>> from example import *
                                                                                                                                        >>> iv = IntVector(4)         # Create an vector<int>
                                                                                                                                        >>> for i in range(0,4):
                                                                                                                                        ...      iv[i] = i
                                                                                                                                        >>> average(iv)               # Call method
                                                                                                                                        1.5
                                                                                                                                        >>> average([0,1,2,3])        # Call with list
                                                                                                                                        1.5
                                                                                                                                        >>> half([1,2,3])             # Half a list
                                                                                                                                        (0.5,1.0,1.5)
                                                                                                                                        >>> halve_in_place([1,2,3])   # Oops
                                                                                                                                        Traceback (most recent call last):
                                                                                                                                          File "<stdin>", line 1, in ?
                                                                                                                                        TypeError: Type error. Expected _p_std__vectorTdouble_t
                                                                                                                                        >>> dv = DoubleVector(4)
                                                                                                                                        >>> for i in range(0,4):
                                                                                                                                        ...       dv[i] = i
                                                                                                                                        >>> halve_in_place(dv)       # Ok
                                                                                                                                        >>> for i in dv:
                                                                                                                                        ...       print i
                                                                                                                                        ...
                                                                                                                                        0.0
                                                                                                                                        0.5
                                                                                                                                        1.0
                                                                                                                                        1.5
                                                                                                                                        >>> dv[20] = 4.5
                                                                                                                                        Traceback (most recent call last):
                                                                                                                                          File "<stdin>", line 1, in ?
                                                                                                                                          File "example.py", line 81, in __setitem__
                                                                                                                                            def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                                                                                                                        IndexError: vector index out of range
                                                                                                                                        >>>
                                                                                                                                        

                                                                                                                                        This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                                                                                                                        %include "std_vector.i"
                                                                                                                                        
                                                                                                                                        namespace std {
                                                                                                                                            %template(IntVector) vector<int>;
                                                                                                                                        }
                                                                                                                                        
                                                                                                                                        using namespace std;
                                                                                                                                        typedef std::vector Vector;
                                                                                                                                        
                                                                                                                                        void foo(vector<int> *x, const Vector &x);
                                                                                                                                        

                                                                                                                                        Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                                                                                                                        Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                                                                                                                        Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                                                                                                                        8.5 Utility Libraries

                                                                                                                                        8.5.1 exception.i

                                                                                                                                        The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                                                                                                                        SWIG_exception(int code, const char *message)

                                                                                                                                        Raises an exception in the target language. code is one of the following symbolic constants:

                                                                                                                                        SWIG_MemoryError
                                                                                                                                        SWIG_IOError
                                                                                                                                        SWIG_RuntimeError
                                                                                                                                        SWIG_IndexError
                                                                                                                                        SWIG_TypeError
                                                                                                                                        SWIG_DivisionByZero
                                                                                                                                        SWIG_OverflowError
                                                                                                                                        SWIG_SyntaxError
                                                                                                                                        SWIG_ValueError
                                                                                                                                        SWIG_SystemError
                                                                                                                                        

                                                                                                                                        message is a string indicating more information about the problem.

                                                                                                                                        The primary use of this module is in writing language-independent exception handlers. For example:

                                                                                                                                        %include "exception.i"
                                                                                                                                        %exception std::vector::getitem {
                                                                                                                                            try {
                                                                                                                                                $action
                                                                                                                                            } catch (std::out_of_range& e) {
                                                                                                                                                SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                                                                                                            }
                                                                                                                                        }
                                                                                                                                        

                                                                                                                                        ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                                                                                                                        

                                                                                                                                        SWIG-1.3 Documentation

                                                                                                                                        
                                                                                                                                        

                                                                                                                                        ---

                                                                                                                                        Table of Contents

                                                                                                                                        
                                                                                                                                        
                                                                                                                                        SWIG-1.3 Development Documentation
                                                                                                                                        • Sections
                                                                                                                                        • SWIG Core Documentation
                                                                                                                                        • Language Module Documentation
                                                                                                                                        • Developer Documentation
                                                                                                                                        • Documentation that has not yet been updated
                                                                                                                                        1 Preface
                                                                                                                                        • 1.1 Introduction
                                                                                                                                        • 1.2 Special Introduction for Version 1.3
                                                                                                                                        • 1.3 SWIG Versions
                                                                                                                                        • 1.4 SWIG resources
                                                                                                                                        • 1.5 Prerequisites
                                                                                                                                        • 1.6 Organization of this manual
                                                                                                                                        • 1.7 How to avoid reading the manual
                                                                                                                                        • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                                                                                                                          >>> make_upper("hello world")
                                                                                                                                          'HELLO WORLD'
                                                                                                                                          >>> attach_header("Hello world")
                                                                                                                                          'header: Hello world'
                                                                                                                                          >>>
                                                                                                                                          

                                                                                                                                          This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                                                                                                                          %cstring_output_maxsize(parm, maxparm)

                                                                                                                                          This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                                                                                                                          %cstring_output_maxsize(char *path, int maxpath);
                                                                                                                                          ...
                                                                                                                                          void get_path(char *path, int maxpath);
                                                                                                                                          

                                                                                                                                          In the target language:

                                                                                                                                          >>> get_path(1024)
                                                                                                                                          '/home/beazley/Packages/Foo/Bar'
                                                                                                                                          >>>
                                                                                                                                          

                                                                                                                                          This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                                                                                                                          %cstring_output_withsize(parm, maxparm)

                                                                                                                                          This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                                                                                                                          %cstring_output_withsize(char *data, int *maxdata);
                                                                                                                                          ...
                                                                                                                                          void get_data(char *data, int *maxdata);
                                                                                                                                          

                                                                                                                                          In the target language:

                                                                                                                                          >>> get_data(1024)
                                                                                                                                          'x627388912'
                                                                                                                                          >>> get_data(1024)
                                                                                                                                          'xyzzy'
                                                                                                                                          >>>
                                                                                                                                          

                                                                                                                                          This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                                                                                                                          %cstring_output_allocate(parm, release)

                                                                                                                                          This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                                                                                                                          void foo(char **s) {
                                                                                                                                              *s = (char *) malloc(64);
                                                                                                                                              sprintf(*s, "Hello world\n");
                                                                                                                                          }
                                                                                                                                          

                                                                                                                                          The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                                                          %cstring_output_allocate(char **s, free(*$1));
                                                                                                                                          ...
                                                                                                                                          void foo(char **s);
                                                                                                                                          

                                                                                                                                          In the target language:

                                                                                                                                          >>> foo()
                                                                                                                                          'Hello world\n'
                                                                                                                                          >>>
                                                                                                                                          

                                                                                                                                          %cstring_output_allocate_size(parm, szparm, release)

                                                                                                                                          This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                                                                                                                          void foo(char **s, int *sz) {
                                                                                                                                              *s = (char *) malloc(64);
                                                                                                                                              *sz = 64;
                                                                                                                                              // Write some binary data
                                                                                                                                              ...
                                                                                                                                          }
                                                                                                                                          

                                                                                                                                          The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                                                          %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                                                                                                                          ...
                                                                                                                                          void foo(char **s, int *slen);
                                                                                                                                          

                                                                                                                                          In the target language:

                                                                                                                                          >>> foo()
                                                                                                                                          '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                                                                                                                          >>>
                                                                                                                                          

                                                                                                                                          This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                                                                                                                          char  *get_data(int *len);
                                                                                                                                          

                                                                                                                                          You could wrap it with a function like this:

                                                                                                                                          void my_get_data(char **result, int *len) {
                                                                                                                                             *result = get_data(len);
                                                                                                                                          }
                                                                                                                                          

                                                                                                                                          Comments:
                                                                                                                                          • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                                                                                                                          • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                                                                                                                          • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                                                                                                                          • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                                                                                                                          8.4 C++ Library

                                                                                                                                          The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                                                                                                                          8.4.1 std_string.i

                                                                                                                                          The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                                                                                                                          %module example
                                                                                                                                          %include "std_string.i"
                                                                                                                                          
                                                                                                                                          std::string foo();
                                                                                                                                          void        bar(const std::string &x);
                                                                                                                                          

                                                                                                                                          In the target language:

                                                                                                                                          x = foo();                # Returns a string object
                                                                                                                                          bar("Hello World");       # Pass string as std::string
                                                                                                                                          

                                                                                                                                          This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                                                                                                                          This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                                                                                                                          %module example
                                                                                                                                          %include "std_string.i"
                                                                                                                                          
                                                                                                                                          using namespace std;
                                                                                                                                          typedef std::string String;
                                                                                                                                          ...
                                                                                                                                          void foo(string s, const String &t);     // std_string typemaps still applied
                                                                                                                                          

                                                                                                                                          Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                                                                                                                          8.4.2 std_vector.i

                                                                                                                                          The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                                                                                                                          %module example
                                                                                                                                          %include "std_vector.i"
                                                                                                                                          
                                                                                                                                          namespace std {
                                                                                                                                             %template(vectori) vector<int>;
                                                                                                                                             %template(vectord) vector<double>;
                                                                                                                                          };
                                                                                                                                          

                                                                                                                                          When a template vector<X> is instantiated a number of things happen:
                                                                                                                                          • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                                                                                                                          • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                                                                                                                          • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                                                                                                                          • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                                                                                                                          • An exception handler for std::out_of_range is defined.
                                                                                                                                          • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                                                                                                                          To illustrate the use of this library, consider the following functions:

                                                                                                                                          /* File : example.h */
                                                                                                                                          
                                                                                                                                          #include <vector>
                                                                                                                                          #include <algorithm>
                                                                                                                                          #include <functional>
                                                                                                                                          #include <numeric>
                                                                                                                                          
                                                                                                                                          double average(std::vector<int> v) {
                                                                                                                                              return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                                                                                                                          }
                                                                                                                                          
                                                                                                                                          std::vector<double> half(const std::vector<double>& v) {
                                                                                                                                              std::vector<double> w(v);
                                                                                                                                              for (unsigned int i=0; i<w.size(); i++)
                                                                                                                                                  w[i] /= 2.0;
                                                                                                                                              return w;
                                                                                                                                          }
                                                                                                                                          
                                                                                                                                          void halve_in_place(std::vector<double>& v) {
                                                                                                                                              std::transform(v.begin(),v.end(),v.begin(),
                                                                                                                                                             std::bind2nd(std::divides<double>(),2.0));
                                                                                                                                          }
                                                                                                                                          

                                                                                                                                          To wrap with SWIG, you might write the following:

                                                                                                                                          %module example
                                                                                                                                          %{
                                                                                                                                          #include "example.h"
                                                                                                                                          %}
                                                                                                                                          
                                                                                                                                          %include "std_vector.i"
                                                                                                                                          // Instantiate templates used by example
                                                                                                                                          namespace std {
                                                                                                                                             %template(IntVector) vector<int>;
                                                                                                                                             %template(DoubleVector) vector<double>;
                                                                                                                                          }
                                                                                                                                          
                                                                                                                                          // Include the header file with above prototypes
                                                                                                                                          %include "example.h"
                                                                                                                                          

                                                                                                                                          Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                                                                                                                          >>> from example import *
                                                                                                                                          >>> iv = IntVector(4)         # Create an vector<int>
                                                                                                                                          >>> for i in range(0,4):
                                                                                                                                          ...      iv[i] = i
                                                                                                                                          >>> average(iv)               # Call method
                                                                                                                                          1.5
                                                                                                                                          >>> average([0,1,2,3])        # Call with list
                                                                                                                                          1.5
                                                                                                                                          >>> half([1,2,3])             # Half a list
                                                                                                                                          (0.5,1.0,1.5)
                                                                                                                                          >>> halve_in_place([1,2,3])   # Oops
                                                                                                                                          Traceback (most recent call last):
                                                                                                                                            File "<stdin>", line 1, in ?
                                                                                                                                          TypeError: Type error. Expected _p_std__vectorTdouble_t
                                                                                                                                          >>> dv = DoubleVector(4)
                                                                                                                                          >>> for i in range(0,4):
                                                                                                                                          ...       dv[i] = i
                                                                                                                                          >>> halve_in_place(dv)       # Ok
                                                                                                                                          >>> for i in dv:
                                                                                                                                          ...       print i
                                                                                                                                          ...
                                                                                                                                          0.0
                                                                                                                                          0.5
                                                                                                                                          1.0
                                                                                                                                          1.5
                                                                                                                                          >>> dv[20] = 4.5
                                                                                                                                          Traceback (most recent call last):
                                                                                                                                            File "<stdin>", line 1, in ?
                                                                                                                                            File "example.py", line 81, in __setitem__
                                                                                                                                              def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                                                                                                                          IndexError: vector index out of range
                                                                                                                                          >>>
                                                                                                                                          

                                                                                                                                          This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                                                                                                                          %include "std_vector.i"
                                                                                                                                          
                                                                                                                                          namespace std {
                                                                                                                                              %template(IntVector) vector<int>;
                                                                                                                                          }
                                                                                                                                          
                                                                                                                                          using namespace std;
                                                                                                                                          typedef std::vector Vector;
                                                                                                                                          
                                                                                                                                          void foo(vector<int> *x, const Vector &x);
                                                                                                                                          

                                                                                                                                          Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                                                                                                                          Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                                                                                                                          Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                                                                                                                          8.5 Utility Libraries

                                                                                                                                          8.5.1 exception.i

                                                                                                                                          The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                                                                                                                          SWIG_exception(int code, const char *message)

                                                                                                                                          Raises an exception in the target language. code is one of the following symbolic constants:

                                                                                                                                          SWIG_MemoryError
                                                                                                                                          SWIG_IOError
                                                                                                                                          SWIG_RuntimeError
                                                                                                                                          SWIG_IndexError
                                                                                                                                          SWIG_TypeError
                                                                                                                                          SWIG_DivisionByZero
                                                                                                                                          SWIG_OverflowError
                                                                                                                                          SWIG_SyntaxError
                                                                                                                                          SWIG_ValueError
                                                                                                                                          SWIG_SystemError
                                                                                                                                          

                                                                                                                                          message is a string indicating more information about the problem.

                                                                                                                                          The primary use of this module is in writing language-independent exception handlers. For example:

                                                                                                                                          %include "exception.i"
                                                                                                                                          %exception std::vector::getitem {
                                                                                                                                              try {
                                                                                                                                                  $action
                                                                                                                                              } catch (std::out_of_range& e) {
                                                                                                                                                  SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                                                                                                              }
                                                                                                                                          }
                                                                                                                                          

                                                                                                                                          ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                                                                                                                          

                                                                                                                                          SWIG-1.3 Documentation

                                                                                                                                          
                                                                                                                                          

                                                                                                                                          ---

                                                                                                                                          Table of Contents

                                                                                                                                          
                                                                                                                                          
                                                                                                                                          SWIG-1.3 Development Documentation
                                                                                                                                          • Sections
                                                                                                                                          • SWIG Core Documentation
                                                                                                                                          • Language Module Documentation
                                                                                                                                          • Developer Documentation
                                                                                                                                          • Documentation that has not yet been updated
                                                                                                                                          1 Preface
                                                                                                                                          • 1.1 Introduction
                                                                                                                                          • 1.2 Special Introduction for Version 1.3
                                                                                                                                          • 1.3 SWIG Versions
                                                                                                                                          • 1.4 SWIG resources
                                                                                                                                          • 1.5 Prerequisites
                                                                                                                                          • 1.6 Organization of this manual
                                                                                                                                          • 1.7 How to avoid reading the manual
                                                                                                                                          • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                                                                                                                            >>> make_upper("hello world")
                                                                                                                                            'HELLO WORLD'
                                                                                                                                            >>> attach_header("Hello world")
                                                                                                                                            'header: Hello world'
                                                                                                                                            >>>
                                                                                                                                            

                                                                                                                                            This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                                                                                                                            %cstring_output_maxsize(parm, maxparm)

                                                                                                                                            This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                                                                                                                            %cstring_output_maxsize(char *path, int maxpath);
                                                                                                                                            ...
                                                                                                                                            void get_path(char *path, int maxpath);
                                                                                                                                            

                                                                                                                                            In the target language:

                                                                                                                                            >>> get_path(1024)
                                                                                                                                            '/home/beazley/Packages/Foo/Bar'
                                                                                                                                            >>>
                                                                                                                                            

                                                                                                                                            This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                                                                                                                            %cstring_output_withsize(parm, maxparm)

                                                                                                                                            This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                                                                                                                            %cstring_output_withsize(char *data, int *maxdata);
                                                                                                                                            ...
                                                                                                                                            void get_data(char *data, int *maxdata);
                                                                                                                                            

                                                                                                                                            In the target language:

                                                                                                                                            >>> get_data(1024)
                                                                                                                                            'x627388912'
                                                                                                                                            >>> get_data(1024)
                                                                                                                                            'xyzzy'
                                                                                                                                            >>>
                                                                                                                                            

                                                                                                                                            This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                                                                                                                            %cstring_output_allocate(parm, release)

                                                                                                                                            This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                                                                                                                            void foo(char **s) {
                                                                                                                                                *s = (char *) malloc(64);
                                                                                                                                                sprintf(*s, "Hello world\n");
                                                                                                                                            }
                                                                                                                                            

                                                                                                                                            The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                                                            %cstring_output_allocate(char **s, free(*$1));
                                                                                                                                            ...
                                                                                                                                            void foo(char **s);
                                                                                                                                            

                                                                                                                                            In the target language:

                                                                                                                                            >>> foo()
                                                                                                                                            'Hello world\n'
                                                                                                                                            >>>
                                                                                                                                            

                                                                                                                                            %cstring_output_allocate_size(parm, szparm, release)

                                                                                                                                            This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                                                                                                                            void foo(char **s, int *sz) {
                                                                                                                                                *s = (char *) malloc(64);
                                                                                                                                                *sz = 64;
                                                                                                                                                // Write some binary data
                                                                                                                                                ...
                                                                                                                                            }
                                                                                                                                            

                                                                                                                                            The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                                                            %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                                                                                                                            ...
                                                                                                                                            void foo(char **s, int *slen);
                                                                                                                                            

                                                                                                                                            In the target language:

                                                                                                                                            >>> foo()
                                                                                                                                            '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                                                                                                                            >>>
                                                                                                                                            

                                                                                                                                            This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                                                                                                                            char  *get_data(int *len);
                                                                                                                                            

                                                                                                                                            You could wrap it with a function like this:

                                                                                                                                            void my_get_data(char **result, int *len) {
                                                                                                                                               *result = get_data(len);
                                                                                                                                            }
                                                                                                                                            

                                                                                                                                            Comments:
                                                                                                                                            • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                                                                                                                            • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                                                                                                                            • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                                                                                                                            • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                                                                                                                            8.4 C++ Library

                                                                                                                                            The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                                                                                                                            8.4.1 std_string.i

                                                                                                                                            The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                                                                                                                            %module example
                                                                                                                                            %include "std_string.i"
                                                                                                                                            
                                                                                                                                            std::string foo();
                                                                                                                                            void        bar(const std::string &x);
                                                                                                                                            

                                                                                                                                            In the target language:

                                                                                                                                            x = foo();                # Returns a string object
                                                                                                                                            bar("Hello World");       # Pass string as std::string
                                                                                                                                            

                                                                                                                                            This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                                                                                                                            This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                                                                                                                            %module example
                                                                                                                                            %include "std_string.i"
                                                                                                                                            
                                                                                                                                            using namespace std;
                                                                                                                                            typedef std::string String;
                                                                                                                                            ...
                                                                                                                                            void foo(string s, const String &t);     // std_string typemaps still applied
                                                                                                                                            

                                                                                                                                            Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                                                                                                                            8.4.2 std_vector.i

                                                                                                                                            The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                                                                                                                            %module example
                                                                                                                                            %include "std_vector.i"
                                                                                                                                            
                                                                                                                                            namespace std {
                                                                                                                                               %template(vectori) vector<int>;
                                                                                                                                               %template(vectord) vector<double>;
                                                                                                                                            };
                                                                                                                                            

                                                                                                                                            When a template vector<X> is instantiated a number of things happen:
                                                                                                                                            • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                                                                                                                            • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                                                                                                                            • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                                                                                                                            • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                                                                                                                            • An exception handler for std::out_of_range is defined.
                                                                                                                                            • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                                                                                                                            To illustrate the use of this library, consider the following functions:

                                                                                                                                            /* File : example.h */
                                                                                                                                            
                                                                                                                                            #include <vector>
                                                                                                                                            #include <algorithm>
                                                                                                                                            #include <functional>
                                                                                                                                            #include <numeric>
                                                                                                                                            
                                                                                                                                            double average(std::vector<int> v) {
                                                                                                                                                return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                                                                                                                            }
                                                                                                                                            
                                                                                                                                            std::vector<double> half(const std::vector<double>& v) {
                                                                                                                                                std::vector<double> w(v);
                                                                                                                                                for (unsigned int i=0; i<w.size(); i++)
                                                                                                                                                    w[i] /= 2.0;
                                                                                                                                                return w;
                                                                                                                                            }
                                                                                                                                            
                                                                                                                                            void halve_in_place(std::vector<double>& v) {
                                                                                                                                                std::transform(v.begin(),v.end(),v.begin(),
                                                                                                                                                               std::bind2nd(std::divides<double>(),2.0));
                                                                                                                                            }
                                                                                                                                            

                                                                                                                                            To wrap with SWIG, you might write the following:

                                                                                                                                            %module example
                                                                                                                                            %{
                                                                                                                                            #include "example.h"
                                                                                                                                            %}
                                                                                                                                            
                                                                                                                                            %include "std_vector.i"
                                                                                                                                            // Instantiate templates used by example
                                                                                                                                            namespace std {
                                                                                                                                               %template(IntVector) vector<int>;
                                                                                                                                               %template(DoubleVector) vector<double>;
                                                                                                                                            }
                                                                                                                                            
                                                                                                                                            // Include the header file with above prototypes
                                                                                                                                            %include "example.h"
                                                                                                                                            

                                                                                                                                            Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                                                                                                                            >>> from example import *
                                                                                                                                            >>> iv = IntVector(4)         # Create an vector<int>
                                                                                                                                            >>> for i in range(0,4):
                                                                                                                                            ...      iv[i] = i
                                                                                                                                            >>> average(iv)               # Call method
                                                                                                                                            1.5
                                                                                                                                            >>> average([0,1,2,3])        # Call with list
                                                                                                                                            1.5
                                                                                                                                            >>> half([1,2,3])             # Half a list
                                                                                                                                            (0.5,1.0,1.5)
                                                                                                                                            >>> halve_in_place([1,2,3])   # Oops
                                                                                                                                            Traceback (most recent call last):
                                                                                                                                              File "<stdin>", line 1, in ?
                                                                                                                                            TypeError: Type error. Expected _p_std__vectorTdouble_t
                                                                                                                                            >>> dv = DoubleVector(4)
                                                                                                                                            >>> for i in range(0,4):
                                                                                                                                            ...       dv[i] = i
                                                                                                                                            >>> halve_in_place(dv)       # Ok
                                                                                                                                            >>> for i in dv:
                                                                                                                                            ...       print i
                                                                                                                                            ...
                                                                                                                                            0.0
                                                                                                                                            0.5
                                                                                                                                            1.0
                                                                                                                                            1.5
                                                                                                                                            >>> dv[20] = 4.5
                                                                                                                                            Traceback (most recent call last):
                                                                                                                                              File "<stdin>", line 1, in ?
                                                                                                                                              File "example.py", line 81, in __setitem__
                                                                                                                                                def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                                                                                                                            IndexError: vector index out of range
                                                                                                                                            >>>
                                                                                                                                            

                                                                                                                                            This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                                                                                                                            %include "std_vector.i"
                                                                                                                                            
                                                                                                                                            namespace std {
                                                                                                                                                %template(IntVector) vector<int>;
                                                                                                                                            }
                                                                                                                                            
                                                                                                                                            using namespace std;
                                                                                                                                            typedef std::vector Vector;
                                                                                                                                            
                                                                                                                                            void foo(vector<int> *x, const Vector &x);
                                                                                                                                            

                                                                                                                                            Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                                                                                                                            Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                                                                                                                            Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                                                                                                                            8.5 Utility Libraries

                                                                                                                                            8.5.1 exception.i

                                                                                                                                            The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                                                                                                                            SWIG_exception(int code, const char *message)

                                                                                                                                            Raises an exception in the target language. code is one of the following symbolic constants:

                                                                                                                                            SWIG_MemoryError
                                                                                                                                            SWIG_IOError
                                                                                                                                            SWIG_RuntimeError
                                                                                                                                            SWIG_IndexError
                                                                                                                                            SWIG_TypeError
                                                                                                                                            SWIG_DivisionByZero
                                                                                                                                            SWIG_OverflowError
                                                                                                                                            SWIG_SyntaxError
                                                                                                                                            SWIG_ValueError
                                                                                                                                            SWIG_SystemError
                                                                                                                                            

                                                                                                                                            message is a string indicating more information about the problem.

                                                                                                                                            The primary use of this module is in writing language-independent exception handlers. For example:

                                                                                                                                            %include "exception.i"
                                                                                                                                            %exception std::vector::getitem {
                                                                                                                                                try {
                                                                                                                                                    $action
                                                                                                                                                } catch (std::out_of_range& e) {
                                                                                                                                                    SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                                                                                                                }
                                                                                                                                            }
                                                                                                                                            

                                                                                                                                            ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                                                                                                                            

                                                                                                                                            SWIG-1.3 Documentation

                                                                                                                                            
                                                                                                                                            

                                                                                                                                            ---

                                                                                                                                            Table of Contents

                                                                                                                                            
                                                                                                                                            
                                                                                                                                            SWIG-1.3 Development Documentation
                                                                                                                                            • Sections
                                                                                                                                            • SWIG Core Documentation
                                                                                                                                            • Language Module Documentation
                                                                                                                                            • Developer Documentation
                                                                                                                                            • Documentation that has not yet been updated
                                                                                                                                            1 Preface
                                                                                                                                            • 1.1 Introduction
                                                                                                                                            • 1.2 Special Introduction for Version 1.3
                                                                                                                                            • 1.3 SWIG Versions
                                                                                                                                            • 1.4 SWIG resources
                                                                                                                                            • 1.5 Prerequisites
                                                                                                                                            • 1.6 Organization of this manual
                                                                                                                                            • 1.7 How to avoid reading the manual
                                                                                                                                            • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                                                                                                                              >>> make_upper("hello world")
                                                                                                                                              'HELLO WORLD'
                                                                                                                                              >>> attach_header("Hello world")
                                                                                                                                              'header: Hello world'
                                                                                                                                              >>>
                                                                                                                                              

                                                                                                                                              This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                                                                                                                              %cstring_output_maxsize(parm, maxparm)

                                                                                                                                              This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                                                                                                                              %cstring_output_maxsize(char *path, int maxpath);
                                                                                                                                              ...
                                                                                                                                              void get_path(char *path, int maxpath);
                                                                                                                                              

                                                                                                                                              In the target language:

                                                                                                                                              >>> get_path(1024)
                                                                                                                                              '/home/beazley/Packages/Foo/Bar'
                                                                                                                                              >>>
                                                                                                                                              

                                                                                                                                              This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                                                                                                                              %cstring_output_withsize(parm, maxparm)

                                                                                                                                              This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                                                                                                                              %cstring_output_withsize(char *data, int *maxdata);
                                                                                                                                              ...
                                                                                                                                              void get_data(char *data, int *maxdata);
                                                                                                                                              

                                                                                                                                              In the target language:

                                                                                                                                              >>> get_data(1024)
                                                                                                                                              'x627388912'
                                                                                                                                              >>> get_data(1024)
                                                                                                                                              'xyzzy'
                                                                                                                                              >>>
                                                                                                                                              

                                                                                                                                              This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                                                                                                                              %cstring_output_allocate(parm, release)

                                                                                                                                              This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                                                                                                                              void foo(char **s) {
                                                                                                                                                  *s = (char *) malloc(64);
                                                                                                                                                  sprintf(*s, "Hello world\n");
                                                                                                                                              }
                                                                                                                                              

                                                                                                                                              The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                                                              %cstring_output_allocate(char **s, free(*$1));
                                                                                                                                              ...
                                                                                                                                              void foo(char **s);
                                                                                                                                              

                                                                                                                                              In the target language:

                                                                                                                                              >>> foo()
                                                                                                                                              'Hello world\n'
                                                                                                                                              >>>
                                                                                                                                              

                                                                                                                                              %cstring_output_allocate_size(parm, szparm, release)

                                                                                                                                              This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                                                                                                                              void foo(char **s, int *sz) {
                                                                                                                                                  *s = (char *) malloc(64);
                                                                                                                                                  *sz = 64;
                                                                                                                                                  // Write some binary data
                                                                                                                                                  ...
                                                                                                                                              }
                                                                                                                                              

                                                                                                                                              The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                                                              %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                                                                                                                              ...
                                                                                                                                              void foo(char **s, int *slen);
                                                                                                                                              

                                                                                                                                              In the target language:

                                                                                                                                              >>> foo()
                                                                                                                                              '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                                                                                                                              >>>
                                                                                                                                              

                                                                                                                                              This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                                                                                                                              char  *get_data(int *len);
                                                                                                                                              

                                                                                                                                              You could wrap it with a function like this:

                                                                                                                                              void my_get_data(char **result, int *len) {
                                                                                                                                                 *result = get_data(len);
                                                                                                                                              }
                                                                                                                                              

                                                                                                                                              Comments:
                                                                                                                                              • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                                                                                                                              • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                                                                                                                              • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                                                                                                                              • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                                                                                                                              8.4 C++ Library

                                                                                                                                              The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                                                                                                                              8.4.1 std_string.i

                                                                                                                                              The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                                                                                                                              %module example
                                                                                                                                              %include "std_string.i"
                                                                                                                                              
                                                                                                                                              std::string foo();
                                                                                                                                              void        bar(const std::string &x);
                                                                                                                                              

                                                                                                                                              In the target language:

                                                                                                                                              x = foo();                # Returns a string object
                                                                                                                                              bar("Hello World");       # Pass string as std::string
                                                                                                                                              

                                                                                                                                              This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                                                                                                                              This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                                                                                                                              %module example
                                                                                                                                              %include "std_string.i"
                                                                                                                                              
                                                                                                                                              using namespace std;
                                                                                                                                              typedef std::string String;
                                                                                                                                              ...
                                                                                                                                              void foo(string s, const String &t);     // std_string typemaps still applied
                                                                                                                                              

                                                                                                                                              Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                                                                                                                              8.4.2 std_vector.i

                                                                                                                                              The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                                                                                                                              %module example
                                                                                                                                              %include "std_vector.i"
                                                                                                                                              
                                                                                                                                              namespace std {
                                                                                                                                                 %template(vectori) vector<int>;
                                                                                                                                                 %template(vectord) vector<double>;
                                                                                                                                              };
                                                                                                                                              

                                                                                                                                              When a template vector<X> is instantiated a number of things happen:
                                                                                                                                              • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                                                                                                                              • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                                                                                                                              • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                                                                                                                              • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                                                                                                                              • An exception handler for std::out_of_range is defined.
                                                                                                                                              • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                                                                                                                              To illustrate the use of this library, consider the following functions:

                                                                                                                                              /* File : example.h */
                                                                                                                                              
                                                                                                                                              #include <vector>
                                                                                                                                              #include <algorithm>
                                                                                                                                              #include <functional>
                                                                                                                                              #include <numeric>
                                                                                                                                              
                                                                                                                                              double average(std::vector<int> v) {
                                                                                                                                                  return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                                                                                                                              }
                                                                                                                                              
                                                                                                                                              std::vector<double> half(const std::vector<double>& v) {
                                                                                                                                                  std::vector<double> w(v);
                                                                                                                                                  for (unsigned int i=0; i<w.size(); i++)
                                                                                                                                                      w[i] /= 2.0;
                                                                                                                                                  return w;
                                                                                                                                              }
                                                                                                                                              
                                                                                                                                              void halve_in_place(std::vector<double>& v) {
                                                                                                                                                  std::transform(v.begin(),v.end(),v.begin(),
                                                                                                                                                                 std::bind2nd(std::divides<double>(),2.0));
                                                                                                                                              }
                                                                                                                                              

                                                                                                                                              To wrap with SWIG, you might write the following:

                                                                                                                                              %module example
                                                                                                                                              %{
                                                                                                                                              #include "example.h"
                                                                                                                                              %}
                                                                                                                                              
                                                                                                                                              %include "std_vector.i"
                                                                                                                                              // Instantiate templates used by example
                                                                                                                                              namespace std {
                                                                                                                                                 %template(IntVector) vector<int>;
                                                                                                                                                 %template(DoubleVector) vector<double>;
                                                                                                                                              }
                                                                                                                                              
                                                                                                                                              // Include the header file with above prototypes
                                                                                                                                              %include "example.h"
                                                                                                                                              

                                                                                                                                              Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                                                                                                                              >>> from example import *
                                                                                                                                              >>> iv = IntVector(4)         # Create an vector<int>
                                                                                                                                              >>> for i in range(0,4):
                                                                                                                                              ...      iv[i] = i
                                                                                                                                              >>> average(iv)               # Call method
                                                                                                                                              1.5
                                                                                                                                              >>> average([0,1,2,3])        # Call with list
                                                                                                                                              1.5
                                                                                                                                              >>> half([1,2,3])             # Half a list
                                                                                                                                              (0.5,1.0,1.5)
                                                                                                                                              >>> halve_in_place([1,2,3])   # Oops
                                                                                                                                              Traceback (most recent call last):
                                                                                                                                                File "<stdin>", line 1, in ?
                                                                                                                                              TypeError: Type error. Expected _p_std__vectorTdouble_t
                                                                                                                                              >>> dv = DoubleVector(4)
                                                                                                                                              >>> for i in range(0,4):
                                                                                                                                              ...       dv[i] = i
                                                                                                                                              >>> halve_in_place(dv)       # Ok
                                                                                                                                              >>> for i in dv:
                                                                                                                                              ...       print i
                                                                                                                                              ...
                                                                                                                                              0.0
                                                                                                                                              0.5
                                                                                                                                              1.0
                                                                                                                                              1.5
                                                                                                                                              >>> dv[20] = 4.5
                                                                                                                                              Traceback (most recent call last):
                                                                                                                                                File "<stdin>", line 1, in ?
                                                                                                                                                File "example.py", line 81, in __setitem__
                                                                                                                                                  def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                                                                                                                              IndexError: vector index out of range
                                                                                                                                              >>>
                                                                                                                                              

                                                                                                                                              This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                                                                                                                              %include "std_vector.i"
                                                                                                                                              
                                                                                                                                              namespace std {
                                                                                                                                                  %template(IntVector) vector<int>;
                                                                                                                                              }
                                                                                                                                              
                                                                                                                                              using namespace std;
                                                                                                                                              typedef std::vector Vector;
                                                                                                                                              
                                                                                                                                              void foo(vector<int> *x, const Vector &x);
                                                                                                                                              

                                                                                                                                              Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                                                                                                                              Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                                                                                                                              Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                                                                                                                              8.5 Utility Libraries

                                                                                                                                              8.5.1 exception.i

                                                                                                                                              The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                                                                                                                              SWIG_exception(int code, const char *message)

                                                                                                                                              Raises an exception in the target language. code is one of the following symbolic constants:

                                                                                                                                              SWIG_MemoryError
                                                                                                                                              SWIG_IOError
                                                                                                                                              SWIG_RuntimeError
                                                                                                                                              SWIG_IndexError
                                                                                                                                              SWIG_TypeError
                                                                                                                                              SWIG_DivisionByZero
                                                                                                                                              SWIG_OverflowError
                                                                                                                                              SWIG_SyntaxError
                                                                                                                                              SWIG_ValueError
                                                                                                                                              SWIG_SystemError
                                                                                                                                              

                                                                                                                                              message is a string indicating more information about the problem.

                                                                                                                                              The primary use of this module is in writing language-independent exception handlers. For example:

                                                                                                                                              %include "exception.i"
                                                                                                                                              %exception std::vector::getitem {
                                                                                                                                                  try {
                                                                                                                                                      $action
                                                                                                                                                  } catch (std::out_of_range& e) {
                                                                                                                                                      SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                                                                                                                  }
                                                                                                                                              }
                                                                                                                                              

                                                                                                                                              ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                                                                                                                              

                                                                                                                                              SWIG-1.3 Documentation

                                                                                                                                              
                                                                                                                                              

                                                                                                                                              ---

                                                                                                                                              Table of Contents

                                                                                                                                              
                                                                                                                                              
                                                                                                                                              SWIG-1.3 Development Documentation
                                                                                                                                              • Sections
                                                                                                                                              • SWIG Core Documentation
                                                                                                                                              • Language Module Documentation
                                                                                                                                              • Developer Documentation
                                                                                                                                              • Documentation that has not yet been updated
                                                                                                                                              1 Preface
                                                                                                                                              • 1.1 Introduction
                                                                                                                                              • 1.2 Special Introduction for Version 1.3
                                                                                                                                              • 1.3 SWIG Versions
                                                                                                                                              • 1.4 SWIG resources
                                                                                                                                              • 1.5 Prerequisites
                                                                                                                                              • 1.6 Organization of this manual
                                                                                                                                              • 1.7 How to avoid reading the manual
                                                                                                                                              • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                                                                                                                                >>> make_upper("hello world")
                                                                                                                                                'HELLO WORLD'
                                                                                                                                                >>> attach_header("Hello world")
                                                                                                                                                'header: Hello world'
                                                                                                                                                >>>
                                                                                                                                                

                                                                                                                                                This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                                                                                                                                %cstring_output_maxsize(parm, maxparm)

                                                                                                                                                This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                                                                                                                                %cstring_output_maxsize(char *path, int maxpath);
                                                                                                                                                ...
                                                                                                                                                void get_path(char *path, int maxpath);
                                                                                                                                                

                                                                                                                                                In the target language:

                                                                                                                                                >>> get_path(1024)
                                                                                                                                                '/home/beazley/Packages/Foo/Bar'
                                                                                                                                                >>>
                                                                                                                                                

                                                                                                                                                This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                                                                                                                                %cstring_output_withsize(parm, maxparm)

                                                                                                                                                This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                                                                                                                                %cstring_output_withsize(char *data, int *maxdata);
                                                                                                                                                ...
                                                                                                                                                void get_data(char *data, int *maxdata);
                                                                                                                                                

                                                                                                                                                In the target language:

                                                                                                                                                >>> get_data(1024)
                                                                                                                                                'x627388912'
                                                                                                                                                >>> get_data(1024)
                                                                                                                                                'xyzzy'
                                                                                                                                                >>>
                                                                                                                                                

                                                                                                                                                This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                                                                                                                                %cstring_output_allocate(parm, release)

                                                                                                                                                This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                                                                                                                                void foo(char **s) {
                                                                                                                                                    *s = (char *) malloc(64);
                                                                                                                                                    sprintf(*s, "Hello world\n");
                                                                                                                                                }
                                                                                                                                                

                                                                                                                                                The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                                                                %cstring_output_allocate(char **s, free(*$1));
                                                                                                                                                ...
                                                                                                                                                void foo(char **s);
                                                                                                                                                

                                                                                                                                                In the target language:

                                                                                                                                                >>> foo()
                                                                                                                                                'Hello world\n'
                                                                                                                                                >>>
                                                                                                                                                

                                                                                                                                                %cstring_output_allocate_size(parm, szparm, release)

                                                                                                                                                This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                                                                                                                                void foo(char **s, int *sz) {
                                                                                                                                                    *s = (char *) malloc(64);
                                                                                                                                                    *sz = 64;
                                                                                                                                                    // Write some binary data
                                                                                                                                                    ...
                                                                                                                                                }
                                                                                                                                                

                                                                                                                                                The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                                                                %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                                                                                                                                ...
                                                                                                                                                void foo(char **s, int *slen);
                                                                                                                                                

                                                                                                                                                In the target language:

                                                                                                                                                >>> foo()
                                                                                                                                                '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                                                                                                                                >>>
                                                                                                                                                

                                                                                                                                                This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                                                                                                                                char  *get_data(int *len);
                                                                                                                                                

                                                                                                                                                You could wrap it with a function like this:

                                                                                                                                                void my_get_data(char **result, int *len) {
                                                                                                                                                   *result = get_data(len);
                                                                                                                                                }
                                                                                                                                                

                                                                                                                                                Comments:
                                                                                                                                                • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                                                                                                                                • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                                                                                                                                • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                                                                                                                                • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                                                                                                                                8.4 C++ Library

                                                                                                                                                The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                                                                                                                                8.4.1 std_string.i

                                                                                                                                                The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                                                                                                                                %module example
                                                                                                                                                %include "std_string.i"
                                                                                                                                                
                                                                                                                                                std::string foo();
                                                                                                                                                void        bar(const std::string &x);
                                                                                                                                                

                                                                                                                                                In the target language:

                                                                                                                                                x = foo();                # Returns a string object
                                                                                                                                                bar("Hello World");       # Pass string as std::string
                                                                                                                                                

                                                                                                                                                This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                                                                                                                                This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                                                                                                                                %module example
                                                                                                                                                %include "std_string.i"
                                                                                                                                                
                                                                                                                                                using namespace std;
                                                                                                                                                typedef std::string String;
                                                                                                                                                ...
                                                                                                                                                void foo(string s, const String &t);     // std_string typemaps still applied
                                                                                                                                                

                                                                                                                                                Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                                                                                                                                8.4.2 std_vector.i

                                                                                                                                                The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                                                                                                                                %module example
                                                                                                                                                %include "std_vector.i"
                                                                                                                                                
                                                                                                                                                namespace std {
                                                                                                                                                   %template(vectori) vector<int>;
                                                                                                                                                   %template(vectord) vector<double>;
                                                                                                                                                };
                                                                                                                                                

                                                                                                                                                When a template vector<X> is instantiated a number of things happen:
                                                                                                                                                • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                                                                                                                                • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                                                                                                                                • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                                                                                                                                • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                                                                                                                                • An exception handler for std::out_of_range is defined.
                                                                                                                                                • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                                                                                                                                To illustrate the use of this library, consider the following functions:

                                                                                                                                                /* File : example.h */
                                                                                                                                                
                                                                                                                                                #include <vector>
                                                                                                                                                #include <algorithm>
                                                                                                                                                #include <functional>
                                                                                                                                                #include <numeric>
                                                                                                                                                
                                                                                                                                                double average(std::vector<int> v) {
                                                                                                                                                    return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                                                                                                                                }
                                                                                                                                                
                                                                                                                                                std::vector<double> half(const std::vector<double>& v) {
                                                                                                                                                    std::vector<double> w(v);
                                                                                                                                                    for (unsigned int i=0; i<w.size(); i++)
                                                                                                                                                        w[i] /= 2.0;
                                                                                                                                                    return w;
                                                                                                                                                }
                                                                                                                                                
                                                                                                                                                void halve_in_place(std::vector<double>& v) {
                                                                                                                                                    std::transform(v.begin(),v.end(),v.begin(),
                                                                                                                                                                   std::bind2nd(std::divides<double>(),2.0));
                                                                                                                                                }
                                                                                                                                                

                                                                                                                                                To wrap with SWIG, you might write the following:

                                                                                                                                                %module example
                                                                                                                                                %{
                                                                                                                                                #include "example.h"
                                                                                                                                                %}
                                                                                                                                                
                                                                                                                                                %include "std_vector.i"
                                                                                                                                                // Instantiate templates used by example
                                                                                                                                                namespace std {
                                                                                                                                                   %template(IntVector) vector<int>;
                                                                                                                                                   %template(DoubleVector) vector<double>;
                                                                                                                                                }
                                                                                                                                                
                                                                                                                                                // Include the header file with above prototypes
                                                                                                                                                %include "example.h"
                                                                                                                                                

                                                                                                                                                Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                                                                                                                                >>> from example import *
                                                                                                                                                >>> iv = IntVector(4)         # Create an vector<int>
                                                                                                                                                >>> for i in range(0,4):
                                                                                                                                                ...      iv[i] = i
                                                                                                                                                >>> average(iv)               # Call method
                                                                                                                                                1.5
                                                                                                                                                >>> average([0,1,2,3])        # Call with list
                                                                                                                                                1.5
                                                                                                                                                >>> half([1,2,3])             # Half a list
                                                                                                                                                (0.5,1.0,1.5)
                                                                                                                                                >>> halve_in_place([1,2,3])   # Oops
                                                                                                                                                Traceback (most recent call last):
                                                                                                                                                  File "<stdin>", line 1, in ?
                                                                                                                                                TypeError: Type error. Expected _p_std__vectorTdouble_t
                                                                                                                                                >>> dv = DoubleVector(4)
                                                                                                                                                >>> for i in range(0,4):
                                                                                                                                                ...       dv[i] = i
                                                                                                                                                >>> halve_in_place(dv)       # Ok
                                                                                                                                                >>> for i in dv:
                                                                                                                                                ...       print i
                                                                                                                                                ...
                                                                                                                                                0.0
                                                                                                                                                0.5
                                                                                                                                                1.0
                                                                                                                                                1.5
                                                                                                                                                >>> dv[20] = 4.5
                                                                                                                                                Traceback (most recent call last):
                                                                                                                                                  File "<stdin>", line 1, in ?
                                                                                                                                                  File "example.py", line 81, in __setitem__
                                                                                                                                                    def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                                                                                                                                IndexError: vector index out of range
                                                                                                                                                >>>
                                                                                                                                                

                                                                                                                                                This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                                                                                                                                %include "std_vector.i"
                                                                                                                                                
                                                                                                                                                namespace std {
                                                                                                                                                    %template(IntVector) vector<int>;
                                                                                                                                                }
                                                                                                                                                
                                                                                                                                                using namespace std;
                                                                                                                                                typedef std::vector Vector;
                                                                                                                                                
                                                                                                                                                void foo(vector<int> *x, const Vector &x);
                                                                                                                                                

                                                                                                                                                Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                                                                                                                                Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                                                                                                                                Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                                                                                                                                8.5 Utility Libraries

                                                                                                                                                8.5.1 exception.i

                                                                                                                                                The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                                                                                                                                SWIG_exception(int code, const char *message)

                                                                                                                                                Raises an exception in the target language. code is one of the following symbolic constants:

                                                                                                                                                SWIG_MemoryError
                                                                                                                                                SWIG_IOError
                                                                                                                                                SWIG_RuntimeError
                                                                                                                                                SWIG_IndexError
                                                                                                                                                SWIG_TypeError
                                                                                                                                                SWIG_DivisionByZero
                                                                                                                                                SWIG_OverflowError
                                                                                                                                                SWIG_SyntaxError
                                                                                                                                                SWIG_ValueError
                                                                                                                                                SWIG_SystemError
                                                                                                                                                

                                                                                                                                                message is a string indicating more information about the problem.

                                                                                                                                                The primary use of this module is in writing language-independent exception handlers. For example:

                                                                                                                                                %include "exception.i"
                                                                                                                                                %exception std::vector::getitem {
                                                                                                                                                    try {
                                                                                                                                                        $action
                                                                                                                                                    } catch (std::out_of_range& e) {
                                                                                                                                                        SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                                                                                                                    }
                                                                                                                                                }
                                                                                                                                                

                                                                                                                                                ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                                                                                                                                

                                                                                                                                                SWIG-1.3 Documentation

                                                                                                                                                
                                                                                                                                                

                                                                                                                                                ---

                                                                                                                                                Table of Contents

                                                                                                                                                
                                                                                                                                                
                                                                                                                                                SWIG-1.3 Development Documentation
                                                                                                                                                • Sections
                                                                                                                                                • SWIG Core Documentation
                                                                                                                                                • Language Module Documentation
                                                                                                                                                • Developer Documentation
                                                                                                                                                • Documentation that has not yet been updated
                                                                                                                                                1 Preface
                                                                                                                                                • 1.1 Introduction
                                                                                                                                                • 1.2 Special Introduction for Version 1.3
                                                                                                                                                • 1.3 SWIG Versions
                                                                                                                                                • 1.4 SWIG resources
                                                                                                                                                • 1.5 Prerequisites
                                                                                                                                                • 1.6 Organization of this manual
                                                                                                                                                • 1.7 How to avoid reading the manual
                                                                                                                                                • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                                                                                                                                  >>> make_upper("hello world")
                                                                                                                                                  'HELLO WORLD'
                                                                                                                                                  >>> attach_header("Hello world")
                                                                                                                                                  'header: Hello world'
                                                                                                                                                  >>>
                                                                                                                                                  

                                                                                                                                                  This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                                                                                                                                  %cstring_output_maxsize(parm, maxparm)

                                                                                                                                                  This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                                                                                                                                  %cstring_output_maxsize(char *path, int maxpath);
                                                                                                                                                  ...
                                                                                                                                                  void get_path(char *path, int maxpath);
                                                                                                                                                  

                                                                                                                                                  In the target language:

                                                                                                                                                  >>> get_path(1024)
                                                                                                                                                  '/home/beazley/Packages/Foo/Bar'
                                                                                                                                                  >>>
                                                                                                                                                  

                                                                                                                                                  This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                                                                                                                                  %cstring_output_withsize(parm, maxparm)

                                                                                                                                                  This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                                                                                                                                  %cstring_output_withsize(char *data, int *maxdata);
                                                                                                                                                  ...
                                                                                                                                                  void get_data(char *data, int *maxdata);
                                                                                                                                                  

                                                                                                                                                  In the target language:

                                                                                                                                                  >>> get_data(1024)
                                                                                                                                                  'x627388912'
                                                                                                                                                  >>> get_data(1024)
                                                                                                                                                  'xyzzy'
                                                                                                                                                  >>>
                                                                                                                                                  

                                                                                                                                                  This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                                                                                                                                  %cstring_output_allocate(parm, release)

                                                                                                                                                  This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                                                                                                                                  void foo(char **s) {
                                                                                                                                                      *s = (char *) malloc(64);
                                                                                                                                                      sprintf(*s, "Hello world\n");
                                                                                                                                                  }
                                                                                                                                                  

                                                                                                                                                  The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                                                                  %cstring_output_allocate(char **s, free(*$1));
                                                                                                                                                  ...
                                                                                                                                                  void foo(char **s);
                                                                                                                                                  

                                                                                                                                                  In the target language:

                                                                                                                                                  >>> foo()
                                                                                                                                                  'Hello world\n'
                                                                                                                                                  >>>
                                                                                                                                                  

                                                                                                                                                  %cstring_output_allocate_size(parm, szparm, release)

                                                                                                                                                  This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                                                                                                                                  void foo(char **s, int *sz) {
                                                                                                                                                      *s = (char *) malloc(64);
                                                                                                                                                      *sz = 64;
                                                                                                                                                      // Write some binary data
                                                                                                                                                      ...
                                                                                                                                                  }
                                                                                                                                                  

                                                                                                                                                  The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                                                                  %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                                                                                                                                  ...
                                                                                                                                                  void foo(char **s, int *slen);
                                                                                                                                                  

                                                                                                                                                  In the target language:

                                                                                                                                                  >>> foo()
                                                                                                                                                  '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                                                                                                                                  >>>
                                                                                                                                                  

                                                                                                                                                  This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                                                                                                                                  char  *get_data(int *len);
                                                                                                                                                  

                                                                                                                                                  You could wrap it with a function like this:

                                                                                                                                                  void my_get_data(char **result, int *len) {
                                                                                                                                                     *result = get_data(len);
                                                                                                                                                  }
                                                                                                                                                  

                                                                                                                                                  Comments:
                                                                                                                                                  • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                                                                                                                                  • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                                                                                                                                  • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                                                                                                                                  • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                                                                                                                                  8.4 C++ Library

                                                                                                                                                  The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                                                                                                                                  8.4.1 std_string.i

                                                                                                                                                  The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                                                                                                                                  %module example
                                                                                                                                                  %include "std_string.i"
                                                                                                                                                  
                                                                                                                                                  std::string foo();
                                                                                                                                                  void        bar(const std::string &x);
                                                                                                                                                  

                                                                                                                                                  In the target language:

                                                                                                                                                  x = foo();                # Returns a string object
                                                                                                                                                  bar("Hello World");       # Pass string as std::string
                                                                                                                                                  

                                                                                                                                                  This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                                                                                                                                  This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                                                                                                                                  %module example
                                                                                                                                                  %include "std_string.i"
                                                                                                                                                  
                                                                                                                                                  using namespace std;
                                                                                                                                                  typedef std::string String;
                                                                                                                                                  ...
                                                                                                                                                  void foo(string s, const String &t);     // std_string typemaps still applied
                                                                                                                                                  

                                                                                                                                                  Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                                                                                                                                  8.4.2 std_vector.i

                                                                                                                                                  The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                                                                                                                                  %module example
                                                                                                                                                  %include "std_vector.i"
                                                                                                                                                  
                                                                                                                                                  namespace std {
                                                                                                                                                     %template(vectori) vector<int>;
                                                                                                                                                     %template(vectord) vector<double>;
                                                                                                                                                  };
                                                                                                                                                  

                                                                                                                                                  When a template vector<X> is instantiated a number of things happen:
                                                                                                                                                  • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                                                                                                                                  • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                                                                                                                                  • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                                                                                                                                  • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                                                                                                                                  • An exception handler for std::out_of_range is defined.
                                                                                                                                                  • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                                                                                                                                  To illustrate the use of this library, consider the following functions:

                                                                                                                                                  /* File : example.h */
                                                                                                                                                  
                                                                                                                                                  #include <vector>
                                                                                                                                                  #include <algorithm>
                                                                                                                                                  #include <functional>
                                                                                                                                                  #include <numeric>
                                                                                                                                                  
                                                                                                                                                  double average(std::vector<int> v) {
                                                                                                                                                      return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                                                                                                                                  }
                                                                                                                                                  
                                                                                                                                                  std::vector<double> half(const std::vector<double>& v) {
                                                                                                                                                      std::vector<double> w(v);
                                                                                                                                                      for (unsigned int i=0; i<w.size(); i++)
                                                                                                                                                          w[i] /= 2.0;
                                                                                                                                                      return w;
                                                                                                                                                  }
                                                                                                                                                  
                                                                                                                                                  void halve_in_place(std::vector<double>& v) {
                                                                                                                                                      std::transform(v.begin(),v.end(),v.begin(),
                                                                                                                                                                     std::bind2nd(std::divides<double>(),2.0));
                                                                                                                                                  }
                                                                                                                                                  

                                                                                                                                                  To wrap with SWIG, you might write the following:

                                                                                                                                                  %module example
                                                                                                                                                  %{
                                                                                                                                                  #include "example.h"
                                                                                                                                                  %}
                                                                                                                                                  
                                                                                                                                                  %include "std_vector.i"
                                                                                                                                                  // Instantiate templates used by example
                                                                                                                                                  namespace std {
                                                                                                                                                     %template(IntVector) vector<int>;
                                                                                                                                                     %template(DoubleVector) vector<double>;
                                                                                                                                                  }
                                                                                                                                                  
                                                                                                                                                  // Include the header file with above prototypes
                                                                                                                                                  %include "example.h"
                                                                                                                                                  

                                                                                                                                                  Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                                                                                                                                  >>> from example import *
                                                                                                                                                  >>> iv = IntVector(4)         # Create an vector<int>
                                                                                                                                                  >>> for i in range(0,4):
                                                                                                                                                  ...      iv[i] = i
                                                                                                                                                  >>> average(iv)               # Call method
                                                                                                                                                  1.5
                                                                                                                                                  >>> average([0,1,2,3])        # Call with list
                                                                                                                                                  1.5
                                                                                                                                                  >>> half([1,2,3])             # Half a list
                                                                                                                                                  (0.5,1.0,1.5)
                                                                                                                                                  >>> halve_in_place([1,2,3])   # Oops
                                                                                                                                                  Traceback (most recent call last):
                                                                                                                                                    File "<stdin>", line 1, in ?
                                                                                                                                                  TypeError: Type error. Expected _p_std__vectorTdouble_t
                                                                                                                                                  >>> dv = DoubleVector(4)
                                                                                                                                                  >>> for i in range(0,4):
                                                                                                                                                  ...       dv[i] = i
                                                                                                                                                  >>> halve_in_place(dv)       # Ok
                                                                                                                                                  >>> for i in dv:
                                                                                                                                                  ...       print i
                                                                                                                                                  ...
                                                                                                                                                  0.0
                                                                                                                                                  0.5
                                                                                                                                                  1.0
                                                                                                                                                  1.5
                                                                                                                                                  >>> dv[20] = 4.5
                                                                                                                                                  Traceback (most recent call last):
                                                                                                                                                    File "<stdin>", line 1, in ?
                                                                                                                                                    File "example.py", line 81, in __setitem__
                                                                                                                                                      def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                                                                                                                                  IndexError: vector index out of range
                                                                                                                                                  >>>
                                                                                                                                                  

                                                                                                                                                  This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                                                                                                                                  %include "std_vector.i"
                                                                                                                                                  
                                                                                                                                                  namespace std {
                                                                                                                                                      %template(IntVector) vector<int>;
                                                                                                                                                  }
                                                                                                                                                  
                                                                                                                                                  using namespace std;
                                                                                                                                                  typedef std::vector Vector;
                                                                                                                                                  
                                                                                                                                                  void foo(vector<int> *x, const Vector &x);
                                                                                                                                                  

                                                                                                                                                  Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                                                                                                                                  Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                                                                                                                                  Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                                                                                                                                  8.5 Utility Libraries

                                                                                                                                                  8.5.1 exception.i

                                                                                                                                                  The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                                                                                                                                  SWIG_exception(int code, const char *message)

                                                                                                                                                  Raises an exception in the target language. code is one of the following symbolic constants:

                                                                                                                                                  SWIG_MemoryError
                                                                                                                                                  SWIG_IOError
                                                                                                                                                  SWIG_RuntimeError
                                                                                                                                                  SWIG_IndexError
                                                                                                                                                  SWIG_TypeError
                                                                                                                                                  SWIG_DivisionByZero
                                                                                                                                                  SWIG_OverflowError
                                                                                                                                                  SWIG_SyntaxError
                                                                                                                                                  SWIG_ValueError
                                                                                                                                                  SWIG_SystemError
                                                                                                                                                  

                                                                                                                                                  message is a string indicating more information about the problem.

                                                                                                                                                  The primary use of this module is in writing language-independent exception handlers. For example:

                                                                                                                                                  %include "exception.i"
                                                                                                                                                  %exception std::vector::getitem {
                                                                                                                                                      try {
                                                                                                                                                          $action
                                                                                                                                                      } catch (std::out_of_range& e) {
                                                                                                                                                          SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                                                                                                                      }
                                                                                                                                                  }
                                                                                                                                                  

                                                                                                                                                  ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                                                                                                                                  

                                                                                                                                                  SWIG-1.3 Documentation

                                                                                                                                                  
                                                                                                                                                  

                                                                                                                                                  ---

                                                                                                                                                  Table of Contents

                                                                                                                                                  
                                                                                                                                                  
                                                                                                                                                  SWIG-1.3 Development Documentation
                                                                                                                                                  • Sections
                                                                                                                                                  • SWIG Core Documentation
                                                                                                                                                  • Language Module Documentation
                                                                                                                                                  • Developer Documentation
                                                                                                                                                  • Documentation that has not yet been updated
                                                                                                                                                  1 Preface
                                                                                                                                                  • 1.1 Introduction
                                                                                                                                                  • 1.2 Special Introduction for Version 1.3
                                                                                                                                                  • 1.3 SWIG Versions
                                                                                                                                                  • 1.4 SWIG resources
                                                                                                                                                  • 1.5 Prerequisites
                                                                                                                                                  • 1.6 Organization of this manual
                                                                                                                                                  • 1.7 How to avoid reading the manual
                                                                                                                                                  • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                                                                                                                                    >>> make_upper("hello world")
                                                                                                                                                    'HELLO WORLD'
                                                                                                                                                    >>> attach_header("Hello world")
                                                                                                                                                    'header: Hello world'
                                                                                                                                                    >>>
                                                                                                                                                    

                                                                                                                                                    This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                                                                                                                                    %cstring_output_maxsize(parm, maxparm)

                                                                                                                                                    This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                                                                                                                                    %cstring_output_maxsize(char *path, int maxpath);
                                                                                                                                                    ...
                                                                                                                                                    void get_path(char *path, int maxpath);
                                                                                                                                                    

                                                                                                                                                    In the target language:

                                                                                                                                                    >>> get_path(1024)
                                                                                                                                                    '/home/beazley/Packages/Foo/Bar'
                                                                                                                                                    >>>
                                                                                                                                                    

                                                                                                                                                    This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                                                                                                                                    %cstring_output_withsize(parm, maxparm)

                                                                                                                                                    This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                                                                                                                                    %cstring_output_withsize(char *data, int *maxdata);
                                                                                                                                                    ...
                                                                                                                                                    void get_data(char *data, int *maxdata);
                                                                                                                                                    

                                                                                                                                                    In the target language:

                                                                                                                                                    >>> get_data(1024)
                                                                                                                                                    'x627388912'
                                                                                                                                                    >>> get_data(1024)
                                                                                                                                                    'xyzzy'
                                                                                                                                                    >>>
                                                                                                                                                    

                                                                                                                                                    This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                                                                                                                                    %cstring_output_allocate(parm, release)

                                                                                                                                                    This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                                                                                                                                    void foo(char **s) {
                                                                                                                                                        *s = (char *) malloc(64);
                                                                                                                                                        sprintf(*s, "Hello world\n");
                                                                                                                                                    }
                                                                                                                                                    

                                                                                                                                                    The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                                                                    %cstring_output_allocate(char **s, free(*$1));
                                                                                                                                                    ...
                                                                                                                                                    void foo(char **s);
                                                                                                                                                    

                                                                                                                                                    In the target language:

                                                                                                                                                    >>> foo()
                                                                                                                                                    'Hello world\n'
                                                                                                                                                    >>>
                                                                                                                                                    

                                                                                                                                                    %cstring_output_allocate_size(parm, szparm, release)

                                                                                                                                                    This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                                                                                                                                    void foo(char **s, int *sz) {
                                                                                                                                                        *s = (char *) malloc(64);
                                                                                                                                                        *sz = 64;
                                                                                                                                                        // Write some binary data
                                                                                                                                                        ...
                                                                                                                                                    }
                                                                                                                                                    

                                                                                                                                                    The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                                                                    %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                                                                                                                                    ...
                                                                                                                                                    void foo(char **s, int *slen);
                                                                                                                                                    

                                                                                                                                                    In the target language:

                                                                                                                                                    >>> foo()
                                                                                                                                                    '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                                                                                                                                    >>>
                                                                                                                                                    

                                                                                                                                                    This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                                                                                                                                    char  *get_data(int *len);
                                                                                                                                                    

                                                                                                                                                    You could wrap it with a function like this:

                                                                                                                                                    void my_get_data(char **result, int *len) {
                                                                                                                                                       *result = get_data(len);
                                                                                                                                                    }
                                                                                                                                                    

                                                                                                                                                    Comments:
                                                                                                                                                    • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                                                                                                                                    • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                                                                                                                                    • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                                                                                                                                    • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                                                                                                                                    8.4 C++ Library

                                                                                                                                                    The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                                                                                                                                    8.4.1 std_string.i

                                                                                                                                                    The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                                                                                                                                    %module example
                                                                                                                                                    %include "std_string.i"
                                                                                                                                                    
                                                                                                                                                    std::string foo();
                                                                                                                                                    void        bar(const std::string &x);
                                                                                                                                                    

                                                                                                                                                    In the target language:

                                                                                                                                                    x = foo();                # Returns a string object
                                                                                                                                                    bar("Hello World");       # Pass string as std::string
                                                                                                                                                    

                                                                                                                                                    This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                                                                                                                                    This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                                                                                                                                    %module example
                                                                                                                                                    %include "std_string.i"
                                                                                                                                                    
                                                                                                                                                    using namespace std;
                                                                                                                                                    typedef std::string String;
                                                                                                                                                    ...
                                                                                                                                                    void foo(string s, const String &t);     // std_string typemaps still applied
                                                                                                                                                    

                                                                                                                                                    Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                                                                                                                                    8.4.2 std_vector.i

                                                                                                                                                    The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                                                                                                                                    %module example
                                                                                                                                                    %include "std_vector.i"
                                                                                                                                                    
                                                                                                                                                    namespace std {
                                                                                                                                                       %template(vectori) vector<int>;
                                                                                                                                                       %template(vectord) vector<double>;
                                                                                                                                                    };
                                                                                                                                                    

                                                                                                                                                    When a template vector<X> is instantiated a number of things happen:
                                                                                                                                                    • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                                                                                                                                    • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                                                                                                                                    • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                                                                                                                                    • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                                                                                                                                    • An exception handler for std::out_of_range is defined.
                                                                                                                                                    • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                                                                                                                                    To illustrate the use of this library, consider the following functions:

                                                                                                                                                    /* File : example.h */
                                                                                                                                                    
                                                                                                                                                    #include <vector>
                                                                                                                                                    #include <algorithm>
                                                                                                                                                    #include <functional>
                                                                                                                                                    #include <numeric>
                                                                                                                                                    
                                                                                                                                                    double average(std::vector<int> v) {
                                                                                                                                                        return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                                                                                                                                    }
                                                                                                                                                    
                                                                                                                                                    std::vector<double> half(const std::vector<double>& v) {
                                                                                                                                                        std::vector<double> w(v);
                                                                                                                                                        for (unsigned int i=0; i<w.size(); i++)
                                                                                                                                                            w[i] /= 2.0;
                                                                                                                                                        return w;
                                                                                                                                                    }
                                                                                                                                                    
                                                                                                                                                    void halve_in_place(std::vector<double>& v) {
                                                                                                                                                        std::transform(v.begin(),v.end(),v.begin(),
                                                                                                                                                                       std::bind2nd(std::divides<double>(),2.0));
                                                                                                                                                    }
                                                                                                                                                    

                                                                                                                                                    To wrap with SWIG, you might write the following:

                                                                                                                                                    %module example
                                                                                                                                                    %{
                                                                                                                                                    #include "example.h"
                                                                                                                                                    %}
                                                                                                                                                    
                                                                                                                                                    %include "std_vector.i"
                                                                                                                                                    // Instantiate templates used by example
                                                                                                                                                    namespace std {
                                                                                                                                                       %template(IntVector) vector<int>;
                                                                                                                                                       %template(DoubleVector) vector<double>;
                                                                                                                                                    }
                                                                                                                                                    
                                                                                                                                                    // Include the header file with above prototypes
                                                                                                                                                    %include "example.h"
                                                                                                                                                    

                                                                                                                                                    Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                                                                                                                                    >>> from example import *
                                                                                                                                                    >>> iv = IntVector(4)         # Create an vector<int>
                                                                                                                                                    >>> for i in range(0,4):
                                                                                                                                                    ...      iv[i] = i
                                                                                                                                                    >>> average(iv)               # Call method
                                                                                                                                                    1.5
                                                                                                                                                    >>> average([0,1,2,3])        # Call with list
                                                                                                                                                    1.5
                                                                                                                                                    >>> half([1,2,3])             # Half a list
                                                                                                                                                    (0.5,1.0,1.5)
                                                                                                                                                    >>> halve_in_place([1,2,3])   # Oops
                                                                                                                                                    Traceback (most recent call last):
                                                                                                                                                      File "<stdin>", line 1, in ?
                                                                                                                                                    TypeError: Type error. Expected _p_std__vectorTdouble_t
                                                                                                                                                    >>> dv = DoubleVector(4)
                                                                                                                                                    >>> for i in range(0,4):
                                                                                                                                                    ...       dv[i] = i
                                                                                                                                                    >>> halve_in_place(dv)       # Ok
                                                                                                                                                    >>> for i in dv:
                                                                                                                                                    ...       print i
                                                                                                                                                    ...
                                                                                                                                                    0.0
                                                                                                                                                    0.5
                                                                                                                                                    1.0
                                                                                                                                                    1.5
                                                                                                                                                    >>> dv[20] = 4.5
                                                                                                                                                    Traceback (most recent call last):
                                                                                                                                                      File "<stdin>", line 1, in ?
                                                                                                                                                      File "example.py", line 81, in __setitem__
                                                                                                                                                        def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                                                                                                                                    IndexError: vector index out of range
                                                                                                                                                    >>>
                                                                                                                                                    

                                                                                                                                                    This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                                                                                                                                    %include "std_vector.i"
                                                                                                                                                    
                                                                                                                                                    namespace std {
                                                                                                                                                        %template(IntVector) vector<int>;
                                                                                                                                                    }
                                                                                                                                                    
                                                                                                                                                    using namespace std;
                                                                                                                                                    typedef std::vector Vector;
                                                                                                                                                    
                                                                                                                                                    void foo(vector<int> *x, const Vector &x);
                                                                                                                                                    

                                                                                                                                                    Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                                                                                                                                    Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                                                                                                                                    Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                                                                                                                                    8.5 Utility Libraries

                                                                                                                                                    8.5.1 exception.i

                                                                                                                                                    The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                                                                                                                                    SWIG_exception(int code, const char *message)

                                                                                                                                                    Raises an exception in the target language. code is one of the following symbolic constants:

                                                                                                                                                    SWIG_MemoryError
                                                                                                                                                    SWIG_IOError
                                                                                                                                                    SWIG_RuntimeError
                                                                                                                                                    SWIG_IndexError
                                                                                                                                                    SWIG_TypeError
                                                                                                                                                    SWIG_DivisionByZero
                                                                                                                                                    SWIG_OverflowError
                                                                                                                                                    SWIG_SyntaxError
                                                                                                                                                    SWIG_ValueError
                                                                                                                                                    SWIG_SystemError
                                                                                                                                                    

                                                                                                                                                    message is a string indicating more information about the problem.

                                                                                                                                                    The primary use of this module is in writing language-independent exception handlers. For example:

                                                                                                                                                    %include "exception.i"
                                                                                                                                                    %exception std::vector::getitem {
                                                                                                                                                        try {
                                                                                                                                                            $action
                                                                                                                                                        } catch (std::out_of_range& e) {
                                                                                                                                                            SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                                                                                                                        }
                                                                                                                                                    }
                                                                                                                                                    

                                                                                                                                                    ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                                                                                                                                    

                                                                                                                                                    SWIG-1.3 Documentation

                                                                                                                                                    
                                                                                                                                                    

                                                                                                                                                    ---

                                                                                                                                                    Table of Contents

                                                                                                                                                    
                                                                                                                                                    
                                                                                                                                                    SWIG-1.3 Development Documentation
                                                                                                                                                    • Sections
                                                                                                                                                    • SWIG Core Documentation
                                                                                                                                                    • Language Module Documentation
                                                                                                                                                    • Developer Documentation
                                                                                                                                                    • Documentation that has not yet been updated
                                                                                                                                                    1 Preface
                                                                                                                                                    • 1.1 Introduction
                                                                                                                                                    • 1.2 Special Introduction for Version 1.3
                                                                                                                                                    • 1.3 SWIG Versions
                                                                                                                                                    • 1.4 SWIG resources
                                                                                                                                                    • 1.5 Prerequisites
                                                                                                                                                    • 1.6 Organization of this manual
                                                                                                                                                    • 1.7 How to avoid reading the manual
                                                                                                                                                    • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                                                                                                                                      >>> make_upper("hello world")
                                                                                                                                                      'HELLO WORLD'
                                                                                                                                                      >>> attach_header("Hello world")
                                                                                                                                                      'header: Hello world'
                                                                                                                                                      >>>
                                                                                                                                                      

                                                                                                                                                      This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                                                                                                                                      %cstring_output_maxsize(parm, maxparm)

                                                                                                                                                      This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                                                                                                                                      %cstring_output_maxsize(char *path, int maxpath);
                                                                                                                                                      ...
                                                                                                                                                      void get_path(char *path, int maxpath);
                                                                                                                                                      

                                                                                                                                                      In the target language:

                                                                                                                                                      >>> get_path(1024)
                                                                                                                                                      '/home/beazley/Packages/Foo/Bar'
                                                                                                                                                      >>>
                                                                                                                                                      

                                                                                                                                                      This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                                                                                                                                      %cstring_output_withsize(parm, maxparm)

                                                                                                                                                      This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                                                                                                                                      %cstring_output_withsize(char *data, int *maxdata);
                                                                                                                                                      ...
                                                                                                                                                      void get_data(char *data, int *maxdata);
                                                                                                                                                      

                                                                                                                                                      In the target language:

                                                                                                                                                      >>> get_data(1024)
                                                                                                                                                      'x627388912'
                                                                                                                                                      >>> get_data(1024)
                                                                                                                                                      'xyzzy'
                                                                                                                                                      >>>
                                                                                                                                                      

                                                                                                                                                      This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                                                                                                                                      %cstring_output_allocate(parm, release)

                                                                                                                                                      This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                                                                                                                                      void foo(char **s) {
                                                                                                                                                          *s = (char *) malloc(64);
                                                                                                                                                          sprintf(*s, "Hello world\n");
                                                                                                                                                      }
                                                                                                                                                      

                                                                                                                                                      The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                                                                      %cstring_output_allocate(char **s, free(*$1));
                                                                                                                                                      ...
                                                                                                                                                      void foo(char **s);
                                                                                                                                                      

                                                                                                                                                      In the target language:

                                                                                                                                                      >>> foo()
                                                                                                                                                      'Hello world\n'
                                                                                                                                                      >>>
                                                                                                                                                      

                                                                                                                                                      %cstring_output_allocate_size(parm, szparm, release)

                                                                                                                                                      This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                                                                                                                                      void foo(char **s, int *sz) {
                                                                                                                                                          *s = (char *) malloc(64);
                                                                                                                                                          *sz = 64;
                                                                                                                                                          // Write some binary data
                                                                                                                                                          ...
                                                                                                                                                      }
                                                                                                                                                      

                                                                                                                                                      The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                                                                      %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                                                                                                                                      ...
                                                                                                                                                      void foo(char **s, int *slen);
                                                                                                                                                      

                                                                                                                                                      In the target language:

                                                                                                                                                      >>> foo()
                                                                                                                                                      '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                                                                                                                                      >>>
                                                                                                                                                      

                                                                                                                                                      This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                                                                                                                                      char  *get_data(int *len);
                                                                                                                                                      

                                                                                                                                                      You could wrap it with a function like this:

                                                                                                                                                      void my_get_data(char **result, int *len) {
                                                                                                                                                         *result = get_data(len);
                                                                                                                                                      }
                                                                                                                                                      

                                                                                                                                                      Comments:
                                                                                                                                                      • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                                                                                                                                      • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                                                                                                                                      • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                                                                                                                                      • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                                                                                                                                      8.4 C++ Library

                                                                                                                                                      The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                                                                                                                                      8.4.1 std_string.i

                                                                                                                                                      The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                                                                                                                                      %module example
                                                                                                                                                      %include "std_string.i"
                                                                                                                                                      
                                                                                                                                                      std::string foo();
                                                                                                                                                      void        bar(const std::string &x);
                                                                                                                                                      

                                                                                                                                                      In the target language:

                                                                                                                                                      x = foo();                # Returns a string object
                                                                                                                                                      bar("Hello World");       # Pass string as std::string
                                                                                                                                                      

                                                                                                                                                      This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                                                                                                                                      This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                                                                                                                                      %module example
                                                                                                                                                      %include "std_string.i"
                                                                                                                                                      
                                                                                                                                                      using namespace std;
                                                                                                                                                      typedef std::string String;
                                                                                                                                                      ...
                                                                                                                                                      void foo(string s, const String &t);     // std_string typemaps still applied
                                                                                                                                                      

                                                                                                                                                      Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                                                                                                                                      8.4.2 std_vector.i

                                                                                                                                                      The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                                                                                                                                      %module example
                                                                                                                                                      %include "std_vector.i"
                                                                                                                                                      
                                                                                                                                                      namespace std {
                                                                                                                                                         %template(vectori) vector<int>;
                                                                                                                                                         %template(vectord) vector<double>;
                                                                                                                                                      };
                                                                                                                                                      

                                                                                                                                                      When a template vector<X> is instantiated a number of things happen:
                                                                                                                                                      • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                                                                                                                                      • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                                                                                                                                      • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                                                                                                                                      • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                                                                                                                                      • An exception handler for std::out_of_range is defined.
                                                                                                                                                      • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                                                                                                                                      To illustrate the use of this library, consider the following functions:

                                                                                                                                                      /* File : example.h */
                                                                                                                                                      
                                                                                                                                                      #include <vector>
                                                                                                                                                      #include <algorithm>
                                                                                                                                                      #include <functional>
                                                                                                                                                      #include <numeric>
                                                                                                                                                      
                                                                                                                                                      double average(std::vector<int> v) {
                                                                                                                                                          return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                                                                                                                                      }
                                                                                                                                                      
                                                                                                                                                      std::vector<double> half(const std::vector<double>& v) {
                                                                                                                                                          std::vector<double> w(v);
                                                                                                                                                          for (unsigned int i=0; i<w.size(); i++)
                                                                                                                                                              w[i] /= 2.0;
                                                                                                                                                          return w;
                                                                                                                                                      }
                                                                                                                                                      
                                                                                                                                                      void halve_in_place(std::vector<double>& v) {
                                                                                                                                                          std::transform(v.begin(),v.end(),v.begin(),
                                                                                                                                                                         std::bind2nd(std::divides<double>(),2.0));
                                                                                                                                                      }
                                                                                                                                                      

                                                                                                                                                      To wrap with SWIG, you might write the following:

                                                                                                                                                      %module example
                                                                                                                                                      %{
                                                                                                                                                      #include "example.h"
                                                                                                                                                      %}
                                                                                                                                                      
                                                                                                                                                      %include "std_vector.i"
                                                                                                                                                      // Instantiate templates used by example
                                                                                                                                                      namespace std {
                                                                                                                                                         %template(IntVector) vector<int>;
                                                                                                                                                         %template(DoubleVector) vector<double>;
                                                                                                                                                      }
                                                                                                                                                      
                                                                                                                                                      // Include the header file with above prototypes
                                                                                                                                                      %include "example.h"
                                                                                                                                                      

                                                                                                                                                      Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                                                                                                                                      >>> from example import *
                                                                                                                                                      >>> iv = IntVector(4)         # Create an vector<int>
                                                                                                                                                      >>> for i in range(0,4):
                                                                                                                                                      ...      iv[i] = i
                                                                                                                                                      >>> average(iv)               # Call method
                                                                                                                                                      1.5
                                                                                                                                                      >>> average([0,1,2,3])        # Call with list
                                                                                                                                                      1.5
                                                                                                                                                      >>> half([1,2,3])             # Half a list
                                                                                                                                                      (0.5,1.0,1.5)
                                                                                                                                                      >>> halve_in_place([1,2,3])   # Oops
                                                                                                                                                      Traceback (most recent call last):
                                                                                                                                                        File "<stdin>", line 1, in ?
                                                                                                                                                      TypeError: Type error. Expected _p_std__vectorTdouble_t
                                                                                                                                                      >>> dv = DoubleVector(4)
                                                                                                                                                      >>> for i in range(0,4):
                                                                                                                                                      ...       dv[i] = i
                                                                                                                                                      >>> halve_in_place(dv)       # Ok
                                                                                                                                                      >>> for i in dv:
                                                                                                                                                      ...       print i
                                                                                                                                                      ...
                                                                                                                                                      0.0
                                                                                                                                                      0.5
                                                                                                                                                      1.0
                                                                                                                                                      1.5
                                                                                                                                                      >>> dv[20] = 4.5
                                                                                                                                                      Traceback (most recent call last):
                                                                                                                                                        File "<stdin>", line 1, in ?
                                                                                                                                                        File "example.py", line 81, in __setitem__
                                                                                                                                                          def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                                                                                                                                      IndexError: vector index out of range
                                                                                                                                                      >>>
                                                                                                                                                      

                                                                                                                                                      This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                                                                                                                                      %include "std_vector.i"
                                                                                                                                                      
                                                                                                                                                      namespace std {
                                                                                                                                                          %template(IntVector) vector<int>;
                                                                                                                                                      }
                                                                                                                                                      
                                                                                                                                                      using namespace std;
                                                                                                                                                      typedef std::vector Vector;
                                                                                                                                                      
                                                                                                                                                      void foo(vector<int> *x, const Vector &x);
                                                                                                                                                      

                                                                                                                                                      Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                                                                                                                                      Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                                                                                                                                      Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                                                                                                                                      8.5 Utility Libraries

                                                                                                                                                      8.5.1 exception.i

                                                                                                                                                      The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                                                                                                                                      SWIG_exception(int code, const char *message)

                                                                                                                                                      Raises an exception in the target language. code is one of the following symbolic constants:

                                                                                                                                                      SWIG_MemoryError
                                                                                                                                                      SWIG_IOError
                                                                                                                                                      SWIG_RuntimeError
                                                                                                                                                      SWIG_IndexError
                                                                                                                                                      SWIG_TypeError
                                                                                                                                                      SWIG_DivisionByZero
                                                                                                                                                      SWIG_OverflowError
                                                                                                                                                      SWIG_SyntaxError
                                                                                                                                                      SWIG_ValueError
                                                                                                                                                      SWIG_SystemError
                                                                                                                                                      

                                                                                                                                                      message is a string indicating more information about the problem.

                                                                                                                                                      The primary use of this module is in writing language-independent exception handlers. For example:

                                                                                                                                                      %include "exception.i"
                                                                                                                                                      %exception std::vector::getitem {
                                                                                                                                                          try {
                                                                                                                                                              $action
                                                                                                                                                          } catch (std::out_of_range& e) {
                                                                                                                                                              SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                                                                                                                          }
                                                                                                                                                      }
                                                                                                                                                      

                                                                                                                                                      ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                                                                                                                                      

                                                                                                                                                      SWIG-1.3 Documentation

                                                                                                                                                      
                                                                                                                                                      

                                                                                                                                                      ---

                                                                                                                                                      Table of Contents

                                                                                                                                                      
                                                                                                                                                      
                                                                                                                                                      SWIG-1.3 Development Documentation
                                                                                                                                                      • Sections
                                                                                                                                                      • SWIG Core Documentation
                                                                                                                                                      • Language Module Documentation
                                                                                                                                                      • Developer Documentation
                                                                                                                                                      • Documentation that has not yet been updated
                                                                                                                                                      1 Preface
                                                                                                                                                      • 1.1 Introduction
                                                                                                                                                      • 1.2 Special Introduction for Version 1.3
                                                                                                                                                      • 1.3 SWIG Versions
                                                                                                                                                      • 1.4 SWIG resources
                                                                                                                                                      • 1.5 Prerequisites
                                                                                                                                                      • 1.6 Organization of this manual
                                                                                                                                                      • 1.7 How to avoid reading the manual
                                                                                                                                                      • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                                                                                                                                        >>> make_upper("hello world")
                                                                                                                                                        'HELLO WORLD'
                                                                                                                                                        >>> attach_header("Hello world")
                                                                                                                                                        'header: Hello world'
                                                                                                                                                        >>>
                                                                                                                                                        

                                                                                                                                                        This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                                                                                                                                        %cstring_output_maxsize(parm, maxparm)

                                                                                                                                                        This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                                                                                                                                        %cstring_output_maxsize(char *path, int maxpath);
                                                                                                                                                        ...
                                                                                                                                                        void get_path(char *path, int maxpath);
                                                                                                                                                        

                                                                                                                                                        In the target language:

                                                                                                                                                        >>> get_path(1024)
                                                                                                                                                        '/home/beazley/Packages/Foo/Bar'
                                                                                                                                                        >>>
                                                                                                                                                        

                                                                                                                                                        This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                                                                                                                                        %cstring_output_withsize(parm, maxparm)

                                                                                                                                                        This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                                                                                                                                        %cstring_output_withsize(char *data, int *maxdata);
                                                                                                                                                        ...
                                                                                                                                                        void get_data(char *data, int *maxdata);
                                                                                                                                                        

                                                                                                                                                        In the target language:

                                                                                                                                                        >>> get_data(1024)
                                                                                                                                                        'x627388912'
                                                                                                                                                        >>> get_data(1024)
                                                                                                                                                        'xyzzy'
                                                                                                                                                        >>>
                                                                                                                                                        

                                                                                                                                                        This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                                                                                                                                        %cstring_output_allocate(parm, release)

                                                                                                                                                        This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                                                                                                                                        void foo(char **s) {
                                                                                                                                                            *s = (char *) malloc(64);
                                                                                                                                                            sprintf(*s, "Hello world\n");
                                                                                                                                                        }
                                                                                                                                                        

                                                                                                                                                        The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                                                                        %cstring_output_allocate(char **s, free(*$1));
                                                                                                                                                        ...
                                                                                                                                                        void foo(char **s);
                                                                                                                                                        

                                                                                                                                                        In the target language:

                                                                                                                                                        >>> foo()
                                                                                                                                                        'Hello world\n'
                                                                                                                                                        >>>
                                                                                                                                                        

                                                                                                                                                        %cstring_output_allocate_size(parm, szparm, release)

                                                                                                                                                        This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                                                                                                                                        void foo(char **s, int *sz) {
                                                                                                                                                            *s = (char *) malloc(64);
                                                                                                                                                            *sz = 64;
                                                                                                                                                            // Write some binary data
                                                                                                                                                            ...
                                                                                                                                                        }
                                                                                                                                                        

                                                                                                                                                        The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                                                                        %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                                                                                                                                        ...
                                                                                                                                                        void foo(char **s, int *slen);
                                                                                                                                                        

                                                                                                                                                        In the target language:

                                                                                                                                                        >>> foo()
                                                                                                                                                        '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                                                                                                                                        >>>
                                                                                                                                                        

                                                                                                                                                        This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                                                                                                                                        char  *get_data(int *len);
                                                                                                                                                        

                                                                                                                                                        You could wrap it with a function like this:

                                                                                                                                                        void my_get_data(char **result, int *len) {
                                                                                                                                                           *result = get_data(len);
                                                                                                                                                        }
                                                                                                                                                        

                                                                                                                                                        Comments:
                                                                                                                                                        • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                                                                                                                                        • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                                                                                                                                        • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                                                                                                                                        • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                                                                                                                                        8.4 C++ Library

                                                                                                                                                        The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                                                                                                                                        8.4.1 std_string.i

                                                                                                                                                        The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                                                                                                                                        %module example
                                                                                                                                                        %include "std_string.i"
                                                                                                                                                        
                                                                                                                                                        std::string foo();
                                                                                                                                                        void        bar(const std::string &x);
                                                                                                                                                        

                                                                                                                                                        In the target language:

                                                                                                                                                        x = foo();                # Returns a string object
                                                                                                                                                        bar("Hello World");       # Pass string as std::string
                                                                                                                                                        

                                                                                                                                                        This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                                                                                                                                        This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                                                                                                                                        %module example
                                                                                                                                                        %include "std_string.i"
                                                                                                                                                        
                                                                                                                                                        using namespace std;
                                                                                                                                                        typedef std::string String;
                                                                                                                                                        ...
                                                                                                                                                        void foo(string s, const String &t);     // std_string typemaps still applied
                                                                                                                                                        

                                                                                                                                                        Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                                                                                                                                        8.4.2 std_vector.i

                                                                                                                                                        The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                                                                                                                                        %module example
                                                                                                                                                        %include "std_vector.i"
                                                                                                                                                        
                                                                                                                                                        namespace std {
                                                                                                                                                           %template(vectori) vector<int>;
                                                                                                                                                           %template(vectord) vector<double>;
                                                                                                                                                        };
                                                                                                                                                        

                                                                                                                                                        When a template vector<X> is instantiated a number of things happen:
                                                                                                                                                        • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                                                                                                                                        • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                                                                                                                                        • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                                                                                                                                        • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                                                                                                                                        • An exception handler for std::out_of_range is defined.
                                                                                                                                                        • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                                                                                                                                        To illustrate the use of this library, consider the following functions:

                                                                                                                                                        /* File : example.h */
                                                                                                                                                        
                                                                                                                                                        #include <vector>
                                                                                                                                                        #include <algorithm>
                                                                                                                                                        #include <functional>
                                                                                                                                                        #include <numeric>
                                                                                                                                                        
                                                                                                                                                        double average(std::vector<int> v) {
                                                                                                                                                            return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                                                                                                                                        }
                                                                                                                                                        
                                                                                                                                                        std::vector<double> half(const std::vector<double>& v) {
                                                                                                                                                            std::vector<double> w(v);
                                                                                                                                                            for (unsigned int i=0; i<w.size(); i++)
                                                                                                                                                                w[i] /= 2.0;
                                                                                                                                                            return w;
                                                                                                                                                        }
                                                                                                                                                        
                                                                                                                                                        void halve_in_place(std::vector<double>& v) {
                                                                                                                                                            std::transform(v.begin(),v.end(),v.begin(),
                                                                                                                                                                           std::bind2nd(std::divides<double>(),2.0));
                                                                                                                                                        }
                                                                                                                                                        

                                                                                                                                                        To wrap with SWIG, you might write the following:

                                                                                                                                                        %module example
                                                                                                                                                        %{
                                                                                                                                                        #include "example.h"
                                                                                                                                                        %}
                                                                                                                                                        
                                                                                                                                                        %include "std_vector.i"
                                                                                                                                                        // Instantiate templates used by example
                                                                                                                                                        namespace std {
                                                                                                                                                           %template(IntVector) vector<int>;
                                                                                                                                                           %template(DoubleVector) vector<double>;
                                                                                                                                                        }
                                                                                                                                                        
                                                                                                                                                        // Include the header file with above prototypes
                                                                                                                                                        %include "example.h"
                                                                                                                                                        

                                                                                                                                                        Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                                                                                                                                        >>> from example import *
                                                                                                                                                        >>> iv = IntVector(4)         # Create an vector<int>
                                                                                                                                                        >>> for i in range(0,4):
                                                                                                                                                        ...      iv[i] = i
                                                                                                                                                        >>> average(iv)               # Call method
                                                                                                                                                        1.5
                                                                                                                                                        >>> average([0,1,2,3])        # Call with list
                                                                                                                                                        1.5
                                                                                                                                                        >>> half([1,2,3])             # Half a list
                                                                                                                                                        (0.5,1.0,1.5)
                                                                                                                                                        >>> halve_in_place([1,2,3])   # Oops
                                                                                                                                                        Traceback (most recent call last):
                                                                                                                                                          File "<stdin>", line 1, in ?
                                                                                                                                                        TypeError: Type error. Expected _p_std__vectorTdouble_t
                                                                                                                                                        >>> dv = DoubleVector(4)
                                                                                                                                                        >>> for i in range(0,4):
                                                                                                                                                        ...       dv[i] = i
                                                                                                                                                        >>> halve_in_place(dv)       # Ok
                                                                                                                                                        >>> for i in dv:
                                                                                                                                                        ...       print i
                                                                                                                                                        ...
                                                                                                                                                        0.0
                                                                                                                                                        0.5
                                                                                                                                                        1.0
                                                                                                                                                        1.5
                                                                                                                                                        >>> dv[20] = 4.5
                                                                                                                                                        Traceback (most recent call last):
                                                                                                                                                          File "<stdin>", line 1, in ?
                                                                                                                                                          File "example.py", line 81, in __setitem__
                                                                                                                                                            def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                                                                                                                                        IndexError: vector index out of range
                                                                                                                                                        >>>
                                                                                                                                                        

                                                                                                                                                        This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                                                                                                                                        %include "std_vector.i"
                                                                                                                                                        
                                                                                                                                                        namespace std {
                                                                                                                                                            %template(IntVector) vector<int>;
                                                                                                                                                        }
                                                                                                                                                        
                                                                                                                                                        using namespace std;
                                                                                                                                                        typedef std::vector Vector;
                                                                                                                                                        
                                                                                                                                                        void foo(vector<int> *x, const Vector &x);
                                                                                                                                                        

                                                                                                                                                        Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                                                                                                                                        Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                                                                                                                                        Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                                                                                                                                        8.5 Utility Libraries

                                                                                                                                                        8.5.1 exception.i

                                                                                                                                                        The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                                                                                                                                        SWIG_exception(int code, const char *message)

                                                                                                                                                        Raises an exception in the target language. code is one of the following symbolic constants:

                                                                                                                                                        SWIG_MemoryError
                                                                                                                                                        SWIG_IOError
                                                                                                                                                        SWIG_RuntimeError
                                                                                                                                                        SWIG_IndexError
                                                                                                                                                        SWIG_TypeError
                                                                                                                                                        SWIG_DivisionByZero
                                                                                                                                                        SWIG_OverflowError
                                                                                                                                                        SWIG_SyntaxError
                                                                                                                                                        SWIG_ValueError
                                                                                                                                                        SWIG_SystemError
                                                                                                                                                        

                                                                                                                                                        message is a string indicating more information about the problem.

                                                                                                                                                        The primary use of this module is in writing language-independent exception handlers. For example:

                                                                                                                                                        %include "exception.i"
                                                                                                                                                        %exception std::vector::getitem {
                                                                                                                                                            try {
                                                                                                                                                                $action
                                                                                                                                                            } catch (std::out_of_range& e) {
                                                                                                                                                                SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                                                                                                                            }
                                                                                                                                                        }
                                                                                                                                                        

                                                                                                                                                        ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                                                                                                                                        

                                                                                                                                                        SWIG-1.3 Documentation

                                                                                                                                                        
                                                                                                                                                        

                                                                                                                                                        ---

                                                                                                                                                        Table of Contents

                                                                                                                                                        
                                                                                                                                                        
                                                                                                                                                        SWIG-1.3 Development Documentation
                                                                                                                                                        • Sections
                                                                                                                                                        • SWIG Core Documentation
                                                                                                                                                        • Language Module Documentation
                                                                                                                                                        • Developer Documentation
                                                                                                                                                        • Documentation that has not yet been updated
                                                                                                                                                        1 Preface
                                                                                                                                                        • 1.1 Introduction
                                                                                                                                                        • 1.2 Special Introduction for Version 1.3
                                                                                                                                                        • 1.3 SWIG Versions
                                                                                                                                                        • 1.4 SWIG resources
                                                                                                                                                        • 1.5 Prerequisites
                                                                                                                                                        • 1.6 Organization of this manual
                                                                                                                                                        • 1.7 How to avoid reading the manual
                                                                                                                                                        • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                                                                                                                                          >>> make_upper("hello world")
                                                                                                                                                          'HELLO WORLD'
                                                                                                                                                          >>> attach_header("Hello world")
                                                                                                                                                          'header: Hello world'
                                                                                                                                                          >>>
                                                                                                                                                          

                                                                                                                                                          This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                                                                                                                                          %cstring_output_maxsize(parm, maxparm)

                                                                                                                                                          This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                                                                                                                                          %cstring_output_maxsize(char *path, int maxpath);
                                                                                                                                                          ...
                                                                                                                                                          void get_path(char *path, int maxpath);
                                                                                                                                                          

                                                                                                                                                          In the target language:

                                                                                                                                                          >>> get_path(1024)
                                                                                                                                                          '/home/beazley/Packages/Foo/Bar'
                                                                                                                                                          >>>
                                                                                                                                                          

                                                                                                                                                          This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                                                                                                                                          %cstring_output_withsize(parm, maxparm)

                                                                                                                                                          This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                                                                                                                                          %cstring_output_withsize(char *data, int *maxdata);
                                                                                                                                                          ...
                                                                                                                                                          void get_data(char *data, int *maxdata);
                                                                                                                                                          

                                                                                                                                                          In the target language:

                                                                                                                                                          >>> get_data(1024)
                                                                                                                                                          'x627388912'
                                                                                                                                                          >>> get_data(1024)
                                                                                                                                                          'xyzzy'
                                                                                                                                                          >>>
                                                                                                                                                          

                                                                                                                                                          This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                                                                                                                                          %cstring_output_allocate(parm, release)

                                                                                                                                                          This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                                                                                                                                          void foo(char **s) {
                                                                                                                                                              *s = (char *) malloc(64);
                                                                                                                                                              sprintf(*s, "Hello world\n");
                                                                                                                                                          }
                                                                                                                                                          

                                                                                                                                                          The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                                                                          %cstring_output_allocate(char **s, free(*$1));
                                                                                                                                                          ...
                                                                                                                                                          void foo(char **s);
                                                                                                                                                          

                                                                                                                                                          In the target language:

                                                                                                                                                          >>> foo()
                                                                                                                                                          'Hello world\n'
                                                                                                                                                          >>>
                                                                                                                                                          

                                                                                                                                                          %cstring_output_allocate_size(parm, szparm, release)

                                                                                                                                                          This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                                                                                                                                          void foo(char **s, int *sz) {
                                                                                                                                                              *s = (char *) malloc(64);
                                                                                                                                                              *sz = 64;
                                                                                                                                                              // Write some binary data
                                                                                                                                                              ...
                                                                                                                                                          }
                                                                                                                                                          

                                                                                                                                                          The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                                                                          %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                                                                                                                                          ...
                                                                                                                                                          void foo(char **s, int *slen);
                                                                                                                                                          

                                                                                                                                                          In the target language:

                                                                                                                                                          >>> foo()
                                                                                                                                                          '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                                                                                                                                          >>>
                                                                                                                                                          

                                                                                                                                                          This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                                                                                                                                          char  *get_data(int *len);
                                                                                                                                                          

                                                                                                                                                          You could wrap it with a function like this:

                                                                                                                                                          void my_get_data(char **result, int *len) {
                                                                                                                                                             *result = get_data(len);
                                                                                                                                                          }
                                                                                                                                                          

                                                                                                                                                          Comments:
                                                                                                                                                          • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                                                                                                                                          • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                                                                                                                                          • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                                                                                                                                          • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                                                                                                                                          8.4 C++ Library

                                                                                                                                                          The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                                                                                                                                          8.4.1 std_string.i

                                                                                                                                                          The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                                                                                                                                          %module example
                                                                                                                                                          %include "std_string.i"
                                                                                                                                                          
                                                                                                                                                          std::string foo();
                                                                                                                                                          void        bar(const std::string &x);
                                                                                                                                                          

                                                                                                                                                          In the target language:

                                                                                                                                                          x = foo();                # Returns a string object
                                                                                                                                                          bar("Hello World");       # Pass string as std::string
                                                                                                                                                          

                                                                                                                                                          This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                                                                                                                                          This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                                                                                                                                          %module example
                                                                                                                                                          %include "std_string.i"
                                                                                                                                                          
                                                                                                                                                          using namespace std;
                                                                                                                                                          typedef std::string String;
                                                                                                                                                          ...
                                                                                                                                                          void foo(string s, const String &t);     // std_string typemaps still applied
                                                                                                                                                          

                                                                                                                                                          Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                                                                                                                                          8.4.2 std_vector.i

                                                                                                                                                          The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                                                                                                                                          %module example
                                                                                                                                                          %include "std_vector.i"
                                                                                                                                                          
                                                                                                                                                          namespace std {
                                                                                                                                                             %template(vectori) vector<int>;
                                                                                                                                                             %template(vectord) vector<double>;
                                                                                                                                                          };
                                                                                                                                                          

                                                                                                                                                          When a template vector<X> is instantiated a number of things happen:
                                                                                                                                                          • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                                                                                                                                          • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                                                                                                                                          • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                                                                                                                                          • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                                                                                                                                          • An exception handler for std::out_of_range is defined.
                                                                                                                                                          • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                                                                                                                                          To illustrate the use of this library, consider the following functions:

                                                                                                                                                          /* File : example.h */
                                                                                                                                                          
                                                                                                                                                          #include <vector>
                                                                                                                                                          #include <algorithm>
                                                                                                                                                          #include <functional>
                                                                                                                                                          #include <numeric>
                                                                                                                                                          
                                                                                                                                                          double average(std::vector<int> v) {
                                                                                                                                                              return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                                                                                                                                          }
                                                                                                                                                          
                                                                                                                                                          std::vector<double> half(const std::vector<double>& v) {
                                                                                                                                                              std::vector<double> w(v);
                                                                                                                                                              for (unsigned int i=0; i<w.size(); i++)
                                                                                                                                                                  w[i] /= 2.0;
                                                                                                                                                              return w;
                                                                                                                                                          }
                                                                                                                                                          
                                                                                                                                                          void halve_in_place(std::vector<double>& v) {
                                                                                                                                                              std::transform(v.begin(),v.end(),v.begin(),
                                                                                                                                                                             std::bind2nd(std::divides<double>(),2.0));
                                                                                                                                                          }
                                                                                                                                                          

                                                                                                                                                          To wrap with SWIG, you might write the following:

                                                                                                                                                          %module example
                                                                                                                                                          %{
                                                                                                                                                          #include "example.h"
                                                                                                                                                          %}
                                                                                                                                                          
                                                                                                                                                          %include "std_vector.i"
                                                                                                                                                          // Instantiate templates used by example
                                                                                                                                                          namespace std {
                                                                                                                                                             %template(IntVector) vector<int>;
                                                                                                                                                             %template(DoubleVector) vector<double>;
                                                                                                                                                          }
                                                                                                                                                          
                                                                                                                                                          // Include the header file with above prototypes
                                                                                                                                                          %include "example.h"
                                                                                                                                                          

                                                                                                                                                          Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                                                                                                                                          >>> from example import *
                                                                                                                                                          >>> iv = IntVector(4)         # Create an vector<int>
                                                                                                                                                          >>> for i in range(0,4):
                                                                                                                                                          ...      iv[i] = i
                                                                                                                                                          >>> average(iv)               # Call method
                                                                                                                                                          1.5
                                                                                                                                                          >>> average([0,1,2,3])        # Call with list
                                                                                                                                                          1.5
                                                                                                                                                          >>> half([1,2,3])             # Half a list
                                                                                                                                                          (0.5,1.0,1.5)
                                                                                                                                                          >>> halve_in_place([1,2,3])   # Oops
                                                                                                                                                          Traceback (most recent call last):
                                                                                                                                                            File "<stdin>", line 1, in ?
                                                                                                                                                          TypeError: Type error. Expected _p_std__vectorTdouble_t
                                                                                                                                                          >>> dv = DoubleVector(4)
                                                                                                                                                          >>> for i in range(0,4):
                                                                                                                                                          ...       dv[i] = i
                                                                                                                                                          >>> halve_in_place(dv)       # Ok
                                                                                                                                                          >>> for i in dv:
                                                                                                                                                          ...       print i
                                                                                                                                                          ...
                                                                                                                                                          0.0
                                                                                                                                                          0.5
                                                                                                                                                          1.0
                                                                                                                                                          1.5
                                                                                                                                                          >>> dv[20] = 4.5
                                                                                                                                                          Traceback (most recent call last):
                                                                                                                                                            File "<stdin>", line 1, in ?
                                                                                                                                                            File "example.py", line 81, in __setitem__
                                                                                                                                                              def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                                                                                                                                          IndexError: vector index out of range
                                                                                                                                                          >>>
                                                                                                                                                          

                                                                                                                                                          This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                                                                                                                                          %include "std_vector.i"
                                                                                                                                                          
                                                                                                                                                          namespace std {
                                                                                                                                                              %template(IntVector) vector<int>;
                                                                                                                                                          }
                                                                                                                                                          
                                                                                                                                                          using namespace std;
                                                                                                                                                          typedef std::vector Vector;
                                                                                                                                                          
                                                                                                                                                          void foo(vector<int> *x, const Vector &x);
                                                                                                                                                          

                                                                                                                                                          Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                                                                                                                                          Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                                                                                                                                          Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                                                                                                                                          8.5 Utility Libraries

                                                                                                                                                          8.5.1 exception.i

                                                                                                                                                          The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                                                                                                                                          SWIG_exception(int code, const char *message)

                                                                                                                                                          Raises an exception in the target language. code is one of the following symbolic constants:

                                                                                                                                                          SWIG_MemoryError
                                                                                                                                                          SWIG_IOError
                                                                                                                                                          SWIG_RuntimeError
                                                                                                                                                          SWIG_IndexError
                                                                                                                                                          SWIG_TypeError
                                                                                                                                                          SWIG_DivisionByZero
                                                                                                                                                          SWIG_OverflowError
                                                                                                                                                          SWIG_SyntaxError
                                                                                                                                                          SWIG_ValueError
                                                                                                                                                          SWIG_SystemError
                                                                                                                                                          

                                                                                                                                                          message is a string indicating more information about the problem.

                                                                                                                                                          The primary use of this module is in writing language-independent exception handlers. For example:

                                                                                                                                                          %include "exception.i"
                                                                                                                                                          %exception std::vector::getitem {
                                                                                                                                                              try {
                                                                                                                                                                  $action
                                                                                                                                                              } catch (std::out_of_range& e) {
                                                                                                                                                                  SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                                                                                                                              }
                                                                                                                                                          }
                                                                                                                                                          

                                                                                                                                                          ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                                                                                                                                          

                                                                                                                                                          SWIG-1.3 Documentation

                                                                                                                                                          
                                                                                                                                                          

                                                                                                                                                          ---

                                                                                                                                                          Table of Contents

                                                                                                                                                          
                                                                                                                                                          
                                                                                                                                                          SWIG-1.3 Development Documentation
                                                                                                                                                          • Sections
                                                                                                                                                          • SWIG Core Documentation
                                                                                                                                                          • Language Module Documentation
                                                                                                                                                          • Developer Documentation
                                                                                                                                                          • Documentation that has not yet been updated
                                                                                                                                                          1 Preface
                                                                                                                                                          • 1.1 Introduction
                                                                                                                                                          • 1.2 Special Introduction for Version 1.3
                                                                                                                                                          • 1.3 SWIG Versions
                                                                                                                                                          • 1.4 SWIG resources
                                                                                                                                                          • 1.5 Prerequisites
                                                                                                                                                          • 1.6 Organization of this manual
                                                                                                                                                          • 1.7 How to avoid reading the manual
                                                                                                                                                          • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                                                                                                                                            >>> make_upper("hello world")
                                                                                                                                                            'HELLO WORLD'
                                                                                                                                                            >>> attach_header("Hello world")
                                                                                                                                                            'header: Hello world'
                                                                                                                                                            >>>
                                                                                                                                                            

                                                                                                                                                            This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                                                                                                                                            %cstring_output_maxsize(parm, maxparm)

                                                                                                                                                            This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                                                                                                                                            %cstring_output_maxsize(char *path, int maxpath);
                                                                                                                                                            ...
                                                                                                                                                            void get_path(char *path, int maxpath);
                                                                                                                                                            

                                                                                                                                                            In the target language:

                                                                                                                                                            >>> get_path(1024)
                                                                                                                                                            '/home/beazley/Packages/Foo/Bar'
                                                                                                                                                            >>>
                                                                                                                                                            

                                                                                                                                                            This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                                                                                                                                            %cstring_output_withsize(parm, maxparm)

                                                                                                                                                            This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                                                                                                                                            %cstring_output_withsize(char *data, int *maxdata);
                                                                                                                                                            ...
                                                                                                                                                            void get_data(char *data, int *maxdata);
                                                                                                                                                            

                                                                                                                                                            In the target language:

                                                                                                                                                            >>> get_data(1024)
                                                                                                                                                            'x627388912'
                                                                                                                                                            >>> get_data(1024)
                                                                                                                                                            'xyzzy'
                                                                                                                                                            >>>
                                                                                                                                                            

                                                                                                                                                            This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                                                                                                                                            %cstring_output_allocate(parm, release)

                                                                                                                                                            This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                                                                                                                                            void foo(char **s) {
                                                                                                                                                                *s = (char *) malloc(64);
                                                                                                                                                                sprintf(*s, "Hello world\n");
                                                                                                                                                            }
                                                                                                                                                            

                                                                                                                                                            The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                                                                            %cstring_output_allocate(char **s, free(*$1));
                                                                                                                                                            ...
                                                                                                                                                            void foo(char **s);
                                                                                                                                                            

                                                                                                                                                            In the target language:

                                                                                                                                                            >>> foo()
                                                                                                                                                            'Hello world\n'
                                                                                                                                                            >>>
                                                                                                                                                            

                                                                                                                                                            %cstring_output_allocate_size(parm, szparm, release)

                                                                                                                                                            This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                                                                                                                                            void foo(char **s, int *sz) {
                                                                                                                                                                *s = (char *) malloc(64);
                                                                                                                                                                *sz = 64;
                                                                                                                                                                // Write some binary data
                                                                                                                                                                ...
                                                                                                                                                            }
                                                                                                                                                            

                                                                                                                                                            The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                                                                            %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                                                                                                                                            ...
                                                                                                                                                            void foo(char **s, int *slen);
                                                                                                                                                            

                                                                                                                                                            In the target language:

                                                                                                                                                            >>> foo()
                                                                                                                                                            '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                                                                                                                                            >>>
                                                                                                                                                            

                                                                                                                                                            This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                                                                                                                                            char  *get_data(int *len);
                                                                                                                                                            

                                                                                                                                                            You could wrap it with a function like this:

                                                                                                                                                            void my_get_data(char **result, int *len) {
                                                                                                                                                               *result = get_data(len);
                                                                                                                                                            }
                                                                                                                                                            

                                                                                                                                                            Comments:
                                                                                                                                                            • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                                                                                                                                            • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                                                                                                                                            • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                                                                                                                                            • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                                                                                                                                            8.4 C++ Library

                                                                                                                                                            The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                                                                                                                                            8.4.1 std_string.i

                                                                                                                                                            The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                                                                                                                                            %module example
                                                                                                                                                            %include "std_string.i"
                                                                                                                                                            
                                                                                                                                                            std::string foo();
                                                                                                                                                            void        bar(const std::string &x);
                                                                                                                                                            

                                                                                                                                                            In the target language:

                                                                                                                                                            x = foo();                # Returns a string object
                                                                                                                                                            bar("Hello World");       # Pass string as std::string
                                                                                                                                                            

                                                                                                                                                            This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                                                                                                                                            This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                                                                                                                                            %module example
                                                                                                                                                            %include "std_string.i"
                                                                                                                                                            
                                                                                                                                                            using namespace std;
                                                                                                                                                            typedef std::string String;
                                                                                                                                                            ...
                                                                                                                                                            void foo(string s, const String &t);     // std_string typemaps still applied
                                                                                                                                                            

                                                                                                                                                            Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                                                                                                                                            8.4.2 std_vector.i

                                                                                                                                                            The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                                                                                                                                            %module example
                                                                                                                                                            %include "std_vector.i"
                                                                                                                                                            
                                                                                                                                                            namespace std {
                                                                                                                                                               %template(vectori) vector<int>;
                                                                                                                                                               %template(vectord) vector<double>;
                                                                                                                                                            };
                                                                                                                                                            

                                                                                                                                                            When a template vector<X> is instantiated a number of things happen:
                                                                                                                                                            • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                                                                                                                                            • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                                                                                                                                            • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                                                                                                                                            • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                                                                                                                                            • An exception handler for std::out_of_range is defined.
                                                                                                                                                            • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                                                                                                                                            To illustrate the use of this library, consider the following functions:

                                                                                                                                                            /* File : example.h */
                                                                                                                                                            
                                                                                                                                                            #include <vector>
                                                                                                                                                            #include <algorithm>
                                                                                                                                                            #include <functional>
                                                                                                                                                            #include <numeric>
                                                                                                                                                            
                                                                                                                                                            double average(std::vector<int> v) {
                                                                                                                                                                return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                                                                                                                                            }
                                                                                                                                                            
                                                                                                                                                            std::vector<double> half(const std::vector<double>& v) {
                                                                                                                                                                std::vector<double> w(v);
                                                                                                                                                                for (unsigned int i=0; i<w.size(); i++)
                                                                                                                                                                    w[i] /= 2.0;
                                                                                                                                                                return w;
                                                                                                                                                            }
                                                                                                                                                            
                                                                                                                                                            void halve_in_place(std::vector<double>& v) {
                                                                                                                                                                std::transform(v.begin(),v.end(),v.begin(),
                                                                                                                                                                               std::bind2nd(std::divides<double>(),2.0));
                                                                                                                                                            }
                                                                                                                                                            

                                                                                                                                                            To wrap with SWIG, you might write the following:

                                                                                                                                                            %module example
                                                                                                                                                            %{
                                                                                                                                                            #include "example.h"
                                                                                                                                                            %}
                                                                                                                                                            
                                                                                                                                                            %include "std_vector.i"
                                                                                                                                                            // Instantiate templates used by example
                                                                                                                                                            namespace std {
                                                                                                                                                               %template(IntVector) vector<int>;
                                                                                                                                                               %template(DoubleVector) vector<double>;
                                                                                                                                                            }
                                                                                                                                                            
                                                                                                                                                            // Include the header file with above prototypes
                                                                                                                                                            %include "example.h"
                                                                                                                                                            

                                                                                                                                                            Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                                                                                                                                            >>> from example import *
                                                                                                                                                            >>> iv = IntVector(4)         # Create an vector<int>
                                                                                                                                                            >>> for i in range(0,4):
                                                                                                                                                            ...      iv[i] = i
                                                                                                                                                            >>> average(iv)               # Call method
                                                                                                                                                            1.5
                                                                                                                                                            >>> average([0,1,2,3])        # Call with list
                                                                                                                                                            1.5
                                                                                                                                                            >>> half([1,2,3])             # Half a list
                                                                                                                                                            (0.5,1.0,1.5)
                                                                                                                                                            >>> halve_in_place([1,2,3])   # Oops
                                                                                                                                                            Traceback (most recent call last):
                                                                                                                                                              File "<stdin>", line 1, in ?
                                                                                                                                                            TypeError: Type error. Expected _p_std__vectorTdouble_t
                                                                                                                                                            >>> dv = DoubleVector(4)
                                                                                                                                                            >>> for i in range(0,4):
                                                                                                                                                            ...       dv[i] = i
                                                                                                                                                            >>> halve_in_place(dv)       # Ok
                                                                                                                                                            >>> for i in dv:
                                                                                                                                                            ...       print i
                                                                                                                                                            ...
                                                                                                                                                            0.0
                                                                                                                                                            0.5
                                                                                                                                                            1.0
                                                                                                                                                            1.5
                                                                                                                                                            >>> dv[20] = 4.5
                                                                                                                                                            Traceback (most recent call last):
                                                                                                                                                              File "<stdin>", line 1, in ?
                                                                                                                                                              File "example.py", line 81, in __setitem__
                                                                                                                                                                def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                                                                                                                                            IndexError: vector index out of range
                                                                                                                                                            >>>
                                                                                                                                                            

                                                                                                                                                            This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                                                                                                                                            %include "std_vector.i"
                                                                                                                                                            
                                                                                                                                                            namespace std {
                                                                                                                                                                %template(IntVector) vector<int>;
                                                                                                                                                            }
                                                                                                                                                            
                                                                                                                                                            using namespace std;
                                                                                                                                                            typedef std::vector Vector;
                                                                                                                                                            
                                                                                                                                                            void foo(vector<int> *x, const Vector &x);
                                                                                                                                                            

                                                                                                                                                            Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                                                                                                                                            Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                                                                                                                                            Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                                                                                                                                            8.5 Utility Libraries

                                                                                                                                                            8.5.1 exception.i

                                                                                                                                                            The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                                                                                                                                            SWIG_exception(int code, const char *message)

                                                                                                                                                            Raises an exception in the target language. code is one of the following symbolic constants:

                                                                                                                                                            SWIG_MemoryError
                                                                                                                                                            SWIG_IOError
                                                                                                                                                            SWIG_RuntimeError
                                                                                                                                                            SWIG_IndexError
                                                                                                                                                            SWIG_TypeError
                                                                                                                                                            SWIG_DivisionByZero
                                                                                                                                                            SWIG_OverflowError
                                                                                                                                                            SWIG_SyntaxError
                                                                                                                                                            SWIG_ValueError
                                                                                                                                                            SWIG_SystemError
                                                                                                                                                            

                                                                                                                                                            message is a string indicating more information about the problem.

                                                                                                                                                            The primary use of this module is in writing language-independent exception handlers. For example:

                                                                                                                                                            %include "exception.i"
                                                                                                                                                            %exception std::vector::getitem {
                                                                                                                                                                try {
                                                                                                                                                                    $action
                                                                                                                                                                } catch (std::out_of_range& e) {
                                                                                                                                                                    SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                                                                                                                                }
                                                                                                                                                            }
                                                                                                                                                            

                                                                                                                                                            ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                                                                                                                                            

                                                                                                                                                            SWIG-1.3 Documentation

                                                                                                                                                            
                                                                                                                                                            

                                                                                                                                                            ---

                                                                                                                                                            Table of Contents

                                                                                                                                                            
                                                                                                                                                            
                                                                                                                                                            SWIG-1.3 Development Documentation
                                                                                                                                                            • Sections
                                                                                                                                                            • SWIG Core Documentation
                                                                                                                                                            • Language Module Documentation
                                                                                                                                                            • Developer Documentation
                                                                                                                                                            • Documentation that has not yet been updated
                                                                                                                                                            1 Preface
                                                                                                                                                            • 1.1 Introduction
                                                                                                                                                            • 1.2 Special Introduction for Version 1.3
                                                                                                                                                            • 1.3 SWIG Versions
                                                                                                                                                            • 1.4 SWIG resources
                                                                                                                                                            • 1.5 Prerequisites
                                                                                                                                                            • 1.6 Organization of this manual
                                                                                                                                                            • 1.7 How to avoid reading the manual
                                                                                                                                                            • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                                                                                                                                              >>> make_upper("hello world")
                                                                                                                                                              'HELLO WORLD'
                                                                                                                                                              >>> attach_header("Hello world")
                                                                                                                                                              'header: Hello world'
                                                                                                                                                              >>>
                                                                                                                                                              

                                                                                                                                                              This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                                                                                                                                              %cstring_output_maxsize(parm, maxparm)

                                                                                                                                                              This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                                                                                                                                              %cstring_output_maxsize(char *path, int maxpath);
                                                                                                                                                              ...
                                                                                                                                                              void get_path(char *path, int maxpath);
                                                                                                                                                              

                                                                                                                                                              In the target language:

                                                                                                                                                              >>> get_path(1024)
                                                                                                                                                              '/home/beazley/Packages/Foo/Bar'
                                                                                                                                                              >>>
                                                                                                                                                              

                                                                                                                                                              This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                                                                                                                                              %cstring_output_withsize(parm, maxparm)

                                                                                                                                                              This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                                                                                                                                              %cstring_output_withsize(char *data, int *maxdata);
                                                                                                                                                              ...
                                                                                                                                                              void get_data(char *data, int *maxdata);
                                                                                                                                                              

                                                                                                                                                              In the target language:

                                                                                                                                                              >>> get_data(1024)
                                                                                                                                                              'x627388912'
                                                                                                                                                              >>> get_data(1024)
                                                                                                                                                              'xyzzy'
                                                                                                                                                              >>>
                                                                                                                                                              

                                                                                                                                                              This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                                                                                                                                              %cstring_output_allocate(parm, release)

                                                                                                                                                              This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                                                                                                                                              void foo(char **s) {
                                                                                                                                                                  *s = (char *) malloc(64);
                                                                                                                                                                  sprintf(*s, "Hello world\n");
                                                                                                                                                              }
                                                                                                                                                              

                                                                                                                                                              The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                                                                              %cstring_output_allocate(char **s, free(*$1));
                                                                                                                                                              ...
                                                                                                                                                              void foo(char **s);
                                                                                                                                                              

                                                                                                                                                              In the target language:

                                                                                                                                                              >>> foo()
                                                                                                                                                              'Hello world\n'
                                                                                                                                                              >>>
                                                                                                                                                              

                                                                                                                                                              %cstring_output_allocate_size(parm, szparm, release)

                                                                                                                                                              This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                                                                                                                                              void foo(char **s, int *sz) {
                                                                                                                                                                  *s = (char *) malloc(64);
                                                                                                                                                                  *sz = 64;
                                                                                                                                                                  // Write some binary data
                                                                                                                                                                  ...
                                                                                                                                                              }
                                                                                                                                                              

                                                                                                                                                              The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                                                                              %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                                                                                                                                              ...
                                                                                                                                                              void foo(char **s, int *slen);
                                                                                                                                                              

                                                                                                                                                              In the target language:

                                                                                                                                                              >>> foo()
                                                                                                                                                              '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                                                                                                                                              >>>
                                                                                                                                                              

                                                                                                                                                              This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                                                                                                                                              char  *get_data(int *len);
                                                                                                                                                              

                                                                                                                                                              You could wrap it with a function like this:

                                                                                                                                                              void my_get_data(char **result, int *len) {
                                                                                                                                                                 *result = get_data(len);
                                                                                                                                                              }
                                                                                                                                                              

                                                                                                                                                              Comments:
                                                                                                                                                              • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                                                                                                                                              • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                                                                                                                                              • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                                                                                                                                              • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                                                                                                                                              8.4 C++ Library

                                                                                                                                                              The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                                                                                                                                              8.4.1 std_string.i

                                                                                                                                                              The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                                                                                                                                              %module example
                                                                                                                                                              %include "std_string.i"
                                                                                                                                                              
                                                                                                                                                              std::string foo();
                                                                                                                                                              void        bar(const std::string &x);
                                                                                                                                                              

                                                                                                                                                              In the target language:

                                                                                                                                                              x = foo();                # Returns a string object
                                                                                                                                                              bar("Hello World");       # Pass string as std::string
                                                                                                                                                              

                                                                                                                                                              This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                                                                                                                                              This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                                                                                                                                              %module example
                                                                                                                                                              %include "std_string.i"
                                                                                                                                                              
                                                                                                                                                              using namespace std;
                                                                                                                                                              typedef std::string String;
                                                                                                                                                              ...
                                                                                                                                                              void foo(string s, const String &t);     // std_string typemaps still applied
                                                                                                                                                              

                                                                                                                                                              Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                                                                                                                                              8.4.2 std_vector.i

                                                                                                                                                              The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                                                                                                                                              %module example
                                                                                                                                                              %include "std_vector.i"
                                                                                                                                                              
                                                                                                                                                              namespace std {
                                                                                                                                                                 %template(vectori) vector<int>;
                                                                                                                                                                 %template(vectord) vector<double>;
                                                                                                                                                              };
                                                                                                                                                              

                                                                                                                                                              When a template vector<X> is instantiated a number of things happen:
                                                                                                                                                              • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                                                                                                                                              • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                                                                                                                                              • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                                                                                                                                              • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                                                                                                                                              • An exception handler for std::out_of_range is defined.
                                                                                                                                                              • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                                                                                                                                              To illustrate the use of this library, consider the following functions:

                                                                                                                                                              /* File : example.h */
                                                                                                                                                              
                                                                                                                                                              #include <vector>
                                                                                                                                                              #include <algorithm>
                                                                                                                                                              #include <functional>
                                                                                                                                                              #include <numeric>
                                                                                                                                                              
                                                                                                                                                              double average(std::vector<int> v) {
                                                                                                                                                                  return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                                                                                                                                              }
                                                                                                                                                              
                                                                                                                                                              std::vector<double> half(const std::vector<double>& v) {
                                                                                                                                                                  std::vector<double> w(v);
                                                                                                                                                                  for (unsigned int i=0; i<w.size(); i++)
                                                                                                                                                                      w[i] /= 2.0;
                                                                                                                                                                  return w;
                                                                                                                                                              }
                                                                                                                                                              
                                                                                                                                                              void halve_in_place(std::vector<double>& v) {
                                                                                                                                                                  std::transform(v.begin(),v.end(),v.begin(),
                                                                                                                                                                                 std::bind2nd(std::divides<double>(),2.0));
                                                                                                                                                              }
                                                                                                                                                              

                                                                                                                                                              To wrap with SWIG, you might write the following:

                                                                                                                                                              %module example
                                                                                                                                                              %{
                                                                                                                                                              #include "example.h"
                                                                                                                                                              %}
                                                                                                                                                              
                                                                                                                                                              %include "std_vector.i"
                                                                                                                                                              // Instantiate templates used by example
                                                                                                                                                              namespace std {
                                                                                                                                                                 %template(IntVector) vector<int>;
                                                                                                                                                                 %template(DoubleVector) vector<double>;
                                                                                                                                                              }
                                                                                                                                                              
                                                                                                                                                              // Include the header file with above prototypes
                                                                                                                                                              %include "example.h"
                                                                                                                                                              

                                                                                                                                                              Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                                                                                                                                              >>> from example import *
                                                                                                                                                              >>> iv = IntVector(4)         # Create an vector<int>
                                                                                                                                                              >>> for i in range(0,4):
                                                                                                                                                              ...      iv[i] = i
                                                                                                                                                              >>> average(iv)               # Call method
                                                                                                                                                              1.5
                                                                                                                                                              >>> average([0,1,2,3])        # Call with list
                                                                                                                                                              1.5
                                                                                                                                                              >>> half([1,2,3])             # Half a list
                                                                                                                                                              (0.5,1.0,1.5)
                                                                                                                                                              >>> halve_in_place([1,2,3])   # Oops
                                                                                                                                                              Traceback (most recent call last):
                                                                                                                                                                File "<stdin>", line 1, in ?
                                                                                                                                                              TypeError: Type error. Expected _p_std__vectorTdouble_t
                                                                                                                                                              >>> dv = DoubleVector(4)
                                                                                                                                                              >>> for i in range(0,4):
                                                                                                                                                              ...       dv[i] = i
                                                                                                                                                              >>> halve_in_place(dv)       # Ok
                                                                                                                                                              >>> for i in dv:
                                                                                                                                                              ...       print i
                                                                                                                                                              ...
                                                                                                                                                              0.0
                                                                                                                                                              0.5
                                                                                                                                                              1.0
                                                                                                                                                              1.5
                                                                                                                                                              >>> dv[20] = 4.5
                                                                                                                                                              Traceback (most recent call last):
                                                                                                                                                                File "<stdin>", line 1, in ?
                                                                                                                                                                File "example.py", line 81, in __setitem__
                                                                                                                                                                  def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                                                                                                                                              IndexError: vector index out of range
                                                                                                                                                              >>>
                                                                                                                                                              

                                                                                                                                                              This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                                                                                                                                              %include "std_vector.i"
                                                                                                                                                              
                                                                                                                                                              namespace std {
                                                                                                                                                                  %template(IntVector) vector<int>;
                                                                                                                                                              }
                                                                                                                                                              
                                                                                                                                                              using namespace std;
                                                                                                                                                              typedef std::vector Vector;
                                                                                                                                                              
                                                                                                                                                              void foo(vector<int> *x, const Vector &x);
                                                                                                                                                              

                                                                                                                                                              Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                                                                                                                                              Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                                                                                                                                              Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                                                                                                                                              8.5 Utility Libraries

                                                                                                                                                              8.5.1 exception.i

                                                                                                                                                              The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                                                                                                                                              SWIG_exception(int code, const char *message)

                                                                                                                                                              Raises an exception in the target language. code is one of the following symbolic constants:

                                                                                                                                                              SWIG_MemoryError
                                                                                                                                                              SWIG_IOError
                                                                                                                                                              SWIG_RuntimeError
                                                                                                                                                              SWIG_IndexError
                                                                                                                                                              SWIG_TypeError
                                                                                                                                                              SWIG_DivisionByZero
                                                                                                                                                              SWIG_OverflowError
                                                                                                                                                              SWIG_SyntaxError
                                                                                                                                                              SWIG_ValueError
                                                                                                                                                              SWIG_SystemError
                                                                                                                                                              

                                                                                                                                                              message is a string indicating more information about the problem.

                                                                                                                                                              The primary use of this module is in writing language-independent exception handlers. For example:

                                                                                                                                                              %include "exception.i"
                                                                                                                                                              %exception std::vector::getitem {
                                                                                                                                                                  try {
                                                                                                                                                                      $action
                                                                                                                                                                  } catch (std::out_of_range& e) {
                                                                                                                                                                      SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                                                                                                                                  }
                                                                                                                                                              }
                                                                                                                                                              

                                                                                                                                                              ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                                                                                                                                              

                                                                                                                                                              SWIG-1.3 Documentation

                                                                                                                                                              
                                                                                                                                                              

                                                                                                                                                              ---

                                                                                                                                                              Table of Contents

                                                                                                                                                              
                                                                                                                                                              
                                                                                                                                                              SWIG-1.3 Development Documentation
                                                                                                                                                              • Sections
                                                                                                                                                              • SWIG Core Documentation
                                                                                                                                                              • Language Module Documentation
                                                                                                                                                              • Developer Documentation
                                                                                                                                                              • Documentation that has not yet been updated
                                                                                                                                                              1 Preface
                                                                                                                                                              • 1.1 Introduction
                                                                                                                                                              • 1.2 Special Introduction for Version 1.3
                                                                                                                                                              • 1.3 SWIG Versions
                                                                                                                                                              • 1.4 SWIG resources
                                                                                                                                                              • 1.5 Prerequisites
                                                                                                                                                              • 1.6 Organization of this manual
                                                                                                                                                              • 1.7 How to avoid reading the manual
                                                                                                                                                              • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                                                                                                                                                >>> make_upper("hello world")
                                                                                                                                                                'HELLO WORLD'
                                                                                                                                                                >>> attach_header("Hello world")
                                                                                                                                                                'header: Hello world'
                                                                                                                                                                >>>
                                                                                                                                                                

                                                                                                                                                                This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                                                                                                                                                %cstring_output_maxsize(parm, maxparm)

                                                                                                                                                                This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                                                                                                                                                %cstring_output_maxsize(char *path, int maxpath);
                                                                                                                                                                ...
                                                                                                                                                                void get_path(char *path, int maxpath);
                                                                                                                                                                

                                                                                                                                                                In the target language:

                                                                                                                                                                >>> get_path(1024)
                                                                                                                                                                '/home/beazley/Packages/Foo/Bar'
                                                                                                                                                                >>>
                                                                                                                                                                

                                                                                                                                                                This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                                                                                                                                                %cstring_output_withsize(parm, maxparm)

                                                                                                                                                                This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                                                                                                                                                %cstring_output_withsize(char *data, int *maxdata);
                                                                                                                                                                ...
                                                                                                                                                                void get_data(char *data, int *maxdata);
                                                                                                                                                                

                                                                                                                                                                In the target language:

                                                                                                                                                                >>> get_data(1024)
                                                                                                                                                                'x627388912'
                                                                                                                                                                >>> get_data(1024)
                                                                                                                                                                'xyzzy'
                                                                                                                                                                >>>
                                                                                                                                                                

                                                                                                                                                                This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                                                                                                                                                %cstring_output_allocate(parm, release)

                                                                                                                                                                This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                                                                                                                                                void foo(char **s) {
                                                                                                                                                                    *s = (char *) malloc(64);
                                                                                                                                                                    sprintf(*s, "Hello world\n");
                                                                                                                                                                }
                                                                                                                                                                

                                                                                                                                                                The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                                                                                %cstring_output_allocate(char **s, free(*$1));
                                                                                                                                                                ...
                                                                                                                                                                void foo(char **s);
                                                                                                                                                                

                                                                                                                                                                In the target language:

                                                                                                                                                                >>> foo()
                                                                                                                                                                'Hello world\n'
                                                                                                                                                                >>>
                                                                                                                                                                

                                                                                                                                                                %cstring_output_allocate_size(parm, szparm, release)

                                                                                                                                                                This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                                                                                                                                                void foo(char **s, int *sz) {
                                                                                                                                                                    *s = (char *) malloc(64);
                                                                                                                                                                    *sz = 64;
                                                                                                                                                                    // Write some binary data
                                                                                                                                                                    ...
                                                                                                                                                                }
                                                                                                                                                                

                                                                                                                                                                The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                                                                                %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                                                                                                                                                ...
                                                                                                                                                                void foo(char **s, int *slen);
                                                                                                                                                                

                                                                                                                                                                In the target language:

                                                                                                                                                                >>> foo()
                                                                                                                                                                '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                                                                                                                                                >>>
                                                                                                                                                                

                                                                                                                                                                This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                                                                                                                                                char  *get_data(int *len);
                                                                                                                                                                

                                                                                                                                                                You could wrap it with a function like this:

                                                                                                                                                                void my_get_data(char **result, int *len) {
                                                                                                                                                                   *result = get_data(len);
                                                                                                                                                                }
                                                                                                                                                                

                                                                                                                                                                Comments:
                                                                                                                                                                • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                                                                                                                                                • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                                                                                                                                                • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                                                                                                                                                • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                                                                                                                                                8.4 C++ Library

                                                                                                                                                                The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                                                                                                                                                8.4.1 std_string.i

                                                                                                                                                                The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                                                                                                                                                %module example
                                                                                                                                                                %include "std_string.i"
                                                                                                                                                                
                                                                                                                                                                std::string foo();
                                                                                                                                                                void        bar(const std::string &x);
                                                                                                                                                                

                                                                                                                                                                In the target language:

                                                                                                                                                                x = foo();                # Returns a string object
                                                                                                                                                                bar("Hello World");       # Pass string as std::string
                                                                                                                                                                

                                                                                                                                                                This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                                                                                                                                                This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                                                                                                                                                %module example
                                                                                                                                                                %include "std_string.i"
                                                                                                                                                                
                                                                                                                                                                using namespace std;
                                                                                                                                                                typedef std::string String;
                                                                                                                                                                ...
                                                                                                                                                                void foo(string s, const String &t);     // std_string typemaps still applied
                                                                                                                                                                

                                                                                                                                                                Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                                                                                                                                                8.4.2 std_vector.i

                                                                                                                                                                The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                                                                                                                                                %module example
                                                                                                                                                                %include "std_vector.i"
                                                                                                                                                                
                                                                                                                                                                namespace std {
                                                                                                                                                                   %template(vectori) vector<int>;
                                                                                                                                                                   %template(vectord) vector<double>;
                                                                                                                                                                };
                                                                                                                                                                

                                                                                                                                                                When a template vector<X> is instantiated a number of things happen:
                                                                                                                                                                • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                                                                                                                                                • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                                                                                                                                                • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                                                                                                                                                • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                                                                                                                                                • An exception handler for std::out_of_range is defined.
                                                                                                                                                                • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                                                                                                                                                To illustrate the use of this library, consider the following functions:

                                                                                                                                                                /* File : example.h */
                                                                                                                                                                
                                                                                                                                                                #include <vector>
                                                                                                                                                                #include <algorithm>
                                                                                                                                                                #include <functional>
                                                                                                                                                                #include <numeric>
                                                                                                                                                                
                                                                                                                                                                double average(std::vector<int> v) {
                                                                                                                                                                    return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                                                                                                                                                }
                                                                                                                                                                
                                                                                                                                                                std::vector<double> half(const std::vector<double>& v) {
                                                                                                                                                                    std::vector<double> w(v);
                                                                                                                                                                    for (unsigned int i=0; i<w.size(); i++)
                                                                                                                                                                        w[i] /= 2.0;
                                                                                                                                                                    return w;
                                                                                                                                                                }
                                                                                                                                                                
                                                                                                                                                                void halve_in_place(std::vector<double>& v) {
                                                                                                                                                                    std::transform(v.begin(),v.end(),v.begin(),
                                                                                                                                                                                   std::bind2nd(std::divides<double>(),2.0));
                                                                                                                                                                }
                                                                                                                                                                

                                                                                                                                                                To wrap with SWIG, you might write the following:

                                                                                                                                                                %module example
                                                                                                                                                                %{
                                                                                                                                                                #include "example.h"
                                                                                                                                                                %}
                                                                                                                                                                
                                                                                                                                                                %include "std_vector.i"
                                                                                                                                                                // Instantiate templates used by example
                                                                                                                                                                namespace std {
                                                                                                                                                                   %template(IntVector) vector<int>;
                                                                                                                                                                   %template(DoubleVector) vector<double>;
                                                                                                                                                                }
                                                                                                                                                                
                                                                                                                                                                // Include the header file with above prototypes
                                                                                                                                                                %include "example.h"
                                                                                                                                                                

                                                                                                                                                                Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                                                                                                                                                >>> from example import *
                                                                                                                                                                >>> iv = IntVector(4)         # Create an vector<int>
                                                                                                                                                                >>> for i in range(0,4):
                                                                                                                                                                ...      iv[i] = i
                                                                                                                                                                >>> average(iv)               # Call method
                                                                                                                                                                1.5
                                                                                                                                                                >>> average([0,1,2,3])        # Call with list
                                                                                                                                                                1.5
                                                                                                                                                                >>> half([1,2,3])             # Half a list
                                                                                                                                                                (0.5,1.0,1.5)
                                                                                                                                                                >>> halve_in_place([1,2,3])   # Oops
                                                                                                                                                                Traceback (most recent call last):
                                                                                                                                                                  File "<stdin>", line 1, in ?
                                                                                                                                                                TypeError: Type error. Expected _p_std__vectorTdouble_t
                                                                                                                                                                >>> dv = DoubleVector(4)
                                                                                                                                                                >>> for i in range(0,4):
                                                                                                                                                                ...       dv[i] = i
                                                                                                                                                                >>> halve_in_place(dv)       # Ok
                                                                                                                                                                >>> for i in dv:
                                                                                                                                                                ...       print i
                                                                                                                                                                ...
                                                                                                                                                                0.0
                                                                                                                                                                0.5
                                                                                                                                                                1.0
                                                                                                                                                                1.5
                                                                                                                                                                >>> dv[20] = 4.5
                                                                                                                                                                Traceback (most recent call last):
                                                                                                                                                                  File "<stdin>", line 1, in ?
                                                                                                                                                                  File "example.py", line 81, in __setitem__
                                                                                                                                                                    def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                                                                                                                                                IndexError: vector index out of range
                                                                                                                                                                >>>
                                                                                                                                                                

                                                                                                                                                                This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                                                                                                                                                %include "std_vector.i"
                                                                                                                                                                
                                                                                                                                                                namespace std {
                                                                                                                                                                    %template(IntVector) vector<int>;
                                                                                                                                                                }
                                                                                                                                                                
                                                                                                                                                                using namespace std;
                                                                                                                                                                typedef std::vector Vector;
                                                                                                                                                                
                                                                                                                                                                void foo(vector<int> *x, const Vector &x);
                                                                                                                                                                

                                                                                                                                                                Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                                                                                                                                                Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                                                                                                                                                Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                                                                                                                                                8.5 Utility Libraries

                                                                                                                                                                8.5.1 exception.i

                                                                                                                                                                The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                                                                                                                                                SWIG_exception(int code, const char *message)

                                                                                                                                                                Raises an exception in the target language. code is one of the following symbolic constants:

                                                                                                                                                                SWIG_MemoryError
                                                                                                                                                                SWIG_IOError
                                                                                                                                                                SWIG_RuntimeError
                                                                                                                                                                SWIG_IndexError
                                                                                                                                                                SWIG_TypeError
                                                                                                                                                                SWIG_DivisionByZero
                                                                                                                                                                SWIG_OverflowError
                                                                                                                                                                SWIG_SyntaxError
                                                                                                                                                                SWIG_ValueError
                                                                                                                                                                SWIG_SystemError
                                                                                                                                                                

                                                                                                                                                                message is a string indicating more information about the problem.

                                                                                                                                                                The primary use of this module is in writing language-independent exception handlers. For example:

                                                                                                                                                                %include "exception.i"
                                                                                                                                                                %exception std::vector::getitem {
                                                                                                                                                                    try {
                                                                                                                                                                        $action
                                                                                                                                                                    } catch (std::out_of_range& e) {
                                                                                                                                                                        SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                                                                                                                                    }
                                                                                                                                                                }
                                                                                                                                                                

                                                                                                                                                                ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                                                                                                                                                

                                                                                                                                                                SWIG-1.3 Documentation

                                                                                                                                                                
                                                                                                                                                                

                                                                                                                                                                ---

                                                                                                                                                                Table of Contents

                                                                                                                                                                
                                                                                                                                                                
                                                                                                                                                                SWIG-1.3 Development Documentation
                                                                                                                                                                • Sections
                                                                                                                                                                • SWIG Core Documentation
                                                                                                                                                                • Language Module Documentation
                                                                                                                                                                • Developer Documentation
                                                                                                                                                                • Documentation that has not yet been updated
                                                                                                                                                                1 Preface
                                                                                                                                                                • 1.1 Introduction
                                                                                                                                                                • 1.2 Special Introduction for Version 1.3
                                                                                                                                                                • 1.3 SWIG Versions
                                                                                                                                                                • 1.4 SWIG resources
                                                                                                                                                                • 1.5 Prerequisites
                                                                                                                                                                • 1.6 Organization of this manual
                                                                                                                                                                • 1.7 How to avoid reading the manual
                                                                                                                                                                • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                                                                                                                                                  >>> make_upper("hello world")
                                                                                                                                                                  'HELLO WORLD'
                                                                                                                                                                  >>> attach_header("Hello world")
                                                                                                                                                                  'header: Hello world'
                                                                                                                                                                  >>>
                                                                                                                                                                  

                                                                                                                                                                  This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                                                                                                                                                  %cstring_output_maxsize(parm, maxparm)

                                                                                                                                                                  This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                                                                                                                                                  %cstring_output_maxsize(char *path, int maxpath);
                                                                                                                                                                  ...
                                                                                                                                                                  void get_path(char *path, int maxpath);
                                                                                                                                                                  

                                                                                                                                                                  In the target language:

                                                                                                                                                                  >>> get_path(1024)
                                                                                                                                                                  '/home/beazley/Packages/Foo/Bar'
                                                                                                                                                                  >>>
                                                                                                                                                                  

                                                                                                                                                                  This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                                                                                                                                                  %cstring_output_withsize(parm, maxparm)

                                                                                                                                                                  This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                                                                                                                                                  %cstring_output_withsize(char *data, int *maxdata);
                                                                                                                                                                  ...
                                                                                                                                                                  void get_data(char *data, int *maxdata);
                                                                                                                                                                  

                                                                                                                                                                  In the target language:

                                                                                                                                                                  >>> get_data(1024)
                                                                                                                                                                  'x627388912'
                                                                                                                                                                  >>> get_data(1024)
                                                                                                                                                                  'xyzzy'
                                                                                                                                                                  >>>
                                                                                                                                                                  

                                                                                                                                                                  This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                                                                                                                                                  %cstring_output_allocate(parm, release)

                                                                                                                                                                  This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                                                                                                                                                  void foo(char **s) {
                                                                                                                                                                      *s = (char *) malloc(64);
                                                                                                                                                                      sprintf(*s, "Hello world\n");
                                                                                                                                                                  }
                                                                                                                                                                  

                                                                                                                                                                  The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                                                                                  %cstring_output_allocate(char **s, free(*$1));
                                                                                                                                                                  ...
                                                                                                                                                                  void foo(char **s);
                                                                                                                                                                  

                                                                                                                                                                  In the target language:

                                                                                                                                                                  >>> foo()
                                                                                                                                                                  'Hello world\n'
                                                                                                                                                                  >>>
                                                                                                                                                                  

                                                                                                                                                                  %cstring_output_allocate_size(parm, szparm, release)

                                                                                                                                                                  This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                                                                                                                                                  void foo(char **s, int *sz) {
                                                                                                                                                                      *s = (char *) malloc(64);
                                                                                                                                                                      *sz = 64;
                                                                                                                                                                      // Write some binary data
                                                                                                                                                                      ...
                                                                                                                                                                  }
                                                                                                                                                                  

                                                                                                                                                                  The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                                                                                  %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                                                                                                                                                  ...
                                                                                                                                                                  void foo(char **s, int *slen);
                                                                                                                                                                  

                                                                                                                                                                  In the target language:

                                                                                                                                                                  >>> foo()
                                                                                                                                                                  '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                                                                                                                                                  >>>
                                                                                                                                                                  

                                                                                                                                                                  This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                                                                                                                                                  char  *get_data(int *len);
                                                                                                                                                                  

                                                                                                                                                                  You could wrap it with a function like this:

                                                                                                                                                                  void my_get_data(char **result, int *len) {
                                                                                                                                                                     *result = get_data(len);
                                                                                                                                                                  }
                                                                                                                                                                  

                                                                                                                                                                  Comments:
                                                                                                                                                                  • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                                                                                                                                                  • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                                                                                                                                                  • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                                                                                                                                                  • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                                                                                                                                                  8.4 C++ Library

                                                                                                                                                                  The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                                                                                                                                                  8.4.1 std_string.i

                                                                                                                                                                  The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                                                                                                                                                  %module example
                                                                                                                                                                  %include "std_string.i"
                                                                                                                                                                  
                                                                                                                                                                  std::string foo();
                                                                                                                                                                  void        bar(const std::string &x);
                                                                                                                                                                  

                                                                                                                                                                  In the target language:

                                                                                                                                                                  x = foo();                # Returns a string object
                                                                                                                                                                  bar("Hello World");       # Pass string as std::string
                                                                                                                                                                  

                                                                                                                                                                  This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                                                                                                                                                  This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                                                                                                                                                  %module example
                                                                                                                                                                  %include "std_string.i"
                                                                                                                                                                  
                                                                                                                                                                  using namespace std;
                                                                                                                                                                  typedef std::string String;
                                                                                                                                                                  ...
                                                                                                                                                                  void foo(string s, const String &t);     // std_string typemaps still applied
                                                                                                                                                                  

                                                                                                                                                                  Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                                                                                                                                                  8.4.2 std_vector.i

                                                                                                                                                                  The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                                                                                                                                                  %module example
                                                                                                                                                                  %include "std_vector.i"
                                                                                                                                                                  
                                                                                                                                                                  namespace std {
                                                                                                                                                                     %template(vectori) vector<int>;
                                                                                                                                                                     %template(vectord) vector<double>;
                                                                                                                                                                  };
                                                                                                                                                                  

                                                                                                                                                                  When a template vector<X> is instantiated a number of things happen:
                                                                                                                                                                  • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                                                                                                                                                  • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                                                                                                                                                  • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                                                                                                                                                  • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                                                                                                                                                  • An exception handler for std::out_of_range is defined.
                                                                                                                                                                  • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                                                                                                                                                  To illustrate the use of this library, consider the following functions:

                                                                                                                                                                  /* File : example.h */
                                                                                                                                                                  
                                                                                                                                                                  #include <vector>
                                                                                                                                                                  #include <algorithm>
                                                                                                                                                                  #include <functional>
                                                                                                                                                                  #include <numeric>
                                                                                                                                                                  
                                                                                                                                                                  double average(std::vector<int> v) {
                                                                                                                                                                      return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                                                                                                                                                  }
                                                                                                                                                                  
                                                                                                                                                                  std::vector<double> half(const std::vector<double>& v) {
                                                                                                                                                                      std::vector<double> w(v);
                                                                                                                                                                      for (unsigned int i=0; i<w.size(); i++)
                                                                                                                                                                          w[i] /= 2.0;
                                                                                                                                                                      return w;
                                                                                                                                                                  }
                                                                                                                                                                  
                                                                                                                                                                  void halve_in_place(std::vector<double>& v) {
                                                                                                                                                                      std::transform(v.begin(),v.end(),v.begin(),
                                                                                                                                                                                     std::bind2nd(std::divides<double>(),2.0));
                                                                                                                                                                  }
                                                                                                                                                                  

                                                                                                                                                                  To wrap with SWIG, you might write the following:

                                                                                                                                                                  %module example
                                                                                                                                                                  %{
                                                                                                                                                                  #include "example.h"
                                                                                                                                                                  %}
                                                                                                                                                                  
                                                                                                                                                                  %include "std_vector.i"
                                                                                                                                                                  // Instantiate templates used by example
                                                                                                                                                                  namespace std {
                                                                                                                                                                     %template(IntVector) vector<int>;
                                                                                                                                                                     %template(DoubleVector) vector<double>;
                                                                                                                                                                  }
                                                                                                                                                                  
                                                                                                                                                                  // Include the header file with above prototypes
                                                                                                                                                                  %include "example.h"
                                                                                                                                                                  

                                                                                                                                                                  Now, to illustrate the behavior in the scripting interpreter, consider this Python example:

                                                                                                                                                                  >>> from example import *
                                                                                                                                                                  >>> iv = IntVector(4)         # Create an vector<int>
                                                                                                                                                                  >>> for i in range(0,4):
                                                                                                                                                                  ...      iv[i] = i
                                                                                                                                                                  >>> average(iv)               # Call method
                                                                                                                                                                  1.5
                                                                                                                                                                  >>> average([0,1,2,3])        # Call with list
                                                                                                                                                                  1.5
                                                                                                                                                                  >>> half([1,2,3])             # Half a list
                                                                                                                                                                  (0.5,1.0,1.5)
                                                                                                                                                                  >>> halve_in_place([1,2,3])   # Oops
                                                                                                                                                                  Traceback (most recent call last):
                                                                                                                                                                    File "<stdin>", line 1, in ?
                                                                                                                                                                  TypeError: Type error. Expected _p_std__vectorTdouble_t
                                                                                                                                                                  >>> dv = DoubleVector(4)
                                                                                                                                                                  >>> for i in range(0,4):
                                                                                                                                                                  ...       dv[i] = i
                                                                                                                                                                  >>> halve_in_place(dv)       # Ok
                                                                                                                                                                  >>> for i in dv:
                                                                                                                                                                  ...       print i
                                                                                                                                                                  ...
                                                                                                                                                                  0.0
                                                                                                                                                                  0.5
                                                                                                                                                                  1.0
                                                                                                                                                                  1.5
                                                                                                                                                                  >>> dv[20] = 4.5
                                                                                                                                                                  Traceback (most recent call last):
                                                                                                                                                                    File "<stdin>", line 1, in ?
                                                                                                                                                                    File "example.py", line 81, in __setitem__
                                                                                                                                                                      def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
                                                                                                                                                                  IndexError: vector index out of range
                                                                                                                                                                  >>>
                                                                                                                                                                  

                                                                                                                                                                  This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:

                                                                                                                                                                  %include "std_vector.i"
                                                                                                                                                                  
                                                                                                                                                                  namespace std {
                                                                                                                                                                      %template(IntVector) vector<int>;
                                                                                                                                                                  }
                                                                                                                                                                  
                                                                                                                                                                  using namespace std;
                                                                                                                                                                  typedef std::vector Vector;
                                                                                                                                                                  
                                                                                                                                                                  void foo(vector<int> *x, const Vector &x);
                                                                                                                                                                  

                                                                                                                                                                  Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

                                                                                                                                                                  Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

                                                                                                                                                                  Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

                                                                                                                                                                  8.5 Utility Libraries

                                                                                                                                                                  8.5.1 exception.i

                                                                                                                                                                  The exception.i library provides a language-independent function for raising a run-time exception in the target language.

                                                                                                                                                                  SWIG_exception(int code, const char *message)

                                                                                                                                                                  Raises an exception in the target language. code is one of the following symbolic constants:

                                                                                                                                                                  SWIG_MemoryError
                                                                                                                                                                  SWIG_IOError
                                                                                                                                                                  SWIG_RuntimeError
                                                                                                                                                                  SWIG_IndexError
                                                                                                                                                                  SWIG_TypeError
                                                                                                                                                                  SWIG_DivisionByZero
                                                                                                                                                                  SWIG_OverflowError
                                                                                                                                                                  SWIG_SyntaxError
                                                                                                                                                                  SWIG_ValueError
                                                                                                                                                                  SWIG_SystemError
                                                                                                                                                                  

                                                                                                                                                                  message is a string indicating more information about the problem.

                                                                                                                                                                  The primary use of this module is in writing language-independent exception handlers. For example:

                                                                                                                                                                  %include "exception.i"
                                                                                                                                                                  %exception std::vector::getitem {
                                                                                                                                                                      try {
                                                                                                                                                                          $action
                                                                                                                                                                      } catch (std::out_of_range& e) {
                                                                                                                                                                          SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
                                                                                                                                                                      }
                                                                                                                                                                  }
                                                                                                                                                                  

                                                                                                                                                                  ./usr/share/doc/swig-doc/Manual/chapters0000644000000000000000000000057010202752305020314 0ustar rootroot00000000000000Preface.html Introduction.html Windows.html Scripting.html SWIG.html SWIGPlus.html Preprocessor.html Library.html Arguments.html Typemaps.html Customization.html Contract.html Varargs.html Warnings.html Modules.html CSharp.html Chicken.html Guile.html Java.html Modula3.html Mzscheme.html Ocaml.html Perl5.html Php.html Pike.html Python.html Ruby.html Tcl.html Extending.html ./usr/share/doc/swig-doc/Manual/SWIGDocumentation.html0000644000000000000000000506635710202752305022775 0ustar rootroot00000000000000
                                                                                                                                                                  

                                                                                                                                                                  SWIG-1.3 Documentation

                                                                                                                                                                  
                                                                                                                                                                  

                                                                                                                                                                  ---

                                                                                                                                                                  Table of Contents

                                                                                                                                                                  
                                                                                                                                                                  
                                                                                                                                                                  SWIG-1.3 Development Documentation
                                                                                                                                                                  • Sections
                                                                                                                                                                  • SWIG Core Documentation
                                                                                                                                                                  • Language Module Documentation
                                                                                                                                                                  • Developer Documentation
                                                                                                                                                                  • Documentation that has not yet been updated
                                                                                                                                                                  1 Preface
                                                                                                                                                                  • 1.1 Introduction
                                                                                                                                                                  • 1.2 Special Introduction for Version 1.3
                                                                                                                                                                  • 1.3 SWIG Versions
                                                                                                                                                                  • 1.4 SWIG resources
                                                                                                                                                                  • 1.5 Prerequisites
                                                                                                                                                                  • 1.6 Organization of this manual
                                                                                                                                                                  • 1.7 How to avoid reading the manual
                                                                                                                                                                  • 1.8 Backwards Coattach_header(char *hstr); In the target language:

                                                                                                                                                                    >>> make_upper("hello world")
                                                                                                                                                                    'HELLO WORLD'
                                                                                                                                                                    >>> attach_header("Hello world")
                                                                                                                                                                    'header: Hello world'
                                                                                                                                                                    >>>
                                                                                                                                                                    

                                                                                                                                                                    This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

                                                                                                                                                                    %cstring_output_maxsize(parm, maxparm)

                                                                                                                                                                    This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

                                                                                                                                                                    %cstring_output_maxsize(char *path, int maxpath);
                                                                                                                                                                    ...
                                                                                                                                                                    void get_path(char *path, int maxpath);
                                                                                                                                                                    

                                                                                                                                                                    In the target language:

                                                                                                                                                                    >>> get_path(1024)
                                                                                                                                                                    '/home/beazley/Packages/Foo/Bar'
                                                                                                                                                                    >>>
                                                                                                                                                                    

                                                                                                                                                                    This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

                                                                                                                                                                    %cstring_output_withsize(parm, maxparm)

                                                                                                                                                                    This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

                                                                                                                                                                    %cstring_output_withsize(char *data, int *maxdata);
                                                                                                                                                                    ...
                                                                                                                                                                    void get_data(char *data, int *maxdata);
                                                                                                                                                                    

                                                                                                                                                                    In the target language:

                                                                                                                                                                    >>> get_data(1024)
                                                                                                                                                                    'x627388912'
                                                                                                                                                                    >>> get_data(1024)
                                                                                                                                                                    'xyzzy'
                                                                                                                                                                    >>>
                                                                                                                                                                    

                                                                                                                                                                    This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

                                                                                                                                                                    %cstring_output_allocate(parm, release)

                                                                                                                                                                    This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

                                                                                                                                                                    void foo(char **s) {
                                                                                                                                                                        *s = (char *) malloc(64);
                                                                                                                                                                        sprintf(*s, "Hello world\n");
                                                                                                                                                                    }
                                                                                                                                                                    

                                                                                                                                                                    The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                                                                                    %cstring_output_allocate(char **s, free(*$1));
                                                                                                                                                                    ...
                                                                                                                                                                    void foo(char **s);
                                                                                                                                                                    

                                                                                                                                                                    In the target language:

                                                                                                                                                                    >>> foo()
                                                                                                                                                                    'Hello world\n'
                                                                                                                                                                    >>>
                                                                                                                                                                    

                                                                                                                                                                    %cstring_output_allocate_size(parm, szparm, release)

                                                                                                                                                                    This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

                                                                                                                                                                    void foo(char **s, int *sz) {
                                                                                                                                                                        *s = (char *) malloc(64);
                                                                                                                                                                        *sz = 64;
                                                                                                                                                                        // Write some binary data
                                                                                                                                                                        ...
                                                                                                                                                                    }
                                                                                                                                                                    

                                                                                                                                                                    The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

                                                                                                                                                                    %cstring_output_allocate_size(char **s, int *slen, free(*$1));
                                                                                                                                                                    ...
                                                                                                                                                                    void foo(char **s, int *slen);
                                                                                                                                                                    

                                                                                                                                                                    In the target language:

                                                                                                                                                                    >>> foo()
                                                                                                                                                                    '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
                                                                                                                                                                    >>>
                                                                                                                                                                    

                                                                                                                                                                    This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

                                                                                                                                                                    char  *get_data(int *len);
                                                                                                                                                                    

                                                                                                                                                                    You could wrap it with a function like this:

                                                                                                                                                                    void my_get_data(char **result, int *len) {
                                                                                                                                                                       *result = get_data(len);
                                                                                                                                                                    }
                                                                                                                                                                    

                                                                                                                                                                    Comments:
                                                                                                                                                                    • Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
                                                                                                                                                                    • Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
                                                                                                                                                                    • If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
                                                                                                                                                                    • Rather than manipulating char * directly, you might consider using a special string structure or class instead.

                                                                                                                                                                    8.4 C++ Library

                                                                                                                                                                    The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL.

                                                                                                                                                                    8.4.1 std_string.i

                                                                                                                                                                    The std_string.i library provides typemaps for converting C++ std::string objects to and from strings in the target scripting language. For example:

                                                                                                                                                                    %module example
                                                                                                                                                                    %include "std_string.i"
                                                                                                                                                                    
                                                                                                                                                                    std::string foo();
                                                                                                                                                                    void        bar(const std::string &x);
                                                                                                                                                                    

                                                                                                                                                                    In the target language:

                                                                                                                                                                    x = foo();                # Returns a string object
                                                                                                                                                                    bar("Hello World");       # Pass string as std::string
                                                                                                                                                                    

                                                                                                                                                                    This module only supports types std::string and const std::string &. Pointers and non-const references are left unmodified and returned as SWIG pointers.

                                                                                                                                                                    This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

                                                                                                                                                                    %module example
                                                                                                                                                                    %include "std_string.i"
                                                                                                                                                                    
                                                                                                                                                                    using namespace std;
                                                                                                                                                                    typedef std::string String;
                                                                                                                                                                    ...
                                                                                                                                                                    void foo(string s, const String &t);     // std_string typemaps still applied
                                                                                                                                                                    

                                                                                                                                                                    Note: The std_string library is incompatible with Perl on some platforms. We're looking into it.

                                                                                                                                                                    8.4.2 std_vector.i

                                                                                                                                                                    The std_vector.i library provides support for the C++ vector class in the STL. Using this library involves the use of the %template directive. All you need to do is to instantiate different versions of vector for the types that you want to use. For example:

                                                                                                                                                                    %module example
                                                                                                                                                                    %include "std_vector.i"
                                                                                                                                                                    
                                                                                                                                                                    namespace std {
                                                                                                                                                                       %template(vectori) vector<int>;
                                                                                                                                                                       %template(vectord) vector<double>;
                                                                                                                                                                    };
                                                                                                                                                                    

                                                                                                                                                                    When a template vector<X> is instantiated a number of things happen:
                                                                                                                                                                    • A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
                                                                                                                                                                    • Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
                                                                                                                                                                    • An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
                                                                                                                                                                    • For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
                                                                                                                                                                    • An exception handler for std::out_of_range is defined.
                                                                                                                                                                    • Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.
                                                                                                                                                                    To illustrate the use of this library, consider the following functions:

                                                                                                                                                                    /* File : example.h */
                                                                                                                                                                    
                                                                                                                                                                    #include <vector>
                                                                                                                                                                    #include <algorithm>
                                                                                                                                                                    #include <functional>
                                                                                                                                                                    #include <numeric>
                                                                                                                                                                    
                                                                                                                                                                    double average(std::vector<int> v) {
                                                                                                                                                                        return std::accumulate(v.begin(),v.end(),0.0)/v.size();
                                                                                                                                                                    }
                                                                                                                                                                    
                                                                                                                                                                    std::vector<double> half(const std::vector<double>& v) {
                                                                                                                                                                        std::vector<double> w(v);
                                                                                                                                                                        for (unsigned int i=0; i<w.size(); i++)
                                                                                                                                                                            w[i] /= 2.0;
                                                                                                                                                                        return w;
                                                                                                                                                                    }
                                                                                                                                                                    
                                                                                                                                                                    void halve_in_place(std::vector<double>& v) {
                                                                                                                                                                        std::transform(v.begin(),v.end(),v.begin(),
                                                                                                                                                                                       std::bind2nd(std::divides<double>(),2.0));
                                                                                                                                                                    }
                                                                                                                                                                    

                                                                                                                                                                    To wrap with SWIG, you might write the following:

                                                                                                                                                                    %module example
                                                                                                                                                                    %{
                                                                                                                                                                    #include "example.h"
                                                                                                                                                                    %}
                                                                                                                                                                    
                                                                                                                                                                    %include "std_vector.i"
                                                                                                                                                                    // Instantiate templates used by example
                                                                                                                                                                    namespace std {
                                                                                                                                                                       %template(IntVector) ve