-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++ class | +C++ Library file | +SWIG 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. +
+ ++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. +
+ +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.