/*
    * $Id: DefaultGroovyMethods.java 4598 2006-12-22 20:21:21Z blackdrag $
    *
    * Copyright 2003 (C) James Strachan and Bob Mcwhirter. All Rights Reserved.
    *
    * Redistribution and use of this software and associated documentation
    * ("Software"), with or without modification, are permitted provided that the
    * following conditions are met:
    *  1. Redistributions of source code must retain copyright statements and
   * notices. Redistributions must also contain a copy of this document.
   *  2. Redistributions in binary form must reproduce the above copyright
   * notice, this list of conditions and the following disclaimer in the
   * documentation and/or other materials provided with the distribution.
   *  3. The name "groovy" must not be used to endorse or promote products
   * derived from this Software without prior written permission of The Codehaus.
   * For written permission, please contact info@codehaus.org.
   *  4. Products derived from this Software may not be called "groovy" nor may
   * "groovy" appear in their names without prior written permission of The
   * Codehaus. "groovy" is a registered trademark of The Codehaus.
   *  5. Due credit should be given to The Codehaus - http://groovy.codehaus.org/
   *
   * THIS SOFTWARE IS PROVIDED BY THE CODEHAUS AND CONTRIBUTORS ``AS IS'' AND ANY
   * EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
   * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
   * DISCLAIMED. IN NO EVENT SHALL THE CODEHAUS OR ITS CONTRIBUTORS BE LIABLE FOR
   * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
   * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
   * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
   * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
   * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
   * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
   * DAMAGE.
   *
   */
  package org.codehaus.groovy.runtime;
  
  import groovy.lang.*;
  import groovy.util.CharsetToolkit;
  import groovy.util.ClosureComparator;
  import groovy.util.OrderBy;
  
  import java.io.*;
  import java.lang.reflect.Array;
  import java.lang.reflect.Field;
  import java.lang.reflect.Modifier;
  import java.lang.reflect.Proxy;
  import java.math.BigDecimal;
  import java.math.BigInteger;
  import java.net.MalformedURLException;
  import java.net.ServerSocket;
  import java.net.Socket;
  import java.net.URI;
  import java.net.URISyntaxException;
  import java.net.URL;
  import java.security.AccessController;
  import java.security.PrivilegedAction;
  import java.util.*;
  import java.util.logging.Logger;
  import java.util.regex.Matcher;
  import java.util.regex.Pattern;
  
  import org.codehaus.groovy.runtime.typehandling.DefaultTypeTransformation;
  import org.codehaus.groovy.runtime.typehandling.NumberMath;
  import org.codehaus.groovy.tools.RootLoader;
  import org.w3c.dom.NodeList;
  
  /***
   * This class defines all the new groovy methods which appear on normal JDK
   * classes inside the Groovy environment. Static methods are used with the
   * first parameter the destination class.
   *
   * @author <a href="mailto:james@coredevelopers.net">James Strachan</a>
   * @author Jeremy Rayner
   * @author Sam Pullara
   * @author Rod Cope
   * @author Guillaume Laforge
   * @author John Wilson
   * @author Hein Meling
   * @author Dierk Koenig
   * @author Pilho Kim
   * @author Marc Guillemot
   * @author Russel Winder
   * @author bing ran
   * @author Jochen Theodorou
   * @version $Revision: 4598 $
   */
  public class DefaultGroovyMethods {
  
      private static final Logger LOG = Logger.getLogger(DefaultGroovyMethods.class.getName());
      private static final Integer ONE = new Integer(1);
  
      /***
       * Identity check. Since == is overridden in Groovy with the meaning of equality
       * we need some fallback to check for object identity.
       *
       * @param self
       * @param other
       * @return true if self and other are identical, false otherwise
       */
     public static boolean is(Object self, Object other) {
         return self == other;
     }
 
     /***
      * Allows the closure to be called for the object reference self
      *
      * @param self    the object to have a closure act upon
      * @param closure the closure to call on the object
      * @return result of calling the closure
      */
     public static Object identity(Object self, Closure closure) {
         final Closure clonedClosure = (Closure) closure.clone();
         clonedClosure.setDelegate(self);
         return clonedClosure.call(self);
     }
 
     /***
      * Allows the subscript operator to be used to lookup dynamic property values.
      * <code>bean[somePropertyNameExpression]</code>. The normal property notation
      * of groovy is neater and more concise but only works with compile-time known
      * property names.
      *
      * @param self the object to act upon
      */
     public static Object getAt(Object self, String property) {
         return InvokerHelper.getProperty(self, property);
     }
 
     /***
      * Allows the subscript operator to be used to set dynamically named property values.
      * <code>bean[somePropertyNameExpression] = foo</code>. The normal property notation
      * of groovy is neater and more concise but only works with property names which
      * are known at compile time.
      *
      * @param self     the object to act upon
      * @param property the name of the property to set
      * @param newValue the value to set
      */
     public static void putAt(Object self, String property, Object newValue) {
         InvokerHelper.setProperty(self, property, newValue);
     }
 
     /***
      * Generates a detailed dump string of an object showing its class,
      * hashCode and fields
      */
     public static String dump(Object self) {
         if (self == null) {
             return "null";
         }
         StringBuffer buffer = new StringBuffer("<");
         Class klass = self.getClass();
         buffer.append(klass.getName());
         buffer.append("@");
         buffer.append(Integer.toHexString(self.hashCode()));
         boolean groovyObject = self instanceof GroovyObject;
 
         /*jes this may be rewritten to use the new getProperties() stuff
          * but the original pulls out private variables, whereas getProperties()
          * does not. What's the real use of dump() here?
          */
         while (klass != null) {
             Field[] fields = klass.getDeclaredFields();
             for (int i = 0; i < fields.length; i++) {
                 final Field field = fields[i];
                 if ((field.getModifiers() & Modifier.STATIC) == 0) {
                     if (groovyObject && field.getName().equals("metaClass")) {
                         continue;
                     }
                     AccessController.doPrivileged(new PrivilegedAction() {
                         public Object run() {
                             field.setAccessible(true);
                             return null;
                         }
                     });
                     buffer.append(" ");
                     buffer.append(field.getName());
                     buffer.append("=");
                     try {
                         buffer.append(InvokerHelper.toString(field.get(self)));
                     } catch (Exception e) {
                         buffer.append(e);
                     }
                 }
             }
 
             klass = klass.getSuperclass();
         }
 
         /* here is a different implementation that uses getProperties(). I have left
          * it commented out because it returns a slightly different list of properties;
          * ie it does not return privates. I don't know what dump() really should be doing,
          * although IMO showing private fields is a no-no
          */
         /*
         List props = getProperties(self);
             for(Iterator itr = props.keySet().iterator(); itr.hasNext(); ) {
             String propName = itr.next().toString();
 
             // the original skipped this, so I will too
             if(pv.getName().equals("metaClass")) continue;
             if(pv.getName().equals("class")) continue;
 
             buffer.append(" ");
             buffer.append(propName);
             buffer.append("=");
             try {
                 buffer.append(InvokerHelper.toString(props.get(propName)));
             }
             catch (Exception e) {
                 buffer.append(e);
             }
         }
         */
 
         buffer.append(">");
         return buffer.toString();
     }
 
     /***
      * Retrieves the list of {@link MetaProperty} objects for 'self' and wraps it
      * in a list of {@link PropertyValue} objects that additionally provide
      * the value for each property of 'self'.
      *
      * @param self the receiver object
      * @return list of {@link PropertyValue} objects
      * @see groovy.util.Expando#getMetaPropertyValues()
      */
     public static List getMetaPropertyValues(Object self) {
         MetaClass metaClass = InvokerHelper.getMetaClass(self);
         List mps = metaClass.getProperties();
         List props = new ArrayList(mps.size());
         for (Iterator itr = mps.iterator(); itr.hasNext();) {
             MetaProperty mp = (MetaProperty) itr.next();
             PropertyValue pv = new PropertyValue(self, mp);
             props.add(pv);
         }
         return props;
     }
 
     /***
      * Convenience method that calls {@link #getMetaPropertyValues(Object)}(self)
      * and provides the data in form of simple key/value pairs, i.e. without
      * type() information.
      *
      * @param self the receiver object
      * @return meta properties as Map of key/value pairs
      */
     public static Map getProperties(Object self) {
         List metaProps = getMetaPropertyValues(self);
         Map props = new HashMap(metaProps.size());
 
         for (Iterator itr = metaProps.iterator(); itr.hasNext();) {
             PropertyValue pv = (PropertyValue) itr.next();
             try {
                 props.put(pv.getName(), pv.getValue());
             } catch (Exception e) {
                 LOG.throwing(self.getClass().getName(), "getProperty(" + pv.getName() + ")", e);
             }
         }
         return props;
     }
 
     /***
      * Scoped use method
      */
     public static void use(Object self, Class categoryClass, Closure closure) {
         GroovyCategorySupport.use(categoryClass, closure);
     }
 
     /***
      * Scoped use method with list of categories
      */
     public static void use(Object self, List categoryClassList, Closure closure) {
         GroovyCategorySupport.use(categoryClassList, closure);
     }
 
 
     /***
      * use() a list of categories, specifying the list as varargs:<br>
      * use(CategoryClass1, CategoryClass2) { ... }<br>
      * This method prevents the error of forgetting to wrap the the category
      * classes in a list.
      *
      * @param self
      * @param array
      */
     public static void use(Object self, Object[] array) {
         if (array.length < 2)
             throw new IllegalArgumentException(
                     "Expecting at least 2 arguments, a category class and a Closure");
         Closure closure;
         try {
             closure = (Closure) array[array.length - 1];
         } catch (ClassCastException e) {
             throw new IllegalArgumentException("Expecting a Closure to be the last argument");
         }
         List list = new ArrayList(array.length - 1);
         for (int i = 0; i < array.length - 1; ++i)
             list.add(array[i]);
         GroovyCategorySupport.use(list, closure);
     }
 
     /***
      * Print to a console in interactive format
      */
     public static void print(Object self, Object value) {
         System.out.print(InvokerHelper.toString(value));
     }
 
     /***
      * Print a linebreak to the standard out.
      */
     public static void println(Object self) {
         System.out.println();
     }
 
     /***
      * Print to a console in interactive format along with a newline
      */
     public static void println(Object self, Object value) {
         System.out.println(InvokerHelper.toString(value));
     }
 
     /***
      * Printf to a console.  Only works with JDK1.5 or later.
      */
     public static void printf(Object self, String format, Object[] values) {
         if (System.getProperty("java.version").charAt(2) == '5') {
             //
             //  Cannot just do:
             //
             //        System.out.printf(format, values) ;
             //
             //  because this fails to compile on JDK1.4.x and earlier.  So until the entire world is using
             //  JDK1.5 or later then we have to do things by reflection so as to hide the use of printf
             //  from the compiler.  In JDK1.5 you might try:
             //
             //        System.out.getClass().getMethod("printf", String.class, Object[].class).invoke(System.out, format, values) ;
             //
             //  but of course this doesn't work on JDK1.4 as it relies on varargs.  argh.  So we are
             //  forced into:
             //
             try {
                 System.out.getClass().getMethod("printf", new Class[]{String.class, Object[].class}).invoke(System.out, new Object[]{format, values});
             } catch (NoSuchMethodException nsme) {
                 throw new RuntimeException("getMethod threw a NoSuchMethodException.  This is impossible.");
             } catch (IllegalAccessException iae) {
                 throw new RuntimeException("invoke threw a IllegalAccessException.  This is impossible.");
             } catch (java.lang.reflect.InvocationTargetException ite) {
                 throw new RuntimeException("invoke threw a InvocationTargetException.  This is impossible.");
             }
         } else {
             throw new RuntimeException("printf requires JDK1.5 or later.");
         }
     }
 
     /***
      * Returns a formatted string using the specified format string and
      * arguments.
      * <p/>
      * <p/>
      * For examples, <pre>
      *     printf ( "Hello, %s!\n" , [ "world" ] as String[] )
      *     printf ( "Hello, %s!\n" , [ "Groovy" ])
      *     printf ( "%d + %d = %d\n" , [ 1 , 2 , 1+2 ] as Integer[] )
      *     printf ( "%d + %d = %d\n" , [ 3 , 3 , 3+3 ])
      * <p/>
      *     ( 1..5 ).each { printf ( "-- %d\n" , [ it ] as Integer[] ) }
      *     ( 1..5 ).each { printf ( "-- %d\n" , [ it ] as int[] ) }
      *     ( 0x41..0x45 ).each { printf ( "-- %c\n" , [ it ] as char[] ) }
      *     ( 07..011 ).each { printf ( "-- %d\n" , [ it ] as byte[] ) }
      *     ( 7..11 ).each { printf ( "-- %d\n" , [ it ] as short[] ) }
      *     ( 7..11 ).each { printf ( "-- %d\n" , [ it ] as long[] ) }
      *     ( 7..11 ).each { printf ( "-- %5.2f\n" , [ it ] as float[] ) }
      *     ( 7..11 ).each { printf ( "-- %5.2g\n" , [ it ] as double[] ) }
      * </pre>
      * <p/>
      *
      * @param format A format string
      * @param arg    Argument which is referenced by the format specifiers in the format
      *               string.  The type of <code>arg</code> should be one of Object[], List,
      *               int[], short[], byte[], char[], boolean[], long[], float[], or double[].
      * @since JDK 1.5
      */
     public static void printf(Object self, String format, Object arg) {
         if (arg instanceof Object[]) {
             printf(self, format, (Object[]) arg);
             return;
         } else if (arg instanceof List) {
             printf(self, format, ((List) arg).toArray());
             return;
         } else if (!arg.getClass().isArray()) {
             Object[] o = (Object[]) java.lang.reflect.Array.newInstance(arg.getClass(), 1);
             o[0] = arg;
             printf(self, format, o);
             return;
         }
 
         Object[] ans = null;
         String elemType = arg.getClass().getName();
         if (elemType.equals("[I")) {
             int[] ia = (int[]) arg;
             ans = new Integer[ia.length];
             for (int i = 0; i < ia.length; i++) {
                 ans[i] = new Integer(ia[i]);
             }
         } else if (elemType.equals("[C")) {
             char[] ia = (char[]) arg;
             ans = new Character[ia.length];
             for (int i = 0; i < ia.length; i++) {
                 ans[i] = new Character(ia[i]);
             }
         } else if (elemType.equals("[Z")) {
             boolean[] ia = (boolean[]) arg;
             ans = new Boolean[ia.length];
             for (int i = 0; i < ia.length; i++) {
                 ans[i] = new Boolean(ia[i]);
             }
         } else if (elemType.equals("[B")) {
             byte[] ia = (byte[]) arg;
             ans = new Byte[ia.length];
             for (int i = 0; i < ia.length; i++) {
                 ans[i] = new Byte(ia[i]);
             }
         } else if (elemType.equals("[S")) {
             short[] ia = (short[]) arg;
             ans = new Short[ia.length];
             for (int i = 0; i < ia.length; i++) {
                 ans[i] = new Short(ia[i]);
             }
         } else if (elemType.equals("[F")) {
             float[] ia = (float[]) arg;
             ans = new Float[ia.length];
             for (int i = 0; i < ia.length; i++) {
                 ans[i] = new Float(ia[i]);
             }
         } else if (elemType.equals("[J")) {
             long[] ia = (long[]) arg;
             ans = new Long[ia.length];
             for (int i = 0; i < ia.length; i++) {
                 ans[i] = new Long(ia[i]);
             }
         } else if (elemType.equals("[D")) {
             double[] ia = (double[]) arg;
             ans = new Double[ia.length];
             for (int i = 0; i < ia.length; i++) {
                 ans[i] = new Double(ia[i]);
             }
         } else {
             throw new RuntimeException("printf(String," + arg + ")");
         }
         printf(self, format, (Object[]) ans);
     }
 
 
     /***
      * @return a String that matches what would be typed into a terminal to
      *         create this object. e.g. [1, 'hello'].inspect() -> [1, "hello"]
      */
     public static String inspect(Object self) {
         return InvokerHelper.inspect(self);
     }
 
     /***
      * Print to a console in interactive format
      */
     public static void print(Object self, PrintWriter out) {
         if (out == null) {
             out = new PrintWriter(System.out);
         }
         out.print(InvokerHelper.toString(self));
     }
 
     /***
      * Print to a console in interactive format
      *
      * @param out the PrintWriter used for printing
      */
     public static void println(Object self, PrintWriter out) {
         if (out == null) {
             out = new PrintWriter(System.out);
         }
         InvokerHelper.invokeMethod(self, "print", out);
         out.println();
     }
 
     /***
      * Provide a dynamic method invocation method which can be overloaded in
      * classes to implement dynamic proxies easily.
      */
     public static Object invokeMethod(Object object, String method, Object arguments) {
         return InvokerHelper.invokeMethod(object, method, arguments);
     }
 
     // isCase methods
     //-------------------------------------------------------------------------
     public static boolean isCase(Object caseValue, Object switchValue) {
         return caseValue.equals(switchValue);
     }
 
     public static boolean isCase(String caseValue, Object switchValue) {
         if (switchValue == null) {
             return caseValue == null;
         }
         return caseValue.equals(switchValue.toString());
     }
 
     public static boolean isCase(Class caseValue, Object switchValue) {
         if (switchValue instanceof Class) {
             Class val = (Class) switchValue;
             return caseValue.isAssignableFrom(val);
         }
         return caseValue.isInstance(switchValue);
     }
 
     public static boolean isCase(Collection caseValue, Object switchValue) {
         return caseValue.contains(switchValue);
     }
 
     public static boolean isCase(Pattern caseValue, Object switchValue) {
         if (switchValue == null) {
             return caseValue == null;
         }
         final Matcher matcher = caseValue.matcher(switchValue.toString());
         if (matcher.matches()) {
             RegexSupport.setLastMatcher(matcher);
             return true;
         } else {
             return false;
         }
     }
 
     // Collection based methods
     //-------------------------------------------------------------------------
 
     public static Collection unique(Collection self) {
         if (self instanceof Set)
             return self;
         List answer = new ArrayList();
         NumberComparator comparator = new NumberComparator();
         for (Iterator it = self.iterator(); it.hasNext();) {
             Object o = it.next();
             boolean duplicated = false;
             for (Iterator it2 = answer.iterator(); it2.hasNext();) {
                 Object o2 = it2.next();
                 if (comparator.compare(o, o2) == 0) {
                     duplicated = true;
                     break;
                 }
             }
             if (!duplicated)
                 answer.add(o);
         }
         self.clear();
         self.addAll(answer);
         return self;
     }
 
     /***
      * A convenience method for making a collection unique using a closure as a comparator
      * (by Michael Baehr)
      *
      * @param self    a Collection
      * @param closure a Closure used as a comparator
      * @return self   without any duplicates
      */
     public static Collection unique(Collection self, Closure closure) {
         if (self instanceof Set)
             return self;
         // use a comparator of one item or two
         int params = closure.getMaximumNumberOfParameters();
         if (params == 1) {
             unique(self, new OrderBy(closure));
         } else {
             unique(self, new ClosureComparator(closure));
         }
         return self;
     }
 
     /***
      * Remove all duplicates from a given Collection.
      * Works on the receiver object and returns it.
      * The order of members in the Collection are compared by the given Comparator.
      * For each duplicate, the first member which is returned
      * by the given Collection's iterator is retained, but all other ones are removed.
      * The given Collection's original order is preserved.
      * <p/>
      * <code><pre>
      *     class Person {
      *         @Property fname, lname
      *         public String toString() {
      *             return fname + " " + lname
      *         }
      *     }
      * <p/>
      *     class PersonComparator implements Comparator {
      *         public int compare(Object o1, Object o2) {
      *             Person p1 = (Person) o1
      *             Person p2 = (Person) o2
      *             if (p1.lname != p2.lname)
      *                 return p1.lname.compareTo(p2.lname)
      *             else
      *                 return p1.fname.compareTo(p2.fname)
      *         }
      * <p/>
      *         public boolean equals(Object obj) {
      *             return this.equals(obj)
      *         }
      *     }
      * <p/>
      *     Person a = new Person(fname:"John", lname:"Taylor")
      *     Person b = new Person(fname:"Clark", lname:"Taylor")
      *     Person c = new Person(fname:"Tom", lname:"Cruz")
      *     Person d = new Person(fname:"Clark", lname:"Taylor")
      * <p/>
      *     def list = [a, b, c, d]
      *     List list2 = list.unique(new PersonComparator())
      *     assert( list2 == list && list == [a, b, c] )
      * <p/>
      * </pre></code>
      *
      * @param self       a Collection
      * @param comparator a Comparator.
      * @return self       without duplicates
      */
     public static Collection unique(Collection self, Comparator comparator) {
         if (self instanceof Set)
             return self;
         List answer = new ArrayList();
         for (Iterator it = self.iterator(); it.hasNext();) {
             Object o = it.next();
             boolean duplicated = false;
             for (Iterator it2 = answer.iterator(); it2.hasNext();) {
                 Object o2 = it2.next();
                 if (comparator.compare(o, o2) == 0) {
                     duplicated = true;
                     break;
                 }
             }
             if (!duplicated)
                 answer.add(o);
         }
         self.clear();
         self.addAll(answer);
         return self;
     }
 
     /***
      * Allows objects to be iterated through using a closure
      *
      * @param self    the object over which we iterate
      * @param closure the closure applied on each element found
      */
     public static void each(Object self, Closure closure) {
         for (Iterator iter = InvokerHelper.asIterator(self); iter.hasNext();) {
             closure.call(iter.next());
         }
     }
 
     /***
      * Allows object to be iterated through a closure with a counter
      *
      * @param self    an Object
      * @param closure a Closure
      */
     public static void eachWithIndex(Object self, Closure closure) {
         int counter = 0;
         for (Iterator iter = InvokerHelper.asIterator(self); iter.hasNext();) {
             closure.call(new Object[]{iter.next(), new Integer(counter++)});
         }
     }
 
     /***
      * Allows objects to be iterated through using a closure
      *
      * @param self    the collection over which we iterate
      * @param closure the closure applied on each element of the collection
      */
     public static void each(Collection self, Closure closure) {
         for (Iterator iter = self.iterator(); iter.hasNext();) {
             closure.call(iter.next());
         }
     }
 
     /***
      * Allows a Map to be iterated through using a closure. If the
      * closure takes one parameter then it will be passed the Map.Entry
      * otherwise if the closure takes two parameters then it will be
      * passed the key and the value.
      *
      * @param self    the map over which we iterate
      * @param closure the closure applied on each entry of the map
      */
     public static void each(Map self, Closure closure) {
         for (Iterator iter = self.entrySet().iterator(); iter.hasNext();) {
             Map.Entry entry = (Map.Entry) iter.next();
             callClosureForMapEntry(closure, entry);
         }
     }
 
 
     /***
      * Iterates over every element of a collection, and check whether a predicate is valid for all elements.
      *
      * @param self    the object over which we iterate
      * @param closure the closure predicate used for matching
      * @return true if every item in the collection matches the closure
      *         predicate
      */
     public static boolean every(Object self, Closure closure) {
         for (Iterator iter = InvokerHelper.asIterator(self); iter.hasNext();) {
             if (!DefaultTypeTransformation.castToBoolean(closure.call(iter.next()))) {
                 return false;
             }
         }
         return true;
     }
 
     /***
      * Iterates over every element of a collection, and check whether a predicate is valid for at least one element
      *
      * @param self    the object over which we iterate
      * @param closure the closure predicate used for matching
      * @return true if any item in the collection matches the closure predicate
      */
     public static boolean any(Object self, Closure closure) {
         for (Iterator iter = InvokerHelper.asIterator(self); iter.hasNext();) {
             if (DefaultTypeTransformation.castToBoolean(closure.call(iter.next()))) {
                 return true;
             }
         }
         return false;
     }
 
     /***
      * Iterates over every element of the collection and return each object that matches
      * the given filter - calling the isCase() method used by switch statements.
      * This method can be used with different kinds of filters like regular expresions, classes, ranges etc.
      *
      * @param self   the object over which we iterate
      * @param filter the filter to perform on the collection (using the isCase(object) method)
      * @return a list of objects which match the filter
      */
     public static List grep(Object self, Object filter) {
         List answer = new ArrayList();
         MetaClass metaClass = InvokerHelper.getMetaClass(filter);
         for (Iterator iter = InvokerHelper.asIterator(self); iter.hasNext();) {
             Object object = iter.next();
             if (DefaultTypeTransformation.castToBoolean(metaClass.invokeMethod(filter, "isCase", object))) {
                 answer.add(object);
             }
         }
         return answer;
     }
 
     /***
      * Counts the number of occurencies of the given value inside this collection
      *
      * @param self  the collection within which we count the number of occurencies
      * @param value the value
      * @return the number of occurrencies
      */
     public static int count(Collection self, Object value) {
         int answer = 0;
         for (Iterator iter = self.iterator(); iter.hasNext();) {
             if (DefaultTypeTransformation.compareEqual(iter.next(), value)) {
                 ++answer;
             }
         }
         return answer;
     }
 
     /***
      * Convert a collection to a List.
      *
      * @param self a collection
      * @return a List
      */
     public static List toList(Collection self) {
         List answer = new ArrayList(self.size());
         answer.addAll(self);
         return answer;
     }
 
     /***
      * Iterates through this object transforming each object into a new value using the closure
      * as a transformer, returning a list of transformed values.
      *
      * @param self    the values of the object to map
      * @param closure the closure used to map each element of the collection
      * @return a List of the mapped values
      */
     public static List collect(Object self, Closure closure) {
         return (List) collect(self, new ArrayList(), closure);
     }
 
     /***
      * Iterates through this object transforming each object into a new value using the closure
      * as a transformer and adding it to the collection, returning the resulting collection.
      *
      * @param self       the values of the object to map
      * @param collection the Collection to which the mapped values are added
      * @param closure    the closure used to map each element of the collection
      * @return the resultant collection
      */
     public static Collection collect(Object self, Collection collection, Closure closure) {
         for (Iterator iter = InvokerHelper.asIterator(self); iter.hasNext();) {
             collection.add(closure.call(iter.next()));
         }
         return collection;
     }
 
     /***
      * Iterates through this collection transforming each entry into a new value using the closure
      * as a transformer, returning a list of transformed values.
      *
      * @param self    a collection
      * @param closure the closure used for mapping
      * @return a List of the mapped values
      */
     public static List collect(Collection self, Closure closure) {
         return (List) collect(self, new ArrayList(self.size()), closure);
     }
 
     /***
      * Iterates through this collection transforming each entry into a new value using the closure
      * as a transformer, returning a list of transformed values.
      *
      * @param self       a collection
      * @param collection the Collection to which the mapped values are added
      * @param closure    the closure used to map each element of the collection
      * @return the resultant collection
      */
     public static Collection collect(Collection self, Collection collection, Closure closure) {
         for (Iterator iter = self.iterator(); iter.hasNext();) {
             collection.add(closure.call(iter.next()));
             if (closure.getDirective() == Closure.DONE) {
                 break;
             }
         }
         return collection;
     }
 
     /***
      * Iterates through this Map transforming each entry into a new value using the closure
      * as a transformer, returning a list of transformed values.
      *
      * @param self       a Map
      * @param collection the Collection to which the mapped values are added
      * @param closure    the closure used for mapping, which can be with one(Map.Entry) or two(key, value) parameters
      * @return a List of the mapped values
      */
     public static Collection collect(Map self, Collection collection, Closure closure) {
         boolean isTwoParams = (closure.getParameterTypes().length == 2);
         for (Iterator iter = self.entrySet().iterator(); iter.hasNext();) {
             if (isTwoParams) {
                 Map.Entry entry = (Map.Entry) iter.next();
                 collection.add(closure.call(new Object[]{entry.getKey(), entry.getValue()}));
             } else {
                 collection.add(closure.call(iter.next()));
             }
         }
         return collection;
     }
 
     /***
      * Iterates through this Map transforming each entry into a new value using the closure
      * as a transformer, returning a list of transformed values.
      *
      * @param self    a Map
      * @param closure the closure used to map each element of the collection
      * @return the resultant collection
      */
     public static List collect(Map self, Closure closure) {
         return (List) collect(self, new ArrayList(self.size()), closure);
     }
 
     /***
      * Finds the first value matching the closure condition
      *
      * @param self    an Object with an iterator returning its values
      * @param closure a closure condition
      * @return the first Object found
      */
     public static Object find(Object self, Closure closure) {
         for (Iterator iter = InvokerHelper.asIterator(self); iter.hasNext();) {
             Object value = iter.next();
             if (DefaultTypeTransformation.castToBoolean(closure.call(value))) {
                 return value;
             }
         }
         return null;
     }
 
     /***
      * Finds the first value matching the closure condition
      *
      * @param self    a Collection
      * @param closure a closure condition
      * @return the first Object found
      */
     public static Object find(Collection self, Closure closure) {
         for (Iterator iter = self.iterator(); iter.hasNext();) {
             Object value = iter.next();
             if (DefaultTypeTransformation.castToBoolean(closure.call(value))) {
                 return value;
             }
         }
         return null;
     }
 
     /***
      * Finds the first value matching the closure condition
      *
      * @param self    a Map
      * @param closure a closure condition
      * @return the first Object found
      */
     public static Object find(Map self, Closure closure) {
         for (Iterator iter = self.entrySet().iterator(); iter.hasNext();) {
             Object value = iter.next();
             if (DefaultTypeTransformation.castToBoolean(closure.call(value))) {
                 return value;
             }
         }
         return null;
     }
 
     /***
      * Finds all values matching the closure condition
      *
      * @param self    an Object with an Iterator returning its values
      * @param closure a closure condition
      * @return a List of the values found
      */
     public static List findAll(Object self, Closure closure) {
         List answer = new ArrayList();
         for (Iterator iter = InvokerHelper.asIterator(self); iter.hasNext();) {
             Object value = iter.next();
             if (DefaultTypeTransformation.castToBoolean(closure.call(value))) {
                 answer.add(value);
             }
         }
         return answer;
     }
 
     /***
      * Finds all values matching the closure condition
      *
      * @param self    a Collection
      * @param closure a closure condition
      * @return a List of the values found
      */
     public static List findAll(Collection self, Closure closure) {
         List answer = new ArrayList(self.size());
         for (Iterator iter = self.iterator(); iter.hasNext();) {
             Object value = iter.next();
             if (DefaultTypeTransformation.castToBoolean(closure.call(value))) {
                 answer.add(value);
             }
         }
         return answer;
     }
 
     /***
      * Finds all entries matching the closure condition. If the
      * closure takes one parameter then it will be passed the Map.Entry
      * otherwise if the closure takes two parameters then it will be
      * passed the key and the value.
      *
      * @param self    a Map
      * @param closure a closure condition applying on the entries
      * @return a new subMap
      */
     public static Map findAll(Map self, Closure closure) {
         Map answer = new HashMap(self.size());
         for (Iterator iter = self.entrySet().iterator(); iter.hasNext();) {
             Map.Entry entry = (Map.Entry) iter.next();
             if (DefaultTypeTransformation.castToBoolean(callClosureForMapEntry(closure, entry))) {
                 answer.put(entry.getKey(), entry.getValue());
             }
         }
         return answer;
     }
 
     /***
      * Groups all collection members into groups determined by the
      * supplied mapping closure.
      *
      * @param self    a collection to group (no map)
      * @param closure a closure mapping entries on keys
      * @return a new Map grouped by keys
      */
     public static Map groupBy(Collection self, Closure closure) {
         Map answer = new HashMap();
         for (Iterator iter = self.iterator(); iter.hasNext();) {
             groupCurrentElement(closure, answer, iter);
         }
         return answer;
     }
 
     /***
      * Groups all map members into groups determined by the
      * supplied mapping closure.
      * 
      * @param self     a map to group
      * @param closure  a closure mapping entries on keys
      * @return         a new Map grouped by keys
      */
     /* Removed for 1.0, to be discussed for 1.1
     public static Map groupBy(Map self, Closure closure) {
         final Map answer = new HashMap();
         for (final Iterator iter = self.entrySet().iterator(); iter.hasNext();) {
             groupCurrentElement(closure, answer, iter);
         }
         return answer;
     }
     */
     
     /***
      * Groups the current element of the iterator as determined
      * by the mapping closure.
      * 
      * @param closure  a closure mapping the current entry on a key
      * @param answer   the map containing the results
      * @param iter     the iterator from which the current element stems
      */   
     private static void groupCurrentElement(Closure closure, Map answer, Iterator iter) {
 	Object element = iter.next();
 	Object value = closure.call(element);
 	if (answer.containsKey(value)) {
 	    ((List) answer.get(value)).add(element);
 	} else {
 	    ArrayList groupedElements = new ArrayList();
 	    groupedElements.add(element);
 	    answer.put(value, groupedElements);
 	}
     }
     
     // internal helper method
     protected static Object callClosureForMapEntry(Closure closure, Map.Entry entry) {
         if (closure.getMaximumNumberOfParameters() == 2) {
             return closure.call(new Object[]{entry.getKey(), entry.getValue()});
         }
         return closure.call(entry);
     }
 
 
     /***
      * Iterates through the given collection, passing in the initial value to
      * the closure along with the current iterated item then passing into the
      * next iteration the value of the previous closure.
      *
      * @param self    a Collection
      * @param value   a value
      * @param closure a closure
      * @return the last value of the last iteration
      */
     public static Object inject(Collection self, Object value, Closure closure) {
         Object[] params = new Object[2];
         for (Iterator iter = self.iterator(); iter.hasNext();) {
             Object item = iter.next();
             params[0] = value;
             params[1] = item;
             value = closure.call(params);
         }
         return value;
     }
 
     /***
      * Iterates through the given array of objects, passing in the initial value to
      * the closure along with the current iterated item then passing into the
      * next iteration the value of the previous closure.
      *
      * @param self    an Object[]
      * @param value   a value
      * @param closure a closure
      * @return the last value of the last iteration
      */
     public static Object inject(Object[] self, Object value, Closure closure) {
         Object[] params = new Object[2];
         for (int i = 0; i < self.length; i++) {
             params[0] = value;
             params[1] = self[i];
             value = closure.call(params);
         }
         return value;
     }
 
     /***
      * Sums a collection of numeric values. <code>coll.sum()</code> is equivalent to:
      * <code>coll.inject(0) {value, item -> value + item}</code>.
      *
      * @param self Collection of values to add together.
      * @return The sum of all of the list itmems.
      */
     public static Object sum(Collection self) {
         Object result = null;
 
         if (self.size() == 0) return result;
 
         boolean isNumber = true;
 
         Class classref = null;
         try {
             classref = Class.forName("java.lang.Number");
         } catch (Exception ex) {
         }
 
         for (Iterator iter = self.iterator(); iter.hasNext();) {
             if (!classref.isInstance(iter.next())) {
                 isNumber = false;
                 break;
             }
         }
 
         if (isNumber) {
             result = new Integer(0);
         } else {
             result = new String();
         }
 
         Object[] param = new Object[1];
         for (Iterator iter = self.iterator(); iter.hasNext();) {
             param[0] = iter.next();
             MetaClass metaClass = InvokerHelper.getMetaClass(result);
             result = metaClass.invokeMethod(result, "plus", param);
         }
         return result;
     }
 
     /***
      * Sums the result of apply a closure to each item of a collection.
      * <code>coll.sum(closure)</code> is equivalent to:
      * <code>coll.collect(closure).sum()</code>.
      *
      * @param self    a Collection
      * @param closure a single parameter closure that returns a numeric value.
      * @return The sum of the values returned by applying the closure to each
      *         item of the list.
      */
     public static Object sum(Collection self, Closure closure) {
         Object result = new Integer(0);
         Object[] closureParam = new Object[1];
         Object[] plusParam = new Object[1];
         for (Iterator iter = self.iterator(); iter.hasNext();) {
             closureParam[0] = iter.next();
             plusParam[0] = closure.call(closureParam);
             MetaClass metaClass = InvokerHelper.getMetaClass(result);
             result = metaClass.invokeMethod(result, "plus", plusParam);
         }
         return result;
     }
 
     /***
      * Concatenates all of the items of the collection together with the given String as a separator
      *
      * @param self      a Collection of objects
      * @param separator a String separator
      * @return the joined String
      */
     public static String join(Collection self, String separator) {
         StringBuffer buffer = new StringBuffer();
         boolean first = true;
 
         if (separator == null) separator = "";
 
         for (Iterator iter = self.iterator(); iter.hasNext();) {
             Object value = iter.next();
             if (first) {
                 first = false;
             } else {
                 buffer.append(separator);
             }
             buffer.append(InvokerHelper.toString(value));
         }
         return buffer.toString();
     }
 
     /***
      * Concatenates all of the elements of the array together with the given String as a separator
      *
      * @param self      an array of Object
      * @param separator a String separator
      * @return the joined String
      */
     public static String join(Object[] self, String separator) {
         StringBuffer buffer = new StringBuffer();
         boolean first = true;
 
         if (separator == null) separator = "";
 
         for (int i = 0; i < self.length; i++) {
             String value = InvokerHelper.toString(self[i]);
             if (first) {
                 first = false;
             } else {
                 buffer.append(separator);
             }
             buffer.append(value);
         }
         return buffer.toString();
     }
 
     /***
      * Selects the maximum value found in the collection
      *
      * @param self a Collection
      * @return the maximum value
      */
     public static Object max(Collection self) {
         Object answer = null;
         for (Iterator iter = self.iterator(); iter.hasNext();) {
             Object value = iter.next();
             if (value != null) {
                 if (answer == null || ScriptBytecodeAdapter.compareGreaterThan(value, answer)) {
                     answer = value;
                 }
             }
         }
         return answer;
     }
 
     /***
      * Selects the maximum value found in the collection using the given comparator
      *
      * @param self       a Collection
      * @param comparator a Comparator
      * @return the maximum value
      */
     public static Object max(Collection self, Comparator comparator) {
         Object answer = null;
         for (Iterator iter = self.iterator(); iter.hasNext();) {
             Object value = iter.next();
             if (answer == null || comparator.compare(value, answer) > 0) {
                 answer = value;
             }
         }
         return answer;
     }
 
     /***
      * Selects the minimum value found in the collection
      *
      * @param self a Collection
      * @return the minimum value
      */
     public static Object min(Collection self) {
         Object answer = null;
         for (Iterator iter = self.iterator(); iter.hasNext();) {
             Object value = iter.next();
             if (value != null) {
                 if (answer == null || ScriptBytecodeAdapter.compareLessThan(value, answer)) {
                     answer = value;
                 }
             }
         }
         return answer;
     }
 
     /***
      * Selects the minimum value found in the collection using the given comparator
      *
      * @param self       a Collection
      * @param comparator a Comparator
      * @return the minimum value
      */
     public static Object min(Collection self, Comparator comparator) {
         Object answer = null;
         for (Iterator iter = self.iterator(); iter.hasNext();) {
             Object value = iter.next();
             if (answer == null || comparator.compare(value, answer) < 0) {
                 answer = value;
             }
         }
         return answer;
     }
 
     /***
      * Selects the minimum value found in the collection using the given closure as a comparator
      *
      * @param self    a Collection
      * @param closure a closure used as a comparator
      * @return the minimum value
      */
     public static Object min(Collection self, Closure closure) {
         int params = closure.getMaximumNumberOfParameters();
         if (params == 1) {
             Object answer = null;
             Object answer_value = null;
             for (Iterator iter = self.iterator(); iter.hasNext();) {
                 Object item = iter.next();
                 Object value = closure.call(item);
                 if (answer == null || ScriptBytecodeAdapter.compareLessThan(value, answer_value)) {
                     answer = item;
                     answer_value = value;
                 }
             }
             return answer;
         } else {
             return min(self, new ClosureComparator(closure));
         }
     }
 
     /***
      * Selects the maximum value found in the collection using the given closure as a comparator
      *
      * @param self    a Collection
      * @param closure a closure used as a comparator
      * @return the maximum value
      */
     public static Object max(Collection self, Closure closure) {
         int params = closure.getMaximumNumberOfParameters();
         if (params == 1) {
             Object answer = null;
             Object answer_value = null;
             for (Iterator iter = self.iterator(); iter.hasNext();) {
                 Object item = iter.next();
                 Object value = closure.call(item);
                 if (answer == null || ScriptBytecodeAdapter.compareLessThan(answer_value, value)) {
                     answer = item;
                     answer_value = value;
                 }
             }
             return answer;
         } else {
             return max(self, new ClosureComparator(closure));
         }
     }
 
     /***
      * Makes a String look like a Collection by adding support for the size() method
      *
      * @param text a String
      * @return the length of the String
      */
     public static int size(String text) {
         return text.length();
     }
 
     /***
      * Provide standard Groovy size() method for StringBuffers
      *
      * @param buffer a StringBuffer
      * @return the length of the StringBuffer
      */
     public static int size(StringBuffer buffer) {
         return buffer.length();
     }
 
     /***
      * Provide the standard Groovy size method
      */
     public static long size(File file) {
         return file.length();
     }
 
 
     /***
      * Provide the standard Groovy size method
      */
     public static long size(Matcher matcher) {
         return getCount(matcher);
     }
 
     /***
      * Makes an Array look like a Collection by adding support for the size() method
      *
      * @param self an Array of Object
      * @return the size of the Array
      */
     public static int size(Object[] self) {
         return self.length;
     }
 
     /***
      * Support the subscript operator for String.
      *
      * @param text  a String
      * @param index the index of the Character to get
      * @return the Character at the given index
      */
     public static CharSequence getAt(CharSequence text, int index) {
         index = normaliseIndex(index, text.length());
         return text.subSequence(index, index + 1);
     }
 
     /***
      * Support the subscript operator for String
      *
      * @param text a String
      * @return the Character object at the given index
      */
     public static String getAt(String text, int index) {
         index = normaliseIndex(index, text.length());
         return text.substring(index, index + 1);
     }
 
     /***
      * Support the range subscript operator for CharSequence
      *
      * @param text  a CharSequence
      * @param range a Range
      * @return the subsequence CharSequence
      */
     public static CharSequence getAt(CharSequence text, Range range) {
         int from = normaliseIndex(DefaultTypeTransformation.intUnbox(range.getFrom()), text.length());
         int to = normaliseIndex(DefaultTypeTransformation.intUnbox(range.getTo()), text.length());
 
         // If this is a backwards range, reverse the arguments to substring.
         if (from > to) {
             int tmp = from;
             from = to;
             to = tmp;
         }
 
         return text.subSequence(from, to + 1);
     }
 
     /***
      * Support the range subscript operator for CharSequence or StringBuffer with IntRange
      *
      * @param text  a CharSequence
      * @param range an IntRange
      * @return the subsequence CharSequence
      */
     public static CharSequence getAt(CharSequence text, IntRange range) {
         return getAt(text, (Range) range);
     }
 
     /***
      * Support the range subscript operator for String with IntRange
      *
      * @param text  a String
      * @param range an IntRange
      * @return the resulting String
      */
     public static String getAt(String text, IntRange range) {
         return getAt(text, (Range) range);
     }
 
     /***
      * Support the range subscript operator for String
      *
      * @param text  a String
      * @param range a Range
      * @return a substring corresponding to the Range
      */
     public static String getAt(String text, Range range) {
         int from = normaliseIndex(DefaultTypeTransformation.intUnbox(range.getFrom()), text.length());
         int to = normaliseIndex(DefaultTypeTransformation.intUnbox(range.getTo()), text.length());
 
         // If this is a backwards range, reverse the arguments to substring.
         boolean reverse = range.isReverse();
         if (from > to) {
             int tmp = to;
             to = from;
             from = tmp;
             reverse = !reverse;
         }
 
         String answer = text.substring(from, to + 1);
         if (reverse) {
             answer = reverse(answer);
         }
         return answer;
     }
 
     /***
      * Creates a new string which is the reverse (backwards) of this string
      *
      * @param self a String
      * @return a new string with all the characters reversed.
      */
     public static String reverse(String self) {
         int size = self.length();
         StringBuffer buffer = new StringBuffer(size);
         for (int i = size - 1; i >= 0; i--) {
             buffer.append(self.charAt(i));
         }
         return buffer.toString();
     }
 
     /***
      * Transforms a String representing a URL into a URL object.
      *
      * @param self the String representing a URL
      * @return a URL
      * @throws MalformedURLException is thrown if the URL is not well formed.
      */
     public static URL toURL(String self) throws MalformedURLException {
         return new URL(self);
     }
 
     /***
      * Transforms a String representing a URI into a URI object.
      *
      * @param self the String representing a URI
      * @return a URI
      * @throws URISyntaxException is thrown if the URI is not well formed.
      */
     public static URI toURI(String self) throws URISyntaxException {
         return new URI(self);
     }
 
     /***
      * Turns a String into a regular expression pattern
      *
      * @param self a String to convert into a regular expression
      * @return the regular expression pattern
      */
     public static Pattern negate(String self) {
         return Pattern.compile(self);
     }
 
     /***
      * Replaces all occurrencies of a captured group by the result of a closure on that text.
      * <p/>
      * <p> For examples,
      * <pre>