===================================================
   Whats new in Castor 1.1 (August 15th 2010)
===================================================


New features:
-------------
- Class Coroutine and macros co_begin, co_end, co_return & co_yield that support coroutine style programming.
  Helpful when defining relations imperatively. See section 3.2 in tutorial.

- New relations: 
  + eq_mem() - for unifying with (non static) data members.
  + eval() and eval_mf() - To execute a function or member function. Return value (if any) is discarded.
  + item_map() - To lookup & enumerate keys/values in associative containers where key and value are not the 
    same (e.g. std::map, std::multimap).
  + item_set() - To lookup & enumerate of objects in associative containers where key and value is the 
    same(e.g. std::set, std::multiset).
  + pause() - To pause execution. Prints a message and waits for a key press by calling cin.ignore(). Helpful 
    as a debugging aid.
  + pause_f() - Similar to pause(), but prints result of a function call instead of a string message.
  + permutation(), permutation_cmp() -  To generate permutations of a sequnce/string.
  + range_dec() - To iterate over a range in decreasing order.
  + ritem() -  To lookup & enumerate values from a sequence in reverse. The sequence must provide rbegin() 
    and rend().
  + rbegin(), rend() - To test & generate reverse iterators for a reversible container.
  + shuffle() - To generate a randomized sequence/string.
  + unique_mem(), unique_mf() - Similar to unique() but filtering is based on a data member or value returned 
    by a method call.
  + writeAll(), writeAllTo() - To print all elements in a sequence to cout or to a stream.
  + write_mem(), writeTo_mem() - To print value of a data member to cout or a stream.
  + zip() - Takes two relations as argument and evaluates them in an interleaved manner until one of them fails.

  + Aggregation Relations - For aggregaring values from a container into a scalar value.
       - max_of(), min_of(), average_of() - To compute the max, min and average value in a container.
       - sum_of() - Total of all values in a container. (Same as reduce_of with std::plus as functor)
       - reduce_of() - For reducing a container into a value using a binary functor.
       - size_of() - For computing the number of items in a container.
        E.g. lref<vector<int> > vi = .. ; 
             sum_of(vi, s);

- New "TakeLeft Relations" (TLRs) for use on the right side of operator >>= . TLRs can only be used in generate mode.
   + TLRs for Aggregation - 
       - max(), min(), average() - Compute the max, min and average of a sequence of values.
       - sum() - Sum of values in a sequence (same as reduce with std::plus as functor).
       - reduce() - Reduce a sequence to a value by applying an operator (similar to std::accumulate).
             E.g.:  range(j,1,10) >>= reduce(j, std::multiplies<int>()); // factorial of 10
       - count() - Count the number of successful evaluations of another relation.
             E.g. range(i,1,10) && predicate(i%2==0) >>= count(n);  // n is the number of evens in range (1,10)
       -  Aggregation TLRs are similar in spirit to their conterpart aggregation relations, but applicable when 
          values are generated by another relation.

   + order() - For producing a sorted sequence of objects.
   + order_mem() - For producing a sorted sequence of objects. Sort objects on a data member.
   + order_mf() - For producing a sorted sequence of objects. Sort based on value method call.
   + reverse() - For reversing a sequence of objects. E.g. range(i,1,10) >>= reverse(i)
   + skip() - Skips the first few solutions generated by another relation.
   + group_by() - For grouping objects based on some criteria. Allows nested grouping. e.g.
        E.g.: 
        // Group strings by first char & then by length
        
        char firstChar(const string& s) { return s[0]; };
        size_t str_len(const string& s) { return s.size(); };
        
        lref<vector<string> > names = .. ;
        lref<string> n;

        lref<group<char,group<size_t,string> > > g;

        relation r = item(n,names) >>= group_by(n, &firstChar, g).then(&str_len);

        while(r()) {
           cout << "\n" << g->key;
           lref<group<size_t,string> > g2;
           relation subgroups = item(g2,g);
           while(subgroups()) {
                cout << "\n   " << g2->key << " : ";
                wirteAll(g2)();
           }
        }


Enhancements to ILE (closure/lambda facility):
----------------------------------------------
- New named ILEs have been provided:
    + at : Allows indexed access. Equivalent to the operator [].
          E.g.  lref<string> str=..; cout << at(str,0)();
    + call : To invoke a function/function object with upto 6 arguments.
          E.g.  eq_f(x, call(&foo,1,2,3) ); eq_f(3, call(plus<int,int>(),1,2) )
    + create : To instantiate an object.    Supercedes Create::with().
          E.g.  create<int>(1); create<pair<int,int> >(1,2);  create<string,const char*>("castor");
    + get : To access a data member of an object.
          E.g.  lref<pair<int,int> > pr .. ; write_f( get(pr,&pair:;first) )
    + id  : References an object. Referenced object's lifetime must extend beyond the life of this ILE.
          E.g.  lref<string> s="";
                (eval(id(cin) >> s) && eval( id(cout) << s ))();  // cin >> *s ; cout << *s;
    + mcall : To invoke member functions with upto 6 arguments.
          E.g.  lref<string> str= "hello" ;  predicate( mcall(str, &string::at,0)=='h' )

- ILE expressions now support use of "string literals".
    E.g. - lref<string> ls="castor"; predicate(ls=="castor");
         - eval(id(cout) << "hello" << " world" )();  // cout << "hello" << " world";
         - stringstream strm; 
           eval(id<ostream>(strm) << "hello")();      // return type of operator << is ostream& and not stringstream&
         - string s;
           eval(id<istream>(strm)) >> id(s))();       // return type of operator >> is istream& and not stringstream&

- Speed improvements for ILE expressions. Closer to the speed of custom function objects.



Enhancements to lref:
---------------------
- A new constructor lref(T*,bool) and a method set_ptr(T*,bool) allow lrefs to reference existing objects 
    via pointers. If bool argument is false, object's lifetime will not be managed.
- lref::operator=(rhs) will reset the lref if rhs is not initialized (This is a semantic change from v1.0)
- lref::bound(lref& rhs) will check if 'this' lref and rhs are bound/joined together. Returns bool.


Other enhancements to existing facilites
----------------------------------------------
- Support for const container<> and const_iterator in relations : begin(), end() & not_empty. 
- New overloads for the following relations that take function pointer or member function pointer as
  argument. These accept a pointer to an *overloaded* function (or method) to without requiring 
  explicit overload disambiguation. Also arguments to be forwarded can be 
  POTs or lrefs :
  + Additional/updated overloads for eq_f, eq_mf, predicate_f & predicate_mf.
  + Signatures for eq_f and predicate_f modified (new signatures continue to be backward compatible).
- Additional constructor for relation True that takes an integral argument denoting how many times to succeed.
- Additional overloads for item : item(lref<T>,lref<std::set<T>>) and item(lref<T>,lref<std::multiset<T>>). These
  enable faster lookups on values if container is a set or a multiset (uses the container's equal_range() method).
- Minor optimization for && operator.


Potential Incompatibilities:
---------------------------
- item() does not work with const containers or const_iterators.
- In generate mode, item() & head() relations now yield an lref<> that references the actual element in the 
  container/sequence instead of a copy.
- item() now succeeds once for every occurance of the value in the container/sequence. Old behavior
  of item was to succeed only once for such cases.
- Template paramters for eq_mf reordered to minimize need for explicit template arguments when 
  using const objects. Code that explicitly specify template arguments to these relations will be affected.


Deprecated:
-----------
In order to use the following deprecated facilites a #define CASTOR_ENABLE_DEPRECATED is required.
- The Named ILE Create::With() is now deprecated. Prefer using the named ILE create().
- OneSolution relation is now deprecated. Use class Coroutine instead.
- size() relation. Use size_of() instead. All (non TLR) aggregate relations now have _of suffix.


Bug fixes:
----------
- head_n and tail_n now fail instead of throwing exception when n>seq_.size()
- UnifyL  ... had a const member relation preventing copy construction
- Data member Read_r<T>::in is now a pointer instead of a reference to allow assignment of Read_r.
- Added #include<cstring.h> in eq.h. (Thanks to David Côme)
- Added #include<algorithm> in refcountedptr.h
- Exception types InvalidDeref and Underflow moved to namespace castor.
- Fixes for Gcc related warnings. (Thanks to Ali Cehreli)
- Efficiency fix for not_empty(). (Thanks to Zach Laine)