A cast converts the value of an original type to the equivalent value of a target type. An implicit cast infers the target type and automatically occurs during certainoperations. An explicit cast specifies the target type and forcefully occurs as its own operation. Use thecast operator '()' to specify an explicit cast. You can also check out thetype casting tutorial for related examples, and for help with troubleshooting refer to "type casting issues" in the Troubleshooting section.

Refer to thecast table for a quick reference on all allowed casts. To help resolve any issues, checkDebug type casting errors in Painless.

Errors

• If during a cast there exists no equivalent value for the target type.
• If an implicit cast is given, but an explicit cast is required.

Grammar

cast: '(' TYPE ')' expression

Examples

• Valid casts

  int i = (int)5L;Map m = new HashMap();HashMap hm = (HashMap)m;

  1. declareint i; explicit castlong 5 toint 5 →int 5; storeint 5 toi
  2. declareMap m; allocateHashMap instance →HashMap reference; implicit castHashMap reference toMap reference →Map reference; storeMap reference tom
  3. declareHashMap hm; load fromm →Map reference; explicit castMap reference toHashMap reference →HashMap reference; storeHashMap reference tohm

Anumeric type cast converts the value of an original numeric type to the equivalent value of a target numeric type. A cast between two numeric type values results in data loss when the value of the original numeric type is larger than the target numeric type can accommodate. A cast between an integer type value and a floating point type value can result in precision loss.

The allowed casts for values of each numeric type are shown as a row in the following table:

Examples

• Valid numeric type casts

  int a = 1;long b = a;short c = (short)b;double e = (double)a;

  1. declareint a; storeint 1 toa
  2. declarelong b; load froma →int 1; implicit castint 1 tolong 1 →long 1; storelong 1 tob
  3. declareshort c; load fromb →long 1; explicit castlong 1 toshort 1 →short 1; storeshort 1 value toc
  4. declaredouble e; load froma →int 1; explicit castint 1 todouble 1.0; storedouble 1.0 toe; (note the explicit cast is extraneous since an implicit cast is valid)

• Invalid numeric type casts resulting in errors

  int a = 1.0;int b = 2;byte c = b;

  1. declareint i;error → cannot implicit castdouble 1.0 toint 1; (note an explicit cast is valid)
  2. declareint b; storeint 2 tob
  3. declare bytec; load fromb →int 2;error → cannot implicit castint 2 tobyte 2; (note an explicit cast is valid)

Areference type cast converts the value of an original reference type to the equivalent value of a target reference type. An implicit cast between two reference type values is allowed when the original reference type is a descendant of the target type. An explicit cast between two reference type values is allowed when the original type is a descendant of the target type or the target type is a descendant of the original type.

Examples

• Valid reference type casts

  List x;ArrayList y = new ArrayList();x = y;y = (ArrayList)x;x = (List)y;

  1. declareList x; store default valuenull tox
  2. declareArrayList y; allocateArrayList instance →ArrayList reference; storeArrayList reference toy;
  3. load fromy →ArrayList reference; implicit castArrayList reference toList reference →List reference; storeList reference tox; (noteArrayList is a descendant ofList)
  4. load fromx →List reference; explicit castList reference toArrayList reference →ArrayList reference; storeArrayList reference toy;
  5. load fromy →ArrayList reference; explicit castArrayList reference toList reference →List reference; storeList reference tox; (note the explicit cast is extraneous, and an implicit cast is valid)

• Invalid reference type casts resulting in errors

  List x = new ArrayList();ArrayList y = x;Map m = (Map)x;

  1. declareList x; allocateArrayList instance →ArrayList reference; implicit castArrayList reference toList reference →List reference; storeList reference tox
  2. declareArrayList y; load fromx →List reference;error → cannot implicit castList reference toArrayList reference; (note an explicit cast is valid sinceArrayList is a descendant ofList)
  3. declareArrayList y; load fromx →List reference;error → cannot explicit castList reference toMap reference; (note no cast is valid since neitherList norMap is a descendant of the other)

Adynamic (def) type cast converts the value of an originaldef type to the equivalent value of any target type or converts the value of any original type to the equivalent value of a targetdef type.

An implicit cast from any original type value to adef type value is always allowed. An explicit cast from any original type value to adef type value is always allowed but never necessary.

An implicit or explicit cast from an originaldef type value to any target type value is allowed if and only if the cast is normally allowed based on the current type value thedef type value represents.

Examples

• Valid dynamic type casts with any original type to a targetdef type

  def d0 = 3;d0 = new ArrayList();Object o = new HashMap();def d1 = o;int i = d1.size();

  1. declaredef d0; implicit castint 3 todef; storeint 3 tod0
  2. allocateArrayList instance →ArrayList reference; implicit castArrayList reference todef →def; storedef tod0
  3. declareObject o; allocateHashMap instance →HashMap reference; implicit castHashMap reference toObject reference →Object reference; storeObject reference too
  4. declaredef d1; load fromo →Object reference; implicit castObject reference todef →def; storedef tod1
  5. declareint i; load fromd1 →def; implicit castdef toHashMap reference → HashMap reference; callsizeonHashMap reference→int 0; storeint 0toi; (notedefwas implicit cast toHashMap referencesinceHashMapis the child-most descendant type value that thedef` type value represents)

• Valid dynamic type casts with an originaldef type to any target type

  def d = 1.0;int i = (int)d;d = 1;float f = d;d = new ArrayList();List l = d;

  1. declaredef d; implicit castdouble 1.0 todef →def; storedef tod
  2. declareint i; load fromd →def; implicit castdef todouble 1.0 →double 1.0; explicit castdouble 1.0 toint 1 →int 1; storeint 1 toi; (note the explicit cast is necessary since adouble type value is not converted to anint type value implicitly)
  3. storeint 1 tod; (note the switch in the typed represents fromdouble toint)
  4. declarefloat i; load fromd →def; implicit castdef toint 1 →int 1; implicit castint 1 tofloat 1.0 →float 1.0; storefloat 1.0 tof
  5. allocateArrayList instance →ArrayList reference; storeArrayList reference tod; (note the switch in the typed represents fromint toArrayList)
  6. declareList l; load fromd →def; implicit castdef toArrayList reference →ArrayList reference; implicit castArrayList reference toList reference →List reference; storeList reference tol

• Invalid dynamic type casts resulting in errors

  def d = 1;short s = d;d = new HashMap();List l = d;

  1. declaredef d; implicit castint 1 todef →def; storedef tod
  2. declareshort s; load fromd →def; implicit castdef toint 1 →int 1;error → cannot implicit castint 1 toshort 1; (note an explicit cast is valid)
  3. allocateHashMap instance →HashMap reference; implicit castHashMap reference todef →def; storedef tod
  4. declareList l; load fromd →def; implicit castdef toHashMap reference;error → cannot implicit castHashMap reference toList reference; (note no cast is valid since neitherHashMap norList is a descendant of the other)

Use the cast operator to convert aString type value into achar type value.

Errors

• If theString type value isn’t one character in length.
• If theString type value isnull.

Examples

• Casting string literals intochar type values

  char c = (char)"C";c = (char)'c';

  1. declarechar c; explicit castString "C" tochar C →char C; storechar C toc
  2. explicit castString 'c' tochar c →char c; storechar c toc

• Casting aString reference into achar type value

  String s = "s";char c = (char)s;

  1. declareString s; storeString "s" tos;
  2. declarechar c load froms →String "s"; explicit castString "s" tochar s →char s; storechar s toc

Use the cast operator to convert achar type value into aString type value.

Examples

• Casting aString reference into achar type value

  char c = 65;String s = (String)c;

  1. declarechar c; storechar 65 toc;
  2. declareString s load fromc →char A; explicit castchar A toString "A" →String "A"; storeString "A" tos

Boxing is a special type of cast used to convert a primitive type to its corresponding reference type. Unboxing is the reverse used to convert a reference type to its corresponding primitive type.

Implicit boxing/unboxing occurs during the following operations:

• Conversions between adef type and a primitive type are implicitly boxed/unboxed as necessary, though this is referred to as an implicit cast throughout the documentation.
• Method/function call arguments are implicitly boxed/unboxed as necessary.
• A primitive type value is implicitly boxed when a reference type method is called on it.

Explicit boxing/unboxing is not allowed. Use the reference type API to explicitly convert a primitive type value to its respective reference type value and vice versa.

Errors

• If an explicit cast is made to box/unbox a primitive type.

Examples

• Uses of implicit boxing/unboxing

  List l = new ArrayList();l.add(1);Integer I = Integer.valueOf(0);int i = l.get(i);

  1. declareList l; allocateArrayList instance →ArrayList reference; storeArrayList reference tol;
  2. load froml →List reference; implicit castint 1 todef →def; calladd onList reference with arguments (def); (note internallyint 1 is boxed toInteger 1 to store as adef type value)
  3. declareInteger I; callvalueOf onInteger with arguments of (int 0) →Integer 0; storeInteger 0 toI;
  4. declareint i; load fromI →Integer 0; unboxInteger 0 →int 0; load froml →List reference; callget onList reference with arguments (int 0) →def; implicit castdef toint 1 →int 1; storeint 1 toi; (note internallyint 1 is unboxed fromInteger 1 when loaded from adef type value)

• Uses of invalid boxing/unboxing resulting in errors.

  Integer x = 1;Integer y = (Integer)1;int a = Integer.valueOf(1);int b = (int)Integer.valueOf(1);

  1. declareInteger x;error → cannot implicit boxint 1 toInteger 1 during assignment
  2. declareInteger y;error → cannot explicit boxint 1 toInteger 1 during assignment
  3. declareint a; callvalueOf onInteger with arguments of (int 1) →Integer 1;error → cannot implicit unboxInteger 1 toint 1 during assignment
  4. declareint a; callvalueOf onInteger with arguments of (int 1) →Integer 1;error → cannot explicit unboxInteger 1 toint 1 during assignment

Promotion is when a single value is implicitly cast to a certain type or multiple values are implicitly cast to the same type as required for evaluation by certain operations. Each operation that requires promotion has a promotion table that shows all required implicit casts based on the type(s) of value(s). A value promoted to adef type at compile-time is promoted again at run-time based on the type thedef value represents.

Errors

• If a specific operation cannot find an allowed promotion type for the type(s) of value(s) given.

Examples

• Uses of promotion

  double d = 2 + 2.0;def x = 1;float f = x + 2.0F;

  1. declaredouble d; promoteint 2 anddouble 2.0 @0: resultdouble; implicit castint 2 todouble 2.0 @1 →double 2.0 @1; adddouble 2.0 @1 anddouble 2.0 @0 →double 4.0; storedouble 4.0 tod
  2. declaredef x; implicit castint 1 todef →def; storedef tox;
  3. declarefloat f; load fromx →def; implicit castdef toint 1 →int 1; promoteint 1 andfloat 2.0: resultfloat; implicit castint 1 tofloat 1.0 →float1.0; addfloat 1.0andfloat 2.0→float 3.0; storefloat 3.0tof; (note this example illustrates promotion done at run-time as promotion done at compile-time would have resolved to adef` type value)

The following tables show all allowed casts. Read the tables row by row, where the original type is shown in the first column, and each subsequent column indicates whether a cast to the specified target type is implicit (I), explicit (E), boxed/unboxed for methods only (A), a reference type cast (@), or is not allowed (-). Seereference type casting for allowed reference type casts.

Primitive/Reference Types

def Type