Package: org.codehaus.groovy.runtime.typehandling

## [Java] Class DefaultTypeTransformation

- org.codehaus.groovy.runtime.typehandling.DefaultTypeTransformation

-     public class DefaultTypeTransformation
      extends Object

  Class providing various type conversions, coercions and boxing/unboxing operations.

  Since:
    Groovy 1.8.0

- - ### Field Summary

    Fields
    Modifiers | Name | Description
    --- | --- | ---
    `protected static Object[]` | `EMPTY_ARGUMENTS` | Empty array constant for backwards compatibility.
    `protected static BigInteger` | `ONE_NEG` | BigInteger constant representing negative one, for backwards compatibility.

  - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `public static Collection` | `arrayAsCollection(Object value)` Converts an array (including primitive arrays) to a Collection.
    `<T>` | `public static Collection<T>` | `arrayAsCollection(T[] value)` Converts an object array to a Collection backed by `Arrays.asList`.
    `` | `public static Object` | `asArray(Object object, Class type)` Converts an object to an array of the specified target array type.
    `<T>` | `public static Collection<T>` | `asCollection(T[] value)` Converts a generic typed array to a typed Collection.
    `` | `public static Collection` | `asCollection(Object value)` Converts an object to a Collection.
    `` | `public static boolean` | `booleanUnbox(Object value)` Unboxes an object to a primitive `boolean` value.
    `` | `public static Object` | `box(boolean value)` Boxes a primitive `boolean` value into a `Boolean` wrapper object.
    `` | `public static Object` | `box(byte value)` Boxes a primitive `byte` value into a `Byte` wrapper object.
    `` | `public static Object` | `box(char value)` Boxes a primitive `char` value into a `Character` wrapper object.
    `` | `public static Object` | `box(short value)` Boxes a primitive `short` value into a `Short` wrapper object.
    `` | `public static Object` | `box(int value)` Boxes a primitive `int` value into an `Integer` wrapper object.
    `` | `public static Object` | `box(long value)` Boxes a primitive `long` value into a `Long` wrapper object.
    `` | `public static Object` | `box(float value)` Boxes a primitive `float` value into a `Float` wrapper object.
    `` | `public static Object` | `box(double value)` Boxes a primitive `double` value into a `Double` wrapper object.
    `` | `public static byte` | `byteUnbox(Object value)` Unboxes an object to a primitive `byte` value.
    `` | `public static boolean` | `castToBoolean(Object object)` Method used for coercing an object to a boolean value, thanks to an `asBoolean()` method added on types.
    `` | `public static char` | `castToChar(Object object)` Attempts to coerce an object to a `char` value (as a Character wrapper).
    `` | `public static Number` | `castToNumber(Object object)` Attempts to coerce an object to a `Number`.
    `` | `public static Number` | `castToNumber(Object object, Class type)` Attempts to coerce an object to a `Number` of a specific target type.
    `` | `public static Object` | `castToType(Object object, Class type)` Performs a comprehensive type cast/coercion of an object to a target class.
    `` | `public static Object` | `castToVargsArray(Object[] origin, int firstVargsPos, Class<?> arrayType)` Converts an array of arguments to a varargs array of the specified type.
    `` | `public static char` | `charUnbox(Object value)` Unboxes an object to a primitive `char` value.
    `` | `public static boolean` | `compareArrayEqual(Object left, Object right)` Compares two arrays element-wise for equality.
    `` | `public static boolean` | `compareEqual(Object left, Object right)` Compares two objects for equality, handling nulls and type coercion.
    `` | `public static int` | `compareTo(Object left, Object right)` Compares the two objects handling nulls gracefully and performing numeric type coercion if required
    `` | `public static boolean[]` | `convertToBooleanArray(Object a)`
    `` | `public static byte[]` | `convertToByteArray(Object a)`
    `` | `public static char[]` | `convertToCharArray(Object a)`
    `` | `public static double[]` | `convertToDoubleArray(Object a)`
    `` | `public static float[]` | `convertToFloatArray(Object a)`
    `` | `public static int[]` | `convertToIntArray(Object a)`
    `` | `public static long[]` | `convertToLongArray(Object a)`
    `` | `public static Object` | `convertToPrimitiveArray(Object a, Class type)`
    `` | `public static short[]` | `convertToShortArray(Object a)`
    `` | `public static double` | `doubleUnbox(Object value)` Unboxes an object to a primitive `double` value.
    `` | `public static float` | `floatUnbox(Object value)` Unboxes an object to a primitive `float` value.
    `` | `public static Character` | `getCharFromSizeOneString(Object value)`
    `` | `public static int` | `intUnbox(Object value)` Unboxes an object to a primitive `int` value.
    `` | `public static boolean` | `isEnumSubclass(Object value)` Determines whether the value object is a Class object representing a subclass of java.lang.Enum.
    `` | `public static long` | `longUnbox(Object value)` Unboxes an object to a primitive `long` value.
    `` | `public static Object[]` | `primitiveArrayBox(Object array)` Boxes a primitive array to an object array.
    `` | `public static List` | `primitiveArrayToList(Object array)` Allows conversion of arrays into a mutable List
    `` | `public static List` | `primitiveArrayToUnmodifiableList(Object array)` Allows conversion of arrays into an immutable List view
    `` | `public static short` | `shortUnbox(Object value)` Unboxes an object to a primitive `short` value.

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class Object` | `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### @Deprecated(forRemoval = true, since = "5.0.0")
      protected static final Object[] EMPTY_ARGUMENTS

      Empty array constant for backwards compatibility.

      deprecated:
        since 5.0.0

    - #### @Deprecated(forRemoval = true, since = "5.0.0")
      protected static final BigInteger ONE_NEG

      BigInteger constant representing negative one, for backwards compatibility.

      deprecated:
        since 5.0.0

  - ### Method Detail

    - #### public static Collection arrayAsCollection(Object value)

      Converts an array (including primitive arrays) to a Collection.

      Parameters:
        `value` - an array (primitive or object array)
      Returns:
        a Collection backed by the array elements

    - #### <T> public static Collection<T> arrayAsCollection(T[] value)

      Converts an object array to a Collection backed by `Arrays.asList`.

      Type Parameters:
        `T` - the element type
      Parameters:
        `value` - an object array
      Returns:
        a Collection (mutable list) backed by the array

    - #### public static Object asArray(Object object, Class type)

      Converts an object to an array of the specified target array type.

      Handles direct assignment if already correct type, stream conversions (IntStream, LongStream, DoubleStream), and generic collection to array conversions with element type casting.

      throws:
        ClassCastException if array element conversion is not possible
      Parameters:
        `object` - the object to convert (Collection, Stream, or already an array)
        `type` - the target array type
      Returns:
        an array of the target type with elements converted and cast as needed

    - #### <T> public static Collection<T> asCollection(T[] value)

      Converts a generic typed array to a typed Collection.

      Type Parameters:
        `T` - the element type
      Parameters:
        `value` - the typed array to convert
      Returns:
        a Collection backed by the array elements

    - #### public static Collection asCollection(Object value)

      Converts an object to a Collection.

      Handles the following conversions:

      - null → empty list
      - Collection → returned as-is
      - Map → collection of entry set
      - array → collection backed by array
      - BaseStream (IntStream, etc.) → list via StreamGroovyMethods
      - String/GString → list of characters
      - Iterable → list via DefaultGroovyMethods
      - Optional → singleton or empty set
      - Enum Class → list of enum constants
      - File → list of lines
      - MethodClosure → list via adapter
      - Other → singleton collection containing the object
      throws:
        GroovyRuntimeException if File reading fails
      Parameters:
        `value` - the object to convert (may be null)
      Returns:
        a Collection representing the object's elements

    - #### @GroovyABI(since = "1.8.0")
      public static boolean booleanUnbox(Object value)

      Unboxes an object to a primitive `boolean` value.

      Uses castToBoolean(Object) to perform the coercion.

      Parameters:
        `value` - the object to unbox (may be null for false, Boolean, or any object with asBoolean())
      Returns:
        the boolean value

    - #### @Deprecated(since = "2.3.0")
      @GroovyABI(since = "1.8.0")
      public static Object box(boolean value)

      Boxes a primitive `boolean` value into a `Boolean` wrapper object.

      deprecated:
        since 2.3.0 - Java's auto-boxing is sufficient for this operation
      Parameters:
        `value` - the boolean value to box
      Returns:
        `Boolean.TRUE` or `Boolean.FALSE`

    - #### @Deprecated(since = "2.3.0")
      @GroovyABI(since = "1.8.0")
      public static Object box(byte value)

      Boxes a primitive `byte` value into a `Byte` wrapper object.

      deprecated:
        since 2.3.0 - Java's auto-boxing is sufficient for this operation
      Parameters:
        `value` - the byte value to box
      Returns:
        a Byte object with the specified value

    - #### @Deprecated(since = "2.3.0")
      @GroovyABI(since = "1.8.0")
      public static Object box(char value)

      Boxes a primitive `char` value into a `Character` wrapper object.

      deprecated:
        since 2.3.0 - Java's auto-boxing is sufficient for this operation
      Parameters:
        `value` - the char value to box
      Returns:
        a Character object with the specified value

    - #### @Deprecated(since = "2.3.0")
      @GroovyABI(since = "1.8.0")
      public static Object box(short value)

      Boxes a primitive `short` value into a `Short` wrapper object.

      deprecated:
        since 2.3.0 - Java's auto-boxing is sufficient for this operation
      Parameters:
        `value` - the short value to box
      Returns:
        a Short object with the specified value

    - #### @Deprecated(since = "2.3.0")
      @GroovyABI(since = "1.8.0")
      public static Object box(int value)

      Boxes a primitive `int` value into an `Integer` wrapper object.

      deprecated:
        since 2.3.0 - Java's auto-boxing is sufficient for this operation
      Parameters:
        `value` - the int value to box
      Returns:
        an Integer object with the specified value

    - #### @Deprecated(since = "2.3.0")
      @GroovyABI(since = "1.8.0")
      public static Object box(long value)

      Boxes a primitive `long` value into a `Long` wrapper object.

      deprecated:
        since 2.3.0 - Java's auto-boxing is sufficient for this operation
      Parameters:
        `value` - the long value to box
      Returns:
        a Long object with the specified value

    - #### @Deprecated(since = "2.3.0")
      @GroovyABI(since = "1.8.0")
      public static Object box(float value)

      Boxes a primitive `float` value into a `Float` wrapper object.

      deprecated:
        since 2.3.0 - Java's auto-boxing is sufficient for this operation
      Parameters:
        `value` - the float value to box
      Returns:
        a Float object with the specified value

    - #### @Deprecated(since = "2.3.0")
      @GroovyABI(since = "1.8.0")
      public static Object box(double value)

      Boxes a primitive `double` value into a `Double` wrapper object.

      deprecated:
        since 2.3.0 - Java's auto-boxing is sufficient for this operation
      Parameters:
        `value` - the double value to box
      Returns:
        a Double object with the specified value

    - #### @GroovyABI(since = "1.8.0")
      public static byte byteUnbox(Object value)

      Unboxes an object to a primitive `byte` value.

      Converts the object to a `Number` and then extracts its byte value.

      throws:
        GroovyCastException if the object cannot be converted to a number
      Parameters:
        `value` - the object to unbox (typically a wrapper object or string representation)
      Returns:
        the byte value

    - #### public static boolean castToBoolean(Object object)

      Method used for coercing an object to a boolean value, thanks to an `asBoolean()` method added on types.

      Parameters:
        `object` - to coerce to a boolean value
      Returns:
        a boolean value

    - #### @Deprecated(since = "2.3.0")
      public static char castToChar(Object object)

      Attempts to coerce an object to a `char` value (as a Character wrapper).

      Accepts Character objects, Numbers (converted via intValue), or Strings of length 1.

      throws:
        GroovyCastException if the object cannot be converted to char
      deprecated:
        since 2.3.0 - use ShortTypeHandling.castToChar instead
      Parameters:
        `object` - the object to coerce (Character, Number, or String)
      Returns:
        a Character with the coerced value

    - #### public static Number castToNumber(Object object)

      Attempts to coerce an object to a `Number`.

      If the object is already a Number, it is returned as-is. Characters are converted to their numeric code point. Strings of length 1 are converted to their character code point. GStrings are converted to String first, then processed.

      throws:
        GroovyCastException if the object cannot be converted to a number
      Parameters:
        `object` - the object to coerce (Number, Character, GString, or String)
      Returns:
        a Number representation of the object

    - #### public static Number castToNumber(Object object, Class type)

      Attempts to coerce an object to a `Number` of a specific target type.

      If the object is already a Number, it is returned as-is. Characters are converted to their numeric code point. Strings of length 1 are converted to their character code point. GStrings are converted to String first, then processed.

      throws:
        GroovyCastException if the object cannot be converted to a number
      Parameters:
        `object` - the object to coerce (Number, Character, GString, or String)
        `type` - the target numeric type (used for error reporting)
      Returns:
        a Number representation of the object

    - #### public static Object castToType(Object object, Class type)

      Performs a comprehensive type cast/coercion of an object to a target class.

      Handles the following conversions:

      - Primitive types (delegates to castToPrimitive)
      - null and Object.class (returns as-is)
      - Already compatible types (returns as-is)
      - Array types (delegates to asArray)
      - Enum types (delegates to ShortTypeHandling)
      - Collection types (delegates to continueCastOnCollection)
      - String type (uses FormatHelper)
      - Boolean type (uses castToBoolean)
      - Character type (delegates to ShortTypeHandling)
      - Class type (delegates to ShortTypeHandling)
      - Number types (delegates to continueCastOnNumber)
      throws:
        ClassCastException or GroovyCastException if casting is not possible
      Parameters:
        `object` - the object to cast (may be null)
        `type` - the target type to cast to
      Returns:
        an object of the target type, or null if input is null and type is not primitive

    - #### @GroovyABI(since = "2.4.0")
      public static Object castToVargsArray(Object[] origin, int firstVargsPos, Class<?> arrayType)

      Converts an array of arguments to a varargs array of the specified type.

      Handles conversion of remaining arguments starting from the specified position into a properly typed array. If the argument at the start position is already the target array type and it's the only remaining argument, returns it unchanged. Otherwise, creates a new array with type-converted elements.

      Parameters:
        `origin` - the original array of arguments
        `firstVargsPos` - the index of the first varargs element
        `arrayType` - the target array type
      Returns:
        an array of the specified type containing the varargs elements

    - #### @GroovyABI(since = "1.8.0")
      public static char charUnbox(Object value)

      Unboxes an object to a primitive `char` value.

      Returns the null character (`'\u0000'`) if the value is null. Otherwise delegates to ShortTypeHandling.castToChar.

      throws:
        GroovyCastException if the object cannot be converted to char
      Parameters:
        `value` - the object to unbox (may be null, Character, Number, or String)
      Returns:
        the char value, or null character if value is null

    - #### public static boolean compareArrayEqual(Object left, Object right)

      Compares two arrays element-wise for equality.

      Performs element-by-element comparison of two arrays using compareEqual(Object, Object). Returns true only if both arrays have the same length and all corresponding elements are equal. Null arrays are handled according to standard null comparison semantics.

      Parameters:
        `left` - the first array to compare
        `right` - the second array to compare
      Returns:
        true if the arrays are equal (same length and equal elements), false otherwise

    - #### public static boolean compareEqual(Object left, Object right)

      Compares two objects for equality, handling nulls and type coercion.

      Performs semantic equality comparison with proper handling of null values, null objects, Comparable types, and arrays. Applies numeric type coercion when appropriate.

      Parameters:
        `left` - the first object to compare
        `right` - the second object to compare
      Returns:
        true if the objects are equal, false otherwise

    - #### public static int compareTo(Object left, Object right)

      Compares the two objects handling nulls gracefully and performing numeric type coercion if required

    - #### @Deprecated(since = "2.3.0")
      public static boolean[] convertToBooleanArray(Object a)

    - #### @Deprecated(since = "2.3.0")
      public static byte[] convertToByteArray(Object a)

    - #### @Deprecated(since = "2.3.0")
      public static char[] convertToCharArray(Object a)

    - #### @Deprecated(since = "2.3.0")
      public static double[] convertToDoubleArray(Object a)

    - #### @Deprecated(since = "2.3.0")
      public static float[] convertToFloatArray(Object a)

    - #### @Deprecated(since = "2.3.0")
      public static int[] convertToIntArray(Object a)

    - #### @Deprecated(since = "2.3.0")
      public static long[] convertToLongArray(Object a)

    - #### @Deprecated(since = "2.3.0")
      public static Object convertToPrimitiveArray(Object a, Class type)

    - #### @Deprecated(since = "2.3.0")
      public static short[] convertToShortArray(Object a)

    - #### @GroovyABI(since = "1.8.0")
      public static double doubleUnbox(Object value)

      Unboxes an object to a primitive `double` value.

      Returns `Double.NaN` if the value is null. Otherwise converts the object to a `Number` and extracts its double value.

      throws:
        GroovyCastException if the object cannot be converted to a number
      Parameters:
        `value` - the object to unbox (typically a wrapper object or string representation, may be null)
      Returns:
        the double value, or NaN if value is null

    - #### @GroovyABI(since = "1.8.0")
      public static float floatUnbox(Object value)

      Unboxes an object to a primitive `float` value.

      Returns `Float.NaN` if the value is null. Otherwise converts the object to a `Number` and extracts its float value.

      throws:
        GroovyCastException if the object cannot be converted to a number
      Parameters:
        `value` - the object to unbox (typically a wrapper object or string representation, may be null)
      Returns:
        the float value, or NaN if value is null

    - #### @Deprecated(since = "2.3.0")
      public static Character getCharFromSizeOneString(Object value)

    - #### @GroovyABI(since = "1.8.0")
      public static int intUnbox(Object value)

      Unboxes an object to a primitive `int` value.

      Converts the object to a `Number` and then extracts its int value.

      throws:
        GroovyCastException if the object cannot be converted to a number
      Parameters:
        `value` - the object to unbox (typically a wrapper object or string representation)
      Returns:
        the int value

    - #### @Deprecated(since = "2.3.0")
      public static boolean isEnumSubclass(Object value)

      Determines whether the value object is a Class object representing a subclass of java.lang.Enum. Uses class name check to avoid breaking on pre-Java 5 JREs.

      Parameters:
        `value` - an object
      Returns:
        true if the object is an Enum

    - #### @GroovyABI(since = "1.8.0")
      public static long longUnbox(Object value)

      Unboxes an object to a primitive `long` value.

      Converts the object to a `Number` and then extracts its long value.

      throws:
        GroovyCastException if the object cannot be converted to a number
      Parameters:
        `value` - the object to unbox (typically a wrapper object or string representation)
      Returns:
        the long value

    - #### public static Object[] primitiveArrayBox(Object array)

      Boxes a primitive array to an object array.

      Converts primitive values in the array to their boxed equivalents. Each primitive element is converted to its corresponding wrapper class (e.g., int to Integer).

      Parameters:
        `array` - the primitive array to box
      Returns:
        an Object array containing the boxed values

    - #### public static List primitiveArrayToList(Object array)

      Allows conversion of arrays into a mutable List

      Parameters:
        `array` - an array
      Returns:
        the array as a List

    - #### public static List primitiveArrayToUnmodifiableList(Object array)

      Allows conversion of arrays into an immutable List view

      Parameters:
        `array` - an array
      Returns:
        a List view of the array

    - #### @GroovyABI(since = "1.8.0")
      public static short shortUnbox(Object value)

      Unboxes an object to a primitive `short` value.

      Converts the object to a `Number` and then extracts its short value.

      throws:
        GroovyCastException if the object cannot be converted to a number
      Parameters:
        `value` - the object to unbox (typically a wrapper object or string representation)
      Returns:
        the short value