Package: java.lang

## [Java] Class Object

-     public class Object
      extends Object

  GDK enhancements for Object.

  displayName:
    Object
  receiverFqcn:
    java.lang.Object

- - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `public void` | `addShutdownHook(Closure closure)` Allows the usage of addShutdownHook without getting the runtime first.
    `` | `public boolean` | `any()` Iterates over the elements of a collection, and checks whether at least one element is true according to the Groovy Truth.
    `` | `public boolean` | `any(Closure predicate)` Iterates over the contents of an object or collection, and checks whether a predicate is valid for at least one element.
    `` | `public boolean` | `asBoolean()` Coerce an object instance to a boolean value.
    `<T>` | `public T` | `asType(Class<T> type)` Converts a given object to a type.
    `<T extends java.lang.Comparable<? super T>>` | `public T` | `clamp(T lower, T upper)` Constrains a Comparable value to lie within the inclusive range `[lower, upper]`.
    `<T extends java.lang.Comparable<? super T>>` | `public T` | `clamp(Range<T> range)` Constrains a Comparable value to lie within the given Range.
    `` | `public Collection` | `collect()` Iterates through this aggregate Object transforming each item into a new value using Closure.IDENTITY as a transformer, basically returning a list of items copied from the original object.
    `<T>` | `public List<T>` | `collect(Closure<T> transform)` Iterates through this aggregate Object transforming each item into a new value using the `transform` closure, returning a list of transformed values.
    `<T, C extends java.util.Collection<T>>` | `public C` | `collect(C collector, Closure<? extends T> transform)` Iterates through this aggregate Object transforming each item into a new value using the `transform` closure and adding it to the supplied `collector`.
    `` | `public String` | `dump()` Generates a detailed dump string of an object showing its class, hashCode and all accessible fields.
    `<T>` | `public T` | `each(Closure closure)` Iterates through an aggregate type or data structure, passing each item to the given closure.
    `<T extends java.lang.CharSequence>` | `public T` | `eachMatch(CharSequence regex, Closure closure)` Processes each regex group matched substring of the given CharSequence.
    `<T extends java.lang.CharSequence>` | `public T` | `eachMatch(Pattern pattern, Closure closure)` Processes each regex group matched substring of the given pattern.
    `<T>` | `public T` | `eachWithIndex(Closure closure)` Iterates through an aggregate type or data structure, passing each item and the item's index (a counter starting at zero) to the given closure.
    `` | `public boolean` | `every(Closure predicate)` Used to determine if the given predicate closure is valid (i.e. returns `true` for all items in this data structure).
    `` | `public boolean` | `every()` Iterates over every element of a collection, and checks whether all elements are `true` according to the Groovy Truth.
    `` | `public Object` | `find(Closure closure)` Finds the first value matching the closure condition.
    `` | `public Object` | `find()` Finds the first item matching the IDENTITY Closure (i.e. matching Groovy truth).
    `` | `public List` | `findAll(Closure closure)` Finds all items matching the closure condition.
    `` | `public List` | `findAll()` Finds all items matching the IDENTITY Closure (i.e. matching Groovy truth).
    `` | `public int` | `findIndexOf(Closure condition)` Iterates over the elements of an aggregate of items and returns the index of the first item that matches the condition specified in the closure.
    `` | `public int` | `findIndexOf(int startIndex, Closure condition)` Iterates over the elements of an aggregate of items, starting from a specified startIndex, and returns the index of the first item that matches the condition specified in the closure.
    `` | `public List<Number>` | `findIndexValues(Closure condition)` Iterates over the elements of an aggregate of items and returns the index values of the items that match the condition specified in the closure.
    `` | `public List<Number>` | `findIndexValues(Number startIndex, Closure condition)` Iterates over the elements of an aggregate of items, starting from a specified startIndex, and returns the index values of the items that match the condition specified in the closure.
    `` | `public int` | `findLastIndexOf(Closure condition)` Iterates over the elements of an aggregate of items and returns the index of the last item that matches the condition specified in the closure.
    `` | `public int` | `findLastIndexOf(int startIndex, Closure condition)` Iterates over the elements of an aggregate of items, starting from a specified startIndex, and returns the index of the last item that matches the condition specified in the closure.
    `` | `public Object` | `findResult(Closure condition)` Treats the object as iterable, iterating through the values it represents and returns the first non-null result obtained from calling the closure, otherwise returns null.
    `` | `public Object` | `findResult()` Treats the object as iterable, iterating through the values it represents and returns the first non-null value, otherwise returns null.
    `` | `public Object` | `findResult(Object defaultResult, Closure condition)` Treats the object as iterable, iterating through the values it represents and returns the first non-null result obtained from calling the closure, otherwise returns the defaultResult.
    `` | `public Object` | `findResult(Object defaultResult)` Treats the object as iterable, iterating through the values it represents and returns the first non-null result, otherwise returns the defaultResult.
    `` | `public Object` | `getAt(String property)` Allows the subscript operator to be used to lookup dynamic property values.
    `` | `public MetaClass` | `getMetaClass()` Obtains a MetaClass for an object either from the registry or in the case of a GroovyObject from the object itself.
    `` | `public List<PropertyValue>` | `getMetaPropertyValues()` Retrieves the list of MetaProperty objects for 'self' and wraps it in a list of PropertyValue objects that additionally provide the value for each property of 'self'.
    `` | `public Map<String, Object>` | `getProperties()` Convenience method that calls Object.getMetaPropertyValues(self) and provides the data in form of simple key/value pairs, i.e. without type() information.
    `` | `public Collection` | `grep(Object filter)` Iterates over the collection of items which this Object represents and returns each item that matches the given filter - calling the `Object.isCase` method used by switch statements.
    `` | `public Collection` | `grep()` Iterates over the collection of items which this Object represents and returns each item that matches using the IDENTITY Closure as a filter - effectively returning all elements which satisfy Groovy truth.
    `` | `public MetaProperty` | `hasProperty(String name)`
    `<T, U>` | `public T` | `identity(Closure<T> closure)` Allows the closure to be called for the object reference self.
    `<T, V extends T>` | `public T` | `inject(Closure<V> closure)` Iterates through the given object, passing the first two elements to the closure.
    `<T>` | `public T` | `inject(BinaryOperator<T> operator)` Iterates through the given object, passing the first two elements to the operator.
    `<T, U extends T, V extends T>` | `public T` | `inject(U initialValue, Closure<V> closure)` Iterates through the given object, passing in the initial value to the closure along with the first item.
    `<U>` | `public U` | `inject(U initialValue, BiFunction<? super U, Object, ? extends U> function)` Iterates through the given object, passing in the initial value to the function along with the first item.
    `` | `public String` | `inspect()` Inspects returns the String that matches what would be typed into a terminal to create this object.
    `` | `public Object` | `invokeMethod(String method, Object arguments)` Provide a dynamic method invocation method which can be overloaded in classes to implement dynamic proxies easily.
    `` | `public boolean` | `is(Object other)` Identity check.
    `` | `public boolean` | `isCase(Object switchValue)` Method for overloading the behavior of the 'case' method in switch statements.
    `` | `public boolean` | `isNotCase(Object switchValue)` Since: 4.0.0
    `` | `public Iterator` | `iterator()` Creates an Iterator for the given Object by converting it to a Collection.
    `` | `public MetaClass` | `metaClass(Closure closure)` Sets/updates the metaclass for a given object to a closure.
    `` | `public void` | `print(Object value)` Print a value formatted Groovy style to self if it is a Writer, otherwise to the standard output stream.
    `` | `public void` | `print(PrintWriter out)` Print to a console in interactive format.
    `` | `public void` | `printf(String format, Object[] values)` Printf to the standard output stream.
    `` | `public void` | `printf(String format, Object arg)` Prints a formatted string using the specified format string and arguments.
    `` | `public void` | `println()` Print a linebreak to the standard output stream.
    `` | `public void` | `println(Object value)` Print a value formatted Groovy style (followed by a newline) to self if it is a Writer, otherwise to the standard output stream.
    `` | `public void` | `println(PrintWriter out)` Print to a console in interactive format.
    `` | `public void` | `putAt(String property, Object newValue)` Allows the subscript operator to be used to set dynamically named property values.
    `` | `public List<MetaMethod>` | `respondsTo(String name, Object[] argTypes)`
    `` | `public List<MetaMethod>` | `respondsTo(String name)`
    `` | `public void` | `setMetaClass(MetaClass metaClass)` Sets the metaclass for an object.
    `` | `public static void` | `sleep(Object self, long milliseconds)` Sleep for so many milliseconds, even if interrupted.
    `` | `public static void` | `sleep(Object self, long milliseconds, Closure onInterrupt)` Sleep for so many milliseconds, using a given closure for interrupt processing.
    `` | `public Collection` | `split(Closure closure)` Splits all items into two lists based on the closure condition.
    `` | `public String` | `sprintf(String format, Object[] values)` Sprintf to a string.
    `` | `public String` | `sprintf(String format, Object arg)` Returns a formatted string using the specified format string and arguments.
    `<T>` | `public Stream<T>` | `stream()` Returns a sequential Stream containing a single element.
    `<T>` | `public T` | `takeIf(Predicate<? super T> condition)` Returns this object if it satisfies the given predicate, or `null` otherwise.
    `<T, U>` | `public U` | `tap(Closure<T> closure)` Allows the closure to be called for the object reference self (similar to `with`) and always returns self.
    `` | `public String` | `toString()` Create a String representation of this object.
    `<T>` | `public T` | `use(Class categoryClass, Closure<T> closure)` Scoped use method
    `<T>` | `public T` | `use(List<Class> categoryClassList, Closure<T> closure)` Scoped use method with list of categories.
    `` | `public Object` | `use(Object[] array)` Allows you to use a list of categories, specifying the list as varargs.
    `<T, U>` | `public T` | `with(Closure<T> closure)` Allows the closure to be called for the object reference self.
    `<T, U extends T, V extends T>` | `public T` | `with(boolean returnIt, Closure<V> closure)` Allows the closure to be called for the object reference self.
    `<T, U extends java.io.Closeable>` | `public T` | `withCloseable(Closure<T> action)` Allows this closeable to be used within the closure, ensuring that it is closed once the closure has been executed and before this method returns.
    `<T, U extends java.lang.AutoCloseable>` | `public T` | `withCloseable(Closure<T> action)` Allows this AutoCloseable to be used within the closure, ensuring that it is closed once the closure has been executed and before this method returns.
    `` | `public Object` | `withMethodClosure(MethodClosure mc)` A utility method for calling a method closure on an object.
    `<T, U extends java.io.InputStream>` | `public T` | `withStream(Closure<T> closure)` Allows this input stream to be used within the closure, ensuring that it is flushed and closed before this method returns.
    `<T, U extends java.io.OutputStream>` | `public T` | `withStream(Closure<T> closure)` Passes this OutputStream to the closure, ensuring that the stream is closed after the closure returns, regardless of errors.
    `` | `public Object` | `withTraits(Class<?> traits)` Dynamically wraps an instance into something which implements the supplied trait classes.

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class Object` | `addShutdownHook, any, any, asBoolean, asType, clamp, clamp, collect, collect, collect, dump, each, eachMatch, eachMatch, eachWithIndex, every, every, find, find, findAll, findAll, findIndexOf, findIndexOf, findIndexValues, findIndexValues, findLastIndexOf, findLastIndexOf, findResult, findResult, findResult, findResult, getAt, getMetaClass, getMetaPropertyValues, getProperties, grep, grep, hasProperty, identity, inject, inject, inject, inject, inspect, invokeMethod, is, isCase, isNotCase, iterator, metaClass, print, print, printf, printf, println, println, println, putAt, respondsTo, respondsTo, setMetaClass, sleep, sleep, split, sprintf, sprintf, stream, takeIf, tap, toString, use, use, use, with, with, withCloseable, withCloseable, withMethodClosure, withStream, withStream, withTraits`

- - ### Method Detail

    - #### public void addShutdownHook(Closure closure)

      Allows the usage of addShutdownHook without getting the runtime first.

      Parameters:
        `closure` - the shutdown hook action
      Since:
        1.5.0

    - #### public boolean any()

      Iterates over the elements of a collection, and checks whether at least one element is true according to the Groovy Truth. Equivalent to self.any({element `->` element})

           assert [false, true].any()
           assert [0, 1].any()
           assert ![0, 0].any()

      Returns:
        true if any item in the collection matches the closure predicate
      Since:
        1.5.0

    - #### public boolean any(Closure predicate)

      Iterates over the contents of an object or collection, and checks whether a predicate is valid for at least one element.

           assert [1, 2, 3].any { it == 2 }
           assert ![1, 2, 3].any { it > 3 }

      Parameters:
        `predicate` - the closure predicate used for matching
      Returns:
        true if any iteration for the object matches the closure predicate
      Since:
        1.0

    - #### public boolean asBoolean()

      Coerce an object instance to a boolean value. An object is coerced to true if it's not null, to false if it is null.

      Returns:
        the boolean value
      Since:
        1.7.0

    - #### <T> public T asType(Class<T> type)

      Converts a given object to a type. This method is used through the "as" operator and is overloadable as any other operator.

      Parameters:
        `type` - the goal type
      Returns:
        the resulting object
      Since:
        1.0

    - #### <T extends java.lang.Comparable<? super T>> public T clamp(T lower, T upper)

      Constrains a Comparable value to lie within the inclusive range `[lower, upper]`. Returns `lower` if `self` is less than `lower`, `upper` if `self` is greater than `upper`, otherwise `self`.

           assert 10.clamp(1, 15) == 10
           assert 10.clamp(1, 5) == 5
           assert 10.clamp(12, 20) == 12
           assert 'a'.clamp('b', 'z') == 'b'

      throws:
        IllegalArgumentException if `lower` is greater than `upper`
      Parameters:
        `lower` - the inclusive lower bound
        `upper` - the inclusive upper bound
      Returns:
        the clamped value
      Since:
        6.0.0

    - #### <T extends java.lang.Comparable<? super T>> public T clamp(Range<T> range)

      Constrains a Comparable value to lie within the given Range.

           assert 10.clamp(12..20) == 12
           assert 10.clamp(1..5) == 5

      Parameters:
        `range` - a Range defining the inclusive bounds
      Returns:
        the clamped value
      Since:
        6.0.0

    - #### public Collection collect()

      Iterates through this aggregate Object transforming each item into a new value using Closure.IDENTITY as a transformer, basically returning a list of items copied from the original object.

          def obj = new Object(); assert obj.collect() == [obj]

      Returns:
        a Collection of the transformed values
      See Also:
        Closure.IDENTITY
      Since:
        1.8.5

    - #### <T> public List<T> collect(Closure<T> transform)

      Iterates through this aggregate Object transforming each item into a new value using the `transform` closure, returning a list of transformed values.

           def list = [1, 'a', 1.23, true ]
           def types = list.collect { it.class }
           assert types == [Integer, String, BigDecimal, Boolean]

      Parameters:
        `transform` - the closure used to transform each item of the aggregate object
      Returns:
        a List of the transformed values
      Since:
        1.0

    - #### <T, C extends java.util.Collection<T>> public C collect(C collector, Closure<? extends T> transform)

      Iterates through this aggregate Object transforming each item into a new value using the `transform` closure and adding it to the supplied `collector`.

      Parameters:
        `collector` - the Collection to which the transformed values are added
        `transform` - the closure used to transform each item of the aggregate object
      Returns:
        the collector with all transformed values added to it
      Since:
        1.0

    - #### public String dump()

      Generates a detailed dump string of an object showing its class, hashCode and all accessible fields.

           assert null.dump() == 'null'
           class Base {
             static String zero = ' '
             final String three = 'z'
           }
           class Pogo extends Base {
             public one = 'x'
             String two = 'y'
           }
           def text = new Pogo().dump()
           assert text ==~ /<Pogo@[0-9a-f]{1,8} one=x two=y three=z>/

      Returns:
        the dump representation
      Since:
        1.0

    - #### <T> public T each(Closure closure)

      Iterates through an aggregate type or data structure, passing each item to the given closure. Custom types may utilize this method by simply providing an "iterator()" method. The items returned from the resulting iterator will be passed to the closure.

           String result = ''
           ['a', 'b', 'c'].each{ result += it }
           assert result == 'abc'

      Parameters:
        `closure` - the closure applied on each element found
      Returns:
        the self Object
      Since:
        1.0

    - #### <T extends java.lang.CharSequence> public T eachMatch(CharSequence regex, Closure closure)

      Processes each regex group matched substring of the given CharSequence. If the closure parameter takes one argument, an array with all match groups is passed to it. If the closure takes as many arguments as there are match groups, then each parameter will be one match group.

      Parameters:
        `regex` - a Regex CharSequence
        `closure` - a closure with one parameter or as many parameters as groups
      Returns:
        the source CharSequence
      Since:
        1.8.2
      See Also:
        eachMatch(String,String,Closure)

    - #### <T extends java.lang.CharSequence> public T eachMatch(Pattern pattern, Closure closure)

      Processes each regex group matched substring of the given pattern. If the closure parameter takes one argument, an array with all match groups is passed to it. If the closure takes as many arguments as there are match groups, then each parameter will be one match group.

      Parameters:
        `pattern` - a regex Pattern
        `closure` - a closure with one parameter or as many parameters as groups
      Returns:
        the source CharSequence
      Since:
        1.8.2
      See Also:
        eachMatch(String,Pattern,Closure)

    - #### <T> public T eachWithIndex(Closure closure)

      Iterates through an aggregate type or data structure, passing each item and the item's index (a counter starting at zero) to the given closure.

           String result = ''
           ['a', 'b', 'c'].eachWithIndex{ letter, index -> result += "$index:$letter" }
           assert result == '0:a1:b2:c'

      Parameters:
        `closure` - a Closure to operate on each item
      Returns:
        the self Object
      Since:
        1.0

    - #### public boolean every(Closure predicate)

      Used to determine if the given predicate closure is valid (i.e. returns `true` for all items in this data structure). A simple example for a list:

          def list = [3,4,5]
           def greaterThanTwo = list.every { it > 2 }

      Parameters:
        `predicate` - the closure predicate used for matching
      Returns:
        true if every iteration of the object matches the closure predicate
      Since:
        1.0

    - #### public boolean every()

      Iterates over every element of a collection, and checks whether all elements are `true` according to the Groovy Truth. Equivalent to `self.every({element `->` element})`

           assert [true, true].every()
           assert [1, 1].every()
           assert ![1, 0].every()

      Returns:
        true if every item in the collection matches satisfies Groovy truth
      Since:
        1.5.0

    - #### public Object find(Closure closure)

      Finds the first value matching the closure condition.

           def numbers = [1, 2, 3]
           def result = numbers.find { it > 1}
           assert result == 2

      Parameters:
        `closure` - a closure condition
      Returns:
        the first Object found or null if none was found
      Since:
        1.0

    - #### public Object find()

      Finds the first item matching the IDENTITY Closure (i.e. matching Groovy truth).

      Example:

           def items = [null, 0, 0.0, false, '', [], 42, 43]
           assert items.find() == 42

      Returns:
        the first Object found or null if none was found
      Since:
        1.8.1
      See Also:
        Closure.IDENTITY

    - #### public List findAll(Closure closure)

      Finds all items matching the closure condition.

      Parameters:
        `closure` - a closure condition
      Returns:
        a List of the values found
      Since:
        1.6.0

    - #### public List findAll()

      Finds all items matching the IDENTITY Closure (i.e. matching Groovy truth).

      Example:

           def items = [1, 2, 0, false, true, '', 'foo', [], [4, 5], null]
           assert items.findAll() == [1, 2, true, 'foo', [4, 5]]

      Returns:
        a List of the truthy values
      Since:
        1.8.1
      See Also:
        Closure.IDENTITY

    - #### public int findIndexOf(Closure condition)

      Iterates over the elements of an aggregate of items and returns the index of the first item that matches the condition specified in the closure.

      Parameters:
        `condition` - the matching condition
      Returns:
        an integer that is the index of the first matched object or -1 if no match was found
      Since:
        1.0

    - #### public int findIndexOf(int startIndex, Closure condition)

      Iterates over the elements of an aggregate of items, starting from a specified startIndex, and returns the index of the first item that matches the condition specified in the closure. Example (aggregate is `ChronoUnit` enum values):

           import java.time.temporal.ChronoUnit
           def nameStartsWithM = { it.name().startsWith('M') }
           def first  = ChronoUnit.findIndexOf(nameStartsWithM)
           def second = ChronoUnit.findIndexOf(first + 1, nameStartsWithM)
           def third  = ChronoUnit.findIndexOf(second + 1, nameStartsWithM)
           Set units  = [first, second, third]
           assert !units.contains(-1) // should have found 3 of MICROS, MILLIS, MINUTES, MONTHS, ...
           assert units.size() == 3 // just check size so as not to rely on order

      Parameters:
        `startIndex` - start matching from this index
        `condition` - the matching condition
      Returns:
        an integer that is the index of the first matched object or -1 if no match was found
      Since:
        1.5.0

    - #### public List<Number> findIndexValues(Closure condition)

      Iterates over the elements of an aggregate of items and returns the index values of the items that match the condition specified in the closure.

      Parameters:
        `condition` - the matching condition
      Returns:
        a list of numbers corresponding to the index values of all matched objects
      Since:
        1.5.2

    - #### public List<Number> findIndexValues(Number startIndex, Closure condition)

      Iterates over the elements of an aggregate of items, starting from a specified startIndex, and returns the index values of the items that match the condition specified in the closure.

      Parameters:
        `startIndex` - start matching from this index
        `condition` - the matching condition
      Returns:
        a list of numbers corresponding to the index values of all matched objects
      Since:
        1.5.2

    - #### public int findLastIndexOf(Closure condition)

      Iterates over the elements of an aggregate of items and returns the index of the last item that matches the condition specified in the closure. Example (aggregate is `ChronoUnit` enum values):

           import java.time.temporal.ChronoUnit
           def nameStartsWithM = { it.name().startsWith('M') }
           def first = ChronoUnit.findIndexOf(nameStartsWithM)
           def last  = ChronoUnit.findLastIndexOf(nameStartsWithM)
           // should have found 2 unique index values for MICROS, MILLIS, MINUTES, MONTHS, ...
           assert first != -1 && last != -1 && first != last

      Parameters:
        `condition` - the matching condition
      Returns:
        an integer that is the index of the last matched object or -1 if no match was found
      Since:
        1.5.2

    - #### public int findLastIndexOf(int startIndex, Closure condition)

      Iterates over the elements of an aggregate of items, starting from a specified startIndex, and returns the index of the last item that matches the condition specified in the closure.

      Parameters:
        `startIndex` - start matching from this index
        `condition` - the matching condition
      Returns:
        an integer that is the index of the last matched object or -1 if no match was found
      Since:
        1.5.2

    - #### public Object findResult(Closure condition)

      Treats the object as iterable, iterating through the values it represents and returns the first non-null result obtained from calling the closure, otherwise returns null.

           int[] numbers = [1, 2, 3]
           assert numbers.findResult { if(it > 1) return it } == 2
           assert numbers.findResult { if(it > 4) return it } == null

      Parameters:
        `condition` - a closure that returns a non-null value to indicate that processing should stop and the value should be returned
      Returns:
        the first non-null result of the closure
      Since:
        1.7.5

    - #### public Object findResult()

      Treats the object as iterable, iterating through the values it represents and returns the first non-null value, otherwise returns null.

           class Foo {
               List items
               Iterator iterator() {
                   items.iterator()
               }
           }
           assert new Foo(items: [null, 2, 4]).findResult() == 2
           assert new Foo(items: [null, null]).findResult() == null

      Returns:
        the first non-null result of the closure
      Since:
        4.0.9

    - #### public Object findResult(Object defaultResult, Closure condition)

      Treats the object as iterable, iterating through the values it represents and returns the first non-null result obtained from calling the closure, otherwise returns the defaultResult.

           int[] numbers = [1, 2, 3]
           assert numbers.findResult(5) { if(it > 1) return it } == 2
           assert numbers.findResult(5) { if(it > 4) return it } == 5

      Parameters:
        `defaultResult` - an Object that should be returned if all closure results are null
        `condition` - a closure that returns a non-null value to indicate that processing should stop and the value should be returned
      Returns:
        the first non-null result of the closure, otherwise the default value
      Since:
        1.7.5

    - #### public Object findResult(Object defaultResult)

      Treats the object as iterable, iterating through the values it represents and returns the first non-null result, otherwise returns the defaultResult.

           class Foo {
               List items
               Iterator iterator() {
                   items.iterator()
               }
           }
           assert new Foo(items: [null, 2, 4]).findResult(5) == 2
           assert new Foo(items: [null, null]).findResult(5) == 5

      Parameters:
        `defaultResult` - an Object that should be returned if all elements are null
      Returns:
        the first non-null element, otherwise the default value
      Since:
        4.0.9

    - #### public Object getAt(String property)

      Allows the subscript operator to be used to lookup dynamic property values. `bean[somePropertyNameExpression]`. The normal property notation of groovy is neater and more concise but only works with compile-time known property names.

      Parameters:
        `property` - the property name of interest
      Returns:
        the property value
      Since:
        1.0

    - #### public MetaClass getMetaClass()

      Obtains a MetaClass for an object either from the registry or in the case of a GroovyObject from the object itself.

      Returns:
        The MetaClass
      Since:
        1.5.0

    - #### public List<PropertyValue> getMetaPropertyValues()

      Retrieves the list of MetaProperty objects for 'self' and wraps it in a list of PropertyValue objects that additionally provide the value for each property of 'self'.

      Returns:
        list of PropertyValue objects
      See Also:
        Expando.getMetaPropertyValues
      Since:
        1.0

    - #### public Map<String, Object> getProperties()

      Convenience method that calls Object.getMetaPropertyValues(self) and provides the data in form of simple key/value pairs, i.e. without type() information.

      Returns:
        meta properties as Map of key/value pairs
      Since:
        1.0

    - #### public Collection grep(Object filter)

      Iterates over the collection of items which this Object represents and returns each item that matches the given filter - calling the `Object.isCase` method used by switch statements. This method can be used with different kinds of filters like regular expressions, classes, ranges etc. Example:

           def list = ['a', 'b', 'aa', 'bc', 3, 4.5]
           assert list.grep( ~/a+/ )  == ['a', 'aa']
           assert list.grep( ~/../ )  == ['aa', 'bc']
           assert list.grep( Number ) == [ 3, 4.5 ]
           assert list.grep{ it.toString().size() == 1 } == [ 'a', 'b', 3 ]

      Parameters:
        `filter` - the filter to perform on the object (using the Object.isCase method)
      Returns:
        a collection of objects which match the filter
      Since:
        1.5.6

    - #### public Collection grep()

      Iterates over the collection of items which this Object represents and returns each item that matches using the IDENTITY Closure as a filter - effectively returning all elements which satisfy Groovy truth.

      Example:

           def items = [1, 2, 0, false, true, '', 'foo', [], [4, 5], null]
           assert items.grep() == [1, 2, true, 'foo', [4, 5]]

      Returns:
        a collection of objects which match the filter
      Since:
        1.8.1
      See Also:
        Closure.IDENTITY

    - #### public MetaProperty hasProperty(String name)

      Returns true of the implementing MetaClass has a property of the given name

      Note that this method will only return true for realised properties and does not take into account implementation of getProperty or propertyMissing

      Parameters:
        `name` - The name of the property of interest
      Returns:
        The found MetaProperty or null if it doesn't exist
      See Also:
        MetaObjectProtocol.hasProperty
      Since:
        1.6.1

    - #### <T, U> public T identity(Closure<T> closure)

      Allows the closure to be called for the object reference self.

      Parameters:
        `closure` - the closure to call on the object
      Returns:
        result of calling the closure
      See Also:
        with(Object, Closure)
      Since:
        1.0

    - #### <T, V extends T> public T inject(Closure<V> closure)

      Iterates through the given object, passing the first two elements to the closure. The result is passed back (injected) to the closure along with the third element and so on until all elements have been consumed.

      throws:
        NoSuchElementException if the iterator is empty
      Parameters:
        `closure` - a closure
      Returns:
        the result of the last closure call
      See Also:
        inject(Object, Object, Closure)
      Since:
        1.8.7

    - #### <T> public T inject(BinaryOperator<T> operator)

      Iterates through the given object, passing the first two elements to the operator. The result is passed back (injected) to the operator along with the third element and so on until all elements have been consumed. A "fat-free" variant of Object.inject accepting a BinaryOperator.

      throws:
        NoSuchElementException if the iterator is empty
      Parameters:
        `operator` - a binary operator combining the running result with each element
      Returns:
        the result of the last operator call
      Since:
        6.0.0

    - #### <T, U extends T, V extends T> public T inject(U initialValue, Closure<V> closure)

      Iterates through the given object, passing in the initial value to the closure along with the first item. The result is passed back (injected) into the closure along with the second item. The new result is injected back into the closure along with the third item and so on until further iteration is not possible.

      Also known as `foldLeft` or `reduce` in functional parlance.

      Parameters:
        `initialValue` - some initial value
        `closure` - a closure
      Returns:
        the result of the last closure call
      See Also:
        inject(Iterator, Object, Closure)
      Since:
        1.5.0

    - #### <U> public U inject(U initialValue, BiFunction<? super U, Object, ? extends U> function)

      Iterates through the given object, passing in the initial value to the function along with the first item. The result is passed back (injected) into the function along with the second item and so on until all elements have been consumed. A "fat-free" variant of Object.inject accepting a BiFunction.

      Parameters:
        `initialValue` - some initial value
        `function` - a function combining the running result with each element
      Returns:
        the result of the last function call
      Since:
        6.0.0

    - #### public String inspect()

      Inspects returns the String that matches what would be typed into a terminal to create this object.

      Returns:
        a String that matches what would be typed into a terminal to create this object. e.g. [1, 'hello'].inspect() `->` [1, 'hello']
      Since:
        1.0

    - #### public Object invokeMethod(String method, Object arguments)

      Provide a dynamic method invocation method which can be overloaded in classes to implement dynamic proxies easily.

      Parameters:
        `method` - the name of the method to call
        `arguments` - the arguments to use
      Returns:
        the result of the method call
      Since:
        1.0

    - #### public boolean is(Object other)

      Identity check. Since == is overridden in Groovy with the meaning of equality we need some fallback to check for object identity. Invoke using the 'is' method, like so: `def same = this.is(that)`

      Parameters:
        `other` - an object to compare identity with
      Returns:
        true if self and other are both references to the same instance, false otherwise
      Since:
        1.0

    - #### public boolean isCase(Object switchValue)

      Method for overloading the behavior of the 'case' method in switch statements. The default implementation handles arrays types but otherwise simply delegates to Object#equals, but this may be overridden for other types. In this example:

           switch( a ) {
             case b: //some code
           }

      "some code" is called when `b.isCase( a )` returns `true`.
      Parameters:
        `switchValue` - the switch value
      Returns:
        true if the switchValue is deemed to be equal to the caseValue
      Since:
        1.0

    - #### public boolean isNotCase(Object switchValue)

      Since:
        4.0.0

    - #### public Iterator iterator()

      Creates an Iterator for the given Object by converting it to a Collection.

      Returns:
        an Iterator for the given Object
      See Also:
        DefaultTypeTransformation.asCollection
      Since:
        1.0

    - #### public MetaClass metaClass(Closure closure)

      Sets/updates the metaclass for a given object to a closure.

      throws:
        GroovyRuntimeException if the metaclass can't be set for this object
      Parameters:
        `closure` - the closure representing the new metaclass
      Returns:
        the new metaclass value
      Since:
        1.6.0

    - #### public void print(Object value)

      Print a value formatted Groovy style to self if it is a Writer, otherwise to the standard output stream.

      Parameters:
        `value` - the value to print
      Since:
        1.0

    - #### public void print(PrintWriter out)

      Print to a console in interactive format.

      Parameters:
        `out` - the PrintWriter used for printing
      Since:
        1.0

    - #### public void printf(String format, Object[] values)

      Printf to the standard output stream. Formatting is locale-sensitive and uses Locale.getDefault. To format for an explicit locale, print the result of String.format instead.

      Parameters:
        `format` - a format string
        `values` - values referenced by the format specifiers in the format string
      See Also:
        String.format
      Since:
        1.0

    - #### public void printf(String format, Object arg)

      Prints a formatted string using the specified format string and arguments.

      Examples:

               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 ])

               ( 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[] ) }

      Formatting is locale-sensitive and uses Locale.getDefault. To format for an explicit locale, print the result of String.format instead.
      Parameters:
        `format` - A format string
        `arg` - Argument which is referenced by the format specifiers in the format string. The type of `arg` should be one of Object[], List, int[], short[], byte[], char[], boolean[], long[], float[], or double[].
      See Also:
        String.format
      Since:
        1.0

    - #### public void println()

      Print a linebreak to the standard output stream.

      Since:
        1.0

    - #### public void println(Object value)

      Print a value formatted Groovy style (followed by a newline) to self if it is a Writer, otherwise to the standard output stream.

      Parameters:
        `value` - the value to print
      Since:
        1.0

    - #### public void println(PrintWriter out)

      Print to a console in interactive format.

      Parameters:
        `out` - the PrintWriter used for printing
      Since:
        1.0

    - #### public void putAt(String property, Object newValue)

      Allows the subscript operator to be used to set dynamically named property values. `bean[somePropertyNameExpression] = foo`. The normal property notation of groovy is neater and more concise but only works with property names which are known at compile time.

      Parameters:
        `property` - the name of the property to set
        `newValue` - the value to set
      Since:
        1.0

    - #### public List<MetaMethod> respondsTo(String name, Object[] argTypes)

      Returns an object satisfying Groovy truth if the implementing MetaClass responds to a method with the given name and arguments types.

      Note that this method's return value is based on realised methods and does not take into account objects or classes that implement invokeMethod or methodMissing

      This method is "safe" in that it will always return a value and never throw an exception

      Parameters:
        `name` - The name of the method of interest
        `argTypes` - The argument types to match against
      Returns:
        A List of MetaMethods matching the argument types which will be empty if no matching methods exist
      See Also:
        MetaObjectProtocol.respondsTo
      Since:
        1.6.0

    - #### public List<MetaMethod> respondsTo(String name)

      Returns an object satisfying Groovy truth if the implementing MetaClass responds to a method with the given name regardless of the arguments.

      Note that this method's return value is based on realised methods and does not take into account objects or classes that implement invokeMethod or methodMissing

      This method is "safe" in that it will always return a value and never throw an exception

      Parameters:
        `name` - The name of the method of interest
      Returns:
        A List of MetaMethods matching the given name or an empty list if no matching methods exist
      See Also:
        MetaObjectProtocol.respondsTo
      Since:
        1.6.1

    - #### public void setMetaClass(MetaClass metaClass)

      Sets the metaclass for an object.

      Parameters:
        `metaClass` - the new metaclass value
      Since:
        1.6.0

    - #### public static void sleep(Object self, long milliseconds)

      Sleep for so many milliseconds, even if interrupted.

      Parameters:
        `self` - placeholder variable used by Groovy categories; ignored for default static methods
        `milliseconds` - the number of milliseconds to sleep
      Since:
        1.0

    - #### public static void sleep(Object self, long milliseconds, Closure onInterrupt)

      Sleep for so many milliseconds, using a given closure for interrupt processing.

      Parameters:
        `self` - placeholder variable used by Groovy categories; ignored for default static methods
        `milliseconds` - the number of milliseconds to sleep
        `onInterrupt` - interrupt handler, InterruptedException is passed to the Closure as long as it returns false, the sleep continues
      Since:
        1.0

    - #### public Collection split(Closure closure)

      Splits all items into two lists based on the closure condition. The first list contains all items matching the closure expression. The second list all those that don't.

      Parameters:
        `closure` - a closure condition
      Returns:
        a List whose first item is the accepted values and whose second item is the rejected values
      Since:
        1.6.0

    - #### public String sprintf(String format, Object[] values)

      Sprintf to a string. Formatting is locale-sensitive and uses Locale.getDefault. To format for an explicit locale, use String.format instead.

      Parameters:
        `format` - a format string
        `values` - values referenced by the format specifiers in the format string
      Returns:
        the resulting formatted string
      See Also:
        String.format
      Since:
        1.5.0

    - #### public String sprintf(String format, Object arg)

      Returns a formatted string using the specified format string and arguments. Formatting is locale-sensitive and uses Locale.getDefault. To format for an explicit locale, use String.format instead.

      Parameters:
        `format` - A format string
        `arg` - Argument which is referenced by the format specifiers in the format string. The type of `arg` should be one of Object[], List, int[], short[], byte[], char[], boolean[], long[], float[], or double[].
      Returns:
        the resulting printf'd string
      See Also:
        String.format
      Since:
        1.5.0

    - #### <T> public Stream<T> stream()

      Returns a sequential Stream containing a single element.

           def item = 'string'
           assert item.stream().toList() == ['string']
           assert item.stream().findFirst().isPresent()

      Since:
        3.0.0

    - #### <T> public T takeIf(Predicate<? super T> condition)

      Returns this object if it satisfies the given predicate, or `null` otherwise. Useful for guarding a value through a chain, particularly with the Elvis or safe-navigation operators.

           assert 'hello'.takeIf{ it.startsWith('h') } == 'hello'
           assert 'hello'.takeIf{ it.startsWith('z') } == null
           assert ('input'.takeIf{ it.startsWith('http') } ?: "https://input") == 'https://input'
           assert [1, 2, 3].takeIf{ !it.isEmpty() }?.size() == 3
           assert [].takeIf{ !it.isEmpty() }?.size() == null

      The predicate is invoked with the receiver as its argument; the receiver is not used as a delegate. The receiver is passed through to the predicate unchanged, including when it is `null`.
      Parameters:
        `condition` - the predicate applied to `self`
      Returns:
        `self` if `condition.test(self)` is `true`, otherwise `null`
      Since:
        6.0.0

    - #### <T, U> public U tap(Closure<T> closure)

      Allows the closure to be called for the object reference self (similar to `with`) and always returns self.

      Any method invoked inside the closure will first be invoked on the self reference. For instance, the following method calls to the append() method are invoked on the StringBuilder instance:

           def b = new StringBuilder().tap {
             append('foo')
             append('bar')
           }
           assert b.toString() == 'foobar'

      This is commonly used to simplify object creation, such as this example:

           def p = new Person().tap {
             firstName = 'John'
             lastName = 'Doe'
           }

      Parameters:
        `closure` - the closure to call on the object
      Returns:
        self
      See Also:
        with(Object, boolean, Closure)
        with(Object, Closure)
      Since:
        2.5.0

    - #### public String toString()

      Create a String representation of this object.

      Returns:
        a string.
      Since:
        1.0

    - #### <T> public T use(Class categoryClass, Closure<T> closure)

      Scoped use method

      Parameters:
        `categoryClass` - a category class to use
        `closure` - the closure to invoke with the category in place
      Returns:
        the value returned from the closure
      Since:
        1.0

    - #### <T> public T use(List<Class> categoryClassList, Closure<T> closure)

      Scoped use method with list of categories.

      Parameters:
        `categoryClassList` - a list of category classes
        `closure` - the closure to invoke with the categories in place
      Returns:
        the value returned from the closure
      Since:
        1.0

    - #### public Object use(Object[] array)

      Allows you to use a list of categories, specifying the list as varargs. `use(CategoryClass1, CategoryClass2) { ... }` This method saves having to wrap the category classes in a list.

      Parameters:
        `array` - a list of category classes and a Closure
      Returns:
        the value returned from the closure
      Since:
        1.0

    - #### <T, U> public T with(Closure<T> closure)

      Allows the closure to be called for the object reference self.

      Any method invoked inside the closure will first be invoked on the self reference. For instance, the following method calls to the append() method are invoked on the StringBuilder instance:

           def b = new StringBuilder().with {
             append('foo')
             append('bar')
             return it
           }
           assert b.toString() == 'foobar'

      This is commonly used to simplify object creation, such as this example:

           def p = new Person().with {
             firstName = 'John'
             lastName = 'Doe'
             return it
           }

      The other typical usage, uses the self object while creating some value:

           def fullName = person.with{ "$firstName $lastName" }

      Parameters:
        `closure` - the closure to call on the object
      Returns:
        result of calling the closure
      See Also:
        with(Object, boolean, Closure)
        tap(Object, Closure)
      Since:
        1.5.0

    - #### <T, U extends T, V extends T> public T with(boolean returnIt, Closure<V> closure)

      Allows the closure to be called for the object reference self.

      Any method invoked inside the closure will first be invoked on the self reference. For example, the following method calls to the append() method are invoked on the StringBuilder instance and then, because 'returning' is true, the self instance is returned:

           def b = new StringBuilder().with(true) {
             append('foo')
             append('bar')
           }
           assert b.toString() == 'foobar'

      The returning parameter is commonly set to true when using with to simplify object creation, such as this example:

           def p = new Person().with(true) {
             firstName = 'John'
             lastName = 'Doe'
           }

      Alternatively, 'tap' is an alias for 'with(true)', so that method can be used instead. The other main use case for with is when returning a value calculated using self as shown here:

           def fullName = person.with(false){ "$firstName $lastName" }

      Alternatively, 'with' is an alias for 'with(false)', so the boolean parameter can be omitted instead.
      Parameters:
        `returnIt` - if true, return the self object; otherwise, the result of calling the closure
        `closure` - the closure to call on the object
      Returns:
        the self object or the result of calling the closure depending on `returnIt`
      See Also:
        with(Object, Closure)
        tap(Object, Closure)
      Since:
        2.5.0

    - #### <T, U extends java.io.Closeable> public T withCloseable(Closure<T> action)

      Allows this closeable to be used within the closure, ensuring that it is closed once the closure has been executed and before this method returns.

      As with the try-with-resources statement, if multiple exceptions are thrown the exception from the closure will be returned and the exception from closing will be added as a suppressed exception.

      throws:
        IOException if an IOException occurs.
      Parameters:
        `action` - the closure taking the Closeable as parameter
      Returns:
        the value returned by the closure
      Since:
        2.4.0

    - #### <T, U extends java.lang.AutoCloseable> public T withCloseable(Closure<T> action)

      Allows this AutoCloseable to be used within the closure, ensuring that it is closed once the closure has been executed and before this method returns.

      As with the try-with-resources statement, if multiple exceptions are thrown the exception from the closure will be returned and the exception from closing will be added as a suppressed exception.

      throws:
        Exception if an Exception occurs.
      Parameters:
        `action` - the closure taking the AutoCloseable as parameter
      Returns:
        the value returned by the closure
      Since:
        2.5.0

    - #### public Object withMethodClosure(MethodClosure mc)

      A utility method for calling a method closure on an object.

      Parameters:
        `mc` - the method closure
      Returns:
        the result of calling the method closure
      Since:
        5.0.0

    - #### <T, U extends java.io.InputStream> public T withStream(Closure<T> closure)

      Allows this input stream to be used within the closure, ensuring that it is flushed and closed before this method returns.

      throws:
        IOException if an IOException occurs.
      Parameters:
        `closure` - the closure that the stream is passed into
      Returns:
        the value returned by the closure
      Since:
        1.5.2

    - #### <T, U extends java.io.OutputStream> public T withStream(Closure<T> closure)

      Passes this OutputStream to the closure, ensuring that the stream is closed after the closure returns, regardless of errors.

      throws:
        IOException if an IOException occurs.
      Parameters:
        `closure` - the closure that the stream is passed into
      Returns:
        the value returned by the closure
      Since:
        1.5.2

    - #### public Object withTraits(Class<?> traits)

      Dynamically wraps an instance into something which implements the supplied trait classes. It is guaranteed that the returned object will implement the trait interfaces, but the original type of the object is lost (replaced with a proxy).

      Parameters:
        `traits` - a list of trait classes
      Returns:
        a proxy implementing the trait interfaces