path: root/CHANGES.current

Unreleased changes
==================

11/02/2005: mmatus

	    [Python]
	    - add 'iterator()' method for all sequences and additionally
	      'key_iterator()' for maps.

	      'iterator()' will always return the native C++ iterator.
	      Additionally, in maps, 'key_iterator()' will return a python
	      iterator using only the map keys.
	      
	      In general the sequence method __iter__ will call
	      'iterator()', returning the native C++ iterator, but in
	      maps it will call 'key_iterator()', maintaining
	      backcompatibilty.

	      Hence, for std::maps, you can play then with the native
	      C++ iterator, which value is a (key, value) pair, by
	      calling map.iterator(), as with map.begin(), map.end(), etc.

	      The difference is that map.iterator() returns a safe
	      'close' iterator, while map.begin() and map.end() are
	      'open' iterators.

	      A 'close' iterator knows the begin and the end of the
	      sequence, and it never can seg. fault. A 'open'
	      iterator, as in C++, can seg. fault at the C++ side.

	         # a close iterator is safe in the following example.
		 # the next() method will throw a StopIteration
	         # exception as needed
	
	         i = seq.iterator()
		 try:
                      while True:
		        sum += i.next()
		 except: pass
		 
		 # an open iterator always need to be checked,
		 # or it will crash at the C++ side

	         current = seq.begin()
                 end = seq.end()
		 while (current != end):
		    sum += current.next()
	      
	      
	    [Python]
	    - Finally, when we call 

	        f = Foo()

	      the construction is 'one-way'. Before construction  was done
	      something like

	          Foo() (python) -> _new_Foo() (C++) 
                  new_Foo() (C++) -> FooPtr() (python) 
                  FooPtr() (python) -> Foo() (python)

              and returning a pointer was done like

                  NewPointerObj() (C++) -> FooPtr() (python)
                  FooPtr(python) -> Foo() (python)
                  		  

	      ie, we when going back and forward between the C++ and
	      python side.

	      Now since there is no FooPtr the construction process is

	          Foo() (python) -> _new_Foo() (C++)
                  _new_Foo() (C++) -> NewPointerObj() (C++) (no shadow class)

              and returning a pointer is done

                  NewPointerObj() (C++) (with shadow class) -> NewInstaceObj() (C++)

	      where NewInstanceObj creates a new instance without
	      calling __init__ and it doesn't go 'back' to python, is
	      'pure' C API.

	     - With this change, and the other ones in the
               PySwigObject type, which now carries the thisown and
               swig_type_info pointer, the generated code shoudl be as
               fast as boost::Python and/or the other python wrappers
               based in pure Python/C API calls.

	       As a reference, the profiletest_runme.py example, which
	       does a simple call function many times:

                    import profiletest       
		                             
		    a = profiletest.A()      
		    b = profiletest.B()      
		    for i in range(0,1000000)
	              a = b.fn(a)            


	       where fn is defined as 'A* B::fn(A *a) {return a;}',
	       produces  the following times

                               nomodern    modern
	         swig-1.3.26    25.9s       7.6s
                 swig-CVS        3.4s       3.3s
	       

	       Clearly, there is a large improvement for the python
	       'nomodern' mode. Still, the 'modern' mode is around
	       twice faster than before.

	       
		  	      
10/31/2005: mmatus
	    [Python]

	    - Finally, no more ClassPtr shadow classes. You will see
	      only a clean Class shadow class in the .py file.

	    - No more thisown attribute either, the PySwigObject now
              carries the ownership info.

	      You can also do something like

	          print self.this.own() 
		  >>> True
		  
		  self.this.disown()
	          print self.this.own() 
		  >>> False		  

		  self.this.acquire()
	          print self.this.own() 
		  >>> True		  

	    - Support for iterartors in STL/STD containers, for example, if you have

                    %template<set_string> std::set<std::string>;
	          
               you can use the C++ iterators as:  

                     s = set_string()
		                     
		     s.append("c")   
		     s.append("a")   
	             s.append("b")

                     b = s.begin()      
		     e = s.end()        
		     sum = ""           
		     while (b != e):    
                         sum += b.next()        
                     print sum

                     >>> "abc" 

		advance the iterator as in C++

                     current = s.begin()      
		     current += 1
                     print current.value()
		     >>> "b"
		     
		now using the reverse operators

                     b = s.rbegin()      
		     e = s.rend()        
		     sum = ""           
		     while (b != e):    
                         sum += b.next()        
                     print sum

                     >>> "cba" 

	        or the 'previous' method

                     b = s.begin()      
		     e = s.end()        
		     sum = ""           
		     while (b != e):    
                         sum += e.previous()
                     print sum

                     >>> "cba" 

                or just as in a python fashion

                     for i in s:
                         sum += i        
                           
                Note 1: Iterators in C++ are very powerful, but
                dangerous too. And in python you can shoot your foot
                as well as in C++, so, be careful.
		
		Note 2: the iterators are 'light', ie, they do not
		convert sequence elements until you request so, via
		next(), value() or previous(). If you just increment/decrement one
		no conversion is performed, for example:

                      
                     b = s.begin()      
	             b += 1
                     b.incr()
                     b.incr(2)
		     b.decr(2)
                     b.decr()
                     b -= 1

		 only the iterator is modified, and not value wrapper
		 is generated. Other typical C++ operations are also 
		 available, such as:

		     print s.end() - s.begin()
		     >>> 3
		     f = s.begin() + 1
		     print f.value()
		     >>> "b"
		     l = s.end() - 1
		     print l.value()
		     >>> "c"
		 
		 etc.  Of course, the 'find', 'insert', 'erase', and
		 so on methods also supports iterators now, ie:

		      i = s.begin()
		      i += 1
		      s.erase(i)
                      for i in s:
                         sum += i
		      print sum
		      >>> "ac"
		      
            *** POTENTIAL INCOMPATIBILITY ***

	    There is no more 'thisown' attribute. If you use it, you
	    need to change as follows:

                if (self.thisown):   ==>   if (self.this.own()):
		self.thisown = 1     ==>   self.this.acquire()
                self.thisown = 0     ==>   self.this.disown()

            if you really really like the old 'thisown' attribute, you
	    can submit a patch to treat it as a property, and dispatch
	    the new method calls. Of course, before you try, it needs
	    to work with old and new python versions, and with classic
	    and modern python classes.
	    
	    

10/30/2005: mkoeppe 
	    [Guile] Make declared and defined linkage of SWIG_init consistent.  
	    Reported by Steven G. Johnson (SF patch 1315498).

10/26/2005: mmatus

	  - Added the attribute.i file to the global library director.
	    Now it can be used from other languages that do not use
	    the unified typemap library as well.

	    So, if you have something like:

	       %include attribute.i

               %attribute(A, int, a, get_a, set_a);
	       				      	  
	       struct A			      	  
	       {    				  
	         int get_a() const; 		  
	         void set_a(int aa); 		  
	       };				  

               %attribute_ref(B, int, c);
	       				
	       struct B			
	       {    			
	         int& c(); 		
	       }; 

	    then in the target language the 'A.a' and 'B.c' attributes will
	    be visible, ie, you can access them as plain variables:

               f   = A()
               f.a = 3
               g   = B()
               g.c = 3 
           
	       h   = f.a + g.c

	    and the proper get/set methods will be dispatched. See
	    attribute.i for more info.
   
          - More cleanups around and adding more test-cases. The
            DISOWN typemap now is tested and working in all the
            languages that use the unified typemap library, ie, tcl,
            ruby, perl and python.
	    

10/25/2005: mmatus

	    - Perl, complete the DISOWN typemap.
	    
	    - added the attribute.i file to the unified typemap
              library (before was only usable from python).

	    - uniform the names for the setter and getter methods in
	      perl,tcl,ruby and python, so, the attribute.i library
	      can work accross them.
	      
	    - see the li_attribute.i test-case or the library file

 	        Lib/typemaps/attribute.swg

              for more info about how to use it.

 
	      

10/24/2005: mmatus

	    - Perl uses now the unified typemap libray.

	    - Changes in ruby to use the $track option in typemaps.

	    - Changes in the unified typemap library to follow the
	      convention that all macros that are not used in the
	      C/C++ side starts with %, such as

	           %delete
		   %new_array

              etc.
	      
	    - Documenting fragments, see fragments.swg.

	    - Cleaner way to use the unified typemap library, include
	      just <typemaps/swigtypes.swg>.

	      Check some of the supported languages: perl, tcl, ruby,
	      python.

	      Always start with the head file, such as

	         python/python.swg
	         tcl/tcl8.swg
	         ruby/ruby.swg
	         perl5/perl5.swg

              and the principal file that invokes the unified library, such as

	         python/pytypemaps.swg	    
	         tcl/tcltypemaps.swg	    
	         ruby/rubytypemaps.swg	    
	         perl/perltypemaps.swg	    
	    
	      The file that provide the specialization for each
	      language are the one that provides the basic types:

	         python/pyprimtypes.swg	
	         ruby/rubyprimtypes.swg	
	         tcl/tclprimtypes.swg	
	         perl5/perlprimtypes.swg

	      and the string manipulation:  	 
	    
	         python/pystrings.swg	
	         ruby/rubystrings.swg	
	         tcl/tclstrings.swg	
	         perl5/perlstrings.swg

		 
	      The rest fo the files, such as carray.i, are mostly one 
	      line files that include the proper typemap library
	      version.

10/23/2005: wuzzeb
            Chicken:
              + pointers to member functions finally work properly
              + add test of member function pointers to cpp_basic.i

10/20/2005: mmatus
	    Ruby, Tcl, Python:

	    - Uniform way to fail (label fail:), now finally
	      SWIG_exception works across the three languages and all
	      the typemaps.

	    - Add proper cleanup code to ruby

	    - More valgrind fixes

	    - Simplify the inline use, it seems a small interface of
	      20,000 lines (plus many many templates0 can break 
	      gcc -O3 easily.

	    - Finalize the typemaps library. All the old  *.i files
	      (carray.i, cpointer.i, exception.i) had been implemented
	      in the new typemaps library.
	    

10/19/2005: wuzzeb
	    Update the Runtime Typemap documentation in Typemaps.html

10/18/2005: wuzzeb
	    Chicken:
	      - Correctly handle %ignored classes
              - Correctly convert long, long long, unsigned long, etc
                to chicken primitives. (Thanks to Felix Winkelmann)
              - Using argout parameters when the return value was a
                wrapped pointer caused a memory corruption.  The chicken
                garbage collector moved a pointer out from under us.
                This is now fixed by running all the proxy creation
                functions as continuations after the wrapper function
                returns.  As part of this, we no longer need the
                chickenfastproxy flag on output typemaps.
              - using -proxy and -nocollection together works now
                Before, it was not exporting the destructor in the proxy
                wrapper.

10/18/2005: mmatus
	    
	    Unifying the typemaps for

 	        python, ruby, tcl

	    and in the process, fix several problems in three
	    languages to work in the "canonical" way now stablished in
	    the typemap library
	    
	       SWIG/Lib/typempas

	    The current status of the unification is that everything
	    compiles and runs inside the test-suite and examples
	    directories. And for the first type we have three
	    languages than pass the primitive_types.i case.

	    Also, we have uniform way to treat the errors, for example
	    if you do something like

	      >>> from primitive_types import *
              >>> print val_uchar(10)
              10
	      >>> print val_uchar(1000)
              Traceback (most recent call last):		      
	        File "<stdin>", line 1, in ?			    
	      OverflowError: in argument 1 of type 'unsigned char'

	    you get the same exception in all the three languages.
	    
	    And well, many more good things will come from this
	    unification, as proper support of the STL/STD classes
	    for all the languages, and hopefully, we can keep
	    adding other languages.

	    The hardest part, writting a common typemap library
	    that suites the three different languages, is done,
	    and adding another language it is easy now. 

	    Still the global unification is not complete, the STL/STD 
	    part is next, and probably adding one or two more
	    languages.

	    If you are curious, look at the python, ruby and/or tcl
	    directories to see what is needed to support the new
	    common typemaps library.  Still, the final way to
	    integrate a new language could change as we move to
	    integrate the STD/STL.

            *** POTENTIAL INCOMPATIBILITY ***

	    Some missing typemaps could start working, and change
	    the old expected behavior, specially in ruby and tcl.