Checkin swig binaries for win, linux and Mac...

swig/Lib/typemaps/fragments.swg

+/*
+  Fragments:
+  ==========
+
+  Second to typemaps, fragments are one the most powerful and
+  dangerous swig features. So, if you are starting to read about them,
+  make sure you read all of this document.
+
+  Basics:
+  =======
+
+  Fragments provide a way to include or generate code into "on-demand"
+  as the typemaps could require.
+
+  For example, if you have a very long typemap
+
+  %typemap(in) MyClass * {
+    MyClass *value = 0;
+
+    <very long typemap>
+    ....
+    value = somewhere_converted_from_input_object_here($input);
+    ...
+    <very long typemap>
+  
+    $result = value;
+  }
+
+  very soon you will discover yourself copying the same long
+  conversion code in several typemaps, such as varin, directorout,
+  etc. Also, you will discover that swig copes verbatim the same very
+  long conversion code for every argument that requires it, making the
+  code very large too.
+
+  To eliminate this automatic or manual code copying, we define a
+  fragment that includes the common conversion code:
+
+  %fragment("AsMyClass","header") {
+     MyClass *AsMyClass(PyObject *obj) {
+        MyClass *value = 0;
+        <very long conversion>
+        ....
+        value = somewhere_converted_from_input_object_here(obj);
+        ...
+        <very long conversion>
+  
+        return value;
+     }
+  }
+
+  %typemap(in,fragment="AsMyClass") MyClass * {
+    $result = AsMyClass($input);
+  }
+
+  %typemap(varin,fragment="AsMyClass") MyClass * {
+    $result = AsMyClass($input);
+  }
+
+  When the 'in' or 'varin' typemaps for MyClass are invoked, the
+  fragment "AsMyClass" is added to the "header" section, and then the
+  typemap code is emitted. Hence, the method AsMyClass will be
+  included in the wrapping code and it will be available at the time
+  the typemap is applied.
+
+  To define a fragment then you need a name, a section where it goes,
+  and the code. Usually the section refers to the "header" part, and
+  both string and braces forms are accepted, ie:
+
+    %fragment("my_name","header") { ... }
+    %fragment("my_name","header") "...";
+
+  To ensure all the fragment/typemap engine works as expected, there
+  are some rules that fragments follow:
+
+  1.- A fragment is added to the wrapping code only once, ie, for the
+      method:
+      
+        int foo(MyClass *a, MyClass *b);
+
+     the wrapped code will look as much as:
+
+      MyClass *AsMyClass(PyObject *obj) {
+        .....
+      }
+      
+      int _wrap_foo(...) {
+        ....
+        arg1 = AsMyClass(obj1);
+        arg2 = AsMyClass(obj2);
+        ...
+        result = foo(arg1, arg2);
+      }
+
+
+     even when there will be duplicated typemap to process 'a' and
+     'b', the 'AsMyClass' method will be defined only once.
+
+     
+  2.- A fragment can only defined once, and the first definition
+      is the only one taking in account. All other definitions of the
+      same fragments are silently ignored. For example, you can have
+
+
+        %fragment("AsMyClass","header") { <definition 1> }
+        ....
+        %fragment("AsMyClass","header") { <definition 2> }
+     
+      and then only the first definition is considered. In this way
+      you can change the 'system' fragments by including yours first.
+
+      Note that this behavior is opposite to the typemaps, where the
+      last typemap applied or defined prevails. Fragment follows the
+      first-in-first-out convention since they are intended to be
+      "global", while typemaps intend to be "locally" specialized.
+      
+  3.- Fragments names can not contain commas.
+        
+
+  A fragment can include one or more additional fragments, for example:
+
+    %fragment("<limits.h>", "header")  {
+      #include <limits.h>
+    }
+
+
+    %fragment("AsMyClass", "header", fragment="<limits.h>") {
+      MyClass *AsMyClass(PyObject *obj) {
+        MyClass *value = 0;
+        int ival = somewhere_converted_from_input_object_here(obj)
+        ...
+        if  (ival < CHAR_MIN) {
+           value = something_from_ival(ival);
+        } else {
+        ...
+        }
+        ...
+        return value;
+      }
+    }
+
+  in this case, when the "AsMyClass" fragment is emitted, it also
+  trigger the inclusion of the "<limits.h>" fragment.
+
+  You can add as many fragments as you want, for example
+
+    %fragment("bigfragment","header", fragment="frag1", fragment="frag2", fragment="frag3") "";
+
+  here, when the "bigfragment" is included, the three fragments "frag1",
+  "frag2" and "frag3" are included. Note that as "bigframent" is defined
+  empty, "", it does not add any code by itself, buy only trigger the
+  inclusion of the other fragments.
+  
+  In a typemap you can also include more than one fragment, but since the
+  syntax is different, you need to specify them in a 'comma separated'
+  list, for example, considering the previous example:
+ 
+     %typemap(in,fragment="frag1,frag2,frag3") {...}
+
+  is equivalent to
+
+     %typemap(in,fragment="bigfragment") {...}
+
+  
+  Finally, you can force the inclusion of a fragment at any moment as follow:
+
+     %fragment("bigfragment");
+
+  which is very useful inside a template class, for example. 
+
+
+  Fragment type specialization
+  ============================
+  
+  Fragments can be "type specialized". The syntax is as follows
+                                                                           
+    %fragment("name","header") { a type independent fragment }
+    %fragment("name" {Type}, "header") { a type dependent fragment  }
+                                                                           
+  and they can also, as typemaps, be used inside templates, for exampe:
+                                                                           
+     template <class T>                                               
+     struct A {                                                       
+        %fragment("incode"{A<T>},"header") {                                  
+          'incode' specialized fragment 
+        }                                                                   
+                                                                           
+        %typemap(in,fragment="incode"{A<T>}) {                      
+           here we use the 'type specialized'                       
+           fragment "incode"{A<T>}                                    
+        }
+     };                                                               
+  
+   which could seems a not much interesting feature, but is
+   fundamental for automatic typemap and template specialization.
+
+
+  Fragments and automatic typemap specialization:
+  ===============================================
+
+  Since fragments can be type specialized, they can be elegantly used
+  to specialized typemaps .
+
+  For example, if you have something like:
+
+    %fragment("incode"{float}, "header") {
+      float in_method_float(PyObject *obj) {
+        ...
+      }
+    }
+
+    %fragment("incode"{long}, "header") {
+      float in_method_long(PyObject *obj) {
+        ...
+      }
+    }
+    
+    %define %my_typemaps(Type) 
+    %typemaps(in,fragment="incode"{Type}) {
+      value = in_method_##Type(obj);
+    }
+    %enddef
+
+    %my_typemaps(float);
+    %my_typemaps(long);
+
+  then the proper "incode"{float,double} fragment will be included,
+  and the proper in_method_{float,double} will be called.
+
+  Since this is a recurrent fragment use, we provide a couple of
+  macros that make the automatic generation of typemaps easier:
+
+
+  Consider for example the following code:
+
+      %fragment(SWIG_From_frag(bool),"header") {     
+      static PyObject*                
+      SWIG_From_dec(bool)(bool value)          
+      {                                        
+        PyObject *obj = value ? Py_True : Py_False;  
+        Py_INCREF(obj);                        
+        return obj;                                    
+      }                                        
+      }                                        
+                                         
+      %typemap(out,fragment=SWIG_From_frag(bool)) bool {
+        $result = SWIG_From(bool)($1));
+      }
+
+  Here the macros
+
+      SWIG_From_frag  => fragment 
+      SWIG_From_dec   => declaration 
+      SWIG_From       => call 
+      
+  allow you to define/include a fragment, and declare and call the
+  'from-bool' method as needed. In the simpler case, these macros 
+  just return something like
+
+      SWIG_From_frag(bool)  => "SWIG_From_bool"
+      SWIG_From_dec(bool)   =>  SWIG_From_bool
+      SWIG_From(bool)       =>  SWIG_From_bool
+
+  But they are specialized for the different languages requirements,
+  such as perl or tcl that requires passing the interpreter pointer,
+  and also they can manage C++ ugly types, for example:
+  
+      SWIG_From_frag(std::complex<double>)  => "SWIG_From_std_complex_Sl_double_Sg_"
+      SWIG_From_dec(std::complex<double>)   =>  SWIG_From_std_complex_Sl_double_Sg_
+      SWIG_From(std::complex<double>)       =>  SWIG_From_std_complex_Sl_double_Sg_
+
+
+  Hence, to declare methods to use with typemaps, always use the
+  SWIG_From* macros. In the same way, the SWIG_AsVal* and SWIG_AsPtr*
+  set of macros are provided.
+    
+*/
+
+
+/* -----------------------------------------------------------------------------
+ * Define the basic macros to 'normalize' the type fragments
+ * ----------------------------------------------------------------------------- */
+
+#ifndef SWIG_AS_DECL_ARGS
+#define SWIG_AS_DECL_ARGS
+#endif
+
+#ifndef SWIG_FROM_DECL_ARGS
+#define SWIG_FROM_DECL_ARGS
+#endif
+
+#ifndef SWIG_AS_CALL_ARGS
+#define SWIG_AS_CALL_ARGS
+#endif
+
+#ifndef SWIG_FROM_CALL_ARGS
+#define SWIG_FROM_CALL_ARGS
+#endif
+
+#define %fragment_name(Name, Type...)     %string_name(Name) "_" {Type}
+
+#define SWIG_Traits_frag(Type...) %fragment_name(Traits, Type) 
+#define SWIG_AsPtr_frag(Type...)  %fragment_name(AsPtr, Type)    
+#define SWIG_AsVal_frag(Type...)  %fragment_name(AsVal, Type)    
+#define SWIG_From_frag(Type...)   %fragment_name(From, Type)     
+
+#define SWIG_AsVal_name(Type...)  %symbol_name(AsVal, Type) 
+#define SWIG_AsPtr_name(Type...)  %symbol_name(AsPtr, Type) 
+#define SWIG_From_name(Type...)   %symbol_name(From, Type)  
+
+#define SWIG_AsVal_dec(Type...)   SWIG_AsVal_name(Type) SWIG_AS_DECL_ARGS
+#define SWIG_AsPtr_dec(Type...)   SWIG_AsPtr_name(Type) SWIG_AS_DECL_ARGS
+#define SWIG_From_dec(Type...)    SWIG_From_name(Type)  SWIG_FROM_DECL_ARGS 
+
+#define SWIG_AsVal(Type...)       SWIG_AsVal_name(Type) SWIG_AS_CALL_ARGS 
+#define SWIG_AsPtr(Type...)       SWIG_AsPtr_name(Type) SWIG_AS_CALL_ARGS        
+#define SWIG_From(Type...)        SWIG_From_name(Type)  SWIG_FROM_CALL_ARGS 
+
+/* ------------------------------------------------------------
+ * common fragments 
+ * ------------------------------------------------------------ */
+
+/* Default compiler options for gcc allow long_long but not LLONG_MAX. 
+ * Define SWIG_NO_LLONG_MAX if this added limits support is not wanted. */
+%fragment("<limits.h>","header") %{
+#include <limits.h>
+#if !defined(SWIG_NO_LLONG_MAX)
+# if !defined(LLONG_MAX) && defined(__GNUC__) && defined (__LONG_LONG_MAX__)
+#   define LLONG_MAX __LONG_LONG_MAX__
+#   define LLONG_MIN (-LLONG_MAX - 1LL)
+#   define ULLONG_MAX (LLONG_MAX * 2ULL + 1ULL)
+# endif
+#endif
+%}
+
+%fragment("<math.h>","header") %{
+#include <math.h>
+%}
+
+%fragment("<wchar.h>","header") %{
+#include <wchar.h>
+#include <limits.h>
+#ifndef WCHAR_MIN
+#  define WCHAR_MIN 0
+#endif
+#ifndef WCHAR_MAX
+#  define WCHAR_MAX 65535
+#endif
+%}
+
+%fragment("<float.h>","header") %{
+#include <float.h>
+%}
+
+%fragment("<stdio.h>","header") %{
+#include <stdio.h>
+#if defined(_MSC_VER) || defined(__BORLANDC__) || defined(_WATCOM)
+# ifndef snprintf
+#  define snprintf _snprintf
+# endif
+#endif
+%}
+
+%fragment("<stdlib.h>","header") %{
+#include <stdlib.h>
+#ifdef _MSC_VER
+# ifndef strtoull
+#  define strtoull _strtoui64
+# endif
+# ifndef strtoll
+#  define strtoll _strtoi64
+# endif
+#endif
+%}
+
+/* -----------------------------------------------------------------------------
+ * special macros for fragments
+ * ----------------------------------------------------------------------------- */
+
+/* Macros to derive numeric types */
+
+%define %numeric_type_from(Type, Base)
+%fragment(SWIG_From_frag(Type),"header",
+          fragment=SWIG_From_frag(Base)) {
+SWIGINTERNINLINE SWIG_Object
+SWIG_From_dec(Type)(Type value)
+{    
+  return SWIG_From(Base)(value);
+}
+}
+%enddef
+
+%define %numeric_type_asval(Type, Base, Frag, OverflowCond)
+%fragment(SWIG_AsVal_frag(Type),"header",
+          fragment=Frag,
+          fragment=SWIG_AsVal_frag(Base)) {
+SWIGINTERN int
+SWIG_AsVal_dec(Type)(SWIG_Object obj, Type *val)
+{
+  Base v;
+  int res = SWIG_AsVal(Base)(obj, &v);
+  if (SWIG_IsOK(res)) {
+    if (OverflowCond) {
+      return SWIG_OverflowError;
+    } else {
+      if (val) *val = %numeric_cast(v, Type);
+    }
+  }  
+  return res;
+}
+}
+%enddef
+
+#define %numeric_signed_type_asval(Type, Base, Frag, Min, Max) \
+%numeric_type_asval(Type, Base, Frag, (v < Min || v > Max))
+
+#define %numeric_unsigned_type_asval(Type, Base, Frag, Max) \
+%numeric_type_asval(Type, Base, Frag, (v > Max))
+
+
+/* Macro for 'signed long' derived types */
+
+%define %numeric_slong(Type, Frag, Min, Max)
+%numeric_type_from(Type, long)
+%numeric_signed_type_asval(Type, long, Frag , Min, Max)
+%enddef
+
+/* Macro for 'unsigned long' derived types */
+
+%define %numeric_ulong(Type, Frag, Max)
+%numeric_type_from(Type, unsigned long)
+%numeric_unsigned_type_asval(Type, unsigned long, Frag, Max)
+%enddef
+
+
+/* Macro for 'double' derived types */
+
+%define %numeric_double(Type, Frag, Min, Max)
+%numeric_type_from(Type, double)
+%numeric_signed_type_asval(Type, double, Frag , Min, Max)
+%enddef
+
+
+/* Macros for missing fragments */
+
+%define %ensure_fragment(Fragment)
+%fragment(`Fragment`,"header") {
+%#error "Swig language implementation must provide the Fragment fragment"
+}
+%enddef
+
+%define %ensure_type_fragments(Type)
+%fragment(SWIG_From_frag(Type),"header") {
+%#error "Swig language implementation must provide a SWIG_From_frag(Type) fragment"
+}
+%fragment(SWIG_AsVal_frag(Type),"header") {
+%#error "Swig language implementation must provide a SWIG_AsVal_frag(Type) fragment"
+}
+%enddef