From c2dc8d3c30e56e4d137cdc4fbae0eb2fbebf9b3a Mon Sep 17 00:00:00 2001 From: William S Fulton Date: Wed, 27 Jul 2005 20:28:54 +0000 Subject: [PATCH] use exception specification instead of %exception to handle STL error checking git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk/SWIG@7353 626c5289-ae23-0410-ae9c-e8d60b6d4f22 --- Doc/Manual/Library.html | 90 ++++++++++++++++++++++++++++++++++++++--- 1 file changed, 84 insertions(+), 6 deletions(-) diff --git a/Doc/Manual/Library.html b/Doc/Manual/Library.html index ab98b48bf..9742c160e 100644 --- a/Doc/Manual/Library.html +++ b/Doc/Manual/Library.html @@ -25,7 +25,7 @@
  • Using %newobject to release memory
  • cstring.i -
  • C++ Library +
  • STL/C++ Library -

    8.4 C++ Library

    +

    8.4 STL/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. +The library modules in this section provide access to parts of the standard C++ library including the STL. +SWIG support for the STL is an ongoing effort. Support is quite comprehensive for some language modules +but some of the lesser used modules do not have quite as much library code written.

    +

    +The following table shows which C++ classes are supported and the equivalent SWIG interface library file for the C++ library. +

    + + + + + + + + + + + + + + + + +
    C++ classC++ Library fileSWIG Interface library file
    std::deque deque std_deque.i
    std::list list std_list.i
    std::map map std_map.i
    std::pair utility std_pair.i
    std::set set std_set.i
    std::string string std_string.i
    std::vector vector std_vector.i
    + +

    +The list is by no means complete; some language modules support a subset of the above and some support additional STL classes. +Please look for the library files in the appropriate language library directory. +

    + +

    8.4.1 std_string.i

    @@ -1596,6 +1623,55 @@ details and the public API exposed to the interpreter vary.

    +

    STL exceptions

    +

    +Many of the STL wrapper functions add parameter checking and will throw a language dependent error/exception +should the values not be valid. The classic example is array bounds checking. +The library wrappers are written to throw a C++ exception in the case of error. +The C++ exception in turn gets converted into an appropriate error/exception for the target language. +By and large this handling should not need customising, however, customisation can easily be achieved by supplying appropriate "throws" typemaps. +For example: +

    + +
    +
    +%module example
+%include "std_vector.i"
+%typemap(throws) std::out_of_range {
+  // custom exception handler
+}
+%template(VectInt) std::vector;
+
    +
    + +

    +The custom exception handler might, for example, log the exception then convert it into a specific error/exception for the target language. +

    + +

    +When using the STL it is advisable to add in an exception handler to catch all STL exceptions. +The %exception directive can be used by placing the following code before any other methods or libraries to be wrapped: +

    + +
    +
    +%include "exception.i"
+
+%exception {
+  try {
+    $action
+  } catch (const std::exception& e) {
+    SWIG_exception(SWIG_RuntimeError, e.what());
+  }
+}
+
    +
    + +

    +Any thrown STL exceptions will then be gracefully handled instead of causing a crash. +

    + +

    8.5 Utility Libraries

    @@ -1604,7 +1680,9 @@ details and the public API exposed to the interpreter vary.

    The exception.i library provides a language-independent function for raising a run-time -exception in the target language. +exception in the target language. This library is largely used by the SWIG library writers. +If possible, use the error handling scheme available to your target language as there is greater +flexibility in what errors/exceptions can be thrown.